ai-workflow-init 3.4.0 → 4.0.0

package/.cursor/commands/generate-standards.md

@@ -1,9 +1,20 @@
+---
+name: generate-standards
+description: Generates/updates code convention and project structure docs from the codebase.
+---
+
 ## Goal
 
 Generate or update `docs/ai/project/CODE_CONVENTIONS.md` and `PROJECT_STRUCTURE.md` from the current codebase with brief Q&A refinement.
 
 ## Step 1: Detect Project Context
 
+**Tools:**
+- search for files matching `**/package.json`
+- search for files matching `**/pyproject.toml`
+- search for files matching `**/*.config.{js,ts}`
+- Read(file_path=...) for each config file found
+
 Detect project languages/frameworks/libraries from repository metadata:
 
 - Analyze `package.json`, `pyproject.toml`, lockfiles, config files
@@ -12,10 +23,17 @@ Detect project languages/frameworks/libraries from repository metadata:
 - Identify libraries and tooling (ESLint, Prettier, testing frameworks, etc.)
 - Note any build tools or bundlers in use
 
+**Error handling:**
+- No config files found: Ask user for project type manually
+- Invalid JSON/TOML: Skip broken file, continue with others
+- Multiple conflicting configs: Prioritize root-level files
+
 **Output**: The detected project context will be written to `CODE_CONVENTIONS.md` as the foundation for code conventions.
 
 ## Step 2: Clarify Scope (3–6 questions max)
 
+**Tool:** ask user for clarification
+
 Quick classification and targeted questions:
 
 - Languages/frameworks detected: confirm correct? (a/b/other)
@@ -27,8 +45,22 @@ Quick classification and targeted questions:
 
 Keep questions short and single-purpose. Stop once sufficient info gathered.
 
+**Error handling:**
+- User skips questions: Use detected defaults from Step 1 only
+- Conflicting answers: Ask follow-up clarification
+- Max 2 retry attempts before proceeding with defaults
+
 ## Step 3: Auto-Discovery
 
+**Automated process:**
+- Use workspace search and analysis to accomplish this task
+    - Import patterns and ordering style
+    - Folder structure organization (feature/layer/mixed)
+    - Test file locations and naming patterns
+    - Common architectural patterns (Repository, Factory, Strategy, etc.)
+    Return concise summary with 2-3 examples for each category."
+)
+
 Analyze repository to infer:
 
 - Dominant naming patterns:
@@ -50,26 +82,30 @@ Analyze repository to infer:
   - Strategy patterns
   - Other architectural patterns
 
+**Error handling:**
+- Explore agent timeout: Fallback to quick Grep-based pattern detection
+- No patterns found: Generate minimal standards template
+- Inconsistent patterns: Document most frequent pattern as primary
+
 ## Step 4: Draft Standards
 
-Generate two documents (with template preload):
+**Tools:**
+- search for files matching `docs/ai/project/template-convention/*.md` to find templates
+- Read(file_path=...) for each matching template
+- create file `docs/ai/project/CODE_CONVENTIONS.md`
+- create file `docs/ai/project/PROJECT_STRUCTURE.md`
 
-### CODE_CONVENTIONS.md
+Generate two documents:
 
-- Template preload (flexible matching based on detected project context):
+### CODE_CONVENTIONS.md
 
-  1. Read all files in `docs/ai/project/template-convention/` directory
-  2. For each template file, determine if it matches the detected project context:
-     - Match by language (e.g., `javascript.md`, `typescript.md`, `python.md`)
-     - Match by framework (e.g., `react.md`, `vue.md`, `angular.md`)
-     - Match by common patterns (e.g., `common.md` — always include if present)
-  3. Load and merge all matching templates in a logical order:
-     - `common.md` first (if present)
-     - Language-specific templates (e.g., `javascript.md`, `typescript.md`)
-     - Framework-specific templates (e.g., `react.md`, `vue.md`)
-     - Other relevant templates based on detected tooling/patterns
-  4. These templates take precedence and should appear at the top of the generated document, followed by auto-discovered rules from codebase analysis.
+**Content order** (see Notes for template matching details):
+1. Project context from Step 1
+2. User preferences from Step 2
+3. Auto-discovered rules from Step 3
+4. Matching templates (merged and applied on top)
 
+**Sections to include:**
 - Naming conventions (variables, functions, classes, constants)
 - Import order and grouping
 - Formatting tools (ESLint/Prettier/etc.) if detected
@@ -81,62 +117,84 @@ Generate two documents (with template preload):
 
 ### PROJECT_STRUCTURE.md
 
