AgentCulture
MenuClose

devague

Every feature starts as a vague idea, and most tooling rushes it straight to code. devague goes the other way: a small command-line tool that walks the idea backwards — from the announcement you wish you could make, to a spec you can defend, to a plan you can hand to a workforce — and then keeps score while the workforce builds, so what you ship is what you can prove.

Seven legs, one deterministic CLI, and a human gate at every point where a machine might otherwise grade its own work. This page is the tour, and the proof.

the pipeline

A vague idea in, an accountable delivery out — and no model in the middle

The arc is seven legs: scope the idea, think it backwards into a spec, challenge that spec for the blind spots it still hides, plan it forwards, fan the plan out to a workforce, stop for every deviation the build forces, then summarize what was actually delivered. Three engines share one CLI — the frame engine works backwards from the announcement, the plan engine works forwards from that spec, and the delivery ledger keeps score from the first departure to the final summary.

Here is the part that surprises people: there is no model inside. devague makes zero LLM calls — it is a small, deterministic, fully unit-tested Python CLI, not an agent, service, or daemon. Its state is plain JSON under .devague/ in the repo you are speccing. Your agent proposes; devague keeps score. That split is the whole design.

And the seam where execution begins is deliberate. The CLI describes the build — plan waves says what can run in parallel, plan deliverables says what exists once every task completes — and there its writ ends. Operators take over at the seam; devague follows the build from the ledger.

  1. ideaannouncement
  2. framecapture · confirm
  3. convergegate
  4. specexport
  5. challengeblind spots
  6. wavesplan
  7. buildworkforce
  8. deviateledger
  9. summaryartifact
The whole arc in one pass: claims arrive proposed, a human confirms them, and the converge gate stays shut until the frame closes — then the spec exports. A challenge pass hunts its blind spots and a human adjudicates what it finds, and the re-exported spec fans out into the waves a workforce builds. Where the build must leave that plan, the run stops and the approved departure lands on the deviate ledger; the closing summary reconciles planned against actual — the accountability artifact.

  1. the frame engine — before there is a frame

    idea → scope

    survey the surfaces the idea touches before framing it; each finding lands as first-class state citing what was actually read — provenance, not disclaimers

    • scope "<surface>" --finding
    • --seeds
    • --list

  2. the frame engine

    idea → spec

    works backwards from the announcement, capturing and pressure-testing every claim it makes

    • new
    • capture
    • interrogate
    • park
    • converge
    • export

  3. the frame engine — reopened by the pass

    spec → challenged spec

    the blind-spot hunt, scaled to risk: findings land proposed for the human through the existing moves; a clean pass records the lenses examined and the residual risk still parked — never a claim of no unknown unknowns

    • capture
    • interrogate
    • question
    • park
    • scope → reconverge
    • re-export

  4. the plan engine

    spec → plan

    works forwards: tasks that cover every confirmed target, each with acceptance criteria and an honest dependency order — amendable without starting over

    • plan new
    • task
    • accept
    • depend
    • cover
    • amend
    • converge
    • export

  5. an operator — never the CLI

    plan → build

    the execution seam: devague describes the dependency waves and the end state, deterministically; an operator performs the fan-out

    • plan waves
    • plan deliverables → parallel fan-out

  6. the delivery ledger

    during the build

    the moment execution must leave the confirmed plan, the run stops; the approved departure lands as an append-only record — never folded silently into drift

    • deviate
    • --confirm
    • --reject
    • --list

  7. the delivery ledger

    after the build

    planned versus actual, mid-work decisions, classified drift, evidence-backed claims, remaining work — rendered from state alone, on complete, partial, and failed runs

    • summary
    • summary --pr
the method

Start from the announcement — pretend it already shipped

When the idea touches an existing codebase, the method opens before the announcement: scope. Survey the surfaces the idea reaches — code, docs, CI, the repos next door — and record each finding with what was actually read, so the frame starts seeded with provenance instead of guesses. It scales with the idea: small ones skip straight to the announcement, and no wizard insists.

