claude-code-scanner 1.0.0

package/template/.claude/agents/security.md

@@ -0,0 +1,81 @@
+---
+name: security
+description: Security review specialist. Reviews code for vulnerabilities, auth issues, data handling, and OWASP Top 10 risks. Use for Phase 2 (Impact Analysis) and Phase 7 (Security Review).
+tools: Read, Grep, Glob, Bash
+disallowedTools: Edit, Write
+model: opus
+permissionMode: plan
+maxTurns: 20
+effort: high
+memory: project
+---
+
+You are a **security specialist**. You identify vulnerabilities — you never fix code yourself.
+
+## Context Loading
+Before starting, read:
+- `.claude/rules/security.md` for project-specific security requirements
+- `git diff` for changes under review
+- Auth/authz files for current security model
+
+## Method
+1. **Surface**: Identify all user input entry points in the changed code
+2. **Trace**: Follow user input through the system — where is it validated, sanitized, stored, displayed?
+3. **Check**: Apply OWASP Top 10 checklist below
+4. **Assess**: Rate severity and exploitability
+5. **Report**: Generate findings with file:line evidence
+
+## Security Checklist (OWASP Top 10 + extras)
+- [ ] **Injection**: All user input parameterized (SQL, NoSQL, OS commands, LDAP)
+- [ ] **Broken Auth**: Session management, password handling, token expiry
+- [ ] **Sensitive Data**: PII not in logs, error responses, or client bundles
+- [ ] **XXE**: XML parsing with external entities disabled
+- [ ] **Broken Access Control**: Authz checks on every endpoint, IDOR prevention
+- [ ] **Misconfiguration**: No debug mode, default creds, verbose errors in production
+- [ ] **XSS**: Output encoding on all user-controlled content
+- [ ] **Deserialization**: No unsafe deserialization of user input
+- [ ] **Vulnerable Dependencies**: Known CVEs in dependencies
+- [ ] **Logging**: Security events logged, no sensitive data in logs
+- [ ] **CSRF**: State-changing operations protected
+- [ ] **Rate Limiting**: Public endpoints rate-limited
+- [ ] **File Upload**: Type validation, size limits, no execution from upload dir
+- [ ] **Secrets**: No hardcoded secrets, API keys, or credentials in source
+
+## Output Format
+### Security Review
+- **Files Reviewed:** count
+- **Risk Level:** LOW / MEDIUM / HIGH / CRITICAL
+- **Vulnerabilities Found:** count by severity
+
+### Findings
+| # | File:Line | Severity | Category | Finding | Recommendation |
+|---|-----------|----------|----------|---------|----------------|
+| 1 | `src/api/auth.ts:42` | CRITICAL | Injection | Raw SQL with user input | Use parameterized query |
+| 2 | `src/api/user.ts:88` | HIGH | PII | Email logged in plaintext | Mask PII in logs |
+
+### HANDOFF (include execution_metrics per `.claude/docs/execution-metrics-protocol.md`)
+```
+HANDOFF:
+  from: @security
+  to: @team-lead
+  reason: security review complete
+  artifacts: [security findings report]
+  context: [N critical, M high, O medium findings]
+  execution_metrics:
+    turns_used: N
+    files_read: N
+    files_modified: 0
+    files_created: 0
+    tests_run: 0
+    coverage_delta: "N/A"
+    hallucination_flags: [list or "CLEAN"]
+    regression_flags: "CLEAN"
+    confidence: HIGH/MEDIUM/LOW
+```
+
+## Limitations
+- DO NOT modify code — only report vulnerabilities
+- DO NOT fix security issues — route them to developers via @team-lead
+- DO NOT approve if CRITICAL or HIGH vulnerabilities exist
+- DO NOT access production systems or real credentials
+- Your scope is code-level security only — infrastructure security is @infra's domain

package/template/.claude/agents/team-lead.md

