devague 0.3.3__tar.gz → 0.4.0__tar.gz

devague-0.4.0/.claude/skills/spec-to-plan/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: spec-to-plan
+description: >
+  Turn a converged devague spec into a buildable plan by working forwards (the
+  spec→plan leg; drives the `devague plan` CLI group). Seed a plan from a
+  converged frame, add tasks that collectively cover every coverage target (the
+  frame's confirmed claims + honesty conditions), give each task acceptance
+  criteria and an honest dependency order, park genuine unknowns as first-class
+  risks, and export a plan only once it *converges*. Use when the user says
+  "spec to plan", "stp", "turn this spec into a plan", "plan this spec", "make a
+  build plan", or after the /think skill exports a spec. Authored and maintained
+  in agentculture/devague (origin = devague); steward pulls this skill from here
+  and broadcasts it to the AgentCulture mesh — it is NOT vendored from steward
+  like the other skills here.
+---
+
+# spec-to-plan — work a converged spec forwards into a buildable plan
+
+The skill is named **`spec-to-plan`**; the product/CLI it drives is the
+**`devague plan`** command group. (The prior leg — turning a vague idea into a
+spec — is the sibling **`/think`** skill.) It is the **forward** peer of the
+working-backwards spec engine: where `/think` converges on *what* to build,
+`/spec-to-plan` converges on *how* to build it.
+
+A plan is seeded from a **converged frame** and tracks **tasks** against the
+spec's **coverage targets**. The CLI is **deterministic and move-driven** — you
+(the agent) choose the next move; the CLI tracks state and tells you what's still
+missing. Run `devague plan learn` for the method and `devague plan explain
+<move>` for any single move.
+
+## How to run
+
+The entry point is `scripts/spec-to-plan.sh`. Invoke it from the repository you
+are speccing (plans persist under `.devague/` in the current directory, alongside
+the frames they derive from):
+
+```bash
+bash .claude/skills/spec-to-plan/scripts/spec-to-plan.sh <move> [args...]
+bash .claude/skills/spec-to-plan/scripts/spec-to-plan.sh status
+```
+
+It resolves the CLI portably — an installed `devague` on `PATH` (the normal
+case), falling back to `uv run devague` inside the devague checkout, else an
+install hint. Every move except `status` is forwarded verbatim as `devague plan
+<move>`, so you can equally call the CLI directly (`devague plan <move> …`).
+
+### Moves
+
+| Move | What it does |
+|------|--------------|
+| `new --frame <slug>` | Seed a plan from a **converged** frame. Derives the coverage targets (`c*`/`h*`) the plan must satisfy. Refuses an unconverged frame. |
+| `task "<summary>"` | Add a task. `--accept "<crit>"`, `--dep <tN>`, `--covers <c*/h*>` (each repeatable); `--origin llm` lands it `proposed`. |
+| `accept <tN> "<crit>"` | Add an acceptance criterion to a task. |
+| `depend <tN> --on <tM>` | Record that task `tN` depends on `tM`. |
+| `cover <tN> --target <c*/h*>` | Mark a task as covering a coverage target. |
+| `confirm <tN>` / `reject <tN>` | Resolve a task. **User-only decision.** |
+| `risk "<text>" --kind <kind>` | Record a first-class plan risk (`--task <tN>` to attach). |
+| `converge` | Evaluate the gate against the **live** source frame; list remaining gaps. |
+| `export` | Write the buildable plan to `docs/plans/` — only after `converge` passes. |
+| `show` / `list` | Render a plan / list plans (`--json` for raw state). |
+| `learn` / `explain <move>` | Teach the method / explain one move. |
+
+Risk kinds (shared with the frame engine): `unknown_nonblocking`,
+`unknown_blocking`, `out_of_scope`, `follow_up`.
+
+### `status` — the next-move helper
+
+`status` is a wrapper-only verb. It reads `devague plan converge --json` +
+`devague plan list --json` and prints where the current plan stands, the
+remaining gaps, and the recommended next move derived from the first gap.
+
+```text
+plan: my-feature    (1 plan total)
+convergence: NOT passed — 2 gap(s):
+  - coverage target c5 (boundary) has no confirmed task
+  - task t2 has no acceptance criteria
+
+recommended next move (first gap):
+  cover c5: devague plan task "<summary>" --covers c5 --accept "<...>"
+```
+
+Run it whenever you're unsure what to do next.
+
+## Hard rules (do not violate)
+
+These are the point of the method — convergence must mean something.
+
+- **Seed from a converged spec only.** `plan new` refuses a frame that hasn't
+  converged. The plan's coverage targets *are* the spec's confirmed claims and
+  honesty conditions — there is nothing honest to plan against until the spec
+  converges.
+- **LLM proposals stay proposed.** A task captured with `--origin llm` lands as
+  `proposed`. **Never `confirm` your own proposal.** Confirmation is a user-only
+  decision — surface the proposed task and let the user confirm or reject it.
+- **Cover every target; criteria on every task.** The gate requires every
+  coverage target to be covered by a confirmed task, and every confirmed task to
+  carry at least one acceptance criterion. Don't hand-wave a task as "done-ish."
+- **Keep the graph honest.** Dependencies must reference real tasks and form an
+  acyclic graph; the gate rejects dangling deps and cycles.
+- **Park real unknowns as risks; don't paper over them.** A genuinely unknown
+  decision is an `unknown_blocking` risk — it holds back convergence, by design.
+- **Converge against the live frame.** `converge`/`export` re-load the source
+  frame every time. If the frame was deleted or has regressed below convergence,
+  they refuse — re-converge the spec (in `/think`) first.
+
+## Output contract
+
+Results go to **stdout**, diagnostics and errors to **stderr** — a strict split
+you can rely on when parsing. Pass `--json` to any move for a structured payload.
+Exit code `0` on success, non-zero on user error (with a `hint:` line). Plans
+live under `.devague/plans/` in the current directory; the exported plan-md lands
+in `docs/plans/`.
+
+## Worked example
+
+Picking up after `/think` exported a spec for the frame `my-feature`:
+
+```bash
+p() { bash .claude/skills/spec-to-plan/scripts/spec-to-plan.sh "$@"; }
+
+p new --frame my-feature        # seeds the plan + its coverage targets
+p show                          # see the c*/h* targets you must cover
+
+p task "Build the core engine" --accept "engine has a convergence gate" \
+    --covers c1 --covers c3
+p task "Pressure-test honesty conditions" --dep t1 --covers h1 --covers h2 \
+    --accept "every honesty condition maps to a test"
+
+# Park a genuine unknown instead of guessing:
+p risk "exact rollout sequencing" --kind unknown_nonblocking
+
+p status        # what's left + the next move
+p converge      # gate; resolve any listed gaps
+p export        # writes docs/plans/my-feature.md once converged
+```
+
+The exported plan-md is a buildable artifact: topologically ordered tasks, each
+with acceptance criteria and the spec targets it covers. It feeds directly into
+implementation (or `superpowers:writing-plans`).
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, where the
+devague agent maintains it alongside the tool it operates (dogfooding), next to
+its sibling `/think`. It is the *inverse* of the other skills under
+`.claude/skills/`, which devague vendors **from** steward. When ready, steward
+pulls it **from** devague and broadcasts it to the rest of the AgentCulture mesh.
+The `cite, don't import` policy still holds: downstream repos copy it, they don't
+symlink or depend on it. See `docs/skill-sources.md`.

devague-0.4.0/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# spec-to-plan.sh — drive devague's spec→plan engine (the /spec-to-plan skill).
+#
+# The skill is named `spec-to-plan`; the product/CLI it drives is `devague` (the
+# idea→spec half lives in the sibling /think skill). This wrapper forwards every
+# move to `devague plan <move>` verbatim, and adds one value-add subcommand —
+# `status` — that reads the plan convergence gate and names the recommended next
+# move. It is the forward leg: seed a plan from a *converged* frame, then work it
+# into a buildable plan.
+#
+# Origin: authored and maintained in agentculture/devague. steward pulls this
+# skill from here and broadcasts it to the rest of the AgentCulture mesh, so it
+# is written to run anywhere — portable bash, no devague-checkout assumptions.
+#
+# Plans persist under .devague/ in the current directory (alongside frames), so
+# run from the repo you are speccing.
+
+set -euo pipefail
+
+# ── resolve the devague CLI (mesh-first, then local-dev fallback) ───────────
+DEVAGUE=()
+resolve_devague() {
+    if command -v devague >/dev/null 2>&1; then
+        DEVAGUE=(devague)            # installed tool — the normal mesh case
+        return 0
+    fi
+    # Local-dev fallback: inside the devague checkout, run via uv.
+    local dir="$PWD"
+    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+        if [ -f "$dir/pyproject.toml" ] \
+            && grep -q '^name = "devague"' "$dir/pyproject.toml" 2>/dev/null; then
+            if command -v uv >/dev/null 2>&1; then
+                DEVAGUE=(uv run devague)
+                return 0
+            fi
+            break
+        fi
+        dir=$(dirname "$dir")
+    done
+    cat >&2 <<'EOF'
+error: devague CLI not found.
+hint: install it with `uv tool install devague` (or `pipx install devague`),
+      or run from inside the devague checkout with `uv` available.
+      https://github.com/agentculture/devague
+EOF
+    return 1
+}
+
+usage() {
+    cat <<'EOF'
+spec-to-plan.sh — drive devague's spec→plan engine (the /spec-to-plan skill).
+
+Usage:
+  spec-to-plan.sh <move> [args...]   forward a `devague plan` move
+  spec-to-plan.sh status [--plan S]  where the plan stands + the next move
+  spec-to-plan.sh help               this help
+
+Moves (forwarded to `devague plan`; run `devague plan learn` for the method):
+  new          start a plan from a CONVERGED frame (--frame <slug>)
+  task         add a task (--accept / --dep / --covers, --origin user|llm)
+  accept       add an acceptance criterion to a task
+  depend       record that a task depends on another (--on)
+  cover        mark a task as covering a coverage target (c*/h*)
+  confirm      confirm a task                          (USER-only decision)
+  reject       reject a task
+  risk         record a first-class plan risk
+  converge     check whether the plan can export
+  export       write the buildable plan (only after converge passes)
+  show / list  render a plan / list plans
+  learn        teach the method   |   explain <move>  explain one move
+
+Plans persist under .devague/ in the current directory — run from the repo you
+are speccing. Results go to stdout, diagnostics to stderr; pass --json to any
+move for structured output.
+
+Note: `status` is a wrapper-only verb; everything else is forwarded verbatim as
+`devague plan <move>`, so new plan moves work without editing this script.
+
+Prior leg: a plan is seeded from a converged frame produced by the /think skill.
+EOF
+}
+
+# ── status: read the plan convergence gate and recommend the next move ──────
+cmd_status() {
+    local list_json conv_out conv_err conv_rc req_plan="" prev="" tmp_err
+
+    for arg in "$@"; do
+        case "$prev" in --plan) req_plan="$arg" ;; esac
+        case "$arg" in --plan=*) req_plan="${arg#--plan=}" ;; esac
+        prev="$arg"
+    done
+
+    list_json="$("${DEVAGUE[@]}" plan list --json 2>/dev/null || true)"
+
+    tmp_err="$(mktemp)"
+    set +e
+    conv_out="$("${DEVAGUE[@]}" plan converge --json "$@" 2>"$tmp_err")"
+    conv_rc=$?
+    set -e
+    conv_err="$(cat "$tmp_err")"
+    rm -f "$tmp_err"
+
+    DEVAGUE_LIST_JSON="$list_json" \
+        DEVAGUE_CONV_JSON="$conv_out" \
+        DEVAGUE_CONV_ERR="$conv_err" \
+        DEVAGUE_CONV_RC="$conv_rc" \
+        DEVAGUE_REQ_PLAN="$req_plan" \
+        python3 - <<'PY'
+import json
+import os
+import re
+import sys
+
+
+def load(name):
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+lst = load("DEVAGUE_LIST_JSON") or {}
+conv = load("DEVAGUE_CONV_JSON")
+conv_err = os.environ.get("DEVAGUE_CONV_ERR", "").strip()
+req_plan = os.environ.get("DEVAGUE_REQ_PLAN", "").strip()
+try:
+    conv_rc = int(os.environ.get("DEVAGUE_CONV_RC", "0") or "0")
+except ValueError:
+    conv_rc = 0
+
+plans = lst.get("plans") or []
+current = lst.get("current")
+
+if not plans:
+    print("no plans yet — seed one from a converged frame:")
+    print('  devague plan new --frame "<slug>"')
+    print("  (the frame must have converged in the /think skill first)")
+    sys.exit(0)
+
+shown = req_plan or current or "(none selected)"
+total = len(plans)
+print(f"plan: {shown}    ({total} plan{'s' if total != 1 else ''} total)")
+
+if conv is None:
+    # A non-zero converge exit is a real error (deleted/regressed source frame,
+    # bad --plan) — relay devague's own error:/hint: lines instead of masking it.
+    if conv_rc != 0 and conv_err:
+        sys.stderr.write(conv_err + "\n")
+        sys.exit(conv_rc)
+    print("convergence: unknown (could not evaluate the plan)")
+    print("next move: devague plan show     # inspect the plan")
+    sys.exit(0)
+
+if conv.get("passed"):
+    print("convergence: PASSED ✓")
+    print("next move: devague plan export   # write the buildable plan")
+    sys.exit(0)
+
+missing = conv.get("missing") or []
+print(f"convergence: NOT passed — {len(missing)} gap(s):")
+for gap in missing:
+    print(f"  - {gap}")
+
+
+def suggest(gap):
+    if "no tasks yet" in gap:
+        return 'devague plan task "<summary>" --covers <c*/h*> --accept "<criterion>"'
+    m = re.search(r"coverage target (\w+) ", gap)
+    if m:
+        tid = m.group(1)
+        return (
+            f'cover {tid}: devague plan task "<summary>" --covers {tid} --accept "<...>"'
+            f"   (or: devague plan cover <tN> --target {tid})"
+        )
+    m = re.search(r"task (t\d+) has no acceptance", gap)
+    if m:
+        return f'devague plan accept {m.group(1)} "<acceptance criterion>"'
+    m = re.search(r"task (t\d+) still proposed", gap)
+    if m:
+        tid = m.group(1)
+        return (
+            f"this is an LLM proposal — the USER decides:"
+            f" devague plan confirm {tid}   (or: devague plan reject {tid})"
+        )
+    m = re.search(r"task (t\d+) depends on unknown task (t\d+)", gap)
+    if m:
+        return f"fix {m.group(1)}'s dependency on missing {m.group(2)} (add it, or drop the dep)"
+    if "dependency cycle" in gap:
+        return "break the dependency cycle: re-point one task's --dep so the graph is acyclic"
+    m = re.search(r"blocking risk (r\d+)", gap)
+    if m:
+        return f"resolve {m.group(1)}: cover it with a task, or re-record it as non-blocking"
+    return "devague plan show     # inspect and decide"
+
+
+if missing:
+    print()
+    print("recommended next move (first gap):")
+    print(f"  {suggest(missing[0])}")
+PY
+}
+
+main() {
+    case "${1:-help}" in
+        help | -h | --help)
+            usage
+            return 0
+            ;;
+        status)
+            shift
+            resolve_devague
+            cmd_status "$@"
+            ;;
+        *)
+            # Forward everything else to `devague plan <move>` verbatim, so the
+            # CLI's own parser owns the plan surface.
+            resolve_devague
+            exec "${DEVAGUE[@]}" plan "$@"
+            ;;
+    esac
+}
+
+main "$@"

