5-phase-workflow 1.9.2 → 1.9.4

package/bin/install.js

@@ -423,8 +423,8 @@ This skill was authored for Claude Code. Map these tool references:
 | Claude Code | Codex Equivalent |
 |-------------|------------------|
 | \`AskUserQuestion\` | Ask the user directly in conversation |
-| \`Task(subagent_type="Explore")\` | Research the codebase yourself using available tools |
-| \`Task(prompt="...")\` | \`spawn_agent(message="...")\` |
+| \`Agent(subagent_type="Explore")\` | Research the codebase yourself using available tools |
+| \`Agent(prompt="...")\` | \`spawn_agent(message="...")\` |
 | \`Read\` | \`read_file\` |
 | \`Write\` | \`write_file\` |
 | \`Edit\` | \`patch\` |

package/bin/sync-agents.js

@@ -81,8 +81,8 @@ This skill was authored for Claude Code. Map these tool references:
 | Claude Code | Codex Equivalent |
 |-------------|------------------|
 | \`AskUserQuestion\` | Ask the user directly in conversation |
-| \`Task(subagent_type="Explore")\` | Research the codebase yourself using available tools |
-| \`Task(prompt="...")\` | \`spawn_agent(message="...")\` |
+| \`Agent(subagent_type="Explore")\` | Research the codebase yourself using available tools |
+| \`Agent(prompt="...")\` | \`spawn_agent(message="...")\` |
 | \`Read\` | \`read_file\` |
 | \`Write\` | \`write_file\` |
 | \`Edit\` | \`patch\` |

package/package.json

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

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

@@ -1,7 +1,7 @@
 ---
 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__*
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Agent, Skill, mcp__jetbrains__*
 user-invocable: true
 model: sonnet
 context: fork
@@ -138,7 +138,7 @@ gh repo view --json owner,name
 Spawn a sonnet agent to analyze PR comments:
 
 ```
-Task tool call:
+Agent tool call:
   subagent_type: general-purpose
   model: sonnet
   description: "Analyze PR review comments"
@@ -163,44 +163,92 @@ Task tool call:
 
     For duplicates, note which local finding covers it.
 
+    For every actionable_fix and manual comment, also provide:
+    - **recommendation**: one of `address`, `defer`, `decline`, or `discuss`
+      - `address` — should be fixed now, clear and reasonable
+      - `defer` — valid concern but low urgency, can wait
+      - `decline` — out of scope or disagree with the suggestion
+      - `discuss` — needs more context before deciding
+    - **reasoning**: one plain-English sentence explaining the recommendation
+
     ## Output Format
     Return a structured list:
 
     ---PR-COMMENTS---
-    {id} | {file}:{line} | {category} | {description} | {duplicate_of or "none"}
+    {id} | {file}:{line} | {category} | {description} | {duplicate_of or "none"} | {recommendation or "n/a"} | {one-sentence reasoning or "n/a"}
     ---END-PR-COMMENTS---
 
     Rules:
     - DO NOT apply fixes
     - DO NOT interact with user
     - Include every comment in the output
+    - recommendation and reasoning are required for actionable_fix and manual; use "n/a" for skip and duplicate
 ```
 
-Parse the `---PR-COMMENTS---` block. Collect:
-- `pr_to_fix` — actionable_fix items
-- `pr_duplicates` — duplicate items
-- `pr_manual` — manual items
+Parse the `---PR-COMMENTS---` block. For each line extract all seven fields. Build:
+- `pr_actionable` — actionable_fix items (with recommendation + reasoning)
+- `pr_manual` — manual items (with recommendation + reasoning)
+- `pr_duplicates` — duplicate items (auto-assign `decision: wont_fix`, no Q&A)
+- `pr_skip` — skip items (auto-assign `decision: wont_fix`, no Q&A)
+
+Initialize `pr_decisions` as an empty list. Append all `pr_duplicates` and `pr_skip` entries with `decision: wont_fix` and `user_note: ""`.
 
-**Present PR comment summary to user:**
+**Display count summary:**
 ```
