@curdx/flow 3.0.0 → 3.1.0

package/knowledge/review-feedback-intake.md

@@ -1,57 +0,0 @@
-# Review Feedback Intake — Verify Before Changing
-
-CurDX-Flow treats review feedback as technical input, not orders to blindly implement. The goal is to fix real issues while avoiding scope creep, regressions, and performative agreement.
-
-## Intake Pattern
-
-For each review item:
-
-1. **Read** the full finding, including severity, evidence, and suggested fix.
-2. **Restate** the technical requirement in one sentence.
-3. **Verify** against the codebase/spec:
-   - Is the finding true at the referenced path/line?
-   - Does it violate an FR, AC, AD, gate, test, or user decision?
-   - Does the suggested fix break existing behavior or platform constraints?
-4. **Classify**:
-   - `BLOCKER`: correctness, security, missing requirement, failing verify, broken CI.
-   - `IMPORTANT`: maintainability or test gap that should be fixed before ship.
-   - `SUGGESTION`: non-blocking improvement or preference.
-   - `PUSHBACK`: technically wrong, violates YAGNI, conflicts with D-NN, or lacks evidence.
-5. **Act one item at a time**:
-   - Fix blockers first.
-   - Run the smallest relevant verification after each fix.
-   - Record pushback with evidence instead of silently ignoring it.
-
-## Required Artifact
-
-When review produces any nontrivial feedback, append a section to `.flow/specs/<active>/.progress.md`:
-
-```markdown
-## Review Feedback Intake YYYY-MM-DD
-
-| Item | Source | Classification | Decision | Evidence | Follow-up |
-|---|---|---|---|---|---|
-| R-01 | review-report.md#... | BLOCKER | fix | `npm test` fails AC-2.1 | Task 4.4 |
-| R-02 | review-report.md#... | PUSHBACK | defer | D-07 says no CSV export | none |
-```
-
-## Pushback Rules
-
-Push back when the feedback:
-
-- Adds unused features or speculative architecture.
-- Conflicts with explicit user decisions (`D-NN`).
-- Breaks compatibility that the current code intentionally preserves.
-- Is unsupported by evidence and cannot be reproduced.
-- Optimizes style while leaving spec compliance unresolved.
-
-Pushback must be technical: cite code, tests, specs, or decisions. Do not use emotional language.
-
-## Fix Loop
-
-1. Intake review items.
-2. Convert accepted blockers/important issues into tasks or direct fixes.
-3. Run targeted verification per item.
-4. Re-run `/curdx-flow:verify` when behavior changed.
-5. Re-run `/curdx-flow:review` until blockers are gone.
-

package/knowledge/spec-driven-development.md

