# Orchestrator

> Thin orchestrator for Task Decomposition Protocol v2. Supports two modes - /plan (decompose spec into tasks) and /execute (run tasks via subagents). Delegates all state management to the tasker CLI.

- Skill: `majiayu000/orchestrator-5` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/orchestrator-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/orchestrator-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/orchestrator-5

---


# Orchestrator v2

A **thin coordination layer** with two distinct modes:
- **Plan Mode** (`/plan`) - Decompose spec into task DAG
- **Execute Mode** (`/execute`) - Run tasks via isolated subagents

## Workflow Integration

The full workflow from requirements to implementation:

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

| Skill | Purpose | Input | Output |
|-------|---------|-------|--------|
| `/specify` | Design vision & capabilities | User requirements | `{TARGET}/docs/specs/<slug>.md` + `.capabilities.json` + ADRs |
| `/plan` | DAG construction (files → tasks) | Spec + capability map | Task DAG in `.tasker/tasks/` |
| `/execute` | Implementation | Task DAG | Working code |

**Entry points:**
- **From scratch** → Run `/specify` first to develop spec and extract capabilities
- **Existing spec** → Run `/plan {TARGET}/docs/specs/<slug>.md` directly (may need capability extraction)
- **From /specify** → Run `/plan {TARGET}/docs/specs/<slug>.md` (skips to physical mapping)

## Philosophy

The orchestrator does NOT:
- Track state itself (tasker CLI does this)
- Validate artifacts (tasker CLI does this)
- Compute ready tasks (tasker CLI does this)

The orchestrator ONLY:
- Queries state via `tasker state`
- Dispatches agents based on mode/phase
- Handles user interaction
- **Ensures commits happen** via `.claude/hooks/post-task-commit.sh` (defense in depth)

---

## Directory Initialization (After target_dir is known)

**CRITICAL:** After obtaining target_dir from the user, the orchestrator MUST initialize the `.tasker/` directory structure. This is the ONLY place where directories are created - sub-agents assume directories already exist.

### Setup (Run after target_dir is confirmed)

Initialize the `.tasker/` directory structure:

```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

Set TASKER_DIR as the working directory for all operations:
```bash
TASKER_DIR="$TARGET_DIR/.tasker"
echo "TASKER_DIR: $TASKER_DIR"
```

**Why centralized initialization?**
1. **Reliability**: Sub-agents run in isolated contexts and directory creation has been unreliable
2. **Single responsibility**: Orchestrator owns the directory structure, sub-agents own the content
3. **Fail-fast**: If directory creation fails, we catch it immediately rather than mid-workflow

**IMPORTANT:** Sub-agents must NOT create directories. They assume the directory structure already exists. If a sub-agent encounters a "directory does not exist" error, it indicates the orchestrator failed to initialize properly.

## Runtime Logging (MANDATORY)

All orchestrator activity and sub-agent activity MUST be logged using `./scripts/log-activity.sh`.

### Logging Script Usage

```bash
./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

### Orchestrator Logging Examples

```bash
./scripts/log-activity.sh INFO orchestrator phase-transition "moving from logical to physical"
./scripts/log-activity.sh INFO orchestrator spawn "launching logic-architect for capability extraction"
./scripts/log-activity.sh INFO orchestrator spawn-complete "logic-architect finished with SUCCESS"
./scripts/log-activity.sh INFO orchestrator validation "capability_map - PASSED"
```

### Sub-Agent Logging Instructions

**CRITICAL:** Include these logging instructions in EVERY sub-agent spawn prompt. Sub-agents are context-isolated and will not see this skill file - they must receive logging instructions explicitly.

Add this block to every spawn prompt:

