@curdx/flow 2.0.0-beta.1 → 2.0.0-beta.10

package/skills/epic/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: epic
+description: Invoke when user wants to break a large feature into multiple smaller specs with a dependency graph. Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "won't fit in one sprint", "needs splitting".
+allowed-tools: [Read, Write, Grep, Glob, Bash]
+---
+
+# Epic Decomposition
+
+You are invoked when the user wants to break a large feature into multiple vertical-slice specs.
+
+## Preconditions
+
+1. A `.flow/` project must exist (run `/curdx-flow:init` first if missing).
+2. The user has stated a feature scope that is too large for a single spec.
+
+## Workflow
+
+### Step 1: Clarify the epic scope
+
+Ask the user (or infer from context) for:
+- **Epic name** (short identifier, kebab-case)
+- **One-sentence goal** of the whole epic
+- **Hard boundary**: what is explicitly out of scope for this epic
+
+### Step 2: Dispatch `flow-triage-analyst`
+
+Delegate to the `flow-triage-analyst` agent with the epic name + goal + boundary. The agent returns:
+- A vertical-slice decomposition (not horizontal by layer)
+- Dependency graph between slices
+- Shared interfaces that must be frozen before parallel work begins
+- Suggested slice ordering (MVP → iteration → polish)
+
+### Step 3: Write epic manifest
+
+Create `.flow/_epics/<epic-name>/epic.md` with:
+
+```markdown
+# Epic: <name>
+
+## Goal
+<one sentence>
+
+## Slices (vertical)
+| ID | Slice | Depends on | Shared interface |
+|----|-------|-----------|------------------|
+| S1 | ...   | —          | —                |
+| S2 | ...   | S1         | `types/auth.ts`  |
+| S3 | ...   | S1         | —                |
+
+## Frozen Interfaces
+(contracts that must not change once slices start)
+
+## Out of Scope
+- ...
+```
+
+### Step 4: Scaffold sub-spec skeletons
+
+For each slice, create `.flow/specs/<epic-name>-<slice-id>/` with a minimal `.state.json` linking back to the epic manifest.
+
+### Step 5: Report to user
+
+Summarize: "Epic `<name>` decomposed into N vertical slices. Start any slice with `/curdx-flow:start <epic-name>-<slice-id>`. Suggested order: S1 → S2 → S3."
+
+## References
+
+- Vertical-slice methodology: `@${CLAUDE_PLUGIN_ROOT}/knowledge/epic-decomposition.md`
+- Spec skeleton: `@${CLAUDE_PLUGIN_ROOT}/templates/`

