@curdx/flow 1.1.4 → 1.1.6

package/commands/init.md

@@ -0,0 +1,105 @@
+---
+name: init
+description: Initialize the CurDX-Flow project structure (create the .flow/ directory and core files)
+argument-hint: "[--force]"
+allowed-tools: [Read, Write, Bash, AskUserQuestion]
+---
+
+# Initialize CurDX-Flow Project
+
+Create the `.flow/` directory structure in the current directory so CurDX-Flow can operate in this project.
+
+## Execution Steps
+
+### Step 1: Check Environment
+
+```bash
+# Confirm a reasonable project root
+pwd
+ls -la
+```
+
+- If the current directory is a dangerous location such as the home directory or a system directory, stop and ask the user to switch
+- If `.flow/` already exists:
+  - With `--force` → continue but warn about overwriting
+  - Without `--force` → stop and prompt the user to run `/curdx-flow:status` to inspect the existing state
+
+### Step 2: Create Directory Skeleton
+
+```bash
+mkdir -p .flow/specs
+mkdir -p .flow/_epics
+mkdir -p .flow/checkpoints
+mkdir -p .flow/threads
+mkdir -p .flow/seeds
+```
+
+### Step 3: Generate Core Files from Templates
+
+Read the files under `${CLAUDE_PLUGIN_ROOT}/templates/`, replace placeholders, and write to `.flow/`:
+
+| Source template | Target file | Description |
+|-----------------|-------------|-------------|
+| `templates/PROJECT.md.tmpl` | `.flow/PROJECT.md` | Project vision (user fills in later) |
+| `templates/CONTEXT.md.tmpl` | `.flow/CONTEXT.md` | User preferences |
+| `templates/STATE.md.tmpl` | `.flow/STATE.md` | Cross-session state (empty) |
+| `templates/ROADMAP.md.tmpl` | `.flow/ROADMAP.md` | Roadmap |
+| `templates/config.json.tmpl` | `.flow/config.json` | Configuration (default standard mode) |
+
+Placeholders:
+- `{{PROJECT_NAME}}` — inferred from the current directory name (user may be asked)
+- `{{CREATED_DATE}}` — `$(date +%Y-%m-%d)`
+- `{{USER_NAME}}` — from git config
+
+### Step 4: Update `.gitignore`
+
+Append (if not already present):
+
+```
+# CurDX-Flow runtime files
+.flow/checkpoints/
+.flow/threads/
+.flow/seeds/
+.flow/.active-spec
+.flow/specs/*/.state.json
+.flow/specs/*/.progress.md
+.flow/_epics/*/.epic-state.json
+```
+
+**Note**: the primary state files (PROJECT.md / CONTEXT.md / STATE.md / ROADMAP.md / config.json)
+**should be committed to version control** so team members share the same view.
+
+### Step 5: Health Check
+
+Run `/curdx-flow:doctor` (or inline its checks) to verify:
+- 3 MCPs started (context7 / sequential-thinking / chrome-devtools)
+- Recommended plugins status (pua / claude-mem / frontend-design)
+
+### Step 6: Prompt Next Steps
+
+Output:
+
+```
+✓ CurDX-Flow project initialized
+  .flow/
+  ├── PROJECT.md       ← fill in your project vision
+  ├── CONTEXT.md       ← fill in your preferences
+  ├── STATE.md
+  ├── ROADMAP.md
+  └── config.json (mode: standard)
+
+Next steps (in order):
+  1. Edit .flow/PROJECT.md to add the project goal
+  2. /curdx-flow:install-deps   — install recommended plugins (if not installed)
+  3. /curdx-flow:doctor         — verify health
+  4. /curdx-flow:status         — view project status
+  
+  Start development (after Phase 1 ships):
+  5. /curdx-flow:start <name> "<goal>"  — kick off the first spec
+```
+
+## Error Handling
+
+- Directory creation failure → report the specific error (permissions/disk/path issue)
+- Missing template file → check whether `${CLAUDE_PLUGIN_ROOT}/templates/` is complete
+- User interrupts with Ctrl+C → leave no partial state, prompt that re-running is safe

package/commands/install-deps.md

