Docs Scaffold

Docs Scaffold

Take raw project documentation and produce a structured docs/ folder that AI agents can navigate efficiently. Splits monolithic files into focused, cross-linked documents with an INDEX.md entry point and AGENTS.md at the project root.

Companion skill to /resolve-docs — this skill creates the structure, /resolve-docs fills the gaps.

Constraints

• Never invent content — unknowns become entries in decisions/open-questions.md, not guesses
• Check reference file sizes before loading — read references/large-files.md for the protocol
• Always confirm understanding AND planned structure before creating any files (two checkpoints)
• One story per file — never combine stories even if short
• Use AGENTS.md (not CLAUDE.md) at project root for tool-universality
• Do not duplicate content — one canonical location, link from others
• Read gotchas.md before starting

Phase 0 — Read Source Material

Read every input file the user provides. Build a mental model:

• What is this project? Purpose, domain, landscape position
• What are the components/layers? Responsibilities and boundaries
• What stories/tasks exist? Grouped by feature or layer
• What external systems are involved? APIs, databases, services
• What cross-cutting concerns exist? Patterns appearing in 2+ stories (logging, retry, auth, status tracking)
• What domain terminology is used? Mixed languages, jargon

Present a structured summary and wait for confirmation before proceeding.

Phase 1 — Plan Folder Structure

Design the docs/ structure based on source content. Only include folders that have content — not every project needs every folder. Always include decisions/open-questions.md.

Present the planned tree to the user and get confirmation before creating files.

See examples/erp-adapter-session.md for a real-world example of the output structure.

Phase 2 — Split and Create Files

Read references/splitting-rules.md for detailed routing rules: which content goes where, story file structure, and cross-reference conventions.

Key principle: identify cross-cutting concerns FIRST and extract them into conventions/ BEFORE writing story files. This prevents duplication.

Phase 3 — Create INDEX.md

Use templates/INDEX.md.tmpl as the starting structure. INDEX.md must contain:

• "How to Use" navigation instructions (not just a file list)
• A section per folder with file links and one-line descriptions
• Warnings about large reference files that should not be auto-loaded

Phase 4 — Create AGENTS.md

Use templates/AGENTS.md.tmpl as the starting structure. Create at the project root (not inside docs/).

If an AGENTS.md or CLAUDE.md already exists, present the proposed additions and ask the user how to reconcile.

Phase 5 — Populate Open Questions

Use templates/open-questions.md.tmpl as the starting structure. Populate with gaps discovered during scaffolding: undefined terms, missing decisions, contradictions, vague sections, "TBD" markers.

Number questions sequentially (OQ-1, OQ-2, ...) grouped by category.

Phase 6 — Handle Large Reference Files

Read references/large-files.md for the full protocol. Key points:

• Check file size first — small files (under ~200KB) can be loaded directly; for large files, ask the user with file name and approximate size
• Distill only relevant endpoints/schemas into a readable markdown doc
• Include a mapping table connecting endpoints to stories
• Store the original in api/specs/ with clear warnings

Phase 7 — Summary and Next Steps

Present a summary of all created files, highlight the most critical open questions, and recommend:

Recommended next step: Run /resolve-docs to work through the open questions interactively.

Example: ERP Adapter Application

A real-world session where docs-scaffold was used to structure documentation for a greenfield Spring Boot middleware project.

Input

Two raw markdown files:

1. `architecture_ai_compatible.md` (~180 lines)

• System overview with mermaid diagram
• Outbound and inbound message flows
• Layer descriptions (Translation, Queue, Delivery)
• Data model: Message (parent) → MessageHandling (child) records
• Architectural constraints (async comms, RabbitMQ compatibility, legacy ERP dependency)
• Notes on priority lanes and virtual threading

2. `USERSTORIES.md` (~190 lines)

• 4 user stories: Translation Layer, Queue Layer, Delivery Layer, Mock Financial Partner
• Each with acceptance criteria and AI-assisted testing notes
• References to Financial System API (external financial application)
• Cross-cutting patterns: MessageHandling status tracking + Elasticsearch logging in every story

Additionally, a large external reference:

• Financial System OpenAPI spec (~4.3MB, 393 endpoints) — fetched from public URL, not auto-loaded

Output

14 files across 6 subdirectories + AGENTS.md at project root:

docs/
├── INDEX.md                           # TOC with "how to use" navigation instructions
├── architecture/
│   ├── overview.md                    # Mermaid diagram, layer table, constraints
│   ├── data-model.md                  # Message/MessageHandling, status lifecycle, storage
│   └── cross-cutting-concerns.md      # Polling, idempotency, retry/DLQ, backpressure, priority, virtual threading
├── domain/
│   ├── glossary.md                    # Domain term translations and definitions
│   └── message-types.md              # Tax codes + tax rates, type-driven behavior per layer
├── stories/
│   ├── translation-layer.md           # Summary, Context (links), Acceptance Criteria, Testing notes
│   ├── queue-layer.md
│   ├── delivery-layer.md
│   └── mock-financial-partner.md
├── api/
│   ├── financial-system-api.md        # Distilled: auth flow, /v1/vat, /v1/vatCategory, /v1/vatZone + schemas
│   └── specs/
│       └── financial-system-service.json  # Full 4.3MB spec (never auto-loaded)
├── conventions/
│   └── logging-status-tracking.md     # Dual-write pattern: Oracle DB + Elasticsearch append-only log
└── decisions/
    └── open-questions.md              # 19 gaps across 6 categories

AGENTS.md (project root)               # Points to docs/INDEX.md, project summary, key rules

Key Decisions Made During Scaffolding

1. Glossary created first — The legacy ERP domain uses non-English terms while the codebase uses English. Without the glossary, every generated doc would use inconsistent naming.

2. Cross-cutting concern extracted early — Every story mentioned "insert MessageHandling record + append to Elasticsearch" at every step. This was extracted into conventions/logging-status-tracking.md before writing story files, preventing duplication across 4 stories.

3. API spec distilled, not loaded — The 4.3MB OpenAPI spec was searched for specific paths (/v1/vat, /v1/vatCategory, /v1/vatZone) and only those endpoints + schemas were distilled into financial-system-api.md. A mapping table connected endpoints to stories.

4. 19 open questions identified — Gaps fell into 6 categories: Architecture (4), Data Model (3), Integration (3), Project Setup (5), Testing (2), CI/CD (2). These became the starting point for /resolve-docs sessions.

What Went Well

• The two-checkpoint confirmation (understanding + structure) caught a misunderstanding about sync direction before files were created
• Story files with context links meant each developer could read their story and find everything they needed via links
• The glossary prevented the agent from inconsistently mixing domain terms across docs

What Would Be Done Differently

• Should have extracted cross-cutting-concerns.md content MORE aggressively from stories — some patterns were partially duplicated
• The open-questions should have been prioritized (blocking vs nice-to-have) rather than flat-listed

Gotchas

Known failure points for this skill. Update this file whenever the skill produces incorrect output or hits a new edge case.

Format

Each gotcha follows this pattern:

• What goes wrong: description of the failure
• Why: root cause
• Fix: how to avoid or work around it

---

Large Reference Files

• What goes wrong: Agent auto-loads a 4.3MB OpenAPI spec, consuming most of the context window, degrading quality of all subsequent output.
• Why: The agent sees a JSON file referenced in the docs and reads it eagerly without checking size.
• Fix: Always ask the user before loading any file in api/specs/. Add explicit "do not auto-load" warnings in INDEX.md, the distilled API doc, and AGENTS.md. Search for specific paths/schemas instead of reading the full file.

• What goes wrong: Distilled API doc lacks a mapping table connecting endpoints to stories, so developers don't know which endpoints matter for their story.
• Why: The distillation focused on extracting schemas and endpoint details but forgot to bridge back to the stories.
• Fix: Always include a "Mapping to Stories" table at the bottom of distilled API docs showing: Story | Primary Endpoint | Operation.

Cross-Cutting Concerns

• What goes wrong: Logging/status tracking pattern is described separately in each story file, creating duplication and inconsistency.
• Why: Cross-cutting concerns feel like "part of each story" during splitting, so they get copied into every story instead of extracted into conventions/.
• Fix: Before writing story files, identify patterns that appear in 2+ stories. Extract these into conventions/ first, then link from each story.

Story Splitting

• What goes wrong: Two short stories get combined into one file "for convenience", causing confusion when different developers own different stories.
• Why: The stories seemed related or small enough to merge.
• Fix: One story per file, always. Even a 10-line story gets its own file. Stories are the unit of work assignment.

Domain Glossary

• What goes wrong: Agent uses inconsistent naming throughout the generated docs — mixing Dutch and English terms, or using different English translations for the same Dutch term.
• Why: Without a glossary created first, the agent has no canonical mapping to follow.
• Fix: If the source material contains non-English terms or domain jargon, create domain/glossary.md BEFORE writing other files. Reference it during all subsequent file creation.

INDEX.md Quality

