5-phase-workflow 1.8.9 → 1.9.1

package/src/skills/generate-readme/TEMPLATE.md

@@ -75,7 +75,7 @@ Examples:
 
 **DO NOT include:**
 
-- General patterns covered in CLAUDE.md
+- General patterns covered in AGENTS.md
 - Obvious patterns like "use builders for construction"
 - Implementation details
 
@@ -95,8 +95,8 @@ Examples:
 
 **Don't include:**
 
-- Links to CLAUDE.md sections relevant to this module
-- Don't repeat things and patterns already documented in CLAUDE.md
+- Links to AGENTS.md sections relevant to this module
+- Don't repeat things and patterns already documented in AGENTS.md
 
 **Include for:**
 
@@ -112,7 +112,7 @@ Examples:
 
 1. List every validator, query, or handler class individually
 2. Document implementation details
-3. Copy content from CLAUDE.md
+3. Copy content from AGENTS.md
 4. Include exhaustive method signatures
 5. Create walls of text
 6. Document every package
@@ -122,7 +122,7 @@ Examples:
 
 1. Focus on top-level overview
 2. List 3-5 key components only
-3. Reference CLAUDE.md for patterns
+3. Reference AGENTS.md for patterns
 4. Keep it under 100 lines
 5. Use examples sparingly
 6. Use package references for groups

package/src/templates/workflow/FEATURE-SPEC.md

@@ -4,6 +4,8 @@
 - Entity definitions describe data concepts, not schemas or interfaces
 - Acceptance criteria describe observable behavior, not test assertions
 - NO code, pseudo-code, or implementation details anywhere in this document
+- Visual Overview section is OPTIONAL — delete it if the feature doesn't benefit from diagrams
+- Mermaid diagrams describe WHAT happens, not HOW it is implemented
 -->
 
 # Feature: {TICKET-ID} - {Title}
@@ -12,27 +14,57 @@
 {TICKET-ID}
 
 ## Summary
-{1-2 sentence overview of what will be implemented}
+{1-2 sentence overview: what capability is being added and who benefits}
 
 ## Problem Statement
-{Why is this feature needed? What problem does it solve?}
+{Describe the current pain point or gap. Who experiences it and what is the impact?}
+
+## Visual Overview
+<!-- OPTIONAL: Include mermaid diagrams only when they add clarity to the feature.
+     Delete this entire section if the feature is simple enough to understand without diagrams.
+     Use whichever diagram types are relevant — you don't need all of them. -->
+
+<!-- Process Flow — use when the feature involves a multi-step process or state transitions -->
+```mermaid
+flowchart TD
+    A[Start state] --> B[Step 1]
+    B --> C{Decision point}
+    C -->|Yes| D[Outcome 1]
+    C -->|No| E[Outcome 2]
+```
+
+<!-- Entity Relationships — use when new data concepts relate to existing ones -->
+```mermaid
+erDiagram
+    ENTITY-A ||--o{ ENTITY-B : "relationship"
+    ENTITY-B }|--|| ENTITY-C : "relationship"
+```
+
+<!-- Component Interactions — use when multiple modules or services communicate -->
+```mermaid
+sequenceDiagram
+    actor User
+    participant ComponentA
+    participant ComponentB
+    User->>ComponentA: action
+    ComponentA->>ComponentB: interaction
+    ComponentB-->>User: result
+```
 
 ## Requirements
 
 ### Functional Requirements
-- {Requirement 1}
-- {Requirement 2}
+- {The system shall... [describe observable behavior]}
 - ...
 
 ### Non-Functional Requirements
-- {Performance requirements}
-- {Compatibility requirements}
+- {Performance, reliability, scalability, or compatibility expectations}
 - ...
 
 ## Constraints
-- {Business constraints}
-- {Technical constraints}
-- {Time/resource constraints}
+- {Business rules that limit the solution space}
+- {Technical boundaries from existing architecture}
+- {Timeline or resource limitations}
 
 ## Affected Components
 - **{component/module-1}** - {What changes here}
@@ -56,9 +88,9 @@
 - ...
 
 ## Acceptance Criteria
-- [ ] {Criterion 1 - how to verify success}
-- [ ] {Criterion 2}
-- [ ] {Criterion 3}
+- [ ] {Observable behavior that proves this requirement is met}
+- [ ] {Observable behavior that proves this requirement is met}
+- [ ] {Observable behavior that proves this requirement is met}
 - ...
 
 ## Alternatives Considered
@@ -78,22 +110,24 @@
 
 ## Decisions
 
-<!-- Tag every Q&A with exactly one of: [DECIDED], [FLEXIBLE], [DEFERRED]
-  - [DECIDED]: Locked decision — Phase 2 planner and Phase 3 agents MUST honor exactly
-  - [FLEXIBLE]: Claude's discretion — planner chooses the best approach
-  - [DEFERRED]: Explicitly out of scope — planner MUST NOT include in the plan
+<!-- Record key decisions from the spec discussion.
+     Tag each with exactly one of: [DECIDED], [FLEXIBLE], [DEFERRED]
+     - [DECIDED]: Locked — Phase 2 planner and Phase 3 agents MUST honor exactly
+     - [FLEXIBLE]: Claude's discretion — planner chooses the best approach
+     - [DEFERRED]: Out of scope — planner MUST NOT include in the plan
 -->
 
-### Q1: {Question from collaboration phase}
-**A:** {Answer from developer} **[DECIDED]**
+### {Topic: brief description of what was decided}
+**Context:** {Why this decision came up}
+**Decision:** {What was decided} **[DECIDED]**
 
-### Q2: {Question}
-**A:** {Answer} **[FLEXIBLE]**
+### {Topic: area left to implementer's discretion}
+**Context:** {What was discussed}
+**Decision:** {General direction, implementer chooses specifics} **[FLEXIBLE]**
 
-### Q3: {Question about a nice-to-have}
-**A:** {Answer — let's skip this for now} **[DEFERRED]**
-
-...
+### {Topic: explicitly deferred item}
+**Context:** {Why it was raised}
+**Decision:** {Not addressing now — reason} **[DEFERRED]**
 
 ## Next Steps
 After approval:

package/src/templates/workflow/PLAN.md

@@ -10,7 +10,8 @@ created: {ISO-timestamp}
 - 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)
-- Implementation Notes: reference existing files as patterns, no code snippets
+- 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
@@ -24,16 +25,16 @@ created: {ISO-timestamp}
 
 ## Components
 
-| Step | Component | Action | File | Description | Pattern File | Verify | Complexity |
-|------|-----------|--------|------|-------------|-------------|--------|------------|
-| 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 |
-| 2 | {name} | modify | {path} | {what to change} | {target file} | {verify} | moderate |
-| 3 | {name} | create | {path} | {what it does} | {pattern} | {verify} | complex |
-| 4 | {name} unit tests | create | {test-path} | Test {what it tests} | {existing test} | {test command} | moderate |
-| 4 | {name} integration tests | create | {test-path} | Test {cross-module interaction} | {existing test} | {test command} | moderate |
-| 4 | {name} e2e tests | create | {test-path} | Test {user-facing flow end-to-end} | {existing test} | {test command} | moderate |
+| 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} |
 
 ## Testing Strategy
 
@@ -41,9 +42,9 @@ created: {ISO-timestamp}
 
 ## Implementation Notes
 
-- Follow the pattern from {existing-file} for {component-type}
-- {Key business rule to remember}
-- {Integration point to wire up}
+- [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}
 
 ## Verification