claude-code-scanner 1.0.0

package/template/.claude/skills/workflow/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: workflow
+description: Full SDLC workflow orchestrator. Coordinates agents from task intake through production deployment. Use when starting new work, checking task status, or managing the development lifecycle.
+user-invocable: true
+disable-model-invocation: true
+context: fork
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob, Agent
+argument-hint: "new|status|plan|dev|review|qa|deploy|resume [description|TASK-id] [--hotfix] [--spike]"
+effort: high
+---
+
+# Workflow: $ARGUMENTS
+
+Orchestrate the full development lifecycle. No phase advances until exit criteria are met.
+
+## Commands
+- `/workflow new "description"` — Full flow from Phase 1
+- `/workflow new --hotfix "issue"` — Skip design/biz, fast-track to deploy
+- `/workflow new --spike "question"` — Research only, no code (ends at CLOSED)
+- `/workflow status` — All active tasks
+- `/workflow resume TASK-id` — Resume ON_HOLD or interrupted task
+- `/workflow cancel TASK-id` — Cancel task with cleanup
+- `/workflow plan|dev|review|qa|deploy TASK-id` — Jump to phase
+
+## Concurrency Rule
+**ONE active workflow at a time.** Before starting `/workflow new`, check `.claude/tasks/` for any task in an active state (DEVELOPING, DEV_TESTING, REVIEWING, etc.). If found:
+- Prompt user: "TASK-{id} is active. Options: (1) pause it to ON_HOLD, (2) cancel it, (3) abort new workflow"
+- Do NOT start a second concurrent workflow
+
+## Orchestration Model
+**IMPORTANT:** Subagents cannot spawn other subagents. All agent-to-agent coordination flows through THIS workflow skill. When Phase N requires multiple agents, invoke them sequentially or in parallel from here — never expect one agent to call another.
+
+**ALL handoffs route through this orchestrator.** When flow-engine describes "@debugger fixes, handoff to @tester", the actual path is: @debugger -> HANDOFF to orchestrator -> orchestrator invokes @tester.
+
+## Agent Team
+| Role | Agent | Responsibility |
+|------|-------|---------------|
+| Coordination | @team-lead | Assigns work, resolves blockers, tech sign-off |
+| Architecture | @architect | Design review, system design |
+| Business | @product-owner | Acceptance criteria, business sign-off |
+| QA Strategy | @qa-lead | QA planning, QA sign-off |
+| Backend Dev | @api-builder | API endpoints, services |
+| Frontend Dev | @frontend | UI components, pages |
+| Testing | @tester | Write and run automated tests |
+| Debugging | @debugger | Root cause analysis, bug fixes |
+| Code Review | @reviewer | Quality, conventions |
+| Security | @security | Vulnerability review |
+| Investigation | @explorer | Codebase exploration, impact mapping |
+| Infrastructure | @infra | Docker, CI/CD, deployment |
+
+## Handoff Protocol
+Every agent transition MUST include a structured handoff:
+```
+HANDOFF:
+  from: @agent-name
+  to: @next-agent
+  reason: why this handoff is happening
+  artifacts:
+    - list of files/docs produced
+  context: |
+    Summary of what was done and key decisions
+  iteration: N/max (if in a loop)
+```
+
+## Context Budget Protocol
+**Note:** This workflow runs in `context: fork`. The `/context-check` skill measures the fork's own context, not the parent. Between heavy phases, compact the fork's context:
+1. Update task record with current phase status (persisted to disk)
+2. If responses feel slow or truncated: `/compact "focus on TASK-{id} Phase {N}"`
+3. After compaction: re-read task file to restore loop state
+
+---
+
+## Prerequisite Validation
+Before advancing ANY phase, check:
+1. **Dependencies:** If task has `depends-on: TASK-X`, verify TASK-X has reached at least Phase 8 (CI_PENDING). If not, BLOCK with reason.
+2. **Task record exists:** `.claude/tasks/TASK-{id}.md` must exist and be readable.
+3. **Previous phase exit criteria met:** Read task record, confirm previous phase output sections are populated.
+
+---
+
+## VARIANT: Hotfix Fast-Track
+
+When `--hotfix` flag is present:
+```
+Phase 1 (Intake: type=hotfix) -> Phase 2 (Impact, abbreviated)
+  -> SKIP Phase 3 (Architecture) and Phase 4 (Business)
+  -> Phase 5 (Dev: @debugger as primary, not @api-builder)
+  -> Phase 6 (Dev-Test: max 3 iterations, not 5)
+  -> Phase 7 (Review: @reviewer + @security, max 2 iterations)
+  -> Phase 8 (PR + CI: max 2 attempts)
+  -> Phase 9 (QA: verify-only — @qa-lead confirms fix, no full test plan)
+  -> Phase 10 (Tech sign-off ONLY — skip QA formal + business sign-off)
+  -> Phase 11 (Deploy: max 1 attempt, rollback immediately on failure)
+  -> Phase 12 (Post-Deploy: monitor 15min, not 30)
+```
+
+**Hotfix circuit breakers (tighter):**
+- Dev-test: max 3 (not 5)
+- Review: max 2 (not 3)
+- CI: max 2 (not 3)
+- Deploy: max 1 (immediate rollback on failure)
+- If any breaker trips: rollback + escalate immediately
+
+---
+
+## VARIANT: Spike (Research Only)
+
+When `--spike` flag is present:
+```
+Phase 1 (Intake: type=spike) -> create task record, NO branch
+  -> Phase 2 (Impact Analysis: @explorer only, no @security)
+  -> Phase 3 (Architecture: @architect + @explorer investigate the question)
+  -> SKIP Phase 4-12 (no code, no tests, no deploy)
+  -> Output: Research Report saved to task record
+    - Question investigated
+    - Findings with file:line refs
+    - Recommendation: proceed as feature / not viable / needs more research
+    - Estimated complexity if proceeding
+  -> Task status: CLOSED (type: spike)
+  -> If recommendation is "proceed as feature": prompt user to run
+    `/workflow new "description based on spike findings"`
+```
+
+**Spike has NO loops, NO circuit breakers, NO sign-offs.**
+
+---
+
+## Phase 1: Task Intake
+**Drift check (automatic):** Run `/sync --check` silently. If drift detected:
+- Minor drift (1-3 items): log warning in task record, continue
+- Major drift (4+ items or tech stack change): prompt user "Environment may be stale. Run `/sync --fix` before continuing? (y/N)"
+- If user says yes: run `/sync --fix`, then continue intake
+- If user says no: continue with warning logged
+
+Classify type (feature/bugfix/refactor/hotfix/spike), scope (frontend/backend/fullstack/infra), complexity (small/medium/large). Create branch (except spike). Log to `.claude/tasks/TASK-{id}.md`.
+
+**State: INTAKE**
+
+## Phase 2: Impact Analysis
+Run @explorer + @security in PARALLEL (spike: @explorer only).
+- Files affected, blast radius, test coverage, security flags
+- Risk: LOW/MEDIUM/HIGH/CRITICAL
+- Exit: impact report generated
+
+**State: ANALYZING**
+
+## Phase 3: Architecture Review
+**Skip condition (automatic):** Skip if ALL of: complexity == small AND risk == LOW AND type != refactor.
+If skipped, log in task record: "Phase 3 skipped: small + LOW risk."
+If NOT skipped: @architect designs solution. User approves before proceeding.
+
+**State: DESIGNING -> APPROVED (on user approval)**
+
+## Phase 4: Business Analysis
+@product-owner generates acceptance criteria (GIVEN/WHEN/THEN). User confirms.
+**Skip condition:** Skip if type == hotfix OR type == refactor OR type == tech-debt.
+
+**State: APPROVED (after user confirms criteria)**
+
+## Phase 5: Development
+@team-lead assigns by scope. **Sub-steps are conditional:**
+
+| Sub-step | Runs When | Agent |
+|----------|-----------|-------|
+| 5a: DB migrations | scope includes backend AND database changes detected | @api-builder |
+| 5b: Backend code | scope includes backend | @api-builder |
+| 5c: Frontend code | scope includes frontend | @frontend |
+| 5d: Tests | always (even infra tasks get smoke tests) | @tester |
+
+**Fullstack parallel execution:**
+1. 5a runs FIRST (DB must be ready before code)
+2. 5b + 5c run in PARALLEL (using isolation: worktree)
+3. @api-builder's worktree merges FIRST (backend defines API contract)
+4. @team-lead resolves any type/interface conflicts
+5. @frontend's worktree merges SECOND (adapts to final backend)
+6. 5d runs AFTER merge (tests against merged code)
+
+**If one parallel agent finishes early:** It waits. The orchestrator does NOT advance that agent to Phase 6 independently — both must complete Phase 5 before either enters Phase 6.
+
+**State: DEVELOPING**
+
+## Phase 6: Dev Self-Testing
+@tester runs FIRST. Measure coverage baseline at Phase 5 end.
+**Loop (max 5 iterations):**
+1. Orchestrator invokes @tester -> full test suite
+2. ALL PASS + coverage >= baseline -> EXIT to Phase 7
+3. FAILURES -> route to fix agent by issue type
+4. Fix agent applies fix -> HANDOFF back
+5. Re-invoke @tester (increment iteration)
+6. **Agent timeout:** If fix agent hits maxTurns, count as 1 loop iteration, re-invoke with narrowed scope
+7. Iteration 5 -> CIRCUIT BREAKER
+
+Track: `dev-test-loop: N/5`, `coverage-baseline`, `coverage-current`, `fix-agent`, `last-failure`
+
+**State: DEV_TESTING**
+
+## Phase 7: Code Review
+@reviewer + @security in PARALLEL. Stricter verdict wins if split.
+**Loop (max 3 iterations):**
+1. BOTH APPROVE -> EXIT to Phase 8
+2. SPLIT DECISION -> only re-review with rejecting agent
+3. REQUEST_CHANGES -> route fixes by category to appropriate dev agent
+4. Partial re-review (only the agent(s) that requested changes)
+5. **Agent timeout:** Reviewer timeout = count as iteration, re-invoke
+6. Iteration 3 -> CIRCUIT BREAKER
+
+Track: `review-loop: N/3`, `reviewer-status`, `security-status`, `open-comments`
+
+**State: REVIEWING**
+
+## Phase 8: PR + CI
+Create PR, wait for CI.
+**Loop (max 3 iterations):**
+1. CI fails -> classify failure -> route to fix agent
+2. Fix -> push -> CI re-runs
+3. Substantive fix (logic change): flag for Phase 7 re-review
+4. **Agent timeout:** CI fix agent timeout = count as iteration
+5. Iteration 3 -> CIRCUIT BREAKER
+
+Track: `ci-fix-loop: N/3`, `last-ci-failure`, `fix-agent`
+
+**State: CI_PENDING**
+
+## Phase 9: QA Testing
+1. @qa-lead creates QA test plan
+2. @tester executes automated scenarios (this is how @qa-lead gets test execution — @qa-lead plans, @tester executes)
+3. @qa-lead reviews results, files bug reports
+
+**Bug loop (max 3 per bug, 15 total):**
+- Priority order: P0 -> P1 -> P2. P3/P4 logged as known issues.
+- Per bug: @debugger fixes -> @tester regression suite -> @qa-lead re-verifies
+- P2: @qa-lead decides — must-fix or CONDITIONAL with workaround doc
+- Per-bug iteration 3 -> escalate THAT bug to @team-lead
+- Total > 15 -> escalate entire Phase 9
+
+Track: `qa-bug-loop` per bug, `total-bugs`, `regression-check-after-each-fix: true`
+
+**State: QA_TESTING**
+
+## Phase 10: Sign-offs (max 2 full rejection cycles)
+Sequential gates:
+1. **QA sign-off** -> @qa-lead
+2. **Business sign-off** -> @product-owner (skip if hotfix/refactor/tech-debt)
+3. **Tech sign-off** -> @team-lead
+
+**Sign-off preservation on rejection:**
+| Rejection | QA Approval | Biz Approval | Route To |
+|-----------|-------------|-------------|----------|
+| @qa-lead (bugs) | INVALIDATED | INVALIDATED | Phase 5 -> Phase 6 -> 7 -> 8 -> 9 -> 10 |
+| @product-owner (reqs) | PRESERVED | INVALIDATED | Phase 4 -> Phase 5 -> ... -> 10 |
+| @product-owner (UI) | PRESERVED | INVALIDATED | Phase 5c -> 6 -> 7 -> 8 -> 9 -> 10 |
+| @team-lead (architecture) | INVALIDATED | INVALIDATED | Phase 3 -> full re-flow |
+| @team-lead (perf/tests) | PRESERVED | PRESERVED | Phase 5 -> 6 -> 7 -> 8 -> 9 -> 10 |
+
+**On re-entry:** ALL inner loop counters reset to 0. Signoff-rejection-cycle increments.
+**Cycle 2 -> CIRCUIT BREAKER:** escalate to user (continue, re-scope, split, cancel)
+
+Track: `signoff-rejection-cycle: N/2`, per-gate status
+
+**States: QA_SIGNOFF -> BIZ_SIGNOFF -> TECH_SIGNOFF**
+
+## Phase 11: Deployment (max 2 attempts)
+@infra: pre-checks -> merge PR -> deploy -> health check -> smoke test.
+**On failure — triage first:**
+- Config/env -> @infra fixes -> retry directly
+- Code bug -> @debugger hotfix -> fast-track Phase 6->7->8->11
+- Infra issue -> @infra resolves -> retry
+- Unknown -> `/rollback`, escalate to user
+Attempt 2 fails -> rollback + escalate.
+
+Track: `deploy-loop: N/2`, `last-deploy-failure`, `rollback-executed`
+
+**State: DEPLOYING**
+
+## Phase 12: Post-Deploy
+Monitor 30min (hotfix: 15min). Close issues. Notify stakeholders.
+Production bugs: P0/P1 -> new hotfix workflow, P2/P3 -> new task.
+
+**State: MONITORING -> CLOSED**
+
+## Phase 13: Execution Report
+Generated by the orchestrator (NOT the Stop hook — Stop hook handles session-level reports, Phase 13 handles workflow-level reports):
+- **Per-phase reports:** Generated after each phase completes, saved to `.claude/reports/executions/TASK-{id}_phase-{N}_{timestamp}.md`
+- **Final cumulative report:** Generated once after Phase 12, saved to `.claude/reports/executions/TASK-{id}_final.md`
+- **Stop hook:** Generates session-level snapshot only — does NOT duplicate Phase 13
+
+---
+
+## ON_HOLD Management
+- **Enter:** Any sign-off gate defers, or user explicitly pauses
+- **State preserved:** Task stays at its current phase, all loop counters preserved
+- **Resume:** `/workflow resume TASK-id` — re-enters at the saved phase
+- **Auto-reminder:** If ON_HOLD > 7 days, session-start hook warns user
+- **Cancel threshold:** If ON_HOLD > 30 days, prompt user to cancel or resume
+
+## CANCELLED Cleanup
+When `/workflow cancel TASK-id`:
+1. Set status to CANCELLED in task record
+2. Close any open PR: `gh pr close {pr_number}`
+3. Delete feature branch: `git branch -D {branch}` (local only — prompt for remote)
+4. Clean up worktrees: `git worktree remove` if any exist
+5. Log cancellation in task timeline with reason
+6. Task record stays in `.claude/tasks/` for historical reference
+
+## Task State Machine
+```
+BACKLOG -> INTAKE -> ANALYZING -> DESIGNING -> APPROVED -> DEVELOPING
+  -> DEV_TESTING -> REVIEWING -> CI_PENDING -> QA_TESTING
+  -> QA_SIGNOFF -> BIZ_SIGNOFF -> TECH_SIGNOFF
+  -> DEPLOYING -> MONITORING -> CLOSED
+
+Special states (from ANY active state):
+  -> BLOCKED (requires depends-on resolution or manual unblock)
+  -> ON_HOLD (user/product-owner deferred, resume with /workflow resume)
+  -> CANCELLED (cleanup executed, terminal state)
+
+Reverse transitions (rejection routing):
+  QA_SIGNOFF -> DEVELOPING (QA rejects)
+  BIZ_SIGNOFF -> APPROVED (reqs wrong) or DEVELOPING (UI wrong)
+  TECH_SIGNOFF -> DESIGNING (architecture) or DEVELOPING (perf/tests)
+```
+
+## Circuit Breaker Summary
+| Loop | Max | Scope | Hotfix Max |
+|------|-----|-------|------------|
+| Dev-Test (P6) | 5 | Global | 3 |
+| Review (P7) | 3 | Global | 2 |
+| CI Fix (P8) | 3 | Global | 2 |
+| QA Bug (P9) | 3/bug, 15 total | Per-bug | 2/bug, 6 total |
+| Sign-off (P10) | 2 cycles | Global | 1 cycle |
+| Deploy (P11) | 2 | Global | 1 |
+
+Any breaker tripped -> STOP -> escalate to user: continue, re-plan, reduce scope, cancel, assign to human.

