plan-flow-skill 1.0.0

package/rules/skills/write-tests-skill.mdc

@@ -0,0 +1,294 @@
+---
+description: "Include when /write-tests is invoked or test coverage improvement is needed"
+alwaysApply: false
+---
+
+# Write Tests Skill
+
+## Purpose
+
+Analyze current test coverage and **iteratively write or improve tests** for each file until the target coverage percentage is achieved across all files.
+
+This skill writes test code to achieve the specified coverage target.
+
+---
+
+## Inputs
+
+| Input               | Required | Description                                      |
+| ------------------- | -------- | ------------------------------------------------ |
+| `target_coverage`   | Yes      | Minimum coverage percentage (e.g., 80, 90, 100)  |
+| `framework`         | Optional | Testing framework (Jest or Pytest, auto-detected)|
+| `specific_files`    | Optional | Specific files to focus on                       |
+
+---
+
+## Workflow
+
+### Step 1: Detect Testing Framework
+
+Identify the testing framework based on project files:
+
+| Framework | Detection                                     |
+| --------- | --------------------------------------------- |
+| Jest      | `jest.config.js`, `package.json` with jest    |
+| Pytest    | `pytest.ini`, `pyproject.toml`, `conftest.py` |
+
+Load the appropriate patterns:
+- Jest: `.cursor/rules/patterns/jest-patterns.mdc`
+- Pytest: `.cursor/rules/patterns/pytest-patterns.mdc`
+
+---
+
+### Step 2: Run Initial Coverage Analysis
+
+Run the coverage command:
+
+**Jest**:
+```bash
+npm run test -- --coverage
+```
+
+**Pytest**:
+```bash
+pytest --cov=src --cov-report=term-missing
+```
+
+Parse the results to identify:
+- Current coverage per file
+- Files below target
+- Uncovered lines/branches
+
+---
+
+### Step 3: Create Work Queue
+
+Sort files by coverage (lowest first):
+
+```markdown
+## Coverage Work Queue
+
+| File                        | Current | Target | Gap  | Priority |
+| --------------------------- | ------- | ------ | ---- | -------- |
+| src/services/userService.ts | 45%     | 80%    | 35%  | 1        |
+| src/utils/validation.ts     | 60%     | 80%    | 20%  | 2        |
+| src/components/Button.tsx   | 75%     | 80%    | 5%   | 3        |
+```
+
+---
+
+### Step 4: For Each File Below Target
+
+For each file in the work queue:
+
+#### 4.1: Analyze Source File
+
+1. Read the source file
+2. Identify all functions/methods
+3. Check existing tests (if any)
+4. Identify uncovered code paths:
+   - Uncovered functions
+   - Uncovered branches (if/else, switch)
+   - Error handling paths
+   - Edge cases
+
+#### 4.2: Write/Improve Tests
+
+1. Create test file if missing
+2. Add tests for uncovered lines
+3. Follow testing patterns from patterns file
+
+**Test File Naming**:
+- Jest: `*.test.ts`, `*.spec.ts`
+- Pytest: `test_*.py`, `*_test.py`
+
+**Test Structure**:
+
+```typescript
+// Jest example
+describe('FunctionName', () => {
+  describe('when condition', () => {
+    it('should expected behavior', () => {
+      // Arrange
+      // Act
+      // Assert
+    });
+  });
+});
+```
+
+```python
+# Pytest example
+class TestFunctionName:
+    def test_when_condition_should_expected_behavior(self):
+        # Arrange
+        # Act
+        # Assert
+```
+
+#### 4.3: Verify File Coverage
+
+After writing tests, run coverage for the specific file:
+
+**Jest**:
+```bash
+npm run test -- --coverage --collectCoverageFrom="src/path/file.ts"
+```
+
+**Pytest**:
+```bash
+pytest tests/test_file.py --cov=src/module --cov-report=term-missing
+```
+
+**CRITICAL**: ALL metrics must meet target:
+- Lines
+- Statements
+- Branches
+- Functions
+
+If not met, continue adding tests until all metrics pass.
+
+---
+
+### Step 5: Final Verification
+
+After all files are processed, run full coverage:
+
+**Jest**:
+```bash
+npm run test -- --coverage
+```
+
+**Pytest**:
+```bash
+pytest --cov=src --cov-report=term-missing
+```
+
+Verify all files meet the target coverage.
+
+---
+
+## Coverage Metrics Priority
+
+1. **Lines**: Most important metric
+2. **Branches**: Cover all conditional paths (if/else, ternary, switch)
+3. **Functions**: Ensure all exported functions are tested
+4. **Statements**: Usually follows lines coverage
+
+---
+
+## Test Writing Guidelines
+
+### What to Test
+
+| Priority | What to Test                    | Why                              |
+| -------- | ------------------------------- | -------------------------------- |
+| High     | Public API / Exported functions | Contract with consumers          |
+| High     | Error handling paths            | Critical for reliability         |
+| High     | Edge cases                      | Often source of bugs             |
+| Medium   | Happy path scenarios            | Basic functionality              |
+| Medium   | Boundary conditions             | Off-by-one errors                |
+| Low      | Private helper functions        | Tested via public API            |
+
+### Test Quality Checklist
+
+- [ ] Tests are independent (no shared state)
+- [ ] Tests have clear names describing behavior
+- [ ] Tests follow AAA pattern (Arrange, Act, Assert)
+- [ ] Mocks are minimal and focused
+- [ ] Edge cases are covered
+- [ ] Error scenarios are tested
+
+---
+
+## Handling Common Patterns
+
+### Async Functions
+
+```typescript
+it('should handle async operation', async () => {
+  const result = await asyncFunction();
+  expect(result).toBe(expected);
+});
+```
+
+### Error Throwing
+
+```typescript
+it('should throw error for invalid input', () => {
+  expect(() => functionWithValidation(null)).toThrow('Invalid input');
+});
+```
+
+### Mocking Dependencies
+
+```typescript
+jest.mock('./dependency', () => ({
+  dependencyFunction: jest.fn().mockReturnValue('mocked'),
+}));
+```
+
+---
+
+## Output Format
+
+Present progress after each file:
+
+```markdown
+## Test Progress: [file_path]
+
+**Before**: 45% coverage
+**After**: 82% coverage
+
+**Tests Added**:
+- test_when_valid_input_returns_result
+- test_when_invalid_input_throws_error
+- test_edge_case_empty_string
+
+**Metrics**:
+| Metric     | Before | After  | Target | Status |
+| ---------- | ------ | ------ | ------ | ------ |
+| Lines      | 45%    | 82%    | 80%    | Pass   |
+| Branches   | 30%    | 80%    | 80%    | Pass   |
+| Functions  | 50%    | 100%   | 80%    | Pass   |
+| Statements | 45%    | 82%    | 80%    | Pass   |
+```
+
+---
+
+## Final Report
+
+After completion, present summary:
+
+```markdown
+## Coverage Target Achieved!
+
+**Target**: [X]%
+**Final Coverage**: [Y]%
+
+### Files Updated:
+
+| File                        | Before | After  |
+| --------------------------- | ------ | ------ |
+| src/services/userService.ts | 45%    | 85%    |
+| src/utils/validation.ts     | 60%    | 92%    |
+
+### Tests Created/Updated:
+
+- Created: X new test files
+- Updated: Y existing test files
+- Total tests added: Z
+
+All metrics meet or exceed the target coverage.
+```
+
+---
+
+## Related Files
+
+| File                                        | Purpose                         |
+| ------------------------------------------- | ------------------------------- |
+| `.cursor/rules/patterns/jest-patterns.mdc`  | Jest testing patterns           |
+| `.cursor/rules/patterns/pytest-patterns.mdc`| Pytest testing patterns         |
+| `.cursor/rules/tools/jest-testing-tool.mdc` | Jest commands and utilities     |
+| `.cursor/rules/tools/pytest-testing-tool.mdc`| Pytest commands and utilities  |

