claude-code-scanner 1.0.0

package/template/.claude/skills/execution-report/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: execution-report
+description: Generate post-execution analytics report after any prompt, phase, or workflow completion. Tracks token usage, context consumption, agent communication, success scoring, hallucination detection, and regression impact analysis.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[task-id|last|all] [--phase N] [--verbose]"
+---
+
+# Execution Report: $ARGUMENTS
+
+Generate a comprehensive post-execution analytics report. This runs automatically after every phase completion and on session Stop, or manually via `/execution-report`.
+
+## Data Collection
+
+### Step 1: Gather Execution Metadata
+Read the active task file from `.claude/tasks/TASK-{id}.md` and the changes log `TASK-{id}_changes.log`.
+
+Collect:
+- **Session ID:** `${CLAUDE_SESSION_ID}`
+- **Task ID:** from task file frontmatter
+- **Phase(s) completed:** from task timeline
+- **Start/end timestamps:** from timeline entries
+- **Agents invoked:** from handoff log
+
+### Step 2: Token & Context Analysis
+Run `/context` or estimate from artifacts:
+
+- **Prompt tokens (input):** estimated from files read + conversation history
+- **Completion tokens (output):** estimated from files written + responses
+- **Total tokens:** input + output
+- **Context window usage:** current % of context consumed
+- **Peak context usage:** highest % reached during execution
+- **Compaction events:** count of `/compact` triggers during execution
+- **Context efficiency score:** (useful output tokens / total tokens) * 100
+
+### Step 3: Agent Communication Analysis
+Read the Handoff Log from the task record:
+
+- **Agents activated:** list with invocation count
+- **Handoff count:** total agent-to-agent transitions
+- **Parallel executions:** count of parallel agent invocations
+- **Loop iterations:** count per loop type (dev-test, review, qa-bug)
+- **Escalations:** count of circuit breaker triggers
+- **Agent efficiency:** per-agent (tasks completed / turns used)
+
+| Agent | Invocations | Turns Used | Success | Rework | Efficiency |
+|-------|-------------|------------|---------|--------|------------|
+| @explorer | N | N | N | N | N% |
+| ... | | | | | |
+
+### Step 4: Success Scoring
+Calculate a composite success score (0-100):
+
+**Completeness Score (0-40 points):**
+- Phase exit criteria all met: +20
+- All acceptance criteria VERIFIED: +10
+- No skipped phases: +5
+- Task status advanced to expected state: +5
+
+**Quality Score (0-30 points):**
+- All tests pass: +10
+- Coverage maintained or increased: +5
+- No lint/type errors: +5
+- Code review APPROVED (no critical issues): +5
+- Security review clean: +5
+
+**Efficiency Score (0-30 points):**
+- Completed within expected turns: +10
+- No circuit breaker triggers: +5
+- Context stayed under 60%: +5
+- Loops resolved within first attempt: +5
+- No unnecessary agent invocations: +5
+
+**Score Interpretation:**
+- 90-100: EXCELLENT — clean execution
+- 70-89: GOOD — minor issues
+- 50-69: FAIR — rework or inefficiency detected
+- 30-49: POOR — significant issues
+- 0-29: FAILED — task incomplete or blocked
+
+### Step 5: Hallucination Detection
+Verify all generated artifacts against the actual codebase:
+
+**File Reference Check:**
+- Scan all file:line references in agent outputs
+- Verify each referenced file exists at that path
+- Verify line numbers are within file range
+- Flag any references to non-existent files/functions
+
+**API/Function Verification:**
+- Check all function names mentioned in generated code exist
+- Verify import paths resolve to real modules
+- Confirm API endpoints referenced actually exist in routes
+- Flag any invented or hallucinated identifiers
+
+**Convention Consistency:**
+- Compare generated code patterns against CLAUDE.md conventions
+- Check naming against existing codebase patterns
+- Verify generated test patterns match existing test files
+- Flag any patterns that don't match the project
+
+**Hallucination Score (0-3):**
+- 0: CLEAN — all references verified
+- 1: MINOR — cosmetic mismatches (wrong line numbers, outdated paths)
+- 2: MODERATE — referenced non-existent functions or wrong imports
+- 3: SEVERE — generated code based on invented APIs or wrong architecture
+
+### Step 6: Regression & Bug Impact Analysis
+Run the test suite and compare against baseline:
+
+```bash
+# Run the project's test command (check package.json scripts, Makefile, or CI config)
+# Examples: npm test, pytest, go test ./..., cargo test
+# Compare test count: before vs after
+# Compare coverage: before vs after
+```
+
+**Regression Checks:**
+- **Test suite result:** PASS/FAIL (count passing/failing/skipped)
+- **New test failures:** list of tests that passed before but fail now
+- **Coverage delta:** before% -> after% (flag if decreased)
+- **Lint check:** PASS/FAIL (new lint errors introduced?)
+- **Type check:** PASS/FAIL (new type errors introduced?)
+- **Build check:** PASS/FAIL (build still succeeds?)
+
+**Bug Impact Assessment:**
+- Files modified in this execution: list from changes log
+- Existing tests covering those files: list
+- Tests that changed from PASS to FAIL: list (these are regressions)
+- Files modified but lacking test coverage: list (risk areas)
+
+**Impact Score (0-3):**
+- 0: CLEAN — no regressions, coverage maintained
+- 1: LOW — coverage decreased slightly but no new failures
+- 2: MEDIUM — new test failures introduced
+- 3: HIGH — build broken or critical regressions
+
+## Output: Execution Report
+
+Save to `.claude/reports/executions/TASK-{id}_phase-{N}_{timestamp}.md`:
+
+```markdown
+# Execution Report: TASK-{id} Phase {N}
+
+## Summary
+| Metric | Value |
+|--------|-------|
+| Task | TASK-{id}: {title} |
+| Phase | {N}: {phase_name} |
+| Duration | {elapsed} |
+| Success Score | {score}/100 ({rating}) |
+| Hallucination Score | {0-3} ({level}) |
+| Regression Impact | {0-3} ({level}) |
+
+## Token & Context Usage
+| Metric | Value |
+|--------|-------|
+| Estimated Input Tokens | {N} |
+| Estimated Output Tokens | {N} |
+| Total Tokens | {N} |
+| Peak Context Usage | {N}% |
+| Compaction Events | {N} |
+| Context Efficiency | {N}% |
+
+## Agent Communication
+| Agent | Invocations | Turns | Success | Rework | Efficiency |
+|-------|-------------|-------|---------|--------|------------|
+| ... | | | | | |
+
+**Handoff Count:** {N}
+**Parallel Executions:** {N}
+**Loop Iterations:** dev-test {N}/5, review {N}/3, qa-bug {N}/3
+**Escalations:** {N}
+
+## Success Breakdown
+| Category | Score | Detail |
+|----------|-------|--------|
+| Completeness | {N}/40 | {detail} |
+| Quality | {N}/30 | {detail} |
+| Efficiency | {N}/30 | {detail} |
+| **Total** | **{N}/100** | **{rating}** |
+
+## Hallucination Check
+| Check | Result | Flags |
+|-------|--------|-------|
+| File references | {N} verified / {N} total | {list of bad refs} |
+| Function/API names | {N} verified / {N} total | {list of invented} |
+| Convention match | {N} consistent / {N} checked | {list of mismatches} |
+| **Score** | **{0-3}** | **{level}** |
+
+## Regression & Bug Impact
+| Check | Result |
+|-------|--------|
+| Test suite | {PASS/FAIL} ({passing}/{total}) |
+| New failures | {count} — {list} |
+| Coverage delta | {before}% -> {after}% ({+/-N}%) |
+| Lint check | {PASS/FAIL} |
+| Type check | {PASS/FAIL} |
+| Build check | {PASS/FAIL} |
+| Uncovered modified files | {list} |
+| **Impact Score** | **{0-3}** ({level}) |
+
+## Recommendations
+- {Actionable recommendation based on findings}
+- {e.g., "Add tests for src/api/handler.ts — modified but uncovered"}
+- {e.g., "Reduce context usage — 72% peak, consider splitting task"}
+```
+
+## Auto-Generation Trigger
+This report is automatically generated:
+1. After each workflow phase completion (appended to task record)
+2. On session Stop (summary report)
+3. On `/execution-report` manual invocation
+4. On workflow completion (final cumulative report)
+
+## Cumulative Report (on workflow completion)
+When the full workflow completes (Phase 12), generate a cumulative report at:
+`.claude/reports/executions/TASK-{id}_final.md`
+
+Includes:
+- Per-phase scores stacked
+- Total token usage across all phases
+- Agent utilization heatmap
+- Phase bottleneck analysis (which phase took most turns/time)
+- Overall success score (weighted average of phase scores)
+- Full hallucination audit
+- Full regression audit
+- Lessons learned (what should be different next time)