@@ -0,0 +1,128 @@
+---
+name: install-deps
+description: Interactively install CurDX-Flow's recommended plugin dependencies (pua / claude-mem / frontend-design)
+argument-hint: "[--all | --skip-prompt]"
+allowed-tools: [Bash, AskUserQuestion]
+---
+
+# One-Shot Install of Recommended Plugins
+
+CurDX-Flow auto-installs 3 MCPs via `plugin.json.mcpServers`:
+- ✓ context7 — docs lookup
+- ✓ sequential-thinking — structured thinking
+- ✓ chrome-devtools — browser QA
+
+This command interactively installs 3 recommended **plugins** (they are not MCPs and must be installed separately):
+
+| Plugin | Purpose | Official/Community |
+|--------|---------|--------------------|
+| **pua** (tanweai/pua) | Prevent AI from giving up; enforces the three red lines | Community |
+| **claude-mem** (thedotmack/claude-mem) | Automatic cross-session memory | Community |
+| **frontend-design** | UI design skill | Anthropic official |
+
+## Execution Steps
+
+### Step 1: Network Check
+
+```bash
+if ! ping -c 1 -W 2 github.com >/dev/null 2>&1; then
+  echo "⚠️ Network unreachable, cannot install plugins from the marketplace."
+  echo "CurDX-Flow will run in degraded mode (MCPs remain available)."
+  exit 0
+fi
+```
+
+### Step 2: Detect Current Installation Status
+
+```bash
+INSTALLED=$(claude plugin list 2>/dev/null || echo "")
+```
+
+Parse out which are installed and which are not.
+
+### Step 3: Ask the User
+
+If the `--all` argument is present, skip asking and install everything. Otherwise use AskUserQuestion:
+
+**Question**: Which recommended plugins to install?
+
+**Options** (list only those not installed):
+- **all** — Install all (recommended)
+- **recommended** — Install pua + claude-mem + frontend-design
+- **custom** — Pick manually (follow up with a multi-select question)
+- **skip** — Skip (the core MCPs are already enough)
+
+If the user picks `custom`, use a second AskUserQuestion to let them multi-select which to install.
+
+### Step 4: Run Installation
+
+Based on the selection (install only those not yet installed):
+
+#### pua
+
+```bash
+claude plugin marketplace add tanweai/pua
+claude plugin install pua@pua-skills --scope user
+```
+
+#### claude-mem
+
+```bash
+claude plugin marketplace add thedotmack/claude-mem
+claude plugin install claude-mem --scope user
+```
+
+#### frontend-design
+
+Anthropic's official plugin is typically in the default marketplace:
+
+```bash
+# If the default marketplace is enabled
+claude plugin install frontend-design --scope user
+```
+
+On failure, tell the user:
+> frontend-design must be installed from the official marketplace. Inside Claude Code run:
+> `/plugin`, then search for "frontend-design" in the Discover panel.
+
+### Step 5: Update Marker
+
+```bash
+DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
+mkdir -p "$DATA_DIR"
+echo "$(date +%Y-%m-%d)" > "$DATA_DIR/.deps-checked"
+```
+
+Prevents the SessionStart hook from continuing to remind.
+
+### Step 6: Verify and Report
+
+```bash
+claude plugin list 2>/dev/null | grep -E "pua|claude-mem|frontend-design"
+```
+
+Print the installation summary:
+
+```
+Install report:
+  ✓ pua             (v3.2.1)
+  ✓ claude-mem      (v12.3.0)
+  ⚠ frontend-design (requires manual install via /plugin)
+
+Next steps:
+  /curdx-flow:doctor      — full health check
+  /curdx-flow:init        — initialize project (if not yet initialized)
+```
+
+## Error Handling
+
+- `claude plugin marketplace add` failure → report the specific error (usually network/permissions)
+- `claude plugin install` failure → ask the user to run the command manually
+- User interruption → keep what is already installed, resume on the next run
+- Installed but needs updating → suggest `claude plugin update <name>`
+
+## Notes
+
+- This command only **installs**, it does not **configure**. See each plugin's own docs for configuration.
+- Installation is **global** (scope=user), shared across all projects.
+- Uninstall: `claude plugin uninstall <name>`

package/commands/party.md

