@arthai/agents 1.0.4 → 1.0.6

package/dist/plugins/prime/commands/planning.md

@@ -58,7 +58,86 @@ Map user choices:
 
 Store the resolved mode as `DEBATE_MODE` (values: `lite`, `fast`, `full`).
 
-### 3. Codebase Scan
+### 3. Phase 0: Spec Generation (before debate)
+
+Before any debate rounds, the PM generates a **spec doc** that becomes the foundation for all subsequent work. This ensures user stories and edge cases are defined BEFORE architecture decisions.
+
+**Create the specs directory:**
+```bash
+mkdir -p .claude/specs
+```
+
+**Spawn PM agent (subagent_type="product-manager", model="sonnet") for spec generation only:**
+
+Prompt:
+```
+You are a Product Manager generating a spec doc for the feature "{feature-name}".
+
+Feature brief: {FEATURE_BRIEF}
+
+Generate a spec doc with these sections:
+
+## User Stories
+Write 3-7 user stories covering the happy path and key error states.
+Format: "As a [user type], I want [action], so that [outcome]"
+Each story must have:
+- **Story ID**: US-1, US-2, etc.
+- **Priority**: P0 (must-have for launch) or P1 (important but deferrable)
+- **Acceptance**: specific testable condition that proves this story is done
+
+Example:
+  US-1 [P0]: As a new developer, I want to install the toolkit with one command,
+  so that I can start using it without manual configuration.
+  Acceptance: `npx @arthai/agents install forge .` succeeds and skills are available.
+
+## User Journey
+Step-by-step flow from the user's first interaction to completion.
+Include:
+- **Happy path**: numbered steps (1. User does X → 2. System responds Y → ...)
+- **Decision points**: where the user makes a choice (mark with ◆)
+- **Error branches**: where things can go wrong (mark with ✗ and show recovery path)
+
+Format as a text flowchart:
+```
+1. User discovers feature
+2. User does [action]
+   ◆ Decision: [choice A] or [choice B]
+   → Choice A: proceed to step 3
+   → Choice B: proceed to step 5
+3. System responds with [result]
+   ✗ Error: [what went wrong] → Recovery: [how to fix]
+4. ...
+```
+
+## Edge Cases
+Structured list of what can go wrong. For each:
+- **ID**: EC-1, EC-2, etc.
+- **Scenario**: what triggers this edge case
+- **Expected behavior**: what should happen (not crash, not hang)
+- **Severity**: Critical (blocks user) / High (degrades experience) / Medium (inconvenience)
+- **Linked story**: which user story this edge case relates to
+
+## Success Criteria
+Measurable outcomes tied to user stories. These become the acceptance criteria
+that /implement and /qa use to validate the implementation.
+- Each criterion references a story ID
+- Each criterion is binary: pass or fail, no subjective judgment
+```
+
+**Write the output to `.claude/specs/{feature-name}.md`** with this frontmatter:
+
+```markdown
+---
+feature: {feature-name}
+generated: {ISO date}
+stories: {count}
+edge_cases: {count}
+---
+```
+
+**Store the spec content as `FEATURE_SPEC`** — this is injected into the shared context block for all debate participants.
+
+### 4. Codebase Scan
 
 Spawn an `explore-light` subagent (model: haiku) to scan for relevant files:
 
@@ -68,7 +147,7 @@ prompt: "For a feature called '{feature-name}', find: (1) related backend routes
 
 Store the result as `CODEBASE_CONTEXT`.
 
-### 4. Create Team + Tasks
+### 5. Create Team + Tasks
 
 Create team: `planning-{feature-name}`
 
@@ -76,12 +155,13 @@ Create these tasks:
 
 | Task | Owner | Subject |
 |------|-------|---------|
-| 1 | product-manager | Define product spec for {feature-name} |
+| 0 | product-manager | Generate spec doc for {feature-name} (Phase 0 — already done above) |
+| 1 | product-manager | Define product scope for {feature-name} (uses spec as input) |
 | 2 | architect | Design technical plan for {feature-name} |
 | 3 (if --design) | design-thinker | Create design brief for {feature-name} |
 | 4 (if not --lite) | devils-advocate | Challenge scope and feasibility for {feature-name} |
 
-### 5. Build Shared Context Block
+### 6. Build Shared Context Block
 
 Compose this block to inject into every teammate's spawn prompt:
 
@@ -95,6 +175,11 @@ Auth: {AUTH_APPROACH}
 ## Feature: {feature-name}
 {FEATURE_BRIEF}
 
