specify

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

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:

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:

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

Create $TARGET_DIR/.tasker/state.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

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 Stack

What tech stack should be used?

Free-form text input. Examples:

• "Python 3.12+ with FastAPI, PostgreSQL, Redis"
• "TypeScript, Next.js, Prisma, Supabase"
• "Go with Chi router, SQLite"
• "Whatever fits best" (let /specify recommend based on requirements)

If user says "whatever fits best" or similar:

• Note this for Phase 2 (Clarify) to recommend based on gathered requirements
• Ask clarifying questions: "Any language preferences?", "Cloud provider constraints?", "Team expertise?"

Question 5: Entry Point (CRITICAL for W8/I6 compliance)

How will users invoke this? What makes it available?

Options to present:

• CLI command — User runs a command (specify command name)
• API endpoint — User calls an HTTP endpoint (specify URL pattern)
• Claude Code skill — User invokes /skillname (specify trigger)
• Library/module — No direct invocation, imported by other code
• Other — Custom activation mechanism

If user selects CLI/API/Skill: Follow up: "What specific steps are needed to make this available to users?"

If user selects Library/module: Note in spec: "Installation & Activation: N/A - library/module only"

Why this matters: Specs that describe invocation without activation mechanism cause W8 weakness and I6 invariant failure. Capturing this early prevents dead entry points.

Output

1. Update State (MANDATORY)

Update $TARGET_DIR/.tasker/state.json:

{
  "phase": {
    "current": "scope",
    "completed": ["initialization"],
    "step": "complete"
  },
  "updated_at": "<timestamp>",
  "scope": {
    "goal": "<user-provided-goal>",
    "non_goals": ["<item1>", "<item2>"],
    "done_means": ["<criterion1>", "<criterion2>"],
    "tech_stack": "<tech-stack-or-TBD>",
    "entry_point": {
      "type": "cli|api|skill|library|other",
      "trigger": "<command-name or /skillname or endpoint>",
      "activation_steps": ["<step1>", "<step2>"]
    },
    "completed_at": "<timestamp>"
  }
}

2. Write Spec Draft (MANDATORY)

Write initial spec sections to $TARGET_DIR/.tasker/spec-draft.md:

# Spec: {Title}

## Goal
{goal from scope}

## Non-goals
{non_goals from scope}

## Done means
{done_means from scope}

## Tech Stack
{tech_stack from scope}

## Installation & Activation
**Entry Point:** {entry_point.trigger from scope}
**Type:** {entry_point.type from scope}

**Activation Steps:**
{entry_point.activation_steps from scope, numbered list}

**Verification:**
<!-- To be filled in during Clarify or Synthesis -->

<!-- Remaining sections will be added by subsequent phases -->

IMPORTANT: All spec content is built in this file, NOT in conversation context. Read from this file when you need prior spec content.

---

Phase 2 — Clarify (Ralph Iterative Discovery Loop)

Purpose

Exhaustively gather requirements via structured questioning.

Setup

1. Initialize Clarify State in state.json (MANDATORY)

Update $TARGET_DIR/.tasker/state.json:

{
  "phase": {
    "current": "clarify",
    "completed": ["initialization", "scope"],
    "step": "starting"
  },
  "updated_at": "<timestamp>",
  "clarify": {
    "current_category": "core_requirements",
    "current_round": 1,
    "categories": {
      "core_requirements": { "status": "not_started", "rounds": 0 },
      "users_context": { "status": "not_started", "rounds": 0 },
      "integrations": { "status": "not_started", "rounds": 0 },
      "edge_cases": { "status": "not_started", "rounds": 0 },
      "quality_attributes": { "status": "not_started", "rounds": 0 },
      "existing_patterns": { "status": "not_started", "rounds": 0 },
      "preferences": { "status": "not_started", "rounds": 0 }
    },
    "pending_followups": [],
    "requirements_count": 0,
    "stock_takes_count": 0,
    "started_at": "<timestamp>"
  }
}

2. Create Discovery File

Create $TARGET_DIR/.tasker/clarify-session.md:

# Discovery: {TOPIC}
Started: {timestamp}

## Category Status

| Category | Status | Rounds | Notes |
|----------|--------|--------|-------|
| Core requirements | ○ Not Started | 0 | — |
| Users & context | ○ Not Started | 0 | — |
| Integrations | ○ Not Started | 0 | — |
| Edge cases | ○ Not Started | 0 | — |
| Quality attributes | ○ Not Started | 0 | — |
| Existing patterns | ○ Not Started | 0 | — |
| Preferences | ○ Not Started | 0 | — |

## Discovery Rounds

3. Create Stock-Takes File

Create $TARGET_DIR/.tasker/stock-takes.md:

# Stock-Takes: {TOPIC}
Started: {timestamp}

This file tracks how the vision evolves as discovery progresses.

---

