ledger

Ledger — Auditable AI-Assisted Development Protocol

A lightweight protocol framework for auditable human-AI software development | v0.2.0 中文: README.zh.md

---

What is it

Ledger is a lightweight protocol framework for building software with AI while keeping product intent, implementation scope, and verification evidence explicit.

It turns AI-assisted development from an open-ended chat into a staged workflow: define intent, write a behavior contract, implement against that contract, verify with real outputs, then archive what changed.

Ledger keeps the daily feature loop lightweight, but feature work is anchored by two global spines: the Product Spine in PAD.md and the Architecture Spine in architecture.md. A feature should explain where it fits in the core business flow and which module / entity boundaries it touches before it enters build.

Ledger is designed for product-minded builders, solo developers, and small teams who want AI to move faster without losing control of scope, state, and quality.

It is not a code generator, an agent scheduler, or a replacement for CI/CD. It is the protocol layer that keeps human decisions and AI execution aligned.

Core idea: Define behavior before implementation. Verify behavior before shipping.

---

Skills System

Ledger v0.2.x uses a skills-based architecture. Skills are composable protocol documents that guide the agent through each phase. They auto-trigger based on project state.

Skill	Phase	Purpose
using-ledger	Session start	State awareness, phase routing, guard enforcement
ledger-scope	Pre-feature	Ledger applicability assessment
ledger-pid	pid	Intent definition + boundary detection
ledger-contract	contract	Behavior contract generation
ledger-build	build	TDD implementation with complexity scoring
ledger-verify	verify	Subagent-driven adversarial verification
ledger-ship	ship	Test suite, acceptance, archive
ledger-retro	Every 3-5 features	Protocol quality review

How it works:

• A SessionStart hook detects .ledger/ in the project and injects using-ledger into the agent context
• The agent reads state.md to determine the current phase
• The matching skill is loaded automatically or via the Skill tool
• Guards enforce phase entry requirements before execution

In Claude Code, skills are provided via a plugin.

---

When to use Ledger

Use Ledger when:

• You are building a product with AI assistance and need the work to remain auditable.
• You want clear handoffs between product intent, implementation, verification, and release.
• You are a solo developer, product-minded builder, or small team working feature by feature.
• You prefer explicit contracts and checkpoints over relying on long prompts.

Avoid Ledger when:

• You need a general-purpose task manager or multi-agent scheduler.
• You need deployment, monitoring, incident response, or CI/CD orchestration.
• You are solving high-risk security, financial, concurrency, or performance problems without specialist review.

---

Scope

Before adopting, check whether your project falls within Ledger's applicable scope.

Detected but not solved (framework halts, expects external specialist input)

• Transaction consistency and concurrency races — boundaries B-H02 / B-H05
• Financial operations and sensitive data — boundaries B-H03 / B-H06
• Cross-user aggregation / real-time communication — boundaries B-H01 / B-H04
• Code performance (N+1, slow queries, etc.) — runtime boundary scan in /ledger.build

Ledger will actively stop you in these situations but does not propose solutions. Pair with specialized reviews (security / performance / DBA). The detect-and-halt behavior is itself one of the framework's deliverables.

Entirely outside framework scope

• Production deployment, monitoring, alerting
• Multi-developer concurrent development conflicts
• CI/CD pipelines and release management

Ledger does not engage with these — use other toolchains.

---

Quick Start

Install details: INSTALL.md Full usage guide: USAGE.md Global Spine Lite guide: docs/concepts/global-spine-lite.md Design Attachments Lite guide: docs/concepts/design-attachments-lite.md Existing project adoption: docs/migration/adopt-global-spine-lite.md

# Recommended: install directly into a project from GitHub
curl -fsSL https://raw.githubusercontent.com/Hypho/ledger-protocol/master/scripts/install-from-github.sh | bash -s -- --target your-project --mode auto