ai-workflow-init 3.2.3 → 3.6.0

package/.cursor/commands/check-implementation.md

@@ -3,29 +3,141 @@ name: check-implementation
 description: Validates implementation against planning doc.
 ---
 
-Compare current implementation against planning doc.
+Compare current implementation against planning doc to ensure all requirements are met and completed tasks have corresponding code.
 
 ## Workflow Alignment
 
 - Provide brief status updates (1–3 sentences) before/after important actions.
+- For medium/large validations, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
+- Update todos immediately after progress; mark completed upon finish.
 - Provide a high-signal summary at completion highlighting key mismatches and next steps.
 
-1. Ask me for:
+---
+
+## Step 1: Load Planning Doc
+
+**Tools:**
+- ask user for clarification if feature name not provided
+- read `docs/ai/planning/feature-{name}.md`
+
+**Purpose:** Load planning doc to extract:
+- Acceptance criteria (Given-When-Then scenarios)
+- Implementation plan tasks (with `[ ]` or `[x]` status)
+- Expected file changes mentioned in tasks
+
+**Error handling:**
+- Planning doc not found: Cannot proceed, notify user and exit
+- Invalid format: Parse available content, warn about missing sections
+- No completed tasks: Nothing to validate, notify user
+
+---
+
+## Step 2: Discover Implementation Files
+
+**Strategy (in order):**
+1. Extract file paths from planning doc task list
+2. If no file paths found: Read implementation doc `docs/ai/implementation/feature-{name}.md`
+3. If no implementation doc: Use git diff to find changed files
+4. If no git changes: Ask user for file paths
 
-- Feature name (if not provided)
-- Then locate planning doc by feature name:
-  - Planning: `docs/ai/planning/feature-{name}.md`
+**Tools:**
+- read `docs/ai/planning/feature-{name}.md` - extract file mentions
+- read `docs/ai/implementation/feature-{name}.md` - fallback
+- run command: `git diff --name-only main` - find changed files
+- search for files matching `src/**/*.{js,ts,py}` - last resort full scan
+- AskUserQuestion - ask user if all else fails
 
-2. Validation Scope (no inference):
+**Output:** List of files to validate against planning doc
 
-- Verify code follows the acceptance criteria from the planning doc
-- Verify code matches the steps/changes in the implementation plan phases
-- Check that completed tasks (marked `[x]`) have corresponding code changes
-- Do NOT invent or infer alternative logic beyond what the docs specify
+**Error handling:**
+- No files found: Cannot validate, notify user
+- File paths invalid: Skip broken paths, continue with valid ones
+- Git not available: Fall back to asking user
+
+---
+
+## Step 3: Validate Implementation vs Planning
+
+**Automated process:**
+- Use workspace search and analysis to accomplish this task
+
+**Alternative approach:** If Explore agent unavailable, manually:
+1. Read each file from Step 2
+2. For each completed task `[x]`, search for related code
+3. Compare against acceptance criteria
+4. Document mismatches
+
+**Validation scope (no inference):**
+- Verify code follows the acceptance criteria from planning doc
+- Verify code matches the implementation plan task descriptions
+- Check completed tasks `[x]` have corresponding code changes
+- **Do NOT** invent or infer alternative logic beyond what docs specify
+
+**Error handling:**
+- Agent timeout: Retry with , then fall back to manual
+- No completed tasks: Report "Nothing to validate"
+- Ambiguous results: Flag for manual review
+
+---
 
