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, completing ALL of them:

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

Phase 1: Interactive Discovery

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

Step 1 — Infer intent from input

Accept the following inputs:

• action-or-description — What kind of documentation to create or update

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:

• "MkDocs documentation site" — Full docs site with mkdocs.yml, Material theme
• "Basic markdown files" — Standalone files like README.md, CONTRIBUTING.md, ARCHITECTURE.md
• "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

• "Generate new pages"
• "Update existing pages"
• "Both — generate and update" Store as

  ACTION

  .

Q3 (if

new

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

  MKDOCS_SCOPE

  . If custom, prompt the user for desired pages (free text).

If

DOC_TYPE = basic-markdown

Q2: Prompt the user — Which files? The user may select multiple options:

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

  MARKDOWN_FILES

  . If "Other" is selected, prompt the user 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.

Immediately proceed to Phase 2.

Phase 2: Project Detection & 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 files matching

  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) to scaffold the configuration
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

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

git diff --stat

Immediately proceed to Phase 3.

Phase 3: Codebase Analysis

Goal: Deep codebase exploration to understand what to document.

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:

Step 2 — Run deep codebase 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.

The deep analysis handles all exploration orchestration (reconnaissance, team planning, parallel exploration, and synthesis).

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

After 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. Delegate to a code exploration task to analyze the changed files:
   • Focus: Analyze files changed in the specified range
   • For each significant change, identify what was added/modified/removed, impact on public APIs, and whether any changes are breaking
   • Return a structured report of findings

Immediately 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)
• Pages to update (with specific sections)
• Proposed

  mkdocs.yml

  nav updates
• Page dependency ordering (independent pages first, then pages that cross-reference them)

Basic Markdown:

• Files to create/update (with target paths)
• Proposed structure/outline for each file
• Content scope per file

Change Summary:

• Output formats to generate (Format 1: Changelog, Format 2: Commit message, Format 3: MkDocs page — only if MkDocs site exists)
• Range confirmation
• Scope of changes

Step 2 — User approval

Prompt the user to choose:

• "Approve the plan as-is"
• "Modify the plan" (describe changes)
• "Reduce scope" (select specific items only)

Immediately proceed to Phase 5.

Phase 5: Documentation Generation

Goal: Generate content using documentation writing tasks.

Step 1 — Load templates

• If

  DOC_TYPE = change-summary

  : Use the Change Summary Templates (see below)
• If

  DOC_TYPE = basic-markdown

  : Use the Markdown File Templates (see below)

Step 2 — Group by dependency

• Independent pages/files — Can be written without referencing other new content (API reference, standalone guides, individual markdown files)
• Dependent pages/files — Reference or summarize content from other pages (index pages, overview pages, README that links to CONTRIBUTING)

Step 3 — Delegate to documentation writing tasks

Delegate each page/file to a documentation writing task.

Launch independent pages/files in parallel, then sequential for dependent ones (include generated content from independent pages in the prompt context).

MkDocs prompt template:

Documentation task: [page type — API reference / architecture / how-to / change summary]
Target file: [docs/path/to/page.md]
Output format: MkDocs
Project: [project name] at [project root]

MkDocs site context:
- Theme: Material for MkDocs
- Extensions available: admonitions, code highlighting, tabbed content, Mermaid diagrams
- Diagram guidance: Follow technical-diagrams conventions — use Mermaid for all diagrams with dark text on nodes.
- Existing pages: [list of current doc pages]

Exploration findings:
[Relevant findings from Phase 3 for this page]

Existing page content (if updating):
[Current content of the page, or "New page — no existing content"]

Generate the complete page content in MkDocs-flavored Markdown.

Basic Markdown prompt template:

Documentation task: [file type — README / CONTRIBUTING / ARCHITECTURE / API docs]
Target file: [path/to/file.md]
Output format: Basic Markdown
Project: [project name] at [project root]

File type guidance:
[Relevant structural template from Markdown File Templates section]

Exploration findings:
[Relevant findings from Phase 3 for this file]

Existing file content (if updating):
[Current content, or "New file — no existing content"]

Generate the complete file content in standard GitHub-flavored Markdown.
Do NOT use MkDocs-specific extensions (admonitions, tabbed content, code block titles).
Diagram guidance: Use Mermaid for all diagrams with dark text on nodes. GitHub renders Mermaid natively.

