Genesis

---
name: Genesis — Codebase Onboarding Reconnaissance
description: Four-stage read-only reconnaissance protocol mapping structure, history, architecture, and governance in unfamiliar codebases.
trigger: user_request
aliases: ["genesis", "init", "onboard", "explore", "map this repo", "what is this codebase"]
---

# 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

| Stage | Name | Subagent | Flash Dispatches | Focus |
|:------|:-----|:---------|:----------------:|:------|
| 1 | 🗺️ **Perimeter** | Broad Repo Scanner | 1–2 | Tech stack, directory tree, dependencies, entry points, test framework, dev environment probe |
| 2 | 📜 **Chronology** | Git History Analyst | 1 | Branch topology, commit frequency, churn heatmap, high-risk files |
| 3 | 📖 **Blueprint** | Architecture Analyst | 1–2 | API surface, data models, config patterns, external integrations, cross-repo boundaries |
| 4 | 🧭 **Policy** | Governance Advisor | 1 | Conventions, test patterns, deployment model, traps, governance config, Context Pre-Seeding |

**Total dispatches**: 4–6 Flash 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.

| Need | Stages | Dispatches | When to Use |
|:-----|:------:|:----------:|:------------|
| Quick layout | Perimeter only | 1–2 | "What is this repo?" — fast directory orientation |
| Risk assessment | Perimeter + Chronology | 2–3 | "Where are the hot spots?" — churn + structure |
| Architecture audit | Perimeter + Blueprint | 2–4 | "How is this system designed?" — API and data model mapping |
| Full onboarding | All 4 stages | 4–6 | "Onboard me to this codebase" — complete reconnaissance |
| Governance setup | Policy | 1 | "Configure governance for this project" — re-run synthesis |

---

## 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 Flash broad repo scanners to map the repository's physical structure.

### Scanner Objectives

| Objective | Method | Output |
|:----------|:-------|:-------|
| Tech stack | Detect language files, framework markers (`next.config.js`, `pom.xml`, `Cargo.toml`) | `{language, framework, build_system, package_manager}` |
| Directory tree | `find` / `fd` with annotated roles | Annotated tree (max 3 levels, role per directory) |
| Dependencies | Parse manifest files (`package.json`, `requirements.txt`, `build.gradle`, `go.mod`, etc.) | Dependency list with counts (direct vs transitive) |
| Entry points | Identify main classes, `index.*`, `server.*`, `main.*`, CLI entry points | List of entry points with file paths |
| Testing framework | Detect test runners (`jest`, `pytest`, `JUnit`, `go test`), test directories, config files | `{framework, runner_command, test_directory, config_file}` |
| Monorepo detection | Check for workspace configs (`lerna.json`, `pnpm-workspace.yaml`, Nx, Turborepo) | `{is_monorepo, workspace_tool, package_count}` |

### 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).

| Probe | Method | Sanitized Output | Must NOT Output |
|:------|:-------|:----------------|:---------------|
| Shell version | `bash --version` | `shell: bash 5.x` | NOT `$SHELL` value |
| OS & arch | `uname -s -m` | `os: linux, arch: x86_64` | NOT hostname |
| Build tools | `command -v make cmake npm cargo go` | `tools: [make, npm, go]` | NOT full paths |
| Container detection | Check `/.dockerenv` existence | `container: false` | NOT env var values |
| IDE context | Check known env vars | `ide: antigravity 2.x` | NOT `$TERM_PROGRAM` raw value |
| Python environment | Check for venv markers | `python: 3.11, venv: true` | NOT `which python3` path |
| Git status | `git --version` | `git: 2.43, configured: true` | NOT `git config user.name` |
| Package managers | `command -v brew apt choco` | `pkg: [apt]` | NOT full paths |

### 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 Flash git history analyst to extract temporal intelligence from the repository's version control history.

### Analyst Objectives

| Objective | Method | Output |
|:----------|:-------|:-------|
| Branch topology | `git branch -a`, `git log --graph` (abbreviated) | Active branches, default branch, stale branches (>90 days) |
| Commit frequency | `git log --since="6 months ago" --oneline \| wc -l` | Commits per month, trend (accelerating/stable/declining) |
| Contributor count | `git shortlog -sn --since="6 months ago"` | Active contributors with commit counts |
| Release cadence | `git tag --sort=-creatordate` | Tag frequency, last release date, versioning scheme |
| Churn heatmap | `git log --pretty=format: --name-only -100 \| sort \| uniq -c \| sort -rn \| head -20` | Top 20 most-modified files in last 100 commits |
| High-risk files | Cross-reference churn with file size/complexity | Files with both high churn AND high line count |

