https://github.com/shiva936/draft
Draft — the workspace before your commit.
https://github.com/shiva936/draft
ai ai-agents ai-coding change-management cli code-review command-line-tool developer-productivity developer-tools devtools git human-in-the-loop local-first provenance rust software-supply-chain verification version-control workflow-automation
Last synced: 1 day ago
JSON representation
Draft — the workspace before your commit.
- Host: GitHub
- URL: https://github.com/shiva936/draft
- Owner: Shiva936
- License: apache-2.0
- Created: 2026-06-28T17:39:25.000Z (15 days ago)
- Default Branch: master
- Last Pushed: 2026-07-03T17:17:46.000Z (10 days ago)
- Last Synced: 2026-07-03T19:16:18.920Z (10 days ago)
- Topics: ai, ai-agents, ai-coding, change-management, cli, code-review, command-line-tool, developer-productivity, developer-tools, devtools, git, human-in-the-loop, local-first, provenance, rust, software-supply-chain, verification, version-control, workflow-automation
- Language: Rust
- Homepage:
- Size: 7.65 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
- Roadmap: ROADMAP.md
- Notice: NOTICE
Awesome Lists containing this project
README
Draft
Local-first review, verification, approval, receipts, and rollback for human + AI-generated software changes.
Quick Start
·
Why Draft
·
How It Works
·
Commands
·
Docs
·
Contributing
---
## What Is Draft?
**Draft** is a local-first compatibility layer for reviewing and controlling software changes before they become part of your real workflow.
It sits between your editor, AI agents, CLI tools, and external automation. Draft turns workspace changes into **ChangePacks** with evidence, verification results, review state, approval state, durable receipts, and safe rollback targets.
Draft is built for the new workflow where humans and AI agents both create code, but the project still needs a trusted review boundary.
```text
Editor / Agent
↓
Draft CLI + Review Cockpit
↓
ChangePacks + Evidence + Events + Receipts
↓
.draft/ local store
↓
Optional external tools via explicit hooks
```
Draft does **not** replace Git, editors, CI, agents, or deployment tools. It gives them a local, auditable compatibility layer.
## Why Draft?
AI agents can generate useful changes quickly, but fast generation creates a new problem: workspace noise.
Draft helps you turn that noise into reviewed, accountable, rollback-safe ChangePacks.
| Problem | What Draft Adds |
| ---------------------------------- | ---------------------------------------------------------------------- |
| AI changes are hard to trust | Changes are captured as named ChangePacks with evidence and provenance. |
| Review happens too late | Draft creates a local approval boundary before save/finalization. |
| Workspace state gets messy | Draft separates working noise from reviewed ChangePacks. |
| Hidden state can leak into changes | `.draft/` is hard-excluded everywhere. |
| Rollback is unclear | Rollback can target checkpoints, ChangePacks, or receipts. |
| External tools are too implicit | Hooks are explicit, local, opaque, policy-checked, and receipt-backed. |
| Teams need auditability | Events and receipts make every meaningful action explainable. |
## Core Principles
Draft is designed around a few strict rules:
* **Local-first:** project state lives in the workspace under `.draft/`.
* **Offline-capable:** core CLI flows do not require a network service.
* **Daemonless by default:** the CLI can run directly without a background daemon.
* **Tool-neutral:** Draft does not depend on a specific AI model, editor, code host, or agent runtime.
* **Append-only provenance:** meaningful actions are recorded as hash-chained events.
* **Review before save:** ChangePacks must pass the local review and approval boundary before finalization.
* **Safe rollback:** checkpoints, ChangePacks, and receipts can be used as rollback targets.
* **Hard `.draft/` exclusion:** Draft never includes its private state in ChangePacks, snapshots, saves, rollback plans, or hook candidate checks.
## Quick Start
Install the latest Draft release on Linux, macOS, or WSL:
```bash
curl -fsSL https://raw.githubusercontent.com/Shiva936/draft/master/install.sh | sh
```
Install the latest Draft release on native Windows PowerShell:
```powershell
irm https://raw.githubusercontent.com/Shiva936/draft/master/install.ps1 | iex
```
Then initialize Draft in a workspace:
```bash
draft init
```
Set your local identity:
```bash
draft config set identity.username "Ada"
draft config set identity.email "ada@example.com"
```
Create a checkpoint, make changes, package them, review them, approve them, and save them:
```bash
draft checkpoint "before change"
# Edit the workspace with your editor, script, or AI agent.
draft status
draft create "update app"
draft list
draft pack
draft verify -p
draft risk -p
draft review -p
draft approve -p --reason "reviewed"
draft save -p
draft receipt list
```
Developers can also build from source:
```bash
cargo build --workspace
cargo run -p draft-cli -- init
```
## The ChangePack Flow
Draft’s main object is a **ChangePack**.
A ChangePack is a local, reviewable unit of change. It contains the change set, evidence, verification results, review decisions, approval state, and event references needed to understand what happened.
Typical flow:
```text
draft init
draft checkpoint "before agent run"
agent/editor changes files
draft status
draft create "feature name"
draft verify -p
draft review -p
draft approve -p
draft save -p
draft rollback # when needed
```
## IDs And Targets
Draft uses stable ID prefixes:
```text
chk_ checkpoint
pck_ ChangePack
rcp_ receipt
```
Rollback accepts any of these:
```bash
draft rollback chk_
draft rollback pck_
draft rollback rcp_
```
Most ChangePack commands accept either a ChangePack ID or a unique ChangePack name:
```bash
draft verify -p pck_abc123
draft verify -p "update app"
```
## Commands
The v0.3.3 command surface is intentionally local and workspace-oriented.
```text
init doctor identity config hook
ignore status event checkpoint create
pack list candidate task verify
risk review approve reject compare
compose disperse save receipt storage
rollback close gc cockpit mcp
acp a2a
```
New in v0.3.3: the verified stable-base model — `draft init` creates a verified
stable base and `stable_head`, `draft save` finalizes packs with configurable
disposal (`merge_and_dispose`/`dispose_only`) gated by project-state
verification, save hooks run in before/after phases, saved packs are disposed
leaving compact receipt provenance, and `draft close`/`draft gc` handle safe
metadata removal and maintenance. A top-level `proto/` directory defines the
protocol contracts. Draft treats each changepack as an independent, composable,
portable, **signed**, locally verifiable unit of change — temporary until
saved. Event history is `draft event` — there is no `log` command; only
`--page` and `--limit` apply. See [CHANGELOG.md](CHANGELOG.md).
### ChangePack Commands
Create a new ChangePack:
```bash
draft create [-p ]
```
ChangePack names must be unique.
Show the current selected ChangePack:
```bash
draft pack
```
Select a ChangePack by ID or name:
```bash
draft pack -s
```
Delete a ChangePack by ID or name:
```bash
draft pack -d
```
Deleting a ChangePack preserves event history and receipts. Draft removes the pack directory, removes task/run records owned only by that pack, and garbage-collects unreachable objects.
List generated ChangePacks:
```bash
draft list
```
### Event Commands
Human-readable timeline:
```bash
draft event
```
Raw event records:
```bash
draft event --raw
```
Verify event, receipt, and transparency integrity:
```bash
draft doctor
draft receipt verify --all
```
Draft stores provenance as append-only hash-chained event records linked to signed receipts and the local transparency chain. The normal `draft event` timeline is a readable view derived from that raw stream; there is no separate durable human log file outside the event model.
### Candidate And Task Commands
Candidates are named execution profiles. They do not represent roles in v0.3.3.
Run a task with an explicit instruction boundary:
```bash
draft task spawn "" --
```
Route a task through a candidate:
```bash
draft task spawn "" -c --
```
Candidates can be auto-registered through `draft task spawn`; users do not need to run a separate candidate registration command first.
## Optional Save Hook
`hooks.save` lets Draft call an explicit local command after approval.
Example:
```bash
draft config set hooks.save "printf %s \"{{message}}\" > .last-draft-save"
```
When `draft save` runs, Draft:
1. renders supported hook variables such as `{{message}}`;
2. checks local policy;
3. verifies canonical approval, workspace hash, receipt signatures, event chain, and transparency linkage;
4. verifies that `.draft/` is not part of the save candidate;
5. executes the command from the workspace root;
6. captures stdout, stderr, exit code, and command hash;
7. writes a durable receipt.
Draft does not parse, detect, or model what the hook command does. Hooks are opaque by design.
## Storage And Safety
Draft stores local project state under `.draft/`:
```text
.draft/
├─ config and policy
├─ content-addressed objects
├─ snapshots and checkpoints
├─ tasks and runs
├─ ChangePacks and evidence
├─ reviews and approvals
├─ receipts
├─ rebuildable indexes
└─ append-only hash-chained events
```
`.draft/` is always hard-excluded from:
```text
status
snapshots
ChangePacks
save candidates
rollback plans
hook candidate checks
```
If a save candidate contains `.draft/`, Draft aborts the save, emits a failed `save.completed` event, records a failed receipt, and does not run `hooks.save`.
## What Draft Is Not
Draft is not:
* a Git replacement;
* a hosted code review system;
* a hosted merge workflow;
* a CI/CD platform;
* an AI model service;
* an agent framework;
* a deployment tool.
Draft is the local review layer that can sit in front of those tools.
## Documentation
Start with [docs/README.md](docs/README.md).
| Topic | Link |
| ------------------ | -------------------------------------------------------- |
| Installation | [docs/installation.md](docs/installation.md) |
| Getting Started | [docs/getting-started.md](docs/getting-started.md) |
| Concepts | [docs/concepts.md](docs/concepts.md) |
| Architecture | [docs/architecture.md](docs/architecture.md) |
| Command Reference | [docs/command-reference.md](docs/command-reference.md) |
| Configuration | [docs/configuration.md](docs/configuration.md) |
| Storage Layout | [docs/storage-layout.md](docs/storage-layout.md) |
| Event Model | [docs/event-model.md](docs/event-model.md) |
| ChangePacks | [docs/changepack.md](docs/changepack.md) |
| Protocol Contracts | [docs/protocol.md](docs/protocol.md) |
| Checkpoints | [docs/checkpoints.md](docs/checkpoints.md) |
| Verification | [docs/verification.md](docs/verification.md) |
| Review & Approval | [docs/review-and-approval.md](docs/review-and-approval.md) |
| Policy | [docs/policy.md](docs/policy.md) |
| Candidates & Tasks | [docs/candidates-and-tasks.md](docs/candidates-and-tasks.md) |
| Safety Model | [docs/safety-model.md](docs/safety-model.md) |
| Services | [docs/services.md](docs/services.md) |
| Security | [docs/security.md](docs/security.md) |
| Release Compliance | [docs/release-compliance.md](docs/release-compliance.md) |
| FAQ | [docs/faq.md](docs/faq.md) |
## Development
Run the standard checks:
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```
Useful local loop:
```bash
cargo run -p draft-cli -- init
cargo run -p draft-cli -- status
cargo run -p draft-cli -- create "test changepack"
cargo run -p draft-cli -- list
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, development workflow, and release expectations.
## Project Status
Draft is pre-1.0 software. The current focus is v0.3.3 production readiness:
* CLI ergonomics;
* verified, signed, portable changepacks;
* AG-UI review cockpit flows;
* event, receipt, and transparency integrity;
* import/export and rollback safety;
* documentation alignment;
* security, performance, and release compliance.
Public APIs and storage details may still evolve before 1.0.
## License
Licensed under the terms in [LICENSE](LICENSE).