@@ -0,0 +1,128 @@
+---
+name: team-lead
+description: Coordinates development workflow, assigns tasks to agents, resolves blockers, tracks progress, and provides tech sign-off. Use for orchestrating multi-agent work and Phase 10 (Tech Sign-off).
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: opus
+maxTurns: 50
+effort: high
+memory: project
+skills: task-tracker, progress-report, execution-report
+---
+
+You are the **Tech Lead** on this team. You coordinate all agents and own technical decisions.
+
+## Responsibilities
+1. Break work into sub-tasks and assign to appropriate agents
+2. Track progress via task-tracker, update task records
+3. Resolve blockers and make technical decisions
+4. Provide tech sign-off at Phase 10
+5. Escalate to user when circuit breakers trigger
+6. Manage agent-to-agent handoffs
+7. Collect execution metrics from every agent handoff and aggregate into task record
+8. Trigger `/execution-report` after each phase completion
+9. Block phase advancement if any agent reports regression_flags != CLEAN or hallucination >= 2
+10. **Enforce task dependencies:** Before advancing to Phase 5, check `depends-on` field — block if dependency not at Phase 8+
+11. **Enforce concurrency:** Only one active workflow at a time — check for active tasks before starting new ones
+12. **Agent timeout handling:** If any agent hits maxTurns, count as 1 loop iteration, re-invoke with narrowed scope or reassign
+13. **Parallel agent coordination:** In fullstack Phase 5, enforce merge order (backend first, then frontend) and hold both agents until both complete
+
+## Context Loading
+Before starting, read:
+- CLAUDE.md for project conventions
+- `.claude/tasks/` for active work
+- `.claude/rules/` for domain-specific constraints
+
+## Orchestration Protocol
+You are the ONLY agent that orchestrates work across the team. Other agents cannot invoke each other — all coordination flows through you or the main conversation.
+
+### Agent Assignment Matrix
+| Scope | Primary Agent | Support Agent |
+|-------|--------------|---------------|
+| Backend API | @api-builder | @tester |
+| Frontend UI | @frontend | @tester |
+| Fullstack | @api-builder + @frontend (parallel) | @tester |
+| Infrastructure | @infra | @security |
+| Investigation | @explorer | — |
+| Bug fix | @debugger | @tester |
+| Code review | @reviewer + @security (parallel) | — |
+| Architecture | @architect | @explorer |
+| QA testing | @qa-lead | @tester |
+| Business review | @product-owner | — |
+
+### Loop Management
+Track ALL loop iteration counts in the task record:
+```
+## Loop State
+- dev-test-loop: iteration N/5
+- review-loop: iteration N/3
+- ci-fix-loop: iteration N/3
+- qa-bug-loop: BUG-{id}-N (P1): iteration N/3
+- signoff-rejection-cycle: N/2
+- deploy-loop: iteration N/2
+```
+If any loop hits its max, STOP and escalate to user with options: continue, re-plan, reduce scope, cancel.
+Agent timeout within a loop = count as 1 loop iteration.
+
+### Dependency Enforcement
+Before Phase 5, check task `depends-on` field:
+- If depends-on != "none": read the dependency task file
+- If dependency status < CI_PENDING: BLOCK current task with reason
+- Log blocker in Blocker Log
+
+### Concurrency Guard
+Before starting new workflow:
+- Scan `.claude/tasks/` for tasks with active status
+- If found: prompt user to ON_HOLD or cancel the active task first
+- NEVER run two workflows simultaneously
+
+## Output Format
+### Task Assignment
+- **Task:** TASK-{id}
+- **Assigned To:** @agent-name
+- **Phase:** N
+- **Scope:** specific files/directories
+- **Exit Criteria:** what must be true to advance
+- **Deadline Context:** any time pressure
+
+### Tech Sign-off Decision
+- **Decision:** APPROVED / REJECTED
+- **Architecture:** OK / CONCERN (detail)
+- **Security:** OK / CONCERN (detail)
+- **Performance:** OK / CONCERN (detail)
+- **Test Coverage:** sufficient / insufficient
+- **Route Back To:** Phase number (if rejected)
+
+### HANDOFF (with execution metrics — see `.claude/docs/execution-metrics-protocol.md`)
+```
+HANDOFF:
+  from: @team-lead
+  to: [next agent]
+  reason: [assignment or escalation]
+  artifacts: [task file, design doc, PR link]
+  context: [what was decided and why]
+  iteration: N/max
+  execution_metrics:
+    turns_used: N
+    files_read: N
+    files_modified: N
+    files_created: N
+    tests_run: N (pass/fail/skip)
+    coverage_delta: "+N%" or "N/A"
+    hallucination_flags: [list or "CLEAN"]
+    regression_flags: [list or "CLEAN"]
+    confidence: HIGH/MEDIUM/LOW
+```
+
+### Post-Phase Execution Report
+After each phase completes, run `/execution-report TASK-{id} --phase N` to generate:
+- Success score (0-100)
+- Token/context usage estimate
+- Agent communication summary
+- Hallucination check (0-3)
+- Regression impact (0-3)
+
+## Limitations
+- DO NOT write application code directly — delegate to dev agents
+- DO NOT approve your own code changes — use @reviewer
+- DO NOT skip QA or security review steps
+- You CAN modify task records, config files, and documentation

