specify

What this skill does

# Specify Workflow

**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).**

An **agent-driven interactive workflow** that transforms ideas into actionable specifications with extracted capabilities, ready for `/plan` to decompose into tasks.

## Core Principles

1. **Workflows and invariants before architecture** - Never discuss implementation until behavior is clear
2. **Decision-dense, not prose-dense** - Bullet points over paragraphs
3. **No guessing** — Uncertainty becomes Open Questions
4. **Minimal facilitation** — Decide only when required
5. **Specs are living; ADRs are historical**
6. **Less is more** — Avoid ceremony

## Artifacts

### Required Outputs (in TARGET project)
- **README** — `{TARGET}/README.md` (project overview - what it is, how to use it)
- **Spec Packet** — `{TARGET}/docs/specs/<slug>.md` (human-readable)
- **Capability Map** — `{TARGET}/docs/specs/<slug>.capabilities.json` (machine-readable, for `/plan`)
- **Behavior Model (FSM)** — `{TARGET}/docs/state-machines/<slug>/` (state machine artifacts, for `/plan` and `/execute`)
- **ADR files** — `{TARGET}/docs/adrs/ADR-####-<slug>.md` (0..N)

### Working Files (in target project's .tasker/)
- **Session state** — `$TARGET_DIR/.tasker/state.json` (persistent, primary resume source)
- **Spec draft** — `$TARGET_DIR/.tasker/spec-draft.md` (working draft, written incrementally)
- **Discovery file** — `$TARGET_DIR/.tasker/clarify-session.md` (append-only log)
- **Stock-takes** — `$TARGET_DIR/.tasker/stock-takes.md` (append-only log of vision evolution)
- **Decision registry** — `$TARGET_DIR/.tasker/decisions.json` (index of decisions/ADRs)
- **Spec Review** — `$TARGET_DIR/.tasker/spec-review.json` (weakness analysis)

### Archive
After completion, artifacts can be archived using `tasker archive` for post-hoc analysis.

---

## MANDATORY: Phase Order

```
Initialization → Scope → Clarification Loop (Discovery) → Synthesis → Architecture Sketch → Decisions/ADRs → Gate → Spec Review → Export
```

**NEVER skip or reorder these phases.**

---

# Phase 0 — Initialization

## Goal
Establish project context and session state before specification work begins.

## STEP 1: Auto-Detect Session State (MANDATORY FIRST)

**Before asking the user anything**, check for existing session state files.

### 1a. Determine Target Directory

Check in order:
1. If user provided a path in their message, use that
2. If CWD contains `.tasker/state.json`, use CWD
3. Otherwise, ask:

```
What is the target project directory?
```

### 1b. Check for Existing Session

```bash
TARGET_DIR="<determined-path>"
STATE_FILE="$TARGET_DIR/.tasker/state.json"

if [ -f "$STATE_FILE" ]; then
    # Read state to determine if session is in progress
    PHASE=$(jq -r '.phase.current' "$STATE_FILE")
    if [ "$PHASE" != "complete" ] && [ "$PHASE" != "null" ]; then
        echo "RESUME: Found active session at phase '$PHASE'"
        # AUTO-RESUME - skip to Step 1c
    else
        echo "NEW: Previous session completed. Starting fresh."
        # Proceed to Step 2 (new session)
    fi
else
    echo "NEW: No existing session found."
    # Proceed to Step 2 (new session)
fi
```

### 1c. Auto-Resume Protocol (if active session found)

**If `.tasker/state.json` exists and `phase.current != "complete"`:**

1. **Read state.json** to get current phase and step
2. **Inform user** (no question needed):
   ```
   Resuming specification session for "{spec_session.spec_slug}"
   Current phase: {phase.current}, step: {phase.step}
   ```
3. **Read required working files** for the current phase (see Resume Protocol section)
4. **Jump directly to the current phase** - do NOT re-run earlier phases

