@arthai/agents 1.0.0

package/skills/restart/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: restart
+description: "Kill and restart local dev servers. Reads service config from CLAUDE.md. Usage: /restart [service]"
+user-invocable: true
+arguments: "<service>"
+---
+
+# Restart Servers Skill
+
+Kill and restart local dev servers using the configuration from CLAUDE.md.
+
+## Instructions
+
+1. **Read CLAUDE.md** in the project root. Look for the **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 |
+```
+
+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
+
+2. **Kill existing processes** for the target service(s):
+
+```bash
+# Kill by port
+lsof -ti:<port> | xargs kill -9 2>/dev/null
+
+# Wait for ports to free
+sleep 2
+```
+
+3. **Start each server** in background using the configured start command:
+
+```bash
+# Run in background
+<start_command> &
+```
+
+Use `run_in_background: true` on the Bash tool.
+
+4. **Health check** after startup:
+
+```bash
+# Check each service
+curl -sf http://localhost:<port>/health > /dev/null 2>&1 && echo "<service>:UP" || echo "<service>:DOWN"
+```
+
+5. **Report** status of all servers.
+
+## 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 |
+
+## If CLAUDE.md Is Missing Service Config
+
+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."

package/skills/review-pr/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: review-pr
+description: "Differentiated PR review — bug fix vs feature. Scope compliance, regression tests, behavior contract, knowledge base lookup. Uses built-in code review + project-specific checks. Usage: /review-pr <#N|branch> <--type bug|feature>"
+user-invocable: true
+arguments: "<#N|branch> <--type bug|feature>"
+---
+
+# /review-pr — Differentiated PR Review
+
+PR review that understands the difference between a bug fix and a feature.
+Uses Claude Code's built-in code review capabilities as the foundation,
+then layers project-specific checks on top.
+
+**For bug fix PRs**: Scope compliance, regression test proof, behavior contract,
+root cause documentation, knowledge base lookup for similar past bugs.
+
+**For feature PRs**: Plan completeness, over-engineering check, test coverage
+for new functionality, domain logic validation.
+
+## Argument Parsing
+
+| Input | Action |
+|-------|--------|
+| `/review-pr` | Review the current branch's PR (auto-detect from `gh pr view`) |
+| `/review-pr #88` | Review specific PR by number |
+| `/review-pr feature/auth` | Review PR for a specific branch |
+| `/review-pr --type bug` | Force bug fix review mode |
+| `/review-pr --type feature` | Force feature review mode |
+
+If `--type` is not provided, auto-detect from PR context (Step 1).
+
+## Execution Steps
+
+### Step 1: Load PR Context
+
+```bash
+# Get PR details
+gh pr view {N} --json number,title,body,labels,files,commits,additions,deletions,headRefName,baseRefName,reviewDecision
+
+# Get the diff
+gh pr diff {N}
+
+# Get commit messages
+gh pr view {N} --json commits --jq '.commits[].messageHeadline'
+```
+
+**Auto-detect PR type:**
+
+| Signal | Type |
+|--------|------|
+| Labels contain `bug`, `fix`, `hotfix`, `regression` | Bug fix |
+| Title starts with `fix:`, `hotfix:`, `bugfix:` | Bug fix |
+| `.claude/.fix-scope-lock.json` exists in the branch | Bug fix (created by `/fix`) |
+| `.claude/.fix-behavior-contract.md` exists | Bug fix (created by `/fix`) |
+| Labels contain `feature`, `enhancement`, `feat` | Feature |
+| Title starts with `feat:`, `feature:`, `add:` | Feature |
+| `.claude/plans/{name}.md` referenced in commits | Feature |
+| None of the above | Ask user, or default to feature |
+
+### Step 1b: Gather context with explore-light (cost: 1x Haiku)
+
+Before reviewing, understand what the changed code connects to:
+
+```
+subagent_type: "explore-light"
+prompt: "For each of these changed files, find:
+1. What imports/calls them (callers — who depends on this code?)
+2. What they import/call (dependencies — what does this code depend on?)
+3. Related test files (do tests exist for these files?)
+4. Similar patterns elsewhere in the codebase (is this consistent?)
+
+Changed files: {list from PR diff}
+Return file paths and brief descriptions."
+```
+
+This gives the code-reviewer context about blast radius — what else could break if
+these files are wrong. 60x cheaper than having Opus do the exploration.
+
+### Step 2: Standard Review (ALL PRs)
+
+Spawn the `code-reviewer` agent with the PR diff, project context, AND explore-light findings:
+
+```
+Agent prompt:
+- PR diff: {diff}
+- PR description: {body}
+- Project profile: {.claude/project-profile.md if exists}
+- Coding conventions: {.claude/knowledge/shared/conventions.md if exists}
+
+Review for:
+1. Code quality — naming, formatting, error handling per project conventions
+2. Security — OWASP top 10, auth checks, input validation, SQL injection
+3. Test coverage — new code has tests, existing tests still relevant
+4. Architecture — SOLID, separation of concerns, no unnecessary coupling
+```
+
+Collect the standard review output.
+
+### Step 3: Type-Specific Review
+
+#### 3A: Bug Fix Review
+
+If PR type is `bug`:
+
+**3A.1: Scope compliance**
+
+If `.claude/.fix-scope-lock.json` exists (created by `/fix`):
+```bash
+# Read the scope lock
+cat .claude/.fix-scope-lock.json
+
+# Get files changed in PR
+CHANGED_FILES=$(gh pr view {N} --json files --jq '.files[].path')
+
+# Check each file against zones
+for file in $CHANGED_FILES; do
+  if in_fix_zone "$file"; then
+    echo "✓ $file — Fix Zone (allowed)"
+  elif in_watch_zone "$file"; then
+    echo "⚠ $file — Watch Zone (needs justification)"
+  else
+    echo "✗ $file — FROZEN ZONE VIOLATION"
+  fi
+done
+```
+
+If scope lock doesn't exist (fix was done without `/fix`), analyze the diff manually:
+- Is the change minimal? (fewer files = better for bug fixes)
+- Are unrelated files modified? Flag them.
+- Are migration files modified? Flag as high risk.
+
+**3A.2: Root cause documentation**
+
+Check the PR body for root cause:
+```
+Required in PR body for bug fixes:
+✓/✗ Root cause described (not just "fixed X" but "X happened because Y")
+✓/✗ Location specified (file:line)
+✓/✗ Trigger condition documented (when does the bug occur?)
+✓/✗ Why existing tests missed it
+```
+
+If any are missing, flag as review comment.
+
+**3A.3: Regression test verification**
+
+```bash
+# Find new test files/functions in the diff
+NEW_TESTS=$(gh pr diff {N} | grep "^+.*def test_\|^+.*it(\|^+.*test(" | head -10)
+
+# Check: do new tests exist?
+if [ -z "$NEW_TESTS" ]; then
+  echo "✗ CRITICAL: No regression test found. Bug fixes MUST include a regression test."
+fi
+```
+
+If `.claude/.fix-behavior-contract.md` exists, check that:
+- Every "MUST CHANGE" row has a corresponding new test
+- Every "MUST NOT CHANGE" row has an existing test that still passes
+
+**3A.4: Mutation test check**
+
+If the regression test exists, verify it actually catches the bug:
+
+```bash
+# Save fix, revert, run test (should FAIL), re-apply, run test (should PASS)
+# This proves the test is meaningful, not just a green checkbox
+
+git stash
+pytest {new_test_file} -v 2>&1  # Should FAIL without fix
+RESULT_WITHOUT=$?
+git stash pop
+pytest {new_test_file} -v 2>&1  # Should PASS with fix
+RESULT_WITH=$?
+
+if [ $RESULT_WITHOUT -eq 0 ]; then
+  echo "✗ CRITICAL: Regression test PASSES without the fix — test doesn't catch the bug"
+elif [ $RESULT_WITH -ne 0 ]; then
+  echo "✗ CRITICAL: Regression test FAILS with the fix — fix is broken"
+else
+  echo "✓ Regression test: fails without fix, passes with fix (mutation check passed)"
+fi
+```
+
+**3A.5: Knowledge base lookup**
+
+```bash
+# Search for similar past bugs in the same files
+for file in $CHANGED_FILES; do
+  grep -rl "$file" .claude/qa-knowledge/incidents/ 2>/dev/null
+done
+
+# Search for similar root cause patterns
+grep -i "{root_cause_keywords}" .claude/qa-knowledge/bug-patterns.md 2>/dev/null
+```
+
+If similar past bugs found:
+```
+⚠ This area has had bugs before:
+  • 2026-03-15: token expiry timezone issue (same file)
+  • 2026-02-28: null session crash (same module)
+  Consider: is this a recurring pattern? Should we add a broader fix?
+```
+
+**3A.6: Breaking change assessment**
+
+If the fix modifies API endpoints, response formats, or public interfaces:
+```
+⚠ Breaking change detected:
+  - POST /auth/refresh response format changed (added error_code field)
+  - Consider: will existing clients handle this?
+  - Consider: should this be versioned? (/api/v2/auth/refresh)
+```
+
+**3A.7: Rollback safety**
+
+```
+Rollback assessment:
+  ✓ No migration changes — safe to revert commit
+  ✓ No schema changes — no data impact on revert
+  ✗ If migration exists: "Reverting requires a down migration"
+  ✗ If data was modified: "Reverting may leave orphan records"
+```
+
+#### 3B: Feature Review
+
+If PR type is `feature`:
+
+**3B.1: Plan completeness**
+
+If `.claude/plans/{feature-name}.md` exists:
+```bash
+# Read the plan
+cat .claude/plans/{feature-name}.md
+
+# Compare planned tasks vs implemented
+# Check: every task in the plan has corresponding code changes
+# Check: no unplanned code changes (scope creep)
+```
+
+Flag:
+- ✗ Planned feature X not implemented
+- ✗ Unplanned change Y added (scope creep)
+- ⚠ Planned feature Z partially implemented
+
+**3B.2: Over-engineering check**
+
+Look for signs of unnecessary complexity:
+- Abstractions for one-time operations
+- Feature flags for first-time features
+- Generic frameworks where a specific solution would do
+- Configuration options nobody asked for
+- "Future-proofing" not in the plan
+
+```
+⚠ Possible over-engineering:
+  - AbstractTokenProviderFactory — only one implementation exists
+  - Consider: use a simple function instead of a class hierarchy
+```
+
+**3B.3: New functionality test coverage**
+
+```bash
+# Find new non-test files
+NEW_CODE=$(gh pr diff {N} | grep "^+++ b/" | grep -v test | grep -v __test__)
+
+# Find new test files
+NEW_TESTS=$(gh pr diff {N} | grep "^+++ b/" | grep -E "test|spec|__test__")
+
+# Check ratio: new code should have proportional new tests
+```
+
+If new endpoints/components have no tests, flag as critical.
+
+**3B.4: Domain logic validation**
+
+If the feature touches domain-specific code:
+- Spawn `qa-domain` agent to validate business rule consistency
+- Check enum/status consistency across layers
+- Verify state machine transitions are valid
+
+### Step 4: Compile Review Report
+
+```markdown
+## PR Review: #{number} — {title}
+
+**Type**: {bug fix | feature}
+**Risk**: {low | medium | high | critical}
+
+### Standard Review
+{code-reviewer agent output — quality, security, architecture}
+
+### {Bug Fix | Feature} Specific Review
+
+{Type-specific findings from Step 3}
+
+### Summary
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Code quality | ✓/⚠/✗ | {notes} |
+| Security | ✓/⚠/✗ | {notes} |
+| Test coverage | ✓/⚠/✗ | {notes} |
+| Scope compliance | ✓/⚠/✗ | {notes} (bug only) |
+| Regression test | ✓/⚠/✗ | {notes} (bug only) |
+| Mutation check | ✓/⚠/✗ | {notes} (bug only) |
+| Root cause documented | ✓/⚠/✗ | {notes} (bug only) |
+| Plan completeness | ✓/⚠/✗ | {notes} (feature only) |
+| Over-engineering | ✓/⚠/✗ | {notes} (feature only) |
+
+### Verdict
+
+{APPROVE | REQUEST CHANGES | COMMENT}
+
+{If REQUEST CHANGES: specific list of what must change before merge}
+```
+
+### Step 5: Post Review Actions
+
+**Post as GitHub review** (if user approves):
+```bash
+# Post the review as a GitHub PR review
+gh pr review {N} --{approve|request-changes|comment} --body "{review_body}"
+```
+
+**Update knowledge base:**
+
+Append to `.claude/knowledge/skills/review-pr.md`:
+```markdown
+### {date} — PR #{number} ({type})
+**Files**: {changed_files}
+**Findings**: {key_findings_summary}
+**Patterns**: {any recurring patterns noticed}
+```
+
+If reviewing a bug fix, check if the same file area has been reviewed before.
+If patterns emerge (e.g., "auth.py has had 3 bug fix PRs in 2 months"),
+flag it as a systemic issue.
+
+---
+
+## Integration with Existing Skills
+
+| Existing | How /review-pr uses it |
+|----------|----------------------|
+| `code-reviewer` agent | Spawned for standard review (Step 2) |
+| `qa-challenger` agent | Spawned for bug fix PRs to generate attack scenarios |
+| `qa-domain` agent | Spawned for feature PRs to validate domain logic |
+| `/fix` artifacts | Reads `.claude/.fix-scope-lock.json` and `.claude/.fix-behavior-contract.md` |
+| `/planning` artifacts | Reads `.claude/plans/{feature}.md` for plan alignment |
+| `qa-knowledge/` | Reads incidents and bug patterns for similar past issues |
+| `.claude/knowledge/` | Reads conventions for code style validation |
+
+---
+
+## Rules
+
+- **Always detect PR type** before reviewing — bug and feature reviews have different criteria
+- **Scope compliance is mandatory for bug fixes** — any Frozen Zone violation is a blocking issue
+- **Regression test is mandatory for bug fixes** — no test = no merge
+- **Mutation check is mandatory** — test must fail without fix and pass with fix
+- **Root cause must be documented** — "fixed it" without explanation is not acceptable
+- **Knowledge base is consulted** — always check for similar past issues
+- **Over-engineering check for features** — keep it simple, match the plan
+- **Never auto-approve** — always present findings and let user decide
+- **Post to GitHub** — review should be visible to the team, not just local
+- **Learn from every review** — write to knowledge base after each review