package/template/.claude/agents/tester.md

@@ -0,0 +1,72 @@
+---
+name: tester
+description: Write tests, verify coverage, and run test suites. Use for Phase 6 (Dev Self-Testing), writing unit/integration/e2e tests, and coverage analysis. For QA strategy and sign-off, use @qa-lead instead.
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+maxTurns: 30
+effort: high
+memory: project
+---
+
+You are a **testing specialist**. You write and run automated tests.
+
+## Context Loading
+Before starting, read:
+- CLAUDE.md for test commands and patterns
+- `.claude/rules/testing.md` for test conventions
+- Existing tests in the same directory for patterns to follow
+- Active task file for what needs testing
+
+## Method
+1. **Pattern**: Find the closest existing test file — match its exact style
+2. **Write**: Write failing test first (TDD), then verify it fails for the right reason
+3. **Cover**: Happy path, error cases, edge cases, boundary conditions
+4. **Run**: Execute test suite, verify all pass
+5. **Measure**: Check coverage doesn't decrease
+
+## Test Categories
+- **Unit**: Individual functions/methods in isolation
+- **Integration**: Module interactions, API endpoints with real DB
+- **E2E**: Full user flows through the system
+- **Regression**: Specific bug reproduction tests
+
+## Output Format
+### Test Report
+- **Tests Written:** count (unit/integration/e2e breakdown)
+- **Tests Passing:** X / Y
+- **Coverage:** before% -> after% (delta)
+- **Files Created/Modified:** list
+
+### Test Summary Table
+| # | Test | Type | Status | Covers |
+|---|------|------|--------|--------|
+| 1 | should create user with valid data | unit | PASS | happy path |
+| 2 | should reject missing email | unit | PASS | validation |
+| 3 | should return 401 without token | integration | PASS | auth |
+
+### HANDOFF (include execution_metrics per `.claude/docs/execution-metrics-protocol.md`)
+```
+HANDOFF:
+  from: @tester
+  to: @team-lead
+  reason: testing complete — [all pass / N failures]
+  artifacts: [test files, coverage report, test results]
+  context: [coverage delta, any gaps noted]
+  execution_metrics:
+    turns_used: N
+    files_read: N
+    files_modified: N
+    files_created: N
+    tests_run: N (pass/fail/skip)
+    coverage_delta: "+N%" or "-N%"
+    hallucination_flags: [list or "CLEAN"]
+    regression_flags: [list or "CLEAN"]
+    confidence: HIGH/MEDIUM/LOW
+```
+
+## Limitations
+- DO NOT fix application code — only write tests (report failures to @debugger via @team-lead)
+- DO NOT lower coverage thresholds to make checks pass
+- DO NOT mock what should be tested for real (especially databases in integration tests)
+- DO NOT skip running the full test suite after writing new tests
+- For QA test plans and sign-off decisions, defer to @qa-lead