@@ -0,0 +1,241 @@
+---
+name: party
+description: Party Mode — multiple persona agents independently think about one question at the same time. BMAD-style true multi-agent collaboration.
+argument-hint: "<persona-1> <persona-2> ... \"<question>\""
+allowed-tools: [Read, Task, AskUserQuestion]
+---
+
+# Flow Party — Multi-Agent Independent Thinking
+
+Have multiple **persona agents** (Mary/John/Winston, etc.) independently think about the same question at the same time. This is BMAD's true innovation: **not one LLM playing multiple roles, but multiple Task subprocesses each thinking on their own, avoiding opinion convergence**.
+
+## When to use
+
+- Hard decisions needing multiple perspectives (e.g., architecture selection)
+- Spec review (separately reviewed from product / arch / qa)
+- Brainstorming / divergent thinking
+- Finding blind spots (one perspective may see what others cannot)
+
+## When not to use
+
+- Simple questions (overhead is high)
+- Questions with a clear answer (agents will only echo)
+- Execution tasks (use a dedicated executor)
+
+## Step 1: Parse arguments
+
+```bash
+ARGS="$ARGUMENTS"
+
+# Recognize personas (known list)
+PERSONAS=()
+QUESTION=""
+
+# Simple parsing: persona names + a question wrapped in quotes at the end
+# Example: /curdx-flow:party mary john winston "JWT or session?"
+
+# Parsing logic: iterate words, add known persona names to PERSONAS, rest is the question
+KNOWN_PERSONAS="mary john winston amelia rachel oliver serena david emma"
+
+REMAINING=""
+for word in $ARGS; do
+    if echo "$KNOWN_PERSONAS" | grep -qw "$word"; then
+        PERSONAS+=("$word")
+    else
+        REMAINING="$REMAINING $word"
+    fi
+done
+
+# REMAINING is the question (possibly with quotes)
+QUESTION=$(echo "$REMAINING" | sed 's/^[[:space:]]*//;s/^["\x27]//;s/["\x27]$//')
+```
+
+## Step 2: Validate arguments
+
+```bash
+if [ ${#PERSONAS[@]} -lt 2 ]; then
+    echo "✗ Party Mode requires ≥ 2 personas"
+    echo "Available: mary john winston amelia rachel oliver serena david emma"
+    exit 1
+fi
+
+if [ ${#PERSONAS[@]} -gt 5 ]; then
+    echo "⚠ More than 5 personas will make output hard to read. Recommend ≤ 5"
+fi
+
+if [ -z "$QUESTION" ]; then
+    echo "✗ Please provide a question"
+    exit 1
+fi
+```
+
+## Step 3: Build shared context
+
+All personas read the same background:
+
+```bash
+CONTEXT_FILES=()
+[ -f "CLAUDE.md" ] && CONTEXT_FILES+=("CLAUDE.md")
+[ -f ".flow/PROJECT.md" ] && CONTEXT_FILES+=(".flow/PROJECT.md")
+[ -f ".flow/CONTEXT.md" ] && CONTEXT_FILES+=(".flow/CONTEXT.md")
+
+# If there is an active spec, append
+ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
+if [ -n "$ACTIVE" ]; then
+    for f in research.md requirements.md design.md; do
+        [ -f ".flow/specs/$ACTIVE/$f" ] && CONTEXT_FILES+=(".flow/specs/$ACTIVE/$f")
+    done
+fi
+```
+
+## Step 4: Dispatch each persona in parallel
+
+**Key**: call multiple Task tools **in a single message** at the same time (parallel execution).
+This way each persona thinks in an independent context without influencing the others.
+
+```
+# Parallel invocation (in a single message):
+Task(mary):
+  subagent_type: general-purpose
+  description: "Mary thinking about $QUESTION"
+  prompt: |
+    You are Mary (Senior Analyst). Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/persona-mary.md
+    
+    Shared context:
+    $(cat ${CONTEXT_FILES[@]} 2>/dev/null)
+    
+    Question: $QUESTION
+    
+    Answer from Mary's perspective:
+    - First list explicit assumptions
+    - Give 2-3 interpretations from a research / analysis perspective
+    - Clearly state open questions
+    - Provide an initial recommendation (if any)
+    
+    **Forbidden**:
+    - Speaking on behalf of other personas
+    - Claiming "synthesizing John's and Winston's opinions" (you don't know what they said)
+    - Echoing / converging
+    
+    Output a concise view of <200 words.
+
+Task(john):
+  ... [john's prompt]
+
+Task(winston):
+  ... [winston's prompt]
+```
+
+**Parallel execution**: Claude Code's Task tool supports multiple invocations in a single message running in parallel.
+
+## Step 5: Collect results
+
+Each Task returns an independent answer. The main agent (you) aggregates:
+
+```markdown
+## Party Mode Results: <QUESTION>
+
+### Mary (Senior Analyst)
+<Mary's answer>
+
+### John (Product Manager)
+<John's answer>
+
+### Winston (Architect)
+<Winston's answer>
+
+## Perspective comparison
+
+| Dimension | Mary | John | Winston |
+|-----------|------|------|---------|
+| Main concern | ... | ... | ... |
+| Recommended direction | ... | ... | ... |
+| Open questions | ... | ... | ... |
+
+## Points of disagreement
+
+1. Mary and Winston disagree on X: <specifics>
+2. Y raised by John that neither of the others considered: <specifics>
+
+## Consensus
+
+1. Everyone agrees on Z
+
+## Recommendation
+
+Based on multi-perspective synthesis:
+- If you care about A → follow Mary
+- If you care about B → follow Winston
+- Middle-ground option: Y proposed by John
+```
+
+## Step 6: Let the user decide
+
+```
+AskUserQuestion:
+  question: "Having seen the multi-perspective analysis, which direction do you lean toward?"
+  options:
+    - Follow Mary's direction
+    - Follow John's direction
+    - Follow Winston's direction
+    - Synthesis: <specific compromise>
+    - Other (user input)
+```
+
+After the user chooses, write the decision to STATE.md (as D-NN, via /curdx-flow:discuss or manually).
+
+## Typical usage
+
+### Architecture selection
+
+```
+/curdx-flow:party winston mary "JWT vs Session — which is more suitable in this project"
+```
+
+### Spec review
+
+```
+/curdx-flow:party john rachel oliver "are the ACs in requirements.md sufficient"
+```
+
+### Bug approach discussion
+
+```
+/curdx-flow:party david winston "should this crash be fixed at the root cause or wrapped in try-catch"
+```
+
+### UX decision
+
+```
+/curdx-flow:party emma john oliver "how to present login failure error messages"
+```
+
+## Forbidden
+
+- ✗ Dispatching only 1 agent (that's not a Party — just use Task directly)
+- ✗ Agents referencing each other (the point of independent thinking is isolation)
+- ✗ Sequential dispatch (must be parallel Task invocations)
+- ✗ Overly long agent output (each <300 words)
+
+## Why Party Mode has value
+
+### Single LLM playing multiple roles vs. true multi-agent
+
+Single LLM: "As Mary I think X... As Winston I think Y... Synthesizing the two views, Z"
+
+Problems:
+- Opinions have already converged in advance (the LLM generates in one pass; later parts are influenced by earlier ones)
+- "Synthesis" is done by the LLM itself, without real collision
+- Easily becomes "one voice imitating multiple people"
+
+True multi-agent (Party Mode):
+- Mary's context contains only "I am Mary" and the question
+- Winston's context contains only "I am Winston" and the question
+- The two have no idea what the other said
+- The output is truly independent thinking
+- The differences are real differences, not acted out
+
+---
+
+_Source: BMAD's Party Mode, implemented in CurDX-Flow via parallel dispatch of Claude Code's Task tool._

package/commands/plan-ceo.md

@@ -0,0 +1,117 @@
+---
+name: plan-ceo
+description: CEO-level planning review — strategic / scope / ROI / opportunity cost. A business-layer review of design.md.
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Flow Plan CEO — Strategic-Layer Review
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md
+
+Review design.md from the **CEO perspective**: is this worth doing? Is the scope right?
+
+## Step 1: Preflight
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec"; exit 1; }
+
+DIR=".flow/specs/$SPEC_NAME"
+[ ! -f "$DIR/design.md" ] && { echo "✗ Missing design.md. Run /curdx-flow:design first"; exit 1; }
+```
+
+## Step 2: Dispatch CEO-perspective review
+
+Reuse the `flow-architect` agent but switch the perspective:
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "CEO Review: $SPEC_NAME"
+  prompt: |
+    **CEO Review Mode**
+    
+    You are not an architect, not a developer. You are a reviewer from the CEO / PM perspective.
+    
+    Full methodology: ${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md (Review 1)
+    
+    Review targets:
+    - .flow/specs/$SPEC_NAME/requirements.md (business goals)
+    - .flow/specs/$SPEC_NAME/design.md (technical solution)
+    - .flow/PROJECT.md (project vision)
+    - .flow/ROADMAP.md (roadmap)
+    
+    Review checklist (answer each):
+    
+    1. Scope appropriateness
+       - Solution scope vs. business value vs. timeline
+       - Over-engineered? (doing more than currently necessary)
+       - Insufficient? (users still unsatisfied after completion)
+    
+    2. Timeline reasonableness
+       - Refer to the priorities in ROADMAP.md
+       - Is the urgency reasonable relative to other work in progress / pending?
+    
+    3. Quantifiable ROI
+       - User value: N users benefit / N scenarios unlocked
+       - Business value: revenue / retention / brand
+       - Engineering cost: estimated person-days
+    
+    4. Opportunity cost
+       - What does doing this mean we won't do?
+       - Is what's being deferred more important?
+    
+    5. Strategic alignment
+       - Does it support company OKRs / quarterly goals
+       - Does it lock in future choices (is this risky)
+    
+    6. Stakeholders
+       - Who benefits? How many?
+       - Who is affected (possibly negatively)?
+    
+    Use sequential-thinking ≥ 5 rounds for derivation.
+    
+    Output:
+    .flow/specs/$SPEC_NAME/plan-review-ceo.md
+    
+    Format:
+    # CEO Plan Review: $SPEC_NAME
+    
+    ## Verdict
+    - APPROVED / APPROVED_WITH_CONCERNS / NEEDS_REVISION / REJECTED
+    
+    ## Findings
+    
+    ### [Scope] Scope analysis
+    ...
+    
+    ### [Timeline] Timeline analysis
+    ...
+    
+    ### [ROI] Business value
+    ...
+    
+    ## Recommendations
+    - Concrete change recommendations (not abstract "increase value")
+    
+    Return a briefing to me.
+```
+
+## Step 3: Output
+
+```
+✓ CEO Review complete
+
+Verdict: <APPROVED / APPROVED_WITH_CONCERNS / NEEDS_REVISION>
+
+Key concerns:
+  - <concern 1>
+  - <concern 2>
+
+Report: .flow/specs/$SPEC_NAME/plan-review-ceo.md
+
+Next steps:
+- If NEEDS_REVISION → /curdx-flow:design to fix + rerun
+- If APPROVED → /curdx-flow:plan-eng (engineering layer) or /curdx-flow:tasks
+```

package/commands/plan-design.md

@@ -0,0 +1,107 @@
+---
+name: plan-design
+description: Design planning review — UI/UX, design system, accessibility review. Dispatches flow-ux-designer (Emma).
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Flow Plan Design — Design-Layer Review
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md
+
+Review design.md and existing sketches (if any) from the **UX perspective**: can users use it? Is the visuals consistent?
+
+## Step 1: Preflight
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec"; exit 1; }
+
+# If no UI-related content (pure backend spec) → skip
+DIR=".flow/specs/$SPEC_NAME"
+if ! grep -qE "(UI|UX|interface|user interface|frontend)" "$DIR"/*.md 2>/dev/null; then
+    echo "ℹ This spec does not involve UI; skipping Design Review"
+    exit 0
+fi
+```
+
+## Step 2: Dispatch Emma (Design Review mode)
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Design Review: $SPEC_NAME"
+  prompt: |
+    **Design Review Mode** (you are Emma, flow-ux-designer)
+    
+    Your full definition: ${CLAUDE_PLUGIN_ROOT}/agents/flow-ux-designer.md
+    Review methodology: ${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md (Review 3)
+    
+    Review targets:
+    - .flow/specs/$SPEC_NAME/design.md (UI-related sections)
+    - .flow/specs/$SPEC_NAME/ui-sketch/ (if /curdx-flow:sketch has been run)
+    - .flow/CONTEXT.md (user preferences)
+    - Existing UI patterns in the project (.flow/codebase-index.md, if present)
+    
+    Review checklist:
+    
+    1. User flow
+       - Main scenario ≤ 3 steps?
+       - Multiple entry points?
+       - Keyboard flow?
+    
+    2. Error states
+       - Are failure messages user-friendly?
+       - Does the user know how to recover?
+    
+    3. Loading states
+       - Visual feedback for long-running operations?
+       - Skeleton / spinner?
+    
+    4. Empty states
+       - Guidance when no data (CTA / illustration)?
+       - Not a blank page
+    
+    5. Accessibility
+       - Color contrast WCAG AA+?
+       - Fully keyboard operable?
+       - Semantic HTML + ARIA?
+       - Screen-reader friendly?
+    
+    6. Design system consistency
+       - Using project tokens (colors / fonts / spacing)?
+       - Using existing components, not reinventing?
+       - New components within the theme?
+    
+    7. Mobile adaptation
+       - Usable at narrowest viewport (375px)?
+       - Touch targets ≥ 44pt?
+       - Both portrait and landscape unbroken?
+    
+    8. Internationalization
+       - Copy replaceable?
+       - RTL compatible?
+       - Space adapts to different lengths (e.g., German is ~30% longer than English)?
+    
+    Output: .flow/specs/$SPEC_NAME/plan-review-design.md
+    
+    Return a briefing.
+```
+
+## Step 3: Output
+
+```
+🎨 Design Review complete
+
+Verdict: <APPROVED / NEEDS_REVISION>
+
+Key findings:
+  - <top 3>
+
+Report: .flow/specs/$SPEC_NAME/plan-review-design.md
+
+Next steps:
+- UI/UX issues → /curdx-flow:sketch to iterate again
+- Or /curdx-flow:design to update UI-related sections
+- Pass → /curdx-flow:plan-dx or /curdx-flow:tasks
+```