5-phase-workflow 1.9.5 → 2.0.0

package/src/skills/configure-skills/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: configure-skills
-description: Generates project-specific create-*/run-* skills and scoped rules from the current codebase. Used during /5:implement-feature CONFIGURE.
-allowed-tools: Read, Write, Bash, Glob, Grep
+description: Generates project-specific create-*/run-* skills and scoped rules from the current codebase. Used during /5:implement CONFIGURE.
+allowed-tools: Read, Write, Bash, Glob, Grep, create-skill, scaffold-skill
 model: sonnet
 context: fork
 user-invocable: false
@@ -11,7 +11,7 @@ user-invocable: false
 
 ## Overview
 
-This skill handles skill and rule generation during Phase 3 (implement-feature) for the CONFIGURE feature. It is called by step-executor to create project-specific skills and scoped rules.
+This skill handles skill and rule generation during implementation for the CONFIGURE feature. It is called by step-executor to create project-specific skills and scoped rules.
 
 It handles two tasks:
 
@@ -28,10 +28,10 @@ This skill supports two modes. The skill generation and rule generation logic is
 
 ### Full Mode (default)
 
-Used by `/5:configure` → `/5:implement-feature CONFIGURE` flow.
+Used by `/5:configure` → `/5:implement CONFIGURE` flow.
 
-- **Input:** Pattern/command selections from feature spec (`.5/features/CONFIGURE/feature.md`)
-- **Behavior:** Creates all selected skills and rules from scratch based on feature spec requirements
+- **Input:** Pattern/command selections from unified plan (`.5/features/CONFIGURE/plan.md`)
+- **Behavior:** Creates all selected skills and rules from scratch based on unified plan requirements
 
 ### Refresh Mode
 
@@ -53,7 +53,7 @@ If `tools.skillCreator.available` is `true` in `.5/config.json`, use the skill-c
 
 If skill-creator is not available, use the existing template-based generation below — no degradation in workflow behavior.
 
-**Reads:** Pattern selections from feature spec (`.5/features/CONFIGURE/feature.md`)
+**Reads:** Pattern selections from unified plan (`.5/features/CONFIGURE/plan.md`)
 
 **Creates:** SKILL.md files in `.claude/skills/{name}/SKILL.md`
 
@@ -61,7 +61,7 @@ If skill-creator is not available, use the existing template-based generation be
 
 Skills are determined by what patterns exist in the codebase (detected during `/5:configure`) and what the user selected — not by project type.
 
-For EACH pattern selected by the user in the feature spec:
+For EACH pattern selected by the user in the unified plan:
 
 1. **Find examples** - Read 2-3 files from the pattern's location
 2. **Extract conventions:**
@@ -124,13 +124,13 @@ Based on {example-file}, new {patterns} should follow:
 
 ## B. Generate Command Skills (run-*)
 
-**Reads:** Command selections from feature spec (`.5/features/CONFIGURE/feature.md`)
+**Reads:** Command selections from unified plan (`.5/features/CONFIGURE/plan.md`)
 
 **Creates:** SKILL.md files in `.claude/skills/run-{command}/SKILL.md`
 
 ### B1. Command-Based Skill Generation
 
-For EACH command selected by the user in the feature spec:
+For EACH command selected by the user in the unified plan:
 
 1. **Read the source** - Check package.json scripts, Makefile, etc.
 2. **Document the command:**
@@ -219,7 +219,7 @@ For each applicable rule:
 1. **Derive `paths:` globs** from detected file locations (e.g., if tests are at `src/**/*.test.ts` and `tests/**/*.spec.ts`, use those patterns)
 2. **Convert analysis observations into imperative directives** — "Use X", "Always Y", "Never Z"
 3. **Keep each file 15-40 lines** — be concise and actionable
-4. **Do not repeat** the 6 mandatory coding guidelines from `AGENTS.md`
+4. **Do not repeat** the general guidance sections from `AGENTS.md`
 
 Write files to `.claude/rules/`:
 
