haraujo21/task-spec

---

The missing contract between intent and execution

A prompt tells an agent what you want. A Task-Spec also records what the agent may change, what observable behavior counts as success, what evidence must exist, who authorized that exact contract, and what an independent gate must verify afterward.

The core stops at that boundary. It does not host models, store credentials, create a sandbox, or turn a weak eval into a wise oracle. Version 3.9 adds TaskMesh as an optional runtime: it can route and execute already-authorized leaves, but it cannot change the contract or accept work on its own terms.

Prove it in one command

After installation, run a complete lifecycle in a disposable repository:

$ taskspec demo
Task-Spec isolated lifecycle
  PLAN=VALID
  DOD=COMPLETE
  VERDICT=DELEGATE TIER=1
  HANDOFF=TaskHandoff/v3
  EVAL=PASS
  ACCEPTED=1
DEMO=READY

taskspec demo creates an isolated Git repository, writes and validates a real TaskPlan/v1, generates one atomic leaf, seals it, emits a portable handoff, runs its eval, accepts the result, and removes the repository. It does not touch the repository from which you invoke it. Executed proof: tests/test-demo.sh and tests/test-v36-experience.sh.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#070A0F', 'primaryColor': '#111720', 'primaryTextColor': '#F5F2EA', 'primaryBorderColor': '#29313A', 'lineColor': '#F5F2EA'}}}%%
flowchart LR
    PlanValid["PLAN=VALID"] --> DodComplete["DOD=COMPLETE"]
    DodComplete --> Verdict["VERDICT=DELEGATETIER=1"]
    Verdict --> Handoff["HANDOFF=TaskHandoff/v3"]
    Handoff --> EvalPass["EVAL=PASS"]
    EvalPass --> Accepted["ACCEPTED=1"]

    classDef default fill:#111720,stroke:#29313A,color:#F5F2EA
    classDef verdict fill:#111720,stroke:#E4A51A,color:#E4A51A
    classDef accepted fill:#E4A51A,stroke:#E4A51A,color:#070A0F,font-weight:bold
    class Verdict verdict
    class Accepted accepted

Chat experience

The CLI is the referee. The skill is how a coding agent finds that referee. After install.sh --global --copy (or --target for one repo), the same SKILL.md lands in every supported harness. The in-repo pack skills/task-spec is a byte-for-byte copy of root SKILL.md. AGENTS.md is the machine contract for this repository. The installed skill is the contract for any repository that uses Task-Spec. The skill drives taskspec. It does not replace the gates.

Claude marketplace (plugin, not a second contract):

/plugin marketplace add luanmorenommaciel/task-spec
/plugin install task-spec@taskspec

Then talk to the agent. Paste one of these; do not skip the plan or the seal.

Plan first (read-only):

Use the task-spec skill. Inspect this repository and turn the following intent
into a TaskPlan/v1. Show me the plan. Do not generate Task-Spec files until I
approve it. Do not stamp signed_off or accepted by hand.

Intent: add repository search with tests.

Generate only after you approve the plan:

The plan is approved. Drive the taskspec CLI: plan --manifest, then batch
--plan. Validate and dod every leaf. Stop before gate --stamp and show me
the generated specs.

Authorize one leaf, then hand it off:

Authorize only tasks/T-...-leaf.md with taskspec gate --stamp. Emit a
TaskHandoff/v3 with taskspec handoff --backend  --out
.taskspec/handoffs/attempt.json. Do not start work until that file exists.

Accept independently (different session or different agent is fine):

Independently run taskspec accept --handoff .taskspec/handoffs/attempt.json
--stamp tasks/T-...-leaf.md. Only then may status become done. Do not
hand-edit accepted: true.

Installation

This repository and its releases are private. Authenticate to GitHub before cloning or downloading assets. Anonymous raw-file URLs are not installation doors.

Pick one door. All of them install the same engine and the same skill.

1. Authenticated source checkout

git clone --depth 1 https://github.com/luanmorenommaciel/task-spec.git \
  "$HOME/.local/share/task-spec-src"

bash "$HOME/.local/share/task-spec-src/install.sh" --global --copy
export PATH="$HOME/.local/bin:$PATH"
taskspec doctor
taskspec demo

Executed proof for doctor and demo: tests/test-v36-experience.sh and tests/test-demo.sh.

Optional TaskMesh, when this checkout has Go available:

bash "$HOME/.local/share/task-spec-src/install.sh" --global --copy --with-mesh
taskspec mesh doctor

Executed proof for mesh: tests/test-mesh-demo.sh and tests/test-mesh-conformance.sh.

Repository-local skill copies use --target DIR --copy (see installation docs).

The installer prints INSTALL=OK only after the engine version, every harness skill copy, and the CLI launcher all agree.

2. Pinned private release archive

gh auth status
release_dir="$(mktemp -d)"
gh release download v3.9.0 \
  --repo luanmorenommaciel/task-spec \
  --pattern 'task-spec-3.9.0.tar.gz*' \
  --pattern 'taskspec-meshd-*' \
  --dir "$release_dir"
(cd "$release_dir" && shasum -a 256 -c task-spec-3.9.0.tar.gz.sha256)
tar -xzf "$release_dir/task-spec-3.9.0.tar.gz" -C "$release_dir"
bash "$release_dir/task-spec-3.9.0/install.sh" --global --copy --with-mesh

3. Node package plus GitHub tag

gh auth setup-git
npm install -g git+https://github.com/luanmorenommaciel/task-spec.git#v3.9.0
taskspec-install --global --with-mesh

Installer flags (--symlink, --force, --no-bin, --bin-dir) and the full harness dest list live in installation.md.

Installation guarantees

Requirements

Bash 3.2+, Git, Python 3, and shellcheck for the PRE-gate and demo. OpenSSL, shasum, or sha256sum for Tier-1 HMAC. Node 18+ only for the npm door. Go 1.25+ only when building TaskMesh from source. Docker or Podman only for autonomous OMP execution.

Step-by-step usage

Everything below happens inside the repository you want to change. The first task should be XS or S and supervised. Calibrate eval quality before increasing autonomy.

1. Prepare the repository

taskspec init
taskspec setup signing
taskspec doctor

Executed proof: tests/test-v36-experience.sh clean-room journey. init creates only missing workspace files. The signing key lives in the repository’s private Git common directory and never enters a handoff.

2. Ask for a plan, not files

Use the chat prompts. The expected boundary is a complete TaskPlan/v1: atomic units, dependencies, write surfaces, behaviors, evals, budgets, and open questions. Approval of the plan is separate from authorization to execute a leaf.

3. Preview, approve, and generate

taskspec plan --manifest tasks/.plans/add-search.yaml
taskspec batch --plan tasks/.plans/add-search.yaml
taskspec new add-search S codex

Executed proof: tests/test-v36-experience.sh (plan, batch, new). plan is read-only. batch refuses an unapproved, malformed, cyclic, or credential-bearing manifest. new scaffolds one leaf. Use format v4 only when acceptance needs independent holdout, graded, human, or environment evidence. Format v3 is the authoring default.

4. Inspect the contract and its proof graph

taskspec validate tasks/T-...-add-search.md
taskspec dod tasks/T-...-add-search.md
taskspec author-doctor tasks/T-...-add-search.md

Executed proof: tests/test-v36-experience.sh. Do not continue until structure is valid, DOD=COMPLETE, and every unresolved semantic decision has an owner or a blocked status.

5. Authorize exactly one ready leaf

taskspec gate --stamp tasks/T-...-add-search.md
taskspec handoff tasks/T-...-add-search.md --backend codex \
  --out .taskspec/handoffs/add-search.json

Executed proof: tests/test-v36-experience.sh (gate, handoff --out). The gate writes the HMAC seal. The handoff is read-only, digest-bound, and credential-free.

6. Execute with the chosen harness

Give the handoff to Codex, Claude Code, Kimi, Grok Build, Cursor, or a conformant custom executor. The player may change; the authorized paths, budgets, behaviors, and eval commands do not.

7. Accept independently

taskspec run tasks/T-...-add-search.md
taskspec accept --stamp --gold-sanity \
  --handoff .taskspec/handoffs/add-search.json \
  tasks/T-...-add-search.md
taskspec transition T-...-add-search done

Executed proof: tests/test-v36-experience.sh (run, accept --gold-sanity, transition).

Acceptance reruns the Exit Check, compares every committed and uncommitted change with the handoff’s immutable Git base, verifies the revision and graph closure, applies v4 receipt policy, and writes AcceptanceRecord/v1. A task cannot transition to done first.

8. Expose the next safe frontier

