feat: APM integration — squad skill publish/install + apm.yml in init

.changeset/apm-integration.md

@@ -0,0 +1,7 @@
+---
+"squad": minor
+---
+
+feat: APM integration — squad skill publish/install + apm.yml in init
+
+Implements #824. Adds `squad skill publish/install/list` commands and generates `apm.yml` on `squad init`.

.squad-templates/squad.agent.md

@@ -915,7 +915,8 @@ If the user says "I need a designer" or "add someone for DevOps":
 4. **Update `.squad/casting/registry.json`** with the new agent entry.
 5. Add to team.md roster.
 6. Add routing entries to routing.md.
-7. Say: *"✅ {CastName} joined the team as {Role}."*
+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.
+8. Say: *"✅ {CastName} joined the team as {Role}."*
 
 ### Removing Team Members
 

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

@@ -0,0 +1,131 @@
+# Appendix A: Wiring a Code Reviewer — Complete Walkthrough
+
+> 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.
+
+## The Problem This Solves
+
+Adding a reviewer to `team.md` gives them an identity. It does NOT:
+- Tell the coordinator to route PRs to them
+- Prevent PRs from being merged without their approval
+- Prevent issues from being closed before review happens
+
+**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?
+
+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.
+
+**The fix has three layers:**
+
+| Layer | What it does | Where it lives |
+|-------|-------------|----------------|
+| Identity | Reviewer exists and knows how to review | `team.md` roster + `charter.md` |
+| Routing | User can explicitly request "review this" | `routing.md` routing table |
+| **Enforcement** | Coordinator MUST route every PR to reviewer before merge | `routing.md` Rules section + `issue-lifecycle.md` post-work steps |
+
+Most squads get layers 1 and 2 right. Layer 3 — enforcement — is what's usually missing.
+
+## Step-by-Step Walkthrough
+
+### Step 1: Create the reviewer's identity
+
+Create `.squad/agents/{name}/charter.md`:
+
+```markdown
+# {Name} — Code Reviewer
+
+## Identity
+- **Name:** {Name}
+- **Role:** Code Reviewer
+- **Expertise:** Code quality, correctness, test coverage, security, patterns
+- **Style:** Thorough, fair, specific. Provides actionable feedback.
+
+## What I Own
+- Reviewing PRs for code quality, correctness, and test coverage
+- Identifying bugs, security issues, and design problems
+- Providing specific, actionable feedback (not vague suggestions)
+
+## How I Review
+1. Read the PR diff completely
+2. Check: does it do what the issue asked for?
+3. Check: are there tests? Do they cover the important cases?
+4. Check: are there bugs, edge cases, or security issues?
+5. Check: does it follow project patterns and conventions?
+6. Verdict: APPROVE or REJECT with specific feedback
+
+## Boundaries
+**I handle:** Code review, PR review, quality gates
+**I don't handle:** Implementation, design, research, documentation
+
+## On REJECT
+I provide specific feedback: what's wrong, why, and what to do instead.
+The original author fixes their work. I re-review after fixes.
+```
+
+Create `.squad/agents/{name}/history.md` seeded with project context.
+
+### Step 2: Add to team.md roster
+
+```markdown
+| 👑 {Name} | Code Reviewer | `.squad/agents/{name}/charter.md` | ✅ Active |
+```
+
+### Step 3: Add routing table entry
+
+In `routing.md` → routing table:
+
+```markdown
+| PR code review | 👑 {Name} | — | "Review PR #42", code quality, finding reports |
+```
+
+**⚠️ This is necessary but NOT sufficient.** This only handles explicit review requests. It does NOT enforce automatic review of every PR.
+
+### Step 4: Add enforcement rule (THIS IS THE CRITICAL STEP)
+
+In `routing.md` → `## Rules` section, add a numbered rule:
+
+```markdown
+N. **{Name} PR Gate** — every PR created by any agent MUST be reviewed by {Name}
+   before merge. The coordinator spawns {Name} (sync) with the PR diff after
+   the author pushes and creates the PR. On REJECT, the original author addresses
+   feedback. On APPROVE, the coordinator merges via `gh pr merge`. No PR merges
+   without {Name}'s approval.
+```
+
+**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."
+
+### Step 5: Wire into issue-lifecycle.md
+
+In `.squad/templates/issue-lifecycle.md`, the "Coordinator Post-Work Steps" section should reference your reviewer by name:
+
+```markdown
+4. **Route to reviewer.** Spawn {Name} (sync) with the PR diff for code review.
+```
+
+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.
+
+### Step 6: Add to casting registry
+
+Update `.squad/casting/registry.json` with the new entry.
+
+### Step 7: Verify
+
+Ask yourself these questions:
+
+- [ ] If a clean session coordinator reads `routing.md` Rules, will it know to route PRs to this reviewer? → Check rule N exists.
+- [ ] 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.
+- [ ] Can the coordinator merge a PR without the reviewer's approval? → The rule should say "No PR merges without {Name}'s approval."
+- [ ] Can the coordinator close an issue without a merged PR? → Check the issue closure rule exists.
+
+If any answer is wrong, you have a gap.
+
+## What Each File Controls (Summary)
+
+| File | What it contributes to the reviewer gate |
+|------|----------------------------------------|
+| `charter.md` | WHO the reviewer is and HOW they review |
+| `team.md` | That the reviewer EXISTS on the team |
+| `routing.md` routing table | That explicit review requests go to this reviewer |
+| `routing.md` Rules section | That the coordinator MUST route EVERY PR to this reviewer (enforcement) |
+| `issue-lifecycle.md` | The step-by-step procedure for the post-work review flow |
+| `casting/registry.json` | Persistent name tracking |
+
+**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