@@ -311,4 +311,4 @@ Component D (Rules): SKIPPED - rules.generate is false in config
 - DO NOT hardcode conventions - always derive from actual project analysis
 - DO NOT generate empty or placeholder skill or rule files
 - DO NOT assume command syntax - always read from actual config files (package.json, Makefile, etc.)
-- DO NOT repeat the 6 mandatory coding guidelines from `AGENTS.md` in rule files
+- DO NOT repeat the general guidance sections from `AGENTS.md` in rule files

package/src/templates/AGENTS.md

@@ -0,0 +1,94 @@
+# Repository Guide
+
+{PROJECT_OVERVIEW}
+
+## Build & Run Commands
+
+{BUILD_RUN_COMMANDS}
+
+## Skill Usage
+
+Before implementing changes, always check the available skills for relevant implementation guidance.
+
+Use skills to understand project-specific workflows, commands, testing expectations, and implementation conventions before editing code.
+
+## Workflow Rules
+
+When running `/5:` workflow commands, follow the command instructions exactly as written.
+Do not skip steps, combine phases, or proceed to actions not specified in the current command.
+Each phase produces a specific artifact - do not create artifacts belonging to other phases.
+
+## Coding Guidelines
+
+1. Prefer explicit types or contracts for public APIs, data transfer shapes, service methods, hooks, and async return values where the language supports them.
+2. Keep comments and docs concise; document constraints and non-obvious behavior, not the obvious.
+3. Keep files focused and bounded; split broad controllers, services, hooks, and components early.
+4. Extract helpers or classes when logic starts mixing orchestration, parsing, IO, and mapping in one place.
+5. Favor SRP and DRY, but follow surrounding module conventions before introducing new abstractions.
+6. Keep features modular: wire backend providers in feature modules, keep UI state in hooks, and avoid cross-layer shortcuts.
+
+## Simplicity First
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No flexibility or configurability that was not requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## Testing
+
+- Add unit tests for business logic when they provide real value.
+- Do not create unit tests just to satisfy coverage or test trivial code.
+- New features must be covered by e2e or integration tests where practical.
+- Bug fixes should include a regression test when practical.
+
+## Surgical Changes
+
+Touch only what you must. Clean up only your own mess.
+When editing existing code:
+
+- Do not improve adjacent code, comments, or formatting.
+- Do not refactor things that are not broken.
+- Match existing style, even if you would do it differently.
+- If you notice unrelated dead code, mention it; do not delete it.
+
+When your changes create orphans:
+
+- Remove imports, variables, functions, and files that your changes made unused.
+- Do not remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## Goal-Driven Execution
+
+Define success criteria. Loop until verified.
+
+Transform tasks into verifiable goals:
+
+- "Add validation" -> "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
+- "Refactor X" -> "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+1. [Step] -> verify: [check]
+2. [Step] -> verify: [check]
+3. [Step] -> verify: [check]
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## Project Documentation
+
+{PROJECT_DOCUMENTATION_LINKS}
+
+## Codebase Index
+
+{CODEBASE_INDEX_LINKS}
+
+## Index Freshness
+
+If the codebase index files are more than one day old, regenerate them by running `.5/index/rebuild-index.sh` before relying on them.
+
+{CUSTOM_DOCUMENTATION}

package/src/templates/workflow/FIX-PLAN.md

@@ -16,7 +16,7 @@
 
 ## Feature Gap Fixes
 
-{If no feature gaps or Layer 2 was skipped: "No feature gaps found." or "Skipped — no feature.md available."}
+{If no feature gaps or Layer 2 was skipped: "No feature gaps found." or "Skipped — no plan.md available."}
 
 | # | File | Issue | Fix | Complexity |
 |---|------|-------|-----|------------|

package/src/templates/workflow/PLAN-COMPACT.md