• What goes wrong: INDEX.md is a flat file list with no navigation guidance. AI agents don't know which file to read first for their task.
• Why: The skill generated a table of contents but skipped the "How to Use" instructions.
• Fix: INDEX.md must start with a "How to Use This Index" section with scenario-based instructions: "Starting a story? Read X. Need API details? Read Y first."

Confirmation Checkpoints

• What goes wrong: Agent creates 14 files based on a misunderstanding of the project, then the user has to ask for all of them to be redone.
• Why: The skill skipped the confirmation step and went straight to file creation.
• Fix: Always present understanding (Phase 0) AND planned structure (Phase 1) for explicit user confirmation before creating any files. Two checkpoints, not one.

Content Invention

• What goes wrong: Agent fills in plausible-looking technical details that were not in the source material (e.g., inventing database schema fields, guessing API response formats).
• Why: The agent tries to be helpful by filling gaps rather than flagging them.
• Fix: Anything not explicitly in the source material goes into open-questions.md as a gap, never into the docs as assumed fact. The strict rule: if you can't point to the source line, it's an open question.

AGENTS.md vs CLAUDE.md

• What goes wrong: Skill creates CLAUDE.md, which only works with Claude Code. Other AI tools (Codex, etc.) don't read it.
• Why: CLAUDE.md is a Claude Code-specific convention.
• Fix: Use AGENTS.md for the project root file. This is tool-universal. If a CLAUDE.md already exists, ask the user how to reconcile rather than overwriting.

Handling Reference Files

How to handle OpenAPI specs, database schemas, and other reference files. Read this during Phase 6 or whenever the user provides a reference file.

Size Check (do this first)

Not all reference files are large. Check the actual file size before deciding how to handle it.

• Small (under ~200KB): Load directly into context. Read and extract what you need — no special handling required.
• Large (200KB+): Follow the protocol below.

Common reference file types (size varies — always check):

• OpenAPI / Swagger specs (can range from 10KB to 5MB+)
• Database schema dumps / DDL files
• WSDL files
• Large configuration files
• Data dictionaries

Protocol (for large files only)

1. Do not auto-load. Ask the user: "I see [file name] (~[size]). Should I load it to distill the relevant parts?" 2. If approved, search for specific paths/schemas — do not read the entire file 3. Distill only endpoints/schemas relevant to the current stories into a readable markdown file 4. Store the original file in api/specs/ (or equivalent subfolder)

Distilled Doc Structure

The distilled doc should contain:

1. Warning banner at the top:

   > This doc covers only the endpoints relevant to current stories.
   > The full spec is at `specs/[filename]` (~[size]).
   > **Do not auto-load.** Ask the user before reading.
   > If this doc doesn't answer your question, ask whether to distill more.

2. Base URL and auth flow — server URL, auth mechanism, token endpoints 3. Relevant endpoints only — path, method, description, request/response schemas 4. Mapping table bridging API endpoints to stories:

   | Story | Primary Endpoint | Operation |
   |-------|-----------------|-----------|
   | [Story name] | `GET /v1/resource` | Read resources for transformation |

INDEX.md Warning

INDEX.md must include a size note about the specs folder:

## API
- [API Reference](api/api-name.md) — Distilled endpoints (read this first)
- [Full Spec](api/specs/) — Raw JSON/YAML (~X MB). **Check size before loading.** If large, ask the user before reading.

Splitting Rules

How to distribute source material into the docs/ folder structure. Read this during Phase 2 when splitting monolithic docs into focused files.

Content Routing

Story File Structure

Each story file in stories/ should follow this structure:

# Story: [Name]

## Summary
[User story statement from source material]

## Context
- [Link to relevant architecture doc]
- [Link to relevant convention]
- [Link to API reference if applicable]
- [Link to glossary if domain terms are used]

## Acceptance Criteria
[Preserved from source — numbered list]

## Testing Notes
[If present in source material]

Cross-Reference Rules

After creating all files, add relative links between related documents:

• Stories link to architecture docs, conventions, domain terms, and API references they depend on
• Architecture docs link to the stories that implement them
• Conventions note which stories/layers they apply to
• The glossary is referenced from any file that uses domain-specific terms
• Use relative paths: [glossary](../domain/glossary.md)

Identifying Cross-Cutting Concerns

Before writing story files, scan all stories for patterns that appear in 2+ stories. Common cross-cutting concerns:

• Logging / audit trail patterns
• Status tracking / state machine
• Error handling / retry logic
• Authentication / authorization
• Idempotency mechanisms
• Configuration loading

Extract these into conventions/ FIRST, then link from each story. This prevents duplication and ensures consistency.