devague 0.3.2__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.4.0/.claude/skills/think/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: think
+description: >
+  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.
+---
+
+# think — work an idea backwards into a buildable spec
+
+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
+the frame converges.
+
+The CLI is **deterministic and move-driven** — it is *not* a wizard. There is no
+fixed sequence of prompts. **You (the agent) choose the next move; the CLI just
+tracks state and tells you what's still missing.** Run `devague learn` for the
+canonical ten-stage arc and `devague explain <move>` for any single move.
+
+This skill is the operator: a portable wrapper plus one helper (`status`) that
+reads the convergence gate and tells you the recommended next move.
+
+## How to run
+
+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/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
+case), falling back to `uv run devague` when you are inside the devague checkout.
+If neither resolves it prints an install hint (`uv tool install devague`). Every
+move except `status` is forwarded verbatim, so you can equally call the CLI
+directly (`devague <move> …`) when it is installed; the wrapper exists for
+portable resolution and the `status` helper.
+
+### Moves
+
+| Move | What it does |
+|------|--------------|
+| `new "<announcement>"` | Start a frame from the announcement (the first move). Seeds an auto-confirmed `announcement` claim. |
+| `capture --kind <kind> "<text>"` | Record + classify a claim. `--origin llm` lands it as `proposed`. |
+| `interrogate <id> --honesty "…"` | Attach an honesty condition (what must be true). Also `--hard-question`, `--risk`, `--contradicts`, `--blocking`. |
+| `confirm <id>` / `reject <id>` | Resolve a claim (`c*`) or honesty condition (`h*`). **User-only decision.** |
+| `park "<text>" --kind <kind>` | Move uncertainty into first-class open vagueness instead of forcing an answer. |
+| `converge` | Evaluate the gate; list remaining gaps. |
+| `export` | Write the buildable spec to `docs/specs/` — only after `converge` passes. |
+| `show` / `list` | Render a frame / list frames (`--json` for raw state). |
+| `learn` / `explain <move>` | Teach the method / explain one move. |
+
+Claim kinds: `announcement`, `audience`, `after_state`, `before_state`,
+`why_it_matters`, `boundary`, `success_signal`, `open_question`. Vagueness kinds:
+`unknown_nonblocking`, `unknown_blocking`, `out_of_scope`, `follow_up`.
+
+These are exactly the kinds the **shipped CLI enforces** (`CLAIM_KINDS` /
+`VAGUENESS_KINDS` in `devague/frame.py`) — the skill documents the surface as
+built, so every command here passes the CLI's `choices=` validation. A fuller
+proposed type/state set, plus the formal per-move input/output/transition
+contract, is tracked on the CLI side in
+[#5](https://github.com/agentculture/devague/issues/5); for the authoritative
+live shape of any move, run it with `--json` (or `devague learn --json` /
+`devague explain <move>`). When the CLI's contract grows, re-sync this list.
+
+### `status` — the next-move helper
+
+`status` is a wrapper-only verb (the CLI has no `status`). It reads
+`converge --json` + `list --json` and prints where the current frame stands, the
+remaining gaps, and the recommended next move derived from the first gap.
+`converge --json` currently emits `{passed, missing}`, which is what the helper
+consumes; if [#5](https://github.com/agentculture/devague/issues/5) enriches that
+payload (e.g. structured `blockers` / `warnings` / `required_next_moves`),
+`status` will surface the richer fields then.
+
+```text
+frame: my-feature    (1 frame total)
+convergence: NOT passed — 2 gap(s):
+  - missing a 'boundary' / non-goal claim
+  - claim c2 has no confirmed honesty condition
+
+recommended next move (first gap):
+  devague capture --kind boundary "<text>"
+```
+
+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.
+
+- **LLM proposals stay proposed.** A claim captured with `--origin llm`, and any
+  honesty condition you (the agent) propose, lands as `proposed`. **Never
+  `confirm` your own proposal.** Confirmation is a user-only decision — surface
+  the proposal and let the user confirm or reject it. Proposed content must not
+  silently become an authoritative requirement.
+- **Honesty conditions route through the user.** Propose them freely with
+  `interrogate --honesty`; the user owns whether they hold.
+- **Converge, don't vibe.** `export` is gated on `converge` passing. Never claim
+  the frame is ready on a hunch — run `converge` (or `status`) and resolve every
+  listed gap. The gate requires confirmed `announcement` / `audience` /
+  `after_state`, a `before_state` or `why_it_matters`, a `boundary`, a
+  `success_signal`, a confirmed honesty condition on every spec-affecting claim,
+  and no unresolved blocking vagueness or hard question.
+- **Park real unknowns; don't paper over them.** If something is genuinely
+  unknown, `park` it (blocking or non-blocking) rather than fabricating an
+  answer. Blocking vagueness holds back convergence — by design.
+
+## 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
+on the same stream. Exit code `0` on success, non-zero on user error (with a
+`hint:` line). Frames live under `.devague/` in the current directory.
+
+## Worked example
+
+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/think/scripts/think.sh "$@"; }
+
+d new "Devague ships a documented spec contract"
+d capture --kind audience "devague + the assisting LLM"
+d capture --kind after_state "a vague idea becomes a buildable, pressure-tested spec"
+d capture --kind why_it_matters "specs converge on evidence, not vibes"
+d capture --kind boundary "not a full PRD generator; no fixed wizard"
+d capture --kind success_signal "a frame exports only after the gate passes"
+
+# Pressure-test a claim, then let the USER confirm the condition:
+d interrogate c1 --honesty "the contract round-trips: save -> load -> identical frame"
+# ...user reviews and runs: d confirm h1
+
+# Park a genuine unknown instead of guessing:
+d park "exact JSON schema versioning policy" --kind unknown_nonblocking
+
+d status        # what's left + the next move
+d converge      # gate; resolve any listed gaps
+d export        # writes docs/specs/<slug>.md once converged
+```
+
+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
+
+This is a **first-party** skill — its origin is `agentculture/devague`, where the
+devague agent maintains it alongside the tool it operates (dogfooding). It is the
+*inverse* of the other skills under `.claude/skills/`, which devague vendors
+**from** steward. When this skill is 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`.