Step 4 — Review generated content

• Verify structure, check for unfilled placeholders
• Validate cross-references between pages/files use correct relative paths

Immediately proceed to Phase 6.

Phase 6: Integration & Finalization

Goal: Write files, validate, present results.

Step 1 — Write files

MkDocs:

• Write pages under

  docs/

• Update

  mkdocs.yml

  nav — read current config, add new pages in logical positions, preserve existing structure

Basic Markdown:

• Write files to their target paths (project root or specified directories)
• For updates, modify existing files

Change Summary:

• Present outputs inline for review
• Write files as applicable (e.g., append to CHANGELOG.md)

Step 2 — Validate

MkDocs:

• Verify all files referenced in

  nav

  exist on disk
• Check for broken cross-references between pages
• If

  mkdocs

  CLI is available, run

  mkdocs build --strict 2>&1

  to check for warnings (non-blocking)

Basic Markdown:

• Validate internal cross-references between files (e.g., README links to CONTRIBUTING)
• Check that referenced paths exist

Step 3 — Present results

Summarize what was done:

• Files created (with paths)
• Files updated (with description of changes)
• Navigation changes (if MkDocs)
• Any validation warnings

For change-summary, present generated outputs directly inline.

Step 4 — Next steps

Prompt the user to choose from relevant options:

MkDocs:

• "Preview the site" (if

  mkdocs serve

  is available)
• "Commit the changes"
• "Generate additional pages"
• "Done — no further action"

Basic Markdown:

• "Commit the changes"
• "Generate additional files"
• "Review a specific file"
• "Done — no further action"

Error Handling

If any phase fails:

1. Explain what went wrong
2. Prompt the user to choose:
   • Retry the phase
   • Skip to next phase (with partial results)
   • Abort the workflow

Non-Git Projects

If the project is not a git repository:

• Skip git remote detection in Phase 2 (omit

  repo_url

  and

  repo_name

  from mkdocs.yml)
• The

  update

  action with git-diff mode is unavailable — fall back to full-scan or targeted mode
• The

  change-summary

  action is unavailable — inform the user and suggest alternatives

Basic Markdown on Non-Git Projects

• CONTRIBUTING.md is still viable — use project conventions instead of git workflow sections
• Skip branch naming and PR process sections; focus on code style, testing, and setup

Phase Failure

• Explain the error clearly
• Offer retry/skip/abort options

Change Summary Templates

Use these templates when generating change summaries in Phase 5.

Format 1: Markdown Changelog

Follows Keep a Changelog conventions. Reference the changelog-format skill for additional guidance.

## [Unreleased]

### Added
- Add [feature] with [key capability]
- Add [new component] for [purpose]

### Changed
- Update [component] to [new behavior]
- Refactor [module] for [improvement]

### Fixed
- Fix [bug] that caused [symptom]

### Removed
- Remove [deprecated feature] in favor of [replacement]

Guidelines

• Use imperative mood ("Add feature" not "Added feature")
• One entry per distinct change
• Group related changes under the same category
• Focus on user-facing impact, not implementation details
• Order categories: Added, Changed, Deprecated, Removed, Fixed, Security

Format 2: Git Commit Message

Follows Conventional Commits style.

type(scope): summary of changes

Detailed description of what changed and why. Cover the motivation
for the change and contrast with previous behavior.

Changes:
- List specific modifications
- Include file paths for significant changes
- Note any breaking changes

BREAKING CHANGE: Description of breaking change (if applicable)

Type Reference

feat

fix

docs

refactor

perf

test

chore

Guidelines

• Subject line: max 72 characters, imperative mood, no period
• Body: wrap at 72 characters, explain "why" not just "what"
• Include

  BREAKING CHANGE:

  footer for breaking changes
• Reference issue numbers where applicable:

  Closes #123

Format 3: MkDocs Documentation Page

Scope: This format applies only when the documentation target is an MkDocs site. For basic markdown projects, use Format 1 (Markdown Changelog) as the primary change summary output.

A full documentation page suitable for a changelog or release notes section.

# Changes: VERSION_OR_RANGE

Summary of changes for this release or period.

