docs-manager

Documentation Manager Workflow

Execute a structured 6-phase workflow for managing documentation. Supports two documentation formats (MkDocs sites and standalone markdown files) and three action types (generate, update, change summary).

Phase Overview

Execute these phases in order:

1. Interactive Discovery -- Determine documentation type, format, and scope through user interaction
2. Project Detection and Setup -- Detect project context, conditionally scaffold MkDocs
3. Codebase Analysis -- Deep codebase exploration using the deep-analysis skill
4. Documentation Planning -- Translate analysis findings into a concrete plan for user approval
5. Documentation Generation -- Launch docs-writer agents to generate content
6. Integration and Finalization -- Write files, validate, present results

Nested Agents

• docs-writer (agents/docs-writer.md) -- Generates MkDocs-flavored or standard GitHub-flavored Markdown documentation from codebase analysis findings. Used in Phase 5.
• code-explorer (cross-reference: ../../core-tools/skills/deep-analysis/agents/code-explorer.md from the core-tools package) -- Used in Phase 3 for change-summary path analysis.

Phase 1: Interactive Discovery

Goal: Determine through user interaction what documentation to create and in what format.

Step 1 -- Infer intent from $ARGUMENTS

Parse the user's input to pre-fill selections:

• Keywords like "README", "CONTRIBUTING", "ARCHITECTURE" -> infer basic-markdown
• Keywords like "mkdocs", "docs site", "documentation site" -> infer mkdocs
• Keywords like "changelog", "release notes", "what changed" -> infer change-summary

If the intent is clear, present a summary for quick confirmation before proceeding (skip to Step 4). If ambiguous, proceed to Step 2.

Step 2 -- Q1: Documentation type

If the documentation type is ambiguous or needs confirmation, prompt the user to choose:

What type of documentation would you like to create?
1. "MkDocs documentation site" -- Full docs site with mkdocs.yml, Material theme
2. "Basic markdown files" -- Standalone files like README.md, CONTRIBUTING.md, ARCHITECTURE.md
3. "Change summary" -- Changelog, release notes, commit message

Store as DOC_TYPE = mkdocs | basic-markdown | change-summary.

Step 3 -- Conditional follow-up questions

If DOC_TYPE = mkdocs:

Q2: Prompt the user -- Existing project or new setup?

• "Existing MkDocs project" -> MKDOCS_MODE = existing
• "New MkDocs setup" -> MKDOCS_MODE = new

Q3 (if existing): Prompt the user -- What to do?

• "Generate new pages"
• "Update existing pages"
• "Both -- generate and update"

Store as ACTION.

Q3 (if new): Prompt the user -- Scope?

• "Full documentation"
• "Getting started only (minimal init)"
• "Custom pages"

Store as MKDOCS_SCOPE. If custom, ask for desired pages (free text).

If DOC_TYPE = basic-markdown:

Q2: Prompt the user (multiSelect) -- Which files?

• "README.md"
• "CONTRIBUTING.md"
• "ARCHITECTURE.md"
• "API documentation"

Store as MARKDOWN_FILES. If "Other" is selected, ask for custom file paths/descriptions.

If DOC_TYPE = change-summary:

Q2: Prompt the user -- What range?

• "Since last tag"
• "Between two refs"
• "Recent changes"

Follow up for specific range details (tag name, ref pair, etc.).

Step 4 -- Confirm selections

Present a summary of all selections and prompt the user to choose:

• "Proceed"
• "Change selections"

If the user wants to change, loop back to the relevant question.

Proceed to Phase 2.

Phase 2: Project Detection and Setup

Goal: Detect project context automatically, conditionally scaffold MkDocs.

Step 1 -- Detect project metadata (all paths)

• Check manifests: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml
• Run git remote get-url origin 2>/dev/null
• Note primary language and framework

Step 2 -- Check existing documentation (all paths)

• Search for docs/**/*.md, README.md, CONTRIBUTING.md, ARCHITECTURE.md
• For MkDocs: check for mkdocs.yml/mkdocs.yaml, read if found

Step 3 -- MkDocs Initialization (only if DOC_TYPE = mkdocs AND MKDOCS_MODE = new)

1. Use the MkDocs configuration template (see below)
2. Fill template with detected metadata (ask the user if incomplete)
3. Generate mkdocs.yml, create docs/index.md and docs/getting-started.md
4. Present scaffold for confirmation before writing

If MKDOCS_SCOPE = minimal (getting started only): write the scaffold files and skip to Phase 6.

Step 4 -- Set action-specific context (for update/change-summary)

For update modes, determine the approach:

• git-diff -- Update docs affected by recent code changes (default if user mentions "recent changes" or a branch/tag)
• full-scan -- Compare all source code against all docs for gap analysis (default if user says "full update" or "sync all")
• targeted -- Update specific pages or sections (default if user specifies file paths or page names)

For change-summary, run git log and git diff --stat for the determined range.

Proceed to Phase 3.

Phase 3: Codebase Analysis

Goal: Deep codebase exploration using the deep-analysis skill.

Skip conditions:

• Skip for change-summary (uses git-based analysis instead -- see below)
• Skip for MkDocs minimal init-only (MKDOCS_SCOPE = minimal)

Step 1 -- Build documentation-focused analysis context

Construct a specific context string based on Phase 1 selections:

| Selection | Analysis Context | |-----------|-----------------| | MkDocs generate | "Documentation generation -- find all public APIs, architecture, integration points, and existing documentation..." | | MkDocs update | "Documentation update -- identify changes to public APIs, outdated references, documentation gaps..." | | Basic markdown README | "Project overview -- understand purpose, architecture, setup, key features, configuration, and dependencies..." | | Basic markdown ARCHITECTURE | "Architecture documentation -- map system structure, components, data flow, design decisions, key dependencies..." | | Basic markdown API docs | "API documentation -- find all public functions, classes, methods, types, their signatures and usage patterns..." | | Basic markdown CONTRIBUTING | "Contribution guidelines -- find dev workflow, testing setup, code style rules, commit conventions, CI process..." | | Multiple files | Combine relevant contexts from above |

Step 2 -- Run deep-analysis

Refer to the deep-analysis skill (from the core-tools package) and follow its workflow.

Pass the documentation-focused analysis context from Step 1.

Deep-analysis handles all agent orchestration (reconnaissance, team planning, team creation, explorers + synthesizer).

Step 3 -- Supplemental analysis for update with git-diff mode

After deep-analysis, additionally:

1. Run git diff --name-only [base-ref] for changed files
2. Search existing docs for references to changed files/functions
3. Cross-reference with synthesis findings

For change-summary path (instead of deep-analysis)

1. Run git log --oneline [range] and git diff --stat [range]
2. Launch 1 exploration agent (see the code-explorer agent from the core-tools package: ../../core-tools/skills/deep-analysis/agents/code-explorer.md) to analyze the changed files:

``` Analysis context: Change summary for [range] Focus area: These files changed in the specified range: [list from git diff --stat]

For each significant change, identify:

• What was added, modified, or removed
• Impact on public APIs and user-facing behavior
• Whether any changes are breaking

Return a structured report of your findings. ```

Proceed to Phase 4.

Phase 4: Documentation Planning

Goal: Translate analysis findings into a concrete documentation plan.

Step 1 -- Produce plan based on doc type

MkDocs:

• Pages to create (with docs/ paths