{devague-0.3.3/.claude/skills/devague → devague-0.4.0/.claude/skills/think}/SKILL.md

@@ -1,21 +1,26 @@
 ---
-name: devague
+name: think
 description: >
-  Operate the devague working-backwards spec tool: turn a vague feature idea
-  into a buildable, pressure-tested spec by starting from the announcement
-  ("pretend it shipped"), capturing and classifying claims, interrogating them
-  with honesty conditions and hard questions, parking open vagueness as a
-  first-class object, and exporting a spec only once the frame *converges*. Use
-  when the user says "spec this", "work backwards", "turn this idea into a
-  spec", "announcement frame", or "devague", or when a feature request is too
-  vague to build yet. Authored and maintained in agentculture/devague (origin =
-  devague); steward pulls this skill from here and broadcasts it to the
+  Think a vague feature idea into a buildable spec by working backwards (the
+  idea→spec leg; drives the `devague` CLI). Start from the announcement
+  ("pretend it shipped"), capture and classify claims, interrogate them with
+  honesty conditions and hard questions, park open vagueness as a first-class
+  object, and export a spec only once the frame *converges*. Use when the user
+  says "think this through", "spec this", "work backwards", "turn this idea into
+  a spec", "announcement frame", or "devague", or when a feature request is too
+  vague to build yet. Once a spec exports, hand off to the sibling /spec-to-plan
+  skill to turn it into a plan. Authored and maintained in agentculture/devague
+  (origin = devague); steward pulls this skill from here and broadcasts it to the
   AgentCulture mesh — it is NOT vendored from steward like the other skills here.
 ---
 
