@curdx/flow 1.1.3 → 1.1.5

package/schemas/config.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/config.schema.json",
+  "title": "CurDX-Flow Project Config",
+  "description": "Schema for .flow/config.json",
+  "type": "object",
+  "required": ["version", "mode"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["sketch", "fast", "standard", "enterprise", "autonomous"],
+      "description": "Default workflow depth for this project"
+    },
+    "execution": {
+      "type": "object",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["auto", "subagent", "stop-hook", "wave", "linear"],
+          "default": "auto"
+        },
+        "max_parallel": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20,
+          "default": 5
+        },
+        "subagent_threshold": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 8,
+          "description": "Task count above which subagent strategy is preferred"
+        }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "description": "Which quality gates to enable. Gate definitions live in gates/*.md (Phase 3)",
+      "properties": {
+        "always_on": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["karpathy-gate", "verification-gate"]
+        },
+        "standard_mode": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "enterprise_mode": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "specs": {
+      "type": "object",
+      "properties": {
+        "directories": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["./.flow/specs"],
+          "description": "Monorepo-friendly: multiple spec directories supported"
+        },
+        "default_task_size": {
+          "type": "string",
+          "enum": ["fine", "coarse"],
+          "default": "fine"
+        }
+      }
+    },
+    "addons": {
+      "type": "object",
+      "properties": {
+        "pua": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "style": {
+              "type": "string",
+              "enum": ["alibaba", "bytedance", "huawei", "tencent", "baidu", "pdd", "meituan", "jd", "xiaomi", "netflix", "musk", "jobs", "amazon"]
+            },
+            "auto_trigger": {
+              "type": "string",
+              "enum": ["on-failure", "always", "manual"]
+            }
+          }
+        }
+      }
+    },
+    "created": {
+      "type": "string",
+      "format": "date"
+    }
+  }
+}

package/schemas/spec-frontmatter.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/spec-frontmatter.schema.json",
+  "title": "CurDX-Flow Spec Document Frontmatter",
+  "description": "YAML frontmatter at the top of research.md / requirements.md / design.md / tasks.md",
+  "type": "object",
+  "required": ["spec", "phase", "created", "version"],
+  "properties": {
+    "spec": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "phase": {
+      "type": "string",
+      "enum": ["research", "requirements", "design", "tasks"]
+    },
+    "created": {
+      "type": "string",
+      "format": "date"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["in_progress", "approved", "frozen", "superseded"]
+    },
+    "depends_on": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ],
+      "description": "Other spec files this one depends on (e.g. design.md depends on requirements.md)"
+    },
+    "task_size": {
+      "type": "string",
+      "enum": ["fine", "coarse"],
+      "description": "Only in tasks.md"
+    }
+  }
+}

package/schemas/spec-state.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://curdx-flow.dev/schemas/spec-state.schema.json",
+  "title": "CurDX-Flow Spec State",
+  "description": "Schema for .flow/specs/<name>/.state.json — tracks phase progress across sessions",
+  "type": "object",
+  "required": ["version", "spec_name", "phase"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "spec_name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Kebab-case identifier matching the directory name"
+    },
+    "goal": {
+      "type": "string",
+      "description": "One-sentence goal from /flow-start"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["sketch", "fast", "standard", "enterprise", "autonomous"],
+      "default": "standard"
+    },
+    "strategy": {
+      "type": "string",
+      "enum": ["auto", "subagent", "stop-hook", "wave", "linear"],
+      "default": "auto"
+    },
+    "phase": {
+      "type": "string",
+      "enum": [
+        "research",
+        "requirements",
+        "design",
+        "tasks",
+        "execute",
+        "verify",
+        "review",
+        "ship",
+        "completed"
+      ]
+    },
+    "phase_status": {
+      "type": "object",
+      "properties": {
+        "research": { "$ref": "#/definitions/phaseStatus" },
+        "requirements": { "$ref": "#/definitions/phaseStatus" },
+        "design": { "$ref": "#/definitions/phaseStatus" },
+        "tasks": { "$ref": "#/definitions/phaseStatus" },
+        "execute": { "$ref": "#/definitions/phaseStatus" },
+        "verify": { "$ref": "#/definitions/phaseStatus" },
+        "review": { "$ref": "#/definitions/phaseStatus" },
+        "ship": { "$ref": "#/definitions/phaseStatus" }
+      }
+    },
+    "execute_state": {
+      "type": "object",
+      "description": "Runtime state for Phase 2 (execution engine, post-Phase 1)",
+      "properties": {
+        "poc_complete": { "type": "boolean" },
+        "refactor_complete": { "type": "boolean" },
+        "test_complete": { "type": "boolean" },
+        "quality_gate_complete": { "type": "boolean" },
+        "task_index": { "type": "integer", "minimum": 0 },
+        "total_tasks": { "type": "integer", "minimum": 0 },
+        "task_iteration": { "type": "integer", "minimum": 1 },
+        "global_iteration": { "type": "integer", "minimum": 1 },
+        "failed_attempts": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "description": "Decisions locked in this spec (mirror of what's in STATE.md)",
+      "items": {
+        "type": "object",
+        "required": ["id", "decision"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^D-[0-9]{2,}$"
+          },
+          "decision": { "type": "string" },
+          "rationale": { "type": "string" },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      }
+    },
+    "gates_enabled": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "agents_active": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "created": {
+      "type": "string",
+      "format": "date"
+    },
+    "updated": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "definitions": {
+    "phaseStatus": {
+      "type": "string",
+      "enum": ["not_started", "in_progress", "completed", "skipped", "failed"]
+    }
+  }
+}

