@curdx/flow 2.0.0-beta.5 → 2.0.0-beta.7

package/templates/research.md.tmpl

@@ -10,105 +10,74 @@ status: in_progress
 
 > **Goal**: {{SPEC_GOAL}}
 >
-> Output of this phase. Subsequent requirements / design / tasks are all based on the conclusions of this document.
+> **Fill only the sections that carry real information.** For a well-understood feature on a known stack, research legitimately compresses to: goal, one recommended direction, known constraints. Delete sections whose honest content would be "N/A" or "first time, nothing to fetch". Padding this document with "TBD" is worse than omitting sections.
 
 ---
 
-## 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)".
--->
+## Prior Experience (from claude-mem, if relevant)
 
 {{CLAUDE_MEM_FINDINGS}}
 
-## Problem Understanding
+<!-- Delete this section if there are no relevant prior observations. -->
 
-<!-- Translate the user's goal into technical language. Explicitly list assumptions. -->
+## Problem Understanding
 
 ### Core Problem
-<!-- One-line description of what we are solving -->
+<!-- One sentence. What are we solving? -->
 
 ### Explicit Assumptions
-<!-- Karpathy principle 1: think before coding. List all assumptions for the user to confirm -->
+<!-- Only real assumptions that matter. Don't list "assumption: we will write code." -->
+
 - Assumption 1: ...
-- Assumption 2: ...
 
 ### Known Constraints
-- Tech stack:
-- Budget / time:
-- Team capability:
-- Compliance requirements:
-
-## Technical Solution Space
+<!-- Include only the constraints that actually shape the solution. -->
 
-<!-- List 2-3 possible approaches with their pros and cons. Pick one in the design phase. -->
+- Tech stack: ...
+- Time budget: ...
+- (Compliance, team capability, etc — only if they constrain this feature)
 
-### Option A: ...
-- **Pros**:
-- **Cons**:
-- **Complexity**: low / medium / high
-- **Docs (context7 queries)**:
-  - `library-name@version`: ...
+## Technical Solution Space
 
-### Option B: ...
-- **Pros**:
-- **Cons**:
-- **Complexity**: low / medium / high
+<!--
+If one approach is clearly the right call for this stack, write only that approach with its rationale.
+Include alternative options ONLY when there is a genuine tradeoff a thoughtful engineer might disagree on.
+Do not invent Option B and Option C just to fill the template.
+-->
 
-### Option C (optional): ...
+### Recommended Approach: ...
+- **Why**: ...
+- **Complexity**: ...
+- **Key APIs verified via context7**: ...
 
-## Existing Code Analysis
+### Alternative: ... (include only if a real alternative exists)
 
-<!-- Codebase scan results. Which existing modules can be reused? Which need to be new? -->
+## Existing Code Analysis (include only if the codebase has relevant prior work)
 
 ### 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
+- `path/to/module` — ...
 
-<!-- Explicitly answer: can this be done? how hard is it? -->
+### New Modules Required
+- `path/to/new` — ...
 
-- **Feasibility**: ✓ feasible / ⚠ risky / ✗ not recommended
-- **Estimated complexity**: 1-10
-- **Main risks**:
-  - Risk 1: ...
-  - Risk 2: ...
+## Latest Documentation Summary
 
-## Recommended Direction
+<!-- Only include libraries whose API is version-sensitive AND used by this feature. Do not cite every library in the stack. -->
 
-<!-- Research conclusion: which option is recommended and why. If multiple options need discussion, explain here. -->
+### {{LIBRARY}}
+- Version: ...
+- Relevant APIs: ...
+- Gotchas: ...
 
-**Recommendation**: Option ?
-**Rationale**:
-**To confirm in the design phase**:
+## Feasibility
 
-## Open Questions
+- **Verdict**: feasible / risky / not recommended
+- **Main risks**: (only if real risks exist)
 
-<!-- Questions the research phase couldn't answer, to be deferred to later phases or asked of the user -->
+## Open Questions (delete if none)
 
 1. ...
-2. ...
 
 ---
 
-_Generated by flow-researcher agent on {{CREATED_DATE}}. Subsequent phases continue from this document._
+_Generated by flow-researcher on {{CREATED_DATE}}._

package/templates/tasks.md.tmpl

