
develop
Development workflow commands
Install
/plugin install develop@psousa50-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add psousa50/claude-plugins.
Contents
Discovered from sourceSkills 5
Build Story
Write tests and implementation together for a user story. Tests and code evolve in tandem — define the behaviour, implement it, iterate until all tests pass.
Input
$ARGUMENTS is the path to a story file.
Steps
1. Read the Story
Read the file at $ARGUMENTS. Extract:
- Acceptance criteria (checkboxes, numbered lists, or prose)
- Technical notes and implementation guidance
- API contracts (request/response examples)
- User flows
2. Load Shared Patterns
Invoke the develop:patterns skill. These rules apply to everything written in this phase.
3. Learn the Project
Before writing anything, understand the project's conventions:
- Look for existing test files using Glob to understand the testing framework, directory structure, naming conventions, and mocking patterns
- Read 2-3 existing test files to learn the exact style and patterns used
- Look for existing source files similar to what you need to create — understand the architecture, naming, and dependency patterns
- Discover the available commands for testing, linting, and formatting by exploring project configuration files
- Identify test utilities, fixtures, factories, or helpers already in the codebase
4. Write Tests
For each acceptance criterion, write test cases following the project's established conventions:
- Same testing framework, file naming pattern, and test structure
- Same mocking approach, utilities, and assertion style
- Tests may reference classes, functions, and modules that do not exist yet — that is expected
5. Implement
Follow the project's established architecture. Implement in dependency order — create things that other things depend on first.
Write the minimum code to satisfy the tests. No gold-plating, no extra methods, no speculative features.
6. Run Tests
Run the project's test command. All tests must pass — both the new ones and existing ones.
If tests fail, read the error output and decide: fix the implementation, or fix the test if it is genuinely wrong. Iterate until all tests pass.
7. Run Linters
Run the project's lint and type-check commands. Fix any violations.
8. Write Summary
Derive story-slug from the story filename. Create the directory docs/reviews/{story-slug}/ if it does not exist.
Write to docs/reviews/{story-slug}/01-build.md:
# Phase 1: Build
**Story:** {story file path}
**Date:** {ISO date}
## Test Files
- `path/to/test_file` — {what it tests}
## Implementation Files
- `path/to/file` — {purpose}
## Files Modified
- `path/to/file` — {what changed}
## Acceptance Criteria Coverage
| Criterion | Test(s) |
| ---------------- | ---------------- |
| {criterion text} | {test reference} |
## Test Corrections
{Only include this section if test files were modified after the initial write. For each change, explain what was wrong and why it was corrected. Omit this section entirely if no corrections were made.}
## Test Results
{Paste the final test output showing all tests passing}
## Lint/Type Check Results
{Paste lint output}
Rules
- Prefer testing behaviour over testing implementation details.
- You MAY modify test files during iteration to correct genuine errors (wrong import path, incorrect assertion, broken setup). Do NOT modify tests to paper over a weak implementation.
- Document every test correction in the "Test Corrections" section with a clear reason.
- Do NOT add features beyond what the acceptance criteria require.
- Do NOT stop until all tests pass and linters are clean.
Final Review
Produce a final human-readable review report after all fixes have been applied. This report is for a human reviewer — concise, clear, and focused on whether the story is ready for merge.
Input
$ARGUMENTS is the path to a story file.
Steps
1. Read Context
Derive story-slug from the story filename. Read:
- The story file at
$ARGUMENTS— for acceptance criteria docs/reviews/{story-slug}/02-review.md— previous review findingsdocs/reviews/{story-slug}/03-fix.md— what was fixed (if it exists)
2. Learn the Project
Discover the project's test commands by exploring project configuration files. Look at existing source files to understand the code style and conventions.
3. Verify Previous Findings Resolved
For each Critical and Warning finding from the previous review, check the specific file and line referenced. Confirm the fix was applied correctly.
4. Fresh Review
Run git diff --name-only HEAD and git status --short to find all changed files. Read every changed file.
Do a holistic review focused on:
- Do all the pieces fit together cohesively?
- Were any new issues introduced by the fixes?
- Is every acceptance criterion covered by a passing test?
- Would a human reviewer find anything surprising or concerning?
5. Run Tests
Run the project's test command. Confirm all tests pass.
6. Write Final Report
Write to docs/reviews/{story-slug}/04-final-review.md:
# Final Review
**Story:** {story file path}
**Date:** {ISO date}
**Verdict:** {READY FOR MERGE | NEEDS ATTENTION}
## What Was Built
{2-3 sentence summary suitable for a PR description}
## Acceptance Criteria
| Criterion | Status | Test |
| ---------------- | --------- | ---------------- |
| {criterion text} | PASS/FAIL | {test reference} |
## Previous Review
- **Critical findings:** {N} found, {N} resolved
- **Warnings:** {N} found, {N} resolved
## Remaining Concerns
{List any issues that still need attention, or "None"}
## Files Changed
- `path/to/file` — {one-line description}
## Test Results
{Summary: N tests passed, 0 failed}
7. Output Verdict
After writing the report, output:
- The verdict (READY FOR MERGE or NEEDS ATTENTION)
- The report file path
- A one-line summary
Rules
- The report is for humans — be concise, not exhaustive.
- If any acceptance criterion lacks a test, mark it FAIL.
- If any Critical finding from the previous review was not resolved, verdict is NEEDS ATTENTION.
- Be honest about the verdict — READY FOR MERGE means you'd be comfortable merging this.
Fix Review Issues
Read a code review report and apply all necessary fixes. Critical findings are mandatory. Warnings are applied unless disproportionate. Suggestions are skipped.
Input
$ARGUMENTS is the path to a story file.
Steps
1. Find the Review Report
Derive story-slug from the story filename. Read docs/reviews/{story-slug}/02-review.md.
If the report status is PASS, there is nothing to fix. Write a brief summary to docs/reviews/{story-slug}/03-fix.md noting no fixes were needed, and stop.
2. Learn the Project
Discover the project's test and lint commands by exploring project configuration files. Look at existing source files to understand the code style.
3. Parse Findings
Categorise the findings:
- Critical — must fix, no exceptions
- Warnings — fix unless doing so requires a disproportionate refactor or conflicts with a Critical fix
- Suggestions — skip (these are for humans to consider later)
4. Apply Fixes
For each Critical finding, then each Warning:
- Read the referenced file
- Understand the issue described
- Apply the fix
- Move to the next finding
Do not introduce new features or refactor beyond what the findings require.
5. Run Tests
Run the project's test command. All tests must still pass after fixes.
If a fix breaks a test, the fix is wrong — revert it and try a different approach. Tests are the source of truth.
6. Run Linters
Run the project's lint and type-check commands. Fix any issues introduced by the fixes.
7. Write Summary
Write to docs/reviews/{story-slug}/03-fix.md:
# Phase 3: Fixes Applied
**Story:** {story file path}
**Date:** {ISO date}
## Critical Fixes
- `path/to/file:line` — {what was fixed}
## Warning Fixes
- `path/to/file:line` — {what was fixed}
## Skipped
- {finding reference} — {reason for skipping}
## Test Results
{Final test output confirming all pass}
Rules
- Do NOT modify test files unless a review finding specifically says to.
- Do NOT add features or refactor beyond what findings require.
- Do NOT apply Suggestions — they are informational only.
- If a fix breaks tests, revert and find an alternative approach.
Story Pipeline Patterns
These patterns apply to all code written or modified by the story pipeline skills.
Code Patterns
- Do NOT add comments, docstrings, or type annotations to code you didn't write. Only add comments where the logic isn't self-evident.
- Do NOT add features, refactor code, or make improvements beyond what was asked.
- Do NOT add error handling, fallbacks, or validation for scenarios that can't happen.
- Do NOT create helpers, utilities, or abstractions for one-time operations.
- Follow the project's existing code style strictly — learn it from existing files, not assumptions.
- Prefer simple, direct code over clever abstractions. Three similar lines is better than a premature abstraction.
Test Patterns
- Never use
patch,mock.patch,vi.mock,jest.mock, or any module-level mocking. Use dependency injection and constructor-level mocks instead. - Only mock dependencies that are explicitly injected — never mock a module or file import directly.
- Do NOT reference AC names or numbers (e.g. "AC1", "Acceptance Criteria 2") in test names or descriptions — tests should describe behaviour, not story structure.
Review Code
Review all code changes for a user story and produce an actionable report. Be thorough but pragmatic — only flag genuine issues, not style preferences already within the project's conventions.
Input
$ARGUMENTS is the path to a story file.
Steps
1. Read the Story
Read the file at $ARGUMENTS. Understand the acceptance criteria — the review must verify the implementation satisfies them.
2. Learn the Project
Before reviewing, understand what "correct" looks like:
- Look at a few existing source files similar to the changed ones to calibrate your expectations
3. Identify Changed Files
Run git diff --name-only HEAD and git status --short to find all changed, staged, and untracked files. Include everything — implementation files, test files, schema changes, configuration.
4. Read Every Changed File
Use the Read tool on each file. Read the full file, not just the diff — context matters for architectural correctness.
5. Review Against Checklist
Evaluate the code against each of these categories:
Correctness
- Does the implementation match every acceptance criterion?
- Are edge cases handled?
Security
- No injection vulnerabilities
- Authentication and authorisation enforced on all endpoints
- No data leakage across users or tenants
- Sensitive data not exposed in responses
Architecture
- Proper layer separation maintained
- Dependencies flow in the correct direction
- No business logic in the wrong layer
Test Quality
- Tests actually test behaviour, not just call code
- Edge cases covered
- Mocking follows project conventions
- Each acceptance criterion has at least one test
Code Style
- Follows the project's established conventions (learned from existing code)
- Consistent with patterns in similar existing files
Naming
- Follows the project's naming conventions exactly
Performance
- No obvious performance issues (N+1 queries, unbounded fetches, missing pagination)
Consistency
- New code follows patterns established in similar existing files
- Uses existing utilities and helpers rather than reinventing
6. Write Report
Derive story-slug from the story filename. Write to docs/reviews/{story-slug}/02-review.md:
# Code Review
**Story:** {story file path}
**Date:** {ISO date}
**Status:** {PASS | ISSUES_FOUND}
## Summary
{One paragraph overall assessment}
## Critical
{Must fix. Each finding with file path and description.}
- `path/to/file:line` — {description of issue and what to fix}
## Warnings
{Should fix. Lower severity but still worth addressing.}
- `path/to/file:line` — {description}
## Suggestions
{Optional improvements. Not blocking.}
- {suggestion}
## Acceptance Criteria Check
| Criterion | Status | Evidence |
| ----------- | --------- | ------------------------ |
| {criterion} | PASS/FAIL | {test or code reference} |
## Files Reviewed
- `path/to/file` — {brief description}
If there are no Critical or Warning findings, set Status to PASS. Otherwise ISSUES_FOUND.
7. Output Summary
After writing the report, output a brief summary: total findings by severity and the report file path.
Rules
- Every finding MUST reference a specific file and ideally a line number.
- Every finding MUST describe what to fix, not just what's wrong.
- Do NOT flag style choices that are consistent with the project's existing patterns.
- Be pragmatic — minor issues that don't affect correctness or security are Suggestions, not Warnings.
Commands 2
Run a mutation testing session.
Usage
/mutation-test <file> [--test '<command>']
Arguments
Parse $ARGUMENTS to extract:
- file: The target file to mutate (required)
- --test: The test command to run (default:
make unit-test)
Raw arguments: $ARGUMENTS
Instructions
- Parse the arguments above to extract the file path and test command
- Read the target file thoroughly
- Identify mutation opportunities (boundary conditions, boolean inversions, status changes, removed statements, etc.)
- For each mutation:
- Make the change
- Run the provided test command
- Record outcome (KILLED if tests fail, SURVIVED if tests pass)
- Revert the change
- Present a final report with:
- Total mutations / killed / survived
- Mutation score percentage
- Table of all mutations with outcomes
- Any test coverage gaps identified (surviving mutations)
Run the complete implementation workflow for a user story. This is a fire-and-forget orchestrator — it chains four phases sequentially using sub-agents for context isolation. Each phase writes artefacts to docs/reviews/{story-slug}/ so you can review what happened after completion.
Input
$ARGUMENTS is the path to a story file.
Workflow
Derive story-slug from the story filename (strip the directory path and file extension). Create the directory docs/reviews/{story-slug}/ if it does not exist.
Run each phase in sequence using the Task tool to launch sub-agents. Each sub-agent gets an isolated context window. Wait for each phase to complete before starting the next.
Phase 1: Build
Launch a sub-agent with subagent_type general-purpose:
Invoke the develop:build skill with arguments: {$ARGUMENTS}
The story slug is: {story-slug}
When the sub-agent returns, check its result. If it reports tests are NOT passing, STOP the workflow. Output an error message with the sub-agent's report and the path to any artefacts written so far.
Phase 2: Code Review
Launch a sub-agent with subagent_type general-purpose:
Invoke the develop:review skill with arguments: {$ARGUMENTS}
The story slug is: {story-slug}
When the sub-agent returns, read docs/reviews/{story-slug}/02-review.md to check the review status.
Phase 3: Fix Review Issues
Only run this phase if the review report status is ISSUES_FOUND.
If the review status is PASS, skip to Phase 4.
Launch a sub-agent with subagent_type general-purpose:
Invoke the develop:fix skill with arguments: {$ARGUMENTS}
The story slug is: {story-slug}
Phase 4: Final Review
Launch a sub-agent with subagent_type general-purpose:
Invoke the develop:final-review skill with arguments: {$ARGUMENTS}
The story slug is: {story-slug}
Completion
After all phases complete, read docs/reviews/{story-slug}/04-final-review.md and output:
- Verdict — READY FOR MERGE or NEEDS ATTENTION
- Summary — what was built (from the final review report)
- Artefacts — list all files in
docs/reviews/{story-slug}/ - Phase recap:
- Phase 1: {N} test files written, all tests passing / failed (if workflow stopped)
- Phase 2: {N} critical, {N} warnings, {N} suggestions
- Phase 3: {N} fixes applied / skipped (if review was clean)
- Phase 4: verdict
Error Handling
- If Phase 1 fails (tests not passing), stop immediately. Output what happened and the artefacts path.
- If any sub-agent fails unexpectedly, stop and report the phase that failed with whatever information is available.
- Do NOT continue to later phases if an earlier phase failed — there is no point reviewing broken code.
Sponsors
Details
- Marketplace
- psousa50/claude-plugins
- Source
- plugins/develop
- Category
- Community