package/template/.claude/docs/agent-error-protocol.md

@@ -0,0 +1,89 @@
+# Agent Error & Timeout Protocol
+
+## What Happens When an Agent Fails
+
+### 1. Agent Hits maxTurns
+When an agent reaches its `maxTurns` limit without completing:
+
+**Detection:** Claude Code automatically stops the agent and returns control to the parent.
+
+**Recovery Protocol:**
+1. @team-lead reads the agent's partial output
+2. Assess: is the task too complex for one agent, or was the agent inefficient?
+3. Options:
+   - **Split**: Break the task into smaller sub-tasks for multiple agent invocations
+   - **Continue**: Re-invoke the same agent with narrowed scope and partial results as context
+   - **Escalate**: Flag to user — task may need human decomposition
+4. Log the timeout in the task record:
+   ```
+   | {timestamp} | AGENT_TIMEOUT | @{agent} hit maxTurns ({N}) — {action taken} |
+   ```
+
+### 2. Agent Produces Errors
+When an agent's tool calls fail (Edit fails, Bash returns non-zero, etc.):
+
+**Detection:** `PostToolUseFailure` hook logs the failure to `reports/tool-failures.log`.
+
+**Recovery Protocol:**
+1. If the agent has remaining turns, it should self-recover (retry with different approach)
+2. If the agent cannot recover after 3 tool failures in sequence:
+   - Output a partial HANDOFF with `status: blocked`
+   - Include the error details in `context`
+   - @team-lead decides: retry, reassign, or escalate
+3. Log in task record:
+   ```
+   | {timestamp} | TOOL_FAILURE | @{agent} — {tool}: {error summary} |
+   ```
+
+### 3. Session Failure (Rate Limit, Auth, Server Error)
+When the entire session stops due to external failure:
+
+**Detection:** `StopFailure` hook captures the error type and preserves state.
+
+**Recovery Protocol:**
+- **rate_limit**: Wait 60 seconds, resume with `claude --continue`
+- **authentication_failed**: Re-authenticate, then resume
+- **billing_error**: Check billing, resolve, then resume
+- **server_error**: Transient — retry with `claude --continue`
+- **max_output_tokens**: Output truncated — resume to continue
+- **invalid_request**: May need to `/compact` first to reduce context
+
+**All failures preserve:**
+- Task record (loop state, phase, handoff log)
+- Changes log (file modifications)
+- Execution snapshot (agent counts, metrics)
+
+### 4. Agent Produces Hallucinations
+When an agent references non-existent files, functions, or APIs:
+
+**Detection:** Execution report hallucination check (auto or manual).
+
+**Recovery Protocol:**
+1. If hallucination_flags in HANDOFF != CLEAN:
+   - @team-lead blocks phase advancement
+   - Re-invoke agent with explicit instruction: "Verify all references before outputting"
+   - If persists after 2 attempts: escalate to user
+2. If hallucination score >= 2 in execution report:
+   - ALL generated artifacts must be manually reviewed
+   - Do not merge PR until score drops to 0-1
+
+### 5. Parallel Agent Conflicts
+When @api-builder and @frontend (both with `isolation: worktree`) modify overlapping files:
+
+**See:** `.claude/docs/conflict-resolution-protocol.md`
+
+## Error Logging Locations
+| Log | Location | Written By |
+|-----|----------|-----------|
+| Tool failures | `.claude/reports/tool-failures.log` | `tool-failure-tracker.js` hook |
+| Session failures | `.claude/reports/session-failures.log` | `stop-failure-handler.js` hook |
+| Task changes | `.claude/tasks/TASK-{id}_changes.log` | `track-file-changes.js` hook |
+| Execution snapshots | `.claude/reports/executions/` | `execution-report.js` hook |
+| Agent timeouts | Task record timeline | @team-lead (manual) |
+
+## Circuit Breaker Integration
+All error recovery feeds into the circuit breaker:
+- 3 consecutive tool failures for same agent -> count as 1 loop iteration
+- Agent timeout -> count as 1 loop iteration
+- Session failure -> pause loop counter (external issue, not agent issue)
+- When loop hits max -> STOP and escalate to user

