@sabaiway/agent-workflow-engine 2.1.0 → 3.1.0
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.
- package/CHANGELOG.md +101 -0
- package/README.md +4 -4
- package/SKILL.md +6 -6
- package/capability.json +1 -1
- package/package.json +2 -2
- package/references/agent-rules-lens-priors.md +32 -0
- package/references/agent-rules-lens.md +3 -2
- package/references/methodology-slot.md +1 -1
- package/references/orchestration.md +3 -3
- package/references/planning.md +89 -119
- package/references/procedures.md +82 -123
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,107 @@ All notable changes to the methodology engine. Versions are this **package's** n
|
|
|
4
4
|
they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
|
|
5
5
|
(which tracks the shared `agent-workflow` lineage, head `3.0.0`).
|
|
6
6
|
|
|
7
|
+
## 3.1.0 — a finding NAMES the invariant its fix enforces, and the acceptance criteria become a machine-readable list (AD-110)
|
|
8
|
+
|
|
9
|
+
A review round produces findings, and the canon never said which of them the phase owes. The two
|
|
10
|
+
ways of getting that wrong are silent and opposite: work the plan already requires gets deferred into
|
|
11
|
+
a queue row nobody reads, and work that was never in scope gets folded in until the round count is
|
|
12
|
+
the only thing that converges. `plan-execution` step 5 now carries the **finding-scope rule**.
|
|
13
|
+
|
|
14
|
+
- **`procedures.md` — the rule, in the plan-execution review step.** Every finding NAMES the
|
|
15
|
+
invariant its fix would enforce, BEFORE the edit, in every round, and where that invariant already
|
|
16
|
+
lives decides the arm. Already an acceptance criterion → **fold here**. It would have to be ADDED →
|
|
17
|
+
the **narrow fix** for the found site ships now (red first) and ONLY the generalization is queued,
|
|
18
|
+
as a row carrying five fields: the invariant, the origin `file:line`, the narrow fix, its proof,
|
|
19
|
+
and a residual exposure declared NOT live. No correct narrow fix → **blocking**: the phase does not
|
|
20
|
+
close, and it is never queued.
|
|
21
|
+
- **Two round bars ride along, declared before each round.** A finding counts only if it changes a
|
|
22
|
+
WRITE/REMOVE decision or is a false statement in shipped text; a repeat finding in one subarea
|
|
23
|
+
routes to SUBTRACTION, not a fourth patch.
|
|
24
|
+
- **Plan-execution scope only.** Plan-authoring settles boundaries and has no shipped behaviour to
|
|
25
|
+
call a live defect in, so it carries none of the three — pinned in both directions, so neither a
|
|
26
|
+
silent deletion nor a scope-creeping copy survives with tests green.
|
|
27
|
+
- **`planning.md` — the acceptance criteria ARE the `- ` bullets under `## Verification`, and they
|
|
28
|
+
are the whole list.** Nothing outside a bullet is one, and a claim matches WITHIN ONE bullet,
|
|
29
|
+
because bullets are reordered, split and deleted independently. A criterion needing two bullets is
|
|
30
|
+
two criteria. A Verification written as prose declares NO criteria and every finding against that
|
|
31
|
+
plan is a new invariant — the closed list fails closed.
|
|
32
|
+
- **The agent-rules lens gains the rule as one bullet, and that bullet carries its SCOPE.** The lens
|
|
33
|
+
intro applies every bullet to plan-AUTHORING as well, so an unqualified bullet would have
|
|
34
|
+
contradicted the canon it is rendered from — it opens `Finding scope (plan-execution)` and says
|
|
35
|
+
plan-review carries none of it. The outgoing body is appended to the append-only prior store, so
|
|
36
|
+
every deployed `agent_rules.md` still carrying the previous canonical body converges on first
|
|
37
|
+
touch.
|
|
38
|
+
|
|
39
|
+
Engine-only release: no migration, no structural change to a deployed `docs/ai/`, and the
|
|
40
|
+
deployment-lineage stamp does not move. One thing in a deployment DOES change, stamp-independently —
|
|
41
|
+
the `agent_rules.md` lens region itself, which the kit's `lens-region` reconcile refreshes on its
|
|
42
|
+
next touch for any deployment still carrying a known canonical body; a customized region is preserved
|
|
43
|
+
verbatim and flagged. The checker the rule names ships in **agent-workflow-kit 7.1.0**
|
|
44
|
+
(`fold-scope`).
|
|
45
|
+
|
|
46
|
+
## 3.0.0 — the plan canon becomes a capped index: a module ledger whose rows ARE the steps (AD-104)
|
|
47
|
+
|
|
48
|
+
A plan is an **index plus constraints**, never a transcript. The executor reads the repository; the
|
|
49
|
+
plan says which files to open, what each may become, and how the result is checked. The canon used
|
|
50
|
+
to say what a plan CONTAINS and never what it may COST — the last plan written to the old shape ran
|
|
51
|
+
690 lines, most of it free prose under `## Approach`, a section with a budget of nothing and no
|
|
52
|
+
check on its content.
|
|
53
|
+
|
|
54
|
+
> ### ⚠ BREAKING — a plan written to any 2.x canon is invalid, and a shipped tool now refuses it
|
|
55
|
+
>
|
|
56
|
+
> The skeleton is LITERAL and tooling extracts by exact match: the title line `# Plan: <title>`,
|
|
57
|
+
> then five `## ` headings — `Goal and boundary`, `Module ledger`, `Verification`, `Phase: Cleanup`,
|
|
58
|
+
> `Next steps`. `## Approach` and `## Decisions (locked)` are gone, and the
|
|
59
|
+
> Plan → Phase → Step → Substep vocabulary with them. Kit **6.0.0**'s `grounding --plan` requires the
|
|
60
|
+
> three canon sections and refuses a MISSING one by name — a plan that exited 0 under every 2.x
|
|
61
|
+
> canon now exits 1. That refusal IS the migration signal, and it is why this is a MAJOR: the same
|
|
62
|
+
> class as **2.0.0**, where deleting a vocabulary from the canon was already called BREAKING.
|
|
63
|
+
> A leftover `## Approach` is not itself the trigger: a section the canon does not name is simply
|
|
64
|
+
> never sliced. A settled decision is no longer a section either — it becomes a boundary or non-goal
|
|
65
|
+
> in *Goal and boundary*, or a check in *Verification*.
|
|
66
|
+
>
|
|
67
|
+
> **Migration.** Rewrite the plan to the skeleton above: the old `## Approach` prose becomes a
|
|
68
|
+
> `## Goal and boundary` (observable outcome, preserved behaviour, explicit non-goals) plus a
|
|
69
|
+
> `## Module ledger` (one row per path, ending in the `total: <before> → <after> lines` budget); its
|
|
70
|
+
> Steps become ledger rows. Nothing in a deployed project's `docs/ai/` moves — the deployment-lineage
|
|
71
|
+
> stamp is unchanged and no migration file is needed.
|
|
72
|
+
|
|
73
|
+
- **`planning.md` 152 → 114 lines.** The whole plan file is capped at **100 lines AND 8000 bytes** —
|
|
74
|
+
both, because a line cap alone is paid off with longer lines. Reserves: Goal and boundary 10,
|
|
75
|
+
Module ledger 60, Verification 20, Cleanup plus Next steps 10. A plan that does not fit is not
|
|
76
|
+
under-described: either the TASK splits along independently verifiable boundaries, or it is a sweep.
|
|
77
|
+
- **The ledger rows ARE the steps**, so the Plan → Phase → Step → Substep numbering is DELETED. One
|
|
78
|
+
row per path, at most 200 bytes, six fields: `<check-id> | create|modify|delete | <path> |
|
|
79
|
+
<responsibility> | <max lines | n/a> | <anchor>`. Rows execute top to bottom, each is one logical
|
|
80
|
+
commit, and a row may anchor only on a path above it or on existing code. The only surviving phases
|
|
81
|
+
are session boundaries and Cleanup. A `create` row's responsibility names the **exported surface**
|
|
82
|
+
— the one interface contract a plan owes its executor, because it is not in the checkout to derive.
|
|
83
|
+
- **A wide mechanical change is ONE row** — a glob path, the invariant every site must satisfy, an
|
|
84
|
+
asserted count. Splitting a sweep into per-file rows costs more prose than the sweep and breaks
|
|
85
|
+
the intermediate states.
|
|
86
|
+
- **The budget that decides is the TOTAL.** The ledger ends with `total: <before> → <after> lines`.
|
|
87
|
+
Five files under a 400-line cap can each be legal while the change doubles the codebase. Growth
|
|
88
|
+
takes a stated reason on that line; a refactor that claims to reduce anything and grows is refused
|
|
89
|
+
at plan time.
|
|
90
|
+
- **Review asks what to cut, not what is missing.** *What gets cut* deletes any line for which both
|
|
91
|
+
answers are yes — can a zero-context executor still pick the right files without it, and can
|
|
92
|
+
verification still catch a wrong result without it. A line may be ADDED only by naming the specific
|
|
93
|
+
wrong execution it prevents AND deleting at least as many lower-value lines.
|
|
94
|
+
- **`procedures.md` 137 → 87 lines, 10427 → 5768 bytes** — back under `planning.md` (5977), as its
|
|
95
|
+
own long-standing assertion requires. Every restated planning rule became a pointer, and the
|
|
96
|
+
pointers name planning sections **by heading**: `planning.md` has no numbered sections, so the old
|
|
97
|
+
`§4/§6/§7/§8/§9` references pointed at moved or deleted text. `procedures-canon.test.mjs` now
|
|
98
|
+
checks that every named anchor is a live `## ` heading and that no `planning.md §N` pointer
|
|
99
|
+
survives.
|
|
100
|
+
- `orchestration.md`'s convergence-bar pointer, the agent-rules **lens fragment** (its two per-Step
|
|
101
|
+
clauses are now per-row, the outgoing body appended verbatim to `agent-rules-lens-priors.md` per
|
|
102
|
+
the AD-041 append-only contract), the methodology **slot** blurb, and the SKILL/README/`package.json`
|
|
103
|
+
descriptions all drop the retired vocabulary.
|
|
104
|
+
- Unchanged and still binding: right altitude and fold-by-code (AD-027/AD-029), checked-vs-unchecked
|
|
105
|
+
syntax — *Un-run syntax never ships in prose* (AD-036), heavy review at the diff, and the mandatory
|
|
106
|
+
`## Phase: Cleanup`.
|
|
107
|
+
|
|
7
108
|
## 2.1.0 — the plan names the layout it is about to create (AD-091)
|
|
8
109
|
|
|
9
110
|
The authoring canon now asks for the layout while the plan is still text: every Step that creates a
|
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @sabaiway/agent-workflow-engine
|
|
2
2
|
|
|
3
3
|
**The canonical home of the `agent-workflow` planning methodology.** It owns the
|
|
4
|
-
methodology *text* — the
|
|
4
|
+
methodology *text* — the capped plan shape (goal and boundary, module ledger, verification), the plan-file lifecycle
|
|
5
5
|
(`docs/plans/*.md`, ephemeral, never committed), the `queue.md` series index, the mandatory
|
|
6
6
|
final **Phase: Cleanup**, the **orchestration-recipe** vocabulary (Solo / Reviewed / Council /
|
|
7
7
|
Delegated), the bounded slot fragments the family kit injects into a deployed project's
|
|
@@ -39,9 +39,9 @@ you install and use the **kit** (`@sabaiway/agent-workflow-kit`), which injects
|
|
|
39
39
|
methodology slot into your project's `AGENTS.md`. Install the engine standalone when you want
|
|
40
40
|
the canonical methodology reference on disk:
|
|
41
41
|
|
|
42
|
-
- [`references/planning.md`](references/planning.md) — the **
|
|
43
|
-
|
|
44
|
-
mandatory final **Phase: Cleanup
|
|
42
|
+
- [`references/planning.md`](references/planning.md) — the **plan canon**: the capped plan shape
|
|
43
|
+
(Goal and boundary · Module ledger · Verification), the subtraction rubric, the plan-file
|
|
44
|
+
lifecycle, the `queue.md` series index, and the mandatory final **Phase: Cleanup**.
|
|
45
45
|
- [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded**
|
|
46
46
|
methodology fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
|
|
47
47
|
pointer, kept under the entry point's line cap).
|
package/SKILL.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agent-workflow-engine
|
|
3
|
-
description: Canonical home of the agent-workflow planning methodology — the
|
|
3
|
+
description: Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, mandatory Cleanup phase, the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
metadata:
|
|
6
|
-
version: '
|
|
6
|
+
version: '3.1.0'
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# agent-workflow-engine
|
|
@@ -18,10 +18,10 @@ slot fill is needed but the engine is absent, the kit's reconcile **fails loudly
|
|
|
18
18
|
|
|
19
19
|
## What it provides (`provides: ["plan"]`)
|
|
20
20
|
|
|
21
|
-
- [`references/planning.md`](references/planning.md) — the **
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
21
|
+
- [`references/planning.md`](references/planning.md) — the **plan canon**: the capped plan shape
|
|
22
|
+
(Goal and boundary · Module ledger · Verification — literal headings), the subtraction rubric for
|
|
23
|
+
review, the plan-file lifecycle (`docs/plans/*.md`, gitignored, never committed), the `queue.md`
|
|
24
|
+
series index and the mandatory final **Phase: Cleanup**.
|
|
25
25
|
- [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded** fragment the
|
|
26
26
|
composition root injects into a deployed project's `AGENTS.md`, between the
|
|
27
27
|
`<!-- workflow:methodology:start -->` / `<!-- workflow:methodology:end -->` markers. A short
|
package/capability.json
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sabaiway/agent-workflow-engine",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "Canonical home of the agent-workflow planning methodology — the
|
|
3
|
+
"version": "3.1.0",
|
|
4
|
+
"description": "Canonical home of the agent-workflow planning methodology — the capped plan shape (goal and boundary, module ledger, verification), plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ai-agents",
|
|
7
7
|
"ai-coding",
|
|
@@ -127,3 +127,35 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
|
|
|
127
127
|
- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
|
|
128
128
|
- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
|
|
129
129
|
- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch into ONE invocation — the review-ledger triad rides one batched write, other stage writers combine via one launcher per stage; never one writer call at a time (each write is its own prompt).
|
|
130
|
+
|
|
131
|
+
<!-- prior: 2026-08-21 (planning canon rewrite) — the two per-Step clauses become per-row -->
|
|
132
|
+
### 2.x. Planning, review & process-fidelity invariants
|
|
133
|
+
Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
|
|
134
|
+
- **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
|
|
135
|
+
- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
|
|
136
|
+
- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
|
|
137
|
+
- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
|
|
138
|
+
- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
|
|
139
|
+
- **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
|
|
140
|
+
- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
|
|
141
|
+
- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
|
|
142
|
+
- **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
|
|
143
|
+
- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
|
|
144
|
+
- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
|
|
145
|
+
- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).
|
|
146
|
+
|
|
147
|
+
<!-- prior: 2026-08-22 (the finding-scope rule) — the outgoing body before the fold-channel bullet -->
|
|
148
|
+
### 2.x. Planning, review & process-fidelity invariants
|
|
149
|
+
Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
|
|
150
|
+
- **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
|
|
151
|
+
- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
|
|
152
|
+
- **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
|
|
153
|
+
- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
|
|
154
|
+
- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
|
|
155
|
+
- **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
|
|
156
|
+
- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-row review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
|
|
157
|
+
- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
|
|
158
|
+
- **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
|
|
159
|
+
- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
|
|
160
|
+
- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
|
|
161
|
+
- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
### 2.x. Planning, review & process-fidelity invariants
|
|
2
2
|
Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
|
|
3
3
|
- **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
|
|
4
|
+
- **Finding scope (plan-execution) — name the invariant BEFORE the edit.** During EXECUTION only — a plan under authoring has no shipped behaviour to call a live defect in, so plan-review carries none of this. Every finding names the invariant its fix would enforce, and where that invariant already lives decides the disposition: already an acceptance criterion of the phase → **fold here**; it would have to be ADDED → ship the **narrow fix** for the found site (red first, then green) and queue ONLY the generalization — a deferral row carries the invariant, the origin `file:line`, the narrow fix, its proof and a residual exposure declared NOT live; no correct narrow fix → **blocking**: the phase does not close, and it is **never queued**. Two bars declared before each round: a finding counts only if it changes a **WRITE/REMOVE decision** or is a false statement in shipped text; a repeat finding in one subarea **routes to SUBTRACTION**, not a fourth patch.
|
|
4
5
|
- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
|
|
5
|
-
- **No code-mechanics in the plan.** A
|
|
6
|
+
- **No code-mechanics in the plan.** A ledger row carries its path and anchor, and Verification carries the exact commands (the plan-shape canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
|
|
6
7
|
- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
|
|
7
8
|
- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
|
|
8
9
|
- **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
|
|
9
|
-
- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-
|
|
10
|
+
- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-row review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
|
|
10
11
|
- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
|
|
11
12
|
- **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
|
|
12
13
|
- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`.
|
|
1
|
+
> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project's **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).
|
|
@@ -75,9 +75,9 @@ reviewers are `ready`, EVERY review round runs BOTH — skipping a ready backend
|
|
|
75
75
|
or "the other one already shipped" is a **SILENT downgrade of Council → Reviewed, and is forbidden**.
|
|
76
76
|
The distinction is strict: an *unavailable* backend is a LOUD, stated degrade (the lattice above); a
|
|
77
77
|
*ready* backend you quietly drop is a fidelity breach, not a degrade. The same holds for any recipe
|
|
78
|
-
that names ≥2 backends. Folding a finding and re-reviewing (the convergence bar, [`
|
|
79
|
-
|
|
80
|
-
clean from all of them.
|
|
78
|
+
that names ≥2 backends. Folding a finding and re-reviewing (the convergence bar, [`procedures.md`](procedures.md)
|
|
79
|
+
*Fold + loop*) re-runs **every named backend each round** — convergence is reached only when one round
|
|
80
|
+
comes back clean from all of them.
|
|
81
81
|
|
|
82
82
|
**Backend divergence is the crossover stop — it bounds the ROUNDS, never the backends.** Running every
|
|
83
83
|
named backend every round CONVERGES when one round returns **0 blockers + 0 majors** from all of them.
|
package/references/planning.md
CHANGED
|
@@ -1,152 +1,122 @@
|
|
|
1
1
|
# Planning Workflow
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
How plans are written, executed and torn down. Overrides the generic `writing-plans` skill — if both
|
|
4
|
+
trigger, this one wins.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
A plan is an **index plus constraints**, never a transcript. The executor reads the repository; the
|
|
7
|
+
plan tells it which files to open, what each one may become, and how the result is checked.
|
|
6
8
|
|
|
7
|
-
##
|
|
9
|
+
## Shape
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
The whole file is capped at **100 lines and 8000 bytes** — both, because a line cap alone is paid off
|
|
12
|
+
with longer lines. The headings are LITERAL, copied bare: tooling extracts sections by exact match.
|
|
10
13
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
## 2. Plan directory & lifecycle
|
|
19
|
-
|
|
20
|
-
Plan files are **ephemeral, machine-local scratch space**, gitignored (`.gitignore` contains `docs/plans/`).
|
|
21
|
-
|
|
22
|
-
**Lifecycle:** Creation (untracked file) → Execution (Phases 1..N-1) → mandatory **Phase N: Cleanup** (§4) → Post-deletion (only `changelog.md` + ADRs remain). Plans are **NEVER committed** — full stop. Even if a plan looks load-bearing (referenced by an ADR), inline the load-bearing content into a persistent doc and delete the plan file.
|
|
23
|
-
|
|
24
|
-
**Forbidden:** `git add` of any plan file; plan-file paths in committed docs; leaving plan files on disk after Cleanup. If the user says "commit the plan" — ask back: "the plan is ephemeral — what exactly should I inline into `decisions.md` / `changelog.md`?".
|
|
25
|
-
|
|
26
|
-
## 3. Series & queue.md
|
|
27
|
-
|
|
28
|
-
A **series** = 2+ related plans that share a roadmap. The index lives at `docs/plans/queue.md` (gitignored, machine-local):
|
|
29
|
-
|
|
30
|
-
```markdown
|
|
31
|
-
## Series: <name>
|
|
32
|
-
|
|
33
|
-
### Current
|
|
34
|
-
- **Plan N / M** — <slug> — <one-line description>
|
|
35
|
-
|
|
36
|
-
### Pending
|
|
37
|
-
- **Plan N+1 / M** — <slug or TBD> — <description>
|
|
38
|
-
|
|
39
|
-
### Done
|
|
40
|
-
- **Plan K / M** — <slug> — done YYYY-MM-DD. Outputs: <pointers>.
|
|
14
|
+
```
|
|
15
|
+
# Plan: <title>
|
|
16
|
+
## Goal and boundary
|
|
17
|
+
## Module ledger
|
|
18
|
+
## Verification
|
|
19
|
+
## Phase: Cleanup
|
|
20
|
+
## Next steps
|
|
41
21
|
```
|
|
42
22
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
## 4. Required Cleanup phase
|
|
46
|
-
|
|
47
|
-
Every Plan MUST end with a final **Phase N: Cleanup** — the last numbered Phase. Without it the Plan is not done.
|
|
48
|
-
|
|
49
|
-
Minimum content:
|
|
50
|
-
|
|
51
|
-
- **Migrate outputs** → `docs/ai/decisions.md` (AD-XXX), `changelog.md`, `known_issues.md` (Issue-XXX), `current_state.md`, `pages/<page>.md`.
|
|
52
|
-
- **Inline cross-references** — `grep -rn "<plan-slug>" docs/` must be empty. Every pointer is rewritten inline or removed.
|
|
53
|
-
- **Update `queue.md`** — if part of a series, mark Done + promote next.
|
|
54
|
-
- **Delete the plan file** — `rm docs/plans/<slug>.md`.
|
|
55
|
-
- **Verification** — `grep -rn "<slug>" .` empty; `ls docs/plans/<slug>.md` → No such file; docs cap-validator green.
|
|
56
|
-
|
|
57
|
-
If a Plan is aborted mid-flight, Cleanup still runs — partial outputs land in `known_issues.md`, then the file is deleted.
|
|
58
|
-
|
|
59
|
-
## 5. All work in plans
|
|
60
|
-
|
|
61
|
-
Anything required for the task is a **Step inside the Plan**. Nothing "before the plan", "between plans", or "don't forget" — those evaporate at execution time because the execution agent reads only the plan file, not chat scrollback. Every dependency, check, and install is its own Step or Substep. The final "Next steps" section contains **only user-actionable** items.
|
|
62
|
-
|
|
63
|
-
## 6. Plan-then-execute split
|
|
64
|
-
|
|
65
|
-
Default workflow for non-trivial features (multi-file change, new service + hook + UI, architectural choices): write a **self-contained Plan** and stop. Implementation runs in a fresh session via the `executing-plans` skill.
|
|
23
|
+
A plan that does not fit is not under-described. Either the TASK is too big — split it along
|
|
24
|
+
independently verifiable boundaries, never by document size — or it is a SWEEP (below).
|
|
66
25
|
|
|
67
|
-
-
|
|
68
|
-
-
|
|
69
|
-
-
|
|
26
|
+
- **Goal and boundary** (10 lines) — the observable outcome, what behaviour is preserved, explicit
|
|
27
|
+
non-goals.
|
|
28
|
+
- **Module ledger** (60 lines) — the single list of paths, and the plan's execution order.
|
|
29
|
+
- **Verification** (20 lines) — the acceptance check, plus one command that validates the whole ledger.
|
|
30
|
+
- **Phase: Cleanup** and **Next steps** (human-actionable only) share the 10 reserved lines.
|
|
70
31
|
|
|
71
|
-
|
|
32
|
+
## Module ledger
|
|
72
33
|
|
|
73
|
-
|
|
34
|
+
One row per path, ≤200 bytes per row, six fields:
|
|
74
35
|
|
|
75
|
-
|
|
36
|
+
```
|
|
37
|
+
<check-id> | create|modify|delete | <path> | <responsibility, one sentence> | <max lines | n/a> | <anchor>
|
|
38
|
+
```
|
|
76
39
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
40
|
+
**The rows ARE the steps.** They execute top to bottom, each row is one logical commit, and a row may
|
|
41
|
+
only anchor on a path above it or on existing code. There is no separate step/phase numbering — the
|
|
42
|
+
only phases are session boundaries in a multi-session plan, and Cleanup.
|
|
80
43
|
|
|
81
|
-
|
|
44
|
+
A `create` row's responsibility names the **exported surface** the module must provide — the names
|
|
45
|
+
other rows import. That surface does not exist in the checkout yet, so it cannot be derived from it;
|
|
46
|
+
this is the one interface contract a plan owes its executor.
|
|
82
47
|
|
|
83
|
-
|
|
48
|
+
Budgets come from the project's declared source-size cap. No declared cap → `n/a`, never an invented
|
|
49
|
+
number. On `modify` the budget is the file's TOTAL size after the change, not a delta. A `delete` row
|
|
50
|
+
carries `—` for budget and anchor.
|
|
84
51
|
|
|
85
|
-
|
|
52
|
+
**Total, not per-file.** The ledger ends with one line:
|
|
53
|
+
`total: <before> → <after> lines`. Five files under a 400 cap can each be legal while the change
|
|
54
|
+
doubles the codebase — the per-file budget cannot see that. Growth is allowed only with a stated
|
|
55
|
+
reason on that line; a refactor that claims to reduce anything and grows is refused here, at plan
|
|
56
|
+
time.
|
|
86
57
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
## Approach ← chosen design + an explicit "What we are NOT doing"
|
|
92
|
-
## Decisions (locked) ← optional: settled, binding decisions the executor must not re-litigate
|
|
93
|
-
## Phase 1: <name>
|
|
94
|
-
### 1.1. <step> ← exact paths + commands
|
|
95
|
-
## Phase 2: <name>
|
|
96
|
-
...
|
|
97
|
-
## Phase N: Cleanup ← mandatory (§4)
|
|
98
|
-
## Critical files ← table: file → change kind (new / modify / delete / move)
|
|
99
|
-
## Reuse ← pointers to existing patterns/snippets to copy, not re-derive
|
|
100
|
-
## Verification ← full check sequence (mechanical + behavioural)
|
|
101
|
-
## Next steps ← user-actionable only (§5)
|
|
102
|
-
```
|
|
58
|
+
**A SWEEP is one row.** A wide mechanical change — one edit repeated across N files — is a single row
|
|
59
|
+
whose path is a glob, whose responsibility states the invariant every site must satisfy, and whose
|
|
60
|
+
count is asserted. Splitting a sweep into per-file rows or into several plans costs more prose than
|
|
61
|
+
the sweep, and breaks the intermediate states.
|
|
103
62
|
|
|
104
|
-
##
|
|
63
|
+
## Verification
|
|
105
64
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
- If part of a series: `queue.md` is initialised / updated (§3).
|
|
111
|
-
- No `git add <plan>` and no "commit the plan" wording in the final report.
|
|
112
|
-
- Every code-touching decision cites the `file:line` it is grounded in; the plan stays at intent / invariant / acceptance altitude, leaving fine code-mechanics to Execute (§9).
|
|
113
|
-
- Decisions the review loop SETTLED (fixtures, contracts, boundary clauses) live under the optional `## Decisions (locked)` heading (§7) — binding for the executor, never re-litigated at Execute.
|
|
65
|
+
Exact existing commands plus the acceptance check for the goal. The ledger is validated by ONE
|
|
66
|
+
command over its `check-id`s — existence and budget for create/modify, absence for delete, the count
|
|
67
|
+
for a sweep, and the total line. Per-row assertions in prose are the repetition this section exists
|
|
68
|
+
to avoid.
|
|
114
69
|
|
|
115
|
-
|
|
70
|
+
**The acceptance criteria ARE the `- ` bullets.** Every top-level `- ` bullet in this section is one
|
|
71
|
+
acceptance criterion, and they are the whole list — nothing outside a bullet is one. That makes the
|
|
72
|
+
list machine-readable, so a review can be told mechanically whether a claimed invariant is already
|
|
73
|
+
required. A claim matches WITHIN ONE bullet: a literal spanning two is not in scope, because bullets
|
|
74
|
+
are reordered, split and deleted independently. A criterion that needs two bullets is two criteria —
|
|
75
|
+
write each one self-contained. A Verification written as prose with no bullets therefore declares NO
|
|
76
|
+
criteria, and every finding against that plan is a new invariant: the closed list fails closed.
|
|
116
77
|
|
|
117
|
-
|
|
78
|
+
## What gets cut
|
|
118
79
|
|
|
119
|
-
|
|
80
|
+
Delete any line for which both answers are yes: *can a zero-context executor still pick the right
|
|
81
|
+
files without it?* and *can verification still catch a wrong result without it?* Specifically, cut:
|
|
120
82
|
|
|
121
|
-
|
|
83
|
+
- prose that restates code reachable from a named anchor — keep the anchor, drop the retelling
|
|
84
|
+
- anything already binding from `AGENTS.md`, package scripts or repo convention
|
|
85
|
+
- rejected alternatives, discussion history, past incidents that do not change the file map
|
|
86
|
+
- edge cases, failure paths, rollback narratives that change neither a boundary nor a check
|
|
87
|
+
- implementation walkthroughs and pseudocode — except a `create` row's exported surface, above
|
|
88
|
+
- any requirement stated twice, and any dependency or install that is not its own ledger row
|
|
122
89
|
|
|
123
|
-
**
|
|
90
|
+
**A decision settled during review is not a section.** It becomes a boundary or non-goal in Goal, or a
|
|
91
|
+
check in Verification. A settlement expressible as neither is code-level detail for Execute.
|
|
124
92
|
|
|
125
|
-
**
|
|
93
|
+
**Review asks what to cut, not what is missing.** A line may be ADDED only by naming the specific
|
|
94
|
+
wrong execution it prevents AND deleting at least as many lower-value lines. A review comment asking
|
|
95
|
+
for "more completeness" is refused by this rule.
|
|
126
96
|
|
|
127
|
-
|
|
97
|
+
## Un-run syntax never ships in prose
|
|
128
98
|
|
|
129
|
-
|
|
99
|
+
A plan carries exact commands its own Verification RUNS against a stated expected outcome, plus
|
|
100
|
+
literal fixtures a named test validates. Control flow, regexes, grammars, algorithm bodies — anything
|
|
101
|
+
that transforms data or evaluates a condition — never live in plan prose: prose has no checker. A
|
|
102
|
+
finding that wants one is the trigger to write a red→green test at Execute instead.
|
|
130
103
|
|
|
131
|
-
|
|
104
|
+
## Cleanup, and the plan's own life
|
|
132
105
|
|
|
133
|
-
|
|
106
|
+
Plan files are **ephemeral, gitignored, never committed**. If something in a plan is load-bearing,
|
|
107
|
+
inline it into a durable doc — `decisions.md`, `changelog.md` — and delete the plan. `git add` of a
|
|
108
|
+
plan file, and plan paths inside committed docs, are forbidden.
|
|
134
109
|
|
|
135
|
-
**
|
|
110
|
+
**Every plan ends with `## Phase: Cleanup`.** It migrates outputs to the durable docs, updates
|
|
111
|
+
`docs/plans/queue.md` for a series, deletes the plan file, and verifies `grep -rn "<slug>" .` is empty
|
|
112
|
+
and the docs cap-validator is green. An aborted plan still runs Cleanup — partial outputs land in
|
|
113
|
+
`known_issues.md`.
|
|
136
114
|
|
|
137
|
-
|
|
115
|
+
## The plan must read cold
|
|
138
116
|
|
|
139
|
-
|
|
117
|
+
The executing session sees the plan file and the repository, never the authoring conversation.
|
|
140
118
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
edits, tests, gates, review dispatches — to the next checkpoint without per-command prompts (the
|
|
146
|
-
OS sandbox confines the blast radius); under `prompt` it asks along the way. **Read the policy at
|
|
147
|
-
session start** (`docs/ai/autonomy.json`; absent → the computed defaults ARE the policy; malformed
|
|
148
|
-
→ STOP loudly) alongside the standing recipe preference, and state the effective level in the
|
|
149
|
-
session's opening summary so the human knows which texture to expect. A plan itself never needs to
|
|
150
|
-
restate the policy — it is per-project configuration, not plan content; a plan names an autonomy
|
|
151
|
-
requirement only when a Step genuinely departs from the declared level (e.g. a consent-gated
|
|
152
|
-
privileged install), and that departure is always an explicit ask, never a silent widening.
|
|
119
|
+
Heavy review belongs at the diff, not the plan: plan review settles boundaries, budgets and the
|
|
120
|
+
total; the per-row review runs against real code where a gate fails immediately. An all-mechanics
|
|
121
|
+
artifact — a sweep, CI wiring, prose-only edits — takes a thin plan plus a diff review rather than
|
|
122
|
+
another prose round.
|
package/references/procedures.md
CHANGED
|
@@ -1,44 +1,29 @@
|
|
|
1
1
|
# Activity Procedures
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
`
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
**Read your preference at session start.** At the start of a planning or execution session, read the
|
|
28
|
-
project's standing recipe preference in `docs/ai/orchestration.json` (set it in plain language with
|
|
29
|
-
`/agent-workflow-kit set-recipe` — it previews then writes; hand-editing the file stays supported); the
|
|
30
|
-
kit resolves it against backend readiness. Do not re-ask each session what is already configured there.
|
|
31
|
-
Read the **autonomy policy** the same way and at the same moment: `docs/ai/autonomy.json` declares the
|
|
32
|
-
red-lines and the per-activity autonomy level (absent → the computed defaults ARE the policy; malformed
|
|
33
|
-
→ STOP loudly, never guess; set it with `/agent-workflow-kit set-autonomy`) — the per-activity
|
|
34
|
-
procedures below run UNDER that policy (`orchestration.md` §7), and the kit's `procedures` advisor
|
|
35
|
-
prints the resolved level beside each activity's recipes.
|
|
36
|
-
|
|
37
|
-
**Communication contract.** Every user-facing message delivers the artifact **inline** — the plan, the
|
|
38
|
-
next-session prompt, the diff, the value asked for — never a bare pointer ("see §X / open the file") as a
|
|
39
|
-
*substitute* for showing it; lead with the result, show exactly what was asked, and never read as
|
|
40
|
-
mockery. For a genuinely large artifact, deliver a real summary or the key excerpt inline **and** link
|
|
41
|
-
the file — never flood, never hide.
|
|
3
|
+
The ordered steps of each named activity, with **typed recipe slots** bound to the
|
|
4
|
+
[orchestration recipes](orchestration.md). It composes with — never restates —
|
|
5
|
+
[`planning.md`](planning.md), naming that canon's sections by *heading*. The kit reads this file
|
|
6
|
+
LIVE and parses ONLY each section's `Slots:` line, never the steps.
|
|
7
|
+
|
|
8
|
+
A **recipe slot**: `review` accepts `solo | reviewed | council`; `execute` accepts
|
|
9
|
+
`solo | delegated`. The per-project default lives in `docs/ai/orchestration.json`, resolved against
|
|
10
|
+
backend readiness by the kit.
|
|
11
|
+
|
|
12
|
+
**When an activity has a commit boundary, the orchestrator owns that commit; a backend is advisory
|
|
13
|
+
or delegated, never autonomous, and never commits** (`orchestration.md` §6). `plan-authoring` ends
|
|
14
|
+
at **approval** with no commit (plans are ephemeral, never committed); `plan-execution` commits per
|
|
15
|
+
ledger row.
|
|
16
|
+
|
|
17
|
+
**Read your preference at session start.** At the start of a planning or execution session, read
|
|
18
|
+
`docs/ai/orchestration.json` (`/agent-workflow-kit set-recipe` writes it; hand-editing stays
|
|
19
|
+
supported) and never re-ask it. Read the **autonomy policy** the same way and at the same moment:
|
|
20
|
+
`docs/ai/autonomy.json` (absent → the computed defaults ARE the policy; malformed → STOP loudly,
|
|
21
|
+
never guess; `/agent-workflow-kit set-autonomy` writes it) — every procedure below runs UNDER it
|
|
22
|
+
(`orchestration.md` §7).
|
|
23
|
+
|
|
24
|
+
**Communication contract.** Every user-facing message delivers the artifact **inline** — never a
|
|
25
|
+
bare pointer ("see §X") as a substitute; lead with the result; a large artifact gets a real summary
|
|
26
|
+
inline plus the link.
|
|
42
27
|
|
|
43
28
|
---
|
|
44
29
|
|
|
@@ -46,92 +31,66 @@ the file — never flood, never hide.
|
|
|
46
31
|
|
|
47
32
|
Slots: review
|
|
48
33
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
**
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
(control-flow, a regex, a glob, a mini-DSL) never enters plan prose — a fold needing one is the
|
|
75
|
-
trigger to name the test instead. Council runs every named backend
|
|
76
|
-
**every round** (recipe fidelity,
|
|
77
|
-
[`orchestration.md`](orchestration.md) §4) — never quietly drop a ready backend. Cap architecture
|
|
78
|
-
plan-review at **≤2 rounds**, stopping at the **crossover** where **backend divergence** (one backend
|
|
79
|
-
grounded-ships while another keeps revising mechanics) IS the stop — the bar is still met by RESOLVING
|
|
80
|
-
the surviving major at altitude (raise it to an acceptance invariant, or hand it to Execute), never by
|
|
81
|
-
exhausting the strictest backend. Run a **self-consistency** read before every re-review and route an
|
|
82
|
-
all-mechanics/CI or prose-only artifact to a **thin plan + diff-review** ([`planning.md`](planning.md)
|
|
83
|
-
§9). Each round MUST emit **{round N · finding-origin tally (first-draft / fold-induced / mechanics) ·
|
|
84
|
-
per-backend verdict}** so the crossover is a computed signal, not a remembered rule. At the cap,
|
|
85
|
-
classify every surviving blocking finding — **fixable-bug** (fold ONCE as a red→green test, re-review)
|
|
86
|
-
/ **inherent-layer-residual** (document + raise to an acceptance criterion) / **escalate** (the
|
|
87
|
-
maintainer decides); a minor never forces triage.
|
|
88
|
-
6. **Present for approval** — surface the finished plan to the user; do not begin execution here. A
|
|
89
|
-
harness "approved — start coding" prompt (**ExitPlanMode**) authorizes the PLAN only
|
|
90
|
-
([`planning.md`](planning.md) §6); continuing into `plan-execution` is a deliberate transition taken
|
|
91
|
-
after the plan + its cold-start prompt exist, never an implicit slide.
|
|
92
|
-
|
|
93
|
-
**Required output (Definition of Done):** a planning session produces a self-contained plan in
|
|
94
|
-
`docs/plans/` **and** a cold-start execution prompt to begin the next session — **both produced without
|
|
95
|
-
the user asking**. A planning session that ends without both is not done.
|
|
96
|
-
|
|
97
|
-
The plan MUST end with the mandatory **Phase: Cleanup** ([`planning.md`](planning.md) §4) — a plan
|
|
98
|
-
without it is not done.
|
|
34
|
+
1. **Research** — the exact files, contracts and constraints touched.
|
|
35
|
+
2. **Draft** — write to the shape [`planning.md`](planning.md) fixes; its *Module ledger* decides
|
|
36
|
+
the layout and every budget before any file exists — a size gate is only the backstop.
|
|
37
|
+
3. **Self-review** — apply *What gets cut*; fold by code (read and cite the `file:line`); update
|
|
38
|
+
`queue.md` for a series.
|
|
39
|
+
4. **review {recipe}** — Solo (self-review only) / Reviewed (one backend) / Council (both; you
|
|
40
|
+
synthesize), as the resolved `review` recipe selects.
|
|
41
|
+
5. **Fold + loop** — fold every finding and re-review; CLEAN is **0 blockers + 0 majors** from every
|
|
42
|
+
backend the recipe names — folding ≠ convergence. Fold a code-touching finding **test-as-spec**,
|
|
43
|
+
with **no code-mechanics** in the plan: only **checked syntax** its Verification runs; un-run,
|
|
44
|
+
**logic-bearing** syntax never enters prose (*Un-run syntax never ships in prose*). Council runs
|
|
45
|
+
every named backend **every round** (recipe fidelity, `orchestration.md` §4). Cap architecture
|
|
46
|
+
review at **≤2 rounds**; **backend divergence** (one ships, one keeps revising mechanics) IS the
|
|
47
|
+
**crossover** — resolve the surviving major at altitude, never by exhausting the strictest
|
|
48
|
+
backend; a **self-consistency** read precedes each re-review; an all-mechanics or prose-only
|
|
49
|
+
artifact takes a thin plan + **diff-review** (*The plan must read cold*). Each round MUST emit
|
|
50
|
+
**{round N · finding-origin tally · per-backend verdict}**. At the cap, classify each surviving
|
|
51
|
+
blocker or major: **fixable-bug** (fold ONCE as a red→green test, re-review) /
|
|
52
|
+
**inherent-layer-residual** (raise to an acceptance criterion) / **escalate**.
|
|
53
|
+
6. **Present for approval** — never execute here: a harness "approved — start coding" prompt
|
|
54
|
+
(**ExitPlanMode**) authorizes the PLAN only; `plan-execution` is a deliberate transition once
|
|
55
|
+
the plan and its cold-start prompt exist.
|
|
56
|
+
|
|
57
|
+
**Definition of Done:** a plan in `docs/plans/` ending with **Phase: Cleanup** **and** a cold-start
|
|
58
|
+
execution prompt to begin the next session — both produced without the user asking.
|
|
99
59
|
|
|
100
60
|
## plan-execution
|
|
101
61
|
|
|
102
62
|
Slots: execute, review
|
|
103
63
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
1. **
|
|
107
|
-
|
|
108
|
-
2. **If `execute` resolved to Delegated, dispatch execution FIRST** —
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
**
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
**
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
**
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
before the plan's Cleanup — this generic canon does not enumerate them.
|
|
64
|
+
Each ledger row is one logical commit.
|
|
65
|
+
|
|
66
|
+
1. **Resolve the recipe per row** — `execute` and `review` from `docs/ai/orchestration.json` +
|
|
67
|
+
readiness (`--override <slot>=<recipe>` per run).
|
|
68
|
+
2. **If `execute` resolved to Delegated, dispatch execution FIRST** — the backend returns a diff
|
|
69
|
+
(codex-exec) *before* you integrate; otherwise implement directly.
|
|
70
|
+
3. **Implement / integrate** — your own edits or the reviewed delegated diff.
|
|
71
|
+
4. **Self-review** — the change against its [`planning.md`](planning.md) ledger row and the plan's
|
|
72
|
+
Verification, under the project's reuse and clean-code rules; fold by code (cite the
|
|
73
|
+
`file:line`); **characterize-first**: pin uncovered code's behaviour in a green test before
|
|
74
|
+
editing it; fold each finding test-as-spec (red→green); atomic, reversible edits.
|
|
75
|
+
5. **review {recipe}** — the **heavy review at the diff** (*The plan must read cold*): real code and
|
|
76
|
+
the full suite. The plan-authoring loop applies unchanged — every named backend every round,
|
|
77
|
+
**0 blockers + 0 majors**, the **{round N · finding-origin tally · per-backend verdict}**
|
|
78
|
+
emission, **fixable-bug / inherent-layer-residual / escalate** at the cap. Its instruments:
|
|
79
|
+
`core-evidence red-proof` declares each bugfix red BEFORE the fix; `core-evidence
|
|
80
|
+
degrade` records an unavailable backend; reviews run on the STAGED tree; `run-gates --final`
|
|
81
|
+
mints the ONE receipt `commit-guard --check` gates the commit against.
|
|
82
|
+
|
|
83
|
+
**Finding scope** — every finding NAMES the invariant its fix enforces, BEFORE the edit, every
|
|
84
|
+
round. Already an acceptance criterion (*Verification*'s `- ` bullets) → **fold here**. It would
|
|
85
|
+
have to be ADDED → the **narrow fix** for the found site ships now (red first) and ONLY the
|
|
86
|
+
generalization is queued, as a row carrying five fields: the invariant, the origin `file:line`,
|
|
87
|
+
the narrow fix, its proof, and a residual exposure declared NOT live. No correct narrow fix →
|
|
88
|
+
**blocking** — the phase does not close, and it is never queued. Two bars, before each round: a
|
|
89
|
+
finding counts only if it changes a WRITE/REMOVE decision or is a false statement in shipped
|
|
90
|
+
text; a repeat finding in one subarea routes to SUBTRACTION, not a fourth patch.
|
|
91
|
+
6. **Gates** — the project's verification gate to green.
|
|
92
|
+
7. **Commit boundary** — the orchestrator makes the single commit; a backend never commits; the
|
|
93
|
+
commit-approval policy lives in the project's own rules.
|
|
94
|
+
8. **After the last row** — the project-declared release or extra stages (the `workflow:methodology`
|
|
95
|
+
slot; this canon bakes in none) and then `## Phase: Cleanup` (*Cleanup, and the plan's own
|
|
96
|
+
life*) run as rows of their own, each through steps 1–7.
|