plan-flow-skill 1.0.0

package/rules/skills/_index.mdc

@@ -0,0 +1,174 @@
+---
+description: "Summary index for skills - load this to see available references"
+alwaysApply: false
+---
+
+# Skills Index
+
+## Overview
+
+Skills implement the workflow logic for commands. Each skill orchestrates a specific process like discovery, planning, execution, or code review.
+
+**Total Files**: 8 files, ~2,506 lines
+**Reference Codes**: SKL-CON-1 through SKL-TEST-5
+
+---
+
+## Reference Codes
+
+### Create Contract Skill (`create-contract-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-CON-1 | Purpose and restrictions (allowed/forbidden actions) | create-contract-skill.mdc | 8-53 |
+| SKL-CON-2 | Workflow (detect source, fetch, ask questions, generate) | create-contract-skill.mdc | 65-140 |
+| SKL-CON-3 | Contract output template | create-contract-skill.mdc | 142-215 |
+| SKL-CON-4 | Validation checklist | create-contract-skill.mdc | 217-240 |
+
+### Create Plan Skill (`create-plan-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-PLN-1 | Purpose and restrictions | create-plan-skill.mdc | 8-53 |
+| SKL-PLN-2 | Workflow (extract, analyze, structure phases) | create-plan-skill.mdc | 67-165 |
+| SKL-PLN-3 | Plan output template | create-plan-skill.mdc | 179-244 |
+| SKL-PLN-4 | Validation checklist | create-plan-skill.mdc | 246-272 |
+
+### Discovery Skill (`discovery-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-DIS-1 | Purpose and restrictions | discovery-skill.mdc | 8-57 |
+| SKL-DIS-2 | Workflow steps 1-4 (read docs, questions, tracking, requirements) | discovery-skill.mdc | 71-173 |
+| SKL-DIS-3 | Workflow steps 5-8 (tech considerations, approach, risks, generate) | discovery-skill.mdc | 175-256 |
+| SKL-DIS-4 | Validation checklist | discovery-skill.mdc | 270-296 |
+
+### Execute Plan Skill (`execute-plan-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-EXEC-1 | Critical rules (build only at end, no DB commands) | execute-plan-skill.mdc | 22-95 |
+| SKL-EXEC-2 | Workflow steps 1-3 (parse, analyze complexity, present summary) | execute-plan-skill.mdc | 105-182 |
+| SKL-EXEC-3 | Workflow steps 4-5 (execute phases with Plan mode, update progress) | execute-plan-skill.mdc | 184-238 |
+| SKL-EXEC-4 | Workflow steps 6-7 (tests phase, completion/verification) | execute-plan-skill.mdc | 240-281 |
+| SKL-EXEC-5 | Complexity-based behavior (low, medium, high, very high) | execute-plan-skill.mdc | 303-332 |
+| SKL-EXEC-6 | Error handling (build failures, test failures, cancellation) | execute-plan-skill.mdc | 334-366 |
+
+### Review Code Skill (`review-code-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-REV-1 | Purpose and restrictions (read-only analysis) | review-code-skill.mdc | 8-58 |
+| SKL-REV-2 | Workflow steps 1-3 (identify files, load patterns, find similar) | review-code-skill.mdc | 72-130 |
+| SKL-REV-3 | Workflow steps 4-6 (analyze, pattern conflicts, generate doc) | review-code-skill.mdc | 131-180 |
+| SKL-REV-4 | Severity levels and conflict resolution | review-code-skill.mdc | 182-231 |
+| SKL-REV-5 | Finding similar implementations (search strategies) | review-code-skill.mdc | 233-259 |
+
+### Review PR Skill (`review-pr-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-PR-1 | Purpose and restrictions (GitHub/Azure DevOps commands) | review-pr-skill.mdc | 8-122 |
+| SKL-PR-2 | Workflow (authenticate, fetch, analyze, generate) | review-pr-skill.mdc | 132-217 |
+| SKL-PR-3 | Output format template with review history | review-pr-skill.mdc | 219-318 |
+| SKL-PR-4 | Severity levels and fix complexity scoring | review-pr-skill.mdc | 320-370 |
+| SKL-PR-5 | Link format for GitHub and Azure DevOps | review-pr-skill.mdc | 372-420 |
+
+### Setup Skill (`setup-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-SETUP-1 | Purpose and critical approach | setup-skill.mdc | 8-30 |
+| SKL-SETUP-2 | Steps 1-2 (scan project structure, dependency analysis) | setup-skill.mdc | 34-106 |
+| SKL-SETUP-3 | Step 3 (deep code analysis, sample files, extract patterns) | setup-skill.mdc | 108-200 |
+| SKL-SETUP-4 | Steps 4-5 (research best practices, check existing rules) | setup-skill.mdc | 202-252 |
+| SKL-SETUP-5 | Step 6 (confirming questions via Plan mode) | setup-skill.mdc | 254-334 |
+| SKL-SETUP-6 | Step 7 (generate framework and library pattern files) | setup-skill.mdc | 336-493 |
+| SKL-SETUP-7 | Steps 8-11 (update core, create analysis doc, create flow folder, summary) | setup-skill.mdc | 595-797 |
+
+### Write Tests Skill (`write-tests-skill.mdc`)
+
+| Code | Description | Source | Lines |
+|------|-------------|--------|-------|
+| SKL-TEST-1 | Purpose and inputs | write-tests-skill.mdc | 8-24 |
+| SKL-TEST-2 | Workflow steps 1-3 (detect framework, coverage analysis, work queue) | write-tests-skill.mdc | 26-78 |
+| SKL-TEST-3 | Step 4 (analyze source, write/improve tests, verify coverage) | write-tests-skill.mdc | 80-150 |
+| SKL-TEST-4 | Step 5 and test writing guidelines | write-tests-skill.mdc | 152-202 |
+| SKL-TEST-5 | Output format and final report | write-tests-skill.mdc | 232-283 |
+
+---
+
+## When to Expand
+
+### Discovery and Planning
+
+| Code | Expand When |
+|------|-------------|
+| SKL-DIS-1 | Need discovery restrictions/allowed actions |
+| SKL-DIS-2 | Need question tracking and requirements gathering workflow |
+| SKL-PLN-2 | Need phase structuring and complexity scoring workflow |
+| SKL-PLN-3 | Need plan output template |
+
+### Execution
+
+| Code | Expand When |
+|------|-------------|
+| SKL-EXEC-1 | Need critical rules (build timing, DB commands) |
+| SKL-EXEC-2 | Need complexity analysis and grouping logic |
+| SKL-EXEC-3 | Need phase execution workflow with Plan mode |
+| SKL-EXEC-5 | Need complexity-based behavior details |
+
+### Code Review
+
+| Code | Expand When |
+|------|-------------|
+| SKL-REV-2 | Need pattern loading and similar implementation search |
+| SKL-REV-4 | Need severity levels and conflict resolution |
+| SKL-PR-3 | Need PR review output template |
+| SKL-PR-5 | Need link format for GitHub/Azure DevOps |
+
+### Setup and Testing
+
+| Code | Expand When |
+|------|-------------|
+| SKL-SETUP-2 | Need dependency detection tables |
+| SKL-SETUP-6 | Need pattern file generation templates |
+| SKL-TEST-2 | Need coverage analysis workflow |
+| SKL-TEST-4 | Need test writing guidelines |
+
+### Contracts
+
+| Code | Expand When |
+|------|-------------|
+| SKL-CON-2 | Need contract creation workflow |
+| SKL-CON-3 | Need contract output template |
+
+---
+
+## Quick Reference by Command
+
+| Command | Skill | Key Codes |
+|---------|-------|-----------|
+| `/discovery-plan` | discovery-skill | SKL-DIS-1 through SKL-DIS-4 |
+| `/create-plan` | create-plan-skill | SKL-PLN-1 through SKL-PLN-4 |
+| `/execute-plan` | execute-plan-skill | SKL-EXEC-1 through SKL-EXEC-6 |
+| `/review-code` | review-code-skill | SKL-REV-1 through SKL-REV-5 |
+| `/review-pr` | review-pr-skill | SKL-PR-1 through SKL-PR-5 |
+| `/setup` | setup-skill | SKL-SETUP-1 through SKL-SETUP-7 |
+| `/write-tests` | write-tests-skill | SKL-TEST-1 through SKL-TEST-5 |
+| `/create-contract` | create-contract-skill | SKL-CON-1 through SKL-CON-4 |
+
+---
+
+## Skill Complexity
+
+| Skill | Lines | Sections | Complexity |
+|-------|-------|----------|------------|
+| setup-skill | 821 | 7 | Highest - deep project analysis |
+| review-pr-skill | 496 | 5 | High - multi-platform support |
+| execute-plan-skill | 388 | 6 | High - phase execution logic |
+| review-code-skill | 308 | 5 | Medium - pattern matching |
+| discovery-skill | 295 | 4 | Medium - requirements gathering |
+| write-tests-skill | 294 | 5 | Medium - iterative testing |
+| create-plan-skill | 271 | 4 | Low - plan structuring |
+| create-contract-skill | 239 | 4 | Low - contract generation |