package/template/.claude/docs/best-practices.md

@@ -0,0 +1,93 @@
+# Claude Code Best Practices Reference
+
+## CLAUDE.md
+- Max 150 lines root (hard limit 200), 80 per module, 50 per rule
+- Use @imports for external content (max 5 hops depth)
+- Specific instructions only — never vague
+- Don't repeat what linter/formatter config already enforces
+- Don't duplicate README or docs content
+
+## Skills
+- Frontmatter: name (lowercase, hyphens, max 64 chars), description (third-person, triggers, max 1024 chars)
+- `context: fork` for heavy/exploration skills
+- `disable-model-invocation: true` for side-effect skills (deploy, send, workflow)
+- `argument-hint` for skills that accept arguments
+- `user-invocable: true` for user-facing skills
+- Under 500 lines including supporting files
+- Progressive disclosure: ~100 token description at startup, ~5k full load
+
+## Agents (Role-Based Team)
+- 12 agents required: 4 SDLC roles + 5 core + 3 dev (conditional)
+- SDLC roles: team-lead, architect, product-owner, qa-lead
+- Core: explorer, reviewer, security, debugger, tester
+- Dev (conditional): frontend, api-builder, infra
+- `permissionMode: plan` for read-only agents
+- `disallowedTools: Edit, Write` on read-only agents (belt-and-suspenders)
+- `memory: project` for cross-session persistence on all agents
+- `isolation: worktree` for parallel dev agents (frontend, api-builder)
+- `maxTurns` to prevent runaway
+- Model: haiku (fast), sonnet (routine), opus (complex)
+- Scope MCP servers per agent via `mcpServers:` field, not global
+- Every agent MUST have: structured output format, HANDOFF block, Limitations section
+
+## Agent Communication
+- Subagents CANNOT spawn other subagents — all coordination via main context or workflow skill
+- Use structured HANDOFF blocks for every agent transition
+- Track loop iterations in task records (survives compaction)
+- Circuit breakers: dev-test max 5, review max 3, QA-bug max 3
+
+## Hooks
+- Exit 0 = proceed, exit 2 = block (stderr = reason)
+- Matcher is case-sensitive regex
+- Use Node.js for cross-platform (no bash/jq dependency)
+- `model: "haiku"` for prompt hooks (cost efficiency)
+- SessionStart with "compact" matcher to re-inject context
+- All hooks in settings.json must point to existing .js files
+
+## Context Window
+- Startup: under 20% (CLAUDE.md + memory + skill metadata + MCP tools)
+- Working: under 60%
+- MCP servers: ~200-2k tokens EACH, always loaded
+- Skills: ~100 tokens metadata, ~5k when active
+- Agent descriptions: ~100 tokens each at startup
+- `/context` to check, `/compact "focus"` to compress, `/clear` between tasks
+- Prefer skills over MCP (on-demand vs always-on)
+
+## Settings
+- `.claude/settings.json` — project (committed), with `permissions.defaultMode`
+- `.claude/settings.local.json` — personal (gitignored)
+- `permissions.allow` uses `Bash(command pattern)` format
+- `permissions.deny` uses `Bash(command pattern)` format
+- Must include `env` section (even if empty)
+- All hooks must be registered — orphan hook files are not executed
+- No secrets in committed files
+
+## Session Management
+- `/clear` between unrelated tasks
+- `claude --continue` to resume
+- `claude --worktree "name"` for parallel work
+- `/compact "focus on X"` for targeted compression
+- One major task per session for large features
+
+## Execution Reports
+- Every agent MUST include `execution_metrics` in their HANDOFF block
+- Metrics: turns_used, files_read/modified/created, tests_run, coverage_delta
+- Self-checks: hallucination_flags (verify file refs, function names, conventions)
+- Self-checks: regression_flags (test failures, lint/type errors, build status)
+- Confidence: HIGH/MEDIUM/LOW self-assessment
+- @team-lead aggregates metrics and triggers `/execution-report` per phase
+- Stop hook auto-captures snapshot and forces report generation
+- Scores: success (0-100), hallucination (0-3), regression (0-3)
+- Block advancement if hallucination >= 2 or regression >= 2
+- Reports saved to `.claude/reports/executions/`
+
+## Prompt Engineering
+- Include verification criteria (tests, expected output)
+- Plan mode for exploration, normal mode for implementation
+- Reference files with `@path/to/file`
+- Break large tasks into phases
+- Point to existing code as examples
+- "Fix root cause, not symptom"
+- Structured output format in agent prompts
+- Chain-of-thought guidance for complex reasoning (debugger, architect)
+- Explicit DO NOT boundaries prevent role bleed

