Walden§

Spec-driven delivery kernel · Open source

Intention before code. Proof before completion.

Walden turns ideas into reviewed feature specifications and executes approved work through a deterministic, gated workflow. A Go CLI enforces the rules. An optional AI skill drafts the specs.

curl -fsSL https://raw.githubusercontent.com/andrearaponi/walden/main/install.sh | sh

Apache‑2.0  ·  Zero dependencies  ·  Pure Go standard library

Plan modes draft. Checklists suggest. Analysis advises. Walden enforces.

Blocking gates with exit codes — validation, proofs, freshness — independent of any model’s judgment.

§ 01 Two halves, one boundary

Walden draws a hard line between what a machine should decide and what a human should author. The non-deterministic work is drafted. The rules are enforced.

The skill drafts

  • Asks the clarifying questions
  • Writes requirements in EARS form
  • Designs architecture, weighs the alternatives
  • Breaks work into tasks, each with a proof
  • Reads past lessons before similar work

non-deterministic · proposes, never approves

The CLI enforces

  • phase order: requirements → design → tasks
  • document freshness & approval chains
  • AC traceability — 100% coverage required
  • a verification proof on every leaf task
  • stale-document detection & reconciliation

deterministic · the same answer every time

§ 02 How it works

Every feature moves through four phases. Each one has an approval gate that must pass before the next begins. Phases cannot be skipped.

  1. 01

    Requirements

    What the feature must do — EARS acceptance criteria with stable IDs like R1.AC1.

    validate · review · approve
  2. 02

    Design

    How it gets built — architecture, alternatives considered, tradeoffs, a coverage matrix.

    validate · review · approve
  3. 03

    Tasks

    What code to write, in order. Every leaf task traces to an AC and carries a proof.

    validate · review · approve
  4. 04

    Execute

    Build it. The CLI runs each verification proof — a task closes only when its proof passes.

    verify · complete

Change an already-approved document and everything downstream resets to draft. Execution stays blocked until the chain is reconciled. No code outruns its spec.

§ 03 Requirements that can't be vague

Every acceptance criterion takes exactly one of six EARS forms. The CLI validates the grammar — a single SHALL, the right keywords in the right place.

WHEN a task’s verification proof passes, the system SHALL mark the task complete.
Ubiquitous
the system SHALL …
Event-driven
WHEN … the system SHALL …
State-driven
WHILE … the system SHALL …
Optional
WHERE … the system SHALL …
Unwanted
IF … THEN the system SHALL …
Complex
WHILE … WHEN … the system SHALL …
§ 04 How you use it

One prompt in. A reviewed spec tree out — every gate passed, every proof recorded, nothing typed but the intent.

claude code — new session

you

We need a small, single-user todo app on the command line — add a task, list what’s still pending, mark one done, all kept in a plain-text file, POSIX shell only. Let’s use Walden.

The skill asks its questions, then drafts every artifact and stops at each gate for your approval. This is what it left behind — open a spec file ↓

todo-cli feature: todo-cli · all gates passed
  • todo-cli
  • .github
  • workflows
  • validate-walden.ymlthe CI gate
  • pull_request_template.md
  • .walden
  • specs
  • todo-cli
  • constitution.mdproject rules
  • lessons.mdpast lessons
  • tests
  • run.shthe proof
  • todobuilt from tasks

Every spec above carries its own frontmatter — status: approved, timestamps, the staleness chain. walden feature init, walden validate, walden review approve, walden task complete ran underneath to earn each of those badges. You never typed them. The feature is a toy; the ceremony isn’t — the same gates hold for the stack you actually ship on.

§ 05 The kernel under your stack

Walden doesn’t replace your agent, your IDE, or your spec tool. It is the gate they call — anything that runs a command and reads an exit code gets hard gates.

Your coding agent

Claude Code, Codex, Copilot, OpenCode — the skill ships inside the binary. It drafts the specs; the kernel enforces the gates.

walden skill install <agent> skill drafts · kernel enforces

Your CI

Gate every pull request that touches a spec. Validation runs headless and the exit code decides — no model in the loop.

walden validate <feature> --all --json exit ≠ 0 → merge blocked

Inside Kiro

Kiro’s hooks honor exit codes. Run the gate as a pre‑tool‑use hook: when validation fails, the action is blocked.

walden validate <feature> --all exit ≠ 0 → action blocked

Inside Spec Kit

Spec Kit workflows run shell steps. Put the gate between phases: the pipeline advances only when the kernel agrees.

walden validate <feature> --all exit ≠ 0 → workflow halts

The same gate returns the same answer in every host. Enforcement stops being a feature of your editor and becomes a property of the spec.

§ 06 Install

One command. The latest release binary lands in ~/.local/bin/walden, checksum-verified — then it installs its own AI skill for Claude Code, Codex, Copilot, or OpenCode. No Go toolchain, no clone. 

curl -fsSL https://raw.githubusercontent.com/andrearaponi/walden/main/install.sh | sh

Prefer the toolchain? go install github.com/andrearaponi/walden/cmd/walden@latest  ·  then walden skill install <agent>. Building from a clone? ./setup.sh still works.

§ 07 On the name
I went to the woods because I wished to live deliberately, to front only the essential facts of life.

— Henry David Thoreau, Walden, or Life in the Woods

Do fewer things, but do them with full attention. Software rarely does. Walden is an attempt to apply that discipline — to require intention before code, and proof before completion.