specweave 1.0.464 → 1.0.466

package/plugins/specweave/skills/team-lead/SKILL.md

@@ -314,11 +314,17 @@ Analyze domains
 
 ## 3b. Plan Review Workflow
 
-The team lead acts as **architectural reviewer** for all sub-agent plans. Do NOT auto-accept plans.
+The team lead reviews agent plans **asynchronously**. Agents do NOT wait for approval — they proceed to implementation immediately after creating plans and sending a notification.
 
-### Why Review
+### Why Async Review
 
-Without review, agents may duplicate work across domains, misinterpret scope, make conflicting architectural decisions, or produce plans misaligned with the spec.
+The previous blocking PLAN_READY/PLAN_APPROVED handshake caused sessions to freeze:
+- When 3-5 Phase 2 agents spawned simultaneously, they ALL blocked waiting for approval
+- Team-lead had to review each plan sequentially while all agents sat idle
+- If team-lead was processing another message (or in extended thinking), agents waited indefinitely
+- In tmux/iTerm2, this appeared as a completely frozen session
+
+Async review eliminates the bottleneck: agents proceed immediately, and the team-lead only intervenes when something is wrong.
 
 ### Permission Mode: bypassPermissions (CRITICAL)
 
@@ -330,56 +336,56 @@ Without review, agents may duplicate work across domains, misinterpret scope, ma
 
 **NEVER use `mode: "plan"` for agent spawns** — it causes agents to block on the trust-folder prompt.
 
-### Protocol (SendMessage-Based)
-
-Since agents use `bypassPermissions` (not `plan` mode), plan review uses an explicit SendMessage protocol:
+### Protocol (Async Notify + Correct)
 
 **Agent side** (built into every agent prompt template):
 1. Read the increment spec and explore the codebase
 2. Create plan files (spec.md, plan.md, tasks.md) in the increment directory
-3. Send plan summary to team-lead:
+3. Send a structured plan notification to team-lead:
 ```
 SendMessage({
   type: "message",
   recipient: "team-lead",
-  content: "PLAN_READY: Created spec.md, plan.md, tasks.md at .specweave/increments/[ID]/. Summary: [key decisions, file list, task count]. Ready for review.",
-  summary: "Plan ready for review"
+  content: "PLAN_READY: Created .specweave/increments/[ID]/\nTasks: [count]\nACs covered: [list AC-IDs]\nKey decisions: [1-2 sentence summary]\nFiles to create/modify: [file list]\nArchitecture: [pattern/approach chosen]",
+  summary: "Plan ready — proceeding to implementation"
 });
 ```
-4. **WAIT for PLAN_APPROVED message** before starting implementation. Do NOT proceed without approval.
+4. **Proceed to implementation IMMEDIATELY.** Do NOT wait for any response.
+5. If team-lead sends `PLAN_CORRECTION`, pause current work, revise the plan, and continue.
 
 **Team-lead side**:
