Documentation bootstrap
This is an occasional bulk task. For changes after this, use engineering:documentation-sync.
1. Take an inventory
List the documents that exist and mark each one present, thin (exists but is mostly empty or out of date) or missing. Check at least:
README.md, CONTRIBUTING.md, CHANGELOG.md, ARCHITECTURE.md or docs/architecture/, decision records, CLAUDE.md, SECURITY.md, LICENSE, the API reference, the configuration reference, runbooks.
git ls-files '*.md' | grep -v node_modules
2. Let the user choose
Show the menu from resources/doc-catalog.md. Mark each type as present, thin or missing. Mark the types that you recommend for this kind of project.
- Present documents are not rewritten. The user can choose "revise" for a thin one.
- The user picks. Do not write a type that the user did not pick.
3. Build the fact sheet
Before anyone writes, collect the facts that more than one document will use. Take them from the code and git, not from memory. Write them to a scratch file.
| Fact | Source |
|---|---|
| Project name and one-sentence purpose | README, manifest, the user |
| Current version | manifest, latest tag (git describe --tags --abbrev=0) |
| Languages, frameworks and their versions | manifests and lock files |
| Install, test, lint, build and run commands | engineering:development-commands |
| Components and their names | directory layout, entry points, compose files |
| Environment variables and settings | .env.example, and the code that reads settings (search for process.env, os.environ, getenv) |
| Important dates | the first commit (git log --reverse), the tags |
| What works today, what does not | the user, open issues |
If two sources disagree, ask the user. Do not choose one silently. Every writer uses only the fact sheet and the code.
4. Write
- Three documents or fewer: write them yourself, one after the other.
- More than three: start one sub-agent for each document or small group, at most four at a time. Give each sub-agent:
- the exact file or files that it owns, and the rule that it may not change any other file;
- the fact sheet;
- the section outline for its type from
resources/doc-catalog.md; - the instruction to write in Simplified Technical English (the
simple-englishskill, if installed); - the instruction to report facts that it needed and did not find, instead of inventing them.
Do not invent history, numbers, users or features. Write "TBD" and list it for the user.
5. Check the set
Follow resources/consistency-check.md. Fix every problem before you continue.
6. Commit
Put the documents on a branch (engineering:git-branching) and open a PR (engineering:github-pr-merge). In the PR body, list each new document and each "TBD" that needs an answer from the user.
Related skills
engineering:documentation-sync: keeps these documents correct after this.gener8v:brownfield: onboards an existing codebase into the gener8v pipeline. It writes.gener8v/context, not these project documents.