manage-codebase-rebuild

<purpose> Two-wave parallel execution -- Wave 1: 3 scanner agents (Component Scanner, Feature Mapper, Requirement Linker) analyze the codebase in parallel. Wave 2: 2 writer agents (Tech Registry Writer, Feature Map Writer) consume scanner results and write documentation files. This is a destructive operation that rebuilds the entire `.workflow/codebase/` directory from scratch.

Core workflow: Prepare Directory -> Decompose Doc Dimensions -> Parallel Generation -> Assemble doc-index.json

Topology: Independent Parallel (single wave)

+---------------------------------------------------------------------------+
|                  CODEBASE REBUILD CSV WAVE WORKFLOW                        |
+---------------------------------------------------------------------------+
|                                                                           |
|  Phase 1: Setup -> CSV                                                    |
|     +-- Validate .workflow/ exists                                        |
|     +-- Confirm rebuild (or --force / -y)                                 |
|     +-- Clear .workflow/codebase/ directory                               |
|     +-- Detect source directories (src/, lib/, app/, packages/)           |
|     +-- Generate tasks.csv with 5 doc generator tasks                    |
|     +-- All tasks wave 1 (no dependencies)                               |
|                                                                           |
|  Phase 2: Wave Execution (Two Waves)                                      |
|     +-- Wave 1: 3 scanners run concurrently                              |
|     |   +-- Component Scanner (TC-* entries)                             |
|     |   +-- Feature Mapper (FT-* entries)                                |
|     |   +-- Requirement Linker (REQ-* entries, if specs exist)           |
|     +-- Wave 2: 2 writers consume scanner results                        |
|     |   +-- Tech Registry Writer (tech-registry/*.md)                    |
|     |   +-- Feature Map Writer (feature-maps/*.md)                       |
|     +-- discoveries.ndjson shared (append-only)                          |
|                                                                           |
|  Phase 3: Results -> .workflow/codebase/                                  |
|     +-- Assemble doc-index.json from agent findings                      |
|     +-- Validate all output files exist                                  |
|     +-- Update state.json with rebuild timestamp                         |
|     +-- Generate context.md summary                                      |
|     +-- Auto-commit (unless --skip-commit)                               |
|     +-- Display completion report                                        |
|                                                                           |
+---------------------------------------------------------------------------+

</purpose> <context> $ARGUMENTS -- optional flags for rebuild control.

Usage:

$manage-codebase-rebuild ""
$manage-codebase-rebuild -y "--force"
$manage-codebase-rebuild -c 5 "--force --skip-commit"
$manage-codebase-rebuild --continue "20260318-rebuild-full"

Flags:

• -y, --yes: Skip all confirmations (auto mode, implies --force)
• -c, --concurrency N: Max concurrent agents (default: 5)
• --continue: Resume existing session

Inner flags (passed inside quotes):

• --force: Clear existing .workflow/codebase/ and rebuild from scratch
• --skip-commit: Do not auto-commit after rebuild

When --yes or -y: Auto-confirm rebuild (implies --force), skip all prompts.

Output Directory: .workflow/.csv-wave/{session-id}/ Core Output: tasks.csv (master state) + results.csv (final) + discoveries.ndjson (shared exploration) + context.md (human-readable report) Target: .workflow/codebase/ (doc-index.json, tech-registry/, feature-maps/)

Output boundary: ALL file writes MUST target .workflow/codebase/, .workflow/state.json, or .workflow/project.md (Tech Stack section only). NEVER modify source code or files outside these paths. </context>

<csv_schema>

tasks.csv (Master State)

id,title,description,doc_dimension,output_path,deps,context_from,wave,status
"1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Return JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols via output_schema. Do NOT write files — orchestrator assembles doc-index.json in Phase 3.","components","<ABS_WORKFLOW>/codebase/doc-index.json#components","","","1","pending"
"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if <ABS_WORKFLOW>/blueprint/ exists. Return JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase via output_schema. Do NOT write files.","features","<ABS_WORKFLOW>/codebase/doc-index.json#features","","","1","pending"
"3","Requirement Linker","If <ABS_WORKFLOW>/blueprint/ exists, scan BLP-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Return JSON arrays for requirements and architecture_decisions via output_schema. Do NOT write files.","requirements","<ABS_WORKFLOW>/codebase/doc-index.json#requirements","","","1","pending"
"4","Tech Registry Writer","For each component discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Also write <ABS_WORKFLOW>/codebase/tech-registry/_index.md with the component table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","tech-registry","<ABS_WORKFLOW>/codebase/tech-registry/","1;2;3","1;2;3","2","pending"
"5","Feature Map Writer","For each feature discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Also write <ABS_WORKFLOW>/codebase/feature-maps/_index.md with the feature table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","feature-maps","<ABS_WORKFLOW>/codebase/feature-maps/","1;2;3","1;2;3","2","pending"

Path resolution (orchestrator MUST do BEFORE writing tasks.csv): substitute <ABS_WORKFLOW> with the absolute path to the project's .workflow/ directory (e.g. D:/maestro2/.workflow). Agent Write tool requires absolute paths — passing relative .workflow/... literals will fail.

Columns:

Column	Phase	Description
id	Input	Generator identifier
title	Input	Doc generator dimension title
description	Input	Detailed generation instructions
doc_dimension	Input	Documentation dimension: components/features/requirements/tech-registry/feature-maps
output_path	Input	Target output path in .workflow/codebase/
deps	Input	Empty (all independent)
context_from	Input	Empty (no cross-task context needed)
wave	Computed	1 (scanners, independent parallel) or 2 (writers, depend on wave 1)
status	Lifecycle	Initialized to pending, updated to completed/failed after wave merge

Output columns (returned exclusively via output_schema, NOT in wave CSV):

Column	Description
result_status	completed / failed (mapped to master status on merge)
result_findings	Generation summary -- counts, paths, notes (max 500 chars)
error	Error message if failed

Column separation rule: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns + prev_context. Output columns are returned exclusively via output_schema.

Per-Wave CSV (Temporary)

Single wave generates wave-1.csv. No prev_context needed (all tasks independent). </csv_schema>

<invariants> 1. **Start Immediately**: First action is session initialization, then Phase 1 2. **CSV is Source of Truth**: tasks.csv holds all generator state 3. **Discovery Board is Append-Only**: Generators share findings via NDJSON 4. **Partial Results OK**: If 3/5 generators succeed, still assemble available docs 5. **Destructive by Design**: This is a full rebuild -- existing codebase/ is cleared 6. **Two Waves**: Wave 1 (Scanner/Mapper/Linker, independent parallel), Wave 2 (Writers, depend on wave 1 results via context_from) 7. **Cleanup Temp Files**: Remove wave-1.csv after results are merged 8. **DO NOT STOP**: Execute until all generators complete or fail 9. **Absolute Paths Only**: All paths in `description` and `output_path` MUST be absolute before tasks.csv is written. Orchestrator substitutes `<ABS_WORKFLOW>` placeholder; never let it leak into a spawned agent's prompt. 10. **Writer vs Returner Split**: Tasks 1-3 return data via `output_schema` (no file writes). Tasks 4-5 MUST write files via Write tool + verify with Glob. Mixing the two contracts (e.g., returning markdown content as text from tasks 4-5) is a contract violation. </invariants> <execution>

Output Artifacts

File	Purpose	Lifecycle
tasks.csv	Master state -- all tasks with status/findings	Updated after wave
wave-1.csv	Wave

---

Content truncated.