package/rules/templates/index-template.mdc

@@ -0,0 +1,126 @@
+---
+description: "Template for creating folder index files - copy and customize for each folder"
+alwaysApply: false
+---
+
+# Index Template
+
+Use this template when creating `_index.mdc` files for each folder. Copy and customize the sections below.
+
+---
+
+## Template
+
+```markdown
+---
+description: "Summary index for [FOLDER_NAME] - load this to see available references"
+alwaysApply: false
+---
+
+# [Folder Name] Index
+
+## Overview
+
+Brief description of what this folder contains and when these rules/patterns are used.
+
+**Total Files**: X files, ~Y lines
+**Reference Codes**: [PREFIX]-1 through [PREFIX]-N
+
+---
+
+## Reference Codes
+
+| Code  | Description                    | Source         | Lines         |
+| ----- | ------------------------------ | -------------- | ------------- |
+| XXX-1 | [Brief description of section] | [filename.mdc] | [start]-[end] |
+| XXX-2 | [Brief description of section] | [filename.mdc] | [start]-[end] |
+
+---
+
+## When to Expand
+
+Use these guidelines to determine when to load full content:
+
+| Code  | Expand When                    |
+| ----- | ------------------------------ |
+| XXX-1 | [Specific use case or trigger] |
+| XXX-2 | [Specific use case or trigger] |
+
+---
+
+## Quick Reference
+
+### [Category 1]
+
+- **XXX-1**: [One-line summary]
+- **XXX-2**: [One-line summary]
+
+### [Category 2]
+
+- **XXX-3**: [One-line summary]
+```
+
+---
+
+## Naming Conventions
+
+### Reference Code Prefixes
+
+| Prefix | Folder     | Example              |
+| ------ | ---------- | -------------------- |
+| COR-   | core/      | COR-1, COR-2         |
+| LNG-   | languages/ | LNG-TS-1, LNG-PY-1   |
+| PTN-   | patterns/  | PTN-DIS-1, PTN-PLN-1 |
+| SKL-   | skills/    | SKL-DIS-1, SKL-PLN-1 |
+| TLS-   | tools/     | TLS-AUTH-1, TLS-AQ-1 |
+
+### Sub-Category Codes
+
+For folders with multiple files, use sub-categories:
+
+| Pattern    | Meaning                         | Example                   |
+| ---------- | ------------------------------- | ------------------------- |
+| LNG-TS-1   | Language: TypeScript, Section 1 | TypeScript best practices |
+| LNG-PY-1   | Language: Python, Section 1     | Python best practices     |
+| PTN-DIS-1  | Pattern: Discovery, Section 1   | Discovery patterns        |
+| SKL-EXEC-1 | Skill: Execute, Section 1       | Execute plan workflow     |
+
+---
+
+## Section Identification Guidelines
+
+When analyzing a file to create reference codes:
+
+1. **Look for major headings** (## or ### level)
+2. **Identify self-contained sections** that can stand alone
+3. **Target 3-5 sections per file** (avoid over-fragmentation)
+4. **Include complete context** in each section
+
+### Good Section Boundaries
+
+- Complete examples with explanation
+- Full workflow steps
+- Entire tables with headers
+- Template blocks with instructions
+
+### Bad Section Boundaries
+
+- Partial code blocks
+- Headers without content
+- Single lines or small fragments
+- Sections that reference other sections heavily
+
+---
+
+## Line Range Format
+
+Use the format `start-end` for line ranges:
+
+- `1-50` - Lines 1 through 50
+- `100-150` - Lines 100 through 150
+
+**Tips**:
+
+- Include a few lines before/after for context
+- Start at section headers
+- End at the next section header minus 1

package/rules/tools/_index.mdc

@@ -0,0 +1,114 @@
+---
+description: "Index of tool documentation with reference codes for on-demand expansion"
+alwaysApply: false
+---
+
+# Tools Index
+
+This index provides reference codes for all tool documentation. Load specific sections on-demand using the line ranges.
+
+---
+
+## Overview
+
+| File | Lines | Description |
+|------|-------|-------------|
+| auth-pr-tool.mdc | 363 | PR authentication for GitHub/Azure DevOps |
+| interactive-questions-tool.mdc | 338 | Interactive questions via Plan mode |
+| jest-testing-tool.mdc | 97 | Jest test commands for JS/TS |
+| plan-mode-tool.mdc | 230 | Plan mode switching for collaborative execution |
+| pytest-testing-tool.mdc | 145 | Pytest commands for Python |
+| reference-expansion-tool.mdc | 219 | Reference code expansion system |
+
+---
+
+## Reference Codes
+
+### TLS-AUTH: PR Authentication Tool
+
+| Code | Lines | Description |
+|------|-------|-------------|
+| TLS-AUTH-1 | 1-41 | Purpose, usage, and environment configuration |
+| TLS-AUTH-2 | 42-142 | Authentication workflow (detect, load, auth, verify, handle errors) |
+| TLS-AUTH-3 | 144-198 | Authentication methods (GitHub CLI, Azure CLI, curl) |
+| TLS-AUTH-4 | 199-224 | Allowed commands for GitHub and Azure DevOps |
+| TLS-AUTH-5 | 225-250 | Security notes and required scopes |
+| TLS-AUTH-6 | 251-363 | Usage examples and error handling |
+
+### TLS-IQ: Interactive Questions Tool
+
+| Code | Lines | Description |
+|------|-------|-------------|
+| TLS-IQ-1 | 1-38 | Purpose, usage, and critical instructions |
+| TLS-IQ-2 | 40-82 | Step 1: Switch to Plan Mode |
+| TLS-IQ-3 | 84-146 | Step 2: Ask Questions using AskQuestion tool |
+| TLS-IQ-4 | 148-195 | Steps 3-5: Wait, Process, Return to Agent mode |
+| TLS-IQ-5 | 197-228 | Complete workflow example |
+| TLS-IQ-6 | 230-288 | When to use and question format guidelines |
+| TLS-IQ-7 | 290-338 | Error handling and related tools |
+
+### TLS-JEST: Jest Testing Tool
+
+| Code | Lines | Description |
+|------|-------|-------------|
+| TLS-JEST-1 | 1-48 | Purpose, usage, and running tests |
+| TLS-JEST-2 | 50-67 | Coverage commands |
+| TLS-JEST-3 | 69-82 | Debugging tests |
+| TLS-JEST-4 | 84-97 | CI/CD commands |
+
+### TLS-PLN: Plan Mode Tool
+
+| Code | Lines | Description |
+|------|-------|-------------|
+| TLS-PLN-1 | 1-68 | Purpose, usage, and how to switch |
+| TLS-PLN-2 | 70-127 | Plan mode workflow (steps 1-5) |
+| TLS-PLN-3 | 129-145 | When to use Plan mode |
+| TLS-PLN-4 | 147-157 | Integration with Execute Plan command |
+| TLS-PLN-5 | 159-192 | Benefits and error handling |
+| TLS-PLN-6 | 194-230 | Complete workflow example |
+
+### TLS-PYTEST: Pytest Testing Tool
+
+| Code | Lines | Description |
+|------|-------|-------------|
+| TLS-PYTEST-1 | 1-55 | Purpose, usage, and running tests |
+| TLS-PYTEST-2 | 57-76 | Coverage commands |
+| TLS-PYTEST-3 | 78-99 | Debugging tests |
+| TLS-PYTEST-4 | 101-124 | CI/CD commands |
+| TLS-PYTEST-5 | 126-145 | Test selection |
+
+### TLS-REF: Reference Expansion Tool
+
+| Code | Lines | Description |
+|------|-------|-------------|
+| TLS-REF-1 | 1-38 | Purpose and reference code system |
+| TLS-REF-2 | 40-74 | Expansion workflow (load, identify, expand, use) |
+| TLS-REF-3 | 76-97 | When to expand vs when to skip |
+| TLS-REF-4 | 99-140 | Examples (discovery and execute plan) |
+| TLS-REF-5 | 142-170 | Maintenance guidelines |
+| TLS-REF-6 | 172-219 | Index locations and troubleshooting |
+
+---
+
+## When to Expand
+
+| Task | Codes to Expand |
+|------|-----------------|
+| Authenticating for PR review | TLS-AUTH-2, TLS-AUTH-3 |
+| Asking interactive questions | TLS-IQ-1, TLS-IQ-2, TLS-IQ-3 |
+| Running Jest tests | TLS-JEST-1, TLS-JEST-2 |
+| Running pytest tests | TLS-PYTEST-1, TLS-PYTEST-2 |
+| Switching to Plan mode | TLS-PLN-1, TLS-PLN-2 |
+| Understanding reference system | TLS-REF-1, TLS-REF-2 |
+| Maintaining index files | TLS-REF-5 |
+
+---
+
+## Quick Reference
+
+- **Need to authenticate?** Use TLS-AUTH-* codes
+- **Need to ask questions?** Use TLS-IQ-* codes
+- **Need to run JS/TS tests?** Use TLS-JEST-* codes
+- **Need to run Python tests?** Use TLS-PYTEST-* codes
+- **Need to switch modes?** Use TLS-PLN-* codes
+- **Need to understand this system?** Use TLS-REF-* codes