package/skills/security-audit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: security-audit
+description: Invoke when the user wants a security review — OWASP Top 10, STRIDE threat modeling, credential handling, injection, secrets, sensitive data handling. Triggers on "security", "auth", "authentication", "credential", "password", "secret", "API key", "token", "OWASP", "STRIDE", "CVE", "vulnerability", "injection", "XSS", "CSRF", "SSRF", "SQL injection", "hardcoded secret", "sensitive data", "leak", "will my API key leak", "is this safe".
+allowed-tools: [Read, Grep, Glob, Bash, WebSearch]
+---
+
+# Security Audit
+
+You are invoked when the user wants a systematic security review of the current spec or codebase.
+
+## Preconditions
+
+1. The code or spec under review is reachable from the current working directory.
+2. The user has identified the scope (current spec, specific module, or whole repo).
+
+## Workflow
+
+### Step 1: Clarify audit scope
+
+Confirm:
+- **Scope** (current spec / specific paths / whole repo)
+- **Depth** (OWASP-only / OWASP + STRIDE / + dependency CVE scan)
+- **Risk tolerance** (block on any SR / only block on SR with POC / advisory only)
+
+### Step 2: Dispatch `flow-security-auditor`
+
+Delegate to the `flow-security-auditor` agent. It will:
+1. Scan for hardcoded secrets, weak crypto, unsanitized inputs
+2. Apply OWASP Top 10 (A01 Broken Access Control → A10 SSRF)
+3. Apply STRIDE threat modeling (Spoofing, Tampering, Repudiation, Information disclosure, DoS, Elevation)
+4. Run dependency CVE scan (`npm audit` / equivalent)
+5. Produce a findings report with severity labels (SR = Blocking Red line, SW = Warning, SM = Mandatory-to-address)
+
+### Step 3: Write security report
+
+Output `.flow/specs/<active>/security-audit.md` containing:
+- **SR (blocking)** — must fix before ship
+- **SW (warning)** — should fix, won't block
+- **SM (mandatory)** — baseline items that must be present
+- **CVE hits** — direct / transitive dependencies with known vulns
+- **Recommended fixes** — concrete patches, not generic advice
+
+### Step 4: Enforce gate
+
+Apply the `security-gate` (`@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`) — if any SR findings exist, block completion until remediated or explicitly waived with a D-NN decision in STATE.md.
+
+## References
+
+- `flow-security-auditor` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-security-auditor.md`
+- security-gate: `@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md`

package/skills/ui-sketch/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: ui-sketch
+description: Invoke when the user wants UI design drafts — components, layouts, variants, mockups, CSS/theme/styling decisions. Triggers on "design UI", "UI design", "component layout", "variants", "wireframe", "mockup", "prototype", "sketch", "draft layout", "visual design", "styling", "CSS", "theming", "dark mode", "responsive design", "color scheme", "build me a UI", "show several variants", "try different colors".
+allowed-tools: [Read, Write, Bash, WebSearch]
+---
+
+# UI Sketch
+
+You are invoked when the user wants fresh UI design drafts — typically 2–4 variants for comparison, or a single iterative refinement.
+
+## Preconditions
+
+1. The `frontend-design` skill (Anthropic official) should be installed. Without it, fall back to Tailwind + shadcn/ui defaults.
+2. The user provides a description of the UI goal (component, page, or flow).
+
+## Workflow
+
+### Step 1: Clarify design brief
+
+Confirm with the user:
+- **What is being designed** (component / page / full screen)
+- **Context** (consumer product / enterprise tool / marketing site / internal dashboard)
+- **Must-haves** (brand colors / existing design system / responsive breakpoints)
+- **Variant count** (default: 3 variants with distinct design directions)
+
+### Step 2: Dispatch `flow-ux-designer`
+
+Delegate to the `flow-ux-designer` agent with the brief. It will:
+1. Invoke the `frontend-design` skill with the brief
+2. Generate N variant HTML/JSX files under `.flow/specs/<active>/sketches/`
+3. For each variant, produce a rationale: typography, color, layout decisions
+4. Open the variants for user preview if a dev server is running
+
+### Step 3: Present variants
+
+Show the user:
+- **Variant preview URLs** or file paths
+- **Design rationale** per variant (what's different, why)
+- **Accessibility notes** (contrast ratios, focus states)
+
+### Step 4: Iterate or finalize
+
+- If user picks a variant: move the chosen file into the spec's `design.md` asset section.
+- If user wants a hybrid: dispatch `flow-ux-designer` again with "merge variant A layout + variant B color scheme".
+
+## References
+
+- `flow-ux-designer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ux-designer.md`
+- `flow-ui-researcher` agent (for competitive reference scraping): `@${CLAUDE_PLUGIN_ROOT}/agents/flow-ui-researcher.md`

package/templates/config.json.tmpl

@@ -32,7 +32,7 @@
   "specs": {
     "directories": ["./.flow/specs"],
     "default_task_size": "fine",
-    "_task_size_options": "fine (40-60 tasks) | coarse (10-20 tasks)"
+    "_task_size_hint": "as-needed decomposition (no fixed count) — see agents/flow-planner.md"
   },
 
   "addons": {

package/templates/design.md.tmpl

@@ -9,155 +9,75 @@ 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.
+> Conclusions from flow-architect. Sequential-thinking is invoked proportional to the genuine tradeoff surface — the chain lives in the thinking tool, not this document.
+>
+> **Fill only the sections that carry real design information for this feature.** Well-known stack assemblies legitimately compress to a stack list + data model + a few real ADs. Delete sections whose honest answer would be "N/A" or "standard for this stack". A forced 13-section template is the bloat pattern this is designed to prevent.
 
 ---
 
 ## Design Overview (one paragraph)
 
-<!-- One-sentence summary of the architecture -->
+<!-- One sentence summary of the approach. -->
 
 ## Architecture Decisions
 
-<!-- Each major decision gets an ID and is written to the decisions array in .flow/STATE.md -->
+<!-- Each real decision gets an AD-NN. If a decision is "obvious, no alternative worth listing," use one line and move on. -->
 
 ### AD-01: ...
-- **Decision**: Use X instead of Y
+- **Decision**: Use X
 - **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)]
-```
+- **Trade-off**: ... (omit if there is no genuine tradeoff)
 
 ## Component Design
 
