Doc System Generator#

Analyze any project → derive optimal grouping → generate complete Markdown documentation system → self-check completeness.

Workflow#

Phase 0: Environment Probe#

1. Detect existing docs: Check for docs/, doc/, documentation/, or any .md files at project root

2. Detect entry file: Check for AGENTS.md, CLAUDE.md, GEMINI.md, README.md

3. Decision point:

   • Existing docs found → present two equal options to user (no default):

     • Option A: Respect existing structure + suggest improvements
     • Option B: Full redesign from scratch

   • No existing docs → proceed directly to Phase 1

4. Deploy tool: Copy scripts/md-sections.sh to project's scripts/ directory (create if needed)

   • Fallback: If md-sections.sh fails (corrupted Markdown, exotic separators), use AI Agent's native Read/Grep tools directly. No additional parser needed.
   • Scope boundary: Online documentation platforms (Notion, Confluence, GitBook) are out of scope — they require API tokens and have their own navigation

Phase 1: Project Analysis#

1. Detect explicit boundaries (🤖 automatic):

   • Scan build files → extract modules/packages/subprojects list
   • Scan directory structure → identify hierarchy pattern
   • Detect entry files → determine application boundaries

2. Identify architecture pattern (🤖👤 semi-automatic):

   • Analyze code organization → match pattern (layered/ECS/microservice/pipeline/plugin/SPA/embedded)
   • Analyze dependency direction → determine coupling style
   • Analyze test structure → identify concern separation

3. Identify cross-cutting concerns (🤖👤 semi-automatic):

   • Scan config files → extract concerns (CI, security, i18n, testing, deployment)
   • Analyze code patterns → identify concerns (error handling, logging, caching)
   • Analyze dependencies → list framework capabilities

4. Optional field research: If unfamiliar project type or user requests, search for industry documentation practices for this tech stack/domain. Use results as hints only, not mandates.

→ Output: Project Profile (JSON) containing: techStack, modules, architecture, concerns. Show Phase 1 reasoning to user before proceeding.

For detailed signal tables and detection methods, see grouping-detection.md.

Phase 2: Grouping Derivation#

1. Derive grouping dimensions from Phase 1 results:

   • Module boundaries → basis for "module" document grouping
   • Architecture pattern → basis for "architecture" document grouping
   • Cross-cutting concerns → basis for "standards/conventions" document grouping

2. Quality check (以职责为核心):

• Cohesion: Do documents in each group answer the same class of questions?
• Independence: Does each group carry a distinct documentation responsibility?
• Discoverability: Can readers locate documents by intent?

1. Present derivation to user: Show reasoning process + result. User confirms or adjusts.

Phase 3: Template Derivation#

Key principle: Three-track system is the foundation. Read three-track-philosophy.md for full philosophy.

1. Classify each document group into tracks:

   • 🔴 Intent: Records design intent (frozen after creation)
   • 🟢 Contract: Follows code (code → doc alignment)
   • 🔵 Constraint: Drives code (doc → code alignment)

2. Determine template flexibility for each group: text

   Documents answer same class of questions?
   ├── No  → Flexibility 1: Fully Independent
   └── Yes → Reader expectations identical?
            ├── Yes → Flexibility 3: Fully Unified
            └── No  → Shared core but unique needs?
                     ├── Yes → Flexibility 4: Mixed (unified shell + free core)
                     └── No  → Flexibility 2: Shell Unified
   
   

3. Generate fixed shell (three tiers):

   • Required: Title + one-sentence purpose + 📋 TOC + track label (🔴/🟢/🔵)
   • Recommended: Overview/background + related docs
   • Optional: Change history (Contract track) / Checklist (Constraint track) / Mermaid diagram

