@curdx/flow 1.1.4 → 1.1.6

package/commands/review.md

@@ -0,0 +1,168 @@
+---
+name: review
+description: Two-Stage Review — Stage 1 spec compliance + Stage 2 code quality. Applies enabled Gates. Dispatches flow-reviewer.
+argument-hint: "[spec-name] [--adversarial | --edge-case | --both]"
+allowed-tools: [Read, Bash, Task, Grep, Glob]
+---
+
+# Flow Review — Two-Stage Code Review
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/two-stage-review.md
+
+Dispatches the `flow-reviewer` agent to perform a Two-Stage Review: Stage 1 compliance + Stage 2 quality.
+Optionally layer on deep reviews from `flow-adversary` and `flow-edge-hunter`.
+
+## When to use
+
+- After `/curdx-flow:verify` passes
+- Before PR
+- When the user explicitly requests a deep review (add --adversarial / --edge-case / --both)
+
+## Step 1: Parse arguments
+
+```bash
+ARGS="$ARGUMENTS"
+ADV=0; EDGE=0
+case "$ARGS" in
+    *--both*)        ADV=1; EDGE=1 ;;
+    *--adversarial*) ADV=1 ;;
+    *--edge-case*)   EDGE=1 ;;
+esac
+
+SPEC_NAME=$(echo "$ARGS" | sed 's/--[a-z-]*//g' | xargs)
+[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+[ -z "$SPEC_NAME" ] && { echo "❌ No active spec"; exit 1; }
+```
+
+## Step 2: Preflight checks
+
+```bash
+DIR=".flow/specs/$SPEC_NAME"
+
+# If /curdx-flow:verify hasn't been run, prompt to run it first
+if [ ! -f "$DIR/verification-report.md" ]; then
+    echo "⚠ /curdx-flow:verify not run. Recommend running goal-reverse verification first."
+    echo "Continue? (y/N)"
+    # AskUserQuestion
+fi
+```
+
+## Step 3: Dispatch flow-reviewer (core)
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Review $SPEC_NAME"
+  prompt: |
+    You are the flow-reviewer agent. Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-reviewer.md
+    
+    Spec files to 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/specs/$SPEC_NAME/verification-report.md (if exists)
+    
+    Enabled Gates (from .flow/config.json):
+    - karpathy-gate (always)
+    - verification-gate (always)
+    - tdd-gate (standard+)
+    - coverage-audit-gate (standard+)
+    
+    Tasks:
+    Stage 1: Spec compliance review
+      - Judge each FR / AC / AD / error path as ✓/⚠/✗
+      - Check Out of Scope adherence
+    
+    Stage 2: Code quality review
+      - Apply all enabled Gates
+      - Emit per-Gate check results
+    
+    Combined verdict:
+      - APPROVED / APPROVED_WITH_WARNINGS / NEEDS_FIXES / BLOCKED
+    
+    Output:
+    .flow/specs/$SPEC_NAME/review-report.md
+    
+    Return a brief to me: Stage 1/2 verdicts, blocking/warning counts, and the top 3 fix suggestions
+```
+
+## Step 4 (optional): Dispatch flow-adversary
+
+If `--adversarial`:
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Adversarial review $SPEC_NAME"
+  prompt: |
+    You are the flow-adversary agent. Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-adversary.md
+    
+    Core rule: zero findings are forbidden — must find ≥ 3 categories of issues
+    
+    Scan:
+    - .flow/specs/$SPEC_NAME/*.md
+    - Related code (git diff)
+    - Recent commits
+    
+    Use sequential-thinking ≥ 12 rounds (2 rounds × 6 dimensions)
+    
+    Output: .flow/specs/$SPEC_NAME/adversarial-review.md
+```
+
+## Step 5 (optional): Dispatch flow-edge-hunter
+
+If `--edge-case`:
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Edge-case scan $SPEC_NAME"
+  prompt: |
+    You are the flow-edge-hunter agent. Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-edge-hunter.md
+    
+    Scan the subject's coverage across 7 categories:
+    - Boundary values / nulls / concurrency / error recovery / security / i18n / performance
+    
+    Use sequential-thinking ≥ 3 rounds per category
+    
+    Output: .flow/specs/$SPEC_NAME/edge-cases.md
+```
+
+## Step 6: Read reports + aggregate verdict
+
+```bash
+MAIN_REPORT="$DIR/review-report.md"
+ADV_REPORT="$DIR/adversarial-review.md"
+EDGE_REPORT="$DIR/edge-cases.md"
+
+# Parse the verdict from review-report.md
+VERDICT=$(grep -E "^## Verdict:" "$MAIN_REPORT" | head -1 | sed 's/## Verdict: //')
+```
+
+## Step 7: Output to user
+
+```
+✓ Review complete: $SPEC_NAME
+
+Main report: .flow/specs/$SPEC_NAME/review-report.md
+  Verdict: $VERDICT
+
+$([ "$ADV" = "1" ] && echo "Adversarial review: $ADV_REPORT")
+$([ "$EDGE" = "1" ] && echo "Edge-case scan: $EDGE_REPORT")
+
+Next steps:
+$([ "$VERDICT" = "APPROVED" ] && echo "  ✓ Proceed to /curdx-flow:ship (Phase 6+)")
+$([ "$VERDICT" = "APPROVED_WITH_WARNINGS" ] && echo "  ⚠ Recommend fixing warnings first, then /curdx-flow:ship")
+$([ "$VERDICT" = "NEEDS_FIXES" ] && echo "  ❌ Fix blockers → /curdx-flow:implement --task=... → /curdx-flow:review re-review")
+$([ "$VERDICT" = "BLOCKED_BY_SPEC" ] && echo "  ❌ Back to /curdx-flow:implement to fill missing FR/AD")
+```
+
+## Error recovery
+
+- review-report.md generation fails → check agent turn limit, reduce spec scope
+- Agent returns no findings (violates adversarial zero-tolerance) → agent auto-triggers Round 2
+- Multiple concurrent agents produce conflicting files → run sequentially, not in parallel

package/commands/security.md

@@ -0,0 +1,109 @@
+---
+name: security
+description: Security audit — OWASP Top 10 + STRIDE + dependency CVEs. Dispatches flow-security-auditor (Serena).
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task, Grep, Glob, WebSearch]
+---
+
+# Flow Security — Security Audit
+
+@${CLAUDE_PLUGIN_ROOT}/gates/security-gate.md
+
+Dispatches `flow-security-auditor` (Serena) to perform a full security audit.
+
+## When to use
+
+- Specs touching authentication / authorization / payments / PII
+- Pre-release gate
+- After adding new API endpoints
+- After dependency upgrades
+
+## Step 1: Preflight
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+
+# Can still run without an active spec (global security scan)
+if [ -z "$SPEC_NAME" ]; then
+    echo "ℹ No active spec; running a security scan across the entire codebase"
+    SPEC_NAME="_global"
+fi
+```
+
+## Step 2: Dispatch Serena
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Security Audit: $SPEC_NAME"
+  prompt: |
+    You are the flow-security-auditor agent (Serena). Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-security-auditor.md
+    
+    Audit scope:
+    $([ "$SPEC_NAME" = "_global" ] && echo "Entire codebase" || echo ".flow/specs/$SPEC_NAME/ + related code")
+    
+    Prerequisites:
+    - OWASP Top 10 (2021) checklist
+    - STRIDE threat modeling
+    - package.json (npm audit)
+    - Project auth / data-layer code
+    
+    Workflow:
+    1. Scan OWASP 10 categories in parallel
+       - A01: Broken access control
+       - A02: Cryptography
+       - A03: Injection
+       - A04: Insecure Design
+       - A05: Misconfiguration
+       - A06: CVE (npm audit)
+       - A07: Auth failures
+       - A08: Integrity
+       - A09: Logging
+       - A10: SSRF
+    2. STRIDE threat modeling (≥6 rounds of sequential-thinking)
+    3. context7 to check CVEs for critical dependencies
+    4. Manual review of suspicious areas
+    5. Generate security-audit.md
+    
+    Output:
+    - .flow/specs/$SPEC_NAME/security-audit.md (or .flow/security-audit-global.md)
+    
+    Return to me:
+    - Findings classified by risk (high/medium/low)
+    - Number of must-fix items
+    - Recommended order
+```
+
+## Step 3: Output
+
+```bash
+REPORT=".flow/specs/$SPEC_NAME/security-audit.md"
+[ "$SPEC_NAME" = "_global" ] && REPORT=".flow/security-audit-global.md"
+
+HIGH=$(grep -c "\[High\]" "$REPORT" || echo 0)
+MED=$(grep -c "\[Medium\]" "$REPORT" || echo 0)
+LOW=$(grep -c "\[Low\]" "$REPORT" || echo 0)
+```
+
+```
+🔒 Security Audit complete
+
+Risk distribution:
+  High:   $HIGH (must fix, blocks release)
+  Medium: $MED (recommended to fix)
+  Low:    $LOW (as needed)
+
+Report: $REPORT
+
+Next steps:
+- High risk → /curdx-flow:implement adds fix tasks
+- Or STATE.md explicitly waives + commits to a fix timeline
+- After fixing → /curdx-flow:security to re-audit
+```
+
+## Error recovery
+
+- npm audit requires package.json → non-Node projects skip this class
+- context7 unavailable → use WebSearch to supplement CVE queries
+- No active spec → global scan mode

package/commands/sketch.md

@@ -0,0 +1,118 @@
+---
+name: sketch
+description: UI design sketch — invokes the frontend-design skill to generate multiple HTML variants. Dispatches flow-ux-designer (Emma).
+argument-hint: "[spec-name] [\"<description>\"]"
+allowed-tools: [Read, Write, Bash, Task, WebSearch, AskUserQuestion]
+---
+
+# Flow Sketch — UI Sketch
+
+Dispatches `flow-ux-designer` (Emma) to use the **frontend-design skill** to generate tasteful UI variants.
+
+## Step 1: Parse arguments
+
+```bash
+ARGS="$ARGUMENTS"
+# The first word may be spec-name (if such a spec exists); otherwise it is the description
+
+SPEC_NAME=""
+DESCRIPTION=""
+
+FIRST_WORD=$(echo "$ARGS" | awk '{print $1}')
+if [ -d ".flow/specs/$FIRST_WORD" ]; then
+    SPEC_NAME="$FIRST_WORD"
+    DESCRIPTION=$(echo "$ARGS" | sed "s/^$FIRST_WORD//" | sed 's/^["\x27]//;s/["\x27]$//' | xargs)
+else
+    DESCRIPTION=$(echo "$ARGS" | sed 's/^["\x27]//;s/["\x27]$//')
+fi
+
+[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+```
+
+## Step 2: Preflight checks
+
+```bash
+# Requires at least an active spec (to read CONTEXT.md)
+if [ -z "$SPEC_NAME" ] && [ -z "$DESCRIPTION" ]; then
+    echo "Usage: /curdx-flow:sketch [spec] \"<description of what to sketch>\""
+    echo "Example: /curdx-flow:sketch \"login form\""
+    exit 1
+fi
+
+# Check frontend-design skill (if unavailable, fall back)
+```
+
+## Step 3: Ask for the variant count
+
+```
+AskUserQuestion:
+  Question: "How many variants to generate?"
+  Options:
+    - 2 (compare minimalist vs distinctive)
+    - 3 (recommended — adds a dense variant)
+    - Custom
+```
+
+## Step 4: Dispatch Emma
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "UI Sketch: $DESCRIPTION"
+  prompt: |
+    You are the flow-ux-designer agent (Emma). Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-ux-designer.md
+    
+    Task:
+    - Description: $DESCRIPTION
+    - Spec: $SPEC_NAME (optional)
+    - Variant count: $VARIANT_COUNT
+    
+    Prerequisites:
+    - .flow/CONTEXT.md (user UI preferences)
+    - .flow/specs/$SPEC_NAME/requirements.md (if present)
+    - .flow/specs/$SPEC_NAME/design.md (if present)
+    - .flow/specs/$SPEC_NAME/ui-research.md (if /curdx-flow:ui-research has been run)
+    
+    Workflow:
+    1. Detect the frontend-design skill
+       - Available: activate it to guide design choices
+       - Unavailable: use Tailwind + shadcn defaults and explicitly announce the fallback
+    2. Read user preferences (CONTEXT.md)
+    3. Generate N variant HTMLs (each a single file, zero dependencies, CDN Tailwind)
+    4. Generate an index.html comparison page (iframes side by side)
+    5. Generate decisions.md explaining the rationale for each variant
+    
+    Output directory:
+    .flow/specs/$SPEC_NAME/ui-sketch/ (or .flow/sketches/<slug>/)
+    
+    Return to me:
+    - The list of generated variants + what distinguishes each
+    - Recommended direction (based on CONTEXT.md)
+    - Preview command (how to open index.html)
+```
+
+## Step 5: Output
+
+```
+🎨 Sketch complete
+
+Variants:
+  variant-a-minimalist.html   (system font + whitespace)
+  variant-b-distinctive.html  (custom font + micro animations)
+  variant-c-dense.html        (information-dense — suited for admin)
+
+Decisions: .flow/specs/<name>/ui-sketch/decisions.md
+Comparison page: open .flow/specs/<name>/ui-sketch/index.html
+
+Next steps:
+- Pick a variant → tell me → I'll convert the HTML into production components
+- Or /curdx-flow:qa to verify interactions in the browser
+- Clone another reference → /curdx-flow:ui-research <feature>
+```
+
+## Error recovery
+
+- frontend-design skill not installed → Emma falls back and announces it
+- Variants are too similar → ask the user to re-run with more specific guidance
+- No spec and no description → at least one must be supplied

package/commands/spec.md

@@ -0,0 +1,135 @@
+---
+name: spec
+description: One-shot sequential run of research → requirements → design → tasks across all four stages
+argument-hint: "[spec-name] [--skip-research | --skip-requirements]"
+allowed-tools: [Read, Write, Bash, Task, AskUserQuestion]
+---
+
+# One-Shot Full Spec Generation
+
+Runs the 4 spec stages sequentially, prompting the user between stages to decide whether to continue. Suitable for generating a full spec in one go.
+
+## Step 1: Preflight + confirmation
+
+```bash
+[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project"; exit 1; }
+
+SPEC_NAME="$(echo "$ARGUMENTS" | awk '{print $1}')"
+[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+
+if [ -z "$SPEC_NAME" ]; then
+    echo "❌ No active spec. Run /curdx-flow:start <name> \"<goal>\" first"
+    exit 1
+fi
+```
+
+## Step 2: Parse skip options
+
+```bash
+SKIP_RESEARCH=0
+SKIP_REQUIREMENTS=0
+case "$ARGUMENTS" in
+    *--skip-research*)     SKIP_RESEARCH=1 ;;
+esac
+case "$ARGUMENTS" in
+    *--skip-requirements*) SKIP_REQUIREMENTS=1 ;;
+esac
+```
+
+## Step 3: Execute the 4 stages in sequence
+
+### Phase 1: Research
+
+```bash
+if [ "$SKIP_RESEARCH" = "1" ]; then
+    echo "⊘ Skipping research"
+elif [ -f ".flow/specs/$SPEC_NAME/research.md" ]; then
+    echo "ℹ research.md already exists; asking the user..."
+    # AskUserQuestion: re-run research? (skip / rerun / abort)
+else
+    echo "▶ Running research stage..."
+    # Via SlashCommand or directly dispatch the agent
+    # Recommended: directly invoke the /curdx-flow:research logic (inline or via the SlashCommand tool)
+fi
+```
+
+**Implementation 1** (recommended): Dispatch the agent directly, skipping SlashCommand:
+
+Call the Task tool with the same content as the Task call in `/curdx-flow:research` (reading flow-researcher.md).
+
+**Implementation 2**: If Claude Code supports the SlashCommand tool chain:
+```
+SlashCommand: /curdx-flow:research $SPEC_NAME
+```
+
+### Intermediate confirmation after each stage
+
+```
+✓ research stage complete
+
+Key findings:
+  - ...
+  - ...
+
+⚠ The following open questions were found; recommend answering first:
+  Q1: ...
+
+Choose:
+  [continue]    Continue to requirements (agent will answer open questions with reasonable assumptions)
+  [pause]       Pause — I'll review research.md myself, then manually run /curdx-flow:requirements
+  [abort]       Abort the entire /curdx-flow:spec
+```
+
+Use AskUserQuestion for the choice.
+
+### Phase 2: Requirements
+
+If continue, dispatch flow-product-designer (mirroring the Task call in `/curdx-flow:requirements`).
+
+Confirm again after completion.
+
+### Phase 3: Design
+
+If continue, dispatch flow-architect (mirroring the Task call in `/curdx-flow:design`).
+
+Confirm again after completion. **This step is especially important** because design freezes the technology choices — recommend that the user review the AD-NN entries before entering tasks.
+
+### Phase 4: Tasks
+
+If continue, dispatch flow-planner (mirroring the Task call in `/curdx-flow:tasks`).
+
+## Step 4: Final summary
+
+```
+═══════════════════════════════════════════════
+✓ Full spec generated: $SPEC_NAME
+
+Output files:
+  .flow/specs/$SPEC_NAME/research.md       (N lines)
+  .flow/specs/$SPEC_NAME/requirements.md   (M lines)
+  .flow/specs/$SPEC_NAME/design.md         (K lines)
+  .flow/specs/$SPEC_NAME/tasks.md          (L lines)
+
+Stats:
+  Research:     2-3 technical options, context7 queried X libraries
+  Requirements: P US, Q FR, R AC
+  Design:       S AD, T components
+  Tasks:        U tasks (fine / coarse)
+
+Next steps:
+  - Review all 4 files
+  - To modify, run /curdx-flow:research / /curdx-flow:requirements / ... individually
+  - After Phase 2 ships: /curdx-flow:implement
+```
+
+## Auto mode (/curdx-flow:spec --yolo)
+
+If the user passes `--yolo`, all intermediate confirmations default to `continue`, running through in one pass.
+
+**Warning**: yolo mode may run to completion but not necessarily match the user's intent. Recommend using it only on sketch / fast projects.
+
+## Error recovery
+
+- A stage fails → stop without advancing; after manual fixes the user can re-run /curdx-flow:<phase>
+- User chooses abort → preserve generated files, but do not advance phase_status
+- sequential-thinking / context7 requirements at every stage match the per-command definitions

package/commands/spike.md

@@ -0,0 +1,181 @@
+---
+name: spike
+description: feasibility experiment — validate an idea with 2-5 small tests, no production code. Output conclusions to STATE.md
+argument-hint: "\"<hypothesis to validate>\""
+allowed-tools: [Read, Write, Edit, Bash, WebSearch, Grep, Glob]
+---
+
+# Flow Spike — Feasibility Experiment
+
+@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+
+**A spike is a short-duration experiment**, aimed at answering one technical question: "Can this approach work?" It is not about delivering a feature.
+
+## Typical Scenarios
+
+- "Can Redis Streams replace Kafka?"
+- "How much faster is Bun than Node? Is our scenario a good fit?"
+- "Is this API's rate limit 10 qps?"
+- "Can the new TypeScript const generic solve problem X?"
+
+## Step 1: Clarify the Hypothesis
+
+```bash
+HYPOTHESIS="$ARGUMENTS"
+[ -z "$HYPOTHESIS" ] && { echo "Usage: /curdx-flow:spike \"<hypothesis>\""; exit 1; }
+```
+
+Confirm with the user:
+```
+Hypothesis to validate: <HYPOTHESIS>
+
+My understanding:
+  - What to validate: <...>
+  - Pass criteria: <...>
+  - What if it fails: <...>
+  - Time budget: recommend 30-60 minutes
+
+Continue? (yes / correct me)
+```
+
+Use AskUserQuestion (unless quickMode).
+
+## Step 2: Design 2-5 Small Tests
+
+**Rules**:
+- Each test is independent
+- Minimal code (50 lines max)
+- Explicit pass/fail criteria
+- Do not touch production code
+
+Example (validating Redis Streams performance):
+
+```
+Test 1: Throughput of writing 1000 messages
+  Code: spike/redis-streams-write.ts
+  Expected: >= 10K msg/sec
+  
+Test 2: Consumer group latency
+  Code: spike/redis-streams-consume.ts
+  Expected: P99 < 10ms
+  
+Test 3: Persistence overhead
+  Code: compare AOF vs RDB
+  Expected: AOF write latency increase < 20%
+```
+
+## Step 3: Create the spike directory
+
+```bash
+mkdir -p spike/$(date +%Y-%m-%d)-${HYPOTHESIS_SLUG}
+```
+
+All experimental code lives here. **Absolutely do not touch production code**.
+
+## Step 4: Run the Tests
+
+```bash
+for test in Test 1 2 3:
+    write code
+    run
+    record results
+    if blocked:
+      not "fix bug and continue", but record "blocker X, cannot test"
+```
+
+**context7 is mandatory**: look up all library APIs via context7, do not rely on memory.
+
+## Step 5: Record Results
+
+Create `spike/<date>-<slug>/RESULTS.md`:
+
+```markdown
+# Spike Results: <hypothesis>
+
+Date: YYYY-MM-DD
+Time: actually took N minutes
+
+## Test Matrix
+
+| Test | Expected | Actual | Conclusion |
+|------|-----|------|------|
+| 1 | >=10K msg/sec | 12K msg/sec | ✓ |
+| 2 | P99 < 10ms | P99 = 15ms | ✗ |
+| 3 | < 20% | 8% | ✓ |
+
+## Conclusion
+
+Hypothesis <HYPOTHESIS> is:
+  ☐ Fully correct — recommended for adoption
+  ☑ Partially correct — P99 latency exceeds expectations, needs deeper optimization
+  ☐ Fully incorrect — not recommended
+
+## Key Findings
+
+- <finding 1>
+- <finding 2>
+
+## Recommendation
+
+<how to handle this hypothesis if used in a real spec>
+
+## Open Questions
+
+<edges not yet tested>
+```
+
+## Step 6: Sync to STATE.md (if in a flow project)
+
+```bash
+if [ -f ".flow/STATE.md" ]; then
+    append to STATE.md:
+      ## Spike: <hypothesis> (YYYY-MM-DD)
+      Conclusion: partially correct
+      Details: spike/<date>-<slug>/RESULTS.md
+fi
+```
+
+This way, subsequent spec discussions can reference it.
+
+## Step 7: Cleanup Decision
+
+Ask the user:
+```
+Spike complete. Code is in spike/<date>-<slug>/
+Keep it?
+  [keep]   may reference later
+  [delete] conclusion recorded, code no longer valuable
+  [commit] commit into git as a historical reference
+```
+
+## Output
+
+```
+✓ Spike complete: <hypothesis>
+
+Conclusion:    partially correct (see RESULTS.md)
+Tests:         3 / 3 executed
+Actual time:   47 minutes
+
+Next step suggestions:
+  - Go deeper: /curdx-flow:start <name> "do <specific feature> based on spike results"
+  - Abandon:   recorded to STATE.md, do not adopt this direction
+
+Artifacts:
+  spike/<date>-<slug>/RESULTS.md
+  spike/<date>-<slug>/*.ts (test code)
+```
+
+## Forbidden
+
+- ✗ Mixing spike code into production code (src/)
+- ✗ Spikes exceeding 2 hours (that's not a spike, that's a mini project)
+- ✗ Claiming validation complete without recording results
+- ✗ Using a spike to replace the real spec workflow
+
+## spike vs research phase
+
+- **spike** is **actually running code** to validate a hypothesis
+- **research phase** is **reading docs / thinking** to determine direction
+
+Research thinks approach A is feasible but has concerns → use a spike to verify → write the conclusion back into the "feasibility" section of research.md.