The frame itself is called the announcement frame, and it opens with one question: pretend this shipped successfully — what would you announce? Every claim that announcement makes becomes an object devague can track.

You capture claims by kind — who it is for, what changed for them, what you are not promising. You interrogate each one: what must be true for this line to be honest? And when something is genuinely unknown, you do not paper over it — you park it, as first-class vagueness on the record.

Then the gate. converge lists every gap still standing between the frame and a spec, and export refuses to write one until the list is empty. Convergence has to mean something — otherwise the spec is just confident prose.

  1. 01 · scope

    What does this idea actually touch?

    survey the surfaces before framing — findings land on the frame, each citing what was read

  2. 02 · new

    What are we saying shipped?

    start a frame from the announcement

  3. 03 · capture

    What does the announcement claim?

    record and classify a claim — audience, after-state, boundary, success signal

  4. 04 · interrogate

    What must be true for this to be honest?

    attach honesty conditions and hard questions to a claim

  5. 05 · park

    What do we honestly not know yet?

    record open vagueness as first-class state instead of forcing an answer

  6. 06 · converge

    Is this solid enough to build from?

    list every gap still standing between the frame and a spec

  7. 07 · export

    Then, and only then —

    write the buildable spec; refused until converge passes

the human gate

The agent can never confirm its own proposal

devague is built for agent-driven development, and one rule is load-bearing: claims an LLM proposes land as proposed, and they stay proposed until a human confirms them. The agent can propose all day; it cannot confirm its own work. No fabricated rigor.

A rule like that only survives if it is ergonomic, so the loop is three commands. review writes a durable artifact listing every proposal awaiting a decision. You read it, mark each line confirm or reject, and apply it. And confirm is transactional — hand it one bad id and nothing changes at all.

And the rule does not stop at the spec. When a build must leave the confirmed plan, the run stops and the departure lands exactly the way a claim does: proposed if an agent raised it, approved only by you, classified acceptable, risky, or needs-follow-up. It is not a fourth gate — it is the owner of the plan gate amending it, one in-flight decision at a time, on an append-only ledger.

  • · review

    Review what's proposed

    writes .devague/reviews/<slug>.md — a durable artifact of every proposal awaiting a human decision

    human gate
    devague review

  • · confirm

    Confirm a batch of claims

    transactional — one bad id in the batch and nothing changes at all

    human gate
    devague confirm c2 h1 h3

  • · confirm

    Confirm from an edited file

    applies the confirm/reject decisions from an edited review file

    human gate
    devague confirm --from-review <file>

  • · reject

    Reject a claim

    the other half of the gate — a rejected claim stays on the record as rejected, not deleted

    human gate
    devague reject c3

  • · deviate

    Flag a deviation from plan

    mid-build, the same rule — an agent-raised deviation lands as proposed, with a reason and a classification, never as approved

    human gate
    devague deviate "…" --task t3 --origin llm

  • · deviate

    Confirm a deviation

    user-only, like every confirm — you approve that specific departure, or --reject it; either way it stays on the ledger

    human gate
    devague deviate --confirm d1
the operator skills

devague keeps score; operators make the moves

Around the CLI sit seven operator skills — authored in the devague repo, broadcast to the AgentCulture mesh — one per leg: /scope surveys before the frame, /think walks an idea to an exported spec, /challenge pressure-tests that exported spec for blind spots before planning, /spec-to-plan walks the challenged spec to an exported plan, /assign-to-workforce fans the plan out to a parallel workforce, /deviate stops the run when execution must leave the plan, and /summarize-delivery closes the loop.

