devague 0.14.0__tar.gz → 0.15.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. {devague-0.14.0 → devague-0.15.0}/.claude/skills/assign-to-workforce/SKILL.md +10 -2
  2. devague-0.15.0/.claude/skills/scope/SKILL.md +132 -0
  3. {devague-0.14.0 → devague-0.15.0}/.claude/skills/spec-to-plan/SKILL.md +23 -1
  4. {devague-0.14.0 → devague-0.15.0}/.claude/skills/think/SKILL.md +39 -2
  5. devague-0.15.0/.devague/current_plan +1 -0
  6. devague-0.15.0/.devague/frames/devague-ships-a-sharper-end-to-end-method-a-guided.json +276 -0
  7. devague-0.15.0/.devague/plans/devague-ships-a-sharper-end-to-end-method-a-guided.json +402 -0
  8. {devague-0.14.0 → devague-0.15.0}/CHANGELOG.md +26 -0
  9. {devague-0.14.0 → devague-0.15.0}/CLAUDE.md +21 -5
  10. {devague-0.14.0 → devague-0.15.0}/PKG-INFO +1 -1
  11. devague-0.15.0/docs/plans/2026-07-01-devague-ships-a-sharper-end-to-end-method-a-guided.md +118 -0
  12. {devague-0.14.0 → devague-0.15.0}/docs/skill-sources.md +8 -6
  13. {devague-0.14.0 → devague-0.15.0}/docs/skills.md +25 -4
  14. devague-0.15.0/docs/specs/2026-07-01-devague-ships-a-sharper-end-to-end-method-a-guided.md +66 -0
  15. {devague-0.14.0 → devague-0.15.0}/pyproject.toml +1 -1
  16. {devague-0.14.0 → devague-0.15.0}/uv.lock +1 -1
  17. devague-0.14.0/.devague/current_plan +0 -1
  18. {devague-0.14.0 → devague-0.15.0}/.claude/skills/agent-config/SKILL.md +0 -0
  19. {devague-0.14.0 → devague-0.15.0}/.claude/skills/agent-config/data/backend-fingerprints.yaml +0 -0
  20. {devague-0.14.0 → devague-0.15.0}/.claude/skills/agent-config/scripts/show.sh +0 -0
  21. {devague-0.14.0 → devague-0.15.0}/.claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh +0 -0
  22. {devague-0.14.0 → devague-0.15.0}/.claude/skills/cicd/SKILL.md +0 -0
  23. {devague-0.14.0 → devague-0.15.0}/.claude/skills/cicd/scripts/_resolve-nick.sh +0 -0
  24. {devague-0.14.0 → devague-0.15.0}/.claude/skills/cicd/scripts/portability-lint.sh +0 -0
  25. {devague-0.14.0 → devague-0.15.0}/.claude/skills/cicd/scripts/pr-reply.sh +0 -0
  26. {devague-0.14.0 → devague-0.15.0}/.claude/skills/cicd/scripts/pr-status.sh +0 -0
  27. {devague-0.14.0 → devague-0.15.0}/.claude/skills/cicd/scripts/workflow.sh +0 -0
  28. {devague-0.14.0 → devague-0.15.0}/.claude/skills/communicate/SKILL.md +0 -0
  29. {devague-0.14.0 → devague-0.15.0}/.claude/skills/communicate/scripts/fetch-issues.sh +0 -0
  30. {devague-0.14.0 → devague-0.15.0}/.claude/skills/communicate/scripts/mesh-message.sh +0 -0
  31. {devague-0.14.0 → devague-0.15.0}/.claude/skills/communicate/scripts/post-comment.sh +0 -0
  32. {devague-0.14.0 → devague-0.15.0}/.claude/skills/communicate/scripts/post-issue.sh +0 -0
  33. {devague-0.14.0 → devague-0.15.0}/.claude/skills/communicate/scripts/templates/skill-new-brief.md +0 -0
  34. {devague-0.14.0 → devague-0.15.0}/.claude/skills/communicate/scripts/templates/skill-update-brief.md +0 -0
  35. {devague-0.14.0 → devague-0.15.0}/.claude/skills/doc-test-alignment/SKILL.md +0 -0
  36. {devague-0.14.0 → devague-0.15.0}/.claude/skills/doc-test-alignment/scripts/check.sh +0 -0
  37. {devague-0.14.0 → devague-0.15.0}/.claude/skills/pypi-maintainer/SKILL.md +0 -0
  38. {devague-0.14.0 → devague-0.15.0}/.claude/skills/pypi-maintainer/scripts/switch-source.sh +0 -0
  39. {devague-0.14.0 → devague-0.15.0}/.claude/skills/recall/SKILL.md +0 -0
  40. {devague-0.14.0 → devague-0.15.0}/.claude/skills/recall/scripts/recall.sh +0 -0
  41. {devague-0.14.0 → devague-0.15.0}/.claude/skills/remember/SKILL.md +0 -0
  42. {devague-0.14.0 → devague-0.15.0}/.claude/skills/remember/scripts/remember.sh +0 -0
  43. {devague-0.14.0 → devague-0.15.0}/.claude/skills/run-tests/SKILL.md +0 -0
  44. {devague-0.14.0 → devague-0.15.0}/.claude/skills/run-tests/scripts/test.sh +0 -0
  45. {devague-0.14.0 → devague-0.15.0}/.claude/skills/sonarclaude/SKILL.md +0 -0
  46. {devague-0.14.0 → devague-0.15.0}/.claude/skills/sonarclaude/scripts/sonar.sh +0 -0
  47. {devague-0.14.0 → devague-0.15.0}/.claude/skills/spec-to-plan/scripts/spec-to-plan.sh +0 -0
  48. {devague-0.14.0 → devague-0.15.0}/.claude/skills/think/scripts/think.sh +0 -0
  49. {devague-0.14.0 → devague-0.15.0}/.claude/skills/version-bump/SKILL.md +0 -0
  50. {devague-0.14.0 → devague-0.15.0}/.claude/skills/version-bump/scripts/bump.py +0 -0
  51. {devague-0.14.0 → devague-0.15.0}/.claude/skills.local.yaml.example +0 -0
  52. {devague-0.14.0 → devague-0.15.0}/.devague/frames/devague-0-6-0-ships-the-human-review-loop-devague.json +0 -0
  53. {devague-0.14.0 → devague-0.15.0}/.devague/frames/devague-now-ships-a-documented-spec-contract-every.json +0 -0
  54. {devague-0.14.0 → devague-0.15.0}/.devague/frames/devague-turns-a-converged-plan-into-parallel-simpl.json +0 -0
  55. {devague-0.14.0 → devague-0.15.0}/.devague/plans/devague-0-6-0-ships-the-human-review-loop-devague.json +0 -0
  56. {devague-0.14.0 → devague-0.15.0}/.devague/plans/devague-now-ships-a-documented-spec-contract-every.json +0 -0
  57. {devague-0.14.0 → devague-0.15.0}/.devague/plans/devague-turns-a-converged-plan-into-parallel-simpl.json +0 -0
  58. {devague-0.14.0 → devague-0.15.0}/.flake8 +0 -0
  59. {devague-0.14.0 → devague-0.15.0}/.github/workflows/publish.yml +0 -0
  60. {devague-0.14.0 → devague-0.15.0}/.github/workflows/security-checks.yml +0 -0
  61. {devague-0.14.0 → devague-0.15.0}/.github/workflows/tests.yml +0 -0
  62. {devague-0.14.0 → devague-0.15.0}/.gitignore +0 -0
  63. {devague-0.14.0 → devague-0.15.0}/.markdownlint-cli2.yaml +0 -0
  64. {devague-0.14.0 → devague-0.15.0}/.pre-commit-config.yaml +0 -0
  65. {devague-0.14.0 → devague-0.15.0}/LICENSE +0 -0
  66. {devague-0.14.0 → devague-0.15.0}/README.md +0 -0
  67. {devague-0.14.0 → devague-0.15.0}/culture.yaml +0 -0
  68. {devague-0.14.0 → devague-0.15.0}/devague/__init__.py +0 -0
  69. {devague-0.14.0 → devague-0.15.0}/devague/__main__.py +0 -0
  70. {devague-0.14.0 → devague-0.15.0}/devague/cli/__init__.py +0 -0
  71. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/__init__.py +0 -0
  72. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/capture.py +0 -0
  73. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/confirm.py +0 -0
  74. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/converge.py +0 -0
  75. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/explain.py +0 -0
  76. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/export.py +0 -0
  77. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/interrogate.py +0 -0
  78. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/learn.py +0 -0
  79. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/list_frames.py +0 -0
  80. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/new.py +0 -0
  81. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/park.py +0 -0
  82. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/plan.py +0 -0
  83. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/question.py +0 -0
  84. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/reject.py +0 -0
  85. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/review.py +0 -0
  86. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/show.py +0 -0
  87. {devague-0.14.0 → devague-0.15.0}/devague/cli/_commands/status.py +0 -0
  88. {devague-0.14.0 → devague-0.15.0}/devague/cli/_errors.py +0 -0
  89. {devague-0.14.0 → devague-0.15.0}/devague/cli/_frames.py +0 -0
  90. {devague-0.14.0 → devague-0.15.0}/devague/cli/_output.py +0 -0
  91. {devague-0.14.0 → devague-0.15.0}/devague/cli/_paths.py +0 -0
  92. {devague-0.14.0 → devague-0.15.0}/devague/cli/_plans.py +0 -0
  93. {devague-0.14.0 → devague-0.15.0}/devague/cli/_status.py +0 -0
  94. {devague-0.14.0 → devague-0.15.0}/devague/convergence.py +0 -0
  95. {devague-0.14.0 → devague-0.15.0}/devague/frame.py +0 -0
  96. {devague-0.14.0 → devague-0.15.0}/devague/plan.py +0 -0
  97. {devague-0.14.0 → devague-0.15.0}/devague/plan_convergence.py +0 -0
  98. {devague-0.14.0 → devague-0.15.0}/devague/plan_store.py +0 -0
  99. {devague-0.14.0 → devague-0.15.0}/devague/questions_io.py +0 -0
  100. {devague-0.14.0 → devague-0.15.0}/devague/render/__init__.py +0 -0
  101. {devague-0.14.0 → devague-0.15.0}/devague/render/frame_md.py +0 -0
  102. {devague-0.14.0 → devague-0.15.0}/devague/render/plan_md.py +0 -0
  103. {devague-0.14.0 → devague-0.15.0}/devague/render/review_md.py +0 -0
  104. {devague-0.14.0 → devague-0.15.0}/devague/render/spec_md.py +0 -0
  105. {devague-0.14.0 → devague-0.15.0}/devague/store.py +0 -0
  106. {devague-0.14.0 → devague-0.15.0}/docs/assign-to-workforce-worked-example.md +0 -0
  107. {devague-0.14.0 → devague-0.15.0}/docs/examples/contract-example.json +0 -0
  108. {devague-0.14.0 → devague-0.15.0}/docs/llm-guidance.md +0 -0
  109. {devague-0.14.0 → devague-0.15.0}/docs/plans/2026-05-23-devague-0-6-0-ships-the-human-review-loop-devague.md +0 -0
  110. {devague-0.14.0 → devague-0.15.0}/docs/plans/2026-05-23-devague-now-ships-a-documented-spec-contract-every.md +0 -0
  111. {devague-0.14.0 → devague-0.15.0}/docs/plans/2026-05-23-devague-turns-a-converged-plan-into-parallel-simpl.md +0 -0
  112. {devague-0.14.0 → devague-0.15.0}/docs/reviews/spec-contract-frame-review.md +0 -0
  113. {devague-0.14.0 → devague-0.15.0}/docs/spec-contract.md +0 -0
  114. {devague-0.14.0 → devague-0.15.0}/docs/specs/2026-05-23-devague-0-6-0-ships-the-human-review-loop-devague.md +0 -0
  115. {devague-0.14.0 → devague-0.15.0}/docs/specs/2026-05-23-devague-now-ships-a-documented-spec-contract-every.md +0 -0
  116. {devague-0.14.0 → devague-0.15.0}/docs/specs/2026-05-23-devague-turns-a-converged-plan-into-parallel-simpl.md +0 -0
  117. {devague-0.14.0 → devague-0.15.0}/docs/superpowers/plans/2026-05-22-specifix-onboarding.md +0 -0
  118. {devague-0.14.0 → devague-0.15.0}/docs/superpowers/plans/2026-05-23-devague-rename.md +0 -0
  119. {devague-0.14.0 → devague-0.15.0}/docs/superpowers/plans/2026-05-23-devague-working-backwards-engine.md +0 -0
  120. {devague-0.14.0 → devague-0.15.0}/docs/superpowers/specs/2026-05-22-specifix-onboarding-design.md +0 -0
  121. {devague-0.14.0 → devague-0.15.0}/docs/superpowers/specs/2026-05-23-devague-spec-to-plan-design.md +0 -0
  122. {devague-0.14.0 → devague-0.15.0}/docs/superpowers/specs/2026-05-23-devague-working-backwards-design.md +0 -0
  123. {devague-0.14.0 → devague-0.15.0}/sonar-project.properties +0 -0
  124. {devague-0.14.0 → devague-0.15.0}/tests/__init__.py +0 -0
  125. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_affordances.py +0 -0
  126. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_chassis.py +0 -0
  127. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_converge_export.py +0 -0
  128. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_errors.py +0 -0
  129. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_learn.py +0 -0
  130. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_moves.py +0 -0
  131. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_output.py +0 -0
  132. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_paths.py +0 -0
  133. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_plan.py +0 -0
  134. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_question.py +0 -0
  135. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_review.py +0 -0
  136. {devague-0.14.0 → devague-0.15.0}/tests/test_cli_status.py +0 -0
  137. {devague-0.14.0 → devague-0.15.0}/tests/test_contract.py +0 -0
  138. {devague-0.14.0 → devague-0.15.0}/tests/test_convergence.py +0 -0
  139. {devague-0.14.0 → devague-0.15.0}/tests/test_frame.py +0 -0
  140. {devague-0.14.0 → devague-0.15.0}/tests/test_offline.py +0 -0
  141. {devague-0.14.0 → devague-0.15.0}/tests/test_package.py +0 -0
  142. {devague-0.14.0 → devague-0.15.0}/tests/test_plan.py +0 -0
  143. {devague-0.14.0 → devague-0.15.0}/tests/test_plan_convergence.py +0 -0
  144. {devague-0.14.0 → devague-0.15.0}/tests/test_plan_store.py +0 -0
  145. {devague-0.14.0 → devague-0.15.0}/tests/test_render.py +0 -0
  146. {devague-0.14.0 → devague-0.15.0}/tests/test_render_plan.py +0 -0
  147. {devague-0.14.0 → devague-0.15.0}/tests/test_review_loop_integration.py +0 -0
  148. {devague-0.14.0 → devague-0.15.0}/tests/test_review_loop_invariants.py +0 -0
  149. {devague-0.14.0 → devague-0.15.0}/tests/test_spec_to_plan_skill.py +0 -0
  150. {devague-0.14.0 → devague-0.15.0}/tests/test_store.py +0 -0
  151. {devague-0.14.0 → devague-0.15.0}/tests/test_think_skill.py +0 -0