@@ -0,0 +1,42 @@
+---
+ticket: {TICKET-ID}
+feature: {feature-name}
+created: {ISO-timestamp}
+planFormat: compact
+---
+
+<!-- PLAN RULES:
+- Use only for low-risk changes with 1-2 components.
+- Write requirements and implementation intent, not code.
+- Keep the Component Checklist human-readable. Do not add step/model/pattern/verify columns.
+- Decisions must be labeled [DECIDED], [FLEXIBLE], or [DEFERRED].
+-->
+
+# Plan: {TICKET-ID} - {Title}
+
+## Overview
+
+{Short narrative describing the problem and desired outcome.}
+
+## Scope
+
+- In: {included work}
+- Out: {excluded work}
+
+## Acceptance Criteria
+
+- [ ] {Observable success criterion}
+
+## Decisions
+
+- [DECIDED] {Decision and rationale}
+
+## Existing Patterns to Follow
+
+- `{path}` - {what pattern this provides}
+
+## Component Checklist
+
+| Component | Action | Target Path | Intent |
+|-----------|--------|-------------|--------|
+| {component-name} | modify | `{path}` | {one-sentence intent} |

package/src/templates/workflow/PLAN.md

@@ -1,52 +1,76 @@
 ---
 ticket: {TICKET-ID}
 feature: {feature-name}
-spec: .5/features/{feature-name}/feature.md
 created: {ISO-timestamp}
 ---
 
 <!-- PLAN RULES:
-- This file is interpolated into agent prompts. Write it as instructions, not documentation.
-- Description column: one action-oriented sentence per component
-- Pattern File column: path to an existing file the executor MUST read before implementing (establishes conventions)
-- Verify column: a concrete command or check the executor runs after implementing (grep pattern, test command, build check)
-- Depends On column: name of a component this one depends on (for cross-step data dependencies), or "—" if none
-- Implementation Notes: scoped with [global], [Step N], or [component-name] prefixes — the orchestrator filters per agent
-- Components table must cover all functional requirements from feature.md
-- Three test tiers: unit (always required for logic), integration (when framework detected + cross-module/DB/API), e2e (when framework detected + endpoints/UI flows)
-- Every "create" component with logic (services, controllers, repositories, utilities) must have a corresponding unit test component
-- Integration/e2e test components are planned only when the project has the corresponding framework
-- Declarative-only components (types, interfaces, route wiring) are exempt from test requirements
+- One planning artifact only: this file.
+- Write requirements and implementation intent, not code.
+- Keep the Component Checklist human-readable. Do not add step/model/pattern/verify columns; step-orchestrator-agent derives those into state.json.
+- Existing Patterns to Follow should name high-value files and conventions so the orchestrator can wire executor prompts cheaply.
+- Decisions must be labeled [DECIDED], [FLEXIBLE], or [DEFERRED].
+- Omit optional sections when they would only contain "none", "n/a", or placeholder content.
 -->
 
-# Implementation Plan: {TICKET-ID}
+# Plan: {TICKET-ID} - {Title}
 
-{One sentence summary of what this plan builds}
+## Overview
 
-## Components
+{Short narrative describing the problem, desired outcome, and why this change is needed.}
 
-| Step | Component | Action | File | Description | Pattern File | Verify | Complexity | Depends On |
-|------|-----------|--------|------|-------------|-------------|--------|------------|------------|
-| 1 | {name} | create | {path} | {what it does} | {existing file to read first} | {grep/test command} | simple | — |
-| 1 | {name} | create | {path} | {what it does} | {pattern} | {verify} | simple | — |
-| 2 | {name} | create | {path} | {what it does} | {pattern} | {verify} | moderate | {step-1-component} |
-| 2 | {name} | modify | {path} | {what to change} | {target file} | {verify} | moderate | — |
-| 3 | {name} | create | {path} | {what it does} | {pattern} | {verify} | complex | {step-2-component} |
-| 4 | {name} unit tests | create | {test-path} | Test {what it tests} | {existing test} | {test command} | moderate | {tested-component} |
-| 4 | {name} integration tests | create | {test-path} | Test {cross-module interaction} | {existing test} | {test command} | moderate | {tested-component} |
-| 4 | {name} e2e tests | create | {test-path} | Test {user-facing flow end-to-end} | {existing test} | {test command} | moderate | {tested-component} |
+## What Changes
 