-<!-- Each component is independently testable. Interfaces are explicit. -->
+<!-- Each component: responsibility, input type, output type, dependencies, error path. Skip if the feature is a single module with no internal boundaries worth naming. -->
 
-### Component: {{COMP_NAME_1}}
+### Component: {{COMP_NAME}}
 - **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,
-  ...
-);
-```
+- **Input**: `interface Input { ... }`
+- **Output**: `interface Output { ... }`
+- **Dependencies**: ...
+- **Errors**: ...
 
-### Or TypeScript types:
-```ts
-interface Entity {
-  id: string;
-  ...
-}
-```
+## Data Model (if the feature touches persistence or structured data)
 
-## State Machine (if applicable)
+<!-- SQL schema, TypeScript types, or API payload shape. Delete if the feature has no meaningful data shape. -->
+
+## Architecture Diagram (include only when it clarifies; prose often suffices)
 
 ```mermaid
-stateDiagram-v2
-  [*] --> Pending
-  Pending --> Active: approve
-  Pending --> Rejected: reject
-  Active --> Completed: finish
+flowchart TB
+  ...
 ```
 
-## Error Path Design
+## State Machine (include only if the feature has non-trivial state transitions)
 
-<!-- Full flow on failure -->
+## Error Path Design (include when error behavior is not obvious)
 
-| 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" |
+| Scenario | System Response | User-visible |
+|-----|---------|---------|
+| ... | ... | ... |
 
-## API Contract
-
-<!-- If this is an API project -->
+## API Contract (include only if this feature exposes or changes an API)
 
 ```yaml
