poly-weaver 0.2.5

package/README.md

@@ -0,0 +1,388 @@
+# poly-weaver
+
+Orchestrates pluggable AI coding agents in iterative plan-review loops.
+
+poly-weaver spawns AI CLI tools (Claude Code, Codex CLI, GitHub Copilot CLI) via PTY and drives them through a declarative **Flow DSL** that defines the workflow as composable steps. A planner agent drafts a plan, a reviewer agent evaluates it, and the user can intervene at each checkpoint. Once approved, an implementor agent executes the plan with its own review cycle. A simplifier agent can optionally refine the result after implementation. All inter-step data flows through an artifact-based system — steps declare what they read and write, and data is exchanged via a shared artifact store.
+
+## How it works
+
+The default flow uses a **two-layered loop** structure:
+
+```
+ Task
+  │
+  ▼
+┌─── Outer loop (user feedback) ──────────────────────────────────┐
+│                                                                 │
+│  ┌──────────┐   ┌──────────────┐                                │
+│  │ Planner  │──▶│ User review  │──▶ accept / give feedback      │
+│  └──────────┘   └──────────────┘         │                      │
+│   ▲                  │ feedback          │ accept                │
+│   └──────────────────┘                   ▼                      │
+│                                ┌─── Inner loop ──────────┐      │
+│                                │ Plan ──▶ Review          │      │
+│                                │  ▲   rejected  │         │      │
+│                                │  └──────────────┘        │      │
+│                                │         │ approved       │      │
+│                                └─────────┼────────────────┘      │
+│                                          ▼                      │
+│                                ┌──────────────┐                 │
+│                                │ User approve │──▶ restart / ok │
+│                                └──────────────┘                 │
+└─────────────────────────────────────────────────────────────────┘
+                                           │ ok
+                                           ▼
+                              ┌─── Impl loop ──────────────┐
+                              │ Implement ──▶ Review        │
+                              │   ▲     rejected  │         │
+                              │   └───────────────┘         │
+                              │          │ approved          │
+                              └──────────┼──────────────────┘
+                                         ▼
+                                       Done
+```
+
+In **auto mode** (`--auto`), user review steps are skipped — the reviewer loop alone decides approval. The startup TUI renders a live ASCII flow diagram reflecting the configured mode.
+
+### "Why So Serious" workflow
+
+The **why-so-serious** workflow (selectable via Shift+Tab in the TUI) extends the default flow with two additions:
+
+1. **Conditional re-planning** — if the implementation reviewer finds more than 2 issues, a planner step runs before the next implementation attempt to draft a targeted fix plan. When issues are within threshold, the implementor revises normally.
+2. **Simplification pass** — after the implementation loop is approved, a simplifier agent reviews the codebase and produces a simplification plan, which the implementor then applies.
+
+```
+  Default impl loop               Why-so-serious impl loop
+  ────────────────                 ────────────────────────
+  Implement → Review              issues > 2 ? → Planner (fix plan)
+    ↑ rejected  │                 Implement → Review
+    └────────────┘                   ↑ rejected  │
+         │ approved                  └────────────┘
+         ▼                                │ approved
+       Done                               ▼
+                                    Simplifier → Implement
+                                          ▼
+                                        Done
+```
+
+### Custom flows
+
+Custom flows live in `~/.poly-weaver/flows/` as `.mjs` files. Each file exports a factory function that receives the DSL toolkit and returns a flow template:
+
+```js
+// ~/.poly-weaver/flows/my-flow.mjs
+export default function (dsl) {
+  const { defineFlow, loop, artifactData, plan, review, TASK } = dsl;
+
+  return {
+    name: "my-flow",
+    params: [
+      { key: "planner", type: "driver", role: "planner", label: "Planner", default: "claude" },
+      { key: "reviewer", type: "driver", role: "reviewer", label: "Reviewer", default: "codex" },
+      { key: "maxIterations", type: "number", label: "Max Iterations", default: 5, min: 1, max: 50 },
+    ],
+    build(values) {
+      return defineFlow("my-flow", [
+        loop(values.maxIterations, artifactData("verdict", "approved"), [
+          plan({ driver: values.planner, reads: { task: TASK, verdict: "verdict" }, writes: { plan: "plan" } }),
+          review({ driver: values.reviewer, variant: "plan", reads: { task: TASK, plan: "plan" }, writes: { verdict: "verdict" } }),
+        ]),
+      ]);
+    },
+  };
+}
+```
+
+The DSL toolkit is imported via `poly-weaver/dsl` and includes all step builders (`plan`, `review`, `implement`, `simplify`, `user`), loop/predicate helpers, and the `TASK` constant. Use `create-flow` and `modify-flow` subcommands for LLM-assisted authoring. See [`src/flow/custom/AUTHORING.md`](src/flow/custom/AUTHORING.md) for the full DSL reference.
+
+Each agent is a real CLI process (Claude Code, Codex, or GitHub Copilot) running in a pseudo-terminal. poly-weaver reads their session files to detect completion, extract responses, and feed feedback.
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- A C++ toolchain for [node-pty](https://github.com/nicktomlin/node-pty):
+  - **Windows** — Visual Studio Build Tools
+  - **macOS** — Xcode Command Line Tools
+  - **Linux** — `build-essential`
+- At least one supported AI CLI installed and authenticated:
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — `npm install -g @anthropic-ai/claude-code`
+  - [Codex CLI](https://github.com/openai/codex) — `npm install -g @openai/codex`
+  - [GitHub Copilot CLI](https://github.com/github/copilot-cli) — `winget install GitHub.CopilotCLI`
+
+### Install from GitHub Packages
+
+```bash
+npm install -g poly-weaver
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/gim-home/poly-weaver.git
+cd poly-weaver
+npm install   # installs dependencies and builds automatically
+npm link      # registers the `poly-weaver` command globally
+```
+
+### Uninstall
+
+```bash
+npm uninstall -g poly-weaver
+# or if installed from source:
+npm unlink -g poly-weaver
+```
+
+## Usage
+
+```bash
+poly-weaver
+```
+
+This opens an interactive TUI to configure the task, select providers for each role, and set options before starting the orchestration loop.
+
+You can also pass arguments directly:
+
+```bash
+# Pass a task directly
+poly-weaver "Refactor the auth module to use JWT"
+
+# Read task from a file
+poly-weaver task.md
+
+# Choose providers for each role
+poly-weaver "Add unit tests" --planner claude --reviewer copilot --implementor claude
+
+# Plan only (skip implementation)
+poly-weaver "Design a caching layer" --plan-only
+
+# Fully automated (no user checkpoints)
+poly-weaver "Fix the login bug" --auto
+
+# Opinionless mode — minimal prompts, agent decides the approach
+poly-weaver "Refactor the auth module" --opinionless
+```
+
+### CLI options
+
+| Option | Description | Default |
+|---|---|---|
+| `[task]` | Task description or path to a `.md`/`.txt` file | _(interactive)_ |
+| `--planner <cli>` | Provider for planning (`claude` \| `codex` \| `copilot`) | `claude` |
+| `--reviewer <cli>` | Provider for reviewing (`claude` \| `codex` \| `copilot`) | `codex` |
+| `--implementor <cli>` | Provider for implementation (`claude` \| `codex` \| `copilot`) | `claude` |
+| `--simplifier <cli>` | Provider for simplification (`claude` \| `codex` \| `copilot`) | `claude` |
+| `--max-iterations <n>` | Max plan-review cycles | `5` (range: 1–50) |
+| `--max-impl-iterations <n>` | Max implementation-review cycles | `5` (range: 1–50) |
+| `--auto` | Skip user review phases | `false` |
+| `--plan-only` | Stop after plan approval, skip implementation | `false` |
+| `--workdir <path>` | Working directory for agent CLIs | current directory |
+| `--opinionless` | Use minimal prompts; let agents decide how to plan/review/implement | `false` |
+| `--no-yolo` | Run agents without auto-approving permissions | `false` (agents run with permission-skipping) |
+| `--whip-mode` / `--no-whip-mode` | Enable/disable neighbor awareness hints between agents | `false` |
+| `--workflow <name>` | Workflow template to use | `default` |
+| `--config <path>` | Path to a JSON config file | _(none)_ |
+| `--verbose` | Preserve session files for debugging | `false` |
+
+Workflow is selected via `--workflow <name>` or **Shift+Tab** in the TUI. Built-in workflows: `default`, `why-so-serious`. Custom flows are also available (see below).
+
+### Subcommands
+
+```bash
+poly-weaver create-flow    # LLM-assisted custom flow creation
+poly-weaver modify-flow    # Modify an existing custom flow
+```
+
+## Architecture
+
+```
+src/
+├── cli.ts                 # Entry point, argument parsing (Commander)
+├── orchestrator.ts        # Builds flow from template, runs executor
+├── config.ts              # Config file loading, user config persistence
+├── dsl.ts                 # DSL toolkit barrel for custom flows (poly-weaver/dsl)
+├── prompts.ts             # Shared prompt utilities (verdict schema, feedback derivation)
+├── preflight.ts           # CLI availability checks
+├── startup-tui.ts         # Interactive startup TUI with live flow diagram
+├── preview-panel.ts       # Shared TUI panel rendering (config fields, flow diagram)
+├── status-bar.ts          # Persistent status bar rendering
+├── terminal-input.ts      # Terminal input utilities
+├── git-info.ts            # Git branch/status detection
+├── ansi.ts                # Shared ANSI helpers
+├── version.ts             # App version constant
+├── flow/
+│   ├── types.ts           # FlowStep, ArtifactStore, FlowTemplate, FlowParam
+│   ├── dsl.ts             # DSL helpers: defineFlow, loop, predicates
+│   ├── executor.ts        # Walks a FlowDefinition, runs steps
+│   ├── neighbors.ts       # Data-flow consumer map computation
+│   ├── artifacts.ts       # MapArtifactStore implementation
+│   ├── params.ts          # Flow param resolution (CLI > file > user > default)
+│   ├── diagram.ts         # ASCII flow diagram renderer for TUI
+│   ├── inspect.ts         # Flow definition introspection utilities
+│   ├── index.ts           # Re-exports
+│   ├── built-in/
+│   │   ├── default.ts     # Default two-layered flow template
+│   │   └── why-so-serious.ts # Why-so-serious flow template (conditional replan + simplify)
+│   └── custom/
+│       ├── load.ts        # Custom flow loader (discovers ~/.poly-weaver/flows/*.mjs)
+│       ├── index.ts       # Re-exports
+│       └── AUTHORING.md   # Full DSL reference for custom flow authors
+├── flow-editor/
+│   ├── tui.ts             # Flow editor TUI (create/modify modes)
+│   ├── llm.ts             # LLM prompt builders and code generation
+│   ├── validate.ts        # Flow code validation pipeline
+│   ├── save.ts            # Flow file persistence with backup
+│   ├── names.ts           # Random flow name generator
+│   └── index.ts           # Re-exports
+├── agents/
+│   ├── registry.ts        # Role registry: registerRole, createHandler
+│   ├── runner.ts          # AgentRunner — shared spawn→detect→exit lifecycle
+│   ├── whip-hint.ts       # Whip mode hint builder
+│   ├── index.ts           # Registers built-in providers, re-exports DSL helpers
+│   ├── planners/
+│   │   ├── prompts.ts     # Planner prompt builders and prompt sets
+│   │   ├── dsl.ts         # plan() DSL helper
+│   │   ├── handler.ts     # PlannerRoleHandler (artifact ↔ driver bridge)
+│   │   ├── adapter.ts     # PlannerAdapter (driver ↔ provider bridge)
+│   │   ├── types.ts       # PlannerDriver interface
+│   │   └── index.ts       # Self-registers into role registry
+│   ├── reviewers/         # Same structure + prompts.ts
+│   ├── implementors/      # Same structure + prompts.ts
+│   └── simplifiers/       # Same structure + prompts.ts
+├── user/
+│   ├── dsl.ts             # user() DSL helper for user-review steps
+│   ├── handler.ts         # User checkpoint handler
+│   ├── prompt.ts          # User prompt rendering
+│   └── index.ts           # Re-exports
+├── providers/
+│   ├── types.ts           # ProviderStrategy, SessionHandler, CompletionDetector
+│   ├── registry.ts        # Built-in provider registry (name → strategy)
+│   ├── invoke.ts          # Non-interactive provider invocation
+│   ├── base-completion.ts # Shared completion detection logic
+│   ├── prompt-file.ts     # Prompt file writing utilities
+│   ├── path-utils.ts      # Path helpers
+│   ├── index.ts           # Re-exports all provider strategies
+│   ├── claude/
+│   │   ├── strategy.ts    # ClaudeStrategy
+│   │   ├── session.ts     # Claude session file handling
+│   │   ├── completion.ts  # Claude completion detection
+│   │   └── index.ts
+│   ├── codex/
+│   │   ├── strategy.ts    # CodexStrategy
+│   │   ├── session.ts     # Codex session file handling
+│   │   ├── completion.ts  # Codex completion detection
+│   │   └── index.ts
+│   └── copilot/
+│       ├── strategy.ts    # CopilotStrategy
+│       ├── session.ts     # Copilot session file handling
+│       ├── completion.ts  # Copilot completion detection
+│       └── index.ts
+├── session/
+│   ├── dir.ts             # Session temp directory lifecycle
+│   ├── reader.ts          # JSONL session file parser
+│   └── locator.ts         # Session file discovery
+└── pty/
+    ├── spawn.ts           # PTY spawning (node-pty)
+    ├── exit.ts            # Exit signal handling
+    └── types.ts           # PTY-related types
+```
+
+### Opinionless mode
+
+By default, poly-weaver prompts include prescriptive criteria for each role — evaluation rubrics for reviewers, structural requirements for planners, step-by-step instructions for implementors.
+
+With `--opinionless`, prompts are stripped to the structural minimum: file path references and the verdict output schema. The agent decides how to approach its role. The verdict schema is also simplified — each issue only requires a `description`, with `category` and `severity` left to the agent's discretion.
+
+This is useful when the AI agent has its own strong conventions, or when you want to compare agent behavior with and without prescriptive guidance.
+
+### Whip mode
+
+With `--whip-mode`, each agent receives a hint describing who produced its input and who will consume its output. For example, a planner might see:
+
+> The previous step was performed by Claude. Codex will review your plan.
+
+Hints are suppressed when neighbors use the same provider — telling Claude that Claude produced the input is not actionable. This means whip mode only adds value in **mixed-provider workflows** where agents benefit from knowing their neighbors' capabilities and conventions.
+
+Toggle it in the TUI or pass `--whip-mode` / `--no-whip-mode` on the command line.
+
+### Registry + Handler + Adapter + Runner
+
+The agent system has four layers:
+
+- **Role Registry** (`src/agents/registry.ts`) — maps role names (planner, reviewer, implementor) to role modules. Each module self-registers on import and exposes `createHandler()` and `availableDrivers()`.
+- **Role Handlers** (e.g. `PlannerRoleHandler`) — bridge the artifact store and the driver interface. They read artifacts declared in the step's `reads`, call the driver, and write results to the step's `writes`.
+- **Role Adapters** (e.g. `PlannerAdapter`) — implement the driver interface by translating role-specific calls into generic agent runs with the appropriate prompts and file routing. Each adapter wraps a `ProviderStrategy`.
+- **`AgentRunner`** — executes the shared lifecycle: snapshot session files → spawn PTY → detect completion → extract response → exit. Accepts any `ProviderStrategy`.
+
+DSL helpers (`plan()`, `review()`, `implement()`, `simplify()`, `user()`) create flow step definitions. The executor walks the flow and uses the registry to instantiate handlers, which delegate to adapters, which delegate to the runner.
+
+For programmatic use outside flows, `invoke(provider, prompt, workdir)` in `src/providers/invoke.ts` offers one-shot non-interactive provider invocation — resolve provider, spawn PTY, detect completion, return response text.
+
+### Artifact system
+
+Steps declare what they read and write via `reads` and `writes` mappings (e.g. `reads: { task: "task", verdict: "verdict" }`). Data flows through a shared in-memory `ArtifactStore` — a `Map<string, Artifact>` where each artifact can carry:
+
+- `file` — path to an artifact file on disk (in the session temp directory)
+- `text` — human-readable content
+- `data` — parsed structured data (for predicates to inspect programmatically)
+- `meta` — metadata (e.g. source, version)
+
+## Adding a provider
+
+1. Implement `ProviderStrategy`, `SessionHandler`, and `CompletionDetector` (see `src/providers/types.ts`)
+2. Register the provider strategy with each role module:
+
+```ts
+import * as planners from "./agents/planners/index.js";
+import * as reviewers from "./agents/reviewers/index.js";
+import * as implementors from "./agents/implementors/index.js";
+import * as simplifiers from "./agents/simplifiers/index.js";
+
+const myProvider = new MyStrategy();
+planners.registerProvider("my-cli", myProvider);
+reviewers.registerProvider("my-cli", myProvider);
+implementors.registerProvider("my-cli", myProvider);
+simplifiers.registerProvider("my-cli", myProvider);
+```
+
+## Adding a role
+
+1. Create six files in `src/agents/<role>/`:
+
+| File | Purpose |
+|------|---------|
+| `types.ts` | Driver interface, run options, and result types |
+| `prompts.ts` | Role-specific prompt builders and prompt sets |
+| `adapter.ts` | Extends `BaseAdapter`; bridges the driver to `AgentRunner` via prompt selection |
+| `handler.ts` | Implements `RoleHandler`; orchestrates artifacts, retry, and session state |
+| `dsl.ts` | DSL helper (e.g. `myRole()`) that wraps `agentStep()` with role defaults |
+| `index.ts` | Module entry — calls `createRoleModule()`, exports DSL helper and `registerProvider` |
+
+2. Wire the role into the system (2 edits):
+   - **`src/agents/index.ts`** — add a side-effect import (`import "./<role>/index.js"`) and re-export the DSL helper
+   - **`src/flow/types.ts`** — add the role name to the `BuiltinRole` union
+
+3. Use the DSL helper in a flow:
+
+```ts
+import { myRole } from "./agents/index.js";
+
+const steps = [
+  myRole({ driver: "claude", reads: { task: "task" }, writes: { output: "result" } }),
+];
+```
+
+## Development
+
+```bash
+npm run build        # Compile TypeScript
+npm run dev          # Run via tsx (no build step)
+npm test             # Run unit tests (vitest)
+npm run test:e2e     # Run end-to-end tests
+npm run typecheck    # Type-check without emitting
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/agents/implementors/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { ImplementorDriver, ImplementResult, ImplementorPromptSet } from "./types.js";
+import type { StepMeta } from "../../flow/types.js";
+import type { ProviderStrategy } from "../../providers/types.js";
+import { BaseAdapter } from "../runner.js";
+type ImplementorRunOptions = {
+    resumeSessionId?: string;
+    feedbackFile?: string;
+    producers?: Record<string, StepMeta>;
+    consumers?: Record<string, StepMeta[]>;
+};
+export declare function selectImplementorPrompt(planFile: string, opts: ImplementorRunOptions, prompts?: ImplementorPromptSet): string;
+export declare class ImplementorAdapter extends BaseAdapter implements ImplementorDriver {
+    private readonly prompts?;
+    constructor(strategy: ProviderStrategy, workdir: string, prompts?: ImplementorPromptSet | undefined, yolo?: boolean);
+    run(planFile: string, opts?: ImplementorRunOptions): Promise<ImplementResult>;
+}
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/agents/implementors/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/agents/implementors/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAI3C,KAAK,qBAAqB,GAAG;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;CACxC,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,GAAE,oBAAgD,GACxD,MAAM,CAQR;AAED,qBAAa,kBAAmB,SAAQ,WAAY,YAAW,iBAAiB;IAI5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAFzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM,EACE,OAAO,CAAC,EAAE,oBAAoB,YAAA,EAC/C,IAAI,CAAC,EAAE,OAAO;IAKV,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,eAAe,CAAC;CAiB5B"}

package/dist/agents/implementors/adapter.js

@@ -0,0 +1,36 @@
+import { BaseAdapter } from "../runner.js";
+import { buildAgentWhipHint } from "../whip-hint.js";
+import { defaultImplementorPrompts } from "./prompts.js";
+export function selectImplementorPrompt(planFile, opts, prompts = defaultImplementorPrompts) {
+    if (opts.feedbackFile) {
+        if (opts.resumeSessionId) {
+            return prompts.resumeRevision(opts.feedbackFile);
+        }
+        return prompts.revision(planFile, opts.feedbackFile);
+    }
+    return prompts.initial(planFile);
+}
+export class ImplementorAdapter extends BaseAdapter {
+    prompts;
+    constructor(strategy, workdir, prompts, yolo) {
+        super(strategy, workdir, yolo);
+        this.prompts = prompts;
+    }
+    async run(planFile, opts = {}) {
+        const rawPrompt = selectImplementorPrompt(planFile, opts, this.prompts);
+        const hint = buildAgentWhipHint(this.strategy.name, opts, "implementation");
+        const prompt = this.applyWhipHint(hint, rawPrompt);
+        const result = await this.runAgent({
+            prompt,
+            workdir: this.workdir,
+            resumeSessionId: opts.resumeSessionId,
+            sessionFilePath: this.sessionFilePath,
+        });
+        return {
+            sessionId: result.sessionId,
+            rawText: result.responseText,
+            agentUsed: this.name,
+        };
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/agents/implementors/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/agents/implementors/adapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AASzD,MAAM,UAAU,uBAAuB,CACrC,QAAgB,EAChB,IAA2B,EAC3B,UAAgC,yBAAyB;IAEzD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,OAAO,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACnD,CAAC;QACD,OAAO,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IAI9B;IAHnB,YACE,QAA0B,EAC1B,OAAe,EACE,OAA8B,EAC/C,IAAc;QAEd,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QAHd,YAAO,GAAP,OAAO,CAAuB;IAIjD,CAAC;IAED,KAAK,CAAC,GAAG,CACP,QAAgB,EAChB,OAA8B,EAAE;QAEhC,MAAM,SAAS,GAAG,uBAAuB,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACxE,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;YACjC,MAAM;YACN,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC,CAAC;QAEH,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,MAAM,CAAC,YAAY;YAC5B,SAAS,EAAE,IAAI,CAAC,IAAI;SACrB,CAAC;IACJ,CAAC;CACF"}

package/dist/agents/implementors/dsl.d.ts

@@ -0,0 +1,11 @@
+import { type PhaseLabelSpec } from "../../flow/dsl.js";
+import type { AgentStep } from "../../flow/types.js";
+export declare function implement(opts: {
+    driver: string;
+    reads: Record<string, string>;
+    writes?: Record<string, string>;
+    id?: string;
+    feedbackToTask?: boolean;
+    phaseLabel?: PhaseLabelSpec;
+}): AgentStep;
+//# sourceMappingURL=dsl.d.ts.map

package/dist/agents/implementors/dsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl.d.ts","sourceRoot":"","sources":["../../../src/agents/implementors/dsl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B,GAAG,SAAS,CAMZ"}

package/dist/agents/implementors/dsl.js

@@ -0,0 +1,9 @@
+import { agentStep } from "../../flow/dsl.js";
+export function implement(opts) {
+    return agentStep("implementor", {
+        feedbackToTask: false,
+        idPrefix: "implement",
+        phaseLabel: "🔨 Implementing...",
+    }, opts);
+}
+//# sourceMappingURL=dsl.js.map

package/dist/agents/implementors/dsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsl.js","sourceRoot":"","sources":["../../../src/agents/implementors/dsl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAuB,MAAM,mBAAmB,CAAC;AAGnE,MAAM,UAAU,SAAS,CAAC,IAOzB;IACC,OAAO,SAAS,CAAC,aAAa,EAAE;QAC9B,cAAc,EAAE,KAAK;QACrB,QAAQ,EAAE,WAAW;QACrB,UAAU,EAAE,oBAAoB;KACjC,EAAE,IAAI,CAAC,CAAC;AACX,CAAC"}

package/dist/agents/implementors/handler.d.ts

@@ -0,0 +1,10 @@
+import type { ImplementorDriver } from "./types.js";
+import { type BaseStep, type StepContext, type StepSignal, type RetryFn, type RoleHandler } from "../../flow/types.js";
+export declare class ImplementorRoleHandler implements RoleHandler {
+    private driver;
+    /** Tracks the last execution mode per step ID for session invalidation. */
+    private lastModeByStep;
+    constructor(driver: ImplementorDriver);
+    execute(step: BaseStep, ctx: StepContext, retry: RetryFn): Promise<StepSignal>;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/agents/implementors/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/agents/implementors/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAE7B,qBAAa,sBAAuB,YAAW,WAAW;IAI5C,OAAO,CAAC,MAAM;IAH1B,2EAA2E;IAC3E,OAAO,CAAC,cAAc,CAA+C;gBAEjD,MAAM,EAAE,iBAAiB;IAEvC,OAAO,CACX,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;CAqDvB"}

package/dist/agents/implementors/handler.js

@@ -0,0 +1,55 @@
+import { resolveWhipNeighbors, } from "../../flow/types.js";
+export class ImplementorRoleHandler {
+    driver;
+    /** Tracks the last execution mode per step ID for session invalidation. */
+    lastModeByStep = new Map();
+    constructor(driver) {
+        this.driver = driver;
+    }
+    async execute(step, ctx, retry) {
+        // Check for revise-plan (pure plan follower mode)
+        const revisePlanFile = step.reads.revisePlan
+            ? ctx.artifacts.getFile(step.reads.revisePlan)
+            : undefined;
+        const currentMode = revisePlanFile ? "revise-plan" : "normal";
+        const lastMode = this.lastModeByStep.get(step.id);
+        let planFile;
+        let feedbackFile;
+        let resumeSessionId;
+        if (revisePlanFile) {
+            // Pure plan follower: revise-plan only, no verdict, fresh session.
+            planFile = revisePlanFile;
+            feedbackFile = undefined;
+            resumeSessionId = undefined;
+        }
+        else {
+            // Normal mode: original plan + verdict feedback
+            const basePlanFile = ctx.artifacts.getFile(step.reads.plan);
+            if (!basePlanFile)
+                throw new Error("ImplementorRoleHandler: plan artifact missing");
+            planFile = basePlanFile;
+            const verdictArtifact = step.reads.verdict
+                ? ctx.artifacts.get(step.reads.verdict) : undefined;
+            feedbackFile = verdictArtifact?.file;
+            // Resume only if previous invocation was also in normal mode (or first time).
+            resumeSessionId = (lastMode === undefined || lastMode === "normal")
+                ? ctx.sessionIds.get(step.id)
+                : undefined;
+        }
+        const { producers, consumers } = resolveWhipNeighbors(step, ctx);
+        const implResult = await retry("implementor", async (attempt) => {
+            return this.driver.run(planFile, {
+                resumeSessionId: attempt === 1 ? resumeSessionId : undefined,
+                feedbackFile: feedbackFile ?? undefined,
+                producers,
+                consumers,
+            });
+        });
+        this.lastModeByStep.set(step.id, currentMode);
+        if (implResult.sessionId) {
+            ctx.sessionIds.set(step.id, implResult.sessionId);
+        }
+        return { kind: "continue" };
+    }
+}
+//# sourceMappingURL=handler.js.map

package/dist/agents/implementors/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/agents/implementors/handler.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,GAMrB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,OAAO,sBAAsB;IAIb;IAHpB,2EAA2E;IACnE,cAAc,GAAG,IAAI,GAAG,EAAoC,CAAC;IAErE,YAAoB,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAEjD,KAAK,CAAC,OAAO,CACX,IAAc,EACd,GAAgB,EAChB,KAAc;QAEd,kDAAkD;QAClD,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU;YAC1C,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;YAC9C,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,WAAW,GACf,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAElD,IAAI,QAAgB,CAAC;QACrB,IAAI,YAAgC,CAAC;QACrC,IAAI,eAAmC,CAAC;QAExC,IAAI,cAAc,EAAE,CAAC;YACnB,mEAAmE;YACnE,QAAQ,GAAG,cAAc,CAAC;YAC1B,YAAY,GAAG,SAAS,CAAC;YACzB,eAAe,GAAG,SAAS,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,gDAAgD;YAChD,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5D,IAAI,CAAC,YAAY;gBAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;YACpF,QAAQ,GAAG,YAAY,CAAC;YACxB,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO;gBACxC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACtD,YAAY,GAAG,eAAe,EAAE,IAAI,CAAC;YAErC,8EAA8E;YAC9E,eAAe,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,QAAQ,CAAC;gBACjE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7B,CAAC,CAAC,SAAS,CAAC;QAChB,CAAC;QAED,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAEjE,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE;gBAC/B,eAAe,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS;gBAC5D,YAAY,EAAE,YAAY,IAAI,SAAS;gBACvC,SAAS;gBACT,SAAS;aACV,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;QAE9C,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YACzB,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/agents/implementors/index.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderStrategy } from "../../providers/types.js";
+import type { ImplementorDriver, ImplementorPromptSet } from "./types.js";
+import type { DriverName } from "../../flow/types.js";
+export { implement } from "./dsl.js";
+export { ImplementorRoleHandler } from "./handler.js";
+export type { ImplementorDriver, ImplementorPromptSet } from "./types.js";
+export type ImplementorFactory = (workdir: string, prompts?: ImplementorPromptSet) => ImplementorDriver;
+export declare const registerProvider: (name: DriverName, strategy: ProviderStrategy) => void;
+export declare const registerFactory: (name: string, factory: ImplementorFactory) => void, availableDrivers: () => string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/implementors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/implementors/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,iBAAiB,CAAC;AAexG,eAAO,MAAM,gBAAgB,EAA2B,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAC/G,eAAO,MAAQ,eAAe,uDAAE,gBAAgB,gBAAQ,CAAC"}

package/dist/agents/implementors/index.js

@@ -0,0 +1,21 @@
+import { ImplementorAdapter } from "./adapter.js";
+import { ImplementorRoleHandler } from "./handler.js";
+import { createRoleModule } from "../registry.js";
+import { minimalImplementorPrompts } from "./prompts.js";
+export { implement } from "./dsl.js";
+export { ImplementorRoleHandler } from "./handler.js";
+const mod = createRoleModule({
+    roleName: "implementor",
+    fromFactory: (factory, workdir, opts) => {
+        const prompts = opts?.opinionless ? minimalImplementorPrompts : undefined;
+        return factory(workdir, prompts);
+    },
+    fromProvider: (strategy, workdir, opts) => {
+        const prompts = opts?.opinionless ? minimalImplementorPrompts : undefined;
+        return new ImplementorAdapter(strategy, workdir, prompts, opts?.yolo);
+    },
+    toHandler: (driver) => new ImplementorRoleHandler(driver),
+});
+export const registerProvider = mod.registerProvider;
+export const { registerFactory, availableDrivers } = mod;
+//# sourceMappingURL=index.js.map

package/dist/agents/implementors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agents/implementors/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAoB,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAKtD,MAAM,GAAG,GAAG,gBAAgB,CAAwC;IAClE,QAAQ,EAAE,aAAa;IACvB,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QACtC,MAAM,OAAO,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1E,OAAO,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IACD,YAAY,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QACxC,MAAM,OAAO,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1E,OAAO,IAAI,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IACD,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,sBAAsB,CAAC,MAAM,CAAC;CAC1D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC,gBAA0E,CAAC;AAC/G,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,GAAG,GAAG,CAAC"}

package/dist/agents/implementors/prompts.d.ts

@@ -0,0 +1,20 @@
+import type { ImplementorPromptSet } from "./types.js";
+/**
+ * Build the initial implementor prompt.
+ */
+export declare function buildImplementorPrompt(planFile: string): string;
+/**
+ * Build the implementor revision prompt (when reviewer feedback was received).
+ */
+export declare function buildImplementorRevisionPrompt(planFile: string, feedbackFile: string): string;
+/**
+ * Build a lighter implementor revision prompt for resumed sessions.
+ * The agent already has task and plan context in-session.
+ */
+export declare function buildImplementorResumeRevisionPrompt(feedbackFile: string): string;
+export declare function buildMinimalImplementorPrompt(planFile: string): string;
+export declare function buildMinimalImplementorRevisionPrompt(planFile: string, feedbackFile: string): string;
+export declare function buildMinimalImplementorResumeRevisionPrompt(feedbackFile: string): string;
+export declare const defaultImplementorPrompts: ImplementorPromptSet;
+export declare const minimalImplementorPrompts: ImplementorPromptSet;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/agents/implementors/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/agents/implementors/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,MAAM,CASR;AAED;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,YAAY,EAAE,MAAM,GACnB,MAAM,CAOR;AAID,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED,wBAAgB,qCAAqC,CACnD,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,MAAM,CAOR;AAED,wBAAgB,2CAA2C,CACzD,YAAY,EAAE,MAAM,GACnB,MAAM,CAMR;AAID,eAAO,MAAM,yBAAyB,EAAE,oBAIvC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,oBAIvC,CAAC"}