plan

What this skill does

# Plan Workflow

**CRITICAL: This is the PLAN skill. Do NOT call Skill(execute) or Skill(tasker:execute). Follow the instructions below directly.**

**IMPORTANT: All tasker working files go in `$TARGET_DIR/.tasker/`. Do NOT create any other directories like `project-planning/`, `planning/`, or `schemas/` at the target project root. The `.tasker/` directory is the ONLY location for tasker artifacts (including `.tasker/schemas/` for JSON schemas).**

Decompose a specification into an executable task DAG. This is Phase 2 of the tasker workflow:

```
/specify → /plan → /execute
```

## Input Requirements

- **Spec** from `/specify`: `{TARGET}/docs/specs/<slug>.md`
- **Capability Map**: `{TARGET}/docs/specs/<slug>.capabilities.json`
- **FSM Artifacts** (optional): `{TARGET}/docs/state-machines/<slug>/`

## Output

- **Task DAG**: `.tasker/tasks/T001.json`, `T002.json`, etc.
- **Physical Map**: `.tasker/artifacts/physical-map.json`
- **Validation Report**: `.tasker/reports/task-validation-report.md`

---

## MANDATORY FIRST STEP: Ask for Target Project Directory

**ALWAYS ask for target_dir FIRST before anything else.** No guessing, no inference from CWD.

### Step 1: Ask for Target Directory

Use AskUserQuestion to ask:
```
What is the target project directory?
```
Free-form text input. User must provide an absolute or relative path.

**Validation:**
```bash
TARGET_DIR="<user-provided-path>"
# Convert to absolute path
TARGET_DIR=$(cd "$TARGET_DIR" 2>/dev/null && pwd || echo "$TARGET_DIR")

if [ ! -d "$TARGET_DIR" ]; then
    # For new projects, check parent exists
    PARENT=$(dirname "$TARGET_DIR")
    if [ -d "$PARENT" ]; then
        echo "Directory will be created: $TARGET_DIR"
        mkdir -p "$TARGET_DIR"
    else
        echo "Error: Parent directory does not exist: $PARENT"
        # Re-ask for target_dir
    fi
fi
```

### Step 2: Check for Existing Session and Initialize

After target_dir is confirmed, check for existing `.tasker/` state:

```bash
TASKER_DIR="$TARGET_DIR/.tasker"
if [ -f "$TASKER_DIR/state.json" ]; then
    echo "Found existing tasker session at $TASKER_DIR"
    echo "Resuming from saved state..."
    # Read phase from state.json and resume
    tasker state status
else
    echo "No existing session. Initializing..."
    # Initialize directory structure
fi
```

### Step 3: Detect Specs (Automatic)

**Specs are REQUIRED for /plan to proceed.** Check `$TARGET_DIR/docs/specs/` for specs from /specify:

```bash
SPEC_DIR="$TARGET_DIR/docs/specs"

# Find spec files (from /specify workflow)
SPEC_FILES=$(find "$SPEC_DIR" -maxdepth 1 -name "*.md" 2>/dev/null)
CAP_MAPS=$(find "$SPEC_DIR" -maxdepth 1 -name "*.capabilities.json" 2>/dev/null)

if [ -n "$SPEC_FILES" ]; then
    echo "=== Specs found ==="
    echo "$SPEC_FILES"

    # Use the first spec (or only spec)
    SPEC_PATH=$(echo "$SPEC_FILES" | head -1)
    SPEC_SLUG=$(basename "$SPEC_PATH" .md)

    # Check for matching capability map
    CAP_MAP="$SPEC_DIR/${SPEC_SLUG}.capabilities.json"
    if [ -f "$CAP_MAP" ]; then
        echo "Capability map found: $CAP_MAP"
        echo "Can skip logic-architect phase"
    fi
else
    echo "No specs found in $SPEC_DIR"
    # BLOCK - see below
fi
```

### If spec found:

Proceed to Step 4. No user question needed.

### If NO spec found — BLOCK and offer /specify:

**/plan CANNOT proceed without specs.** Present this to the user:

```markdown
## Specs Required

Planning requires a specification to decompose into tasks. Without a spec, there's nothing to plan.

**Would you like to create a spec now using `/specify`?**

The `/specify` workflow will guide you through:
1. Defining goals and scope
2. Clarifying requirements through structured questions
3. Extracting capabilities and behaviors
4. Producing a spec ready for `/plan`
```

