manage-codebase-rebuild

<purpose>
Full rebuild of `.workflow/codebase/` docs: 4 parallel mapper agents → tech-stack, architecture, features, concerns. Destructive — overwrites existing docs.
</purpose>

<required_reading>
@~/.maestro/workflows/codebase-rebuild.md
</required_reading>

<context>
$ARGUMENTS -- optional flags.

**Flags:**
- `--focus <area>` -- Scope mapper agents to a single domain (e.g., `auth`, `api`, `database`). When omitted, all 4 mappers run on the full codebase.
- `--force` -- Skip confirmation prompt and proceed directly
- `--skip-commit` -- Do not auto-commit after rebuild

**Mapper agent assignments (when `--focus` omitted):**
| Agent | Focus | Output file |
|-------|-------|-------------|
| Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
| Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
| Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |

**State files:**
- `.workflow/` -- must be initialized (project.md, state.json exist)
- `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
- `.workflow/codebase/doc-index.json` -- generated documentation index
- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by `maestro kg index`)
</context>

<execution>
Follow '~/.maestro/workflows/codebase-rebuild.md' completely.

**When `--focus <area>` is set:** pass the area string to each mapper agent as scoping context; only regenerate the docs relevant to that scope (leave others untouched unless missing).

</execution>

<completion>
### Next-step routing

| Condition | Suggestion |
|-----------|-----------|
| View updated state | `/manage-status` |
| Incremental updates later | `/quality-sync` |
| Verify KG stats | `maestro kg stats` |
| Future change impact | `maestro kg diff-wiki` |
</completion>

<error_codes>
| Code | Severity | Condition | Recovery |
|------|----------|-----------|----------|
| E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
| W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
| W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
</error_codes>

<success_criteria>
- [ ] User confirmed rebuild (or --force used)
- [ ] .workflow/codebase/ cleared and rebuilt from scratch (or scoped subset when --focus set)
- [ ] All 4 mapper agents spawned (failures logged as W001)
- [ ] doc-index.json generated and valid
- [ ] All documentation files regenerated
- [ ] state.json updated with rebuild timestamp
- [ ] project.md Tech Stack section updated if changes detected
- [ ] KG pipeline executed (`maestro kg index`)
- [ ] knowledge-graph.json generated in .workflow/codebase/
- [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
- [ ] Next step routed
</success_criteria>