Loop Engineering in Claude Code

.
+-- CLAUDE.md
+-- .claude/
|   +-- agents/
|   |   +-- backlog-verifier.md
|   |   +-- release-risk-reviewer.md
|   |   +-- product-slice-reviewer.md
|   +-- commands/
|   |   +-- manager-sweep.md
|   |   +-- backlog-loop.md
|   +-- loop.md
|   +-- settings.json
+-- docs/
    +-- agent-runs/
        +-- product-slice-loop.md
        +-- backlog-loop.md
        +-- incident-loop.md

/goal Ship the private-beta invite request slice.
 
Read first:
- CLAUDE.md
- docs/product/private-beta.md
- app/invite/**
- lib/db/**
- current diff
 
State:
- Update docs/agent-runs/product-slice-loop.md after every pass.
 
Scope:
- Build one path: request invite, persist pending request, show duplicate-request error.
- Do not add billing, team roles, email delivery, or admin dashboards.
 
Verifier:
- npm test
- npm run lint
- npm run build
- browser check for happy path and duplicate-request error
 
Stop when:
- The invite request path works end to end.
- The verifier passes.
- product-slice-reviewer reports no P0/P1 issue.
- The state file lists changed files, commands, screenshots, and remaining risk.
 
Escalate when:
- Auth/session behavior changes.
- A migration or permission change is needed.
- The same failure repeats twice.

# Product slice loop
 
## Objective
A private-beta user can request an invite, see the saved pending state, and see duplicate-request feedback.
 
## Scope
- In scope: invite request UI, API handler, persistence, duplicate-request state, tests.
- Out of scope: billing, roles, email provider, admin dashboard.
 
## Verifier
`npm test && npm run lint && npm run build`
 
Browser checks:
- /invite accepts a new request.
- /invite shows duplicate-request feedback for an existing email.
 
## Pass log
| pass | hypothesis | changed files | verifier | evidence | decision |
| --- | --- | --- | --- | --- | --- |
| 1 | | | | | |
 
## Risks
| risk | owner needed | trigger | next check |
| --- | --- | --- | --- |
 
## Fresh review
| reviewer | result | blocking findings |
| --- | --- | --- |
 
## Final evidence
- Changed files:
- Commands:
- Screenshots:
- Remaining risks:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "test -f docs/agent-runs/product-slice-loop.md || { echo 'Missing product slice loop state file'; exit 2; }"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "case "$CLAUDE_TOOL_INPUT" in *'rm -rf '*|*'--force'*) echo 'Destructive command blocked by loop policy'; exit 2;; esac"
          }
        ]
      }
    ]
  }
}

---
name: product-slice-reviewer
description: Read-only reviewer for a product-slice loop. Use after implementation claims the slice is done.
tools: Read, Grep, Bash
---
 
You review the diff against the original product-slice goal.
You do not edit files.
 
Check:
1. The implemented path matches the objective in docs/agent-runs/product-slice-loop.md.
2. The diff stays inside the stated scope.
3. The verifier was run and not weakened.
4. Tests cover the happy path and at least one failure state.
5. Screenshots or browser notes prove the user path.
6. No P0/P1 risk remains.
 
Return:
- pass: true or false
- p0_p1_findings: list
- missing_evidence: list
- next_action: one concrete step

---
name: backlog-verifier
description: Read-only reviewer for backlog and production-error loops. Use after the implementing agent claims an issue is fixed.
tools: Read, Grep, Bash
---
 
You verify backlog fixes. You do not edit files.
 
Check:
1. The issue was reproduced or explicitly proven stale or duplicate.
2. The fix addresses root cause, not only symptoms.
3. Tests were added or updated for the failing behavior.
4. Existing tests, logs, and monitoring were not weakened.
5. The issue update contains commands, output, files, and remaining risk.
 
Return:
- pass: true or false
- blocking_findings: prioritized list
- missing_evidence: list
- suggested_next_action: one concrete step

Run a backlog repair loop for the top P0/P1 issue batch.
 
Inputs:
- Open P0/P1 issues older than 14 days
- Recent production errors
- Current branch diff
- docs/agent-runs/backlog-loop.md
 
Protocol:
1. Sort by customer impact, age, and reproducibility.
2. Pick one issue.
3. Reproduce it with a failing test, script, log query, or explicit non-repro note.
4. Patch only the root cause.
5. Add or update a regression check.
6. Run the verifier named in the state file.
7. Ask backlog-verifier to review the result.
8. Close, duplicate, or escalate with evidence.
 
Forbidden:
- Closing from summary alone.
- Weakening tests.
- Silencing logs.
- Broadening catch blocks without root-cause evidence.

Read docs/agent-runs/manager-operating-loop.md and update it.
 
Check:
1. Pull requests older than two business days.
2. Failed or stuck CI checks.
3. Incident follow-up items without recent evidence.
4. Recently changed code paths whose docs or runbooks are stale.
5. Promises in planning notes that lack an owner or proof.
 
Output:
- owner
- blocker
- latest evidence
- next observable check
- escalation date
 
Do not change code unless the sweep finds a low-risk docs-only update. Record any proposed code change as a separate action.