Aif Docs

Docs - Project Documentation Generator

Generate, maintain, and improve project documentation following a landing-page README + detailed docs-directory structure.

Core Principles

1. README is a landing page, not a manual. ~80-120 lines. First impression, install, quick example, links to details.
2. Details go to the resolved docs directory (paths.docs, default: docs/). Each file is self-contained — one topic, one page. A user should be able to read a single doc file and get the full picture on that topic.
3. No duplication. If information lives in the resolved docs directory, README links to it — does not repeat it. Exception: installation command can appear in both (users expect it in README).
4. Navigation. Every doc file in the resolved docs directory has a header line with prev/next links following the Documentation table order: [← Previous Page](prev.md) · [Back to README](<docs-to-readme-link>) · [Next Page →](next.md). First page has no prev link; last page has no next link. Every page ends with a "See Also" section linking to 2-3 related pages.
5. Cross-links use relative paths. From README: link to the resolved docs directory path (for example docs/workflow.md by default). Between doc pages in the same directory: workflow.md.
6. Scannable. Use tables, bullet lists, and code blocks. Avoid long paragraphs. Users scan, they don't read.

Workflow

Step 0: Load Config & Project Context

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description, paths.architecture, and paths.docs
• Language: language.ui for prompts and language.artifacts for generated docs

If config.yaml doesn't exist, use defaults:

• DESCRIPTION.md: .ai-factory/DESCRIPTION.md
• ARCHITECTURE.md: .ai-factory/ARCHITECTURE.md
• Docs directory: docs/
• Language: en (English)

Note: README.md remains the landing page in the project root. Detailed docs are written to the resolved paths.docs directory (default: docs/).

THEN: Read .ai-factory/DESCRIPTION.md (use path from config) if it exists to understand:

• Tech stack (language, framework, database)
• Project purpose and architecture
• Key features and conventions

Also read .ai-factory/ARCHITECTURE.md (use path from config) if it exists to align documentation with the project's structure and boundaries.

Explore the codebase:

• Read package.json, composer.json, requirements.txt, go.mod, Cargo.toml, etc.
• Scan src/ structure to understand architecture
• Look for existing docs, comments, API endpoints, CLI commands
• Check for existing README.md and the resolved docs directory

Read .ai-factory/skill-context/aif-docs/SKILL.md — MANDATORY if the file exists.

This file contains project-specific rules accumulated by /aif-evolve from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

• Treat them as project-level overrides for this skill's general instructions
• When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)
• When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
• Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient
• CRITICAL: skill-context rules apply to ALL outputs of this skill — including README.md, documentation pages, and their templates. The templates in this SKILL.md are base structures. If a skill-context rule says "docs MUST include X" or "README MUST have section Y" — you MUST augment the templates accordingly. Generating documentation that violates skill-context rules is a bug.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.

Scan for scattered markdown files in project root:

Use Glob to find all *.md files in the project root (exclude node_modules/, .ai-factory/, agent dirs):

CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md, DEPLOYMENT.md,
SECURITY.md, API.md, SETUP.md, DEVELOPMENT.md, TESTING.md, etc.

Record each file, its size, and a brief summary of its content. This list is used in Step 1.1.

Step 0.1: Parse Flags

--web  → Generate HTML version of documentation

Step 1: Determine Current State

Check what documentation already exists:

State A: No README.md                        → Full generation (README + docs dir)
State B: README.md exists, no docs dir      → Analyze README, propose split into docs dir
State C: README.md + docs dir exist         → Depends on flags (see below)

State C with --web flag — ask the user:

Documentation already exists (README.md + resolved docs directory).

AskUserQuestion: What would you like to do?

Options:
1. Generate HTML only — build site from current docs as-is
2. Audit & improve first — check for issues, then generate HTML
3. Audit only — check for issues without generating HTML

Based on choice:

• Generate HTML only → skip Step 1.1, Step 2, Step 4 — go directly to Step 3 (HTML generation), then done
• Audit & improve first → run Step 1.1 → Step 2 (State C) → Step 3 → Step 4 → Step 4.1
• Audit only → run Step 1.1 → Step 2 (State C) → Step 4 → Step 4.1 (skip Step 3)

State C without --web flag → run Step 2 (State C) as usual.

Step 1.1: Check for Scattered Markdown Files

If scattered .md files were found in the project root (from Step 0), propose consolidating them into the resolved docs directory.

Common files that should move to the resolved docs directory:

Files that stay in root (standard convention):

• README.md — always stays
• CHANGELOG.md — standard root-level file, keep as-is
• LICENSE / LICENSE.md — standard root-level file, keep as-is
• CODE_OF_CONDUCT.md — standard root-level file, keep as-is

If scattered files found, ask the user:

Found [N] markdown files in the project root:

  CONTRIBUTING.md (45 lines) — contribution guidelines
  ARCHITECTURE.md (120 lines) — system architecture overview
  DEPLOYMENT.md (80 lines) — deployment instructions
  SETUP.md (30 lines) — setup guide (overlaps with getting-started)

Suggested actions:
  → Move CONTRIBUTING.md → <resolved docs dir>/contributing.md
  → Move ARCHITECTURE.md → <resolved docs dir>/architecture.md
  → Move DEPLOYMENT.md → <resolved docs dir>/deployment.md
  → Merge SETUP.md into <resolved docs dir>/getting-started.md