@@ -1,180 +0,0 @@
-# Spec-Driven Development — CurdX-Flow Methodology
-
-> Spec-driven development (SDD): decompose the path from "idea" to "code" into 4 verifiable phases, each with clear deliverables.
->
-> Agents reference this file via `@${CLAUDE_PLUGIN_ROOT}/knowledge/spec-driven-development.md`.
-
----
-
-## Core Idea
-
-**Do not write code until research, requirements, and design are clear.**
-
-```
-┌─────────┐    ┌─────────────┐    ┌────────┐    ┌───────┐    ┌─────────┐
-│ Research │ → │ Requirements │ → │ Design │ → │ Tasks │ → │ Execute │
-└─────────┘    └─────────────┘    └────────┘    └───────┘    └─────────┘
- "can it be done" "what to do"   "how to do"  "split how"   "actually do"
-```
-
-Each phase:
-- Has an independent Markdown deliverable (research.md / requirements.md / design.md / tasks.md)
-- Output is user-reviewed before progressing to the next
-- Later phases strictly reference prior conclusions — no re-litigation
-
----
-
-## Why This Way?
-
-### Problems from not doing this (writing code directly)
-
-```
-User: "Add user authentication"
-AI: writes 800 lines of JWT code
-User: "Actually I wanted session cookies"
-AI: rewrites 800 lines of session code
-User: "I forgot to mention SSO is required"
-AI: rewrites again…
-```
-
-What's wasted isn't code — it's context tokens and decision fatigue from churn.
-
-### Benefits of doing it this way
-
-- **Catch misunderstandings early** — ask during research, not at implementation time
-- **Decisions are traceable** — every choice is written in design.md; later refer to `AD-01` rather than re-debating
-- **Interruptible and resumable** — spec files persist; tomorrow's continuation requires only a read
-- **Team collaboration** — others can pick up the work by reading the spec
-
----
-
-## The 4 Phases Explained
-
-### Phase 1: Research
-
-**Question**: Can this be done? What should it use?
-
-**Key behaviors** (flow-researcher agent):
-1. Read `.flow/PROJECT.md` and `.flow/CONTEXT.md` to understand project background
-2. Call `mcp__claude_mem__search` to retrieve relevant historical experience
-3. Use sequential-thinking proportional to the unknowns (1 thought for a trivial prototype, many for a novel domain)
-4. Scan the codebase for reusable modules
-5. Use `mcp__context7__*` to look up latest docs for relevant libraries
-6. When necessary, WebSearch for the latest technical trends
-
-**Deliverable**: `research.md` — includes:
-- Problem understanding + explicit assumptions
-- 2-3 candidate technical approaches
-- Existing code analysis
-- Feasibility judgment + recommended direction
-
-**Next-step decision**: the recommended direction enters requirements; if entirely infeasible, stop here.
-
----
-
-### Phase 2: Requirements
-
-**Question**: What will the user see / experience?
-
-**Key behaviors** (flow-product-designer agent):
-1. Read `research.md` to understand technical direction
-2. Translate technical capabilities into user stories (US-NN)
-3. Write 2-5 acceptance criteria per story (AC-X.Y)
-4. List FR (functional requirements) + NFR (non-functional requirements)
-5. Define an **explicit out-of-scope** list (prevents later scope creep)
-6. Raise open questions for the user to answer
-
-**Deliverable**: `requirements.md`
-
-**User review focus**:
-- Are the user stories correct? (maybe research misunderstood)
-- Are edge cases handled reasonably?
-- Is the out-of-scope list accepted?
-
----
-
-### Phase 3: Design
-
-**Question**: How is the code organized? What decisions are made?
-
-**Key behaviors** (flow-architect agent):
-1. Read `research.md` + `requirements.md`
-2. **Use sequential-thinking proportional to the tradeoff surface** — the phases below are orientation, not a quota:
-   - Constraints (from NFR / tech stack)
-   - Option comparison (only when alternatives genuinely compete)
-   - Selection + accepted tradeoff
-   - Self-rebuttal
-   A well-known stack pick may finish in 1 thought; a distributed-system design may run many. Do not pad.
-3. Assign an `AD-NN` ID to each architectural decision
-4. Draw a data flow diagram (mermaid)
-5. Define component interfaces + error paths
-6. Make the test strategy explicit
-
-**Deliverable**: `design.md`
-
-**Freeze**: once tasks begin, the design is frozen. If changes are needed, return to the design phase to update (and bump AD numbers).
-
----
-
-### Phase 4: Tasks (decomposition)
-
-**Question**: How many steps to do it? How is each step verified?
-
-**Key behaviors** (flow-planner agent):
-1. Read `requirements.md` + `design.md`
-2. Decompose by POC-First 5 Phases (see `poc-first-workflow.md`)
-3. Each task has 5 fields: `Do` / `Files` / `Done-when` / `Verify` / `Commit`
-4. **Multi-source coverage audit**: for each FR / AC / AD / decision, confirm there is a covering task (no omissions)
-5. Mark `[P]` (parallel-safe) and `[VERIFY]` (checkpoint)
-6. Simple decomposition doesn't need sequential-thinking; run a coverage audit at the end (every FR/AC/AD has a task)
-
-**Deliverable**: `tasks.md`
-
-**Verification standard**: each `Verify` field must be an **automated command**, not "manual test".
-
----
-
-## Spec-File Invariants
-
-Regardless of the path taken, the 4 files must satisfy:
-
-1. **Clear dependency chain**: requirements reference research conclusions; design references requirements' FR; tasks reference design's AD.
-2. **IDs unique and stable**: US-01 refers to the same story across every file.
-3. **Auditable and traceable**: every implementation task can be traced to some FR or AC.
-4. **No backward edits**: once frozen, changes bump the version number (1.0 → 1.1), with prior versions kept.
-
----
-
-## Spec vs Epic Difference
-
-- **Spec**: a single independently-deliverable feature. Typically 1-2 weeks of effort.
-- **Epic**: a collection of specs. The `epic` skill (auto-invoked, or say "break this big feature down") breaks down a large goal into multiple specs.
-
-`.flow/specs/<name>/` is a single-spec directory.
-`.flow/_epics/<name>/` is an Epic directory (contains the dependency graph and sub-spec list).
-
----
-
-## When Not to Use the Full Flow
-
-SDD is not dogma. The following scenarios may skip phases:
-
-- **One-off scripts** (`/curdx-flow:fast` mode) — skip all specs
-- **UI prototype exploration** (the `ui-sketch` skill) — only research + design sketches
-- **Emergency hotfix** (`/curdx-flow:fast "spike: validate <hypothesis>"` mode) — validating the assumption is enough
-
-But **production code changes** should follow the full flow. Rationale:
-- Code may be only 20 lines, but impact may reach all users
-- The spec file itself is a record of "why" — valuable for future maintenance
-
----
-
-## Division of Labor with claude-mem
-
-- **claude-mem** automatically captures all tool calls and conversation → implicit memory
-- **Spec files** are **explicit decision records** → consciously written
-  
-The two complement each other:
-- Agents `mcp__claude_mem__search` the history before starting research
-- What gets written into research.md is filtered, retention-worthy conclusions
-- Subsequent sessions: claude-mem auto-injects recent context; spec files provide the structured overview

