Initial commit

2025-11-29 17:59:51 +08:00
commit 5a4f0900ad
15 changed files with 2857 additions and 0 deletions
--- a/commands/brainstorm.md
+++ b/commands/brainstorm.md
@@ -0,0 +1,662 @@
+# Interactive Requirements Brainstorming with Intelligent Analysis v2.0
+
+Start an interactive Q&A session with deep codebase analysis and dynamically generated questions.
+
+**⚠️ CRITICAL: THIS COMMAND ONLY GATHERS REQUIREMENTS - NEVER IMPLEMENTS CODE ⚠️**
+
+## STRICT OPERATING MODE: READ-ONLY ANALYSIS
+
+**YOU MUST NEVER:**
+- Write, edit, or modify any code files
+- Create new source code files (except in `.requirements/` folder)
+- Execute implementation commands
+- Make code changes of any kind
+- Use Edit, Write, or code modification tools
+- Suggest or execute implementation during this workflow
+
+**YOU MAY ONLY:**
+- Read and analyze existing code
+- Search and explore the codebase
+- Research best practices
+- Ask questions
+- Create requirement documents in `.requirements/` folder
+- Generate specifications and recommendations
+
+**GOAL:** Gather complete, actionable requirements so implementation can happen later with `/implement` command.
+
+---
+
+## Full Workflow
+
+### Phase 1: Setup & Initialization
+
+When user runs `/brainstorm <description>`:
+
+1. **Parse the request**
+   - Extract feature description from arguments
+   - Generate slug: kebab-case version (e.g., "add user logging" → "user-logging")
+
+2. **Create timestamped requirement folder**
+   - Format: `.requirements/YYYY-MM-DD-HHMM-[slug]/`
+   - Example: `.requirements/2025-10-25-1430-user-logging/`
+
+3. **Initialize files**
+   - `01-initial-request.md` - Save user's original request verbatim
+   - `metadata.json` - Initialize tracking structure
+   - Update `.requirements/_current-requirement` with folder name
+
+4. **Initialize metadata.json**
+   ```json
+   {
+     "id": "user-logging",
+     "slug": "user-logging",
+     "started": "2025-10-25T14:30:00Z",
+     "lastUpdated": "2025-10-25T14:30:00Z",
+     "status": "active",
+     "phase": "discovery",
+     "originalRequest": "add user logging",
+     "progress": {
+       "discovery": { "generated": false, "answered": 0, "total": 0 },
+       "analysis": { "status": "pending" },
+       "expert": { "generated": false, "answered": 0, "total": 0 }
+     },
+     "contextFiles": [],
+     "relatedFeatures": [],
+     "toolsAvailable": ["serena", "context7", "WebSearch"]
+   }
+   ```
+
+5. **Announce**: "Starting requirements gathering for: [description]"
+
+---
+
+### Phase 2: Generate & Ask Discovery Questions
+
+**IMPORTANT: Questions are NOT hardcoded - they are generated dynamically based on the user's request!**
+
+#### Step 2.1: Generate Discovery Questions
+
+Use **sequential thinking** to generate contextual questions:
+
+```
+Task: Generate 5-7 discovery questions to gather requirements for: "[user's request]"
+
+Guidelines:
+- Analyze what's ambiguous or unclear in the request
+- Focus on WHAT the user wants, not HOW to implement
+- Questions should clarify scope, behavior, and expectations
+- Each question needs 2-5 numbered options with smart defaults
+- Mark one option as [default - brief reason why]
+- Include "Other (please specify)" for flexibility
+- Mix yes/no with multiple choice appropriately
+
+Focus areas based on request context:
+- Scope and boundaries of the feature
+- User interactions and workflows
+- Data/content being worked with
+- Performance or scale expectations
+- Security/privacy considerations
+- Integration with existing systems
+
+Output format for each question:
+## Q[N]: [Question Title]
+```
+[Question text that makes sense for THIS request]
+
+1. [Option 1] [default - reason based on request context]
+2. [Option 2]
+3. [Option 3]
+4. Other (please specify)
+```
+
+Available tools: serena (code analysis), context7 (library docs), WebSearch (best practices)
+
+Save all generated questions to: 02-discovery-questions.md
+```
+
+**Example output for "add user logging":**
+```markdown
+## Q1: What should be logged?
+```
+What information should the logging system capture?
+
+1. Error details and stack traces [default - most common use case]
+2. User actions and events
+3. Both errors and user actions
+4. Other (please specify)
+```
+
+## Q2: Where should logs be stored?
+```
+What's the preferred log storage solution?
+
+1. Local files (rotating logs) [default - simplest approach]
+2. Database (queryable logs)
+3. External service (e.g., Datadog, LogRocket)
+4. Other (please specify)
+```
+```
+
+**Example output for "build user dashboard":**
+```markdown
+## Q1: What data should the dashboard display?
+```
+What key metrics or information will users see?
+
+1. User activity and engagement [default - common dashboard need]
+2. System metrics and performance
+3. Business analytics and reports
+4. Other (please specify)
+```
+
+## Q2: Should the dashboard update in real-time?
+```
+How current should the dashboard data be?
+
+1. Static/on-page-load [default - simplest implementation]
+2. Real-time updates (WebSocket/polling)
+3. Refresh on user action
+4. Other (please specify)
+```
+```
+
+#### Step 2.2: Ask Questions One at a Time
+
+**UX Rules:**
+- Present ONE question at a time
+- Wait for user response before next question
+- Accept numbered responses (e.g., "1", "2") or free text for "Other"
+- Support revisions: user can say "back", "change Q2", or "restart"
+- Show progress after every 2-3 questions: "So far: [brief summary]..."
+- If user provides just number, auto-select that option
+
+**After all discovery questions answered:**
+- Save answers to `03-discovery-answers.md`
+- Update `metadata.json` progress
+- Announce: "Discovery complete. Starting intelligent codebase analysis..."
+
+---
+
+### Phase 3: Intelligent Codebase Analysis (Autonomous)
+
+**NO USER INTERACTION - Fully autonomous**
+
+**⚠️ CRITICAL REMINDER: READ-ONLY ANALYSIS ONLY - DO NOT IMPLEMENT ANYTHING ⚠️**
+
+Use **sequential thinking** for intelligent analysis:
+
+```
+Task: Analyze codebase to support implementing: "[user's request]"
+
+**CRITICAL CONSTRAINTS:**
+- DO NOT write, edit, or modify any code files
+- DO NOT create new source code files
+- DO NOT use Edit, Write, or any code modification tools
+- ONLY read, search, and analyze existing code
+- ONLY create requirement documents in .requirements/ folder
+- Your role is RESEARCH and SPECIFICATION, not implementation
+
+Context from discovery phase:
+[Include summary of all discovery answers]
+
+Your objectives:
+1. Understand current architecture and technology stack (READ-ONLY)
+2. Find similar features or related implementations (READ-ONLY)
+3. Identify specific files that will need modification (DOCUMENT, don't modify)
+4. Research best practices for this type of feature (RESEARCH ONLY)
+5. Determine integration points with existing code (ANALYZE, don't implement)
+6. Generate implementation recommendations with rationale (RECOMMEND, don't execute)
+
+Available tools (READ-ONLY usage):
+- serena: For finding symbols, searching patterns, analyzing code structure
+  * Use find_symbol to locate classes/functions
+  * Use search_for_pattern for code patterns
+  * Use find_referencing_symbols for dependencies
+  * Use get_symbols_overview for file structure
+  * DO NOT use replace_symbol_body, insert_after_symbol, insert_before_symbol
+
+- context7: For library/framework documentation
+  * Research best practices for libraries used in codebase
+
+- WebSearch: For industry best practices
+  * Search for implementation patterns
+  * Find security considerations
+  * Discover performance optimization techniques
+
+Output required in 04-context-findings.md:
+
+# Codebase Analysis Findings
+
+## Architecture Overview
+[High-level structure - technology stack, patterns used]
+
+## Similar Features Found
+- `[file-path]` - [what it does, why similar]
+- [Include code snippets showing patterns]
+
+## Patterns to Follow
+```[language]
+// Example from [file-path]:[line-number]
+[relevant code snippet]
+```
+[Explanation of pattern and why it's relevant]
+
+## Files to Modify/Create
+- `[path]` - [what changes needed]
+- `[path]` - [what to add]
+
+## Integration Points
+[How this feature connects to existing code]
+
+## Best Practices Research
+[External best practices found via context7/WebSearch]
+
+## Recommended Approach
+[Specific implementation strategy with rationale]
+
+## Technical Constraints
+[Limitations, dependencies, considerations]
+```
+
+**After Phase 3:**
+- Save findings to `04-context-findings.md`
+- Update `metadata.json` with `contextFiles` and `relatedFeatures`
+- Announce: "✅ Read-only analysis complete. Found [N] related features and [N] files to modify (documentation only - no code was changed). Generating expert questions..."
+
+---
+
+### Phase 4: Generate & Ask Expert Questions
+
+**Again, questions are dynamically generated based on findings!**
+
+#### Step 4.1: Generate Expert Questions
+
+Use **sequential thinking** to generate implementation questions:
+
+```
+Task: Generate 5-7 expert implementation questions
+
+Input context:
+- Original request: "[user's request]"
+- Discovery answers: [summary from Phase 2]
+- Codebase findings: [summary from 04-context-findings.md]
+
+Guidelines:
+- Reference ACTUAL files and patterns found in Phase 3
+- Questions should finalize implementation approach
+- Include numbered options with defaults based on codebase patterns
+- Explain WHY each default makes sense (cite specific findings)
+- Focus on HOW to implement, not WHAT to build
+
+Question types to consider:
+- Architecture decisions (extend existing vs create new)
+- File/component organization
+- Library/framework usage patterns
+- Code pattern consistency
+- Integration approach
+- Testing strategy
+
+Output format for each question:
+## Q[N]: [Question Title]
+```
+[Question text referencing actual findings]
+
+1. [Option 1] [default - reason citing analysis]
+2. [Option 2]
+3. [Option 3]
+
+**Why this matters:**
+[Explanation based on Phase 3 findings - cite files, patterns discovered]
+```
+
+Save all generated questions to: 05-expert-questions.md
+```
+
+**Example output for "add user logging" after finding existing Logger:**
+```markdown
+## Q6: Should we extend the existing Logger?
+```
+Found Logger class at `src/utils/logger.ts`. How should we implement user logging?
+
+1. Extend existing Logger class [default - maintains consistency]
+2. Create separate UserLogger class
+3. Add logging as middleware
+
+**Why this matters:**
+Analysis found that `AuthService` and `PaymentService` both use the
+existing Logger at src/utils/logger.ts:15. The Logger already supports
+Winston with rotating file transport. Extending it maintains architectural
+consistency and reuses existing log rotation configuration.
+```
+
+## Q7: Which log format should we use?
+```
+The existing Logger uses JSON format. Should user logging follow this pattern?
+
+1. Yes, use JSON format [default - matches existing pattern]
+2. Plain text format
+3. Structured format (custom)
+
+**Why this matters:**
+Found 47 log statements across the codebase all using JSON format via
+`logger.info({...})` pattern. The log aggregator at scripts/analyze-logs.ts
+parses JSON format. Consistency enables easier log analysis.
+```
+```
+
+#### Step 4.2: Ask Expert Questions One at a Time
+
+Same UX rules as Phase 2:
+- ONE question at a time
+- Accept numbered responses
+- Support revisions
+- Show progress summaries
+
+**After all expert questions answered:**
+- Save answers to `06-expert-answers.md`
+- Update `metadata.json`
+- Announce: "Expert questions complete. Generating comprehensive requirements specification..."
+
+---
+
+### Phase 5: Generate Comprehensive Requirements Spec
+
+Create `07-requirements-spec.md` synthesizing all information:
+
+```markdown
+# [Feature Name from Request]
+
+**Created:** [ISO-8601 timestamp]
+**Status:** draft
+**Last Updated:** [ISO-8601 timestamp]
+
+---
+
+## Overview
+
+[2-3 paragraph summary combining:
+- Original request
+- Discovery answers (what user wants)
+- Analysis findings (current state)
+- Implementation approach (expert decisions)]
+
+---
+
+## Requirements
+
+### Functional Requirements
+[From discovery answers - what the feature must do]
+
+1. [Requirement based on discovery Q&A]
+2. [Requirement based on discovery Q&A]
+3. [Additional requirements inferred]
+
+### User Interactions
+[Detailed workflow based on discovery answers]
+
+---
+
+## Technical Implementation
+
+### Architecture Decision
+[Based on expert Q&A - chosen approach with rationale]
+
+### Files to Modify
+[From Phase 3 analysis and Phase 4 decisions]
+
+- **`[file-path]`**
+  - What to change: [description]
+  - Pattern to follow: [reference to similar code]
+
+- **`[file-path]`**
+  - What to create: [description]
+
+### Technology Stack
+[Libraries/frameworks from analysis and decisions]
+
+### Integration Points
+[From Phase 3 analysis - how it connects]
+
+---
+
+## Implementation Guide
+
+### Patterns to Follow
+
+```[language]
+// From [similar-feature-file]:[line-number]
+[code snippet showing pattern to follow]
+```
+**Apply this pattern for:** [explanation]
+
+### Similar Features for Reference
+- **`[file-path]`** - [what it does similarly, line numbers]
+- **`[file-path]`** - [pattern to emulate]
+
+### Step-by-Step Approach
+1. [Concrete step from expert decisions]
+2. [Concrete step referencing files]
+3. [Concrete step with pattern reference]
+
+---
+
+## Testing Strategy
+
+[Based on how similar features are tested]
+
+- Unit tests: [approach based on codebase patterns]
+- Integration tests: [if needed]
+- Test files: [where to add tests, following existing structure]
+
+---
+
+## Edge Cases & Constraints
+
+### Edge Cases to Handle
+[From discovery phase and analysis]
+
+### Technical Constraints
+[From Phase 3 analysis]
+
+### Performance Considerations
+[From discovery answers if applicable]
+
+### Security Considerations
+[From discovery answers and analysis]
+
+---
+
+## Acceptance Criteria
+
+- [ ] [Functional criterion from requirements]
+- [ ] [Implementation criterion from expert decisions]
+- [ ] [Integration criterion from analysis]
+- [ ] [Testing criterion]
+- [ ] [Documentation criterion]
+
+---
+
+## Implementation Checklist
+
+- [ ] Review similar implementation at `[file-path]:[line]`
+- [ ] [Specific action from expert Q&A]
+- [ ] Modify `[file-path]` following pattern from `[reference-file]`
+- [ ] Add tests in `[test-file-path]` (follow existing test structure)
+- [ ] Update documentation at `[doc-path]`
+- [ ] [Any security/performance tasks]
+
+---
+
+## References
+
+- **Codebase Analysis:** `04-context-findings.md`
+- **Similar Features:**
+  - `[file-path]` - [what to learn from it]
+- **Best Practices:** [links from WebSearch/context7]
+- **Dependencies:** [libraries mentioned in analysis]
+
+---
+
+## Notes
+
+[Any assumptions made, open questions, or alternative approaches considered]
+```
+
+**After Phase 5:**
+- Update `.requirements/_index.json`:
+  ```json
+  {
+    "user-logging": {
+      "created": "2025-10-25T14:30:00Z",
+      "status": "draft",
+      "lastModified": "2025-10-25T15:15:00Z",
+      "lastWorked": null,
+      "folder": ".requirements/2025-10-25-1430-user-logging/",
+      "relatedFeatures": ["auth-service", "payment-logging"],
+      "filesInvolved": 5
+    }
+  }
+  ```
+- Show completion summary with **explicit reminder**:
+
+```
+✅ Requirements gathering complete!
+
+📁 All documentation saved to: .requirements/[folder]/
+
+⚠️ IMPORTANT: NO CODE WAS MODIFIED
+- This was a READ-ONLY analysis phase
+- All findings are documented in requirement files
+- No source code files were changed
+
+📋 Next Steps:
+1. Review requirements: .requirements/[folder]/07-requirements-spec.md
+2. When ready to implement: /implement [slug]
+
+This brainstorm session ONLY gathered requirements.
+Implementation is a separate step that you control.
+```
+
+---
+
+## Best Practices
+
+### Question Flow
+- **One at a time** - Never ask multiple questions simultaneously
+- **Accept shorthand** - User can respond with just number (e.g., "1")
+- **Auto-select defaults** - If user presses enter, use [default]
+- **Follow-up intelligently** - Ask clarifying questions based on answers
+- **Show progress** - Every 2-3 questions, show summary: "So far we have..."
+- **Allow revisions** - User can say "back", "change Q3", or "restart from Q5"
+
+### Analysis Phase
+- **CRITICAL: READ-ONLY MODE** - Never use Edit, Write, or code modification tools
+- Use sequential thinking for intelligent tool coordination
+- Document file paths and line numbers in findings
+- Capture code snippets from similar features (for documentation, not implementation)
+- Research external best practices
+- Generate hypotheses and verify them (through reading, not implementing)
+- Track confidence in recommendations
+- **STOP if you find yourself about to modify code** - This is requirements gathering only!
+
+### Expert Questions
+- Always reference actual files found in analysis
+- Explain rationale for defaults using findings
+- Give user flexibility to choose different approach
+- Use numbered format for consistency
+- Include "Why this matters" explanations
+
+### Tool Usage
+
+**ALLOWED TOOLS (Read-Only):**
+- ✅ Read - Read existing files
+- ✅ Glob - Find files by pattern
+- ✅ Grep - Search code content
+- ✅ serena (read-only): find_symbol, search_for_pattern, get_symbols_overview, find_referencing_symbols
+- ✅ context7 - Research library documentation
+- ✅ WebSearch - Research best practices
+- ✅ Bash (read-only commands): ls, cat, find, grep, git log, etc.
+
+**FORBIDDEN TOOLS (Implementation):**
+- ❌ Edit - NEVER use
+- ❌ Write - NEVER use (EXCEPT for creating files in `.requirements/` folder ONLY)
+- ❌ NotebookEdit - NEVER use
+- ❌ serena (write operations): replace_symbol_body, insert_after_symbol, insert_before_symbol, rename_symbol - NEVER use
+- ❌ Bash (write commands): touch, cp, mv (except in `.requirements/`), git commit, npm install - NEVER use
+- ❌ Task - NEVER use for implementation agents
+- ❌ Any code generation or modification tool
+
+**EXCEPTION:** Write tool is allowed ONLY for creating requirement documents in `.requirements/[timestamp-slug]/` folder. Never write to source code files.
+
+**Guidelines:**
+- Check which tools are available before use
+- Prefer serena for symbol-level code analysis (READ-ONLY)
+- Use context7 for library documentation
+- Use WebSearch for industry best practices
+- Always document which tools were used in metadata
+- **IF YOU CATCH YOURSELF ABOUT TO USE A FORBIDDEN TOOL, STOP IMMEDIATELY**
+
+### User Experience
+- Announce phase transitions clearly
+- Provide rich context for decisions
+- Save progress after each phase
+- Support interruption and resumption
+- Allow user to review/revise any phase
+- Generate actionable, specific outputs
+
+---
+
+## Why This Version Is Optimal
+
+1. ✅ **Adaptive** - Questions change based on what user actually asked for
+2. ✅ **Intelligent** - Sequential thinking powers all analysis and generation
+3. ✅ **Context-aware** - Expert questions reference actual code found
+4. ✅ **Simple tools** - Only serena, context7, WebSearch (no redundant tools)
+5. ✅ **User-friendly** - Numbered choices, revisions, progress tracking
+6. ✅ **Actionable** - Output includes specific files, patterns, and steps
+7. ✅ **Flexible** - Works for any type of request (logging, UI, API, refactoring, etc.)
+8. ✅ **Safe** - READ-ONLY mode prevents accidental implementation during requirements gathering
+
+---
+
+## Examples of Adaptive Behavior
+
+### Request: "add logging to error handlers"
+- Phase 2 generates questions about: log levels, storage, PII handling, error context
+- Phase 3 finds: existing error handlers, current logging setup
+- Phase 4 asks: extend current logger? which error handler files to modify?
+
+### Request: "build user dashboard"
+- Phase 2 generates questions about: data to show, real-time updates, user personalization
+- Phase 3 finds: existing dashboard components, data fetching patterns
+- Phase 4 asks: reuse Dashboard layout? follow existing chart library pattern?
+
+### Request: "refactor authentication"
+- Phase 2 generates questions about: what to improve, breaking changes okay?, migration path
+- Phase 3 finds: current auth implementation, all usage locations
+- Phase 4 asks: backward compatibility approach? update all 47 references at once?
+
+**The questions adapt to the request - no more generic "what type of feature is this?"**
+
+---
+
+## Phase Transitions
+
+After each phase, clearly announce:
+- ✅ "Phase 1 complete. Generating discovery questions for: [request]..."
+- ✅ "Phase 2 complete. Starting READ-ONLY codebase analysis (no code will be modified)..."
+- ✅ "Phase 3 complete (READ-ONLY analysis - no code changed). Generating expert questions based on findings..."
+- ✅ "Phase 4 complete. Generating comprehensive requirements specification..."
+- ✅ "Requirements gathering complete! Review at `.requirements/[folder]/`. NO CODE WAS MODIFIED - implementation is a separate step."
+
+---
+
+## Error Handling
+
+- **If you catch yourself using Edit/Write/modification tools**: STOP IMMEDIATELY, apologize, explain this is read-only mode, continue with read-only analysis
+- **If you start implementing code**: STOP IMMEDIATELY, delete any modifications, remind yourself this is requirements gathering only
+- If tools unavailable: Skip Phase 3, ask generic expert questions
+- If sequential thinking fails: Fall back to manual analysis
+- If user abandons mid-session: Save progress in metadata, allow resume
+- If folder exists: Ask "Requirement exists. Overwrite, new version, or cancel?"
+- **If user asks "can you implement this?"**: Respond "This is requirements gathering phase. Once complete, use `/implement [slug]` to start implementation."
--- a/commands/continue.md
+++ b/commands/continue.md
@@ -0,0 +1,77 @@
+# Continue implementation
+
+Resume implementation of a requirement that was interrupted.
+
+# Instructions
+
+When the user runs `/continue [name]`:
+
+1. **Determine which requirement to continue**
+
+   a. **If name is provided**: `/continue user-authentication`
+      - Use that specific requirement
+
+   b. **If no name provided**: `/continue`
+      - Read `.requirements/_index.json`
+      - Find the requirement with the most recent `lastWorked` timestamp
+      - If none found or multiple with same timestamp, ask user to specify
+
+2. **Load the requirement and current state**
+   - Read `.requirements/<name>.md`
+   - Check which items in Implementation Checklist are checked
+   - Check which Acceptance Criteria are marked done
+   - Review any notes about implementation progress
+
+3. **Analyze codebase for current state**
+   - Use available tools to examine relevant files
+   - Identify what has been implemented
+   - Find where implementation stopped
+   - Look for TODO comments or incomplete code
+
+4. **Determine remaining work**
+   - Compare requirements with actual implementation
+   - List what's complete
+   - List what remains to be done
+   - Identify any gaps or issues
+
+5. **Present status to user**
+   Show clearly:
+   ```
+   Continuing: <name>
+
+   ✅ Completed:
+   - [Item 1]
+   - [Item 2]
+
+   ⏳ In Progress:
+   - [Item 3] (partially done)
+
+   ❌ Not Started:
+   - [Item 4]
+   - [Item 5]
+
+   Next step: [What I'll do next]
+   ```
+
+6. **Ask for confirmation**
+   "Should I continue with [next step], or would you like to adjust the plan?"
+
+7. **Resume implementation**
+   - Pick up where it left off
+   - Follow the same systematic approach as `/implement`
+   - Update checklist items as completed
+   - Update `_index.json` with `lastWorked` timestamp
+
+8. **Handle completion**
+   - If all work is done, mark requirement as "done" in `_index.json`
+   - Summarize what was completed in this session
+   - Suggest running `/req-status <name>` to verify
+
+## Best Practices
+
+- Always verify current state before continuing
+- Don't assume previous implementation was complete
+- Check for code quality issues in existing implementation
+- Maintain consistency with existing code
+- Update the requirements document with any new insights
+- If previous implementation has issues, fix them before continuing
--- a/commands/implement.md
+++ b/commands/implement.md
@@ -0,0 +1,89 @@
+# Implement a requirement
+
+Implement a feature based on its requirements document.
+
+# Instructions
+
+When the user runs `/implement <name>`:
+
+1. **Validate requirement exists**
+   - Check if `.requirements/<name>.md` exists
+   - If not found, list available requirements and ask user to choose or run `/brainstorm` first
+
+2. **Read and analyze the requirement**
+   - Load `.requirements/<name>.md`
+   - Parse all sections: overview, functional requirements, technical requirements, edge cases, acceptance criteria
+   - Understand the full scope before starting
+
+3. **Update status to in-progress**
+   - Update `.requirements/_index.json`:
+     ```json
+     {
+       "<name>": {
+         "status": "in-progress",
+         "lastWorked": "2025-01-17T11:00:00Z",
+         "lastModified": "2025-01-17T11:00:00Z"
+       }
+     }
+     ```
+
+4. **Create implementation plan**
+   Present a clear plan to the user:
+   - Break down into logical steps
+   - Identify files that need to be created/modified
+   - Highlight any dependencies or prerequisites
+   - Estimate complexity
+
+   Ask user: "Does this plan look good? Should I proceed?"
+
+5. **Execute implementation systematically**
+
+   a. **Setup phase**
+      - Create necessary directories
+      - Set up any configuration files
+      - Install dependencies if needed
+
+   b. **Core implementation**
+      - Follow the plan step by step
+      - Implement according to technical requirements
+      - Handle edge cases mentioned in requirements
+      - Add proper error handling
+      - Include logging where appropriate
+
+   c. **Testing**
+      - Write unit tests for core functionality
+      - Write integration tests if applicable
+      - Test edge cases from requirements
+      - Verify acceptance criteria
+
+   d. **Documentation**
+      - Add code comments for complex logic
+      - Update README if needed
+      - Document API endpoints or interfaces
+
+6. **Track progress in requirements file**
+   - Check off items in the Implementation Checklist
+   - Mark completed acceptance criteria
+   - Add notes about implementation decisions
+
+7. **Report completion**
+   - Summarize what was implemented
+   - Show which acceptance criteria were met
+   - Highlight any deviations from original requirements
+   - Suggest running `/req-status <name>` to verify
+   - Update status in `_index.json` to "done" if fully complete
+
+8. **Handle interruptions gracefully**
+   - If implementation is interrupted, save state clearly
+   - Update `_index.json` with current progress
+   - User can resume with `/continue <name>`
+
+## Best Practices
+
+- Always confirm the plan before executing
+- Implement incrementally, not all at once
+- Test as you go, don't wait until the end
+- Keep the user informed of progress
+- If requirements are unclear, ask for clarification before implementing
+- Follow existing code patterns and project conventions
+- Prioritize code quality and maintainability
--- a/commands/req-list.md
+++ b/commands/req-list.md
@@ -0,0 +1,62 @@
+# List all requirements
+
+Show all requirements with their status and metadata.
+
+# Instructions
+
+When the user runs `/req-list`:
+
+1. **Check if requirements directory exists**
+   - Look for `.requirements/` directory
+   - If not found, show message: "No requirements found. Run `/brainstorm <name>` to create your first requirement."
+
+2. **Read all requirement files**
+   - List all `.md` files in `.requirements/` directory (excluding `_index.json`)
+   - Load metadata from `.requirements/_index.json`
+
+3. **Display requirements in a table format**
+
+   ```
+   Requirements
+
+   Name                    Status        Created      Last Modified
+   ────────────────────────────────────────────────────────────────
+   user-authentication     in-progress   2025-01-15   2025-01-17
+   payment-flow           done          2025-01-14   2025-01-16
+   admin-dashboard        draft         2025-01-17   2025-01-17
+   api-rate-limiting      in-progress   2025-01-16   2025-01-17
+   ```
+
+4. **Add summary statistics**
+   ```
+   Total: 4 requirements
+   ✅ Done: 1
+   ⏳ In Progress: 2
+   📝 Draft: 1
+   ```
+
+5. **Provide helpful next actions**
+   - If there are draft requirements: "Run `/implement <name>` to start implementation"
+   - If there are in-progress: "Run `/continue <name>` to resume work"
+   - If there are done requirements: "Run `/req-status <name>` to verify completion"
+
+6. **Handle empty or missing metadata**
+   - If `_index.json` doesn't exist, create it with default values for discovered requirements
+   - If a requirement file exists but not in index, add it with default metadata
+
+## Display Options
+
+**Sort by:**
+- Default: Last modified (most recent first)
+- Can be enhanced to allow sorting by name, status, or created date
+
+**Filter by status** (optional enhancement):
+- Show only requirements with specific status
+- Example: `/req-list --status in-progress`
+
+## Best Practices
+
+- Keep display clean and easy to scan
+- Use emojis sparingly for status indicators
+- Show most recently modified first by default
+- Make it easy to identify what to work on next
--- a/commands/req-status.md
+++ b/commands/req-status.md
@@ -0,0 +1,126 @@
+# Show requirement implementation status
+
+Compare requirements with actual implementation to show progress and gaps.
+
+# Instructions
+
+When the user runs `/req-status [name]`:
+
+1. **Determine which requirement(s) to check**
+
+   a. **If name provided**: `/req-status user-authentication`
+      - Check that specific requirement
+
+   b. **If no name provided**: `/req-status`
+      - Show status for all requirements
+      - Focus on in-progress and recent ones
+
+2. **Load requirement and analyze**
+   - Read `.requirements/<name>.md`
+   - Extract all requirements, acceptance criteria, and checklist items
+
+3. **Analyze codebase implementation**
+   - Use available tools to examine relevant files
+   - Search for related code
+   - Check tests
+   - Verify functionality exists
+
+4. **Compare requirements vs reality**
+
+   For each requirement, determine:
+   - ✅ **Fully Implemented** - Code exists, tests pass, acceptance criteria met
+   - ⚠️ **Partially Implemented** - Started but incomplete
+   - ❌ **Not Started** - No code found
+   - ❓ **Cannot Verify** - Need manual verification
+
+5. **Generate detailed status report**
+
+   **For single requirement:**
+   ```
+   Status: user-authentication
+
+   Overall Progress: 75% (6/8 items complete)
+
+   Functional Requirements:
+   ✅ User can register with email/password
+   ✅ User can login with credentials
+   ⚠️ Password reset flow (partially done - email not implemented)
+   ❌ OAuth integration not started
+
+   Acceptance Criteria:
+   ✅ Passwords are hashed
+   ✅ JWT tokens are generated
+   ⚠️ Password strength validation (basic only, missing special chars)
+   ❌ Rate limiting not implemented
+
+   Tests:
+   ✅ Unit tests: 12/12 passing
+   ⚠️ Integration tests: 3/5 passing
+   ❌ E2E tests: Not written
+
+   Issues Found:
+   - Password reset emails not configured
+   - Rate limiting mentioned in requirements but missing
+   - Integration tests failing for OAuth flows
+   ```
+
+   **For all requirements:**
+   ```
+   Requirements Status Overview
+
+   Name                    Progress  Status
+   ────────────────────────────────────────────
+   user-authentication     75%       in-progress
+   payment-flow           100%       done ✅
+   admin-dashboard        30%       in-progress
+   api-rate-limiting      0%        draft
+
+   Summary:
+   - 1 complete
+   - 2 in progress (average 52.5% done)
+   - 1 not started
+   ```
+
+6. **Identify gaps and issues**
+   - Requirements with no implementation
+   - Partial implementations
+   - Missing tests
+   - Acceptance criteria not met
+   - Code that exists but wasn't in requirements (scope creep)
+
+7. **Provide actionable recommendations**
+   ```
+   Recommendations:
+
+   High Priority:
+   - Complete password reset email integration
+   - Implement rate limiting (security requirement)
+   - Fix failing integration tests
+
+   Medium Priority:
+   - Enhance password validation
+   - Add E2E tests
+
+   Low Priority:
+   - Start OAuth integration planning
+   ```
+
+8. **Update metadata if status changed**
+   - If implementation is now complete, update status to "done"
+   - Update `lastModified` timestamp
+
+9. **Suggest next actions**
+   - If incomplete: "Run `/continue <name>` to finish implementation"
+   - If gaps found: "Run `/req-update <name>` to adjust requirements"
+   - If complete: "Requirement fully implemented!"
+
+## Best Practices
+
+- Be thorough but don't overwhelm with too much detail
+- Highlight critical gaps (security, core functionality)
+- Show progress visually (percentages, checkmarks)
+- Make it easy to see what needs attention
+- Don't just check if files exist - verify functionality
+- Consider test coverage as part of "done"
+- Flag discrepancies between requirements and implementation
+- Provide clear next steps
--- a/commands/req-tests.md
+++ b/commands/req-tests.md
@@ -0,0 +1,153 @@
+# Generate test plan from requirements
+
+Create comprehensive test scenarios based on a requirement document.
+
+# Instructions
+
+When the user runs `/req-tests <name>`:
+
+1. **Validate requirement exists**
+   - Check if `.requirements/<name>.md` exists
+   - If not found, list available requirements
+
+2. **Read and analyze the requirement**
+   - Load `.requirements/<name>.md`
+   - Extract:
+     - Functional requirements
+     - Edge cases and constraints
+     - Acceptance criteria
+     - User stories
+
+3. **Generate comprehensive test scenarios**
+
+   Create tests covering:
+
+   **a. Unit Tests**
+   - Test each functional requirement individually
+   - Test edge cases mentioned in requirements
+   - Test error conditions
+   - Test validation logic
+
+   **b. Integration Tests**
+   - Test interactions between components
+   - Test external integrations (APIs, databases, etc.)
+   - Test data flow through the system
+
+   **c. End-to-End Tests**
+   - Test complete user flows from user stories
+   - Test acceptance criteria scenarios
+   - Test real-world usage patterns
+
+   **d. Edge Case Tests**
+   - Test all edge cases mentioned in requirements
+   - Test boundary conditions
+   - Test error handling
+   - Test performance under constraints
+
+4. **Structure test scenarios**
+
+   Format:
+   ```markdown
+   ## Test Scenarios
+
+   ### Unit Tests
+
+   #### Test: [Function/Component Name]
+   - **Given:** [Initial state/conditions]
+   - **When:** [Action taken]
+   - **Then:** [Expected outcome]
+   - **Test Type:** Unit
+   - **Priority:** High/Medium/Low
+
+   ### Integration Tests
+
+   #### Test: [Integration Point]
+   - **Given:** [Setup]
+   - **When:** [Integration action]
+   - **Then:** [Expected result]
+   - **Test Type:** Integration
+   - **Priority:** High/Medium/Low
+
+   ### End-to-End Tests
+
+   #### Test: [User Flow]
+   - **Scenario:** [User story or flow]
+   - **Steps:**
+     1. [Step 1]
+     2. [Step 2]
+     3. [Step 3]
+   - **Expected:** [Final outcome]
+   - **Test Type:** E2E
+   - **Priority:** High/Medium/Low
+
+   ### Edge Case Tests
+
+   #### Test: [Edge Case Description]
+   - **Given:** [Edge case setup]
+   - **When:** [Edge case trigger]
+   - **Then:** [Expected handling]
+   - **Test Type:** Edge Case
+   - **Priority:** High/Medium/Low
+   ```
+
+5. **Ask for preference on storage**
+   ```
+   Where should I save these test scenarios?
+
+   1. Append to requirements file (.requirements/<name>.md)
+   2. Create separate test file (.requirements/<name>-tests.md)
+   3. Show only (don't save)
+   ```
+
+6. **Save test scenarios**
+   Based on user choice:
+   - If appending: Add "## Test Scenarios" section to requirement file
+   - If separate: Create new test file
+   - If show only: Display but don't persist
+
+7. **Generate test code templates** (optional)
+   Ask: "Would you like me to generate test code templates?"
+
+   If yes, create example test code in the project's test framework:
+   ```javascript
+   // Example for Jest
+   describe('User Authentication', () => {
+     test('should allow login with valid credentials', () => {
+       // Given: Valid user credentials
+       const credentials = { email: 'user@example.com', password: 'password123' };
+
+       // When: User attempts to login
+       const result = login(credentials);
+
+       // Then: Login succeeds
+       expect(result.success).toBe(true);
+       expect(result.token).toBeDefined();
+     });
+   });
+   ```
+
+8. **Update requirement metadata**
+   - Add note that test scenarios were generated
+   - Update `lastModified` in `_index.json`
+
+9. **Provide summary**
+   ```
+   Generated test scenarios:
+   - 5 Unit Tests
+   - 3 Integration Tests
+   - 2 End-to-End Tests
+   - 4 Edge Case Tests
+
+   Total: 14 test scenarios covering all requirements
+   ```
+
+## Best Practices
+
+- Cover all functional requirements with tests
+- Don't forget negative test cases (what should fail)
+- Prioritize tests based on critical functionality
+- Make tests specific and actionable
+- Include setup/teardown considerations
+- Consider performance testing for performance requirements
+- Include security testing for security requirements
+- Map tests back to acceptance criteria
--- a/commands/req-update.md
+++ b/commands/req-update.md
@@ -0,0 +1,93 @@
+# Update a requirement
+
+Modify an existing requirement document.
+
+# Instructions
+
+When the user runs `/req-update <name>`:
+
+1. **Validate requirement exists**
+   - Check if `.requirements/<name>.md` exists
+   - If not found, list available requirements or suggest creating one with `/brainstorm`
+
+2. **Load current requirement**
+   - Read `.requirements/<name>.md`
+   - Show summary of current content
+
+3. **Ask what to update**
+   Present options:
+   ```
+   What would you like to update?
+
+   1. Overview / Goals
+   2. User Stories
+   3. Functional Requirements
+   4. Technical Requirements
+   5. Edge Cases & Constraints
+   6. Acceptance Criteria
+   7. Free-form edit (tell me what to change)
+   ```
+
+4. **Handle the update based on choice**
+
+   **For specific sections (1-6):**
+   - Show current content of that section
+   - Ask: "What changes would you like to make?"
+   - Accept additions, modifications, or deletions
+   - Update that section while preserving the rest
+
+   **For free-form edit (7):**
+   - Ask: "Describe the changes you want to make"
+   - Parse user's intent
+   - Apply changes to appropriate sections
+   - Show what changed
+
+5. **Preview changes**
+   Show diff or summary:
+   ```
+   Changes to be made:
+
+   + Added to Functional Requirements:
+     - Support OAuth 2.0 authentication
+
+   ~ Modified in Technical Requirements:
+     - JWT tokens → OAuth 2.0 tokens
+
+   - Removed from Edge Cases:
+     - Password reset via email (no longer needed)
+   ```
+
+6. **Confirm before saving**
+   Ask: "Should I save these changes?"
+
+7. **Save updates**
+   - Write updated content to `.requirements/<name>.md`
+   - Update metadata in `.requirements/_index.json`:
+     ```json
+     {
+       "<name>": {
+         "lastModified": "2025-01-17T12:00:00Z",
+         "version": 2
+       }
+     }
+     ```
+   - Add changelog entry at bottom of requirement file:
+     ```markdown
+     ## Changelog
+     - **2025-01-17**: Updated authentication approach to OAuth 2.0
+     - **2025-01-15**: Initial version
+     ```
+
+8. **Suggest next steps**
+   - If status is "done": "Requirements changed. Consider running `/req-status <name>` to check if implementation still matches."
+   - If status is "in-progress": "Updated requirements. You may want to adjust your implementation."
+   - If status is "draft": "Requirements updated. Ready to run `/implement <name>`?"
+
+## Best Practices
+
+- Always show what will change before saving
+- Preserve existing content unless explicitly asked to remove it
+- Maintain document structure and formatting
+- Keep changelog for traceability
+- If changes affect completed work, warn the user
+- Be careful not to lose information during updates