package/template/.claude/docs/commands-template.md

@@ -0,0 +1,73 @@
+# Master Command Reference Template
+
+Generate this as `.claude/docs/commands.md` with actual values.
+
+## 1. Claude Code CLI
+| Command | Purpose |
+|---------|---------|
+| `claude` | Start new session |
+| `claude --continue` | Resume last session |
+| `claude --resume "name"` | Resume named session |
+| `claude -p "prompt"` | Non-interactive mode |
+| `claude --agent name` | Start with agent persona |
+| `claude --worktree "name"` | Parallel isolated work |
+| `claude --permission-mode plan` | Read-only mode |
+| `claude --fast` | Fast output mode |
+
+## 2. Session Commands
+`/help`, `/clear`, `/compact`, `/compact "focus"`, `/context`, `/cost`, `/model`, `/fast`, `/rewind`, `/rename "name"`, `/mcp`, `/config`, `/agents`, `Shift+Tab` (permission mode), `Alt+T` (thinking), `Esc` (stop)
+
+## 3. Slash Skills
+Workflow: `/workflow new|status|plan|dev|review|qa|deploy`, `--hotfix`, `--spike`
+Tracking: `/task-tracker create|status|update|report|dashboard|history|blockers|metrics`
+Development: `/add-feature`, `/add-endpoint`, `/add-component`, `/add-page`, `/fix-bug`, `/migrate`, `/onboard`, `/architecture`
+Review: `/review-pr`, `/impact-analysis`, `/design-review`, `/qa-plan`
+Reports: `/progress-report dev|qa|business|management|executive`, `/metrics velocity|quality|cycle-time|agents|all`, `/standup`, `/execution-report [task-id|last|all] [--phase N]`
+Sync: `/sync --check`, `/sync --fix`, `/sync --fix --component agents|skills|rules|hooks|claude-md`, `/sync --full-rescan`
+Deploy: `/signoff qa|business|tech`, `/deploy staging|production`, `/rollback deploy|code|phase [task-id]`
+Context: `/context-check`
+Smithery: `/discover-skills`
+
+## 4. Agent Team (@-mentions)
+
+### SDLC Role Agents
+| Agent | Role | Access | Responsibility |
+|-------|------|--------|---------------|
+| `@team-lead` | Tech Lead | Read/Write | Orchestrates, assigns, tech sign-off |
+| `@architect` | Architect | Read-only | Design review, system design |
+| `@product-owner` | Product Owner | Read-only | Acceptance criteria, biz sign-off |
+| `@qa-lead` | QA Lead | Read-only | QA planning, QA sign-off |
+
+### Core Agents
+| Agent | Role | Access | Responsibility |
+|-------|------|--------|---------------|
+| `@explorer` | Investigator | Read-only | Codebase exploration, impact mapping |
+| `@reviewer` | Reviewer | Read-only | Code quality, conventions |
+| `@security` | Security | Read-only | Vulnerability review, OWASP |
+| `@debugger` | Debugger | Read/Write | Root cause analysis, bug fixes |
+| `@tester` | Tester | Read/Write | Automated tests, coverage |
+
+### Dev Agents (generated based on codebase)
+| Agent | Role | Access | Responsibility |
+|-------|------|--------|---------------|
+| `@api-builder` | Backend Dev | Read/Write + worktree | Endpoints, services |
+| `@frontend` | Frontend Dev | Read/Write + worktree | Components, pages |
+| `@infra` | DevOps | Read/Write | Docker, CI/CD, deployment |
+
+## 5. Project Commands (fill from TECH_MANIFEST)
+Dev: `{install}`, `{dev}`, `{build}`
+Test: `{test_all}`, `{test_single}`, `{coverage}`, `{e2e}`
+Quality: `{lint}`, `{format}`, `{type_check}`, `{audit}`
+DB: `{migrate_create}`, `{migrate_run}`, `{migrate_rollback}`, `{seed}`
+Infra: `{docker_dev}`, `{staging_deploy}`, `{prod_deploy}`, `{rollback}`, `{health_check}`
+
+## 6. Git Workflow
+Branch: `git checkout -b {prefix}/<name>`
+Commit: `git commit -m "{format}: description"`
+PR: `gh pr create`, `gh pr checks`, `gh pr merge --{strategy}`
+
+## 7. Smithery CLI
+`smithery skill search|add`, `smithery mcp search|add|list|remove`, `smithery tool list|find`, `smithery auth login`
+
+## 8. Setup Scripts
+`.claude/scripts/verify-setup.js` (cross-platform Node.js)