CRITICAL: Resume Capability

On resume (after compaction or restart):

1. Read $TARGET_DIR/.tasker/state.json to get clarify state
2. Read $TARGET_DIR/.tasker/clarify-session.md to get discovery history
3. Resume from clarify.current_category and clarify.current_round
4. If clarify.pending_followups is non-empty, continue follow-up loop first

DO NOT rely on conversation context for clarify progress. Always read from files.

Loop Rules

• No iteration cap - Continue until goals are met

• Category Focus Mode - Work on ONE category at a time until it's complete or explicitly deferred

• Each iteration:

  1. Read discovery file
  2. Select ONE incomplete category to focus on (priority: Core requirements → Users & context → Integrations → Edge cases → Quality attributes → Existing patterns → Preferences)
  3. Ask 2–4 questions within that focused category
  4. Get user answers
  5. Run Follow-up Sub-loop (see below) - validate and drill down on answers
  6. Only after follow-ups are complete: update discovery file, extract requirements, update category status
  7. Repeat within same category until goal is met OR user says "move on from this category"

• Clarity Before Progress - If user response is anything except a direct answer (counter-question, confusion, pushback, tangential), provide clarification FIRST. Do NOT present new questions until prior questions have direct answers.

• Stop ONLY when:

  • ALL category goals are met (see checklist), OR
  • User says "enough", "stop", "move on", or similar

Follow-up Sub-loop (MANDATORY)

After receiving answers to a question round, DO NOT immediately move to the next round. First, validate each answer:

Answer Validation Triggers

For each answer, check if follow-up is required:

| Trigger | Example | Required Follow-up | |---------|---------|-------------------| | Vague quantifier | "several users", "a few endpoints" | "How many specifically?" | | Undefined scope | "and so on", "etc.", "things like that" | "Can you list all items explicitly?" | | Weak commitment | "probably", "maybe", "I think" | "Is this confirmed or uncertain?" | | Missing specifics | "fast response", "secure" | "What's the specific target? (e.g., <100ms)" | | Deferred knowledge | "I'm not sure", "don't know yet" | "Should we make a default assumption, or is this blocking?" | | Contradicts earlier answer | Conflicts with prior round | "Earlier you said X, now Y. Which is correct?" |

Sub-loop Process

For each answer in current round:
  1. Check against validation triggers
  2. If trigger found:
     a. Add to pending_followups in state.json
     b. Ask ONE follow-up question (not batched)
     c. Wait for response
     d. Remove from pending_followups, re-validate the new response
     e. Repeat until answer is concrete OR user explicitly defers
  3. Only after ALL answers validated → proceed to next round

MANDATORY: Persist Follow-up State

Before asking a follow-up question, update state.json:

{
  "clarify": {
    "pending_followups": [
      {
        "question_id": "Q3.2",
        "original_answer": "<user's vague answer>",
        "trigger": "vague_quantifier",
        "followup_question": "<the follow-up question being asked>"
      }
    ]
  }
}

After receiving follow-up response, remove from pending_followups and update the round in clarify-session.md.

Follow-up Question Format

Use AskUserQuestion with context from the original answer:

{
  "question": "You mentioned '{user_quote}'. {specific_follow_up_question}",
  "header": "Clarify",
  "options": [
    {"label": "Specify", "description": "I'll provide a specific answer"},
    {"label": "Not critical", "description": "This detail isn't important for the spec"},
    {"label": "Defer", "description": "I don't know yet, note as open question"}
  ]
}

Handling Non-Direct Responses (MANDATORY)

If the user's response is anything other than a direct answer, assume clarification is required. Do NOT present new questions until the original question is resolved.

| Response Type | Example | Required Action | |---------------|---------|-----------------| | Counter-question | "What do you mean by X?" | Answer their question, then re-ask yours | | Confusion | "I'm not sure what you're asking" | Rephrase the question with more context | | Pushback | "Why do you need to know that?" | Explain why this matters for the spec | | Tangential | Talks about something else | Acknowledge, then redirect to the question | | Partial answer | Answers part, ignores rest | Note the partial, ask about the unanswered part | | Meta-comment | "This is getting detailed" | Acknowledge, offer to simplify or defer |

Process:

