Plan

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:

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:

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:

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:

## 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:

# 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.

# 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:

# 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.

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 orchestrator activity and sub-agent activity MUST be logged using ./scripts/log-activity.sh.

./scripts/log-activity.sh <LEVEL> <AGENT> <EVENT> "<MESSAGE>"

Parameters:

• LEVEL: INFO, WARN, ERROR
• AGENT: orchestrator, logic-architect, physical-architect, task-author, etc.
• EVENT: start, decision, tool, complete, spawn, spawn-complete, phase-transition, validation
• MESSAGE: Description of the activity

Skip Phases for /specify-Generated Specs

If the spec came from /specify workflow, it has already been reviewed AND capabilities have been extracted. Check for artifacts:

# Derive capability map path from spec path
SPEC_DIR=$(dirname "$SPEC_PATH")
SPEC_SLUG=$(basename "$SPEC_PATH" .md)
CAPABILITY_MAP="${SPEC_DIR}/${SPEC_SLUG}.capabilities.json"

if [ -f "$CAPABILITY_MAP" ]; then
    echo "Capability map found from /specify workflow: $CAPABILITY_MAP"
    echo "Copying artifacts and skipping to physical phase..."

    # Copy artifacts to .tasker/ directory
    cp "$CAPABILITY_MAP" "$TASKER_DIR/artifacts/capability-map.json"

    # Check for FSM artifacts from /specify workflow
    FSM_DIR="${SPEC_DIR}/../state-machines/${SPEC_SLUG}"
    if [ -d "$FSM_DIR" ]; then
        echo "FSM artifacts found from /specify workflow: $FSM_DIR"
        mkdir -p "$TASKER_DIR/artifacts/fsm"
        cp -r "$FSM_DIR"/* "$TASKER_DIR/artifacts/fsm/"
    fi

    # Skip spec_review AND logical phases - advance directly to physical
    tasker state set-phase physical
fi

Skip phases when /specify artifacts exist:

• spec_review - Skipped (already done by /specify Phase 7)
• logical - Skipped (capability map already exists from /specify Phase 3)

Plan Phase Dispatch

# Initialize if no state exists
if [ ! -f "$TASKER_DIR/state.json" ]; then
    tasker state init "$TARGET_DIR"
fi

# Check current phase
tasker state status

Plan Loop

while phase not in ["ready", "executing", "complete"]:
    1. Query current phase
    2. Spawn appropriate agent WITH FULL CONTEXT (see spawn templates below)
    3. Wait for agent to complete
    4. **VERIFY OUTPUT EXISTS** (critical - see below)
       - DO NOT log spawn-complete until file verified
       - DO NOT proceed to validation until file verified
    5. If file missing: RE-SPAWN agent immediately (see recovery below)
    6. Validate output:
       - For artifacts: tasker state validate <artifact>
       - For task validation: tasker state validate-tasks <verdict>
    7. If valid: tasker state advance
    8. If invalid: Tell agent to fix, re-validate

CRITICAL: Never log "spawn-complete: SUCCESS" until the output file is verified to exist!

Output Verification Before Validation

MANDATORY STEP: After each agent completes, you MUST verify its output file exists before attempting validation.

# After logic-architect completes:
if [ ! -f $TASKER_DIR/artifacts/capability-map.json ]; then
    echo "ERROR: capability-map.json not written. Agent must retry."
fi

# After physical-architect completes:
if [ ! -f $TASKER_DIR/artifacts/physical-map.json ]; then
    echo "ERROR: physical-map.json not written. Agent must retry."
fi

# After task-author completes:
task_count=$(ls $TASKER_DIR/tasks/*.json 2>/dev/null | wc -l)
if [ "$task_count" -eq 0 ]; then
    echo "ERROR: No task files written. Agent must retry."
fi

Recovery procedure: If file doesn't exist:

1. Check if directory exists: ls -la $TASKER_DIR/artifacts/
2. Re-spawn the agent with explicit reminder to use Write tool

Agent Spawn Templates

CRITICAL: Each sub-agent is context-isolated. They CANNOT see the orchestrator's conversation. You MUST pass ALL relevant context explicitly in the spawn prompt.

Physical Phase: physical-architect

Map behaviors to concrete file paths.

## Logging (MANDATORY)

./scripts/log-activity.sh INFO physical-architect start "Mapping behaviors to file paths"

## Context

TASKER_DIR: {absolute path to .tasker directory}
Target Directory: {TARGET_DIR}
Project Type: {new | existing}
Tech Stack: {from spec or inferred}

## Project Context (CRITICAL for existing projects)

{INSERT FULL PROJECT_CONTEXT HERE}

## Your Task

1. Read {TASKER_DIR}/artifacts/capability-map.json
2. **For existing projects:** Map behaviors to paths that FIT the existing structure
3. For new projects: Establish clean, conventional structure
4. **CRITICAL: Use the Write tool** to save to {TASKER_DIR}/artifacts/physical-map.json
5. **Verify file exists**: `ls -la {TASKER_DIR}/artifacts/physical-map.json`
6. Validate with: `cd {TASKER_DIR}/.. && tasker state validate physical_map`

Definition Phase: task-author

Create individual task files from the physical map.

## Logging (MANDATORY)

./scripts/log-activity.sh INFO task-author start "Creating task files"

## Context

TASKER_DIR: {absolute path to .tasker directory}
Target Directory: {TARGET_DIR}
Project Type: {new | existing}

## Project Context (for existing projects)

{INSERT FULL PROJECT_CONTEXT HERE}

## Your Task

1. Read {TASKER_DIR}/artifacts/physical-map.json
2. Read {TASKER_DIR}/artifacts/capability-map.json (for behavior details)
3. **Check for FSM artifacts**: If {TASKER_DIR}/artifacts/fsm/index.json exists, add FSM context to tasks
4. **CRITICAL: Use the Write tool** to save each task file to {TASKER_DIR}/tasks/T001.json, etc.
5. **Verify files exist**: `ls -la {TASKER_DIR}/tasks/`
6. Load tasks with: `cd {TASKER_DIR}/.. && tasker state load-tasks`

Validation Phase: task-plan-verifier

Verify task definitions for planning

## Logging (MANDATORY)

./scripts/log-activity.sh INFO task-plan-verifier start "Verifying task definitions"

## Context

TASKER_DIR: {absolute path to .tasker directory}
Spec: {TASKER_DIR}/inputs/spec.md
Capability Map: {TASKER_DIR}/artifacts/capability-map.json
Tasks Directory: {TASKER_DIR}/tasks/

## Required Command

Register verdict using: tasker state validate-tasks <VERDICT> "<summary>"

Sequencing Phase: plan-auditor

Assign phases to tasks and validate the dependency graph.

## Logging (MANDATORY)

./scripts/log-activity.sh INFO plan-auditor start "Assigning phases and validating DAG"

## Context

TASKER_DIR: {absolute path to .tasker directory}

## Your Task

1. Read {TASKER_DIR}/tasks/*.json
2. Read {TASKER_DIR}/artifacts/capability-map.json (for steel thread flows)
3. Build dependency graph
4. Assign phases (1: foundations, 2: steel thread, 3+: features)
5. **CRITICAL: Update task files** using Write tool
6. Validate DAG (no cycles, deps in earlier phases)
7. Run: cd {TASKER_DIR}/.. && tasker state load-tasks

Plan Completion

When phase reaches "ready":

## Planning Complete ✓

**Tasks:** 24
**Phases:** 4
**Steel Thread:** T001 → T003 → T007 → T012

Run `/execute` to begin implementation.

Archive Planning Artifacts (Automatic)

After planning completes, archive the artifacts:

tasker archive planning {project_name}

State Commands Reference

# General
tasker state status          # Current phase, task counts
tasker state advance         # Try to advance phase

# Planning
tasker state init <dir>      # Initialize new plan
tasker state validate <art>  # Validate artifact
tasker state validate-tasks <verdict> [summary]  # Register task validation result
tasker state load-tasks      # Reload from files

Error Recovery

If agent produces invalid output:

1. Validation fails (tasker state validate returns non-zero)
2. Report errors to agent
3. Agent fixes and re-outputs
4. Re-validate
5. Only advance on success