autodoc-orchestrator

Purpose

Thin orchestrator that drives a 5-phase autonomous documentation pipeline. Takes an existing codebase as input, dispatches specialized subagents to scan, analyze, and write documentation, and produces a complete documentation package with no human gates.

Iron Laws

Pipeline Overview

Phase 0  Interview (if needed)      → collect project path + focus areas
Phase 1  autodoc-scanner            → artifacts/project-map.md
Phase 2  autodoc-analyst × N        → artifacts/analysis/<module>.md  [parallel]
Phase 3  autodoc-architect          → artifacts/architecture.md
Phase 4  autodoc-writer × N         → docs/<section>.md               [parallel]
Phase 5  autodoc-assembler          → docs/README.md + docs/index.md

Phase 0: Initialization

Job Directory Setup

1. Create jobs/autodoc-<slugified-project-name>/
2. Create subdirectories: artifacts/, artifacts/analysis/, docs/, ai/
3. Initialize state.json

Input Assessment

Evaluate what the user provided:

SUFFICIENT — proceed directly to Phase 1 if ALL of:
  ✓ Project directory path (absolute) is provided
  ✓ Path exists and contains code files

NEEDS_INPUT — ask questions if ANY of:
  ✗ No project path given
  ✗ Multiple repos mentioned without clear scope
  ✗ User specified unusual focus (e.g., "only the auth module")

Interview (only when NEEDS_INPUT)

Ask ONLY what is missing. Maximum 4 questions, always with options:

I need a few details to get started:

1. Project path?
   ○ Type the absolute path to the project root

2. Which parts to document? (default: everything)
   A) Full project — backend + frontend + shared
   B) Backend only
   C) Frontend only
   D) Specific path — [type it]

3. Output language?
   A) English (default)
   B) Russian
   C) Both

4. Existing docs to incorporate? (default: none)
   ○ Path to existing docs/README, or skip

Save answers to state.json.config.

Dispatch Protocol

Every subagent dispatch follows this contract:

Agent({
  description: "<phase>: <task>",
  prompt: |
    ## Your Role
    You are <agent_role>. Load skill: skills/<skill-name>/SKILL.md

    ## Task
    <specific task>

    ## Input Artifacts
    <list of file paths to read>

    ## Job Context
    JOB_DIR: <absolute path to job directory>
    PROJECT_DIR: <absolute path to project>
    CONFIG: <from state.json.config>

    ## Output Contract
    1. Write artifact to: <output path>
    2. Return ONLY (apply rules/core/terse-subagent-response.mdc):
       STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT
       summary: (≤5 bullet fragments — no prose)
       concerns: (if DONE_WITH_CONCERNS)
       questions: (if NEEDS_CONTEXT — with A/B/C/D options)
       next_phase_hints: (key findings for orchestrator routing)
})

Status Handling

STATUS: DONE
  → Save summary to state.json.phase_summaries
  → Proceed to next phase

STATUS: DONE_WITH_CONCERNS
  → Log concerns in state.json
  → Proceed (documentation pipeline continues; concerns noted in final report)

STATUS: NEEDS_CONTEXT
  → IF resolvable autonomously (file exists, can be read):
      → Dispatch context-collector or read file directly
      → Re-dispatch subagent with answer
  → IF requires user input:
      → Ask user with A/B/C/D options
      → Re-dispatch with answer
  → Max 2 resolution rounds per phase

Phase 1: Project Scanning

Subagent: autodoc-scanner Input: PROJECT_DIR, CONFIG Output: artifacts/project-map.md

After completion, parse next_phase_hints.modules[] from the scanner's response. This list drives how many parallel analysts to launch in Phase 2.

Phase 2: Deep Analysis (Parallel)

Subagent: autodoc-analyst — one instance per module from project-map Input: artifacts/project-map.md + module path Output: artifacts/analysis/<module-slug>.md

Launch ALL analysts simultaneously:

Agent × N in parallel, one per module:
  module: frontend  → artifacts/analysis/frontend.md
  module: backend   → artifacts/analysis/backend.md
  module: shared    → artifacts/analysis/shared.md
  ...

Wait for ALL to complete before Phase 3.

Phase 3: Architecture Synthesis

Subagent: autodoc-architect Input: artifacts/project-map.md + ALL artifacts/analysis/*.md Output: artifacts/architecture.md

Phase 4: Documentation Writing (Parallel)

Subagent: autodoc-writer — one instance per documentation section

Determine sections from Phase 3 output and CONFIG. Standard sections:

Launch ALL writers simultaneously. Wait for ALL to complete.

Phase 5: Assembly

Subagent: autodoc-assembler Input: ALL docs/*.md + artifacts/architecture.md + artifacts/project-map.md Output: docs/README.md + docs/index.md

The assembler creates the main entry-point document with links to all sections, a brief project overview, and a quick-start section.

State Resumption

Check for interrupted jobs on start:

IF jobs/autodoc-*/state.json exists AND status == "in_progress":
  → Show: "Found interrupted autodoc job: <name> at Phase <N>"
  → Ask: A) Resume  B) Start fresh  C) Show state

Output Structure

jobs/autodoc-<project>/
├── state.json                    # Pipeline state
├── artifacts/
│   ├── project-map.md            # Phase 1
│   └── analysis/                 # Phase 2
│       ├── frontend.md
│       ├── backend.md
│       └── <module>.md
├── docs/                         # Final documentation
│   ├── README.md                 # Main entry point (Phase 5)
│   ├── index.md                  # Navigation index (Phase 5)
│   ├── onboarding.md             # Phase 4
│   ├── architecture.md           # Phase 4
│   ├── modules.md                # Phase 4
│   ├── api-reference.md          # Phase 4 (if applicable)
│   └── data-models.md            # Phase 4 (if applicable)
└── ai/
    └── context.md                # Internal context snapshot

Final Report

After Phase 5, present to user:

autodoc complete for: <project name>

Documentation generated:
  ✓ docs/README.md         — main entry point
  ✓ docs/onboarding.md     — setup + dev workflow
  ✓ docs/architecture.md   — system architecture
  ✓ docs/modules.md        — module reference
  ✓ docs/api-reference.md  — API contracts
  ✓ docs/data-models.md    — data schemas

Modules analyzed: <N> (<list>)
Concerns: <none | list>

Full docs: jobs/autodoc-<name>/docs/

state.json Template

{
  "job_name": "autodoc-<slug>",
  "created_at": "<ISO>",
  "current_phase": 0,
  "status": "in_progress",
  "config": {
    "project_dir": null,
    "scope": "full",
    "language": "en",
    "existing_docs": null
  },
  "detected_modules": [],
  "detected_sections": [],
  "phase_summaries": {},
  "concerns": [],
  "history": []
}