@@ -110,7 +110,13 @@ Once the human approves, the main agent fans out each wave in order:
110
110
 
111
111
  2. **Spawn a task agent** inside that worktree (using the approved model from
112
112
  the split plan), with:
113
- - The task id, summary, and acceptance criteria as its brief.
113
+ - The task id, summary, acceptance criteria, and covered targets as its
114
+ brief — **quoted verbatim** from `devague plan show --json` (or the
115
+ exported plan-md). No operator paraphrasing: the plan text *is* the
116
+ contract the user confirmed, and a reworded brief silently drifts from it.
117
+ (When the enriched `waves --json` payload lands — devague#53, task t9 —
118
+ the brief comes straight from that one payload, per-task instructions
119
+ included.)
114
120
  - Instruction to work **test-first** (TDD): write the failing test(s) that
115
121
  match the acceptance criteria before implementing.
116
122
  - Instruction to commit its work to the worktree branch.
@@ -228,7 +234,9 @@ bash .claude/skills/cicd/scripts/workflow.sh open
228
234
 
229
235
  The exported plan-md from `devague plan export` is the standing brief for
230
236
  each task agent — its task id, summary, acceptance criteria, and the targets
231
- it covers are already in that file.
237
+ it covers are already in that file. Quote those fields **verbatim** into each
238
+ task agent's brief; the fan-out is honest only if what the subagent builds
239
+ against is exactly what the user confirmed in the plan.
232
240
 