@@ -5,137 +5,80 @@ 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**.
+> POC-First is an **orientation, not a mandate**. Use the phases below as an organizing idea and **delete phases that don't apply to this feature**. A bug-fix may be one task. A prototype may skip Phase 2 (refactor) and Phase 5 (PR lifecycle). A library may skip the PR lifecycle entirely. Forcing all five phases for a small feature is the padding pattern this template is designed to prevent.
 >
-> Each task includes: `Do`, `Files`, `Done-when`, `Verify`, `Commit`. Verifiable via automation.
+> Each task includes whatever of `Do`, `Files`, `Done-when`, `Verify`, `Commit` is needed for the executor to finish it in a single sub-agent dispatch. Verify must be an automated command (no "manual test").
 
 ---
 
 ## 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)
+- `[P]` parallel-safe (dispatch in parallel within the same wave)
+- `[VERIFY]` quality checkpoint (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.
+> Goal: end-to-end runnable. Hardcoding is acceptable; skip tests here.
 
-- [ ] **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
+<!-- Add only the tasks this feature genuinely needs. Do not invent skeleton tasks to "round out" the phase. -->
 
-- [ ] **1.2** [P] ...
+- [ ] **1.1** ...
   - **Do**: ...
   - **Files**: ...
   - **Done when**: ...
   - **Verify**: ...
   - **Commit**: ...
-  - _Requirements_: ...
-  - _Design_: AD-01
+  - _Requirements_: FR-NN
 
-- [ ] **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)
+- [ ] **1.X** [VERIFY] End-to-end POC verification
+  - **Verify**: `<command>`
+  - **Done when**: happy path returns the expected result
 
-## Phase 2: Refactoring
+## Phase 2: Refactoring (delete if the POC is already clean)
 
-> 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
+> Include only if the POC has genuine duplication or structural mud that warrants cleanup. Skip for tiny features.
 
 ## 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`
+> Rule: tests first. Red → Green → Yellow. **Collapse red+green into one task when the test and implementation are trivially paired**; split only when the test genuinely precedes a nontrivial implementation.
 
-- [ ] **3.4** [RED → GREEN → YELLOW] Integration tests
-  - <!-- Repeat the TDD cycle -->
+- [ ] **3.X** [RED→GREEN→YELLOW] ...
 
-- [ ] **3.5** [VERIFY] Coverage check
-  - **Verify**: `npm test -- --coverage` — core logic > 80%
+- [ ] **3.X+1** [VERIFY] Coverage check
+  - **Verify**: coverage on the changed surface ≥ project standard
 
 ## 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
+> Include only the checks this project actually runs. `npx eslint` is dead weight if the project uses biome. `tsc --strict` is dead weight for a JS project.
 
-- [ ] **5.1** Generate PR
-  - **Do**: `/flow-ship` creates the PR
-  - **Done when**: PR URL returned, description is clear
+- [ ] **4.X** [VERIFY] Final health check
+  - **Do**: flow-verifier performs goal-driven reverse verification
+  - **Done when**: every FR/AC has an automated check
 
-- [ ] **5.2** Respond to review feedback
-  - **Do**: iterate until approved
-  - **Verify**: CI all green
+## Phase 5: PR Lifecycle (delete for local-only work, scripts, internal tools without a PR flow)
 
-- [ ] **5.3** Merge
-  - **Do**: `/flow-land`
-  - **Verify**: the main branch contains all commits for this spec
+- [ ] **5.X** Ship / Land
 
 ---
 
 ## Coverage Audit
 
-<!-- Final step for flow-planner: confirm every FR / AC / AD / D has a corresponding task -->
+<!-- flow-planner fills this in. Every FR / AC / AD / D must map to a task, or explicitly defer with reason. -->
 
 | Requirement ID | Task(s) | Status |
 |--------|---------|------|
-| FR-01 | 1.2, 3.1 | ✓ |
-| FR-02 | ... | ⚠ uncovered — needs adding |
-| AD-01 | 1.1 | ✓ |
-| D-05 (STATE.md) | ... | ✓ |
+| FR-01 | ... | ✓ |
 
-**Uncovered items must be handled**: add a task or document the deferral reason in 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._
+_Generated by flow-planner on {{CREATED_DATE}}._