**This is automatic. Do not ask the user whether to resume.**

---

## STEP 2: New Session Setup (only if no active session)

### 2a. No Guessing on Reference Materials

**You MUST NOT:**
- Scan directories to infer what files exist
- Guess spec locations from directory structure
- Read files to detect existing specs
- Make any assumptions about what the user has

**The user tells you everything. You ask, they answer.**

### 2b. Ask About Reference Materials

Ask using AskUserQuestion:
```
Do you have existing specification reference materials (PRDs, requirements docs, design docs, etc.)?
```
Options:
- **No reference materials** — Starting from scratch
- **Yes, I have reference materials** — I'll provide the location(s)

### If "Yes, I have reference materials":
Ask for the location(s):
```
Where are your reference materials located? (Provide path(s) - can be files or directories)
```
Free-form text input. User provides path(s) (e.g., `docs/specs/`, `requirements.md`, `PRD.pdf`).

**Validate path exists:**
```bash
EXISTING_SPEC_PATH="<user-provided-path>"
if [ ! -e "$TARGET_DIR/$EXISTING_SPEC_PATH" ] && [ ! -e "$EXISTING_SPEC_PATH" ]; then
    echo "Warning: Path not found. Please verify the path."
fi
```

### 2c. Initialize Session State

Create `.tasker/` directory structure in target project:

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

Create `$TARGET_DIR/.tasker/state.json`:

```json
{
  "version": "3.0",
  "target_dir": "<absolute-path>",
  "phase": {
    "current": "initialization",
    "completed": [],
    "step": null
  },
  "created_at": "<timestamp>",
  "updated_at": "<timestamp>",
  "spec_session": {
    "project_type": "new|existing",
    "existing_spec_path": "<path-from-step-2-or-null>",
    "spec_slug": "<slug>",
    "spec_path": "<target>/docs/specs/<slug>.md",
    "started_at": "<timestamp>",
    "resumed_from": null
  },
  "scope": null,
  "clarify": null,
  "synthesis": null,
  "architecture": null,
  "decisions": null,
  "review": null
}
```

**CRITICAL: Update state.json after EVERY significant action.** This enables resume from any point.

The phase-specific state objects are populated as each phase progresses (see phase definitions below).

**If user provided existing spec path in Step 2b**, store it in `spec_session.existing_spec_path` for reference during Scope phase.

## Output (New Session Only)

For **new sessions** (Step 2 path):
- `.tasker/` directory structure created in target project
- Session state initialized in `$TARGET_DIR/.tasker/state.json`
- Existing spec path captured (if provided)
- Proceed to Phase 1 (Scope)

For **resumed sessions** (Step 1c path):
- State already exists - no initialization needed
- Jump directly to `phase.current` phase
- Read working files as specified in Resume Protocol

---

# Phase 1 — Scope

## Goal
Establish bounds before discovery.

## Pre-Scope: Load Existing Spec (if provided)

If `spec_session.existing_spec_path` was set during initialization:

1. **Read the existing spec file** to understand prior context
2. **Extract initial answers** for the scope questions below (Goal, Non-goals, Done means)
3. **Present extracted context** to user for confirmation/refinement rather than asking from scratch

```bash
if [ -n "$EXISTING_SPEC_PATH" ]; then
    echo "Loading existing spec from: $EXISTING_SPEC_PATH"
    # Read and analyze existing spec
    # Pre-fill scope questions with extracted information
fi
```

## Required Questions (AskUserQuestion)

Ask these questions using AskUserQuestion tool with structured options.
**If existing spec was loaded**, present extracted answers for confirmation rather than blank questions:

### Question 1: Goal
```
What are we building?
```
Free-form text input.

### Question 2: Non-goals
```
What is explicitly OUT of scope?
```
Free-form text input (allow multiple items).

### Question 3: Done Means
```
What are the acceptance bullets? (When is this "done"?)
```
Free-form text input (allow multiple items).

### Question 4: Tech