-# devague — work an idea backwards into a buildable spec
+# think — work an idea backwards into a buildable spec
 
-`devague` turns a vague feature idea into a buildable spec by **working
+The skill is named **`think`**; the product/CLI it drives is **`devague`**. (The
+forward leg — turning a converged spec into a plan — is the sibling
+**`/spec-to-plan`** skill, which drives `devague plan`.)
+
+`think` turns a vague feature idea into a buildable spec by **working
 backwards**: you start from the announcement you'd make if it had already
 shipped, then build an **Announcement Frame** by capturing claims, pressure
 -testing them, parking what's still genuinely unknown, and only exporting once
@@ -31,12 +36,12 @@ reads the convergence gate and tells you the recommended next move.
 
 ## How to run
 
-The entry point is `scripts/devague.sh`. Invoke it from the repository you are
+The entry point is `scripts/think.sh`. Invoke it from the repository you are
 speccing (frames persist under `.devague/` in the current directory):
 
 ```bash
-bash .claude/skills/devague/scripts/devague.sh <move> [args...]
-bash .claude/skills/devague/scripts/devague.sh status
+bash .claude/skills/think/scripts/think.sh <move> [args...]
+bash .claude/skills/think/scripts/think.sh status
 ```
 
 It resolves the CLI portably — an installed `devague` on `PATH` (the normal
@@ -129,7 +134,7 @@ A short end-to-end session (the kind you'd run to spec a feature like
 [devague#5](https://github.com/agentculture/devague/issues/5)):
 
 ```bash
-d() { bash .claude/skills/devague/scripts/devague.sh "$@"; }
+d() { bash .claude/skills/think/scripts/think.sh "$@"; }
 
 d new "Devague ships a documented spec contract"
 d capture --kind audience "devague + the assisting LLM"
@@ -150,8 +155,10 @@ d converge      # gate; resolve any listed gaps
 d export        # writes docs/specs/<slug>.md once converged
 ```
 
-The exported spec-md is a buildable artifact; it can feed directly into
-`superpowers:writing-plans` or a normal implementation PR.
+The exported spec-md is a buildable artifact. The next leg is the sibling
+**`/spec-to-plan`** skill: `devague plan new --frame <slug>` seeds a plan from the
+converged frame and works it forward into a buildable plan (it can equally feed
+`superpowers:writing-plans` or a normal implementation PR).
 
 ## Provenance
 

devague-0.3.3/.claude/skills/devague/scripts/devague.sh → devague-0.4.0/.claude/skills/think/scripts/think.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
-# devague.sh — operate the devague working-backwards spec tool.
+# think.sh — drive devague's working-backwards idea→spec engine (the /think skill).
 #
+# The skill is named `think`; the product/CLI it drives is `devague` (the spec→plan
+# half lives in the sibling /spec-to-plan skill, which drives `devague plan`).
 # devague turns a vague feature idea into a buildable spec by working backwards.
 # This wrapper is the agent-facing operator for the deterministic devague CLI:
 # it resolves the CLI portably, forwards every move verbatim, and adds one
@@ -47,12 +49,12 @@ EOF
 
 usage() {
     cat <<'EOF'
-devague.sh — operate the devague working-backwards spec tool.
+think.sh — drive devague's working-backwards idea→spec engine (the /think skill).
 
 Usage:
-  devague.sh <move> [args...]    forward a devague move
-  devague.sh status [--frame S]  where the frame stands + the next move
-  devague.sh help                this help
+  think.sh <move> [args...]    forward a devague move
+  think.sh status [--frame S]  where the frame stands + the next move
+  think.sh help                this help
 
 Moves (forwarded to the devague CLI; run `devague learn` for the full method):
   new          start a frame from the announcement ("pretend it shipped")
@@ -73,6 +75,9 @@ any move for structured output.
 Note: `status` is a wrapper-only verb (the CLI has no `status`); everything
 else is forwarded verbatim, so new devague moves work without editing this
 script.
+
+Next leg: once a frame exports a spec, hand off to the /spec-to-plan skill
+(`devague plan ...`) to turn that spec into a buildable plan.
 EOF
 }
 

{devague-0.3.3 → devague-0.4.0}/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-05-23
+
+### Added
+
+- **Spec→plan engine** — a deterministic structural peer of the working-backwards frame engine that turns a converged spec into a buildable plan. New modules: `devague/plan.py` (Plan / Task / PlanRisk / CoverageTarget domain), `plan_convergence.py` (coverage + acceptance + acyclic-dependency + blocking-risk gate, reusing `ConvergenceResult`), `plan_store.py` (`.devague/plans/`), and `render/plan_md.py` (topologically-ordered buildable plan).
+- Nested `devague plan` CLI group (`new` / `task` / `accept` / `depend` / `cover` / `confirm` / `reject` / `risk` / `converge` / `export` / `show` / `list` / `learn` / `explain`), all with `--json`. `plan new` requires a converged source frame; `converge`/`export` re-evaluate against the **live** frame and refuse on frame drift (deleted or regressed).
+- New first-party **`/spec-to-plan`** skill (`.claude/skills/spec-to-plan/`): a portable wrapper (`scripts/spec-to-plan.sh`) forwarding to `devague plan` plus a `status` next-move helper over the plan gate.
+
+### Changed
+
+- **Renamed the `devague` skill to `think`** (`.claude/skills/think/`, `scripts/think.sh`) — clearer idea→spec framing and to pair with the new `/spec-to-plan` sibling. The product/CLI/repo name stays `devague`; only the skill identity changed. `docs/skill-sources.md` and downstream steward re-vendoring must relearn the new name. ("devague" remains a trigger keyword on `/think`.)
+
 ## [0.3.3] - 2026-05-23
 
 ### Added

{devague-0.3.3 → devague-0.4.0}/CLAUDE.md

@@ -4,12 +4,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Status
 
-**Working-backwards engine landed (v0.3.0).** The full deterministic spec
-engine is implemented: Frame domain model, persistent JSON store, convergence
-gate, pluggable renderer registry, and all CLI moves — `new` / `capture` /
-`interrogate` / `confirm` / `reject` / `park` / `converge` / `export` / `show`
-/ `list` — plus real `learn` / `explain` bodies that teach the method.
-Coverage is 94 %; all linters pass. Run `git ls-files` to see the real surface.
+**Spec→plan engine landed (v0.4.0).** Both deterministic engines now ship.
+The **frame engine** (idea→spec) — Frame domain model, JSON store, convergence
+gate, renderer registry, and the flat moves `new` / `capture` / `interrogate` /
+`confirm` / `reject` / `park` / `converge` / `export` / `show` / `list` /
+`learn` / `explain`. The **plan engine** (spec→plan) is its structural peer:
+`devague/plan.py`, `plan_convergence.py`, `plan_store.py`, `render/plan_md.py`,
+and the nested group `devague plan <move>` (`new` / `task` / `accept` / `depend`
+/ `cover` / `confirm` / `reject` / `risk` / `converge` / `export` / `show` /
+`list` / `learn` / `explain`). The two operator skills are `/think` (idea→spec,
+renamed from `/devague`) and `/spec-to-plan` (spec→plan). Coverage ≥ 95 %; all
+linters pass. Run `git ls-files` to see the real surface.
 
 Real commands: `uv sync`; `uv run devague --version`; `python -m devague`;
 `uv run pytest -n auto` (single test: `uv run pytest tests/<file>::<node> -v`);
@@ -39,15 +44,44 @@ itself. The workflow:
 
 Full design: `docs/superpowers/specs/2026-05-23-devague-working-backwards-design.md`.
 
+## Spec→plan method (the forward leg)
+
+The **plan engine** is the structural peer of the frame engine — same chassis,
+same anti-fabrication rules, no LLM inside the CLI. It is namespaced under the
+`devague plan` subcommand group (the *skill* is `/spec-to-plan`; the CLI verb is
+`plan` — they intentionally differ, mirroring how `/think` drives the flat
+verbs). The workflow:
+
+1. `devague plan new --frame <slug>` — seed a plan from a **converged** frame.
+   Derives **coverage targets** (the frame's confirmed claims + honesty
+   conditions). Refuses an unconverged frame; refuses to clobber an existing plan.
+2. `devague plan task "<summary>" [--accept … --dep … --covers … --origin]` —
+   add tasks; `--origin llm` lands `proposed` (user must `confirm`). Refine with
+   `accept` / `depend` / `cover`.
+3. `devague plan risk "<text>" --kind <kind>` — park a genuine unknown as a
+   first-class plan risk instead of guessing.
+4. `devague plan converge` — re-evaluates the gate **against the live frame**
+   (catches frame drift); lists gaps. A plan converges when every target is
+   covered by a confirmed task, every confirmed task has acceptance criteria, the
+   dependency graph is acyclic, and no blocking risk remains.
+5. `devague plan export` — only after `converge` passes; writes a buildable
+   plan-md (topologically ordered) to `docs/plans/`.
+
+Full design: `docs/superpowers/specs/2026-05-23-devague-spec-to-plan-design.md`.
+
 ## Project intent
 
 **devague** — an AgentCulture agent that turns a vague feature idea into a
-**buildable spec** by working backwards. The method: start from the
-announcement ("pretend it shipped — what would you announce?"), build an
-**Announcement Frame** by capturing and classifying claims, pressure-testing
-them with honesty conditions and hard questions, parking unresolved uncertainty
-as first-class "open vagueness," and only exporting a buildable spec once the
-frame *converges*.
+**buildable spec**, then that spec into a **buildable plan**, by working
+backwards then forwards. The spec method: start from the announcement ("pretend
+it shipped — what would you announce?"), build an **Announcement Frame** by
+capturing and classifying claims, pressure-testing them with honesty conditions
+and hard questions, parking unresolved uncertainty as first-class "open
+vagueness," and only exporting a buildable spec once the frame *converges*. The
+plan method: seed a plan from that converged frame and converge it on coverage,
+acceptance criteria, and an acyclic dependency order before exporting a plan.
+Two operator skills cover the two legs: **`/think`** (idea→spec) and
+**`/spec-to-plan`** (spec→plan); the product/CLI for both is **`devague`**.
 
 This is a **state machine over claims, honesty conditions, open vagueness, and
 convergence** driven by LLM-chosen moves — not a linear wizard. The CLI is
@@ -85,8 +119,12 @@ that unless the user asks otherwise. The established sibling shape is:
   `DevagueError` + exit-code policy) and `_output.py` (strict stdout/stderr
   split, `--json` support).
 - `devague/cli/_commands/` — one module per verb, each exposing `register()`.
-  Implemented verbs: `new`, `capture`, `interrogate`, `confirm`, `reject`,
-  `park`, `converge`, `export`, `show`, `list`, `learn`, `explain`.
+  Frame verbs: `new`, `capture`, `interrogate`, `confirm`, `reject`, `park`,
+  `converge`, `export`, `show`, `list`, `learn`, `explain`. The plan engine adds
+  one module, `_commands/plan.py`, registering the nested `plan` subcommand group.
+- Frame engine: `devague/frame.py`, `convergence.py`, `store.py`,
+  `render/{spec_md,frame_md}.py`. Plan engine (its peer): `devague/plan.py`,
+  `plan_convergence.py`, `plan_store.py`, `render/plan_md.py`, `cli/_plans.py`.
 - `pyproject.toml`, `CHANGELOG.md`, `tests/`, `docs/`, `culture.yaml`,
   `sonar-project.properties`, `uv.lock`.
 

devague-0.4.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: devague
+Version: 0.4.0
+Summary: devague — turns a vague feature idea into a buildable spec, then a buildable plan.
+Project-URL: Homepage, https://github.com/agentculture/devague
+Project-URL: Issues, https://github.com/agentculture/devague/issues
+Author: AgentCulture
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# devague
+
+**`devague` is a command-line tool** that turns a vague feature idea into a
+buildable **spec**, then that spec into a buildable **plan** — by working
+backwards, then forwards. It is a small, deterministic Python CLI (no LLM calls
+inside it, fully unit-tested) — not an agent, service, or daemon. You install it
+and run `devague` from the repository you are speccing; state is plain JSON under
+`.devague/`.
+
+```text
+vague idea ──▶ buildable spec ──▶ buildable plan ──▶ build
+```
+
+## Install
+
+```bash
+uv tool install devague      # or: pipx install devague / pip install devague
+devague --version
+```
+
+## Two engines, one CLI
+
+- **Frame engine** (idea→spec) — start from the announcement ("pretend it
+  shipped"), capture and pressure-test claims, park open vagueness, and `export`
+  a spec only once the frame *converges*. Flat verbs: `devague new` /
+  `capture` / `interrogate` / `confirm` / `converge` / `export` / …
+- **Plan engine** (spec→plan) — seed a plan from a converged frame, cover every
+  target with tasks that carry acceptance criteria and an acyclic dependency
+  order, and `export` a plan only once it *converges*. Nested group:
+  `devague plan new` / `task` / `cover` / `converge` / `export` / …
+
+Run `devague learn` (or `devague plan learn`) to learn the method, and `devague
+explain <move>` for any single move.
+
+## Driving it from an agent
+
+Inside AgentCulture, an assistant drives this CLI through two operator skills —
+**`/think`** (idea→spec) and **`/spec-to-plan`** (spec→plan) — which add a
+portable wrapper and a `status` next-move helper over the convergence gate. The
+CLI is the deterministic affordance; the agent decides the next move. See
+`CLAUDE.md` for that workflow and `docs/superpowers/specs/` for the design docs.