-## Testing Strategy
+- {Logical behavior or capability that changes}
+- {User-visible or system-visible outcome}
 
-{Which test tiers apply to this feature and why. E.g.: "Unit tests for service logic. Integration tests for API endpoints using Supertest. No e2e — no UI changes."}
+## Existing Patterns to Follow
 
-## Implementation Notes
+- `{path}` - {what pattern this provides}
+- `{path}` - {what convention this establishes}
 
-- [global] Follow the pattern from {existing-file} for {component-type}
-- [Step N] {Convention or context relevant to all components in step N}
-- [{component-name}] {Key business rule or integration point specific to this component}
+## Constraints
 
-## Verification
+- {Technical, product, compatibility, performance, or rollout constraint}
 
-- Build: {command or "auto"}
-- Test: {command or "auto"}
+## Scope
+
+### In
+
+- {Included work}
+
+### Out
+
+- {Explicitly excluded work}
+
+## Acceptance Criteria
+
+- [ ] {Observable success criterion}
+- [ ] {Observable success criterion}
+
+## Decisions
+
+- [DECIDED] {Decision and rationale}
+- [FLEXIBLE] {Area where implementation may choose the best local pattern}
+- [DEFERRED] {Work intentionally not included}
+
+## Module Impact
+
+| Module/Area | Impact |
+|-------------|--------|
+| {module} | {create/modify/delete behavior at a high level} |
+
+## Component Checklist
+
+| Component | Action | Target Path | Intent |
+|-----------|--------|-------------|--------|
+| {component-name} | create | `{path}` | {one-sentence intent} |
+| {component-name} | modify | `{path}` | {one-sentence intent} |
+
+## Technical Notes
+
+- {Important implementation context, invariants, or migration notes}
+
+## Alternatives Considered
+
+- {Alternative}: {why it was not chosen}

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

@@ -8,15 +8,12 @@
 
 ## How to Use This File
 
-1. Review each finding below
-2. For each finding, choose an action:
-   - `[FIX]` - Apply this fix automatically (leave as-is)
-   - `[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: `/5:address-review-findings`
+1. Review this file if you want context before applying fixes
+2. Run: `/5:address-review-findings`
+3. The command will present each finding one by one with a recommendation
+4. Choose `fix`, `wont_fix`, `wait`, or provide textual instructions
 
-The command will read your annotations and apply marked fixes.
+The command records your decisions separately and applies only findings marked `fix`.
 
 ---
 
@@ -38,12 +35,6 @@ The command will read your annotations and apply marked fixes.
 {raw output from reviewer}
 ```
 
-**Action:** [FIX]
-
-**Custom Instructions:** (only if you selected [MANUAL])
-<!-- Add detailed instructions here if you want a custom fix -->
-
-
 ---
 
 ## Summary
@@ -54,5 +45,5 @@ The command will read your annotations and apply marked fixes.
 - Manual Review: {N}
 
 **Next Steps:**
-1. Edit this file to mark which findings to fix
-2. Run: `/5:address-review-findings`
+1. Run: `/5:address-review-findings`
+2. Decide on each finding interactively

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

@@ -11,6 +11,7 @@
 - **User-Resolved Questions:** {N}
 - **Manual Review Needed:** {N}
 - **Skipped by User:** {N}
+- **Deferred by User:** {N}
 
 ## Applied Fixes (User Approved)
 
@@ -29,6 +30,10 @@
 
 - `{file-path}:{line}` - User chose not to apply
 
+## Deferred Issues
+
+- `{file-path}:{line}` - User chose to wait
+
 ## Files Modified
 
 - {file-path} ({N} fixes applied)

package/src/templates/workflow/STATE.json

