@sabaiway/agent-workflow-engine 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `1.3.0`).
 
+## 1.3.0 — Activity procedures: named, recipe-aware playbooks
+
+The engine now also owns the **activity-procedures** canon — *how to perform* a named workflow
+activity, as ordered steps with **typed recipe slots** that bind to the orchestration recipes (Solo /
+Reviewed / Council / Delegated). Two v1 activities: **`plan-authoring`** (slot: `review`) and
+**`plan-execution`** (slots: `execute`, `review`). The canon composes with `planning.md` (it binds to
+the §7 structure, §8 self-review, and §4 Cleanup without restating them) and stays **generic** — it
+bakes in no single project's stages, deferring any project-declared release/publishing to that
+project's `workflow:methodology` slot. The kit reads this canon **live** and surfaces a read-only
+`/agent-workflow-kit procedures <activity>` that renders the steps + the resolved effective recipe per
+slot (from `docs/ai/orchestration.json` + backend readiness).
+
+### Added
+- **`references/procedures.md`** — the canonical activity-procedures canon: `plan-authoring` +
+  `plan-execution` as `## <activity>` sections, each opening with a machine-parseable `Slots:` line
+  (the only line the kit parses, drift-guarded against its activity table). It carries the
+  load-bearing "Delegated → dispatch execution first" rule and restates the commit contract as a
+  commit-BOUNDARY rule (when an activity has a commit boundary the orchestrator owns that commit; a
+  backend never commits — `plan-authoring` ends at approval with no commit, `plan-execution` commits
+  per Step).
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file). The
+npm package version is a separate axis.
+
+## 1.2.0 — Orchestration recipes: a named vocabulary for composing the bridges
+
+The engine now also owns the **orchestration-recipe** canon — the named patterns an agent uses to
+compose the optional execution-backends (the `codex` / `agy` bridges) into `plan → execute → review`.
+Four recipes, built over the bridges' role vocabulary: **Solo** (no backend — the floor), **Reviewed**
+(one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a
+bounded sub-task). The orchestrator always owns the decisions and the single commit; a backend is
+advisory or delegated, never autonomous. The kit reads this canon **live** and surfaces a read-only
+`/agent-workflow-kit recipes` advisor that plans a recipe for the current environment.
+
+### Added
+- **`references/orchestration.md`** — the canonical narrative: the four recipes over the role
+  vocabulary, the when/why decision guidance, the graceful-degradation lattice (Council → Reviewed →
+  Solo; Delegated → Solo, always with a stated reason), and the quota/health guard.
+- **`references/orchestration-slot.md`** — the bounded **one-line** fragment the composition root
+  injects into a deployed `AGENTS.md` (between the `workflow:orchestration` markers). It names the four
+  recipes and routes to `/agent-workflow-kit recipes` — never to this engine-internal reference.
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file). The
+npm package version is a separate axis.
+
 ## 1.1.0 — Live-read ready: never-downgrade gate + installer hardening
 
 The kit now reads this canon **live from the installed engine** and has retired its bundled mirror

package/README.md

@@ -3,8 +3,9 @@
 **The canonical home of the `agent-workflow` planning methodology.** It owns the
 methodology *text* — the Plan → Phase → Step vocabulary, the plan-file lifecycle
 (`docs/plans/*.md`, ephemeral, never committed), the `queue.md` series index, the mandatory
-final **Phase: Cleanup**, and the bounded methodology slot fragment the family kit injects
-into a deployed project's `AGENTS.md`.
+final **Phase: Cleanup**, the **orchestration-recipe** vocabulary (Solo / Reviewed / Council /
+Delegated), and the two bounded slot fragments the family kit injects into a deployed project's
+`AGENTS.md`.
 
 This is the **methodology engine** of the `agent-workflow` family — the canonical source the
 rest of the family builds on. It is **content**, not a runtime: it reads nothing, writes
