devague reference

devague turns a vague idea into a buildable spec by working backwards.

First question: What’s the announcement? Pretend this shipped successfully. What would you announce to users, teammates, or yourself?

Start from that announcement, then build an Announcement Frame by capturing claims, interrogating them, parking what’s still vague, and converging. The arc emerges from the moves; it is not a fixed wizard. You (the agent) choose the next move; devague tracks state. LLM-proposed claims and honesty conditions stay ‘proposed’ until the user confirms them.

Guided stages (the recommended sequence — drive them with the moves):

  1. Announcement what are we saying shipped? [new]
  2. Audience who needs this? [capture –kind audience]
  3. After what changed for them? [capture –kind after_state]
  4. Matter why is it worth doing? [capture –kind why_it_matters]
  5. Before what pain made this necessary? [capture –kind before_state]
  6. Honest what must be true for the announcement to be honest? [interrogate –honesty]
  7. FAQ what hard questions remain? [interrogate –hard-question]
  8. Boundaries what are we not promising? [capture –kind boundary]
  9. Success how will we know? [capture –kind success_signal]
  10. Spec what should be built? [converge -> export]

Moves: new Start a frame from the announcement (pretend it shipped). capture Record and classify a claim (audience, after_state, boundary, …). interrogate Pressure-test a claim: honesty conditions, hard questions, contradictions. confirm Confirm a claim or honesty condition (user-only — no fabricated rigor). reject Reject a claim or honesty condition. park Move uncertainty into first-class open vagueness instead of forcing an answer. converge Check whether the frame is solid enough to export a spec. export Write the buildable spec — only once the frame converges. show Render the Announcement Frame. list List frames.

devague is NOT:

  • a wizard (no fixed prompt sequence)
  • a scripted questionnaire (you don’t read questions off a form)
  • a PRD generator (it never invents content to fill a template)

Operating rules (the anti-fabrication contract — do not violate):

  • LLM proposals stay proposed — capture your own ideas with –origin llm; never confirm your own proposal. Confirmation is a user-only decision.
  • Honesty conditions route through the user — propose freely with ‘interrogate –honesty’; the user owns whether each one holds.
  • Park real unknowns instead of papering over them — ‘park’ a genuine unknown rather than writing confident prose that hides the gap.
  • Converge, don’t vibe — ‘export’ is gated on ‘converge’; resolve every listed gap instead of declaring readiness on a hunch.
  • Order is adaptive — the ten stages are an artifact shape, not a mandatory conversation order; capture what the user gives you and circle back.

Assign-to-workforce: parallel plan execution via subagent-driven development When: Once a plan converges (all targets covered, all tasks have acceptance criteria, dependency graph is acyclic), you can fan out its waves to parallel agents working in isolated git worktrees. Prerequisites: A converged plan with deterministic dependency waves (devague plan waves). Human gates (3): The human approves at exactly three points: (1) the exported spec, (2) the implementation split plan (plan/tasks map, per-task agent/model assignment, go/no-go to workforce), and (3) the final PR. The human is NOT in the per-task worktree-merge loop. Safety: Each task runs in an isolated git worktree (one per task per wave). This keeps file-contention safe: overlapping same-file changes surface as merge conflicts at reconcile time, not live races. Main agent: The main agent gates each subagent worktree merge with TDD: tests pass before AND after merge. No human per-task merge decision. TDD: Each task carries TDD acceptance criteria (tests first) scoped tightly enough for a simpler/cheaper model to build. The tests validate that the task was built correctly — no re-deriving the design needed. Scope: devague itself does not orchestrate: it does not spawn subagents, manage worktrees, mark tasks done, or pick a backend. Orchestration is a cited skill convention (assign-to-workforce), not part of the deterministic CLI.

Full portable guidance for any assisting model: https://github.com/agentculture/devague/blob/main/docs/llm-guidance.md (in the devague repo: docs/llm-guidance.md) Agent-agnostic; your repo-specific agreements live in your agent’s main instruction file — AGENTS.md, CLAUDE.md, a system prompt — not there.

Table of contents