### 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 Flash architecture analysts to map the system's logical architecture from code.

### Analyst Objectives

| Objective | Method | Output |
|:----------|:-------|:-------|
| API surface | Scan for route definitions, controller annotations, handler registrations | List of endpoints with HTTP method, path, handler file:line |
| Data models | Scan for schema definitions, entity classes, DTOs, migrations | Entity inventory with field counts and relationships |
| Configuration | Identify env var usage, config files, secrets management | Config pattern: `{env_vars: [], config_files: [], secrets_manager: ""}` |
| External integrations | Detect database drivers, queue clients, cache clients, HTTP clients | Service dependency map with connection patterns |
| Cross-repo boundaries | Find shared contracts (proto files, OpenAPI specs, shared types) | Boundary inventory: `{shared_schemas: [], api_specs: [], proto_files: []}` |

### 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 Flash governance advisor to synthesize all prior stage outputs into actionable governance configuration.

### Advisor Objectives

| Objective | Method | Output |
|:----------|:-------|:-------|
| Coding conventions | Detect naming style, formatting, error handling patterns | Convention profile (camelCase vs snake_case, linter config, etc.) |
| Testing patterns | Assess test structure, coverage indicators, test naming conventions | `{pattern: "unit+integration", coverage_tool: "", naming: ""}` |
| Deployment model | Detect Dockerfiles, CI configs, IaC files (Terraform, Pulumi, CDK) | Deployment profile with detected tooling |
| Known traps | Cross-reference Chronology churn + Blueprint complexity → fragile areas | Trap list: `[{file, reason, recommendation}]` |
| Magic Numbers | 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. | List of brittle files with high magic number density |
| Governance config | Recommend which rules to activate, review protocol level | `{rules: [], default_protocol: "", risk_areas: []}` |
| Context Pre-Seeding | Auto-generate context header for future subagent prompts (approx. ~200 tokens; measured via `aegis_core/metrics.py`) | Ready-to-use context block |

### 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
```
<!-- CONTEXT: [PROJECT_NAME] -->
[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.
<!-- END CONTEXT -->
```

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`:

```markdown
# 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

| Scenario | Behavior |
|:---------|:---------|
| First run | Full 4-stage scan, produces `genesis-report-[project].md` |
| Subsequent run (same repo) | Re-runs selected stages, diffs against cached report, highlights changes |
| Subsequent run (new files detected) | Re-runs Perimeter + impacted stages, appends diff section |
| Force full refresh | User says "genesis --fresh" or "re-scan everything" — ignores cache |

The diff section uses standard diff formatting:
```diff
## 🗺️ 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)
  └─────────────────┘
```

| Genesis Stage | Feeds | How |
|:-------------|:------|:----|
| Perimeter | Context Pre-Seeding | Auto-generated `<!-- CONTEXT -->` block used in all subagent prompts |
| Perimeter | Session Preflight | Tech stack, test runner, and dev environment probe inform environment verification |
| Chronology | Sentry | Churn heatmap prioritizes which files scouts examine first |
| Chronology | Post-Mortem | Historical contributor and release context |
| Blueprint | Trace | Pre-computed dependency graph accelerates blast-radius analysis |
| Blueprint | Security Audit | API surface and external integrations define the attack surface |
| Policy | Staff Review | Recommended protocol level becomes the session default |
| Policy | Governance Auditor | Recommended rules are activated for the project |

---

## 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

| Role | Model | Rationale |
|:-----|:------|:----------|
| Perimeter scanner | `flash` | File-system traversal, manifest parsing, structured output |
| Chronology analyst | `flash` | Git command execution, quantitative analysis, heatmap generation |
| Blueprint analyst | `flash` | Pattern matching on code (routes, schemas, configs), structured tables |
| Policy advisor | `flash` | Synthesis of prior outputs, governance recommendation, template generation |
| Report synthesizer | orchestrator (self) | Cross-stage reconciliation, diff generation, artifact persistence |

---

## 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.