@getpipher/armory-fleet 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-fleet",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "The armory suite's subagent orchestrator for the pi coding agent — a cross-harness, superpowers-native fleet where every agent is armory-native from birth.",
   "license": "MIT",

package/src/engine/run-registry.ts

@@ -23,11 +23,15 @@ export function genRunId(): string {
   return "fl-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8);
 }
 
+export type RunRegistryChangeListener = () => void;
+
 export class RunRegistry {
   private readonly runs = new Map<string, RunRecord>();
+  private readonly listeners = new Set<RunRegistryChangeListener>();
 
   add(r: RunRecord): void {
     this.runs.set(r.runId, r);
+    this.emit();
   }
   get(id: string): RunRecord | undefined {
     return this.runs.get(id);
@@ -38,6 +42,14 @@ export class RunRegistry {
   }
   update(id: string, patch: Partial<Omit<RunRecord, "runId">>): void {
     const r = this.runs.get(id);
-    if (r) this.runs.set(id, { ...r, ...patch });
+    if (r) { this.runs.set(id, { ...r, ...patch }); this.emit(); }
+  }
+  /** SPEC-5a proper-fix: subscribe to add/update mutations. Returns an unsubscribe fn. */
+  subscribe(fn: RunRegistryChangeListener): () => void {
+    this.listeners.add(fn);
+    return () => { this.listeners.delete(fn); };
+  }
+  private emit(): void {
+    for (const fn of this.listeners) fn();
   }
 }

package/src/engine/spawnSubagent.ts

@@ -72,6 +72,15 @@ export interface SpawnOptions {
   visionPort?: VisionPort;
   signal?: AbortSignal;
   onEvent?: (e: ChildSessionEvent) => void;
+  /** SPEC-4: when set, this spawn is a lifecycle phase child. It links to this lifecycle todo
+   *  (not creates a new one) and finishRun skips mark-done/revert — the lifecycle engine owns
+   *  the lifecycle todo's status + progress block. */
+  lifecycleTodoId?: string;
+  /** SPEC-4: when set (lifecycle phase child), override the agent's `skills` frontmatter with
+   *  the lifecycle's merged phase skill bundle (Q1=B) + route to the phase's resolved backend
+   *  (Q4=C) instead of the agent's `backend`. */
+  skillsOverride?: string[];
+  backendOverride?: "pi" | "claude";
 }
 
 export interface SpawnResult {
@@ -111,18 +120,23 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     }
 
     // SPEC-3: route via the backend registry; fail fast if the backend is missing/unavailable.
-    const backend = opts.backendRegistry.get(agentDef.backend);
+    // SPEC-4: a lifecycle phase child may override the backend (Q4=C) + the skill bundle (Q1=B).
+    const backendId = opts.backendOverride ?? agentDef.backend;
+    const backend = opts.backendRegistry.get(backendId);
     if (!backend || !backend.available()) {
       const note = backend?.versionInfo()?.note ?? "not registered";
-      return fail(runId, startedAt, `backend '${agentDef.backend}' unavailable: ${note}`, opts.agent);
+      return fail(runId, startedAt, `backend '${backendId}' unavailable: ${note}`, opts.agent);
     }
+    // SPEC-4: when a lifecycle provides a skills override, clone the agentDef so the factory's
+    // skillsOverride (buildChildLoader reads agent.skills) loads the phase's bundle, not the agent's.
+    const childAgent = opts.skillsOverride ? { ...agentDef, skills: opts.skillsOverride } : agentDef;
 
     // resolve model
     const model = opts.model ?? agentDef.model ?? `${opts.parentModel.provider}/${opts.parentModel.id}`;
 
     // child tools pass through UNFILTERED — the single-writer `todo`-exclusion is enforced
     // downstream by the child factory's `excludeTools: ["todo"]` (SPEC-2 §9.1 hardening).
-    const tools = agentDef.tools ?? PI_DEFAULT_TOOLS;
+    const tools = childAgent.tools ?? PI_DEFAULT_TOOLS;
     const memoryPort = opts.memoryPort ?? NOOP_MEMORY_PORT;
     const visionPort = opts.visionPort ?? NOOP_VISION_PORT;
 
@@ -138,7 +152,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     try {
       const link = await opts.todoSync.linkOrCreateRunTodo({
         runId, agent: agentDef.name, task: opts.task,
-        todoId: opts.todoId, track: track && agentDef.todoSync,
+        todoId: opts.lifecycleTodoId ?? opts.todoId, track: track && agentDef.todoSync,
       });
       todoId = link.todoId;
       priorStatus = link.priorStatus;
@@ -151,12 +165,12 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     const { session } = await backend.factory.create({
       cwd: opts.parentCwd,
       model,
-      thinkingLevel: agentDef.thinkingLevel,
+      thinkingLevel: childAgent.thinkingLevel,
       tools,
-      rolePrompt: agentDef.rolePrompt,
-      skills: agentDef.skills ?? [],
+      rolePrompt: childAgent.rolePrompt,
+      skills: childAgent.skills ?? [],
       task: opts.task,
-      agent: agentDef,
+      agent: childAgent,
       memoryPort,
       visionPort,
     });
@@ -229,15 +243,18 @@ async function finishRun(
 ): Promise<SpawnResult> {
   const endedAt = Date.now();
   opts.runRegistry.update(runId, { status, endedAt, resultSummary: finalText.slice(0, 120) });
-  // todo-sync reconciliation must not mask the run result
-  try {
-    if (status === "completed") {
-      await opts.todoSync.markRunTodoDone(todoId, priorStatus, finalText.slice(0, 500));
-    } else {
-      await opts.todoSync.markRunTodoReverted(todoId, priorStatus, error ?? status);
+  // SPEC-4: lifecycle phase children skip the per-run todo reconciliation — the lifecycle
+  // engine owns the lifecycle todo's status + progress block (Q7=C).
+  if (!opts.lifecycleTodoId) {
+    try {
+      if (status === "completed") {
+        await opts.todoSync.markRunTodoDone(todoId, priorStatus, finalText.slice(0, 500));
+      } else {
+        await opts.todoSync.markRunTodoReverted(todoId, priorStatus, error ?? status);
+      }
+    } catch {
+      // swallow — the run result is authoritative; the finally in spawnSubagent releases the lock
     }
-  } catch {
-    // swallow — the run result is authoritative; the finally in spawnSubagent releases the lock
   }
   return {
     status, finalText, runId, todoId, agent: agentName, model,

package/src/index.ts

@@ -26,6 +26,20 @@ import { ResumeStore } from "./backend/resume-store.ts";
 import { detectClaude } from "./backend/claude-detector.ts";
 import { createClaudeChildFactory } from "./backend/claude-factory.ts";
 import { join } from "node:path";
+import { discoverLifecycles } from "./lifecycle/registry.ts";
+import { DEFAULT_LIFECYCLE, builtinLifecyclesDir } from "./lifecycle/default.ts";
+import type { LifecycleDef } from "./lifecycle/lifecycle-types.ts";
+import type { LifecycleRunDeps } from "./lifecycle/run-lifecycle.ts";
+import { WorktreeService } from "./worktree/worktree-service.ts";
+import { DiffService } from "./worktree/diff-service.ts";
+import { RunJournal } from "./runtime/run-journal.ts";
+import { ConcurrencyPool } from "./runtime/concurrency-pool.ts";
+import { ResultsInbox } from "./runtime/results-inbox.ts";
+import { runBackground, type AsyncRunnerDeps } from "./runtime/async-runner.ts";
+import { scanResumeCandidates } from "./runtime/resume.ts";
+import { Scheduler } from "./scheduling/scheduler.ts";
+import { createFleetResultsTool } from "./tools/fleet-results.ts";
+import { BgRunsStore } from "./panel/bg-runs-store.ts";
 
 /** The package builtin agents/ dir, resolved relative to this module. */
 function builtinAgentsDir(): string {
@@ -126,7 +140,55 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     backendRegistry: await buildDefaultBackendRegistry(modelRuntime),
     parentModel: { provider: "", id: "" },
     parentCwd: "",
+    lifecycleRegistry: new Map<string, LifecycleDef>(),
+    lifecycleRuns: new Map<string, import("./lifecycle/lifecycle-types.ts").LifecycleRunRecord>(),
+    lifecycleDeps: {
+      registry: new Map(),          // wired to the real agent registry in refreshLifecycles (Task 12)
+      agentRegistry: new Map(),     // ditto
+      todoPort: new ArmoryTodoAdapter(),
+      resolveBackend: (phaseBackend, lifecycleBackend) => {
+        const id = phaseBackend ?? lifecycleBackend;
+        if (id === "claude" && !deps.backendRegistry.get("claude")?.available()) {
+          throw new Error("phase requests backend 'claude' but claude is not installed; run 'claude' to set up, or change the phase backend in the lifecycle file");
+        }
+        return id;
+      },
+      genRunId: () => "fl-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8),
+    },
+  };
+  // Seed the builtin `default` lifecycle + wire lifecycleDeps to the live registries.
+  deps.lifecycleRegistry.set(DEFAULT_LIFECYCLE.name, DEFAULT_LIFECYCLE);
+  deps.lifecycleDeps.registry = deps.lifecycleRegistry;
+  deps.lifecycleDeps.agentRegistry = deps.registry;
+
+  // ── SPEC-5a: operational runtime (async/bg + scheduling + worktree isolation) ──
+  const fleetDir = (cwd: string) => join(cwd, ".pi", "fleet");
+  const bgRuns = new BgRunsStore();
+  const resultsInbox = new ResultsInbox();
+  // The async runner's runLifecycle adapter: call the real runLifecycle with the worktree as the
+  // spawn cwd + override genRunId so the lifecycle runId IS the async runner's runId (Q1=B seam).
+  const asyncRunLifecycle: AsyncRunnerDeps["runLifecycle"] = async (task, lifecycleName, opts) => {
+    const { runLifecycle } = await import("./lifecycle/run-lifecycle.ts");
+    const { spawnSubagent } = await import("./engine/spawnSubagent.ts");
+    const lifecycleFullDeps: LifecycleRunDeps = {
+      ...deps.lifecycleDeps,
+      genRunId: () => opts.runId,   // override: use the async runner's runId
+      // SPEC-5a (Q3=A): isolated run — worktree-diff artifact discovery instead of the prompt-baked block.
+      artifactDiscovery: ({ finalText, cwd, baseRef }) => (deps.asyncRunner as AsyncRunnerDeps).diff.diffPhase(cwd, baseRef, finalText),
+      spawn: async (o) => spawnSubagent({
+        agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
+        skillsOverride: o.skills, backendOverride: o.backend,
+        registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
+        backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: opts.worktreePath,  // child runs in the worktree
+      }),
+    };
+    const res = await runLifecycle(task, lifecycleName, { deps: lifecycleFullDeps, mode: opts.mode, worktreePath: opts.worktreePath, baseRef: "HEAD", onCheckpoint: async (p) => p.status === "failed" ? { action: "abort" } : { action: "continue" } });
+    return res as unknown as import("./runtime/async-runner.ts").FakeLifecycleResult;
   };
+  // asyncRunnerDeps + scheduler are built per-session (need the session cwd); wired on session_start.
+  // At init they're undefined — the subagent tool's `if (!deps.asyncRunner)` guard returns an
+  // actionable "not configured" error if called before session_start (can't happen in practice).
+  deps.bgRuns = bgRuns;
 
   const refresh = (ctx: { cwd: string; ui: { notify: (m: string, t?: "info" | "warning" | "error") => void } }): void => {
     const r = discoverAgents({
@@ -136,22 +198,67 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     });
     for (const e of r.errors) ctx.ui.notify(e, "error");
     for (const w of r.warnings) ctx.ui.notify(w, "warning");
-    deps.registry = r.agents;
+    // Mutate in place (not replace the reference) so lifecycleDeps.agentRegistry — which is bound
+    // to this same Map once at init — stays live across refreshes (SPEC-4 fix).
+    deps.registry.clear();
+    for (const [k, v] of r.agents) deps.registry.set(k, v);
+  };
+
+  const refreshLifecycles = (ctx: { cwd: string; ui: { notify: (m: string, t?: "info" | "warning" | "error") => void } }): void => {
+    const r = discoverLifecycles({
+      projectDir: join(ctx.cwd, ".pi", "lifecycles"),
+      globalDir: join(process.env.HOME ?? "", ".pi", "agent", "lifecycles"),
+      builtinDir: builtinLifecyclesDir(),
+    });
+    for (const e of r.errors) ctx.ui.notify(e, "error");
+    for (const w of r.warnings) ctx.ui.notify(w, "warning");
+    deps.lifecycleRegistry.clear();
+    deps.lifecycleRegistry.set(DEFAULT_LIFECYCLE.name, DEFAULT_LIFECYCLE);
+    for (const [name, def] of r.lifecycles) deps.lifecycleRegistry.set(name, def);
   };
 
   pi.on("session_start", (_event, ctx) => {
     refresh(ctx);
+    refreshLifecycles(ctx);
     const m = ctx.model;
     deps.parentModel = m ? { provider: m.provider, id: m.id } : { provider: "", id: "" };
     deps.parentCwd = ctx.cwd;
+    // SPEC-5a: build the per-session async runner + scheduler, start firing, scan for interrupted runs.
+    const dir = fleetDir(ctx.cwd);
+    deps.asyncRunner = {
+      worktree: new WorktreeService({ rootDir: ctx.cwd }),
+      diff: new DiffService(),
+      journal: new RunJournal(join(dir, "runs")),
+      pool: new ConcurrencyPool(3),
+      inbox: resultsInbox,
+      runLifecycle: asyncRunLifecycle,
+      notify: (m, lvl) => ctx.ui.notify(m, lvl),
+      genRunId: () => "fl-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8),
+      onProgress: (runId, status) => { bgRuns.set(runId, status); },
+    };
+    deps.scheduler = new Scheduler({
+      storePath: join(dir, "schedules.json"),
+      lockPath: join(dir, "schedules.lock"),
+      onFire: (spec) => {
+        if (!deps.asyncRunner) return;
+        runBackground(spec.task, { deps: deps.asyncRunner, lifecycle: spec.lifecycle ?? "default", mode: spec.auto ? "auto" : "checkpointed" });
+      },
+    });
+    deps.scheduler.start();
+    const cands = scanResumeCandidates(ctx.cwd, { runsDir: join(dir, "runs"), worktree: deps.asyncRunner.worktree });
+    if (cands.length > 0) {
+      ctx.ui.notify(`${cands.length} interrupted fleet run${cands.length > 1 ? "s" : ""} — open /fleet to resume`, "info");
+    }
   });
 
   pi.on("resources_discover", (event, ctx) => {
-    if (event.reason === "reload") refresh(ctx);
+    if (event.reason === "reload") { refresh(ctx); refreshLifecycles(ctx); }
     return undefined;
   });
 
   pi.registerTool(createSubagentTool(deps) as never);
+  // SPEC-5a: fleet.results — the agent pulls completed bg-run results from the inbox (Q6=C).
+  pi.registerTool(createFleetResultsTool({ inbox: resultsInbox }) as never);
 
   pi.registerCommand("fleet", {
     description: "Open the armory-fleet panel (running + recent subagents + agent registry).",
@@ -163,4 +270,50 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       openFleetPanel(deps, ctx as never);
     },
   });
+
+  // SPEC-4: /fleet-implement <task> [--lifecycle <name>] [--auto] — the done-bar slash.
+  const parseImplementArgs = (args: string): { task: string; lifecycle?: string; auto?: boolean } => {
+    const parts = String(args ?? "").trim().split(/\s+/);
+    let lifecycle: string | undefined; let auto = false; const taskParts: string[] = [];
+    for (let i = 0; i < parts.length; i++) {
+      if (parts[i] === "--lifecycle") { lifecycle = parts[++i]; continue; }
+      if (parts[i] === "--auto") { auto = true; continue; }
+      taskParts.push(parts[i]!);
+    }
+    return { task: taskParts.join(" ").trim(), lifecycle, auto };
+  };
+
+  pi.registerCommand("fleet-implement", {
+    description: "Run a task through the superpowers lifecycle (default). Flags: --lifecycle <name>, --auto.",
+    handler: async (args, ctx) => {
+      const parsed = parseImplementArgs(args);
+      const lcName = parsed.lifecycle ?? "default";
+      if (!parsed.task) { ctx.ui.notify("usage: /fleet-implement <task> [--lifecycle <name>] [--auto]", "warning"); return; }
+      if (!deps.lifecycleRegistry.has(lcName)) {
+        ctx.ui.notify(`lifecycle '${lcName}' not found; available: ${[...deps.lifecycleRegistry.keys()].sort().join(", ")}`, "error");
+        return;
+      }
+      const { runLifecycle } = await import("./lifecycle/run-lifecycle.ts");
+      const { spawnSubagent } = await import("./engine/spawnSubagent.ts");
+      const onCheckpoint: import("./lifecycle/run-lifecycle.ts").CheckpointFn = parsed.auto
+        ? async (_phase) => ({ action: "continue" })
+        : async (phase) => {
+            // Non-TUI / non-auto: can't prompt interactively → auto-continue + notify (open /fleet for interactive).
+            ctx.ui.notify(`lifecycle checkpoint at '${phase.name}' — open /fleet Lifecycle view to Continue/Revise/Abort (auto-continuing)`, "info");
+            return { action: "continue" };
+          };
+      const lifecycleFullDeps: import("./lifecycle/run-lifecycle.ts").LifecycleRunDeps = {
+        ...deps.lifecycleDeps,
+        spawn: async (o) => spawnSubagent({
+          agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
+            skillsOverride: o.skills, backendOverride: o.backend,
+          registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
+          backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: deps.parentCwd,
+        }),
+      };
+      const res = await runLifecycle(parsed.task, lcName, { deps: lifecycleFullDeps, mode: parsed.auto ? "auto" : "checkpointed", onCheckpoint });
+      deps.lifecycleRuns.set(res.runId, res);
+      ctx.ui.notify(`lifecycle ${res.status}: ${res.runId}${res.error ? " — " + res.error : ""}`, res.status === "completed" ? "info" : "warning");
+    },
+  });
 }

package/src/lifecycle/artifacts-parser.ts

@@ -0,0 +1,57 @@
+// src/lifecycle/artifacts-parser.ts
+import { parse as parseYaml } from "yaml";
+
+export const MAX_REVISE = 3;
+
+export interface ArtifactsOk { summary: string; paths: string[] }
+export interface ArtifactsErr { error: string }
+export type ArtifactsResult = ArtifactsOk | ArtifactsErr;
+
+/** Parse the trailing `Artifacts:` YAML block from a child's finalText.
+ *  Returns {summary, paths} on success, or {error} on failure.
+ *  terminal=true exempts a missing block (the finish phase may have no file artifact). */
+export function parseArtifacts(finalText: string, opts: { terminal?: boolean } = {}): ArtifactsResult {
+  // Strip a trailing prompt-echo trailer (e.g. CIPHER's "📌 YOUR PROMPT: ..." bordered by `---`),
+  // which the child may inherit from the base system prompt. The echo can contain the literal
+  // "Artifacts:" (quoting the phase instruction) and would fool lastIndexOf below.
+  let text = finalText;
+  const echoIdx = text.lastIndexOf("📌 YOUR PROMPT:");
+  if (echoIdx >= 0) {
+    text = text.slice(0, echoIdx).replace(/\n---\s*$/, "");
+  }
+  const marker = "Artifacts:";
+  const idx = text.lastIndexOf(marker);
+  if (idx < 0) {
+    if (opts.terminal) return { summary: text.trim(), paths: [] };
+    return { error: "missing Artifacts block (child did not list produced file paths)" };
+  }
+  const summary = text.slice(0, idx).trim();
+  let block = text.slice(idx + marker.length);
+  // Robustness: models often wrap the YAML in a fenced code block (the `Artifacts:` marker sits
+  // inside the fence) and/or trail a prompt-echo / signature. Strip a leading opening fence line
+  // (```yaml) if present, then truncate at the FIRST closing fence (```) or markdown thematic
+  // break (`\n---\n`) — whichever comes first — so trailing content can't break the YAML parse.
+  block = block.replace(/^\s*```[a-zA-Z]*\s*\n/, "");
+  const fenceClose = block.indexOf("```");
+  const brk = block.search(/\n---\s*\n/);
+  let cut = block.length;
+  if (fenceClose >= 0) cut = Math.min(cut, fenceClose);
+  if (brk >= 0) cut = Math.min(cut, brk);
+  block = block.slice(0, cut);
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(block) ?? [];
+  } catch (e) {
+    return { error: `malformed Artifacts block: ${(e as Error).message}` };
+  }
+  if (!Array.isArray(parsed)) return { error: "Artifacts block must be a list of {path, kind}" };
+  const entries = parsed as Array<Record<string, unknown>>;
+  const paths: string[] = [];
+  for (const e of entries) {
+    if (typeof e.path === "string" && e.path.trim()) paths.push(e.path.trim());
+  }
+  if (paths.length === 0 && !opts.terminal) {
+    return { error: "Artifacts block has no paths (non-terminal phase must produce at least one file)" };
+  }
+  return { summary, paths };
+}

package/src/lifecycle/default.ts

@@ -0,0 +1,74 @@
+// src/lifecycle/default.ts
+import { join } from "node:path";
+import { parseLifecycleFile } from "./registry.ts";
+import type { LifecycleDef } from "./lifecycle-types.ts";
+
+/** The package builtin lifecycles/ dir, resolved relative to this module. */
+export function builtinLifecyclesDir(): string {
+  return join(new URL(".", import.meta.url).pathname, "..", "..", "lifecycles");
+}
+
+/** The shipped `default` lifecycle as a markdown string (frontmatter + ## phase templates).
+ *  This is the single source of truth — it is both written to lifecycles/default.md
+ *  (for human reading) AND parsed here at runtime so the builtin is always in sync. */
+export const DEFAULT_LIFECYCLE_SOURCE = `---
+name: default
+description: The superpowers-native 5-phase lifecycle (brainstorm→plan→implement→review→finish).
+backend: pi
+phases:
+  - name: brainstorm
+    skills: [brainstorming]
+    agent: general-purpose
+    checkpoint: true
+  - name: plan
+    skills: [writing-plans]
+    agent: general-purpose
+    checkpoint: true
+  - name: implement
+    skills: [executing-plans, test-driven-development, verification-before-completion]
+    agent: general-purpose
+    checkpoint: false
+  - name: review
+    skills: [requesting-code-review, receiving-code-review]
+    agent: general-purpose
+    checkpoint: true
+  - name: finish
+    skills: [finishing-a-development-branch]
+    agent: general-purpose
+---
+
+## brainstorm
+You are the **brainstorm** phase of a superpowers lifecycle. Use the brainstorming skill.
+Task: {{task}}
+{% if prev %}Previous phase ({{prev.name}}) produced: {{prev.summary}}
+Artifacts to read: {{prev.paths}}{% endif %}
+Explore the task, produce a design doc per the brainstorming skill. End your response with an
+\`Artifacts:\` block (YAML) listing the produced file paths + a kind.
+
+## plan
+You are the **plan** phase. Use writing-plans. Read the brainstorm phase's design artifact.
+{% if prev %}Previous phase: {{prev.summary}} | Artifacts: {{prev.paths}}{% endif %}
+{% if feedback %}Human feedback on a prior attempt: {{feedback}}{% endif %}
+Write the implementation plan per writing-plans. End with an \`Artifacts:\` block.
+
+## implement
+You are the **implement** phase. Use executing-plans + test-driven-development + verification-before-completion.
+Read the plan artifact. Implement it, run tests, verify before claiming done.
+End with an \`Artifacts:\` block (files changed).
+
+## review
+You are the **review** phase. Use requesting-code-review + receiving-code-review.
+Review the implementation against the plan + design. Produce review findings.
+End with an \`Artifacts:\` block (review notes path).
+
+## finish
+You are the **finish** phase. Use finishing-a-development-branch.
+Decide merge/PR/cleanup per the skill and execute it. End with an \`Artifacts:\` block
+(or omit on a merge/PR with no further file artifact — terminal-phase exemption).
+`;
+
+export const DEFAULT_LIFECYCLE: LifecycleDef = parseLifecycleFile(
+  DEFAULT_LIFECYCLE_SOURCE,
+  "<builtin:default>",
+  "builtin",
+);

package/src/lifecycle/lifecycle-todo.ts

@@ -0,0 +1,84 @@
+// src/lifecycle/lifecycle-todo.ts
+import type { BackendId, LifecycleMode } from "./lifecycle-types.ts";
+
+/** Minimal port shape the lifecycle-todo helpers need (so unit tests can pass a fake
+ *  without depending on the full TodoSyncPort). */
+export interface LifecycleTodoPort {
+  linkOrCreateRunTodo(run: { runId: string; agent: string; task: string; todoId?: string; track: boolean }): Promise<{ todoId: string | null; priorStatus?: string }>;
+  markRunTodoDone(todoId: string | null, priorStatus: string | undefined, result: string): Promise<void>;
+  markRunTodoReverted(todoId: string | null, priorStatus: string | undefined, reason: string): Promise<void>;
+  updateLifecycleProgress(todoId: string, progressBlock: string): Promise<void>;
+}
+
+/** Test fake helper type (re-exported so tests don't hand-roll the shape). */
+export interface FakeTodoPort extends LifecycleTodoPort {
+  _state: Map<string, { id: string; notes: string; status: string }>;
+}
+
+export interface LifecycleTodoMeta {
+  runId: string; task: string; lifecycle: string; backend: BackendId; mode: LifecycleMode;
+  phases: string[];
+}
+
+export interface ProgressPhase {
+  name: string;
+  done: boolean;
+  revising?: boolean;
+  attempt?: number;
+}
+
+export function buildProgressBlock(opts: {
+  lifecycle: string; task: string; backend: BackendId; mode: LifecycleMode;
+  phases: ProgressPhase[]; last: string;
+}): string {
+  const marks = opts.phases.map((p) => {
+    if (p.done) return `[x] ${p.name}`;
+    if (p.revising) return `[~] ${p.name} (revising, attempt ${p.attempt ?? 1}/3)`;
+    return `[ ] ${p.name}`;
+  }).join("  ");
+  return [
+    `Lifecycle: ${opts.lifecycle} · task: "${opts.task}"`,
+    `Backend: ${opts.backend} · Mode: ${opts.mode}`,
+    `Phases: ${marks}`,
+    `Last: ${opts.last}`,
+  ].join("\n");
+}
+
+export async function createLifecycleTodo(port: LifecycleTodoPort, meta: LifecycleTodoMeta): Promise<string> {
+  const link = await port.linkOrCreateRunTodo({
+    runId: meta.runId, agent: meta.lifecycle, task: meta.task, track: true,
+  });
+  if (!link.todoId) throw new Error("lifecycle TODO link-or-create returned null (armory-todo port error)");
+  await port.updateLifecycleProgress(link.todoId, buildProgressBlock({
+    lifecycle: meta.lifecycle, task: meta.task, backend: meta.backend, mode: meta.mode,
+    phases: meta.phases.map((n) => ({ name: n, done: false })), last: "started",
+  }));
+  return link.todoId;
+}
+
+export async function updateProgress(
+  port: LifecycleTodoPort, todoId: string,
+  upd: { phase: string; done: boolean; last: string; revising: boolean; attempt: number },
+  ctx: { lifecycle: string; task: string; backend: BackendId; mode: LifecycleMode; phases: ProgressPhase[] },
+): Promise<void> {
+  // Mutate the shared progressPhases in place so completion accumulates across phases
+  // (a new array here would discard prior phases' [x] state — the block is the single source of truth).
+  for (const ph of ctx.phases) {
+    if (ph.name === upd.phase) {
+      ph.done = upd.done;
+      ph.revising = upd.revising;
+      ph.attempt = upd.attempt;
+    }
+  }
+  await port.updateLifecycleProgress(todoId, buildProgressBlock({
+    lifecycle: ctx.lifecycle, task: ctx.task, backend: ctx.backend, mode: ctx.mode, phases: ctx.phases, last: upd.last,
+  }));
+}
+
+export async function completeLifecycleTodo(port: LifecycleTodoPort, todoId: string, result: string): Promise<void> {
+  await port.markRunTodoDone(todoId, undefined, result);
+}
+
+export async function revertLifecycleTodo(port: LifecycleTodoPort, todoId: string, reason: string): Promise<void> {
+  await port.markRunTodoReverted(todoId, undefined, reason);
+}

package/src/lifecycle/lifecycle-types.ts

@@ -0,0 +1,66 @@
+// src/lifecycle/lifecycle-types.ts
+import type { FleetRunStatus } from "../todo-sync/port.ts";
+import type { AgentSource } from "../registry/frontmatter.ts";
+
+/** Backend id (mirrors SPEC-3 AgentDef.backend). */
+export type BackendId = "pi" | "claude";
+
+/** Lifecycle-wide status (richer than FleetRunStatus: adds checkpoint + revising). */
+export type LifecycleStatus = "running" | "checkpoint" | "completed" | "failed" | "aborted";
+
+export type LifecycleMode = "checkpointed" | "auto";
+
+/** A phase definition (parsed from a lifecycle file's frontmatter). */
+export interface PhaseDef {
+  name: string;
+  skills: string[];
+  /** Per-phase default agent pin; absent → general-purpose. */
+  agent?: string;
+  /** Per-phase backend override (Q4=C); absent → lifecycle.backend. */
+  backend?: BackendId;
+  /** Pause for human review after this phase; default true. Terminal phase omits (no checkpoint). */
+  checkpoint?: boolean;
+  /** The phase prompt template (parsed from the `## <name>` body section). */
+  promptTemplate: string;
+}
+
+export interface LifecycleDef {
+  name: string;
+  description: string;
+  /** Lifecycle-wide default backend; absent → "pi". */
+  backend: BackendId;
+  phases: PhaseDef[];
+  source: AgentSource;
+  filePath: string;
+}
+
+/** The record of one phase's execution (stored on the LifecycleRunRecord). */
+export interface PhaseRecord {
+  name: string;
+  summary: string;
+  paths: string[];
+  status: FleetRunStatus;
+  reviseCount: number;
+}
+
+export interface LifecycleRunRecord {
+  runId: string;
+  lifecycleName: string;
+  task: string;
+  backend: BackendId;
+  mode: LifecycleMode;
+  status: LifecycleStatus;
+  phases: PhaseRecord[];
+  startedAt: number;
+  /** Set when the lifecycle reaches a terminal status (completed/failed/aborted). */
+  endedAt?: number;
+  todoId: string | null;
+}
+
+/** Human (or auto) decision at a checkpoint. */
+export type CheckpointAction = "continue" | "revise" | "abort";
+export interface CheckpointDecision {
+  action: CheckpointAction;
+  /** Present only when action === "revise". */
+  feedback?: string;
+}

package/src/lifecycle/port.ts

@@ -0,0 +1,7 @@
+// src/lifecycle/port.ts
+export { parseLifecycleFile, discoverLifecycles, LifecycleParseError } from "./registry.ts";
+export type { LifecycleDiscoverOpts, LifecycleDiscoverResult } from "./registry.ts";
+export type {
+  LifecycleStatus, LifecycleMode, BackendId, PhaseDef, LifecycleDef, PhaseRecord,
+  LifecycleRunRecord, CheckpointAction, CheckpointDecision,
+} from "./lifecycle-types.ts";

package/src/lifecycle/prompt-template.ts

@@ -0,0 +1,40 @@
+// src/lifecycle/prompt-template.ts
+import type { PhaseRecord } from "./lifecycle-types.ts";
+
+export interface PromptVars {
+  task: string;
+  lifecycle: string;
+  phase: string;
+  /** Previous phase record (absent on phase 1). */
+  prev?: { name: string; summary: string; paths: string[] };
+  /** On Revise only: human feedback + prior-attempt digest. */
+  feedback?: string;
+}
+
+/** Render a phase prompt template. Supports {{task}}, {{lifecycle}}, {{phase}},
+ *  {{prev.name}}, {{prev.summary}}, {{prev.paths}}, {{feedback}}, and
+ *  {% if prev %}…{% endif %} / {% if feedback %}…{% endif %} conditional blocks. */
+export function renderPhasePrompt(template: string, vars: PromptVars): string {
+  let out = template;
+
+  // {% if prev %}…{% endif %}
+  out = out.replace(/{%\s*if\s*prev\s*%}([\s\S]*?){%\s*endif\s*%}/g,
+    vars.prev ? "$1" : "");
+  // {% if feedback %}…{% endif %}
+  out = out.replace(/{%\s*if\s*feedback\s*%}([\s\S]*?){%\s*endif\s*%}/g,
+    vars.feedback ? "$1" : "");
+
+  // {{prev.paths}} → newline-separated "- path" list (or empty)
+  const pathsStr = vars.prev ? vars.prev.paths.map((p) => `- ${p}`).join("\n") : "";
+
+  out = out
+    .replace(/{{\s*task\s*}}/g, vars.task)
+    .replace(/{{\s*lifecycle\s*}}/g, vars.lifecycle)
+    .replace(/{{\s*phase\s*}}/g, vars.phase)
+    .replace(/{{\s*prev\.name\s*}}/g, vars.prev?.name ?? "")
+    .replace(/{{\s*prev\.summary\s*}}/g, vars.prev?.summary ?? "")
+    .replace(/{{\s*prev\.paths\s*}}/g, pathsStr)
+    .replace(/{{\s*feedback\s*}}/g, vars.feedback ?? "");
+
+  return out;
+}