@curdx/flow 2.0.0-beta.1 → 2.0.0-beta.11

package/templates/design.md.tmpl

@@ -9,155 +9,75 @@ depends_on: requirements.md
 
 # Technical Design: {{SPEC_NAME}}
 
-> Conclusions from the flow-architect agent using at least 8 rounds of `sequential-thinking` reasoning.
-> This document freezes the technical choices. Subsequent tasks / implementation strictly follow this design.
+> Conclusions from flow-architect. Sequential-thinking is invoked proportional to the genuine tradeoff surface — the chain lives in the thinking tool, not this document.
+>
+> **Fill only the sections that carry real design information for this feature.** Well-known stack assemblies legitimately compress to a stack list + data model + a few real ADs. Delete sections whose honest answer would be "N/A" or "standard for this stack". A forced 13-section template is the bloat pattern this is designed to prevent.
 
 ---
 
 ## Design Overview (one paragraph)
 
-<!-- One-sentence summary of the architecture -->
+<!-- One sentence summary of the approach. -->
 
 ## Architecture Decisions
 
-<!-- Each major decision gets an ID and is written to the decisions array in .flow/STATE.md -->
+<!-- Each real decision gets an AD-NN. If a decision is "obvious, no alternative worth listing," use one line and move on. -->
 
 ### AD-01: ...
-- **Decision**: Use X instead of Y
+- **Decision**: Use X
 - **Rationale**: ...
-- **Trade-off**: Accepted [downside] in exchange for [upside]
-- **sequentialthinking rounds**: rounds 3-5
-
-### AD-02: ...
-
-## System Architecture Diagram
-
-```mermaid
-flowchart TB
-  <!-- actual data flow generated by flow-architect -->
-  User[User] --> API[API Gateway]
-  API --> Auth[Auth Service]
-  Auth --> DB[(Database)]
-```
+- **Trade-off**: ... (omit if there is no genuine tradeoff)
 
 ## Component Design
 
-<!-- Each component is independently testable. Interfaces are explicit. -->
+<!-- Each component: responsibility, input type, output type, dependencies, error path. Skip if the feature is a single module with no internal boundaries worth naming. -->
 
-### Component: {{COMP_NAME_1}}
+### Component: {{COMP_NAME}}
 - **Responsibility**: ...
-- **Input**:
-  ```ts
-  interface Input {
-    field: Type;
-  }
-  ```
-- **Output**:
-  ```ts
-  interface Output {
-    field: Type;
-  }
-  ```
-- **Dependencies**: Component X, Library Y
-- **Errors**:
-  - `ErrorCode.X` — when ... happens
-  - `ErrorCode.Y` — when ... happens
-
-### Component: {{COMP_NAME_2}}
-<!-- ... -->
-
-## Data Model
-
-<!-- Database schema / data structures -->
-
-### Entity: ...
-```sql
-CREATE TABLE ... (
-  id UUID PRIMARY KEY,
-  ...
-);
-```
+- **Input**: `interface Input { ... }`
+- **Output**: `interface Output { ... }`
+- **Dependencies**: ...
+- **Errors**: ...
 
-### Or TypeScript types:
-```ts
-interface Entity {
-  id: string;
-  ...
-}
-```
+## Data Model (if the feature touches persistence or structured data)
 
-## State Machine (if applicable)
+<!-- SQL schema, TypeScript types, or API payload shape. Delete if the feature has no meaningful data shape. -->
+
+## Architecture Diagram (include only when it clarifies; prose often suffices)
 
 ```mermaid
-stateDiagram-v2
-  [*] --> Pending
-  Pending --> Active: approve
-  Pending --> Rejected: reject
-  Active --> Completed: finish
+flowchart TB
+  ...
 ```
 
-## Error Path Design
+## State Machine (include only if the feature has non-trivial state transitions)
 
-<!-- Full flow on failure -->
+## Error Path Design (include when error behavior is not obvious)
 
-| Scenario | Upstream Behavior | System Response | User-visible |
-|-----|--------|---------|---------|
-| DB connection lost | retry 3 times | return 503 | "Temporarily unavailable, retry in 1 minute" |
-| Rate limit hit | none | return 429 | "Too many requests, retry in 60 seconds" |
+| Scenario | System Response | User-visible |
+|-----|---------|---------|
+| ... | ... | ... |
 
-## API Contract
-
-<!-- If this is an API project -->
+## API Contract (include only if this feature exposes or changes an API)
 
 ```yaml
-POST /api/v1/...
-Request:
-  body:
-    field: string
-Response:
-  200:
-    body:
-      field: string
-  400:
-    body:
-      error: string
+...
 ```
 
-## Test Matrix
+## Test Matrix (brief — one line per layer)
 
 | Layer | Coverage | Tool |
 |---|-----|------|