1. Detect non-direct response
2. Address the user's concern/question FIRST
3. Only after clarity achieved → re-present the original question (or confirm it's now answered)
4. Do NOT batch new questions until all prior questions have direct answers

Example:

Agent: "What authentication method should users use?"
User: "What options are there?"

[NON-DIRECT: User asked a counter-question]

Agent: "Common options are: (1) Email/password, (2) OAuth (Google, GitHub),
       (3) Magic link, (4) SSO/SAML. Which fits your use case?"
User: "Email/password for now, maybe OAuth later."

[NOW DIRECT: Can proceed]

When NOT to Follow Up

• User explicitly says "that's all I know" or "let's move on"
• The answer is already concrete and specific
• The detail is genuinely non-blocking (implementation detail, not spec-level)
• You've already asked 2 follow-ups on the same answer (avoid interrogation)

Example Interaction

Agent: "What integrations are required?"
User: "We need to connect to a few external services and maybe some APIs."

[FOLLOW-UP REQUIRED: "a few" is vague, "maybe" is weak commitment]

Agent: "You mentioned 'a few external services'. Can you list all the external systems this will integrate with?"
User: "Stripe for payments, SendGrid for email, and our internal user service."

[ANSWER NOW CONCRETE: specific services named]

Agent: "You said 'maybe some APIs'. Are there additional API integrations beyond Stripe, SendGrid, and the user service?"
User: "No, that's all."

[CATEGORY GOAL PROGRESS: Integrations now has concrete list]

Category Checklist (Goal-Driven Coverage)

Each category has concrete "done" criteria. Track completion in the discovery file.

| Category | Goal (Done When) | |----------|------------------| | Core requirements | Primary workflows enumerated with inputs, outputs, and happy path steps | | Users & context | User roles identified, expertise levels known, access patterns clear | | Integrations / boundaries | All external systems named, data flows mapped, API contracts sketched | | Edge cases / failures | Error handling defined for each workflow step, retry/fallback behavior specified | | Quality attributes | Performance targets have numbers (or explicit "not critical"), security requirements stated | | Existing patterns | Relevant prior art identified OR confirmed none exists, conventions to follow listed | | Preferences / constraints | Tech stack decided, deployment target known, timeline/resource constraints stated |

Tracking Format

Update discovery file with completion status:

## Category Status

| Category | Status | Notes |
|----------|--------|-------|
| Core requirements | ✓ Complete | 3 workflows defined |
| Users & context | ✓ Complete | 2 roles: admin, user |
| Integrations | ⋯ In Progress | DB confirmed, auth TBD |
| Edge cases | ○ Not Started | — |
| Quality attributes | ○ Not Started | — |
| Existing patterns | ✓ Complete | Follow auth module pattern |
| Preferences | ⋯ In Progress | Python confirmed, framework TBD |

Completion Criteria

A category is complete when:

1. The goal condition is satisfied (see table above)
2. User has confirmed or provided the information
3. All answers have passed follow-up validation (no vague quantifiers, no weak commitments, no undefined scope)
4. No obvious follow-up questions remain for that category
5. User has explicitly confirmed or the agent has verified understanding

Do NOT mark complete if:

• User said "I don't know" without a fallback decision
• Information is vague (e.g., "fast" instead of "<100ms")
• Dependencies on other categories are unresolved
• Follow-up validation has not been run on all answers
• Any answer contains unresolved triggers (vague quantifiers, weak commitments, etc.)

Category Transition Rules

Before moving to a new category:

1. Summarize what was learned in the current category
2. Confirm with user: "I've captured X, Y, Z for [category]. Does that cover everything, or is there more?"
3. Run Stock-Take (see below)
4. Only then move to the next incomplete category

This prevents the feeling of being "rushed" through categories.

Stock-Taking (Big Picture Synthesis)

Purpose

As questions are answered and categories complete, periodically synthesize the "big picture" - what's emerging, the shape of the vision. This helps users see how their answers are building toward something coherent and provides calibration moments.

Trigger

Stock-take is triggered after each category completes (before transitioning to the next category). This creates a natural rhythm of ~5-7 stock-takes during Phase 2.

Content

A stock-take is NOT a list of answers. It's a synthesis of meaning - what's taking shape:

1. What we're building (1-2 sentences, evolving as understanding deepens)
2. Key constraints/boundaries that have emerged from answers
3. The shape becoming visible (patterns, tensions, tradeoffs surfacing)
4. Direction check - light confirmation the vision still feels right

Format

**Taking stock** (after {category_name}):

{1-3 sentence synthesis of what's emerging - not a summary of answers, but the picture forming}

{Any notable patterns, tensions, or tradeoffs becoming visible}

Does this still capture where we're heading?

Example

After completing "Integrations" category:

Taking stock (after Integrations):

We're building a CLI skill system where specs drive task decomposition. The emphasis is on preventing incomplete handoffs - every behavior must trace back to stated requirements. The system is self-contained except for Git (for state persistence) and Claude Code (as the execution runtime).

There's tension between thoroughness and workflow friction that keeps surfacing - users want comprehensive specs but not interrogation.

Does this still capture where we're heading?

Tone

• Reflective, not interrogative
• Synthesizing, not summarizing
• Calibrating, not gate-checking

The question at the end is light - "Does this still feel right?" not "Please confirm items 1-7."

Process

After category completion:

1. Read accumulated state from spec-draft.md (scope), clarify-session.md (discovery so far)
2. **Synth

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->