Brief-Spec

Different agents in. One predictable human handoff out.

Brief-Spec is a type-aware, evidence-backed delivery contract for AI coding harnesses. Same fields, same order, preserved evidence. It does not make every answer shorter; it makes every important answer legible. Brief-Spec standardizes the explanation and handoff, not the agent's reasoning. It never calls a model.

Public release v0.6.0 on GitHub and PyPI · MIT

• Public release: v0.6.0 on GitHub with wheels, sdists, schemas, and signed manifests.
• PyPI: brief-spec, brief-spec-renderer-pdf, and brief-spec-renderer-audio 0.6.0, the same bytes as the GitHub release.

What's new · Notifications · The problem · How it works · Outcome Brief · Docs · Skills · Harness · CLI · Install

What's new in 0.6.0

0.6.0 makes a valid brief mean something true, keeps the task type in step with the conversation, and lets a brief reach people where they already work.

• Notifications. brief-spec notify posts a brief to Slack, Microsoft Teams, Discord, Google Chat, or a signed webhook. Follow-ups for the same task go to one thread, and nothing is posted without --consent-network. See Notifications.
• DONE means directly verified. A DONE brief now needs at least one [direct/pass] proof and no failing proof. Use REVIEW when the evidence is only derived or reported.
• Better classification. On an independent set of conversational prompts, accuracy rose from 30.7% to 69.3%. A new request such as "review the folder structure" now switches the task type, while nouns and questions do not. brief-spec eval measures it.
• Freshness. Exports record the Git commit they describe, and verify says whether HEAD has moved on since.
• Secret scan. Export, bundle, verify, and notify refuse a brief that contains a token, key, or webhook URL.
• Decisions you can acknowledge. DECIDE briefs can carry a decision card (options, recommendation, reversibility, deadline), and brief-spec ack records what you chose.
• Re-entry after compaction. When the host compacts the context mid-task, the agent first gives a short Orient re-entry.

The 0.5.0 highlights (the brief-spec name, eight work types, typed wrapper, five required harnesses, exports and verification) are in the changelog. The full 0.6.0 list is in the changelog.

The problem

Good agent output can still be exhausting to consume.

Once several agents are running, generation is no longer the only bottleneck. Re-entry becomes the bottleneck. One response begins with a narrative. Another hides the decision below a test log. A third mixes completed work, caveats, and suggested work into the same paragraph.

Before acting, you must first discover how to read the answer.

Brief-Spec makes that last mile predictable. It keeps the agent's full work available while giving the human handoff a stable shape.

How it works

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#111720', 'primaryTextColor': '#F5F2EA', 'primaryBorderColor': '#A56BFF', 'lineColor': '#29313A', 'secondaryColor': '#070A0F', 'tertiaryColor': '#29313A', 'background': '#070A0F', 'mainBkg': '#111720', 'nodeBorder': '#A56BFF', 'clusterBkg': '#111720', 'titleColor': '#F5F2EA', 'edgeLabelBackground': '#111720'}}}%%
flowchart LR
    A["Host task"] --> B["Harness adapter"]
    B --> C["Local type classification"]
    C --> D["Type-specific explanation"]
    D --> E{"Eligible and at a boundary?"}
    E -->|"Checkpoint"| F["Orient, Teach, or Spoken Brief"]
    E -->|"Agent stopping"| G["Outcome Brief"]
    F --> H["Canonical delivery object"]
    G --> H
    H --> I["Verified downloads"]
    J["Repository, command, test, URL, or artifact"] -. "inspectable proof" .-> I

    style A fill:#111720,stroke:#29313A,color:#F5F2EA
    style B fill:#111720,stroke:#29313A,color:#F5F2EA
    style C fill:#111720,stroke:#29313A,color:#F5F2EA
    style D fill:#111720,stroke:#29313A,color:#F5F2EA
    style E fill:#29313A,stroke:#A56BFF,color:#F5F2EA
    style F fill:#111720,stroke:#29313A,color:#F5F2EA
    style G fill:#A56BFF,stroke:#A56BFF,color:#F5F2EA
    style H fill:#111720,stroke:#A56BFF,color:#F5F2EA
    style I fill:#111720,stroke:#29313A,color:#F5F2EA
    style J fill:#111720,stroke:#29313A,color:#F5F2EA

