knowledge-build

name	knowledge-build
description	Orchestrates parallel KB generation using spatial analysis and a map-reduce architecture with incremental and feature-learning modes.
allowed-tools	Bash(echo *), Bash(rp1 *), Bash(git *), Bash(jq *), Bash(wc *), Bash(mkdir *)
metadata	{"category":"knowledge","is_workflow":true,"arcade_tracked":false,"workflow":{"run_policy":"fresh","identity_args":[]},"version":"2.2.1","tags":["documentation","analysis","planning","core","parallel"],"created":"2025-10-25T00:00:00.000Z","updated":"2026-04-09T00:00:00.000Z","author":"cloud-on-prem/rp1","arguments":[{"name":"FEATURE_ID","type":"string","required":false,"description":"Feature ID to incorporate learnings from an archived or active feature into KB"}],"sub_agents":["rp1-base:kb-spatial-analyzer","rp1-base:kb-concept-extractor","rp1-base:kb-architecture-mapper","rp1-base:kb-interaction-mapper","rp1-base:kb-module-analyzer","rp1-base:kb-pattern-extractor"]}

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
  • 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 5 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.

2. Spatial Analysis

1. Spawn the spatial analyzer with the actual mode and changed-file frontier:

{% dispatch_agent "rp1-base:kb-spatial-analyzer" %} Use the computed build inputs from the parent orchestrator.

• MODE: actual build mode (FULL, INCREMENTAL, or FEATURE_LEARNING)
• CHANGED_FILES: actual JSON array for the scoped changed-file list when available; empty only for first-time FULL
• Task: rank files 0-5 and categorize them into index_files, concept_files, arch_files, interaction_files, module_files
• Return JSON only with:
  • repo_type
  • monorepo_projects
  • total_files_scanned
  • index_files
  • concept_files
  • arch_files
  • interaction_files
  • module_files
  • local_meta Do not echo placeholder tokens. {% enddispatch_agent %}

2. Parse and validate the JSON.
3. Fatal if:
   • JSON missing
   • required keys missing
   • all file categories empty
4. Store:
   • repo_type
   • monorepo_projects
   • local_meta.repo_root
   • local_meta.current_project_path

3. Parallel Analysis

1. Compute:

• PATTERN_FILES = unique(concept_files + module_files)
• INTERACTION_FILES = unique(interaction_files)
• per-agent diff subsets from FILE_DIFFS

2. Spawn all 5 analyzers in one batch:

{% dispatch_agent "rp1-base:kb-concept-extractor", background %} Use the parent-computed inputs.

• KB_ROOT={kbRoot}
• MODE: actual mode
• REPO_TYPE: actual repo type
• CONCEPT_FILES_JSON: actual JSON array
• FILE_DIFFS: actual diff subset JSON or empty object
• FEATURE_CONTEXT: actual feature context JSON or empty object
• Task: return JSON only for concept_map.md {% enddispatch_agent %}

{% dispatch_agent "rp1-base:kb-architecture-mapper", background %} Use the parent-computed inputs.

• KB_ROOT={kbRoot}
• MODE: actual mode
• REPO_TYPE: actual repo type
• ARCH_FILES_JSON: actual JSON array
• FILE_DIFFS: actual diff subset JSON or empty object
• FEATURE_CONTEXT: actual feature context JSON or empty object
• Task: return JSON only for architecture.md {% enddispatch_agent %}

{% dispatch_agent "rp1-base:kb-interaction-mapper", background %} Use the parent-computed inputs.

• KB_ROOT={kbRoot}
• MODE: actual mode
• REPO_TYPE: actual repo type
• INTERACTION_FILES_JSON: actual JSON array
• FILE_DIFFS: actual diff subset JSON or empty object
• FEATURE_CONTEXT: actual feature context JSON or empty object
• Task: return JSON only for interaction-model.md {% enddispatch_agent %}

{% dispatch_agent "rp1-base:kb-module-analyzer", background %} Use the parent-computed inputs.

• KB_ROOT={kbRoot}
• MODE: actual mode
• REPO_TYPE: actual repo type
• MODULE_FILES_JSON: actual JSON array
• FILE_DIFFS: actual diff subset JSON or empty object
• FEATURE_CONTEXT: actual feature context JSON or empty object
• Task: return JSON only for modules.md {% enddispatch_agent %}

{% dispatch_agent "rp1-base:kb-pattern-extractor", background %} Use the parent-computed inputs.

• KB_ROOT={kbRoot}
• MODE: actual mode
• REPO_TYPE: actual repo type
• PATTERN_FILES_JSON: actual JSON array
• FILE_DIFFS: actual diff subset JSON or empty object
• FEATURE_CONTEXT: actual feature context JSON or empty object
• Task: return JSON only for patterns.md
• Constraint: rendered patterns.md MUST stay <=150 lines {% enddispatch_agent %}

3. Wait for all 5 agents to finish.
4. Parse JSON from each response.
5. Failure policy:
   • 0 failures: continue normally
   • 1 failure: continue, but generate a placeholder section for the failed file and report partial success
   • 2+ failures: do not write partial KB, stop

4. Reduce + Write

1. Read needed KB templates directly from plugins/base/skills/artifact-templates/templates/knowledge-base/ (fall back to rp1-base:artifact-templates SKILL.md index if a direct path fails).
2. Merge analyzer output into:
   • concept_map.md
   • architecture.md
   • interaction-model.md
   • modules.md
   • patterns.md
3. Validate the architecture.md Mermaid diagram via rp1-base:mermaid.
   • If invalid: simplify or omit the broken diagram, do not fail the whole run for diagram syntax alone.
4. Write these files first:
   • {kbRoot}/concept_map.md
   • {kbRoot}/architecture.md
   • {kbRoot}/interaction-model.md
   • {kbRoot}/modules.md
   • {kbRoot}/patterns.md
5. Count lines for the written markdown files.
6. Generate index.md directly from aggregated results plus measured line counts.
7. Write {kbRoot}/index.md last.
8. Write {kbRoot}/state.json with:
   • strategy=parallel-map-reduce
   • repo_type
   • monorepo_projects
   • generated_at
   • git_commit
   • files_analyzed
   • languages
   • metrics
9. Write {kbRoot}/meta.json with:
   • repo_root
   • current_project_path
10. meta.json is local-only. Write it, but do not register it anywhere.

§FAIL

Fatal errors:

• missing feature path
• empty FILES_MODIFIED in feature mode
• git failure during git-driven mode
• spatial analyzer failure or invalid JSON
• template load failure
• repeated write failure
• 2+ analyzer failures

On any fatal error:

• output a concise message naming the failed phase + cause
• stop immediately

§OUT

User-visible output only:

• Initial mode/status line
• Optional high-level progress line when the run is long
• Final report

Final report must include:

• overall result:
  • Knowledge Base Generated Successfully
  • Feature Learnings Captured
  • or Partial KB Generated
• repository type
• files analyzed
• files written under .rp1/context/
• note that this passive workflow does not register an Arcade run
• reminder: agents load KB automatically via progressive disclosure