devague 0.17.2__tar.gz → 0.18.1__tar.gz

{devague-0.17.2 → devague-0.18.1}/.claude/skills/assign-to-workforce/SKILL.md

@@ -11,7 +11,7 @@ description: >
   "fan out the plan", "parallel subagents", or after /spec-to-plan exports a
   plan. Authored and maintained in agentculture/devague (origin = devague);
   guildmaster pulls this skill from here and broadcasts it to the AgentCulture
-  mesh — it is NOT vendored from guildmaster like the other skills here.
+  mesh — it is NOT vendored from guildmaster like the inbound skills here.
 type: command
 ---
 
@@ -53,14 +53,16 @@ carries every active task's summary, instruction, acceptance criteria, and
 covered targets keyed by task id — and renders the human-facing
 implementation split plan: task map (task id, wave, summary verbatim, whether
 an instruction is present, acceptance-criteria count), proposed per-task
-agent + model assignment, and the go/no-go question. The `waves` subcommand
-forwards to `devague plan waves` verbatim.
+agent + model assignment, the go/no-go question, and — last — an End state
+section that is the verbatim output of `devague plan deliverables` (#70),
+degrading to a one-line hint on a `devague` too old to have the verb. The
+`waves` subcommand forwards to `devague plan waves` verbatim.
 
 ### Usage
 
 | Subcommand | What it does |
 |------------|--------------|
-| `split-plan [--plan S]` | Read `devague plan waves --json` and print the implementation split plan — task map (summary/instruction/acceptance-criteria count, verbatim) with per-task agent + model proposal — ready for human go/no-go review. |
+| `split-plan [--plan S]` | Read `devague plan waves --json` and print the implementation split plan — task map (summary/instruction/acceptance-criteria count, verbatim) with per-task agent + model proposal, go/no-go, and a trailing End state section quoting `devague plan deliverables` verbatim (one-line hint on an older devague) — ready for human go/no-go review. |
 | `waves [--plan S] [--json]` | Forward to `devague plan waves [--json]`. Read-only; lists wave batches. On a converged plan exits 0 listing the waves. |
 | `help` | Print usage. |
 
@@ -92,6 +94,13 @@ The split plan contains:
    safe to delegate).
 3. **Go/no-go question** — explicit human decision: "Approve this split and
    assign the plan to the workforce, or edit it first?"