Note what devague itself never does: orchestrate. devague plan waves only describes the dependency graph — deterministic metadata, nothing more. Spawning agents, managing worktrees, gating merges: that is the operator's job. The tool that keeps score should not also play the game.

  • idea → scope

    /scope

    survey the surfaces the idea touches before framing — each finding lands on the frame citing what was actually read

  • idea → spec

    /think

    drive the frame engine — announce, capture, interrogate, park; export once the frame converges

  • between spec and plan

    /challenge

    run a risk-scaled blind-spot pass over the exported spec — findings land proposed for the human, and a clean pass records the lenses examined and the residual uncertainty, never a claim of no unknown unknowns

  • spec → plan

    /spec-to-plan

    drive the plan engine — tasks that cover every confirmed target, with acceptance criteria and honest dependencies

  • plan → build

    /assign-to-workforce

    fan the plan's waves out to parallel agents in isolated git worktrees, with TDD-gated merges — the human owns three gates: the spec, the split plan, the final PR

  • during the build

    /deviate

    stop the run the moment execution must leave the plan; the approved departure lands on the ledger before work resumes

  • after the build

    /summarize-delivery

    record planned versus actual, mid-work decisions, classified drift, and evidence-backed claims — on complete, partial, and failed runs alike

real captures

This page specced itself — three times now

Three real working sessions are replayed below — recorded live, never edited, never reworded. Each is told twice: first the story in plain language, then the terminal record it comes from. The human gate is real, not ceremony.

Session 1 · 14 July 2026 · devague 0.17

The page specs itself

Before this page was built, the team ran devague on the idea of the page. One sentence — "imagine this page is live: what does it contain?" — was broken into eighteen separate promises. A human approved or rejected every one. Only when each promise had an answer did the tool write the final spec — and the build plan's first task was to record this very session, so you can read it below.

  1. One sentence, pretended true

    The method starts by pretending the work is finished: describe the launch you wish you could announce. The tool turns that one sentence into a frame — a container for every promise the announcement quietly makes.

    devague new "agentculture.org/agents/devague is live — a presentation-grade page introducing devague: the CLI that turns a vague idea into a buildable spec, then a buildable plan, by working backwards; the page presents the method (announcement frame, interrogation, convergence, human review loop), the command surface, real captured sessions, and a what's-next drawn from its issue tracker — good enough that Ori can present by just showing the page"

    created frame 'agentculture-org-agents-devague-is-live-a-presenta' (announcement = c1)

  2. Promises land as "proposed"

    Each promise is captured one at a time. Watch the last word of the reply: proposed. The AI suggested it — nobody has agreed to it yet.

    devague capture --origin llm --kind audience "A live-presentation audience first: Ori presents and just shows this page while explaining. Secondarily, humans and agents browsing agentculture.org/agents/."

    captured c2 (audience, proposed)

  3. Reality answers mid-session

    Earlier the session hit a question it couldn't answer: the code was private but the package public — where should links point? While that question sat open, Ori made the repository public in real life. The session resolved its own question with something that had just actually happened.

    devague question --resolve q1 --decision "Repo made public (Apache-2.0) on 2026-07-14, ahead of this page; the card and page link GitHub like every other /agents/ entry, with PyPI as the install artifact."

    q1 -> resolved

  4. Fifteen yes, six no

    A human went through every promise. Fifteen were approved — and six were rejected outright, on the record. Rejection is a first-class outcome here, not a failure.

    devague reject c3 c9 c12 h1 h4 h7

    c3 -> rejected

    c9 -> rejected

    c12 -> rejected

    h1 -> rejected

    h4 -> rejected

    h7 -> rejected

  5. "The USER decides"

    When asked for status, the tool listed seven promises still undecided — and look at how it phrases the next step. It will not decide for you.

    recommended next move (first gap):

    this is an LLM proposal — the USER decides: devague confirm c15 (or reject c15)

  6. Converged — and a plan in waves

    With every promise settled, the spec became a build plan, and the plan sorted itself into waves — what can be built in parallel, and what has to wait. The first task in wave zero: record this session.

    devague plan waves

    wave 0: t1, t2, t3, t6

    wave 1: t4

    wave 2: t5

    wave 3: t7

    wave 4: t8

    wave 5: t9

