@curdx/flow 1.1.3 → 1.1.5

package/templates/progress.md.tmpl

@@ -0,0 +1,58 @@
+# Progress Log: {{SPEC_NAME}}
+
+> Living document. The agent appends here every time a task is completed / a gotcha is discovered / a decision is made.
+>
+> On resume after an interruption, the agent reads this file to rebuild context.
+
+---
+
+## Reality Check (current actual state)
+
+<!-- At the start of each session, the agent reconciles: expected state vs actual state -->
+
+**Last updated**: {{CREATED_DATE}}
+
+- Current phase: research
+- Current task: N/A (tasks phase not yet entered)
+- Blockers: none
+
+## Completed Tasks
+
+<!-- List of completed tasks -->
+
+_(not yet started)_
+
+## Learnings
+
+<!-- Things the agent discovered during execution that are worth remembering (useful for similar future situations) -->
+
+### Gotchas
+_(none)_
+
+### Patterns that worked
+_(none)_
+
+### Approaches that didn't work
+_(none)_
+
+## Decisions Made Here
+
+<!-- Technical decisions made within this spec (major decisions should be synced to .flow/STATE.md) -->
+
+_(none)_
+
+## Next Steps
+
+<!-- What to do next. Must be filled in before ending the session. -->
+
+- [ ] Enter the research phase: run `/flow-research`
+
+## Questions for User
+
+<!-- Questions that need user answers -->
+
+_(none)_
+
+---
+
+_Spec initialized on {{CREATED_DATE}}._

package/templates/requirements.md.tmpl

@@ -0,0 +1,94 @@
+---
+spec: {{SPEC_NAME}}
+phase: requirements
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+depends_on: research.md
+---
+
+# Requirements Spec: {{SPEC_NAME}}
+
+> **Recommended direction from the research phase**: {{RESEARCH_CONCLUSION}}
+>
+> This phase: translate "technically feasible" into "concrete behaviors users benefit from".
+
+---
+
+## User Stories
+
+<!-- Each story follows the format: As X, I want Y, so that Z -->
+
+### US-01: ...
+**As** [user role],
+**I want** [capability],
+**so that** [business value].
+
+**Acceptance criteria**:
+- AC-1.1: [verifiable behavior]
+- AC-1.2: [verifiable behavior]
+- AC-1.3: [edge case handling]
+
+### US-02: ...
+<!-- ... -->
+
+## Functional Requirements
+
+<!-- FR-NN format. Each FR must be a verifiable statement of "the system must X". -->
+
+- **FR-01**: The system must ...
+- **FR-02**: The system must ...
+- **FR-03**: ...
+
+## Non-Functional Requirements
+
+### Performance
+- **NFR-P-01**: [e.g. P95 response time < 200ms]
+- **NFR-P-02**: ...
+
+### Security
+- **NFR-S-01**: ...
+- **NFR-S-02**: ...
+
+### Maintainability
+- **NFR-M-01**: ...
+
+### Compatibility
+- **NFR-C-01**: ...
+
+## Edge Cases and Error Handling
+
+<!-- Must be explicit: what happens on failure? how are abnormal inputs handled? -->
+
+| Scenario | Expected behavior |
+|-----|--------|
+| Network disconnected | ... |
+| Database exception | ... |
+| Invalid input | ... |
+| Concurrent conflict | ... |
+
+## Out of Scope
+
+<!-- Karpathy principle 2: simplicity first. Explicitly list "not this time" to prevent scope creep. -->
+
+- ✗ Feature A — deferred to the next version
+- ✗ Feature B — out of budget
+- ✗ Feature C — needs its own spec
+
+## Success Metrics
+
+<!-- Must be quantifiable -->
+
+- Metric 1: [e.g. user signup completion rate > 80%]
+- Metric 2: [e.g. complaint rate < 1%]
+
+## Open Questions
+
+<!-- Questions that need user answers -->
+
+1. **Question 1**: ...
+2. **Question 2**: ...
+
+---
+
+_Generated by flow-product-designer agent on {{CREATED_DATE}}. After user review, proceed to the design phase._

package/templates/research.md.tmpl

