@curdx/flow 1.1.3 → 1.1.5

package/knowledge/epic-decomposition.md

@@ -0,0 +1,307 @@
+# Epic Decomposition — Vertical Slicing of Epics
+
+> How do you break down a large feature? The core principle is **vertical slicing** (by user value), not **horizontal layering** (by technical layer).
+>
+> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/epic-decomposition.md`.
+
+---
+
+## What is an Epic?
+
+An Epic = **a collection of sub-specs** that together deliver a large user goal.
+
+Typical scenarios:
+- "Add payment system"
+- "Refactor authentication module"
+- "Migrate from REST to GraphQL"
+- "Add internationalization support"
+
+These are all too large to do as a single spec. They must be broken down.
+
+---
+
+## Vertical Slicing vs Horizontal Layering
+
+### ✗ Horizontal layering (bad)
+
+```
+Epic: Add payment system
+  Spec 1: Frontend (all payment UI)
+  Spec 2: Backend (all payment APIs)
+  Spec 3: DB (orders / transactions / refunds tables)
+```
+
+**Problems**:
+- Each spec alone delivers **no user value** (frontend cannot call a non-existent backend)
+- All 3 must ship together — no incremental release
+- If spec 2 is abandoned halfway, spec 1 and 3 are wasted
+- Hard to test (no frontend-only E2E without a backend)
+
+### ✓ Vertical slicing (good)
+
+```
+Epic: Add payment system
+  Spec 1: Credit card payment       (UI + API + DB, end-to-end)
+  Spec 2: Alipay payment            (UI + API + DB)
+  Spec 3: Refund flow               (UI + API + DB)
+  Spec 4: Transaction history query (UI + API)
+```
+
+**Advantages**:
+- Each spec ships independently = real user value
+- Incremental release (credit card first, Alipay a week later)
+- Failure isolation (delaying refunds doesn't block payments)
+- Each spec is independently E2E testable
+
+---
+
+## Deciding When to Break Into an Epic
+
+Ask yourself:
+
+1. **Effort**: Can this be done in 1-2 weeks?
+   - Yes → single spec
+   - No → Epic
+
+2. **Independent delivery**: Can it be split into multiple parts "the user can perceive separately"?
+   - Yes → Epic (split along those)
+   - No → keep refining, or it shouldn't be split
+
+3. **Dependencies**: Are sub-parts hard or soft dependencies?
+   - All hard (must serialize) → consider not splitting; do as one large spec
+   - Mostly soft (can parallelize) → Epic
+
+---
+
+## Slicing Dimensions
+
+### 1. By user type
+
+```
+Epic: Multi-user payment system
+  Spec 1: Personal user credit card payment
+  Spec 2: Enterprise user bank transfer
+  Spec 3: Platform merchant collection
+```
+
+### 2. By use case
+
+```
+Epic: Order management
+  Spec 1: Checkout flow
+  Spec 2: Post-payment shipping
+  Spec 3: Refund flow
+  Spec 4: After-sales support
+```
+
+### 3. By channel
+
+```
+Epic: Multi-channel payment
+  Spec 1: Credit card (Stripe)
+  Spec 2: Alipay
+  Spec 3: WeChat Pay
+  Spec 4: Apple Pay
+```
+
+### 4. By data dimension
+
+```
+Epic: User profile system
+  Spec 1: Basic info profile
+  Spec 2: Behavior profile
+  Spec 3: Preference profile
+  Spec 4: Profile query API
+```
+
+### 5. By business phase (MVP → Full)
+
+```
+Epic: Recommendation system
+  Spec 1: Hot list (minimal MVP)
+  Spec 2: Collaborative filtering
+  Spec 3: Deep learning model
+  Spec 4: Personalized re-rank
+```
+
+---
+
+## Dependency Identification
+
+### Hard Dependency
+
+B needs A's data structures or interfaces to work. A must be completed first.
+
+```
+A: define Order type + create orders table
+B: consume Order to implement payment logic
+  → B hard-depends on A
+```
+
+### Soft Dependency
+
+B's **final integration** needs A, but can be stubbed earlier.
+
+```
+A: payment gateway integration
+B: refund flow
+  → B can mock the payment API and build the happy path first
+  → integrate with the real API once A is done
+  → B soft-depends on A
+```
+
+### Parallel
+
+A and B do not depend on each other. Can fully parallelize.
+
+```
+A: credit card payment
+B: Alipay payment
+  → independent UI/API/DB
+  → two teams can work in parallel
+```
+
+### Express with mermaid
+
+```mermaid
+flowchart LR
+    A[Spec 1: Order basics] --> B[Spec 2: Credit card]
+    A --> C[Spec 3: Alipay]
+    B -.software-dep.-> D[Spec 4: Refund]
+    C -.software-dep.-> D
+```
+
+Solid line = hard dependency; dashed line + "software-dep" = soft dependency.
+
+---
+
+## Freezing Shared Interfaces
+
+Multiple sub-specs use the same type (e.g., `Order`). That type must be frozen at the Epic level.
+
+### Define in epic.md
+
+```typescript
+// All sub-specs must comply
+interface Order {
+  id: string;
+  userId: string;
+  amount: number;           // cents (integer)
+  currency: "CNY" | "USD";
+  status: OrderStatus;
+  paymentMethod: PaymentMethod;
+  createdAt: string;
+  updatedAt: string;
+}
+
+type OrderStatus =
+  | "pending"
+  | "paid"
+  | "refunded"
+  | "failed";
+
+type PaymentMethod =
+  | { kind: "credit_card"; lastFour: string }
+  | { kind: "alipay"; openId: string }
+  | { kind: "wechat"; openId: string };
+```
+
+### Change rules
+
+- During Epic development, the interface is **frozen**
+- If a change is unavoidable, bump the Epic version (1.0 → 1.1)
+- Re-review all completed sub-specs
+- Avoid "one spec changed the interface, another didn't know"
+
+---
+
+## Execution Order Suggestions
+
+### Topological sort
+
+```
+1. Specs with no dependencies can start in parallel
+2. Hard-dependent specs wait for upstream to complete
+3. Soft-dependent specs can start early (using mocks)
+```
+
+### Typical pattern
+
+```
+Week 1-2: Spec 1 (Order basics) [critical path]
+Week 3-4: Spec 2 (credit card) + Spec 3 (Alipay) in parallel
+Week 5-6: Spec 4 (refund) + Spec 5 (query)
+```
+
+---
+
+## Epic Lifecycle
+
+```
+1. /curdx-flow:triage "Epic goal"
+     ↓ flow-triage-analyst decomposes
+2. Generates .flow/_epics/<name>/epic.md + sub-spec skeletons
+3. User reviews epic.md
+     ↓
+4. For each sub-spec:
+   /curdx-flow:switch <sub-spec-name>
+   /curdx-flow:spec
+   /curdx-flow:implement
+   /curdx-flow:review
+     ↓
+5. All sub-specs done → Epic complete
+6. /curdx-flow:retro (Phase 6+) for Epic-level retrospective
+```
+
+---
+
+## Anti-patterns
+
+### 1. "Treating the mermaid diagram as the spec"
+
+The Epic dependency graph is only high-level planning. Each sub-spec still needs a full research / requirements / design / tasks cycle.
+
+### 2. Too many sub-specs (> 10)
+
+Granularity is too fine. Merge. Or this is not one Epic but multiple Epics.
+
+### 3. Too few sub-specs (< 3)
+
+Not split finely enough, or shouldn't be split at all. Treat as a single large spec.
+
+### 4. Sub-specs form a hard-dep chain
+
+```
+A → B → C → D → E
+```
+
+A "serial chain" is no different from not splitting. Rethink the slicing approach.
+
+### 5. Interface not frozen
+
+"Each spec defines its own Order type" → incompatibility surfaces at integration time. The interface must be defined once, at the Epic level.
+
+---
+
+## Real Example: Migrating to GraphQL
+
+Wrong decomposition (horizontal):
+```
+Spec 1: Write all GraphQL schema
+Spec 2: Write all resolvers
+Spec 3: Adapt frontend to GraphQL client
+```
+→ Users see nothing until all 3 are done
+
+Correct decomposition (vertical):
+```
+Spec 1: User module migration (schema + resolver + 1 frontend page)
+Spec 2: Order module migration
+Spec 3: Product module migration
+Spec 4: Retire old REST
+```
+→ Spec 1 can partially ship, users start experiencing GraphQL benefits
+
+---
+
+_Sources: XP's User Story Splitting + BMAD-METHOD's Epic design._

package/knowledge/execution-strategies.md

@@ -0,0 +1,278 @@
+# Execution Strategies — 4 Execution Strategies Explained
+
+> `/curdx-flow:implement`'s Strategy Router picks a strategy based on task characteristics. This doc describes how each strategy works, its trade-offs, and when to use it.
+>
+> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/execution-strategies.md`.
+
+---
+
+## Overview
+
+```
+Task list (tasks.md)
+  ↓
+┌──────────────────────────────────────────────┐
+│ Strategy Router                              │
+│                                              │
+│  Task count < 5 and strong deps?  → linear   │
+│  [P] markers and independent?     → wave     │
+│  Task count > 10 and quality-first? → subagent │
+│  Long chain, unattended?          → stop-hook │
+│  No explicit preference?          → auto (picks sub) │
+└──────────────────────────────────────────────┘
+```
+
+---
+
+## Strategy 1: Linear (sequential, inline)
+
+### How it works
+The main agent runs all tasks sequentially **in the current session**. When one task ends, it starts the next — no subagent is dispatched.
+
+```
+main agent → task 1 → task 2 → task 3 → ... → done
+           (same context)
+```
+
+### When to use
+- ✓ Task count < 5
+- ✓ Strong dependencies between tasks (the next must read the previous result)
+- ✓ Debugging scenarios (you want to see the full process)
+- ✓ Simple bug fixes
+- ✓ Phase 0 / Phase 5 (few tasks)
+
+### Advantages
+- Full context is visible, debugging-friendly
+- No subagent communication overhead
+- Easy for a human to take over on failure
+
+### Disadvantages
+- A long task chain exhausts context
+- Cannot parallelize
+- Quality decay curve (output degrades after 50% context)
+
+### Enable
+```bash
+/curdx-flow:implement --strategy=linear
+```
+
+---
+
+## Strategy 2: Subagent (isolated context per task)
+
+### How it works
+The main agent reads tasks.md and **dispatches a fresh flow-executor subagent per task**. Each subagent has a clean context — it does not inherit the main agent's history.
+
+```
+main agent
+  ├─ Task() → subagent(task 1) → TASK_COMPLETE
+  ├─ Task() → subagent(task 2) → TASK_COMPLETE
+  └─ ...
+   (each subagent has isolated context)
+```
+
+### When to use
+- ✓ Task count > 10
+- ✓ Quality-first (every task must be high-quality, avoid context pollution)
+- ✓ Moderate task size (2-15 minutes)
+- ✓ Tasks relatively independent, no complex shared context needed
+- ✓ Superpowers style
+
+### Advantages
+- Each subagent uses at most ~30% context → stable quality
+- Debugging a failed task doesn't pollute the main agent
+- Composable: subagents share files (tasks.md / .progress.md)
+
+### Disadvantages
+- Dispatch overhead (each subagent reloads context)
+- Cross-task info sharing goes through files (.progress.md)
+- Not parallel (a single Task call is serial)
+
+### Enable
+```bash
+/curdx-flow:implement --strategy=subagent
+```
+
+Or (default):
+```bash
+/curdx-flow:implement   # auto routing picks subagent
+```
+
+---
+
+## Strategy 3: Stop-Hook (auto-loop)
+
+### How it works
+- Main agent executes 1 task → ends naturally (Stop event)
+- `stop-watcher.sh` hook fires
+- Checks whether `.state.json` still has unfinished tasks
+- If yes, it outputs `{"decision": "block", "reason": "continue task N"}`
+- Claude Code treats `decision=block` as "issue another response round", and the main agent automatically continues with the next task
+- Repeats until `TASK_FAILED` or `ALL_TASKS_COMPLETE`
+
+```
+main agent → task N → Stop → stop-watcher.sh
+                                 ↓
+                   still tasks? → "block, continue task N+1"
+                                 → main agent continues (new round)
+                                 ↓
+                   no tasks?     → allow stop
+```
+
+### When to use
+- ✓ Long task chains (20+)
+- ✓ Unattended execution (overnight automation)
+- ✓ You don't want to trigger each step manually
+- ✓ smart-ralph style
+
+### Advantages
+- Truly autonomous execution — the user can walk away
+- Each "round" session has an independent context (auto-cleaned)
+- On failure the hook can halt the loop, preventing infinite failure
+
+### Disadvantages
+- Each round reloads context (.progress.md, tasks.md)
+- Needs `quick-mode-guard` to disable AskUserQuestion (otherwise it stalls)
+- Harder to debug (Stop events are asynchronous)
+
+### Enable
+```bash
+/curdx-flow:implement --strategy=stop-hook --quick
+```
+
+`--quick` is the recommended pairing, otherwise the agent will ask on ambiguities and the loop will stall.
+
+---
+
+## Strategy 4: Wave (DAG parallel)
+
+### How it works
+- Tasks in tasks.md marked `[P]` are "parallel-safe"
+- The main agent identifies consecutive `[P]` tasks as one wave
+- **In a single message**, it dispatches multiple Task() tool calls simultaneously
+- All tasks within a wave run in parallel
+- Waves run serially relative to each other
+
+```
+main agent
+  ├─ Wave 1: [P] task1, [P] task2, [P] task3  ← parallel
+  ├─ Wave 2: [VERIFY] task4                   ← serial checkpoint
+  ├─ Wave 3: [P] task5, [P] task6             ← parallel again
+  └─ ...
+```
+
+### When to use
+- ✓ Many `[P]` markers in tasks.md
+- ✓ Tasks are independent (different files, different components)
+- ✓ Time-pressured (parallelism is faster)
+- ✓ get-shit-done style
+
+### Advantages
+- Wall-clock time greatly reduced (N parallel tasks at once)
+- DAG analysis makes dependencies explicit
+- Precise failure localization (which task in which wave)
+
+### Disadvantages
+- Parallel conflict risk (e.g., two tasks editing the same file)
+- Requires flow-planner to have tagged `[P]` (Phase 1-generated tasks.md should)
+- Main agent manages many Task calls, high context pressure
+
+### Enable
+```bash
+/curdx-flow:implement --strategy=wave
+```
+
+### Parallel-safety rules
+`[P]` tasks must:
+- Not edit the same file
+- Not read output of another `[P]` task
+- `[VERIFY]` checkpoints break the parallel group
+- `[SEQUENTIAL]` forces serial execution (overrides `[P]`)
+
+---
+
+## Strategy 5 (default): Auto
+
+### Decision tree
+
+```python
+if args.strategy:
+    return args.strategy
+
+if majority "[SEQUENTIAL]" or strong task dependencies:
+    return "linear"
+
+if "[P]" markers >= 40% of tasks:
+    return "wave"
+
+if task count >= 20 and user requests unattended:
+    return "stop-hook"
+
+if task count >= 8:
+    return "subagent"
+
+return "linear"
+```
+
+### Configuration
+`.flow/config.json`'s `execution.strategy` can override the default:
+- `"auto"` — use the decision tree above (default)
+- Other concrete strategies
+
+---
+
+## Failure Handling (common to all strategies)
+
+`flow-executor` agent's 5-round retry mechanism:
+
+```
+Rounds 1-2: agent retries autonomously (edit code, rerun Verify)
+Round 3: sequential-thinking root-cause analysis ≥ 5 rounds
+Round 4: read related source + trace data flow
+Round 5: report TASK_FAILED
+```
+
+### Extra protections for Stop-Hook strategy
+- 3 consecutive TASK_FAILED → stop-watcher.sh halts the loop
+- 10 consecutive Stop triggers with no progress → halt (anti-deadlock)
+- A single spec exceeding 100 rounds → force halt (requires user check)
+
+### Subagent strategy
+- Each subagent at most 30 turns (beyond flow-executor's maxTurns)
+- Timed-out subagents get marked failed by the main agent, which moves on (or halts, depending on strategy)
+
+---
+
+## Switching Strategies
+
+Can you switch strategies mid-execution? Not recommended.
+
+- Linear → Subagent: wastes existing context, better to stay linear
+- Subagent → Stop-Hook: needs to clean `execute_state`, messy
+- Any → Wave: needs `[P]` markers in tasks.md
+
+If you really must switch, do it manually:
+1. `/curdx-flow:doctor` to check status
+2. Manually edit `.flow/specs/<name>/.state.json`'s `strategy` field
+3. Rerun `/curdx-flow:implement`
+
+---
+
+## Monitoring and Interruption
+
+### View progress
+```bash
+/curdx-flow:status        # global
+/curdx-flow:status <name> # single-spec details
+```
+
+### Interrupt
+- `Ctrl+C` interrupts the current session → Stop event triggers, state is saved
+- Next `/curdx-flow:switch <name>` resumes from `task_index`
+
+### Snapshots
+`/curdx-flow:save <label>` saves a checkpoint (Phase 5+ rollout).
+
+---
+
+_Adapted from smart-ralph (stop-hook), superpowers (subagent), get-shit-done (wave)._