Setting the file. One moment.
Subchapter 54.48
workflow-wiring-appendix-b-documenter.mdMarkdown6 KBView on GitHub
End-to-end example of adding a documenter role that ensures significant changes are documented. This is a FOLLOW-UP TRIGGER pattern — not a gate (which blocks), but an automatic downstream task that fires after work completes.
Your project has agents building features, fixing bugs, and writing tools. But nobody documents what was built, how to use it, or what changed. Documentation happens only when someone explicitly asks — and by then, the context is lost.
A documenter/librarian role solves this by automatically evaluating whether completed work needs documentation and producing it if so.
| Pattern | Blocks work? | When it runs | Example |
|---|---|---|---|
| Gate (Appendix A) | Yes — work cannot proceed without approval | Before merge | Code reviewer must approve PR |
| Follow-up trigger | No — work proceeds, documentation happens in parallel | After merge | Documenter evaluates if docs are needed |
A documenter is typically a follow-up trigger, not a gate. You don’t want documentation review to block a hotfix from merging. But you DO want documentation to happen automatically after significant changes.
Create .squad/agents/{name}/charter.md:
# {Name} — Documenter
## Identity
- **Name:** {Name}
- **Role:** Documenter / Librarian
- **Expertise:** Documentation, guides, READMEs, changelogs, knowledge management
- **Style:** Clear, thorough, user-focused. Makes complex things understandable.
## What I Own
- Evaluating whether completed work needs documentation
- Writing/updating READMEs, guides, and runbooks
- Maintaining a docs index so nothing gets lost
- Summarizing design decisions and architectural changes
## How I Work
1. Read the PR diff or agent output
2. Assess: does this change user-facing behavior? Add a new feature? Change configuration?
3. If yes: write or update the relevant documentation
4. If no: report "no docs needed" with brief justification
## Boundaries
**I handle:** Documentation, guides, READMEs, summaries, knowledge management
**I don't handle:** Code implementation, code review, research, operationsCreate .squad/agents/{name}/history.md seeded with project context.
| 📝 {Name} | Documenter | `.squad/agents/{name}/charter.md` | ✅ Active |In routing.md → routing table:
| Documentation, reports, summaries | 📝 {Name} | `docs/` | "Write docs for X", "Summarize this", guides, READMEs |In routing.md → ## Rules section, add a numbered rule:
N. **Documentation follow-up** — after any PR is merged that adds or modifies
user-facing features, scripts, tools, or configuration, the coordinator
spawns {Name} (background) to evaluate whether documentation is needed.
{Name} reads the merged PR diff and either writes/updates docs or reports
"no docs needed." This is a follow-up, not a gate — it does not block
the merge.Why a rule and not a ceremony: Ceremonies are structured multi-participant meetings. This is a single-agent follow-up task. A routing rule is simpler and more appropriate.
Why background, not sync: Documentation doesn’t block other work. The documenter runs in parallel with whatever comes next.
This is the trickiest part. The coordinator’s After Agent Work flow doesn’t currently have a “post-merge” hook. You wire this through the issue-lifecycle template.
In .squad/templates/issue-lifecycle.md, after the merge step, add:
8. **Documentation follow-up.** After merge, check routing.md Rules for
documentation follow-up rule. If present, spawn the documenter (background)
with the merged PR diff to evaluate whether docs are needed.Alternatively, you can wire this as an after ceremony in ceremonies.md:
- name: "Documentation Check"
when: "after"
condition: "PR merged that adds features, scripts, tools, or config changes"
facilitator: "{DocumenterName}"
participants: ["{DocumenterName}"]
output: "Docs written/updated, or 'no docs needed' with justification"If the documenter produces files, they need a worktree — docs are files too. The coordinator should:
squad/{issue}-docs)This means doc changes also get reviewed. The documenter is not exempt from the review gate.
Update .squad/casting/registry.json with the new entry.
| File | What it contributes |
|---|---|
charter.md | WHO the documenter is and HOW they evaluate |
team.md | That the documenter EXISTS |
routing.md routing table | That explicit doc requests go to this member |
routing.md Rules section | That the coordinator MUST spawn docs evaluation after merges (enforcement) |
issue-lifecycle.md or ceremonies.md | The procedural hook: when exactly the follow-up fires |
casting/registry.json | Persistent name tracking |
The most commonly missed piece: The Rules section entry (Step 4). Without it, the documenter only runs when someone explicitly says “write docs for X.” The whole point is that it runs automatically.