@@ -0,0 +1,114 @@
+---
+spec: {{SPEC_NAME}}
+phase: research
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+---
+
+# Research Report: {{SPEC_NAME}}
+
+> **Goal**: {{SPEC_GOAL}}
+>
+> Output of this phase. Subsequent requirements / design / tasks are all based on the conclusions of this document.
+
+---
+
+## Prior Experience (from claude-mem)
+
+<!--
+flow-researcher first calls mcp__claude_mem__search to retrieve relevant history.
+If there are relevant observations, summarize them here; if not, write "(first research on this topic)".
+-->
+
+{{CLAUDE_MEM_FINDINGS}}
+
+## Problem Understanding
+
+<!-- Translate the user's goal into technical language. Explicitly list assumptions. -->
+
+### Core Problem
+<!-- One-line description of what we are solving -->
+
+### Explicit Assumptions
+<!-- Karpathy principle 1: think before coding. List all assumptions for the user to confirm -->
+- Assumption 1: ...
+- Assumption 2: ...
+
+### Known Constraints
+- Tech stack:
+- Budget / time:
+- Team capability:
+- Compliance requirements:
+
+## Technical Solution Space
+
+<!-- List 2-3 possible approaches with their pros and cons. Pick one in the design phase. -->
+
+### Option A: ...
+- **Pros**:
+- **Cons**:
+- **Complexity**: low / medium / high
+- **Docs (context7 queries)**:
+  - `library-name@version`: ...
+
+### Option B: ...
+- **Pros**:
+- **Cons**:
+- **Complexity**: low / medium / high
+
+### Option C (optional): ...
+
+## Existing Code Analysis
+
+<!-- Codebase scan results. Which existing modules can be reused? Which need to be new? -->
+
+### Reusable Modules
+- `path/to/existing-module.ts` — ...
+
+### Modules to Create
+- `path/to/new-module.ts` — ...
+
+### Modules to Modify
+- `path/to/modify.ts` — ...
+
+## Latest Documentation Summary (context7)
+
+<!-- Latest APIs / best practices found by flow-researcher via mcp__context7__* -->
+
+### {{LIBRARY_1}}
+- Version:
+- Relevant APIs:
+- Gotchas / changes:
+
+### {{LIBRARY_2}}
+- ...
+
+## Feasibility Assessment
+
+<!-- Explicitly answer: can this be done? how hard is it? -->
+
+- **Feasibility**: ✓ feasible / ⚠ risky / ✗ not recommended
+- **Estimated complexity**: 1-10
+- **Main risks**:
+  - Risk 1: ...
+  - Risk 2: ...
+
+## Recommended Direction
+
+<!-- Research conclusion: which option is recommended and why. If multiple options need discussion, explain here. -->
+
+**Recommendation**: Option ?
+**Rationale**:
+**To confirm in the design phase**:
+
+## Open Questions
+
+<!-- Questions the research phase couldn't answer, to be deferred to later phases or asked of the user -->
+
+1. ...
+2. ...
+
+---
+
+_Generated by flow-researcher agent on {{CREATED_DATE}}. Subsequent phases continue from this document._

package/templates/tasks.md.tmpl

