@arthai/agents 1.0.0

package/skills/implement/SKILL.md

@@ -0,0 +1,532 @@
+---
+name: implement
+description: "Spin up an implementation team from a plan. Usage: /implement <feature-name> [--frontend-only] [--backend-only] [--no-redteam] [--redteam-once] [--redteam-strict]"
+user-invocable: true
+arguments: "<feature-name> <--frontend-only> <--backend-only> <--no-redteam> <--redteam-once> <--redteam-strict>"
+---
+
+# Implementation Team Skill
+
+Automates the implementation team workflow into a single command.
+
+## Argument Parsing
+
+- `feature-name`: Required. Kebab-case name (used in team name `impl-{feature-name}`).
+- `--frontend-only`: Override. Force frontend-only even if plan says both.
+- `--backend-only`: Override. Force backend-only even if plan says both.
+- `--no-redteam`: Skip red team entirely (Fast mode — build only).
+- `--redteam-once`: Run red team once at end only (Guarded mode — balanced).
+- `--redteam-strict`: Block on any unresolved HIGH finding (stricter than default which only blocks on CRITICAL).
+
+If no feature name is provided, use AskUserQuestion to get it.
+
+## Execution Steps
+
+### 1. Load the Plan
+
+**First**, check for a plan file at `.claude/plans/{feature-name}.md` (written by `/planning`).
+
+If the plan file exists:
+- Read it with the Read tool.
+- Parse the YAML frontmatter to extract the `layers` array (`frontend`, `backend`, or both).
+- Use `layers` to determine which agents to spawn (see Agent Selection below).
+- Use the full file content as `PLAN`.
+
+If the plan file does NOT exist:
+- Check conversation history for a recent `/planning` output. If found, use it as `PLAN` and infer layers from task breakdown.
+- If neither exists, ask the user with AskUserQuestion:
+  "Paste or describe the implementation plan — include: (1) what to build, (2) API contract (if any), (3) task breakdown (frontend vs backend tasks), (4) acceptance criteria."
+  Then infer layers from the user's response.
+
+Store as `PLAN`.
+
+### 1b. Mode Selection (Red Team Trade-Off)
+
+**If a red team flag was passed on the CLI** (`--no-redteam`, `--redteam-once`, or `--redteam-strict`), skip this prompt and use the corresponding mode directly.
+
+**Otherwise**, present the following prompt via AskUserQuestion:
+
+```
+Implementation mode:
+  [1] Fast    — build only, no red team (~31x cost, fastest)
+  [2] Guarded — red team once at end (~40x cost, balanced)
+  [3] Strict  — red team per step + cross-examine (~49x cost, most thorough)
+  [auto]      — decide based on plan size and risk
+
+Your pick? [auto]
+```
+
+**Auto-detection logic** (used when user picks `auto` or presses Enter):
+
+1. Count `TASK_COUNT` = total tasks extracted from `PLAN`.
+2. Count `FILE_COUNT` = total distinct files referenced in the plan.
+3. Check `RISK_FLAGS` = plan mentions auth, payments, data migration, security, or PII.
+
+| Condition | Auto Mode |
+|-----------|-----------|
+| `TASK_COUNT < 3` AND `FILE_COUNT < 5` | Fast |
+| `TASK_COUNT < 3` AND `FILE_COUNT >= 5` | Guarded |
+| `TASK_COUNT` between 3 and 9 (inclusive) AND no `RISK_FLAGS` | Guarded |
+| `TASK_COUNT >= 10` OR `RISK_FLAGS` present | Strict |
+
+**Map selection to internal flags:**
+
+| Selection | Internal flag | `BLOCK_ON_HIGH` | Red team behavior |
+|-----------|--------------|-----------------|-------------------|
+| Fast / `--no-redteam` | `REDTEAM_MODE=none` | `false` | Skip Step 5b entirely |
+| Guarded / `--redteam-once` | `REDTEAM_MODE=once` | `false` | Run Step 5b once after all steps complete |
+| Strict / default | `REDTEAM_MODE=strict` | `false` | Run Step 5b after each major step group |
+| `--redteam-strict` | `REDTEAM_MODE=strict` | `true` | Strict + block on any unresolved HIGH |
+
+Store as `REDTEAM_MODE` and `BLOCK_ON_HIGH`.
+
+### Agent Selection
+
+Determine which agents to spawn using this priority:
+
+1. **CLI flags override everything**: `--frontend-only` or `--backend-only` wins.
+2. **Plan file `layers` field**: If no flags, use `layers` from `.claude/plans/{feature-name}.md`.
+3. **Inferred from tasks**: If no plan file, scan the plan text for frontend or backend file paths and task headers.
+4. **Default**: Spawn both frontend and backend if ambiguous.
+
+| layers | Agents spawned |
+|--------|---------------|
+| `[frontend]` | frontend + qa |
+| `[backend]` | backend + qa |
+| `[frontend, backend]` | frontend + backend + qa |
+
+### 2. Parse Tasks from Plan
+
+Extract from `PLAN`:
+- **API_CONTRACT**: Endpoint signatures, request/response shapes (if any)
+- **BACKEND_TASKS**: List of backend tasks (routes, services, models, migrations)
+- **FRONTEND_TASKS**: List of frontend tasks (components, pages, API integration)
+- **ACCEPTANCE_CRITERIA**: What "done" looks like
+
+If tasks aren't clearly split, infer from the plan based on file ownership rules defined in your project structure.
+
+### 3. Create Team + Tasks
+
+Create team: `impl-{feature-name}`
+
+Create one TaskCreate per task extracted from the plan. Tag each with its owner:
+- Backend tasks → owner: `backend`
+- Frontend tasks → owner: `frontend`
+- QA tasks → owner: `qa`
+
+If tasks have dependencies (e.g., frontend needs backend endpoint first), set `addBlockedBy` accordingly.
+
+### 3b. Scan existing patterns with explore-light (cost: 1x Haiku)
+
+Before agents start writing code, understand what patterns already exist:
+
+```
+subagent_type: "explore-light"
+prompt: "Scan the codebase to find existing patterns for:
+1. How routes/endpoints are structured (naming, middleware, validation)
+2. How services/business logic is organized (file structure, naming)
+3. How tests are written (fixture approach, assertion style, file naming)
+4. How similar features were implemented (find the closest existing feature to {feature-name})
+
+Focus on: {BACKEND_DIR} and {FRONTEND_DIR}
+Return: concrete examples with file paths and code snippets."
+```
+
+Include the results in the shared context block below so agents match existing
+patterns instead of inventing new ones. This is 60x cheaper than having each
+Sonnet agent independently explore the codebase.
+
+### 4. Build Shared Context Block
+
+```
+## Project Context
+{PROJECT_NAME} - {PROJECT_DESCRIPTION}
+Stack: {TECH_STACK}
+Stage: {DEVELOPMENT_STAGE}
+Auth: {AUTH_APPROACH}
+
+## Implementation Plan
+{PLAN}
+
+## API Contract
+{API_CONTRACT}
+
+## Acceptance Criteria
+{ACCEPTANCE_CRITERIA}
+
+## Your Team
+You are on team "impl-{feature-name}". Use SendMessage to collaborate.
+Teammates: {list based on flags}
+
+## File Ownership (STRICT)
+- Frontend agent: ONLY modify files in {FRONTEND_DIR}
+- Backend agent: ONLY modify files in {BACKEND_DIR}
+- Violations will be rejected.
+
+## When Done
+Mark your tasks as completed. Notify team lead.
+
+## Red Team Protocol
+After each major implementation step, a red team will challenge your work:
+- red-challenger attacks: "this will break because..."
+- red-reviewer validates against plan: "this doesn't match step N because..."
+
+When you receive a challenge via SendMessage:
+1. If valid: fix the code, reply "FIXED: {what you changed}"
+2. If invalid: reply "DEFENDED: {why not a real issue}"
+3. If partial: reply "ACKNOWLEDGED: {risk accepted because...}"
+
+When you complete a step group, notify team-lead:
+  SendMessage: "Completed: {summary}. Files: {list}. Ready for red team."
+```
+
+### 5. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
+
+Use the Agent Selection result from Step 1 to determine which agents to spawn.
+
+**Spawn if `backend` is in layers:**
+
+The `backend` agent is adaptive — it handles Python, Node.js, Go, Rust, Ruby, Java, Elixir,
+and more. It detects the framework at runtime from project files. Always use it for backend work.
+
+| Signal Found | subagent_type | Notes |
+|-------------|---------------|-------|
+| Any backend code (Python, Node, Go, Rust, Ruby, Java, Elixir) | `python-backend` | The agent is named python-backend in Claude Code's registry but handles ALL backends. It reads project files to detect the actual framework and adapts. |
+| `.claude/project-profile.md` exists with backend info | `python-backend` | Agent reads the profile for pre-detected framework and conventions |
+| Unknown / ambiguous | `python-backend` | Agent will detect at runtime |
+
+Check `.claude/project-profile.md` first (if /calibrate has run). Otherwise the agent auto-detects from project files.
+
+- **backend** (subagent_type="{detected-type}", model="sonnet", name="backend")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the Backend engineer. Implement your assigned tasks. Share endpoint signatures with the frontend teammate via SendMessage BEFORE implementing so they can build against the contract. Run linters and type checkers before marking tasks done. Only modify files in {BACKEND_DIR}."
+
+**Spawn if `frontend` is in layers:**
+- **frontend** (subagent_type="frontend", model="sonnet", name="frontend")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the Frontend engineer. Implement your assigned tasks. If you depend on backend endpoints, wait for the backend teammate to share the API contract via SendMessage. Run type checkers and linters before marking tasks done. Only modify files in {FRONTEND_DIR}."
+
+**Always spawn:**
+- **qa** (subagent_type="qa", model="sonnet", name="qa")
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are QA. Your job: (1) Review backend and frontend implementations as they complete. (2) Ask teammates 'why did you do X?' when something looks wrong. (3) Run validation checks (linters, type checkers, build commands). (4) Report issues back to the responsible teammate. (5) Mark your tasks done when all checks pass. Do NOT write code — only review and validate."
+
+### 5b. Red Team Phase
+
+**Skip this entire step if `REDTEAM_MODE=none`.**
+
+**Trigger:** A developer sends a SendMessage with "step complete" (or the implementation reaches the end of all steps if `REDTEAM_MODE=once`). For `REDTEAM_MODE=once`: ignore individual "step complete" messages and only trigger Step 5b after ALL implementation steps are done.
+
+#### 5b.1: Compute Diff
+
+Run `git diff` to capture all changes since the last red team review (or since implementation started if this is the first cycle). Store as `STEP_DIFF`.
+
+Track `REDTEAM_CYCLE` (starts at 1, increments after each cycle). Maximum 2 cycles — after cycle 2, remaining HIGHs become warnings rather than blockers.
+
+#### 5b.2: Spawn Red Team Agents (parallel)
+
+Spawn both agents in a single message:
+
+**red-challenger** (subagent_type: "qa-challenger", model: "sonnet", name: "red-challenger"):
+
+```
+Prompt:
+You are a security and reliability adversary. Your job is to break this implementation
+before it reaches production.
+
+## Step Diff
+{STEP_DIFF}
+
+## Implementation Plan
+{PLAN}
+
+## Your Task
+Generate 3-5 attack scenarios targeting the code changes above. For each:
+
+1. Describe the attack vector or failure mode concretely.
+2. Show the exact input, state, or sequence that triggers it.
+3. Classify severity: CRITICAL / HIGH / MEDIUM / LOW
+   - CRITICAL: data loss, auth bypass, security breach, production outage
+   - HIGH: wrong behavior under realistic conditions, data corruption, broken contract
+   - MEDIUM: edge case failures, degraded UX, performance issue
+   - LOW: cosmetic, unlikely edge case, minor inconsistency
+4. Name the file(s) and line(s) affected.
+
+Format each finding as:
+ATTACK-{N} [{SEVERITY}]: {title}
+Trigger: {exact scenario}
+Impact: {what breaks}
+Location: {file:line}
+
+After generating all attacks, send each HIGH and CRITICAL finding directly to the
+responsible developer via SendMessage with subject "RED TEAM ATTACK".
+Then send your full report to team-lead via SendMessage with subject "RED TEAM REPORT".
+```
+
+**red-reviewer** (subagent_type: "code-reviewer", model: "sonnet", name: "red-reviewer"):
+
+```
+Prompt:
+You are a plan compliance reviewer. Your job is to verify the implementation matches
+what was planned — no more, no less.
+
+## Step Diff
+{STEP_DIFF}
+
+## Implementation Plan
+{PLAN}
+
+## API Contract
+{API_CONTRACT}
+
+## Acceptance Criteria
+{ACCEPTANCE_CRITERIA}
+
+## Your Task
+Validate the implementation against the plan:
+
+1. Every planned task has corresponding code — flag any gaps.
+2. API contract is honoured — method, path, request/response shape, status codes.
+3. Acceptance criteria are satisfiable by the code as written.
+4. No scope creep — no features added beyond the plan.
+5. No scope gaps — no planned features omitted without explanation.
+
+For each finding, classify: CRITICAL / HIGH / MEDIUM / LOW (same scale as attacker).
+
+Format each finding as:
+REVIEW-{N} [{SEVERITY}]: {title}
+Expected: {what the plan required}
+Actual: {what the code does}
+Location: {file:line or "missing"}
+
+Send HIGH and CRITICAL findings to the responsible developer via SendMessage
+with subject "PLAN COMPLIANCE FINDING".
+Send your full report to team-lead via SendMessage with subject "REVIEW REPORT".
+```
+
+#### 5b.3: Challenge-Defend Cycle
+
+Developers must reply to each ATTACK and FINDING via SendMessage. Valid responses:
+
+- `FIXED: {what you changed}` — code was updated; red team issue is resolved.
+- `DEFENDED: {why not a real issue}` — explains why the attack does not apply.
+- `ACKNOWLEDGED: {risk accepted because...}` — known risk, deliberately not fixed.
+
+Track unresolved items: an item is unresolved if the developer has not replied FIXED, DEFENDED, or ACKNOWLEDGED.
+
+If a developer completes their next step with 2 or more unresolved items from the previous cycle, the orchestrator sends them a blocking SendMessage: "You have {N} unresolved red team items from the last cycle. Resolve them before proceeding."
+
+#### 5b.4: Verdict Gate
+
+After all developer responses are received (or timeout), compute:
+
+```
+unresolved_criticals = items where severity=CRITICAL AND response != FIXED
+unresolved_highs     = items where severity=HIGH AND response not in (FIXED, DEFENDED)
+
+block_threshold = 1 if BLOCK_ON_HIGH else 3
+```
+
+| Condition | Verdict | Action |
+|-----------|---------|--------|
+| `unresolved_criticals > 0` | BLOCK | Pause. Escalate to user: "Red team found {N} unresolved CRITICAL(s). [fix / override / abort]"<br>- fix: Send unresolved CRITICALs back to developers for another fix attempt<br>- override: Accept risks, mark all unresolved CRITICALs as ACKNOWLEDGED, proceed to PASS<br>- abort: Stop implementation, present findings to user for manual review |
+| `unresolved_highs >= block_threshold` | FIX | Send findings back to developer. Allow up to 2 cycles total. |
+| Otherwise | PASS | Continue to next step or final QA. |
+
+If `REDTEAM_CYCLE >= 2` and the verdict would be FIX: downgrade to PASS with warnings — remaining HIGHs are logged but do not block.
+
+#### 5b.5: Shutdown Red Team
+
+After PASS (or user override of BLOCK):
+- Send shutdown_request to red-challenger and red-reviewer.
+- Store cycle results as `REDTEAM_RESULTS[cycle_N]` for the final report.
+- Increment `REDTEAM_CYCLE`.
+
+### 6. Monitor + Coordinate
+
+- Watch TaskList for progress.
+- If backend finishes API endpoints, nudge frontend to unblock.
+- If a teammate is stuck, relay context from the other teammate.
+- If teammates disagree on API contract, make a decision.
+- When a developer sends "step complete" via SendMessage, trigger Step 5b (unless `REDTEAM_MODE=none`).
+- If `REDTEAM_MODE=once`, defer Step 5b until all implementation steps are complete.
+- Track `REDTEAM_CYCLE`. If a BLOCK verdict is returned from Step 5b.4, pause all progress and escalate to the user before continuing.
+
+### 7. Cleanup Implementation Team
+
+- Send shutdown_request to all teammates.
+- TeamDelete after all confirm.
+- Report what was built:
+
+```markdown
+# Implementation Complete: {feature-name}
+
+## What was built
+- Backend: {summary}
+- Frontend: {summary}
+
+## Files Changed
+{list}
+
+## Red Team Summary
+- Mode: {Fast / Guarded / Strict}
+- Challenges raised: {N}
+- Critical found and fixed: {N}
+- Plan compliance gaps fixed: {N}
+- Defenses accepted (false positives): {N}
+- Cycles: {N}
+- Key fixes: {list of FIXED items, or "none" if REDTEAM_MODE=none}
+```
+
+Omit the Red Team Summary section entirely if `REDTEAM_MODE=none`.
+
+Then proceed directly to Step 8 (Post-Implementation Workflow).
+
+### 8. Post-Implementation Workflow
+
+This is the coordinated handoff from implementation to PR. No redundant QA runs —
+each step has a distinct purpose.
+
+#### 8.1: Ask user what QA level to run
+
+Use AskUserQuestion:
+
+```
+Implementation complete. What level of QA should I run?
+
+  [1] commit  — targeted checks on changed files only (~1-3 min)
+  [2] full    — comprehensive checks across full codebase (~10-20 min)
+  [3] staging — deploy verification against staging environment
+  [4] skip    — I'll test manually, skip automated QA
+
+Default: commit
+```
+
+Store the choice as `QA_LEVEL`.
+
+#### 8.2: Run /qa at chosen level
+
+If user chose `skip`, skip to Step 8.3.
+
+Otherwise, invoke `/qa {QA_LEVEL}` via the Skill tool:
+
+1. Run `/qa {QA_LEVEL}`
+2. **If QA fails** — show failures. Ask user: "Fix these issues? [yes / skip / abort]"
+   - `yes` → fix the issues (re-enter implementation if needed), then re-run QA
+   - `skip` → proceed anyway (user takes responsibility)
+   - `abort` → stop the workflow
+3. **If QA passes** — continue to Step 8.3
+
+Record QA results as `QA_RESULT` for the PR body.
+
+#### 8.3: Restart local servers and ask user to test
+
+**Check if local services exist** — read CLAUDE.md `## Local Dev Services` table.
+
+If the table exists and has entries:
+
+```bash
+# Restart services using the Start Command from the Local Dev Services table
+# For each service row in the table:
+#   {Start Command} from {Directory}
+
+# Example:
+# cd frontend && npm run dev &
+# cd backend && source .venv/bin/activate && uvicorn app.main:app --reload &
+```
+
+If the project has a `/restart` skill configured, invoke `/restart` instead.
+
+After restart (or if no local services), ask the user:
+
+```
+Local servers restarted. Please test the changes manually.
+
+When you're done testing, let me know:
+  [ready]  — looks good, proceed to PR
+  [issues] — found problems (describe them)
+```
+
+**If user says `issues`**: Address the problems, re-run QA at `commit` level only
+(since the scope is narrow), then ask again.
+
+**If user says `ready`**: Proceed to Step 8.4.
+
+#### 8.4: Create PR via /pr --skip-qa
+
+Invoke `/pr --skip-qa` — this tells /pr to skip its own `/qa commit` step since QA
+already ran in Step 8.2. /pr will only:
+
+1. Run a **quick sanity check** (lint + type check — 10 seconds, not a full QA run)
+2. Stage and commit changes
+3. Find or create GitHub issue
+4. Push to feature branch
+5. Open PR with:
+   - Summary of changes
+   - QA results from Step 8.2 (passed to /pr)
+   - User testing confirmation from Step 8.3
+6. Return PR URL
+
+#### 8.5: Ask what's next
+
+After PR is created:
+
+```
+PR #{number} created: {url}
+
+What's next?
+  [1] Review another PR — /review-pr
+  [2] Start next feature — /planning <feature>
+  [3] Pick up an issue — /fix #N
+  [4] See project status — /onboard
+  [5] Done for now
+```
+
+If autopilot is active, skip this prompt and continue the autopilot loop.
+
+## Cost Optimization
+
+| Role | Model | Rationale |
+|------|-------|-----------|
+| backend | sonnet | Code generation, bounded scope |
+| frontend | sonnet | Code generation, bounded scope |
+| qa | sonnet | Needs reasoning for review + orchestrating test agents |
+| red-challenger | sonnet | Adversarial reasoning, needs depth |
+| red-reviewer | sonnet | Plan compliance analysis, needs reasoning |
+
+### Mode Cost Estimates
+
+| Mode | Flag | Approx. Cost | Red Team |
+|------|------|-------------|----------|
+| Fast | `--no-redteam` | ~31x | None — build only |
+| Guarded | `--redteam-once` | ~40x | +9x for one end-of-run cycle |
+| Strict | (default) | ~49x | +18x for per-step red team (typical 2-step build) |
+| Strict + block on HIGH | `--redteam-strict` | ~49x | Same as Strict, stricter verdict gate |
+
+## Common Patterns
+
+### Frontend-only change (e.g., UI fix)
+```
+/implement fix-component --frontend-only
+```
+Spawns: frontend + qa only. No backend agent.
+
+### Backend-only change (e.g., new endpoint)
+```
+/implement add-api-endpoint --backend-only
+```
+Spawns: backend + qa only. No frontend agent.
+
+### Full-stack feature
+```
+/implement new-feature
+```
+Spawns: frontend + backend + qa. Backend shares API contract first.
+
+## Continuation (Workflow Chaining)
+
+After Step 8.5:
+
+**If autopilot is active** (check `.claude/.workflow-state.json` mode == "autopilot"):
+- Update workflow state: `phase: "awaiting_merge"`, `pr_number: N`
+- **STOP HERE** — never merge without human approval
+
+**If guided mode** (no autopilot or mode != "autopilot"):
+- Wait for user's choice from Step 8.5 and route accordingly