+## Spec Doc (from Phase 0)
+{FEATURE_SPEC}
+
+(Full spec at: .claude/specs/{feature-name}.md)
+
 ## Relevant Codebase
 {CODEBASE_CONTEXT}
 
@@ -114,13 +199,13 @@ This planning session runs in {DEBATE_MODE} mode.
 - If DA recommends KILL and user overrides, record as USER OVERRIDE in the plan.
 ```
 
-### 6. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
+### 7. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
 
 Spawn all teammates in a **single message** with multiple Task tool calls:
 
 **Always spawn:**
 - **product-manager** (subagent_type="product-manager", model="opus")
-  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'.\n\nIn Round 1, you LEAD with your scope claim. Format your must-haves as:\n  [M1] requirement — BECAUSE reason\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver user value, is it over-engineered, what is the time-to-value?\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence."
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'. You generated the spec doc in Phase 0 — your user stories and edge cases are in the shared context above. Use them as the foundation for your scope claim.\n\nIn Round 1, you LEAD with your scope claim. Each must-have should trace to one or more user stories (reference by ID, e.g., 'US-1, US-3'). Format your must-haves as:\n  [M1] requirement — BECAUSE reason (traces to US-X)\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver the user journey as specified? Is it over-engineered? What is the time-to-value? Reference edge cases the approach doesn't handle.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Reference user stories to justify why a must-have cannot be cut."
 
 - **architect** (subagent_type="architect", model="opus")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the Architect. Own the 'how'.\n\nIn Round 1, you COUNTER the PM's scope from a feasibility lens. Challenge feasibility, flag hidden complexity, identify scope creep vectors, propose a counter-scope.\n\nIn Round 2, you LEAD with your technical approach: API contract, DB changes, architecture decision + WHY, task breakdown with S/M/L/XL estimates, implementation cost, dependencies, risks.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Keep it simple for early-stage. Push back on scope that doesn't match the development stage."
@@ -140,7 +225,7 @@ Spawn all teammates in a **single message** with multiple Task tool calls:
 - **gtm-expert** (subagent_type="gtm-expert", model="sonnet")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the GTM Expert. Own distribution and launch strategy. Advise on positioning, viral mechanics, and launch sequencing. Challenge the team on how users will discover and adopt this feature. Your output feeds into Round 3 as additional evidence for the devil's advocate."
 
-### 7. Structured Debate Protocol
+### 8. Structured Debate Protocol
 
 Facilitate the following rounds in sequence. Each phase completes before the next begins.
 
@@ -279,7 +364,7 @@ Each matched item is flagged as a RISK NOTE in the plan.
 
 ---
 
-### 8. Convergence Logic
+### 9. Convergence Logic
 
 **Plan is APPROVED when ALL of the following are true after all applicable rounds complete:**
 - Rounds 1 and 2 have zero UNRESOLVED items
@@ -296,7 +381,7 @@ If user overrides a KILL recommendation, record as `USER OVERRIDE` in the plan.
 
 In lite and fast modes, skip convergence checks for rounds that were not run. Apply only the checks applicable to completed rounds.
 
-### 9. Scope Lock
+### 10. Scope Lock
 
 After convergence, compute a `scope_hash`:
 - Concatenate all locked MUST-HAVE strings from Round 1 in order
@@ -305,7 +390,7 @@ After convergence, compute a `scope_hash`:
 
 When `/implement` loads the plan, it can verify the hash against the locked must-haves to detect tampering.
 
-### 10. Write Plan File + Present to User
+### 11. Write Plan File + Present to User
 
 Synthesize teammate outputs into a structured plan and **write it to `.claude/plans/{feature-name}.md`** using the Write tool. This file is read by `/implement` to auto-configure the implementation team.
 
@@ -317,6 +402,7 @@ feature: {feature-name}
 debate_mode: {DEBATE_MODE}
 scope_hash: {SHA-256 of locked must-haves}
 da_confidence: {HIGH|MEDIUM|LOW|N/A}
+spec: specs/{feature-name}.md
 layers:
   - frontend  # include if ANY frontend tasks exist
   - backend   # include if ANY backend tasks exist
@@ -324,6 +410,9 @@ layers:
 
 # Planning Summary: {feature-name}
 
+## Spec Reference
+See `.claude/specs/{feature-name}.md` for user stories, user journey, edge cases, and success criteria.
+
 ## Problem & User Segment (from PM)
 ...
 
@@ -394,7 +483,7 @@ layers:
 
 Present the plan to the user for review.
 
-### 11. Cleanup
+### 12. Cleanup
 
 After user reviews the plan:
 - Send shutdown_request to all teammates.

package/dist/plugins/prime/commands/qa-incident.md

@@ -40,6 +40,60 @@ affected_files:
 
 4. **Confirm to user**: "Incident logged. Next `/qa` run will generate a regression test targeting this issue."
 
+## Auto-Logging from Escalation (Circuit Breaker Resolution)
+
+When an agent resolves a stuck situation (circuit breaker was tripped, then the issue was fixed),
+the resolution should be logged automatically. This enables future agents to find the fix
+without repeating the same debugging journey.
+
+**Trigger:** Any workflow that resolves an error after the escalation guard tripped (3+ consecutive failures).
+
+**Auto-log format** — create `.claude/qa-knowledge/incidents/{date}-escalation-{slug}.md`:
+
+```markdown
+---
+date: {today YYYY-MM-DD}
+severity: medium
+status: covered
+type: escalation-resolution
+error_signature: {from .claude/.escalation-state.json}
+affected_files:
+  - {files that were modified to fix the issue}
+---
+# Escalation: {brief description of what was stuck}
+
+## Error
+{exact error message that triggered the circuit breaker}
+
+## What Was Tried (failed)
+1. {attempt 1 from escalation state} → {result}
+2. {attempt 2} → {result}
+3. {attempt 3} → {result}
+
+## Root Cause
+{what was actually wrong}
+
+## Fix Applied
+{what change resolved the issue}
+
+## How to Prevent
+{if applicable — what convention or check would catch this earlier}
+
+## Search Keywords
+{error message fragments, file names, command patterns — for future KB searches}
+```
+
+**Also update** `.claude/qa-knowledge/bug-patterns.md` if this represents a new pattern:
+```
+## {Pattern name}
+- **Signature:** {error message or command pattern}
+- **Root cause:** {common reason}
+- **Fix:** {standard resolution}
+- **First seen:** {date}
+```
+
+This closes the learning loop: stuck → escalate → fix → log → future agents find it instantly.
+
 ## If No Description Provided
 
 Ask: "Describe the issue you want to log (e.g., 'admin page crashes when user has no sessions')"

package/dist/plugins/prime/commands/restart.md

@@ -1,68 +1,224 @@
 ---
 name: restart
-description: "Kill and restart local dev servers. Reads service config from CLAUDE.md. Usage: /restart [service]"
+description: "Discover, restart, and validate local dev servers. Auto-detects Docker vs native, checks health, catches crash loops. Usage: /restart <service> <--preflight>"
 ---
 
 # Restart Servers Skill
 
-Kill and restart local dev servers using the configuration from CLAUDE.md.
+Discover how services run, restart them safely, and verify they stay healthy.
 
-## Instructions
+## Phase 1: Discover Services
 
-1. **Read CLAUDE.md** in the project root. Look for the **Local Dev Services** table:
+**First, check CLAUDE.md** for a `Local Dev Services` table:
 
 ```markdown
 ## Local Dev Services
 
