plan-flow-skill 1.0.0

package/rules/skills/discovery-skill.mdc

@@ -0,0 +1,295 @@
+---
+description: "Include when /discovery-plan is invoked or requirements gathering before implementation is needed"
+alwaysApply: false
+---
+
+# Discovery Skill
+
+## Purpose
+
+Perform a comprehensive **requirements gathering and documentation** process that reads referenced documents, asks clarifying questions, and produces a structured discovery document.
+
+This skill **only produces a markdown file** in `flow/discovery/`. It does NOT:
+
+- Write any code
+- Modify any source files
+- Create implementation plans
+- Execute any implementation
+
+---
+
+## Restrictions - DISCOVERY ONLY
+
+This skill is **strictly for gathering and documenting requirements**. The process:
+
+1. **Reads** all referenced documents and contracts
+2. **Asks** clarifying questions via Interactive Questions Tool
+3. **Documents** requirements (FR, NFR, Constraints)
+4. **Identifies** technical considerations (high-level only)
+5. **Proposes** approach (conceptual, no code)
+6. **Generates** a discovery markdown file
+
+**No code, no implementation, no source file modifications.**
+
+### NEVER Do These Actions
+
+| Forbidden Action                       | Reason                                    |
+| -------------------------------------- | ----------------------------------------- |
+| Create/edit source code files          | Discovery is requirements gathering only  |
+| Write implementation code in responses | No code during discovery                  |
+| Create implementation plans            | Plans come after discovery                |
+| Modify configuration files             | No codebase changes                       |
+| Run build or test commands             | No execution commands                     |
+| Create files outside `flow/discovery/` | Only write discovery documents            |
+
+### Allowed Actions
+
+| Allowed Action                         | Purpose                              |
+| -------------------------------------- | ------------------------------------ |
+| Read any project file                  | Understand existing implementation   |
+| Read referenced documents              | Extract requirements and constraints |
+| Search codebase (grep, glob, semantic) | Find existing patterns               |
+| Use Interactive Questions Tool         | Gather requirements from user        |
+| Write to `flow/discovery/`             | Save discovery document              |
+| Read project rule files                | Understand patterns to follow        |
+
+> **Important**: The ONLY writable location is `flow/discovery/`. No source code, configuration files, or any other project files should be modified.
+
+---
+
+## Inputs
+
+| Input                | Required | Description                                           |
+| -------------------- | -------- | ----------------------------------------------------- |
+| `feature_name`       | Yes      | Name of the feature or topic to explore               |
+| `context`            | Optional | Why this discovery is needed                          |
+| `referenced_docs`    | Optional | List of documents to review (@mentions, file paths)   |
+| `known_requirements` | Optional | Any requirements already known                        |
+
+---
+
+## Workflow
+
+### Step 1: Read All Referenced Documents
+
+**BEFORE asking detailed questions**, read every referenced document.
+
+**Actions**:
+
+1. Identify references (look for @mentions, file paths, URLs)
+2. Read each file using the Read tool
+3. Extract key information (requirements, constraints, contracts)
+4. Summarize findings for each source
+
+**Document Analysis Format**:
+
+```markdown
+## Referenced Documents Analysis
+
+### `flow/contracts/api-contract.md`
+
+**Key Findings**:
+- [Key point 1]
+- [Key point 2]
+
+**Questions Raised**:
+- [Gap or unclear aspect]
+```
+
+**Important**: NEVER read or reference files in `flow/archive/` - these are outdated documents.
+
+---
+
+### Step 2: Ask Clarifying Questions
+
+Ask questions about gaps identified in documents and unclear requirements.
+
+**Question Categories**:
+
+| Category   | Focus                              |
+| ---------- | ---------------------------------- |
+| Functional | What the feature must do           |
+| NFR        | Performance, security, scalability |
+| Technical  | Architecture, dependencies         |
+| UI/UX      | User interface and experience      |
+
+**Use Interactive Questions Tool**:
+
+Follow `.cursor/rules/tools/interactive-questions-tool.mdc`:
+
+1. Call `SwitchMode` tool to enter Plan mode
+2. Call `AskQuestion` tool for each question (2-6 options, A/B/C/D format)
+3. Wait for responses
+4. Call `SwitchMode` tool to return to Agent mode
+
+**Skip Interactive Questions If**:
+
+- All questions answered in chat already
+- User confirmed all assumptions
+- No blocked or open questions remain
+
+---
+
+### Step 3: Track Question Status
+
+Maintain a question tracking table:
+
+```markdown
+## Open Questions
+
+| #   | Category   | Question                   | Status   | Answer            |
+| --- | ---------- | -------------------------- | -------- | ----------------- |
+| 1   | Functional | Max steps per workflow?    | Answered | 20 steps maximum  |
+| 2   | Technical  | Use existing store or new? | Open     | -                 |
+| 3   | NFR        | Required response time?    | Assumed  | <500ms (validate) |
+```
+
+**Status Legend**:
+
+- **Open**: Awaiting answer
+- **Answered**: Response received
+- **Assumed**: Made assumption (needs validation)
+- **Blocked**: Cannot proceed without answer
+
+---
+
+### Step 4: Document Requirements
+
+Categorize requirements as they are gathered:
+
+```markdown
+## Requirements Gathered
+
+### Functional Requirements
+- [FR-1]: [Description] (Source: [document or user])
+
+### Non-Functional Requirements
+- [NFR-1]: [Description]
+
+### Constraints
+- [C-1]: [Description]
+```
+
+---
+
+### Step 5: Identify Technical Considerations
+
+Document high-level technical insights (NO implementation code):
+
+```markdown
+## Technical Considerations
+
+### Architecture Fit
+- [How this fits into existing system]
+
+### Dependencies
+- [What this relies on]
+
+### Patterns to Apply
+- [Relevant patterns from cursor rules]
+
+### Challenges Identified
+- [Potential difficulties]
+```
+
+---
+
+### Step 6: Propose High-Level Approach
+
+Suggest an approach based on findings (NO implementation code):
+
+```markdown
+## Proposed Approach
+
+Based on the requirements gathered, I recommend:
+
+1. [High-level approach point 1]
+2. [High-level approach point 2]
+
+### Alternative Approaches Considered
+
+| Approach | Pros | Cons | Recommendation |
+| -------- | ---- | ---- | -------------- |
+| [A]      | ...  | ...  | Yes/No         |
+```
+
+---
+
+### Step 7: Document Risks and Unknowns
+
+Capture risks discovered:
+
+```markdown
+## Risks and Unknowns
+
+### Risks
+
+| Risk | Impact | Likelihood | Mitigation |
+| ---- | ------ | ---------- | ---------- |
+| ...  | ...    | ...        | ...        |
+
+### Unknowns (Require Further Investigation)
+- [ ] [Unknown item]
+```
+
+---
+
+### Step 8: Generate Discovery Document
+
+Create the discovery markdown file:
+
+**Location**: `flow/discovery/discovery_<feature_name>_v<version>.md`
+
+**Use Template**: See `.cursor/rules/patterns/discovery-templates.mdc`
+
+**Required Sections**:
+
+1. Context
+2. Referenced Documents
+3. Requirements Gathered (FR, NFR, Constraints)
+4. Open Questions (all answered)
+5. Technical Considerations
+6. Proposed Approach
+7. Risks and Unknowns
+8. Next Steps
+
+---
+
+## Output Format
+
+The discovery document should follow the template in `.cursor/rules/patterns/discovery-templates.mdc`.
+
+**Naming Convention**: `discovery_<feature_name>_v<version>.md`
+
+**Examples**:
+- `discovery_workflow_editor_v1.md`
+- `discovery_user_authentication_v1.md`
+
+---
+
+## Validation Checklist
+
+Before completing discovery, verify:
+
+- [ ] All referenced documents have been read
+- [ ] Document is saved in `flow/discovery/` folder
+- [ ] File uses correct naming convention
+- [ ] Open questions table has no "Blocked" status
+- [ ] Requirements are categorized (FR, NFR, Constraints)
+- [ ] Technical considerations are documented
+- [ ] Risks and unknowns are identified
+- [ ] Proposed approach is documented (high-level only)
+- [ ] Next steps are defined (pointing to `/create-plan`)
+- [ ] **NO implementation code is included**
+- [ ] **NO source files were created or modified**
+
+---
+
+## Related Files
+
+| File                                              | Purpose                           |
+| ------------------------------------------------- | --------------------------------- |
+| `.cursor/rules/patterns/discovery-patterns.mdc`   | Rules and patterns for discovery  |
+| `.cursor/rules/patterns/discovery-templates.mdc`  | Document templates                |
+| `.cursor/rules/tools/interactive-questions-tool.mdc` | Interactive Questions UI workflow |
+| `flow/discovery/`                                 | Output folder for discovery docs  |