## Highlights

> **Key Changes:** Brief summary of the most important changes in this release.

### New Features

#### Feature Name

Description of the new feature and its purpose.

### Improvements

- **Component**: Description of improvement
- **Performance**: Description of optimization

### Bug Fixes

- Fix [issue description] that affected [scenario] (#issue-number)

### Breaking Changes

> **Warning:** The following changes require action when upgrading.

#### Change Description

**Before:**
```language
// Old API or behavior

After:

// New API or behavior

Migration: Steps to update existing code.

Affected Files

path/to/file

Contributors

• @username — Description of contribution

#### Guidelines
- Highlight breaking changes and key features prominently
- Include before/after code examples for API changes
- Provide migration guidance for breaking changes
- Link to relevant documentation pages for new features
- List affected files with change types (Added, Modified, Removed)

### Choosing Formats

When the user requests a change summary, present the three format options:

| Format | Best For |
|--------|----------|
| **Markdown Changelog** | Appending to an existing CHANGELOG.md |
| **Git Commit Message** | Describing changes in a commit or PR |
| **MkDocs Page** | Publishing release notes in the documentation site |

The user may select multiple formats. Generate each independently — they serve different audiences and purposes.

---

## MkDocs Configuration Template

Use this template when scaffolding a new MkDocs project in Phase 2.

### Template

```yaml
site_name: PROJECT_NAME
site_description: PROJECT_DESCRIPTION
site_url: ""
repo_url: REPO_URL
repo_name: REPO_NAME

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.tabs.link
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_guess: false
  - pymdownx.inlinehilite
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.snippets
  - attr_list
  - md_in_html
  - toc:
      permalink: true

nav:
  - Home: index.md
  - Getting Started: getting-started.md

Field Descriptions

site_name

package.json

pyproject.toml

Cargo.toml

site_description

repo_url

git remote get-url origin

repo_name

owner/repo

site_url

Git Remote Detection

Use this approach to populate

repo_url

repo_name

# Get the remote URL
REMOTE_URL=$(git remote get-url origin 2>/dev/null)

# Convert SSH to HTTPS if needed
# git@github.com:owner/repo.git -> https://github.com/owner/repo
if [[ "$REMOTE_URL" == git@* ]]; then
  REMOTE_URL=$(echo "$REMOTE_URL" | sed 's|git@\(.*\):\(.*\)\.git|https://\1/\2|')
fi

# Extract owner/repo for repo_name
REPO_NAME=$(echo "$REMOTE_URL" | sed 's|.*/\([^/]*/[^/]*\)$|\1|' | sed 's|\.git$||')

If not a git repository or no remote is configured, omit

repo_url

repo_name

Starter Pages

docs/index.md

# PROJECT_NAME

PROJECT_DESCRIPTION

## Overview

Brief overview of what the project does and who it's for.

## Quick Start

Minimal steps to get started:

1. Install the project
2. Run a basic example
3. Explore further documentation

## Documentation

| Section | Description |
|---------|-------------|
| [Getting Started](getting-started.md) | Installation and first steps |

docs/getting-started.md

# Getting Started

## Prerequisites

List prerequisites here (language runtime, tools, etc.).

## Installation

Installation instructions for the project.

## Basic Usage

A minimal working example demonstrating core functionality.

## Next Steps

Links to further documentation sections.

Integration Notes

What this component does: Manages documentation lifecycle for MkDocs sites and standalone markdown files, covering initialization, generation, updates, and change summaries through a 6-phase workflow.

Capabilities needed:

• File reading and searching (project detection, existing docs analysis)
• File writing and editing (documentation output)
• Shell command execution (git commands, mkdocs build)
• User interaction (documentation type selection, plan approval)
• Background task delegation (parallel documentation writing)

Adaptation guidance:

• Phase 3 loads deep-analysis from the core-tools package for codebase exploration — this is an external dependency; adapt the delegation mechanism to your platform
• Phase 3 also uses code-explorer from core-tools for change-summary analysis
• Phase 5 delegates to docs-writer tasks — see the docs-writer skill in this package
• The change summary templates and MkDocs configuration template (originally separate reference files) are inlined above
• The markdown file templates reference is in

  references/markdown-file-templates.md

  (kept separate due to size)