```
## Logging (MANDATORY)

Log your activity using the logging script:

\`\`\`bash
./scripts/log-activity.sh INFO $AGENT_NAME start "Starting task description"
./scripts/log-activity.sh INFO $AGENT_NAME decision "What decision and why"
./scripts/log-activity.sh INFO $AGENT_NAME complete "Outcome description"
./scripts/log-activity.sh WARN $AGENT_NAME warning "Warning message"
./scripts/log-activity.sh ERROR $AGENT_NAME error "Error message"
\`\`\`

Replace $AGENT_NAME with your agent name (e.g., logic-architect, task-executor).
```

## CRITICAL: Path Management

**TASKER_DIR must be an absolute path.** Sub-agents run in isolated contexts and cannot resolve relative paths correctly.

After obtaining target_dir from user, compute and store:
```bash
# Get absolute path to .tasker directory within target project
TARGET_DIR="<user-provided-absolute-path>"
TASKER_DIR="$TARGET_DIR/.tasker"
echo "TASKER_DIR: $TASKER_DIR"
```

This `TASKER_DIR` value (e.g., `/Users/foo/my-project/.tasker`) MUST be passed to every sub-agent spawn. Do NOT use relative paths like `.tasker/` in spawn prompts.

**NOTE:** Throughout this document, `TASKER_DIR` replaces the old `PLANNING_DIR` variable. They serve the same purpose.

---

# Plan Mode

Triggered by `/plan`. Runs phases 0-6 (spec review through ready).

## 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 (see Directory Initialization below)
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

**If user chooses "Yes, start /specify":**
1. Invoke the `tasker:specify` skill with the already-collected `target_dir`
2. Pass context: `TARGET_DIR` is already known, skip Step 1 of /specify
3. After /specify completes, automatically return to /plan

**If user chooses "No":**
Exit gracefully with message: "Run `/plan` again when you have a spec ready, or use `/specify` to create one."

### 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)
```

**Present findings and store context:**
```markdown
## Existing Project Analysis

**Directory:** /path/to/project
**Stack Detected:** Python 3.11+ (pyproject.toml with uv)
**Source Layout:** src/ with module structure
**Test Layout:** tests/ mirroring src/

**Key Configuration:**
- pyproject.toml: dependencies include fastapi, pydantic, loguru
- Uses ruff for linting, pytest for testing

**Discovered Patterns:**
- Naming: snake_case for files and functions
- Imports: absolute imports from src root
- Architecture: Protocol-based interfaces in src/interfaces/
- Testing: pytest with fixtures in conftest.py

**Key Files:**
- src/main.py (entry point)
- src/interfaces/ (Protocol definitions)
- src/services/ (business logic)
- tests/conftest.py (shared fixtures)

**Integration Considerations:**
- New code must follow existing module structure
- Must use existing Protocols for interfaces
- Tests should extend existing fixtures
- Must pass ruff and existing test suite

Proceed with planning? (y/n)
```

**Tech stack comes from the spec.** A well-developed spec (from /specify) includes tech stack requirements. Do not ask for tech stack separately — read it from the spec.

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

## Ingestion: Storing the Spec

First, check if the spec already exists (directory was created during initialization):

```bash
if [ -f "$TASKER_DIR/inputs/spec.md" ]; then
    echo "Spec found, proceeding to planning..."
fi
```

**If spec already exists:** Skip ingestion, proceed to logical phase.

**If spec doesn't exist**, ask user for specification, then:

- **User provides a file path** → `cp /path/to/spec "$TASKER_DIR/inputs/spec.md"`
- **User pastes content** → Write it to `$TASKER_DIR/inputs/spec.md`

**Important:** Store the spec exactly as provided - no transformation, summarization, or normalization.

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

```bash
# Derive capability map path from spec path
# e.g., /path/to/project/docs/specs/my-feature.md → /path/to/project/docs/specs/my-feature.capabilities.json
SPEC_DIR=$(dirname "$SPEC_PATH")
SPEC_SLUG=$(basename "$SPEC_PATH" .md)
CAPABILITY_MAP="${SPEC_DIR}/${SPEC_SLUG}.capabilities.json"

