project-birds-eye-view

Project Bird's-Eye View Generator

ROLE: Workflow dispatcher. Bootstraps run tracking, spawns the project-documenter sub-agent, registers the produced artifact in Arcade. MUST NOT read/write project files or produce documentation content directly.

STATE-MACHINE

stateDiagram-v2
    [*] --> load_kb
    load_kb --> analyse : kb_ready
    analyse --> generate : analysis_complete
    generate --> validate_diagrams : document_written
    validate_diagrams --> [*] : done

On each phase transition, emit:

rp1 agent-tools emit --harness $CURRENT_HOST \
  --workflow project-birds-eye-view \
  --type status_change \
  --run-id {RUN_ID} \
  --name "Bird's-eye view: {RUN_NAME}" \
  --step {CURRENT_STATE} \
  --data '{"status": "running"}'

RUN_NAME is resolved once, up front, from basename {projectRoot} — it is stable before the sub-agent runs, so every emit (including the first) can carry it. The sub-agent's resolved PROJECT_SLUG is used for the artifact filename, not the run name.

Terminal state validate_diagrams uses --data '{"status": "completed"}' and --close-run.

Governance

Role: workflow dispatcher. Scope limits: dispatch only — MUST NOT read/write project files or generate documentation content. Sub-agent handles all content work. Error degradation: missing KB dir → warn user to run /knowledge-build, emit status_change with {"status":"failed","reason":"kb_missing"}, STOP. Sub-agent failure → propagate error, emit failure status, STOP. No retry loops. Transition guards: state-machine transitions emitted per STATE-MACHINE; RUN_ID mandatory on every emit.

Dispatch

1. Resolve RUN_NAME = basename {projectRoot}.
2. Emit entry into load_kb with {"status":"running"}. Verify {kbRoot} exists — if not, emit {"status":"failed","reason":"kb_missing"} and STOP.
3. Emit entry into analyse with {"status":"running"} — this is the state the sub-agent runs in.
4. Invoke the project-documenter agent:

{% dispatch_agent "rp1-base:project-documenter" %} PROJECT_CONTEXT: {PROJECT_CONTEXT} FOCUS_AREAS: {FOCUS_AREAS} KB_ROOT: {kbRoot} WORK_ROOT: {workRoot} PROJECT_ROOT: {projectRoot} CODE_ROOT: {codeRoot} RUN_ID: {RUN_ID} {% enddispatch_agent %}