package/template/.claude/skills/generate-environment/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: generate-environment
+description: Generate complete Claude Code environment from scan results. Use after /scan-codebase completes.
+user-invocable: true
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+context: fork
+effort: high
+---
+
+# Generate Environment: $ARGUMENTS
+
+## Prerequisite Check
+Before generating, verify `.claude/scan-results.md` exists. If NOT found:
+1. Warn: "scan-results.md not found. Run /scan-codebase first."
+2. STOP — do NOT generate generic templates without scan data.
+3. Exit with instructions to run `/scan-codebase` first.
+
+Read `.claude/scan-results.md` (from /scan-codebase). Replace ALL `{placeholders}` with actual values. If a value wasn't found, OMIT that section — never leave placeholders.
+
+**Reference files in this skill directory:**
+- `artifact-templates.md` — full CLAUDE.md template, rule templates, settings.json, hook scripts, profiles, code template extraction instructions
+- `additional-skills.md` — all skill SKILL.md templates to generate
+- `domain-agents.md` — frontend, api-builder, infra agent templates
+
+## Generate These Files (in order):
+
+### 1. Root CLAUDE.md (max 150 lines)
+```
+# Project: {name}
+## Tech Stack (exact versions from scan)
+## Quick Commands (every build/test/lint/dev/migrate command)
+## Architecture (3-5 lines: type, pattern, data flow, auth, API style)
+## Code Style (ONLY rules differing from linter defaults)
+## Git Conventions (branch pattern, commit format, PR requirements)
+## Key Paths (entry points, handlers, services, models, tests, config, generated DO NOT EDIT)
+## Gotchas (non-obvious things with file:line refs)
+## Testing (framework, commands, patterns)
+@.claude/rules/domain-terms.md
+```
+
+### 2. Nested CLAUDE.md (per module, max 80 lines each)
+Only for monorepo packages or distinct modules.
+
+### 3. .claude/rules/ (max 50 lines each, with paths: frontmatter)
+- `domain-terms.md` — business glossary (paths: **/*)
+- `api.md` — endpoint conventions (paths: src/api/**)
+- `testing.md` — test patterns (paths: **/*.test.*, tests/**)
+- `database.md` — migration/query rules (paths: src/db/**, migrations/**)
+- `frontend.md` — component patterns (paths: src/components/**, app/**)
+- `security.md` — input validation, auth, PII rules (paths: src/auth/**, src/api/**)
+- `infrastructure.md` — Docker, CI, IaC rules (paths: Dockerfile*, .github/workflows/**)
+- Generate additional rules ONLY if codebase demands them.
+
+### 4. .claude/agents/ (see agents/ directory and domain-agents.md for templates)
+**Always generate (SDLC roles):** team-lead, architect, product-owner, qa-lead
+**Always generate (core):** explorer, reviewer, debugger, tester
+**Generate if layer exists:** frontend, api-builder, infra + domain-specific
+
+All agents MUST include:
+- `memory: project` for cross-session persistence
+- `disallowedTools` on read-only agents (Edit, Write, Bash)
+- `permissionMode: plan` on read-only agents
+- `isolation: worktree` on parallel dev agents (frontend, api-builder)
+- Structured output format section
+- HANDOFF block in output format
+- Limitations section with explicit DO NOT rules
+- Model: haiku (fast checks), sonnet (routine), opus (complex reasoning)
+- Set `maxTurns`, `effort`, `tools` per agent
+- Scope `mcpServers:` per agent
+
+### 5. .claude/skills/ (see skills/ directory for templates)
+Generate: workflow, onboard, add-feature, add-endpoint, add-component, add-page, fix-bug, review-pr, qa-plan, signoff, deploy, rollback, migrate, task-tracker, progress-report, metrics, standup, impact-analysis, design-review, discover-skills, architecture, execution-report, context-check, sync.
+- Heavy skills: `context: fork`
+- Side-effect skills: `disable-model-invocation: true`
+
+### 6. .claude/settings.json
+Permissions (allow trusted commands, deny dangerous), hooks (SessionStart, PreToolUse, PostToolUse, Notification, Stop), env vars.
+
+### 7. .claude/settings.local.json (gitignored)
+Machine-specific env vars template.
+
+### 8. .claude/hooks/ (cross-platform Node.js scripts)
+- protect-files.js — block edits to .env, lock files, CI configs (PreToolUse)
+- post-edit-format.js — auto-format after edits (PostToolUse)
+- validate-bash.js — block dangerous commands (PreToolUse)
+- session-start.js — re-inject context on startup/resume/compact (SessionStart)
+- track-file-changes.js — log file modifications to task changes log (PostToolUse)
+- notify-approval.js — OS notification when approval needed (Notification)
+- execution-report.js — capture execution snapshot on Stop (Stop)
+- tool-failure-tracker.js — log tool failures for debugging (PostToolUseFailure)
+- stop-failure-handler.js — handle rate limits, auth failures, preserve state (StopFailure)
+- pre-compact-save.js — save critical workflow state before compaction hits (PreCompact)
+- post-compact-recovery.js — re-inject loop state, handoffs, blockers after compaction (PostCompact)
+
+### 9. .claude/templates/ (extracted from REAL code, not invented)
+Read 3-5 existing files of each type, extract common skeleton.
+- component.md, api-endpoint.md, service.md, model.md, test.md, hook.md
+- Only generate templates for patterns that actually exist in the codebase.
+
+### 10. .claude/profiles/
+- backend.md, frontend.md, devops.md (only those relevant to the project)
+
+### 11. .claude/docs/commands.md
+Master command reference: Claude CLI, session commands, /slash skills, @agent mentions, build/test/lint commands, git workflow, Smithery CLI.
+
+### 12. .gitignore additions
+```
+.claude/settings.local.json
+.claude/agent-memory-local/
+.claude/tasks/
+.claude/reports/
+```
+
+## Validation After Generation
+- Count CLAUDE.md lines (must be under 150)
+- Validate settings.json with `JSON.parse()` or `node -e`
+- Check hook .js scripts exist
+- Test that build/test/lint commands actually work
+- Verify no placeholder `{...}` values remain
+
+## Update Manifest
+After generation, create/update `.claude/manifest.json`:
+- Set `last_sync` and `last_scan` to current ISO timestamp
+- Hash every generated file (agents, skills, hooks, rules, CLAUDE.md)
+- Record tech stack dependency file hashes (package.json, etc.)
+- Record project structure (source dirs, test dirs, config files)
+- Record CLAUDE.md line count and agent count
+This manifest enables `/sync` to detect drift in future sessions.

package/template/.claude/skills/generate-environment/additional-skills.md

@@ -0,0 +1,276 @@
+# Additional Skill Templates to Generate
+
+## Always Generate
+
+### /onboard
+```yaml
+---
+name: onboard
+description: Onboard a new developer. Use when someone is new to the project.
+user-invocable: true
+context: fork
+agent: explorer
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[area or topic to focus on]"
+---
+Walk through: architecture overview, setup verification ({install_cmd}, {build_cmd}, {test_cmd}), domain terms, key concepts, first task guidance.
+Focus on $ARGUMENTS if provided.
+```
+
+### /add-feature
+```yaml
+---
+name: add-feature
+description: Scaffold a new feature following project patterns.
+user-invocable: true
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+argument-hint: "[feature description]"
+---
+1. Find closest existing pattern
+2. Scaffold files in correct directories with naming conventions
+3. Implement with proper error handling and logging
+4. Write tests following existing patterns
+5. Verify: {test_cmd} → {lint_cmd} → {build_cmd}
+```
+
+### /fix-bug
+```yaml
+---
+name: fix-bug
+description: Systematic bug fixing. Use when something is broken.
+user-invocable: true
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+argument-hint: "[bug description or error message]"
+---
+1. Reproduce with failing test
+2. Trace code path from entry to failure
+3. Fix root cause (not symptom)
+4. Verify: failing test passes, no regressions
+Run {test_cmd} after fix.
+```
+
+### /review-pr
+```yaml
+---
+name: review-pr
+description: Review a PR against project standards.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[PR-number]"
+---
+`gh pr diff $0` — check conventions, tests, security, performance, backward compatibility.
+Output: APPROVE/CHANGES_REQUESTED with file:line comments.
+```
+
+### /design-review
+```yaml
+---
+name: design-review
+description: Architecture and design review for proposed changes.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash, Agent
+argument-hint: "[change description]"
+---
+@explorer: analyze fit with existing architecture, propose file locations, compare alternatives, flag breaking changes. Output Mermaid diagram.
+```
+
+### /qa-plan
+```yaml
+---
+name: qa-plan
+description: Generate QA test plan for current changes.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+---
+Analyze `git diff {base}...HEAD`. Generate: happy path scenarios, error/edge cases, regression tests, performance checks, cross-browser matrix. Format as checkable table.
+```
+
+### /signoff
+```yaml
+---
+name: signoff
+description: Generate sign-off request for QA, business, or tech lead.
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[qa|business|tech] [task-id]"
+---
+qa: test results, known issues, recommendation.
+business: acceptance criteria verification, demo URL, impact, rollback plan.
+tech: all prior sign-offs, architecture/security review status, merge strategy.
+```
+
+### /deploy
+```yaml
+---
+name: deploy
+description: Deploy with pre/post checks.
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: Read, Bash, Grep, Glob
+argument-hint: "[staging|production] [pr-number]"
+---
+Pre-checks → merge PR → deploy → health check → smoke test. Rollback on failure.
+```
+
+### /standup
+```yaml
+---
+name: standup
+description: Auto-generate daily standup from active task data.
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash
+---
+Read .claude/tasks/. Output: yesterday (completed), today (planned), blockers, metrics.
+```
+
+### /discover-skills
+```yaml
+---
+name: discover-skills
+description: Search Smithery for matching skills and install them.
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: Bash
+---
+`smithery skill search "$ARGUMENTS"` → evaluate match → install → `/context` to verify budget.
+```
+
+### /architecture
+```yaml
+---
+name: architecture
+description: Generate or explain project architecture.
+user-invocable: true
+context: fork
+agent: explorer
+allowed-tools: Read, Grep, Glob, Bash
+---
+System context, container diagram, component diagram, data flow, key decisions. Mermaid diagrams.
+```
+
+### /execution-report
+```yaml
+---
+name: execution-report
+description: Generate post-execution analytics report with success scoring, hallucination detection, and regression impact analysis.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[task-id|last|all] [--phase N] [--verbose]"
+---
+Collect execution metadata, calculate success score (0-100), check for hallucinations (verify file refs, function names, conventions), assess regression impact (test suite, coverage delta), and output scored report to .claude/reports/executions/.
+```
+
+### /sync
+```yaml
+---
+name: sync
+description: Detect drift between Claude Code environment and actual codebase. Updates CLAUDE.md, agents, skills, rules, hooks when roles change or project evolves.
+user-invocable: true
+context: fork
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob, Agent
+argument-hint: "[--check|--fix|--full-rescan] [--component agents|skills|rules|hooks|claude-md|all]"
+---
+Drift detection across 8 categories: agents, skills, hooks, rules, CLAUDE.md, settings, tech stack, structure.
+--check: report only. --fix: auto-repair. --full-rescan: re-scan + regenerate.
+Updates manifest.json for future drift tracking.
+```
+
+### /context-check
+```yaml
+---
+name: context-check
+description: Check current context usage and enforce the 60% working budget. Use between workflow phases or when responses feel slow.
+user-invocable: true
+allowed-tools: Read, Bash, Grep, Glob
+argument-hint: "[--compact] [--force]"
+---
+Run /context, evaluate against budget thresholds (GREEN <40%, YELLOW 40-60%, ORANGE 60-75%, RED 75%+).
+If ORANGE+: compact with focus on current task/phase. Log context pressure in task record.
+Auto-invoked between every workflow phase transition.
+```
+
+### /rollback
+```yaml
+---
+name: rollback
+description: Rollback a failed deployment, revert code changes, or undo a workflow phase.
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: Read, Bash, Grep, Glob
+argument-hint: "[deploy|code|phase] [task-id] [--to-commit SHA]"
+---
+Deploy rollback: revert merge, redeploy, health check.
+Code rollback: revert commits or close PR.
+Phase rollback: undo artifacts from target phase range, reset task status.
+Safety: never force-push, always create revert commit, always run tests after.
+```
+
+### /migrate
+```yaml
+---
+name: migrate
+description: Create database migrations.
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+argument-hint: "[migration description]"
+---
+Check schema → create migration file → write up/down → test → verify.
+```
+
+## Conditional Skills (generate ONLY if codebase has the layer)
+
+### /add-endpoint — Generate if backend API exists
+```yaml
+---
+name: add-endpoint
+description: Create new API endpoint following project patterns.
+user-invocable: true
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+---
+1. Find closest existing endpoint in `{routes_dir}` — READ it
+2. Create: route in `{routes_dir}`, handler in `{handlers_dir}`, schema in `{schemas_dir}`, service in `{services_dir}`
+3. Add validation using {validation_library}, auth using {auth_pattern}
+4. Write tests in `{api_test_dir}`: happy path, validation errors, auth errors, not found
+5. Verify: {test_cmd} → {lint_cmd} → {type_check_cmd}
+```
+
+### /add-component — Generate if frontend exists
+```yaml
+---
+name: add-component
+description: Create new UI component following project patterns.
+user-invocable: true
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+---
+1. Find similar component in `{component_dir}` — READ it for exact pattern
+2. Create: component `{ComponentName}.{ext}`, test `{ComponentName}.test.{ext}`, styles if co-located
+3. Follow: {prop_pattern}, {styling_approach}, {export_pattern}
+4. Write tests: render, behavior, props variations
+5. Verify: {frontend_test_cmd} → {frontend_build_cmd}
+```
+
+### /add-page — Generate if frontend has routing
+```yaml
+---
+name: add-page
+description: Create new page/route.
+user-invocable: true
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+---
+1. Pages in `{pages_dir}` use {file-based | config-based} routing
+2. READ existing page for: data loading pattern, layout, error handling
+3. Create page, set up data loading ({getServerSideProps | loader | useEffect})
+4. Apply layout, add navigation link
+5. Write test, verify with {dev_cmd}
+```
+
+### Additional conditional skills:
+- If i18n: `/add-translation` (translation file format + key naming)
+- If GraphQL: `/add-query`, `/add-mutation` (schema + resolver patterns)
+- If Storybook: `/add-story` (story format + decorators)
+- If WebSocket: `/add-channel` (event patterns)