-| Service  | Port | Directory | Start Command |
-|----------|------|-----------|---------------|
-| Frontend | 3000 | frontend/ | npm run dev |
-| Backend  | 8000 | backend/  | uvicorn app.main:app --reload --port 8000 |
+| Service  | Type   | Port | Directory | Start Command                         | Health Check    | Depends On |
+|----------|--------|------|-----------|---------------------------------------|-----------------|------------|
+| Postgres | docker | 5432 | —         | docker compose up -d postgres         | pg_isready      | Docker     |
+| Backend  | native | 8000 | backend/  | uvicorn app.main:app --reload         | /api/health     | Postgres   |
+| Frontend | native | 3000 | frontend/ | npm run dev                           | /health         | Backend    |
 ```
 
-If CLAUDE.md doesn't have this section, scan the project:
-- `package.json` scripts → find dev/start commands
-- `requirements.txt` / `pyproject.toml` → look for uvicorn/gunicorn/flask
-- `docker-compose.yml` → extract service ports
-- Common ports: frontend 3000, backend 8000
+**If the table is missing or incomplete, auto-discover** by scanning the repo. Check these files in order:
+
+| File | What to extract |
+|------|-----------------|
+| `docker-compose.yml` / `docker-compose.*.yml` | Service names, ports, images, healthcheck configs, volume mounts. These are **docker** type services. |
+| `Dockerfile` / `Dockerfile.*` | What gets containerized — cross-reference with compose to understand which services are Docker-managed. |
+| `package.json` (root + subdirs) | `scripts.dev`, `scripts.start`, `scripts.serve` → these are **native** Node services. Check `proxy` field for backend port. |
+| `Makefile` / `Procfile` / `Justfile` | Process definitions, often with ports and dependency ordering. |
+| `pyproject.toml` / `requirements.txt` | Python services — look for uvicorn/gunicorn/flask/django in deps. |
+| `.env` / `.env.local` / `.env.example` | Port assignments (`PORT=`, `DATABASE_URL=`, `REDIS_URL=`), required env vars. |
+| `turbo.json` / `nx.json` / `pnpm-workspace.yaml` | Monorepo structure — maps workspace packages to services. |
+
+For each discovered service, determine:
+- **Name**: human-readable (e.g., "Backend API", "Postgres")
+- **Type**: `docker` (managed by docker compose) or `native` (runs directly on host)
+- **Port**: what port it listens on
+- **Directory**: where to `cd` before running the start command
+- **Start command**: exact command to launch it
+- **Health check**: endpoint or command to verify it's running (look for `/health`, `/api/health`, `pg_isready`, `redis-cli ping`, etc.)
+- **Depends on**: other services that must be running first (DB before backend, backend before frontend)
+
+**If discovery is ambiguous, ASK the user.** Specifically ask when:
+- Multiple compose files exist and it's unclear which to use (dev vs prod vs test)
+- A service could be Docker OR native (e.g., Postgres has both a compose entry and a local install)
+- No health check endpoint is obvious — ask what URL or command confirms the service is healthy
+- Port conflicts or unusual port assignments are detected
+- You find services but can't determine the dependency order
+
+Present what you found and ask for confirmation:
+```
+Found 3 services:
+  1. Postgres (docker, port 5432) — via docker-compose.yml
+  2. Backend (native, port 8000) — via backend/pyproject.toml
+  3. Frontend (native, port 3000) — via frontend/package.json
+
+Dependencies: Frontend → Backend → Postgres
+
+Health checks:
+  - Postgres: pg_isready -h localhost -p 5432
+  - Backend: curl localhost:8000/api/health
+  - Frontend: curl localhost:3000
+
+Does this look right? Any corrections?
+```
+
+After confirmation (or if CLAUDE.md table already exists), proceed to Phase 2.
+
+**Update CLAUDE.md**: If services were auto-discovered and the user confirmed, write/update the `Local Dev Services` table in CLAUDE.md so future runs skip discovery.
 
-2. **Kill existing processes** for the target service(s):
+## Phase 2: Pre-flight Validation
 
+Before touching any running processes, validate the environment is ready:
+
+### 2a. Docker check (if any service type is `docker`)
+```bash
+# Is Docker daemon running?
+docker info > /dev/null 2>&1 && echo "Docker: OK" || echo "Docker: NOT RUNNING"
+```
+If Docker is not running, **stop and tell the user**. Don't proceed.
+
+### 2b. Dependency check (for native services)
 ```bash