The host integrations normalize lifecycle events when the host provides them: session start, user prompt, tool use, pre-compaction, agent stop, and session end.

Brief-Spec records bounded operational state, applies eligibility and cooldown rules, and injects guidance at the next available boundary. Full guidance arrives once per context window; later prompts get a one-line reminder with the exact typed marker. Background task notifications, system reminders, and hook feedback are ignored as host text. A valid Outcome Brief closes the task, so the next request is classified afresh. Hooks fail open: an internal Brief-Spec error is reported to standard error and the host receives an empty decision rather than a blocked session.

Outcome Brief

A stable end-of-task contract. Seven fields, fixed order, five honest statuses.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#111720', 'primaryTextColor': '#F5F2EA', 'primaryBorderColor': '#A56BFF', 'lineColor': '#29313A', 'secondaryColor': '#070A0F', 'tertiaryColor': '#29313A', 'background': '#070A0F', 'mainBkg': '#111720', 'nodeBorder': '#A56BFF', 'clusterBkg': '#111720', 'titleColor': '#F5F2EA', 'edgeLabelBackground': '#111720'}}}%%
flowchart LR
    S["Status"] --> O["Outcome"]
    O --> H["Human action"]
    H --> P["Proof"]
    P --> G["Gaps"]
    G --> N["Next"]
    N --> X["Open"]

    style S fill:#111720,stroke:#29313A,color:#F5F2EA
    style O fill:#A56BFF,stroke:#A56BFF,color:#F5F2EA
    style H fill:#111720,stroke:#29313A,color:#F5F2EA
    style P fill:#111720,stroke:#29313A,color:#F5F2EA
    style G fill:#111720,stroke:#29313A,color:#F5F2EA
    style N fill:#111720,stroke:#29313A,color:#F5F2EA
    style X fill:#111720,stroke:#29313A,color:#F5F2EA

The contract

Status → Outcome → Human action → Proof → Gaps → Next → Open

Example

<!-- briefspec:outcome:v1 -->
## Outcome Brief

Status: REVIEW
Outcome: The Copilot plugin, project bridge, and hook adapter are implemented.
Human action: Review the generated repository files before enabling the cloud hook.

Proof:
- [direct/info] `.github/plugin/marketplace.json` — declares the Copilot plugin source
- [direct/pass] `brief-spec doctor copilot --scope project --probe` → synthetic hook passed

Gaps:
- An authenticated Copilot cloud run has not been observed in this environment.

Next:
- Run the cloud acceptance scenario and retain its run URL.

Open:
- Whether cloud checkpoints should persist beyond the job.
<!-- /briefspec -->

Proof items are prefixed [direct|derived|reported]/[pass|fail|info]. direct means you observed it yourself; derived means you inferred it; reported means someone else said so. See schemas/ for the machine-readable contracts.

A DECIDE brief works best with a decision card in Open:

Open:
- Options: SQS; Redis streams — Recommendation: SQS — Reversible: yes — Needed by: 2026-10-12

A DONE result with nothing left for the human may use the compact form, which keeps only Status, Outcome, and Proof. Brief-Spec reads the missing fields as None, so the canonical object is the same as the full form. Every other status needs all seven fields.

<!-- briefspec:outcome:v1 -->
## Outcome Brief

Status: DONE
Outcome: The parser now accepts empty input.
Proof: [direct/pass] `uv run pytest tests/test_parser.py` → 12 passed
<!-- /briefspec -->

Documentation

Why the skills exist

The CLI validates. The skills are how a chat agent finds the contract.