-- Folder layout summary:
-  - `src/`: source code organization
-  - `docs/ai/**`: documentation structure
+**Sections to include:**
+- Folder layout summary (`src/`, `docs/ai/**`, etc.)
 - Module boundaries and dependency direction
 - Design patterns actually observed in codebase
 - Test placement and naming conventions
 - Config/secrets handling summary
 
+**Error handling:**
+- Template directory not found: Use hardcoded minimal template
+- Template parse error: Skip broken template, log warning
+- No matching templates: Generate standards from Step 3 discovery only
+
 ## Step 5: Persist (Update-in-place, Non-destructive)
 
-- Target files:
-  - `docs/ai/project/CODE_CONVENTIONS.md`
-  - `docs/ai/project/PROJECT_STRUCTURE.md`
-- Add header note: "This document is auto-generated from codebase analysis + brief Q&A. Edit manually as needed."
-- Do NOT blindly overwrite entire files. Update only the managed blocks using markers:
+**Tools:**
+- Read(file_path=...) to check existing content
+- Edit(file_path=..., old_string=..., new_string=...) for updates within managed blocks
+- Write(file_path=...) if file doesn't exist
+
+**Target files:**
+- `docs/ai/project/CODE_CONVENTIONS.md`
+- `docs/ai/project/PROJECT_STRUCTURE.md`
+
+**Update strategy:**
+- Use managed block markers to wrap generated content (see Notes for marker format)
+- If file exists with markers: Update content between START/END markers only
+- If file exists without markers: Append managed block to end
+- If file doesn't exist: Create with header note and managed block
+- Never modify content outside managed blocks
+
+**Error handling:**
+- File write permission denied: Notify user, suggest manual save
+- File locked by another process: Retry once, then notify user
+- Invalid marker format in existing file: Append new managed block instead of updating
+
+## Step 6: Next Actions
+
+- Suggest running `code-review` to validate new standards are being followed
+- Inform user they can manually edit these files anytime
+
+## Notes
+
+### General Guidelines
 
-### Managed Block Markers
+- Focus on patterns actually present in codebase, not ideal patterns
+- Keep generated docs concise and actionable
+- User can refine standards manually after generation
 
-Use these exact markers to wrap generated content:
+### Template Matching Details (Step 4)
 
+**Template loading logic:**
+1. Glob all files in `docs/ai/project/template-convention/`
+2. Match templates by filename:
+   - `common.md` → Always include if present
+   - `javascript.md`, `typescript.md`, `python.md` → Match by language
+   - `react.md`, `vue.md`, `angular.md` → Match by framework
+   - Other files → Match by detected tooling
+3. Merge order: `common.md` → language → framework → tooling
+4. Templates appear at top of generated doc, followed by auto-discovered rules
+
+### Managed Block Markers (Step 5)
+
+**Marker format for CODE_CONVENTIONS.md:**
 ```
 <!-- GENERATED: CODE_CONVENTIONS:START -->
 ... generated content ...
 <!-- GENERATED: CODE_CONVENTIONS:END -->
 ```
 
+**Marker format for PROJECT_STRUCTURE.md:**
 ```
 <!-- GENERATED: PROJECT_STRUCTURE:START -->
 ... generated content ...
 <!-- GENERATED: PROJECT_STRUCTURE:END -->
 ```
 
-### Update Rules
-
-1. If the target file exists and contains the corresponding markers, replace only the content between START/END with the newly generated content.
-2. If the file exists but does not contain markers, append a new managed block to the end of the file (preserve all existing manual content).
-3. If the file does not exist, create it with the header note and a single managed block.
-4. Never modify content outside the managed blocks.
-
-### Generated Content Order (for CODE_CONVENTIONS)
-
-1. **Project Context Section**: Write the detected project context from Step 1 (languages, frameworks, libraries, tooling)
-2. **Template Rules Section**: Merge all matching templates from `docs/ai/project/template-convention/` directory:
-   - Read all files in the directory
-   - Filter templates that match the detected project context (by language, framework, or common patterns)
-   - Merge in logical order: common → language → framework → tooling-specific
-3. **Auto-Discovered Rules Section**: Append auto-discovered rules from codebase analysis (Step 3)
-4. **Project-Specific Rules Section**: Include any project-specific conventions from Q&A (Step 2)
-
-## Step 6: Next Actions
-
-- Suggest running `code-review` to validate new standards are being followed
-- Inform user they can manually edit these files anytime
-
-## Notes
-
-- Focus on patterns actually present in codebase, not ideal patterns
-- Keep generated docs concise and actionable
-- User can refine standards manually after generation
+**Header note template:**
+```
+This document is auto-generated from codebase analysis + brief Q&A.
+Edit manually as needed.
+```