-| Unit | All pure functions | vitest |
-| Integration | Between components | vitest + supertest |
-| E2E | Complete user flows | playwright / chrome-devtools MCP |
-
-### Key Test Scenarios
-1. Happy path: ...
-2. Edge case 1: ...
-3. Error recovery: ...
-
-## Suggested Implementation Order
-
-<!-- Reference for decomposition in the tasks phase -->
-
-1. Build skeleton first (Component A → empty implementation)
-2. Then wire up the real logic (core logic of Component A)
-3. Connect DB (persistence for Component A)
-4. Then do Component B ...
-
-## Risks and Mitigations
+| ... | ... | ... |
 
-| Risk | Level | Mitigation |
-|-----|-----|------|
-| ... | medium | ... |
+## Risks and Mitigations (include only if risks exist that aren't obvious from the ADs)
 
 ## Defer to Implementation
 
-<!-- Decisions not worth spending time on in the design phase -->
+<!-- Decisions explicitly deferred to when the executor writes the code. -->
 
-- Logging library choice → reuse project's existing one during implementation
-- Caching strategy → no caching initially, adjust based on data after launch
+- ...
 
 ---
 
-_Generated by flow-architect agent on {{CREATED_DATE}}. After user reviews and approves AD-01~N, proceed to the tasks phase._
+_Generated by flow-architect on {{CREATED_DATE}}._

package/templates/requirements.md.tmpl

@@ -9,86 +9,68 @@ depends_on: research.md
 
 # Requirements Spec: {{SPEC_NAME}}
 
-> **Recommended direction from the research phase**: {{RESEARCH_CONCLUSION}}
+> **Recommended direction from research**: {{RESEARCH_CONCLUSION}}
 >
-> This phase: translate "technically feasible" into "concrete behaviors users benefit from".
+> **Fill only the sections that carry real information for this feature.** Delete or collapse any section whose honest content would be "N/A" or "same as usual". Padding sections with "TBD" is worse than omitting them.
 
 ---
 
 ## 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].
+**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]
+- AC-1.2: ...
 
-### US-02: ...
-<!-- ... -->
+<!-- Add more US-NN blocks only if the feature genuinely has multiple independent user flows. -->
 
 ## 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**: ...
+- **FR-02**: ...
 
 ## Non-Functional Requirements
 
-### Performance
-- **NFR-P-01**: [e.g. P95 response time < 200ms]
-- **NFR-P-02**: ...
+<!--
+Include ONLY the NFR categories that this feature is actually constrained by.
+For a small internal CRUD feature, "Performance / Security / Maintainability / Compatibility" as a four-bucket grid is usually padding.
+Delete categories that have no real requirement, or collapse into one line: "NFR: standard for this stack, no special constraints."
+-->
 
-### Security
-- **NFR-S-01**: ...
-- **NFR-S-02**: ...
+### Performance (if applicable)
+- **NFR-P-01**: ...
 
-### Maintainability
-- **NFR-M-01**: ...
+### Security (if applicable)
+- **NFR-S-01**: ...
 
-### Compatibility
-- **NFR-C-01**: ...
+<!-- Delete Maintainability / Compatibility sections unless they carry a real constraint. -->
 
 ## Edge Cases and Error Handling
 
-<!-- Must be explicit: what happens on failure? how are abnormal inputs handled? -->
+<!-- Include rows only for scenarios that actually apply. -->
 
 | 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
+## Success Metrics (if the feature has measurable outcomes)
 
-<!-- Must be quantifiable -->
+<!-- Delete this section for internal tools or refactors with no user-visible metric. -->
 
-- Metric 1: [e.g. user signup completion rate > 80%]
-- Metric 2: [e.g. complaint rate < 1%]
+- Metric 1: ...
 
 ## Open Questions
 
-<!-- Questions that need user answers -->
+<!-- Include only if there are genuinely unresolved questions. Delete when empty. -->
 
-1. **Question 1**: ...
-2. **Question 2**: ...
+1. ...
 
 ---
 
-_Generated by flow-product-designer agent on {{CREATED_DATE}}. After user review, proceed to the design phase._
+_Generated by flow-product-designer on {{CREATED_DATE}}._

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}}._

package/hooks/scripts/fail-tracker.sh

@@ -1,31 +0,0 @@
-#!/usr/bin/env bash
-# CurDX-Flow PostToolUseFailure Hook
-# Tracks consecutive tool failures to enable pua integration (Phase 4+).
-# For now, just maintains a counter in plugin data directory.
-#
-# Future: when pua is installed and fail_count >= threshold, auto-invoke /pua:pua.
-
-set -u
-
-DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
-COUNTER="$DATA_DIR/fail-count"
-
-mkdir -p "$DATA_DIR" 2>/dev/null || true
-
-# Read current count
-CURRENT=0
-[ -f "$COUNTER" ] && CURRENT="$(cat "$COUNTER" 2>/dev/null || echo 0)"
-
-# Increment
-NEXT=$((CURRENT + 1))
-echo "$NEXT" > "$COUNTER" 2>/dev/null || true
-
-# Placeholder for future pua escalation (Phase 4+):
-# if [ "$NEXT" -ge 2 ] && command -v claude >/dev/null 2>&1; then
-#   if claude plugin list 2>/dev/null | grep -q 'pua'; then
-#     # Inject escalation suggestion via hook output
-#     ...
-#   fi
-# fi
-
-exit 0