Eight work types

Each type has an ordered explanation profile loaded by the brief-spec router.

Four reading experiences

Harness support

brief-spec setup installs skills and lifecycle hooks for each harness. Project destinations vary by host.

The five required harnesses pass the live host matrix recorded in the verification record. Copilot, Cursor Agent, and Goose are experimental: they install and pass a synthetic hook probe, but no live host gate covers them. Kimi lifecycle hooks exist only in the user-wide plugin, so a Kimi project install adds skills only.

Codex runs a hook only after you approve it in /hooks, and codex exec skips unapproved hooks without an error. brief-spec doctor codex reports which Brief-Spec hooks are approved.

Project-scoped Copilot installation also creates the network-free bridge used by Copilot cloud coding agents:

.agents/skills/{brief-spec,outcome-brief,session-checkpoint}/
.github/brief-spec/brief-spec.pyz
.github/hooks/brief-spec.json
.github/instructions/brief-spec.instructions.md

The installer merges lifecycle hooks instead of replacing the host file, refuses to overwrite foreign skill files, restores prior files if installation fails, and records what it owns.

A .claude-plugin/ directory is present in this repository for local plugin development.

CLI

First journey

The journey below uses the published 0.6.0 release; see Install. The older v0.2.0 release installs only the briefspec command with install, uninstall, doctor, validate, config, and state.

# Install the published release
uv tool install brief-spec

# Verify the installation
brief-spec --version

# See the eight work types
brief-spec types list

# Classify bounded task text (no network)
echo "Review the authentication module" | brief-spec classify - --json

# Measure the classifier on the bundled labeled prompts
brief-spec eval

# Validate an Outcome Brief
brief-spec validate outcome path/to/handoff.md

# Validate a Checkpoint
brief-spec validate checkpoint path/to/checkpoint.md --mode spoken

# Install harness integrations
brief-spec setup codex
brief-spec setup all --scope user --require codex,claude,omp,grok,kimi

# Check installation health
brief-spec doctor all --scope user --probe --all-scopes

Export and verify

# Export to multiple formats
brief-spec export handoff.md \
  --formats markdown,json,html \
  --output-dir delivery/

# Bundle with manifest
brief-spec bundle handoff.md --output handoff.zip

# Verify the bundle
brief-spec verify handoff.zip --level rendered --offline --no-plugins

# Deliver with receipt
brief-spec deliver handoff.zip --to /path/to/deliveries/
brief-spec verify /path/to/deliveries/handoff.zip.receipt.json --level delivered

Verification levels are cumulative: structural → resolved → rendered → delivered. See docs/delivery.md for the complete export and verification reference.

Exports record the current Git commit. When verify runs inside the same repository, a freshness check reports whether the brief still describes HEAD.

brief-spec frame request.json --output frame.md renders a Human Frame from a BriefSpecFrameRequest/v1 request. It writes Markdown and a receipt. It does not approve or dispatch anything.

Notifications

brief-spec notify posts a brief to a chat channel or a webhook. It is one-way: Brief-Spec never reads replies and never approves or starts work.

Configure channels in ~/.local/state/brief-spec/config.toml or a project .brief-spec.toml. Config files may only name environment variables. Brief-Spec refuses a config that contains a URL or token, so the file is safe to commit.

[channels.eng]
kind = "slack-bot"
target = "C0123ABCD"               # channel id, not a secret
secret_env = "BRIEF_SPEC_SLACK_TOKEN"
when_status = ["BLOCKED", "DECIDE", "REVIEW"]

[channels.ops]
kind = "teams-workflow"
secret_env = "BRIEF_SPEC_TEAMS_URL"

[channels.ci]
kind = "webhook"
url_env = "BRIEF_SPEC_HOOK_URL"
secret_env = "BRIEF_SPEC_HOOK_SECRET"  # whsec_… signing secret, optional