Ask using AskUserQuestion:
```
Would you like to run /specify to create a spec now?
```
Options:
- **Yes, start /specify** — Begin the specification workflow
- **No, I'll provide a spec later** — Exit /plan for now

### Step 4: Detect Project Type (Automatic)

**Do not ask the user** — infer project type from target directory:

```bash
# Check if target directory has source code
SOURCE_FILES=$(find "$TARGET_DIR" \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \
    -not -path "*node_modules*" -not -path "*__pycache__*" -not -path "*.venv*" -not -path "*/.git/*" 2>/dev/null | head -5)

if [ -n "$SOURCE_FILES" ]; then
    PROJECT_TYPE="existing"
    echo "Detected existing project with source files"
else
    PROJECT_TYPE="new"
    echo "New project (no existing source files)"
fi
```

- **Existing project** → Proceed to Step 5 (project analysis)
- **New project** → Skip to Step 6 (tech stack)

### Step 5: Existing Project Analysis (if PROJECT_TYPE=existing)

**If enhancing an existing project**, you MUST analyze the target directory **BEFORE proceeding to ingestion**. This analysis is CRITICAL - sub-agents cannot see the codebase, so you must extract and pass this context to them.

```bash
# Check directory exists
if [ ! -d "$TARGET_DIR" ]; then
    echo "Error: Target directory does not exist"
    exit 1
fi

# Analyze structure (capture output for context)
echo "=== Project Structure ==="
tree -L 3 -I 'node_modules|__pycache__|.git|venv|.venv|dist|build|.pytest_cache' "$TARGET_DIR" 2>/dev/null || \
    find "$TARGET_DIR" -maxdepth 3 -type f | head -50

# Identify key configuration files
echo "=== Key Configuration Files ==="
for f in package.json pyproject.toml Cargo.toml go.mod Makefile requirements.txt setup.py tsconfig.json; do
    [ -f "$TARGET_DIR/$f" ] && echo "Found: $f"
done

# Detect source layout patterns
echo "=== Source Layout ==="
for d in src lib app pkg cmd internal; do
    [ -d "$TARGET_DIR/$d" ] && echo "Found directory: $d/"
done

# Detect test layout
echo "=== Test Layout ==="
for d in tests test spec __tests__; do
    [ -d "$TARGET_DIR/$d" ] && echo "Found test directory: $d/"
done

# Sample existing code files to understand patterns
echo "=== Code Samples ==="
find "$TARGET_DIR" \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) \
    -not -path "*node_modules*" -not -path "*__pycache__*" -not -path "*.venv*" | head -10
```

**Read key files to understand patterns:**
```bash
# Read config files to understand dependencies and structure
[ -f "$TARGET_DIR/pyproject.toml" ] && cat "$TARGET_DIR/pyproject.toml"
[ -f "$TARGET_DIR/package.json" ] && cat "$TARGET_DIR/package.json"

# Sample a few source files to understand coding patterns
# (naming conventions, import style, architecture patterns)
```

### Step 6: Store Discovery Context

**CRITICAL:** You must retain this analysis for passing to sub-agents. Store it as a structured context block:

```
PROJECT_CONTEXT = """
Directory: {TARGET_DIR}
Project Type: existing
Stack: {detected stack}
Source Layout: {layout pattern}
Test Layout: {test pattern}

Key Patterns:
- {pattern 1}
- {pattern 2}
- {pattern 3}

Integration Requirements:
- {requirement 1}
- {requirement 2}
"""
```

This `PROJECT_CONTEXT` MUST be included in every sub-agent spawn prompt (logic-architect, physical-architect, task-author). Without it, sub-agents will design solutions that conflict with existing code.

---

## Directory Initialization

**CRITICAL:** After obtaining target_dir, initialize the `.tasker/` directory structure. Sub-agents assume directories already exist.

```bash
TASKER_DIR="$TARGET_DIR/.tasker"
mkdir -p "$TASKER_DIR"/{artifacts,inputs,tasks,reports,bundles,logs}
```

This creates:
- `$TARGET_DIR/.tasker/artifacts/` - For capability-map.json, physical-map.json
- `$TARGET_DIR/.tasker/inputs/` - For spec.md
- `$TARGET_DIR/.tasker/tasks/` - For T001.json, T002.json, etc.
- `$TARGET_DIR/.tasker/reports/` - For task-validation-report.md
- `$TARGET_DIR/.tasker/bundles/` - For execution bundles
- `$TARGET_DIR/.tasker/logs/` - For activity logging

---

## Runtime Logging (MANDATORY)

All or