Genesis — Codebase Onboarding Reconnaissance

Role: Maps an unfamiliar codebase across four read-only stages — structure, history, architecture, and governance fitness — then produces a persistent Genesis Report artifact. The output feeds downstream skills (Sentry priority, Trace blast-radius, Context Pre-Seeding) so the governance system has situational awareness from the first interaction.

Stages

Total dispatches: 4–6 ${SLOT.MODEL_FAST} subagents across all stages.

Stage Selection

Genesis stages are incremental — run any subset, in any order. Later stages build on earlier outputs when available but degrade gracefully without them.

Design Invariants

1. Read-only: Genesis NEVER modifies the repository. It produces artifacts only — no writes, no commits, no branch creation.
2. Incremental: Any single stage can run standalone. Stages build on prior outputs when available but function independently.
3. Multi-repo: Accepts multiple repo paths for multi-service architectures. Each repo gets its own stage passes; Policy synthesizes across all of them.
4. Cacheable: Output persists as a governance artifact (genesis-report-[project].md). Subsequent runs diff against the previous report and highlight what changed.
5. Feeds downstream: Perimeter → Context Pre-Seeding. Chronology → Sentry priority ranking. Blueprint → Trace blast-radius context. Policy → governance configuration.

Stage 1: Perimeter (Repository Structure Mapping)

Dispatch 1–2 ${SLOT.MODEL_FAST} broad repo scanners to map the repository's physical structure.

Scanner Objectives

Dev Environment Probe

[!NOTE] Local environment blindness is the #4 source of wasted agent steps (120 steps). Perimeter supplements repository structure mapping with a sanitized dev environment probe, establishing situational awareness before downstream tools execute build, lint, or test commands.

[!CAUTION] Privacy Invariant: All probe outputs must be sanitized aggregates — versions and booleans, NOT raw command output.

• NO file paths (especially not which python3 output, which leaks /home/<user>/)
• NO usernames (especially not git config user.name, which leaks real names)
• NO raw environment variable values (especially not $SHELL, $TERM_PROGRAM, $CODESPACES, or $REMOTE_CONTAINERS_IPC)
• NO hostnames (use uname -s -m, never hostname or uname -n)

[!IMPORTANT] Orchestrator Execution Mandate: Research subagents have read-only tools only — probes requiring shell execution must be performed by the parent orchestrator before dispatch. The orchestrator gathers and sanitizes the probe values, then injects the clean aggregate block into the Perimeter subagent prompt (or directly records it in the report artifact).

Perimeter Prompt Template

<!-- CONTEXT: Genesis Perimeter -->
You are a codebase reconnaissance scanner. Your job is to map the repository structure.
You are READ-ONLY — do not modify any files.

Scan this repository: [REPO_PATH]