package/templates/CONTEXT.md.tmpl

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — User Preferences and Decisions
+
+> CurDX-Flow Context — your coding, design, and interaction preferences. Agents read this to understand your taste.
+
+---
+
+## Code Style Preferences
+
+- **Indentation**: <!-- 2 spaces / 4 spaces / Tab -->
+- **Quotes**: <!-- single / double -->
+- **Semicolons**: <!-- always / never / asi -->
+- **Naming**: <!-- camelCase / snake_case / PascalCase -->
+- **Comment density**: <!-- minimal / when non-obvious / generous -->
+
+## Architecture Preferences
+
+- **Error handling**: <!-- try/catch / Result type / panics -->
+- **Async pattern**: <!-- async/await / promises / callbacks -->
+- **Dependency injection**: <!-- constructor / service locator / none -->
+- **Testing style**: <!-- TDD / test-after / integration-heavy -->
+
+## UI/UX Preferences
+
+- **Design style**: <!-- minimalist / brutalist / corporate / playful -->
+- **Color scheme**: <!-- light / dark / auto / specific palette -->
+- **Typography**: <!-- system / Inter / Space Grotesk / other -->
+- **Density**: <!-- spacious / compact / mixed -->
+- **Animation**: <!-- none / purposeful / expressive -->
+
+## Communication Preferences
+
+- **Language**: <!-- Simplified Chinese / English / bilingual -->
+- **Verbosity**: <!-- terse / balanced / verbose -->
+- **Explanation depth**: <!-- surface / mechanism / first-principles -->
+- **When to ask**: <!-- ask at any fork / only on major decisions / be autonomous -->
+
+## Tooling Preferences
+
+- **Package manager**: <!-- npm / pnpm / yarn / bun -->
+- **Runtime**: <!-- node / bun / deno -->
+- **Test framework**: <!-- vitest / jest / other -->
+- **Linter**: <!-- eslint / biome / other -->
+- **Commit convention**: <!-- conventional / gitmoji / free -->
+
+## Special Requirements
+
+<!-- Rules specific to this project -->
+
+- TODO:
+
+---
+
+_Generated by `/flow-init` on {{CREATED_DATE}}. Update to match your actual preferences._

package/templates/PROJECT.md.tmpl

@@ -0,0 +1,59 @@
+# {{PROJECT_NAME}}
+
+> CurDX-Flow project vision — 500 lines max, loaded on every session
+
+---
+
+## One-line Description
+
+<!-- In one sentence, state what this project is, for whom, and what problem it solves -->
+
+TODO: fill in the one-line description of the project
+
+## Why This Project Exists
+
+<!-- Background, motivation, pain points to solve -->
+
+TODO:
+
+## Core Users
+
+<!-- Who will use it? Their typical scenarios? -->
+
+TODO:
+
+## Success Criteria
+
+<!-- 3-5 verifiable metrics (e.g. "first response < 100ms", "weekly active users > 1000") -->
+
+1. TODO:
+2. TODO:
+3. TODO:
+
+## Tech Stack (with Rationale)
+
+<!-- Write the reasoning for each choice to avoid future second-guessing -->
+
+| Layer | Choice | Rationale |
+|---|-----|------|
+| Frontend | TODO | TODO |
+| Backend | TODO | TODO |
+| Database | TODO | TODO |
+| Deployment | TODO | TODO |
+
+## Out of Scope (Scope Guard)
+
+<!-- Explicitly list what does not belong in this project, to prevent scope creep -->
+
+- ✗ TODO:
+- ✗ TODO:
+
+## Constraints
+
+<!-- Budget, time, team size, compliance, etc. -->
+
+- TODO:
+
+---
+
+_Generated by `/flow-init` on {{CREATED_DATE}}. Maintainer: {{USER_NAME}}_

package/templates/ROADMAP.md.tmpl

@@ -0,0 +1,50 @@
+# {{PROJECT_NAME}} — Roadmap
+
+> CurDX-Flow ROADMAP — phase plan and success criteria. Works alongside `.flow/specs/*`: ROADMAP sets direction, specs handle concrete implementation.
+
+---
+
+## Current Version: v0.1 (MVP)
+
+**Goal**: <!-- one sentence -->
+
+TODO: describe the minimum viable product to deliver in v0.1.
+
+### Success Criteria (v0.1)
+
+<!-- Must be verifiable -->
+
+- [ ] TODO:
+- [ ] TODO:
+- [ ] TODO:
+
+### Phases
+
+<!-- List in development order -->
+
+#### Phase 1 — TODO
+- Goal:
+- Related spec: `specs/<name>`
+- Completion criteria:
+
+#### Phase 2 — TODO
+- Goal:
+- Completion criteria:
+
+---
+
+## Next Version: v0.2
+
+**Theme**: TODO
+
+No details yet.
+
+---
+
+## Vision (12 months)
+
+TODO: describe what this project should look like one year from now.
+
+---
+
+_Initialized on {{CREATED_DATE}}. The roadmap is a statement of intent, not a commitment._

