@nklisch/pi-agile-workflow 0.15.3

package/docs/VISION.md

@@ -0,0 +1,106 @@
+# Vision: agile-workflow
+
+**agile-workflow** is a portable agent workflow plugin/package that ships a
+markdown-based work-tracking substrate for AI-driven software projects. Work
+lives as plain markdown items in a `.work/` directory inside the repo. Each item
+is a single file with structured frontmatter — its body accumulates the brief,
+the design, the implementation notes, and the review findings as work
+progresses. Skills operate as verbs over those files, while each harness can add
+native ergonomics around the same substrate. There are no parallel design docs,
+no separate progress trackers, no tracking-board dependencies. The repo is the
+system of record.
+
+## Why this exists
+
+AI-driven software projects accumulate document sprawl: design docs that
+disagree with the code, progress files that go stale, roadmaps that bind
+features to releases the project never ships. The agent re-explains itself
+every session because it can't trust what it reads. The user re-feeds context
+because the artifacts have drifted from reality.
+
+The substrate pattern collapses this. The item file *is* the work. Stage
+advances as work happens. Foundation docs roll forward — they describe the
+system as it is now or as it is intended to become, never as it was. Git
+carries history; the active truth is what's in the file. An agent picking up a
+fresh session reads `.work/active/`, runs the prescribed grep primitives, and
+knows what's in flight without being re-fed.
+
+## Substrate philosophy
+
+The plugin enforces three execution principles:
+
+- **The item file is the work.** No parallel design docs. No separate
+  progress trackers. The brief, the design, the implementation notes, the
+  review findings — all accumulate in the item's body as stages advance.
+  Reading the file IS reading the state of work.
+- **Foundation docs roll forward.** `docs/VISION.md`, `docs/SPEC.md`,
+  `docs/ARCHITECTURE.md` describe current truth or intended future state.
+  When implementation changes what those docs assert, the docs update to
+  match the new truth. No "previously this worked differently." No legacy
+  comments. Git is the audit trail.
+- **Late-bind everything.** No upfront roadmap. No pre-populated stages.
+  No pre-tagged release bindings. Items advance stages when work actually
+  completes. Releases bind items only when the user cuts a version.
+
+The plugin's `principles` skill loads these alongside the code-design
+principles (Ports & Adapters, Single Source of Truth, Generated Contracts,
+Fail Fast) carried over from `workflow`. The two paradigms — substrate
+execution and code design — operate together during agile-workflow work.
+
+## Who this is for
+
+Project owners running AI-driven development who want:
+
+- A work-tracking substrate that lives with the repo, not behind a service
+- Cross-session continuity without manually re-feeding context to the agent
+- A pattern that scales from solo single-project to long-running
+  maintenance loops
+- Tooling-portable substrate (git, plain markdown, a small compiled binary
+  with a bash fallback — no MCP, no auth, no daemon)
+
+This is the supported workflow pattern for new projects in this repo. The older
+`workflow` plugin still ships only so existing installs do not break; migrate old
+projects with `/agile-workflow:convert`.
+
+## What success looks like now
+
+agile-workflow is complete enough to operate as the supported workflow engine:
+
+- 28 skills covering ideation, conversion, scoping, epic/feature design,
+  refactor/perf/e2e design, implementation orchestration, review, bug fixing,
+  board launch, bug scanning, release gates, release-deploy, and goal-backed
+  autopilot.
+- A compiled `work-view` CLI (with a pure-bash fallback on unsupported
+  platforms) for fast queries by stage, tag, kind, parent, release binding,
+  gate origin, and dependency state.
+- An interactive `work-view board` surface over the same substrate feed, with
+  kanban, dependency, table, detail, filter, and browsing views for humans.
+- Shared Claude/Codex/Pi substrate context injection that force-loads rules at
+  session/compaction boundaries, surfaces prompt-time principles capsules only
+  for actionable workflow prompts, auto-bumps `updated:` where the harness
+  supports it, and reports cheap substrate validation issues.
+- Three-channel plugin distribution metadata: Claude Code marketplace, OpenAI
+  Codex marketplace, and Pi packages share the same `skills/` source while
+  each channel carries native metadata and ergonomics.
+- Real releases move through scope → design → implement → review →
+  release-deploy on the substrate; gates produce items, and the release ships
+  only after every bound item is terminal.
+
+The pattern proves itself when a fresh session in a substrate-bootstrapped repo
+picks up active work without re-feed, when an autopilot run drains an epic to
+done autonomously across compaction events while respecting the declared
+dependency graph, and when foundation docs five features later still describe
+the present without legacy comments.
+
+## Relationship to workflow
+
+`workflow` is deprecated and retained only for compatibility with existing
+installs. New work should use `agile-workflow`; existing `workflow` projects
+migrate via `/agile-workflow:convert`. Supported agile-workflow channels are
+Claude Code, OpenAI Codex, and Pi; each channel adds native ergonomics around
+shared skill content rather than forking the workflow model.
+
+For depth on the principles, see [PRINCIPLES.md](./PRINCIPLES.md).
+For the technical contracts, see [SPEC.md](./SPEC.md).
+For the substrate's internal design, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+For the on-ramp from existing project shapes, see [MIGRATION.md](./MIGRATION.md).

