Scaffold the documentation tree
Create the canonical documentation tree and its seed READMEs, so that every later document has a
legal home before anyone has to invent one. Reference: references/structure.md — the tree, the
filename grammar, and the freeze list; read it when the canonical tree is in question. The
docs root defaults to docs/; read it from
.ai-badger/config.json's docs.root if the project sets one.
What a finished scaffold IS — four parts, in this order:
- The canonical tree, every directory present, none extra.
- A root
README.md — a complete map: one row per directory, no omissions.
- One
README.md per directory, each a complete map of that directory.
- One ledger entry per seeded file, if the project keeps a ledger, so the next person's check is
green from the first commit.
Seeded READMEs are meant to be edited. They carry no generated-file header and no golden test.
Steps
- Inventory the current tree against the canonical one. Postcondition: you have a written
list of missing and extra paths. If the list is empty on both sides, the tree is already
canonical — say so and stop; you are not the right skill.
- Create every missing directory. Postcondition: each one exists and is a directory. A
path that collided with an existing file is resolved one path at a time — never by deleting or
re-running blind.
- Structure gate. Re-run the inventory from step 1 and do not proceed until it comes back
empty — no content is written before it does. Content written into a wrong tree has to be
moved, and moving it costs the file's history on every file.
- Write the root README and each directory README as complete, visual-first maps.
- Root README: Keep it concise and low-noise: high-level architecture/flow Mermaid diagram, quick start snippet, capabilities matrix, and clear links to dedicated Diátaxis pages.
- Directory READMEs: One row per file, describing purpose directly without fluffy prose.
- Humanization: Apply
humanizer rules — active verbs, no em-dash filler, no empty copulas (serves as).
Postcondition: every file in each governed directory appears in its parent README, and every relative link in what you wrote resolves to a path that exists. Check both by hand; a missing entry is a document nobody will find.
- Record the seeded files in the project's documentation ledger, if it has one.
Postcondition: every seeded file has an entry, and the ledger's own consistency check is
green. An unrecorded seed makes the very next person's check fail.
Scripts versus judgement
A step whose output is checkable is a script call, where the project has a script. A step needing
judgement is prose followed by a check of its postcondition.
Never script: what a directory is for. A generated purpose line reads like a decision and is
not one, and nobody re-opens it.
Do not put a script inside this skill directory. Documentation tooling, if a project has any,
belongs in the project's scripts directory and is bound through .ai-badger/config.json's docs
map — see extensions/ledger/.
Where reference material lives
A skills directory registers exactly one nesting level, and a directory without a SKILL.md is
silently ignored rather than erroring. Verified across the agents ai-badger supports. So
when placing a skill's reference material, put it in a references/ subdirectory inside
that skill, which ships
with it — never in a sibling directory beside it, which would never be indexed and would never be
delivered. The same rule applies to the documentation tree you are creating: nothing is picked up
because it is nearby.
Gotchas
No environment-specific gotchas known.
Red flags — STOP
- Writing any document before the structure inventory comes back empty
- Adding a directory the canonical tree does not have, "because this repo needs it"
- A directory README that lists the interesting files instead of all of them
- Putting a script inside this skill directory
- Creating or touching content under a frozen build-input directory — read the freeze list in
references/structure.md when a build-input path is in question
- Reporting the scaffold done with seeded files the ledger does not know about
1---2name: scaffold-documentation3description: Use when a repository has no documentation tree yet, or the canonical docs layout is missing, incomplete or was hand-created — "set up docs", "scaffold documentation", "create the docs structure", a fresh repo with only a README, a docs directory missing its directory READMEs, or a structure check that reports absent directories. Not for adding or editing a document (use update-documentation), and not for reorganising docs that already exist (use migrate-documentation).4license: MIT5---67# Scaffold the documentation tree89Create the canonical documentation tree and its seed READMEs, so that every later document has a10legal home before anyone has to invent one. Reference: `references/structure.md` — the tree, the11filename grammar, and the freeze list; read it **when the canonical tree is in question**. The12docs root defaults to `docs/`; read it from13`.ai-badger/config.json`'s `docs.root` if the project sets one.1415**What a finished scaffold IS** — four parts, in this order:16171. The canonical tree, every directory present, none extra.182. A root `README.md` — a **complete** map: one row per directory, no omissions.193. One `README.md` per directory, each a complete map of that directory.204. One ledger entry per seeded file, if the project keeps a ledger, so the next person's check is21 green from the first commit.2223Seeded READMEs are meant to be edited. They carry no generated-file header and no golden test.2425## Steps26271. **Inventory the current tree against the canonical one.** **Postcondition:** you have a written28 list of missing and extra paths. If the list is empty on both sides, the tree is already29 canonical — say so and stop; you are not the right skill.302. **Create every missing directory.** **Postcondition:** each one exists and is a directory. A31 path that collided with an existing *file* is resolved one path at a time — never by deleting or32 re-running blind.333. **Structure gate. Re-run the inventory from step 1 and do not proceed until it comes back34 empty** — no content is written before it does. Content written into a wrong tree has to be35 moved, and moving it costs the file's history on every file.364. **Write the root README and each directory README as complete, visual-first maps.**37 - **Root README:** Keep it concise and low-noise: high-level architecture/flow Mermaid diagram, quick start snippet, capabilities matrix, and clear links to dedicated Diátaxis pages.38 - **Directory READMEs:** One row per file, describing purpose directly without fluffy prose.39 - **Humanization:** Apply `humanizer` rules — active verbs, no em-dash filler, no empty copulas (`serves as`).40 **Postcondition:** every **file** in each governed directory appears in its parent README, and every relative link in what you wrote resolves to a path that exists. Check both by hand; a missing entry is a document nobody will find.415. **Record the seeded files** in the project's documentation ledger, if it has one.42 **Postcondition:** every seeded file has an entry, and the ledger's own consistency check is43 green. An unrecorded seed makes the very next person's check fail.4445## Scripts versus judgement4647A step whose output is checkable is a script call, where the project has a script. A step needing48judgement is prose followed by a check of its postcondition.4950**Never script:** what a directory is for. A generated purpose line reads like a decision and is51not one, and nobody re-opens it.5253Do not put a script inside this skill directory. Documentation tooling, if a project has any,54belongs in the project's scripts directory and is bound through `.ai-badger/config.json`'s `docs`55map — see `extensions/ledger/`.5657## Where reference material lives5859**A skills directory registers exactly one nesting level, and a directory without a `SKILL.md` is60silently ignored rather than erroring.** Verified across the agents ai-badger supports. So61**when placing a skill's reference material**, put it in a `references/` subdirectory *inside*62that skill, which ships63with it — never in a sibling directory beside it, which would never be indexed and would never be64delivered. The same rule applies to the documentation tree you are creating: nothing is picked up65because it is nearby.6667## Gotchas6869No environment-specific gotchas known.7071## Red flags — STOP7273- Writing any document before the structure inventory comes back empty74- Adding a directory the canonical tree does not have, "because this repo needs it"75- A directory README that lists the interesting files instead of all of them76- Putting a script inside this skill directory77- Creating or touching content under a frozen build-input directory — read the freeze list in78 `references/structure.md` when a build-input path is in question79- Reporting the scaffold done with seeded files the ledger does not know about
Arasz