@crafts69guy/orchestra 0.0.0-stage → 0.4.0

package/skills/dispatch/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: dispatch
+description: "orch workflow: run independent substantial tasks from .scratch/<feature>/plan.md in parallel, one implementer per git worktree (worktrunk), then merge them into the feature branch one at a time."
+---
+
+# Dispatch
+
+Run the plan in waves. Harness-specific spawn syntax:
+[Claude Code](references/claude.md) · [Codex](references/codex.md).
+
+`orch` is the CLI shipped with this plugin; the session context names its
+absolute path. Use that path where the plugin's `bin/` is not on `PATH` (Codex).
+`orch wt` wraps worktrunk (`wt`) and prints JSON.
+
+## Preconditions
+
+- You are on the feature branch `F` named in the plan, with a clean tree.
+- `wt` is installed. If the repo has worktrunk project hooks
+  (`.config/wt.toml`) and the user has not said the repo is trusted, ask once
+  before passing `--yes`: it runs the repo's hook commands.
+
+## Each wave
+
+1. **Pick** the ready `substantial` tasks: all `depends_on` merged, `files`
+   disjoint. At most 4 per wave; queue the rest. `small` tasks are never
+   dispatched: run them as one batched implementer task on `F`, before any wave
+   that depends on them.
+2. **Create** worktrees: `orch wt new <F> <T1> <T2> …` → JSON list of
+   `{task, branch, path}`.
+3. **Spawn** one implementer per task, all in the **same message** so they run
+   in parallel. Brief each with: plan path + task id, its worktree `path`
+   (work only there), the plan's Decisions, `validate`, and "do not commit".
+4. **Wait** for all reports. `partial`/`blocked` → answer and resume that agent
+   (max 2 rounds), or re-plan.
+5. **Review** each diff (`git -C <path> diff`). Send defects back to the same
+   agent.
+6. **Merge one task at a time:**
+   `orch wt merge <F> <T> --message "<conventional commit message>"`.
+   The message is the full commit message: include any trailers your
+   instructions require (e.g. `Co-Authored-By`). Never rewrite merged commits
+   afterwards.
+   - `status: merged` → next task.
+   - `status: conflict` → the rebase was aborted and the worktree kept. Resolve
+     it yourself in the worktree, or resume the task's implementer with the
+     conflicting files, then merge again.
+7. **Verify** the full test suite on `F` before the next wave.
+
+## After the last wave
+
+Report per task: merged commit, validation evidence, anything skipped. Shipping
+(push, PR) is still the shipper's job and needs the user's go-ahead.
+
+## Don't
+
+- Run two implementers in the same checkout.
+- Merge in parallel, or merge a task whose validation you have not seen.
+- Let implementers commit, push, or touch files outside their `files`.

package/skills/dispatch/references/claude.md

@@ -0,0 +1,9 @@
+# Dispatch on Claude Code
+
+- Agent names carry the plugin prefix: `orch:implementer`, `orch:scoper`,
+  `orch:reviewer`, `orch:shipper`. The bare name is not found.
+- Parallel spawn: several Agent tool calls in one assistant message.
+- Do not set `isolation: "worktree"`; the worktree comes from `orch wt new`.
+- Resume an agent with SendMessage to its id or name; it keeps its context.
+- Plugin hooks see `agent_type` as `orch:<role>` and enforce: implementers
+  cannot commit or push; only the shipper pushes or opens PRs.

package/skills/dispatch/references/codex.md

@@ -0,0 +1,12 @@
+# Dispatch on Codex
+
+- Agent names are bare: `implementer`, `scoper`, `reviewer`, `shipper`. They
+  are loaded from the plugin's `codex/agents/*.toml` by the `orch codex`
+  launcher (`-c agents.<name>.config_file=…`). An unknown name silently falls
+  back to the default agent, so confirm the role in its first reply.
+- Spawn each task with `spawn_agent` (`agent_type`, no forked turns), all
+  before waiting, then `wait_agent` on every id.
+- The sandbox must allow writing `<repo>/.git` (`--add-dir <repo>/.git`) or
+  `orch wt new` and commits fail. `orch codex` adds it.
+- Hooks only run when the user trusted them, so restate "do not commit or
+  push" in every brief.

package/skills/plan/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: plan
+description: "orch workflow: write .scratch/<feature>/plan.md, a task list with file ownership and dependencies that the dispatch skill can run in parallel waves. Use when work has 2+ separable parts."
+---
+
+# Plan
+
+Write `.scratch/<feature>/plan.md` in the repo root. Keep `.scratch/` out of git
+(`.git/info/exclude`) unless the repo already tracks it.
+
+## Before writing
+
+1. Read the scoper brief if there is one; do not rescope.
+2. Decide every cross-cutting choice now (interfaces, names, libraries, error
+   handling). Workers run in parallel and cannot ask each other.
+
+## Format
+
+````markdown
+# <feature>
+
+Base branch: <F>   # the branch the tasks merge into
+
+## Decisions
+
+- <decision that every task must follow>
+
+## Tasks
+
+```yaml
+- id: T1
+  goal: <one sentence, observable outcome>
+  files: [<paths this task owns>]
+  depends_on: []
+  size: small        # or substantial (rule below)
+  validate: <command that proves this task works>
+  decisions: [<task-specific choices>]
+```
+````
+
+## Rules
+
+- `files` is ownership. Two tasks with no dependency path between them must not
+  share a file. If they must, add a `depends_on` edge or merge the tasks.
+- Shared files that everyone touches (lockfiles, barrel exports, registries) go
+  to one task that the others depend on.
+- Each task is 1 implementer-sized unit (one module or feature), not a project.
+- `size` is `substantial` when the task is its own module or feature needing
+  several edit-and-test cycles, roughly 100+ changed lines; otherwise `small`.
+- `validate` runs inside the task's own worktree and must not need other
+  unmerged tasks.
+- Don't split one feature into many tiny tasks. Separate features stay separate
+  tasks (each can land as its own commit), but small ones are batched, not
+  dispatched (below).
+
+## After writing
+
+Show the user the task table (id, goal, size, depends_on) in a few lines. If 2+
+independent tasks are `substantial`, continue with the `dispatch` skill for
+them. Batch the `small` tasks into one implementer task (all of them, in order,
+on the feature branch); run the rest (a lone or dependent substantial task) with
+its own implementer, one at a time. Parallel worktrees only pay off when each
+task is substantial.