package/knowledge/systematic-debugging.md

@@ -1,378 +0,0 @@
-# Systematic Debugging — 4-Stage Methodology
-
-> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md`.
-
----
-
-## Why Systematic
-
-**Unsystematic debugging**:
-- "Try this" → doesn't work
-- "Try that" → doesn't work
-- "Change this line" → looks good?
-- (half an hour later) the bug is back
-
-**Problems**:
-- Without a root cause → fix isn't sturdy
-- No failing test → no regression protection
-- Consumes a lot of time
-- Introduces new bugs while fixing bugs
-
-**Systematic debugging**: explicit 4 stages, each with deliverables, preventing skipping.
-
----
-
-## 4-Stage Overview
-
-```
-Phase 1: Root Cause Investigation
-  ↓ a clear root cause statement
-Phase 2: Pattern Analysis
-  ↓ compare working vs broken
-Phase 3: Hypothesis & Test
-  ↓ single hypothesis, minimal test, verify
-Phase 4: Implement Fix
-  ↓ failing test → fix root cause → verify
-```
-
-Skipping any stage = incomplete.
-
----
-
-## Phase 1: Root Cause Investigation
-
-### Step 1.1: Read the error carefully
-
-Don't skim and start changing things. **Read every word**:
-
-```
-TypeError: Cannot read property 'email' of undefined
-    at validateUser (src/auth/login.ts:42:18)
-    at processLogin (src/auth/login.ts:15:3)
-    at async Router.post (src/routes/auth.ts:22:5)
-```
-
-What I can learn:
-- **Type**: TypeError (not a logic error)
-- **Cause**: reading .email on undefined
-- **Location**: login.ts:42
-- **Call chain**: processLogin → validateUser
-- **Entry**: POST /auth/... route handler
-
-Don't skip these.
-
-### Step 1.2: Reliable reproduction
-
-Establish **minimal** reproduction steps:
-
-```
-Preconditions:
-  1. Run dev server
-  2. Clear cookies
-  3. Visit /login
-
-Steps:
-  1. Leave email empty
-  2. Fill password with anything
-  3. Click Submit
-
-Expected: 400 + "email required"
-Actual: 500 + stack trace with the TypeError above
-```
-
-If **unstable** (sometimes happens, sometimes not):
-- Record under what conditions it occurs
-- Under what conditions it doesn't
-- This hints at: race condition / initialization order / environment difference
-
-### Step 1.3: Check recent changes
-
-```bash
-git log --oneline -20 src/auth/login.ts
-git log --oneline --all --since="7 days ago"
-git diff HEAD~5 src/auth/login.ts
-```
-
-Most bugs are introduced by recent changes. Look at the suspicious recent commits first.
-
-### Step 1.4: Trace data flow
-
-Backwards from the error point:
-
-```
-error at login.ts:42: user.email is undefined
-  → where does user come from?
-    → validateUser(user) parameter
-      → req.body.user in processLogin
-        → route parameter req.body
-          → JSON.parse(request.body)
-            → payload from client
-
-Reasoning:
-  If payload = `{email: ""}`,
-  req.body = {email: ""},
-  and code reads req.body.user.email → undefined.email → crash
-```
-
-Root cause found: the code expected `req.body.user.email`, but the API contract sends `req.body.email`.
-
-### Step 1.5: Root cause statement
-
-The completion sign for Phase 1: **being able to write the root cause in one sentence**.
-
-Format:
-> "Root cause: <specific cause>; trigger: <specific condition>; scope: <scope>"
-
-Example:
-> "Root cause: validateUser reads req.body.user.email, but the API sends req.body.email; trigger: all login requests; scope: the entire login flow fails 100%."
-
-**Forbidden**:
-- "Might be..." (hypothesis, not root cause)
-- "Maybe..." (same)
-- "I think..." (subjective)
-
-If still at the "might be" level → continue investigating, don't enter Phase 2.
-
----
-
-## Phase 2: Pattern Analysis
-
-### Step 2.1: Find working examples
-
-90% of the code in the system doesn't have this bug. What does that 90% look like?
-
-```bash
-# Find similar scenarios
-grep -rn "req.body" src/routes/
-```
-
-Results:
-```
-src/routes/auth.ts:15: const { email } = req.body       ← works
-src/routes/auth.ts:22: req.body.user.email              ← broken
-src/routes/user.ts:10: const { name } = req.body         ← works
-src/routes/order.ts:8:  const { amount } = req.body      ← works
-```
-
-### Step 2.2: Locate the difference
-
-```
-Working pattern: const { email } = req.body  (destructure top-level fields)
-Broken pattern: req.body.user.email          (access nested field)
-```
-
-Difference is clear → confirms the root cause.
-
-### Step 2.3: Isolated case or systemic?
-
-```bash
-grep -rn "req\.body\.user\." src/
-```
-
-If the `req.body.user` pattern is used in multiple places:
-- A wrong mental model exists in the system
-- Fix all of them, not just one
-
-If only this one:
-- Isolated case, fix only here
-
----
-
-## Phase 3: Hypothesis & Test
-
-### Step 3.1: Single hypothesis
-
-**Do not** test multiple hypotheses simultaneously. If something works, you won't know which one did it.
-
-**Single hypothesis**:
-> "Hypothesis: changing login.ts:42 from req.body.user.email to req.body.email will fix this bug."
-
-### Step 3.2: Minimal test
-
-```bash
-# Reproduce with current code first
-curl -X POST localhost:3000/auth/login \
-  -d '{"email":"","password":""}'
-# → 500 + TypeError  ✓ (reproduces)
-
-# Make the minimum change (in memory / editor, don't commit)
-# Edit login.ts:42
-
-# Test again
-curl ... # expect 400 + "email required"
-
-# If success → hypothesis confirmed
-# If failure → hypothesis wrong; go back to Phase 1
-```
-
-### Step 3.3: Hypothesis confirmed → Phase 4
-
-Once confirmed, proceed to the fix.
-
-Hypothesis refuted → **do not** keep guessing; go back to Phase 1 and re-investigate the data flow.
-
----
-
-## Phase 4: Implement Fix
-
-### Step 4.1: Write a failing test (**before code**)
-
-```typescript
-// login.test.ts
-test("rejects empty email with 400 (regression for #N)", async () => {
-  const res = await request(app)
-    .post("/auth/login")
-    .send({ email: "", password: "any" })
-
-  expect(res.status).toBe(400)
-  expect(res.body.error).toMatch(/email required/i)
-})
-```
-
-Run:
-```bash
-npm test -- login.test.ts
-# ✗ FAIL (expected, since it currently crashes with 500)
-```
-
-Commit: `test(auth): red - reject empty email in login`
-
-### Step 4.2: Fix the root cause (not the symptom)
-
-Phase 1 root cause: the code mis-reads `req.body.user.email`.
-
-**Correct fix**: change to `req.body.email`
-```typescript
-// login.ts
-- const email = req.body.user.email  // wrong
-+ const email = req.body.email       // correct
-```
-
-**Symptom fix** (wrong): add a null check
-```typescript
-// ✗ symptom fix (doesn't answer "why is user.email undefined")
-if (!req.body.user?.email) return res.status(400)
-```
-
-### Step 4.3: Verify
-
-```bash
-npm test -- login.test.ts
-# ✓ PASS
-
-# Full test run to ensure no regressions
-npm test
-# ✓ all pass
-```
-
-### Step 4.4: Commit the fix
-
-```
-fix(auth): green - read email from req.body directly
-
-Root cause: validateUser expected req.body.user.email but API
-contract sends req.body.email directly. This caused TypeError
-on all login requests (100% failure).
-
-Phase 1-4 analysis:
-  - Phase 1: traced data flow, found contract mismatch
-  - Phase 2: 3 other routes use correct `req.body.{field}` pattern
-  - Phase 3: hypothesis confirmed by minimal test
-  - Phase 4: test + fix + full regression passed
-
-Fixes: #N
-```
-
----
-
-## 3-Failure Protection (Anti-Loop)
-
-```python
-failed_attempts = 0
-
-while bug_not_fixed:
-    run_4_phases()
-    if failed:
-        failed_attempts += 1
-
-    if failed_attempts >= 3:
-        STOP_AND_REPORT:
-        """
-        I tried 3 different approaches, all failed:
-        1. <method 1>: <why it failed>
-        2. <method 2>: <why it failed>
-        3. <method 3>: <why it failed>
-
-        This suggests the underlying problem may be:
-        - Wrong architecture (e.g., auth layer shouldn't own token mgmt)
-        - Dependency issue (e.g., bcrypt version incompatibility)
-        - Data issue (e.g., schema mismatches code)
-        - Tests don't reflect real scenarios
-
-        Recommendation: user intervention to decide direction.
-        """
-```
-
-**Key**: do not blindly attempt a 4th time. 3 failures mean your hypothesis framework is wrong — step back and see the big picture.
-
----
-
-## Forbidden Anti-Patterns
-
-### 1. Pray programming
-
-```python
-for retry in range(10):
-    try:
-        do_thing()
-        break
-    except:
-        pass
-```
-This is not fixing the bug, it's **masking** it.
-
-### 2. "Maybe it's..." attribution
-
-```
-"Maybe it's a network issue"  → didn't verify
-"Maybe permissions"            → didn't ls -la
-"Maybe timezone"               → didn't check timestamps
-```
-**Verify** before attributing.
-
-### 3. Fix without a failing test
-
-"I fixed it" → no test written → 6 months later a regression → debug again
-
-Every fix comes with:
-1. A failing test that reproduces the bug
-2. The fix
-3. Test passes
-
-### 4. Bypassing the root cause
-
-```typescript
-// Bug: user.email is null causing crash
-// ✗ wrong fix: if (!user?.email) return defaultEmail
-// ✓ correct fix: trace data flow, find where email becomes null
-```
-
-### 5. Half-fix
-
-- ✗ Fixed one place, but similar code exists in 5 more
-- ✓ Phase 2 analysis identifies all cases, fixes all at once
-
----
-
-## Summary
-
-```
-The value of systematic debugging:
-  Phase 1 ensures → don't fix on a hypothesis
-  Phase 2 ensures → recognize patterns, avoid isolated cases
-  Phase 3 ensures → know the fix works before applying
-  Phase 4 ensures → fix is durable + regression-proof
-
-Unsystematic → fixes fast but fragile → bitten again by the same bug
-Systematic  → fixes slow but thorough → solved once, never looked back
-```