package/.cursor/commands/init-chat.md

@@ -1,3 +1,8 @@
+---
+name: init-chat
+description: Initializes chat by loading and aligning to AGENTS.md project rules.
+---
+
 ## Goal
 
 Initialize a new chat by loading and aligning to `AGENTS.md` so the AI agent consistently follows project rules (workflow, tooling, communication, language mirroring) from the first message.

package/.cursor/commands/writing-test.md

@@ -1,24 +1,34 @@
+---
+name: writing-test
+description: Generates comprehensive test files with edge cases, parameter variations, and coverage analysis.
+---
+
 Use `docs/ai/testing/feature-{name}.md` as the source of truth.
 
 ## Workflow Alignment
+
 - Provide brief status updates (1–3 sentences) before/after important actions.
 - For medium/large tasks, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
 - Update todos immediately after progress; mark completed upon finish.
 - Default to parallel execution for independent operations; use sequential steps only when dependencies exist.
 
 ## Step 1: Gather Context (minimal)
+
 - Ask for feature name if not provided (must be kebab-case).
 - **Load template:** Read `docs/ai/testing/feature-template.md` to understand required structure.
-- Then locate docs by convention:
-  - Planning: `docs/ai/planning/feature-{name}.md`
-  - Implementation (optional): `docs/ai/implementation/feature-{name}.md`
-- **Detect test framework:** Check `package.json` and project structure to identify test framework (Vitest, Jest, Mocha, pytest, etc.). Auto-detect from `package.json` first; if no test runner found, create skeleton test and report missing runner.
-- **Load standards:** Read `docs/ai/project/PROJECT_STRUCTURE.md` for test file placement rules
-- **Load conventions:** Read `docs/ai/project/CODE_CONVENTIONS.md` for coding standards
+- **Load planning doc:** Read `docs/ai/planning/feature-{name}.md` for:
+  - Acceptance criteria (test alignment)
+  - Implementation plan (files to test)
+  - Functions/components that need coverage
+- **Detect test framework:** Check `package.json` to identify test framework (Vitest, Jest, Mocha, pytest, etc.). If no test runner found, create skeleton test and report missing runner.
+- **Load standards:**
+  - `docs/ai/project/PROJECT_STRUCTURE.md` for test file placement rules
+  - `docs/ai/project/CODE_CONVENTIONS.md` for coding standards
 
-Always align test cases with acceptance criteria from the planning doc. If implementation notes are missing, treat planning as the single source of truth.
+**Source of truth:** Planning doc acceptance criteria + actual source code implementation.
 
 ## Step 2: Scope (logic and component tests only)
+
 - **Focus on:**
   - Pure function logic: test with various input parameters (happy path, edge cases, invalid inputs)
   - Component logic: test component behavior with different props/parameters (without complex rendering)
@@ -34,161 +44,74 @@ Always align test cases with acceptance criteria from the planning doc. If imple
   - E2E flows or end-to-end user journey tests
   - Tests requiring external API calls, database connections, or network mocking
   - Performance/load testing
+- **Dependency isolation (mocking):**
+  - Mock external dependencies (API clients, database connections, file system)
+  - Mock imported utilities/hooks if they have side effects
+  - Keep internal logic unmocked (test actual implementation)
+  - Use test framework's mocking utilities (vi.mock, jest.mock, unittest.mock)
 - Keep tests simple, fast, and deterministic.
 
