Metadata-Version: 2.5
Name: brief-spec
Version: 0.6.0
Summary: Type-aware, evidence-backed delivery contracts for AI coding harnesses.
Project-URL: Homepage, https://github.com/luanmorenommaciel/brief-spec
Project-URL: Repository, https://github.com/luanmorenommaciel/brief-spec
Project-URL: Issues, https://github.com/luanmorenommaciel/brief-spec/issues
Author: Luan Moreno Maciel
License: MIT License
        
        Copyright (c) 2026 Luan Moreno Maciel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,brief-spec,claude,codex,copilot,developer-tools,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Brief-Spec

<p align="center">
  <img src="assets/lockup-hero.png" alt="BRIEF-SPEC — Different agents in. One predictable human handoff out." width="100%">
</p>

<p align="center"><strong>Different agents in. One predictable human handoff out.</strong></p>

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.

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%2B-A56BFF?labelColor=111720" alt="Python 3.11+"></a>
  <a href="https://github.com/luanmorenommaciel/brief-spec/releases/tag/v0.6.0"><img src="https://img.shields.io/badge/public_release-v0.6.0-070A0F?labelColor=111720" alt="Public release v0.6.0"></a>
  <a href="https://pypi.org/project/brief-spec/"><img src="https://img.shields.io/badge/pypi-brief--spec_0.6.0-29313A?labelColor=111720" alt="PyPI brief-spec 0.6.0"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-29313A?labelColor=111720" alt="MIT License"></a>
</p>