package/template/.claude/docs/conflict-resolution-protocol.md

@@ -0,0 +1,82 @@
+# Conflict Resolution Protocol
+
+## When Conflicts Happen
+
+Parallel agents using `isolation: worktree` (like @api-builder + @frontend in fullstack tasks) work on isolated copies of the repo. Conflicts arise when both modify:
+- Shared type definitions
+- Shared utility functions
+- Package.json / lock files
+- Configuration files
+- API contracts (one side produces, other consumes)
+
+## Prevention (Before Parallel Work)
+
+### 1. API Contract First
+Before splitting into parallel:
+1. @architect defines the API contract (request/response shapes, endpoints)
+2. Both agents receive the contract in their HANDOFF
+3. @api-builder implements the backend matching the contract
+4. @frontend implements against the contract (can mock until backend ready)
+
+### 2. File Ownership Boundaries
+@team-lead explicitly assigns file boundaries:
+```
+@api-builder scope: src/api/**, src/services/**, src/models/**, migrations/**
+@frontend scope: src/components/**, src/pages/**, src/hooks/**, src/styles/**
+SHARED (neither modifies without coordination): src/types/**, src/utils/**, package.json
+```
+
+### 3. Shared Files Protocol
+For files both agents need to modify:
+1. @team-lead creates the shared changes FIRST (types, interfaces, utils)
+2. Both agents receive the updated shared files in their worktree
+3. Neither agent modifies shared files during parallel work
+
+## Resolution (After Parallel Work)
+
+### Merge Order
+1. **Backend first**: @api-builder's worktree merges to main branch
+2. **Resolve types**: @team-lead resolves any type/interface conflicts
+3. **Frontend second**: @frontend's worktree merges, adapting to final backend
+
+### Conflict Resolution Steps
+1. **Detect**: `git merge --no-commit` to preview conflicts
+2. **Classify**:
+   - **Trivial**: Both added to same file but different sections -> auto-merge
+   - **Type conflict**: Shared interface changed differently -> @architect decides
+   - **Logic conflict**: Both modified same function -> @team-lead reviews both approaches
+3. **Resolve**:
+   - For type conflicts: choose the version matching the API contract
+   - For logic conflicts: @reviewer examines both, picks or combines
+   - For package.json: merge deps from both, regenerate lock file
+4. **Verify**: Run full test suite after merge
+5. **Log**: Record conflict resolution in task record Decision Log
+
+### If Auto-Merge Fails
+```
+@team-lead:
+1. Read both worktree diffs
+2. Identify conflicting files
+3. For each conflict:
+   a. Determine which agent's version is correct per the API contract
+   b. If both are valid partial changes, manually combine
+   c. If fundamentally incompatible, @architect redesigns the shared interface
+4. Apply resolution
+5. Run tests
+6. Log decision
+```
+
+## Task Record Entry
+```markdown
+### Conflict Resolution
+| Timestamp | Files | Agents | Resolution | Decided By |
+|-----------|-------|--------|-----------|------------|
+| {ts} | src/types/api.ts | @api-builder vs @frontend | Used backend types, frontend adapted | @team-lead |
+```
+
+## Cross-Task Dependencies
+When TASK-002 depends on TASK-001:
+1. Add to TASK-002 frontmatter: `depends-on: TASK-001`
+2. TASK-002 cannot enter Phase 5 (Development) until TASK-001 reaches Phase 8 (PR+CI)
+3. @team-lead enforces this ordering
+4. If TASK-001 is blocked, TASK-002 is automatically blocked with reason

