Local PRD commands

create-design.md

(local) Create Technical Design Document

Goal

Create a technical design that discusses how a feature could be implemented at a high level. This is step 2 of 3 - a discussion document for senior engineers, not an implementation guide.

Process

1. Read PRD: Load and understand the requirements ($ARGUMENTS)
2. Start Conversation: Ask clarifying questions about complexity and constraints
3. Gather Context: Based on the PRD and conversation, search for:
   • Similar patterns in the codebase
   • Relevant architecture documentation
   • Existing components that could be extended
4. Iterate Together: Suggest approaches, refine through conversation
5. Save Progress: Update __tasks/[feature-name]/design.md as decisions are made
6. Finalize: Complete the design document

Key Focus Areas

• Naming - Good names simplify concepts. Discuss what things should be called.
• Interfaces & Integration - What do methods accept/return? How do components connect?

Interaction Model

Work conversationally to distill complexity into simple solutions:

• Ask questions about constraints and existing patterns
• Present different approaches with trade-offs
• Get feedback and iterate until the solution is clear
• Focus on architectural decisions, not implementation details
• Think like senior engineers discussing an approach, not writing instructions

create-prd.md

(local) Create Product Requirements Document (PRD)

Goal

Create a focused Product Requirements Document (PRD) that defines what needs to be built and why, setting the foundation for a subsequent technical design document that will address how to implement it.

Process

1. Receive Initial Prompt: The user provides a brief description or request for a new feature: $ARGUMENTS
2. Ask Clarifying Questions: Gather essential details focusing on business requirements, user needs, and desired outcomes. Avoid technical implementation details. Use numbered questions for easy reference.
3. Iterative Refinement (Optional): If the user provides partial answers, confirm what questions remain unanswered and let the user choose whether to provide more details or proceed with PRD generation.
4. Generate PRD: Create a concise PRD using the structure below, focusing on requirements and outcomes.
5. Save PRD: Save as __tasks/[feature-name]/prd.md
6. Next Step: This PRD will inform a follow-up technical design document covering architecture and implementation approach.

Clarifying Questions

Focus on business requirements and user needs. Use numbered questions for easy reference and answers. Key areas to explore:

1. Problem/Goal: What problem does this solve? What's the desired outcome?
2. Target User: Who will use this feature? What's their context?
3. Core Functionality: What key actions should users be able to perform?
4. User Stories: Can you provide 2-3 user stories showing the main use cases?
5. Success Criteria: How will we know this feature is successful?
6. Scope/Boundaries: What should this feature NOT include?
7. Data Requirements: What information does this feature work with?

Interaction Notes:

• Ask questions in numbered format for easy reference
• User can answer with format like "1: answer, 3: answer, 5: answer" to address specific questions
• If user provides partial answers, summarize what's still unanswered and let them choose to elaborate or proceed
• General rule: Assume less, ask more

PRD Structure

1. Overview: Brief description of the feature and problem it solves
2. Goals: Specific, measurable objectives
3. User Stories: 2-3 key user narratives showing main use cases
4. Functional Requirements: Numbered list of what the system must do
5. Non-Goals: What this feature will NOT include
6. Success Metrics: How success will be measured
7. Open Questions: Any remaining clarifications needed

Key Principles

• Business Focus: Describe WHAT needs to be built and WHY, not HOW
• Clear Requirements: Use explicit, unambiguous language
• User-Centered: Focus on user needs and outcomes
• Scope Management: Clearly define what's included and excluded

Output

Save as __tasks/[feature-name]/prd.md

Instructions

1. Ask clarifying questions first using numbered format for easy reference
2. Focus on business requirements, avoid technical implementation
3. Confirmation Approach: If user provides incomplete answers, summarize what questions remain unanswered and ask if they want to provide more details or proceed with PRD generation
4. Create the PRD based on user responses, avoiding assumptions when possible
5. Create the feature directory if it doesn't exist
6. The PRD will feed into a separate technical design step

Example Interaction Flow:

• Initial questions: "Here are some questions to help me create the PRD: 1. What problem does this solve? 2. Who will use this feature? ..."
• Confirmation: "Thanks for answering questions 1, 3, and 5. I still have questions 2, 4, and 6 unanswered. Would you like to provide answers to these, or should I proceed with creating the PRD based on what you've shared?"

create-tasks.md

(local) Rule: Generating a Task List from a PRD

Goal

To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on an existing Product Requirements Document (PRD). The task list should guide a developer through implementation.

Input

Feature directory: $ARGUMENTS (e.g., __tasks/user-profile-editing/)

• Contains: prd.md and design.md

Process Guidelines

Always read: .ai/incremental_development.md - Core workflow principles

Process

1. Read Context: Load PRD and design document from the feature directory
2. Phase 1: Generate Parent Tasks: Based on the PRD and design, create the file and generate the main, high-level tasks required to implement the feature. Use your judgement on how many high-level tasks to use. It's likely to be about 5. Present these tasks to the user in the specified format (without sub-tasks yet). Inform the user: "I have generated the high-level tasks based on the PRD. Ready to generate the sub-tasks? Respond with 'Go' to proceed."
3. Wait for Confirmation: Pause and wait for the user to respond with "Go".
4. Phase 2: Generate Sub-Tasks: Once confirmed, break down each parent task into smaller, actionable sub-tasks following incremental development principles. Ensure sub-tasks logically follow from the parent task and cover the implementation details implied by the design PRD. Important: Include testing tasks at logical points throughout implementation (e.g., after completing a controller action, form object, or key service) rather than leaving all testing for the end. Focus on testing what provides value - not every small implementation detail needs immediate specs, but core functionality and user-facing features should be tested as they're built.
5. Generate Final Output: Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure.
6. Save Task List: Save as __tasks/[feature-name]/tasks.md