@@ -0,0 +1,140 @@
+# Appendix B: Wiring a Documenter/Librarian — Complete Walkthrough
+
+> 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.
+
+## The Problem This Solves
+
+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.
+
+## Gate vs Follow-Up Trigger
+
+| 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.
+
+## Step-by-Step Walkthrough
+
+### Step 1: Create the documenter's identity
+
+Create `.squad/agents/{name}/charter.md`:
+
+```markdown
+# {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, operations
+```
+
+Create `.squad/agents/{name}/history.md` seeded with project context.
+
+### Step 2: Add to team.md roster
+
+```markdown
+| 📝 {Name} | Documenter | `.squad/agents/{name}/charter.md` | ✅ Active |
+```
+
+### Step 3: Add routing table entry
+
+In `routing.md` → routing table:
+
+```markdown
+| Documentation, reports, summaries | 📝 {Name} | `docs/` | "Write docs for X", "Summarize this", guides, READMEs |
+```
+
+### Step 4: Add follow-up trigger rule
+
+In `routing.md` → `## Rules` section, add a numbered rule:
+
+```markdown
+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.
+
+### Step 5: Wire into the coordinator's post-merge flow
+
+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:
+
+```markdown
+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`:
+
+```yaml
+- 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"
+```
+
+### Step 6: Worktree for doc changes
+
+If the documenter produces files, they need a worktree — docs are files too. The coordinator should:
+1. Create a worktree for the doc update (e.g., `squad/{issue}-docs`)
+2. The documenter commits and pushes
+3. A PR is created for the docs
+4. The docs PR goes through the normal review flow (including the code reviewer if you have one)
+
+This means doc changes also get reviewed. The documenter is not exempt from the review gate.
+
+### Step 7: Add to casting registry
+
+Update `.squad/casting/registry.json` with the new entry.
+
+### Step 8: Verify
+
+- [ ] After a feature PR merges, does the coordinator spawn the documenter? → Check the routing rule exists.
+- [ ] Does the documenter get a worktree for their work? → Check the worktree rule covers docs.
+- [ ] Do doc changes go through the review gate? → They should — docs are files, files need PRs, PRs need review.
+- [ ] Is the follow-up non-blocking? → The documenter should be background, not sync.
+
+## What Each File Controls (Summary)
+
+| 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.