-## Step 3: Analyze Code to Test
-Read implementation files from `docs/ai/implementation/feature-{name}.md` or scan source code files:
-- Identify all functions/components that need testing:
-  - List each function with its signature (parameters, return type, exceptions)
-  - List each component with its props interface
-  - List each class with its methods and properties
-- For each function/component, identify:
-  - Input parameter types and possible values
-  - Expected outputs for different inputs
-  - Edge cases (null, undefined, empty, boundaries, min/max values)
-  - Error cases (invalid inputs, exceptions, error messages)
-  - Control flow branches (if/else, switch cases, loops)
-  - Mathematical properties (if applicable): commutativity, associativity, idempotency, invariants
-
-## Step 4: Generate Test Code (automatic)
-For each function/component identified:
-
-1. **Create test file** according to `PROJECT_STRUCTURE.md`:
-   - Colocated `*.spec.*` or `*.test.*` files with source, OR
-   - Under `__tests__/` or `tests/` mirroring source structure
-   - Follow naming conventions from `CODE_CONVENTIONS.md`
-
-2. **Write complete test code** with:
-   - Test framework setup (imports, describe blocks, test utilities)
-   - Multiple test cases per function/component:
-     - **Happy path**: normal parameters → expected output
-     - **Edge cases**: empty/null/undefined inputs, boundary values (min/max, 0, -1, empty strings/arrays)
-     - **Parameter combinations**: systematically test different combinations of parameters (cartesian product when practical)
-     - **Error cases**: invalid inputs, exceptions, error messages
-     - **Type safety**: wrong types, missing properties, extra properties
-     - **Property-based**: verify mathematical properties if applicable
-   - Clear, descriptive test names describing what is being tested
-   - Assertions using appropriate test framework syntax
-
-3. **Focus on logic testing:**
-   - For functions: test return values, side effects (if any), error handling
-   - For components: test output/logic with different props (avoid complex rendering - use lightweight snapshots or logic checks)
-   - For classes: test methods independently with various inputs
-   - Test parameter combinations systematically
-
-4. **Generate edge cases systematically:**
-   - For each parameter, generate: null, undefined, empty, zero, negative, max/min values
-   - Test type mismatches: wrong types, missing required properties
-   - Test boundary conditions: off-by-one errors, overflow/underflow
-
-5. **Property-based testing (when applicable):**
-   - Identify mathematical/algorithmic properties
-   - Generate property-based tests: commutativity, associativity, idempotency, invariants
-   - Test with random inputs following constraints
-
-**Example test structure:**
-```javascript
-import { describe, it, expect } from 'vitest';
-import { functionToTest } from './source-file';
-
-describe('functionToTest', () => {
-  it('should return correct value with normal parameters', () => {
-    // Test with standard inputs
-  });
-  
-  it('should handle edge case with empty input', () => {
-    // Test boundary
-  });
-  
-  it('should handle null input', () => {
-    // Test null handling
-  });
-  
-  it('should handle different parameter combinations', () => {
-    // Test various param combinations
-  });
-  
-  it('should throw error with invalid input', () => {
-    // Test error handling
-  });
-  
-  it('should maintain idempotency property', () => {
-    // Property-based test
-  });
-});
-```
-
-## Step 5: Run Tests with Logging (automatic)
-After generating test code:
-
-1. **Execute test command** based on detected framework (use non-interactive flags):
-   - Vitest: `npm test` or `npx vitest run --run`
-   - Jest: `npm test` or `npx jest --ci`
-   - Mocha: `npm test` or `npx mocha --reporter spec`
-   - pytest: `pytest` or `python -m pytest -v`
-   - Other: detect from `package.json` scripts, add `--no-interactive` or equivalent flags
-
-2. **Capture and display output** in terminal with detailed logging:
-   - Show test execution progress (which tests are running)
-   - Show test results (pass/fail) for each test case with execution time
-   - Show test summary (total tests, passed, failed, skipped)
-   - Show any error messages, stack traces, or assertion failures for failures
-   - Show coverage report if available (lines, branches, functions coverage)
-   - Format output clearly for readability
-
-3. **Log format example:**
-   ```
-   === Running tests for feature: {name} ===
-   
-   RUN  test-file-1.spec.js
-     ✓ should handle normal case (2ms)
-     ✓ should handle edge case (1ms)
-     ✗ should handle invalid input (3ms)
-       
-       Error: Expected error to be thrown
-       at test-file-1.spec.js:25
-       
-     ✓ should handle parameter combinations (5ms)
-     ✓ should maintain property (1ms)
-   
-   Test Files:  1 passed | 0 failed | 1 total
-   Tests:       4 passed | 1 failed | 5 total
-   Time:        0.012s
-   
-   Coverage:
-   - Lines: 82% (lines covered / total lines)
-   - Branches: 75% (branches covered / total branches)
-   - Functions: 90% (functions covered / total functions)
-   ```
-
-4. **If tests fail:**
-   - Analyze failure reason from logs
-   - Fix test code or implementation as needed
-   - Re-run tests until all pass
-   - Update implementation doc if code changes were needed
-
-## Step 6: Coverage Gap Analysis (automatic)
-After initial test generation and execution:
-
-1. **Analyze coverage report:**
-   - Identify untested branches/conditions
-   - Identify untested lines/paths
-   - Identify untested functions/methods
-
-2. **Generate additional tests automatically:**
-   - For each uncovered branch: create test case
-   - For each uncovered line: ensure it's reachable by existing tests or add new test
-   - For each uncovered function: create test cases
-
-3. **Re-run tests and verify coverage:**
-   - Execute tests again with coverage
-   - Verify coverage targets are met (default: 80% lines, 70% branches)
-   - Continue generating tests until targets are met or all practical cases are covered
-
-## Step 7: Update Testing Doc
+## Step 3: Analyze Code & Generate Tests (automatic)
+
+**Analyze implementation:**
+- Read files from `docs/ai/implementation/feature-{name}.md` or scan source
+- Identify functions/components: signatures, parameters, return types, exceptions
+- Map: input types → expected outputs → edge cases → error cases
+
+**Generate test files:**
+- Create test file per `PROJECT_STRUCTURE.md` (colocated `*.spec.*` or `__tests__/`)
+- Follow naming conventions from `CODE_CONVENTIONS.md`
+
+**Test coverage strategy:**
+- **Happy path**: normal parameters → expected output
+- **Edge cases**: null, undefined, empty, boundaries (min/max, 0, -1)
+- **Parameter combinations**: systematically test input variations
+- **Error handling**: invalid inputs, exceptions, error messages
+- **Type safety**: wrong types, missing properties
+- **Property-based** (if applicable): commutativity, associativity, idempotency
+
+**For complex test suites (>15 test cases):**
+- Use Task tool with `subagent_type='general-purpose'`
+- Task prompt: "Generate comprehensive test cases for [function] covering happy path, edge cases, error handling, and parameter combinations"
+
+## Step 4: Run Tests with Logging (automatic)
+
+**Execute test command** (non-interactive):
+- Vitest: `npx vitest run --passWithNoTests`
+- Jest: `npx jest --ci --passWithNoTests`
+- Mocha: `npx mocha --reporter spec`
+- pytest: `pytest -v --tb=short`
+
+**Display output:**
+- Test execution progress and results (pass/fail, timing)
+- Test summary (total/passed/failed/skipped)
+- Error messages and stack traces for failures
+- Coverage report (lines, branches, functions %)
+
+**If tests fail:**
+- Analyze failure reason (test logic vs implementation bug)
+- **Fix test logic** if test expectations are incorrect
+- **Report implementation bug** if source code violates acceptance criteria (do NOT auto-fix source code)
+- Re-run tests after fixing test logic
+- Update testing doc with results
+
+## Step 5: Coverage Gap Analysis (automatic)
+
+**Analyze coverage report:**
+- Identify untested branches/lines/functions
+
+**Generate additional tests:**
+- Create test cases for uncovered branches/lines/functions
+- Re-run tests with coverage
+- Verify targets met (default: 80% lines, 70% branches)
+- Continue until targets met or all practical cases covered
+
+## Step 6: Update Testing Doc
+
 Use structure from `docs/ai/testing/feature-template.md` to populate `docs/ai/testing/feature-{name}.md`.
 
 Fill with:
+
 - **Test Files Created**: List all test files generated with paths
 - **Test Cases Summary**: Brief summary of what was tested (function/component + key scenarios)
   - Happy path scenarios
@@ -205,14 +128,17 @@ Fill with:
 
 Ensure all required sections from template are present. Keep the document brief and actionable.
 
-## Step 8: Verify Tests Pass
+## Step 7: Verify Tests Pass
+
 - Ensure all generated tests pass successfully
 - Ensure coverage targets are met (default: 80% lines, 70% branches)
-- If any test fails, debug and fix issues
-- Update implementation doc if code changes were needed
-- Re-run tests to confirm fixes
+- If any test fails:
+  - Debug test logic and fix test expectations
+  - **OR** report implementation bug to user (if source code violates acceptance criteria)
+- Re-run tests after fixing test logic
 
 ## Notes
+
 - Tests should be simple enough to run quickly and verify logic correctness
 - Focus on catching logic errors and edge cases through systematic parameter variation
 - Avoid complex test setup or mocking unless necessary for logic isolation
@@ -220,5 +146,10 @@ Ensure all required sections from template are present. Keep the document brief
 - Test execution must show clear, detailed logging in terminal
 - AI excels at: edge case generation, parameter combinations, property-based testing, coverage analysis
 - Keep tests deterministic (avoid external dependencies, random values without seeds, time-dependent logic)
-- Creates test files only; does not edit non-test source files.
-- Idempotent: safe to re-run; appends entries or updates test doc deterministically.
+
+**Scope boundaries:**
+- **Creates:** Test files only (*.spec.*, *.test.*)
+- **Modifies:** Test files only when fixing test logic
+- **Does NOT edit:** Non-test source files (implementation code)
+- **If implementation bug found:** Report to user; do NOT auto-fix source code
+- Idempotent: safe to re-run; updates test doc deterministically