@@ -41,14 +42,23 @@ the canonical methodology reference on disk:
   Plan → Phase → Step vocabulary, the plan-file lifecycle, the `queue.md` series index, the
   mandatory final **Phase: Cleanup**, and the plan-then-execute split.
 - [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded**
-  fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
+  methodology fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
   pointer, kept under the entry point's line cap).
+- [`references/orchestration.md`](references/orchestration.md) — the canonical **orchestration-recipe**
+  reference: the four recipes (Solo / Reviewed / Council / Delegated) over the bridges' role
+  vocabulary, the when/why, the graceful-degradation lattice, and the quota/health guard.
+- [`references/orchestration-slot.md`](references/orchestration-slot.md) — the **bounded** one-line
+  orchestration fragment the composition root injects into a deployed `AGENTS.md`, routing to the
+  in-project recipes surface.
+- [`references/procedures.md`](references/procedures.md) — the canonical **activity-procedures** canon:
+  the named activities (`plan-authoring`, `plan-execution`) as ordered steps with typed recipe slots,
+  read live and rendered by the read-only `/agent-workflow-kit procedures <activity>`.
 
 ## What this package ships
 
-`SKILL.md` (the canon overview + ownership rule), `references/` (the full methodology
-reference + the bounded slot fragment), `capability.json` (the family manifest), and this
-installer. It ships **no** family-wide tooling (the schema/validator/injection live in the
+`SKILL.md` (the canon overview + ownership rule), `references/` (the full methodology + the
+orchestration + activity-procedures references + the two bounded slot fragments), `capability.json`
+(the family manifest), and this installer. It ships **no** family-wide tooling (the schema/validator/injection live in the
 composition root) and mutates nothing — preserving "knows nobody".
 
 ## License

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: agent-workflow-engine
-description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, and the bounded methodology slot fragment. 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 slot from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
+description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, 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.
 disable-model-invocation: true
 metadata:
-  version: '1.1.0'
+  version: '1.3.0'
 ---
 
 # agent-workflow-engine
@@ -26,6 +26,19 @@ slot fill is needed but the engine is absent, the kit's reconcile **fails loudly
   composition root injects into a deployed project's `AGENTS.md`, between the
   `<!-- workflow:methodology:start -->` / `<!-- workflow:methodology:end -->` markers. A short
   summary + pointer, not the full reference, so the entry point stays under its line cap.
+- [`references/orchestration.md`](references/orchestration.md) — the canonical **orchestration-recipe**
+  reference: the four recipes (Solo / Reviewed / Council / Delegated) defined over the bridges' role
+  vocabulary, the when/why decision guidance, the graceful-degradation lattice, and the quota/health
+  guard. The kit owns the executable dispatch and surfaces it as `/agent-workflow-kit recipes`.
+- [`references/orchestration-slot.md`](references/orchestration-slot.md) — the **bounded** one-line
+  orchestration fragment the composition root injects into a deployed `AGENTS.md`, between the
+  `<!-- workflow:orchestration:start -->` / `<!-- workflow:orchestration:end -->` markers. It names the
+  four recipes and routes to `/agent-workflow-kit recipes`, never to this engine-internal reference.
+- [`references/procedures.md`](references/procedures.md) — the canonical **activity-procedures** canon:
+  the ordered steps of the named activities (`plan-authoring`, `plan-execution`) with **typed recipe
+  slots** that bind to the orchestration recipes, composing with `planning.md` without restating it. It
+  stays generic (no project-specific stages baked in). The kit reads it live and renders the steps +
+  the resolved effective recipe per slot via the read-only `/agent-workflow-kit procedures <activity>`.
 
 ## Ownership rule (the engine knows nobody)
 

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-engine",
   "kind": "methodology-engine",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "available": true,
   "provides": ["plan"],
   "roles": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step vocabulary, plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/methodology-slot.md

@@ -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`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project's **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5.
+> **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`. Full vocabulary, lifecycle, and the plan-then-execute split 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.

package/references/orchestration-slot.md

@@ -0,0 +1 @@
+> **Orchestration recipes** — compose plan → execute → review with a named recipe: **Solo** (no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a bounded sub-task); the orchestrator always commits, a backend is never autonomous. Pick + plan one for this environment with `/agent-workflow-kit recipes` (read-only); the deployed how/why lives in your `docs/ai/` workflow docs.

package/references/orchestration.md

@@ -0,0 +1,92 @@
+# Orchestration Recipes
+
+Canonical, on-demand reference for **how an orchestrating agent composes the optional
+execution-backends** (the family's subscription-CLI bridges) into the `plan → execute → review`
+flow. This is the *narrative* source of truth — the **vocabulary** (what each recipe is), the
+**when/why** (which to reach for), the **graceful-degradation lattice** (what happens when a backend
+is unavailable), and the **quota/health guard**. The kit (`agent-workflow-kit`) owns the *executable*
+dispatch (`tools/recipes.mjs` — `planRecipe` / `recommendRecipe`) and surfaces it read-only as
+`/agent-workflow-kit recipes`; the two representations are kept in lockstep by a recipe-name parity
+guard. For the plan lifecycle this composes with, see [`planning.md`](planning.md).
+
+---
+
+## 1. The role vocabulary recipes are built over
+
+A recipe is an **orchestration pattern**, not a runnable script. The **orchestrator** (the main
+agent) always owns the decisions, the edits it accepts, verification, and the **single commit** — a
+backend is **advisory or delegated, never autonomous, and never commits**.
+
+Each backend declares what it can do in its `capability.json` `provides` / `roles`:
+
+- **`codex-cli-bridge`** (`codex`) — `provides: ["execute", "review"]`. It can run a bounded
+  execution sub-task (`codex-exec`, output: a diff) and give an advisory review (`codex-review`,
+  modes `plan` / `code`).
+- **`antigravity-cli-bridge`** (`agy`) — `provides: ["review", "probe"]`. It can give an advisory
+  review and answer a bounded probe (both via `agy-run`).
+
+Both are **subscription** backends with a **finite quota** — spend deliberately.
+
+## 2. The four recipes
+
+| Recipe (id) | Pattern | Roles needed | Backends that satisfy it |
+|-------------|---------|--------------|--------------------------|
+| **Solo** (`solo`) | The orchestrator plans, executes, and self-reviews. No backend. | none | — (always available; the floor) |
+| **Reviewed** (`reviewed`) | The orchestrator executes; **one** backend reviews the result (advisory). | ≥1 backend providing `review` | `codex` and/or `agy` |
+| **Council** (`council`) | **Both** backends review independently; the orchestrator synthesizes the two opinions. | ≥2 backends providing `review` | `codex` **and** `agy` |
+| **Delegated** (`delegated`) | The orchestrator hands a **bounded** execution sub-task to a backend, then reviews the returned diff and commits. | ≥1 backend providing `execute` | `codex` only |
+
+## 3. When / why to reach for each (the decision vocabulary)
+
+- **Solo** — the default for small, self-contained, low-risk work where a second opinion would not
+  change the outcome: typos, one-line fixes, mechanical edits, doc tweaks. It is also the **floor**
+  every other recipe degrades to, so the flow never blocks on a backend.
+- **Reviewed** — the everyday choice when work carries real risk (a bug class, a security surface, a
+  non-obvious refactor) and an independent reviewer is worth one backend's quota. When **both**
+  backends can review, prefer **`codex`** (deterministic tie-break — `agy` carries a standing health
+  caveat, §5).
+- **Council** — for high-stakes or genuinely ambiguous decisions where two *diverse* opinions catch
+  what one would miss. It spends **two** backends' quota, so reserve it for changes that justify the
+  cost.
+- **Delegated** — when a bounded, well-specified sub-task can be handed off (parallelism, or to keep
+  the orchestrator's own context focused). Only `codex` provides `execute`. The orchestrator still
+  reviews the returned diff and owns the commit — delegation never bypasses the review or the gate.
+
+## 4. Graceful degradation (never silent)
+
+Availability is **pure file-presence**: a backend is dispatchable **iff its detector `readiness` is
+`ready`** — full stop. Every other readiness (`needs-skill` / `needs-cli` / `needs-credentials` /
+`degraded`) means *not dispatchable*, and the specific value is the human reason (not installed → run
+`/agent-workflow-kit setup`; CLI missing → install the CLI; credentials missing → log in; degraded →
+the wrapper is not on `PATH`). This is a claim about **set-up state only** — never about whether a
+backend's *service* is actually responsive.
+
+When a recipe's roles can't be satisfied, it **degrades to a weaker recipe with a stated reason** —
+always reported, never silently dropped:
+
+- **Council → Reviewed → Solo.** Only one of the two reviewers is `ready` → Reviewed with that one;
+  neither is `ready` → Solo.
+- **Delegated → Solo.** No backend provides `execute` and is `ready` → Solo, with the reason.
+- **Reviewed → Solo.** No backend provides `review` and is `ready` → Solo, with the reason.
+
+## 5. Quota & health guard (advisory)
+
+Backends are **subscription** services with **finite** quota. The orchestrator should: prefer the
+cheapest model that fits the task; not reach for a top-tier model by reflex; and remember that
+**Council spends two backends' quota** for one decision.
+
+A **standing health advisory** applies to `agy`: the Antigravity service can **stall on substantive
+prompts** (a long hang that returns nothing — an external service issue, not a setup problem;
+tracked as **Issue-001** in the kit's known issues). It is **invisible to file-presence detection**,
+so it is *not* a readiness signal — it is a static caveat attached whenever a recipe would use `agy`. While it lasts, **prefer `codex`** for substantive
+reviews (this is the Reviewed tie-break in §3). The recipe machinery **never runs a subscription
+CLI** to check — detection stays read-only.
+
+## 6. The orchestrator always commits
+
+No recipe makes a backend write to the repo or create a commit. The kit's `recipes` surface is
+**read-only** — it lists the recipes, plans one for the current environment, and recommends a
+default; it **never executes** a recipe and **never runs a subscription CLI**. The orchestrator
+executes the chosen recipe through the bridge skills, accepts or rejects every edit, runs the
+verification gate, and makes the **one** commit — exactly as the plan lifecycle (`planning.md`)
+requires.

package/references/procedures.md

@@ -0,0 +1,70 @@
+# Activity Procedures
+
+Canonical, on-demand reference for **how an orchestrating agent performs a named activity** — the
+ordered steps of a workflow activity with **typed recipe slots** that bind to the
+[orchestration recipes](orchestration.md) (Solo / Reviewed / Council / Delegated). This is the
+*how to perform* source of truth; it composes with — and never restates — the plan structure and
+lifecycle in [`planning.md`](planning.md). The composition root (`agent-workflow-kit`) reads this
+canon LIVE and renders the requested activity's steps + the resolved effective recipe per slot via
+the read-only `/agent-workflow-kit procedures <activity>`; it parses ONLY each section's `Slots:`
+line (drift-guarded against its activity table), never the steps.
+
+A **recipe slot** is a point in an activity where a recipe applies: `review` accepts
+`solo | reviewed | council`; `execute` accepts `solo | delegated`. The per-project default lives in
+`docs/ai/orchestration.json` and is resolved against backend readiness by the kit — never decided in
+this canon. Each activity section below begins with a machine-parseable `Slots:` line (the only line
+the kit parses) and then its ordered steps. Terse by design: it points at the canon it binds to, it
+does not restate it.
+
+The commit rule holds across every activity: **when an activity has a commit boundary, the
+orchestrator owns that commit; a backend is advisory or delegated, never autonomous, and never
+commits** (see [`orchestration.md`](orchestration.md) §6). Not every activity commits —
+`plan-authoring` ends at **approval** and produces **no** commit (plans are ephemeral, never
+committed); `plan-execution` commits **per Step**. Any project-declared release/publishing or extra
+stages are honored per the project's `workflow:methodology` slot — this generic canon bakes in no
+single project's stages.
+
+---
+
+## plan-authoring
+
+Slots: review
+
+Produce a self-contained, cold-readable plan, reviewed to the configured depth before approval.
+
+1. **Research** — gather the exact files, contracts, and constraints the plan will touch.
+2. **Draft** — write the plan to the document structure defined in [`planning.md`](planning.md) §7,
+   with exact paths and commands per Step. Bind to that structure; do not restate it here.
+3. **Self-review** — run the [`planning.md`](planning.md) §8 checklist (exact paths/commands, strict
+   vocabulary, every out-of-plan recommendation folded into a Step, `queue.md` updated for a series).
+4. **review {recipe}** — review the draft at the depth the resolved `review` recipe selects: Solo
+   (self-review only), Reviewed (one backend reviews), or Council (both backends review, you
+   synthesize). The kit resolves the effective recipe from `docs/ai/orchestration.json` + readiness.
+5. **Fold + loop** — fold every finding back into the draft and re-review until the review is clean.
+6. **Present for approval** — surface the finished plan to the user; do not begin execution here.
+
+The plan MUST end with the mandatory **Phase: Cleanup** ([`planning.md`](planning.md) §4) — a plan
+without it is not done.
+
+## plan-execution
+
+Slots: execute, review
+
+Execute an approved plan Step by Step; each Step is one logical commit.
+
+1. **Per Step, resolve the recipe** — the kit resolves `execute` and `review` for this run from
+   `docs/ai/orchestration.json` + readiness (a per-run `--override <slot>=<recipe>` is allowed).
+2. **If `execute` resolved to Delegated, dispatch execution FIRST** — hand the bounded sub-task to the
+   backend (codex-exec → a diff) *before* integrating; otherwise the orchestrator implements the Step
+   directly.
+3. **Implement / integrate** — apply the change (your own edits, or the reviewed delegated diff),
+   following the project's reuse + clean-code rules.
+4. **Self-review** — run the [`planning.md`](planning.md) §8 self-review on the change.
+5. **review {recipe}** — review the result at the resolved `review` depth (Solo / Reviewed / Council),
+   exactly as in plan-authoring.
+6. **Gates** — run the project's verification gate (tests + checks) to green before committing.
+7. **Commit boundary** — the orchestrator makes the single commit for the Step; a backend never
+   commits. The project's commit-approval policy (e.g. ask first) lives in the project's own rules.
+
+Honor any project-declared release/publishing or extra stages (per the `workflow:methodology` slot)
+before the plan's Cleanup — this generic canon does not enumerate them.