package/rules/skills/create-contract-skill.mdc

@@ -0,0 +1,239 @@
+---
+description: "Include when /create-contract is invoked or integration contract creation from documentation URLs is needed"
+alwaysApply: false
+---
+
+# Create Contract Skill
+
+## Purpose
+
+Create an **integration contract document** by fetching information from a documentation URL or analyzing a project repository. The contract captures all necessary details for frontend integration including endpoints, schemas, authentication, and usage patterns.
+
+This skill **only produces a markdown file** in `flow/contracts/`. It does NOT:
+
+- Write any code
+- Implement any integrations
+- Modify source files
+- Execute any implementation
+
+---
+
+## Restrictions - CONTRACT CREATION ONLY
+
+This skill is **strictly for creating contract documents**. The process:
+
+1. **Fetches** information from the source URL
+2. **Analyzes** the API structure and schemas
+3. **Asks** clarifying questions via Interactive Questions Tool
+4. **Generates** a contract markdown file
+
+**No code, no implementation, no source file modifications.**
+
+### NEVER Do These Actions
+
+| Forbidden Action                       | Reason                              |
+| -------------------------------------- | ----------------------------------- |
+| Create/edit source code files          | Contract creation only              |
+| Write implementation code              | Contracts describe, not implement   |
+| Modify configuration files             | No codebase changes                 |
+| Run build or test commands             | No execution commands               |
+| Create files outside `flow/contracts/` | Only write contract documents       |
+
+### Allowed Actions
+
+| Allowed Action                         | Purpose                              |
+| -------------------------------------- | ------------------------------------ |
+| Use Web Search tool                    | Fetch documentation from URLs        |
+| Read repository files                  | Analyze API structure                |
+| Use Interactive Questions Tool         | Gather requirements from user        |
+| Write to `flow/contracts/`             | Save contract document               |
+| Read project rule files                | Understand patterns to follow        |
+
+> **Important**: The ONLY writable location is `flow/contracts/`. No source code or other files should be modified.
+
+---
+
+## Inputs
+
+| Input         | Required | Description                                          |
+| ------------- | -------- | ---------------------------------------------------- |
+| `source_url`  | Yes      | Documentation URL or repository URL                  |
+| `description` | Yes      | What the user wants to integrate on the frontend     |
+
+---
+
+## Workflow
+
+### Step 1: Detect Source Type
+
+Analyze the provided URL to determine the source type:
+
+| Source Type      | Detection                                      |
+| ---------------- | ---------------------------------------------- |
+| Documentation    | Contains `/docs`, `/api`, swagger, openapi     |
+| Repository       | Contains github.com, gitlab.com, bitbucket.org |
+| OpenAPI Spec     | Ends with `.json`, `.yaml`, `/swagger`         |
+
+---
+
+### Step 2A: Handle Documentation URL
+
+If the source is a documentation URL:
+
+1. Use Web Search tool to fetch documentation content
+2. Extract key information:
+   - API endpoints
+   - Request/response schemas
+   - Authentication methods
+   - Error formats
+   - Rate limits
+
+---
+
+### Step 2B: Handle Repository URL
+
+If the source is a repository URL:
+
+1. Analyze repository structure
+2. Identify relevant files:
+   - API route definitions
+   - Type definitions
+   - Schema files
+   - README/docs
+3. Read and extract key information
+
+---
+
+### Step 3: Ask Clarifying Questions
+
+**Use Interactive Questions Tool** to gather requirements.
+
+Follow `.cursor/rules/tools/interactive-questions-tool.mdc`:
+
+1. Call `SwitchMode` tool to enter Plan mode
+2. Call `AskQuestion` tool for each question about:
+   - **Scope**: Which specific endpoints/features are needed?
+   - **Authentication**: How will the FE authenticate?
+   - **Error Handling**: How should the FE handle errors?
+   - **Caching**: Any caching requirements?
+3. Wait for all responses
+4. Call `SwitchMode` tool to return to Agent mode
+5. Document answers for use in the contract document
+
+---
+
+### Step 4: Generate Contract Document
+
+Create the contract with all gathered information:
+
+**Location**: `flow/contracts/<service_name>_contract.md`
+
+**Required Sections**:
+
+1. Overview
+2. Authentication
+3. Endpoints (with request/response schemas)
+4. Error Handling
+5. Integration Notes
+6. Usage Examples
+
+---
+
+## Output Format
+
+### Contract Template
+
+```markdown
+# Integration Contract: [Service Name]
+
+## Overview
+
+**Source**: [URL]
+**Description**: [What this integration provides]
+**Version**: [API version if applicable]
+
+## Authentication
+
+**Method**: [Bearer token, API key, OAuth, etc.]
+**Header**: [Authorization header format]
+**Token Source**: [Where FE gets the token]
+
+## Endpoints
+
+### [Endpoint Name]
+
+**Method**: [GET/POST/PUT/DELETE]
+**URL**: [Endpoint URL]
+**Description**: [What this endpoint does]
+
+**Request**:
+```typescript
+interface RequestBody {
+  // Request schema
+}
+```
+
+**Response**:
+```typescript
+interface Response {
+  // Response schema
+}
+```
+
+**Example**:
+```bash
+curl -X POST /api/endpoint \
+  -H "Authorization: Bearer token" \
+  -d '{"field": "value"}'
+```
+
+## Error Handling
+
+| Status Code | Meaning              | FE Action                 |
+| ----------- | -------------------- | ------------------------- |
+| 400         | Bad Request          | Show validation error     |
+| 401         | Unauthorized         | Redirect to login         |
+| 404         | Not Found            | Show not found message    |
+| 500         | Server Error         | Show generic error        |
+
+## Integration Notes
+
+### Rate Limits
+[Any rate limiting information]
+
+### Caching
+[Caching recommendations]
+
+### Pagination
+[Pagination format if applicable]
+
+## Usage Examples
+
+### [Use Case 1]
+[Code example or description]
+```
+
+---
+
+## Validation Checklist
+
+Before completing the contract, verify:
+
+- [ ] Contract is saved in `flow/contracts/` folder
+- [ ] File uses naming: `<service_name>_contract.md`
+- [ ] All requested endpoints are documented
+- [ ] Authentication method is clear
+- [ ] Request/response schemas are defined
+- [ ] Error handling is documented
+- [ ] **NO implementation code is included**
+- [ ] **NO source files were created or modified**
+
+---
+
+## Related Files
+
+| File                                               | Purpose                           |
+| -------------------------------------------------- | --------------------------------- |
+| `.cursor/rules/patterns/contract-patterns.mdc`     | Rules and patterns for contracts  |
+| `.cursor/rules/tools/interactive-questions-tool.mdc` | Interactive Questions workflow  |
+| `flow/contracts/`                                  | Output folder for contracts       |

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

