Docs

Docs

Create and maintain project documentation in docs/ with a consistent, lightweight structure.

Outputs

Maintain these outputs:

1. docs/SUMMARY.md — documentation entry point (always regenerated) 2. docs/architecture/ — system design, infrastructure, component interactions, data flows, feature flows. Focus on _how the system works_, not file/code structure. 3. docs/codebase/ — file organization, directory structure, entry points, key modules and their responsibilities. Focus on _where things live in the code_. 4. docs/code-standard/ — coding conventions, naming rules, style guides, environment setup, custom rules and patterns the team follows. Focus on _how to write code that fits in with the existing codebase_, best practices, and team conventions, very important for maintaining consistency. 5. docs/project-pdr/ — product goals, use cases, business rules, constraints, and decision rationale. Nice to have many use case/requirements files

Also keep README.md aligned with current docs links and project summary.

Workflow

Step 1: Context Scan

Scan the project to understand what needs documenting:

1. Read existing docs if any (docs/SUMMARY.md and topic folders) 2. Read README.md and key config files (package.json, tsconfig.json, Cargo.toml, etc.) 3. Scan source directories to understand project structure, entry points, and major components 4. Check git log --oneline -20 for recent changes when updating existing docs

Focus on facts: features, architecture, stack, directory structure, and workflows. Do not invent requirements or assume business logic that is not evident from the code.

Step 2: Infer Behavior

• Infer whether the repository needs an initial documentation pass or an incremental update based on the current docs/ state.
• If docs/ does not exist or is clearly incomplete, perform initialization behavior.
• If docs/ already exists with the standard structure, perform update behavior.
• State the inferred behavior briefly when relevant.

Step 3: Produce Documentation

Initialize docs when missing or incomplete

1. Create docs/ and 4 topic folders: architecture/, codebase/, code-standard/, project-pdr/ 2. For each topic folder: a. Scan codebase for relevant information b. Generate content based on codebase scan c. Create topic-specific files based on content found in the codebase. Name each file by its content (e.g., components.md, conventions.md). Do NOT use generic names (overview.md, index.md, main.md). Split into multiple files when content covers 2+ clearly distinct sub-topics. Minimum 1 file per folder. 3. Create docs/SUMMARY.md using the format specified in Content Requirements 4. Update README.md with link to docs/SUMMARY.md

Populate each file with concrete, project-specific content. Avoid placeholders and generic templates.

Update docs when they already exist

1. Detect what changed: compare current code against existing docs. Use git log --oneline and source file scanning to identify new/modified/removed components. 2. Preserve useful existing content and section structure. 3. Update stale or inaccurate sections in-place — do not rewrite from scratch. 4. Add newly discovered features, components, or conventions. 5. Remove clearly obsolete statements. 6. Add, modify, or remove detail files as needed based on content changes. 7. Regenerate docs/SUMMARY.md to match current files — only list files that actually exist on disk. 8. Update README.md if documentation links changed.

Important: The goal is an incremental, surgical update — not a full rewrite.

Step 4: Sync README

Ensure README.md includes:

• Short project overview
• Quick start (if present in project)
• Documentation link pointing to docs/SUMMARY.md

Step 5: Validate Quality

Before finishing, verify:

• docs/SUMMARY.md exists and lists every detail file that actually exists on disk (no phantom entries)
• Each topic folder has at least 1 topic-specific file
• No generic file names (overview.md, index.md, main.md) in topic folders
• README.md links point to docs/SUMMARY.md
• SUMMARY.md is concise and contains file tables for all sections
• Terminology is consistent across files
• No contradictions between docs and code
• Paths and component names are accurate
• Content is concise, specific, and actionable

Content Requirements

SUMMARY.md format

Contains project overview and file tables for each documentation section.

Strictly follow the template in references/summary-template.md.

Topic file rules

• Each file focuses on 1 specific sub-topic within its folder
• Named by content slug: components.md, conventions.md, product-goals.md
• Do NOT use generic names: overview.md, index.md, main.md, general.md
• Keep files focused and concise without enforcing line-count targets

Edge Cases

• Minimal/empty project: If the codebase has very little code, keep topic files short and factual. Do not pad content to reach arbitrary size targets. Mark sections as "TBD — to be documented as the project grows" when there is genuinely nothing to document yet. Even with 1 file per folder, name it by its content.
• Custom files in `docs/`: Preserve any user-created files outside the 4 standard topic folders (e.g., docs/API.md, docs/deployment.md). List them under "Other" in SUMMARY.md. Do not move or rename them.
• Monorepo: If the project contains multiple packages/apps, document the overall structure in architecture/components.md and note each package's purpose. Each package does not need its own full docs set — keep it proportional.

Rules

• Keep documentation factual; do not invent requirements.
• Prefer concise updates over verbose prose.
• Keep docs aligned with current implementation.
• When uncertain, mark assumptions explicitly and request confirmation.
• Ask targeted questions when information cannot be reliably inferred (business goals, ambiguous module ownership, conflicting conventions, unclear architecture decisions).

Documentation Summary

Project name — 1-2 sentence project description. Key tech stack or architecture summary.

Architecture

System design, component interactions, data flows, deployment, and external integrations.

Codebase

Directory structure, entry points, API patterns, and key modules.

Code Standard

Conventions, naming rules, tech stack versions, and development workflows.

Project PDR

Product goals, use cases, business rules, and constraints.

Other

Optional section for repository-specific docs outside the standard topic folders, such as dated brainstorms, plans, or deployment notes.