@curdx/flow 3.0.0 → 3.1.0

package/knowledge/epic-decomposition.md

@@ -1,307 +0,0 @@
-# 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. Invoke the `epic` skill with "Epic goal" (auto-invoked; or say "break this big feature down")
-     ↓ 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:start <sub-spec-name>
-   /curdx-flow:spec
-   /curdx-flow:implement
-   /curdx-flow:review
-     ↓
-5. All sub-specs done → Epic complete
-6. Record an epic-level retrospective in `.flow/_epics/<name>/epic.md`
-```
-
----
-
-## 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

@@ -1,303 +0,0 @@
-# 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
-  ├─ Agent() → subagent(task 1) → TASK_COMPLETE
-  ├─ Agent() → 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
-- ✓ Stable per-task quality matters more than dispatch overhead
-
-### 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 Agent 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
-- Cross-checks `tasks.md`; completion requires zero unchecked tasks as well as completed state
-- Allows stop when Claude Code reports `stop_hook_active=true` to avoid recursive stop-hook loops
-- 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
-```
-
-Safety invariant: `ALL_TASKS_COMPLETE` is advisory, not authoritative. If `tasks.md` still has unchecked tasks, the hook blocks and tells the agent to continue those tasks instead of advancing to verify.
-
-### When to use
-- ✓ Long task chains (20+)
-- ✓ Unattended execution (overnight automation)
-- ✓ You don't want to trigger each step manually
-- ✓ Long-running sequential work with checkpointed continuation
-
-### 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 Agent() 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)
-- ✓ Parallel-safe delivery work
-
-### 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 Agent 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
-
-Execution failure recovery is explicit:
-- `recovery_mode: "manual"` — default; never skip a failed task, retry from the first unchecked task after root-cause analysis.
-- `recovery_mode: "fix-task"` — insert a targeted `[FIX <task_id>]` task before retrying the original failure.
-- `max_fix_tasks_per_original` — hard ceiling for generated fix tasks per original task.
-
----
-
-## Failure Handling (common to all strategies)
-
-`flow-executor` agent's retry ladder — each step escalates only when the prior is honestly exhausted, not on a fixed count:
-
-```
-Step A: autonomous retry (edit + rerun Verify) — only for shallow failures
-Step B: sequential-thinking root-cause analysis proportional to the hypothesis space
-Step C: read related source + trace data flow
-Step D: if ≥3 retries fail with no new hypothesis, stop and challenge the architecture (see preamble L3)
-Step E: report TASK_FAILED
-```
-
-If fix-task recovery is enabled, the coordinator turns a `TASK_FAILED` into a ledgered repair task before doing more work:
-
-```markdown
-- [ ] **<task_id>.<n>** [FIX <task_id>] Fix: <root cause>
-  - **Do**: <repair steps>
-  - **Files**: <same files as the original task or narrower>
-  - **Done when**: Original failure no longer reproduces
-  - **Verify**: <original verify command or tighter reproduction>
-  - **Commit**: `fix(<scope>): address <failure>`
-```
-
-The fix task must be written to `tasks.md` and tracked in `.state.json` `execute_state.fix_task_map` before it is executed. Executors do not invent and execute recovery work in the same turn.
-
-### 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. `npx @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:start --list        # global
-# For single-spec details, inspect .flow/specs/<name>/.progress.md
-```
-
-### Interrupt
-- `Ctrl+C` interrupts the current session → Stop event triggers, state is saved
-- Next `/curdx-flow:start <name>` (or `/curdx-flow:start --resume`) resumes from `task_index`
-
-### Snapshots
-Claude Code checkpoints plus `.flow/specs/<name>/.progress.md` are the current recovery surface. Use `/curdx-flow:status` to inspect recoverability.
-
----
-
-This document defines CurDX-Flow's shipped strategy semantics: stop-hook for
-checkpointed continuation, subagent for serial isolated execution, and wave for
-parallel batches.