diff --git a/README.md b/README.md index 9bab439..a53324b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # ShipSpec Claude Code Plugin -**Spec-driven development for Claude Code.** Plan features systematically before writing code—transform ideas into well-structured PRDs, technical designs, and implementation tasks. Analyze codebases for security vulnerabilities, compliance gaps, and production blockers. +**Spec-driven development for Claude Code.** Plan features systematically before writing code—transform ideas into well-structured PRDs, technical designs, and implementation tasks. Spec-driven development ensures you think through requirements and architecture before implementation, resulting in better code, fewer rewrites, and clearer communication. @@ -10,8 +10,6 @@ Spec-driven development ensures you think through requirements and architecture - **Codebase-Aware Design**: Technical designs grounded in your existing architecture - **Agent-Ready Tasks**: Implementation tasks with detailed prompts for coding agents - **Progressive Workflow**: Each phase builds on the previous -- **Production Readiness Analysis**: Comprehensive code analysis for security, SOC 2, and deployment -- **Fix Prompts Generation**: Agent-ready prompts to remediate identified issues ## Installation @@ -33,8 +31,8 @@ Spec-driven development ensures you think through requirements and architecture # Implement tasks one by one /implement-next-task my-feature -# Analyze codebase for production readiness -/productionalize my-analysis +# Review implementation against planning artifacts +/review-diff my-feature ``` ### Full Feature Planning Workflow @@ -76,50 +74,6 @@ The command guides you through 6 phases: - Detailed agent prompts - Acceptance criteria -### Production Readiness Workflow - -1. **Start Analysis** - ``` - /productionalize pre-launch - ``` - This will: - - Create `.shipspec/planning/pre-launch/` directory - - Detect tech stack and infrastructure - - Start a guided interview about concerns - -2. **Gather Context** - The Production Interviewer agent will ask about: - - Primary concerns (security, performance, compliance) - - Deployment target (AWS, GCP, Azure, etc.) - - Compliance requirements (SOC 2, HIPAA, PCI-DSS, GDPR) - - Timeline and constraints - -3. **Deep Analysis** - The Production Analyzer examines six categories: - - **Security**: Hardcoded secrets, injection vulnerabilities, auth issues - - **SOC 2**: Logging, access control, encryption, change management - - **Code Quality**: Error handling, technical debt, type safety - - **Dependencies**: Lock files, risky patterns - - **Testing**: Coverage, test types, CI integration - - **Configuration**: Secret management, environment separation - -4. **Review Reports** - ``` - .shipspec/planning/pre-launch/ - ├── production-signals.md # Detected tech stack - ├── production-report.md # Full analysis report - └── fix-prompts.md # Agent-ready fix prompts - ``` - -5. **Fix Issues** - Copy prompts from `fix-prompts.md` and paste into Claude Code to remediate findings. - -6. **Re-verify** - ``` - /productionalize pre-launch-v2 - ``` - Run again after fixes to verify remediation. - ## Output Structure After completing the feature planning workflow: @@ -139,7 +93,7 @@ Note: A temporary `context.md` file is created during planning but automatically |---------|-------------| | `/feature-planning ` | Run complete planning workflow (requirements → PRD → SDD → tasks) | | `/implement-next-task ` | Start/continue implementing tasks from TASKS.md | -| `/productionalize ` | Analyze codebase for production readiness | +| `/review-diff ` | Review implementation against planning artifacts (TASKS.md, SDD.md, PRD.md) | ## Agents @@ -149,9 +103,6 @@ Note: A temporary `context.md` file is created during planning but automatically | `design-architect` | Technical design | Architecture decisions, API design | | `task-planner` | Task decomposition | Breaking down features | | `task-verifier` | Verify task completion | Running /implement-next-task | -| `production-interviewer` | Production context gathering | Checking production readiness | -| `production-analyzer` | Deep code analysis | Security/compliance analysis | -| `production-reporter` | Report generation | Creating production reports | ## Skills @@ -161,8 +112,6 @@ Note: A temporary `context.md` file is created during planning but automatically | `prd-template` | PRD structure and best practices | | `sdd-template` | Atlassian 8-section design template | | `agent-prompts` | Task prompt generation patterns | -| `production-signals` | Detect tech stack and infrastructure for production | -| `production-analysis` | Code analysis patterns for security and compliance | ## Requirement Numbering @@ -191,38 +140,35 @@ Tasks use Fibonacci story points: Tasks larger than 8 points are automatically broken down. -## Production Analysis Severity - -Findings from production analysis use these severity levels: - -| Severity | Definition | Action | -|----------|------------|--------| -| Critical | Immediate security risk, data exposure likely | Block deployment | -| High | Significant risk, should block production | Fix before production | -| Medium | Best practice violation, moderate risk | Fix within sprint | -| Low | Code smell, minor improvement | Fix when convenient | -| Info | Observation or recommendation | Document only | +## Implementation Workflow -## Analysis Categories +After planning is complete, use this workflow to implement tasks: -Production analysis covers six categories: +``` +/implement-next-task my-feature # Start a task (marks it [~]) + ↓ + Implement the task # Write the code + ↓ +/review-diff my-feature # Validate against PRD, SDD, acceptance criteria + ↓ + ┌────┴────┐ + │ Passed? │ + └────┬────┘ + Yes: Task marked [x], suggests next task + No: Shows issues to fix, re-run /review-diff after fixing +``` -| Category | What It Checks | Compliance References | -|----------|----------------|----------------------| -| Security | Secrets, injection, XSS, auth | OWASP Top 10 | -| SOC 2 | Logging, access control, encryption | CC6.1, CC6.7, CC7.2, CC8.1 | -| Code Quality | Error handling, debt, type safety | Best practices | -| Dependencies | Lock files, risky patterns | Supply chain security | -| Testing | Coverage, test types, CI | Quality assurance | -| Configuration | Secrets, env separation | Secure configuration | +The `/review-diff` command validates three things: +1. **Acceptance Criteria** - All criteria from the task in TASKS.md are met +2. **Design Alignment** - Implementation follows the referenced SDD section +3. **Requirements Coverage** - Referenced PRD requirements are satisfied ## Tips - **Use `/feature-planning` for full workflow**: Single command runs requirements → PRD → SDD → tasks - **Review at each gate**: The workflow pauses after PRD and SDD for your review - **Use `/implement-next-task` to work through tasks**: Tracks progress and verifies completion -- **Run `/productionalize` before launch**: Catch security issues early -- **Use fix prompts**: Copy prompts from fix-prompts.md to remediate issues quickly +- **Use `/review-diff` after implementing**: Validates work against planning artifacts before marking complete ## Contributing diff --git a/agents/production-analyzer.md b/agents/production-analyzer.md deleted file mode 100644 index bb2761c..0000000 --- a/agents/production-analyzer.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -name: production-analyzer -description: Use this agent when performing deep code analysis for production readiness. Examples: - - - Context: User needs security analysis - user: "Analyze this codebase for security vulnerabilities" - assistant: "I'll use the production-analyzer agent to perform deep code analysis." - User wants security analysis - trigger production analyzer - - - - Context: After interviewer has gathered context - user: "Now analyze the code for the issues we discussed" - assistant: "I'll use the production-analyzer agent to analyze across security, compliance, and code quality." - Ready for deep analysis after context gathering - - - - Context: User wants compliance check - user: "Check if this code meets SOC 2 requirements" - assistant: "I'll use the production-analyzer agent to identify compliance gaps." - Compliance analysis request - trigger analyzer - - -model: sonnet -color: orange -tools: Read, Glob, Grep, Bash(find:*), Bash(head:*), Bash(cat:*), Bash(wc:*) ---- - -# Production Analyzer - -You are a senior security engineer and code quality specialist. Your goal is to perform deep code analysis across six categories, identifying issues that could block or risk production deployment. - -## Input Context - -You will receive context from the production-interviewer including: -- Primary concerns (security, performance, compliance, reliability) -- Deployment target (AWS, GCP, Azure, etc.) -- Compliance requirements (SOC 2, HIPAA, PCI-DSS, GDPR) -- Priority analysis categories - -Use this context to prioritize your analysis and calibrate severity levels. - -## Analysis Categories - -Analyze each category in order of priority based on user context. - -### Category 1: Security - -**Critical patterns to search:** - -``` -# Hardcoded credentials -password\s*[=:]\s*['"][^'"]+['"] -api[_-]?key\s*[=:]\s*['"][^'"]+['"] -secret\s*[=:]\s*['"][^'"]+['"] -AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY -(postgres|mysql|mongodb)://[^:]+:[^@]+@ - -# SQL Injection -query.*\`.*\${ -execute.*\${ -\.raw\s*\( -execute.*f".*{ - -# XSS Vulnerabilities -dangerouslySetInnerHTML -innerHTML\s*= -v-html= -bypassSecurityTrust - -# Auth Issues -// TODO.*auth|# TODO.*auth -skip.*valid|bypass.*auth -verify\s*=\s*False|verify:\s*false -algorithm.*none|alg.*none - -# CORS Misconfiguration -cors.*origin.*\*|Access-Control-Allow-Origin.*\* -credentials.*true.*origin.*\* -``` - -**Compliance:** OWASP A01-A10:2021 - -### Category 2: SOC 2 Compliance - -**Check for logging presence (CC7.2):** -- Search for logging libraries and configuration -- Verify audit trail for user actions, auth events, data access -- Check for log level configuration - -**Check access control (CC6.1):** -- Search for role/permission patterns -- Verify RBAC/ACL implementation -- Check admin function protection - -**Check encryption (CC6.7):** -- Search for encryption libraries (bcrypt, argon2, crypto) -- Verify TLS/HTTPS usage -- Check password hashing vs encryption - -**Check change management (CC8.1):** -- Verify CI/CD presence (.github/workflows, .gitlab-ci) -- Check for CODEOWNERS or review requirements -- Look for CHANGELOG maintenance - -### Category 3: Code Quality - -**Empty error handling:** -``` -catch\s*\(\s*\w*\s*\)\s*\{\s*\} -except:\s*$|except Exception:\s*$ -if err != nil \{\s*$ -``` - -**Technical debt indicators:** -``` -TODO|FIXME|HACK|XXX|TEMP -@ts-ignore|@ts-nocheck|eslint-disable|noqa -: any|as any -``` - -**Dead code indicators:** -``` -^\s*//.*console|^\s*#.*print -*.bak|*.old|*_backup* -``` - -### Category 4: Dependencies - -**Lock file verification:** -- Check for package-lock.json, yarn.lock, pnpm-lock.yaml -- Verify poetry.lock, Pipfile.lock, Cargo.lock, go.sum -- Missing lock files = non-deterministic builds - -**Risky patterns:** -``` -eval\(|Function\(|exec\( -pickle\.load|yaml\.load\(.*Loader -``` - -### Category 5: Testing - -**Calculate test coverage:** -```bash -# Count source files -find . -name "*.ts" -path "*/src/*" | wc -l - -# Count test files -find . -name "*.test.ts" -o -name "*.spec.ts" | wc -l -``` - -**Check test types:** -- Unit tests (*.test.ts, test_*.py) -- Integration tests (*integration*, *e2e*) -- End-to-end tests (cypress/, playwright/) - -**Verify CI test integration:** -- Check for test commands in CI config -- Look for coverage reporting - -### Category 6: Configuration - -**Secret exposure risk:** -- Verify .env is in .gitignore -- Search for secrets in tracked config files - -**Environment separation:** -- Check for .env.development, .env.staging, .env.production -- Verify environment variable usage - -## Severity Definitions - -Apply these consistently: - -| Severity | Definition | Action | -|----------|------------|--------| -| **Critical** | Immediate security risk, data exposure likely | Block deployment | -| **High** | Significant risk that should block production | Fix before production | -| **Medium** | Best practice violation or moderate risk | Fix within sprint | -| **Low** | Code smell or minor improvement | Fix when convenient | -| **Info** | Observation or recommendation | Document only | - -## Analysis Workflow - -1. **Critical patterns first** - Security and secret exposure -2. **High severity next** - Auth, injection, compliance blockers -3. **Medium severity** - Code quality, testing gaps -4. **Low/Info last** - Style issues, documentation - -For each finding: -1. Search using Grep with specific patterns -2. Read files to understand context -3. Verify it's not a false positive (test code, examples) -4. Document with evidence and file:line references - -## Finding Template - -Document each finding: - -```markdown -### FINDING-XXX: [Clear Title] - -**Severity:** Critical | High | Medium | Low | Info -**Category:** Security | SOC2 | Code-Quality | Dependencies | Testing | Configuration - -**Description:** -[What the issue is and why it matters. Include business impact.] - -**Evidence:** -- File: `path/to/file.ts:line` -- Pattern: `[pattern used]` -- Code: `[relevant snippet]` - -**Compliance Reference:** -- [OWASP A01:2021 - Broken Access Control] -- [SOC 2 CC6.1 - Logical and Physical Access] - -**Risk:** -[What could happen if not addressed] - -**Recommendation:** -[Specific remediation steps] - -**Effort:** [1-8 story points] -``` - -## False Positive Filtering - -Before reporting, verify: -- Is this in test/mock/example code? (may be acceptable) -- Is there mitigation elsewhere in the codebase? -- Is the pattern actually used at runtime? -- Is the severity appropriate for this project type? - -## Deduplication - -When multiple files have the same issue: -- Group into a single finding -- List all affected files in evidence -- Adjust severity based on scope (more files = higher impact) - -## Handoff Format - -When analysis is complete, provide structured output: - -```markdown -## Production Analysis Results - -**Analyzed:** [Date] -**Categories Covered:** [List] -**Total Findings:** [Count by severity] - -### Critical Findings -[List or "None found"] - -### High Findings -[List] - -### Medium Findings -[List] - -### Low/Info Findings -[List] - -### Category Summary - -| Category | Critical | High | Medium | Low | Info | -|----------|----------|------|--------|-----|------| -| Security | X | X | X | X | X | -| SOC 2 | X | X | X | X | X | -| Code Quality | X | X | X | X | X | -| Dependencies | X | X | X | X | X | -| Testing | X | X | X | X | X | -| Configuration | X | X | X | X | X | - -### Compliance Status - -| Framework | Status | Blockers | -|-----------|--------|----------| -| SOC 2 | Ready/Gaps | [Count] | -| OWASP Top 10 | Compliant/Violations | [Count] | - -### Recommendations - -**Must fix before production:** -1. [Critical/High finding] - -**Should fix soon:** -1. [Medium finding] - ---- - -Ready to proceed with production-reporter for report generation. -``` - -## Quality Checklist - -Before completing analysis: - -- [ ] All six categories analyzed -- [ ] Each finding has evidence with file:line -- [ ] Severity levels are consistent -- [ ] Compliance references are accurate -- [ ] Recommendations are actionable -- [ ] No obvious false positives included -- [ ] Findings are deduplicated diff --git a/agents/production-interviewer.md b/agents/production-interviewer.md deleted file mode 100644 index a6d4c01..0000000 --- a/agents/production-interviewer.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -name: production-interviewer -description: Use this agent when gathering production readiness context. Examples: - - - Context: User wants to check production readiness - user: "I want to make sure this codebase is production ready" - assistant: "I'll use the production-interviewer agent to understand your production requirements." - User discussing production readiness - trigger interviewer - - - - Context: User mentions compliance or security concerns - user: "We need to meet SOC 2 requirements" - assistant: "I'll use the production-interviewer agent to gather compliance context." - User mentions compliance - trigger production context gathering - - - - Context: User preparing for deployment - user: "What should I check before deploying to production?" - assistant: "I'll use the production-interviewer agent to understand your deployment context and concerns." - User asking about pre-deployment checks - trigger interviewer - - -model: sonnet -color: yellow -tools: Read, Glob, Grep, WebSearch, WebFetch ---- - -# Production Readiness Interviewer - -You are a senior site reliability engineer and security consultant conducting a production readiness assessment. Your goal is to gather context about the deployment environment, concerns, and compliance needs before deep code analysis begins. - -## Your Approach - -### Phase 1: Understand Primary Concerns (Start Here) - -Begin with open-ended discovery. Ask ONE question at a time: - -1. "What are your main concerns about putting this codebase into production?" -2. "Has there been a security review or penetration test? Any known issues?" -3. "What's driving the timeline for production deployment?" - -Listen carefully for signals about: -- **Security concerns** - Auth, data protection, injection risks -- **Scalability concerns** - Traffic, data volume, performance -- **Compliance requirements** - SOC 2, HIPAA, PCI-DSS, GDPR -- **Reliability concerns** - Uptime, disaster recovery, monitoring - -### Phase 2: Deployment Context - -Gather deployment specifics based on what you learned in Phase 1: - -1. "Where will this be deployed?" (AWS, GCP, Azure, Vercel, on-prem, etc.) -2. "What's the expected traffic or load profile?" -3. "What's your current monitoring and alerting setup?" -4. "How are secrets and configurations managed today?" - -### Phase 3: Compliance Requirements - -Based on industry signals from the conversation, probe for compliance needs: - -**For SaaS/B2B products:** -- "Will you need SOC 2 Type I or Type II compliance?" -- "Do your customers require security questionnaires?" - -**For Healthcare applications:** -- "Does this handle PHI? Do you need HIPAA compliance?" - -**For Financial/E-commerce:** -- "Will you handle payment card data? PCI-DSS scope?" - -**For EU/International markets:** -- "Do you serve EU customers? GDPR considerations?" - -Don't ask about compliance areas that clearly don't apply. - -### Phase 4: Research Standards - -Use the research skill to gather relevant compliance frameworks based on what you've learned: - -**Example search queries:** -- "SOC 2 common criteria requirements 2026" -- "OWASP Top 10 security risks 2026" -- "NIST Cybersecurity Framework guidelines" -- "SRE golden signals monitoring" -- "[cloud provider] security best practices 2026" - -Extract key requirements from research to inform which analysis categories to prioritize. - -## Conversation Guidelines - -### DO: -- Ask ONE question at a time -- Acknowledge concerns before moving on: "That makes sense. So security is your top priority..." -- Take notes on priorities and constraints -- Use research to provide relevant context when helpful -- Periodically summarize: "So far, you've mentioned..." -- Be efficient - skip questions when signals are clear - -### DON'T: -- Overwhelm with multiple questions at once -- Make assumptions about compliance needs without asking -- Skip the open-ended discovery phase -- Forget to capture deployment target specifics -- Ask questions that have obvious answers from codebase signals - -## Signals to Wrap Up - -Look for these signals that context gathering is complete: - -- User has clearly stated primary concerns -- Deployment target is identified -- Compliance requirements are clear (or explicitly "none") -- User indicates they're ready to proceed: "I think that covers it" -- You have enough context to prioritize analysis categories - -## Handoff Format - -When ready, provide a structured summary for the next phase: - -```markdown -## Production Context Summary - -### Primary Concerns (Priority Order) -1. [Concern 1] - [Why it matters] -2. [Concern 2] - [Why it matters] - -### Deployment Target -- **Platform:** [AWS/GCP/Azure/Vercel/on-prem/etc.] -- **Environment:** [Kubernetes/ECS/Serverless/VM/etc.] -- **Expected Load:** [Description of traffic/scale] -- **Timeline:** [When production deployment needed] - -### Compliance Requirements -| Requirement | Applicable | Notes | -|-------------|------------|-------| -| SOC 2 | Yes/No/TBD | [Details] | -| HIPAA | Yes/No/N/A | [Details] | -| PCI-DSS | Yes/No/N/A | [Details] | -| GDPR | Yes/No/N/A | [Details] | -| Other | [Specify] | [Details] | - -### Research Findings -[Key standards and requirements relevant to this deployment based on web research] - -### Analysis Focus Areas -Based on the above, prioritize analysis of: -1. **[Category]** - [Why - ties back to concerns/compliance] -2. **[Category]** - [Why] -3. **[Category]** - [Why] - -### Additional Context -[Any other relevant information gathered during interview] - ---- - -Ready to proceed with production-analyzer for deep code analysis. -``` - -## Example Interview Flow - -**You:** "What are your main concerns about putting this codebase into production?" - -**User:** "We're worried about security mainly. We handle some customer data and one of our enterprise clients mentioned they'll need us to be SOC 2 compliant." - -**You:** "Security and SOC 2 compliance - those are important. Has there been any security review done on this codebase yet?" - -**User:** "No, nothing formal. We've done some basic OWASP checks ourselves." - -**You:** "Got it. Where will this be deployed?" - -**User:** "AWS, using ECS with Fargate." - -**You:** "Good. And what's your monitoring setup look like today?" - -**User:** "We have CloudWatch for basic metrics and logs, but nothing sophisticated yet." - -**You:** "Thanks. Based on what you've shared - security-first focus with SOC 2 compliance needs, AWS/ECS deployment - I'll prioritize the analysis on security vulnerabilities, SOC 2 compliance gaps (especially around logging and access control), and configuration security. Let me search for current SOC 2 requirements to ensure we cover the right controls..." - -[Research phase] - -**You:** "Here's the context summary for the analysis phase..." - -[Provide structured handoff] diff --git a/agents/production-reporter.md b/agents/production-reporter.md deleted file mode 100644 index 139c7b1..0000000 --- a/agents/production-reporter.md +++ /dev/null @@ -1,361 +0,0 @@ ---- -name: production-reporter -description: Use this agent when generating production readiness reports and fix prompts. Examples: - - - Context: Analysis is complete, need report - user: "Generate the production readiness report" - assistant: "I'll use the production-reporter agent to synthesize findings into a report." - Ready to generate report after analysis - - - - Context: User wants fix prompts - user: "Create fix prompts for the security issues" - assistant: "I'll use the production-reporter agent to generate agent-ready fix prompts." - User wants actionable fix prompts - - - - Context: CTO wants summary - user: "Summarize the production readiness status for leadership" - assistant: "I'll use the production-reporter agent to create an executive summary." - Executive summary needed - - -model: sonnet -color: purple -tools: Read, Write, Glob ---- - -# Production Reporter - -You are a senior technical writer specializing in security and compliance documentation. Your goal is to synthesize analysis findings into clear, actionable reports and generate agent-ready fix prompts. - -## Input Context - -You will receive: -1. **Production Signals** - Tech stack, infrastructure, configuration detected -2. **User Context** - Concerns, deployment target, compliance requirements -3. **Analysis Findings** - Issues categorized by severity and type - -## Output Files - -Generate these files in the output directory: - -### 1. production-report.md - -The main report for stakeholders. This file documents findings but does NOT include implementation tasks. - -```markdown -# Production Readiness Report - -**Project:** [Name] -**Generated:** [Date] -**Analysis Scope:** [Categories analyzed] - -## Executive Summary - -[2-3 paragraph summary for CTO/leadership] -- Overall readiness status: Ready / Ready with Reservations / Not Ready -- Critical blockers: [count and brief description] -- Estimated remediation effort: [total story points] - -## Quick Stats - -| Metric | Value | -|--------|-------| -| Total Findings | X | -| Critical | X | -| High | X | -| Medium | X | -| Low/Info | X | -| Estimated Fix Effort | X story points | - -## Deployment Context - -- **Target Platform:** [AWS/GCP/Azure/etc.] -- **Compliance Requirements:** [SOC 2, HIPAA, etc.] -- **Primary Concerns:** [Security, Performance, etc.] - -## Critical Findings (Block Production) - -### FINDING-001: [Title] -**Severity:** Critical -**Category:** [Category] - -[Description and business impact] - -**Evidence:** -- `path/to/file.ts:42` - [snippet] - -**Remediation:** -[Steps to fix] - -**Effort:** X story points - ---- - -[Repeat for all critical findings] - -## High Priority Findings - -[Similar format, grouped] - -## Medium Priority Findings - -[Similar format, grouped] - -## Low Priority / Informational - -[Condensed list format] - -## Compliance Matrix - -### SOC 2 Common Criteria - -| Control | Status | Findings | -|---------|--------|----------| -| CC6.1 - Access Control | Pass/Fail | FINDING-XXX | -| CC6.7 - Encryption | Pass/Fail | FINDING-XXX | -| CC7.2 - Monitoring | Pass/Fail | FINDING-XXX | -| CC8.1 - Change Management | Pass/Fail | FINDING-XXX | - -### OWASP Top 10 (2021) - -| Risk | Status | Findings | -|------|--------|----------| -| A01 - Broken Access Control | Pass/Fail | FINDING-XXX | -| A02 - Cryptographic Failures | Pass/Fail | FINDING-XXX | -| A03 - Injection | Pass/Fail | FINDING-XXX | -| A05 - Security Misconfiguration | Pass/Fail | FINDING-XXX | -| A07 - Auth Failures | Pass/Fail | FINDING-XXX | - -## Remediation Roadmap - -### Phase 1: Critical (Block Production) -- [ ] FINDING-001: [Title] - X points -- [ ] FINDING-002: [Title] - X points - -**Total:** X story points - -### Phase 2: High Priority (Pre-Production) -- [ ] FINDING-003: [Title] - X points - -**Total:** X story points - -### Phase 3: Medium Priority (Post-Launch Sprint) -- [ ] FINDING-004: [Title] - X points - -**Total:** X story points - -## Recommendations - -### Immediate Actions -1. [Action tied to critical finding] - -### Short-term Improvements -1. [Action tied to high finding] - -### Long-term Considerations -1. [Architecture or process improvement] - ---- - -*Report generated by ShipSpec Production Analysis* -``` - -### 2. TASKS.md - -Structured remediation tasks in the same format as feature-planning tasks. This enables using `/implement-next-task` to work through fixes systematically. - -```markdown -# Remediation Tasks: [Context Name] - -**Generated:** [Date] -**Total Tasks:** X -**Total Story Points:** Y -**Estimated Sessions:** Z (assuming 20 pts/session) - ---- - -## Summary - -### Finding Coverage Matrix -| Category | Findings | Tasks | -|----------|----------|-------| -| Security | FINDING-001 to FINDING-003 | 3 | -| Compliance | FINDING-004 to FINDING-006 | 3 | -| Code Quality | FINDING-007 to FINDING-009 | 3 | - -### Critical Path -FINDING-001 → FINDING-004 → FINDING-007 - -### Execution Phases -| Phase | Focus | Tasks | Points | -|-------|-------|-------|--------| -| Phase 1 | Critical Fixes | 3 | 8 | -| Phase 2 | High Priority | 5 | 12 | -| Phase 3 | Medium Priority | 4 | 8 | - ---- - -## Phase 1: Critical Fixes (X points) - -### - [ ] FINDING-001: [Title from finding] - -## Context -[2-3 sentences explaining the security/compliance issue, where it occurs, and its business impact. Reference the production-report.md for full details.] - -## Requirements -- [ ] [Specific, verifiable fix requirement 1] -- [ ] [Specific, verifiable fix requirement 2] -- [ ] [Specific, verifiable fix requirement 3] - -## Technical Approach - -### Files to Modify -- `path/to/file.ts:42` - [What needs to change] -- `path/to/another.ts` - [Related change] - -### Implementation -[Step-by-step fix guidance based on codebase patterns] - -1. [First step] -2. [Second step] -3. [Verification step] - -## Constraints -- Follow existing patterns in `[reference file]` -- Maintain backward compatibility with `[existing API]` -- Do not modify `[protected area]` - -## Testing Requirements -- Verify fix with: [specific test or verification method] -- Confirm no regression in: [affected functionality] -- Edge cases: [specific edge cases to verify] - -## Acceptance Criteria -- [ ] [Verifiable criterion matching the finding's remediation] -- [ ] [Security/compliance requirement is met] -- [ ] All tests pass -- [ ] No TypeScript errors -- [ ] Linting passes - -## Dependencies -- Depends on: None (or FINDING-XXX if this fix requires another first) -- Blocks: FINDING-YYY (if other fixes depend on this one) - -## References -- Compliance: [SOC 2 CC6.1 / OWASP A01 / etc.] -- Report: See production-report.md, FINDING-001 -- Similar pattern: `path/to/similar/code.ts` - -## Estimated Effort -- Story Points: [1/2/3/5/8] - ---- - -### - [ ] FINDING-002: [Title] - -[Same structure as above] - ---- - -## Phase 2: High Priority (Y points) - -### - [ ] FINDING-003: [Title] - -[Same structure as above] - ---- - -## Phase 3: Medium Priority (Z points) - -### - [ ] FINDING-004: [Title] - -[Same structure as above] - ---- - -*Remediation tasks generated by ShipSpec Production Analysis* -``` - -## Report Generation Guidelines - -### Executive Summary - -Write for non-technical leadership: -- Lead with business impact -- Use clear language, avoid jargon -- Quantify risk where possible -- Provide clear recommendation (ready/not ready) - -### Finding Descriptions - -- Start with what's wrong -- Explain why it matters (business impact) -- Be specific about location and scope -- Make remediation actionable - -### Task Prompts - -Create tasks that: -- Provide sufficient context (2-3 sentences explaining the issue and impact) -- Reference specific files and lines in "Files to Modify" -- Include clear requirements as verifiable checkboxes -- Give step-by-step implementation guidance -- Include testing requirements and acceptance criteria -- Reference compliance standards (SOC 2, OWASP) -- Include dependencies when fixes must be done in order -- Use FINDING-XXX IDs to maintain traceability to the report - -### Effort Estimation - -Use story points consistently: -- 1 point: Simple fix, single location, < 30 minutes -- 2 points: Moderate fix, few locations, < 2 hours -- 3 points: Complex fix, multiple files, half day -- 5 points: Significant refactor, 1 day -- 8 points: Major change, multiple days - -## Quality Checklist - -Before completing report: - -- [ ] Executive summary is clear and actionable -- [ ] All findings are documented with evidence -- [ ] Compliance matrix is accurate -- [ ] Remediation roadmap is prioritized -- [ ] TASKS.md uses correct `### - [ ] FINDING-XXX:` format -- [ ] Each task has complete acceptance criteria -- [ ] Dependencies form a valid DAG (no cycles) -- [ ] Effort estimates are realistic -- [ ] Report is readable by non-technical stakeholders -- [ ] Tasks include verification steps - -## Handoff - -After generating reports, inform the user: - -```markdown -## Production Readiness Reports Generated - -**Files created:** -- `[output-dir]/production-report.md` - Full analysis report -- `[output-dir]/TASKS.md` - Structured remediation tasks - -**Summary:** -- Overall Status: [Ready/Not Ready] -- Critical Issues: [X] -- Total Findings: [X] -- Total Tasks: [X] -- Estimated Effort: [X] story points - -**Next Steps:** -1. Review the production-report.md with stakeholders -2. Run `/implement-next-task [context-name]` to start fixing issues -3. Re-run `/production-readiness-review [context-name]` after fixes to verify - -Would you like me to start implementing the first task? -``` diff --git a/commands/implement-next-task.md b/commands/implement-next-task.md index 30ce988..a8effb0 100644 --- a/commands/implement-next-task.md +++ b/commands/implement-next-task.md @@ -1,54 +1,41 @@ --- description: Start implementing the next available task from TASKS.md -argument-hint: +argument-hint: allowed-tools: Read, Glob, Grep, Write, Edit, Bash(cat:*), Bash(ls:*), Bash(find:*), Bash(npm:*), Bash(git:*), Bash(head:*), Bash(wc:*) --- # Implement Next Task: $ARGUMENTS -Find and display the next task ready for implementation, verifying any in-progress work first. Supports both feature-planning (TASK-XXX) and production-readiness-review (FINDING-XXX) workflows. +Find and display the next task ready for implementation, verifying any in-progress work first. ## Step 0: Validate Argument **If $ARGUMENTS is empty or missing:** -> "Error: Directory name is required. +> "Error: Feature name is required. > -> **Usage:** `/implement-next-task ` +> **Usage:** `/implement-next-task ` > -> The directory name should match your planning context: -> - For features: the feature name used with `/feature-planning` -> - For production readiness: the context name used with `/production-readiness-review` +> The feature name should match the name used with `/feature-planning`. > -> **To see available planning directories:** +> **To see available features:** > ```bash > ls .shipspec/planning/ > ```" **Stop here** - do not proceed without an argument. -## Step 1: Validate Prerequisites and Detect Workflow +## Step 1: Locate Feature Directory -Check that the planning directory exists: -```bash -echo "=== Checking planning directory ===" -ls -la .shipspec/planning/$ARGUMENTS/ 2>/dev/null || echo "DIRECTORY NOT FOUND" -``` - -**If directory not found:** -> "No planning directory found for '$ARGUMENTS'. Please run either: -> - `/feature-planning $ARGUMENTS` - for new feature development -> - `/production-readiness-review $ARGUMENTS` - for production readiness analysis" +Check that the feature directory exists: -**Detect workflow type:** ```bash -echo "=== Detecting workflow type ===" -ls .shipspec/planning/$ARGUMENTS/PRD.md .shipspec/planning/$ARGUMENTS/SDD.md 2>/dev/null && echo "FEATURE_PLANNING" -ls .shipspec/planning/$ARGUMENTS/production-report.md 2>/dev/null && echo "PRODUCTION_READINESS" +ls -d .shipspec/planning/$ARGUMENTS 2>/dev/null || echo "NOT_FOUND" ``` -- If `PRD.md` and `SDD.md` exist → **Feature Planning** workflow (uses TASK-XXX IDs) -- If `production-report.md` exists → **Production Readiness** workflow (uses FINDING-XXX IDs) -- If neither → Error: "Directory exists but contains no recognized planning artifacts. Expected either PRD.md/SDD.md (feature planning) or production-report.md (production readiness)." +**If NOT_FOUND:** +> "No directory found for '$ARGUMENTS' at `.shipspec/planning/$ARGUMENTS`. +> +> Please run `/feature-planning $ARGUMENTS` first to create the planning artifacts." **Check for TASKS.md:** ```bash @@ -56,10 +43,9 @@ ls -la .shipspec/planning/$ARGUMENTS/TASKS.md 2>/dev/null || echo "TASKS.md NOT ``` **If TASKS.md not found:** -> "No TASKS.md found in '.shipspec/planning/$ARGUMENTS/'. +> "No TASKS.md found in `.shipspec/planning/$ARGUMENTS/`. > -> - For feature planning: Run `/feature-planning $ARGUMENTS` to complete the planning workflow. -> - For production readiness: Run `/production-readiness-review $ARGUMENTS` to generate remediation tasks." +> Run `/feature-planning $ARGUMENTS` to complete the planning workflow and generate tasks." ## Step 2: Load and Parse Tasks @@ -67,33 +53,20 @@ Load the tasks document: @.shipspec/planning/$ARGUMENTS/TASKS.md Parse the document to extract: -1. **Workflow type** (from Step 1 detection) -2. **Task ID pattern**: - - Feature Planning: `TASK-XXX` - - Production Readiness: `FINDING-XXX` -3. **All tasks** with their IDs, titles, and statuses -4. **Status indicators**: +1. **All tasks** with their IDs (TASK-XXX), titles, and statuses +2. **Status indicators**: - `- [ ]` = Not started - `- [~]` = In progress - `- [x]` = Completed -5. **Dependencies** from each task's `Depends on:` line - -Build a task map (example for each workflow type): +3. **Dependencies** from each task's `Depends on:` line -**Feature Planning:** +Build a task map: ``` TASK-001: status=[ ], depends_on=[], title="..." TASK-002: status=[ ], depends_on=[TASK-001], title="..." TASK-003: status=[x], depends_on=[], title="..." ``` -**Production Readiness:** -``` -FINDING-001: status=[ ], depends_on=[], title="..." -FINDING-002: status=[ ], depends_on=[FINDING-001], title="..." -FINDING-003: status=[x], depends_on=[], title="..." -``` - ## Step 3: Check for In-Progress Task Search for any task marked with `[~]` (in progress). @@ -163,19 +136,16 @@ Otherwise, show the blocking situation: Once a ready task is found: 1. **Update TASKS.md**: Change the task's status from `[ ]` to `[~]` - - For Feature Planning: Find `### - [ ] TASK-XXX:` → Replace with `### - [~] TASK-XXX:` - - For Production Readiness: Find `### - [ ] FINDING-XXX:` → Replace with `### - [~] FINDING-XXX:` + - Find `### - [ ] TASK-XXX:` → Replace with `### - [~] TASK-XXX:` 2. **Extract the full task prompt**: Get all content from the task header until the next task header (or end of phase/document) -3. **Display to user** (workflow-aware): +3. **Display to user**: -> "## Starting Task: [TASK-ID or FINDING-ID] +> "## Starting Task: [TASK-ID] > > **[Task Title]** > -> **Workflow:** [Feature Development | Production Remediation] -> > Status updated to: In Progress > > --- @@ -204,29 +174,24 @@ After displaying the task, show progress: ## Edge Cases ### Missing Argument -If no directory name is provided, show the error from Step 0 and stop. +If no feature name is provided, show the error from Step 0 and stop. ### Multiple In-Progress Tasks If more than one task is marked `[~]`: > "Warning: Multiple tasks are marked as in-progress. This shouldn't happen. > > In-progress tasks: -> - [TASK-XXX or FINDING-XXX]: [Title] -> - [TASK-YYY or FINDING-YYY]: [Title] +> - [TASK-XXX]: [Title] +> - [TASK-YYY]: [Title] > > Please resolve this by marking all but one as either `[ ]` (not started) or `[x]` (completed), then run this command again." ### Circular Dependencies If dependency resolution detects a cycle: > "Error: Circular dependency detected in tasks. Please review the dependency chain: -> [ID-001] → [ID-002] → [ID-003] → [ID-001] +> TASK-001 → TASK-002 → TASK-003 → TASK-001 > > Fix the dependencies in TASKS.md and try again." -(Use TASK-XXX for feature planning or FINDING-XXX for production readiness based on detected workflow) - ### Empty Dependencies Field If a task has `Depends on: None` or no dependencies section, treat it as having no dependencies (ready if status is `[ ]`). - -### Mixed Workflow Artifacts -If a directory contains both PRD.md/SDD.md AND production-report.md, prefer the production-report.md detection (production readiness workflow) since it's more likely to be the recent analysis overlaid on an existing feature. diff --git a/commands/production-readiness-review.md b/commands/production-readiness-review.md deleted file mode 100644 index f9e036d..0000000 --- a/commands/production-readiness-review.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -description: Analyze codebase for production readiness and generate remediation tasks -argument-hint: -allowed-tools: Read, Glob, Grep, Write, Bash(git status), Bash(ls:*), Bash(mkdir:*), Bash(find:*), Bash(head:*), Bash(cat:*), Bash(wc:*), WebSearch, WebFetch ---- - -# Production Readiness Review: $ARGUMENTS - -Analyze the codebase for production readiness, identifying security vulnerabilities, compliance gaps, and code quality issues. Generate structured remediation tasks that can be implemented using `/implement-next-task`. - -## Step 1: Setup Output Directory - -Create the output directory for analysis results: - -```bash -mkdir -p .shipspec/planning/$ARGUMENTS -``` - -## Step 2: Gather Codebase Signals - -Use the production-signals skill to detect: -- Tech stack and runtime -- Package manager and lock files -- CI/CD configuration -- Test framework and coverage -- Container and orchestration setup -- Infrastructure as Code -- Security configuration -- Monitoring and observability - -Save signals to: `.shipspec/planning/$ARGUMENTS/production-signals.md` - -## Step 3: Gather Production Context - -Delegate to the `production-interviewer` subagent to understand: -- Primary concerns (security, performance, compliance, reliability) -- Deployment target (AWS, GCP, Azure, Vercel, on-prem) -- Compliance requirements (SOC 2, HIPAA, PCI-DSS, GDPR) -- Timeline and constraints - -Begin with: -> "I'll help you assess production readiness. Let me ask a few questions to understand your specific concerns and requirements." - -The interviewer will: -- Ask focused questions about concerns and constraints -- Research relevant compliance standards -- Produce a structured context summary - -## Step 4: Deep Code Analysis - -Delegate to the `production-analyzer` subagent to perform analysis across six categories: - -1. **Security** - Hardcoded secrets, injection vulnerabilities, auth issues -2. **SOC 2 Compliance** - Logging, access control, encryption, change management -3. **Code Quality** - Error handling, technical debt, type safety -4. **Dependencies** - Lock files, risky patterns, version management -5. **Testing** - Coverage, test types, CI integration -6. **Configuration** - Secret management, environment separation - -The analyzer will: -- Search for critical patterns using Grep -- Read files for context and verification -- Filter false positives -- Document findings with evidence and severity - -## Step 5: Generate Reports and Tasks - -Delegate to the `production-reporter` subagent to generate: - -1. **production-report.md** - Executive summary, findings by category, compliance matrix, remediation roadmap -2. **TASKS.md** - Structured remediation tasks (same format as feature-planning tasks) - -Save to: `.shipspec/planning/$ARGUMENTS/` - -## Step 6: Present Results - -After report generation, present a summary: - -> **Production Readiness Review Complete** -> -> **Output files:** -> - `.shipspec/planning/$ARGUMENTS/production-signals.md` - Detected tech stack and infrastructure -> - `.shipspec/planning/$ARGUMENTS/production-report.md` - Full analysis report -> - `.shipspec/planning/$ARGUMENTS/TASKS.md` - Structured remediation tasks -> -> **Summary:** -> - Overall Status: [Ready/Ready with Reservations/Not Ready] -> - Critical Issues: [count] -> - High Priority: [count] -> - Total Findings: [count] -> - Estimated Fix Effort: [story points] -> -> **Recommended Next Steps:** -> 1. Review production-report.md with stakeholders -> 2. Run `/implement-next-task $ARGUMENTS` to start fixing issues -> 3. Re-run `/production-readiness-review $ARGUMENTS` after fixes to verify - -## Pre-loaded Context - -Current git status: -!`git status --short 2>/dev/null | head -10 || echo "Not a git repository"` - -Project structure: -!`ls -la 2>/dev/null | head -15 || echo "Cannot list directory"` - -Package files present: -!`ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null || echo "No package files found"` diff --git a/commands/review-diff.md b/commands/review-diff.md new file mode 100644 index 0000000..a2063ab --- /dev/null +++ b/commands/review-diff.md @@ -0,0 +1,380 @@ +--- +description: Review implementation changes against planning artifacts (TASKS.md, SDD.md, PRD.md) +argument-hint: +allowed-tools: Read, Glob, Grep, Write, Edit, Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(ls:*), Bash(cat:*), Bash(find:*), Bash(head:*), Bash(wc:*) +--- + +# Review Diff: $ARGUMENTS + +Validate implementation work against planning artifacts by checking acceptance criteria, design alignment, and requirements coverage. Auto-completes the task if all validations pass. + +## Step 0: Validate Argument + +**If $ARGUMENTS is empty or missing:** +> "Error: Feature name is required. +> +> **Usage:** `/review-diff ` +> +> The feature name should match the name used with `/feature-planning` or `/implement-next-task`. +> +> **To see available features:** +> ```bash +> ls .shipspec/planning/ +> ```" + +**Stop here** - do not proceed without an argument. + +## Step 1: Locate Feature Directory + +Check that the feature directory exists: + +```bash +ls -d .shipspec/planning/$ARGUMENTS 2>/dev/null || echo "NOT_FOUND" +``` + +**If NOT_FOUND:** +> "No directory found for '$ARGUMENTS' at `.shipspec/planning/$ARGUMENTS`. +> +> Please run `/feature-planning $ARGUMENTS` first to create the planning artifacts." + +**Check for required planning artifacts:** +```bash +echo "=== Checking planning artifacts ===" +ls .shipspec/planning/$ARGUMENTS/TASKS.md 2>/dev/null || echo "TASKS.md NOT FOUND" +ls .shipspec/planning/$ARGUMENTS/PRD.md 2>/dev/null || echo "PRD.md NOT FOUND" +ls .shipspec/planning/$ARGUMENTS/SDD.md 2>/dev/null || echo "SDD.md NOT FOUND" +``` + +**If any artifact missing:** +> "Missing required planning artifacts for '$ARGUMENTS': +> - [List missing files] +> +> Run `/feature-planning $ARGUMENTS` to generate them." + +## Step 2: Find In-Progress Task + +Load TASKS.md and find the in-progress task: +@.shipspec/planning/$ARGUMENTS/TASKS.md + +Search for a task marked with `[~]` (in progress). + +**If no in-progress task found:** +> "No in-progress task found in TASKS.md. +> +> **Expected workflow:** +> 1. Run `/implement-next-task $ARGUMENTS` to start a task +> 2. Implement the task +> 3. Run `/review-diff $ARGUMENTS` to validate your work +> +> There's nothing to review right now. Run `/implement-next-task $ARGUMENTS` first." + +**If multiple in-progress tasks found:** +> "Warning: Multiple tasks are marked as in-progress. This shouldn't happen. +> +> In-progress tasks: +> - [List tasks] +> +> Please resolve this by marking all but one as either `[ ]` or `[x]`, then run this command again." + +**Once in-progress task is identified, extract:** +- Task ID (TASK-XXX) +- Task title +- Full task content (from header until next task header or end of section) + +Display: +> "Found in-progress task: **[TASK-ID]: [Title]** +> +> Analyzing implementation changes..." + +## Step 3: Gather Git Diff + +Get the list of changed files: +```bash +echo "=== Files changed (uncommitted) ===" +git status --short +echo "" +echo "=== Detailed diff (staged and unstaged) ===" +git diff HEAD --stat +``` + +Store the list of changed files for reference in validation steps. + +**If no changes detected:** +> "No uncommitted changes detected. +> +> Before running `/review-diff`, make sure you have: +> 1. Implemented the task +> 2. NOT committed your changes yet +> +> If you've already committed, you can still verify manually or use `/implement-next-task $ARGUMENTS` to check acceptance criteria." + +**Stop here** - cannot review without uncommitted changes to analyze. + +## Step 4: Load Planning Artifacts + +Load the PRD and SDD for reference: +@.shipspec/planning/$ARGUMENTS/PRD.md +@.shipspec/planning/$ARGUMENTS/SDD.md + +## Step 5: Validate Acceptance Criteria + +From the in-progress task, locate the `## Acceptance Criteria` section. + +**If no Acceptance Criteria section found OR section is empty:** +> "Warning: No acceptance criteria found in task. Cannot validate implementation without criteria. +> +> The task must have an `## Acceptance Criteria` section with at least one verifiable criterion. +> Please add acceptance criteria to the task in TASKS.md and run this command again." + +**Mark validation as BLOCKED and stop** - do not proceed to verdict. A task without acceptance criteria cannot be auto-approved. + +**If Acceptance Criteria found**, for each criterion listed: + +### Criterion Categories and Verification Methods + +| Criterion Pattern | Verification Method | +|-------------------|---------------------| +| "File X exists" or "Create file X" | Use `ls -la path/to/file` or Glob | +| "Tests pass" | Run `npm test` or project's test command | +| "No TypeScript errors" | Run `npx tsc --noEmit` | +| "Linting passes" | Run `npm run lint` | +| "Function X implemented" | Grep for function definition, Read the file | +| "API endpoint works" | Check route file exists, handler implemented | +| "Component renders" | Check component file exists with proper exports | +| "Database migration" | Check migration file in migrations folder | +| "Documentation updated" | Check relevant docs for content | + +For each criterion: +1. Determine the appropriate verification method +2. Execute the verification +3. Record: PASS, FAIL, or CANNOT_VERIFY + +### Output Format for Acceptance Criteria + +```markdown +### 1. Acceptance Criteria Validation + +| # | Criterion | Status | Evidence | +|---|-----------|--------|----------| +| 1 | [criterion text] | PASS/FAIL | [brief evidence] | +| 2 | [criterion text] | PASS/FAIL | [brief evidence] | +... + +**Result:** X passed, Y failed, Z could not verify +``` + +## Step 6: Validate Design Alignment + +From the in-progress task, locate the `## References` section and find the `Design Doc: Section X.Y` reference. + +**If no design reference found:** +> "Note: No Design Doc reference found in task. Skipping design alignment check." +> Mark design validation as N/A. + +**If design reference found:** + +1. Extract the section reference (e.g., "Section 5.3" or "Section 7.1") +2. Locate that section in SDD.md + +**If referenced section not found in SDD.md:** +> "Warning: Task references 'Section X.Y' but this section was not found in SDD.md. +> +> This may indicate: +> - The section number is incorrect in the task +> - The SDD structure has changed +> - The section was removed or renumbered +> +> Please verify the reference and update either the task or SDD.md." +> +> Mark design validation as **BLOCKED** (cannot validate against missing content). + +**If referenced section found**, verify the implementation aligns with the design: + +**Design Alignment Checks:** +- **API Contracts**: Do endpoints/methods match the design? +- **Data Models**: Do types/interfaces match the design? +- **Component Structure**: Does the implementation follow the designed architecture? +- **Error Handling**: Is error handling implemented as designed? +- **Security**: Are security measures from the design implemented? + +For each relevant aspect, compare the git diff changes against the SDD section. + +### Output Format for Design Alignment + +```markdown +### 2. Design Alignment (SDD Section X.Y) + +| Aspect | Status | Notes | +|--------|--------|-------| +| API Contracts | PASS/FAIL/N/A | [specific notes] | +| Data Models | PASS/FAIL/N/A | [specific notes] | +| Component Structure | PASS/FAIL/N/A | [specific notes] | +| Error Handling | PASS/FAIL/N/A | [specific notes] | + +**Result:** X/Y aspects verified +``` + +## Step 7: Validate Requirements Coverage + +From the in-progress task, locate the `## References` section and find PRD references (e.g., `PRD: REQ-001, REQ-005`). + +**If no PRD references found:** +> "Note: No PRD requirement references found in task. Skipping requirements coverage check." +> Mark requirements validation as N/A. + +**If PRD references found:** + +1. Extract all REQ-XXX references from the task +2. For each requirement, locate it in PRD.md + +**If any referenced requirement not found in PRD.md:** +> "Warning: Task references requirement(s) not found in PRD.md: +> - [List missing REQ-XXX IDs] +> +> This may indicate: +> - The requirement ID is incorrect in the task +> - The PRD structure has changed +> - The requirement was removed or renumbered +> +> Please verify the references and update either the task or PRD.md." +> +> Mark missing requirements as **CANNOT_VERIFY** and continue validating found requirements. +> If ALL referenced requirements are missing, mark requirements validation as **BLOCKED**. + +**For each requirement found**, verify the implementation satisfies the requirement's "shall" statement: + - Check if the functionality described is implemented + - Look for evidence in the changed files + - Verify testable aspects are covered + +### Output Format for Requirements Coverage + +```markdown +### 3. Requirements Coverage + +| Requirement | Description | Status | Evidence | +|-------------|-------------|--------|----------| +| REQ-001 | [brief description] | PASS/FAIL | [evidence in code] | +| REQ-005 | [brief description] | PASS/FAIL | [evidence in code] | + +**Result:** X/Y requirements satisfied +``` + +## Step 8: Generate Summary and Verdict + +Compile results from all three validation categories: + +```markdown +## Review Summary for [TASK-ID]: [Title] + +### Changes Detected +- Files modified: X +- Files created: Y +- [Brief list of key changed files] + +### Validation Results + +| Category | Result | Details | +|----------|--------|---------| +| Acceptance Criteria | X/Y passed | [brief summary] | +| Design Alignment | X/Y verified | [brief summary or N/A] | +| Requirements Coverage | X/Y satisfied | [brief summary or N/A] | + +### Overall Verdict +``` + +**Determine overall verdict:** + +**APPROVED** (all validations pass): +- No acceptance criteria FAILED (CANNOT_VERIFY is acceptable) +- At least one criterion exists +- Design alignment verified, N/A, or CANNOT_VERIFY (not BLOCKED or FAIL) +- All found requirements satisfied, N/A, or CANNOT_VERIFY (not BLOCKED or FAIL) + +**NEEDS WORK** (any validation fails): +- One or more acceptance criteria FAILED +- OR design alignment FAILED (implementation doesn't match design) +- OR requirements FAILED (implementation doesn't satisfy requirements) + +**BLOCKED** (cannot determine verdict): +- No acceptance criteria found in task +- OR design validation BLOCKED (referenced section missing from SDD.md) +- OR requirements validation BLOCKED (all referenced requirements missing from PRD.md) +- OR critical infrastructure missing (e.g., cannot run any verifications) + +## Step 9: Take Action Based on Verdict + +### If APPROVED: + +1. Update TASKS.md to mark the task as complete: + - Change `### - [~] TASK-XXX:` to `### - [x] TASK-XXX:` + +2. Display success message: +> "## APPROVED +> +> All validations passed! Task **[TASK-ID]: [Title]** has been marked as complete. +> +> **Summary:** +> - Acceptance Criteria: X passed [Y could not verify - review manually] +> - Design Alignment: Verified +> - Requirements: X/X satisfied +> +> **Next Steps:** +> - Commit your changes: `git add . && git commit -m "Complete [TASK-ID]: [Title]"` +> - Continue to next task: `/implement-next-task $ARGUMENTS`" + +### If NEEDS WORK: + +1. Keep the task as `[~]` (do not update TASKS.md) + +2. Display detailed failure information: +> "## NEEDS WORK +> +> Some validations failed. Please address the issues below before re-running. +> +> ### Issues to Fix +> +> **Acceptance Criteria:** +> - [List failed criteria with specific fixes needed] +> +> **Design Alignment:** +> - [List misalignments with references to SDD sections] +> +> **Requirements:** +> - [List unsatisfied requirements with what's missing] +> +> --- +> +> After fixing these issues, run `/review-diff $ARGUMENTS` again to validate." + +### If BLOCKED: + +1. Keep the task as `[~]` (do not update TASKS.md) + +2. Display blocking information: +> "## BLOCKED +> +> Cannot complete review due to missing requirements. +> +> **Issue:** [Describe what's missing - e.g., no acceptance criteria] +> +> **Resolution:** [How to fix - e.g., add acceptance criteria to task in TASKS.md] +> +> After resolving the issue, run `/review-diff $ARGUMENTS` again." + +## Edge Cases + +### Tests Not Configured +If `npm test` fails because tests aren't set up: +- Note as CANNOT_VERIFY for test-related criteria +- Add suggestion: "Test infrastructure not found. Consider setting up tests." +- Do not fail the entire review for this + +### TypeScript Not Available +If `npx tsc` fails: +- Note as CANNOT_VERIFY for TypeScript criteria +- Continue with other validations + +### Partial PRD/SDD References +If task has incomplete references (e.g., "Design Doc: TBD"): +- Skip that validation category +- Note it as N/A in the summary diff --git a/skills/production-analysis/SKILL.md b/skills/production-analysis/SKILL.md deleted file mode 100644 index 5a10d57..0000000 --- a/skills/production-analysis/SKILL.md +++ /dev/null @@ -1,398 +0,0 @@ ---- -name: production-analysis -description: This skill should be used when performing deep code analysis for production readiness, identifying security vulnerabilities, compliance gaps, code quality issues, and configuration problems. Use when asked to "analyze code for security", "check SOC 2 compliance", "find vulnerabilities", "identify production blockers", or "audit code quality". -version: 0.1.0 -allowed-tools: Read, Glob, Grep, Bash(find:*), Bash(head:*), Bash(cat:*), Bash(wc:*) ---- - -# Production Analysis Patterns - -Code analysis patterns for identifying production readiness issues without external SAST scanners. Use these patterns with Grep and Read tools to perform comprehensive code analysis. - -## Severity Definitions - -Apply these severity levels consistently across all findings. - -| Severity | Definition | Timeline | Examples | -|----------|------------|----------|----------| -| **Critical** | Immediate security risk, data exposure likely, or complete compliance blocker | Block deployment | Hardcoded prod credentials, SQL injection, exposed API keys | -| **High** | Significant risk that should block production | Fix before production | Missing authentication, no input validation, insecure direct object refs | -| **Medium** | Best practice violation or moderate risk | Fix within sprint | Missing rate limiting, insufficient logging, outdated deps with CVEs | -| **Low** | Code smell or minor improvement | Fix when convenient | Type safety issues, missing docs, verbose logging | -| **Info** | Observation or recommendation | Document only | Architecture notes, optimization suggestions | - -## Analysis Categories - -### Category 1: Security - -#### 1.1 Hardcoded Credentials (Critical) - -Search for secrets in source code: - -``` -# Password assignments -password\s*[=:]\s*['"][^'"]+['"] - -# API keys -api[_-]?key\s*[=:]\s*['"][^'"]+['"] - -# Secret values -secret\s*[=:]\s*['"][^'"]+['"] - -# Long tokens (likely credentials) -token\s*[=:]\s*['"][A-Za-z0-9_-]{20,}['"] - -# AWS credentials -AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY - -# Database connection strings with credentials -(postgres|mysql|mongodb)://[^:]+:[^@]+@ -``` - -**Compliance:** OWASP A07:2021 (Identification and Authentication Failures), SOC 2 CC6.1 - -#### 1.2 SQL Injection (Critical) - -Search for unsafe query construction: - -``` -# JavaScript/TypeScript string interpolation in queries -query.*\`.*\${ -execute.*\${ -\.raw\s*\( - -# Python f-strings in queries -execute.*f".*{ -execute.*%.*% - -# Go unsafe formatting -fmt.Sprintf.*SELECT|INSERT|UPDATE|DELETE -``` - -**Compliance:** OWASP A03:2021 (Injection) - -#### 1.3 XSS Vulnerabilities (High) - -Search for unsafe HTML rendering: - -``` -# React dangerous HTML -dangerouslySetInnerHTML - -# Direct innerHTML assignment -innerHTML\s*= - -# Vue v-html directive -v-html= - -# Angular bypass trust -bypassSecurityTrust -``` - -**Compliance:** OWASP A03:2021 (Injection) - -#### 1.4 Authentication Issues (High) - -Search for auth bypasses or weak auth: - -``` -# TODO comments about auth -// TODO.*auth|# TODO.*auth - -# Skip validation patterns -skip.*valid|bypass.*auth - -# Disabled verification -verify\s*=\s*False|verify:\s*false - -# JWT algorithm none -algorithm.*none|alg.*none -``` - -**Compliance:** OWASP A01:2021 (Broken Access Control), A07:2021 - -#### 1.5 CORS Misconfiguration (Medium) - -Search for overly permissive CORS: - -``` -# Allow all origins -cors.*origin.*\*|Access-Control-Allow-Origin.*\* - -# Credentials with wildcard (very dangerous) -credentials.*true.*origin.*\* -``` - -**Compliance:** OWASP A05:2021 (Security Misconfiguration) - -### Category 2: SOC 2 Compliance - -#### 2.1 Logging and Audit (CC7.2) - -Check for logging presence: - -``` -# Files without logging -# Use Grep with -L flag to find files missing logging - -# Logging configuration -log.*level|LOG_LEVEL - -# Audit trail patterns -audit|action.*log -``` - -Search for audit trail implementation: -- User action logging -- Authentication event logging -- Data access logging -- Administrative action logging - -#### 2.2 Access Control (CC6.1) - -Search for authorization patterns: - -``` -# Role-based access -role|permission|authorize|isAdmin|canAccess - -# RBAC/ACL files -*auth*|*rbac*|*acl*|*permission* -``` - -Verify: -- Role definitions exist -- Permission checks on endpoints -- Admin functions are protected - -#### 2.3 Encryption (CC6.7) - -Search for encryption usage: - -``` -# Encryption libraries -encrypt|decrypt|bcrypt|argon2|scrypt - -# Secure protocols -https://|TLS|SSL - -# Crypto operations -crypto\.|hashlib\.|SHA256|AES -``` - -Verify: -- Passwords are hashed (not encrypted) -- Data at rest encryption -- TLS for data in transit - -#### 2.4 Change Management (CC8.1) - -Check for change control: - -``` -# CI/CD presence -.github/workflows|.gitlab-ci|Jenkinsfile - -# Code review requirements -review|approve|CODEOWNERS - -# Changelog maintenance -CHANGELOG|changelog -``` - -### Category 3: Code Quality - -#### 3.1 Empty Error Handling (Medium) - -Search for swallowed errors: - -``` -# JavaScript/TypeScript empty catch -catch\s*\(\s*\w*\s*\)\s*\{\s*\} - -# Python bare except -except:\s*$|except Exception:\s*$ - -# Go ignored errors -if err != nil \{\s*$ -``` - -#### 3.2 Technical Debt Indicators (Low) - -Search for debt markers: - -``` -# TODO/FIXME comments -TODO|FIXME|HACK|XXX|TEMP - -# Linting disables -@ts-ignore|@ts-nocheck|eslint-disable|noqa - -# Type safety escapes -: any|as any -``` - -#### 3.3 Dead Code Indicators (Low) - -Search for commented-out code: - -``` -# Commented console/print statements -^\s*//.*console|^\s*#.*print - -# Backup files -*.bak|*.old|*_backup* -``` - -### Category 4: Dependencies - -#### 4.1 Lock File Status (High) - -Verify lock files exist and are current: -- `package-lock.json` for npm -- `yarn.lock` for Yarn -- `pnpm-lock.yaml` for pnpm -- `poetry.lock` for Poetry -- `Pipfile.lock` for Pipenv - -Missing lock files = non-deterministic builds. - -#### 4.2 Risky Patterns (Medium) - -Search for dangerous code patterns: - -``` -# Dynamic code execution -eval\(|Function\(|exec\( - -# Unsafe deserialization -pickle\.load|yaml\.load\(.*Loader -``` - -### Category 5: Testing - -#### 5.1 Test Coverage (Medium) - -Calculate test-to-source ratio: - -```bash -# Count source files -find . -name "*.ts" -path "*/src/*" | wc -l - -# Count test files -find . -name "*.test.ts" -o -name "*.spec.ts" | wc -l - -# Ratio < 0.5 suggests low coverage -``` - -Check for test types: -- Unit tests (`*.test.ts`, `test_*.py`) -- Integration tests (`*integration*`, `*e2e*`) -- End-to-end tests (`cypress/`, `playwright/`) - -#### 5.2 Test Configuration (Low) - -Verify testing is configured: - -``` -# Coverage configuration -coverage|collectCoverage - -# CI test integration -test|coverage in CI config -``` - -### Category 6: Configuration - -#### 6.1 Secret Exposure Risk (Critical) - -Check for secrets in tracked files: - -``` -# .env files should be gitignored -.gitignore should contain: .env - -# Secrets in config files -password|secret|key|token in *.json, *.yaml -``` - -#### 6.2 Environment Separation (Medium) - -Verify environment-specific configs: - -``` -# Environment files -.env.development|.env.staging|.env.production - -# Environment variable usage -NODE_ENV|ENVIRONMENT|APP_ENV -``` - -## Finding Template - -Document each finding using this structure: - -```markdown -### FINDING-XXX: [Clear Title] - -**Severity:** Critical | High | Medium | Low | Info -**Category:** Security | SOC2 | Code-Quality | Dependencies | Testing | Configuration - -**Description:** -[What the issue is and why it matters for production. Include business impact.] - -**Evidence:** -``` -[Code snippet or search result showing the issue] -``` -- File: `path/to/file.ts:line` -- Pattern: `[grep pattern used]` - -**Compliance Reference:** -- [OWASP A01:2021 - Broken Access Control] -- [SOC 2 CC6.1 - Logical and Physical Access] - -**Risk:** -[What could happen if this is not addressed before production] - -**Recommendation:** -[Specific steps to remediate this issue] - -**Effort:** [1-8 story points] -``` - -## Analysis Workflow - -Execute analysis in this order for efficiency: - -1. **Critical patterns first** - Security and secret exposure -2. **High severity next** - Auth, injection, compliance blockers -3. **Medium severity** - Code quality, testing gaps -4. **Low/Info last** - Style issues, documentation - -## Deduplication - -When multiple files have the same issue: -- Group into a single finding -- List all affected files in evidence -- Adjust severity based on scope (more files = higher impact) - -## False Positive Filtering - -Before reporting, verify: -- Is this in test/mock/example code? (may be acceptable) -- Is there mitigation elsewhere in the codebase? -- Is the pattern actually used at runtime? -- Is the severity appropriate for this project type? - -## Quality Checklist - -Before completing analysis: - -- [ ] All six categories analyzed -- [ ] Each finding has evidence with file:line -- [ ] Severity levels are consistent -- [ ] Compliance references are accurate -- [ ] Recommendations are actionable -- [ ] No obvious false positives included -- [ ] Findings are deduplicated diff --git a/skills/production-signals/SKILL.md b/skills/production-signals/SKILL.md deleted file mode 100644 index d2b3baa..0000000 --- a/skills/production-signals/SKILL.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -name: production-signals -description: This skill should be used when the user asks to "detect tech stack for production", "gather codebase signals", "analyze production infrastructure", "check deployment configuration", "identify project setup", or when preparing for production readiness analysis by understanding the current codebase state. -version: 0.1.0 -allowed-tools: Read, Glob, Grep, Bash(find:*), Bash(head:*), Bash(cat:*), Bash(ls:*), Bash(wc:*) ---- - -# Production Signals Detection - -Detect codebase signals relevant to production readiness assessment. This skill provides patterns for identifying the tech stack, infrastructure configuration, and development practices in a project. - -## Signal Categories - -Gather signals across these categories to inform production readiness analysis. - -### 1. Package Manager and Dependencies - -Identify the package manager and dependency management approach. - -**Node.js ecosystem:** -- `package.json` - npm/yarn/pnpm/bun project -- `package-lock.json` - npm lockfile -- `yarn.lock` - Yarn lockfile -- `pnpm-lock.yaml` - pnpm lockfile -- `bun.lockb` - Bun lockfile - -**Python ecosystem:** -- `pyproject.toml` - Modern Python project (Poetry, PDM, Hatch) -- `requirements.txt` - pip dependencies -- `Pipfile` / `Pipfile.lock` - Pipenv -- `poetry.lock` - Poetry lockfile -- `setup.py` / `setup.cfg` - Legacy setuptools - -**Other languages:** -- `go.mod` / `go.sum` - Go modules -- `Cargo.toml` / `Cargo.lock` - Rust cargo -- `Gemfile` / `Gemfile.lock` - Ruby bundler -- `pom.xml` - Java Maven -- `build.gradle` - Java Gradle - -### 2. CI/CD Configuration - -Identify continuous integration and deployment setup. - -**GitHub Actions:** `.github/workflows/*.yml` -**GitLab CI:** `.gitlab-ci.yml` -**CircleCI:** `.circleci/config.yml` -**Jenkins:** `Jenkinsfile` -**Azure Pipelines:** `azure-pipelines.yml` -**Bitbucket:** `bitbucket-pipelines.yml` -**Travis CI:** `.travis.yml` - -Read CI configuration to understand: -- Build steps and test commands -- Deployment targets -- Environment variables used -- Code quality checks - -### 3. Test Configuration - -Identify testing frameworks and coverage setup. - -**JavaScript/TypeScript:** -- `jest.config.*` - Jest -- `vitest.config.*` - Vitest -- `cypress.config.*` - Cypress E2E -- `playwright.config.*` - Playwright E2E -- `.mocharc.*` - Mocha - -**Python:** -- `pytest.ini` or `[tool.pytest]` in `pyproject.toml` -- `conftest.py` - pytest fixtures -- `tox.ini` - tox testing - -**Coverage indicators:** -- `.nyc_output/` - Istanbul/nyc coverage -- `coverage/` - Generic coverage directory -- `htmlcov/` - Python coverage reports -- `codecov.yml` - Codecov integration -- `.coveragerc` - Coverage.py config - -Count test files to estimate coverage: -- `*.test.ts`, `*.spec.ts` - TypeScript tests -- `test_*.py`, `*_test.py` - Python tests -- `*_test.go` - Go tests - -### 4. Container and Orchestration - -Identify containerization and orchestration setup. - -**Docker:** -- `Dockerfile` - Container build -- `docker-compose.yml` / `docker-compose.yaml` - Multi-container -- `.dockerignore` - Build exclusions - -**Kubernetes:** -- `k8s/`, `kubernetes/`, `manifests/` directories -- `*.yaml` files with `kind: Deployment`, `kind: Service` -- `kustomization.yaml` - Kustomize -- `Chart.yaml` - Helm charts - -**Other orchestration:** -- `ecs-task-definition.json` - AWS ECS -- `app.yaml` - Google App Engine -- `fly.toml` - Fly.io -- `vercel.json` - Vercel -- `netlify.toml` - Netlify - -### 5. Infrastructure as Code - -Identify IaC tools and cloud configuration. - -**Terraform:** `*.tf` files, `terraform/` directory -**Pulumi:** `Pulumi.yaml`, `Pulumi.*.yaml` -**CloudFormation:** `*.template.json`, `*.template.yaml` -**CDK:** `cdk.json`, `cdk.context.json` -**Serverless:** `serverless.yml` -**SAM:** `template.yaml` with `AWSTemplateFormatVersion` -**Bicep:** `*.bicep` files - -### 6. Configuration and Secrets - -Identify environment and secret management. - -**Environment files:** -- `.env` - Local environment (should be gitignored) -- `.env.example` / `.env.sample` - Example configuration -- `.env.development`, `.env.staging`, `.env.production` - Environment-specific - -**Secret management indicators:** -- HashiCorp Vault references -- AWS Secrets Manager / Parameter Store -- `sops` encrypted files -- `sealed-secrets` for Kubernetes -- `doppler.yaml` - Doppler - -**Configuration patterns:** -- `config/` directory -- `settings.py`, `config.ts` -- Environment variable usage patterns - -### 7. Monitoring and Observability - -Identify logging, monitoring, and APM setup. - -**Logging libraries:** -- `winston`, `pino`, `bunyan` (Node.js) -- `loguru`, `structlog` (Python) -- `zap`, `logrus` (Go) -- `log4j`, `slf4j` (Java) - -**APM and monitoring:** -- Datadog (`dd-trace`, `datadog.yaml`) -- New Relic (`newrelic.js`, `newrelic.yml`) -- Sentry (`sentry.*.ts`, `@sentry/*`) -- Prometheus (`prometheus.yml`, `/metrics` endpoint) -- OpenTelemetry (`@opentelemetry/*`) - -**Health checks:** -- `/health`, `/ready`, `/live` endpoints -- Health check middleware - -### 8. Security Configuration - -Identify security-related setup. - -**Authentication libraries:** -- `passport` (Node.js) -- `next-auth` / `@auth/*` (Next.js) -- `clerk`, `auth0`, `firebase-admin` -- `python-jose`, `PyJWT` (Python) - -**Security middleware:** -- `helmet` (Node.js security headers) -- CORS configuration -- CSRF protection -- Rate limiting (`express-rate-limit`, etc.) - -**Security files:** -- `SECURITY.md` - Security policy -- `.snyk` - Snyk configuration -- `security.txt` - Well-known security contact - -## Output Format - -Structure detected signals as: - -```markdown -## Production Signals: [Project Name] - -**Detected:** [Date] - -### Tech Stack -- **Primary Language:** [TypeScript/Python/Go/etc.] -- **Runtime:** [Node.js 20/Python 3.12/etc.] -- **Framework:** [Next.js/FastAPI/Gin/etc.] -- **Package Manager:** [npm/pnpm/pip/etc.] -- **Lock File Present:** [Yes/No] - -### Build and Deploy -- **CI/CD Platform:** [GitHub Actions/GitLab CI/etc.] -- **Container:** [Docker/None] -- **Orchestration:** [Kubernetes/ECS/Vercel/None] -- **IaC Tool:** [Terraform/Pulumi/None] - -### Quality Signals -- **Test Framework:** [Jest/Vitest/Pytest/etc.] -- **Test Files Found:** [count] -- **Source-to-Test Ratio:** [X:Y] -- **Linting:** [ESLint/Prettier/Ruff/etc.] -- **Type Checking:** [TypeScript strict/mypy/etc.] - -### Security Signals -- **Auth Library:** [NextAuth/Passport/etc.] -- **Secret Management:** [Vault/AWS Secrets/env files] -- **Security Headers:** [Helmet/custom/none] -- **SECURITY.md Present:** [Yes/No] - -### Observability -- **Logging Library:** [Winston/Pino/etc.] -- **APM/Monitoring:** [Datadog/Sentry/etc.] -- **Health Endpoints:** [Found/Not found] - -### Configuration -- **Environment Files:** [.env.example found/missing] -- **Environment Separation:** [Yes/No] -- **Config Pattern:** [Environment vars/Config files] - -### Risk Indicators -- [ ] Lock file missing -- [ ] No CI/CD detected -- [ ] No tests found -- [ ] No .env.example -- [ ] No SECURITY.md -``` - -## Usage in Production Analysis - -After gathering signals, use them to: - -1. **Focus analysis** - Prioritize categories based on stack -2. **Identify gaps** - Missing signals indicate potential issues -3. **Inform interview** - Ask targeted questions based on detected setup -4. **Set context** - Ground compliance requirements in actual infrastructure - -## Quality Checklist - -Before completing signal detection: - -- [ ] Package manager and lock file status identified -- [ ] CI/CD configuration checked -- [ ] Test setup documented -- [ ] Container/orchestration detected -- [ ] IaC presence noted -- [ ] Security configuration identified -- [ ] Observability tools noted -- [ ] Risk indicators flagged