-PR Review Comments:
-- Actionable (new): {N}
-- Duplicates (covered by local findings): {N}
-- Manual/Discussion: {N}
-- Skipped (bot/resolved): {N}
+PR Review Comments found:
+- Actionable (new):              {N}
+- Manual/Discussion:             {N}
+- Duplicates (covered by local): {N}
+- Skipped (bot/resolved):        {N}
 
-Actionable PR comments:
-{#} {file}:{line} — {description}
+You will now be asked to decide on each actionable and manual comment individually.
+```
 
-Manual PR comments:
-{#} {file}:{line} — {description}
+If there are no `pr_actionable` and no `pr_manual` items, display `"No actionable or manual PR comments to review."` and skip the loop below.
+
+**Per-comment decision loop** — iterate over all items in `pr_actionable + pr_manual` in order, using a counter `i` from 1 to total:
+
+For each comment:
+
+1. Display:
+   ```
+   ── PR Comment {i} of {total} ──────────────────────────
+   Category:       {category}
+   File:           {file}:{line}
+   Comment:        {description}
+
+   Recommendation: {recommendation} — {reasoning}
+   ──────────────────────────────────────────────────────
+   ```
+
+2. Ask via AskUserQuestion:
+   - Question: `"[{i}/{total}] {file}:{line} — How do you want to handle this comment?"`
+   - Options: `"fix — apply the suggested change"` / `"won't fix — decline"` / `"wait — defer for later"`
+
+3. Record the decision (map to internal values: `fix`, `wont_fix`, `wait`).
+
+4. Ask via AskUserQuestion:
+   - Question: `"Add a note for this comment? (shown in PR reply and summary report)"`
+   - Options: `"No note"` / `"Add a note"`
+   - If "Add a note": ask via AskUserQuestion with free-text input (no fixed options):
+     - Question: `"Enter your note for: {file}:{line}"`
+
+5. Append to `pr_decisions`:
+   ```
+   { comment_id, file_line, category, description, decision, user_note (or ""), recommendation, reasoning }
+   ```
+
+After the loop, display:
 ```
+Decision summary:
+- fix:       {N} comments
+- won't fix: {N} comments
+- wait:      {N} comments
 
-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.
+Proceeding to apply fixes...
+```
 
-Collect final `pr_approved_fixes` list.
+Derive `pr_approved_fixes` as the subset of `pr_decisions` where `decision == fix`. This list is used by Step 5.
 
 ### Step 5: Apply Fixes
 
@@ -224,7 +272,7 @@ Apply from highest line number to lowest within each file to avoid line offset s
 #### Agent Application (4+ fixes per file)
 
 ```
-Task tool call:
+Agent tool call:
   subagent_type: general-purpose
   model: {haiku for simple | sonnet for complex}
   description: "Apply fixes to {file-path}"
@@ -265,9 +313,7 @@ For each `[MANUAL]` item with custom instructions:
 
 ### 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:
+Iterate over every entry in `pr_decisions` (excluding entries with category `skip` — do not reply to those). For each entry, post a reply using the GitHub API.
 
 **For review comments (inline):**
 ```bash
@@ -283,12 +329,22 @@ gh api repos/{owner}/{repo}/issues/{number}/comments \
   --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}`
+**Template selection logic:**
+
+1. If `category == "duplicate"`: use the auto-duplicate template below
+2. Else if `decision == "fix"`: use fix template, with or without note based on `user_note` presence
+3. Else if `decision == "wont_fix"`: use wont_fix template, with or without note based on `user_note` presence
+4. Else if `decision == "wait"`: use wait template, with or without note based on `user_note` presence
+
+**Templates:**
+
+- **`fix` (with user note):** `Applied fix: {description}. Will be included in the next push. Note: {user_note}`
+- **`fix` (no note):** `Applied fix: {description}. Will be included in the next push.`
+- **`wont_fix` (with user note):** `Reviewed — not addressing: {user_note}`
+- **`wont_fix` (no note):** `Reviewed — not addressing: will handle separately`
+- **`wait` (with user note):** `Noted for later: {user_note}`
+- **`wait` (no note):** `Noted for later: deferring for now`
+- **`wont_fix` (auto, duplicate):** `Covered by local review findings — {local_decision}` where `{local_decision}` is `"fix applied"` if the matched local finding has action `[FIX]`, otherwise `"marked as skipped"` or `"flagged for manual review"` accordingly
 
 If `gh api` is unavailable or fails, log the failure and continue. Do NOT abort for reply failures.
 
@@ -317,15 +373,16 @@ Use the template structure from `.claude/templates/workflow/REVIEW-SUMMARY.md`.
 
 **Reviewed:** {feature} — findings from {findings-filename}
 **Timestamp:** {ISO-timestamp}
-**User Decisions:** Applied {N} fixes, skipped {N}, {N} manual
+**User Decisions:** Applied {N} fixes, declined {N}, deferred {N}
 
 ## Summary
 
 - **Local Fixes Applied:** {N}
 - **Local Fixes Skipped:** {N}
 - **Manual Items Applied:** {N}
-- **PR Comments Fixed:** {N}
-- **PR Comments Skipped:** {N}
+- **PR Comments Fixed:**    {N}  (decision = fix)
+- **PR Comments Deferred:** {N}  (decision = wait)
+- **PR Comments Declined:** {N}  (decision = won't fix, excluding auto)
 - **Build:** {passed/failed}
 - **Tests:** {passed/failed}
 
@@ -338,6 +395,12 @@ Use the template structure from `.claude/templates/workflow/REVIEW-SUMMARY.md`.
 ## Manual Items
 ...
 
+## PR Comment Decisions
+
+| # | File:Line | Description | Decision | Note |
+|---|-----------|-------------|----------|------|
+| {i} | {file}:{line} | {description} | {fix/won't fix/wait} | {user_note or "—"} |
+
 ## PR Comment Replies
 ...
 ```

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

@@ -1,7 +1,7 @@
 ---
 name: 5:analyze-feature
 description: Analyze any feature, dataflow, or domain concept in the codebase and generate comprehensive documentation with mermaid diagrams. Use when you need to understand how a feature works end-to-end, trace a dataflow, or document a domain area.
-allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
+allowed-tools: Read, Write, Glob, Grep, Agent, AskUserQuestion
 user-invocable: true
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: 5:discuss-feature
 description: Discusses and refines an existing feature specification through iterative Q&A. Use after /plan-feature when requirements need clarification or changes. Updates the feature spec based on discussion.
-allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
+allowed-tools: Read, Write, Glob, Grep, Agent, AskUserQuestion
 user-invocable: true
 model: opus
 context: inherit
@@ -129,7 +129,7 @@ Based on the user's focus area, explore the codebase if needed:
 - Check dependencies
 - Identify ripple effects
 
-Use Task tool with subagent_type=Explore for complex exploration.
+Use Agent tool with subagent_type=Explore for complex exploration.
 
 ### Step 5: Interactive Q&A
 

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

@@ -1,7 +1,7 @@
 ---
 name: 5:implement-feature
 description: Executes an implementation plan by delegating to agents. Phase 3 of the 5-phase workflow.
-allowed-tools: Task, Read, Write, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList
+allowed-tools: Agent, Read, Write, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList
 user-invocable: true
 model: opus
 context: fork
@@ -189,7 +189,7 @@ For steps with multiple independent components, spawn one agent per component in
 Agent prompt template (adapt per component):
 
 ```
-Task tool call:
+Agent tool call:
   subagent_type: general-purpose
   model: {based on complexity}
   description: "{Action} {component-name} for {feature-name}"

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

@@ -1,7 +1,7 @@
 ---
 name: 5:plan-feature
 description: Plans feature implementation by analyzing requirements, identifying affected modules, and creating a structured feature specification. Use at the start of any new feature to ensure systematic implementation. This is Phase 1 of the 5-phase workflow.
-allowed-tools: Read, Write, Task, AskUserQuestion
+allowed-tools: Read, Write, Agent, AskUserQuestion
 user-invocable: true
 model: opus
 ---
@@ -18,7 +18,7 @@ HARD CONSTRAINTS:
 - Do NOT write code or pseudo-code — describe behavior and data shapes in natural language or tables
 - Do NOT create implementation plans, file lists, or step-by-step build guides — that is Phase 2's job
 - Do NOT offer to proceed to the next phase — the user will invoke `/5:plan-implementation` themselves
-- Do NOT spawn Task agents with subagent_type other than Explore
+- Do NOT use the Agent tool with subagent_type other than Explore
 - Do NOT write to any file except .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md
 - Do NOT call EnterPlanMode — the workflow has its own planning process
 - Do NOT use Bash to create, write, or modify files — this bypasses the plan-guard
@@ -122,7 +122,7 @@ Ask the developer for the feature description using AskUserQuestion:
 
 > **ROLE CHECK:** You are a Feature Planner. Your ONLY output is feature.md. If you are tempted to write code or create files, STOP and return to the next question in Step 3.
 
-Spawn a Task with `subagent_type=Explore`:
+Spawn an Agent with `subagent_type=Explore`:
 
 ```
 Analyze the codebase for a feature specification session.

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

@@ -1,7 +1,7 @@
 ---
 name: 5:plan-implementation
 description: Creates an implementation plan from a feature spec. Phase 2 of the 5-phase workflow.
-allowed-tools: Read, Write, Task, AskUserQuestion
+allowed-tools: Read, Write, Agent, AskUserQuestion
 user-invocable: true
 model: opus
 ---
@@ -144,7 +144,7 @@ Read `.5/features/{feature-name}/codebase-scan.md`. If it exists and is non-empt
 
 **If `codebase-scan.md` does NOT exist** (e.g., user skipped Phase 1 or ran an older version), spawn a fresh Explore agent:
 
-Spawn a Task with `subagent_type=Explore`:
+Spawn an Agent with `subagent_type=Explore`:
 
 ```
 Quick codebase scan for implementation planning.

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

@@ -1,7 +1,7 @@
 ---
 name: 5:quick-implement
 description: Execute small, focused implementations quickly with state tracking and atomic commits. Skips extensive planning phases and verification agents - use for tasks where you know exactly what to do.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, mcp__jetbrains__*
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, mcp__jetbrains__*
 user-invocable: true
 ---
 
@@ -244,7 +244,7 @@ Determine the model based on the highest complexity in the plan's components:
 Spawn an agent with inline instructions:
 
 ```
-Task tool call:
+Agent tool call:
   subagent_type: general-purpose
   model: {haiku or sonnet based on complexity above}
   description: "Execute quick implementation for ${feature_name}"

package/src/commands/5/reconfigure.md

@@ -1,7 +1,7 @@
 ---
 name: 5:reconfigure
 description: Lightweight refresh of project documentation, codebase index, and skills without full Q&A. Re-detects codebase changes, regenerates .5/*.md docs, rebuilds .5/index/, updates AGENTS.md, and refreshes all skills.
-allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+allowed-tools: Read, Write, Bash, Glob, Grep, Agent, AskUserQuestion
 user-invocable: true
 context: fork
 ---
@@ -134,7 +134,7 @@ New skills will be created and stale skills removed based on the user's choices.
 
 ### Step 5: Regenerate
 
-Invoke the refresh skills in **refresh mode** via the Task tool:
+Invoke the refresh skills in **refresh mode** via the Agent tool:
 
 ```
 Task prompt 1: "Run configure-docs-index skill in REFRESH MODE.
@@ -163,7 +163,7 @@ Re-analyze the codebase and:
 6. Remove rule files the user chose to drop"
 ```
 
-Use `subagent_type: "general-purpose"` for the Task.
+Use `subagent_type: "general-purpose"` for the Agent.
 
 ### Step 6: Track
 

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

@@ -1,7 +1,7 @@
 ---
 name: 5:review-code
 description: Reviews code changes using native agent review or CodeRabbit CLI. Categorizes findings and saves them for /5:address-review-findings.
-allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion, Task, mcp__jetbrains__*
+allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion, Agent, mcp__jetbrains__*
 user-invocable: true
 model: sonnet
 context: fork
@@ -62,7 +62,7 @@ Spawn a single agent to execute the review. Do NOT run the review yourself.
 #### 3A: CodeRabbit Review Agent
 
 ```
-Task tool call:
+Agent tool call:
   subagent_type: general-purpose
   model: sonnet
   description: "Run CodeRabbit review"
@@ -105,7 +105,7 @@ Task tool call:
 #### 3B: Native Review Agent
 
 ```
-Task tool call:
+Agent tool call:
   subagent_type: general-purpose
   model: sonnet
   description: "Run native code review"

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

@@ -1,7 +1,7 @@
 ---
 name: 5:verify-implementation
 description: Verifies a feature implementation is complete and working with multi-layer checks. Phase 4 of the 5-phase workflow.
-allowed-tools: Read, Glob, Grep, Bash, Write, Task, AskUserQuestion
+allowed-tools: Read, Glob, Grep, Bash, Write, Agent, AskUserQuestion
 user-invocable: true
 model: sonnet
 context: fork
@@ -105,7 +105,7 @@ Record: SUCCESS / FAILED with details (which tests failed, error messages).
 Spawn a sonnet agent to cross-reference the implementation against the feature spec:
 
 ```
-Task tool call:
+Agent tool call:
   subagent_type: general-purpose
   model: sonnet
   description: "Verify feature completeness for {feature-name}"

package/src/hooks/plan-guard.js

@@ -2,7 +2,7 @@
 
 // Plan Guard - PreToolUse Hook
 // Prevents LLM breakout from planning phases by blocking:
-// - Task agents other than Explore (when not in implementation mode)
+// - Agent/Task agents other than Explore (when not in implementation mode)
 // - Write/Edit operations outside .5/ (when not in implementation mode)
 //
 // Planning mode is detected per-feature by checking if that specific feature's
@@ -20,8 +20,8 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input);
     const toolName = data.tool_name || '';
 
-    // Short-circuit: only check Task, Write, Edit, EnterPlanMode, and Bash tools
-    if (toolName !== 'Task' && toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'EnterPlanMode' && toolName !== 'Bash') {
+    // Short-circuit: only check Agent, Task, Write, Edit, EnterPlanMode, and Bash tools
+    if (toolName !== 'Agent' && toolName !== 'Task' && toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'EnterPlanMode' && toolName !== 'Bash') {
       process.exit(0);
     }
 
@@ -57,7 +57,7 @@ process.stdin.on('end', () => {
       process.exit(2);
     }
 
-    if (toolName === 'Task') {
+    if (toolName === 'Agent' || toolName === 'Task') {
       const agentType = toolInput.subagent_type || '';
       if (agentType && agentType !== 'Explore') {
         const blockCount = incrementBlockCount(workspaceDir);
@@ -189,7 +189,7 @@ function getTargetFeature(toolName, toolInput, workspaceDir) {
     }
   }
 
-  if (toolName === 'Task') {
+  if (toolName === 'Agent' || toolName === 'Task') {
     // Check the task prompt for feature name references
     const prompt = toolInput.prompt || '';
     const desc = toolInput.description || '';

package/src/settings.json

@@ -28,7 +28,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Task",
+        "matcher": "Task|Agent",
         "hooks": [
           {
             "type": "command",
@@ -38,7 +38,7 @@
         ]
       },
       {
-        "matcher": "Task|Write|Edit|EnterPlanMode|Bash",
+        "matcher": "Task|Agent|Write|Edit|EnterPlanMode|Bash",
         "hooks": [
           {
             "type": "command",