-3. Output
+## Step 4: Generate Validation Report
+
+**Report structure:**
+
+### Summary
+- Total tasks in planning: `X`
+- Completed tasks `[x]`: `Y`
+- Validated successfully: `Z`
+- Mismatches found: `N` (critical: `C`, minor: `M`)
+- Missing implementations: `P`
+
+### Completed Tasks Without Implementation
+
+For each task marked `[x]` but code not found:
+
+```
+- [ ] Task: [Task description from planning]
+  - Expected file: [file mentioned in task or "not specified"]
+  - Status: Missing or Partial
+  - Action: Implement missing code or update task to [ ]
+```
+
+### Mismatches (Code ≠ Planning)
+
+For each discrepancy between planning and code:
+
+```
+- File: path/to/file.ext
+  - Planning requirement: [what planning doc says]
+  - Current implementation: [what code actually does]
+  - Severity: Critical / Minor
+  - Action: Update code to match planning OR revise planning doc
+```
+
+### Acceptance Criteria Status
+
+For each acceptance criteria:
+
+```
+- [x] AC1: [Description] → ✅ Verified (code satisfies criteria)
+- [ ] AC2: [Description] → ❌ Not implemented
+- [x] AC3: [Description] → ⚠️ Partial (missing edge cases)
+```
+
+### Next Steps (Prioritized)
+
+1. **Critical issues** (blocking):
+   - [ ] Fix mismatch in [file]: [specific issue]
+   - [ ] Implement missing task: [task name]
+
+2. **Minor issues** (non-blocking):
+   - [ ] Address partial implementation in [file]
+   - [ ] Update planning doc to reflect changes
+
+3. **Follow-up**:
+   - [ ] Re-run `/check-implementation` after fixes
+   - [ ] Run `/code-review` for standards compliance
+
+---
 
-- List concrete mismatches between code and planning doc
-- List missing pieces the planning doc requires but code lacks
-- List tasks marked complete `[x]` but code not implemented
-- Short actionable next steps
+**Note:** This validation checks implementation completeness, not code quality. Run `/code-review` separately for standards compliance.

package/.cursor/commands/code-review.md

@@ -1,80 +1,186 @@
+---
+name: code-review
+description: Performs a local code review strictly for standards conformance.
+---
+
 You are helping me perform a local code review **before** I push changes. This review is restricted to standards conformance only.
 
 ## Workflow Alignment
+
 - Provide brief status updates (1–3 sentences) before/after important actions.
+- For medium/large reviews, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
+- Update todos immediately after progress; mark completed upon finish.
 - Provide a high-signal summary at completion highlighting key findings and impact.
 
