| name | do-it-handbook |
| description | Use when a project needs a lean `.do-it/handbook/` for stable project truth plus `.do-it/worklog/` for daily or goal notes. |
Do-It Handbook
Purpose
Use this to scaffold a small project handbook for truth that should survive many
sessions: invariants, stable architecture shape, and glossary terms. Everything
that changes daily or per-goal goes to .do-it/worklog/ instead of the
handbook.
The point is low context load. Code locations are rediscovered with rg or a
temporary code-mapper dispatch; they are not maintained in a persistent
code-map.md.
When To Use
- The user explicitly asks to bootstrap a handbook (
/do-it-handbook init, "建 handbook", "set up the handbook").
- The project is starting to grow beyond a single CLAUDE.md and the team is rediscovering the same terms each turn.
- A new contributor (human or agent) keeps asking what counts as a
Blocking finding, or where the architecture invariants live.
- Stable project truth is repeatedly rediscovered and a small shared home would prevent future drift.
Skip when:
- A
docs/handbook/ (or equivalent) already exists. Do not duplicate.
- The project is a one-shot script with no team beyond a single user.
File Layout
.do-it/handbook/
README.md # navigation hub
invariants.md # rules that always win
architecture.md # stable system shape
glossary.md # vocabulary (long-stable terms)
worklog-template.md # template copied into .do-it/worklog/
.do-it/worklog/
.gitkeep
The handbook holds only project-specific truth — the facts a generic skill
cannot carry. Process docs (task-card layout, review protocol, subagent
dispatch, execution pipeline, maintenance rules), code maps, runtime status, and
backlog queues are NOT scaffolded here. Per-task or per-day detail belongs in
.do-it/worklog/YYYY-MM-DD.md, .do-it/worklog/<goal>.md, plans, or review
artifacts.
Bootstrap Behavior
When explicitly invoked (/do-it-handbook or a user request):
- Check whether
.do-it/handbook/ exists.
- If it does and every file from the template list is present, report
handbook is current and stop.
- If it does and some files are missing, copy only the missing files (additive, never overwrite).
- If it does not exist, create the full tree.
- Templates are copied verbatim from
templates/ under this skill. Each template is a skeleton with placeholder text the project owner replaces; do not hand-edit the project's handbook from inside the bootstrap step.
- Add a
.gitkeep to .do-it/brainstorm/, .do-it/grill/, .do-it/plans/,
and .do-it/worklog/ if any of those directories are missing, so the project
tracks them in version control.
- Print one line per file written, then a one-paragraph "next steps" pointer telling the user to start by filling in
invariants.md and glossary.md.
The bootstrap must actually write files, not merely suggest that the user create them. The placeholders are intentional — they prompt the human owner to make the call in a later turn.
Do not:
- run
git add or git commit automatically;
- overwrite an existing handbook file (additive only);
- attempt to discover the project's architecture and back-fill the templates with project-specific content. That is a separate, larger pass; the bootstrap leaves placeholders.
Relationship To Other Skills
| Owns | Reads from handbook |
|---|
do-it-context | .do-it/CONTEXT.md (active sediment) | glossary.md (long-stable terms) |
do-it-code-quality | inline review output | architecture.md, invariants.md |
do-it-decide | .do-it/grill/<task>.md | invariants.md, glossary.md |
do-it-review | review protocol / findings (inline or parent agent consumption) | invariants.md |
do-it-decide owns the task-card layout itself, do-it-review owns the
review protocol, and do-it-router owns the dispatch contract —
none of them read a handbook copy. The handbook only feeds them project-specific
truth (invariants.md, glossary.md, architecture.md).
The handbook is read-mostly. Routine progress, experiments, lessons, and
day-level status go to worklogs; promote only stable facts back into the
handbook.
Term Ownership (.do-it/CONTEXT.md ↔ glossary.md)
Keep one home per term:
.do-it/CONTEXT.md holds terse, active terms and invariants that agents need during current work.glossary.md holds terminology the project intends to preserve across long-lived docs and architecture.- Promote a term when it has become stable project vocabulary, not after an arbitrary session count.
- After promotion, replace the context entry with a pointer or remove it; if the definition changes, update the glossary and current context together.
Maintenance
When and how to update each handbook or worklog file. The per-session sediment
(.do-it/CONTEXT.md) and per-task artifacts (.do-it/grill/, .do-it/plans/)
live outside the handbook.
Update triggers:
- Implementation moved → do not update a persistent code map. Use
rg or a
temporary code-mapper dispatch in the next task, then record only durable
lessons in the worklog or handbook.
- Cross-cutting issue opened/closed → record the current state in the
relevant plan/review artifact or worklog. Promote to handbook only if it
becomes an invariant.
- Contract changed → schema snippets in
architecture.md, enum values in
glossary.md, and the affected plan cards; then search the codebase for
callers.
- Invariant changed → open a task card citing the invariant number; after
landing, sweep for contradictions and file backlog issues for any you cannot
fix in the same change.
- Term stabilized → promote
.do-it/CONTEXT.md → glossary.md when it is durable project vocabulary; leave one canonical home.
- Route settled for good → when a grill/decide conclusion permanently fixes a route ("we chose X over Y because Z"), promote it to one paragraph in
decisions.md. One file, one paragraph per decision; promotion-triggered, never per-task ceremony.
Keep any single handbook file under ~15 KB. Worklogs may be archived by day or
goal; do not require routine agents to read old worklogs unless the active
task points at one.
Output
The bootstrap command should produce a short, deterministic report:
[do-it-handbook] writing 4 file(s) to .do-it/handbook/ and 1 template to .do-it/worklog/
+ .do-it/handbook/README.md
+ .do-it/handbook/invariants.md
+ .do-it/handbook/architecture.md
+ .do-it/handbook/glossary.md
+ .do-it/handbook/worklog-template.md
+ .do-it/worklog/.gitkeep
next: fill in invariants.md and glossary.md, then use .do-it/worklog/YYYY-MM-DD.md for daily progress.
Idempotent re-runs print only the files actually written; an empty list means the handbook is current.
Common Mistakes
- Treating the bootstrap as a one-time action and never refreshing the templates against do-it upstream. When
do-it ships a new template (e.g. a new truth file), the bootstrap should be re-runnable to add it.
- Copying the templates and then immediately auto-filling them from the codebase. The placeholders are intentional — they prompt the human owner to make the call.
- Recreating a persistent code map. Code locations are cheap to rediscover and
expensive to keep current.
- Promoting every term from
.do-it/CONTEXT.md to glossary.md as soon as it appears. Promote only vocabulary that should remain stable across project documentation.
Related Skills
do-it-context — owns active sediment; promotes terms to glossary.md.do-it-code-quality — reads architecture.md and invariants.md.do-it-decide — reads invariants.md and glossary.md for term anchoring.do-it-decide / do-it-review / do-it-router — own their task-card layout / review protocol / dispatch contract directly; the handbook no longer carries a copy.