taskspec ready --all
taskspec graph --check
taskspec status T-...-add-search

Executed proof: tests/test-v36-experience.sh (ready, graph, status). The graph is a deterministic projection of Markdown and Git. status returns exactly one safe next command. Task-Spec still does not choose or schedule the frontier.

How it works

The Receipt Gate: PRE-gate seals the contract, POST-gate earns ACCEPTED=1.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#070A0F', 'primaryColor': '#111720', 'primaryTextColor': '#F5F2EA', 'primaryBorderColor': '#29313A', 'lineColor': '#F5F2EA'}}}%%
flowchart LR
    subgraph PRE["PRE-GATE"]
        Intent["Intent"] --> Plan["TaskPlan/v1"]
        Plan --> Leaf["Atomic Leaf"]
        Leaf --> Gate["gate --stampHMAC v3"]
    end

    subgraph HANDOFF["HANDOFF"]
        Gate --> Transfer["TaskHandoff/v3"]
        Transfer --> Executor["Executor"]
    end

    subgraph POST["POST-GATE"]
        Executor --> Accept["accept --stamp"]
        Accept --> Verdict["ACCEPTED=1"]
    end

    classDef default fill:#111720,stroke:#29313A,color:#F5F2EA
    classDef verdict fill:#E4A51A,stroke:#E4A51A,color:#070A0F,font-weight:bold
    class Verdict verdict

TaskMesh sits between the ready handoff and the executor only when installed.

What shipped in 3.9

TaskMesh is the optional portable execution control plane for authorized atomic tasks. It cannot widen task authority, rewrite dependencies, or merge the target branch. Task-Spec remains the canonical authority and acceptance layer.

taskspec mesh frontier
taskspec mesh run --task T-...-add-search --adapter codex-native --execute
taskspec mesh watch 

Executed proof: tests/test-mesh-demo.sh and tests/test-mesh-conformance.sh complete control-plane corridor. finish prints a merge route only; it never merges, pushes, or opens a pull request against the target branch.

Read the five-minute TaskMesh journey, runtime contracts, and trust boundaries.

Trust boundaries

The 3.8.1 quality corridor is reused by 3.9.0 (QUALITY_SCORE=97). It is not a nine-provider claim. TaskMesh 3.9 proof lives in release/3.9.0/ and must emit MESH_CONFORMANCE, MESH_RECOVERY, MESH_ISOLATION, MESH_DEMO, and MESH_INSTALL as READY. Missing runtime is UNAVAILABLE, never a pass.

Who it is for

• Teams that need one atomic leaf with explicit paths, behavior, evals, budget, and owner
• Shops that run Codex, Claude Code, Kimi, Grok Build, Cursor, or any conformant executor against the same contract
• Reviewers who want to falsify release claims from the reviewer route
• Existing repositories: the installer and init are non-clobbering by default

Who it is not for

• Anyone expecting the core to host models, store credentials, or create a sandbox
• Anyone treating a weak eval as a wise oracle, or accepted: true as deployed
• Anyone wanting Homebrew or an anonymous curl installer (not shipped)
• Anyone wanting TaskMesh to widen scope, rewrite a signed leaf, or merge the user branch
• Anyone needing a live nine-engine matrix badge (not claimed)

Documentation

Inspect the installed contract and the bundled TaskPlan example:

taskspec agent-context
taskspec example task-plan --out tasks/.plans/reviewer.yaml
taskspec plan --manifest tasks/.plans/reviewer.yaml

Executed proof: tests/test-v36-experience.sh (agent-context) and tests/test-v381-experience.sh (installed canonical example).

From a source checkout, make check is the single local and normal-CI boundary. It ends with CHECK=READY only when doctor, documentation lint, every self-test, the isolated demo, and conformance are green.

Contributing

Humans and coding agents follow the same contract: AGENTS.md.

make check

Format changes are triple-locked: schema, conformance fixture, and changelog. Hosted CI runs make check on ubuntu-latest only; run the bash-3.2 floor locally. Do not rewrite frozen artifacts. Extracted from Converge at v3.3.0 (converge@f78f077).

Maintainers

Luan Moreno Medeiros Maciel. Security reports belong in SECURITY.md, not in a public issue. Use GitHub private vulnerability reporting, or email [email protected] when private reporting is unavailable.

License

MIT Copyright © 2026 Luan Moreno Medeiros Maciel.