brief-spec channels list
brief-spec notify handoff.md --to eng --dry-run          # show the exact payload, send nothing
brief-spec notify handoff.md --to eng --consent-network  # post it
brief-spec notify handoff.md --to all --consent-network  # every channel whose when_status matches
brief-spec ack decide.md --choice "SQS" --by luan        # record your decision

The chat card is Orient-style: status, outcome, human action, gaps, and next steps. Use template = "full" to include proof. A local send log prevents duplicate posts; --resend posts again. Receipts record the channel, message id, permalink, and hashes, never the secret.

To post every valid brief automatically when an agent stops, opt in explicitly:

[notify]
on_stop = true
consent_network = true
channels = ["eng"]

The Stop hook then starts a detached brief-spec notify process. A slow or failing channel never blocks or breaks the agent session.

Configuration

Create user or project configuration:

brief-spec config init
brief-spec config show
brief-spec config init --scope project --project /path/to/repository

Project values override user values. See docs/configuration.md for policy options.

Install

Brief-Spec requires Python 3.11+. The core package has no runtime dependencies.

1. Install the command

The recommended path is uv:

uv tool install brief-spec

To add the optional PDF and MP3 renderers in the same environment:

uv tool install brief-spec --with brief-spec-renderer-pdf --with brief-spec-renderer-audio

With pipx or pip:

pipx install brief-spec
# or, inside a virtual environment
pip install brief-spec brief-spec-renderer-pdf brief-spec-renderer-audio

The PyPI files are byte-identical to the wheels and sdists attached to the v0.6.0 GitHub release, and each carries a build attestation. To pin the version, use brief-spec==0.6.0.

2. Connect your harnesses

brief-spec setup all --scope user --require codex,claude
brief-spec doctor all --scope user --probe

--require stops setup if a listed harness is not installed. Add omp, grok, or kimi if you use them. Then:

• Codex: open Codex, run /hooks, and approve the five Brief-Spec hooks. Codex skips unapproved hooks without an error. brief-spec doctor codex shows which hooks are still unapproved.
• Claude Code: start a new session. The hooks load from ~/.claude/settings.json.

Upgrading from 0.5.0

uv tool upgrade brief-spec          # or: pip install --upgrade brief-spec
brief-spec setup all --scope user   # refresh the hooks and skills each harness runs
brief-spec doctor all --scope user --probe

DONE briefs now need a [direct/pass] proof; briefs exported by 0.5.0 still verify, with a warning.

Upgrading from v0.2.0

uv tool uninstall briefspec
uv tool install brief-spec
brief-spec setup all --scope user
brief-spec doctor all --scope user --probe

The command is now brief-spec; briefspec remains an alias. setup replaces install, which still works. State moves to ~/.local/state/brief-spec, or to $BRIEF_SPEC_HOME if set. The old state, receipts, and markers stay readable through 0.x.

Dogfood from checkout

uv tool install --force --reinstall \
  --with ./packages/brief-spec-renderer-pdf \
  --with ./packages/brief-spec-renderer-audio \
  .
brief-spec setup all --scope user --require codex,claude,omp,grok,kimi
brief-spec doctor all --scope user --probe --all-scopes

Project-scoped installation keeps the integration inside one repository:

brief-spec setup all --scope project --project /path/to/repository
brief-spec doctor all --scope project --project /path/to/repository --probe

Legacy release (v0.2.0)

uv tool install git+https://github.com/luanmorenommaciel/brief-spec.git@v0.2.0
briefspec install all --scope user
briefspec doctor all --probe

This older release uses the briefspec command and does not include work types, classification, exports, or the Grok, OMP, and Kimi integrations.

The tagged URL installs a versioned release instead of whatever happens to be on main.

Who this is for

Brief-Spec is for engineers and teams running multiple AI coding agents who want a predictable handoff without rebuilding their workflow.

Who this is not for