4. Derive core chapters:

   • Primary path: Reader questions → chapter names (per track's typical reader questions)
   • Secondary path: Code patterns → supplementary technical chapters
   • Optional: Field research for domain-specific chapter conventions

5. Present templates to user: Show derived templates per group. User confirms or adjusts.

For detailed template derivation methods, see template-derivation.md.

Phase 4: Document Generation#

1. Generate entry file (AGENTS.md or equivalent):

   • Documentation system overview (tech stack summary, module structure)
   • Core coding rules extracted from Constraint track
   • Document index with reference strength (⛔ MUST / ⚠️ SHOULD / 💡 MAY)
   • Layered disclosure rule as highest priority constraint

2. Generate meta-system doc (docs/README.md):

   • Three-track system definition
   • Seven writing principles (see Constraints below)
   • Template descriptions
   • Navigation index
   • Maintenance governance (🤖/🤖👤/👤 classification)
   • Anti-pattern warnings

3. Generate group README for each group directory:

   • Template description + writing guide
   • Document list with one-sentence purpose each

4. Generate all documents per derived templates:

   • Apply fixed shell + core chapters
   • Fill with analyzed project content
   • Add cross-references between related documents
   • Add track labels and reference strength annotations

5. Write layered disclosure rule into entry file: markdown

   ## ⛔ Documentation Loading Rules (Highest Priority)
   For documents exceeding 200 lines:
   Step 1: Run `scripts/md-sections.sh <file>` for JSON structure
   Step 2: Run `scripts/md-sections.sh <file> "Section Name"` to extract specific content
   PROHIBITED: Reading full document content in one operation
   
   

Phase 5: Completeness Self-Check#

1. Run structural checks (S1-S7, 🤖 automatic):

   • S1: Template compliance — all fixed sections present
   • S2: TOC accuracy — 📋 matches actual sections
   • S3: Cross-references — all links point to existing targets
   • S4: Entry index coverage — entry file references all documents
   • S5: Track labels — all documents labeled
   • S6: Reference strength — all index entries annotated
   • S7: Change history — all Contract-track docs have it

2. Run content checks (C1-C6, 🤖👤 semi-automatic):

   • C1: Code references exist — mentioned entities found in codebase
   • C2: API signatures match — documented APIs match code
   • C3: Data models match — documented models match code
   • C4: Config items match — documented configs match code
   • C5: Version numbers match — documented versions match build files
   • C6: Semantic consistency — documented behavior matches code (deep mode only)
   • Record detection methods derived for C2-C5 in project metadata (for contract-doc-sync reuse)

3. Run system health checks (H1-H5, 👤 human judgment):

   • H1: Module coverage — every code module has a document
   • H2: Concern coverage — every concern has a standards document
   • H3: Responsibility uniqueness — no two documents answer the same question
   • H4: No information islands — every document is referenced by at least one other
   • H5: Industry benchmark — field research coverage comparison

4. Output self-check report using fixed template (see completeness-checklist.md for full template).

Phase 6: User Confirmation#

1. Present full results: generated file list + self-check report
2. Iterate on user feedback: adjust grouping, templates, or content as needed

---

Constraints#

Writing Principles (for all generated documents)#

1. Single Responsibility: Every document has exactly one purpose, expressible in one sentence. If two documents answer the same question → merge or re-split.
2. Layered Disclosure: Documents exceeding 200 lines require structure-first access. Always include 📋 TOC section. Within a single session, parse the same file's structure only once — reuse the parsed tree for subsequent extractions.
3. Hierarchy Limit: Section depth must not exceed L3 (###). L3 for fine-grained subdivisions only.
4. Link Over Copy: When content from another document is needed, use Markdown links — never copy content.
5. Positive Constraints: Write rules as "do X" with specifics, not "don't do Y". Pair safety-critical negatives with positive alternatives.
6. Track Labeling: Every document carries a track label (🔴/🟢/🔵) in its header.
7. Reference Strength: Every document entry in index files carries a strength annotation (⛔/⚠️/💡).

Maintenance Classification (for generated governance sections)#

LevelMarkerTriggerExample🤖 DeterministicDirect fix1:1 mappable from codeAPI signature change → update API reference🤖👤 Semi-deterministic[pending confirmation]Requires intent understandingBusiness logic change → update description👤 CreativeSkip, reportRequires original thinkingNew module → create new document

Format Rules#

• All generated documents use Markdown format exclusively
• Use Mermaid diagrams for architecture and flow documentation
• Use numbered tables for API/configuration references
• Entry file (AGENTS.md): concise, constraint summary + document index only
• Meta-system doc (docs/README.md): self-describing, includes all governance rules

---

Examples#

Example 1: Java Spring Boot multi-module project#

→ 1. Phase 0: No existing docs → proceed directly → 2. Phase 1: Detect Maven modules (common, client-cache, client-oss, app), identify layered architecture, find concerns (auth, caching, storage, testing) → 3. Phase 2: Derive 3 groups: architecture/ (by question), conventions/ (by concern), modules/ (by module) → 4. Phase 3: architecture=Flexibility 1, conventions=Flexibility 2, modules=Flexibility 3. Intent track in openspec/specs/, Contract in docs/modules/ + docs/architecture/, Constraint in docs/conventions/ + AGENTS.md → 5. Phase 4: Generate 22 documents + AGENTS.md + docs/README.md + group READMEs → 6. Phase 5: S1-S7 all pass. C2-C5 use Java-specific detection (annotations, pom.xml). H5: compare against Spring Boot doc conventions → 7. Phase 6: User confirms

Example 2: React component library, existing messy docs/#

→ 1. Phase 0: Existing docs/ with disorganized files → present two options → user chooses "Full redesign" → 2. Phase 1: Detect npm workspaces, identify component structure, find concerns (styling, accessibility, testing, i18n) → 3. Phase 2: Derive groups: components/ (by component), guides/ (by concern), architecture/ (by question) → 4. Phase 3: components=Flexibility 3 (all need Overview/Props/Events/Examples), guides=Flexibility 2, architecture=Flexibility 4 → 5. Phase 4: Generate documents. Field research reveals Storybook conventions → incorporate Props/Events/Accessibility chapters → 6. Phase 5: S4 finds entry file missing 3 new docs → fix. H5: accessibility docs missing → flag → 7. Phase 6: User adds accessibility concern → regenerate

Example 3: Game engine (Unreal)#

→ 1. Phase 0: No existing docs → 2. Phase 1: Detect CMake/workspace modules, identify ECS + Game Loop pattern, find concerns (performance, memory, scripting, asset pipeline) → 3. Phase 2: Derive 4 groups: systems/ (AI, rendering, physics, audio), pipelines/ (asset, build, CI), guides/ (scripting, performance, debugging), architecture/ (overview, patterns, memory model) → 4. Phase 3: systems=Flexibility 4 (unified shell: Overview/Integration/Performance, but unique chapters: AI has Behavior Tree, Rendering has Shader Pipeline) → 5. Phase 4: Generate. Field research: Unreal docs commonly cover Blueprints, C++ API, Performance budgets → incorporate → 6. Phase 5: H1 finds 2 subsystems without docs → flag for user → 7. Phase 6: User confirms

---

Verification#

After completing the workflow:

1. File existence: All planned documents were created (check with ls -la docs/ recursively)
2. Structure valid: Run scripts/md-sections.sh <each-file> → verify TOC sections exist
3. Entry index complete: Entry file references all generated documents
4. Cross-references valid: No broken Markdown links between documents
5. Self-check report clean: S1-S7 all pass; C1-C6 reviewed; H1-H5 acknowledged by user
6. Track consistency: Each document's track label matches its actual time/direction behavior

If any check fails → diagnose, fix, re-verify. If user disagrees with grouping/templates → iterate from corresponding Phase.

---

Resources#

FileWhen to Readthree-track-philosophy.mdPhase 3 — Need to explain track classification or writing philosophy to usergrouping-detection.mdPhase 1-2 — Need detailed signal tables, architecture patterns, or quality criteriatemplate-derivation.mdPhase 3 — Need detailed flexibility judgment, fixed shell definition, or chapter derivation methodscompleteness-checklist.mdPhase 5-6 — Need 18-dimension checklist details, dependency order, or report template

Scripts#

ScriptPurposescripts/md-sections.shMarkdown chapter parser with three operations: (1) md-sections.sh <file> → JSON structure tree, (2) md-sections.sh <file> "Section" → extract section content, (3) md-sections.sh <file> --line <N> → locate section by line number. Deploy to project's scripts/ in Phase 0

Complementary Skills#

SkillRelationshipcontract-doc-syncMaintenance partner: This skill = architect (one-time generation), contract-doc-sync = property manager (ongoing drift detection + sync). This skill's generated detection configs can be reused by contract-doc-sync