
por-dev
A development plugin for the Product on Rails methodology
- GitHub stars
- 12
Install
/plugin install por-dev@por-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add lfnovo/por-marketplace.
Contents
Discovered from sourceCommands 10
Design Command
This command takes the requirements from specs/<feature_slug>/spec.md and transforms them into a concrete technical architecture by solving all its open questions and implementation ambiguities.
User Input
Arguments:
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Prerequisites
Before running this command:
- ✅ Feature specs must exist at
./specs/<feature_slug>/specs.md - ✅ You should be on the correct feature branch
- ❌ Do NOT run this if specs are incomplete or have unresolved clarifications
Execution Flow
Step 0: Load Context
-
Identify the current feature by checking:
- Current git branch name (if using git)
- Ask user to specify feature if unclear
-
Load the specs file at
./specs/<feature_slug>/specs.md -
Verify specs are complete:
- No
[NEEDS CLARIFICATION]markers remaining - All user stories defined with priorities
- Success criteria are clear
- If incomplete, STOP and tell user to run
/discoverfirst
- No
Step 1: Technical Research
Based on the requirements in specs.md, identify what you need to research:
Research Triggers:
- New libraries/frameworks mentioned that you're not familiar with
- Integration with external services/APIs
- Unfamiliar patterns or architectural approaches
- Performance requirements that need specific solutions
- Security/compliance requirements needing validation
Research Tools Available:
- WebSearch: For general technical information, library documentation, best practices
- Context7: For library-specific documentation and examples
- Perplexity: For recent technical decisions, comparisons, and up-to-date practices
Research Process:
- List what needs research (be specific: "How to implement rate limiting in xxxx framework" not "research rate limiting")
- For each item, use the appropriate tool and synthesize findings
- Document key decisions as you research (don't wait until the end)
Important: Don't research things you already know well. Focus on gaps in your knowledge that would affect implementation quality.
Step 2: Codebase Analysis
Understand the existing codebase structure and patterns:
Discovery Questions:
- What is the existing tech stack? (language, frameworks, key libraries)
- What are the established patterns? (file structure, naming conventions, architectural patterns)
- Where do similar features live in the codebase?
- What existing components can be reused?
- What are the testing patterns?
Analysis Tools:
- Use available MCP tools to search and read code
- Look for similar features to understand patterns
- Identify the main directories and their purposes
- Note any conventions (naming, structure, imports)
Tips:
- Search for keywords from your specs to find related code
- Look at recent commits/PRs for active patterns
- Check for README files explaining structure
- Identify configuration files and their purposes
Step 3: Architecture Design
Now design the architecture for this feature:
What to Define:
-
Component Structure:
- What new files/modules need to be created?
- What existing files need modification?
- How do components relate to each other?
- Where does each user story map to in the code?
-
Technical Decisions:
- Which libraries/frameworks to use (with rationale)
- Which patterns to follow (with justification)
- How to handle edge cases
- Performance considerations
- Security considerations
-
Integration Points:
- How does this feature integrate with existing code?
- What APIs/interfaces need to be defined?
- What side effects or dependencies exist?
-
Data Flow:
- How does data move through the system?
- What transformations occur?
- Where is state managed?
Architecture Principles:
- Follow existing codebase patterns (don't reinvent)
- Prefer simplicity over cleverness
- Consider testability
- Think about maintenance and debugging
- Address non-functional requirements (performance, security, etc.)
Step 4: Generate architecture.md
Create ./specs/<feature_slug>/architecture.md with this structure:
# Architecture: [FEATURE NAME]
**Feature**: [Feature name]
**Date**: [Current date]
**Branch**: [feature branch name]
**Specs**: [Link to specs.md]
## Summary
[2-3 sentence overview: what we're building and the core technical approach]
## Technical Context
**Language/Stack**: [e.g., Python 3.11 + FastAPI, TypeScript + React, etc.]
**Key Dependencies**: [Libraries/frameworks being used or added]
**Storage**: [Database, files, cache - if applicable]
**Testing**: [Testing approach and tools]
**Platform**: [Where this runs - server, browser, mobile, etc.]
## Technical Decisions
### Decision 1: [Decision Title]
**What**: [What was decided]
**Why**: [Rationale for this decision]
**Alternatives Considered**: [What else was considered and why rejected]
**Trade-offs**: [What we gain vs what we lose]
[Repeat for each major technical decision]
## Architecture Overview
[High-level description of how the system works before and after this change]
### Component Structure
**New Files/Modules:**
path/to/new/file.ext - Purpose and responsibility path/to/another/file.ext - Purpose and responsibility
**Modified Files:**
path/to/existing/file.ext - What changes and why
### Component Relationships
[Describe how components interact - can use bullet points or simple diagrams]
### Data Flow
[Describe how data moves through the system for key user stories]
## Implementation Approach
### User Story Mapping
**US1 (P1): [Story Title]**
- Files involved: [list]
- Key components: [list]
- Dependencies: [if any]
- Testing approach: [how to verify]
**US2 (P2): [Story Title]**
[Same structure]
### File Structure
[Show the relevant part of the directory structure with new/modified files marked]
project/ ├── src/ │ ├── [existing]/ │ ├── [new-module]/ # NEW │ │ ├── init.py # NEW │ │ └── core.py # NEW │ └── [existing-file.py] # MODIFIED └── tests/ └── test_new_feature.py # NEW
## Integration Points
[Describe how this feature integrates with existing code]
- **Integration with [Component A]**: [How and why]
- **New APIs/Interfaces**: [What's exposed]
- **Dependencies**: [What this feature depends on]
## Technical Constraints
- [Constraint 1: e.g., Must maintain backward compatibility with v1 API]
- [Constraint 2: e.g., Response time must be <200ms]
- [Constraint 3: e.g., Must work offline]
## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk description] | [High/Med/Low] | [How we'll handle it] |
## Open Questions
[If any technical questions remain that need resolution before implementation]
- [ ] Question 1
- [ ] Question 2
## Next Steps
1. Review this architecture with stakeholders
2. Resolve any open questions
3. Run `/tasks` to break down into implementation tasks
Step 5: Generate contracts.md (Optional)
Only create this file if the feature involves:
- External APIs or services
- Data models with validation rules
- Integration contracts with other systems
- Complex request/response formats
If needed, create ./specs/<feature_slug>/contracts.md:
# Contracts: [FEATURE NAME]
**Feature**: [Feature name]
**Date**: [Current date]
## Data Models
### [Entity Name]
**Purpose**: [What this represents]
**Attributes:**
- `field_name` (type): Description, validation rules
- `another_field` (type): Description
**Example:**
```json
{
"field_name": "value",
"another_field": 123
}
[Repeat for each entity]
API Contracts
[Endpoint Name]
Endpoint: POST /api/path
Purpose: [What this does]
Request:
{
"param1": "value",
"param2": 123
}
Response (Success - 200):
{
"result": "success",
"data": {}
}
Response (Error - 400):
{
"error": "Error message"
}
Validation Rules:
- param1: Required, must be non-empty string
- param2: Required, must be positive integer
[Repeat for each endpoint/contract]
Integration Contracts
[If integrating with external services, document the contract/expectations]
[Service Name]
What we expect:
- Input format: [describe]
- Output format: [describe]
- Error handling: [describe]
State Transitions
[If there are complex state machines or workflows, document them]
[Current State] --[Action]--> [New State]
### Step 6 Final Review & Report
Present to the user:
1. **Summary of architecture:**
- Core technical approach
- Major decisions made
- Key components involved
2. **Files generated:**
- Link to `architecture.md`
- Link to `contracts.md` (if created)
- Agent file updated (CLAUDE.md or AGENTS.md)
3. **Key decisions to review:**
- List the most important architectural decisions
- Ask if user wants to discuss or adjust anything
4. **Next steps:**
- Suggest reviewing the architecture.md
- Ask if they want to proceed to `/tasks` or iterate on architecture
- Mention any open questions that need resolution
## Guidelines
### Research Guidelines
**When to use each tool:**
- **WebSearch**: General information, official docs, Stack Overflow patterns
- **Context7**: Library-specific docs, API references, code examples
- **Perplexity**: Recent best practices, "what's the latest way to...", comparisons
**How to research efficiently:**
- Be specific in search queries
- Look for official documentation first
- Cross-reference multiple sources for important decisions
- Document your findings as you go (don't wait until end)
### Architecture Guidelines
**Keep it pragmatic:**
- Don't over-engineer
- Follow existing patterns in the codebase
- Consider the team's skill level and familiarity
- Choose boring, proven technologies over shiny new ones
**Think about the future:**
- How easy is this to test?
- How easy is this to debug?
- How easy is this to extend?
- How easy is this to maintain?
**Address non-functionals:**
- Performance requirements from specs
- Security considerations
- Accessibility needs (if applicable)
- Error handling and resilience
### Documentation Guidelines
**Write for humans:**
- Use clear, simple language
- Explain WHY, not just WHAT
- Include examples where helpful
- Use diagrams/ASCII art if it helps clarity
**Be concise but complete:**
- Every section should add value
- Remove boilerplate that doesn't apply
- Focus on decisions and trade-offs
- Link to external docs rather than copying them
**Make it actionable:**
- Anyone should be able to implement from this
- Include enough detail for task breakdown
- Highlight dependencies and prerequisites
- Call out risks and gotchas
## Error Handling
**If specs.md is missing:**
ERROR: No specs found at ./specs/<feature_slug>/specs.md
Please run /discover first to create the feature specification.
**If specs have unresolved clarifications:**
ERROR: Specs contain [NEEDS CLARIFICATION] markers:
- [List the markers]
Please resolve these before proceeding to architecture. You can:
- Run
/discoveragain to address clarifications - Manually edit specs.md to resolve them
Once you are done and the architecture is complete, run the /plan command.
Feature Discovery
You're writing a plan to implement a net new feature that will add value to the application.
The text in the arguments is the requirements source. Your first step here is to analyze what is the source for the feature arguments, which could be:
- A string (requirements typed in natural language)
- A file in the local filesystem
- A card in a project management software that you can access through MCP Tools
Based on the identified source, acquire the necessary context by reviewing what was types, reading the file or pulling the card from the tool.
Given that feature description, do this:
#$ARGUMENTSYou MUST consider the user input before proceeding (if not empty). If the input is empty, error now and ask for a proper input.
Setup
- Create a slug for this feature (<feature_slug>), should be a git branch friendly name that is not in the ./specs folder (not repeated)
- Create the folder at ./specs/<feature_slug>
- Make sure we are in a branch with the same name. If not, create it.
- Parse user description from Input If empty: ERROR "No feature description provided"
- Extract key concepts from description Identify: actors, actions, data, constraints
Analysis
Go through the cards, parents and children if required, and build an initial understanding of what needs to be build. Think carefully about what is requested, ensure you understand exactly: - Why this is being built (context) - What is the expected outcome for this issue? (goal) - How should it be built, just directionally, not in details (approach) - If it requires using new APIs/tools, do you understand them? - How should this be tested? - What are the dependencies? - What are the constraints? Anything that isn't clear MUST be recorded as a question / clarification needed.
Once you have a good understanding of what is being built, save it in the specs/<feature_slug>/spec.md file and ask the human to review it.
Your goal at this point is to extract the feature requirements from the functionality perspective, not to define its architecure.
General Guidelines
Quick Guidelines
- Focus on WHAT users need and WHY.
- Avoid HOW to implement (no tech stack, APIs, code structure) for now.
- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
Spec Format
# Feature Specification: [FEATURE NAME]
**Feature Branch**: `[###-feature-name]`
**Input**: User description: "$ARGUMENTS"
## Context and Understanding
[ Explain what you understand from the user requirements. What is the user trying to build and what is the motivation for it? What is wrong / missing today and needs to change?]
## Feature Description
<describe the feature in detail, including its purpose and value to users>
## Requirements *(mandatory)*
<!--
ACTION REQUIRED: The content in this section represents placeholders.
Fill them out with the right functional requirements.
-->
### Proposed solution
<!--
ACTION REQUIRED: How will this feature really work? Think about user journeys, APIs, reports. Do we need tests? Do we need configuration changes? Are we handling deployment? Create as many stories as its required to deliver this.
-->
Examples:
- **US-001**: User Story for an important feature
- **US-002**: User Story for the backend service
- **US-003**: User Story for the frontend implementation
- **US-004**: User Story for configuration
- **US-005**: User Story for unit testings
### Functional Requirements
- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
- **FR-005**: System MUST [behavior, e.g., "log all security events"]
*Example of marking unclear requirements:*
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
## Success Criteria *(mandatory)*
<!--
ACTION REQUIRED: Define measurable success criteria.
These must be technology-agnostic and measurable.
-->
### Measurable Outcomes
- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
## Clarification Needed
<optionally list any questions and clarifications required to properly design the feature. A developer will answer them in time. If the user answers your clarification questions, you should update the documentation.>
## Notes
<optionally list any additional notes, future considerations, or context that are relevant to the feature that will be helpful to the developer>
After creating the spec file, present your questions to the human.
Ask the questions in Clarification Needed section in one single message. Provide alternatives and suggest your preferred appraoch.
Example:
I have finished my initial review. In the analysis process, I identified some issues that would benefit from clarification. I am providing each of them below. You can reply only for the items you want to change. Any item you don't reply to, I'll consider you accepted my suggestion. You can reply to all of them in the same message.
1. Insert your question here provididing details on context and why it's important
A) Option 1
B) Option 2
C) Option 3
D) Tell me what to do.
(repeat this process for each question)
Once the human provides you with the answers, MUST update the spec.md file and provide the human answer to your clarification questions so you can refer to them later.
Once you are done and the discovery is complete, run the /design command.
Bug Planning
Create a new plan in specs/*.md to resolve the Bug using the exact specified markdown Plan Format. Follow the Instructions to create the plan use the Relevant Files to focus on the right files.
Instructions
- You're writing a plan to resolve a bug, it should be thorough and precise so we fix the root cause and prevent regressions.
- Create the plan in the
specs/*.mdfile. Name it appropriately based on theBug. - Use the plan format below to create the plan.
- Research the codebase to understand the bug, reproduce it, and put together a plan to fix it.
- IMPORTANT: Replace every in the
Plan Formatwith the requested value. Add as much detail as needed to fix the bug. - Use your reasoning model: THINK HARD about the bug, its root cause, and the steps to fix it properly.
- IMPORTANT: Be surgical with your bug fix, solve the bug at hand and don't fall off track.
- IMPORTANT: We want the minimal number of changes that will fix and address the bug.
- Don't use decorators. Keep it simple.
- If you need a new library, use
uv addand be sure to report it in theNotessection of thePlan Format. - Respect requested files in the
Relevant Filessection. - Start your research by reading the
README.mdfile.
Plan Format
# Bug: <bug name>
## Bug Description
<describe the bug in detail, including symptoms and expected vs actual behavior>
## Problem Statement
<clearly define the specific problem that needs to be solved>
## Solution Statement
<describe the proposed solution approach to fix the bug>
## Steps to Reproduce
<list exact steps to reproduce the bug>
## Root Cause Analysis
<analyze and explain the root cause of the bug>
## Relevant Files
Use these files to fix the bug:
<find and list the files that are relevant to the bug describe why they are relevant in bullet points. If there are new files that need to be created to fix the bug, list them in an h3 'New Files' section.>
## Step by Step Tasks
IMPORTANT: Execute every step in order, top to bottom.
<list step by step tasks as h3 headers plus bullet points. use as many h3 headers as needed to fix the bug. Order matters, start with the foundational shared changes required to fix the bug then move on to the specific changes required to fix the bug. Include tests that will validate the bug is fixed with zero regressions. Your last step should be running the `Validation Commands` to validate the bug is fixed with zero regressions.>
## Validation Commands
Execute every command to validate the bug is fixed with zero regressions.
<list commands you'll use to validate with 100% confidence the bug is fixed with zero regressions. every command must execute without errors so be specific about what you want to run to validate the bug is fixed with zero regressions. Include commands to reproduce the bug before and after the fix.>
- `cd app/server && uv run pytest` - Run server tests to validate the bug is fixed with zero regressions
## Notes
<optionally list any additional notes or context that are relevant to the bug that will be helpful to the developer>
Bug
$ARGUMENTS
Chore Planning
Create a new plan in specs/*.md to resolve the Chore using the exact specified markdown Plan Format. Follow the Instructions to create the plan use the Relevant Files to focus on the right files.
Instructions
- You're writing a plan to resolve a chore, it should be simple but we need to be thorough and precise so we don't miss anything or waste time with any second round of changes.
- Create the plan in the
specs/*.mdfile. Name it appropriately based on theChore. - Use the plan format below to create the plan.
- Research the codebase and put together a plan to accomplish the chore.
- IMPORTANT: Replace every in the
Plan Formatwith the requested value. Add as much detail as needed to accomplish the chore. - Use your reasoning model: THINK HARD about the plan and the steps to accomplish the chore.
- Respect requested files in the
Relevant Filessection. - Start your research by reading the
README.mdfile.
Plan Format
# Chore: <chore name>
## Chore Description
<describe the chore in detail>
## Relevant Files
Use these files to resolve the chore:
<find and list the files that are relevant to the chore describe why they are relevant in bullet points. If there are new files that need to be created to accomplish the chore, list them in an h3 'New Files' section.>
## Step by Step Tasks
IMPORTANT: Execute every step in order, top to bottom.
<list step by step tasks as h3 headers plus bullet points. use as many h3 headers as needed to accomplish the chore. Order matters, start with the foundational shared changes required to fix the chore then move on to the specific changes required to fix the chore. Your last step should be running the `Validation Commands` to validate the chore is complete with zero regressions.>
## Validation Commands
Execute every command to validate the chore is complete with zero regressions.
<list commands you'll use to validate with 100% confidence the chore is complete with zero regressions. every command must execute without errors so be specific about what you want to run to validate the chore is complete with zero regressions. Don't validate with curl commands.>
- `cd app/server && uv run pytest` - Run server tests to validate the chore is complete with zero regressions
## Notes
<optionally list any additional notes or context that are relevant to the chore that will be helpful to the developer>
Chore
$ARGUMENTS
Feature Planning
Create a new plan in specs/*.md to implement the Feature using the exact specified markdown Plan Format. Follow the Instructions to create the plan use the Relevant Files to focus on the right files.
Instructions
- You're writing a plan to implement a net new feature that will add value to the application.
- Create the plan in the
specs/*.mdfile. Name it appropriately based on theFeature. - Use the
Plan Formatbelow to create the plan. - Research the codebase to understand existing patterns, architecture, and conventions before planning the feature.
- IMPORTANT: Replace every in the
Plan Formatwith the requested value. Add as much detail as needed to implement the feature successfully. - Use your reasoning model: THINK HARD about the feature requirements, design, and implementation approach.
- Follow existing patterns and conventions in the codebase. Don't reinvent the wheel.
- Design for extensibility and maintainability.
- If you need a new library, use
uv addand be sure to report it in theNotessection of thePlan Format. - Start your research by reading the
README.mdfile and docs/ folder.
Plan Format
# Feature: <feature name>
## Feature Description
<describe the feature in detail, including its purpose and value to users>
## User Story
As a <type of user>
I want to <action/goal>
So that <benefit/value>
## Problem Statement
<clearly define the specific problem or opportunity this feature addresses>
## Solution Statement
<describe the proposed solution approach and how it solves the problem>
## Relevant Files
Use these files to implement the feature:
<find and list the files that are relevant to the feature describe why they are relevant in bullet points. If there are new files that need to be created to implement the feature, list them in an h3 'New Files' section.>
## Implementation Plan
### Phase 1: Foundation
<describe the foundational work needed before implementing the main feature>
### Phase 2: Core Implementation
<describe the main implementation work for the feature>
### Phase 3: Integration
<describe how the feature will integrate with existing functionality>
## Step by Step Tasks
IMPORTANT: Execute every step in order, top to bottom.
<list step by step tasks as h3 headers plus bullet points. use as many h3 headers as needed to implement the feature. Order matters, start with the foundational shared changes required then move on to the specific implementation. Include creating tests throughout the implementation process. Your last step should be running the `Validation Commands` to validate the feature works correctly with zero regressions.>
## Testing Strategy
### Unit Tests
<describe unit tests needed for the feature>
### Integration Tests
<describe integration tests needed for the feature>
### Edge Cases
<list edge cases that need to be tested>
## Acceptance Criteria
<list specific, measurable criteria that must be met for the feature to be considered complete>
## Validation Commands
Execute every command to validate the feature works correctly with zero regressions.
<list commands you'll use to validate with 100% confidence the feature is implemented correctly with zero regressions. every command must execute without errors so be specific about what you want to run to validate the feature works as expected. Include commands to test the feature end-to-end.>
- `cd app/server && uv run pytest` - Run server tests to validate the feature works with zero regressions
## Clarification Needed
<optionally list any questions and clarifications required to properly design the feature. A developer will answer them in time. Also include your default decision (the one you'll follow if your questions are not answered). If the user answers your clarification questions, you should update the documentation.>
## Notes
<optionally list any additional notes, future considerations, or context that are relevant to the feature that will be helpful to the developer>
Feature
$ARGUMENTS
Implement the following plan
Follow the Instructions to implement the Plan then Report the completed work.
Instructions
- Read the plan, think hard about the plan and implement the plan.
Parameters
If this command is called with the --ff parameter, it means you should build the feature completely. In this case, you should reach out to the user only a) if you are done, b) if you have question or c) if you find any blocks.
If the command is not called with any parameter or you find the --phases parameter in the arguments, then you should proceed with a phased approach to the development, which means you should stop after each phase and ask the user for review before continuing to the next stage.
Plan
$ARGUMENTS
Report
In any mode (ff or phases), at the end of each phase:
- Update the plan.md file (if there is one), marking completed tasks as done
[X] - Add comments to the completed phase with a summary of what was accomplished, specially if you changed the plan for some reason.
In any mode (ff or phases), when you are done:
- Summarize the work you've just done in a concise bullet point list.
- Report the files and total lines changed with
git diff --stat
Tasks Command
This command breaks down the architecture into concrete, actionable implementation tasks organized by user story and phase.
User Input
Arguments:
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Prerequisites
Before running this command:
- ✅ Feature specs must exist at
./specs/<feature_slug>/specs.md - ✅ Architecture must exist at
./specs/<feature_slug>/architecture.md - ✅ You should be on the correct feature branch
- ❌ Do NOT run this if architecture has unresolved open questions
Execution Flow
Step 0: Load Context
-
Identify the current feature by checking:
- Current git branch name (if using git)
- Ask user to specify feature if unclear
-
Load required files from
./specs/<feature_slug>/:- Required:
specs.md(for user stories with priorities) - Required:
architecture.md(for tech decisions and components) - Optional:
contracts.md(for API endpoints and data models)
- Required:
-
Verify architecture is complete:
- No unresolved "Open Questions" section items
- All user stories have component mappings
- File structure is defined
- If incomplete, STOP and tell user to resolve architecture first
Step 1: Extract Information
From the loaded documents, extract:
From specs.md:
- All user stories with priorities (P1, P2, P3, etc.)
- For each user story: title, goal, acceptance criteria
- Edge cases and special requirements
From architecture.md:
- Tech stack and dependencies
- Component structure (new files, modified files)
- User story mapping (which files belong to which story)
- Integration points and dependencies
- File structure and naming conventions
From contracts.md (if exists):
- Data models/entities
- API endpoints
- Validation rules
- Request/response formats
Step 2: Organize Tasks by Phase
Break down the implementation into phases following this structure:
Phase 1: Setup (~1-2h)
- Project initialization
- Dependency installation
- Configuration setup
- Development environment prep
Phase 2: Foundational (~2-4h)
- Core infrastructure that BLOCKS all user stories
- Examples: Database setup, auth framework, base classes, routing infrastructure
- CRITICAL: Nothing user-story-specific here - only blocking prerequisites
Phase 3+: User Stories (one phase per story, in priority order)
- Each user story gets its own phase
- Organized by priority (P1 first, then P2, then P3, etc.)
- Each phase should be ~2-4 hours of work
- Include: models, services, endpoints, UI, tests (if requested)
Final Phase: Polish
- Documentation
- Code cleanup
- Performance optimization
- Cross-cutting concerns
Step 3: Generate Tasks
For each phase, generate specific tasks following these rules:
Task Format:
- [ ] T001 [P] [US1] Specific task description with file path
Components:
[ ]or[x]: Checkbox for completion trackingT001: Unique sequential ID[P]: OPTIONAL marker for tasks that can run in parallel (different files, no dependencies)[US1]: User story reference (omit for Setup/Foundational/Polish phases)- Description: Concrete action with specific file path when relevant
Task Granularity:
- Each task should be completable in 15-30 minutes
- Include enough detail that an LLM can execute it
- Specify file paths when creating/modifying files
- Be specific but not excessively verbose
Parallelization Rules:
- Mark [P] only if tasks touch different files
- Same file = sequential (no [P] marker)
- Different files with no logical dependency = [P]
- Tests can often be [P] with each other
Test Tasks (OPTIONAL):
- Only include if explicitly requested in specs or user asks
- Tests should come BEFORE implementation (TDD approach)
- Each test task should verify it FAILS before implementation
Step 4: Estimate Time
For each phase, provide a realistic time estimate:
- Setup: Usually 1-2h
- Foundational: 2-4h (can be longer for complex setups)
- User Stories: 2-4h each (adjust based on complexity)
- Polish: 1-2h
Time estimates help with:
- Session planning (knowing when to take breaks)
- Progress tracking
- Resource allocation
Step 5: Map Dependencies
Document explicit dependencies between phases:
- Which phases must complete before others can start
- Which user stories are independent vs dependent
- Parallel opportunities (which stories can be worked simultaneously)
Step 6: Generate plan.md
Create ./specs/<feature_slug>/plan.md with this structure (the content itself is just for your reference, keep the structure):
# Tasks: [FEATURE NAME]
**Branch**: [branch-name]
**Specs**: [link to specs.md]
**Architecture**: [link to architecture.md]
**Status**: Not Started ⏳
---
## Phase 1: Setup ⏳ (~2h)
**Purpose**: Initialize project structure and dependencies
- [ ] T001 [P] Create project structure per architecture.md
- [ ] T002 [P] Install dependencies: [list key dependencies]
- [ ] T003 Configure [linting/formatting tools]
- [ ] T004 Setup development environment variables
**Notes:**
- [Space for learnings and comments during implementation]
---
## Phase 2: Foundational ⏳ (~3h)
**Purpose**: Core infrastructure that BLOCKS all user stories
⚠️ **CRITICAL**: No user story work can begin until this phase completes
- [ ] T005 Setup database schema and migrations in [path]
- [ ] T006 [P] Implement authentication middleware in [path]
- [ ] T007 [P] Create base error handling in [path]
- [ ] T008 Setup logging infrastructure in [path]
**Checkpoint**: ✋ Foundation ready - user stories can now proceed
**Notes:**
- [Space for learnings and comments]
---
## Phase 3: User Story 1 - [Title] (P1) ⏳ 🎯 MVP (~4h)
**Goal**: [Brief description from specs.md]
**Independent Test**: [How to verify this story works standalone]
### Tasks
- [ ] T009 [P] [US1] Create [Entity] model in src/models/[entity].py
- [ ] T010 [P] [US1] Create [Entity2] model in src/models/[entity2].py
- [ ] T011 [US1] Implement [Service] in src/services/[service].py
- [ ] T012 [US1] Create [endpoint/feature] in src/[path]/[file].py
- [ ] T013 [US1] Add validation for [entity] fields
- [ ] T014 [US1] Add error handling for [scenario]
- [ ] T015 [US1] Add logging for [operations]
**Checkpoint**: ✋ User Story 1 complete and independently testable
**Notes:**
- [Space for learnings and comments]
---
## Phase 4: User Story 2 - [Title] (P2) ⏳ (~3h)
**Goal**: [Brief description from specs.md]
**Independent Test**: [How to verify this story works standalone]
### Tasks
- [ ] T016 [P] [US2] Create [Entity] model in src/models/[entity].py
- [ ] T017 [US2] Implement [Service] in src/services/[service].py
- [ ] T018 [US2] Create [endpoint/feature] in src/[path]/[file].py
- [ ] T019 [US2] Integrate with User Story 1 (if needed)
**Checkpoint**: ✋ User Stories 1 AND 2 both work independently
**Notes:**
- [Space for learnings and comments]
---
[Repeat for each user story: Phase 5 for US3, Phase 6 for US4, etc.]
---
## Phase N: Polish & Documentation ⏳ (~2h)
**Purpose**: Final touches and cross-cutting improvements
- [ ] TXXX [P] Update README.md with new feature documentation
- [ ] TXXX [P] Add inline code comments for complex logic
- [ ] TXXX Code cleanup and refactoring
- [ ] TXXX Performance optimization review
- [ ] TXXX Security review checklist
**Notes:**
- [Space for learnings and comments]
---
## Dependencies & Execution Order
### Phase Dependencies
Setup (Phase 1) ↓ Foundational (Phase 2) ← BLOCKS everything below ↓ ├─→ User Story 1 (Phase 3) - Can start ├─→ User Story 2 (Phase 4) - Can start in parallel OR after US1 └─→ User Story 3 (Phase 5) - Can start in parallel OR after US1/US2 ↓ Polish (Final Phase) - After all desired stories complete
### User Story Independence
- **US1 (P1)**: No dependencies on other stories ✅ MVP
- **US2 (P2)**: [Independent OR depends on US1 - specify]
- **US3 (P3)**: [Independent OR depends on US1/US2 - specify]
### Parallel Opportunities
**Within a phase:**
- Tasks marked [P] can run simultaneously
- Example: Multiple model files can be created in parallel
**Across phases:**
- After Foundational completes, ALL user stories CAN run in parallel
- Recommended: Complete US1 first (MVP), then parallelize US2+US3
---
## Implementation Strategy
### 🎯 MVP First (Recommended)
1. Complete Phase 1: Setup ✅
2. Complete Phase 2: Foundational ✅
3. Complete Phase 3: User Story 1 ✅
4. **STOP and VALIDATE** - Test US1 independently
5. Deploy/demo if ready
6. Then proceed to US2, US3, etc.
### 📈 Incremental Delivery
Each user story adds value independently:
- After US1: Deploy MVP ✅
- After US2: Deploy US1+US2 ✅
- After US3: Deploy US1+US2+US3 ✅
### 👥 Parallel Team Strategy
With multiple developers after Foundational:
- Developer A: User Story 1
- Developer B: User Story 2
- Developer C: User Story 3
- Stories integrate seamlessly when complete
---
## Progress Tracking
**Emoji Legend:**
- ⏳ Not Started
- ⏰ In Progress
- ✅ Completed
**Update this file as you work:**
1. Change phase status emoji (⏳ → ⏰ → ✅)
2. Check off tasks as completed: `- [x]`
3. Add notes/learnings in the Notes sections
4. Update time estimates if needed
---
## Task Execution Tips
**Before starting a task:**
- Read the task description carefully
- Check if any [P] sibling tasks can run in parallel
- Verify prerequisites are complete
**While executing:**
- Follow file paths exactly as specified
- Match existing code patterns and conventions
- Test incrementally (don't wait until phase end)
**After completing a task:**
- Mark it complete: `- [x]`
- Commit if it's a logical unit
- Add any learnings to Notes section
**At checkpoints:**
- Validate the entire phase works as expected
- Test user story independently
- Get user approval before continuing
---
## Notes
**Key Conventions:**
- [P] = Can run in parallel (different files)
- [US1] = Belongs to User Story 1
- File paths should be exact and absolute when possible
- Commit after each task or logical grouping
- Stop at checkpoints to validate
**Remember:**
- Each user story should be independently completable
- Foundational phase blocks everything - don't skip it
- MVP = Just User Story 1 (P1)
- Add learnings to Notes sections as you discover them
Step 7: Final Report
Present to the user:
-
Task Summary:
- Total number of tasks: [X]
- Number of phases: [Y]
- Tasks per user story breakdown
- Estimated total time: [Z hours]
-
Files generated:
- Link to
plan.md
- Link to
-
MVP Definition:
- Clearly state what constitutes the MVP (usually just P1 user story)
- Estimated time to MVP: [X hours]
-
Parallel Opportunities:
- Highlight which phases can be parallelized
- Note tasks marked [P] within phases
-
Next Steps:
- Suggest reviewing plan.md
- Recommend starting with Phase 1 (Setup)
- Mention checkpoints for validation
- Ask if they want to proceed to
/workor adjust tasks
Guidelines
Task Generation Guidelines
Be Specific:
- ❌ "Implement user authentication"
- ✅ "Implement JWT authentication middleware in src/auth/jwt.py"
Be Actionable:
- Each task should have a clear deliverable
- Include file paths when creating/modifying code
- Specify what needs to be tested
Be Realistic:
- Each task: 15-30 minutes
- Each phase: 2-4 hours
- Don't create micro-tasks (too granular)
- Don't create mega-tasks (too broad)
Be Independent:
- User stories should be independently completable
- Mark dependencies explicitly when they exist
- Prefer independence over tight coupling
Time Estimation Guidelines
Consider:
- Complexity of the task
- Need for research/learning
- Testing and debugging time
- Integration complexity
Default Estimates:
- Simple CRUD: 2-3h per user story
- API endpoints: 3-4h per user story
- Complex business logic: 4-6h per user story
- UI components: 2-4h per user story
Adjust based on:
- Team experience with tech stack
- Code familiarity
- Availability of examples/patterns
Documentation Guidelines
Notes Sections:
- Use for learnings during implementation
- Document unexpected issues
- Record decisions made on-the-fly
- Capture "gotchas" for future reference
Status Tracking:
- Update emojis as phases progress
- Check off tasks as completed
- Keep the file current (living document)
Error Handling
If specs.md is missing:
ERROR: No specs found at ./specs/<feature_slug>/specs.md
Please run `/specify` first to create the feature specification.
If architecture.md is missing:
ERROR: No architecture found at ./specs/<feature_slug>/architecture.md
Please run `/plan` first to create the technical architecture.
If architecture has open questions:
WARNING: Architecture has unresolved open questions:
- [List them]
Resolve these before generating tasks, or tasks may be incomplete.
Proceed anyway? (yes/no)
If no user stories found:
ERROR: No user stories found in specs.md
User stories are required to organize tasks by priority.
Please update specs.md with user stories before running /tasks.
Example Flow
User: /tasks
Claude:
I'll break down the architecture into actionable tasks.
[Loads specs.md and architecture.md from ./specs/001-api-endpoints/]
Found:
- 3 user stories (P1, P2, P3)
- Tech stack: Python 3.11 + FastAPI
- 5 new files to create, 2 files to modify
Generating tasks organized by user story...
✅ Tasks created!
📄 File: ./specs/001-api-endpoints/plan.md
📊 Summary:
- Total tasks: 24
- Phases: 6 (Setup, Foundational, 3 User Stories, Polish)
- Estimated time: ~16 hours
- MVP (US1 only): ~7 hours
🎯 MVP Definition:
User Story 1 (P1): "API Authentication" - Allows users to authenticate via JWT
🔀 Parallel Opportunities:
- Within Phase 2: Tasks T005-T007 can run in parallel
- After Phase 2: All user stories can proceed in parallel
- Within each user story: Model creation tasks marked [P]
💡 Recommended Approach:
1. Start with Phase 1 (Setup) - ~2h
2. Complete Phase 2 (Foundational) - ~3h ⚠️ This blocks everything
3. Focus on Phase 3 (US1 - MVP) - ~4h
4. Validate US1 works independently ✋
5. Then proceed to US2 and US3 in any order
Ready to start implementation? Run `/implement` when you're ready!
Prime
Execute the following sections to understand the codebase then summarize your understanding.
Run
git ls-files
Read
README.md
List
Run tree docs to know which docs are available.
Read as needed during the session if you have any questions on how this project works.
List All Tools
List all availagle tools detailed in your system prompt. Display them in bullet points. Display them in typescript function signature format and suffix the purpose of the tool.
Generate CLAUDE.md Documentation
Generate CLAUDE.md files to provide AI coding assistants with codebase context.
Purpose
CLAUDE.md files exist solely to help AI developers understand the codebase when working on files in each directory. They are NOT:
- Human documentation (README, docs/)
- Tutorials or guides
- API references
- Installation instructions
They ARE:
- Contextual maps for AI navigating the codebase
- Integration guides showing how modules connect
- Pattern documentation for consistent code generation
- Gotcha lists preventing common AI mistakes
What to Include
Essential Content
- Module purpose: One sentence explaining what this code does
- File catalog: What each file contains and its role
- Key patterns: How things are done here (naming, structure, error handling)
- Integration points: How this module connects to others
- Gotchas: Traps that would cause AI to generate incorrect code
- Anti-patterns: What NOT to do in this codebase
Exclude
- Version numbers, dates, "last updated"
- Installation/setup instructions
- CLI usage examples (unless explaining internal implementation)
- Human-readable tutorials
- Badges, links to external docs
- Anything a human needs but code context doesn't require
File Template
# [Module Name]
[One sentence: what this module does]
## Files
- **`file.py`**: [What it contains, key classes/functions]
- **`other.py`**: [What it contains]
## Patterns
- **[Pattern name]**: [How it's implemented here, when to use it]
## Integration
- Imports from: `module.x`, `module.y`
- Used by: `other_module.z`
- Data flow: [Brief description of how data moves through]
## Gotchas
- [Specific trap that would cause incorrect code generation]
- [Another gotcha]
## When Adding Code
- [Constraint or convention to follow]
- [Another convention]
Hierarchy Rules
Execution Order: Leaves → Trunk
Build from deepest directories up to root:
- Leaf files (deepest): Document every file, all patterns, all gotchas
- Parent directories: Focus on how children integrate, reference children for details
- Root (last): High-level map only, everything else in children
Content Distribution
| Level | Contains | Avoids |
|---|---|---|
| Leaf | All file details, all patterns, all gotchas | - |
| Mid | Integration between children, cross-cutting patterns | Repeating child content |
| Root | Directory map, project-wide patterns only | Implementation details |
Reference Pattern
Parent files should say:
## Submodules
- **[child/](child/CLAUDE.md)**: [What it handles]
See child CLAUDE.md for implementation details.
NOT duplicate the child's content.
Anti-Patterns
DON'T include:
## Quick Startor## Getting Started## Installation## Usage Examples(unless showing internal patterns)## Versionor version numbers## Contributingor## LicenseCurrent: v1.2.0or any version stringsLast Updated: January 2025- Links to external documentation
- Badges or status indicators
DON'T duplicate:
- Same file description in parent and child
- Same gotcha at multiple levels
- Same pattern explanation repeated
DO include:
- What would cause AI to write incorrect code
- How modules actually connect (not how users use them)
- Naming conventions that must be followed
- Edge cases in the implementation
Placement Strategy
Create CLAUDE.md in:
- Project root (always)
- Directories with substantial implementation code (3+ non-trivial files)
- Directories with complex internal logic worth documenting
Skip CLAUDE.md for:
- Pass-through directories: Folders that just contain
__init__.py+ subfolders (e.g.,src/package/when all code is insrc/package/core/,src/package/utils/) - Simple re-export levels: If a directory only has
__init__.pythat re-exports from children, skip it - document in root instead - Single-file directories
- Generated code
- Pure configuration directories
node_modules,__pycache__,.git, etc.
Pass-Through Directory Rule
If a directory structure looks like:
src/mypackage/
├── __init__.py # Just re-exports
├── one_simple_file.py # Could be mentioned in root
├── core/ # Has real implementation
├── utils/ # Has real implementation
└── api/ # Has real implementation
Then skip src/mypackage/CLAUDE.md. Instead:
- Root CLAUDE.md references
core/,utils/,api/directly - Mention
__init__.pyandone_simple_file.pybriefly in root
This avoids CLAUDE.md files that are just "see children for details".
Execution
- Map directory structure, identify documentation points
- Start with deepest directories (leaves)
- Work up, referencing children instead of repeating
- Finish with root as navigation hub
- Review: remove any human-oriented content that crept in
Sponsors
Details
- Marketplace
- lfnovo/por-marketplace
- Source
- por-dev
- Category
- Community