@curdx/flow 1.1.4 → 1.1.6

package/commands/triage.md

@@ -0,0 +1,160 @@
+---
+name: triage
+description: Epic decomposition — slice a big goal vertically by user value, generate dependency graph + multiple sub-specs. Dispatches flow-triage-analyst.
+argument-hint: "\"<epic goal>\" [--specs=<N>]"
+allowed-tools: [Read, Write, Bash, Task, WebSearch]
+---
+
+# Flow Triage — Epic Decomposition
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/epic-decomposition.md
+
+Break down a big goal (needs 4+ sub-specs to complete) into an Epic of vertical slices.
+
+## When to Use
+
+- Goal is clearly more than 2 weeks of work
+- Involves multiple "independently usable" features
+- At `/curdx-flow:start`, you realize the goal is too big — switch to `/curdx-flow:triage`
+
+## When Not to Use
+
+- Goal fits in 1-2 weeks → use `/curdx-flow:start`
+- Emergency fix → use `/curdx-flow:fast`
+- Exploratory validation → use `/curdx-flow:spike`
+
+## Step 1: Preflight Check
+
+```bash
+[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project"; exit 1; }
+
+GOAL="$ARGUMENTS"
+# Extract --specs argument
+TARGET_SPECS=""
+case "$GOAL" in
+    *--specs=*)
+        TARGET_SPECS=$(echo "$GOAL" | grep -oE -- '--specs=[0-9]+' | cut -d= -f2)
+        GOAL=$(echo "$GOAL" | sed 's/--specs=[0-9]*//g' | xargs)
+        ;;
+esac
+
+[ -z "$GOAL" ] && { echo "Usage: /curdx-flow:triage \"<epic goal>\""; exit 1; }
+```
+
+## Step 2: Generate Epic Name
+
+Derive a kebab-case name from the goal, or ask the user:
+
+```python
+# Rough inference
+slug = re.sub(r'\s+', '-', goal.lower())
+slug = re.sub(r'[^a-z0-9-]', '', slug)[:40]
+# e.g.: "add payment system" → "payment-system"
+# May need AskUserQuestion to confirm
+```
+
+## Step 3: Create Epic Directory
+
+```bash
+EPIC_DIR=".flow/_epics/$EPIC_NAME"
+mkdir -p "$EPIC_DIR"
+```
+
+## Step 4: Dispatch flow-triage-analyst
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Epic decomposition: $EPIC_NAME"
+  prompt: |
+    You are the flow-triage-analyst agent. Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-triage-analyst.md
+    
+    Knowledge base (must read):
+    ${CLAUDE_PLUGIN_ROOT}/knowledge/epic-decomposition.md
+    
+    Input:
+    - Epic goal: "$GOAL"
+    - Epic name: $EPIC_NAME
+    - Suggested sub-spec count: ${TARGET_SPECS:-auto (4-8)}
+    - Project context: .flow/PROJECT.md + .flow/CONTEXT.md + .flow/STATE.md
+    
+    Mandatory workflow:
+    1. sequential-thinking >= 5 rounds to understand the goal
+    2. context7 to validate the key technologies involved
+    3. claude-mem to retrieve history
+    4. sequential-thinking 5+ rounds to brainstorm decomposition
+    5. Vertical slice by user value (not by technical layer)
+    6. Define shared interfaces (freeze)
+    7. Identify dependencies (hard/soft/parallel)
+    8. Generate epic.md + sub-spec skeletons
+    
+    Output files:
+    - .flow/_epics/$EPIC_NAME/epic.md  (Epic master document)
+    - .flow/_epics/$EPIC_NAME/.epic-state.json
+    - .flow/specs/<sub-1>/.state.json
+    - .flow/specs/<sub-2>/.state.json
+    - ...(skeleton for each sub-spec)
+    
+    Success criteria:
+    - Sub-spec count: 4-8
+    - Each sub-spec has independent user value
+    - Dependency graph is clear (mermaid)
+    - Shared interfaces frozen (TypeScript types)
+    - Out of Scope is explicit
+    
+    When done, return a brief:
+    - Sub-spec list (name + one-sentence description)
+    - Dependency graph
+    - Recommended execution order
+    - Estimated total duration
+```
+
+## Step 5: Validate Output
+
+```bash
+EPIC_FILE="$EPIC_DIR/epic.md"
+[ ! -f "$EPIC_FILE" ] && { echo "❌ Epic document not generated"; exit 1; }
+
+# Count sub-specs
+SUB_COUNT=$(grep -c "^### Spec [0-9]" "$EPIC_FILE" || echo 0)
+[ $SUB_COUNT -lt 3 ] && echo "⚠ Fewer than 3 sub-specs; may not be decomposed enough"
+[ $SUB_COUNT -gt 10 ] && echo "⚠ More than 10 sub-specs; granularity may be too fine"
+
+# Check mermaid graph
+grep -q "mermaid" "$EPIC_FILE" || echo "✗ No mermaid dependency graph found"
+
+# Check shared interfaces
+grep -q "shared interface" "$EPIC_FILE" || echo "✗ Shared interfaces not defined"
+```
+
+## Step 6: Show Results to User
+
+```
+✓ Epic decomposition complete: $EPIC_NAME
+
+Files:
+  .flow/_epics/$EPIC_NAME/epic.md
+  .flow/_epics/$EPIC_NAME/.epic-state.json
+
+Sub-specs: $SUB_COUNT (skeletons created)
+
+Dependency graph: see epic.md
+
+Recommended execution order:
+  Week 1: /curdx-flow:switch <sub-1> → /curdx-flow:spec → /curdx-flow:implement
+  Week 2: /curdx-flow:switch <sub-2> (parallel with sub-3 if independent)
+  Week 3: /curdx-flow:switch <sub-4> (depends on sub-1 being done)
+  ...
+
+Next steps:
+  1. Review .flow/_epics/$EPIC_NAME/epic.md to confirm the decomposition is reasonable
+  2. First sub-spec: /curdx-flow:switch <sub-1-name>
+  3. Then proceed with the normal /curdx-flow:spec → /curdx-flow:implement flow
+```
+
+## Error Recovery
+
+- triage-analyst fails → the goal may be too abstract; refine the description manually and rerun
+- Too many/too few sub-specs → use `--specs=N` to force a count
+- Incomplete interface definitions → go back to epic.md and add interfaces manually, or rerun the agent to fill them in

package/commands/verify.md

@@ -0,0 +1,124 @@
+---
+name: verify
+description: goal reverse verification — trace back from FR/AC/AD to check whether the code actually implements them, detect stubs / fake completion. Dispatches flow-verifier.
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Bash, Task, Grep, Glob]
+---
+
+# Flow Verify — Goal Reverse Verification
+
+Dispatch the `flow-verifier` agent to confirm, starting from the spec, that the code truly implements the requirements; do not trust any "done" claim.
+
+## When to Use
+
+- After `/curdx-flow:implement` completes
+- Final gate before a PR
+- When you suspect a feature is a fake implementation (stub/TODO)
+
+## Step 1: Parse + Preflight Check
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+[ -z "$SPEC_NAME" ] && { echo "❌ No active spec. Run /curdx-flow:switch or /curdx-flow:start first"; exit 1; }
+
+DIR=".flow/specs/$SPEC_NAME"
+for f in requirements.md design.md; do
+    [ ! -f "$DIR/$f" ] && { echo "❌ Missing $f. Complete /curdx-flow:requirements /curdx-flow:design first"; exit 1; }
+done
+```
+
+## Step 2: Determine Scope
+
+```bash
+# Read the commit range for the execute phase
+# From .state.json or git reflog
+
+LAST_EXEC_START=$(python3 -c "
+import json
+s = json.load(open('$DIR/.state.json'))
+# Custom field or inferred from git
+print(s.get('execute_state', {}).get('start_commit', ''))
+")
+
+# If unavailable, use main..HEAD
+RANGE="${LAST_EXEC_START:-main}..HEAD"
+echo "Verification scope: $RANGE"
+```
+
+## Step 3: Dispatch flow-verifier
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "verify $SPEC_NAME"
+  prompt: |
+    You are the flow-verifier agent. Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-verifier.md
+    
+    Must read:
+    - .flow/specs/$SPEC_NAME/requirements.md
+    - .flow/specs/$SPEC_NAME/design.md
+    - .flow/specs/$SPEC_NAME/tasks.md
+    - .flow/specs/$SPEC_NAME/.state.json
+    - .flow/STATE.md
+    
+    Verification scope: commits $RANGE
+    
+    Tasks:
+    1. Extract every FR / AC / AD / Component / error-path assertion
+    2. Find evidence for each assertion (code + test + actual run)
+    3. Scan for stub patterns (TODO / Not implemented / return {})
+    4. Generate verification-report.md
+    5. Update phase_status.verify in .state.json
+    
+    Output file:
+    .flow/specs/$SPEC_NAME/verification-report.md
+    
+    Return a brief:
+    - Fully verified / partially verified / not verified counts
+    - Number of fake implementations
+    - List of blockers
+    - Suggested next step
+```
+
+## Step 4: Read Report + Decide
+
+```bash
+REPORT="$DIR/verification-report.md"
+[ ! -f "$REPORT" ] && { echo "❌ verifier did not produce a report"; exit 1; }
+
+# Parse the verdict from the report
+VERIFIED=$(grep -c "^\- ✓" "$REPORT" || echo 0)
+PARTIAL=$(grep -c "^\- ⚠" "$REPORT" || echo 0)
+MISSING=$(grep -c "^\- ✗" "$REPORT" || echo 0)
+STUBS=$(grep -c "^\- 🚨" "$REPORT" || echo 0)
+```
+
+## Step 5: Output to User
+
+```
+✓ Verify complete: $SPEC_NAME
+
+Stats:
+  ✓ Fully verified:     $VERIFIED
+  ⚠ Partially verified: $PARTIAL
+  ✗ Not verified:       $MISSING
+  🚨 Fake implementations: $STUBS
+
+Report: .flow/specs/$SPEC_NAME/verification-report.md
+
+Verdict:
+  $([ $MISSING -gt 0 ] && echo '❌ BLOCKED — unimplemented FR/AC/AD exist, return to /curdx-flow:implement to fill in')
+  $([ $STUBS -gt 0 ] && echo '❌ BLOCKED — fake implementations found')
+  $([ $MISSING -eq 0 ] && [ $STUBS -eq 0 ] && echo '✓ PASS — can proceed to /curdx-flow:review')
+
+Next step:
+  $([ $MISSING -gt 0 ] && echo 'fix blockers → /curdx-flow:implement --task=<new task>')
+  $([ $MISSING -eq 0 ] && echo '/curdx-flow:review — enter code quality review')
+```
+
+## Error Recovery
+
+- verifier times out → reduce spec scope (verify only specific FRs), then rerun
+- Some Verify commands are unavailable (e.g. require a DB connection) → mark "needs manual verification" in the report
+- verifier output is vague → prompt to look at specific sections of the report

package/gates/adversarial-review-gate.md

@@ -0,0 +1,219 @@
+---
+gate: adversarial-review-gate
+category: enterprise-mode
+severity: warning
+depends_on: []
+---
+
+# Adversarial Review Gate
+
+> Derived from BMAD-METHOD's "Adversarial Review Prompts".
+>
+> **Core**: The reviewer must find problems. "Zero findings" triggers re-analysis. This forcibly breaks confirmation bias.
+
+---
+
+## Trigger Timing
+
+- /curdx-flow:review command
+- Before Phase transitions (requirements → design, design → tasks)
+- Before code merge (/curdx-flow:ship)
+- Enabled by default in Enterprise mode
+
+---
+
+## Core Rules
+
+### Rule 1: Zero Findings Forbidden
+
+A reviewer agent's output of "everything looks fine, no issues found" is an **invalid conclusion**.
+
+**Reasons**:
+- Real systems inevitably contain trade-offs, boundaries, and risks
+- "Looks good" is usually confirmation bias (the agent only checked the obvious)
+- AI tends to please the user ("great job!") — fight this tendency
+
+**Forced actions**:
+1. If the agent outputs "no issues", automatically trigger a second round
+2. The second round requires the agent to perform deeper analysis via sequential-thinking
+3. If both rounds yield no findings, the agent must **prove** it checked:
+   - List the dimensions examined (at least 5)
+   - For each dimension, give the specific code/file locations inspected
+   - Provide counterfactual hypotheses of "what it would look like if there were a problem"
+
+---
+
+### Rule 2: Findings in at Least 3 Categories
+
+A complete adversarial review must cover (find issues in at least 3 of these categories):
+
+1. **Architecture layer**: Are decisions sound? Future-extensible? Lock-in risks?
+2. **Implementation layer**: Code quality? Error handling? Performance?
+3. **Test layer**: Coverage? Edge cases? Over-mocking?
+4. **Security layer**: Injection risks? Permission checks? Sensitive data leakage?
+5. **Maintainability layer**: Documentation? Naming? Readability?
+6. **User experience layer**: Error messages? Loading states? Accessibility?
+
+---
+
+### Rule 3: Findings Must Have Evidence + Recommendation
+
+Format for each finding:
+
+```markdown
+### [Category] Issue Title
+
+**Location**: src/auth/login.ts:42
+
+**Observation**: <what was specifically seen>
+
+**Risk**: <what problem will this cause? High/Medium/Low?>
+
+**Evidence**: <code snippet / test output / scenario>
+
+**Recommendation**: <specifically how to fix>
+```
+
+Not allowed:
+- ✗ "The code could be better" (too vague)
+- ✗ "I think... maybe..." (no specific basis)
+
+---
+
+## Execution Flow
+
+```
+Input: object under review (code range / spec / PR diff)
+  ↓
+Round 1 (agent self-analysis):
+  - Use sequential-thinking ≥ 6 rounds
+  - Scan all 6 categories
+  - Output findings list
+  ↓
+Decision:
+  - Findings ≥ 3? → output report
+  - Findings < 3? → force Round 2
+  ↓
+Round 2 (deep analysis):
+  - sequential-thinking for another 6 rounds
+  - Focus on "seemingly no issues" parts (trust but verify)
+  - May introduce external perspectives (read issues from similar projects)
+  ↓
+Decision:
+  - Still < 3? → agent must explicitly prove it checked
+  - Otherwise → output report
+  ↓
+Output: review-report.md
+```
+
+---
+
+## Typical Finding Patterns (for agent reference)
+
+### Architecture
+- "New component X depends on Y, but Y is not mentioned in design.md → introduces implicit coupling"
+- "AD-03 chooses JWT, but does not handle token revocation → user logout is not thorough"
+
+### Implementation
+- "src/auth/login.ts:42 catches all exceptions and returns 500, but bcrypt timeout should return 429"
+- "Verify in tasks.md is `npm test`, no specific test file specified → may have run unrelated tests"
+
+### Testing
+- "login.test.ts has 5 tests, but AC-1.3 (empty password) is not covered"
+- "Tests use `jest.fn()` to mock DB; actual DB constraints are not tested → may fail in production"
+
+### Security
+- "Error message returns `User not found`, can be identified by enumeration attack for existence"
+- "JWT secret comes from process.env with no fallback → crashes when environment variable is missing"
+
+---
+
+## Output Format
+
+```markdown
+## Adversarial Review Report
+
+Object under review: auth-system spec (commits abc..xyz)
+Review time: 2026-04-19
+Review rounds: 2 (Round 1 found 2, triggered Round 2)
+
+## Total findings: 5
+
+### [Architecture] Token revocation not designed
+Location: design.md AD-01
+Observation: stateless JWT was chosen, but requirements FR-04 requires "user logout immediately invalidates other sessions"
+Risk: High — violates an explicit requirement
+Evidence: AD-01 only says "use JWT", does not say how to revoke
+Recommendation: Add AD-06 explaining the use of Redis blacklist + check-on-each-request
+
+### [Implementation] bcrypt error handling missing
+Location: src/auth/login.ts:58
+Observation: await bcrypt.compare() has no try-catch
+Risk: Medium — bcrypt crash will cause 500 exposing internal stack
+Evidence: (code snippet omitted)
+Recommendation: wrap in try-catch, return 401
+
+### [Test] AC-1.3 not covered
+Location: login.test.ts
+Observation: requirements AC-1.3 requires "empty password returns 400", but there is no corresponding test
+Risk: Medium — regression risk
+Evidence: grep "empty password" → 0 matches
+Recommendation: add test("rejects empty password", ...)
+
+### [Security] User enumeration leak
+Location: src/auth/login.ts:45-50
+Observation: email not found → "User not found"; email found pwd wrong → "Wrong password"
+Risk: High — can be used to enumerate registered emails
+Evidence: (code snippet)
+Recommendation: unify error message to "Invalid credentials"
+
+### [Maintainability] Inconsistent log format
+Location: src/auth/login.ts:42 vs src/auth/logout.ts:18
+Observation: one uses `console.log`, the other uses `logger.info`
+Risk: Low — does not affect functionality, but future monitoring will be messy
+Evidence: grep log → 2 patterns
+Recommendation: unify to logger.info
+
+## Summary
+
+Blockers: 2 ([Architecture] token revocation, [Security] user enumeration)
+Warnings: 3
+
+Fix loop:
+1. Dispatch flow-executor to fix security + architecture (high priority)
+2. Add tests
+3. Unify log
+4. Re-run /curdx-flow:review for re-review
+```
+
+---
+
+## Failure Recovery
+
+If after 2 rounds there are still < 3 findings:
+
+```markdown
+## Adversarial Review — Insufficient Findings
+
+I have examined the following dimensions across 2 rounds of analysis:
+
+1. Architecture: checked AD-01~04 and corresponding implementations, no obvious issues found
+2. Implementation: checked src/auth/*.ts totaling 342 lines, no obvious issues found
+3. Tests: checked 15 tests, covered all ACs, no gaps found
+4. Security: checked input validation, error messages, secret management, no issues found
+5. Maintainability: naming and structure are consistent
+
+⚠ Note: this does not mean there are truly no issues. It may be that:
+- the object under review is indeed high quality
+- or my review capability has blind spots (e.g., specific domains)
+- or there are hidden issues that will only surface at runtime
+
+Recommendations:
+- Human review (at least walk through the diff once)
+- Consider /curdx-flow:qa for real browser/integration testing (Phase 5+)
+- Wait until deployment to staging to observe
+```
+
+---
+
+_Source: BMAD-METHOD's adversarial review prompts._

package/gates/coverage-audit-gate.md

@@ -0,0 +1,184 @@
+---
+gate: coverage-audit-gate
+category: standard-mode
+severity: blocking
+depends_on: []
+---
+
+# Coverage Audit Gate — Multi-Source Coverage Audit
+
+> Derived from get-shit-done's "Multi-Source Coverage Audit".
+>
+> Rule: every claim in the spec must be covered by implementation/tests. Uncovered = missed = future bug.
+
+---
+
+## Trigger Timing
+
+- End of the tasks phase (last step of flow-planner)
+- Before the execution phase completes (when /curdx-flow:verify runs)
+- Explicitly requested by /curdx-flow:audit
+
+---
+
+## Audit Sources (4 categories)
+
+### Source 1: Requirements (FR + AC)
+
+**Source**: `requirements.md`
+
+**Checks**:
+- Does every FR-NN have a corresponding task in tasks.md?
+- Does every AC-X.Y have a corresponding test in code?
+
+**Missing handling**:
+- Uncovered FR → block, must add task or exempt
+- Uncovered AC → warning, recommend adding test
+
+---
+
+### Source 2: Design (AD + Components)
+
+**Source**: `design.md`
+
+**Checks**:
+- Does every AD-NN have a corresponding implementation task in tasks.md?
+- Does every Component have a skeleton task + core logic task in tasks.md?
+- Does every error path have a corresponding scenario in tests?
+
+**Missing handling**:
+- Uncovered AD → block (an architecture decision not landed = design failure)
+- Uncovered error path → warning
+
+---
+
+### Source 3: Research recommendations
+
+**Source**: the "recommendations" section of `research.md`
+
+**Checks**:
+- Are the technical approaches recommended by research implemented in design.md?
+- Are the pitfalls found by research avoided in the implementation?
+
+**Missing handling**:
+- Recommended direction not adopted → warning (design.md must explain why not)
+- Pitfall not avoided → block
+
+---
+
+### Source 4: Project-level decisions (D-NN)
+
+**Source**: the decisions array in `.flow/STATE.md`
+
+**Checks**:
+- Which D-NN are involved in this spec?
+- Is each relevant D-NN referenced in design.md / tasks.md?
+- Does the implementation comply with the decision?
+
+**Missing handling**:
+- Violates D-NN → block, must either return to the design phase to challenge the decision or modify the implementation
+- Not referenced but actually compliant → warning (prompt to add reference)
+
+---
+
+## Execution Flow
+
+```python
+# pseudocode
+def audit(spec_name):
+    req = parse_requirements(spec_name)
+    design = parse_design(spec_name)
+    research = parse_research(spec_name)
+    state = parse_global_state()
+    tasks = parse_tasks(spec_name)
+    commits = git_log_for_spec(spec_name)
+    
+    missing = []
+    
+    # Source 1
+    for fr in req.functional_requirements:
+        if not any(fr.id in t.requirements_ref for t in tasks):
+            missing.append(("FR", fr.id, "no task covers"))
+    
+    for ac in req.acceptance_criteria:
+        if not any(ac.id in c.body for c in commits):
+            missing.append(("AC", ac.id, "no test covers"))
+    
+    # Source 2
+    for ad in design.architecture_decisions:
+        if not any(ad.id in t.design_ref for t in tasks):
+            missing.append(("AD", ad.id, "no task implements"))
+    
+    # Source 3
+    for rec in research.recommendations:
+        if rec not in design.chosen_approaches:
+            missing.append(("Research", rec.summary, "not adopted, no rationale"))
+    
+    # Source 4
+    relevant_decisions = [d for d in state.decisions if spec_touches(d)]
+    for d in relevant_decisions:
+        if not any(d.id in text for text in [design.content, tasks.content]):
+            missing.append(("D", d.id, "not referenced"))
+    
+    return missing
+```
+
+---
+
+## Violation Levels
+
+| Missing Type | Level | Action |
+|---------|------|------|
+| FR uncovered | **block** | add task |
+| AC uncovered | warning | add test (recommended) |
+| AD uncovered | **block** | add implementation task |
+| Component uncovered | **block** | add skeleton + logic tasks |
+| Error path uncovered | warning | add error test |
+| Research recommendation not adopted | warning | add rejection rationale to design.md |
+| Project decision violated | **block** | challenge decision or fix implementation |
+
+---
+
+## Output Format
+
+```markdown
+## Coverage Audit Report
+
+Spec: auth-system
+Audit time: 2026-04-19
+
+### Source 1: Requirements
+- FR-01 login: ✓ tasks 1.1, 1.2
+- FR-02 logout: ✓ tasks 2.1
+- FR-03 refresh token: ✗ **uncovered**
+- AC-1.1: ✓ test in tasks 3.1
+- AC-1.2: ⚠ no corresponding test
+- AC-2.1: ✓ test in tasks 3.2
+
+### Source 2: Design
+- AD-01 JWT vs Session: ✓ tasks 1.1
+- AD-02 bcrypt cost 12: ✓ tasks 1.2
+- AD-03 refresh rotation: ✗ **uncovered** (maps to FR-03)
+- Component TokenManager: ✗ **uncovered**
+- Error path: network fail: ⚠ no test
+
+### Source 3: Research
+- Recommendation: use Redis to store blacklist → ✓ adopted in design
+- Pitfall: bcrypt cost > 15 will be slow → ✓ design limits ≤ 12
+
+### Source 4: Decisions
+- D-07 session storage → ✓ referenced by AD-01
+- D-12 error log format → ⚠ not mentioned in design/tasks
+
+### Summary
+Blockers: 3 (FR-03, AD-03, Component TokenManager)
+Warnings: 3
+
+Fix recommendations:
+1. Add tasks to cover FR-03 / AD-03 / TokenManager, or
+2. Explicitly exempt in STATE.md (defer to next spec)
+```
+
+---
+
+_Source: get-shit-done's multi-source coverage audit._