diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..41ed7d9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 ShipSpec + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 4ab0039..9bab439 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# ShipSpec Planning Plugin +# 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. @@ -17,16 +17,6 @@ Spec-driven development ensures you think through requirements and architecture ### From Local Directory -```bash -# Add as a local marketplace -/plugin marketplace add /path/to/shipspec - -# Install the plugin -/plugin install shipspec@local -``` - -### From GitHub (when published) - ```bash /plugin marketplace add shipspec/planning-plugin /plugin install shipspec@shipspec diff --git a/agents/production-reporter.md b/agents/production-reporter.md index f207384..139c7b1 100644 --- a/agents/production-reporter.md +++ b/agents/production-reporter.md @@ -45,7 +45,7 @@ Generate these files in the output directory: ### 1. production-report.md -The main report for stakeholders. +The main report for stakeholders. This file documents findings but does NOT include implementation tasks. ```markdown # Production Readiness Report @@ -165,136 +165,120 @@ The main report for stakeholders. *Report generated by ShipSpec Production Analysis* ``` -### 2. fix-prompts.md +### 2. TASKS.md -Agent-ready prompts for each finding. +Structured remediation tasks in the same format as feature-planning tasks. This enables using `/implement-next-task` to work through fixes systematically. ```markdown -# Fix Prompts for Production Readiness +# Remediation Tasks: [Context Name] -Use these prompts with Claude Code to fix identified issues. - -## How to Use - -1. Copy the prompt for the finding you want to fix -2. Paste into Claude Code -3. Review and apply the suggested changes -4. Re-run analysis to verify the fix +**Generated:** [Date] +**Total Tasks:** X +**Total Story Points:** Y +**Estimated Sessions:** Z (assuming 20 pts/session) --- -## Critical Fixes +## Summary -### FINDING-001: [Title] +### 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 | -**Context:** -[Brief description of what was found and why it matters] +### Critical Path +FINDING-001 → FINDING-004 → FINDING-007 -**Files Affected:** -- `path/to/file.ts:42` +### Execution Phases +| Phase | Focus | Tasks | Points | +|-------|-------|-------|--------| +| Phase 1 | Critical Fixes | 3 | 8 | +| Phase 2 | High Priority | 5 | 12 | +| Phase 3 | Medium Priority | 4 | 8 | -**Prompt:** -``` -Fix the [issue type] in [file path]. +--- -The current code [description of problem]: -[code snippet] +## Phase 1: Critical Fixes (X points) -This is a security risk because [explanation]. +### - [ ] FINDING-001: [Title from finding] -Please: -1. [Specific fix instruction] -2. [Additional instruction if needed] -3. Ensure [verification criteria] +## Context +[2-3 sentences explaining the security/compliance issue, where it occurs, and its business impact. Reference the production-report.md for full details.] -Reference: [OWASP/SOC 2 control] -``` +## Requirements +- [ ] [Specific, verifiable fix requirement 1] +- [ ] [Specific, verifiable fix requirement 2] +- [ ] [Specific, verifiable fix requirement 3] -**Verification:** -After applying the fix, verify by: -- [ ] [Check 1] -- [ ] [Check 2] +## Technical Approach ---- +### Files to Modify +- `path/to/file.ts:42` - [What needs to change] +- `path/to/another.ts` - [Related change] -### FINDING-002: [Title] +### Implementation +[Step-by-step fix guidance based on codebase patterns] -[Same format] +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]` -## High Priority Fixes +## Testing Requirements +- Verify fix with: [specific test or verification method] +- Confirm no regression in: [affected functionality] +- Edge cases: [specific edge cases to verify] -[Same format for high findings] +## 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) -## Medium Priority Fixes +## References +- Compliance: [SOC 2 CC6.1 / OWASP A01 / etc.] +- Report: See production-report.md, FINDING-001 +- Similar pattern: `path/to/similar/code.ts` -[Same format for medium findings] +## Estimated Effort +- Story Points: [1/2/3/5/8] --- -## Batch Fix Prompts +### - [ ] FINDING-002: [Title] -### Fix All Hardcoded Secrets +[Same structure as above] -``` -Search the codebase for hardcoded credentials and secrets. - -Patterns to find: -- password = "..." -- api_key = "..." -- secret = "..." -- Connection strings with embedded credentials - -For each occurrence: -1. Replace with environment variable reference -2. Add the variable to .env.example with a placeholder -3. Ensure .env is in .gitignore - -Do not commit actual secrets. Use descriptive placeholder values. -``` +--- -### Fix All Empty Error Handlers +## Phase 2: High Priority (Y points) -``` -Find all empty catch blocks and exception handlers in the codebase. +### - [ ] FINDING-003: [Title] -Patterns: -- catch (e) { } -- except: pass -- if err != nil { } +[Same structure as above] -For each: -1. Add appropriate error logging -2. Re-throw or handle the error appropriately -3. Consider if the error should trigger an alert +--- -Use the project's existing logging pattern. -``` +## Phase 3: Medium Priority (Z points) -### Add Missing Input Validation +### - [ ] FINDING-004: [Title] -``` -Review all API endpoints and user input handlers. - -For each endpoint that accepts user input: -1. Add input validation using [project's validation library] -2. Sanitize string inputs to prevent injection -3. Validate types and ranges -4. Return appropriate error messages - -Focus on: -- Query parameters -- Request body fields -- Path parameters -- Headers used in logic -``` +[Same structure as above] --- -*Fix prompts generated by ShipSpec Production Analysis* +*Remediation tasks generated by ShipSpec Production Analysis* ``` ## Report Generation Guidelines @@ -314,15 +298,17 @@ Write for non-technical leadership: - Be specific about location and scope - Make remediation actionable -### Fix Prompts +### Task Prompts -Create prompts that: -- Provide sufficient context -- Reference specific files and lines -- Include the problematic code snippet -- Give clear, step-by-step instructions -- Include verification criteria -- Reference compliance standards +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 @@ -341,10 +327,12 @@ Before completing report: - [ ] All findings are documented with evidence - [ ] Compliance matrix is accurate - [ ] Remediation roadmap is prioritized -- [ ] Fix prompts are specific and actionable +- [ ] 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 -- [ ] Fix prompts include verification steps +- [ ] Tasks include verification steps ## Handoff @@ -355,18 +343,19 @@ After generating reports, inform the user: **Files created:** - `[output-dir]/production-report.md` - Full analysis report -- `[output-dir]/fix-prompts.md` - Agent-ready fix prompts +- `[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. Use fix-prompts.md to address findings -3. Re-run `/productionalize` after fixes to verify +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 help fix any specific finding? +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 6d5e90d..30ce988 100644 --- a/commands/implement-next-task.md +++ b/commands/implement-next-task.md @@ -1,23 +1,65 @@ --- 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. +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. -## Step 1: Validate Prerequisites +## Step 0: Validate Argument -Check that TASKS.md exists: +**If $ARGUMENTS is empty or missing:** +> "Error: Directory name is required. +> +> **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` +> +> **To see available planning directories:** +> ```bash +> ls .shipspec/planning/ +> ```" + +**Stop here** - do not proceed without an argument. + +## Step 1: Validate Prerequisites and Detect Workflow + +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" + +**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" +``` + +- 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)." + +**Check for TASKS.md:** ```bash -echo "=== Checking TASKS.md ===" ls -la .shipspec/planning/$ARGUMENTS/TASKS.md 2>/dev/null || echo "TASKS.md NOT FOUND" ``` -If TASKS.md is not found, tell the user: -> "No TASKS.md found for '$ARGUMENTS'. Please run `/feature-planning $ARGUMENTS` first to complete the planning workflow and generate tasks." +**If TASKS.md not found:** +> "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." ## Step 2: Load and Parse Tasks @@ -25,20 +67,33 @@ Load the tasks document: @.shipspec/planning/$ARGUMENTS/TASKS.md Parse the document to extract: -1. **All tasks** with their IDs, titles, and statuses -2. **Status indicators**: +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**: - `- [ ]` = Not started - `- [~]` = In progress - `- [x]` = Completed -3. **Dependencies** from each task's `Depends on:` line +5. **Dependencies** from each task's `Depends on:` line -Build a task map: +Build a task map (example for each workflow type): + +**Feature Planning:** ``` 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). @@ -108,17 +163,19 @@ Otherwise, show the blocking situation: Once a ready task is found: 1. **Update TASKS.md**: Change the task's status from `[ ]` to `[~]` - - Find the line with `### - [ ] TASK-XXX:` - - Replace with `### - [~] TASK-XXX:` + - For Feature Planning: Find `### - [ ] TASK-XXX:` → Replace with `### - [~] TASK-XXX:` + - For Production Readiness: Find `### - [ ] FINDING-XXX:` → Replace with `### - [~] FINDING-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**: +3. **Display to user** (workflow-aware): -> "## Starting Task: [TASK-ID] +> "## Starting Task: [TASK-ID or FINDING-ID] > > **[Task Title]** > +> **Workflow:** [Feature Development | Production Remediation] +> > Status updated to: In Progress > > --- @@ -146,22 +203,30 @@ After displaying the task, show progress: ## Edge Cases +### Missing Argument +If no directory 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]: [Title] -> - [TASK-YYY]: [Title] +> - [TASK-XXX or FINDING-XXX]: [Title] +> - [TASK-YYY or FINDING-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: -> TASK-001 → TASK-002 → TASK-003 → TASK-001 +> [ID-001] → [ID-002] → [ID-003] → [ID-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/productionalize.md b/commands/production-readiness-review.md similarity index 84% rename from commands/productionalize.md rename to commands/production-readiness-review.md index ed325d9..f9e036d 100644 --- a/commands/productionalize.md +++ b/commands/production-readiness-review.md @@ -1,12 +1,12 @@ --- -description: Analyze codebase for production readiness and generate fix prompts +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 Analysis: $ARGUMENTS +# Production Readiness Review: $ARGUMENTS -Analyze the codebase for production readiness, identifying security vulnerabilities, compliance gaps, and code quality issues. +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 @@ -63,12 +63,12 @@ The analyzer will: - Filter false positives - Document findings with evidence and severity -## Step 5: Generate Reports +## 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. **fix-prompts.md** - Agent-ready prompts for each finding +2. **TASKS.md** - Structured remediation tasks (same format as feature-planning tasks) Save to: `.shipspec/planning/$ARGUMENTS/` @@ -76,12 +76,12 @@ Save to: `.shipspec/planning/$ARGUMENTS/` After report generation, present a summary: -> **Production Readiness Analysis Complete** +> **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/fix-prompts.md` - Agent-ready fix prompts +> - `.shipspec/planning/$ARGUMENTS/TASKS.md` - Structured remediation tasks > > **Summary:** > - Overall Status: [Ready/Ready with Reservations/Not Ready] @@ -92,9 +92,8 @@ After report generation, present a summary: > > **Recommended Next Steps:** > 1. Review production-report.md with stakeholders -> 2. Address critical findings immediately -> 3. Use fix-prompts.md to fix issues with Claude Code -> 4. Re-run `/productionalize $ARGUMENTS` after fixes to verify +> 2. Run `/implement-next-task $ARGUMENTS` to start fixing issues +> 3. Re-run `/production-readiness-review $ARGUMENTS` after fixes to verify ## Pre-loaded Context