**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](#whats-new-in-060) · [Notifications](#notifications) · [The problem](#the-problem) · [How it works](#how-it-works) · [Outcome Brief](#outcome-brief) · [Docs](#documentation) · [Skills](#why-the-skills-exist) · [Harness](#harness-support) · [CLI](#cli) · [Install](#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](#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](CHANGELOG.md#050---2026-10-08). The
full 0.6.0 list is in the [changelog](CHANGELOG.md#060---2026-10-08).

---

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

![The same engineering session without Brief-Spec as a dense, irregular chat and with Brief-Spec as a calm, consistently structured handoff.](assets/briefspec-before-after.png)

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

![Scattered session evidence flows into a Brief-Spec Outcome Brief and emerges as three directly answered human questions, while proof and unresolved boundaries remain visible.](assets/briefspec-output-comparison.png)

---

## How it works

<p align="center">
  <img src="assets/flow.png" alt="How Brief-Spec works — host task through adapter, local type classification, and type-specific explanation; at a boundary a Checkpoint (Orient, Teach, or Spoken) or an Outcome Brief becomes a canonical delivery object and verified downloads, with inspectable proof from a repository, command, test, URL, or artifact." width="100%">
</p>

<details>
<summary>View diagram source</summary>

```mermaid
%%{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
```

</details>

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.

<p align="center">
  <img src="assets/contract.png" alt="Outcome Brief seven-field contract in order — Status, Outcome, Human action, Proof, Gaps, Next, Open — with Outcome in Ion Violet. Statuses: DONE, REVIEW, DECIDE, BLOCKED, FAILED." width="100%">
</p>

<details>
<summary>View diagram source</summary>

```mermaid
%%{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
```

</details>

### The contract

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

| Status | Meaning | Constraints |
| --- | --- | --- |
| `DONE` | Requested outcome achieved and directly verified | No required action, no unresolved gaps, at least one `[direct/pass]` proof, no failing proof |
| `REVIEW` | Implementation ready for human inspection | Requires human action |
| `DECIDE` | A meaningful choice is required | Requires human action and an open decision |
| `BLOCKED` | External dependency prevents continuation | Requires a gap and a next action |
| `FAILED` | The attempt did not achieve the requested outcome | Requires a gap and a next action |

### Example

```markdown
<!-- 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/`](schemas/) for the machine-readable contracts.

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

```text
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.

```markdown
<!-- 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

| Topic | Link |
| --- | --- |
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
| Skills reference | [docs/skills.md](docs/skills.md) |
| Installation | [docs/installation.md](docs/installation.md) |
| Configuration | [docs/configuration.md](docs/configuration.md) |
| Architecture | [docs/architecture.md](docs/architecture.md) |
| Behavior examples | [docs/examples.md](docs/examples.md) |
| Human Continuity | [docs/human-continuity.md](docs/human-continuity.md) |
| Repository layout | [docs/repository-layout.md](docs/repository-layout.md) |
| Verified delivery | [docs/delivery.md](docs/delivery.md) |
| Compatibility | [docs/compatibility.md](docs/compatibility.md) |
| Verification record | [docs/verification.md](docs/verification.md) |
| Design theory | [docs/theory.md](docs/theory.md) |
| Brand assets | [assets/ASSETS.md](assets/ASSETS.md) |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Security | [SECURITY.md](SECURITY.md) |

---

## Why the skills exist

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

<table>
<thead>
<tr>
<th>Skill</th>
<th>Why it exists</th>
<th>When / not</th>
<th>Gate</th>
<th>Optional?</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>brief-spec</code></td>
<td>Classify substantive work and shape the full explanation for the selected profile</td>
<td>
<strong>When</strong> a task begins or clearly pivots; when the user asks Brief-Spec to explain work; or when a lifecycle hook supplies a type decision.<br>
<strong>Not</strong> sending task text to another model or network; inventing Grok classification metadata.
</td>
<td><code>brief-spec classify</code></td>
<td>No</td>
</tr>
<tr>
<td><code>outcome-brief</code></td>
<td>Close substantive work with a consistently ordered, evidence-backed handoff</td>
<td>
<strong>When</strong> a task reaches a terminal outcome; when the user asks what shipped, what changed, what needs attention, or what happens next; or when a host hook requests a valid outcome.<br>
<strong>Not</strong> turning formatting into proof; claiming DONE with required action or unresolved gaps.
</td>
<td><code>brief-spec validate outcome</code></td>
<td>No</td>
</tr>
<tr>
<td><code>session-checkpoint</code></td>
<td>Re-orient a long, dense, or interruption-prone session without replacing the underlying evidence</td>
<td>
<strong>When</strong> the user asks for a recap, orientation, teaching explanation, or spoken summary; many turns or tool calls; before compaction; or a hook says a checkpoint is eligible.<br>
<strong>Not</strong> treating spoken mode as audio generation; claiming the checkpoint is canonical project memory; silently ingesting into Nexo or Obsidian.
</td>
<td><code>brief-spec validate checkpoint</code></td>
<td>No</td>
</tr>
</tbody>
</table>

### Eight work types

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

| Type | Explanation order |
| --- | --- |
| `general` | Answer, rationale, next action |
| `exploration` | Question, system map, entry points, flow, unknowns, next probe |
| `review` | Scope, verdict, findings, risk, validation, recommendation |
| `implementation` | Intent, changes, resulting behavior, verification, tradeoffs |
| `debugging` | Symptom, root cause, fix, regression protection, residual risk |
| `planning` | Goal, decisions, approach, sequence, gates |
| `research` | Question, synthesis, evidence quality, limitations, recommendation |
| `operations` | Event, impact, current state, actions, recovery, follow-up |

### Four reading experiences

| Experience | Purpose |
| --- | --- |
| **Outcome** | Terminal handoff: what is true, what requires the human, what proves the claim |
| **Orient** | 30–45 second operational scan: where we are, what changed, next move |
| **Teach** | Plain-language mental model: what we did, why it works, example, watch-outs |
| **Spoken** | 80–240 word sequential script designed to be heard |

---

## Harness support

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

| Harness | Status | Command | Project destination |
| --- | --- | --- | --- |
| Codex | Required | `brief-spec setup codex` | `.codex/`, `.agents/skills/` |
| Claude Code | Required | `brief-spec setup claude` | `.claude/` |
| OMP | Required | `brief-spec setup omp` | `.omp/` |
| Grok Build | Required | `brief-spec setup grok` | `.grok/` |
| Kimi Code | Required | `brief-spec setup kimi` | `.kimi-code/skills/` (skills only) |
| Copilot | Experimental | `brief-spec setup copilot --scope project` | `.agents/skills/`, `.github/` |
| Cursor Agent | Experimental | `brief-spec setup cursor` | `.cursor/` |
| Goose | Experimental | `brief-spec setup goose` | `.agents/skills/`, `.goose/` |

The five required harnesses pass the live host matrix recorded in the [verification record](docs/verification.md). 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:

```text
.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](#install). The older
`v0.2.0` release installs only the `briefspec` command with `install`, `uninstall`, `doctor`,
`validate`, `config`, and `state`.

```bash
# 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

```bash
# 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](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.

| Kind | Where it posts | Threads follow-ups | Updates the first message | Attachments |
| --- | --- | --- | --- | --- |
| `slack-webhook` | Slack incoming webhook | No | No | No |
| `slack-bot` | Slack `chat.postMessage` with a bot token | Yes | Yes | Yes (`--attach`) |
| `teams-workflow` | Microsoft Teams Workflows webhook (Adaptive Card) | No | No | No |
| `discord` | Discord webhook | Via `target` thread id | No | No |
| `google-chat` | Google Chat webhook | Yes | No | No |
| `webhook` | Any HTTPS endpoint, signed per Standard Webhooks | n/a | n/a | n/a |

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.

```toml
[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
```

```bash
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:

```toml
[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:

```bash
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](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`:

```bash
uv tool install brief-spec
```

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

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

With `pipx` or `pip`:

```bash
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](https://github.com/luanmorenommaciel/brief-spec/releases/tag/v0.6.0), and each
carries a build attestation. To pin the version, use `brief-spec==0.6.0`.

### 2. Connect your harnesses

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

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

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

```bash
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:

```bash
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)

```bash
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/`](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](docs/human-continuity.md).

---

## Release truth

| Version | State | Notes |
| --- | --- | --- |
| v0.6.0 | Published on GitHub and PyPI | Latest public release |
| v0.5.0 | Published on GitHub and PyPI | Previous release |
| v0.2.0 | Published GitHub release | Historical release |
| 0.3.0, 0.4.0 | Unpublished | Folded into 0.5.0 |

See the full [changelog](CHANGELOG.md) and [verification record](docs/verification.md) for the evidence boundary.

---

## Repository map

```text
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](docs/repository-layout.md) for the complete ownership map.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and quality gates.

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

```bash
# 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](LICENSE)