Output Format

The generated task list must follow this structure:

### Notes

- **Testing Strategy**: Follow Rails testing best practices with RSpec. Tests should be written alongside implementation, not as a separate phase.

## Tasks

- [ ] 1.0 Parent Task Title
  - [ ] 1.1 [Implementation sub-task]
  - [ ] 1.2 [Implementation sub-task]
  - [ ] 1.3 [Write specs for core functionality]
  - [ ] 1.4 [Integration sub-task]
- [ ] 2.0 Parent Task Title  
  - [ ] 2.1 [Implementation sub-task]
  - [ ] 2.2 [Implementation sub-task]
  - [ ] 2.3 [Write specs for user-facing features]
- [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration)

Output

• Format: Markdown (.md)
• Location: __tasks/[feature-name]/
• Filename: tasks.md

Interaction Model

The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details.

Target Audience

Assume the primary reader of the task list is a junior developer who will implement the feature.

process-tasks.md

(local) Process Task List

Goal

To guide you through implementing a feature by working through tasks one at a time, with user approval between each task.

Input

Feature directory: $ARGUMENTS (e.g., __tasks/user-profile-editing/)

• Contains: prd.md, design.md, and tasks.md

Process Guidelines

Context gathering:

• Check .ai/ for relevant guides before implementing
• Example: testing tasks → read rspec.md, testing_execution.md
• Search codebase for similar patterns

Task Implementation Rules

• One sub-task at a time: Do NOT start the next sub‑task until you ask the user for permission and they say "yes" or "y"
• Completion protocol:
  1. When you finish a sub‑task, immediately mark it as completed by changing [ ] to [x].
  2. If all subtasks underneath a parent task are now [x], also mark the parent task as completed.
• Stop after each sub‑task and wait for the user's go‑ahead.

Task List Maintenance

1. Update the task list as you work:

   • Mark tasks and subtasks as completed ([x]) per the protocol above.
   • Add new tasks as they emerge.

2. Maintain the "Relevant Files" section:

   • List every file created or modified.
   • Give each file a one‑line description of its purpose.

Execution Mode Selection

Before beginning task implementation, ask the user to choose their preferred execution mode:

"Would you like to use parallel sub-agent execution for independent tasks? This can be faster but uses more tokens. (yes for parallel, no for sequential)"

• Parallel Mode (yes): Launch multiple sub-agents to work on independent tasks simultaneously

  • Faster completion for tasks without dependencies
  • Higher token usage due to multiple concurrent agents
  • All dependency rules are strictly enforced
  • Only tasks with satisfied dependencies can run in parallel

• Sequential Mode (no): Process tasks one at a time in order

  • Lower token usage
  • Easier to follow progress
  • Traditional one-by-one execution

Process

1. Read Context: Load PRD, design document, and task list from the feature directory
2. Ask Execution Mode: Present the parallel vs sequential choice to the user
3. Identify Next Task(s):
   • Sequential Mode: Find the first incomplete sub-task (marked with [ ]) that has all its dependencies satisfied
   • Parallel Mode: Find ALL incomplete sub-tasks that have all their dependencies satisfied
   • Check for [depends on: X.Y] notation
   • Verify all referenced dependencies are marked [x]
   • Skip tasks with incomplete dependencies
4. Implement Task(s):
   • Sequential Mode: Work on the specific sub-task
   • Parallel Mode: Launch sub-agents for each independent task
   • Follow best practices:
     • Understand existing codebase patterns before making changes
     • Follow project conventions and coding standards
     • Write tests when applicable
     • Ensure code quality and security
5. Update Task List: Mark completed sub-task(s) as [x] and update relevant files section
6. Request Permission: Ask user for permission to continue to next sub-task(s)
7. Repeat: Continue with next batch of tasks only after user approval

Important Guidelines

• Before starting work: Check which sub‑task is next by examining the task list and verifying all dependencies are satisfied
• After implementing a sub‑task: Update the task list file and pause for user approval
• When all sub-tasks under a parent are complete: Mark the parent task as [x] as well
• If you discover new tasks: Add them to the task list in the appropriate location
• For file modifications: Always read existing files first to understand patterns and conventions
• For testing: Run bundle exec rspec to verify implementations (see testing_execution.md)

Dependency Checking

Before starting any task:

1. Parse the [depends on: X.Y] notation in the task description
2. For each dependency:
   • Locate the referenced task (X.Y or X.0)
   • Verify it is marked as complete [x]
3. If any dependencies are incomplete:
   • Skip this task
   • Show message: "Task X.Y is blocked by incomplete dependencies: [list]"
   • Find the next available task with satisfied dependencies
4. Handle multiple dependencies (e.g., [depends on: 1.2, 3.4]) by checking all listed tasks

Task Completion Protocol

1. Complete the implementation for one sub-task
2. Update the task list file:
   • Change [ ] to [x] for the completed sub-task
   • Update "Relevant Files" section if new files were created/modified
   • Mark parent task [x] if all its sub-tasks are now complete
3. Save the updated task list file
4. Ask user: "Sub-task [X.Y] completed. Ready for the next sub-task? (yes/y to continue)"
5. Wait for user confirmation before proceeding

Error Handling

• If a sub-task cannot be completed due to blockers, keep it as [ ] and create a new sub-task describing what needs to be resolved
• Never mark a task as completed if:
  • Tests are failing
  • Implementation is partial
  • Unresolved errors occurred
  • Required files or dependencies are missing

Instructions

1. Read the task list file specified in $ARGUMENTS
2. Find the first incomplete sub-task with all dependencies satisfied
3. If a task has dependencies, verify they are complete before proceeding
4. Implement the task following the completion protocol
5. Update the task list and request user permission before continuing
6. Only work on one sub-task at a time with user approval between each