-## Step 1: Gather Context (minimal)
-- Ask for feature name if not provided (must be kebab-case).
-- Then locate and read:
-  - Planning doc: `docs/ai/planning/feature-{name}.md` (for file list context only)
-  - Implementation doc: `docs/ai/implementation/feature-{name}.md` (for file list context only)
-
-## Step 2: Standards Focus (only)
-- Load project standards:
-  - `docs/ai/project/CODE_CONVENTIONS.md`
-  - `docs/ai/project/PROJECT_STRUCTURE.md`
-- Review code strictly for violations against these two documents.
-- **Do NOT** provide design opinions, performance guesses, or alternative architectures.
-- **Do NOT** infer requirements beyond what standards explicitly state.
-
-### Automated Checks (recommended)
-- Detect tools from project config and run non-interactive checks:
-  - JS/TS: `npx eslint .` (or `pnpm eslint .`), consider `--max-warnings=0`; type checks with `npx tsc --noEmit`
-  - Python: `ruff .` or `flake8 .`; type checks with `mypy .` or `pyright`
-  - Go: `golangci-lint run` or `go vet ./...`
-  - Rust: `cargo clippy -- -D warnings`
-  - Java: `./gradlew check` or `mvn -q -DskipTests=false -Dspotbugs.failOnError=true verify`
-- Use results to focus the review; still report only clear violations per standards.
-
-## Step 3: File-by-File Review (standards violations only)
-For every relevant file, report ONLY standards violations per the two docs above. Do not assess broader design or run git commands.
-
-## Step 4: Cross-Cutting Concerns (standards only)
-- Naming consistency and adherence to CODE_CONVENTIONS
-- Structure/module boundaries per PROJECT_STRUCTURE
-
-### Standards Conformance Report (required)
-- After reviewing `CODE_CONVENTIONS.md` and `PROJECT_STRUCTURE.md`, list violations in this exact format:
+---
+
+
+## Step 1: Determine Review Scope & Gather Context
+
+**Scope detection (in order):**
+1. If feature name provided: Review files from planning/implementation docs
+2. If no feature name but git repo: Review changed files from git diff
+3. If no git changes: Ask user for file paths or review entire src/
+
+**Tools:**
+- ask user for clarification if feature name not provided
+- read `docs/ai/planning/feature-{name}.md` for file list
+- read `docs/ai/implementation/feature-{name}.md` for file list
+- run command: `git diff --name-only HEAD` to find changed files (fallback)
+- search for files matching `src/**/*.{js,ts,py,go,rs,java}` for full project scan (last resort)
+
+**Error handling:**
+- Feature docs not found: Fall back to git diff
+- Git not available: Ask user for file paths
+- No files to review: Notify user and exit
+
+## Step 2: Load Standards & Run Quality Checks
+
+**Tools:**
+- read `docs/ai/project/CODE_CONVENTIONS.md`
+- read `docs/ai/project/PROJECT_STRUCTURE.md`
+
+**Standards review scope:**
+- Review code strictly for violations against CODE_CONVENTIONS and PROJECT_STRUCTURE only
+- **Do NOT** provide design opinions, performance guesses, or alternative architectures
+- **Do NOT** infer requirements beyond what standards explicitly state
+
+**Quality checks (automated):**
+
+Follow step by step in `.claude/skills/quality/code-check/SKILL.md` for automated validation:
+- **Linting**: Code style and best practices (ESLint, Ruff, golangci-lint, Clippy)
+- **Type checking**: Type safety validation (tsc, MyPy, Pyright)
+- **Build verification**: Compilation and packaging checks
+
+See Notes section for manual commands by language if needed.
+
+Use results to focus manual review; report only clear violations per standards.
+
+**Error handling:**
+- Standards docs not found: Notify user, cannot proceed without standards
+- Skill not available: Fall back to manual commands (see Notes)
+- Quality checks fail: Report errors as violations, fix and retry up to 3 times
+
+## Step 3: Scan for Standards Violations
+
+**Automated process:**
+- Use workspace search and analysis to accomplish this task
+    - Import order and grouping
+    - Folder structure and module boundaries
+    - Test placement and naming
+    - Cross-file consistency (naming patterns, module boundaries)
+    Return violations with file:line, rule violated, and brief description."
+)
+
+**Alternative approach:** If Explore agent unavailable, manually Read each file and check against standards.
+
+**Review scope:** Files from Step 1 only. Report ONLY standards violations, not design opinions.
+
+**Output format (Standards Conformance Report):**
+
 ```
 - path/to/file.ext — [Rule]: short description of the violated rule
 ```
-- Only include clear violations. Group similar violations by file when helpful.
 