package/template/.claude/templates/README.md

@@ -0,0 +1,42 @@
+# Code Templates
+
+This directory contains code scaffolding templates extracted from the REAL codebase during `/generate-environment`. Templates are NOT invented — they are skeletons derived from actual existing files.
+
+## How Templates Are Extracted
+1. Read 3-5 existing files of each type
+2. Identify the common skeleton (imports, structure, patterns, exports)
+3. Replace specific values with `{placeholder}` markers
+4. Save as a markdown file with the template in a code block
+
+## Expected Templates (generated per project)
+- `component.md` — UI component skeleton (if frontend exists)
+- `api-endpoint.md` — API route/handler/service skeleton (if backend API exists)
+- `service.md` — Business logic service skeleton
+- `model.md` — Data model/entity skeleton (if ORM exists)
+- `test.md` — Test file skeleton matching project patterns
+- `hook.md` — React hook / lifecycle hook skeleton (if applicable)
+- `migration.md` — Database migration skeleton (if migrations exist)
+- `middleware.md` — Middleware skeleton (if middleware pattern detected)
+
+## Template Format
+```markdown
+# Template: {type}
+Source: extracted from {list of source files}
+Pattern: {pattern name}
+
+\`\`\`{language}
+{template code with {placeholders}}
+\`\`\`
+
+## Usage
+{when to use this template}
+
+## Customization Points
+- {placeholder1}: {what to replace with}
+- {placeholder2}: {what to replace with}
+```
+
+## Important
+- Templates are EMPTY until `/generate-environment` runs
+- Never invent patterns — only extract from existing code
+- Update templates when codebase patterns change significantly