frame legframe — announce & captureorg repo · frame leg · devague /thinkdevague 0.17.0 · captured 2026-07-14
$ devague new "agentculture.org/agents/devague is live — a presentation-grade page introducing devague: the CLI that turns a vague idea into a buildable spec, then a buildable plan, by working backwards; the page presents the method (announcement frame, interrogation, convergence, human review loop), the command surface, real captured sessions, and a what's-next drawn from its issue tracker — good enough that Ori can present by just showing the page"
created frame 'agentculture-org-agents-devague-is-live-a-presenta' (announcement = c1)
$ devague capture --origin llm --kind audience "A live-presentation audience first: Ori presents and just shows this page while explaining. Secondarily, humans and agents browsing agentculture.org/agents/."
captured c2 (audience, proposed)
$ devague capture --origin llm --kind after_state "agentculture.org/agents/devague presents devague end to end: the idea-to-spec-to-plan pipeline, the announcement-frame method (capture, interrogate, park, converge, export), the human review loop (proposals stay proposed until a human confirms), the deterministic no-LLM CLI, the operator skills (/think, /spec-to-plan, /assign-to-workforce), real captured sessions, and a what's-next drawn from the open issue tracker. The /agents/ directory gains a devague card linking to the page."
captured c4 (after_state, proposed)
… (why_it_matters c5, boundary c6 captures elided)
$ devague capture --origin llm --kind success_signal "Same measurable floor as /agents/lobes: Lighthouse performance and accessibility >= 95 on the built page, light and dark themes both pass WCAG AA, animations compositor-only honoring prefers-reduced-motion, zero client-side network calls; plus an explicit presentable-as-is preview sign-off from Ori before merge/deploy."
captured c8 (success_signal, proposed)
$ devague capture --origin llm --kind decision "Centerpiece demo is the dogfood loop: the captured session shown on the page is the real devague frame that specced this very page — announcement to converge to export — so the page demonstrates the tool by exhibiting its own origin."
captured c13 (decision, proposed)

Session 2 · 15 July 2026 · devague 0.18

The tool outgrows its own page

By the next day the tool had grown three new abilities — which made this page out of date the moment they shipped. So the page went back through its own process. This session ran before the seventh leg existed, and its transcript honestly announces the method as it then stood: one leg shorter. This time, the tool refused to finish until the missing evidence arrived.

  1. Look first, then promise

    New in this version: before promising anything, the session reads the real files and writes down what it found — with receipts naming exactly what was read.

    devague scope "site-astro/src/data/devague.ts" --finding "carries all page copy: fact chips incl. 'public since 2026-07-14' and 'version 0.17.2 — 2026-07-14', the went-public hero paragraph, a 3-stage pipeline, 3 skill cards, and whatsNext linking #62/#68/#69/#70 — all closed by 0.18.0" --seeds c3 c5

    recorded s1 (site-astro/src/data/devague.ts)

  2. The gate refuses

    Six promises still had no evidence behind them. The tool didn't warn — it refused, and listed exactly what was missing.

    devague export

    error: frame has not converged; cannot export

    hint: resolve: claim c2 has no confirmed honesty condition; claim c3 has no confirmed honesty condition; claim c8 has no confirmed honesty condition; claim c9 has no confirmed honesty condition; claim c11 has no confirmed honesty condition; claim c12 has no confirmed honesty condition

  3. Ori decides, live

    Then a human typed an instruction directly. Watch the last word — every AI suggestion above needed explicit approval, but a person's own words are trusted the moment they land.

    devague capture --kind decision "Ori loves the page's animations: every existing animated beat is preserved, and the new steps get their own animated beats — the DevagueFlow arc's execution-seam stages animate in the same compositor-only language, and every new capture pane replays with the same typing/settle motion."

    captured c19 (decision, confirmed)

    confirmed instantly — no separate approval step, because a human said it.

  4. The empty ledger, said plainly

    The tool keeps a ledger of moments the build had to leave the plan. Nothing went off-plan in this run — and the ledger says so, instead of inventing drama. Honesty over padding.

    devague --version

    devague 0.18.0

    devague deviate --list

    no deviations recorded yet

  5. The report refuses to pretend

    The delivery report was test-run before anything was built — so every result field correctly says 'fill this in later' rather than claiming work that hadn't happened.

    ## Mid-work Decisions

    (no deviations recorded yet)

    ## Drift From Plan

    no approved deviation records yet — record drift via devague deviate before this section can be filled in

