@arthai/agents 1.0.0

package/skills/autopilot/SKILL.md

@@ -0,0 +1,425 @@
+---
+name: autopilot
+description: "Autonomous work loop — picks up issues, implements, QAs, PRs. Stops for merge approval."
+user-invocable: true
+arguments: "<issue_number> <--dry-run>"
+---
+
+# Autopilot Skill — Autonomous Junior Engineer
+
+Runs a continuous work loop: assess → plan → implement → QA → PR → wait for merge → repeat.
+Acts like a junior engineer — takes initiative on scoped work, escalates when unsure,
+never merges without human approval.
+
+## Arguments
+
+- `issue-number` (optional): Start with a specific issue. If omitted, auto-picks highest priority.
+- `--dry-run` (optional): Show what would be done without doing it. Useful for trust-building.
+
+## Workflow State
+
+All state lives in `.claude/.workflow-state.json`. This file:
+- Persists between turns (triage router reads it to maintain continuity)
+- Tracks current work item, phase, risk, confidence, scope
+- Records session history (what was completed, what's pending)
+
+On first run, create the file. On subsequent runs (after merge, or user says "continue"),
+read the file and resume from the current phase.
+
+### State Schema
+
+```json
+{
+  "mode": "autopilot",
+  "started_at": "ISO timestamp",
+  "current_item": {
+    "type": "issue|pr|bug",
+    "number": 141,
+    "title": "description",
+    "source": "gh-issue|gh-pr|qa-finding|manual"
+  },
+  "risk": {
+    "score": 5,
+    "blast_radius": 1,
+    "reversibility": 1,
+    "confidence": 85,
+    "domain_sensitivity": 2,
+    "reasoning": "why this score"
+  },
+  "phase": "assess|classify|plan|implement|qa|self-review|pr|awaiting_merge|done",
+  "planned_scope": {
+    "files": ["list of expected files"],
+    "layers": ["backend", "frontend"]
+  },
+  "actual_scope": {
+    "files_changed": [],
+    "layers_touched": []
+  },
+  "attempts": {
+    "qa_fixes": 0,
+    "stuck_turns": 0
+  },
+  "session_summary": {
+    "completed": [{"item": "#141", "pr": 275}],
+    "prs_open": [275],
+    "blocked": [],
+    "issues_filed": []
+  }
+}
+```
+
+## The Loop
+
+### Phase 1: ASSESS
+
+If `current_item` is null or `phase` is "assess":
+
+1. Gather project state (same signals as /onboard but faster — no full briefing):
+
+```bash
+# Run in parallel
+git status --short
+git log --oneline -5
+gh pr list --author @me --json number,title,state,headRefName --limit 10
+gh issue list --assignee @me --json number,title,labels --limit 10
+gh issue list --json number,title,labels,assignees --limit 15
+```
+
+2. Build a priority list using these rules:
+
+**Priority order (highest first):**
+- CI/CD failures on main → fix immediately (blocks everything)
+- PRs with review comments unaddressed → respond/fix (someone is waiting)
+- Issues labeled `bug`, `critical`, `urgent`, `P0`, `security` → fix ASAP
+- Stale PRs (yours, no activity > 5 days) → rebase, re-QA, push
+- Issues assigned to you, oldest first
+- Unassigned issues labeled `P1` or `bug`
+- Unassigned issues, oldest first
+
+3. If a specific `issue-number` was provided as argument, skip priority and use that.
+
+4. Present the choice:
+```
+AUTOPILOT: Assessed project state.
+  Top priority: #141 "Short session credit refund" (bug, assigned to you, 7 days old)
+
+  Next in queue: #162 "Feedback nudge reappears" (bug), #71 "Sentry env vars" (infra)
+
+  Starting work on #141.
+```
+
+5. Update workflow state: `phase: "classify"`, `current_item: {...}`.
+
+### Phase 2: CLASSIFY (Risk Pre-Flight)
+
+Before touching any code, evaluate the work item:
+
+**Read the issue/PR carefully.** Then score each dimension 0-3:
+
+| Dimension | 0 | 1 | 2 | 3 |
+|-----------|---|---|---|---|
+| **Blast radius** | 1 isolated file | 1 feature area | Shared component (auth, API client, billing service) | Infrastructure, deployment, database schema |
+| **Reversibility** | Simple git revert | Revert + minor cleanup | Needs migration or manual data fix to undo | Data loss possible, can't fully undo |
+| **Confidence** | Clear requirements, existing test patterns | Some ambiguity, mostly follows codebase patterns | Novel approach needed, unclear requirements | Don't understand the existing code well enough |
+| **Domain sensitivity** | Docs, tests, UI copy, styling | Feature logic, new endpoints, new components | Auth flows, payment logic, data models, API contracts | Secrets, production DB, CI/CD pipelines, infra config |
+
+**Sum the scores (0-12) and decide:**
+
+| Score | Level | Action |
+|-------|-------|--------|
+| 0-5 | **Proceed** | Work autonomously. No notification needed. |
+| 6-8 | **Proceed with notice** | Tell the user what you're doing and why. Continue unless they object. |
+| 9-10 | **Stop and ask** | Present the risk assessment. Wait for explicit approval. |
+| 11-12 | **Refuse** | Tell the user this requires manual intervention. |
+
+**Automatic escalation triggers (override score):**
+- Confidence below 50 → STOP regardless of score
+- Requires database migration → minimum Level 3 (stop and ask)
+- Touches auth middleware or payment webhooks → minimum Level 3
+- No test suite exists for the area → flag it, write tests first
+- Issue requirements are vague (no acceptance criteria, no reproduction steps) → STOP, ask for clarification
+
+**Write to workflow state:**
+```json
+"risk": {
+  "score": 5,
+  "blast_radius": 1,
+  "reversibility": 1,
+  "confidence": 85,
+  "domain_sensitivity": 2,
+  "reasoning": "Billing-adjacent but no Stripe integration. 3 backend files, existing test patterns."
+}
+```
+
+If proceeding, move to Phase 3. If stopping, present assessment and wait.
+
+### Phase 3: PLAN
+
+**For bug fixes (risk 0-5):**
+Skip formal planning. Read the issue, identify root cause, describe the fix approach in 2-3 sentences.
+Write to workflow state and proceed to Phase 4.
+
+**For bug fixes (risk 6-8):**
+Brief plan: root cause analysis, proposed fix, files to change, potential side effects.
+Share with user as an FYI (don't wait for approval unless risk >= 9).
+
+**For features (any risk):**
+Check if a plan already exists at `.claude/plans/{feature-name}.md`.
+- If yes: read it, verify it's current, use it.
+- If no: create a brief plan. For risk 0-5, write it inline (no team needed).
+  For risk 6+, spawn a `/planning` session and wait for the plan.
+
+**Scope definition (critical for Phase 6 scope guard):**
+After planning, write the expected scope:
+```json
+"planned_scope": {
+  "files": ["backend/app/services/session_service.py", "backend/tests/test_session.py"],
+  "layers": ["backend"]
+}
+```
+
+Update phase to "implement".
+
+### Phase 4: IMPLEMENT
+
+**Spawn the right agents based on plan layers:**
+
+| Layers in plan | Agents to spawn |
+|----------------|----------------|
+| backend only | auto-detect backend agent (Sonnet) — see `/implement` for detection logic |
+| frontend only | frontend (Sonnet) |
+| both | auto-detect backend + frontend (Sonnet each) |
+| infra/deploy | sre (Sonnet) |
+
+**Backend agent detection:** Check CLAUDE.md Tech Stack, then project files (`requirements.txt` → python-backend, `package.json` with backend framework → frontend agent as Node backend, `go.mod`/`Cargo.toml` → general-purpose). Default: python-backend.
+
+**Use agent teams for multi-agent work:**
+1. Create team `autopilot-{item-number}`
+2. Create tasks from the plan
+3. Spawn agents, assign tasks
+4. Monitor progress via TaskList and teammate messages
+
+**For simple fixes (1-3 files, risk 0-3):**
+Skip teams entirely. Use tools directly (Read, Edit, Write, Bash).
+This is faster and cheaper than spawning agents for trivial changes.
+
+**Track actual scope:**
+As files are changed, update `actual_scope` in workflow state.
+
+Update phase to "qa" when implementation is complete.
+
+### Phase 5: QA
+
+Run validation appropriate to the change:
+
+**Minimum (always):**
+- Run the project's test suite (read CLAUDE.md for the command)
+- Run linter
+- Run type checker
+
+**For backend changes:**
+```bash
+cd backend && source .venv/bin/activate && python -m pytest
+cd backend && ruff check .
+```
+
+**For frontend changes:**
+```bash
+cd frontend && npm run lint
+cd frontend && npx tsc --noEmit
+cd frontend && npm test
+```
+
+**If QA fails:**
+1. Analyze the failure. Is it related to your changes?
+2. If yes: fix it (increment `attempts.qa_fixes`).
+3. Re-run QA.
+4. If still failing after 2 fix attempts: **STOP**.
+   - Update workflow state: `phase: "blocked"`
+   - Report: "QA failed after 2 fix attempts. Here's what's failing and why I'm stuck."
+   - Wait for human guidance.
+
+**If QA passes:**
+Update phase to "self-review".
+
+### Phase 6: SELF-REVIEW
+
+Before creating a PR, review your own work. This catches issues QA misses.
+
+**Read the full diff:**
+```bash
+git diff --stat
+git diff
+```
+
+**Check against this list:**
+1. **Scope guard**: Compare `actual_scope.files_changed` vs `planned_scope.files`.
+   - If actual > planned * 1.5: **STOP**. "Scope grew from {N} to {M} files. Review?"
+   - If touching layers not in plan: **STOP**. "Started as backend-only, now touching frontend."
+2. **Hardcoded values**: Any magic numbers, URLs, credentials, API keys?
+3. **Error handling**: Are new code paths handling errors? Especially API calls and DB queries.
+4. **Security**: Any user input flowing into queries or templates without sanitization?
+5. **Test coverage**: Did you write tests for the new code? If not, why?
+6. **Unintended changes**: Files modified that aren't related to the work item?
+
+**Risk re-assessment**: Now that code is written, has the risk changed?
+If risk increased (e.g., you discovered the fix needs a migration), re-evaluate.
+If new risk >= 9: **STOP** and present updated assessment.
+
+**Discovered issues**: If you find unrelated bugs or tech debt during review:
+- Do NOT fix them inline
+- File separate GitHub issues: `gh issue create --title "..." --body "Found during #141 work"`
+- Record in workflow state: `session_summary.issues_filed`
+
+Update phase to "pr" if review passes.
+
+### Phase 7: PR (MANDATORY STOP POINT)
+
+**Always stop here. Never merge without human approval.**
+
+Create the PR with a structured template:
+
+```bash
+gh pr create --title "fix: short description (#ISSUE)" --body "$(cat <<'EOF'
+## Summary
+[2-3 bullet points: what changed and why]
+
+## Risk Assessment
+- **Score: X/12 (Level Y)**
+- Blast radius: [description] (N/3)
+- Reversibility: [description] (N/3)
+- Confidence: N% — [reasoning]
+- Domain: [description] (N/3)
+
+## Scope Check
+- Planned: N files | Actual: M files
+- Layers: [backend/frontend/both]
+- Scope status: [clean / grew — explanation]
+
+## QA Results
+- Tests: X/Y passed
+- Lint: clean/N warnings
+- Types: clean/N errors
+- QA fix attempts: N
+
+## What I Didn't Do
+- [Things considered but intentionally left out]
+- [Related issues filed: #276, #277]
+
+## Test Plan
+- [ ] Verify [specific behavior]
+- [ ] Check [edge case]
+
+Closes #ISSUE
+
+Co-Authored-By: Claude Autopilot <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Update workflow state:**
+```json
+{
+  "phase": "awaiting_merge",
+  "pr_number": 275
+}
+```
+
+**Present to user:**
+```
+AUTOPILOT: PR #275 ready for review.
+  "fix: short sessions no longer consume credits (#141)"
+
+  Risk: 5/12 (Level 1 — proceeded autonomously)
+  Scope: 3 files planned / 3 actual (clean)
+  QA: all tests passing
+
+  Merge when ready. I'll pick up the next item automatically.
+```
+
+**Wait for user input.** Do not proceed until the user indicates the PR was merged
+(or tells you to move on to the next item).
+
+### Phase 8: POST-MERGE
+
+When user confirms merge (or says "continue", "next", "merged"):
+
+1. Update session summary: add to `completed`
+2. Reset current item and phase to "assess"
+3. Loop back to Phase 1
+
+**If there are no more items** (all issues addressed, no PRs pending):
+```
+AUTOPILOT: Session complete.
+
+  Completed: 3 items
+    ✓ #141 — short session credit refund (PR #275, merged)
+    ✓ #162 — feedback nudge fix (PR #276, merged)
+    ✓ #71 — sentry env vars (PR #277, merged)
+
+  Filed during work: #278 (stale test cleanup), #279 (billing edge case)
+
+  Nothing left in queue. /autopilot again when new issues come in.
+```
+
+Update workflow state: `mode: "idle"`.
+
+## Dry Run Mode
+
+If `--dry-run` is passed:
+- Run Phase 1 (ASSESS) and Phase 2 (CLASSIFY) normally
+- Present the full priority list, risk assessment, and planned approach
+- Do NOT proceed to Phase 3+
+- Report: "DRY RUN: Would work on #141 (risk 5/12). Plan: [brief]. Approve to start."
+
+This lets users build trust before enabling full autonomy.
+
+## Exiting Autopilot
+
+The user can exit autopilot at any time by:
+- Saying "stop", "pause", "exit autopilot"
+- Giving a specific instruction (triage router detects non-autopilot intent)
+
+On exit:
+1. If mid-implementation: commit work-in-progress, note the branch
+2. Update workflow state: `mode: "paused"`, preserve all state
+3. Report current status and how to resume
+
+To resume: `/autopilot` (reads existing state and continues).
+
+## Communication Rules
+
+The agent communicates at natural checkpoints, not continuously:
+
+| Event | What to say |
+|-------|-------------|
+| Starting work on an item | "Starting #141 (risk 5/12). Implementing backend fix for short sessions." |
+| QA passed | Nothing (silence = good) |
+| QA failed, fixing | "QA: 2 test failures, fixing..." |
+| QA failed, stuck | "BLOCKED: Can't resolve test failure after 2 attempts. Need help." |
+| Scope grew | "SCOPE: Started at 3 files, now at 6. The fix requires [X]. Continue?" |
+| Risk escalation | "RISK: This needs a migration (was risk 5, now risk 9). Approve?" |
+| PR ready | Full PR summary (see Phase 7) |
+| Moving to next item | "Merged #275. Next: #162 (feedback nudge bug, risk 3/12)." |
+| Session done | Full session summary |
+
+**Do NOT:**
+- Narrate every file read or edit
+- Ask "should I continue?" after every phase (just continue if risk allows)
+- Repeat information the user already saw
+- Send messages for Level 0-1 actions (just do them)
+
+## Cost Awareness
+
+Minimize API spend by choosing the cheapest capable model:
+
+| Task | Agent/Model | Cost |
+|------|-------------|------|
+| Project assessment | explore-light (Haiku) or inline | 1x |
+| Simple bug fix (1-3 files) | Inline tools (no agent) | 0x (just Opus) |
+| Backend implementation | auto-detect backend (Sonnet) | 10x |
+| Frontend implementation | frontend (Sonnet) | 10x |
+| QA validation | ops (Haiku) for tests, inline for review | 1x |
+| Complex planning | architect (Opus) | 60x — only for risk 6+ |
+
+**Rule: Never spawn an Opus agent for a risk 0-3 task.** Handle it inline or with Sonnet/Haiku.