@@ -4,11 +4,40 @@
   "status": "in-progress",
   "currentStep": 1,
   "totalSteps": 0,
-  "pendingComponents": [],
+  "steps": [
+    {
+      "number": 1,
+      "name": "{step-name}",
+      "mode": "parallel",
+      "model": "haiku",
+      "components": []
+    }
+  ],
+  "pendingComponents": [
+    {
+      "name": "{component-name}",
+      "action": "create",
+      "step": 1,
+      "mode": "parallel",
+      "model": "haiku",
+      "file": "{target-path}",
+      "sourceFile": null,
+      "description": "{one-sentence intent}",
+      "dependsOn": [],
+      "patternRefs": [],
+      "verifyCommands": [],
+      "notes": []
+    }
+  ],
   "completedComponents": [],
-  "failedAttempts": [],
+  "recentFailures": [],
+  "baseline": {},
+  "latestCommandResults": [],
+  "verificationStatus": "pending",
   "verificationResults": {},
-  "commitResults": [],
+  "verifiedAt": null,
+  "latestCommitResults": [],
+  "eventLog": ".5/features/{feature-name}/state-events.jsonl",
   "startedAt": "{ISO-timestamp}",
   "lastUpdated": "{ISO-timestamp}"
 }

package/src/agents/component-executor.md

@@ -1,57 +0,0 @@
----
-name: component-executor
-description: Implements individual components by following existing codebase patterns. Spawned by /5:implement-feature orchestrator.
-tools: Read, Write, Edit, Glob, Grep, Bash, context7
----
-
-<role>
-You are a Component Executor. You implement individual components for a feature.
-You follow existing codebase patterns. You do NOT deviate from the plan.
-</role>
-
-<process>
-## Implementation Process
-
-1. **Read required files FIRST** — If your prompt includes a `Pattern File` or `Read First` field, you MUST read every listed file before writing any code. This establishes ground truth and prevents assumptions about conventions, naming, or structure.
-2. **For creating files:**
-   - Read the pattern file (from step 1) to understand conventions
-   - Create the new file following the same patterns exactly
-   - If no pattern file was provided, find a similar existing file via Glob and read it
-3. **For modifying files:**
-   - Read the target file
-   - Apply the described change via Edit
-   - Verify the change is correct
-4. **Run verify command** — If your prompt includes a `Verify` field, run that command and confirm it passes. If it fails, fix the issue (subject to the 3-attempt limit). If no verify command was provided, verify each file exists after changes.
-</process>
-
-<output-format>
-When done, output your result in this exact format:
-
----RESULT---
-STATUS: success | failed
-FILES_CREATED: [comma-separated paths]
-FILES_MODIFIED: [comma-separated paths]
-VERIFY: passed | failed | skipped
-DEVIATIONS: none | {brief list of auto-fixes applied}
-ERROR: none | {error description}
----END---
-</output-format>
-
-<deviation-rules>
-## Deviation Rules
-
-You WILL discover unplanned work. Handle as follows:
-
-| Trigger | Action | Permission |
-|---------|--------|------------|
-| Bug/error in existing code | Fix → verify → note in result | Auto |
-| Missing import/dependency | Add → verify → note in result | Auto |
-| Missing validation/auth/logging | Add → verify → note in result | Auto |
-| Blocking issue (prevents task completion) | Fix → verify → note in result | Auto |
-| Architectural change needed (new DB table, schema change, service switch) | STOP → report in ERROR field | Ask user |
-| Auth error ("401", "Not authenticated", "Set ENV_VAR") | STOP → report as AUTH_GATE in ERROR | Ask user |
-
-**Priority:** Architectural/Auth (ask) > Auto-fix rules > Unsure (treat as architectural, ask)
-
-**3-attempt limit:** If you have attempted 3 auto-fixes on a SINGLE issue and it still fails, STOP. Report the issue in the ERROR field with `ATTEMPTS_EXHAUSTED: {description}`. Do not keep trying — the orchestrator will handle it.
-</deviation-rules>