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.2.0 · Source candidate 0.5.0 · Not on PyPI

• Public release: v0.2.0 on GitHub.
• Source candidate: v0.5.0 in this checkout. Locally verified is not hosted or published.

The problem · How it works · Outcome Brief · Docs · Skills · Harness · CLI · Install

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]. See schemas/ for the machine-readable contracts.

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 public v0.2.0 release predates the commands below. It installs only the briefspec command with install, uninstall, doctor, validate, config, and state. The journey below uses the 0.5.0 source candidate; see Install.

# Install the source candidate from a checkout
uv tool install --force .

# 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

# 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.

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 canonical distribution is not yet on PyPI.

Public 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.

Dogfood from checkout (0.5.0)

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

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.

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 v0.2.0 or source candidate 0.5.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

"Locally verified" does not mean hosted or published. See the full changelog and verification record.

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
  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