Tasks

A task is a scoped unit of work: one objective, a bounded set of files, and verification commands that prove completion.

What a task is

Tasks serve two audiences simultaneously: human-readable intent for auditability, and machine-precise instructions for autonomous execution. Claude Code reads a task, implements the changes, runs verification commands, and reports results.

Anatomy

- id: setup-auth-client
  spec_id: auth-layer
  objective: "Create the Supabase auth client singleton"
  intent: |
    The app currently initializes Supabase inline in components.
    Centralizing this removes duplication and enables consistent
    error handling across auth operations.
  acceptance_criteria:
    - "src/auth/client.ts exports a typed supabase client"
    - "All existing component imports updated to use the singleton"
    - "No duplicate Supabase client initializations remain"
  file_scope:
    - "src/auth/client.ts"
    - "src/components/Login.tsx"
    - "src/components/Profile.tsx"
  verification:
    - command: "bun run typecheck"
      proves: "No TypeScript errors introduced"
    - command: "bun test src/auth"
      proves: "Auth client behaves correctly"
  guardrails:
    - "Do not change the Supabase project URL or anon key"
    - "Do not add new npm dependencies"
  complexity: simple
  dependencies: []
  status: new

Complexity levels

Level	Description	Typical scope
simple	Mechanical change, one clear path	1-2 files
moderate	Some judgment required	3-5 files
complex	Architectural decisions, high blast radius	May need splitting

When in doubt, split a complex task into two moderate ones.

file_scope

The file_scope field is the key constraint for autonomous execution. Claude Code will only modify files listed here — nothing else. Keep it to 1-5 files per task. More than 5 is a signal the task should be split.

Verification commands

Verification commands must exit with code 0 on success and must be idempotent. At least one command should prove the feature works behaviorally, not just that the code compiles.

Weak: only bun run typecheck Better: bun run typecheck plus curl -s localhost:3000/api/health | grep ok

Dependencies

List task IDs that must complete before this task starts. Only add real dependencies — false sequencing prevents parallelism.

Task types

Each task has a type that describes the kind of work it represents:

Type	Description
code	Default. A code change implemented by an AI agent or developer.
human	Manual action outside the codebase (e.g., configure a service, approve a deployment).
waiting	Blocked on an external event (approval, deploy, upstream fix).
decision	A choice that must be made and recorded with rationale.

Status flow

new -> pending -> in-progress -> running -> verifying -> local-verified -> passed
                              -> failed
                              -> blocked
                              -> canceled
                              -> skipped

Key statuses:

Status	Meaning
new	Created but not yet scheduled
pending	Queued, waiting for dependencies
in-progress	Claimed by an agent or developer
running	Actively being executed
verifying	Work done, verification commands running
local-verified	Local criteria pass; awaiting staging/production verification
passed	All verification criteria pass across all environments
failed	Verification failed or work could not be completed
blocked	Waiting on an external dependency or decision
canceled	Abandoned; no longer needed
skipped	Intentionally skipped (e.g., superseded by another task)

Use jig task start, jig task done, and jig task fail to move through statuses. Always include --notes when marking done or failed.

Structured acceptance criteria

Tasks can have structured acceptance criteria that are mechanically verifiable. Each criterion has four parts: subject (what to check), property (what about it), expected (the right answer), and method (how to check). See Acceptance Criteria for full details.

Guardrails

Guardrails are prohibitions — things the task must not do. Violating a guardrail is an automatic task failure, regardless of whether other acceptance criteria pass. Examples:

• “Do not change the database schema”
• “Do not add new npm dependencies”
• “Do not modify files outside file_scope”

CLI commands

See CLI Reference for full details on tasks, task show, task start, task done, task fail, next, and decompose.