orchestrator-workflow 0.3.0 → 0.4.0

package/README.md

@@ -13,23 +13,23 @@ evidence. Every unit of work leaves an auditable run directory behind.
 ## Why this shape
 
 ```text
-              Operator
-          goal |    ^ handoff: what changed, how verified,
-               v    | what remains open
-          Orchestrator  . . . . . . .  .ai/runs/<date>-<slug>/
-          session model                  00-goal       04-implementation-summary
-          plans, validates slices,       01-plan       05-review-findings
-          decides acceptance             02-tasks      06-handoff
-               |                         03-decisions
-    narrow     |     ^ structured        (state lives in files,
-    contracts  v     | YAML evidence      not in chat history)
-      +--------------+--------------+
-      |              |              |
-  task-slicer    implementer    reviewer
-    sonnet         sonnet         opus
-  small,         one narrow     skeptical, severity-rated
-  testable       task, plus     findings, no rewrites
-  slices         tests
+                 Operator
+             goal |    ^ handoff: what changed, how verified,
+                  v    | what remains open
+  explorer  -->  Orchestrator  . . . . .  .ai/runs/<date>-<slug>/
+  optional,      session model             00-goal       04-implementation-summary
+  read-only      plans, validates slices,  01-plan       05-review-findings
+  terrain map    decides acceptance        02-tasks      06-handoff
+                      |                     03-decisions
+     narrow           |    ^ structured     (state lives in files,
+     contracts        v    | YAML evidence   not in chat history)
+        +-------------+-------------+
+        |             |             |
+    task-slicer   implementer   reviewer
+      sonnet        sonnet        opus
+    small,        one narrow    skeptical, severity-rated
+    testable      task, plus    findings, no rewrites
+    slices        tests
 ```
 
 Two effects fall out of this shape:
@@ -40,7 +40,8 @@ Two effects fall out of this shape:
   in run files that survive context compaction. The cheap models do the
   volume work; the strongest model is spent only on orchestration decisions
   and the skeptical review. The ceremony scales to the task: a trivial change