-POST /api/v1/...
-Request:
-  body:
-    field: string
-Response:
-  200:
-    body:
-      field: string
-  400:
-    body:
-      error: string
+...
 ```
 
-## Test Matrix
+## Test Matrix (brief — one line per layer)
 
 | 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 | ... |
+## Risks and Mitigations (include only if risks exist that aren't obvious from the ADs)
 
 ## Defer to Implementation
 
-<!-- Decisions not worth spending time on in the design phase -->
+<!-- Decisions explicitly deferred to when the executor writes the code. -->
 
-- 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._
+_Generated by flow-architect on {{CREATED_DATE}}._

package/templates/requirements.md.tmpl

@@ -9,86 +9,68 @@ depends_on: research.md
 
 # Requirements Spec: {{SPEC_NAME}}
 
-> **Recommended direction from the research phase**: {{RESEARCH_CONCLUSION}}
+> **Recommended direction from research**: {{RESEARCH_CONCLUSION}}
 >
-> This phase: translate "technically feasible" into "concrete behaviors users benefit from".
+> **Fill only the sections that carry real information for this feature.** Delete or collapse any section whose honest content would be "N/A" or "same as usual". Padding sections with "TBD" is worse than omitting them.
 
 ---
 
 ## User Stories
 
-<!-- Each story follows the format: As X, I want Y, so that Z -->
-
 ### US-01: ...
-**As** [user role],
-**I want** [capability],
-**so that** [business value].
+**As** [user role], **I want** [capability], **so that** [business value].
 
 **Acceptance criteria**:
 - AC-1.1: [verifiable behavior]
-- AC-1.2: [verifiable behavior]
-- AC-1.3: [edge case handling]
+- AC-1.2: ...
 
-### US-02: ...
-<!-- ... -->
+<!-- Add more US-NN blocks only if the feature genuinely has multiple independent user flows. -->
 
 ## Functional Requirements
 
-<!-- FR-NN format. Each FR must be a verifiable statement of "the system must X". -->
-
 - **FR-01**: The system must ...
-- **FR-02**: The system must ...
-- **FR-03**: ...
+- **FR-02**: ...
 
 ## Non-Functional Requirements
 
-### Performance
-- **NFR-P-01**: [e.g. P95 response time < 200ms]
-- **NFR-P-02**: ...
+<!--
+Include ONLY the NFR categories that this feature is actually constrained by.
+For a small internal CRUD feature, "Performance / Security / Maintainability / Compatibility" as a four-bucket grid is usually padding.
+Delete categories that have no real requirement, or collapse into one line: "NFR: standard for this stack, no special constraints."
+-->
 
-### Security
-- **NFR-S-01**: ...
-- **NFR-S-02**: ...
+### Performance (if applicable)
+- **NFR-P-01**: ...
 
-### Maintainability
-- **NFR-M-01**: ...
+### Security (if applicable)
+- **NFR-S-01**: ...
 
-### Compatibility
-- **NFR-C-01**: ...
+<!-- Delete Maintainability / Compatibility sections unless they carry a real constraint. -->
 
 ## Edge Cases and Error Handling
 
-<!-- Must be explicit: what happens on failure? how are abnormal inputs handled? -->
+<!-- Include rows only for scenarios that actually apply. -->
 
 | Scenario | Expected behavior |
 |-----|--------|
-| Network disconnected | ... |
-| Database exception | ... |
-| Invalid input | ... |
-| Concurrent conflict | ... |
+| ... | ... |
 
 ## Out of Scope
 
-<!-- Karpathy principle 2: simplicity first. Explicitly list "not this time" to prevent scope creep. -->
-
-- ✗ Feature A — deferred to the next version
-- ✗ Feature B — out of budget
-- ✗ Feature C — needs its own spec
+- ✗ ...
 
-## Success Metrics
+## Success Metrics (if the feature has measurable outcomes)
 
-<!-- Must be quantifiable -->
+<!-- Delete this section for internal tools or refactors with no user-visible metric. -->
 
-- Metric 1: [e.g. user signup completion rate > 80%]
-- Metric 2: [e.g. complaint rate < 1%]
+- Metric 1: ...
 
 ## Open Questions
 
-<!-- Questions that need user answers -->
+<!-- Include only if there are genuinely unresolved questions. Delete when empty. -->
 
-1. **Question 1**: ...
-2. **Question 2**: ...
+1. ...
 
 ---
 
-_Generated by flow-product-designer agent on {{CREATED_DATE}}. After user review, proceed to the design phase._
+_Generated by flow-product-designer on {{CREATED_DATE}}._

package/templates/research.md.tmpl

@@ -10,105 +10,74 @@ status: in_progress
 
 > **Goal**: {{SPEC_GOAL}}
 >
-> Output of this phase. Subsequent requirements / design / tasks are all based on the conclusions of this document.
+> **Fill only the sections that carry real information.** For a well-understood feature on a known stack, research legitimately compresses to: goal, one recommended direction, known constraints. Delete sections whose honest content would be "N/A" or "first time, nothing to fetch". Padding this document with "TBD" is worse than omitting sections.
 
 ---
 
-## Prior Experience (from claude-mem)
-
-<!--
-flow-researcher first calls mcp__claude_mem__search to retrieve relevant history.
-If there are relevant observations, summarize them here; if not, write "(first research on this topic)".
--->
+## Prior Experience (from claude-mem, if relevant)
 
 {{CLAUDE_MEM_FINDINGS}}
 
-## Problem Understanding
+<!-- Delete this section if there are no relevant prior observations. -->
 
-<!-- Translate the user's goal into technical language. Explicitly list assumptions. -->
+## Problem Understanding
 
 ### Core Problem
-<!-- One-line description of what we are solving -->
+<!-- One sentence. What are we solving? -->
 
 ### Explicit Assumptions
-<!-- Karpathy principle 1: think before coding. List all assumptions for the user to confirm -->
+<!-- Only real assumptions that matter. Don't list "assumption: we will write code." -->
+
 - Assumption 1: ...
-- Assumption 2: ...
 
 ### Known Constraints
-- Tech stack:
-- Budget / time:
-- Team capability:
-- Compliance requirements:
-
-## Technical Solution Space
+<!-- Include only the constraints that actually shape the solution. -->
 
-<!-- List 2-3 possible approaches with their pros and cons. Pick one in the design phase. -->
+- Tech stack: ...
+- Time budget: ...
+- (Compliance, team capability, etc — only if they constrain this feature)
 
-### Option A: ...
-- **Pros**:
-- **Cons**:
-- **Complexity**: low / medium / high
-- **Docs (context7 queries)**:
-  - `library-name@version`: ...
+## Technical Solution Space
 
-### Option B: ...
-- **Pros**:
-- **Cons**:
-- **Complexity**: low / medium / high
+<!--
+If one approach is clearly the right call for this stack, write only that approach with its rationale.
+Include alternative options ONLY when there is a genuine tradeoff a thoughtful engineer might disagree on.
+Do not invent Option B and Option C just to fill the template.
+-->
 
-### Option C (optional): ...
+### Recommended Approach: ...
+- **Why**: ...
+- **Complexity**: ...
+- **Key APIs verified via context7**: ...
 
-## Existing Code Analysis
+### Alternative: ... (include only if a real alternative exists)
 
-<!-- Codebase scan results. Which existing modules can be reused? Which need to be new? -->
+## Existing Code Analysis (include only if the codebase has relevant prior work)
 
 ### Reusable Modules
-- `path/to/existing-module.ts` — ...
-
-### Modules to Create
-- `path/to/new-module.ts` — ...
-
-### Modules to Modify
-- `path/to/modify.ts` — ...
-
-## Latest Documentation Summary (context7)
-
-<!-- Latest APIs / best practices found by flow-researcher via mcp__context7__* -->
-
-### {{LIBRARY_1}}
-- Version:
-- Relevant APIs:
-- Gotchas / changes:
-
-### {{LIBRARY_2}}
-- ...
-
-## Feasibility Assessment
+- `path/to/module` — ...
 
-<!-- Explicitly answer: can this be done? how hard is it? -->
+### New Modules Required
+- `path/to/new` — ...
 
-- **Feasibility**: ✓ feasible / ⚠ risky / ✗ not recommended
-- **Estimated complexity**: 1-10
-- **Main risks**:
-  - Risk 1: ...
-  - Risk 2: ...
+## Latest Documentation Summary
 
-## Recommended Direction
+<!-- Only include libraries whose API is version-sensitive AND used by this feature. Do not cite every library in the stack. -->
 
-<!-- Research conclusion: which option is recommended and why. If multiple options need discussion, explain here. -->
+### {{LIBRARY}}
+- Version: ...
+- Relevant APIs: ...
+- Gotchas: ...
 
-**Recommendation**: Option ?
-**Rationale**:
-**To confirm in the design phase**:
+## Feasibility
 
-## Open Questions
+- **Verdict**: feasible / risky / not recommended
+- **Main risks**: (only if real risks exist)
 
-<!-- Questions the research phase couldn't answer, to be deferred to later phases or asked of the user -->
+## Open Questions (delete if none)
 
 1. ...
-2. ...
 
 ---
 
-_Generated by flow-researcher agent on {{CREATED_DATE}}. Subsequent phases continue from this document._
+_Generated by flow-researcher on {{CREATED_DATE}}._