package/rules/skills/execute-plan-skill.mdc

@@ -0,0 +1,388 @@
+---
+description: "Include when /execute-plan is invoked or phase-by-phase plan execution is needed"
+alwaysApply: false
+---
+
+# Execute Plan Skill
+
+## Purpose
+
+Execute an implementation plan **phase by phase**, using complexity scores to determine execution strategy. Each phase triggers **Plan mode** for collaborative design before implementation.
+
+This skill **implements the plan** by:
+
+- Reading and parsing the plan file
+- Grouping phases by complexity
+- Switching to Plan mode for each phase
+- Implementing after user approval
+- Updating progress in the plan file
+
+---
+
+## CRITICAL RULE: Build Verification ONLY at the End
+
+**DO NOT run `npm run build` after each phase or group.**
+
+**`npm run build` and `npm run test` MUST ONLY be executed at the very end, after ALL phases (including Tests) are complete.**
+
+**Why**:
+
+- Running build after each phase wastes time and breaks flow
+- Intermediate phases may have temporary type errors that get resolved in later phases
+- The final build verification ensures everything works together
+
+**The ONLY time to run build/test**:
+
+- After ALL phases are complete → `npm run build && npm run test`
+
+---
+
+## CRITICAL RULE: No Direct Database or ORM Commands
+
+**NEVER execute any ORM or database commands directly. ALWAYS ask the user to run them manually.**
+
+### Forbidden Commands (NEVER execute directly)
+
+| Category        | Commands                                              |
+| --------------- | ----------------------------------------------------- |
+| **Prisma**      | `prisma migrate`, `prisma db push`, `prisma db seed`  |
+| **Django**      | `python manage.py migrate`, `python manage.py dbshell`|
+| **Alembic**     | `alembic upgrade`, `alembic downgrade`                |
+| **Sequelize**   | `sequelize db:migrate`, `sequelize db:seed`           |
+| **TypeORM**     | `typeorm migration:run`, `typeorm migration:revert`   |
+| **Drizzle**     | `drizzle-kit push`, `drizzle-kit drop`                |
+| **Raw SQL**     | Any direct SQL execution, psql, mysql, sqlite3        |
+| **Connections** | Any database connection or query commands             |
+
+### When Database Commands Are Needed
+
+**ALWAYS present the command to the user and wait for confirmation:**
+
+```markdown
+## Action Required: Database Migration
+
+The following command needs to be executed manually:
+
+\`\`\`bash
+[command here]
+\`\`\`
+
+**Why manual execution is required:**
+- Database operations can be destructive and irreversible
+- User should review the migration before applying
+- Prevents accidental data loss in development/production
+
+Please run this command and let me know when it's complete, or if you encounter any issues.
+```
+
+### Safe Commands (CAN be executed directly)
+
+| Command               | Why It's Safe                              |
+| --------------------- | ------------------------------------------ |
+| `prisma generate`     | Only generates client code, no DB changes  |
+| `prisma format`       | Only formats schema file                   |
+| `prisma validate`     | Only validates schema                      |
+| Reading schema files  | Read-only operation                        |
+
+### Why This Rule Exists
+
+1. **Data Safety**: Database migrations can delete or modify data
+2. **Reversibility**: Some operations cannot be undone
+3. **Environment Awareness**: User knows if this is dev/staging/prod
+4. **Verification**: User can review the migration before applying
+5. **Error Handling**: User can handle errors appropriately
+
+---
+
+## Inputs
+
+| Input       | Required | Description                          |
+| ----------- | -------- | ------------------------------------ |
+| `plan_file` | Yes      | Path to plan file in `flow/plans/`   |
+
+---
+
+## Workflow
+
+### Step 1: Parse the Plan
+
+1. Read the specified plan file
+2. Parse all phases with their complexity scores and tasks
+3. Validate that all phases have complexity scores
+
+**Important**: NEVER read or reference files in `flow/archive/` - these are outdated plans.
+
+---
+
+### Step 2: Analyze Complexity and Determine Execution Strategy
+
+Parse each phase and calculate execution groups based on complexity scores:
+
+**Execution Strategy Rules**:
+
+| Total Adjacent Score | Execution Strategy                                          |
+| -------------------- | ----------------------------------------------------------- |
+| ≤ 6                  | **Aggregate**: Execute multiple phases together in one pass |
+| 7-10                 | **Cautious**: Execute 1-2 phases, then continue             |
+| > 10                 | **Sequential**: Execute one phase at a time                 |
+
+**Aggregation Rules**:
+
+1. **Can aggregate** phases when their combined complexity ≤ 6
+2. **Never aggregate** across a phase with complexity ≥ 8
+3. **Always execute separately**: Tests phase (regardless of score)
+4. **Prefer aggregation** for trivial consecutive phases (0-2 each)
+
+**Example Analysis**:
+
+```
+Phase 1: Types and Schemas - Complexity: 3/10
+Phase 2: Utility Functions - Complexity: 2/10
+Phase 3: API Route - Complexity: 7/10
+Phase 4: UI Components - Complexity: 6/10
+Phase 5: Integration - Complexity: 4/10
+Phase 6: Tests - Complexity: 5/10
+
+Execution Groups:
+
+- Group 1: Phase 1 + Phase 2 (combined: 5) → Aggregate
+- Group 2: Phase 3 (7) → Execute alone
+- Group 3: Phase 4 + Phase 5 (combined: 10) → Execute together
+- Group 4: Phase 6 (Tests) → Always separate
+```
+
+---
+
+### Step 3: Present Execution Plan Summary
+
+Before starting, present the execution plan to the user:
+
+```markdown
+## Execution Plan Summary
+
+**Plan**: [Plan Name]
+**Total Phases**: X
+**Total Complexity**: XX/XX
+
+### Execution Groups:
+
+| Group | Phases           | Combined Complexity | Strategy   |
+| ----- | ---------------- | ------------------- | ---------- |
+| 1     | Phase 1, Phase 2 | 5/10                | Aggregate  |
+| 2     | Phase 3          | 7/10                | Sequential |
+| 3     | Phase 4, Phase 5 | 10/10               | Cautious   |
+| 4     | Phase 6 (Tests)  | 5/10                | Sequential |
+
+**Build Verification**: Only at the end, after ALL phases complete
+
+Ready to begin execution?
+```
+
+Wait for user confirmation before proceeding.
+
+---
+
+### Step 4: Execute Each Phase with Plan Mode
+
+**CRITICAL RULE**: Use the [Plan Mode Tool](../tools/plan-mode-tool.mdc) to switch to Plan mode for **EACH individual phase**.
+
+**REMINDER**: Do NOT run `npm run build` between phases.
+
+**For Each Phase**:
+
+1. **Auto-switch to Plan mode** - Call `SwitchMode` tool
+2. **Present phase details** - Show scope, tasks, and approach
+3. **Wait for approval** - Get user confirmation
+4. **Implement** - Execute the phase following approved approach
+5. **Update progress** - Mark tasks complete in plan file
+6. **Continue to next phase** - NO BUILD between phases
+
+**Phase Presentation Template**:
+
+```markdown
+## Phase Execution: Phase X - [Phase Name]
+
+**Complexity**: X/10
+**Scope**: [Phase scope description]
+
+### Tasks to Complete:
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+### Implementation Approach:
+[Discuss the approach, patterns to follow, and any decisions needed]
+
+### Cursor Rules Checklist:
+- [ ] Following allowed patterns
+- [ ] Avoiding forbidden patterns
+- [ ] Using appropriate language patterns
+
+---
+
+**Ready to implement this phase?**
+```
+
+---
+
+### Step 5: Update Progress After Each Phase
+
+Mark completed tasks in the plan file:
+
+```markdown
+- [x] Task 1
+- [x] Task 2
+```
+
+Then continue to the next phase (NO BUILD HERE).
+
+---
+
+### Step 6: Handle Tests Phase
+
+The Tests phase is **always executed separately**, regardless of complexity score:
+
+1. Switch to Plan mode
+2. Present the testing strategy
+3. Discuss test coverage and edge cases
+4. Get user approval
+5. Implement tests
+6. **DO NOT run tests yet** - Continue to Step 7
+
+---
+
+### Step 7: Completion - Build and Test Verification
+
+**This is the ONLY place where build and tests are run.**
+
+After ALL phases are complete (including Tests phase):
+
+1. **Run final verification**:
+
+```bash
+npm run build && npm run test
+```
+
+2. **Handle failures**:
+   - If build fails: Fix the issue, re-run verification
+   - If tests fail: Fix the issue, re-run verification
+   - Only proceed after everything passes
+
+3. **Present summary** of completed work
+
+4. **List all key changes** made
+
+5. **Ask if the plan should be archived**:
+
+```bash
+mv flow/plans/plan_feature_name_v1.md flow/archive/
+```
+
+---
+
+## Execution Flow Within a Group
+
+```
+Group 1: Phase 1 + Phase 2 (combined complexity: 5)
+│
+├── AUTO-SWITCH to Plan Mode for Phase 1
+├── Present Phase 1 details
+├── Get user approval
+├── Implement Phase 1
+├── Update Phase 1 progress in plan file
+│
+├── AUTO-SWITCH to Plan Mode for Phase 2
+├── Present Phase 2 details
+├── Get user approval
+├── Implement Phase 2
+├── Update Phase 2 progress in plan file
+│
+└── Continue to next group (NO BUILD HERE)
+```
+
+---
+
+## Complexity-Based Behavior
+
+### Low Complexity Phases (0-4)
+
+- Can be grouped with adjacent low-complexity phases
+- Still requires Plan mode for each individual phase
+- Quick planning discussion
+- Focus on consistency with existing patterns
+
+### Medium Complexity Phases (5-6)
+
+- May be grouped if combined score ≤ 6
+- Moderate planning discussion
+- Review key decisions and patterns
+
+### High Complexity Phases (7-8)
+
+- Execute alone or with one adjacent phase if combined ≤ 10
+- Detailed planning discussion
+- Consider multiple approaches
+
+### Very High Complexity Phases (9-10)
+
+- **Always execute alone**
+- Extensive planning discussion
+- Break down into sub-tasks if needed
+- Consider spikes or prototypes first
+
+---
+
+## Error Handling
+
+### Build Failures (at Completion)
+
+If `npm run build` fails at Step 7:
+
+1. Analyze the error
+2. Determine which phase introduced the issue
+3. Fix the issue
+4. Re-run build verification
+5. Only complete after successful build
+
+### Test Failures (at Completion)
+
+If `npm run test` fails at Step 7:
+
+1. Analyze failing tests
+2. Determine if it's a test issue or implementation bug
+3. Fix the issue
+4. Re-run tests
+5. Only complete after all tests pass
+
+### User Cancellation
+
+If the user wants to stop execution:
+
+1. Save current progress in the plan file
+2. Note which phases are complete
+3. The plan can be resumed later from the last completed phase
+4. When resuming, run build verification first
+
+---
+
+## Summary of Key Rules
+
+| Rule                         | Description                                                 |
+| ---------------------------- | ----------------------------------------------------------- |
+| **Auto-switch to Plan mode** | Switch immediately for each phase, no asking                |
+| **Build ONLY at end**        | `npm run build && npm run test` runs once, after ALL phases |
+| **No intermediate builds**   | Never run build between phases or groups                    |
+| **Tests phase separate**     | Always execute Tests phase individually                     |
+| **Update progress**          | Mark tasks complete in plan file after each phase           |
+
+---
+
+## Related Files
+
+| File                                        | Purpose                          |
+| ------------------------------------------- | -------------------------------- |
+| `.cursor/rules/patterns/plans-patterns.mdc` | Plan patterns and rules          |
+| `.cursor/rules/core/complexity-scoring.mdc` | Complexity scoring system        |
+| `.cursor/rules/tools/plan-mode-tool.mdc`    | Plan mode switching instructions |
+| `flow/plans/`                               | Input plan documents             |
+| `flow/archive/`                             | Completed plans destination      |