-  is done directly, the full flow is for non-trivial work.
+  is done directly, the full flow is for non-trivial work, and a read-only
+  explorer maps the terrain first only when the solution is unclear.
 - **Quality through structure.** Writing and reviewing are separated by
   role and model, task slices are validated before any implementation
   starts, acceptance is decided on evidence (tests executed, findings
@@ -96,9 +97,9 @@ Per selected harness:
 
 | Harness | Files | Notes |
 |---|---|---|
-| Claude Code | `.claude/skills/orchestrator-workflow/SKILL.md`, `.claude/agents/{task-slicer,implementer,reviewer}.md`, `CLAUDE.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; the installer adds an additive `@AGENTS.md` import. Subagent models go into the `model:` frontmatter. |
+| Claude Code | `.claude/skills/orchestrator-workflow/SKILL.md`, `.claude/agents/{explorer,task-slicer,implementer,reviewer}.md`, `CLAUDE.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; the installer adds an additive `@AGENTS.md` import. Subagent models go into the `model:` frontmatter; the read-only explorer also gets `disallowedTools: Edit, Write, NotebookEdit`. |
 | OpenAI Codex | `.agents/skills/orchestrator-workflow/SKILL.md` | Codex reads `AGENTS.md` natively. There is no standardized project-level subagent definition; the skill instructs running the roles inline with the same contracts. |
-| opencode | `.opencode/agents/{task-slicer,implementer,reviewer}.md` | opencode reads `AGENTS.md` natively and cross-discovers `.claude/skills/`. Subagents get `mode: subagent` plus a fully qualified `provider/model-id`. |
+| opencode | `.opencode/agents/{explorer,task-slicer,implementer,reviewer}.md` | opencode reads `AGENTS.md` natively and cross-discovers `.claude/skills/`. Subagents get `mode: subagent` plus a fully qualified `provider/model-id`; the explorer also gets `permission: edit: deny`. |
 
 ## Model preselection
 

package/assets/agents/explorer.md

@@ -0,0 +1,54 @@
+---
+name: explorer
+description: "Read-only discovery: maps the relevant terrain of a codebase before planning. Finds what exists, how it connects, and which solution options are viable. Does not write code or change files."
+---
+
+You are the discovery subagent of an orchestrator-led workflow.
+
+The orchestrator sends you when the goal or the solution is still unclear, or
+when the codebase is unfamiliar. Your job is to make the terrain visible so the
+orchestrator can plan with facts instead of guesses. You are read-only: you
+read, search, and trace, but you never write code or change files.
+
+Rules:
+
+- Investigate only what is relevant to the stated goal. Do not survey the whole
+  repository; follow the question.
+- Report what you actually found, with `file:line` references. Distinguish
+  verified facts from inference, and never present a guess as a fact.
+- Surface the constraints and conventions a plan must respect (existing
+  patterns, public interfaces, tests, build and CI steps, risky areas).
+- Lay out the viable solution options you can see, with the trade-off that
+  decides between them. Do not pick one and start implementing.
+- If a question can only be answered by the operator (product intent, an
+  external system, a decision), put it under open questions rather than
+  guessing.
+- Do not spawn further subagents and do not implement anything. Return your
+  findings to the orchestrator and let it decide.
+
+Return exactly this structure as your final output, nothing else:
+
+```yaml
+status: done | partial | blocked
+role: explorer
+summary:
+  - ""
+relevant_terrain:
+  - path: ""
+    role: ""
+    notes: ""
+how_it_connects:
+  - ""
+constraints_and_conventions:
+  - ""
+solution_options:
+  - option: ""
+    pros:
+      - ""
+    cons:
+      - ""
+    risk: low | medium | high
+open_questions:
+  - ""
+recommendation: ""
+```

package/assets/agents-md-section.md

@@ -13,6 +13,9 @@ and the subagent I/O contracts live in the `orchestrator-workflow` skill.
 
 - Only the orchestrator spawns or coordinates subagents. Subagents never spawn
   further subagents.
+- When the goal, the solution, or the terrain is unclear, the orchestrator may
+  send a read-only explorer subagent to map the terrain before planning. The
+  explorer reads and reports; it never changes files.
 - The orchestrator plans features itself. It may delegate task slicing, but it
   validates the sliced tasks before implementation starts.
 - Non-trivial implementation goes to narrow implementer subagents, one task
@@ -29,7 +32,10 @@ The orchestrator matches the ceremony to the task; the full flow is a
 default, not a ritual.
 
 - A trivial change (a typo, a one-line fix, a rename) may be implemented by
-  the orchestrator directly, without slicing or an implementer subagent.
+  the orchestrator directly, without discovery, slicing, or an implementer
+  subagent.
+- Discovery (the read-only explorer) is for unfamiliar terrain or an unclear
+  solution; skip it when the change is well understood.
 - Slicing and implementer subagents are for non-trivial work: multiple files,
   real logic, or anything that benefits from decomposition or a fresh context.
 - Review judgment applies to every change. For a trivial change the

package/assets/skill/SKILL.md

@@ -29,6 +29,10 @@ the apparatus changes.
   validates task slices, assigns implementation and review, decides acceptance,
   reports back. The orchestrator must not become a passive transcript
   collector; it maintains compact run state.
+- **Explorer** (optional, read-only): maps the relevant terrain before
+  planning when the goal or solution is unclear or the codebase is unfamiliar.
+  Reports what exists, how it connects, the constraints to respect, and the
+  viable options. Never writes code.
 - **Task slicer** (optional): breaks a large change into small, testable tasks
   with dependencies and risk markers.
 - **Implementer**: implements exactly one narrow task, touches only relevant
@@ -37,8 +41,8 @@ the apparatus changes.
   tests, security, and edge cases. Classifies severity, recommends fixes,
   avoids unsolicited rewrites.
 
-Where the harness supports subagent definitions, the slicer, implementer, and
-reviewer roles are installed as named subagents (Claude Code:
+Where the harness supports subagent definitions, the explorer, slicer,
+implementer, and reviewer roles are installed as named subagents (Claude Code:
 `.claude/agents/`, opencode: `.opencode/agents/`) with preselected models.
 Spawn those instead of improvising role prompts. Extended role prompts live in
 the [agentic-coding-playbook skills](https://github.com/LanNguyenSi/agent-dx/tree/master/packages/agentic-coding-playbook/skills).
@@ -71,31 +75,63 @@ directory and the subagents.
 1. **Understand the goal.** Create the run directory and fill `00-goal.md`:
    operator request, goal, non-goals, constraints, assumptions, open questions.
    If the task can proceed on reasonable assumptions, proceed without blocking.
-2. **Plan.** Fill `01-plan.md`: approach, affected areas, risks, test strategy,
+2. **Discover (optional, read-only).** When the goal, the solution, or the
+   terrain is unclear, send the explorer subagent before planning. Fold its
+   findings into a "Terrain" section of `01-plan.md`. Skip this step when the
+   change is well understood. If the explorer surfaces a question only the
+   operator can answer, ask the operator instead of guessing.
+3. **Plan.** Fill `01-plan.md`: approach, affected areas, risks, test strategy,
    rollback considerations where relevant.
-3. **Slice tasks.** For non-trivial changes, fill `02-tasks.md`. Delegate to
+4. **Slice tasks.** For non-trivial changes, fill `02-tasks.md`. Delegate to
    the task-slicer subagent when the change is large enough to benefit. Each
    task carries: id, goal, relevant files, acceptance criteria, constraints,
    suggested tests, dependencies, risk.
-4. **Validate tasks.** Check the slices are independently understandable, small
+5. **Validate tasks.** Check the slices are independently understandable, small
    enough, testable, ordered correctly, and aligned with the goal. Fix the
    slicing before any implementation starts.
-5. **Delegate implementation.** Send each implementer subagent one narrow task
+6. **Delegate implementation.** Send each implementer subagent one narrow task
    contract (format below). Record meaningful decisions in `03-decisions.md`
    and consolidate evidence in `04-implementation-summary.md`.
-6. **Delegate review.** Send the diff to the reviewer subagent. The reviewer
+7. **Delegate review.** Send the diff to the reviewer subagent. The reviewer
    checks spec compliance, architecture consistency, edge cases, security,
    test adequacy (including whether new tests would fail if the change were
    reverted), and maintainability. Findings go to `05-review-findings.md`.
-7. **Decide acceptance.** Accept, request fixes, defer a known issue, or
+8. **Decide acceptance.** Accept, request fixes, defer a known issue, or
    escalate to the operator. Record the decision in `03-decisions.md`.
-8. **Hand off.** Fill `06-handoff.md` and report to the operator: what changed,
+9. **Hand off.** Fill `06-handoff.md` and report to the operator: what changed,
    why, how it was verified, known risks, suggested next step.
 
+## Explorer output contract
+
+```yaml
+status: done | partial | blocked
+role: explorer
+summary:
+  - ""
+relevant_terrain:
+  - path: ""
+    role: ""
+    notes: ""
+how_it_connects:
+  - ""
+constraints_and_conventions:
+  - ""
+solution_options:
+  - option: ""
+    pros:
+      - ""
+    cons:
+      - ""
+    risk: low | medium | high
+open_questions:
+  - ""
+recommendation: ""
+```
+
 ## Subagent input contract
 
 ```yaml
-role: implementer | reviewer | task_slicer
+role: explorer | implementer | reviewer | task_slicer
 task_id: T-000
 goal: ""
 context:
@@ -194,7 +230,8 @@ open_questions:
 ## Harness notes
 
 - **Claude Code**: spawn the installed `.claude/agents/` subagents
-  (task-slicer, implementer, reviewer) via the native subagent mechanism.
+  (explorer, task-slicer, implementer, reviewer) via the native subagent
+  mechanism.
 - **opencode**: invoke the installed `.opencode/agents/` subagents
   (`mode: subagent`).
 - **OpenAI Codex**: there is no standardized project-level subagent definition

package/assets/templates/01-plan.md

@@ -4,6 +4,11 @@
 
 <!-- Short summary of the intended approach. -->
 
+## Terrain
+
+<!-- Optional. Discovery findings from the explorer subagent: what exists,
+how it connects, constraints to respect. Omit when no discovery was needed. -->
+
 ## Affected Areas
 
 - <!-- area/file/module -->

package/dist/init.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, normalize, sep } from "node:path";
 import { PACKAGE_VERSION, listTemplateNames, readAgentAsset, readAsset, } from "./assets.js";
 import { HARNESSES } from "./detect.js";
-import { ROLES, assertValidModelId, claudeModelValue, opencodeModelValue, } from "./models.js";
+import { READ_ONLY_ROLES, ROLES, assertValidModelId, claudeModelValue, opencodeModelValue, } from "./models.js";
 import { emptyReport, ensureClaudeImport, installFile, upsertMarkerSection, } from "./writers.js";
 const SKILL_NAME = "orchestrator-workflow";
 const MANIFEST_PATH = join(".ai", "workflow", "manifest.json");
@@ -84,29 +84,32 @@ function yamlQuote(value) {
 }
 function composeClaudeAgent(role, model) {
     const asset = readAgentAsset(role);
-    return [
+    const frontmatter = [
         "---",
         `name: ${asset.name}`,
         `description: ${yamlQuote(asset.description)}`,
         `model: ${claudeModelValue(model)}`,
-        "---",
-        "",
-        asset.body.trimEnd(),
-        "",
-    ].join("\n");
+    ];
+    // Read-only roles keep every read/search tool but cannot mutate files.
+    if (READ_ONLY_ROLES.has(role)) {
+        frontmatter.push("disallowedTools: Edit, Write, NotebookEdit");
+    }
+    frontmatter.push("---");
+    return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
 }
 function composeOpencodeAgent(role, model) {
     const asset = readAgentAsset(role);
-    return [
+    const frontmatter = [
         "---",
         `description: ${yamlQuote(asset.description)}`,
         "mode: subagent",
         `model: ${opencodeModelValue(model)}`,
-        "---",
-        "",
-        asset.body.trimEnd(),
-        "",
-    ].join("\n");
+    ];
+    if (READ_ONLY_ROLES.has(role)) {
+        frontmatter.push("permission:", "  edit: deny");
+    }
+    frontmatter.push("---");
+    return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
 }
 export function runInit(options) {
     const { targetDir } = options;

package/dist/models.d.ts

@@ -1,5 +1,10 @@
-export type Role = "task-slicer" | "implementer" | "reviewer";
+export type Role = "explorer" | "task-slicer" | "implementer" | "reviewer";
 export declare const ROLES: Role[];
+/**
+ * Roles that map the terrain or judge work without changing it. They are
+ * installed with a read-only posture (no file-mutation tools).
+ */
+export declare const READ_ONLY_ROLES: ReadonlySet<Role>;
 export type ModelAlias = "sonnet" | "opus" | "haiku";
 export declare const MODEL_ALIASES: ModelAlias[];
 /**

package/dist/models.js

@@ -1,10 +1,21 @@
-export const ROLES = ["task-slicer", "implementer", "reviewer"];
+export const ROLES = [
+    "explorer",
+    "task-slicer",
+    "implementer",
+    "reviewer",
+];
+/**
+ * Roles that map the terrain or judge work without changing it. They are
+ * installed with a read-only posture (no file-mutation tools).
+ */
+export const READ_ONLY_ROLES = new Set(["explorer"]);
 export const MODEL_ALIASES = ["sonnet", "opus", "haiku"];
 /**
  * Per-role defaults. The orchestrator itself runs on the session model and is
  * deliberately not configured here.
  */
 export const DEFAULT_MODELS = {
+    explorer: "sonnet",
     "task-slicer": "sonnet",
     implementer: "sonnet",
     reviewer: "opus",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Installer for an orchestrator-led agent workflow: .ai/ run state, an AGENTS.md policy section, and per-harness subagent definitions for Claude Code, OpenAI Codex, and opencode",
   "main": "dist/index.js",
   "type": "module",