-1. Receive `PLAN_READY` message from agent
-2. Read the agent's plan files (spec.md, plan.md, tasks.md)
-3. Evaluate:
-   - Does it align with the feature spec and ACs?
-   - Is the architecture consistent with existing codebase patterns?
-   - Does the agent stay within its file ownership boundaries?
-   - Are there conflicts with other agents' plans?
-   - Is scope correct — not too broad, not too narrow?
-4. Approve or reject:
-
-```
-// Approve
+1. Receive `PLAN_READY` notification from agent
+2. Review using the **structured summary in the message** (do NOT read full plan files unless a concern is detected)
+3. Quick-evaluate:
+   - Do the covered ACs match what this agent should handle?
+   - Are the files within this agent's ownership boundaries?
+   - Do any key decisions conflict with other agents' plans?
+   - Is the task count reasonable (<15)?
+4. If plan looks good: **do nothing** — agent is already implementing
+5. If plan has issues: send correction:
+
+```
+// Correct a plan issue (agent is already implementing)
 SendMessage({
   type: "message",
   recipient: "database-agent",
-  content: "PLAN_APPROVED: Go ahead with implementation.",
-  summary: "Plan approved"
-});
-
-// Reject with feedback
-SendMessage({
-  type: "message",
-  recipient: "database-agent",
-  content: "PLAN_REJECTED: Revise: 1) Add index on user_id for sessions. 2) Missing migration for AC-US1-03.",
-  summary: "Plan needs revision"
+  content: "PLAN_CORRECTION: 1) Add index on user_id for sessions. 2) You're missing AC-US1-03 — add a task for it. Pause current work and revise before continuing.",
+  summary: "Plan needs correction"
 });
 ```
+6. If agent ignores `PLAN_CORRECTION` (continues without revising after 2 turns):
+```
+SendMessage({ type: "shutdown_request", recipient: "database-agent" });
+// Report to user: "Agent ignored correction, shutting down. Manual intervention needed."
+```
 
-### Non-Blocking Review
+### Review Priorities
 
-Plan review MUST NOT block other agents. Review plans as they arrive — agents waiting for approval are idle, but other agents continue working normally.
+Not all plans need deep review. Prioritize:
+- **Phase 1 (upstream) plans** — errors here cascade to all downstream agents
+- **Plans with >10 tasks** — higher risk of scope creep
+- **Plans touching shared files** — ownership conflicts
+- **Single-agent teams** — skip review entirely (no coordination needed)
 
 ### Multi-Increment Consideration
 
@@ -482,8 +488,11 @@ Agents communicate contract readiness, blocking issues, and completion status us
 | Prefix | Purpose | Sender | Receiver |
 |--------|---------|--------|----------|
 | `CONTRACT_READY:` | Upstream contract is published | Upstream agent | team-lead (broadcasts to downstream) |
+| `PLAN_READY:` | Plan created, agent proceeding to implementation | Any agent | team-lead (async review) |
+| `STATUS:` | Heartbeat — task progress update | Any agent | team-lead (stuck detection) |
 | `BLOCKING_ISSUE:` | Agent is stuck, needs help | Any agent | team-lead |
 | `COMPLETION:` | Agent finished all tasks | Any agent | team-lead |
+| `PLAN_CORRECTION:` | Plan needs revision (async) | team-lead | Specific agent |
 
 ### Message Examples
 
@@ -496,6 +505,22 @@ SendMessage({
   summary: "Shared types contract ready"
 });
 
+// Agent notifies plan is ready (does NOT wait for response)
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "PLAN_READY: Created .specweave/increments/0202-checkout-backend/\nTasks: 8\nACs covered: AC-US1-01, AC-US1-02, AC-US2-01\nKey decisions: REST API with Express, JWT auth middleware\nFiles: src/api/checkout.ts, src/services/payment.ts, src/middleware/auth.ts\nArchitecture: Controller-Service-Repository pattern",
+  summary: "Backend plan ready — proceeding to implementation"
+});
+
+// Agent heartbeat after each task completion
+SendMessage({
+  type: "message",
+  recipient: "team-lead",
+  content: "STATUS: T-003/8 complete. Next: T-004 (implement payment service). Tests: 12/12 passing.",
+  summary: "Backend agent: task 3 of 8 done"
+});
+
 // Agent reports a blocking issue
 SendMessage({
   type: "message",
@@ -511,6 +536,14 @@ SendMessage({
   content: "COMPLETION: All 8 tasks done. Tests passing (24/24). Ready for team-lead closure.",
   summary: "Frontend agent completed all tasks"
 });
+
+// Team-lead sends async plan correction (agent is already implementing)
+SendMessage({
+  type: "message",
+  recipient: "database-agent",
+  content: "PLAN_CORRECTION: 1) Add index on user_id for sessions table. 2) Missing AC-US1-03 — add a migration task. Pause and revise.",
+  summary: "Plan correction for database agent"
+});
 ```
 
 ---