Read these files first (if they exist):
- README.md (or README.*)
- package.json / requirements.txt / pom.xml / build.gradle / Cargo.toml / go.mod
- Makefile / Justfile / Taskfile.yml
- .github/workflows/*.yml / .gitlab-ci.yml / Jenkinsfile
- docker-compose.yml / Dockerfile

[IF DEV ENVIRONMENT INJECTED BY ORCHESTRATOR]:
Include the parent-probed dev environment block in report delivery:
[Sanitized Dev Environment Block]
[END IF]

Deliver:

### Tech Stack
- Language(s): [with version if detectable]
- Framework: [name + version]
- Build system: [tool + command]
- Package manager: [name]

### Dev Environment (if provided by orchestrator)
- Shell: [sanitized version]
- OS & arch: [sanitized os, arch]
- Build tools: [sanitized tool list]
- Container: [container boolean]
- IDE: [sanitized context]
- Python: [version, venv boolean]
- Git: [version, configured boolean]
- Package managers: [sanitized pkg list]

### Directory Tree (annotated, max 3 levels)

src/ — application source tests/ — test suites docs/ — documentation scripts/ — automation ...

### Dependencies
- Direct: [count]
- Dev: [count]
- Notable: [list any critical or unusual deps]

### Entry Points
- [file:path] — [role: server, CLI, worker, etc.]

### Testing
- Framework: [name]
- Runner: `[command]`
- Test directory: [path]
- Config: [file if present]

### Monorepo
- Is monorepo: [yes/no]
- Workspace tool: [if applicable]
- Package count: [if applicable]

[OUTPUT]: Max 5 bullets per section. Cite file paths.
<!-- END CONTEXT -->

Stage 2: Chronology (Git History Intelligence)

Dispatch 1 ${SLOT.MODEL_FAST} git history analyst to extract temporal intelligence from the repository's version control history.

Analyst Objectives

Chronology Prompt Template

<!-- CONTEXT: Genesis Chronology -->
You are a git history analyst. Your job is to extract temporal intelligence from version control.
You are READ-ONLY — do not create branches, tags, or commits.

Analyze this repository: [REPO_PATH]

Run these commands (or equivalent) to gather data:
- git log --oneline -100
- git branch -a
- git shortlog -sn --since="6 months ago"
- git tag --sort=-creatordate | head -10
- git log --pretty=format: --name-only -100 | sort | uniq -c | sort -rn | head -20
- git log --diff-filter=M --since="3 months ago" --pretty=format: --name-only | sort | uniq -c | sort -rn | head -10

[IF PERIMETER OUTPUT EXISTS]:
Cross-reference churn heatmap against Perimeter entry points and test files.
[Perimeter output summary]
[END IF]

Deliver:

### Branch Topology
- Default branch: [name]
- Active branches: [count] (list top 5)
- Stale branches (>90 days): [count]

### Commit Activity (last 6 months)
- Total commits: [count]
- Monthly average: [count]
- Trend: [accelerating / stable / declining]
- Active contributors: [count] (list top 5 with commit counts)

### Release Cadence
- Last release: [tag @ date]
- Versioning: [semver / calver / other]
- Average release interval: [N days/weeks]

### Churn Heatmap (top 10 most-modified files, last 100 commits)
| File | Modifications | Role (from Perimeter) |
|:-----|:------------:|:------------------------|
| [path] | [count] | [source / test / config / etc.] |

### High-Risk Files
[Files with both high churn (>5 modifications) AND high complexity (>200 lines)]
- [file:path] — [modifications] changes, [lines] lines — Risk: [assessment]

[OUTPUT]: Cite exact git commands used. Quantify everything.
<!-- END CONTEXT -->

Stage 3: Blueprint (Architecture Extraction)

Dispatch 1–2 ${SLOT.MODEL_FAST} architecture analysts to map the system's logical architecture from code.

Analyst Objectives

Blueprint Prompt Template

<!-- CONTEXT: Genesis Blueprint -->
You are an architecture analyst. Your job is to extract the logical architecture from code.
You are READ-ONLY — do not modify any files.

Analyze this repository: [REPO_PATH]

[IF PERIMETER OUTPUT EXISTS]:
Use this structure map to focus your search:
[Perimeter output summary — tech stack, directory tree, entry points]
[END IF]

[IF CHRONOLOGY OUTPUT EXISTS]:
Prioritize high-churn files from Chronology:
[Chronology churn heatmap top 10]
[END IF]

Scan for:
1. Route/endpoint definitions (Express routes, Flask blueprints, Spring controllers, etc.)
2. Schema/entity/model definitions (ORM models, Prisma schema, protobuf, etc.)
3. Environment variable usage (process.env, os.environ, etc.)
4. Database/queue/cache client initialization
5. Shared contracts (proto files, OpenAPI specs, shared type packages)

Deliver:

### API Surface
| Method | Path | Handler | File |
|:-------|:-----|:--------|:-----|
| [GET/POST/...] | [/api/...] | [function] | [file:line] |

### Data Models
| Entity | Fields | Relationships | File |
|:-------|:------:|:-------------|:-----|
| [name] | [count] | [belongs_to, has_many, etc.] | [file:line] |

### Configuration Pattern
- Config strategy: [env vars / config files / secrets manager / mixed]
- Config files: [list paths]
- Env vars referenced: [count] (list critical ones)
- Secrets management: [tool/pattern if detected]

### External Service Integrations
| Service | Type | Client Library | Connection File |
|:--------|:-----|:---------------|:---------------|
| [name] | [DB/queue/cache/API] | [library] | [file:line] |

### Cross-Repo Boundaries
- Shared schemas: [list files]
- API specs: [OpenAPI/Swagger/proto files]
- Shared type packages: [if monorepo or multi-repo]
- Contract testing: [detected / not detected]

[OUTPUT]: Max 10 rows per table. Cite file:line for every entry.
<!-- END CONTEXT -->

Stage 4: Policy (Contextual Synthesis & Recommendations)

Dispatch 1 ${SLOT.MODEL_FAST} governance advisor to synthesize all prior stage outputs into actionable governance configuration.

Advisor Objectives

Policy Prompt Template

<!-- CONTEXT: Genesis Policy -->
You are a governance advisor. Your job is to synthesize codebase intelligence into
actionable governance configuration. You are READ-ONLY.

Repository: [REPO_PATH]
Project name: [PROJECT_NAME]

Prior stage outputs:
[PERIMETER SUMMARY — tech stack, structure, entry points, test framework]
[CHRONOLOGY SUMMARY — commit activity, churn heatmap, high-risk files]
[BLUEPRINT SUMMARY — API surface, data models, config pattern, integrations]

Deliver:

### Coding Conventions
- Naming: [camelCase / snake_case / PascalCase / mixed]
- Formatting: [prettier / black / gofmt / none detected]
- Linter: [eslint / pylint / clippy / none]
- Error handling: [try-catch / Result type / error codes / mixed]

### Testing Patterns
- Strategy: [unit / integration / e2e / mixed]
- Framework: [from Perimeter]
- Coverage tool: [if detected]
- Test naming: [describe/it / test_ prefix / @Test / etc.]
- Approximate test count: [count test files × avg tests per file]

### Deployment Model
- Containerized: [yes/no] — [Dockerfile location]
- CI/CD: [GitHub Actions / GitLab CI / Jenkins / etc.] — [config location]
- IaC: [Terraform / Pulumi / CDK / none] — [directory]
- Environments: [detected from config/env files]

### Known Traps & Gotchas
[Cross-reference Chronology churn heatmap with Blueprint architecture findings]
- **Magic Numbers & Hardcoded Coordinates**: Scan for density of hardcoded numeric literals (screen coordinates like `1920`, `1080`, pixel positions, port numbers, timeout values). High density of magic numbers indicates structural brittleness. Flag files with >10 hardcoded numeric literals as candidates for Trap rule generation.

| File | Signal | Trap | Recommendation |
|:-----|:-------|:-----|:---------------|
| [path] | [high churn + complex] | [description] | [mitigation] |

### Recommended Governance Configuration
- Default review protocol: [Sweep / Vanguard / Bulwark] — [rationale]
- Rules to activate: [list applicable rule files]
- High-risk areas requiring Bulwark+: [list paths/patterns]
- Suggested Sentry lenses: [list 3-4 recommended lenses]

### Auto-Generated Context Pre-Seeding Block

[PROJECT]: [Name] — [1-sentence core purpose] [STACK]: [Language] | [Key libs] | Test: [test_command] [LAYOUT]:

• [dir]/: [3-word role] [CONSTRAINTS]:
• [Critical invariant or known trap from Policy analysis] [OUTPUT]: Max 5 bullets per section. Cite file:line.

This block is nominally ~200 tokens (approximate target; ground-truth token count is measured via `aegis_core/metrics.py`) and is used verbatim in all future subagent prompts.
<!-- END CONTEXT -->

Multi-Repo Mode

When provided multiple repository paths, Genesis runs Stages 1–3 independently for each repo, then runs a single Policy pass that synthesizes across all repositories.

genesis([repo_a, repo_b, repo_c])

  Stage 1: Perimeter(repo_a), Perimeter(repo_b), Perimeter(repo_c)      ← parallel
  Stage 2: Chronology(repo_a), Chronology(repo_b), Chronology(repo_c)  ← parallel
  Stage 3: Blueprint(repo_a), Blueprint(repo_b), Blueprint(repo_c)      ← parallel
  Stage 4: Policy(all_outputs)                                          ← single synthesis

The Policy stage additionally identifies:

• Shared contracts between repos (proto files, OpenAPI specs, shared packages)
• Deployment coupling (do repos deploy independently or together?)
• Cross-repo churn correlation (do changes in repo_a frequently accompany changes in repo_b?)

Output Format

The Genesis Report is a structured markdown artifact persisted as genesis-report-[project-name].md:

# Genesis Report — [Project Name]
> Generated: [timestamp] | Stages: [list] | Repos: [count]

## 🗺️ Perimeter
[Stage 1 output — tech stack, directory tree, dependencies, entry points, testing]

### Dev Environment
[Sanitized environment aggregates: shell, OS/arch, build tools, container status, IDE, Python/venv, Git status, package managers. Note: Probed by parent orchestrator; research subagents have read-only tools only. Contains zero raw paths, usernames, or env vars.]

## 📜 Chronology
[Stage 2 output — branch topology, commit activity, churn heatmap, high-risk files]

## 📖 Blueprint
[Stage 3 output — API surface, data models, config patterns, integrations, boundaries]

## 🧭 Policy
[Stage 4 output — conventions, testing patterns, deployment model, traps, governance config]

## Auto-Generated Context Block
[Context pre-seeding block (~200 tokens approx, measured via `aegis_core/metrics.py`) ready for copy-paste into subagent prompts]

---
## Diff from Previous Report
[If a prior genesis-report exists, show what changed since last run]

Cache & Diff Behavior

The diff section uses standard diff formatting:

## 🗺️ Perimeter
- Dependencies: 42 direct, 18 dev
+ Dependencies: 45 direct, 19 dev
  [+3 new: @aws-sdk/client-s3, zod, vitest]

Relationship to Existing System

Genesis output feeds directly into multiple downstream skills and prongs:

  Genesis                         Downstream Consumer
  ┌─────────────────┐
  │ 🗺️ Perimeter   │ ──────────► Context Pre-Seeding (all subagent prompts)
  │                 │ ──────────► Session Preflight (env verification)
  ├─────────────────┤
  │ 📜 Chronology  │ ──────────► Sentry (priority ranking by churn)
  │                 │ ──────────► Post-Mortem (historical context)
  ├─────────────────┤
  │ 📖 Blueprint   │ ──────────► Trace (blast-radius pre-computation)
  │                 │ ──────────► Security Audit (attack surface map)
  ├─────────────────┤
  │ 🧭 Policy      │ ──────────► Staff Review (default protocol selection)
  │                 │ ──────────► Governance Auditor (rule activation)
  └─────────────────┘

Anti-Patterns

• Don't modify the repository — Genesis is strictly read-only reconnaissance. If a stage subagent proposes a fix, discard it. Genesis observes; other skills act.
• Don't skip Perimeter — All other stages benefit from structure context. Running Chronology or Blueprint without Perimeter produces lower-quality output.
• Don't run Policy without at least one prior stage — Policy synthesizes; it needs raw data to synthesize. Running Policy on an empty input produces generic boilerplate.
• Don't dispatch >2 subagents per stage — Genesis stages are sequential and focused. Unlike Sentry (which benefits from orthogonal lenses), Genesis stages have a single objective each.
• Don't cache across major version changes — If the repo undergoes a major refactor (new framework, language migration), force a fresh Genesis run. Diffing against a stale baseline produces misleading deltas.
• Don't substitute Genesis for a review — Genesis maps the terrain; it does not evaluate quality. Use Staff Review, Sentry, or Adaptive Reviewer to assess code quality.
• Don't let Policy subagents apply governance config — Policy recommends configuration. The orchestrator presents recommendations to the user, who decides what to activate.

Model Selection

When to Use

• "What is this codebase?" — Full Genesis (all 4 stages)
• "Onboard me" / "I'm new to this repo" — Full Genesis + present Context Pre-Seeding block
• "Map this repo" / "Show me the structure" — Perimeter only
• "Where are the hot spots?" — Perimeter + Chronology
• "How is this system architected?" — Perimeter + Blueprint
• "Set up governance for this project" — Full Genesis (Policy needs all prior stages for good recommendations)
• "What changed since last scan?" — Re-run Genesis with cache diff

When NOT to Use

• Code review — Use Staff Review or Adaptive Reviewer. Genesis maps; it does not judge.
• Known defect — Use Patrol. The bug is already located; no reconnaissance needed.
• Active debugging — Use Incident Debug. Genesis is pre-engagement reconnaissance, not live triage.
• Single-file exploration — Just read the file. Genesis is for repository-scale mapping.
• CI/CD pipeline — Genesis is interactive and conversational. For automated quality gates, use Bastion as a CI check.