package/template/CLAUDE.md

@@ -0,0 +1,67 @@
+# Codebase Scanner & Claude Code Environment Generator
+
+You are a **Codebase Archaeology & Claude Code Setup Specialist**. Scan any existing codebase and generate a production-ready Claude Code environment.
+
+## What You Generate
+- `CLAUDE.md` (root + nested per module)
+- `.claude/rules/` — path-specific rules
+- `.claude/agents/` — role-based agent team (12 agents)
+- `.claude/skills/` — workflow skills
+- `.claude/settings.json` — permissions, hooks
+- `.claude/hooks/` — automation scripts
+- `.claude/templates/` — code scaffolding templates
+- `.claude/profiles/` — developer role profiles
+- `.claude/scripts/` — setup + verification scripts
+- `.claude/docs/commands.md` — master command reference
+
+## Execution Order
+
+### Phase 1: Scan (parallel subagents)
+Use `/scan-codebase` skill — spawns 6 agents to fingerprint the tech stack, directory structure, backend, frontend, architecture, domain knowledge, and tooling. Outputs a `TECH_MANIFEST`.
+
+### Phase 2: Generate
+Use `/generate-environment` skill — takes TECH_MANIFEST and produces all artifacts. Every `{placeholder}` replaced with real values from Phase 1.
+
+### Phase 3: Validate
+Use `/validate-setup` skill — checks line counts, JSON validity, hook permissions, context budget.
+
+### Phase 4: Setup Smithery
+Use `/setup-smithery` skill — installs matching Smithery skills and MCP servers based on tech stack.
+
+## Context Budget Rules
+- Root CLAUDE.md: recommended 150 lines (hard limit 200)
+- Rules: max 50 lines each, with `paths:` frontmatter
+- Skills: `context: fork` for heavy work
+- MCP servers: max 5, scoped to agents via `mcpServers:` field
+- Startup context: under 20%
+- Working context: under 60%
+- Run `/context` to verify
+
+## Agent Team (Role-Based)
+| Role | Agent | Access |
+|------|-------|--------|
+| Tech Lead | `@team-lead` | Read/Write — orchestrates, assigns, signs off |
+| Architect | `@architect` | Read-only — designs, reviews architecture |
+| Product Owner | `@product-owner` | Read-only — acceptance criteria, biz sign-off |
+| QA Lead | `@qa-lead` | Read-only — QA plans, QA sign-off |
+| Explorer | `@explorer` | Read-only — investigation, impact analysis |
+| Reviewer | `@reviewer` | Read-only — code review |
+| Security | `@security` | Read-only — vulnerability review |
+| API Dev | `@api-builder` | Read/Write — backend endpoints, services |
+| Frontend Dev | `@frontend` | Read/Write — UI components, pages |
+| Tester | `@tester` | Read/Write — automated tests |
+| Debugger | `@debugger` | Read/Write — bug fixes |
+| Infra | `@infra` | Read/Write — Docker, CI/CD, deployment |
+
+## Keeping In Sync
+- `/sync --check` — detect drift between environment and codebase (weekly recommended)
+- `/sync --fix` — auto-repair stale agents, skills, CLAUDE.md, rules, hooks
+- `/sync --full-rescan` — re-scan and regenerate everything
+- Drift detector runs automatically on every session start
+
+## Workflow After Setup
+- `/workflow new "task"` — full SDLC (intake -> impact -> design -> dev -> test -> review -> QA -> signoff -> deploy)
+- `/task-tracker status` — dashboard
+- See `.claude/docs/commands.md` for complete reference
+
+@.claude/rules/context-budget.md