AskUserQuestion: Would you like to apply the consolidation?

Options:
1. Apply all suggestions
2. Let me pick which ones
3. Skip — keep files where they are

Based on choice:

• Apply all suggestions → move/merge all listed files, continue to Step 2
• Let me pick which ones → present each file individually for approval, apply selected
• Skip → leave files where they are, continue to Step 2

When moving/merging:

1. Create the target file in the resolved docs directory with prev/next navigation header (following Documentation table order) and "See Also" footer
2. If merging into an existing doc — append content under a new section header, avoid duplicating info that's already there
3. Do NOT delete originals yet — keep them until the review step confirms everything is in place
4. Add the new doc page to README's Documentation table using the correct path relative to README
5. Update any links in other files that pointed to the old root-level file
6. Record which files were moved/merged — this list is used in Step 4.1

IMPORTANT: Never force-move files. Always show the plan and get user approval first.

Step 2 (State A): Generate from Scratch

When no README.md exists, generate the full documentation set.

2.1: Analyze project for documentation topics

Explore the codebase and identify documentation topics:

Always include:
- getting-started.md    (installation, setup, quick start)

Include if relevant:
- architecture.md       (if project has clear architecture: services, modules, layers)
- api.md                (if project exposes API endpoints)
- configuration.md      (if project has config files, env vars, feature flags)
- deployment.md         (if Dockerfile, CI/CD, deploy scripts exist)
- contributing.md       (if open-source or team project)
- security.md           (if auth, permissions, or security patterns exist)
- testing.md            (if test suite exists)
- cli.md                (if project has CLI commands)

Ask the user:

I've analyzed your project and suggest these documentation pages:

1. getting-started.md — Installation, setup, quick start
2. architecture.md — Project structure and patterns
3. api.md — API endpoints reference
4. configuration.md — Environment variables and config

AskUserQuestion: Would you like to generate these documentation pages?

Options:
1. Generate all of these
2. Let me pick which ones
3. Add more topics

Based on choice:

• Generate all → proceed to generate README.md and all listed doc files in the resolved docs directory
• Let me pick → present each topic for individual approval, generate only approved
• Add more topics → ask what additional topics to include, confirm final list, then generate

2.2: Generate README.md

Structure (aim for ~80-120 lines):

# Project Name

> One-line tagline describing the project.

Brief 2-3 sentence description of what this project does and why it exists.

## Quick Start

\`\`\`bash
# Installation steps (1-3 commands)
\`\`\`

## Key Features

- **Feature 1** — brief description
- **Feature 2** — brief description
- **Feature 3** — brief description

## Example

\`\`\`
# Show a real usage example — this is where users decide "I want this"
\`\`\`

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](<readme-to-docs-dir>/getting-started.md) | Installation, setup, first steps |
| [Architecture](<readme-to-docs-dir>/architecture.md) | Project structure and patterns |
| [API Reference](<readme-to-docs-dir>/api.md) | Endpoints, request/response formats |
| [Configuration](<readme-to-docs-dir>/configuration.md) | Environment variables, config files |

## License

MIT (or whatever is in the project)

Key rules for README:

• Logo/badge line at the top (if project has one)
• Tagline as blockquote
• Quick Start with real installation commands (detect from package manager)
• Key Features as bullet list (3-6 items, scannable)
• Real usage example that shows the "wow factor"
• Documentation table with links to the resolved docs directory
• License at the bottom
• NO long descriptions, NO full API reference, NO configuration details

2.3: Generate documentation files in the resolved docs directory

For each approved topic, create a doc file:

[← Previous Topic](previous-topic.md) · [Back to README](<docs-to-readme-link>) · [Next Topic →](next-topic.md)

# Topic Title

Content organized by subtopic with headers, code examples, and tables.
Keep each section self-contained.

## See Also

- [Related Topic 1](related-topic.md) — brief description
- [Related Topic 2](other-topic.md) — brief description

Navigation link order follows the Documentation table in README.md (top to bottom). The first doc page omits the "← Previous" link; the last page omits the "Next →" link. Use the correct relative link from the resolved docs directory back to README.md. Example for the default docs/ layout:

getting-started.md:  [Back to README](../README.md) · [Architecture →](architecture.md)
architecture.md:     [← Getting Started](getting-started.md) · [Back to README](../README.md) · [API Reference →](api.md)
api.md:              [← Architecture](architecture.md) · [Back to README](../README.md) · [Configuration →](configuration.md)
configuration.md:    [← API Reference](api.md) · [Back to README](../README.md)

Content guidelines per topic:

getting-started.md:

• Prerequisites (runtime versions, tools needed)
• Step-by-step installation
• First run / quick start
• Verify it works (expected output)
• Next steps links

architecture.md:

• High-level overview (diagram if useful)
• Directory structure with explanations
• Key patterns (naming, imports, error handling)
• Data flow

api.md:

• Base URL / configuration
• Authentication
• Endpoints grouped by resource
• Request/response examples
• Error codes

configuration.md:

• All environment variables with descriptions and defaults
• Config files and their purpose
• Feature flags

deployment.md:

• Build steps
• Environment setup
• CI/CD pipeline description
• Monitoring / health checks

Step 2 (State B): Split Existing README into the resolved docs directory

When README.md exists but is long (150+ lines) and there's no resolved docs directory yet.