--- name: autodoc-orchestrator description: > Autonomous reverse-engineering documentation pipeline — scans an existing codebase and produces comprehensive developer documentation without user involvement after initial setup. Use when the user provides a repo path, asks to document existing code, or wants onboarding docs, an API reference, or an architecture overview generated automatically. NOT for: writing new PRDs or planning new features (use gproject-orchestrator). triggers: - "autodoc" - "document codebase" - "reverse engineer docs" - "автодок" - "document this codebase" - "generate docs for my project" - "reverse engineer documentation" - "задокументируй кодовую базу" - "сгенерируй документацию проекта" metadata: version: 1.0.0 --- **Preflight:** run in the main session. Without a subagent-spawn tool (`Agent`, `spawn_subagent` or the host's equivalent) or depth budget, output only `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`, with no tool calls. # autodoc-orchestrator ## Purpose Thin orchestrator that drives a 5-phase autonomous documentation pipeline. Plan bridge: publish `phase-0`…`phase-5` with `plan_set` and `plan_update`; `state.json` stays the source of truth — see the `session-plan-bridge` rule. 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. --- ## Execution metrics (opt-in) When a USER runs this orchestrator directly (not as a dispatched subagent), at the start ask "Collect execution statistics for this run? (yes/no)" per `.metaproject/rules/core/execution-metrics.md`. If yes, append the `## Execution Metrics` section at the end and save it under the run's artifact dir (`.metaproject/data/gdwiki/metrics/` or the docs output dir). Never ask or emit it when dispatched as a subagent. ## Iron Laws | # | Law | |---|-----| | 1 | Orchestrator NEVER reads or summarizes code itself — only subagents do | | 2 | Orchestrator NEVER writes documentation content — only subagents do | | 3 | Every phase MUST produce artifact files before proceeding | | 4 | Phase 2 analysts run in PARALLEL — one per detected module/domain | | 5 | Phase 4 writers run in PARALLEL — one per documentation section | | 6 | Subagents receive ONLY artifacts listed in their dispatch contract | | 7 | If a subagent returns NEEDS_CONTEXT, resolve autonomously before re-dispatching | --- ## Red Flags Stop and re-read this skill if you are thinking: | Rationalization | Rebuttal | |---|---| | "The subagent's response summarized its findings, so the phase is complete." | Iron Law 3 requires an artifact FILE. The next phase reads `artifacts/analysis/*.md`, not your transcript — a phase whose file is missing produces a downstream subagent documenting nothing. Check the path exists before advancing. | | "This module is tiny — faster to describe it myself than to dispatch an analyst." | Iron Laws 1 and 2 have no size exception. The moment the orchestrator writes content, the pipeline has one unreviewed author whose output no artifact backs, and the parallel structure silently becomes serial guesswork. | | "The scanner found 12 modules; I'll analyze the important ones and cover the rest later." | Phase 2 is one analyst per detected module, launched together, and Phase 3 waits for all of them. A partial analysis set yields an architecture doc that describes a system missing several of its parts, with nothing marking the omission. | | "A writer came back DONE_WITH_CONCERNS, but the file looks fine, so I'll drop the concern." | `DONE_WITH_CONCERNS` exists so the concern reaches the user. It goes into `state.json` and into the Final Report's `Concerns` line. A dropped concern is indistinguishable from a clean run. | | "The subagent asked for context twice — I know this repo, I'll answer from memory." | Iron Law 1 again: answering from your own reading of the code is the orchestrator reading code. Resolve from artifacts or a dispatched collector; after two rounds, ask the user with A/B/C/D options. | | "There is an interrupted job in `jobs/`, but starting fresh is cleaner." | State Resumption is the user's call, offered as A/B/C. Starting fresh silently discards completed phases they paid for and may overwrite `docs/` files they have already read. | --- ## 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/.md [parallel] Phase 3 autodoc-architect → artifacts/architecture.md Phase 4 autodoc-writer × N → docs/
.md [parallel] Phase 5 autodoc-assembler → docs/README.md + docs/index.md ``` --- ## Phase 0: Initialization ### Job Directory Setup 1. Create `jobs/autodoc-/` 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: ": ", prompt: | ## Your Role You are . Load skill: skills//SKILL.md ## Task ## Input Artifacts ## Job Context JOB_DIR: PROJECT_DIR: CONFIG: ## Output Contract 1. Write artifact to: 2. Return ONLY: STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT summary: (3-5 sentences) 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/.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: | Section | Output file | Always? | |---------|------------|---------| | Onboarding | `docs/onboarding.md` | Yes | | Architecture overview | `docs/architecture.md` | Yes | | Module reference | `docs/modules.md` | Yes | | API reference | `docs/api-reference.md` | Only if APIs detected | | Data models | `docs/data-models.md` | Only if schemas detected | 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: at Phase " → Ask: A) Resume B) Start fresh C) Show state ``` --- ## Output Structure ``` jobs/autodoc-/ ├── state.json # Pipeline state ├── artifacts/ │ ├── project-map.md # Phase 1 │ └── analysis/ # Phase 2 │ ├── frontend.md │ ├── backend.md │ └── .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: 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: () Concerns: Full docs: jobs/autodoc-/docs/ ``` --- ## state.json Template ```json { "job_name": "autodoc-", "created_at": "", "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": [] } ```