claude-code-scanner 1.0.0

package/template/.claude/skills/generate-environment/artifact-templates.md

@@ -0,0 +1,386 @@
+# Artifact Templates for Generation
+
+## CLAUDE.md Full Template
+```markdown
+# Project: {name}
+{one-line description}
+
+## Tech Stack
+- **Backend:** {language} {version} + {framework} {version} ({api_style})
+- **Frontend:** {framework} {version} + {meta_framework} {version} ({rendering_mode})
+- **Database:** {database_type} + {orm} ({migration_tool})
+- **Cache:** {cache_system}
+- **Queue:** {queue_system}
+- **Infra:** {containerization} + {orchestration} + {cloud_provider}
+- **CI/CD:** {platform} ({config_file})
+
+## Quick Commands
+- Install: `{install_command}`
+- Build: `{build_command}`
+- Dev: `{dev_command}`
+- Test all: `{test_command}`
+- Test single: `{single_test_command}`
+- Lint: `{lint_command}`
+- Format: `{format_command}`
+- Type check: `{type_check_command}`
+- Migrate: `{migration_command}`
+
+## Architecture
+- Type: {monolith | modular | microservices}
+- Pattern: {MVC | Clean | DDD | Hexagonal | Feature-based}
+- Data flow: {request → middleware → controller → service → repository → DB}
+- Auth: {mechanism} via {library}
+
+## Code Style
+- {ONLY rules differing from linter config}
+- Import order: {if custom}
+- Error pattern: {convention}
+
+## Git Conventions
+- Branch: `{pattern}`
+- Commit: `{format}`
+- PR: `{requirements}`
+
+## Key Paths
+- Entry points: `{path}`
+- API routes: `{path}`
+- Services: `{path}`
+- Models: `{path}`
+- Migrations: `{path}`
+- Shared/common: `{path}`
+- Types: `{path}`
+- Frontend components: `{path}`
+- Tests: `{path}` (unit), `{path}` (e2e)
+- Generated (DO NOT EDIT): `{path}`
+
+## Gotchas
+- {non-obvious thing with file:line ref}
+
+## Testing
+- Unit: `{framework}` — `{command}` — pattern: `{naming}`
+- E2E: `{framework}` — `{command}`
+- Coverage: `{command}`
+
+@.claude/rules/domain-terms.md
+```
+
+## Rule File Templates
+
+### domain-terms.md
+```yaml
+---
+paths: ["**/*"]
+---
+# Domain Terms
+- {Term}: {Definition as used in THIS codebase}
+```
+
+### api.md
+```yaml
+---
+paths: ["src/api/**/*", "src/routes/**/*"]
+---
+# API Rules
+- Endpoint naming: {pattern}
+- Request validation: {library} — {pattern}
+- Response format: {format}
+- Error format: {format}
+- Auth: {how to protect endpoints}
+```
+
+### testing.md
+```yaml
+---
+paths: ["**/*.test.*", "**/*.spec.*", "tests/**/*"]
+---
+# Testing Rules
+- File naming: {pattern}
+- Test naming: {convention}
+- Mocks: {library and pattern}
+- Integration vs unit: {boundary}
+```
+
+### frontend.md
+```yaml
+---
+paths: ["src/components/**/*", "src/pages/**/*", "app/**/*"]
+---
+# Frontend Rules
+- Component pattern: {hooks | Composition API | class-based}
+- Styling: {approach}
+- State: {when global vs local}
+- Data fetching: {pattern}
+```
+
+### database.md
+```yaml
+---
+paths: ["src/db/**/*", "migrations/**/*", "src/models/**/*"]
+---
+# Database Rules
+- Migration naming: {convention}
+- Query pattern: {repository | active record | query builder}
+- ORM: {orm_name} — always use parameterized queries
+- Transactions: {how to wrap multi-step operations}
+```
+
+### security.md
+```yaml
+---
+paths: ["src/auth/**/*", "src/api/**/*"]
+---
+# Security Rules
+- Validate ALL inputs with {library}
+- Never log PII
+- Parameterized queries only via {orm}
+- Auth on every non-public endpoint
+```
+
+### infrastructure.md
+```yaml
+---
+paths: ["Dockerfile*", "docker-compose*", "terraform/**/*", ".github/workflows/**/*", "k8s/**/*"]
+---
+# Infrastructure Rules
+- Docker: {base image policy, multi-stage build pattern}
+- CI: {what must pass before merge}
+- Env vars: {naming convention}
+- Secrets: {management approach}
+```
+
+## Nested CLAUDE.md Template (per module)
+```markdown
+# {Module Name}
+{one-line purpose}
+
+## Commands
+- Test: `{module_test_cmd}`
+- Build: `{module_build_cmd}`
+
+## Patterns
+- {module-specific patterns only}
+
+## Dependencies
+- Depends on: {internal modules}
+- Depended on by: {internal modules}
+```
+
+## Profile Templates
+
+### backend.md
+```markdown
+# Backend Developer Profile
+Focus: API development, database, business logic
+Agents: @debugger, @api-builder, @tester
+Commands: Run API `{api_start_cmd}`, Test `{backend_test_cmd}`, Migrate `{migration_cmd}`
+Load: .claude/rules/api.md, .claude/rules/database.md
+```
+
+### frontend.md
+```markdown
+# Frontend Developer Profile
+Focus: UI components, styling, user experience
+Agents: @frontend, @tester
+Commands: Dev `{frontend_dev_cmd}`, Test `{frontend_test_cmd}`, Storybook `{storybook_cmd}`
+Load: .claude/rules/frontend.md
+```
+
+### devops.md
+```markdown
+# DevOps Profile
+Focus: Infrastructure, CI/CD, deployment
+Agents: @infra
+Commands: Deploy `{deploy_cmd}`, Logs `{log_cmd}`, Status `{status_cmd}`
+Load: .claude/rules/infrastructure.md
+```
+
+## Settings.json Template
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash({pkg_mgr} test *)", "Bash({pkg_mgr} run *)",
+      "Bash({build_cmd})", "Bash({lint_cmd})",
+      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)", "Bash(sudo *)",
+      "Bash(git push --force *)", "Bash(git reset --hard)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [{"matcher": "startup|resume|compact", "hooks": [{"type": "command", "command": "node .claude/hooks/session-start.js"}]}],
+    "PreToolUse": [
+      {"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "node .claude/hooks/protect-files.js"}]},
+      {"matcher": "Bash", "hooks": [{"type": "command", "command": "node .claude/hooks/validate-bash.js"}]}
+    ],
+    "PostToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "node .claude/hooks/post-edit-format.js"}]}],
+    "Notification": [{"matcher": "permission_prompt", "hooks": [{"type": "command", "command": "node .claude/hooks/notify-approval.js"}]}],
+    "Stop": [{"hooks": [{"type": "prompt", "prompt": "Check if task is complete. Tests pass, no lint errors, no type errors. Return {\"ok\": true} or {\"ok\": false, \"reason\": \"what's missing\"}", "model": "haiku"}]}]
+  }
+}
+```
+
+## Hook Script Templates (Cross-Platform Node.js)
+
+All hooks use Node.js for cross-platform compatibility (Windows, macOS, Linux). No bash or jq dependency required.
+
+### protect-files.js
+```javascript
+#!/usr/bin/env node
+// Pre-tool hook: block edits to protected files
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const file = (data.tool_input && data.tool_input.file_path) || '';
+    if (!file) process.exit(0);
+    const PROTECTED = ['.env', '.env.local', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', '.github/workflows/'];
+    for (const p of PROTECTED) {
+      if (file.includes(p)) { process.stderr.write(`BLOCKED: ${file} is protected.\n`); process.exit(2); }
+    }
+  } catch {}
+  process.exit(0);
+});
+```
+
+### post-edit-format.js
+```javascript
+#!/usr/bin/env node
+// Post-tool hook: auto-format edited files
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const file = (data.tool_input && data.tool_input.file_path) || '';
+    if (!file || !fs.existsSync(file)) process.exit(0);
+    const ext = path.extname(file).toLowerCase();
+    const formatters = {
+      '.ts': 'npx prettier --write', '.tsx': 'npx prettier --write',
+      '.js': 'npx prettier --write', '.jsx': 'npx prettier --write',
+      '.json': 'npx prettier --write', '.css': 'npx prettier --write',
+      '.py': 'black', '.go': 'gofmt -w', '.rs': 'rustfmt',
+    };
+    const formatter = formatters[ext];
+    if (formatter) { try { execSync(`${formatter} "${file}"`, { stdio: 'ignore', timeout: 10000 }); } catch {} }
+  } catch {}
+  process.exit(0);
+});
+```
+
+### validate-bash.js
+```javascript
+#!/usr/bin/env node
+// Pre-tool hook: block dangerous bash commands
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const cmd = (data.tool_input && data.tool_input.command) || '';
+    if (!cmd) process.exit(0);
+    const DANGEROUS = ['rm -rf /', ':(){ :|:& };:', '> /dev/sda', 'mkfs', 'dd if=', 'curl.*| bash'];
+    for (const p of DANGEROUS) {
+      if (cmd.includes(p)) { process.stderr.write('BLOCKED: Dangerous command.\n'); process.exit(2); }
+    }
+  } catch {}
+  process.exit(0);
+});
+```
+
+### session-start.js
+```javascript
+#!/usr/bin/env node
+// Re-inject critical context on session start
+const fs = require('fs');
+const path = require('path');
+console.log('PROJECT: {package_manager} | Test: {test_cmd} | Lint: {lint_cmd} | Build: {build_cmd}');
+const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+if (fs.existsSync(tasksDir)) {
+  for (const file of fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'))) {
+    const content = fs.readFileSync(path.join(tasksDir, file), 'utf-8');
+    if (/status:\s*(DEVELOPING|DEV_TESTING)/.test(content)) {
+      const title = (content.match(/^title:\s*(.+)$/m) || [])[1];
+      if (title) console.log(`ACTIVE TASK: ${title.trim()}`);
+      break;
+    }
+  }
+}
+```
+
+### notify-approval.js
+```javascript
+#!/usr/bin/env node
+// Cross-platform OS notification when Claude needs user approval
+const { execSync } = require('child_process');
+const MSG = 'Claude Code needs your approval';
+function tryExec(cmd) { try { execSync(cmd, { stdio: 'ignore', timeout: 5000 }); } catch {} }
+if (process.platform === 'darwin') {
+  tryExec(`osascript -e 'display notification "${MSG}" with title "Claude Code"'`);
+} else if (process.platform === 'win32') {
+  tryExec(`powershell.exe -NoProfile -Command "Add-Type -A System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('${MSG}','Claude Code')"`);
+} else {
+  tryExec(`notify-send "Claude Code" "${MSG}"`);
+}
+```
+
+## Auto-Progress Hook (add to settings.json hooks)
+Track file changes for active task:
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        {"type": "command", "command": "node .claude/hooks/track-file-changes.js"}
+      ]
+    }
+  ]
+}
+```
+
+### track-file-changes.js
+```javascript
+#!/usr/bin/env node
+// Post-tool hook: track file changes for active task
+const fs = require('fs');
+const path = require('path');
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const file = (data.tool_input && data.tool_input.file_path) || '';
+    if (!file) process.exit(0);
+    const tasksDir = path.join(process.cwd(), '.claude', 'tasks');
+    if (!fs.existsSync(tasksDir)) process.exit(0);
+    for (const tf of fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'))) {
+      const taskPath = path.join(tasksDir, tf);
+      const content = fs.readFileSync(taskPath, 'utf-8');
+      if (/status:\s*(DEVELOPING|DEV_TESTING)/.test(content)) {
+        const logPath = taskPath.replace(/\.md$/, '_changes.log');
+        fs.appendFileSync(logPath, `| ${new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')} | file_changed | ${file} |\n`);
+        break;
+      }
+    }
+  } catch {}
+  process.exit(0);
+});
+```
+
+## Code Template Extraction Instructions
+For each template type (component, endpoint, service, model, test):
+1. Read 3-5 existing files of that type
+2. Identify the common skeleton (imports, structure, exports)
+3. Replace specific names with `{Placeholder}`
+4. Preserve exact: import order, export style, prop pattern, error handling
+5. Include both code skeleton AND test skeleton

package/template/.claude/skills/generate-environment/domain-agents.md

@@ -0,0 +1,202 @@
+# Domain-Specific Agent Templates
+
+Generate ONLY if codebase has that layer. All agents MUST include: structured output format, HANDOFF block, limitations section, `memory: project` field.
+
+## SDLC Role Agents (always generate these 4)
+
+### product-owner.md — Always generate
+```yaml
+---
+name: product-owner
+description: Business analysis, acceptance criteria, and business sign-off gate for {project_name}.
+tools: Read, Grep, Glob
+disallowedTools: Edit, Write, Bash
+model: opus
+permissionMode: plan
+maxTurns: 20
+effort: high
+memory: project
+---
+
+Product Owner for {project_name}. You bridge business requirements and technical implementation.
+
+Responsibilities:
+1. Write acceptance criteria in GIVEN/WHEN/THEN format
+2. Validate requirements against implementation
+3. Approve/reject at business sign-off gate (Phase 10)
+4. Flag scope creep immediately
+
+Output: acceptance criteria table, sign-off decision, HANDOFF block.
+
+Limitations:
+- DO NOT modify code — read-only
+- DO NOT make technical decisions — defer to @architect or @team-lead
+- DO NOT approve without verifying ALL acceptance criteria
+```
+
+### team-lead.md — Always generate
+```yaml
+---
+name: team-lead
+description: Coordinates workflow, assigns tasks, resolves blockers, and provides tech sign-off for {project_name}.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: opus
+maxTurns: 50
+effort: high
+memory: project
+skills: task-tracker, progress-report, execution-report
+---
+
+Tech Lead for {project_name}. You coordinate all agents and own technical decisions.
+
+Agent assignment: backend -> @api-builder, frontend -> @frontend, fullstack -> parallel, infra -> @infra, investigation -> @explorer, bugs -> @debugger, review -> @reviewer + @security, architecture -> @architect, QA -> @qa-lead + @tester.
+
+Loop management: track iteration counts in task records. Escalate at max.
+
+Limitations:
+- DO NOT write application code — delegate to dev agents
+- DO NOT approve your own changes — use @reviewer
+- DO NOT skip QA or security review
+```
+
+### architect.md — Always generate
+```yaml
+---
+name: architect
+description: Architecture design and review for {project_name}. Phase 3 (Architecture Review) and design-review.
+tools: Read, Grep, Glob, Bash
+disallowedTools: Edit, Write
+model: opus
+permissionMode: plan
+maxTurns: 25
+effort: high
+memory: project
+---
+
+Architect for {project_name}. Architecture: {architecture_type}, {api_style}, {deployment_topology}.
+
+Method: map current state -> analyze impact -> design with alternatives -> evaluate trade-offs -> recommend -> document with Mermaid diagrams.
+
+Output: design options table, recommendation, Mermaid diagram, decision record, HANDOFF block.
+
+Limitations:
+- DO NOT write implementation code — design documents only
+- DO NOT modify source files — strictly read-only
+```
+
+### qa-lead.md — Always generate
+```yaml
+---
+name: qa-lead
+description: QA planning, test strategy, and QA sign-off gate for {project_name}.
+tools: Read, Grep, Glob, Bash
+disallowedTools: Edit, Write
+model: sonnet
+permissionMode: plan
+maxTurns: 25
+effort: high
+memory: project
+---
+
+QA Lead for {project_name}. Test framework: {test_framework}, commands: `{test_cmd}`.
+
+Method: create scenario matrix -> verify automated coverage -> identify gaps -> triage bugs (P0-P4) -> sign-off decision.
+
+Bug severity: P0/P1 block sign-off, P2 QA decides, P3/P4 conditional approve.
+
+Output: QA test plan table, bug reports, sign-off decision, HANDOFF block.
+
+Limitations:
+- DO NOT fix bugs — report to @debugger via @team-lead
+- DO NOT modify code — strictly read-only
+- DO NOT approve if P0/P1 bugs open
+```
+
+## Dev Role Agents (generate based on codebase layers)
+
+### frontend.md — Generate if TECH_MANIFEST.frontend.exists
+```yaml
+---
+name: frontend
+description: Frontend specialist for {project_name}. Builds UI using {framework} {version}.
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+maxTurns: 30
+effort: high
+memory: project
+isolation: worktree
+---
+
+{framework} specialist. Tech: {framework} {version}, {meta_framework}, {state_mgmt}, {styling}, {ui_library}, {test_framework}.
+
+Components in `{component_dir}`: {naming_pattern}, {prop_pattern}, {styling_approach}.
+Pages in `{pages_dir}`: {routing_pattern}, {data_loading_pattern}.
+Tests in `{test_dir}`: `{test_command}`.
+
+Method: find similar existing -> copy exact pattern -> implement -> accessibility check -> add tests -> verify build.
+
+Output: implementation summary, files list, HANDOFF block.
+
+Limitations:
+- DO NOT modify backend code — @api-builder's domain
+- DO NOT modify CI/CD — @infra's domain
+- DO NOT skip accessibility
+```
+
+### api-builder.md — Generate if backend has API routes
+```yaml
+---
+name: api-builder
+description: API endpoint specialist for {project_name}. Creates {api_style} endpoints using {framework}.
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+maxTurns: 30
+effort: high
+memory: project
+isolation: worktree
+---
+
+API specialist. Routes: `{routes_dir}`, Handlers: `{handlers_dir}`, Services: `{services_dir}`, Schemas: `{schemas_dir}`.
+
+Patterns: {route_definition}, {validation_pattern}, {response_format}, {error_format}, {auth_pattern}.
+
+Method: find similar endpoint -> copy pattern -> route -> validation -> handler -> service -> tests -> verify.
+DB: {orm} in `{models_dir}`, migrations: `{migration_cmd}`.
+
+Output: endpoint summary, files list, HANDOFF block.
+
+Limitations:
+- DO NOT modify frontend code — @frontend's domain
+- DO NOT modify CI/CD — @infra's domain
+- DO NOT skip input validation
+```
+
+### infra.md — Generate if Docker/k8s/Terraform/CI present
+```yaml
+---
+name: infra
+description: Infrastructure and DevOps specialist for {project_name}. Manages Docker, CI/CD, deployment.
+tools: Read, Edit, Write, Bash, Grep, Glob
+disallowedTools: NotebookEdit
+model: sonnet
+maxTurns: 30
+effort: high
+memory: project
+---
+
+Infra specialist. Docker: `{dockerfile}`, Compose: `{compose_file}`.
+CI: {platform} at `{ci_config}`. Cloud: {provider}. IaC: `{iac_dir}`.
+
+Always modify IaC files, never manual changes. Test locally before pushing.
+
+Output: infrastructure changes, new env vars, rollback plan, HANDOFF block.
+
+Limitations:
+- DO NOT modify application source code — infrastructure files only
+- DO NOT hardcode secrets
+- Scope: Dockerfile*, docker-compose*, .github/workflows/**, k8s/**, terraform/**
+```
+
+## Additional agents to generate based on codebase:
+- **data-engineer.md** — if data pipelines/ETL detected
+- **ml-engineer.md** — if ML models/training detected

package/template/.claude/skills/impact-analysis/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: impact-analysis
+description: Analyze the blast radius of a proposed change. Use before making significant code changes.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Impact Analysis: $ARGUMENTS
+
+Run @explorer and @security in parallel.
+
+**@explorer:** Files directly affected, modules with transitive dependencies, existing test coverage, related pending changes.
+
+**@security:** Auth/authz code touched? User input handling? DB queries? PII? File uploads?
+
+**Output:** Files affected (file:line refs), blast radius, test coverage %, security flags, risk level (LOW/MEDIUM/HIGH/CRITICAL), Mermaid diagram.

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

@@ -0,0 +1,19 @@
+---
+name: metrics
+description: Calculate aggregate task metrics — velocity, quality, cycle-time, agent performance. Use when asking about team performance or bottlenecks.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[velocity|quality|cycle-time|agents|blockers|all] [--period 7d|30d|90d]"
+---
+
+# Metrics: $ARGUMENTS
+
+Read all `.claude/tasks/*.md` and calculate:
+
+- **velocity** — tasks/week, throughput trend, WIP count
+- **quality** — test pass rate, coverage trend, bug escape rate, deploy success rate, rollback frequency
+- **cycle-time** — avg per phase, bottleneck detection, time in BLOCKED, review iteration count
+- **agents** — tasks handled, avg duration, success rate, rework rate per agent
+- **blockers** — total in period, avg resolution time, most common categories
+- **all** — everything above combined

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

@@ -0,0 +1,27 @@
+---
+name: progress-report
+description: Generate progress reports for different stakeholders. Use when someone asks for status updates, reports, or summaries.
+user-invocable: true
+context: fork
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: "[dev|qa|business|management|executive] [task-id|all]"
+---
+
+# Progress Report: $ARGUMENTS
+
+Read task files from `.claude/tasks/` and generate audience-appropriate report.
+
+## dev — Developer Report
+What's done (file:line refs), what's in progress, what's next, test results, coverage, build/lint status, agent activity, open questions, commands to run.
+
+## qa — QA Report
+Change summary (plain language), backend/frontend/DB changes with what to test, automated test results, manual testing needed (step-by-step), regression risks, known limitations, environment setup.
+
+## business — Business Report
+One paragraph summary, acceptance criteria status table (VERIFIED/IN_PROGRESS/NOT_MET), progress bar per phase, estimated completion, risks in business terms, impact when delivered, decisions needed.
+
+## management — Management Report
+Portfolio table (all tasks with phase/status/%/ETA), health indicators (on track/at risk/overdue), blocker summary, this week's completions, key decisions needed, 30-day metrics.
+
+## executive — Executive Summary
+Status light (green/yellow/red), key metrics table with trends (tasks completed, cycle time, quality, deploy success, blocked), highlights, risks, needs attention.