knowledge-build

Knowledge Build

§ROLE: KB orchestrator. Update kbRoot, not workRoot.

§CTX

• Use the pre-resolved projectRoot, kbRoot, and workRoot values from the generated Workflow Bootstrap section.
• KB outputs live under kbRoot:
  • index.md
  • concept_map.md
  • architecture.md
  • interaction-model.md
  • modules.md
  • patterns.md
  • features.md
  • state.json
  • meta.json
• index.md is orchestrator-owned. Never delegate it.
• state.json is shareable. meta.json is local-only and SHOULD be gitignored.
• Exclude these paths from change scope and file hygiene:
  • node_modules/, .git/, build/, dist/, cli/dist/, target/, .next/, __pycache__/, vendor/, .venv/, .rp1/context/

§DO

• Execute immediately. No approval loop.
• Single pass. No refinement loop.
• Treat this as an orchestrator, not a wrapper.
• FULL means wide evidence collection, not blank-slate regeneration.
• When prior KB exists, section agents MUST reconcile against it, even in FULL.
• Section agents MUST also treat prior KB as incomplete and perform one explicit novelty scan for material knowledge absent from it.
• Replace all placeholders with concrete values before dispatching child agents.
• Spawn the 6 analysis agents in one parallel batch.
• Wait patiently for child agents on the critical path. Do not declare them stalled after a short wait.
• Keep user-visible output terse:
  1. Initial status line
  2. Sparse progress only when useful
  3. Final report or fatal error

§PROC

1. Detect Mode

1. Use the pre-resolved directories. Create kbRoot if missing.
2. If FEATURE_ID is non-empty:
   • Set MODE=FEATURE_LEARNING.
   • Search, in order:
     • {workRoot}/archives/features/{FEATURE_ID}
     • {workRoot}/features/{FEATURE_ID}
   • If neither exists: report the checked paths, stop.
   • Read:
     • requirements.md
     • design.md
     • field-notes.md if present
     • tasks.md
   • Extract FILES_MODIFIED from tasks.md implementation summaries. Accept patterns like **Files**: and **Files Modified**:.
   • If FILES_MODIFIED is empty: explain that feature learning needs a concrete file scope, stop.
   • Build FEATURE_CONTEXT with:
     • feature id
     • feature path
     • summarized requirements
     • architectural decisions
     • discoveries from field notes
     • implementation patterns
     • files_modified
   • Set:
     • FILE_SCOPE=FILES_MODIFIED
     • FILE_DIFFS={}
     • INITIAL_MESSAGE=Feature learning build for {FEATURE_ID}
3. Else use git-driven mode:
   • Read {kbRoot}/state.json if it exists.
   • Get CURRENT_COMMIT via git rev-parse HEAD.
   • If no state.json:
     • Set MODE=FULL
     • FILE_SCOPE=[]
     • FILE_DIFFS={}
     • INITIAL_MESSAGE=First-time KB generation with parallel analysis (10-15 min)
   • Else read:
     • OLD_COMMIT=state.json.git_commit
     • REPO_TYPE=state.json.repo_type // "single-project"
     • repo_root + current_project_path from {kbRoot}/meta.json
     • Fallback: use state.json for those local fields only if meta.json is absent
   • If OLD_COMMIT == CURRENT_COMMIT:
     • Output KB is up-to-date (commit {CURRENT_COMMIT}). No regeneration needed. and stop
   • Build scoped changed-file list:
     • If REPO_TYPE=monorepo, run diff from repo_root and filter to current_project_path unless it is . or empty
     • Else diff the current repo normally
     • Drop excluded paths and obviously irrelevant binary/media files
   • If scoped change list is empty:
     • Update only git_commit in state.json
     • Keep all other fields unchanged
     • Output No in-scope changes. Updated commit reference ({OLD_COMMIT} -> {CURRENT_COMMIT}). and stop
   • Preserve the full scoped changed-file list as the evidence frontier in both FULL and INCREMENTAL.
   • Count changed files:
     • > 50 -> MODE=FULL
     • <= 50 -> MODE=INCREMENTAL
   • If MODE=FULL:
     • INITIAL_MESSAGE=Large change set ({N} files). Wide reconcile (10-15 min)
     • FILE_SCOPE=<scoped changed files>
     • Build FILE_DIFFS as path -> git diff OLD_COMMIT CURRENT_COMMIT -- path
   • If MODE=INCREMENTAL:
     • INITIAL_MESSAGE=Changes detected since last build ({OLD_COMMIT} -> {CURRENT_COMMIT}). Analyzing {N} changed files (2-5 min)
     • FILE_SCOPE=<scoped changed files>
     • Build FILE_DIFFS as path -> git diff OLD_COMMIT CURRENT_COMMIT -- path
4. Print INITIAL_MESSAGE.