@curdx/flow 1.1.4 → 1.1.6

package/knowledge/spec-driven-development.md

@@ -0,0 +1,183 @@
+# 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 for 5-8 rounds of problem understanding
+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. **Must use sequential-thinking for at least 8 rounds**:
+   - Rounds 1-2: constraints
+   - Rounds 3-5: comparison of options A/B
+   - Rounds 6-7: selection + trade-offs
+   - Round 8: rebut yourself
+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, but reflect on coverage every 5 tasks
+
+**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. `/curdx-flow:triage` 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** (`/curdx-flow:sketch` mode) — only research + design sketches
+- **Emergency hotfix** (`/curdx-flow:spike` 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
+
+---
+
+_Adapted from smart-ralph's spec engine, extended with get-shit-done's multi-source audit._

package/knowledge/systematic-debugging.md

@@ -0,0 +1,384 @@
+# Systematic Debugging — 4-Stage Methodology
+
+> Inherited from superpowers' systematic-debugging skill.
+>
+> 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
+```
+
+---
+
+_Source: superpowers' systematic-debugging skill._