scope legscope — survey the surfaces, seed the frameorg repo · scope leg · devague /scopedevague 0.18.0 · captured 2026-07-15
$ devague new "agentculture.org/agents/devague now presents devague as the complete six-leg method — scope, think, spec-to-plan, assign-to-workforce, deviate, summarize-delivery — as a pure product presentation: the pipeline and method arc carry the execution seam (scope entries on the frame, the deviation ledger, the delivery summary), the operator-skills section shows all six legs, real captured sessions demonstrate the new legs, launch-day meta (public-since dates, dated version chips) is gone, and what's-next is re-verified against the live tracker — good enough that Ori presents the product by just showing the page" --title "devague page: six-leg update"
created frame 'devague-page-six-leg-update' (announcement = c1)
$ devague capture --origin llm --kind requirement "Pipeline, diagram, and skills copy reflect the devague 0.18 surface verified against the installed CLI and CHANGELOG: the scope verb (pre-frame scoping recorded on the frame), the deviate verb (append-only deviation ledger under .devague/deliveries/), the summary verb (render-only eight-section skeleton, --pr variant), and plan deliverables/amend."
captured c6 (requirement, proposed)
$ devague capture --origin llm --kind requirement "whatsNext is re-distilled from the live tracker at authoring time (gh issue list on agentculture/devague, 2026-07-15): the resolution-moves cluster (#60, #57, #55, #52, #49, #48, #45) and the consolidated board (#36) remain open; #62, #68, #69, #70 are closed and must not be linked as direction."
captured c15 (requirement, proposed)
… (c2–c5, c7–c14, c16–c18 captures elided)
$ devague scope "site-astro/src/data/devague.ts" --finding "carries all page copy: fact chips incl. 'public since 2026-07-14' and 'version 0.17.2 — 2026-07-14', the went-public hero paragraph, a 3-stage pipeline, 3 skill cards, and whatsNext linking #62/#68/#69/#70 — all closed by 0.18.0" --seeds c3 c5
recorded s1 (site-astro/src/data/devague.ts)
$ devague scope "devague 0.18.0 (devague --help; ../devague/CHANGELOG.md 0.18.0)" --finding "ships the scope, deviate, and summary verbs plus plan deliverables/amend; docs name the six-leg flow scope→think→spec-to-plan→assign-to-workforce→deviate→summarize-delivery" --seeds c6
recorded s2 (devague 0.18.0 (devague --help; ../devague/CHANGELOG.md 0.18.0))
$ devague scope "site-astro/src/data/devague-captures.ts" --finding "verbatim-replay contract: every line captured from a real run, cuts marked with first-class ellipsis lines, versions and dates carried as pane provenance — new panes must meet the same bar" --seeds c7 c10
recorded s3 (site-astro/src/data/devague-captures.ts)
$ devague scope --list
s1: site-astro/src/data/devague.ts -> carries all page copy: fact chips incl. 'public since 2026-07-14' and 'version 0.17.2 — 2026-07-14', the went-public hero paragraph, a 3-stage pipeline, 3 skill cards, and whatsNext linking #62/#68/#69/#70 — all closed by 0.18.0 [seeds: c3, c5]
s2: devague 0.18.0 (devague --help; ../devague/CHANGELOG.md 0.18.0) -> ships the scope, deviate, and summary verbs plus plan deliverables/amend; docs name the six-leg flow scope→think→spec-to-plan→assign-to-workforce→deviate→summarize-delivery [seeds: c6]
s3: site-astro/src/data/devague-captures.ts -> verbatim-replay contract: every line captured from a real run, cuts marked with first-class ellipsis lines, versions and dates carried as pane provenance — new panes must meet the same bar [seeds: c7, c10]
… (s4 through s8 — DevagueTerminal.astro, DevagueFlow.astro, the live issue tracker, docs/skill-sources.md, site.ts — cut for length)

Session 3 · 15 July 2026 · devague 0.19

The what-did-we-miss pass