@@ -528,7 +561,7 @@ TeamCreate({
 
 ### Step 2: Spawn Upstream Agents (Phase 1)
 
-All agents are spawned with `mode: "bypassPermissions"` to prevent blocking on trust-folder prompts. Plan review is enforced via the SendMessage PLAN_READY/PLAN_APPROVED protocol (see Section 3b).
+All agents are spawned with `mode: "bypassPermissions"` to prevent blocking on trust-folder prompts. Agents notify team-lead of their plans via PLAN_READY but proceed to implementation immediately (see Section 3b for async review protocol).
 
 For each agent: **Read the agent definition file** (see Section 4 reference table), replace placeholders (`[INCREMENT_ID]`, `[MASTER_INCREMENT_PATH]`, `{ORG}`, `{repo-name}`), and use the full content as the Task() prompt.
 
@@ -598,15 +631,39 @@ Agent Workflow:
 
 **Why agents don't run /sw:done**: The /sw:done skill invokes 4 sub-skills (grill, judge-llm, sync-docs, qa), each loading a full SKILL.md. After 15+ tasks of auto-mode context, this pushes agents into extended thinking (30+ min hangs). Centralizing closure on the team-lead (which has a cleaner context) avoids this.
 
-### Orchestrator Quality Gate (Centralized Closure)
+### Active Phase Rules (CRITICAL — While Agents Are Implementing)
+
+**During the active phase (between spawning agents and receiving ALL COMPLETION signals), the team-lead MUST NOT run any closure operations.**
 
-After all agents complete, the team-lead runs closure **centrally** for each increment.
+```
+ALLOWED during active phase:
+  ✓ Process SendMessage from agents (PLAN_READY, STATUS, CONTRACT_READY, BLOCKING_ISSUE, COMPLETION)
+  ✓ Async plan review (read PLAN_READY summaries, send PLAN_CORRECTION if needed)
+  ✓ Track heartbeat STATUS per agent for stuck detection
+  ✓ Respond to BLOCKING_ISSUE messages
+  ✓ Send STATUS_CHECK to silent agents
+  ✓ Shutdown stuck agents
+
+FORBIDDEN during active phase:
+  ✗ Run /sw:grill on any increment
+  ✗ Run /sw:done on any increment
+  ✗ Invoke any closure-related skills (judge-llm, sync-docs, qa)
+  ✗ Read full plan/spec files (use PLAN_READY summaries instead)
+```
+
+**Why**: Closure loads 4+ skill definitions into context. Running it while agents are active causes the orchestrator to enter extended thinking (30+ min) and stop responding to agent messages — freezing the entire session.
+
+### Orchestrator Quality Gate — Closure Phase (After ALL Agents Complete)
+
+**Closure begins ONLY after ALL agents have signaled COMPLETION (or been declared stuck).**
+
+The team-lead runs closure **centrally** for each increment, sequentially in dependency order.
 
 **CRITICAL: Increments MUST be closed sequentially, not skipped on failure.**
 
 ```
-Orchestrator Final Check:
-  1. All agents signaled COMPLETION
+Closure Phase (triggered when all COMPLETION signals received):
+  1. Verify: all agents signaled COMPLETION (or declared stuck)
   2. No unresolved BLOCKING_ISSUE messages
   3. Run full test suite (all domains combined)
   4. For EACH increment in dependency order (shared → database → backend → frontend → testing → security):
@@ -655,34 +712,56 @@ Orchestrator Final Check:
 
 ---
 
-## 8b. Agent Timeout and Stuck Detection
+## 8b. Agent Timeout and Stuck Detection (Heartbeat-Based)
+
+Agents send `STATUS: T-{N}/{total}` heartbeat messages after each task completion. The team-lead uses these to detect stuck agents proactively.
 
-Agents can get stuck in extended thinking if their context overflows. The team-lead MUST monitor for stuck agents.
+### Heartbeat Tracking
+
+The team-lead maintains a mental log of the last STATUS received from each agent:
+
+```
+Agent Heartbeat Log (example):
+  backend-agent:  STATUS T-003/8  (last seen: 2 turns ago)
+  frontend-agent: STATUS T-005/12 (last seen: this turn)
+  database-agent: COMPLETION       (done)
+  testing-agent:  STATUS T-001/6  (last seen: 4 turns ago) ← STUCK?
+```
 
 ### Stuck Detection Rules
 
-**Note**: Claude Code has no built-in timers. These are best-effort heuristics applied when the team-lead regains control (e.g., after processing other agent messages).
+**Note**: Claude Code has no built-in timers. Heartbeats are tracked relative to team-lead turns (each time the orchestrator processes messages).
 
 | Condition | Action |
 |-----------|--------|
-| Agent has not messaged since team-lead's last turn | Send `STATUS_CHECK` message to agent |
-| Agent does not respond to STATUS_CHECK on next team-lead turn | Declare agent stuck |
-| Agent stuck | Log warning, proceed with other agents, handle stuck agent's increment manually in team-merge |
+| Agent sent STATUS within last 2 team-lead turns | Healthy — no action needed |
+| No STATUS from agent for 2 consecutive turns | Send `STATUS_CHECK` message to agent |
+| No STATUS for 3 consecutive turns (or no response to STATUS_CHECK) | Declare agent stuck |
+| Agent sends STATUS but task number hasn't changed for 3+ heartbeats | Stuck in loop — declare stuck |
 | All agents stuck | STOP team, report to user |
 
+### Stuck-in-Loop Detection
+
+An agent may appear to send heartbeats but actually be looping on the same task (e.g., test fails → fix → test fails → fix → ...). To detect this:
+
+- Track the task number in each STATUS message
+- If the same task number appears in 3+ consecutive STATUS messages from the same agent, the agent is stuck in a loop
+- Action: send a message to the agent with guidance, or declare stuck if the loop continues
+
 ### Stuck Agent Recovery
 
 When an agent is declared stuck:
-1. Do NOT wait for it — proceed with closure of other agents' increments
-2. Note the stuck agent's increment ID and last known task progress
-3. During /sw:team-merge, the stuck agent's increment is left open for manual completion
-4. Send shutdown_request to the stuck agent to free resources
+1. Do NOT wait for it — proceed with other agents
+2. Note the stuck agent's increment ID and last known task progress (from last STATUS)
+3. Send shutdown_request to the stuck agent to free resources
+4. During closure phase, the stuck agent's increment is left open for manual completion
 
 ### Preventing Stuck Agents
 
 - Enforce the 15-task cap (Section 3b)
 - Agents use `--simple` flag in auto-mode (reduces context per iteration)
 - Agents do NOT run /sw:done (team-lead handles closure centrally)
+- Heartbeat STATUS messages let team-lead detect problems early instead of after long silences
 - If an agent's task count exceeds 15 despite the cap, the team-lead should split it before spawning
 
 ---
@@ -697,18 +776,29 @@ When an agent is declared stuck:
   │     └── Missing? → Auto-invoke /sw:increment, wait for completion
   ├── Step 0b: ACTIVATE MASTER INCREMENT (MANDATORY)
   │     └── Edit metadata.json: set status to "active" BEFORE spawning agents
-  ├── Step 1: Analyze feature (from master spec) -> identify domains -> decide increment split
+  ├── Step 1: Analyze feature (from master spec) → identify domains → decide increment split
   ├── Step 2: Create team via TeamCreate
   ├── Step 3: Create per-domain increments (derived from master spec)
+  │
+  │ ── ACTIVE PHASE (agents implementing, team-lead monitoring) ──
+  │
   ├── Step 4: Contract-first spawning (all agents with mode: "bypassPermissions")
   │     ├── Phase 1: Spawn shared + database
-  │     │     └── Receive PLAN_READY, review & approve via SendMessage (Section 3b)
-  │     │     └── Wait for CONTRACT_READY after approval
+  │     │     └── Agents send PLAN_READY notification → proceed immediately
+  │     │     └── Team-lead reviews async, sends PLAN_CORRECTION only if needed
+  │     │     └── Wait for CONTRACT_READY
   │     └── Phase 2: Spawn backend + frontend + testing
-  │           └── Receive PLAN_READY, review & approve via SendMessage
-  ├── Step 5: Monitor progress via SendMessage (timeout: 20min idle → STATUS_CHECK)
-  ├── Step 6: Agents signal COMPLETION (tests pass, no /sw:grill or /sw:done on agents)
-  ├── Step 7: Team-lead runs centralized closure per increment:
+  │           └── Agents send PLAN_READY notification → proceed immediately
+  ├── Step 5: Monitor progress via STATUS heartbeats
+  │     ├── Track per-agent: last STATUS task number and turn count
+  │     ├── No STATUS for 2 turns → send STATUS_CHECK
+  │     ├── No STATUS for 3 turns or same task 3+ times → declare stuck
+  │     └── DO NOT run grill/done/closure during this phase
+  ├── Step 6: Collect all COMPLETION signals (or declare remaining agents stuck)
+  │
+  │ ── CLOSURE PHASE (all agents done, team-lead runs quality gates) ──
+  │
+  ├── Step 7: Team-lead runs centralized closure per increment (dependency order):
   │     ├── Pre-closure: verify/fix metadata.json status → must be "active"
   │     ├── /sw:grill → fix findings → retry if needed (max 2)
   │     └── /sw:done --auto → fix gate failures → retry if needed (max 2)
@@ -761,6 +851,10 @@ To execute, run without --dry-run.
 |-------|-------|-----|
 | **TeamCreate blocked by guard** | No increment with spec.md exists | Run `/sw:increment "feature"` first, then retry `/sw:team-lead`. The guard requires a substantive spec.md (>200 bytes, not a template) |
 | **Agent stuck on trust folder** | Agent spawned without `bypassPermissions` | ALWAYS use `mode: "bypassPermissions"` — NEVER `mode: "plan"`. Trust prompts require interactive input agents cannot provide |
+| **Session freezes after first agent completes** | Closure ran during active phase (pre-v0528 bug) | Ensure §8 active-phase rules are followed: NO grill/done until ALL agents signal COMPLETION |
+| **Agent proceeds with wrong plan** | Async model means agents don't wait for approval | Send `PLAN_CORRECTION` immediately; agent should pause and revise. If ignored, send `shutdown_request` |
+| **No heartbeat STATUS from agent** | Agent didn't implement heartbeat or is stuck | Check if agent template includes heartbeat step. If yes, agent is stuck — send STATUS_CHECK, then declare stuck after 3 turns |
+| **Agent stuck in loop (same task repeated)** | Test fail → fix → test fail cycle | Heartbeat shows same task number 3+ times. Send guidance message or declare stuck |
 | **Agents editing same files** | Overlapping file ownership patterns | Review ownership map; reassign conflicting files to a single owner; use `--dry-run` to validate before launch |
 | **Token cost too high** | Too many agents or overly large prompts | Reduce `--max-agents`; use `--domains` to limit scope; split feature into smaller increments |
 | **Agent stuck in extended thinking** | Too many tasks (>15) causing context overflow | Enforce 15-task cap per agent; split large domains into 2 agents; agents use `--simple` mode |

package/plugins/specweave/skills/team-lead/agents/backend.md

@@ -38,17 +38,21 @@ WORKFLOW:
      - Read prisma/schema.prisma for database schema
      - Read src/types/ for shared interfaces
   8. Create plan files (plan.md, tasks.md) for your increment
-  9. Send plan to team-lead and WAIT for approval:
+  9. Send structured plan notification to team-lead (do NOT wait for approval):
      SendMessage({ type: "message", recipient: "team-lead",
-       content: "PLAN_READY: [increment path]. [summary of planned tasks and files].",
-       summary: "Backend plan ready for review" })
-  10. WAIT for "PLAN_APPROVED" message. If "PLAN_REJECTED", revise and re-submit.
+       content: "PLAN_READY: Created [increment path]\nTasks: [count]\nACs covered: [AC-IDs]\nKey decisions: [summary]\nFiles: [file list]\nArchitecture: [approach]",
+       summary: "Backend plan ready — proceeding to implementation" })
+  10. Proceed to implementation IMMEDIATELY. If team-lead sends "PLAN_CORRECTION", pause current work, revise, then continue.
   11. Execute tasks autonomously: /sw:auto --simple (minimal context mode to prevent context overflow)
-  12. Generate or update OpenAPI spec if API routes change
-  13. Run all tests for owned code (unit + integration): npm test
-  14. Do NOT signal completion until all tests pass
-  15. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
-  16. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
+  12. After EACH task completion, send heartbeat:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "STATUS: T-{N}/{total} complete. Next: T-{N+1}. Tests: [pass/fail count].",
+       summary: "Backend agent: task {N} of {total} done" })
+  13. Generate or update OpenAPI spec if API routes change
+  14. Run all tests for owned code (unit + integration): npm test
+  15. Do NOT signal completion until all tests pass
+  16. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
+  17. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
 
 RULES:
   - WRITE only to files you own (listed above)

package/plugins/specweave/skills/team-lead/agents/database.md

@@ -27,19 +27,23 @@ WORKFLOW:
   5. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   6. Design database schema changes
   7. Create plan files (plan.md, tasks.md) for your increment
-  8. Send plan to team-lead and WAIT for approval:
+  8. Send structured plan notification to team-lead (do NOT wait for approval):
      SendMessage({ type: "message", recipient: "team-lead",
-       content: "PLAN_READY: [increment path]. [summary of schema changes, migrations, seed data].",
-       summary: "Database plan ready for review" })
-  9. WAIT for "PLAN_APPROVED" message. If "PLAN_REJECTED", revise and re-submit.
+       content: "PLAN_READY: Created [increment path]\nTasks: [count]\nACs covered: [AC-IDs]\nKey decisions: [schema changes summary]\nFiles: [migration files, schema changes]\nArchitecture: [approach]",
+       summary: "Database plan ready — proceeding to implementation" })
+  9. Proceed to implementation IMMEDIATELY. If team-lead sends "PLAN_CORRECTION", pause current work, revise, then continue.
   10. Generate Prisma migration: npx prisma migrate dev --name <migration-name>
   11. Write seed data if needed
   12. Execute tasks autonomously: /sw:auto --simple (minimal context mode to prevent context overflow)
-  13. Run all tests for owned code (migration, seed): npm test
-  14. Do NOT signal completion until all tests pass
-  15. Signal CONTRACT_READY with schema details via SendMessage to team-lead
-  16. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
-  17. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
+  13. After EACH task completion, send heartbeat:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "STATUS: T-{N}/{total} complete. Next: T-{N+1}. Tests: [pass/fail count].",
+       summary: "Database agent: task {N} of {total} done" })
+  14. Run all tests for owned code (migration, seed): npm test
+  15. Do NOT signal completion until all tests pass
+  16. Signal CONTRACT_READY with schema details via SendMessage to team-lead
+  17. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
+  18. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
 
 RULES:
   - WRITE only to files you own (listed above)

package/plugins/specweave/skills/team-lead/agents/frontend.md

@@ -40,16 +40,20 @@ WORKFLOW:
      - Read src/types/ for shared interfaces
      - Read openapi.yaml for API endpoints (if backend produces one)
   8. Create plan files (plan.md, tasks.md) for your increment
-  9. Send plan to team-lead and WAIT for approval:
+  9. Send structured plan notification to team-lead (do NOT wait for approval):
      SendMessage({ type: "message", recipient: "team-lead",
-       content: "PLAN_READY: [increment path]. [summary of planned tasks and files].",
-       summary: "Frontend plan ready for review" })
-  10. WAIT for "PLAN_APPROVED" message. If "PLAN_REJECTED", revise and re-submit.
+       content: "PLAN_READY: Created [increment path]\nTasks: [count]\nACs covered: [AC-IDs]\nKey decisions: [summary]\nFiles: [file list]\nArchitecture: [approach]",
+       summary: "Frontend plan ready — proceeding to implementation" })
+  10. Proceed to implementation IMMEDIATELY. If team-lead sends "PLAN_CORRECTION", pause current work, revise, then continue.
   11. Execute tasks autonomously: /sw:auto --simple (minimal context mode to prevent context overflow)
-  12. Run all tests for owned code (unit + integration): npm test
-  13. Do NOT signal completion until all tests pass
-  14. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
-  15. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
+  12. After EACH task completion, send heartbeat:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "STATUS: T-{N}/{total} complete. Next: T-{N+1}. Tests: [pass/fail count].",
+       summary: "Frontend agent: task {N} of {total} done" })
+  13. Run all tests for owned code (unit + integration): npm test
+  14. Do NOT signal completion until all tests pass
+  15. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
+  16. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
 
 RULES:
   - WRITE only to files you own (listed above)

package/plugins/specweave/skills/team-lead/agents/security.md

@@ -28,19 +28,23 @@ WORKFLOW:
   5. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   6. Audit code produced by other agents for security issues
   7. Create plan files (plan.md, tasks.md) for your increment
-  8. Send plan to team-lead and WAIT for approval:
+  8. Send structured plan notification to team-lead (do NOT wait for approval):
      SendMessage({ type: "message", recipient: "team-lead",
-       content: "PLAN_READY: [increment path]. [summary of security findings, hardening plan].",
-       summary: "Security plan ready for review" })
-  9. WAIT for "PLAN_APPROVED" message. If "PLAN_REJECTED", revise and re-submit.
+       content: "PLAN_READY: Created [increment path]\nTasks: [count]\nACs covered: [AC-IDs]\nKey decisions: [security findings, hardening approach]\nFiles: [file list]\nRisk areas: [identified vulnerabilities]",
+       summary: "Security plan ready — proceeding to implementation" })
+  9. Proceed to implementation IMMEDIATELY. If team-lead sends "PLAN_CORRECTION", pause current work, revise, then continue.
   10. Implement auth/authz middleware if needed
   11. Add input validation and sanitization
   12. Execute tasks autonomously: /sw:auto --simple (minimal context mode to prevent context overflow)
-  13. Run all tests for owned code (security tests): npm test
-  14. Run security audit tools (npm audit, dependency check)
-  15. Do NOT signal completion until all tests pass
-  16. Signal COMPLETION via SendMessage to team-lead with summary of tasks done, test results, and security findings
-  17. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
+  13. After EACH task completion, send heartbeat:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "STATUS: T-{N}/{total} complete. Next: T-{N+1}. Tests: [pass/fail count].",
+       summary: "Security agent: task {N} of {total} done" })
+  14. Run all tests for owned code (security tests): npm test
+  15. Run security audit tools (npm audit, dependency check)
+  16. Do NOT signal completion until all tests pass
+  17. Signal COMPLETION via SendMessage to team-lead with summary of tasks done, test results, and security findings
+  18. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
 
 RULES:
   - WRITE only to files you own (listed above)

package/plugins/specweave/skills/team-lead/agents/testing.md

@@ -33,19 +33,23 @@ WORKFLOW:
   5. Read the MASTER SPEC at [MASTER_INCREMENT_PATH]/spec.md for scope and ACs
   6. Wait for ALL other agents to produce initial code
   7. Create plan files (plan.md, tasks.md) for your increment
-  8. Send plan to team-lead and WAIT for approval:
+  8. Send structured plan notification to team-lead (do NOT wait for approval):
      SendMessage({ type: "message", recipient: "team-lead",
-       content: "PLAN_READY: [increment path]. [summary of test strategy, coverage plan].",
-       summary: "Testing plan ready for review" })
-  9. WAIT for "PLAN_APPROVED" message. If "PLAN_REJECTED", revise and re-submit.
+       content: "PLAN_READY: Created [increment path]\nTasks: [count]\nACs covered: [AC-IDs]\nKey decisions: [test strategy, frameworks]\nFiles: [test file list]\nCoverage plan: [unit/integration/E2E breakdown]",
+       summary: "Testing plan ready — proceeding to implementation" })
+  9. Proceed to implementation IMMEDIATELY. If team-lead sends "PLAN_CORRECTION", pause current work, revise, then continue.
   10. Write unit tests for new services/components
   11. Write integration tests for API endpoints
   12. Write E2E tests for user journeys
   13. Execute tasks autonomously: /sw:auto --simple (minimal context mode to prevent context overflow)
-  14. Run all tests (unit + integration + E2E): npm test && npx playwright test
-  15. Do NOT signal completion until all tests pass -- if tests fail, fix and repeat
-  16. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
-  17. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
+  14. After EACH task completion, send heartbeat:
+     SendMessage({ type: "message", recipient: "team-lead",
+       content: "STATUS: T-{N}/{total} complete. Next: T-{N+1}. Tests: [pass/fail count].",
+       summary: "Testing agent: task {N} of {total} done" })
+  15. Run all tests (unit + integration + E2E): npm test && npx playwright test
+  16. Do NOT signal completion until all tests pass -- if tests fail, fix and repeat
+  17. Signal COMPLETION via SendMessage to team-lead with summary of tasks done and test results
+  18. Do NOT run /sw:done or /sw:grill yourself — team-lead handles closure centrally
 
 RULES:
   - WRITE only to test files (listed above)

package/plugins/specweave-ado/lib/ado-ac-checkbox-sync.js

@@ -226,7 +226,7 @@ ${acLines}
             external_url: fm.external_url,
             imported_at: fm.imported_at,
             origin: fm.origin,
-            external_tools: fm.external_tools || fm.external
+            external_tools: { ...fm.external || {}, ...fm.external_tools || {} }
           });
         }
       }

package/plugins/specweave-ado/lib/ado-ac-checkbox-sync.ts

@@ -292,7 +292,7 @@ ${acLines}
             external_source: fm.external_source,
             external_id: fm.external_id, external_url: fm.external_url,
             imported_at: fm.imported_at, origin: fm.origin,
-            external_tools: fm.external_tools || fm.external,
+            external_tools: { ...(fm.external || {}), ...(fm.external_tools || {}) },
           });
         }
       }

package/plugins/specweave-ado/lib/ado-spec-sync.js

@@ -411,7 +411,7 @@ ${SpecParser.extractOverview(spec.markdown).replace(/\n/g, "<br>")}
    * Generate story description from user story
    */
   generateStoryDescription(us) {
-    const acList = us.acceptanceCriteria.map((ac) => `<li>${ac.status === "done" ? "\u2611" : "\u2610"} ${ac.description}</li>`).join("\n");
+    const acList = us.acceptanceCriteria.map((ac) => `<li>${ac.status === "done" ? "\u2611" : "\u2610"} ${ac.id}: ${ac.description}</li>`).join("\n");
     return `
 <h2>User Story</h2>
 

package/plugins/specweave-ado/lib/ado-spec-sync.ts

@@ -563,7 +563,7 @@ ${SpecParser.extractOverview(spec.markdown).replace(/\n/g, '<br>')}
    */
   private generateStoryDescription(us: UserStory): string {
     const acList = us.acceptanceCriteria
-      .map(ac => `<li>${ac.status === 'done' ? '☑' : '☐'} ${ac.description}</li>`)
+      .map(ac => `<li>${ac.status === 'done' ? '☑' : '☐'} ${ac.id}: ${ac.description}</li>`)
       .join('\n');
 
     return `

package/plugins/specweave-github/lib/github-ac-checkbox-sync.js

@@ -262,7 +262,7 @@ ${[...usAcStatus.entries()].map(
           const match = fileContent.match(/^---\n([\s\S]*?)\n---/);
           if (match) {
             const fm = yaml.parse(match[1]);
-            const externalTools = fm.external_tools || fm.external;
+            const externalTools = { ...fm.external || {}, ...fm.external_tools || {} };
             usFiles.push({
               id: fm.id,
               title: fm.title,

package/plugins/specweave-github/lib/github-ac-checkbox-sync.ts

@@ -367,8 +367,8 @@ ${[...usAcStatus.entries()].map(([id, done]) =>
           const match = fileContent.match(/^---\n([\s\S]*?)\n---/);
           if (match) {
             const fm = yaml.parse(match[1]);
-            // Support both external_tools (legacy) and external (living docs) formats
-            const externalTools = fm.external_tools || fm.external;
+            // Merge both external_tools and external (GitHub writes external, JIRA/ADO write external_tools)
+            const externalTools = { ...(fm.external || {}), ...(fm.external_tools || {}) };
             usFiles.push({
               id: fm.id,
               title: fm.title,

package/plugins/specweave-github/lib/github-feature-sync.js

@@ -5,8 +5,8 @@ import * as yaml from "yaml";
 import { UserStoryIssueBuilder } from "./user-story-issue-builder.js";
 import { CompletionCalculator } from "./completion-calculator.js";
 import { DuplicateDetector } from "./duplicate-detector.js";
-import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
-import { getGitHubAuthFromProject } from "../../../src/utils/auth-helpers.js";
+import { execFileNoThrow } from "../../specweave/lib/vendor/utils/execFileNoThrow.js";
+import { getGitHubAuthFromProject } from "../../specweave/lib/vendor/utils/auth-helpers.js";
 const _GitHubFeatureSync = class _GitHubFeatureSync {
   // 30 seconds
   constructor(client, specsDir, projectRoot) {
@@ -974,6 +974,14 @@ ${newFrontmatter}---${bodyContent}`;
       throw new Error(`${userStoryPath}: Missing YAML frontmatter`);
     }
     const frontmatter = yaml.parse(match[1]);
+    if (!frontmatter.external_tools) {
+      frontmatter.external_tools = {};
+    }
+    if (!frontmatter.external_tools.github) {
+      frontmatter.external_tools.github = {};
+    }
+    frontmatter.external_tools.github.issue = issueNumber;
+    frontmatter.external_tools.github.url = `https://github.com/${this.client.getOwner()}/${this.client.getRepo()}/issues/${issueNumber}`;
     if (!frontmatter.external) {
       frontmatter.external = {};
     }
@@ -981,7 +989,7 @@ ${newFrontmatter}---${bodyContent}`;
       frontmatter.external.github = {};
     }
     frontmatter.external.github.issue = issueNumber;
-    frontmatter.external.github.url = `https://github.com/${this.client.getOwner()}/${this.client.getRepo()}/issues/${issueNumber}`;
+    frontmatter.external.github.url = frontmatter.external_tools.github.url;
     const newFrontmatter = yaml.stringify(frontmatter);
     const bodyContent = content.slice(match[0].length);
     const newContent = `---