From damascus
Diagnose stuck or broken Damascus /forge-team sessions. Trigger only when user mentions forge-team or damascus-forge AND describes a problem. Not for general agent teams questions or non-Damascus issues.
npx claudepluginhub flashwade03/damascus-for-claude-code --plugin damascusThis skill uses the workspace's default tool permissions.
Diagnose and resolve issues in Damascus `/forge-team` Agent Teams sessions. This skill encodes hard-won debugging knowledge from real production failures.
Creates new Angular apps using Angular CLI with flags for routing, SSR, SCSS, prefixes, and AI config. Follows best practices for modern TypeScript/Angular development. Use when starting Angular projects.
Generates Angular code and provides architectural guidance for projects, components, services, reactivity with signals, forms, dependency injection, routing, SSR, ARIA accessibility, animations, Tailwind styling, testing, and CLI tooling.
Executes ctx7 CLI to fetch up-to-date library documentation, manage AI coding skills (install/search/generate/remove/suggest), and configure Context7 MCP. Useful for current API refs, skill handling, or agent setup.
Diagnose and resolve issues in Damascus /forge-team Agent Teams sessions. This skill encodes hard-won debugging knowledge from real production failures.
When the user reports a stuck session, identify which phase is stuck:
| Symptom | Likely Phase | Jump To |
|---|---|---|
| "Nothing happening after start" | Phase 0 or 1 | Setup Phase Failures first, then Planner Issues |
| "Explorers finished but plan not submitted" | Phase 1 — ExitPlanMode | ExitPlanMode Failures |
| "Plan submitted but file not written" | Phase 2 — Writing | Scribe Issues |
| "File written but reviews not arriving" | Phase 3 — Review | Message Routing |
| "Reviews done but no verdict / no next round" | Phase 4 — Consolidation | Message Routing |
| "Session just hangs indefinitely" | Any | Full Diagnostic |
Run these steps in order. At each step, also rule out other known failures — explicitly note which patterns you checked and eliminated. This differential diagnosis prevents misattribution when symptoms overlap (e.g., "nothing happening" could be Setup Phase failure OR ExitPlanMode failure).
ls ~/.claude/teams/damascus-forge/
Expected: config.json + inboxes/ directory. If missing → team was never created or was already deleted.
# List all inboxes
ls ~/.claude/teams/damascus-forge/inboxes/
# Check Lead's inbox for unread messages
cat ~/.claude/teams/damascus-forge/inboxes/team-lead.json | jq '.[] | select(.read == false)'
# Check specific teammate inbox
cat ~/.claude/teams/damascus-forge/inboxes/planner.json | jq '.[] | select(.read == false)'
Key insight: Lead's inbox is team-lead.json, NOT lead.json. This is the #1 routing bug — see Message Routing.
Differential checks at this step:
lead.json exists → routing bug (F-001), jump to Message Routingteam-lead.json + planner.json exist (no explorer/scribe/reviewer inboxes) → Setup Phase Failuresteam-lead.json has no plan_approval_request → ExitPlanMode Failures# See all messages in order
for f in ~/.claude/teams/damascus-forge/inboxes/*.json; do
echo "=== $(basename $f) ==="
cat "$f" | jq -r '.[] | "\(.read)\t\(.type)\t\(.sender // "system")\t\(.content[:80])"'
done
Look for:
read: false — these are undelivered/unreadlead.json (wrong) instead of team-lead.json (correct)Lead skips spawning teammates (F-008) — Explorers, scribe, or reviewers never created
The Lead must spawn all teammates during the Setup Phase before entering the Round Flow. If it jumps directly to sending PLANNING PHASE to the planner without spawning explorers, the planner has no one to assign work to and stalls.
Diagnosis:
# Check which inboxes exist — missing inboxes = missing teammates
ls ~/.claude/teams/damascus-forge/inboxes/
# Expected for a healthy session: team-lead.json, planner.json, explorer-1.json,
# explorer-2.json (or more), scribe.json, reviewer-claude.json, etc.
# If only team-lead.json + planner.json exist → Setup Phase was skipped
Malformed task message — even if teammates are spawned, the PLANNING PHASE message to the planner must include the explorer list, mode, and ExitPlanMode reinforcement. Compare the actual message against the format in skills/ForgeTeamOrchestrator/references/round-flow.md.
Fix: Delete team and restart. Verify the Lead follows ForgeTeamOrchestrator's Setup Phase (spawn all teammates) before entering Round 1.
The 'lead' vs 'team-lead' Bug — CRITICAL, confirmed in 9+ sessions
The Lead teammate is spawned with name: "team-lead". Its inbox file is team-lead.json. However, it's natural to use recipient: "lead" in SendMessage — this creates a separate lead.json file that Lead never reads.
Diagnosis:
# If this file exists, you have the routing bug
ls ~/.claude/teams/damascus-forge/inboxes/lead.json
# Check for unread messages in wrong inbox
cat ~/.claude/teams/damascus-forge/inboxes/lead.json | jq 'length'
Fix: All teammate prompts must use recipient: "team-lead" (not "lead"). Check skills/ForgeTeamOrchestrator/references/teammate-prompts.md — every SendMessage example must specify recipient: "team-lead".
ExitPlanMode not mentioned in prompt → plan mode never works
100% correlation across 9 sessions: if the planner's spawn prompt does not explicitly mention ExitPlanMode, the planner never submits a plan. The mode: "plan" on the Agent tool sets planModeRequired: true, but the planner needs to know it must call ExitPlanMode.
Diagnosis:
# Check if planner has been in plan mode
cat ~/.claude/teams/damascus-forge/inboxes/team-lead.json | jq '.[] | select(.type == "plan_approval_request")'
If no plan_approval_request exists → planner never called ExitPlanMode.
Fix: Ensure the planner prompt contains:
Planner waiting for explorers that finished
The planner prompt says "wait until all have reported." If an explorer sends findings but the planner doesn't receive them, it waits indefinitely.
Diagnosis:
# Check explorer messages to planner
cat ~/.claude/teams/damascus-forge/inboxes/planner.json | jq '.[] | select(.sender | startswith("explorer"))'
Planner stuck in revision loop (Round 2+)
On Round 2+, the planner must call EnterPlanMode before ExitPlanMode. If it doesn't, it can't submit the revised plan.
Diagnosis: Check if planner received the revision message from team-lead and whether a plan_approval_request was generated.
Scribe not writing
The scribe is the ONLY agent with write access (subagent_type: "general-purpose"). If it's stuck, the file won't be written.
Diagnosis:
# Check if scribe received instructions
cat ~/.claude/teams/damascus-forge/inboxes/scribe.json | jq '.[] | select(.read == false)'
# Check if scribe confirmed write
cat ~/.claude/teams/damascus-forge/inboxes/team-lead.json | jq '.[] | select(.sender == "scribe")'
Never use multiple planners. When a planner sends a DONE message and then receives any new message, it reactivates and may send conflicting plans. This was solved by using a single Planner + N Explorers architecture. If you see multiple planner-N teammates, the architecture is wrong.
See references/diagnostic-commands.md for copy-paste diagnostic commands.
| Problem | Recovery |
|---|---|
| Wrong inbox routing | Fix prompts, restart session |
| ExitPlanMode not called | Cannot fix mid-session — restart with corrected prompt |
| Setup Phase skipped | TeamDelete("damascus-forge"), restart — verify Lead spawns all teammates before Round 1 |
| Malformed task message | Restart — check message format against round-flow.md |
| Single teammate stuck | Send a nudge message via SendMessage |
| Team state corrupted | TeamDelete("damascus-forge"), restart session |
| Max rounds reached but not approved | Normal behavior — report final verdict to user |