@cryptotaxi247 / SquadScope-1
Code Commits Issues Pulls Sessions CI/CD
main
main
md 140 lines 6.06 KB
Rendered Raw
1 # Appendix B: Wiring a Documenter/Librarian — Complete Walkthrough
2
3 > 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.
4
5 ## The Problem This Solves
6
7 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.
8
9 A documenter/librarian role solves this by automatically evaluating whether completed work needs documentation and producing it if so.
10
11 ## Gate vs Follow-Up Trigger
12
13 | Pattern | Blocks work? | When it runs | Example |
14 |---------|-------------|-------------|---------|
15 | **Gate** (Appendix A) | Yes — work cannot proceed without approval | Before merge | Code reviewer must approve PR |
16 | **Follow-up trigger** | No — work proceeds, documentation happens in parallel | After merge | Documenter evaluates if docs are needed |
17
18 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.
19
20 ## Step-by-Step Walkthrough
21
22 ### Step 1: Create the documenter's identity
23
24 Create `.squad/agents/{name}/charter.md`:
25
26 ```markdown
27 # {Name} — Documenter
28
29 ## Identity
30 - **Name:** {Name}
31 - **Role:** Documenter / Librarian
32 - **Expertise:** Documentation, guides, READMEs, changelogs, knowledge management
33 - **Style:** Clear, thorough, user-focused. Makes complex things understandable.
34
35 ## What I Own
36 - Evaluating whether completed work needs documentation
37 - Writing/updating READMEs, guides, and runbooks
38 - Maintaining a docs index so nothing gets lost
39 - Summarizing design decisions and architectural changes
40
41 ## How I Work
42 1. Read the PR diff or agent output
43 2. Assess: does this change user-facing behavior? Add a new feature? Change configuration?
44 3. If yes: write or update the relevant documentation
45 4. If no: report "no docs needed" with brief justification
46
47 ## Boundaries
48 **I handle:** Documentation, guides, READMEs, summaries, knowledge management
49 **I don't handle:** Code implementation, code review, research, operations
50 ```
51
52 Create `.squad/agents/{name}/history.md` seeded with project context.
53
54 ### Step 2: Add to team.md roster
55
56 ```markdown
57 | 📝 {Name} | Documenter | `.squad/agents/{name}/charter.md` | ✅ Active |
58 ```
59
60 ### Step 3: Add routing table entry
61
62 In `routing.md` → routing table:
63
64 ```markdown
65 | Documentation, reports, summaries | 📝 {Name} | `docs/` | "Write docs for X", "Summarize this", guides, READMEs |
66 ```
67
68 ### Step 4: Add follow-up trigger rule
69
70 In `routing.md` → `## Rules` section, add a numbered rule:
71
72 ```markdown
73 N. **Documentation follow-up** — after any PR is merged that adds or modifies
74 user-facing features, scripts, tools, or configuration, the coordinator
75 spawns {Name} (background) to evaluate whether documentation is needed.
76 {Name} reads the merged PR diff and either writes/updates docs or reports
77 "no docs needed." This is a follow-up, not a gate — it does not block
78 the merge.
79 ```
80
81 **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.
82
83 **Why background, not sync:** Documentation doesn't block other work. The documenter runs in parallel with whatever comes next.
84
85 ### Step 5: Wire into the coordinator's post-merge flow
86
87 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.
88
89 In `.squad/templates/issue-lifecycle.md`, after the merge step, add:
90
91 ```markdown
92 8. **Documentation follow-up.** After merge, check routing.md Rules for
93 documentation follow-up rule. If present, spawn the documenter (background)
94 with the merged PR diff to evaluate whether docs are needed.
95 ```
96
97 Alternatively, you can wire this as an `after` ceremony in `ceremonies.md`:
98
99 ```yaml
100 - name: "Documentation Check"
101 when: "after"
102 condition: "PR merged that adds features, scripts, tools, or config changes"
103 facilitator: "{DocumenterName}"
104 participants: ["{DocumenterName}"]
105 output: "Docs written/updated, or 'no docs needed' with justification"
106 ```
107
108 ### Step 6: Worktree for doc changes
109
110 If the documenter produces files, they need a worktree — docs are files too. The coordinator should:
111 1. Create a worktree for the doc update (e.g., `squad/{issue}-docs`)
112 2. The documenter commits and pushes
113 3. A PR is created for the docs
114 4. The docs PR goes through the normal review flow (including the code reviewer if you have one)
115
116 This means doc changes also get reviewed. The documenter is not exempt from the review gate.
117
118 ### Step 7: Add to casting registry
119
120 Update `.squad/casting/registry.json` with the new entry.
121
122 ### Step 8: Verify
123
124 - [ ] After a feature PR merges, does the coordinator spawn the documenter? → Check the routing rule exists.
125 - [ ] Does the documenter get a worktree for their work? → Check the worktree rule covers docs.
126 - [ ] Do doc changes go through the review gate? → They should — docs are files, files need PRs, PRs need review.
127 - [ ] Is the follow-up non-blocking? → The documenter should be background, not sync.
128
129 ## What Each File Controls (Summary)
130
131 | File | What it contributes |
132 |------|-------------------|
133 | `charter.md` | WHO the documenter is and HOW they evaluate |
134 | `team.md` | That the documenter EXISTS |
135 | `routing.md` routing table | That explicit doc requests go to this member |
136 | `routing.md` Rules section | That the coordinator MUST spawn docs evaluation after merges (enforcement) |
137 | `issue-lifecycle.md` or `ceremonies.md` | The procedural hook: when exactly the follow-up fires |
138 | `casting/registry.json` | Persistent name tracking |
139
140 **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.