5-phase-workflow 1.6.0 → 1.7.1

package/README.md

@@ -10,7 +10,7 @@ The **5-Phase Workflow** is a structured approach to feature development that br
 2. **Implementation Planning** - Map requirements to technical components
 3. **Orchestrated Implementation** - Execute with state tracking and parallel processing
 4. **Verify Implementation** - Automated verification of completeness and correctness
-5. **Code Review** - AI-powered review and quality improvements
+5. **Code Review** - AI-powered review, findings annotation, and fix application
 
 ## Why Use It?
 
@@ -79,6 +79,9 @@ After configuration is complete, start your first feature:
 
 # Phase 5: Review code
 /5:review-code
+
+# Phase 5b: Apply review findings (optional — if you chose "Fix later")
+/5:address-review-findings
 ```
 
 **Tip:** Running `/clear` between phases resets context and keeps conversations focused. Each phase reads necessary artifacts from previous phases, so no context is lost.
@@ -124,7 +127,8 @@ All commands are available under the `/5:` namespace:
 | `/5:plan-implementation` | 2 | Map feature to technical components |
 | `/5:implement-feature` | 3 | Execute implementation with agents |
 | `/5:verify-implementation` | 4 | Verify completeness and correctness |
-| `/5:review-code` | 5 | AI-powered code review (CodeRabbit) |
+| `/5:review-code` | 5 | AI-powered code review (Claude or CodeRabbit) |
+| `/5:address-review-findings` | 5 | Apply annotated findings and address PR comments |
 | `/5:quick-implement` | Fast | Streamlined workflow for small tasks |
 | `/5:unlock` | Utility | Remove planning guard lock |
 
@@ -223,12 +227,21 @@ Results are saved to a verification report.
 
 ### Phase 5: Code Review
 
-Automated review using CodeRabbit (if installed):
+Two commands work together to handle the review workflow:
+
+**`/5:review-code`** — runs the automated review and presents findings:
+- Supports Claude (built-in, no setup) or CodeRabbit CLI
+- Reviews staged changes, unstaged changes, or branch diff
+- Categorizes findings as Fixable, Questions, or Manual
+- Lets you fix immediately or save findings for later
 
-- Finds code smells and potential issues
-- Suggests improvements
-- Applies approved fixes
-- Re-verifies after changes
+**`/5:address-review-findings`** — applies annotated findings from a saved file:
+- Reads the `review-findings-*.md` file generated by `/5:review-code`
+- Applies `[FIX]` items, skips `[SKIP]` items, and follows `[MANUAL]` instructions
+- Optionally fetches and addresses GitHub PR review comments
+- Posts threaded replies to processed PR comments
+- Runs build, tests, and lint after applying fixes
+- Saves a summary report
 
 ## Project Structure
 
@@ -247,6 +260,7 @@ After installation, your `.claude/` directory will contain:
 │   ├── implement-feature.md
 │   ├── verify-implementation.md
 │   ├── review-code.md
+│   ├── address-review-findings.md
 │   ├── discuss-feature.md
 │   ├── quick-implement.md
 │   ├── configure.md

package/bin/install.js

@@ -41,7 +41,7 @@ function getInstalledVersion(isGlobal) {
 
   try {
     const data = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
-    return data.installedVersion;
+    return data.packageVersion;
   } catch (e) {
     return null; // Corrupted file, treat as missing
   }
@@ -386,6 +386,20 @@ function selectiveUpdate(targetPath, sourcePath) {
   log.success('Updated templates/ (workflow files only)');
 }
 
+// Ensure .5/.gitignore exists and contains .update-cache.json
+function ensureDotFiveGitignore(dataDir) {
+  const gitignorePath = path.join(dataDir, '.gitignore');
+  const entry = '.update-cache.json';
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (!content.includes(entry)) {
+      fs.appendFileSync(gitignorePath, '\n' + entry + '\n');
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, entry + '\n');
+  }
+}
+
 // Initialize version.json after successful install
 function initializeVersionJson(isGlobal) {
   const dataDir = getDataPath(isGlobal);
@@ -400,13 +414,13 @@ function initializeVersionJson(isGlobal) {
 
   const versionData = {
     packageVersion: version,
-    installedVersion: version,
     installedAt: now,
     lastUpdated: now,
     installationType: isGlobal ? 'global' : 'local'
   };
 
   fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
+  ensureDotFiveGitignore(dataDir);
   log.success('Initialized version tracking');
 }
 
@@ -486,14 +500,15 @@ function checkExistingInstallation(targetPath) {
 // Helper to show commands
 function showCommandsHelp(isGlobal) {
   log.info('Available commands:');
-  log.info('  /5:plan-feature          - Start feature planning (Phase 1)');
-  log.info('  /5:plan-implementation   - Create implementation plan (Phase 2)');
-  log.info('  /5:implement-feature     - Execute implementation (Phase 3)');
-  log.info('  /5:verify-implementation - Verify implementation (Phase 4)');
-  log.info('  /5:review-code          - Code review (Phase 5)');
-  log.info('  /5:configure            - Interactive project setup');
-  log.info('  /5:reconfigure          - Refresh docs/skills (no Q&A)');
-  log.info('  /5:unlock               - Remove planning guard lock');
+  log.info('  /5:plan-feature              - Start feature planning (Phase 1)');
+  log.info('  /5:plan-implementation       - Create implementation plan (Phase 2)');
+  log.info('  /5:implement-feature         - Execute implementation (Phase 3)');
+  log.info('  /5:verify-implementation     - Verify implementation (Phase 4)');
+  log.info('  /5:review-code               - Code review (Phase 5)');
+  log.info('  /5:address-review-findings   - Apply review findings & PR comments');
+  log.info('  /5:configure                 - Interactive project setup');
+  log.info('  /5:reconfigure               - Refresh docs/skills (no Q&A)');
+  log.info('  /5:unlock                    - Remove planning guard lock');
   log.info('');
   log.info(`Config file: ${path.join(getDataPath(isGlobal), 'config.json')}`);
 }
@@ -553,26 +568,23 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   // Update version.json
   const dataDir = getDataPath(isGlobal);
   const versionFile = path.join(dataDir, 'version.json');
+  const now = new Date().toISOString();
 
-  let versionData;
-  if (fs.existsSync(versionFile)) {
-    versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
-  } else {
-    // Legacy install, create version.json
-    versionData = {
-      installedAt: new Date().toISOString(),
-      installationType: isGlobal ? 'global' : 'local'
-    };
-  }
-
-  versionData.packageVersion = versionInfo.available;
-  versionData.installedVersion = versionInfo.available;
-  versionData.lastUpdated = new Date().toISOString();
+  const existing = fs.existsSync(versionFile)
+    ? JSON.parse(fs.readFileSync(versionFile, 'utf8'))
+    : {};
+  const versionData = {
+    packageVersion: versionInfo.available,
+    installedAt: existing.installedAt || now,
+    lastUpdated: now,
+    installationType: existing.installationType || (isGlobal ? 'global' : 'local')
+  };
 
   if (!fs.existsSync(dataDir)) {
     fs.mkdirSync(dataDir, { recursive: true });
   }
   fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
+  ensureDotFiveGitignore(dataDir);
 
   // Create features directory if it doesn't exist
   const featuresDir = path.join(dataDir, 'features');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"

package/src/agents/implementation-planner.md

@@ -21,6 +21,7 @@ HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
 - Each component in the table gets: name, action, file path, one-sentence description, complexity
 - Implementation Notes reference EXISTING pattern files, not new code
 - If a component needs more than one sentence to describe, split it into multiple components
+- Every component with action "create" that contains logic (services, controllers, repositories, hooks, utilities, helpers) MUST have a corresponding test component in the plan. Declarative components (types, interfaces, models without logic, route registrations, config files) are exempt. When uncertain, include the test.
 </constraints>
 
 <write-rules>
@@ -59,6 +60,7 @@ After writing plan.md, read it back and verify:
 3. **Scope:** Every component traces back to a requirement in feature.md — if not, remove it
 4. **Completeness:** Every functional requirement from feature.md has at least one component
 5. **Description length:** Each Description cell is one sentence. If longer, split the component.
+6. **Test coverage:** Every "create" component with logic has a corresponding test component. Declarative-only components (types, interfaces, route wiring) are exempt. If a testable component lacks a test, add one.
 
 Output the verification result before the completion message.
 </self-check>

package/src/commands/5/address-review-findings.md

@@ -0,0 +1,364 @@
+---
+name: 5:address-review-findings
+description: Applies annotated review findings and/or addresses GitHub PR review comments. Use --github to process PR comments only.
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Task, Skill, mcp__jetbrains__*
+model: sonnet
+context: fork
+user-invocable: true
+disable-model-invocation: true
+---
+
+<role>
+You are a Fix Applicator. You read annotated review findings and apply approved fixes.
+You do NOT review code. You do NOT implement new features. You do NOT refactor beyond what findings specify.
+You apply fixes exactly as described in the findings file and confirmed by the user.
+You follow the exact step sequence below. Do not skip or reorder steps.
+</role>
+
+# Address Review Findings (Phase 5b)
+
+This command reads a `review-findings-*.md` file produced by `/5:review-code`, applies all `[FIX]` items, and optionally fetches and addresses GitHub PR review comments.
+
+## Options
+
+- **`--github`** — Skip local findings entirely. Only fetch and process GitHub PR review comments for the current branch.
+
+## Process
+
+### Step 1: Determine Mode and Feature Context
+
+Check if the command was invoked with `--github`.
+
+- **`--github` mode:** Skip Steps 2 and 3. Proceed directly to Step 4 (GitHub PR Integration), which is now mandatory — do not ask the user whether to include PR comments.
+- **Normal mode:** Follow all steps in order.
+
+---
+
+Regardless of mode, read `.5/features/*/state.json` using Glob to find all state files. Select the one with the most recent `startedAt` (or `lastUpdated` if present).
+
+Read `.5/features/*/state.json` using Glob to find all state files. Select the one with the most recent `startedAt` (or `lastUpdated` if present).
+
+Extract:
+- `feature` — feature directory name
+- `ticket` — ticket ID
+- Feature directory path: `.5/features/{feature}/`
+
+Also read `.5/config.json` if present. Extract `git.branch` if set.
+
+If no state.json files found, ask user via AskUserQuestion: "Which feature are you working on?" — prompt them to enter the feature name manually.
+
+### Step 2: Locate Review Findings File *(skipped in --github mode)*
+
+Use Glob to find `review-findings-*.md` in the feature directory:
+```
+.5/features/{feature}/review-findings-*.md
+```
+
+- **Multiple files found:** Use the one with the most recent timestamp in the filename (format `YYYYMMDD-HHmmss`).
+- **One file found:** Use it.
+- **No file found:** Ask via AskUserQuestion:
+  - "No review-findings file found. How would you like to proceed?"
+  - Options: "Proceed with GitHub PR comments only" / "Stop — I'll run /5:review-code first"
+  - If "Stop", exit with: `Run /5:review-code to generate a findings file first.`
+  - If "GitHub PR only", skip to Step 4.
+
+#### Parse Findings
+
+Read the findings file. For each finding block, extract:
+- File path
+- Line number
+- Category and severity
+- Description
+- Suggested fix
+- Custom instructions (if MANUAL)
+- **Action:** `[FIX]` / `[SKIP]` / `[MANUAL]`
+
+Collect three lists:
+- `to_fix` — all `[FIX]` items
+- `to_skip` — all `[SKIP]` items
+- `to_manual` — all `[MANUAL]` items
+
+### Step 3: Present Findings Summary *(skipped in --github mode)*
+
+Display a summary to the user:
+
+```
+Review Findings Summary:
+- To fix (automatic):  {N}
+- To skip:             {N}
+- Manual (custom fix): {N}
+
+Fixes to apply:
+{#} {file}:{line} — {description}
+
+Manual items:
+{#} {file}:{line} — {description}
+  Instructions: {custom instructions}
+
+Skipped items:
+{#} {file}:{line} — {description}
+```
+
+### Step 4: GitHub PR Integration
+
+Check if a PR exists for the current branch:
+```bash
+gh pr list --head "$(git branch --show-current)" --json number,url,title --limit 1
+```
+
+If the `gh` command is not available or returns an error:
+- In `--github` mode: report the error and STOP — PR comments are the only goal.
+- In normal mode: skip this step silently.
+
+**If no PR is found:**
+- In `--github` mode: report "No open PR found for the current branch." and STOP.
+- In normal mode: skip this step.
+
+**If a PR is found in normal mode:** Ask via AskUserQuestion:
+- "A PR was found: {title} ({url}). Include PR review comments?"
+- Options: "Yes, include PR comments" / "No, local findings only"
+- If "No": skip the rest of this step.
+
+**If a PR is found in `--github` mode:** proceed immediately without asking.
+
+**Fetch PR comments:**
+
+Fetch review comments (inline code comments):
+```bash
+gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate
+```
+
+Fetch issue comments (general PR comments):
+```bash
+gh api repos/{owner}/{repo}/issues/{number}/comments --paginate
+```
+
+To get `{owner}` and `{repo}`, run:
+```bash
+gh repo view --json owner,name
+```
+
+Spawn a sonnet agent to analyze PR comments:
+
+```
+Task tool call:
+  subagent_type: general-purpose
+  model: sonnet
+  description: "Analyze PR review comments"
+  prompt: |
+    Analyze these GitHub PR review comments and categorize each one.
+
+    ## Local Findings (already being addressed)
+    {list of file:line:description from to_fix + to_skip + to_manual — or "none" in --github mode}
+
+    ## PR Review Comments
+    {raw JSON of review comments}
+
+    ## PR Issue Comments
+    {raw JSON of issue comments}
+
+    ## Instructions
+    For each PR comment, categorize it as:
+    - **actionable_fix**: Clear code change needed, not already covered by local findings
+    - **duplicate**: Same file + similar issue already in local findings
+    - **manual**: Requires judgment or discussion, not a simple code fix
+    - **skip**: Automated, bot-generated, resolved, or not actionable
+
+    For duplicates, note which local finding covers it.
+
+    ## Output Format
+    Return a structured list:
+
+    ---PR-COMMENTS---
+    {id} | {file}:{line} | {category} | {description} | {duplicate_of or "none"}
+    ---END-PR-COMMENTS---
+
+    Rules:
+    - DO NOT apply fixes
+    - DO NOT interact with user
+    - Include every comment in the output
+```
+
+Parse the `---PR-COMMENTS---` block. Collect:
+- `pr_to_fix` — actionable_fix items
+- `pr_duplicates` — duplicate items
+- `pr_manual` — manual items
+
+**Present PR comment summary to user:**
+```
+PR Review Comments:
+- Actionable (new): {N}
+- Duplicates (covered by local findings): {N}
+- Manual/Discussion: {N}
+- Skipped (bot/resolved): {N}
+
+Actionable PR comments:
+{#} {file}:{line} — {description}
+
+Manual PR comments:
+{#} {file}:{line} — {description}
+```
+
+Ask via AskUserQuestion for each actionable PR comment batch:
+- "Apply actionable PR fixes?" Options: "All" / "None" / "Let me choose"
+- If "Let me choose": present each one and ask Fix / Skip per item.
+
+Collect final `pr_approved_fixes` list.
+
+### Step 5: Apply Fixes
+
+Apply fixes in this order: local `[FIX]` items first, then local `[MANUAL]` items, then approved PR fixes.
+
+#### Grouping Strategy
+
+Group fixes by target file. For each file:
+- **1–3 fixes:** Apply directly using Read + Edit tools (bottom-to-top by line number to preserve positions)
+- **4+ fixes or complex logic:** Spawn a haiku or sonnet agent per file
+
+#### Direct Application (1–3 fixes per file)
+
+For each fix:
+1. Read the file
+2. Apply the change using Edit tool
+3. Track result: APPLIED or FAILED
+
+Apply from highest line number to lowest within each file to avoid line offset shifts.
+
+#### Agent Application (4+ fixes per file)
+
+```
+Task tool call:
+  subagent_type: general-purpose
+  model: {haiku for simple | sonnet for complex}
+  description: "Apply fixes to {file-path}"
+  prompt: |
+    Apply these fixes to the file below. Apply all fixes.
+    Work from the highest line number to the lowest to avoid line offset issues.
+
+    ## File
+    {file-path}
+
+    ## Fixes to Apply
+    {#1} Line {N}: {description}
+    Fix: {suggested fix or custom instructions}
+
+    {#2} Line {N}: {description}
+    Fix: {suggested fix or custom instructions}
+
+    ## Instructions
+    1. Read the file first
+    2. Apply each fix using Edit tool
+    3. Apply from highest line to lowest
+    4. Do NOT introduce unrelated changes
+    5. Report each fix as APPLIED or FAILED with reason
+
+    ## Output Format
+    {#} APPLIED | {description}
+    {#} FAILED | {description} | {reason}
+```
+
+Collect all APPLIED/FAILED results.
+
+#### Apply [MANUAL] Items
+
+For each `[MANUAL]` item with custom instructions:
+- Read the file
+- Apply the custom instructions using Edit tool
+- If instructions are ambiguous, spawn a sonnet agent with the full context
+
+### Step 6: Reply to GitHub PR Comments
+
+For each PR comment that was processed (from `pr_approved_fixes`, `pr_duplicates`, and `pr_manual`):
+
+Post a reply using the GitHub API:
+
+**For review comments (inline):**
+```bash
+gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
+  --method POST \
+  --field body="{reply text}"
+```
+
+**For issue comments (general):**
+```bash
+gh api repos/{owner}/{repo}/issues/{number}/comments \
+  --method POST \
+  --field body="{reply text}"
+```
+
+Reply templates:
+- **Fixed:** `Applied fix: {description}. Will be included in the next push.`
+- **Skipped:** `Reviewed — not addressing: {reason if known, else "will handle separately"}`
+- **Duplicate (applied):** `Covered by local review findings — fix applied.`
+- **Duplicate (skipped):** `Covered by local review findings — marked as skip.`
+- **Manual/Discussion:** `Noted. This requires manual review: {description}`
+
+If `gh api` is unavailable or fails, log the failure and continue. Do NOT abort for reply failures.
+
+### Step 7: Verification
+
+After all fixes are applied:
+
+1. **Build:** Use the `/build-project` skill: `Skill tool: skill="build-project", args="target=compile"`
+2. **Test:** Use the `/run-tests` skill: `Skill tool: skill="run-tests", args="target=all"`
+3. **Lint:** Check for any lint warnings and errors
+
+If build fails:
+- Report which file(s) were modified and likely caused the failure
+- Ask via AskUserQuestion: "Build failed after applying fixes. What would you like to do?"
+  - Options: "Show me the error and I'll fix manually" / "Revert the last fix and retry"
+  - If revert: re-read the original file content (from git: `git show HEAD:{file}`) and restore it, then re-run build
+
+### Step 8: Save Summary Report
+
+Write `.5/features/{feature}/review-summary-{YYYYMMDD-HHmmss}.md`.
+
+Use the template structure from `.claude/templates/workflow/REVIEW-SUMMARY.md`. Include:
+
+```markdown
+# Code Review Summary
+
+**Reviewed:** {feature} — findings from {findings-filename}
+**Timestamp:** {ISO-timestamp}
+**User Decisions:** Applied {N} fixes, skipped {N}, {N} manual
+
+## Summary
+
+- **Local Fixes Applied:** {N}
+- **Local Fixes Skipped:** {N}
+- **Manual Items Applied:** {N}
+- **PR Comments Fixed:** {N}
+- **PR Comments Skipped:** {N}
+- **Build:** {passed/failed}
+- **Tests:** {passed/failed}
+
+## Applied Fixes
+...
+
+## Skipped Items
+...
+
+## Manual Items
+...
+
+## PR Comment Replies
+...
+```
+
+### Step 9: Final Output
+
+Output exactly:
+
+```
+Review findings addressed.
+
+Local findings:       {N fixed / N skipped / N manual  — or "skipped (--github mode)"}
+PR comments:          {N fixed / N skipped / N replied  — or "none"}
+
+Build: {passed/failed/skipped}
+Tests: {passed/failed/skipped}
+
+Summary saved at .5/features/{feature}/review-summary-{timestamp}.md
+```
+
+STOP. Do not implement new features. Your job is done.

package/src/commands/5/configure.md

@@ -4,6 +4,7 @@ description: Configures the project. Analyzes project, gathers preferences, writ
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 context: inherit
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Configure (Phase 1 - Plan Feature for Project Configuration)

package/src/commands/5/discuss-feature.md

@@ -4,6 +4,7 @@ description: Discusses and refines an existing feature specification through ite
 allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
 context: inherit
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Discuss Feature Specification (Phase 1 - Optional Iteration)

package/src/commands/5/implement-feature.md

@@ -4,6 +4,7 @@ description: Executes an implementation plan by delegating to agents. Phase 3 of
 allowed-tools: Task, Read, Write, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList
 context: fork
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Implement Feature (Phase 3)
@@ -236,6 +237,16 @@ Update `verificationResults` in state.json:
 ```
 Also update `lastUpdated`.
 
+**4b. Check test file creation**
+
+For each component in the plan that appears to be a test file (filename contains `.test.`, `.spec.`, `test_`, or lives in a `__tests__`/`tests` directory):
+- Verify the file was actually created using Glob
+- If a planned test file was NOT created, record it as a verification warning
+
+For each non-test component with action "create" that contains logic:
+- Check if its corresponding test component exists in the plan
+- If a test was planned but is in `failedAttempts`, flag it prominently
+
 **MANDATORY VERIFICATION:** Read state.json back and confirm `verificationResults.builtAt` is set.
 
 If build or tests fail:
@@ -267,6 +278,8 @@ Implementation complete!
 - {M} components skipped (failures that exhausted retries)
 - Build: {status}
 - Tests: {status}
+- Test files created: {N}/{M} planned test files exist
+{If any planned test files missing: "⚠ Missing test files: {list}"}
 {If git.autoCommit was true: "- Commits: {N} atomic commits created"}
 
 {If any failures: list them with errors}

package/src/commands/5/plan-feature.md

@@ -5,6 +5,7 @@ agent: feature-planner
 allowed-tools: Read, Write, Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, TaskGet
 context: fork
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Plan Feature (Phase 1)

package/src/commands/5/plan-implementation.md

@@ -5,6 +5,7 @@ agent: implementation-planner
 allowed-tools: Read, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Plan Implementation (Phase 2)
@@ -43,6 +44,7 @@ Add emergency schedule tracking to products with date validation.
 | 3 | Schedule controller | create | src/controllers/ScheduleController.ts | REST endpoints: GET/POST/DELETE /api/schedules | moderate |
 | 3 | Register routes | modify | src/routes/index.ts | Add schedule routes to router | simple |
 | 4 | Schedule service tests | create | src/services/__tests__/ScheduleService.test.ts | Test validation and CRUD | moderate |
+| 4 | Schedule controller tests | create | src/controllers/__tests__/ScheduleController.test.ts | Test REST endpoints and error handling | moderate |
 
 ## Implementation Notes
 
@@ -96,12 +98,14 @@ Quick codebase scan for implementation planning.
 2. Identify where similar components live (models, services, controllers, tests)
 3. Note naming conventions from existing files
 4. Find example files that can serve as patterns for new components
+5. Identify the project's test framework, test file conventions, and test directory structure (e.g., __tests__/, tests/, *.test.ts, *.spec.ts, test_*.py)
 
 **Report Format:**
 - Project structure (key directories)
 - Naming conventions observed
 - Pattern files for each component type
 - Where new files should be placed
+- Test setup: framework, file naming pattern, test directory location (or "no test setup detected")
 
 **IMPORTANT:** Quick scan, not deep analysis. Focus on structure and patterns.
 **READ-ONLY:** Only use Read, Glob, and Grep tools.
@@ -141,9 +145,13 @@ Group into steps:
 - **Step 1**: Foundation (models, types, interfaces)
 - **Step 2**: Logic (services, business rules)
 - **Step 3**: Integration (controllers, routes, wiring)
-- **Step 4**: Tests (if not alongside components)
+- **Final step**: Tests for all logic-bearing components
 
-Not every feature needs all steps. Use what makes sense.
+**Test requirement:** Every component with action "create" that contains logic (services, controllers, repositories, hooks, utilities, helpers) MUST have a corresponding test component. Exempt: types, interfaces, pure models, route registrations, config wiring. When uncertain, include the test.
+
+If the explore agent reported "no test setup detected," still include test components but add an Implementation Note: "Project has no test framework detected — test components may need framework setup first or may be skipped during implementation."
+
+Not every feature needs all non-test steps. Use what makes sense. But testable components always need tests.
 
 **Parallel execution:** Components in the same step run in parallel. Group independent components together, separate dependent ones into different steps.
 
@@ -173,6 +181,7 @@ Plan self-check:
 - Scope: pass/fail
 - Completeness: pass/fail
 - Description length: pass/fail
+- Test coverage: pass/fail
 ```
 
 If any check fails, fix plan.md before proceeding to the completion output.

package/src/commands/5/quick-implement.md

@@ -4,6 +4,7 @@ description: Execute small, focused implementations quickly with state tracking
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, mcp__jetbrains__*
 context: fork
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Quick Implement

package/src/commands/5/reconfigure.md

@@ -4,6 +4,7 @@ description: Lightweight refresh of project documentation and skills without ful
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 context: fork
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Reconfigure (Lightweight Refresh)

package/src/commands/5/review-code.md

@@ -1,19 +1,19 @@
 ---
 name: 5:review-code
-description: Reviews code changes using Claude (built-in) or CodeRabbit CLI. Handles user interaction and fix application in main context.
-allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Task, mcp__jetbrains__*
+description: Reviews code changes using Claude (built-in) or CodeRabbit CLI. Categorizes findings and saves them for /5:address-review-findings.
+allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion, Task, mcp__jetbrains__*
 model: sonnet
 context: fork
 user-invocable: true
+disable-model-invocation: true
 ---
 
 <role>
-You are a Code Reviewer. You review code and apply user-approved fixes.
-You do NOT implement new features. You do NOT refactor beyond review findings.
-You ALWAYS get user consent before applying ANY fix.
-You ALWAYS verify changes after applying fixes (build + test).
+You are a Code Reviewer. Your job is to review code, categorize findings, and save them to a findings file.
+You do NOT apply fixes. You do NOT implement new features. You do NOT refactor code.
+Fix application is handled by /5:address-review-findings.
 You follow the exact step sequence below. Do not skip or reorder steps.
-After saving the review report, you are DONE.
+After saving the findings file, you are DONE.
 </role>
 
 # Review Code (Phase 5)
@@ -44,35 +44,23 @@ If not installed or not authenticated, ask user via AskUserQuestion:
 - "Switch to Claude for this review? (Recommended)" / "I'll install CodeRabbit first"
 - If they choose CodeRabbit setup, provide install instructions and STOP
 
-### Step 2: Check for Apply Mode
-
-If user invoked with `apply` argument (`/5:review-code apply`):
-- Skip to Step 10 (Apply Annotated Findings)
-- Do NOT run a new review
-
-Otherwise, continue with new review.
-
-### Step 3: Determine What to Review
+### Step 2: Determine What to Review
 
 Ask the user via AskUserQuestion:
 
-**Question 1: What to review?**
+**Question: What to review?**
 1. Staged changes (`git diff --cached`) — default
 2. Unstaged changes (`git diff`)
 3. All changes (`git diff HEAD`)
 4. Current branch vs main/master (`git diff main...HEAD`)
 
-**Question 2: How to present results?**
-1. Interactive (show findings, apply fixes immediately) — default
-2. Save to file (for later annotation with `[FIX]`/`[SKIP]`/`[MANUAL]`)
-
-### Step 4: Spawn Review Agent
+### Step 3: Spawn Review Agent
 
 Spawn a single agent to execute the review. Do NOT run the review yourself.
 
-**Architecture:** You (main agent) handle user interaction and fix application. The spawned agent runs the review and categorizes findings.
+**Architecture:** You (main agent) handle user interaction. The spawned agent runs the review and categorizes findings.
 
-#### 4A: CodeRabbit Review Agent
+#### 3A: CodeRabbit Review Agent
 
 ```
 Task tool call:
@@ -83,7 +71,7 @@ Task tool call:
     Run CodeRabbit CLI and categorize findings.
 
     ## Review Scope
-    Scope: {scope from Step 3}
+    Scope: {scope from Step 2}
     Base Branch: {branch-name if scope is "branch"}
 
     ## Process
@@ -115,7 +103,7 @@ Task tool call:
     - Include ALL findings
 ```
 
-#### 4B: Claude Review Agent
+#### 3B: Claude Review Agent
 
 ```
 Task tool call:
@@ -127,7 +115,7 @@ Task tool call:
     Review this code blind, purely on its merits.
 
     ## Review Scope
-    Scope: {scope from Step 3}
+    Scope: {scope from Step 2}
     Base Branch: {branch-name if scope is "branch"}
 
     ## Process
@@ -169,17 +157,13 @@ Task tool call:
     - Be thorough but practical — focus on real issues, not style nitpicks
 ```
 
-### Step 5: Process Agent Results
+### Step 4: Process Agent Results
 
 Receive structured results from the agent. If agent returned failure, report error and STOP.
 
-**If user selected "Save to file":** Skip to Step 9.
+### Step 5: Present Findings
 
-**If user selected "Interactive":** Continue to Step 6.
-
-### Step 6: Present Overview and Ask User
-
-Present ALL findings to the user first. Do NOT apply anything yet.
+Present ALL findings to the user.
 
 ```
 Code Review Results:
@@ -200,87 +184,31 @@ Manual Review Needed:
 - {file}:{line} - {description}
 ```
 
-Ask via AskUserQuestion: "Which fixable issues should be applied?"
-- Options: All / Selected / None
-
-### Step 7: Apply User-Approved Fixes
-
-**ONLY apply fixes the user has agreed to.**
-
-- If "All": Apply all fixable issues
-- If "Selected": Ask which specific fixes, then apply only those
-- If "None": Skip to Step 8
-
-For each fix:
-1. Read the file
-2. Apply the fix using Edit tool
-3. Track applied fixes
-
-### Step 8: Handle Questions
-
-If there are questions from the reviewer, ask via AskUserQuestion:
-- "Ask me each question" / "Skip all questions"
-
-If "Ask me each": Present each question individually via AskUserQuestion. If the answer requires a code change, apply it.
-
-### Step 9: Save Findings to File (File-Based Mode)
-
-For "Save to file" mode only.
+### Step 6: Save Findings to File
 
 Determine feature name from `.5/features/*/state.json` (most recent by `startedAt` field) or ask user.
 
-Write to `.5/features/{feature-name}/review-{YYYYMMDD-HHmmss}-findings.md`.
-
-Use the template structure from `.claude/templates/workflow/REVIEW-FINDINGS.md`. Include all findings with `[FIX]`/`[SKIP]`/`[MANUAL]` action markers.
-
-Tell user: "Findings saved. Edit the file to mark actions, then run `/5:review-code apply`"
-
-Skip to REVIEW COMPLETE.
-
-### Step 10: Apply Annotated Findings (Apply Mode)
-
-When invoked with `apply`:
-
-1. Determine feature name from `.5/features/*/state.json` (most recent by `startedAt` field) or ask user
-2. Find most recent `review-*-findings.md` in the feature folder
-3. If none found, tell user to run `/5:review-code` first and STOP
-4. Parse each finding and its action marker: `[FIX]`, `[SKIP]`, `[MANUAL]`
-5. Apply `[FIX]` findings using Edit tool
-6. Apply `[MANUAL]` findings using custom instructions from the file
-7. Skip `[SKIP]` findings
-8. Continue to Step 11
+Write to `.5/features/{feature-name}/review-findings-{YYYYMMDD-HHmmss}.md`.
 
-### Step 11: Verify Changes
-
-After applying any fixes (interactive or file-based):
-
-1. **Build:** Use the `/build-project` skill: `Skill tool: skill="build-project", args="target=compile"`
-2. **Test:** Use the `/run-tests` skill: `Skill tool: skill="run-tests", args="target=all"`
-3. If build fails: report which fixes caused issues
-4. If tests fail: report which tests failed
-
-### Step 12: Save Review Report
-
-**Interactive mode:** Save summary to `.5/features/{feature-name}/review-{YYYYMMDD-HHmmss}.md`
-
-Use the template structure from `.claude/templates/workflow/REVIEW-SUMMARY.md`.
-
-**Apply mode:** Append application results to the findings file with: fixes applied count, custom fixes count, skipped count, build/test status.
+Use the template structure from `.claude/templates/workflow/REVIEW-FINDINGS.md`. All findings get their default action markers:
+- Fixable items → `[FIX]`
+- Manual items → `[MANUAL]`
+- Questions → `[FIX]` (with the question as the suggested fix instruction)
 
 ## REVIEW COMPLETE
 
-After saving the report, output exactly:
+Output exactly:
 
 ```
 Review complete.
 
-- Fixes applied: {N}
-- Questions resolved: {N}
+- Fixable: {N}
+- Questions: {N}
 - Manual review needed: {N}
-- Build: {passed/failed}
-- Tests: {passed/failed}
 
-Report saved at `.5/features/{feature-name}/review-{timestamp}.md`
+Findings saved at `.5/features/{feature-name}/review-findings-{timestamp}.md`
+
+Edit the file to adjust actions ([FIX] / [SKIP] / [MANUAL]), then run `/5:address-review-findings {feature-name}` to apply fixes and optionally address GitHub PR comments.
 ```
 
 STOP. You are a reviewer. Your job is done. Do not implement new features.

package/src/commands/5/unlock.md

@@ -4,6 +4,7 @@ description: Remove the planning guard lock to allow edits outside the workflow
 allowed-tools: Bash
 context: inherit
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Unlock Planning Guard

package/src/commands/5/update.md

@@ -4,6 +4,7 @@ description: Update the 5-Phase Workflow to the latest version
 allowed-tools: Bash, Read, AskUserQuestion
 context: inherit
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Update 5-Phase Workflow

package/src/commands/5/verify-implementation.md

@@ -4,6 +4,7 @@ description: Verifies a feature implementation is complete and working with mult
 allowed-tools: Read, Glob, Grep, Bash, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
+disable-model-invocation: true
 ---
 
 # Verify Implementation (Phase 4)
@@ -154,6 +155,12 @@ For each component with action `create` in the plan:
 
 This is a lightweight check — it only verifies test files exist for new code, not test quality.
 
+**Test requirement enforcement:**
+- Components with logic (services, controllers, repositories, hooks, utilities, helpers) without tests → MISSING_REQUIRED_TEST (error-level)
+- Declarative components (types, interfaces, models without logic) without tests → MISSING_OPTIONAL_TEST (info-level, not counted as issues)
+
+If no test framework detected (no test runner in config, no existing test files found via Glob for `**/*.test.*`, `**/*.spec.*`, `**/test_*.*`), downgrade all MISSING_REQUIRED_TEST to warnings with note: "No test framework detected."
+
 ### Step 5: Determine Status
 
 Evaluate all three layers:
@@ -168,10 +175,11 @@ Evaluate all three layers:
 
 **PARTIAL** — infrastructure OK but gaps exist:
 - All files exist AND build succeeds AND tests pass
-- BUT: some acceptance criteria not satisfied, OR some requirements not implemented, OR some components partial, OR some new files lack tests
+- BUT: some acceptance criteria not satisfied, OR some requirements not implemented, OR some components partial, OR logic-bearing components lack tests but project has no test framework
 
 **FAILED** — infrastructure problems:
 - Any files missing, OR build fails, OR tests fail
+- Any logic-bearing components lack test files (MISSING_REQUIRED_TEST) AND project has a test framework
 
 ### Step 6: Generate Verification Report
 
@@ -223,7 +231,8 @@ Build fix entries from verification results:
 - Partial components → fix: describe what's missing from the component
 
 **From Layer 3 (Quality):**
-- Missing test files → fix: create test file for the component
+- Missing required test files (logic-bearing components) → fix: create test file for the component (priority: high)
+- Missing optional test files (declarative components) → note in report, no fix entry
 
 Each fix entry follows the same table format as `plan.md`:
 

package/src/hooks/check-updates.js

@@ -40,7 +40,7 @@ async function checkForUpdates(workspaceDir) {
   }
 
   // Compare versions
-  const installed = versionData.installedVersion;
+  const installed = versionData.packageVersion;
   const latestVersion = await getLatestVersion();
 
   let newLatest = null;
@@ -48,16 +48,16 @@ async function checkForUpdates(workspaceDir) {
     newLatest = latestVersion;
   }
 
-  // Only write if latestAvailableVersion actually changed
-  const oldLatest = versionData.latestAvailableVersion || null;
+  // Read/write latestAvailableVersion from .update-cache.json (gitignored)
+  const cacheFile = path.join(path.dirname(versionFile), '.update-cache.json');
+  let cacheData = {};
+  if (fs.existsSync(cacheFile)) {
+    try { cacheData = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch(e) {}
+  }
+  const oldLatest = cacheData.latestAvailableVersion || null;
   if (newLatest !== oldLatest) {
-    versionData.latestAvailableVersion = newLatest;
-
-    // Clean up legacy throttling fields
-    delete versionData.updateCheckLastRun;
-    delete versionData.updateCheckFrequency;
-
-    fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
+    cacheData.latestAvailableVersion = newLatest;
+    fs.writeFileSync(cacheFile, JSON.stringify(cacheData, null, 2));
   }
 
   process.exit(0);

package/src/hooks/statusline.js

@@ -50,9 +50,16 @@ process.stdin.on('end', () => {
       const versionFile = path.join(dir, '.5', 'version.json');
       const versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
 
-      // Update check
-      const latest = versionData.latestAvailableVersion;
-      const installed = versionData.installedVersion;
+      // Update check — read latestAvailableVersion from cache file (gitignored)
+      const cacheFile = path.join(dir, '.5', '.update-cache.json');
+      let latest = null;
+      if (fs.existsSync(cacheFile)) {
+        try {
+          const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+          latest = cache.latestAvailableVersion || null;
+        } catch(e) {}
+      }
+      const installed = versionData.packageVersion;
       if (latest && installed && compareVersions(installed, latest) < 0) {
         updateIndicator = ` | \x1b[33m↑${latest} → /5:update\x1b[0m`;
       }

package/src/templates/workflow/PLAN.md

@@ -9,6 +9,8 @@ created: {ISO-timestamp}
 - Description column: one action-oriented sentence per component
 - Implementation Notes: reference existing files as patterns, no code snippets
 - Components table must cover all functional requirements from feature.md
+- Every "create" component with logic (services, controllers, repositories, utilities) must have a corresponding test component
+- Declarative-only components (types, interfaces, route wiring) are exempt from test requirements
 -->
 
 # Implementation Plan: {TICKET-ID}
@@ -24,6 +26,7 @@ created: {ISO-timestamp}
 | 2 | {name} | create | {path} | {what it does} | moderate |
 | 2 | {name} | modify | {path} | {what to change} | moderate |
 | 3 | {name} | create | {path} | {what it does} | complex |
+| 4 | {name} tests | create | {test-path} | Test {what it tests} | moderate |
 
 ## Implementation Notes
 

package/src/templates/workflow/REVIEW-FINDINGS.md

@@ -14,9 +14,9 @@
    - `[SKIP]` - Don't apply this fix (change FIX to SKIP)
    - `[MANUAL]` - Custom instructions (change FIX to MANUAL and add instructions)
 3. Save this file
-4. Run: `/review-code apply`
+4. Run: `/5:address-review-findings`
 
-The apply command will read your annotations and apply marked fixes.
+The command will read your annotations and apply marked fixes.
 
 ---
 
@@ -55,4 +55,4 @@ The apply command will read your annotations and apply marked fixes.
 
 **Next Steps:**
 1. Edit this file to mark which findings to fix
-2. Run: `/review-code apply`
+2. Run: `/5:address-review-findings`

package/src/templates/workflow/VERIFICATION-REPORT.md

@@ -73,14 +73,22 @@
 
 ### Test Coverage for New Files
 
+**Required Tests (logic-bearing components):**
+
+| New File | Test File | Status |
+|----------|-----------|--------|
+| {src/path/Service.ts} | {src/path/Service.test.ts} | HAS TEST |
+| {src/path/Controller.ts} | — | MISSING REQUIRED TEST |
+
+**Optional Tests (declarative components):**
+
 | New File | Test File | Status |
 |----------|-----------|--------|
-| {src/path/File.ts} | {src/path/File.test.ts} | HAS TEST |
-| {src/path/Other.ts} | — | NO TEST |
+| {src/path/types.ts} | — | NO TEST (exempt) |
 
-**Result:** {N}/{M} new files have tests
+**Result:** {N}/{M} required test files exist
 
-**Layer 3 Result:** PASSED | PARTIAL
+**Layer 3 Result:** PASSED | FAILED | PARTIAL
 
 ---