package/templates/STATE.md.tmpl

@@ -0,0 +1,49 @@
+# {{PROJECT_NAME}} — Cross-Session State
+
+> CurDX-Flow STATE — explicit decision log + important context. Agents read this file at the start of every session.
+>
+> Division of labor with claude-mem: claude-mem captures everything automatically; STATE.md only records **decisions you and the agent explicitly agreed on**.
+
+---
+
+## Key Decisions
+
+<!--
+Format: D-NN | YYYY-MM-DD | decision | why
+Once a decision is recorded, subsequent agents must explicitly note "I challenge D-NN" before violating it.
+-->
+
+<!-- Example (delete on init):
+- **D-01** | 2026-04-19 | Use JWT instead of session cookie | Support cross-origin SPA
+- **D-02** | 2026-04-19 | bcrypt cost factor = 12 | Balance 10K QPS performance with security
+-->
+
+No decisions yet.
+
+## Blockers
+
+<!-- Items currently blocking progress, and who/what is being waited on -->
+
+No blockers.
+
+## Open Questions
+
+<!-- Questions that need user answers or investigation -->
+
+None yet.
+
+## Important Context
+
+<!-- Long-standing context the agent should remember, not quite at "decision" level -->
+
+None yet.
+
+## Milestones
+
+<!-- Project-level major milestones -->
+
+None yet.
+
+---
+
+_Initialized on {{CREATED_DATE}}. This file will grow as the project evolves._

package/templates/config.json.tmpl

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://raw.githubusercontent.com/wdx/curdx-flow/main/schemas/config.schema.json",
+  "version": "1.0",
+  "mode": "standard",
+  "_mode_options": "sketch | fast | standard | enterprise | autonomous",
+
+  "execution": {
+    "strategy": "auto",
+    "_strategy_options": "auto | subagent | stop-hook | wave | linear",
+    "max_parallel": 5,
+    "subagent_threshold": 8
+  },
+
+  "gates": {
+    "always_on": [
+      "karpathy-gate",
+      "verification-gate"
+    ],
+    "standard_mode": [
+      "tdd-gate",
+      "coverage-audit-gate",
+      "simplicity-gate"
+    ],
+    "enterprise_mode": [
+      "adversarial-review-gate",
+      "edge-case-gate",
+      "hard-gate",
+      "security-gate"
+    ]
+  },
+
+  "specs": {
+    "directories": ["./.flow/specs"],
+    "default_task_size": "fine",
+    "_task_size_options": "fine (40-60 tasks) | coarse (10-20 tasks)"
+  },
+
+  "addons": {
+    "pua": {
+      "enabled": false,
+      "style": "alibaba",
+      "_style_options": "alibaba | bytedance | huawei | tencent | baidu | pdd | meituan | jd | xiaomi | netflix | musk | jobs | amazon",
+      "auto_trigger": "on-failure"
+    }
+  },
+
+  "created": "{{CREATED_DATE}}"
+}

package/templates/design.md.tmpl

@@ -0,0 +1,163 @@
+---
+spec: {{SPEC_NAME}}
+phase: design
+created: {{CREATED_DATE}}
+version: 1.0
+status: in_progress
+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.
+
+---
+
+## Design Overview (one paragraph)
+
+<!-- One-sentence summary of the architecture -->
+
+## Architecture Decisions
+
+<!-- Each major decision gets an ID and is written to the decisions array in .flow/STATE.md -->
+
+### AD-01: ...
+- **Decision**: Use X instead of Y
+- **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)]
+```
+
+## Component Design
+
+<!-- Each component is independently testable. Interfaces are explicit. -->
+
+### Component: {{COMP_NAME_1}}
+- **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,
+  ...
+);
+```
+
+### Or TypeScript types:
+```ts
+interface Entity {
+  id: string;
+  ...
+}
+```
+
+## State Machine (if applicable)
+
+```mermaid
+stateDiagram-v2
+  [*] --> Pending
+  Pending --> Active: approve
+  Pending --> Rejected: reject
+  Active --> Completed: finish
+```
+
+## Error Path Design
+
+<!-- Full flow on failure -->
+
+| 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" |
+
+## API Contract
+
+<!-- If this is an API project -->
+
+```yaml
+POST /api/v1/...
+Request:
+  body:
+    field: string
+Response:
+  200:
+    body:
+      field: string
+  400:
+    body:
+      error: string
+```
+
+## Test Matrix
+
+| 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 | ... |
+
+## Defer to Implementation
+
+<!-- Decisions not worth spending time on in the design phase -->
+
+- 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._