@@ -0,0 +1,141 @@
+---
+spec: {{SPEC_NAME}}
+phase: tasks
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+depends_on: design.md
+task_size: fine
+---
+
+# Task Breakdown: {{SPEC_NAME}}
+
+> POC-First 5 Phases: **work → refactor → test → quality gates → PR lifecycle**.
+>
+> Each task includes: `Do`, `Files`, `Done-when`, `Verify`, `Commit`. Verifiable via automation.
+
+---
+
+## Marker Rules
+
+- `[ ]` TODO / `[x]` done
+- `[P]` parallel-safe (can be dispatched in parallel within the same wave)
+- `[VERIFY]` quality checkpoint (run by the flow-verifier agent)
+- `[SEQUENTIAL]` must be serial (breaks the parallel group)
+
+---
+
+## Phase 1: Make It Work (POC)
+
+> Goal: get it running end-to-end. Hardcoding is acceptable; skip tests.
+
+- [ ] **1.1** [P] Initialize module skeleton
+  - **Do**: create `src/{{MODULE}}/` directory, add `index.ts`, `types.ts`
+  - **Files**: `src/{{MODULE}}/index.ts`, `src/{{MODULE}}/types.ts`
+  - **Done when**: directory exists, `import {} from './{{MODULE}}'` does not error
+  - **Verify**: `npx tsc --noEmit`
+  - **Commit**: `feat({{MODULE}}): initialize module skeleton`
+  - _Requirements_: FR-01
+
+- [ ] **1.2** [P] ...
+  - **Do**: ...
+  - **Files**: ...
+  - **Done when**: ...
+  - **Verify**: ...
+  - **Commit**: ...
+  - _Requirements_: ...
+  - _Design_: AD-01
+
+- [ ] **1.3** [VERIFY] End-to-end POC verification
+  - **Do**: run the happy path manually, confirm the core scenario works
+  - **Verify**: `curl http://localhost:3000/... | jq`
+  - **Done when**: returns expected data (edge cases may still be wrong)
+
+## Phase 2: Refactoring
+
+> Goal: clean up the code structure. Behavior unchanged.
+
+- [ ] **2.1** Extract duplicated logic
+  - **Do**: ...
+  - **Verify**: `npx tsc --noEmit && git diff --stat`
+  - **Commit**: `refactor({{MODULE}}): extract common logic`
+
+- [ ] **2.2** [VERIFY] Refactor does not break behavior
+  - **Verify**: rerun the manual test from Phase 1
+  - **Done when**: all outputs match
+
+## Phase 3: Testing (TDD red / green / yellow)
+
+> Rule: tests first. Let the test fail first (RED), then implement (GREEN), then clean up (YELLOW).
+
+- [ ] **3.1** [RED] Write failing tests — unit
+  - **Do**: write unit tests for core functions
+  - **Files**: `src/{{MODULE}}/*.test.ts`
+  - **Verify**: `npm test -- src/{{MODULE}}` — expected to fail
+  - **Commit**: `test({{MODULE}}): red - add unit tests for core logic`
+
+- [ ] **3.2** [GREEN] Make tests pass
+  - **Do**: fix the implementation so the tests from 3.1 pass
+  - **Verify**: `npm test -- src/{{MODULE}}` — all green
+  - **Commit**: `feat({{MODULE}}): green - satisfy unit tests`
+
+- [ ] **3.3** [YELLOW] Refactor and clean up
+  - **Do**: clean up the implementation, tests still pass
+  - **Commit**: `refactor({{MODULE}}): yellow - clean implementation`
+
+- [ ] **3.4** [RED → GREEN → YELLOW] Integration tests
+  - <!-- Repeat the TDD cycle -->
+
+- [ ] **3.5** [VERIFY] Coverage check
+  - **Verify**: `npm test -- --coverage` — core logic > 80%
+
+## Phase 4: Quality Gates
+
+> Full local checks. Last gate before CI.
+
+- [ ] **4.1** TypeScript strict check
+  - **Verify**: `npx tsc --strict --noEmit` — 0 errors
+  - **Commit**: `chore({{MODULE}}): tsc strict passes`
+
+- [ ] **4.2** Lint
+  - **Verify**: `npx eslint src/{{MODULE}}` — 0 errors, 0 warnings
+
+- [ ] **4.3** All tests pass
+  - **Verify**: `npm test` — all green
+
+- [ ] **4.4** [VERIFY] Final health check
+  - **Do**: flow-verifier agent performs goal-driven reverse verification
+  - **Done when**: every FR-XX and AC-X.Y has a corresponding automated verification
+
+## Phase 5: PR Lifecycle
+
+- [ ] **5.1** Generate PR
+  - **Do**: `/flow-ship` creates the PR
+  - **Done when**: PR URL returned, description is clear
+
+- [ ] **5.2** Respond to review feedback
+  - **Do**: iterate until approved
+  - **Verify**: CI all green
+
+- [ ] **5.3** Merge
+  - **Do**: `/flow-land`
+  - **Verify**: the main branch contains all commits for this spec
+
+---
+
+## Coverage Audit
+
+<!-- Final step for flow-planner: confirm every FR / AC / AD / D has a corresponding task -->
+
+| Requirement ID | Task(s) | Status |
+|--------|---------|------|
+| FR-01 | 1.2, 3.1 | ✓ |
+| FR-02 | ... | ⚠ uncovered — needs adding |
+| AD-01 | 1.1 | ✓ |
+| D-05 (STATE.md) | ... | ✓ |
+
+**Uncovered items must be handled**: add a task or document the deferral reason in STATE.md.
+
+---
+
+_Generated by flow-planner agent on {{CREATED_DATE}}. N tasks total, estimated X hours._