devague 0.3.3__tar.gz → 0.4.1__tar.gz

devague-0.4.1/.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.1/.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.1/.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,28 @@ 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.
+
+## After export — commit, then hand off
+
+Once `export` writes the spec **and the user has reviewed it**, close the
+idea→spec leg cleanly before moving on:
+
+1. **Commit the spec.** Commit the exported `docs/specs/<slug>.md` (along with
+   the `.devague/<slug>.json` frame state and any review artifact under
+   `docs/reviews/`) so the converged frame is durable in history, not just on
+   disk. Use a focused message, e.g. `git commit -m "spec: <slug> (devague
+   /think)"`. The frame and the spec are the evidence trail for every confirmed
+   claim — keep them together. (Per the repo's standing convention this normally
+   becomes a branch + PR via the `cicd` skill; commit-only is fine when the user
+   asks for it.)
+2. **Hand off to `/spec-to-plan`.** The forward leg is the sibling 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).
+
+Don't pause for a "what next?" menu after a reviewed export — the standing flow
+is **commit, then `/spec-to-plan`**.
 
 ## Provenance
 

devague-0.3.3/.claude/skills/devague/scripts/devague.sh → devague-0.4.1/.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.4.1/.devague/current_plan

@@ -0,0 +1 @@
+devague-now-ships-a-documented-spec-contract-every