plan-flow-skill 1.0.0

package/.claude/rules/tools/interactive-questions-tool.md

@@ -0,0 +1,235 @@
+# Interactive Questions Tool for Claude Code
+
+## Purpose
+
+Provides a standardized way to ask interactive questions using Claude Code's native `AskUserQuestion` tool. This tool presents structured questions with multiple-choice options to gather requirements and confirm decisions.
+
+## Usage
+
+This tool is used by:
+- Discovery commands that need to gather requirements from users
+- Skills that require user input before proceeding
+- Any process that needs interactive question-answer sessions
+
+---
+
+## How to Use Interactive Questions in Claude Code
+
+Claude Code has a native `AskUserQuestion` tool that presents structured questions to users. Use this for gathering requirements and confirming patterns.
+
+### Using the AskUserQuestion Tool
+
+When you need to ask the user questions, use the `AskUserQuestion` tool with structured options:
+
+```typescript
+// Example: Ask about feature requirements
+AskUserQuestion({
+  questions: [{
+    question: "What is the primary user action for this feature?",
+    header: "Action",
+    options: [
+      { label: "Create new items", description: "Users will create new data entries" },
+      { label: "View existing items", description: "Users will browse and view data" },
+      { label: "Edit existing items", description: "Users will modify existing data" },
+      { label: "Delete items", description: "Users will remove data entries" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+### Question Format
+
+Each question object has these properties:
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `question` | Yes | The complete question text |
+| `header` | Yes | Short label (max 12 chars) for the question |
+| `options` | Yes | Array of 2-4 choices |
+| `multiSelect` | No | Set to `true` to allow multiple selections |
+
+### Option Format
+
+Each option in the options array has:
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `label` | Yes | Short display text (1-5 words) |
+| `description` | Yes | Explanation of what this option means |
+
+---
+
+## Workflow for Gathering Requirements
+
+### Step 1: Present Context First
+
+Before asking questions, summarize what you've learned:
+
+```markdown
+## Analysis Summary
+
+I've analyzed the codebase and found:
+
+**Stack**: TypeScript + Next.js
+**Key Libraries**: Zod, Prisma, Zustand
+**Architecture**: Feature-based organization
+
+Now I'll ask a few questions to confirm these patterns.
+```
+
+### Step 2: Ask Questions
+
+Use the `AskUserQuestion` tool to present questions. You can ask up to 4 questions at once.
+
+**Example for Stack Confirmation**:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "I detected the following stack. Is this accurate?",
+    header: "Stack",
+    options: [
+      { label: "Yes, correct", description: "The detected stack matches our project" },
+      { label: "Partially correct", description: "Some details need adjustment" },
+      { label: "No, different", description: "Let me describe our actual stack" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**Example for Pattern Enforcement**:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Which coding patterns should I enforce when generating code?",
+    header: "Patterns",
+    options: [
+      { label: "All detected (Recommended)", description: "Enforce all patterns I found in the codebase" },
+      { label: "Let me review", description: "Show me the patterns first and I'll select which to keep" },
+      { label: "Describe preferred", description: "These are legacy patterns, I'll describe new ones" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**Example for Strictness Level**:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "How strictly should patterns be enforced?",
+    header: "Strictness",
+    options: [
+      { label: "Strict", description: "Always follow patterns exactly, no exceptions" },
+      { label: "Moderate (Recommended)", description: "Follow patterns but allow justified exceptions" },
+      { label: "Loose", description: "Use as guidelines, not strict requirements" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+### Step 3: Wait for Responses
+
+After calling `AskUserQuestion`, wait for the user to respond before proceeding. The tool will return the selected option(s).
+
+### Step 4: Process Responses
+
+Use the selected answers to inform your next actions:
+
+1. Extract the selected options from the response
+2. Map them to corresponding actions
+3. Document the confirmed decisions
+4. Proceed with the workflow based on user choices
+
+---
+
+## When to Use Interactive Questions
+
+### Use For:
+
+1. **Discovery Phase**: Gathering requirements and clarifying unknowns
+2. **Planning Phase**: Understanding scope, priorities, and constraints
+3. **Critical Decisions**: When user input is required before proceeding
+4. **Pattern Confirmation**: Confirming detected patterns during setup
+5. **Complex Choices**: When options need to be clearly presented
+
+### Don't Use For:
+
+1. **Simple Yes/No Questions**: Just ask in regular conversation
+2. **Single Simple Questions**: Regular conversation is faster
+3. **Information Already Available**: Don't ask if you can find the answer
+4. **Read-Only Operations**: No questions needed for reading/searching
+
+---
+
+## Question Guidelines
+
+### Good Questions
+
+```typescript
+// Clear, specific, with context
+AskUserQuestion({
+  questions: [{
+    question: "Where should the new button be placed in the navigation?",
+    header: "Placement",
+    options: [
+      { label: "Before Library", description: "Insert before the Library menu item" },
+      { label: "After Library", description: "Insert after the Library menu item" },
+      { label: "Separate toolbar", description: "Create a new toolbar for this action" },
+      { label: "Dropdown menu", description: "Add as an option in an existing dropdown" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+### Avoid
+
+- Questions that are too vague ("What do you want?")
+- Too many options (stick to 2-4)
+- Options without clear descriptions
+- Asking about things you can determine from code
+
+---
+
+## Multiple Questions at Once
+
+You can ask up to 4 related questions in a single call:
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Is the detected tech stack correct?",
+      header: "Stack",
+      options: [
+        { label: "Yes, correct", description: "All detected technologies are accurate" },
+        { label: "Needs adjustment", description: "Some corrections needed" }
+      ],
+      multiSelect: false
+    },
+    {
+      question: "Which patterns should be enforced?",
+      header: "Patterns",
+      options: [
+        { label: "All detected", description: "Enforce all patterns found" },
+        { label: "Review first", description: "Let me review before deciding" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+---
+
+## Related Rules
+
+- Discovery patterns: `.claude/rules/patterns/discovery-patterns.md`
+- Plan patterns: `.claude/rules/patterns/plans-patterns.md`
+- Setup skill: `.claude/skills/setup/SKILL.md`

package/.claude/rules/tools/jest-testing-tool.md

@@ -0,0 +1,73 @@
+
+## Running Tests
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests in watch mode
+npm run test -- --watch
+
+# Run specific test file
+npm run test -- src/commands/streamChatCommand.server.test.ts
+
+# Run tests matching pattern
+npm run test -- --testNamePattern="chat validation"
+
+# Run with coverage
+npm run test -- --coverage
+
+# Run only changed files
+npm run test -- --onlyChanged
+
+# Run with verbose output
+npm run test -- --verbose
+```
+
+---
+
+## Coverage Commands
+
+```bash
+# Generate coverage report
+npm run test -- --coverage
+
+# Generate HTML coverage report
+npm run test -- --coverage --coverageReporters="html"
+
+# Check coverage thresholds
+npm run test -- --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
+
+# Coverage for specific files
+npm run test -- --coverage --collectCoverageFrom="src/commands/**/*.ts"
+```
+
+---
+
+## Debugging Tests
+
+```bash
+# Run with Node debugger
+node --inspect-brk node_modules/.bin/jest --runInBand
+
+# Run single test for debugging
+npm run test -- --runInBand --testNamePattern="specific test name"
+
+# Show why tests are slow
+npm run test -- --detectOpenHandles
+```
+
+---
+
+## CI/CD Commands
+
+```bash
+# Run in CI mode (no watch, fail on console errors)
+npm run test -- --ci
+
+# Run with JUnit reporter for CI
+npm run test -- --ci --reporters=default --reporters=jest-junit
+
+# Run with max workers for parallel execution
+npm run test -- --maxWorkers=4
+```

package/.claude/rules/tools/plan-mode-tool.md

@@ -0,0 +1,164 @@
+# Plan Mode for Claude Code
+
+## Purpose
+
+Claude Code has a native plan mode that enables collaborative planning before implementation. This tool provides guidance on using plan mode effectively for structured development workflows.
+
+## When to Use Plan Mode
+
+### Use the `EnterPlanMode` Tool For:
+
+1. **Implementation Tasks**: Before implementing features that require architectural decisions
+2. **High Complexity Tasks**: Before tasks with complexity score >= 7
+3. **Multi-File Changes**: When changes will affect multiple files
+4. **New Features**: When adding new functionality that requires planning
+5. **Critical Decisions**: Before making architectural or design decisions
+
+### Don't Use Plan Mode For:
+
+1. **Simple Fixes**: Single-line changes, typos, obvious bugs
+2. **Read-Only Operations**: Reading files, searching codebase
+3. **Information Gathering**: Discovery, analysis, documentation
+4. **Trivial Tasks**: Tasks with complexity <= 2
+
+---
+
+## How to Use Plan Mode in Claude Code
+
+### Entering Plan Mode
+
+Use the `EnterPlanMode` tool when you need to plan before implementing:
+
+```typescript
+// When starting a non-trivial implementation task
+EnterPlanMode()
+```
+
+Claude Code will then allow you to:
+1. Explore the codebase using Glob, Grep, and Read tools
+2. Design an implementation approach
+3. Present your plan to the user for approval
+4. Exit plan mode with `ExitPlanMode` when ready to implement
+
+### Plan Mode Workflow
+
+1. **Enter Plan Mode**: Call `EnterPlanMode` for implementation tasks
+2. **Explore**: Use read-only tools to understand the codebase
+3. **Design**: Create a structured implementation plan
+4. **Present**: Show the plan to the user
+5. **Clarify**: Use `AskUserQuestion` if you need decisions
+6. **Exit**: Call `ExitPlanMode` when the plan is ready for implementation
+
+---
+
+## Phase Execution Pattern
+
+When executing implementation plan phases, follow this pattern:
+
+### Step 1: Present Phase Details
+
+Before implementing each phase, present the details:
+
+```markdown
+## Implementing Phase X: [Phase Name]
+
+**Complexity**: X/10
+**Scope**: [Phase scope description]
+
+### Tasks to Complete:
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+### Implementation Approach:
+[Describe the approach, patterns to follow, and any decisions needed]
+
+### Patterns to Follow:
+- [Pattern 1 from project rules]
+- [Pattern 2 from project rules]
+
+**Proceeding with implementation...**
+```
+
+### Step 2: Implement
+
+Proceed with implementation following the discussed approach.
+
+### Step 3: Update Progress
+
+Mark completed tasks in the plan file after completing the phase.
+
+---
+
+## Integration with Execute Plan Command
+
+When executing a plan created by `/create-plan`:
+
+1. **Read the plan file** to understand phases and complexity scores
+2. **For each phase**:
+   - Present phase details and approach
+   - Implement the phase following project patterns
+   - Update the plan file to mark tasks complete
+3. **Run verification** only at the very end (not between phases)
+
+---
+
+## Complexity-Based Execution Strategy
+
+Based on complexity scores from the plan:
+
+| Combined Score | Strategy |
+|---------------|----------|
+| <= 6 | **Aggregate**: Execute multiple phases together |
+| 7-10 | **Cautious**: Execute 1-2 phases, then verify |
+| > 10 | **Sequential**: Execute one phase at a time |
+
+---
+
+## Presenting Plans for Approval
+
+When presenting a plan for user approval:
+
+```markdown
+## Implementation Plan: [Feature Name]
+
+### Phase Overview
+
+| Phase | Name | Complexity | Description |
+|-------|------|------------|-------------|
+| 1 | Types and Schemas | 3/10 | Define TypeScript types and Zod schemas |
+| 2 | API Implementation | 6/10 | Create API routes with validation |
+| 3 | UI Components | 5/10 | Build React components |
+| 4 | Tests | 4/10 | Write comprehensive tests |
+
+### Execution Strategy
+
+Phases 1-2 will be executed together (combined complexity: 9)
+Phase 3 will be executed separately
+Phase 4 (Tests) always executed separately
+
+### Key Decisions
+
+1. [Decision 1 and reasoning]
+2. [Decision 2 and reasoning]
+
+**Ready to proceed?**
+```
+
+---
+
+## Benefits of Plan Mode
+
+1. **Collaborative Design**: Discuss approach before implementation
+2. **Risk Mitigation**: Catch issues early in planning
+3. **User Control**: Approve approach before changes are made
+4. **Better Decisions**: Time to consider alternatives and trade-offs
+5. **Documentation**: Planning discussions serve as decision records
+
+---
+
+## Related Rules
+
+- Plan patterns: `.claude/rules/patterns/plans-patterns.md`
+- Complexity scoring: `.claude/rules/core/complexity-scoring.md`
+- Execute plan skill: `.claude/skills/execute-plan/SKILL.md`

package/.claude/rules/tools/pytest-testing-tool.md

@@ -0,0 +1,121 @@
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with verbose output
+pytest -v
+
+# Run specific test file
+pytest tests/test_service.py
+
+# Run specific test class
+pytest tests/test_service.py::TestUserService
+
+# Run specific test
+pytest tests/test_service.py::TestUserService::test_get_user_returns_user
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+
+# Run only marked tests
+pytest -m "integration"
+
+# Run with parallel execution
+pytest -n auto
+
+# Stop on first failure
+pytest -x
+```
+
+---
+
+## Coverage Commands
+
+```bash
+# Generate coverage report
+pytest --cov=src
+
+# Generate HTML coverage report
+pytest --cov=src --cov-report=html
+
+# Generate XML coverage report (for CI)
+pytest --cov=src --cov-report=xml
+
+# Check coverage thresholds
+pytest --cov=src --cov-fail-under=80
+
+# Coverage for specific modules
+pytest --cov=src/mymodule --cov-report=term-missing
+```
+
+---
+
+## Debugging Tests
+
+```bash
+# Drop into debugger on failure
+pytest --pdb
+
+# Drop into debugger at start of each test
+pytest --pdb-first
+
+# Show local variables in tracebacks
+pytest -l
+
+# Verbose output with full diff
+pytest -vv
+
+# Show print statements
+pytest -s
+
+# Capture no output (show all print statements)
+pytest --capture=no
+```
+
+---
+
+## CI/CD Commands
+
+```bash
+# Run with JUnit XML output for CI
+pytest --junitxml=results.xml
+
+# Run with coverage and XML output
+pytest --cov=src --cov-report=xml --junitxml=results.xml
+
+# Fail if coverage drops below threshold
+pytest --cov=src --cov-fail-under=80
+
+# Run in parallel (requires pytest-xdist)
+pytest -n auto
+
+# Rerun only failed tests
+pytest --lf
+
+# Rerun failed tests first, then rest
+pytest --ff
+```
+
+---
+
+## Test Selection
+
+```bash
+# Run tests matching a keyword expression
+pytest -k "user and not integration"
+
+# Run tests matching a marker
+pytest -m "slow"
+
+# Run tests in a specific directory
+pytest tests/unit/
+
+# Run tests that failed in the last run
+pytest --lf
+
+# Run tests in random order (requires pytest-random-order)
+pytest --random-order
+```