• If you want a second brain or knowledge graph, Brief-Spec is not that. Use Nexo, Obsidian, or your preferred knowledge system.
• If you want an agent orchestrator, Brief-Spec is not that. It is the human handoff, not the task executor.
• If you want to replace Git, CI, or your issue tracker, Brief-Spec is not that. Original evidence remains authoritative.

Brief-Spec is a presentation layer. The original repository, command output, document, or host transcript remains the source of truth.

Safety invariants

Brief-Spec compresses presentation, not provenance.

• A brief is never more authoritative than its source.
• A passing syntax check does not prove a live integration.
• A local commit does not prove publication.
• Planned work is not completed work.
• Direct, derived, and reported evidence must remain distinguishable.
• Unknown or unverified state is a gap, not a reason to infer success.
• Hooks fail open on internal errors.
• Installation refuses destructive overwrite of foreign files.
• Nothing is silently ingested into Nexo, Obsidian, or another knowledge system.

The JSON schemas in schemas/ define the portable data contracts.

Honest limits

• A consistent format cannot make an unsupported claim true.
• A checkpoint cannot recover evidence the host never exposed.
• Lifecycle automation depends on the events supported by each host version.
• Spoken Brief is text until a separate text-to-speech system renders it.
• Automatic checkpoint thresholds are heuristics and remain configurable.
• Brief-Spec reduces reading friction; high-risk changes still deserve direct inspection.
• Classification is local and approximate. On 150 independent conversational prompts it chooses the right type 69% of the time; run brief-spec eval to measure your own prompts. Use an explicit type: review (or any type) when it matters.
• Notifications are one-way. A Slack incoming webhook cannot thread or edit; use a bot token for that. Teams Workflows posts as the Flow bot and belongs to the user who created the flow.

Experimental: Human Continuity

The source tree contains an optional, independently versioned Chronicle extension. It does not change the frozen Outcome Brief or Session Checkpoint 1.0 contracts and is not part of the public 0.6.0 publication claims.

Chronicle is never activated globally. It records what Brief-Spec observed; it does not replace Seamwise intent, Task-Spec acceptance, Converge authorization, Git evidence, or reviewed durable knowledge.

Read the complete Human Continuity architecture.

Release truth

See the full changelog and verification record for the evidence boundary.

Repository map

skills/
  brief-spec/            Type router and eight compact profiles
  outcome-brief/         Stable terminal handoff
  session-checkpoint/    Orient, Teach, and Spoken Brief
src/brief_spec/          Canonical Python import
src/briefspec/
  adapters/              Host payload normalization
  delivery.py            Canonical envelope and core renderers
  notify.py              One-way Slack, Teams, Discord, Google Chat, and webhook posts
  work_types.py          Local classifier rules and the shipped Naive Bayes fallback
  evaluation.py          `brief-spec eval` scoring
  data/                  Classifier model and labeled evaluation prompts
  verification.py        Structural through delivered verification
  hooks.py               Safe-boundary and one-repair control
  installers.py          Transactional user/project integration
packages/
  brief-spec-renderer-pdf/    Optional HTML-to-PDF renderer
  brief-spec-renderer-audio/  Optional script-to-MP3 renderer
  brief-spec-chronicle/       Optional project continuity extension
  brief-spec-renderer-video/  Experimental Chronicle video renderer
schemas/                 Portable machine-readable contracts
docs/                    Theory, architecture, examples, installation

See docs/repository-layout.md for the complete ownership map.

Contributing

See CONTRIBUTING.md for development setup and quality gates.

git clone https://github.com/luanmorenommaciel/brief-spec.git
cd brief-spec
uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest --cov=briefspec --cov-report=term-missing

Uninstall

# Preview removal
brief-spec uninstall all --dry-run

# Remove user installation
brief-spec uninstall all

# Remove one project installation
brief-spec uninstall copilot --scope project --project /path/to/repository

Brief-Spec removes receipt-owned files only when their content still matches the installed hash.

License

MIT