package/extensions/agile-workflow.test.ts

@@ -0,0 +1,419 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  chmodSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import agileWorkflowExtension from "./agile-workflow";
+
+type ExecCall = {
+  command: string;
+  args: string[];
+  options?: { signal?: AbortSignal; timeout?: number };
+};
+
+type RegisteredHandler = (args: string | undefined, ctx: TestContext) => Promise<string>;
+type EventHandler = (event: unknown, ctx: TestContext) => unknown | Promise<unknown>;
+
+type TestContext = {
+  cwd?: string;
+  signal?: AbortSignal;
+  ui?: {
+    notifications: Array<{ message: string; level?: string }>;
+    statuses: Array<{ key: string; message: string }>;
+    widgets: Array<{ key: string; lines: string[] }>;
+    notify: (message: string, level?: "info" | "warning" | "error" | "success") => void;
+    setStatus: (key: string, message: string) => void;
+    setWidget: (key: string, lines: string[]) => void;
+  };
+};
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), "aw-extension-test-"));
+  roots.push(root);
+  return root;
+}
+
+function makeSubstrate(): { root: string; nested: string; workView: string } {
+  const root = tempRoot();
+  const workDir = join(root, ".work");
+  const binDir = join(workDir, "bin");
+  const nested = join(root, "one", "two");
+  mkdirSync(binDir, { recursive: true });
+  mkdirSync(nested, { recursive: true });
+  writeFileSync(join(workDir, "CONVENTIONS.md"), "# Project Conventions\n", "utf8");
+  const workView = join(binDir, "work-view");
+  writeFileSync(workView, "#!/usr/bin/env sh\nexit 0\n", "utf8");
+  chmodSync(workView, 0o755);
+  return { root, nested, workView };
+}
+
+function makeUi(): NonNullable<TestContext["ui"]> {
+  return {
+    notifications: [],
+    statuses: [],
+    widgets: [],
+    notify(message, level) {
+      this.notifications.push({ message, level });
+    },
+    setStatus(key, message) {
+      this.statuses.push({ key, message });
+    },
+    setWidget(key, lines) {
+      this.widgets.push({ key, lines });
+    },
+  };
+}
+
+function makePi(options: {
+  exec?: (command: string, args: string[], options?: ExecCall["options"]) => Promise<{
+    stdout?: string;
+    stderr?: string;
+    code?: number | null;
+    killed?: boolean;
+  }>;
+  sendUserMessage?: (content: string, options?: { deliverAs?: "followUp" | "steer" | "immediate" }) => void | Promise<void>;
+} = {}) {
+  const execCalls: ExecCall[] = [];
+  const sentMessages: Array<{ content: string; options?: { deliverAs?: "followUp" | "steer" | "immediate" } }> = [];
+  const eventHandlers: Record<string, EventHandler[]> = {};
+  let handler: RegisteredHandler | null = null;
+  const pi: {
+    exec: (command: string, args: string[], execOptions?: ExecCall["options"]) => Promise<{
+      stdout?: string;
+      stderr?: string;
+      code?: number | null;
+      killed?: boolean;
+    }>;
+    sendUserMessage?: (content: string, options?: { deliverAs?: "followUp" | "steer" | "immediate" }) => void | Promise<void>;
+    registerCommand: (name: string, commandOptions: { handler: RegisteredHandler }) => void;
+    on: (event: string, eventHandler: EventHandler) => void;
+  } = {
+    exec: async (command: string, args: string[], execOptions?: ExecCall["options"]) => {
+      execCalls.push({ command, args, options: execOptions });
+      if (options.exec) {
+        return options.exec(command, args, execOptions);
+      }
+      return { stdout: "story-a\n", code: 0 };
+    },
+    registerCommand: (name: string, commandOptions: { handler: RegisteredHandler }) => {
+      expect(name).toBe("aw");
+      handler = commandOptions.handler;
+    },
+    on: (event: string, eventHandler: EventHandler) => {
+      (eventHandlers[event] ??= []).push(eventHandler);
+    },
+  };
+  if ("sendUserMessage" in options) {
+    if (options.sendUserMessage) {
+      pi.sendUserMessage = options.sendUserMessage;
+    }
+  } else {
+    pi.sendUserMessage = async (content, messageOptions) => {
+      sentMessages.push({ content, options: messageOptions });
+    };
+  }
+  agileWorkflowExtension(pi);
+  if (!handler) {
+    throw new Error("extension did not register /aw");
+  }
+  return {
+    handler,
+    execCalls,
+    sentMessages,
+    eventHandlers,
+  };
+}
+
+async function fireEvent(
+  handlers: Record<string, EventHandler[]>,
+  eventName: string,
+  event: unknown,
+  ctx: TestContext,
+): Promise<unknown> {
+  let result: unknown;
+  for (const eventHandler of handlers[eventName] ?? []) {
+    const next = await eventHandler(event, ctx);
+    if (next !== undefined) result = next;
+  }
+  return result;
+}
+
+
+describe("/aw command shell", () => {
+  test("help does not require a substrate", async () => {
+    const { handler, execCalls } = makePi();
+    const result = await handler("help", { cwd: tempRoot() });
+    expect(result).toContain("/aw status");
+    expect(result).toContain("/aw autopilot [scope]");
+    expect(execCalls).toHaveLength(0);
+  });
+
+  test("missing substrate and missing work-view return actionable warnings", async () => {
+    const { handler } = makePi();
+    const ui = makeUi();
+    const noSubstrate = await handler("status", { cwd: tempRoot(), ui });
+    expect(noSubstrate).toContain("No agile-workflow substrate found");
+    expect(ui.notifications.at(-1)).toMatchObject({ level: "warning" });
+
+    const root = tempRoot();
+    mkdirSync(join(root, ".work"), { recursive: true });
+    writeFileSync(join(root, ".work", "CONVENTIONS.md"), "# Project Conventions\n", "utf8");
+    const missingTool = await handler("status", { cwd: root, ui });
+    expect(missingTool).toContain("no .work/bin/work-view");
+    expect(ui.notifications.at(-1)).toMatchObject({ level: "warning" });
+  });
+
+  test("walks upward from ctx.cwd and invokes work-view with an argument array", async () => {
+    const substrate = makeSubstrate();
+    const { handler, execCalls } = makePi({
+      exec: async () => ({ stdout: "story-ready\n", code: 0 }),
+    });
+    const signal = new AbortController().signal;
+
+    const result = await handler("ready", { cwd: substrate.nested, signal });
+
+    expect(result).toBe("story-ready");
+    expect(execCalls).toEqual([
+      {
+        command: substrate.workView,
+        args: ["--ready"],
+        options: { signal, timeout: 10_000 },
+      },
+    ]);
+  });
+});
+
+describe("/aw queue commands", () => {
+  test("status composes ready, review, and blocked calls and updates Pi UI", async () => {
+    const substrate = makeSubstrate();
+    const ui = makeUi();
+    const { handler, execCalls } = makePi({
+      exec: async (_command, args) => {
+        const key = args.join(" ");
+        if (key === "--ready") {
+          return { stdout: "ID  KIND  STAGE  TAGS  PARENT\n--  ----  -----  ----  ------\nready-a story implementing [] -\nready-b story review [] -\n", code: 0 };
+        }
+        if (key === "--stage review") {
+          return { stdout: "review-a\n", code: 0 };
+        }
+        if (key === "--blocked") {
+          return { stdout: "", code: 0 };
+        }
+        throw new Error(`unexpected args ${key}`);
+      },
+    });
+
+    const result = await handler("status", { cwd: substrate.root, ui });
+
+    expect(execCalls.map((call) => call.args)).toEqual([
+      ["--ready"],
+      ["--stage", "review"],
+      ["--blocked"],
+    ]);
+    expect(result).toContain("agile-workflow: 2 ready | 1 review | 0 blocked");
+    expect(ui.statuses).toEqual([{ key: "agile-workflow", message: "2 ready | 1 review | 0 blocked" }]);
+    expect(ui.widgets.at(-1)).toEqual({
+      key: "agile-workflow",
+      lines: ["agile-workflow", "2 ready | 1 review | 0 blocked", `root: ${substrate.root}`],
+    });
+  });
+
+  test("id filters reject invalid ids before exec and pass valid ids as arguments", async () => {
+    const substrate = makeSubstrate();
+    const { handler, execCalls } = makePi();
+
+    const invalid = await handler("parent ../../oops", { cwd: substrate.root });
+    expect(invalid).toContain("Expected an item id for --parent");
+    expect(execCalls).toHaveLength(0);
+
+    await handler("blocking story-alpha", { cwd: substrate.root });
+    expect(execCalls).toHaveLength(1);
+    expect(execCalls[0].args).toEqual(["--blocking", "story-alpha"]);
+  });
+
+  test("large output is truncated with an explicit marker", async () => {
+    const substrate = makeSubstrate();
+    const { handler } = makePi({
+      exec: async () => ({ stdout: "x".repeat(6_010), code: 0 }),
+    });
+
+    const result = await handler("ready", { cwd: substrate.root });
+
+    expect(result.length).toBeLessThan(6_100);
+    expect(result).toContain("[truncated 10 chars]");
+  });
+});
+
+describe("Pi hook parity adapter", () => {
+  test("injects shared .agents/rules content and prompt-gated principles", async () => {
+    const substrate = makeSubstrate();
+    mkdirSync(join(substrate.root, ".agents", "rules"), { recursive: true });
+    writeFileSync(
+      join(substrate.root, ".agents", "rules", "agile-workflow.md"),
+      "## Test Rules\n- keep the shared rules source",
+      "utf8",
+    );
+    const { eventHandlers } = makePi();
+
+    const result = await fireEvent(
+      eventHandlers,
+      "before_agent_start",
+      {
+        prompt: "implement story-alpha",
+        systemPrompt: "BASE",
+        systemPromptOptions: { cwd: substrate.root },
+      },
+      { cwd: substrate.root },
+    ) as {
+      systemPrompt: string;
+      message: { customType: string; content: string; display: boolean };
+    };
+
+    expect(result.systemPrompt.startsWith("BASE")).toBe(true);
+    expect(result.systemPrompt).toContain("## Project Rules (.agents/rules/)");
+    expect(result.systemPrompt).toContain("keep the shared rules source");
+    expect(result.systemPrompt).not.toContain("## Agile Workflow Principles");
+    expect(result.message.customType).toBe("agile-workflow-principles");
+    expect(result.message.display).toBe(true);
+    expect(result.message.content).toContain("## Agile Workflow Principles");
+    expect(result.message.content).toContain("Code-design capsule");
+  });
+
+  test("treats bare high-intent workflow verbs as actionable", async () => {
+    const substrate = makeSubstrate();
+    const { eventHandlers } = makePi();
+
+    const result = await fireEvent(
+      eventHandlers,
+      "before_agent_start",
+      { prompt: "implement", systemPrompt: "BASE", systemPromptOptions: { cwd: substrate.root } },
+      { cwd: substrate.root },
+    ) as { message: { content: string } };
+
+    expect(result.message.content).toContain("## Agile Workflow Principles");
+    expect(result.message.content).toContain("Code-design capsule");
+  });
+
+  test("forces rules context every Pi turn while honoring CONVENTIONS opt-out", async () => {
+    const substrate = makeSubstrate();
+    mkdirSync(join(substrate.root, ".agents", "rules"), { recursive: true });
+    writeFileSync(join(substrate.root, ".agents", "rules", "project.md"), "## Rules\n- loaded each turn", "utf8");
+    const { eventHandlers } = makePi();
+
+    const first = await fireEvent(
+      eventHandlers,
+      "before_agent_start",
+      { prompt: "explain this repo", systemPrompt: "BASE", systemPromptOptions: { cwd: substrate.root } },
+      { cwd: substrate.root },
+    ) as { systemPrompt: string };
+    const second = await fireEvent(
+      eventHandlers,
+      "before_agent_start",
+      { prompt: "explain this repo", systemPrompt: "BASE", systemPromptOptions: { cwd: substrate.root } },
+      { cwd: substrate.root },
+    ) as { systemPrompt: string };
+
+    expect(first.systemPrompt).toContain("loaded each turn");
+    expect(second.systemPrompt).toContain("loaded each turn");
+
+    writeFileSync(join(substrate.root, ".work", "CONVENTIONS.md"), "rules_context: off\n", "utf8");
+    const disabled = await fireEvent(
+      eventHandlers,
+      "before_agent_start",
+      { prompt: "explain this repo", systemPrompt: "BASE", systemPromptOptions: { cwd: substrate.root } },
+      { cwd: substrate.root },
+    );
+    expect(disabled).toBeUndefined();
+  });
+
+  test("runs substrate maintenance after mutating tools", async () => {
+    const substrate = makeSubstrate();
+    const storyDir = join(substrate.root, ".work", "active", "stories");
+    mkdirSync(storyDir, { recursive: true });
+    const storyPath = join(storyDir, "story-alpha.md");
+    writeFileSync(
+      storyPath,
+      [
+        "---",
+        "id: story-alpha",
+        "stage: implementing",
+        "tags: []",
+        "parent: null",
+        "depends_on: []",
+        "release_binding: null",
+        "gate_origin: null",
+        "created: 2000-01-01",
+        "updated: 2000-01-01",
+        "---",
+        "# Story Alpha",
+      ].join("\n"),
+      "utf8",
+    );
+    const { eventHandlers } = makePi();
+
+    const result = await fireEvent(
+      eventHandlers,
+      "tool_result",
+      {
+        toolName: "edit",
+        input: { path: storyPath },
+        content: [{ type: "text", text: "edited" }],
+      },
+      { cwd: substrate.root },
+    ) as { content: Array<{ type: string; text: string }> };
+
+    const updatedStory = readFileSync(storyPath, "utf8");
+    expect(updatedStory).toMatch(/updated: \d{4}-\d{2}-\d{2}/);
+    expect(updatedStory).not.toContain("updated: 2000-01-01");
+    expect(result.content.at(-1)?.text).toContain("Agile Workflow substrate validation found issues");
+    expect(result.content.at(-1)?.text).toContain("missing required frontmatter fields: kind");
+  });
+});
+
+describe("/aw workflow handoffs", () => {
+  test("queues board, autopilot, and scope through Pi follow-up messages", async () => {
+    const substrate = makeSubstrate();
+    const { handler, sentMessages } = makePi();
+
+    await handler("board", { cwd: substrate.root });
+    await handler("autopilot", { cwd: substrate.root });
+    await handler("autopilot feature-alpha", { cwd: substrate.root });
+    await handler("scope capture this idea", { cwd: substrate.root });
+
+    expect(sentMessages).toEqual([
+      { content: "$agile-workflow:board", options: { deliverAs: "followUp" } },
+      { content: "$agile-workflow:autopilot --all", options: { deliverAs: "followUp" } },
+      { content: "$agile-workflow:autopilot feature-alpha", options: { deliverAs: "followUp" } },
+      { content: "$agile-workflow:scope capture this idea", options: { deliverAs: "followUp" } },
+    ]);
+  });
+
+  test("scope requires text and handoffs fall back when follow-ups are unavailable", async () => {
+    const substrate = makeSubstrate();
+    const ui = makeUi();
+    const { handler, sentMessages } = makePi({ sendUserMessage: undefined });
+
+    const missingScope = await handler("scope", { cwd: substrate.root, ui });
+    expect(missingScope).toContain("Expected an idea or item id for /aw scope");
+
+    const fallback = await handler("board", { cwd: substrate.root, ui });
+    expect(fallback).toContain("Pi follow-up messages are unavailable");
+    expect(fallback).toContain("$agile-workflow:board");
+    expect(sentMessages).toHaveLength(0);
+  });
+});