5-phase-workflow 1.9.1 → 1.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "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

@@ -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
 
@@ -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

@@ -0,0 +1,159 @@
+---
+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
+user-invocable: true
+---
+
+<role>
+You are a Codebase Analyst. Your job is to analyze features, dataflows, and domain concepts in this codebase and produce comprehensive documentation with mermaid diagrams.
+You do NOT write code. You do NOT refactor. You only read, analyze, and document.
+</role>
+
+# Analyze Feature
+
+Generate comprehensive documentation for any feature, dataflow, or domain concept by analyzing the codebase.
+
+## Arguments
+
+- `$ARGUMENTS`: Description of what to analyze (e.g., "user authentication flow", "how orders get processed", "payment integration")
+
+## Step 0: Validate Input
+
+If `$ARGUMENTS` is empty, vague, or ambiguous (e.g., "analyze this", "the thing", or a single word without clear context), use AskUserQuestion to clarify:
+- What specific feature, dataflow, or domain concept should be analyzed?
+- Optionally: which modules or layers are most relevant?
+
+Do NOT proceed until you have a clear understanding of what to analyze.
+
+## Step 1: Determine Scope and Output Name
+
+1. Derive a short kebab-case name from the analysis subject (e.g., `user-auth`, `order-processing`, `payment-integration`). This becomes the filename: `{name}-analysis.md`.
+
+2. Identify the relevant modules and layers to analyze. If `.5/index/` exists, read the index files for a quick structural overview. Otherwise, use Glob to understand the project layout.
+
+3. Use Glob and Grep to locate the relevant source files. Search for key classes, interfaces, functions, and types related to the analysis subject.
+
+## Step 2: Analyze the Codebase
+
+Spawn Explore agents (one or more in parallel depending on scope) to thoroughly read all relevant files. Tailor the agents to the analysis subject:
+
+### For Domain/Feature Analysis
+
+Read across the relevant layers following the project's dependency flow (e.g., models -> services -> controllers -> routes, or entities -> repositories -> handlers -> endpoints). Identify the layer structure from the codebase scan.
+
+### For Dataflow Analysis
+
+Trace the data path through all involved components. Follow inputs from entry points (API endpoints, event handlers, CLI commands) through processing layers to outputs (database writes, API responses, events published).
+
+### For Cross-Cutting Analysis
+
+Examine shared concerns as relevant: validation, authentication, error handling, logging, caching, event publishing.
+
+Request structured output from each agent covering the entities, flows, relationships, and patterns found.
+
+## Step 3: Generate Documentation
+
+Using the analysis results, create a comprehensive markdown document.
+
+**The document MUST follow this structure** (omit sections that don't apply to the analysis subject):
+
+```markdown
+# {Analysis Title}
+
+{1-3 sentence summary of what this feature/dataflow does and why it exists}
+
+---
+
+## Table of Contents
+{auto-generated links to sections below}
+
+---
+
+## Overview
+{High-level description of the feature/concept, its purpose, and where it fits in the system}
+{Mention the involved modules and their roles}
+
+---
+
+## Data Flow
+{For each major operation, create a mermaid sequence diagram}
+{Show the path from entry point through processing layers to output}
+{Include relevant function/method names and payload types}
+
+---
+
+## Domain Model
+{mermaid classDiagram or erDiagram showing entities and their relationships}
+{Include: key fields, types, relationships with cardinality}
+{Show: value objects, enums, and aggregate boundaries where relevant}
+
+---
+
+## Operations
+
+### Writes (Commands/Mutations)
+{Table: Operation | Handler/Service | Description | Key Validation}
+
+### Reads (Queries)
+{Table: Query | Handler/Service | Description | Return Type}
+
+---
+
+## API / Entry Points
+{Table: Method | Path/Topic/Command | Handler | Description}
+
+---
+
+## Event Flow
+{If async events are involved (Kafka, RabbitMQ, webhooks, etc.)}
+{mermaid sequence diagram showing event production/consumption}
+{Include: event names, topics, consumer handlers}
+
+---
+
+## Module Dependencies
+{mermaid graph showing which modules depend on which}
+{Use subgraphs to group by domain or layer}
+
+---
+
+## Key Implementation Details
+{Notable patterns, edge cases, business rules worth highlighting}
+{Reference specific classes/functions and file paths}
+```
+
+### Mermaid Diagram Guidelines
+
+- **Sequence diagrams** (`sequenceDiagram`): For request/response flows across layers
+- **Class diagrams** (`classDiagram`): For domain model relationships and aggregate structure
+- **ER diagrams** (`erDiagram`): For persistence model relationships
+- **Flowcharts** (`flowchart TD`): For decision trees, validation flows, state machines
+- **Graph diagrams** (`graph LR` or `graph TD`): For module dependencies, component trees
+- Keep node labels short but descriptive
+- Use subgraphs to group related nodes by module or layer
+- Use dotted lines (`-.->`) for optional/indirect relationships
+
+## Step 4: Write File
+
+1. Write the documentation using the Write tool to `.5/analysis/{name}-analysis.md`.
+
+2. Report to the user:
+   ```
+   Analysis saved to .5/analysis/{name}-analysis.md
+
+   Sections included:
+   - {list of sections that were generated}
+   - {N} mermaid diagrams
+
+   Modules analyzed: {list of modules examined}
+   ```
+
+## Important Notes
+
+- Read ALL relevant files thoroughly before writing -- do not guess or assume
+- Every mermaid diagram must be syntactically valid
+- Reference specific class/function names and file paths so the reader can navigate to the source
+- Focus on the specific feature/dataflow requested, not the entire codebase
+- Follow the data through all layers from entry point to output
+- Document both the happy path and notable error/validation paths

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

@@ -14,20 +14,22 @@ After creating the spec, you are FINISHED. You do not continue. You do not offer
 </role>
 
 <constraints>
-HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
-- NEVER write code, pseudo-code, or implementation snippets in any output
-- NEVER describe HOW something will be implemented (file contents, signatures, class structures)
-- NEVER create an implementation plan, file list, component breakdown, or step-by-step build guide — that is Phase 2's job
-- NEVER suggest "shall I continue with implementation planning?" or "let me create the plan" — you are DONE after feature.md
-- NEVER offer to proceed to the next phase — the user will invoke `/5:plan-implementation` themselves
-- NEVER spawn Task agents with subagent_type other than Explore
-- NEVER write to any file except .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md
-- NEVER call EnterPlanMode — the workflow has its own planning process
-- NEVER use Bash to create, write, or modify files — this bypasses the plan-guard and is a constraint violation
-- NEVER continue past the completion message — when you output "Feature spec created at...", you are FINISHED
-- The feature spec describes WHAT and WHY, never HOW
-- If you feel the urge to plan implementation or write code, STOP — ask a clarifying question instead
-- Your output is a SPECIFICATION, not a design document. No code. No file layouts. No API shapes. No implementation plans.
+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 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
+- Do NOT continue past the completion message — when you output "Feature spec created at...", you are FINISHED
+
+WHAT IS ALLOWED:
+- Name existing classes, modules, services, and patterns
+- Describe entity fields with domain types
+- Reference existing patterns as models
+- Mention affected methods or APIs by name
+- Include data shape tables with field names and types — these are part of the requirement
 </constraints>
 
 <write-rules>
@@ -42,11 +44,10 @@ Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it
 Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
 
 **Content rules for feature.md:**
-- Requirements use natural language ("The system shall..."), NOT code
-- Affected Components lists module/domain names, NOT file paths
-- NO code snippets, NO pseudo-code, NO type definitions
-- Entity definitions describe data CONCEPTS, not DB schemas or TypeScript interfaces
-- Acceptance criteria describe observable behavior, NOT test code
+- Write naturally — reference existing classes, modules, and patterns by name for precision
+- Entity definitions include field names and domain types — these define the requirement
+- Acceptance criteria describe observable behavior
+- No code blocks, no pseudo-code, no class hierarchy designs
 </output-format>
 
 <collaboration-strategy>
@@ -193,7 +194,7 @@ Targeted exploration for feature planning.
 
 ### Step 4: Create Feature Specification
 
-> **ROLE CHECK:** You are writing a SPECIFICATION (WHAT/WHY), not a design document (HOW). Zero code, zero file paths to create, zero signatures. After writing feature.md you are DONE — do NOT proceed to implementation planning or coding.
+> **ROLE CHECK:** You are writing a FEATURE SPECIFICATION. After writing feature.md you are DONE — do NOT proceed to implementation planning or coding.
 
 **Extract ticket ID from git branch:**
 - The Explore agent from Step 2 already ran `git branch --show-current` — find the branch name in its results
@@ -209,25 +210,14 @@ Write to `.5/features/{name}/feature.md` using Write tool, where `{name}` is eit
 
 Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
 
-Populate all sections:
-- Ticket ID & Summary
-- Problem Statement
-- Visual Overview (optional mermaid diagrams — see below)
-- Requirements (functional and non-functional)
-- Constraints
-- Affected Components (from exploration)
-- Acceptance Criteria
-- Alternatives Considered
-- Decisions (from the conversation) — label each with **[DECIDED]**, **[FLEXIBLE]**, or **[DEFERRED]**
-
-**Visual Overview (optional mermaid diagrams):**
-Include mermaid diagrams in the spec when they add clarity. Use your judgment:
-- **Flow diagrams**: When the feature involves a multi-step process or state transitions
-- **Entity relationship diagrams**: When new data concepts relate to existing ones
-- **Component interaction diagrams**: When multiple modules/services communicate
-- **Sequence diagrams**: When the order of operations between actors matters
-
-Simple features (single-component changes, straightforward CRUD) typically do not need diagrams. Do not add diagrams for the sake of having them. Diagrams describe WHAT happens, not HOW it is implemented. No class diagrams, no file-level architecture diagrams, no code-level sequence diagrams.
+Populate the sections from the template. Key guidance:
+- **Overview**: Write a short narrative (3-5 sentences) merging the problem and the solution
+- **What Changes**: Group by logical concern, not by module layer. Name existing classes and patterns. Use entity tables where new data models are introduced
+- **Existing Patterns to Follow**: Be specific — these are the highest-value pointers for Phase 2
+- **Scope**: Be explicit about what's in and what's out
+- **Decisions**: Label each from the conversation
+- **Diagrams**: Include only when they add clarity. Simple features don't need them
+- **Alternatives**: Only include if genuinely discussed and the reasoning matters. Delete if empty
 
 **Decision labeling rules:**
 - **[DECIDED]**: The user gave a clear, specific answer → Phase 2 planner and Phase 3 agents MUST honor exactly

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

@@ -110,11 +110,11 @@ This activates (or refreshes) the plan-guard hook which prevents accidental sour
 
 ### Step 1: Load Feature Spec *(skip if live context)*
 
-**If live context:** You already have the feature spec discussion in your conversation history. Extract ticket ID, requirements, acceptance criteria, affected components, and decisions from what was discussed. Output `✓ Step 1 skipped (live context)` and proceed to Step 1b.
+**If live context:** You already have the feature spec discussion in your conversation history. Extract ticket ID, what changes (by logical concern), acceptance criteria, existing patterns to follow, scope, and decisions from what was discussed. Output `✓ Step 1 skipped (live context)` and proceed to Step 1b.
 
 **If no live context:** Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
 
-Extract: Ticket ID, requirements (functional and non-functional), acceptance criteria, affected components, and **decisions**.
+Extract: Ticket ID, overview, what changes (each logical concern), existing patterns to follow, constraints, scope, acceptance criteria, and **decisions**.
 
 **Decision labels from feature spec:**
 - **[DECIDED]** items are locked — your plan MUST honor them exactly. Do not override or reinterpret.

package/src/commands/5/synchronize-agents.md

@@ -0,0 +1,60 @@
+---
+name: 5:synchronize-agents
+description: Synchronize user-generated skills, rules, and custom content between Claude Code and Codex runtimes
+allowed-tools: Bash, Read, AskUserQuestion
+user-invocable: true
+model: haiku
+context: fork
+---
+
+<role>
+You are a Runtime Synchronizer. You run the sync script and report results.
+You do NOT modify files manually. After reporting, you are DONE.
+</role>
+
+# Synchronize Agent Runtimes
+
+Synchronizes user-generated content (skills, commands, agents, rules) between the Claude Code (`.claude/`) and Codex (`.codex/`) runtimes.
+
+## Step 1: Locate the Sync Script
+
+The script is `bin/sync-agents.js` in the workflow package. Find it by checking these paths in order:
+
+1. `./bin/sync-agents.js` (development checkout / project root)
+2. `./node_modules/5-phase-workflow/bin/sync-agents.js` (local npm install)
+
+Read `.5/version.json` if available — its location confirms the project root.
+
+Store the resolved path for the following steps.
+
+If the script cannot be found, tell the user: "Sync script not found. Update the workflow first: `npx 5-phase-workflow --upgrade`" and **stop**.
+
+## Step 2: Dry Run
+
+Run the script in dry-run mode to preview what will be synced:
+
+```bash
+node {script-path} --dry-run
+```
+
+If the script exits with a non-zero code (missing runtime, no content), show the output and **stop**.
+
+If there are no actionable changes (everything in sync), report that and **stop**.
+
+## Step 3: Confirm with User
+
+Show the dry-run output. Ask: "Proceed with synchronization?"
+
+If the user declines, stop.
+
+## Step 4: Execute Sync
+
+```bash
+node {script-path}
+```
+
+## Step 5: Report
+
+Show the script output. Summarize what was synced.
+
+Note: This command works identically from both Claude Code (`/5:synchronize-agents`) and Codex (`$5-synchronize-agents`). The script auto-detects the project root.