-## Step 5: Summarize Findings (rules-focused)
-Provide results in this structure:
-```
-### Summary
-- Blocking issues: [count]
-- Important follow-ups: [count]
-- Nice-to-have improvements: [count]
+Only include clear violations. Group similar violations by file when helpful.
 
-Severity criteria:
-- Blocking: Violates CODE_CONVENTIONS or PROJECT_STRUCTURE causing build/test failure, security risk, or clear architectural breach.
-- Important: Violations that don't break build but degrade maintainability/performance or developer ergonomics.
-- Nice-to-have: Style/consistency improvements with low impact.
+**Error handling:**
+- Agent timeout: Retry once with , then fall back to manual review
+- No violations found: Report clean bill of health
+- Too many violations (>50): Group by file and summarize patterns
 
-### Detailed Notes
-1. **[File or Component]**
-   - Issue/Observation: ...
-   - Impact: (blocking / important / nice-to-have)
-   - Rule violated: [Rule name from CODE_CONVENTIONS or PROJECT_STRUCTURE]
-   - Recommendation: Fix to comply with [Rule]
+## Step 4: Summarize Findings (rules-focused)
 
-2. ... (repeat per finding)
+**Report structure:**
 
-### Recommended Next Steps
-- [ ] Address blocking issues
-- [ ] Fix important violations
-- [ ] Consider nice-to-have improvements
-- [ ] Re-run code review command after fixes
-```
+1. **Summary**: Violation counts by severity (Blocking / Important / Nice-to-have)
+2. **Detailed Findings**: For each violation:
+   - File path and line number
+   - Rule violated (from CODE_CONVENTIONS or PROJECT_STRUCTURE)
+   - Brief description and impact
+   - Recommended fix
+3. **Next Steps**: Prioritized action items
+
+**Severity criteria:**
+- **Blocking**: Build/test failure, security risk, architectural breach
+- **Important**: Degrades maintainability, not immediately breaking
+- **Nice-to-have**: Style/consistency improvements, low impact
+
+(See Notes for detailed report format example)
+
+## Step 5: Final Checklist (rules-focused)
 
-## Step 6: Final Checklist (rules-focused)
 Confirm whether each item is complete (yes/no/needs follow-up):
+
 - Naming and formatting adhere to CODE_CONVENTIONS
 - Structure and boundaries adhere to PROJECT_STRUCTURE
 
 ---
 
+## Notes
+
+### Automated Checks Complete List (Step 2)
+
+**JavaScript/TypeScript:**
+- Linting: `npx eslint . --max-warnings=0` or `pnpm eslint .`
+- Type checking: `npx tsc --noEmit`
+- Alternative linters: `npx biome check .`
+
+**Python:**
+- Linting: `ruff check .` or `flake8 .`
+- Type checking: `mypy .` or `pyright`
+- Formatting: `ruff format --check .` or `black --check .`
+
+**Go:**
+- Linting: `golangci-lint run`
+- Vet: `go vet ./...`
+- Formatting: `gofmt -l .`
+
+**Rust:**
+- Linting: `cargo clippy -- -D warnings`
+- Formatting: `cargo fmt --check`
+
+**Java:**
+- Gradle: `./gradlew check`
+- Maven: `mvn -q -DskipTests=false -Dspotbugs.failOnError=true verify`
+
+### Detailed Report Format Example (Step 5)
+
+```markdown
+## Code Review Summary
+
+### Standards Compliance Overview
+- ✅ Blocking issues: 0
+- ⚠️  Important follow-ups: 3
+- 💡 Nice-to-have improvements: 5
+
+### Detailed Findings
+
+#### 1. src/services/user-service.ts
+- **Issue**: Function name uses snake_case instead of camelCase
+- **Rule violated**: CODE_CONVENTIONS > Naming > Functions must use camelCase
+- **Impact**: Important (consistency)
+- **Recommendation**: Rename `get_user_by_id` → `getUserById`
+
+#### 2. src/utils/helpers.ts
+- **Issue**: Missing index.ts export
+- **Rule violated**: PROJECT_STRUCTURE > Module boundaries > All utils must export via index
+- **Impact**: Important (architecture)
+- **Recommendation**: Add export to `src/utils/index.ts`
+
+#### 3. tests/unit/user.spec.ts
+- **Issue**: Test file placed in wrong directory
+- **Rule violated**: CODE_CONVENTIONS > Tests > Colocate with source files
+- **Impact**: Nice-to-have (organization)
+- **Recommendation**: Move to `src/services/user-service.spec.ts`
+
+### Recommended Next Steps
+- [ ] Fix 3 important violations (estimated 15 minutes)
+- [ ] Address 5 nice-to-have improvements (estimated 30 minutes)
+- [ ] Re-run `/code-review` after fixes
+- [ ] Run automated checks: `npm run lint && npm run type-check`
+```
+
+---
+
 Let me know when you're ready to begin the review.