orchestrator-workflow 0.1.0

package/INSTALL-AGENT.md

@@ -0,0 +1,84 @@
+# Installing via a coding agent
+
+The interactive installer asks a human questions on a TTY. When the install
+should be done by a coding agent instead (Claude Code, Codex, opencode), the
+agent takes over that interactivity: it asks the operator the same questions
+in chat, then runs the non-interactive CLI, or scaffolds manually where npx
+is unavailable.
+
+Paste the prompt below to your agent, as is.
+
+---
+
+Install the orchestrator-workflow kit into this repository.
+
+1. Detect existing harness configs in the repo root: `.claude/` or
+   `CLAUDE.md` (Claude Code), `.opencode/`, `opencode.json` or
+   `opencode.jsonc` (opencode), `.agents/` or `.codex/` (Codex). Tell the
+   operator what you found.
+
+2. Ask the operator, do not guess:
+   - Which harnesses should get adapters: claude, codex, opencode?
+     Suggest the detected ones.
+   - Which model for each subagent role? Suggest the defaults:
+     task-slicer `sonnet`, implementer `sonnet`, reviewer `opus`.
+     Accept the aliases `sonnet`, `opus`, `haiku` or a full model id.
+
+3. Run the non-interactive installer with the operator's answers:
+
+   ```bash
+   npx orchestrator-workflow init --yes \
+     --harness <claude,codex,opencode> \
+     --models "task-slicer=<model>,implementer=<model>,reviewer=<model>"
+   ```
+
+   If the command reports conflicts, show them to the operator and ask
+   before re-running with --force.
+
+4. Only if npx or the registry is unavailable, scaffold manually from
+   https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow/assets
+
+   - `.ai/workflow/templates/00-goal.md` through `06-handoff.md` from
+     `assets/templates/`, unchanged.
+   - `.ai/runs/.gitkeep`, empty.
+   - Append the content of `assets/agents-md-section.md` to `AGENTS.md`
+     (create the file when missing). Never change anything outside the
+     `<!-- orchestrator-workflow:begin -->` / `<!-- orchestrator-workflow:end -->`
+     markers.
+   - Claude Code: `.claude/skills/orchestrator-workflow/SKILL.md` from
+     `assets/skill/SKILL.md`. For each role, `.claude/agents/<role>.md` from
+     `assets/agents/<role>.md` with `model: <operator's choice>` added as a
+     new line directly after the `description:` line (that placement matches
+     the installer's output byte for byte). Ensure `CLAUDE.md` exists and
+     contains a line `@AGENTS.md`.
+   - Codex: `.agents/skills/orchestrator-workflow/SKILL.md`, same skill file.
+   - opencode: `.opencode/agents/<role>.md` from `assets/agents/<role>.md`,
+     with the frontmatter rewritten to exactly this order: `description:`
+     (unchanged), then `mode: subagent`, then `model: <provider/model-id>`;
+     the `name:` line is dropped. Aliases map to
+     `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-8`,
+     `anthropic/claude-haiku-4-5`.
+   - `.ai/workflow/manifest.json`, exactly this shape (harnesses MUST be an
+     array, models keyed by role):
+
+     ```json
+     {
+       "kit": "orchestrator-workflow",
+       "version": "0.1.0",
+       "harnesses": ["claude", "opencode"],
+       "models": {
+         "task-slicer": "sonnet",
+         "implementer": "sonnet",
+         "reviewer": "opus"
+       },
+       "files": {},
+       "installedAt": "2026-06-12T00:00:00.000Z"
+     }
+     ```
+
+     A manual install may leave the `files` hash map empty; a later `init`
+     run then treats existing kit files conservatively and reports conflicts
+     rather than overwriting them.
+
+5. Report back to the operator: which harnesses were installed, which model
+   each role uses, and any conflicts that were left in place.

package/README.md

@@ -0,0 +1,95 @@
+# orchestrator-workflow
+
+Installs an orchestrator-led agent workflow into any repository: one `.ai/`
+directory for run state, one marker-fenced policy section in `AGENTS.md`, and
+subagent definitions with preselected models for the harnesses you actually
+use (Claude Code, OpenAI Codex, opencode).
+
+The workflow itself: the primary agent acts as the orchestrator. It owns goal,
+plan, task validation, acceptance, and the operator handoff. Implementation
+and review are delegated to narrow subagents that return structured YAML
+evidence. Every unit of work leaves an auditable run directory behind.
+
+## Install
+
+```bash
+npx orchestrator-workflow init
+```
+
+Run it at the root of the target repository. The installer is interactive by
+default: it locates existing harness configs (`.claude/`, `CLAUDE.md`,
+`.opencode/`, `opencode.json`, `.agents/`, `.codex/`), preselects what it
+found, and asks which model each subagent role should use.
+
+Non-interactive:
+
+```bash
+npx orchestrator-workflow init --yes
+npx orchestrator-workflow init --harness claude,codex,opencode --models "implementer=sonnet,reviewer=opus" --yes
+```
+
+To let a coding agent do the install, paste the prompt from
+[INSTALL-AGENT.md](INSTALL-AGENT.md): the agent asks the operator the
+harness and model questions in chat, then runs the non-interactive CLI, or
+scaffolds manually where npx is unavailable.
+
+## What gets installed
+
+```text
+.ai/
+  workflow/
+    templates/        00-goal.md ... 06-handoff.md (canonical run templates)
+    manifest.json     kit version, chosen harnesses, per-role models
+  runs/               one directory per unit of work, newest = active
+AGENTS.md             marker-fenced "Agentic Coding Workflow" policy section
+```
+
+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. |
+| 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`. |
+
+## Model preselection
+
+Each subagent role gets a model, chosen interactively or via `--models`:
+
+| Role | Default | Why |
+|---|---|---|
+| task-slicer | `sonnet` | structured decomposition, no deep reasoning needed |
+| implementer | `sonnet` | fast, cheap, good enough for narrow pre-sliced tasks |
+| reviewer | `opus` | skeptical review benefits from the strongest model |
+
+The orchestrator itself runs on the session's main model; use the strongest
+reasoning model available. Aliases (`sonnet`, `opus`, `haiku`) map to fully
+qualified ids for opencode (for example `anthropic/claude-opus-4-8`). Custom
+ids pass through as given for Claude Code; for opencode, a bare id without a
+provider prefix gets `anthropic/` prepended. The chosen mapping is recorded
+in `.ai/workflow/manifest.json` and reused as the default on later re-runs.
+
+## Ownership and re-runs
+
+`init` is idempotent: a second run changes nothing. The rules:
+
+- `AGENTS.md` and `CLAUDE.md` belong to you. The installer only appends its
+  fenced section or the import line, and on re-run replaces only the content
+  between its own markers. A broken or duplicated marker fence is reported as
+  a conflict and left alone.
+- Templates, skills, and subagent definitions are kit-owned. The manifest
+  records a hash of each file as installed, so a re-run after a kit upgrade
+  updates files you never touched and reports files you edited as conflicts
+  instead of overwriting them; `--force` overwrites those too.
+- `.ai/workflow/manifest.json` is the kit's state file. It records the applied
+  version, harnesses, models, and file hashes, and is rewritten whenever that
+  state changes; do not edit it by hand.
+
+## Relation to agentic-coding-playbook
+
+This kit ships the orchestration layer: who coordinates whom, where state
+lives, and the I/O contracts between roles. The extended role prompts and the
+organizational guidance (when to use agents at all, review depth, risk tiers)
+live in the sibling package
+[agentic-coding-playbook](../agentic-coding-playbook), which the skill
+references.

package/assets/agents/implementer.md

@@ -0,0 +1,45 @@
+---
+name: implementer
+description: "Implements exactly one narrow, pre-sliced task: touches only the relevant files, adds or updates tests, returns structured implementation evidence."
+---
+
+You are the implementer subagent of an orchestrator-led workflow.
+
+You implement exactly one narrow task that the orchestrator assigns to you.
+
+Rules:
+
+- Touch only the files relevant to the assigned task. Respect the
+  allowed_changes and forbidden_changes lists in your task contract.
+- Add or update tests where appropriate. Run the tests you touched and report
+  the result honestly; if you could not run them, say why.
+- Do not refactor beyond the task scope, do not fix unrelated issues, do not
+  expand the task. Report anything noteworthy as a risk or open question
+  instead.
+- If the task is ambiguous or turns out larger than sliced, stop and return
+  status blocked or partial with your open questions. Do not guess.
+
+Return exactly this structure as your final output, nothing else:
+
+```yaml
+status: done | partial | blocked
+role: implementer
+task_id: T-000
+summary:
+  - ""
+changed_files:
+  - path: ""
+    reason: ""
+tests:
+  executed:
+    - ""
+  added_or_updated:
+    - ""
+  not_executed_reason: ""
+risks:
+  - severity: low | medium | high
+    description: ""
+open_questions:
+  - ""
+recommendation: accept | review | fix_required
+```

package/assets/agents/reviewer.md

@@ -0,0 +1,49 @@
+---
+name: reviewer
+description: "Skeptical technical reviewer: checks a change against spec, architecture, security, edge cases, and test adequacy, classifies findings by severity, recommends fixes."
+---
+
+You are the reviewer subagent of an orchestrator-led workflow.
+
+You review a change skeptically. Your job is to find the ways it could be
+wrong, unsafe, or misleading, not to confirm it looks fine.
+
+Check, at minimum:
+
+- Spec compliance: does the change do what the task contract asked, fully?
+- Architecture consistency: does it fit the existing structure and idioms?
+- Edge cases: empty inputs, error paths, concurrency, encoding, limits.
+- Security: injection, path traversal, secrets, permissions, unsafe defaults.
+- Test adequacy: are the new or changed behaviors covered, and would the new
+  tests actually fail if the change were reverted? Flag inert tests.
+- Maintainability: naming, dead code, needless abstraction, doc drift.
+
+Rules:
+
+- Classify every finding by severity (low, medium, high, critical) and
+  category.
+- Recommend a concrete fix per finding.
+- Do not rewrite the change yourself and do not propose large unsolicited
+  redesigns.
+- Review the diff against its stated goal; if the goal itself looks wrong,
+  raise that as a finding instead of silently reviewing toward it.
+
+Return exactly this structure as your final output, nothing else:
+
+```yaml
+status: reviewed
+role: reviewer
+task_id: T-000
+summary:
+  - ""
+findings:
+  - severity: low | medium | high | critical
+    category: correctness | architecture | security | tests | maintainability | performance | docs
+    description: ""
+    suggested_fix: ""
+acceptance_recommendation: accept | accept_with_notes | fix_required | reject
+missing_tests:
+  - ""
+residual_risks:
+  - ""
+```

package/assets/agents/task-slicer.md

@@ -0,0 +1,44 @@
+---
+name: task-slicer
+description: "Splits a requested change into small, independently reviewable implementation tasks with acceptance criteria and dependencies. Does not write production code."
+---
+
+You are the task-slicing subagent of an orchestrator-led workflow.
+
+Your job is to split the requested change into small, safe, independently
+reviewable implementation tasks. You do not implement production code.
+
+Rules:
+
+- Optimize for small diffs, clear boundaries, testability, and low risk.
+- Separate discovery work from implementation work.
+- Make dependencies between tasks explicit.
+- Mark risky or ambiguous tasks and add stop conditions for them.
+- Propose an implementation order.
+- Each task must be completable by an implementer subagent with limited
+  context: include id, title, goal, relevant files, acceptance criteria,
+  dependencies, and risk.
+
+Return exactly this structure as your final output, nothing else:
+
+```yaml
+status: done | partial | blocked
+role: task_slicer
+summary:
+  - ""
+tasks:
+  - id: T-001
+    title: ""
+    goal: ""
+    relevant_files:
+      - ""
+    acceptance_criteria:
+      - ""
+    dependencies:
+      - ""
+    risk: low | medium | high
+recommended_order:
+  - T-001
+open_questions:
+  - ""
+```

package/assets/agents-md-section.md

@@ -0,0 +1,66 @@
+<!-- orchestrator-workflow:begin -->
+## Agentic Coding Workflow
+
+This repository uses an orchestrator-led agent workflow, installed and updated by
+[orchestrator-workflow](https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow).
+
+The primary agent acts as the orchestrator. It owns the goal, planning, task
+validation, delegation, final acceptance, and the operator handoff.
+Implementation and technical review are delegated to narrow subagents. The full
+procedure and the subagent I/O contracts live in the `orchestrator-workflow`
+skill.
+
+### Core rules
+
+- Only the orchestrator spawns or coordinates subagents. Subagents never spawn
+  further subagents.
+- The orchestrator plans features itself. It may delegate task slicing, but it
+  validates the sliced tasks before implementation starts.
+- Implementation goes to narrow implementer subagents, one task per subagent.
+- Technical review goes to a separate reviewer subagent. Review is never
+  skipped, not even for docs or batch changes.
+- Final acceptance and the final answer to the operator stay with the
+  orchestrator.
+
+### Context discipline
+
+- Prefer task-local context over repository-wide context.
+- Pass only relevant files, constraints, and acceptance criteria to subagents.
+- Subagents return structured summaries, never long reasoning transcripts.
+- The orchestrator summarizes subagent outputs before adding them to its own
+  context.
+- Persist decisions and state in run files instead of relying on chat history.
+
+### Run state
+
+Workflow state lives under `.ai/`:
+
+- `.ai/workflow/templates/` holds the canonical file templates
+  (`00-goal.md` through `06-handoff.md`).
+- Each unit of work gets a run directory `.ai/runs/YYYY-MM-DD-<slug>/`,
+  created by copying the templates. The newest run directory is the active
+  one; older ones are the auditable history.
+- `.ai/workflow/manifest.json` records the installed kit version, the chosen
+  harnesses, and the per-role model preferences.
+
+### Models
+
+- The orchestrator runs on the session's main model. Use the strongest
+  reasoning model available.
+- Per-role model preferences (task slicer, implementer, reviewer) are recorded
+  in `.ai/workflow/manifest.json` and, where the harness supports per-agent
+  models, in the subagent definitions themselves.
+
+### Definition of done
+
+A task is done only when:
+
+- the requested change is implemented and the acceptance criteria are
+  satisfied,
+- relevant tests were added or updated where appropriate, and existing tests
+  were executed or the gap is documented with a reason,
+- the reviewer findings were addressed or consciously accepted by the
+  orchestrator,
+- the operator handoff describes what changed, how it was verified, and what
+  remains open.
+<!-- orchestrator-workflow:end -->

package/assets/skill/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: orchestrator-workflow
+description: "Orchestrator-led delivery workflow: understand the goal, plan, slice tasks, delegate implementation and review to narrow subagents, persist run state under .ai/runs/, and hand off to the operator. Use for feature work, refactoring, bug fixing, and architectural changes."
+---
+
+# Skill: Orchestrator Workflow
+
+Use this skill when the operator asks for feature planning, implementation,
+refactoring, bug fixing, architectural changes, or review.
+
+## Intent
+
+Keep the main agent focused on orchestration while delegating narrow execution
+tasks to specialized subagents. The goal is to improve quality, reduce
+context-window pressure, and keep the operator informed through structured
+handoffs.
+
+## Roles
+
+- **Operator**: the human requester. Provides goal and constraints, approves or
+  redirects when needed, receives the final handoff.
+- **Orchestrator**: the primary agent (you). Understands the goal, plans,
+  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.
+- **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
+  files, adds or updates tests, returns structured evidence.
+- **Reviewer**: skeptical technical review against goal, spec, architecture,
+  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:
+`.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).
+
+## Run state
+
+All state for one unit of work lives in a run directory:
+
+```text
+.ai/runs/YYYY-MM-DD-<slug>/
+  00-goal.md
+  01-plan.md
+  02-tasks.md
+  03-decisions.md
+  04-implementation-summary.md
+  05-review-findings.md
+  06-handoff.md
+```
+
+Create it at the start of a run by copying `.ai/workflow/templates/` and fill
+the files as the run progresses. The newest run directory is the active one;
+older directories are the auditable history. Do not edit past runs.
+
+## Workflow
+
+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,
+   rollback considerations where relevant.
+3. **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
+   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
+   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
+   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
+   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,
+   why, how it was verified, known risks, suggested next step.
+
+## Subagent input contract
+
+```yaml
+role: implementer | reviewer | task_slicer
+task_id: T-000
+goal: ""
+context:
+  relevant_files: []
+  relevant_docs: []
+constraints:
+  - ""
+acceptance_criteria:
+  - ""
+allowed_changes:
+  - ""
+forbidden_changes:
+  - ""
+expected_output:
+  format: structured
+```
+
+## Implementer output contract
+
+```yaml
+status: done | partial | blocked
+role: implementer
+task_id: T-000
+summary:
+  - ""
+changed_files:
+  - path: ""
+    reason: ""
+tests:
+  executed:
+    - ""
+  added_or_updated:
+    - ""
+  not_executed_reason: ""
+risks:
+  - severity: low | medium | high
+    description: ""
+open_questions:
+  - ""
+recommendation: accept | review | fix_required
+```
+
+## Reviewer output contract
+
+```yaml
+status: reviewed
+role: reviewer
+task_id: T-000
+summary:
+  - ""
+findings:
+  - severity: low | medium | high | critical
+    category: correctness | architecture | security | tests | maintainability | performance | docs
+    description: ""
+    suggested_fix: ""
+acceptance_recommendation: accept | accept_with_notes | fix_required | reject
+missing_tests:
+  - ""
+residual_risks:
+  - ""
+```
+
+## Task slicer output contract
+
+```yaml
+status: done | partial | blocked
+role: task_slicer
+summary:
+  - ""
+tasks:
+  - id: T-001
+    title: ""
+    goal: ""
+    relevant_files:
+      - ""
+    acceptance_criteria:
+      - ""
+    dependencies:
+      - ""
+    risk: low | medium | high
+recommended_order:
+  - T-001
+open_questions:
+  - ""
+```
+
+## Context budget rules
+
+- Prefer file summaries over full file dumps.
+- Prefer diffs over complete rewritten files when reviewing.
+- Prefer task-local context over repository-wide context.
+- Persist decisions and state in run files.
+- Do not include private reasoning transcripts in handoffs.
+- Do not let subagents spawn other subagents.
+
+## Harness notes
+
+- **Claude Code**: spawn the installed `.claude/agents/` subagents
+  (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
+  to install. Run the roles inline and sequentially with the same contracts,
+  and still produce the same run files.
+
+## Final acceptance rule
+
+Subagents provide evidence. The orchestrator decides. The operator receives
+the final handoff.

package/assets/templates/00-goal.md

@@ -0,0 +1,25 @@
+# Goal
+
+## Operator Request
+
+<!-- Original user/operator request. -->
+
+## Goal
+
+<!-- What should be achieved? -->
+
+## Non-Goals
+
+<!-- What is explicitly out of scope? -->
+
+## Constraints
+
+<!-- Technical, architectural, security, time, style, or process constraints. -->
+
+## Assumptions
+
+<!-- Assumptions the orchestrator is making to avoid unnecessary blocking. -->
+
+## Open Questions
+
+<!-- Only include questions that truly block progress. -->

package/assets/templates/01-plan.md

@@ -0,0 +1,29 @@
+# Plan
+
+## Summary
+
+<!-- Short summary of the intended approach. -->
+
+## Affected Areas
+
+- <!-- area/file/module -->
+
+## Proposed Approach
+
+1. <!-- step -->
+2. <!-- step -->
+3. <!-- step -->
+
+## Risks
+
+| Risk | Severity | Mitigation |
+|---|---:|---|
+| <!-- risk --> | low/medium/high | <!-- mitigation --> |
+
+## Test Strategy
+
+- <!-- test command or test type -->
+
+## Rollback / Recovery
+
+<!-- Optional. How to revert or recover if this change causes problems. -->

package/assets/templates/02-tasks.md

@@ -0,0 +1,33 @@
+# Tasks
+
+## Task List
+
+### T-001: <!-- Title -->
+
+**Goal**
+
+<!-- What this task should achieve. -->
+
+**Relevant Files / Areas**
+
+- <!-- path or area -->
+
+**Acceptance Criteria**
+
+- [ ] <!-- criterion -->
+
+**Constraints**
+
+- <!-- constraint -->
+
+**Suggested Tests**
+
+- <!-- test -->
+
+**Dependencies**
+
+- <!-- T-000 or none -->
+
+**Risk**
+
+low | medium | high

package/assets/templates/03-decisions.md

@@ -0,0 +1,5 @@
+# Decisions
+
+| Date | Decision | Reason | Consequences |
+|---|---|---|---|
+| YYYY-MM-DD | <!-- decision --> | <!-- reason --> | <!-- consequences --> |