# Check for /specify artifacts (spec review may be in tasker's .claude/)
SPEC_REVIEW=".claude/spec-review.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 planning directory
    cp "$CAPABILITY_MAP" "$TASKER_DIR/artifacts/capability-map.json"
    [ -f "$SPEC_REVIEW" ] && cp "$SPEC_REVIEW" "$TASKER_DIR/artifacts/spec-review.json"

    # Check for FSM artifacts from /specify workflow
    FSM_DIR="${SPEC_DIR}/../fsm/${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/"

        # Validate FSM artifacts
        tasker fsm validate validate "$TASKER_DIR/artifacts/fsm"
        if [ $? -ne 0 ]; then
            echo "WARNING: FSM validation failed. Review artifacts before proceeding."
        fi
    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

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

# Check current phase
tasker state status
```

| Phase | Agent | Output | Validation | Skip if |
|-------|-------|--------|------------|---------|
| `ingestion` | (none) | `inputs/spec.md` (verbatim) | File exists | — |
| `spec_review` | **spec-reviewer** | `artifacts/spec-review.json` | All critical resolved | `/specify` artifacts exist |
| `logical` | **logic-architect** | `artifacts/capability-map.json` | `validate capability_map` | `/specify` artifacts exist |
| `physical` | **physical-architect** | `artifacts/physical-map.json` | `validate physical_map` | — |
| `definition` | **task-author** | `tasks/*.json` | `load-tasks` | — |
| `validation` | **task-plan-verifier** | Validation report | `validate-tasks <verdict>` | — |
| `sequencing` | **plan-auditor** | Updated task phases | DAG is valid | — |
| `ready` | (done) | Planning complete | — | — |

**Entry points based on artifacts:**
- **No artifacts** → Start at `ingestion` (raw spec provided)
- **Has `.capabilities.json`** → Start at `physical` (came from `/specify`)

**Note:** When starting at `physical`, the capability-map.json is copied from `{TARGET}/docs/specs/<slug>.capabilities.json` to `artifacts/capability-map.json`.

## Plan Loop

```python
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: state.py validate <artifact>
       - For task validation: state.py validate-tasks <verdict>
    7. If valid: state.py advance
    8. If invalid: Tell agent to fix, re-validate
```

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

## CRITICAL: Output Verification Before Validation

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

Note: `$TASKER_DIR` below refers to the absolute path you passed to the agent (e.g., `/Users/foo/my-project/.tasker`).

```bash
# After logic-architect completes:
if [ ! -f $TASKER_DIR/artifacts/capability-map.json ]; then
    echo "ERROR: capability-map.json not written. Agent must retry."
    # Re-spawn the agent with explicit reminder to use Write tool
fi

# After physical-architect completes:
if [ ! -f $TASKER_DIR/artifacts/physical-map.json ]; then
    echo "ERROR: physical-map.json not written. Agent must retry."
    # Re-spawn the agent with explicit reminder to use Write tool
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."
    # Re-spawn the agent with explicit reminder to use Write tool
fi
```

**Why this matters:** Sub-agents may fail silently (e.g., output JSON to conversation instead of writing to file, or write to wrong directory). The orchestrator MUST verify files exist at the correct absolute path before calling `state.py validate`, otherwise validation will fail with "Artifact not found" which is confusing.

**Recovery procedure:** If file doesn't exist:
1. Check if directory exists: `ls -la $TASKER_DIR/artifacts/`
2. Re-spawn the agent with this explicit reminder:
   > "IMPORTANT: You must use the Write tool to save the file to the absolute path {TASKER_DIR}/artifacts/. Simply outputting JSON to the conversation is NOT sufficient. Do NOT use relative paths like .tasker/."

## Agent Spawn Templates

**CRITICAL:** Each sub-agent is context-isolated. They CANNOT see the orchestrator's conversation or any information you've gathered from the user. You MUST pass ALL relevant context explicitly in the spawn prompt.

**MANDATORY:** For existing projects, you MUST include the full PROJECT_CONTEXT from the discovery phase. Sub-agents have no visibility into the target codebase - they rely entirely on the context you provide.

### Spec Review Phase: spec-reviewer

**Spawn prompt for spec-reviewer:**

```
Analyze the specification for weaknesses before capability extraction.

## Logging (MANDATORY)

Log your activity using the logging script:

./scripts/log-activity.sh INFO spec-reviewer start "Analyzing spec for weaknesses"
./scripts/log-activity.sh INFO spec-reviewer decision "What decision and why"
./scripts/log-activity.sh INFO spec-reviewer complete "Outcome description"

## Context

TASKER_DIR: {absolute path to .tasker directory, e.g., /Users/foo/my-project/.tasker}

## Your Task

1. Run weakness detection:
   tasker spec review analyze {TASKER_DIR}/inputs/spec.md

2. Save results to {TASKER_DIR}/artifacts/spec-review.json

3. For CRITICAL weaknesses (W1: Non-behavioral, W6: Contradictions):
   - Use AskUserQuestion tool to engage user for resolution
   - Record resolutions to {TASKER_DIR}/artifacts/spec-resolutions.json

4. Check status:
   tasker spec review status {TASKER_DIR}

CRITICAL WEAKNESS CATEGORIES:
- W1: Non-behavioral (DDL/schema not stated as behavior) - Ask: "Should DDL be DB-level or app-layer?"
- W6: Contradictions (conflicting statements) - Ask: "Which statement is authoritative?"

WARNING CATEGORIES (proceed with notes):
- W2: Implicit requirements
- W3: Cross-cutting concerns
- W5: Fragmented requirements

INFO CATEGORIES (log only):
- W4: Missing acceptance criteria

IMPORTANT:
- You MUST resolve all CRITICAL weaknesses before signaling completion
- Use AskUserQuestion for each critical weakness requiring user input
- Save resolutions in spec-resolutions.json for the logic-architect to consume

**Note:** The orchestrator has already created all required directories. Do NOT create directories yourself.
```

### Logical Phase: logic-architect

**Spawn prompt for logic-architect:**

```
Extract capabilities and behaviors from the specification.

## Logging (MANDATORY)

Log your activity using the logging script:

./scripts/log-activity.sh INFO logic-architect start "Extracting capabilities from spec"
./scripts/log-activity.sh INFO logic-architect decision "What decision and why"
./scripts/log-activity.sh INFO logic-architect complete "Outcome description"

## Context

TASKER_DIR: {absolute path to .tasker directory, e.g., /Users/foo/my-project/.tasker}
Target Directory: {TARGET_DIR}
Project Type: {new | existing}
Tech Stack: {user-provided constraints or "none specified"}

## Project Context (CRITICAL for existing projects)

{INSERT FULL PROJECT_CONTEXT HERE - this is MANDATORY for existing projects}

Example for existing project:
"""
Directory: /Users/foo/my-app
Project Type: existing
Stack: Python 3.11+ with FastAPI, managed by uv
Source Layout: src/ with module packages
Test Layout: tests/ mirroring src structure

Key Patterns:
- Naming: snake_case for files and functions
- Imports: absolute imports from src root
- Architecture: Protocol-based interfaces in src/interfaces/
- Error handling: Custom exceptions in src/exceptions.py
- Logging: loguru with structured logging

Integration Requirements:
- New capabilities must define Protocols in src/interfaces/
- Implementations go in src/services/ or src/domain/
- Must not duplicate existing functionality
- Must integrate with existing error handling patterns
"""

For new projects, state: "New project - no existing patterns to follow"

## Specification Location

The full specification is in: {TASKER_DIR}/inputs/spec.md

Read that file for the complete requirements. The spec has already been stored verbatim.

## Your Task

1. Read {TASKER_DIR}/inputs/spec.md
2. Read {TASKER_DIR}/artifacts/spec-resolutions.json if it exists
   - Resolutions marked "mandatory" MUST become explicit behaviors
   - Non-behavioral requirements (W1) should be tagged for explicit tasks
   - Cross-cutting concerns (W3) should be flagged for dedicated capabilities
3. **For existing projects:** Consider how new capabilities integrate with existing structure
4. Extract capabilities using I.P.S.O. decomposition
5. Apply phase filtering (Phase 1 only)
6. **CRITICAL: Use the Write tool** to save to {TASKER_DIR}/artifacts/capability-map.json
7. **Verify file exists**: `ls -la {TASKER_DIR}/artifacts/capability-map.json`
8. Validate with: `cd {TASKER_DIR}/.. && tasker state validate capability_map`

IMPORTANT - YOUR TASK IS NOT COMPLETE UNTIL:
1. You MUST use the Write tool to save the file. Simply outputting JSON to the conversation is NOT sufficient.
2. Use the TASKER_DIR absolute path provided above. Do NOT use relative paths.
3. After Write, you MUST verify: `ls -la {TASKER_DIR}/artifacts/capability-map.json` - if file doesn't exist, Write again!
4. You MUST run validation and confirm it passes.
5. For existing projects, ensure capabilities don't duplicate what already exists in the codebase.

**Note:** The orchestrator has already created all required directories. Do NOT create directories yourself. If you encounter "directory does not exist" errors, report this to the orchestrator.

If you complete without the file existing at the absolute path, you have FAILED.
```

### Physical Phase: physical-architect

**Spawn prompt for physical-architect:**

```
Map behaviors to concrete file paths.

## Logging (MANDATORY)

Log your activity using the logging script:

./scripts/log-activity.sh INFO physical-architect start "Mapping behaviors to file paths"
./scripts/log-activity.sh INFO physical-architect decision "What decision and why"
./scripts/log-activity.sh INFO physical-architect complete "Outcome description"

## Context

TASKER_DIR: {absolute path to .tasker directory, e.g., /Users/foo/my-project/.tasker}
Target Directory: {TARGET_DIR}
Project Type: {new | existing}
Tech Stack: {user-provided constraints or "infer from capability-map"}

## Project Context (CRITICAL for existing projects)

{INSERT FULL PROJECT_CONTEXT HERE - this is MANDATORY for existing projects}

This context tells you:
- Where source files should go (e.g., src/services/, src/domain/)
- Where tests should go (e.g., tests/ mirroring src/)
- Naming conventions to follow
- Existing patterns to integrate with
- Files/modules that already exist (don't recreate them)

For new projects, state: "New project - establish sensible conventions"

## Your Task

1. Read {TASKER_DIR}/artifacts/capability-map.json
2. **For existing projects:** Map behaviors to paths that FIT the existing structure
   - Use existing directories (don't create parallel structures)
   - Follow established naming conventions
   - Integrate with existing modules where appropriate
3. For new projects: Establish clean, conventional structure
4. Add cross-cutting concerns and infrastructure
5. **CRITICAL: Use the Write tool** to save to {TASKER_DIR}/artifacts/physical-map.json
6. **Verify file exists**: `ls -la {TASKER_DIR}/artifacts/physical-map.json`
7. Validate with: `cd {TASKER_DIR}/.. && tasker state validate physical_map`

IMPORTANT - YOUR TASK IS NOT COMPLETE UNTIL:
1. You MUST use the Write tool to save the file. Simply outputting JSON to the conversation is NOT sufficient.
2. Use the TASKER_DIR absolute path provided above. Do NOT use relative paths.
3. After Write, you MUST verify: `ls -la {TASKER_DIR}/artifacts/physical-map.json` - if file doesn't exist, Write again!
4. You MUST run validation and confirm it passes.
5. For existing projects, respect the established structure - don't fight it.

**Note:** The orchestrator has already created all required directories. Do NOT create directories yourself. If you encounter "directory does not exist" errors, report this to the orchestrator.

If you complete without the file existing at the absolute path, you have FAILED.
```

### Definition Phase: task-author

**Spawn prompt for task-author:**

```
Create individual task files from the physical map.

## Logging (MANDATORY)

Log your activity using the logging script:

./scripts/log-activity.sh INFO task-author start "Creating task files from physical map"
./scripts/log-activity.sh INFO task-author decision "What decision and why"
./scripts/log-activity.sh INFO task-author complete "Outcome description"

## Context

TASKER_DIR: {absolute path to .tasker directory, e.g., /Users/foo/my-project/.tasker}
Target Directory: {TARGET_DIR}
Project Type: {new | existing}

## Project Context (for existing projects)

{INSERT FULL PROJECT_CONTEXT HERE if existing project}

Key information for task definitions:
- Testing patterns (what framework, where fixtures live)
- Linting/formatting requirements (ruff, eslint, etc.)
- Build/run commands (make test, uv run pytest, npm test)
- Integration points with existing code

## Tech Stack Constraints
{user-provided constraints that affect implementation}

## 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:
   - Read the FSM index and transitions files
   - For each task, identify which FSM transitions it covers
   - Add `state_machine` field to task definitions (see FSM Integration below)
   - Generate FSM-aware acceptance criteria
4. **For existing projects:** Include acceptance criteria that verify integration:
   - Tests pass with existing test suite
   - Linting passes (ruff, eslint, etc.)
   - New code follows established patterns
5. **CRITICAL: Use the Write tool** to save each task file to {TASKER_DIR}/tasks/T001.json, etc.
6. **Verify files exist**: `ls -la {TASKER_DIR}/tasks/`
7. Load tasks with: `cd {TASKER_DIR}/.. && tasker state load-tasks`

## FSM Integration (if FSM artifacts exist)

When FSM artifacts are present at {TASKER_DIR}/artifacts/fsm/:

### Add state_machine field to tasks
```json
{
  "id": "T001",
  "name": "Implement credential validation",
  ...
  "state_machine": {
    "transitions_covered": ["TR1", "TR2"],
    "guards_enforced": ["I1"],
    "states_reached": ["S2", "S3"]
  }
}
```

### Generate FSM-aware acceptance criteria
For each transition covered:
- "Transition TR1 (S1→S2) fires when trigger X occurs"
- "Guard I1 prevents invalid transition when condition Y fails"

Example:
```json
{
  "criterion": "Transition TR1: Unauthenticated→Validating fires on login request",
  "verification": "pytest tests/auth/test_fsm.py::test_tr1_login_triggers_validation"
},
{
  "criterion": "Guard I1: Invalid email format prevents authentication",
  "verification": "pytest tests/auth/test_fsm.py::test_guard_invalid_email_blocked"
}
```

### Coverage validation (HARD GATE)

After creating tasks, verify FSM transition coverage. **This is a HARD PLANNING GATE**:

```bash
# Generate coverage report (for observability)
tasker fsm validate coverage-report \
    {TASKER_DIR}/artifacts/fsm/index.json \
    {TASKER_DIR}/tasks \
    --output {TASKER_DIR}/artifacts/fsm-coverage.plan.json

# Validate coverage meets thresholds (HARD GATE)
tasker fsm validate task-coverage \
    {TASKER_DIR}/artifacts/fsm/index.json \
    {TASKER_DIR}/tasks \
    --steel-threshold 1.0 \
    --other-threshold 0.9
```

**Coverage Requirements:**
- **Steel-thread transitions: 100% coverage required** - Every transition in the primary machine MUST have at least one task covering it
- **Non-steel-thread transitions: 90% coverage required** (configurable)

**If coverage gate fails:**
1. Planning BLOCKS until coverage is achieved
2. Task-author must add tasks to cover missing transitions
3. Each transition should have:
   - Implementation task(s) that implement the transition
   - Verification in acceptance criteria that the transition works

IMPORTANT - YOUR TASK IS NOT COMPLETE UNTIL:
1. You MUST use the Write tool to save each file. Simply outputting JSON to the conversation is NOT sufficient.
2. Use the TASKER_DIR absolute path provided above. Do NOT use relative paths.
3. After Write, you MUST verify: `ls {TASKER_DIR}/tasks/*.json | wc -l` - if count is 0, Write again!
4. You MUST run load-tasks and confirm it succeeds.
5. For existing projects, tasks must include verification that new code integrates cleanly.
6. **If FSM artifacts exist**: You MUST run FSM coverage validation:
   ```bash
   tasker fsm validate task-coverage \
       {TASKER_DIR}/artifacts/fsm/index.json \
       {TASKER_DIR}/tasks
   ```
   This is a **HARD GATE** - planning cannot proceed if steel-thread coverage < 100%.

**Note:** The orchestrator has already created all required directories. Do NOT create directories yourself. If you encounter "directory does not exist" errors, report this to the orchestrator.

If you complete without task files existing at the absolute path, you have FAILED.
```

### Validation Phase Details

**Automated Planning Gates (Pre-Check)**

Before advancing from `definition` to `validation` phase, the system automatically runs programmatic validation gates:

```bash
# This happens automatically when calling: tasker state advance
# The following gates are checked:
# - Spec coverage ≥ 90% (tasks cover requirements)
# - No phase leakage (Phase 2+ content not in Phase 1 tasks)
# - All task dependencies reference existing tasks
# - Acceptance criteria quality (no vague terms like "works correctly")
```

If any gate fails, phase advancement is blocked:
```
Planning gates failed: Spec coverage 75.0% below threshold 90.0%; Acceptance criteria quality issues: 3 problem(s)
Run 'tasker validate gates' for details
```

Results are stored in `state.json → artifacts.validation_results` for observability.

**LLM-as-Judge Verification**

After programmatic gates pass, the `validation` phase runs **task-plan-verifier** to evaluate task definitions.

**Spawn prompt for task-plan-verifier:**

```
Verify task definitions for planning

## Logging (MANDATORY)

Log your activity using the logging script:

./scripts/log-activity.sh INFO task-plan-verifier start "Verifying task definitions"
./scripts/log-activity.sh INFO task-plan-verifier decision "What decision and why"
./scripts/log-activity.sh INFO task-plan-verifier complete "Outcome description"

## 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/
User Preferences: ~/.claude/CLAUDE.md (if exists)

## Required Command

Register verdict using: tasker state validate-tasks <VERDICT> "<summary>"
(IMPORTANT: The command is validate-tasks, NOT validate-complete or any other variant)
```

The verifier:
1. Evaluates all tasks against spec, strategy, and user preferences
2. Registers its verdict via `tasker state validate-tasks <VERDICT> ...`
3. Returns a detailed report

Verdicts:
- `READY` - All tasks pass, proceed to sequencing
- `READY_WITH_NOTES` - Tasks pass with minor issues noted
- `BLOCKED` - Critical issues found, must fix before continuing

After the verifier completes, the orchestrator:
```bash
# Check if we can advance (verifier already registered verdict)
tasker state advance
```

If BLOCKED, the orchestrator:
1. Displays the verifier's summary to user
2. Points user to full report: `{TASKER_DIR}/reports/task-validation-report.md`
3. Waits for user to fix task files
4. Re-runs task-plan-verifier (or user runs `/verify-plan`)
5. Repeats until READY or READY_WITH_NOTES

### Sequencing Phase: plan-auditor

**Spawn prompt for plan-auditor:**

```
Assign phases to tasks and validate the dependency graph.

## Logging (MANDATORY)

Log your activity using the logging script:

./scripts/log-activity.sh INFO plan-auditor start "Assigning phases and validating DAG"
./scripts/log-activity.sh INFO plan-auditor decision "What decision and why"
./scripts/log-activity.sh INFO plan-auditor complete "Outcome description"

## Context

TASKER_DIR: {absolute path to .tasker directory, e.g., /Users/foo/my-project/.tasker}

## 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 to {TASKER_DIR}/tasks/T001.json etc.
6. Validate DAG (no cycles, deps in earlier phases)
7. Run: cd {TASKER_DIR}/.. && tasker state load-tasks

IMPORTANT:
- You MUST update task files using the Write tool or jq.
- Use the TASKER_DIR absolute path provided above. Do NOT use relative paths.
```

The report file contains:
- Per-task evaluations with evidence
- Specific issues and fix suggestions
- User preference violations (from ~/.claude/CLAUDE.md)

## Plan Completion

When phase reaches "ready":
```markdown
## 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 for post-hoc analysis:

```bash
# Archive planning artifacts
tasker archive planning {project_name}
```

This creates:
```
archive/{project_name}/planning/{timestamp}/
├── inputs/         # spec.md (verbatim)
├── artifacts/      # capability-map.json, physical-map.json, spec-review.json
├── tasks/          # T001.json, T002.json, ...
├── reports/        # task-validation-report.md
├── state.json      # State snapshot
└── archive-manifest.json
```

The archive preserves full context for:
- Gap analysis after implementation
- Debugging spec coverage issues
- Auditing planning decisions
- Restoring planning state if needed

---

# Execute Mode

Triggered by `/execute`. Runs task execution phase, followed by optional compliance check.

## Execute Inputs

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

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

After target_dir is confirmed:
```bash
TARGET_DIR="<user-provided-path>"
# Convert to absolute path
TARGET_DIR=$(cd "$TARGET_DIR" 2>/dev/null && pwd)

TASKER_DIR="$TARGET_DIR/.tasker"

# Verify .tasker/ exists and has state
if [ ! -f "$TASKER_DIR/state.json" ]; then
    echo "Error: No tasker session found at $TASKER_DIR"
    echo "Run /plan first to create a task plan."
    exit 1
fi
```

## Execute Prerequisites

```bash
# Verify planning is complete
tasker state status
# Phase must be: ready, executing, or have tasks
```

## Git Repository Initialization (MANDATORY)

**Before any implementation begins**, check if the target repository has git initialized. If not, initialize it:

```
Bash: ./scripts/ensure-git.sh "$TARGET_DIR"
```

**Why this is required:**
- Enables automatic commit hooks to track changes per task
- Provides audit trail of all implementation changes
- Required for the post-task-commit hook to function

## Recovery on Start (CRITICAL)

**Before starting the execute loop**, always check for and recover from a previous crash:

```bash
# Check for existing checkpoint from previous run
tasker state checkpoint status

# If checkpoint exists and is active, recover
tasker state checkpoint recover

# This will:
# 1. Find tasks that completed (have result files) but weren't acknowledged
# 2. Identify orphaned tasks (still "running" with no result file)
# 3. Update checkpoint state accordingly
```

If orphaned tasks are found, ask user:
```markdown
Found 3 orphaned tasks from previous run:
- T019, T011, T006

Options:
1. Retry orphaned tasks (reset to pending)
2. Skip orphaned tasks (mark failed)
3. Abort and investigate
```

To retry orphaned tasks:
```bash
tasker state task retry T019
tasker state task retry T011
tasker state task retry T006
tasker state checkpoint clear
```

## Execute Loop

**CRITICAL CONSTRAINTS:**
- **Max 3 parallel executors** - More causes orchestrator context exhaustion
- **Task-executors are self-completing** - They call `state.py complete-task` directly
- **Checkpoint before spawning** - Track batch for crash recovery
- **Minimal returns** - Executo

…(truncated)