Skip to content

Commit 6e72c8a

Browse files
tamirdresherjonibajbenamiCopilotCopilot
authored
feat: APM integration — squad skill publish/install + apm.yml in init (#876)
* Add enforcement wiring step to hiring process + workflow wiring guide (#592) Fixes #591 - Added step 7 (Wire enforcement) to Adding Team Members in squad.agent.md - Added workflow-wiring-guide.md with configuration surface area, wiring instructions, common mistakes, and verification checklist - Added appendix walkthroughs for code reviewer (gate pattern) and documenter (follow-up trigger pattern) Co-authored-by: Jonathan Ben Ami <jbenami@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(agents): add Challenger / Devil's Advocate agent template + fact-checking skill (#603) * feat(skills): add fact-checking skill\n\nAdds challenger/fact-checking review pattern.\nVerified against 200+ issues in production squads.\nCloses #598 * feat(agents): add challenger agent charter template\n\nGeneric Devil's Advocate / Challenger template.\nProvides auto-spawn integration pattern for coordinators.\nCloses #598 * feat: add APM integration for skill publishing and installation Closes #824 ## Changes ### New command: squad skill - squad skill publish [<name>] — exports skill(s) to APM format, generating/updating apm.yml - squad skill install <source> — installs a skill from APM registry - Supports owner/repo, owner/repo/skill-name, and direct URLs - Uses GitHub CLI to fetch from repos that have apm.yml or .squad/skills/ - Writes .apm-source.json metadata to track skill origin - squad skill list — lists installed skills with source provenance ### Updated: squad init - Now generates �pm.yml at project root alongside .squad/ - Follows skipExisting semantics (safe to re-run) - apm.yml includes skills, instructions, and prompts sections ### Updated: squad help - Added skill command to help text with usage examples ## APM format apm.yml is the Agent Package Manager manifest — package.json for AI agent context. See: https://github.com/microsoft/apm The manifest declares skills, instructions, and prompts in a portable format that �pm install can deploy to .github/, .claude/, .cursor/ etc. * chore: add changeset for APM integration * docs: update CHANGELOG.md with APM integration entry * fix(skill): use .copilot/skills/ as primary path per #430 The skills unification in #430 migrated skills from .squad/skills/ to .copilot/skills/. This updates the APM skill command to: - Check .copilot/skills/ first, fall back to .squad/skills/ (backward compat) - Use resolveSkillsDir() helper matching LocalSkillSource pattern - Update all user-facing messages and apm.yml template paths - Fix installSkillsFromSquadDir candidate order Addresses review feedback from @Meir017. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: align CHANGELOG.md with dev branch Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: add missing fs import in init.ts Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: joniba <joniba@users.noreply.github.com> Co-authored-by: Jonathan Ben Ami <jbenami@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: Copilot <copilot@github.com>
1 parent 9451e66 commit 6e72c8a

11 files changed

Lines changed: 1325 additions & 1 deletion

File tree

‎.changeset/apm-integration.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"squad": minor
3+
---
4+
5+
feat: APM integration — squad skill publish/install + apm.yml in init
6+
7+
Implements #824. Adds `squad skill publish/install/list` commands and generates `apm.yml` on `squad init`.

‎.squad-templates/squad.agent.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -915,7 +915,8 @@ If the user says "I need a designer" or "add someone for DevOps":
915915
4. **Update `.squad/casting/registry.json`** with the new agent entry.
916916
5. Add to team.md roster.
917917
6. Add routing entries to routing.md.
918-
7. Say: *"✅ {CastName} joined the team as {Role}."*
918+
7. **Wire enforcement (if applicable).** If the new member's role involves gating other agents' work (reviewer, design approver, quality gate), add a numbered enforcement rule to `routing.md` → Rules section. A routing table entry (step 6) only handles explicit requests — enforcement rules are required for automatic gates. Read `.squad/templates/workflow-wiring-guide.md` for the full wiring process, including walkthroughs for common role types (code reviewer, documenter). Check `.squad/templates/issue-lifecycle.md` for lifecycle integration if the project uses PR-gated workflows.
919+
8. Say: *"✅ {CastName} joined the team as {Role}."*
919920
920921
### Removing Team Members
921922

‎.squad-templates/workflow-wiring-appendix-a-code-reviewer.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Appendix A: Wiring a Code Reviewer — Complete Walkthrough
2+
3+
> End-to-end example of adding a code reviewer to your squad and wiring their gate so it actually gets enforced. This walkthrough addresses a common failure: a reviewer is on the roster but never reviews a single PR because the gate wasn't wired.
4+
5+
## The Problem This Solves
6+
7+
Adding a reviewer to `team.md` gives them an identity. It does NOT:
8+
- Tell the coordinator to route PRs to them
9+
- Prevent PRs from being merged without their approval
10+
- Prevent issues from being closed before review happens
11+
12+
**What goes wrong without enforcement:** A reviewer can be on the roster as "Reviewer" from day one. Their charter says they review PRs. The routing table says "PR code review → {ReviewerName}." But PRs get merged and issues get closed without them ever being spawned. Why?
13+
14+
Because the routing table says WHO handles what — it's for incoming requests ("review PR #42"). It does NOT say "after every agent completes work, route their output to {ReviewerName}." The coordinator routes work TO agents, but nothing tells it to route COMPLETED work to a reviewer. The "After Agent Work" flow in `squad.agent.md` says: collect results → present → spawn Scribe. No review step.
15+
16+
**The fix has three layers:**
17+
18+
| Layer | What it does | Where it lives |
19+
|-------|-------------|----------------|
20+
| Identity | Reviewer exists and knows how to review | `team.md` roster + `charter.md` |
21+
| Routing | User can explicitly request "review this" | `routing.md` routing table |
22+
| **Enforcement** | Coordinator MUST route every PR to reviewer before merge | `routing.md` Rules section + `issue-lifecycle.md` post-work steps |
23+
24+
Most squads get layers 1 and 2 right. Layer 3 — enforcement — is what's usually missing.
25+
26+
## Step-by-Step Walkthrough
27+
28+
### Step 1: Create the reviewer's identity
29+
30+
Create `.squad/agents/{name}/charter.md`:
31+
32+
```markdown
33+
# {Name} — Code Reviewer
34+
35+
## Identity
36+
- **Name:** {Name}
37+
- **Role:** Code Reviewer
38+
- **Expertise:** Code quality, correctness, test coverage, security, patterns
39+
- **Style:** Thorough, fair, specific. Provides actionable feedback.
40+
41+
## What I Own
42+
- Reviewing PRs for code quality, correctness, and test coverage
43+
- Identifying bugs, security issues, and design problems
44+
- Providing specific, actionable feedback (not vague suggestions)
45+
46+
## How I Review
47+
1. Read the PR diff completely
48+
2. Check: does it do what the issue asked for?
49+
3. Check: are there tests? Do they cover the important cases?
50+
4. Check: are there bugs, edge cases, or security issues?
51+
5. Check: does it follow project patterns and conventions?
52+
6. Verdict: APPROVE or REJECT with specific feedback
53+
54+
## Boundaries
55+
**I handle:** Code review, PR review, quality gates
56+
**I don't handle:** Implementation, design, research, documentation
57+
58+
## On REJECT
59+
I provide specific feedback: what's wrong, why, and what to do instead.
60+
The original author fixes their work. I re-review after fixes.
61+
```
62+
63+
Create `.squad/agents/{name}/history.md` seeded with project context.
64+
65+
### Step 2: Add to team.md roster
66+
67+
```markdown
68+
| 👑 {Name} | Code Reviewer | `.squad/agents/{name}/charter.md` | ✅ Active |
69+
```
70+
71+
### Step 3: Add routing table entry
72+
73+
In `routing.md` → routing table:
74+
75+
```markdown
76+
| PR code review | 👑 {Name} | — | "Review PR #42", code quality, finding reports |
77+
```
78+
79+
**⚠️ This is necessary but NOT sufficient.** This only handles explicit review requests. It does NOT enforce automatic review of every PR.
80+
81+
### Step 4: Add enforcement rule (THIS IS THE CRITICAL STEP)
82+
83+
In `routing.md` → `## Rules` section, add a numbered rule:
84+
85+
```markdown
86+
N. **{Name} PR Gate** — every PR created by any agent MUST be reviewed by {Name}
87+
before merge. The coordinator spawns {Name} (sync) with the PR diff after
88+
the author pushes and creates the PR. On REJECT, the original author addresses
89+
feedback. On APPROVE, the coordinator merges via `gh pr merge`. No PR merges
90+
without {Name}'s approval.
91+
```
92+
93+
**Why this works when the routing table alone didn't:** The routing table is for matching incoming work to agents. Rules are behavioral constraints the coordinator must follow AFTER work completes. The rule says "after a PR exists, you MUST do X before proceeding." The routing table says "if someone asks for a review, route to X."
94+
95+
### Step 5: Wire into issue-lifecycle.md
96+
97+
In `.squad/templates/issue-lifecycle.md`, the "Coordinator Post-Work Steps" section should reference your reviewer by name:
98+
99+
```markdown
100+
4. **Route to reviewer.** Spawn {Name} (sync) with the PR diff for code review.
101+
```
102+
103+
This is the operational detail — the step-by-step instructions the coordinator follows after an agent completes issue work. The routing rule (Step 4) is the mandate; the lifecycle template is the procedure.
104+
105+
### Step 6: Add to casting registry
106+
107+
Update `.squad/casting/registry.json` with the new entry.
108+
109+
### Step 7: Verify
110+
111+
Ask yourself these questions:
112+
113+
- [ ] If a clean session coordinator reads `routing.md` Rules, will it know to route PRs to this reviewer? → Check rule N exists.
114+
- [ ] If an agent completes work and pushes a PR, does the coordinator's post-work flow include a review step? → Check `issue-lifecycle.md` step 4.
115+
- [ ] Can the coordinator merge a PR without the reviewer's approval? → The rule should say "No PR merges without {Name}'s approval."
116+
- [ ] Can the coordinator close an issue without a merged PR? → Check the issue closure rule exists.
117+
118+
If any answer is wrong, you have a gap.
119+
120+
## What Each File Controls (Summary)
121+
122+
| File | What it contributes to the reviewer gate |
123+
|------|----------------------------------------|
124+
| `charter.md` | WHO the reviewer is and HOW they review |
125+
| `team.md` | That the reviewer EXISTS on the team |
126+
| `routing.md` routing table | That explicit review requests go to this reviewer |
127+
| `routing.md` Rules section | That the coordinator MUST route EVERY PR to this reviewer (enforcement) |
128+
| `issue-lifecycle.md` | The step-by-step procedure for the post-work review flow |
129+
| `casting/registry.json` | Persistent name tracking |
130+
131+
**Remove any one of these and the gate has a hole.** The most commonly missed piece is the Rules section entry (Step 4).

‎.squad-templates/workflow-wiring-appendix-b-documenter.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
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.

0 commit comments

Comments
 (0)