/hybrid-worktree

description: "Start a new task in an isolated Git worktree with Hybrid Ralph PRD mode. Creates worktree, branch, loads existing PRD or auto-generates from description. Usage: /plan-cascade:hybrid-worktree [--flow <quick|standard|full>] [--tdd <off|on|auto>] [--confirm] [--no-confirm] [--spec <off|auto|on>] [--first-principles] [--max-questions N] [--agent <name>] <task-name> <target-branch> <prd-path-or-description> [design-doc-path]"

Hybrid Ralph + Worktree Mode (Fully Automated)

You are starting a task in **Git Worktree + Hybrid Ralph mode**. This will create the worktree and handle the PRD automatically.

Execution Flow Parameters

This command accepts flow control parameters that affect story execution:

Parameter Priority

Parameters are saved to `prd.json` in the worktree and later used by `/plan-cascade:approve`. Priority order:

1. **Command-line flags to THIS command** (highest priority)

• Example: `/plan-cascade:hybrid-worktree --flow full fix-auth main "Fix bug"`
• Saved to `<worktree>/prd.json` as `flow_config`, `tdd_config`, etc.

2. **Command-line flags to `/plan-cascade:approve`** (when run in worktree)

• Can override values saved in `prd.json`

3. **Default values** (lowest priority)

**Worktree Isolation:** Parameters are stored in the worktree's `prd.json`, ensuring complete isolation from other tasks. When you run `/plan-cascade:approve` in the worktree, it automatically finds and uses this PRD.

**Example:**

# Create worktree with strict flow
/plan-cascade:hybrid-worktree --flow full --tdd on fix-auth main "Fix authentication bug"
# → Creates worktree at .worktree/fix-auth/
# → Saves prd.json with flow_config.level="full", tdd_config.mode="on"

# Later, in the worktree directory:
cd .worktree/fix-auth/
/plan-cascade:approve
# → Uses flow="full", tdd="on" from prd.json in current worktree

`--flow <quick|standard|full>`

Override the execution flow depth for the approve phase.

| Flow | Gate Mode | AI Verification | Code Review | Test Enforcement | |------|-----------|-----------------|-------------|------------------| | `quick` | soft | disabled | no | no | | `standard` | soft | enabled | no | no | | `full` | **hard** | enabled | **required** | **required** |

`--tdd <off|on|auto>`

Control Test-Driven Development mode for story execution.

| Mode | Description | |------|-------------| | `off` | TDD disabled | | `on` | TDD enabled with prompts and compliance checks | | `auto` | Automatically decide based on risk assessment (default) |

`--confirm`

Require confirmation before each batch execution in the approve phase.

`--no-confirm`

Explicitly disable batch confirmation, even if FULL flow would normally require it. Useful for CI/automated environments.

**Precedence**: `--no-confirm` overrides `--confirm` and FULL flow's default confirmation requirement.

`--spec <off|auto|on>`

Enable a planning-time **spec interview** to produce `spec.json/spec.md` before finalizing `prd.json`.

• `auto` (default): enabled when `--flow full`, otherwise disabled
• `on`: always run interview before PRD finalization
• `off`: never run interview

`--first-principles`

Ask 3–5 first-principles questions before detailed spec questions (only when spec interview runs).

`--max-questions N`

Soft cap for interview length (recorded in `.state/spec-interview.json`).

Path Storage Modes

Plan Cascade supports two path storage modes for runtime files:

New Mode (Default)

Runtime files are stored in a user directory, keeping the project root clean:

• **Windows**: `%APPDATA%/plan-cascade/<project-id>/`
• **Unix/macOS**: `~/.plan-cascade/<project-id>/`

Where `<project-id>` is a unique identifier based on the project name and path hash (e.g., `my-project-a1b2c3d4`).

File locations in new mode:

• Worktrees: `<user-dir>/.worktree/<task-name>/`
• PRD: `<worktree>/.prd.json` or `<user-dir>/prd.json` for non-worktree
• State files: `<user-dir>/.state/`

Legacy Mode

All files stored in project root (backward compatible):

• Worktrees: `<project-root>/.worktree/<task-name>/`
• PRD: `<worktree>/prd.json`

**Note**: User-visible files like `findings.md`, `progress.txt`, and `mega-findings.md` always remain in the worktree/project root for easy access.

Tool Usage Policy (CRITICAL)

**To avoid command confirmation prompts:**

1. **Use Read tool for file reading** - NEVER use `cat` via Bash

• ✅ `Read("prd.json")`, `Read(".planning-config.json")`
• ❌ `Bash("cat prd.json")`

2. **Only use Bash for actual system commands:**

• Git operations: `git worktree add`, `git show-ref`
• OS detection: `uname -s`
• File writing when creating new files

3. **Use Write tool for creating structured files** - When possible

• ✅ `Write("prd.json", content)` for JSON files

Step 1: Parse Parameters

Parse user arguments:

• **Task name**: First positional arg (or `task-YYYY-MM-DD-HHMM`)
• **Target branch**: Second positional arg (or auto-detect `main`/`master`)
• **PRD path OR description**: Third positional arg
• If it's an existing file path → Load that PRD
• Otherwise → Use as task description to auto-generate PRD
• **Design doc path**: Fourth positional arg (optional)
• If provided → Convert external doc to design_doc.json format
• **--flow**: Execution flow depth (quick|standard|full)
• **--tdd**: TDD mode (off|on|auto)
• **--confirm**: Require batch confirmation
• **--no-confirm**: Disable batch confirmation (overrides --confirm and FULL flow default)
• **--spec**: Spec interview mode (off|auto|on)
• **--first-principles**: Enable first-principles questions (when spec interview runs)
• **--max-questions**: Soft cap for interview length
• **--agent**: Optional agent override for PRD generation

TASK_NAME=""
TARGET_BRANCH=""
PRD_ARG=""
DESIGN_ARG=""
PRD_AGENT=""
FLOW_LEVEL=""           # --flow <quick|standard|full>
TDD_MODE=""             # --tdd <off|on|auto>
CONFIRM_MODE=false      # --confirm
NO_CONFIRM_MO