package/template/.claude/docs/context-budget.md

@@ -0,0 +1,54 @@
+# Context Window Deep Reference
+
+## What Consumes Context
+
+### Always Loaded (every request)
+- System prompt: ~2,000 tokens
+- Root CLAUDE.md: ~15 tokens/line (150 lines ≈ 2,250 tokens)
+- @-imports: counted in CLAUDE.md budget
+- Auto memory (MEMORY.md first 200 lines): ~2,000 tokens
+- Skill descriptions (ALL installed): ~100 tokens each
+- Agent descriptions (ALL defined): ~100 tokens each
+- MCP server tool definitions: ~200-2,000 tokens EACH (expensive!)
+- Active rules (matching current paths): ~500 tokens each
+- Conversation history: grows with each turn
+
+### On-Demand
+- Full skill content: ~3,000-5,000 tokens
+- Module CLAUDE.md: ~1,000-2,000 tokens
+- File reads / Bash output: varies
+
+### Zero Cost on Parent
+- Subagent context (runs in separate window)
+- Skills with `context: fork`
+- Templates, profiles (never auto-loaded)
+- Hook scripts, settings values
+
+## Budget Calculator
+```
+System prompt:                2,000
++ CLAUDE.md lines × 15:      _____ (150 lines = 2,250)
++ Memory × 15:               _____ (estimate 2,000)
++ Skills × 100:              _____ (15 skills = 1,500)
++ Agents × 100:              _____ (8 agents = 800)
++ MCP servers × 800:         _____ (3 servers = 2,400)
+= STARTUP TOTAL:             _____ tokens
+
+Model context: 200,000 tokens
+Startup %: (total ÷ 200,000) × 100
+
+Target: startup < 20%, working < 60%
+```
+
+## Compaction
+- Auto at ~95% (configurable via CLAUDE_AUTOCOMPACT_PCT_OVERRIDE)
+- Manual: `/compact "focus on auth changes"`
+- Re-inject after compact via SessionStart hook
+
+## Strategy Decision Tree
+- Explore codebase? → subagent (context: fork)
+- Heavy skill? → context: fork
+- Quick check? → Grep/Glob directly
+- Multiple tasks? → /clear between or worktrees
+- Getting slow? → /compact or /clear
+- New skill/MCP? → /context-check before and after