@selesai/code 0.8.2 → 0.8.4

package/docs/plans/workflow-subagent-consolidation-planb.md

@@ -0,0 +1,374 @@
+# Plan — Plan B: consolidate the workflow extension onto pi-subagents primitives
+
+## Goal
+
+Replace the bundled `workflow` extension's bespoke engine (state machine, `workflow.json`
+run state, marker validators, exclusive-transition gating) with pi-subagents' durable
+primitives — **missions**, **saved chains**, **checkpoints**, and **verified acceptance** —
+while keeping the `/workflow-prototype|quicktype|task|loop` command names and the four
+mode shapes.
+
+Executed by a small coding model with no project knowledge. Everything needed is here.
+
+## Decisions (user-confirmed)
+
+- **Disposition = thin-shell.** Keep the `/workflow-*` command surface; delete the engine
+  (`state-machine.ts`, `run-state.ts`, `validators.ts`, `adapter.ts`, old `modes/*`), the
+  `write_workflow_artifact` / `end_workflow` tools, and the marker validator machinery.
+  The four modes become **saved chain templates** launched through pi-subagents.
+- **Migration = drop.** Active `workflow.json` runs under `.selesai/artifacts/` are no
+  longer resumable. Documented; no read-only shim.
+
+## Design
+
+### The launch seam (verified)
+
+pi-subagents exports `launchSlashSubagent(pi, ctx, params)` from
+`src/extensions/pi-subagents/src/slash/slash-commands.ts` (line 620). It takes a
+`SubagentParamsLike` (including `{ chain, task, async, agentScope }`), drives the full
+slash UX (live result card, snapshots, notifications), and is what `/run-chain`, `/chain`,
+and `/parallel` already funnel through. The thin shell reuses it directly — no executor
+construction, no new machinery.
+
+```ts
+import { launchSlashSubagent } from "../pi-subagents/src/slash/slash-commands.ts";
+
+pi.registerCommand("workflow-task", {
+  description: "Run the task workflow (plan → reuse → handoff → build↔review loop) as a pi-subagents chain.",
+  handler: async (args, ctx) => {
+    const goal = args.trim();
+    launchSlashSubagent(pi, ctx, { chain: taskChain, task: goal, async: true, agentScope: "both" });
+  },
+});
+```
+
+`task` becomes the `{task}` template variable for the chain's first step (per the chain
+schema: `{task}` = the original request).
+
+### Mode → chain mapping (the design content)
+
+Chain steps use the Selesai agent roster (`architect`, `builder`, `commentator`,
+`explorer`, `recapper`, `researcher`). Human gates are `checkpoint` steps (approve /
+reject via `approve-checkpoint` / `reject-checkpoint`). Build verification is a chain
+`acceptance` gate. **Note:** the `gate: "npm test"` shorthand is `workflowScript`-only; in
+a chain step use the `acceptance` field (read
+`src/extensions/pi-subagents/src/runs/shared/acceptance.ts` + the `ChainItem` schema in
+`schemas.ts` for the exact shape; a verified run is `acceptance: { level: "checked",
+evidence: ["commands-run", "changed-files"] }`).
+
+| Mode | Chain steps (agent · gate) |
+| --- | --- |
+| **task** | `architect` (plan, `{task}`) → `checkpoint` "approve plan?" → `explorer` (reuse) → `recapper` (handoff from `{outputs.plan}`/`{previous}`) → `checkpoint` "approve handoff?" → `builder` (implement, acceptance) → `commentator` (read-only review) → `checkpoint` "approve implementation?" |
+| **prototype** | `researcher` (research) → `architect` (plan) → `checkpoint` → `explorer` (reuse) → `recapper` (handoff) → `checkpoint` → `builder` (acceptance) → `commentator` (review) → `checkpoint` → `commentator` (audit of uncommitted diff) |
+| **quicktype** | same as prototype **minus** the `researcher` step |
+| **loop** | `builder` (acceptance) → `commentator` (review) → `checkpoint` "approve implementation?" (direct build↔review for an already-agreed plan; no plan/reuse/handoff artifacts) |
+
+Step tasks reuse the existing mode-prompt language from the current `src/extensions/workflow/modes/*.ts`
+(the executor copies the phase instructions into each chain step's `task`), with two changes:
+- the `WORKFLOW_*_STATUS` marker contract is dropped (no engine enforces it); the
+  `checkpoint` step is the human approval gate instead,
+- the `output: false` / `write_workflow_artifact` instructions are dropped (children own
+  writes; durable artifacts are child output files + mission artifacts).
+
+### What is intentionally dropped (honest tradeoff)
+
+- The **automatic N-round capped loop** (`loopMaxIterations` + engine-written
+  `loop-complete.md`). Replaced by the `builder → commentator → checkpoint` segment: a
+  blocking review rejects the checkpoint and the user re-runs `/workflow-<mode>` (or the
+  parent uses `append-step` / `resume` for another round). If the auto-loop is a hard
+  requirement, `/workflow-loop` can instead be a `workflowScript` (JS round cap + `gate` +
+  mission `state`) — an optional variant, not the default.
+- The **`grill` phase** (interactive clarification). This is now the parent's pre-launch
+  job; it is not a chain step.
+- **Marker-gated artifacts** and **parent-owned `write_workflow_artifact`**. Durable
+  process state now lives in the auto-created **mission** (per-launch `mission` record with
+  `state`, artifacts, decisions, receipts; recover via `mission.list`/`mission.show`);
+  resumability is pi-subagents' retained children (`children.list` + `runs.run({ resume })`).
+
+## Prerequisite — resolve the uncommitted "merge" work
+
+The previous session left an **uncommitted** merge-into-shell change (Tasks 1-6 of
+`docs/plans/workflow-subagent-scripted-merge.md`). Plan B supersedes it: the adapter/modes
+changes are deleted, and the doc/skill edits are reverted/replaced. **Before starting**,
+do one of:
+
+- **Option 1 (recommended):** commit the merge as-is as a checkpoint commit
+  (`git add -A && git commit -m "wip: merge-into-shell (superseded by plan B)"`), then work
+  on a clean tree. Do NOT include `src/extensions/handoff-new.ts` in that commit (it is a
+  separate pre-existing change).
+- **Option 2:** `git restore` the merge's doc/skill changes
+  (`doc-web/.../workflow.mdx`, `.../pi-subagents.mdx`, `doc-web/src/data/capabilities.ts`,
+  both `execution-controls.md` copies) and leave the rest to be overwritten by deletion.
+
+The executor must not commit; it leaves changes for the user.
+
+---
+
+## Task 1 — Delete the engine (pure removal)
+
+### 1. Discovery
+- Confirm no imports reference these modules outside `src/extensions/workflow/` and
+  `src/__tests__/` (verified: none).
+- Confirm `src/__tests__/bootstrap.test.ts` does not import the workflow extension
+  (verified: it does not; it must still pass because the thin shell remains a valid
+  loadable extension package).
+
+### 2. Identification
+- **Delete:** `src/extensions/workflow/{adapter.ts, state-machine.ts, run-state.ts,
+  validators.ts, modes/loop.ts, modes/task.ts, modes/prototype.ts, modes/quicktype.ts}`.
+- **Delete:** `src/__tests__/{adapter.test.ts, state-machine.test.ts,
+  workflow-run-state.test.ts, task-workflow.test.ts, loop-workflow.test.ts,
+  quicktype-workflow.test.ts}`.
+- **Keep:** `src/extensions/workflow/{extension.ts, package.json}` (rewritten in Tasks 2-3).
+- **Why only these:** the engine and its tests are self-contained; nothing else references
+  them.
+
+### 3. Change
+Remove the listed files. Do not touch any other file.
+
+### 4. Verification
+- **Success:** `grep -rn "WorkflowStateMachine\|createWorkflowExtension\|write_workflow_artifact\|end_workflow" src --include=*.ts` returns nothing.
+- **Failure:** n/a.
+- **Regression:** `src/__tests__/bootstrap.test.ts` still passes (the package dir still
+  exists with a valid `package.json` + `extension.ts`).
+
+---
+
+## Task 2 — Define the four mode chains
+
+### 1. Discovery
+Read the current `src/extensions/workflow/modes/*.ts` before deletion (or from git history)
+to harvest the phase prompt language. Read `src/extensions/pi-subagents/src/slash/slash-commands.ts`
+for the `ChainStep`/`SubagentParamsLike` shape and
+`src/extensions/pi-subagents/src/agents/agents.ts` for the `ChainConfig`/`ChainStepConfig`
+types. Read `schemas.ts` `ChainItem` for the `checkpoint`/`message`/`acceptance`/`as`/
+`outputSchema` fields.
+
+### 2. Identification
+- **Create:** `src/extensions/workflow/modes.ts` (single file; four exported step arrays).
+  One file beats a directory — no per-mode files, no loader indirection.
+- **Why here:** the mode definitions are the thin shell's only content; pi-subagents owns
+  execution.
+
+### 3. Change
+Define, in `modes.ts`:
+
+```ts
+import type { ChainStep } from "../pi-subagents/src/shared/settings.ts"; // verify path
+
+export const taskChain: ChainStep[] = [
+  { agent: "architect", as: "plan", task: "Produce an implementation plan for: {task}. Return the complete plan inline." },
+  { checkpoint: "approve-plan", message: "Approve the plan before implementation?" },
+  { agent: "explorer", task: "Explore the codebase for reusable patterns relevant to the plan: {previous}." },
+  { agent: "recapper", as: "handoff", task: "Compile a self-contained handoff from the plan and reuse findings: {previous}." },
+  { checkpoint: "approve-handoff", message: "Approve the handoff before implementation?" },
+  { agent: "builder", task: "Implement the plan from the handoff: {previous}. Run relevant checks.", acceptance: { level: "checked", evidence: ["commands-run", "changed-files"] } },
+  { agent: "commentator", task: "Independently review the uncommitted diff against the handoff acceptance criteria and report evidence." },
+  { checkpoint: "approve-implementation", message: "Approve the implementation and review?" },
+];
+
+export const prototypeChain: ChainStep[] = [ /* researcher → architect → checkpoint → explorer → recapper → checkpoint → builder(acceptance) → commentator → checkpoint → commentator(audit) */ ];
+export const quicktypeChain: ChainStep[] = [ /* prototypeChain minus researcher */ ];
+export const loopChain: ChainStep[] = [ /* builder(acceptance) → commentator → checkpoint */ ];
+```
+
+Use `as: "plan"` / `as: "handoff"` so later steps can reference `{outputs.plan}` and
+`{outputs.handoff}` instead of relying only on `{previous}`. Copy the substantive
+instructions from the current mode prompts (plan/reuse/handoff/loop/audit wording), minus
+the marker and `write_workflow_artifact` instructions. The `checkpoint` `message` is the
+human-visible approval question.
+
+**Code explicitly not to add:** a `workflowScript` variant for the loop, marker parsing,
+any filesystem writes, or a `modes/` directory.
+
+### 4. Verification
+- **Success:** `modes.ts` typechecks; each chain uses only real agent names
+  (`architect`/`builder`/`commentator`/`explorer`/`recapper`/`researcher`); checkpoint steps
+  have a non-empty `checkpoint` + `message`; builder steps carry `acceptance`.
+- **Failure:** n/a.
+- **Regression:** n/a (new file).
+
+---
+
+## Task 3 — Thin-shell extension (rewrite `extension.ts`)
+
+### 1. Discovery
+Read `src/extensions/pi-subagents/src/slash/slash-commands.ts` around line 620
+(`launchSlashSubagent`) and confirm its export. Read the old `src/extensions/workflow/extension.ts`
+(being replaced) for the command-name/description convention.
+
+### 2. Identification
+- **Modify:** `src/extensions/workflow/extension.ts` (keep `package.json` unchanged — it
+  still declares `pi.extensions: ["./extension.ts"]`).
+- **Why here:** this is the single registration point; `launchSlashSubagent` already owns
+  all execution.
+
+### 3. Change
+Rewrite `extension.ts` to register four commands. Each handler:
+
+```ts
+import { launchSlashSubagent } from "../pi-subagents/src/slash/slash-commands.ts";
+import { taskChain, prototypeChain, quicktypeChain, loopChain } from "./modes.ts";
+
+export default function workflowModesExtension(pi: ExtensionAPI): void {
+  const register = (name: string, description: string, chain: ChainStep[]) =>
+    pi.registerCommand(name, {
+      description,
+      handler: async (args, ctx) => {
+        const goal = args.trim();
+        if (!goal) { ctx.ui.notify(`${description}\nUsage: /${name} <goal>`, "info"); return; }
+        launchSlashSubagent(pi, ctx, { chain, task: goal, async: true, agentScope: "both" });
+      },
+    });
+  register("workflow-task", "Run the task workflow (plan → reuse → handoff → build↔review loop) as a pi-subagents chain.", taskChain);
+  register("workflow-prototype", "Run the full prototype workflow (research → plan → reuse → handoff → loop → audit) as a chain.", prototypeChain);
+  register("workflow-quicktype", "Run the quicker prototype workflow without research as a chain.", quicktypeChain);
+  register("workflow-loop", "Run direct build↔review rounds for an already-agreed plan as a chain.", loopChain);
+}
+```
+
+**Code explicitly not to add:** `write_workflow_artifact` / `end_workflow` tools, any state,
+any `pi.on("tool_call"/"tool_result")` hooks, or a `resume` subcommand.
+
+### 4. Verification
+- **Success:** `/workflow-task <goal>` resolves and launches the `taskChain` via
+  `launchSlashSubagent` with `task: goal` and `async: true`.
+- **Failure:** empty goal → a usage notify, no launch.
+- **Regression:** the package still loads as a bundled extension
+  (`src/__tests__/bootstrap.test.ts` green); `/run-chain` and the pi-subagents commands are
+  unaffected.
+
+---
+
+## Task 4 — Tests
+
+### 1. Discovery
+Read `src/__tests__/bootstrap.test.ts` to see how bundled extensions are loaded, and the
+pi-subagents slash test patterns (if any) under `src/extensions/pi-subagents/test/`.
+
+### 2. Identification
+- **Create:** `src/__tests__/workflow-modes.test.ts` (replaces the six deleted files).
+- **Why here:** the deleted tests lived in `src/__tests__/`; keep the thin shell's tests
+  there for consistency. Do not add to pi-subagents' test tree (its own surface is
+  unchanged).
+
+### 3. Change
+Cover, without mocking pi-subagents internals:
+
+- **`modes.ts` shape:** each of the four chains is a non-empty array; `task`/`quicktype`/`loop`
+  chain step agents are a subset of the Selesai roster; `prototype` contains a `researcher`
+  step and `quicktype` does not; builder steps have `acceptance`; every `checkpoint` step has
+  a non-empty `message`.
+- **command registration:** importing `extension.ts` (with a minimal fake `pi` capturing
+  `registerCommand` calls) registers exactly the four `/workflow-*` names. Keep the fake
+  `pi` minimal (only the methods `registerCommand` touches).
+
+**Code explicitly not to add:** end-to-end execution tests (they belong to pi-subagents'
+integration suite), or importing `launchSlashSubagent` in tests (it needs a full pi + state).
+
+### 4. Verification
+- **Success:** `npx vitest run src/__tests__/workflow-modes.test.ts src/__tests__/bootstrap.test.ts` green.
+- **Failure:** n/a.
+- **Regression:** the six deleted test files are gone; full unit suite stays green.
+
+---
+
+## Task 5 — Docs
+
+### 1. Discovery
+Read `doc-web/src/content/docs/capabilities/delegation/workflow.mdx` (current, including the
+prior "Scripted subagent steps" section), `pi-subagents.mdx`, and
+`doc-web/src/data/capabilities.ts`.
+
+### 2. Identification
+- **Modify:** `doc-web/src/content/docs/capabilities/delegation/workflow.mdx`,
+  `.../pi-subagents.mdx`, `doc-web/src/data/capabilities.ts`.
+- **Why here:** these are the registered capability pages; the workflow page must stop
+  describing a deleted engine.
+
+### 3. Change
+- **workflow.mdx:** rewrite to: "the `workflow` extension now ships the four mode shapes as
+  pi-subagents saved chains; `/workflow-*` launches them; phases = chain steps; human gates =
+  checkpoints; verified acceptance = chain `acceptance`; durable state = missions
+  (`mission.list`/`show`); resumability = retained children." Remove all `write_workflow_artifact`
+  / `end_workflow` / `workflow.json` / marker content and the prior "Scripted subagent steps"
+  section. Add a "Migration" note: active `workflow.json` runs are not resumable (Plan B).
+- **pi-subagents.mdx:** update the Limits-and-safety paragraph added by the prior merge to
+  reflect that the workflow modes are now chains (not "drives a script"), and note
+  `/run-chain <mode>` parity is optional.
+- **capabilities.ts:** update the `workflow` `benefit` string to "the four workflow modes as
+  pi-subagents saved chains".
+
+### 4. Verification
+- **Success:** `npx astro check` (doc-web) and `npm run validate:content` pass; the page no
+  longer references `write_workflow_artifact`/`end_workflow`/`workflow.json`.
+- **Failure:** n/a.
+- **Regression:** `pi-subagents.mdx` retains its unrelated content; capabilities.ts categories
+  and `manifestEntry: "./workflow"` are unchanged.
+
+---
+
+## Task 6 — Skill doctrine (3-way sync)
+
+### 1. Discovery
+Read the "Durable-shell integration" note added by the prior merge in
+`src/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md`
+(canonical copy), and confirm the three copies are currently byte-identical.
+
+### 2. Identification
+- **Modify:** all three copies of `references/execution-controls.md`:
+  `src/extensions/pi-subagents/skills/pi-subagents` ↔ `src/skills/pi-subagents` ↔
+  `~/.selesai/agent/skills`.
+
+### 3. Change
+Replace the "Durable-shell integration" note (which describes the now-deleted merge) with a
+short "Workflow modes as saved chains" note: the bundled `workflow` extension ships the four
+mode shapes as chains launched via `/workflow-*`; human gates are checkpoints; verified
+acceptance is chain `acceptance`; durable state is the auto-created mission. Apply the
+identical diff to all three copies.
+
+### 4. Verification
+- **Success:** `diff -q` across the three copies reports identical; the old
+  "Durable-shell integration" text is gone.
+- **Failure:** n/a.
+- **Regression:** all other `execution-controls.md` sections byte-identical.
+
+---
+
+## Task order and dependencies
+
+1. Task 1 (delete engine) — first, unblocks everything.
+2. Task 2 (mode chains) — independent content work.
+3. Task 3 (thin shell) — depends on 2.
+4. Task 4 (tests) — depends on 2-3.
+5. Tasks 5-6 (docs/skill) — after behavior is stable; can run in parallel.
+
+## Definition of done
+
+- `npx vitest run src/__tests__/workflow-modes.test.ts src/__tests__/bootstrap.test.ts` green.
+- Full unit suite green (the six deleted workflow tests are gone; pi-subagents integration
+  suite unaffected: `npm run test:integration` in `src/extensions/pi-subagents` with clean
+  `SELESAI_SUBAGENT_*` env, expecting 737/0).
+- Typecheck clean: `npx tsc --noEmit` (pi-subagents) + `npx tsgo -p tsconfig.build.json --noEmit`.
+- `npx astro check` + `npm run validate:content` (doc-web) clean.
+- `diff -q` clean across the 3-way skill sync.
+- `grep -rn "WorkflowStateMachine\|write_workflow_artifact\|end_workflow\|WORKFLOW_PLAN_STATUS" src` returns nothing.
+- `git status` shows: deletions of the 8 engine files + 6 test files; new `modes.ts`,
+  `workflow-modes.test.ts`; modified `extension.ts`, two `.mdx`, `capabilities.ts`, three
+  `execution-controls.md`; `src/extensions/handoff-new.ts` untouched; nothing committed.
+
+## Final review checklist (planger)
+
+- [x] Discovery: seam (`launchSlashSubagent`), agent roster, chain schema, saved-chain
+      format, test locations, and the uncommitted-merge prerequisite all verified.
+- [x] Ownership: pi-subagents owns execution/missions/checkpoints/gates; the thin shell owns
+      only the four chain definitions + command registration.
+- [x] Simplest acceptable: one exported seam reused, one new `modes.ts`, one rewritten
+      `extension.ts`, one test file; no new abstractions, deps, or state.
+- [x] Reuse: `launchSlashSubagent`, the Selesai agent roster, the existing mode-prompt
+      language, `acceptance`/`checkpoint` chain fields.
+- [x] Scope: deletes only the engine + its tests; keeps command names; drops old runs as
+      decided.
+- [x] Verification: success/failure/regression per task + Definition of done.
+- [x] Executable without assumptions: exact paths, the exported seam, the chain mapping, and
+      the one prerequisite resolution step.