+4. **End state** — the verbatim output of `devague plan deliverables` (#70):
+   what the plan actually produces — confirmed after-state claims, terminal
+   tasks with acceptance criteria, and surviving open items. Present this to
+   the human alongside the go/no-go question, not just the task map — approving
+   a fan-out without seeing the world it produces is the gap this closes. On a
+   `devague` too old to have the verb, this degrades to a one-line hint naming
+   the minimum version instead of failing the split plan.
 
 The human may edit any row (agent type, model, scope) before approving. The
 plan is model-agnostic — devague does not pick a backend (#20).
@@ -253,6 +262,13 @@ plan is found. On error (no plan, cyclic graph) it exits non-zero with a
 `hint:` line on stderr. The `waves` subcommand forwards the CLI's own output
 contract (stdout, `--json` for structured output, exit 0 on success).
 
+The trailing End state section (#70) never fails `split-plan`: on a `devague`
+new enough to have `plan deliverables`, it quotes that command's stdout
+verbatim under an `End state (from \`devague plan deliverables\`):` header; on
+an older `devague`, it prints exactly one hint line naming the minimum version
+(e.g. `hint: End state view requires devague >= 0.18.0 (devague plan
+deliverables)`) and `split-plan` still exits 0.
+
 ## Worked example
 
 Picking up after `/spec-to-plan` exported a plan for the frame `my-feature`:

{devague-0.17.2 → devague-0.18.1}/.claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh

@@ -4,17 +4,24 @@
 # The skill is named `assign-to-workforce`; it reads `devague plan waves --json`
 # — the enriched payload (devague#53 t9: {"plan", "waves", "tasks"}, the latter
 # keyed by task id with summary/instruction/acceptance_criteria/covers) — and
-# renders the implementation split plan: task map (summary, instruction
-# marker, acceptance-criteria count — all verbatim from the payload) +
-# per-task agent/model proposal + a go/no-go prompt for the human. The actual
-# fan-out (worktree creation, spawning, TDD-gated merges) is performed by the
-# operator/main agent once the human approves the split plan.
+# renders the implementation split plan: a wave listing (each task id carries
+# an `[instruction: yes|no, accept: N]` marker, verbatim from the payload) plus
+# a single four-column per-task table — Wave, Task, Model, Task summary (#69)
+# — and a go/no-go prompt for the human. The Model cell is a presentation-only
+# default (`sonnet`); the devague CLI stays model-agnostic (#20) and the human
+# is expected to edit it to a real model token (and harness, when it matters)
+# before approving. The actual fan-out (worktree creation, spawning, TDD-gated
+# merges) is performed by the operator/main agent once the human approves the
+# split plan. Output ends with an End state section (devague#70 t6) — the
+# verbatim output of `devague plan deliverables` — so the human can see what
+# the plan actually produces before saying go; on an older devague lacking
+# that verb the section degrades to a one-line hint instead of failing.
 #
 # The devague CLI is non-orchestrating (#20): `devague plan waves` describes
 # the dependency graph; it does not spawn agents, manage worktrees, or pick
 # a backend. This wrapper is the operator-facing helper.
 #
-# Origin: authored and maintained in agentculture/devague. steward pulls this
+# Origin: authored and maintained in agentculture/devague. guildmaster 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.
 #
@@ -63,11 +70,14 @@ Usage:
 
 Commands:
   split-plan   Read `devague plan waves --json` and render the human-facing
-               implementation split plan: task map (summary, instruction
-               marker, acceptance-criteria count — all verbatim from the
-               payload) + per-task agent/model proposal + go/no-go. Present
-               this to the human before any fan-out; do not proceed without
-               approval.
+               implementation split plan: a wave listing (with per-task
+               instruction/acceptance-count markers, verbatim from the
+               payload) + a four-column Wave/Task/Model/Task-summary table
+               (Model defaults to `sonnet`; edit it before approving) +
+               go/no-go, ending with an End state section — the verbatim
+               output of `devague plan deliverables` (degrades to a one-line
+               hint on an older devague lacking that verb). Present this to
+               the human before any fan-out; do not proceed without approval.
   waves        Forward `devague plan waves` (and any extra flags) verbatim.
                On a converged plan exits 0 and lists the dependency waves.
 
@@ -143,36 +153,49 @@ waves = data.get("waves") or []
 # contract, keyed by id — summary, instruction, acceptance criteria, covers.
 tasks_meta = data.get("tasks") or {}
 
+# Presentation-only default (issue #69): the devague CLI itself stays
+# model-agnostic (#20) — this is just what the table proposes before a human
+# edits it.
+DEFAULT_MODEL = "sonnet"
+MAX_SUMMARY_LEN = 72
+ELLIPSIS = "..."
+
+
+def marker(task_id):
+    """`[instruction: yes|no, accept: N]`, verbatim from the payload (#53 t13,
+    c12/h5) — no operator paraphrasing of the underlying summary/instruction."""
+    meta = tasks_meta.get(task_id) or {}
+    has_instruction = "yes" if meta.get("instruction") else "no"
+    accept_count = len(meta.get("acceptance_criteria") or [])
+    return f"{task_id} [instruction: {has_instruction}, accept: {accept_count}]"
+
+
+def truncate(summary):
+    if len(summary) > MAX_SUMMARY_LEN:
+        return summary[:MAX_SUMMARY_LEN] + ELLIPSIS
+    return summary
+
+
 print(f"Implementation split plan — plan: {plan_slug}")
 print()
 print("Dependency waves (from `devague plan waves`):")
 for i, wave in enumerate(waves, 1):
-    tasks = ", ".join(wave)
-    print(f"  Wave {i}: [{tasks}]")
+    markers = ", ".join(marker(task_id) for task_id in wave)
+    print(f"  Wave {i}: [{markers}]")
 
 print()
-print("Task assignments (proposed — edit before approving):")
+print("Task assignments (proposed — edit the Model column before approving):")
 print()
 
-headers = ("Task", "Wave", "Summary", "Instruction", "Accept.", "Agent type", "Model", "Scope note")
+headers = ("Wave", "Task", "Model", "Task summary")
 rows = []
 for i, wave in enumerate(waves, 1):
     for task_id in wave:
         meta = tasks_meta.get(task_id) or {}
-        # Verbatim from the payload — no operator paraphrasing (#53 t13, c12/h5).
+        # Verbatim from the payload — no operator paraphrasing (#53 t13, c12/h5) —
+        # never a placeholder unless the payload truly has no summary recorded.
         summary = meta.get("summary") or "(no summary recorded)"
-        has_instruction = "yes" if meta.get("instruction") else "no"
-        accept_count = str(len(meta.get("acceptance_criteria") or []))
-        rows.append((
-            task_id,
-            str(i),
-            summary,
-            has_instruction,
-            accept_count,
-            "subagent",
-            "cheaper/faster",
-            "TDD-scoped task; isolated worktree; tests gate merge",
-        ))
+        rows.append((str(i), task_id, DEFAULT_MODEL, truncate(summary)))
 
 col_widths = [max(len(h), max((len(r[j]) for r in rows), default=0))
               for j, h in enumerate(headers)]
@@ -187,8 +210,13 @@ for row in rows:
     print(row_str(row))
 
 print()
-print("Go/no-go: review the table above, edit agent type / model / scope as needed,")
-print("then confirm: \"Approved — assign to workforce\" or \"Edit first\".")
+print("Model column: edit each row to a real model token (e.g. haiku, sonnet,")
+print("opus, fable), optionally qualified with the harness when it matters")
+print("(e.g. colleague, codex) — the default above is a starting proposal, not")
+print("a recommendation.")
+print()
+print("Go/no-go: review the table above, edit the Model column as needed, then")
+print("confirm: \"Approved — assign to workforce\" or \"Edit first\".")
 print()
 print("Once approved, fan out wave by wave:")
 print("  1. Create one git worktree per task in the wave.")
@@ -199,6 +227,28 @@ print("  3. Await all tasks in the wave; then TDD-gate each merge (tests before
 print("  4. Advance to the next wave.")
 print("  5. Open the final PR (human gate 3) after all waves merge and tests pass.")
 PY
+
+    # ── End state: quote `devague plan deliverables` verbatim (#70 t6) ───────
+    # Never composed freehand — it is the single synthesized "what do we have
+    # in the end?" view (confirmed after-state claims, terminal tasks, and
+    # surviving open items). Forward the same --plan args used for waves.
+    # Degrades gracefully on an older devague that predates the verb: print
+    # one hint line naming the minimum version and keep exiting 0 — this
+    # section must never fail the script.
+    local deliverables_out deliverables_rc
+    set +e
+    deliverables_out="$("${DEVAGUE[@]}" plan deliverables "${extra_args[@]}" 2>/dev/null)"
+    deliverables_rc=$?
+    set -e
+
+    echo
+    if [ "$deliverables_rc" -eq 0 ]; then
+        echo 'End state (from `devague plan deliverables`):'
+        echo
+        printf '%s\n' "$deliverables_out"
+    else
+        echo 'hint: End state view requires devague >= 0.18.0 (devague plan deliverables)'
+    fi
 }
 
 main() {

devague-0.18.1/.claude/skills/deviate/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: deviate
+description: >
+  Stop an in-flight assign-to-workforce run the moment execution must diverge
+  from the confirmed plan, get explicit human approval for the divergence, and
+  record it as a first-class, append-only deviation record via `devague
+  deviate` before resuming — never fold a deviation silently into drift after
+  the fact. Use when the user says "deviate from the plan", "we need to change
+  the plan mid-run", "record a deviation", "this isn't matching the plan
+  anymore", or when a task agent discovers the confirmed plan no longer
+  matches reality partway through a workforce run. Authored and maintained in
+  agentculture/devague (origin = devague); guildmaster pulls this skill from
+  here and broadcasts it to the AgentCulture mesh — it is NOT vendored from
+  guildmaster like the inbound skills here.
+type: command
+---
+
+# deviate — record an approved mid-run departure from the confirmed plan
+
+The skill is named **`deviate`**; it is the **execution-time leg** of the
+devague method — the *sixth* leg, sitting between the two execution skills:
+
+```text
+scope -> think -> spec-to-plan -> assign-to-workforce -> deviate -> summarize-delivery
+```
+
+Where `/assign-to-workforce` fans out a converged plan's waves and
+`/summarize-delivery` closes the loop afterward, `/deviate` runs **during**
+the fan-out, at the exact moment reality stops matching the plan the human
+approved at gate 2 (the implementation split plan). It is not a new standing
+gate — it is the human owner of gate 2 **amending** the approved split
+mid-flight, scoped to the one deviation in front of them.
+
+The plan the user confirmed is a contract. Task agents hit constraints,
+discover a dependency was wrong, or find the acceptance criteria no longer
+make sense once code is in front of them. Until this skill existed, that
+reality either silently reshaped what got built (undocumented drift) or the
+run stalled with no recorded path forward. `/deviate` is that path: the
+departure is named, approved, and recorded **before** anyone keeps building
+against it.
+
+## The method
+
+1. **STOP the run.** The moment a task agent (or the main agent) discovers
+   the confirmed plan no longer matches what needs to happen, halt — do not
+   keep implementing against the stale contract and do not let the fan-out
+   continue past this task.
+2. **Present what, why, and what it affects.** Lay out, for the human:
+   - **what** is diverging — the specific change from the confirmed task(s);
+   - **why** — the constraint or discovery that forced it;
+   - **what it affects** — the plan item ref(s) involved (`--task`), any
+     other task ids or coverage targets it touches (`--affects`), and which
+     acceptance criteria are no longer accurate.
+3. **Get explicit human approval.** This is the one non-negotiable step. A
+   deviation is not real until a human says yes to *this specific* departure
+   — not a standing blanket permission, not an inference from silence.
+4. **Record it via `devague deviate`.** Once approved, record the deviation
+   as a first-class ledger entry (never edit the plan itself — the plan
+   stays the untouched historical contract; see `devague/delivery.py`). An
+   `--origin llm` record lands `proposed` and still needs the user's
+   `--confirm` — recording is not the same as approval landing as final.
+5. **Adjust the affected task briefs.** Update the working instructions the
+   task agent(s) are building against so they reflect the approved
+   departure, not the stale plan text.
+6. **Resume.** Only after the record exists (and, for an `llm`-origin record,
+   only after it is confirmed) does the fan-out continue.
+
+Deviations are never silently folded into drift after the fact — by the time
+`/summarize-delivery` runs, every departure from the plan already has a
+`dN` record with a reason, an approval, and an optional classification. The
+delivery summary quotes these records; it does not reconstruct drift from
+memory.
+
+## The shipped CLI surface
+
+This skill invokes the CLI directly and stays self-contained (if `devague`
+isn't on your PATH: `uv tool install devague`). Deviation state persists
+under `.devague/deliveries/<plan-slug>.json` — a peer of the plan store, keyed
+by the plan slug, and never touches the plan JSON itself.
+
+| Move | What it does |
+|------|---------------|
+| `devague deviate "<what>" --task <tN> --reason "<text>"` | Record a deviation against plan item `<tN>`. User-origin (the default) auto-approves. |
+| `devague deviate "<what>" --task <tN> --reason "<text>" --affects <ref> [<ref> ...]` | Same, also naming every other plan item ref or coverage target the deviation touches (repeatable). |
+| `devague deviate "<what>" --task <tN> --reason "<text>" --classification acceptable\|risky\|needs-follow-up` | Same, tagging the deviation with the classification the drift-entry contract consumes downstream. |
+| `devague deviate "<what>" --task <tN> --reason "<text>" --origin llm` | An LLM-proposed record; lands `proposed`, not `approved`. |
+| `devague deviate --confirm <dN>` | User-only: approve a `proposed` deviation. |
+| `devague deviate --reject <dN>` | User-only: reject a `proposed` (or any) deviation. |
+| `devague deviate --list [--json]` | Read every recorded deviation back (also the default action with no positional/flag). |
+| `devague deviate ... --plan <slug>` | Target a plan other than the current one. |
+
+`--reason` is required on every record — omitting it is refused with a hint.
+`--task` naming the plan item ref is likewise required.
+
+## Hard rules (do not violate)
+
+- **Never record a deviation the human did not approve.** `devague deviate`
+  without `--origin llm` auto-approves the instant it is run — so a
+  user-origin record IS the approval. Only run it after the human has said
+  yes to this specific departure, never preemptively "to be safe."
+- **Never continue past a refused approval.** If the human does not approve,
+  the run stays stopped on that task. Do not record the deviation anyway, do
+  not quietly implement the diverging approach, and do not advance the wave.
+- **LLM-origin records stay proposed until the user confirms.** `--origin
+  llm` lands `proposed`; only `devague deviate --confirm <dN>` (user-only)
+  makes it `approved`. Same anti-fabrication contract as every other origin
+  in the method — an agent's own proposal never self-confirms.
+- **Deviations are never silently folded into drift after the fact.** Every
+  departure from the confirmed plan gets a `dN` record at the moment it
+  happens — not reconstructed from memory when `/summarize-delivery` runs
+  later.
+- **The CLI stays non-orchestrating (issue #20).** `devague deviate` records
+  a decision the human already made; it does not spawn agents, gate merges,
+  mark tasks done, or make the approval decision itself. Recording is
+  deterministic — no LLM calls inside the CLI.
+- **This is not a fourth standing gate.** `/assign-to-workforce`'s three
+  human gates are the exported spec, the implementation split plan, and the
+  final PR. `/deviate` does not add a fourth — it is the human owner of gate
+  2 amending the approved split for one scoped, in-flight decision.
+
+## Worked example
+
+Mid-fan-out on task `t4`, the task agent discovers the acceptance criteria
+assumed a helper that task `t2` never actually shipped:
+
+```bash
+# 1. STOP — the main agent halts t4's worktree before more code lands
+#    against a criterion that can't be met as written.
+
+# 2. Present what/why/what-it-affects to the human:
+#    what:    t4's acceptance criterion 2 assumes a `--json` flag on a
+#             helper that t2 shipped without one
+#    why:     t2's scope was cut to land its wave on time
+#    affects: t4 (this task), and coverage target c9 (the criterion in
+#             question)
+
+# --- HUMAN: approves dropping the --json assumption from t4's criterion ---
+
+# 3. Record the approved deviation
+devague deviate "drop the --json assumption from t4's acceptance criterion" \
+  --task t4 --reason "t2 shipped its helper without --json to land its wave on time" \
+  --affects t2 --affects c9 --classification acceptable
+
+# 4. Adjust t4's working brief to match what was approved, then resume the
+#    task agent against the corrected instruction.
+
+# Read the ledger back at any point:
+devague deviate --list
+devague deviate --list --json
+```
+
+If the agent had proposed the record itself (`--origin llm`), the same
+record would land `proposed` and need an explicit
+`devague deviate --confirm d1` from the user before `/summarize-delivery`
+could cite it as approved.
+
+## After recording — resume, then hand off to /summarize-delivery
+
+Once the affected task briefs are adjusted and the fan-out resumes, nothing
+further is needed from this skill — the record already lives in the delivery
+store. When the run reaches `/summarize-delivery`, that skill's Drift From
+Plan and Mid-work Decisions sections quote these records by their `dN` id
+instead of reconstructing drift from memory, so the connective tissue between
+the confirmed plan and the delivery summary is the ledger this skill wrote,
+not anyone's recollection of the run.
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, the
+*sixth* in the outbound family after `/scope`, `/think`, `/spec-to-plan`,
+`/assign-to-workforce`, and `/summarize-delivery`, covering the execution-time
+leg that runs inside an `/assign-to-workforce` fan-out. guildmaster pulls it
+from here and broadcasts it to the AgentCulture mesh; because devague is
+upstream, it is **never re-vendored back** from guildmaster's re-broadcast
+copy. 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.17.2 → devague-0.18.1}/.claude/skills/scope/SKILL.md

@@ -158,8 +158,10 @@ LLM-proposed claims there, as always.
 ## Provenance
 
 This is a **first-party** skill — its origin is `agentculture/devague`, the
-*fourth* in the outbound family after `/think`, `/spec-to-plan`, and
-`/assign-to-workforce`, covering the pre-frame exploration leg. guildmaster
-pulls it from here and broadcasts it to the AgentCulture mesh. The
+*fourth* authored in the outbound family (after `/think`, `/spec-to-plan`, and
+`/assign-to-workforce`) but the **opening leg** of the flow, covering the
+pre-frame exploration that runs before `/think`. guildmaster pulls it from here
+and broadcasts it to the AgentCulture mesh; because devague is upstream, it is
+**never re-vendored back** from guildmaster's re-broadcast copy. 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.17.2 → devague-0.18.1}/.claude/skills/spec-to-plan/SKILL.md

@@ -11,7 +11,7 @@ description: >
   build plan", or after the /think skill exports a spec. Authored and maintained
   in agentculture/devague (origin = devague); guildmaster pulls this skill from
   here and broadcasts it to the AgentCulture mesh — it is NOT vendored from
-  guildmaster like the other skills here.
+  guildmaster like the inbound skills here.
 type: command
 ---
 

{devague-0.17.2 → devague-0.18.1}/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh

@@ -8,7 +8,7 @@
 # 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
+# Origin: authored and maintained in agentculture/devague. guildmaster 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.
 #