@@ -0,0 +1,271 @@
+---
+description: "Include when /create-plan is invoked or implementation planning from discovery documents is needed"
+alwaysApply: false
+---
+
+# Create Plan Skill
+
+## Purpose
+
+Create a structured **implementation plan** with phases, complexity scores, and tasks based on a discovery document or user requirements.
+
+This skill **only produces a markdown file** in `flow/plans/`. It does NOT:
+
+- Write any code
+- Execute any implementation
+- Modify source files
+- Run build or test commands
+
+---
+
+## Restrictions - PLANNING ONLY
+
+This skill is **strictly for creating plan documents**. The process:
+
+1. **Reads** the discovery document or gathers requirements
+2. **Analyzes** complexity and scope
+3. **Structures** phases with complexity scores
+4. **Generates** a plan markdown file
+
+**No code, no implementation, no source file modifications.**
+
+### NEVER Do These Actions
+
+| Forbidden Action                    | Reason                           |
+| ----------------------------------- | -------------------------------- |
+| Create/edit source code files       | Planning only, no implementation |
+| Write implementation code           | Plans describe what, not how     |
+| Execute any plan phases             | Use /execute-plan for that       |
+| Run build or test commands          | No execution commands            |
+| Create files outside `flow/plans/`  | Only write plan documents        |
+
+### Allowed Actions
+
+| Allowed Action                         | Purpose                           |
+| -------------------------------------- | --------------------------------- |
+| Read discovery documents               | Extract requirements              |
+| Read any project file                  | Understand existing codebase      |
+| Search codebase (grep, glob, semantic) | Find existing patterns            |
+| Write to `flow/plans/`                 | Save plan document                |
+| Read project rule files                | Understand patterns to follow     |
+
+> **Important**: The ONLY writable location is `flow/plans/`. No source code or other files should be modified.
+
+---
+
+## Inputs
+
+| Input                | Required | Description                                        |
+| -------------------- | -------- | -------------------------------------------------- |
+| `discovery_document` | Optional | Path to discovery document (recommended)           |
+| `feature_name`       | Yes      | Name of the feature to plan                        |
+| `requirements`       | Optional | Direct requirements if no discovery document       |
+| `version`            | Optional | Version number (auto-incremented if not provided)  |
+
+---
+
+## Workflow
+
+### Step 1: Extract Requirements
+
+**If discovery document was provided**:
+
+1. Read the discovery document
+2. Extract feature name, description, goals from the document
+3. Extract FR, NFR, Constraints
+4. Note any risks identified
+
+**If no discovery document**:
+
+1. Use requirements provided directly
+2. Note that discovery was skipped
+
+---
+
+### Step 2: Analyze Scope and Complexity
+
+Based on extracted requirements:
+
+1. Identify the major components/areas of work
+2. Group related tasks into logical phases
+3. Estimate complexity for each phase using `.cursor/rules/core/complexity-scoring.mdc`
+
+---
+
+### Step 3: Structure Phases
+
+Create phases following these guidelines:
+
+**Phase Structure**:
+
+```markdown
+### Phase X: [Phase Name]
+
+**Scope**: [What this phase covers]
+**Complexity**: X/10
+
+- [ ] Task 1
+- [ ] Task 2
+
+**Build Verification**: Run `npm run build`
+```
+
+**Standard Phase Order**:
+
+1. Types and Schemas (usually low complexity)
+2. Backend/API Implementation
+3. Store/State Management
+4. UI Components
+5. Integration
+6. Tests (ALWAYS last)
+
+**Complexity Scoring** (per `.cursor/rules/core/complexity-scoring.mdc`):
+
+| Score | Level     | Description                      |
+| ----- | --------- | -------------------------------- |
+| 0-2   | Trivial   | Simple, mechanical changes       |
+| 3-4   | Low       | Straightforward implementation   |
+| 5-6   | Medium    | Moderate effort, some decisions  |
+| 7-8   | High      | Complex, multiple considerations |
+| 9-10  | Very High | Significant complexity/risk      |
+
+---
+
+### Step 4: Add Key Changes Summary
+
+Document the most important modifications:
+
+```markdown
+## Key Changes
+
+1. **[Category]**: [Description of change]
+2. **[Category]**: [Description of change]
+```
+
+---
+
+### Step 5: Generate Plan Document
+
+Create the plan markdown file:
+
+**Location**: `flow/plans/plan_<feature_name>_v<version>.md`
+
+**Use Template**: See `.cursor/rules/patterns/plans-templates.mdc`
+
+**Required Sections**:
+
+1. Overview (with discovery document reference)
+2. Goals
+3. Non-Goals
+4. Requirements Summary (FR, NFR, Constraints)
+5. Risks
+6. Phases (with complexity scores)
+7. Key Changes
+
+---
+
+## Output Format
+
+The plan document should follow the template in `.cursor/rules/patterns/plans-templates.mdc`.
+
+**Naming Convention**: `plan_<feature_name>_v<version>.md`
+
+**Examples**:
+- `plan_user_authentication_v1.md`
+- `plan_dark_mode_v2.md`
+
+---
+
+## Plan Template
+
+```markdown
+# Plan: [Feature Name]
+
+## Overview
+
+[Brief description of the feature and its purpose]
+
+**Based on Discovery**: `flow/discovery/discovery_<feature>_v1.md` (or "Discovery skipped")
+
+## Goals
+
+- [Goal 1]
+- [Goal 2]
+
+## Non-Goals
+
+- [What this plan explicitly does NOT cover]
+
+## Requirements Summary
+
+### Functional Requirements
+
+- [FR-1]: [Description]
+
+### Non-Functional Requirements
+
+- [NFR-1]: [Description]
+
+### Constraints
+
+- [C-1]: [Description]
+
+## Risks
+
+| Risk     | Impact          | Mitigation            |
+| -------- | --------------- | --------------------- |
+| [Risk 1] | High/Medium/Low | [Mitigation strategy] |
+
+## Phases
+
+### Phase 1: [Phase Name]
+
+**Scope**: [What this phase covers]
+**Complexity**: X/10
+
+- [ ] Task 1
+- [ ] Task 2
+
+**Build Verification**: Run `npm run build`
+
+### Phase N: Tests (Final)
+
+**Scope**: Write comprehensive tests
+**Complexity**: X/10
+
+- [ ] Unit tests
+- [ ] Integration tests
+
+**Build Verification**: Run `npm run build && npm run test`
+
+## Key Changes
+
+1. **[Category]**: [Description]
+```
+
+---
+
+## Validation Checklist
+
+Before completing the plan, verify:
+
+- [ ] Plan is saved in `flow/plans/` folder
+- [ ] File uses snake_case naming: `plan_<feature>_v<version>.md`
+- [ ] All phases have complexity scores (X/10)
+- [ ] Tests are the LAST phase
+- [ ] Key Changes section is populated
+- [ ] Discovery document is referenced (or noted as skipped)
+- [ ] **NO implementation code is included**
+- [ ] **NO source files were created or modified**
+
+---
+
+## Related Files
+
+| File                                           | Purpose                          |
+| ---------------------------------------------- | -------------------------------- |
+| `.cursor/rules/patterns/plans-patterns.mdc`    | Rules and patterns for plans     |
+| `.cursor/rules/patterns/plans-templates.mdc`   | Plan templates                   |
+| `.cursor/rules/core/complexity-scoring.mdc`    | Complexity scoring system        |
+| `flow/plans/`                                  | Output folder for plan documents |
+| `flow/discovery/`                              | Input discovery documents        |