-# Kill by port
+# Node services — are node_modules installed?
+[ -d "<directory>/node_modules" ] && echo "node_modules: OK" || echo "node_modules: MISSING — run npm install"
+
+# Python services — is the venv active / deps installed?
+[ -f "<directory>/.venv/bin/python" ] && echo "venv: OK" || echo "venv: MISSING"
+```
+
+### 2c. Environment variables
+```bash
+# Check critical env vars exist (read from .env.example or known requirements)
+[ -f "<directory>/.env" ] || [ -f "<directory>/.env.local" ] && echo "env file: OK" || echo "env file: MISSING"
+```
+
+### 2d. Port availability
+```bash
+# Check if port is already in use by a DIFFERENT process than expected
+lsof -ti:<port> 2>/dev/null
+```
+If a port is occupied by an unexpected process, warn the user before killing it.
+
+### 2e. Pre-flight only mode
+If the user ran `/restart --preflight`, **stop here** and report results. Don't restart anything.
+
+## Phase 3: Restart Services (dependency order)
+
+Restart in dependency order — infrastructure first, then backends, then frontends.
+
+### 3a. Stop services (reverse dependency order)
+```bash
+# For native services — kill by port
 lsof -ti:<port> | xargs kill -9 2>/dev/null
 
+# For docker services — stop the specific service
+docker compose stop <service_name>
+
 # Wait for ports to free
 sleep 2