233
241
  ## Provenance
234
242
 
@@ -0,0 +1,132 @@
1
+ ---
2
+ name: scope
3
+ description: >
4
+ Explore the scope of a vague idea BEFORE framing it into a spec (the
5
+ idea→scope leg; the optional opening move ahead of /think). Survey the
6
+ surfaces the idea touches — code, docs, skills, CI, sibling repos — and seed
7
+ the coming Announcement Frame with boundary, non-goal, and assumption claims
8
+ that cite what was actually explored (provenance, not generic disclaimers).
9
+ Use when the user says "explore scope", "scope this idea", "what does this
10
+ touch", "map the scope", "scope exploration", or when an idea touches an
11
+ existing codebase and speccing it cold would mean guessing its boundaries.
12
+ Hand off to the sibling /think skill to build the frame. Authored and
13
+ maintained in agentculture/devague (origin = devague); guildmaster pulls this
14
+ skill from here and broadcasts it to the AgentCulture mesh — it is NOT
15
+ vendored from guildmaster like the inbound skills here.
16
+ type: command
17
+ ---
18
+
19
+ # scope — explore what an idea touches before you frame it
20
+
21
+ The skill is named **`scope`**; it is the **opening leg** of the devague method
22
+ — run it *before* the sibling **`/think`** skill frames an idea into a spec.
23
+ Where `/think` converges on *what* to build, `/scope` grounds *where the idea
24
+ lives*: which surfaces it touches, which it must not, and what is genuinely
25
+ unknown — so the frame starts from explored territory instead of guesses.
26
+
27
+ This comes from the sharper end-to-end method spec (devague#53): scope grounded
28
+ up front means convergence measures real coverage instead of vibes. The
29
+ exploration itself is **agent-side work** — the devague CLI stays deterministic
30
+ and never explores anything (#20).
31
+
32
+ ## When to use — and when to skip
33
+
34
+ Use `/scope` when the idea touches an existing codebase or ecosystem: a feature
35
+ in a real repo, a process change across skills, anything where boundaries are
36
+ discoverable rather than invented.
37
+
38
+ **Skip it freely for small ideas.** Scope exploration is *not* a mandatory
39
+ first stage — the move-driven adaptive arc stays intact, and an idea that fits
40
+ in one announcement can go straight to `/think`. (This is a recorded non-goal
41
+ of the method: no wizard.)
42
+
43
+ ## The method
44
+
45
+ 1. **Enumerate candidate surfaces.** List what the idea *might* touch: source
46
+ packages, CLI verbs, renderers, schemas, tests, docs, skills, CI workflows,
47
+ sibling repos. `git ls-files` and the repo's `CLAUDE.md` are the usual map.
48
+ 2. **Explore each surface read-only.** Read enough of each candidate to decide:
49
+ touched, not touched, or unknown. Exploration never mutates anything —
50
+ no edits, no state changes, no CLI moves yet.
51
+ 3. **Classify every finding.** Each explored surface yields one of:
52
+ - **in scope** — the idea changes it → becomes a `requirement` or
53
+ `assumption` claim in the frame;
54
+ - **out of scope** — the idea must not change it → becomes a `boundary` or
55
+ `non_goal` claim;
56
+ - **genuinely unknown** — can't tell without a decision → becomes a `park`
57
+ (open vagueness) or a `question` (pending user decision).
58
+ 4. **Seed the frame with provenance.** When `/think` starts, capture the
59
+ findings as claims whose text **cites the surface explored** — "the CLI
60
+ stays deterministic per issue 20; scope exploration is agent-side"
61
+ beats "we won't overreach". Provenance, not generic disclaimers: a reviewer
62
+ should be able to trace every boundary claim back to something you read.
63
+
64
+ ## How findings land (the shipped surface)
65
+
66
+ There is no `devague scope` CLI verb yet — findings land through the existing
67
+ `devague` moves (this skill invokes the CLI directly and stays self-contained;
68
+ if `devague` isn't on your PATH: `uv tool install devague`):
69
+
70
+ | Finding | Move |
71
+ |---------|------|
72
+ | in scope (the idea changes this) | `capture --kind requirement` / `--kind assumption` (with `--origin llm` if you proposed it) |
73
+ | out of scope (must not change) | `capture --kind boundary` / `--kind non_goal` |
74
+ | genuinely unknown, needs a user decision | `question "<text>"` (later `question --resolve <qid> --decision "<text>"`) |
75
+ | genuinely unknown, not decidable now | `park "<text>" --kind unknown_blocking\|unknown_nonblocking` |
76
+
77
+ A deterministic **`devague scope` move** — recording explored surfaces and
78
+ findings as first-class frame state with provenance links — is **planned, not
79
+ shipped**: it is task t3 of the committed sharper-end-to-end-method plan
80
+ (`docs/plans/2026-07-01-devague-ships-a-sharper-end-to-end-method-a-guided.md`,
81
+ devague#53). Do not run `devague scope` until it exists; this skill documents
82
+ the surface as built.
83
+
84
+ ## Hard rules (do not violate)
85
+
86
+ - **Exploration is read-only.** Surveying scope never edits files, never
87
+ mutates frame state, never runs a mutating CLI move.
88
+ - **Provenance in every seeded claim.** A scope-derived claim cites what was
89
+ explored. If you didn't read it, don't claim it.
90
+ - **LLM proposals stay proposed.** Findings you capture with `--origin llm`
91
+ land `proposed`; the user confirms. Same anti-fabrication contract as
92
+ `/think`.
93
+ - **Don't become a wizard.** Scope exploration is optional-by-size and
94
+ adaptive. Never block a small idea on a survey it doesn't need.
95
+
96
+ ## Worked example
97
+
98
+ Scoping "devague exports should carry per-item instructions" against the
99
+ devague repo itself:
100
+
101
+ ```bash
102
+ # 1–2. enumerate + explore (read-only)
103
+ git ls-files devague/ | head -30 # the CLI package map
104
+ # read: devague/frame.py (claim model), devague/render/spec_md.py (renderer),
105
+ # docs/spec-contract.md (schema contract), .claude/skills/think/SKILL.md
106
+
107
+ # 3–4. hand off to /think and seed with provenance
108
+ devague new "devague exports carry per-item instructions" --title "per-item instructions"
109
+ devague capture --origin llm --kind requirement "claims gain an optional instruction field — devague/frame.py claim model + docs/spec-contract.md schema both need a bump"
110
+ devague capture --origin llm --kind boundary "render/spec_md.py renders instructions verbatim; absent instructions render nothing — the renderer never fabricates filler"
111
+ devague capture --origin llm --kind non_goal "no LLM calls land inside the CLI (issue 20) — instruction text is authored by the operator/user, never generated in-CLI"
112
+ devague question "do instructions attach to frame claims, plan tasks, or both?"
113
+ ```
114
+
115
+ Every claim above names the file or issue that was actually read — that is the
116
+ provenance bar.
117
+
118
+ ## After scoping — hand off to /think
119
+
120
+ Scope exploration produces no artifact of its own (until the planned CLI move
121
+ lands, the findings *are* the seeded claims). When the survey is done, start
122
+ the frame with `/think` and capture the findings as the frame's opening claims.
123
+ The user confirms LLM-proposed ones there, as always.
124
+
125
+ ## Provenance
126
+
127
+ This is a **first-party** skill — its origin is `agentculture/devague`, the
128
+ *fourth* in the outbound family after `/think`, `/spec-to-plan`, and
129
+ `/assign-to-workforce`, covering the pre-frame exploration leg. guildmaster
130
+ pulls it from here and broadcasts it to the AgentCulture mesh. The
131
+ `cite, don't import` policy still holds: downstream repos copy it, they don't
132
+ symlink or depend on it. See `docs/skill-sources.md`.
@@ -55,7 +55,7 @@ install hint. Every move — including `status` — is forwarded verbatim as
55
55
  | `accept <tN> "<crit>"` | Add an acceptance criterion to a task. |
56
56
  | `depend <tN> --on <tM>` | Record that task `tN` depends on `tM`. |
57
57
  | `cover <tN> --target <c*/h*>` | Mark a task as covering a coverage target. |
58
- | `confirm <tN>` / `reject <tN>` | Resolve a task. **User-only decision.** |
58
+ | `confirm <tN>` / `reject <tN>` | Resolve a task. **User-only decision.** Takes **one task id per call** — loop for batches (unlike the frame engine's transactional multi-id `confirm`; parity is a recorded follow-up in the 2026-07-01 plan, devague#53). |
59
59
  | `risk "<text>" --kind <kind>` | Record a first-class plan risk (`--task <tN>` to attach). |
60
60
  | `converge` | Evaluate the gate against the **live** source frame; list remaining gaps. |
61
61
  | `export` | Write the buildable plan to `docs/plans/` — only after `converge` passes. |
@@ -119,6 +119,28 @@ When authoring a plan that will be built via parallel execution (fanned out to
119
119
  multiple agents via the downstream `/assign-to-workforce` skill), prefer the
120
120
  following discipline to maximize parallelism and minimize merge friction:
121
121
 
122
+ ### Acceptance criteria are the instruction contract (today)
123
+
124
+ Until the planned per-task `instruction` field lands (task t5 of the
125
+ sharper-end-to-end-method plan, devague#53), **acceptance criteria are where a
126
+ task's working instructions live**. Write each criterion as something a cheaper
127
+ model can execute test-first without re-deriving the design: name the files or
128
+ modules the task owns, the observable behavior that proves it done, and the
129
+ compatibility constraints ("pre-existing plans load with no error"). A criterion
130
+ a subagent can't act on alone is a summary, not a contract. The enriched
131
+ `waves --json` payload (carrying summary + instructions + acceptance criteria +
132
+ covered targets per task) is planned in the same increment — until then, the
133
+ brief is composed from `plan show --json` + the exported plan-md.
134
+
135
+ ### Text hygiene for exports
136
+
137
+ The exported plan-md must pass markdown lint. The plan's H1 inherits the
138
+ *frame's* title — set a short, period-free `--title` at `devague new` time (see
139
+ `/think`'s export-hygiene rules). And backtick angle-bracket placeholders in
140
+ task text (`` `instruct <tN>` ``, not `instruct <tN>`) — bare ones fail MD033.
141
+ There is no task-edit move yet, so fixing text after confirmation means
142
+ hand-editing state JSON.
143
+
122
144
  ### Small and crisply scoped
123
145
 
124
146
  Each task should be **small enough for a simpler or cheaper model to build
@@ -37,6 +37,15 @@ This skill is the operator: a portable wrapper that resolves the CLI and
37
37
  forwards every move verbatim — including `status`, the read-only verb that reads
38
38
  the convergence gate and tells you the recommended next move.
39
39
 
40
+ **Explore scope first when the idea touches an existing codebase.** The sibling
41
+ **`/scope`** skill is the optional opening leg: survey the surfaces the idea
42
+ touches *before* framing, then seed the frame with `boundary` / `non_goal` /
43
+ `assumption` claims that cite what was actually explored (provenance, not
44
+ generic disclaimers). Small ideas skip it and start here — no wizard. (From the
45
+ sharper end-to-end method spec, devague#53; the deterministic `devague scope`
46
+ move that will record findings as first-class state is planned there, not yet
47
+ shipped.)
48
+
40
49
  ## How to run
41
50
 
42
51
  The entry point is `scripts/think.sh`. Invoke it from the repository you are
@@ -58,7 +67,7 @@ for portable resolution.
58
67
 
59
68
  | Move | What it does |
60
69
  |------|--------------|
61
- | `new "<announcement>"` | Start a frame from the announcement (the first move). Seeds an auto-confirmed `announcement` claim. |
70
+ | `new "<announcement>" [--title "<short>"]` | Start a frame from the announcement (the first move). Seeds an auto-confirmed `announcement` claim. Always pass `--title` (see *Export hygiene*). |
62
71
  | `capture --kind <kind> "<text>"` | Record + classify a claim. `--origin llm` lands it as `proposed`. |
63
72
  | `interrogate <id> --honesty "…"` | Attach an honesty condition (what must be true). Also `--hard-question`, `--risk`, `--contradicts`, `--blocking`. |
64
73
  | `confirm <id> [<id>…]` / `reject <id> [<id>…]` | Resolve one or more claims (`c*`) / honesty conditions (`h*`) in one **transactional** call. **User-only decision.** Also `confirm --from-review <file>` to apply an edited review artifact. |
@@ -113,6 +122,34 @@ recommended next move (first gap):
113
122
 
114
123
  Run it whenever you're unsure what to do next.
115
124
 
125
+ ### Export hygiene — keep the artifacts lint-clean
126
+
127
+ The exported spec-md must pass the repo's markdown lint. Two gotchas found by
128
+ dogfooding (devague#53), both cheap to avoid up front and expensive after —
129
+ there is no retitle/edit move yet, so fixing them later means hand-editing
130
+ state JSON and re-exporting:
131
+
132
+ - **Always pass `--title "<short title>"` to `new`.** The title becomes the H1
133
+ of every exported artifact (the plan inherits it too). The default is the
134
+ full announcement — long, and if it ends with a period the H1 fails MD026
135
+ (trailing punctuation). Keep the title short, no trailing period.
136
+ - **Backtick angle-bracket tokens.** A placeholder like `--seeds <claim-id>`
137
+ in claim or honesty-condition text renders as inline HTML (MD033) unless
138
+ wrapped in backticks. Write `` `--seeds <claim-id>` ``, not the bare form.
139
+ - **Lint before committing:** `markdownlint-cli2 "docs/specs/<file>.md"`.
140
+
141
+ ### Pending decisions — the `question` loop
142
+
143
+ When a genuine design decision surfaces mid-frame, don't guess and don't stall:
144
+
145
+ 1. `question "<the decision to make>"` — records it as durable working state.
146
+ 2. Put it to the user (with concrete options where possible).
147
+ 3. `question --resolve <qid> --decision "<what the user chose>"`.
148
+ 4. `capture --kind decision "<the choice>"` — a user-origin capture
149
+ auto-confirms, making the decision a first-class frame claim.
150
+
151
+ This keeps every user decision traceable from question → resolution → claim.
152
+
116
153
  ## Hard rules (do not violate)
117
154
 
118
155
  These are the point of the method — convergence must mean something.
@@ -149,7 +186,7 @@ A short end-to-end session (the kind you'd run to spec a feature like
149
186
  ```bash
150
187
  d() { bash .claude/skills/think/scripts/think.sh "$@"; }
151
188
 
152
- d new "Devague ships a documented spec contract"
189
+ d new "Devague ships a documented spec contract" --title "documented spec contract"
153
190
  d capture --kind audience "devague + the assisting LLM"
154
191
  d capture --kind after_state "a vague idea becomes a buildable, pressure-tested spec"
155
192
  d capture --kind why_it_matters "specs converge on evidence, not vibes"
@@ -0,0 +1 @@
1
+ devague-ships-a-sharper-end-to-end-method-a-guided
@@ -0,0 +1,276 @@
1
+ {
2
+ "slug": "devague-ships-a-sharper-end-to-end-method-a-guided",
3
+ "title": "devague ships a sharper end-to-end method",
4
+ "schema_version": 1,
5
+ "status": "exported",
6
+ "created": "2026-07-01T22:07:23Z",
7
+ "updated": "2026-07-01T22:32:01Z",
8
+ "claims": [
9
+ {
10
+ "id": "c1",
11
+ "kind": "announcement",
12
+ "text": "devague ships a sharper end-to-end method: a guided scope-exploration stage before the announcement frame, per-item instructions on every claim and task, sharper spec and plan exports, and a guided plan-to-fanout leg that carries those instructions to the workforce.",
13
+ "origin": "user",
14
+ "status": "confirmed",
15
+ "honesty_conditions": [
16
+ {
17
+ "id": "h1",
18
+ "text": "an operator can run idea to scope to spec to plan to fanout end-to-end and every handoff carries the per-item instructions without manual re-entry",
19
+ "status": "confirmed"
20
+ }
21
+ ],
22
+ "hard_questions": [
23
+ {
24
+ "id": "q1",
25
+ "text": "does the added scope stage slow the lightweight case \u2014 small ideas that today go announcement to converge in minutes?",
26
+ "resolved": false,
27
+ "blocking": false
28
+ }
29
+ ],
30
+ "links": []
31
+ },
32
+ {
33
+ "id": "c2",
34
+ "kind": "audience",
35
+ "text": "devague operators \u2014 the agent driving /think and /spec-to-plan \u2014 plus the humans who own the three gates, and the per-task workforce subagents who receive the instructions",
36
+ "origin": "llm",
37
+ "status": "confirmed",
38
+ "honesty_conditions": [
39
+ {
40
+ "id": "h7",
41
+ "text": "each named audience actually touches the shipped surface: the operator agent runs the new moves, the gate-owning humans review the sharper artifacts, and workforce subagents receive the instruction payloads",
42
+ "status": "confirmed"
43
+ }
44
+ ],
45
+ "hard_questions": [],
46
+ "links": []
47
+ },
48
+ {
49
+ "id": "c3",
50
+ "kind": "after_state",
51
+ "text": "an idea's scope is explored and mapped before the frame is built; every claim, honesty condition, and plan task can carry its own working instruction; exports read sharp \u2014 every item actionable, no boilerplate; and the plan-to-fanout leg hands the workforce per-task instructions instead of bare summaries",
52
+ "origin": "llm",
53
+ "status": "confirmed",
54
+ "honesty_conditions": [
55
+ {
56
+ "id": "h8",
57
+ "text": "the after-state is observable in one dogfooded run: a real idea goes scope, frame, sharper spec, plan, fanout using only the shipped surface",
58
+ "status": "confirmed"
59
+ }
60
+ ],
61
+ "hard_questions": [],
62
+ "links": []
63
+ },
64
+ {
65
+ "id": "c4",
66
+ "kind": "before_state",
67
+ "text": "today the frame starts cold at the announcement with no scope survey; claims and tasks carry only their summary text; exports leave the reader to re-derive how to act on each item; and plan waves emits task ids whose context assign-to-workforce must reconstruct by hand",
68
+ "origin": "llm",
69
+ "status": "confirmed",
70
+ "honesty_conditions": [
71
+ {
72
+ "id": "h9",
73
+ "text": "the before-state pains are citable gaps in today's code: no scope move exists, neither store has an instruction field, and assign-to-workforce reconstructs task context by hand",
74
+ "status": "confirmed"
75
+ }
76
+ ],
77
+ "hard_questions": [],
78
+ "links": []
79
+ },
80
+ {
81
+ "id": "c5",
82
+ "kind": "why_it_matters",
83
+ "text": "scope grounded up front means convergence measures real coverage instead of vibes, and per-item instructions make every exported artifact executable by a cheaper model without re-deriving the design",
84
+ "origin": "llm",
85
+ "status": "confirmed",
86
+ "honesty_conditions": [
87
+ {
88
+ "id": "h10",
89
+ "text": "coverage reported by the gate maps to scope that was actually explored \u2014 convergence measures explored territory, not just whatever text happened to be captured",
90
+ "status": "confirmed"
91
+ }
92
+ ],
93
+ "hard_questions": [],
94
+ "links": []
95
+ },
96
+ {
97
+ "id": "c6",
98
+ "kind": "boundary",
99
+ "text": "the CLI stays deterministic and non-orchestrating per issue 20: scope exploration is an agent/skill-side stage and fanout guidance lives in the assign-to-workforce skill \u2014 no LLM calls and no orchestration land inside the CLI",
100
+ "origin": "llm",
101
+ "status": "confirmed",
102
+ "honesty_conditions": [
103
+ {
104
+ "id": "h11",
105
+ "text": "the shipped diff contains no LLM calls, no subagent spawning, and no worktree management anywhere inside the devague package",
106
+ "status": "confirmed"
107
+ }
108
+ ],
109
+ "hard_questions": [],
110
+ "links": []
111
+ },
112
+ {
113
+ "id": "c7",
114
+ "kind": "non_goal",
115
+ "text": "not a wizard: scope exploration does not become a mandatory fixed first stage; the move-driven adaptive arc stays intact and small ideas can still skip straight to the announcement",
116
+ "origin": "llm",
117
+ "status": "confirmed",
118
+ "honesty_conditions": [],
119
+ "hard_questions": [],
120
+ "links": []
121
+ },
122
+ {
123
+ "id": "c8",
124
+ "kind": "success_signal",
125
+ "text": "a spec produced with the new process shows scope-exploration provenance on its boundary and non-goal claims; every exported plan task renders an instruction block; and an assign-to-workforce run consumes those instructions as the subagent brief without the operator re-typing context",
126
+ "origin": "llm",
127
+ "status": "confirmed",
128
+ "honesty_conditions": [
129
+ {
130
+ "id": "h12",
131
+ "text": "every success signal is checkable on artifacts alone: the exported spec shows scope provenance, the exported plan renders instruction blocks, and a fanout brief quotes them verbatim",
132
+ "status": "confirmed"
133
+ }
134
+ ],
135
+ "hard_questions": [],
136
+ "links": []
137
+ },
138
+ {
139
+ "id": "c9",
140
+ "kind": "requirement",
141
+ "text": "a scope-exploration stage precedes the frame: before or right after 'new', the operator surveys the repo/context the idea touches and the findings seed boundary, non-goal, and assumption claims that cite what was explored",
142
+ "origin": "llm",
143
+ "status": "confirmed",
144
+ "honesty_conditions": [
145
+ {
146
+ "id": "h2",
147
+ "text": "a frame built with scope exploration contains boundary and non-goal claims that cite the surfaces actually explored \u2014 provenance, not generic disclaimers",
148
+ "status": "confirmed"
149
+ }
150
+ ],
151
+ "hard_questions": [],
152
+ "links": []
153
+ },
154
+ {
155
+ "id": "c10",
156
+ "kind": "requirement",
157
+ "text": "claims and plan tasks accept an optional per-item instruction \u2014 how to verify or implement that item \u2014 stored in frame/plan state and rendered verbatim in exports; an absent instruction renders nothing",
158
+ "origin": "llm",
159
+ "status": "confirmed",
160
+ "honesty_conditions": [
161
+ {
162
+ "id": "h3",
163
+ "text": "instructions round-trip: capture, store, export renders them verbatim; an item without an instruction renders nothing rather than fabricated filler",
164
+ "status": "confirmed"
165
+ }
166
+ ],
167
+ "hard_questions": [
168
+ {
169
+ "id": "q2",
170
+ "text": "LLM-proposed instructions must stay proposed too \u2014 does the user confirm loop scale when every claim and task can carry one?",
171
+ "resolved": false,
172
+ "blocking": false
173
+ }
174
+ ],
175
+ "links": []
176
+ },
177
+ {
178
+ "id": "c11",
179
+ "kind": "requirement",
180
+ "text": "sharper exports: the rendered spec-md and plan-md make every item directly actionable, with the definition of sharper agreed with the user before build",
181
+ "origin": "llm",
182
+ "status": "confirmed",
183
+ "honesty_conditions": [
184
+ {
185
+ "id": "h4",
186
+ "text": "sharper has a written definition the user confirmed before any renderer change lands",
187
+ "status": "confirmed"
188
+ },
189
+ {
190
+ "id": "h6",
191
+ "text": "the tightened gate stays deterministic: it checks structural sharpness signals \u2014 instruction present on spec-affecting items, a measurable success signal, claim text meeting explicit structural rules \u2014 never LLM text judgment inside the CLI",
192
+ "status": "confirmed"
193
+ }
194
+ ],
195
+ "hard_questions": [
196
+ {
197
+ "id": "q3",
198
+ "text": "which structural checks can a deterministic CLI actually run to catch woolly text, and what is the false-positive story when they misfire on legitimate prose?",
199
+ "resolved": false,
200
+ "blocking": false
201
+ }
202
+ ],
203
+ "links": []
204
+ },
205
+ {
206
+ "id": "c12",
207
+ "kind": "requirement",
208
+ "text": "the plan-to-fanout leg is guided end-to-end: plan waves output carries each task's instruction and acceptance criteria, and the assign-to-workforce skill consumes that payload as the per-subagent brief",
209
+ "origin": "llm",
210
+ "status": "confirmed",
211
+ "honesty_conditions": [
212
+ {
213
+ "id": "h5",
214
+ "text": "an assign-to-workforce subagent receives its task's instruction and acceptance criteria in its brief with no operator paraphrasing required",
215
+ "status": "confirmed"
216
+ }
217
+ ],
218
+ "hard_questions": [],
219
+ "links": []
220
+ },
221
+ {
222
+ "id": "c13",
223
+ "kind": "assumption",
224
+ "text": "scope exploration is performed by the operating agent reading the repo and context \u2014 it adds no new CLI dependencies and no LLM calls inside devague",
225
+ "origin": "llm",
226
+ "status": "confirmed",
227
+ "honesty_conditions": [],
228
+ "hard_questions": [],
229
+ "links": []
230
+ },
231
+ {
232
+ "id": "c14",
233
+ "kind": "decision",
234
+ "text": "sharper results means both legs: exports render every item actionable with instruction blocks and no boilerplate, and the convergence gate tightens to flag vague untestable claim text",
235
+ "origin": "user",
236
+ "status": "confirmed",
237
+ "honesty_conditions": [],
238
+ "hard_questions": [],
239
+ "links": []
240
+ },
241
+ {
242
+ "id": "c15",
243
+ "kind": "decision",
244
+ "text": "scope exploration lands as a new deterministic CLI move \u2014 devague scope \u2014 that records explored surfaces and findings as first-class state with provenance; the operating agent performs the actual exploration",
245
+ "origin": "user",
246
+ "status": "confirmed",
247
+ "honesty_conditions": [],
248
+ "hard_questions": [],
249
+ "links": []
250
+ },
251
+ {
252
+ "id": "c16",
253
+ "kind": "decision",
254
+ "text": "per-item instructions attach to both frame claims and plan tasks via an optional instruction field, with a schema_version bump in both stores, flowing spec to plan to fanout",
255
+ "origin": "user",
256
+ "status": "confirmed",
257
+ "honesty_conditions": [],
258
+ "hard_questions": [],
259
+ "links": []
260
+ }
261
+ ],
262
+ "open_vagueness": [
263
+ {
264
+ "id": "v1",
265
+ "text": "the exact stored shape of the scope move's record \u2014 fields, provenance format, how findings link to the claims they seed",
266
+ "kind": "unknown_nonblocking",
267
+ "claim_id": "c15"
268
+ },
269
+ {
270
+ "id": "v2",
271
+ "text": "whether the tightened gate's structural checks land as blockers or as warnings first (a deprecation-style soft rollout)",
272
+ "kind": "unknown_nonblocking",
273
+ "claim_id": "c14"
274
+ }
275
+ ]
276
+ }