One more ability arrived: a formal blind-spot check. It swept the finished spec through a fixed checklist of angles — hidden assumptions, security, what-if-it-breaks, can-we-undo-it — specifically to catch what nobody had thought to ask.

  1. One real catch

    The sweep found a genuinely undecided question — seven cards in a grid designed for six — and routed it to a human to decide, rather than quietly picking an answer.

    devague scope "challenge pass / unstated-assumptions lens: devague.astro skills grid CSS" --finding "the six cards sit 3+3; a seventh lands 3+3+1 with the last card alone — surfaced the layout assumption nobody had stated and proposed it for adjudication" --seeds c19

    recorded s10 (challenge pass / unstated-assumptions lens: devague.astro skills grid CSS)

  2. Honest about the unknown

    One thing couldn't be known yet — how a layout reads on tablet-sized screens — so it was parked as an open unknown instead of being papered over.

    devague park "how the re-timed 9-stage cascade and raised stacking breakpoint read at mid-tablet widths is only observable in a browser during the build — residual until the flow task verifies it" --kind unknown_nonblocking

    parked v1 (unknown_nonblocking)

  3. Adjudicated, reconverged, re-exported

    Ori confirmed the one open call, the frame converged again, and the export rewrote the same spec file — the pass made the existing spec stronger rather than spawning a new one.

    devague confirm c19

    c19 -> confirmed

    devague converge

    converged ✓

    … (seven non-blocking no-instruction warnings on descriptive claims — cut for length)

    devague export

    exported spec to docs/specs/2026-07-15-devague-page-the-challenge-leg.md

challenge legchallenge — sweep the lenses, route the findingsorg repo · challenge leg · devague /challengedevague 0.19.0 · captured 2026-07-15
$ devague capture --origin llm --kind assumption "the seventh skill card reads acceptably in the existing auto-fit grid (3+3+1); if it reads awkward at build time the task owner may give the row a deliberate treatment like the moves grid's full-width lead card — a styling call inside the task, not a new requirement"
captured c19 (assumption, proposed)
$ devague scope "challenge pass / unstated-assumptions lens: devague.astro skills grid CSS" --finding "the six cards sit 3+3; a seventh lands 3+3+1 with the last card alone — surfaced the layout assumption nobody had stated and proposed it for adjudication" --seeds c19
recorded s10 (challenge pass / unstated-assumptions lens: devague.astro skills grid CSS)
… (adjacent-systems lenses s11–s12 — DevagueFlow/DevagueTerminal imports, the site.ts directory entry — both clean; cut for length)
$ devague scope "challenge pass / operations+reversibility lens: .github/workflows/deploy.yml" --finding "merge to main auto-deploys site-astro/** to Cloudflare Pages (push-path trigger, secrets-gated, PR builds included) — the page goes live on merge with no separate operator step, and a git revert redeploys the old page; no rollback gap"
recorded s13 (challenge pass / operations+reversibility lens: .github/workflows/deploy.yml)
$ devague scope "challenge pass / cheap-probe lens: npm run build on the untouched tree" --finding "astro build exits 0 (6 pages, ~209ms) — c15's verification lane confirmed live before the workforce depends on it; dist/ is gitignored so the probe mutated nothing tracked"
recorded s14 (challenge pass / cheap-probe lens: npm run build on the untouched tree)
$ devague park "how the re-timed 9-stage cascade and raised stacking breakpoint read at mid-tablet widths is only observable in a browser during the build — residual until the flow task verifies it" --kind unknown_nonblocking
parked v1 (unknown_nonblocking)

Transcripts are stored verbatim in a data module and replayed as text — the page never runs devague in your browser, and nothing is invented.

what's next

The tracker is public too — this is direction, not a promise

devague is small and moving, and its direction is checkable the same way its facts are: on the open tracker. Three themes stand out in the open issues.

devague

devague is open source, Apache-2.0, and deliberately small — a scorekeeper, not a player. It earned this page the honest way, three times over: the page was specced, planned, and built through the tool it presents, and this very update ran all seven legs, scope to delivery summary — including the challenge pass on its own spec. Every fact above traces to the public repo, PyPI, the open tracker, or the CLI's own output. Nothing was invented.

Read the code →uv tool install devague