-```
 
-3. **Start each server** in background using the configured start command:
+# Verify port is actually free
+lsof -ti:<port> 2>/dev/null && echo "WARNING: port <port> still occupied" || echo "Port <port>: free"
+```
 
+### 3b. Start services (dependency order)
 ```bash
-# Run in background
-<start_command> &
+# Docker services first
+docker compose up -d <service_name>
+
+# Then native services — run in background
+cd <directory> && <start_command>
 ```
 
-Use `run_in_background: true` on the Bash tool.
+Use `run_in_background: true` on the Bash tool for native services.
+
+**Wait between dependency layers** — don't start the backend until the DB health check passes. Don't start the frontend until the backend health check passes.
+
+## Phase 4: Post-restart Health Validation
+
+This is the critical phase. A single health check is not enough — services can start and then crash seconds later.
 
-4. **Health check** after startup:
+### 4a. Initial health check (per service, in dependency order)
 
 ```bash
-# Check each service
-curl -sf http://localhost:<port>/health > /dev/null 2>&1 && echo "<service>:UP" || echo "<service>:DOWN"
+# HTTP services
+curl -sf http://localhost:<port><health_path> > /dev/null 2>&1 && echo "<service>: UP" || echo "<service>: DOWN"
+
+# Postgres
+pg_isready -h localhost -p <port> 2>/dev/null && echo "Postgres: UP" || echo "Postgres: DOWN"
+
+# Redis
+redis-cli -p <port> ping 2>/dev/null | grep -q PONG && echo "Redis: UP" || echo "Redis: DOWN"
+
+# Docker services
+docker compose ps <service_name> --format '{{.Status}}' | grep -q "Up" && echo "<service>: UP" || echo "<service>: DOWN"
+```
+
+### 4b. Crash loop detection (wait 8 seconds, check again)
+
+```bash
+sleep 8
+
+# Re-check each service
+curl -sf http://localhost:<port><health_path> > /dev/null 2>&1 && echo "<service>: STABLE" || echo "<service>: CRASHED"
+
+# For native services — is the process still running?
+lsof -ti:<port> > /dev/null 2>&1 && echo "<service> process: alive" || echo "<service> process: GONE"
 ```
 
-5. **Report** status of all servers.
+If a service is down on the second check:
+1. **Check logs** — read the last 30 lines of output for error messages
+2. **Report the failure clearly** with the error
+3. **Do NOT retry automatically** — tell the user what went wrong
+
+### 4c. Final status report
+
+```
+✅ Restart complete
+
+| Service  | Type   | Port | Status  |
+|----------|--------|------|---------|
+| Postgres | docker | 5432 | STABLE  |
+| Backend  | native | 8000 | STABLE  |
+| Frontend | native | 3000 | STABLE  |
+
+All services healthy after 10s stability check.
+```
+
+Or if something failed:
+
+```
+⚠️ Restart partial — 1 service unhealthy
+
+| Service  | Type   | Port | Status  |
+|----------|--------|------|---------|
+| Postgres | docker | 5432 | STABLE  |
+| Backend  | native | 8000 | CRASHED |
+| Frontend | native | 3000 | SKIPPED |
+
+Backend crashed after startup. Last error:
+  ModuleNotFoundError: No module named 'sqlalchemy'
+
+Fix: Run `pip install -r requirements.txt` in backend/ and retry.
+Frontend was skipped because it depends on Backend.
+```
 
 ## Argument Patterns
 
 | User Input | Action |
 |-----------|--------|
-| `/restart` (no args) | Kill and restart all configured servers |
-| `/restart backend` | Kill and restart only the backend service |
-| `/restart frontend` | Kill and restart only the frontend service |
-| `/restart <service>` | Kill and restart the named service |
+| `/restart` (no args) | Discover → validate → restart all services |
+| `/restart backend` | Restart only the named service (and its dependencies if they're down) |
+| `/restart --preflight` | Discover and validate only — don't restart anything |
 
-## If CLAUDE.md Is Missing Service Config
+## Key Principles
 
-Report: "No Local Dev Services table found in CLAUDE.md. Add a table with Service, Port, Directory, and Start Command columns. Or specify the services manually."
+1. **Never guess** — if you can't determine how a service runs, ask
+2. **Dependency order matters** — always start infra → backend → frontend
+3. **One health check isn't enough** — check twice with a gap to catch crash loops
+4. **Report errors with context** — show the actual log output, not just "DOWN"
+5. **Don't retry blindly** — if a service crashes, diagnose and report, don't loop