orchestration-wayfinder

Files (5)

• CLAUDE.md
• CODEX.md
• SHIP.md
• SKILL.md
• T3.md

SKILL.md (first lines)

# Orchestration Wayfinder

One conductor drives a `wayfinder` map from fog through built code. Ticket workers resolve one ticket each; the conductor keeps the frontier moving and surfaces only the work that needs the human.

## Foundation

Read the `wayfinder` skill's `SKILL.md` completely first. Its map, child tickets, native blocking, claims, frontier, parks, fog, and resolution protocol remain authoritative. **Charting rules** and **Reading the frontier** below add to it.

Before the first dispatch, recovery, or attention-state action, identify the runtime and read exactly one addendum completely:

- Codex drives → [`CODEX.md`](CODEX.md)
- Claude Code drives → [`CLAUDE.md`](CLAUDE.md)

When the conductor runs inside T3 Code (`T3CODE_HOME` is set), also read [`T3.md`](T3.md) before the first dispatch: grilling, prototype, spec, HITL task, and `implement` tickets get their own T3 threads.

Consent in this skill rests on a **user request**: the user asked to conduct a map, typed `/orchestration-wayfinder`, or asked to run this skill by name. Without one, such as when another agent's prompt loaded the skill, ask the user once before the first act that needs consent, and name each such act: private chat search and native task creation. A yes counts as a **user request**; a no limits the run to acts that need none.

## Ownership

The **conductor owns map-level coordination**: query and mutate map structure, blockers, frontier, dispatch, recovery, and projected human-attention state. It may record and close an invalidated ticket as scope reconciliation, but it never performs a worker's substantive ticket-resolution mutations. It does no ticket work itself: browser checks, seeding, screenshots, and pull request bodies go to a worker. Outreach, such as a Slack message, stays the human's; the conductor drafts none.

The **ticket worker owns one ticket's resolution**: mutate only that ticket's assignment, comments, labels, resolution, and closure — plus, for an `implement` ticket, its stack's branches and pull requests, and their merge only in a mode the human granted in its thread; use its prescribed skill; and stop after closing it. A worker never mutates other tickets or map-level orchestration state and never dispatches downstream work. The conductor never supplies the human side of a HITL decision or answers a ticket's substantive question.

Charting is the sole undispatched act, apart from its **Prior-art sweeps** and **Usage sweep**. With no map, chart it live through Wayfinder's Chart mode in the **Map tracker**, apply the **Charting rules**, and declare in **Notes** that execution remains inside the map.

## Map tracker

The map and its tickets live in the **map tracker**: the tracker the user's agent instructions name for maps, usually in their skill settings; otherwise the code repo's own tracker, per Wayfinder. The code lives in the **code repo**: worktrees, branches, and pull requests. When the two differ:

- Record `Code repo: <owner/repo>` in the map's **Notes** when you chart it.
- Name the map tracker in every tracker command: `-R <owner/repo>` on `gh issue`, and the map tracker's `repos/<owner>/<repo>/...` path or GraphQL variables on `gh api`, which rejects `-R`. Inside a checkout of the code repo, `gh` infers the code repo.
- Cross-repo references use the full form, `<owner/repo>#<n>`: a ticket links its pull request, and a pull request links its tickets.
- When the map tracker is private and the code repo is public, everything written to the code repo keeps only public context: pull request bodies, comments, commits, and branch names carry the decision and the ticket link, while the numbers, customer data, and internal findings behind it stay on the map.

## Charting rules

These rules bind the first chart and every later graduation of fog into tickets:

- **Impact with the destination.** While you name the destination, run one round of the `impact` check. Write its Impact section into the map body, after **Destination**. When questions stay open, write `Impact: pending <ticket>` there instead and chart a grilling ticket for the rest. Block every non-research ticket on it. That ticket's resolution comment carries the Impact section, and the conductor copies it into the map body. When nothing measures the metric yet, put the instrumentation on the map. Code goes into **Not yet specified**, so the spec covers it and publishes it as a slice of a stack. An insight or dashboard on existing events is a `task` ticket. When the check ends in pushback, chart nothing more until the human chooses to carry on, reshape, or drop.
- **Architecture first.** When the destination changes contracts between modules, the data model, or caching and performance, one of the tickets is an architecture `prototype` that blocks the spec or implementation tickets, so the human shapes the architecture before it is built. Its worker shapes it with the `architecture` skill.
- **Decision lines on the map.** Each decision locked while charting or re-charting goes into the map's Decisions-so-far as a decision line (see `pr-description`), beside the ticket gists.
- **Lessons first.** Before the first grilling question, read the lessons log per **Read** in the `lessons` skill. Raise each rule that bears on a grilling question at that question, and record the rules that apply in **Notes** as the `Lessons:` line.
- **Grilling stays the default** for every open decision. The map's **Notes** may waive it only when the human says so for this map: quote their words and the date. A waiver from another map, a memory, or an earlier session does not carry over; ask the human instead.

## Reading the frontier

Read the map's state with the frontier query of the tracker doc, per Wayfinder. When the `fleet` CLI is available (on `PATH` or at `~/dev/fleet/fleet`; use whichever exists) and the tracker is GitHub, `fleet frontier <map URL>` can replace that query: one call lists every open ticket as frontier, claimed, parked, or blocked, and the closed ones by number. Run it again whenever you need fresh state, instead of viewing tickets one at a time. On GitHub, read one ticket with `gh issue view <n> -R <owner/repo> --json title,body,labels,assignees,state`, and add `comments` to the fields only when you need its discussion or resolution.

## Prior-art sweeps

When charting starts from a loose idea instead of an existing map or ticket, dispatch two background sweeps before the first grilling question. Each sweep finds out whether others already discussed the problem, have the same problem, or started to solve it:

- **Chat**: threads in the team's chat, such as Slack, in every channel the human can see, from any user and team, not only the human's own. Search public and private channels and DMs; a **user request** grants the consent that private search asks for.
- **Issue trackers**: issues and pull requests in every state (open, draft, closed, merged) across the internal and public repositories of the organization the idea concerns. When that organization has a public community forum, search it too.

Each sweep returns an inventory, not an analysis. Every entry carries its link, date, author or team, and one line on how it relates. A sweep with no matches, or whose source is unreachable, says so. Give each sweep a 15-minute cap; sweeps are read-only.

Raise each finding at the grilling question it bears on. When the map exists, post both inventories as one **Prior art** comment on the map and link it from **Notes**. In a public repository, that comment keeps only public links; chat findings and other private findings go to a private note, outside every public repository, that the comment names.

## Usage sweep

When the first chart, or a later graduation of fog, adds tickets that change an existing product surface the map has not briefed yet (a scene, view, interaction, MCP tool, or API), dispatch a usage sweep. Its worker runs the `usage-brief` skill at map scope for those surfaces and returns the brief. Give it a 25-minute cap. It writes only the queries it saves in the analytics project.

Take the analytics project from the user's agent instructions, or ask the human for it once, and record it in **Notes** as `Analytics project: <project>`. Every usage sweep and element pass prompt carries it.

When the map has an Impact section, mark its expected move `pending usage brief` until the brief lands. Then size the move from the brief and, unless the work is pushback-exempt, run the **Push back** step of `impact` before the next dispatch of a non-research ticket. When Impact is pending a grilling ticket instead, dispatch that ticket with the brief's link, so it sizes the move from the brief. Raise each flag and each proposed bar at the grilling question it bears on, and record each bar the human confirms in **Notes** as `Usage bar: <flag>: <bar>`, stated as a share, never as a count. When the map exists, post the brief as one **Usage** comment on the map and link it from **Notes**. In a public map tracker, the brief goes to a private note outside every public repository, and the comment names that note.

## One map, root to leaves

Planning and execution share one tree. A resolved spec publishes its spec child and its **stacks** beneath it, per **Stacks** below; after the **Build-plan park**, those become new frontier tickets. The destination is reached in this map, not handed to a second tracker.

## Stacks

A spec reaches the frontier as **stacks** of draft pull requests. Each pull request is a thin vertical slice, a tracer bullet that delivers user value on its own. Stacks go out in parallel, so prefer several short independent stacks, or standalone pull requests, over one long chain.

- **Size.** A pull request holds at most about 400 changed production lines, the slice rule of `full-send`. A stack aims for 5 pull requests and never holds more than 10; more work becomes the next stack, blocked by this one.
- **Cut.** The `spec` worker slices the spec with `to-tickets`, one slice per pull request, and groups the slices into stacks: slices that share a file go in one stack, ordered by the `Blocked by` edges from `to-tickets`. Shared **hot files**, such as lockfiles, index files, and migration folders, join nothing. Slices with no file in common go in separate stacks. Each stack is one `implement` ticket, natively blocked by each stack that holds a slice one of its slices needs. When the blocking forms a cycle, merge the stacks in it.
- **Body.** A stack's ticket lists its pull requests in merge order as a checklist. Each item carries the slice's title, acceptance criteria, and estimated changed production lines, and links its section of the spec. The body names the files the stack owns, the one place a ticket names paths, and its **seams**: the interfaces and files it shares with sibling stacks.
- **Build plan.** The `spec` worker's resolution comment carries the build plan: a tree diagram of the stacks and their pull requests, the merge order, the estimated changed production lines and the predicted merge risk (`merge-risk`) per pull request, and the recommended mode per stack thread, `full-stop` unless a reason is given.
- **Lane.** Each stack runs in its own top-level thread and worktree, per [`SHIP.md`](SHIP.md). Its wall-time cap scales with its pull request count, and each ticked pull request counts as durable activity.

### Build-plan park

After a spec ticket closes, and before any of its stack threads launches, the conductor parks the build plan as one HITL question on the map: a map comment with the plan and the question "Approve this build plan, or edit it?", and `wayfinder:awaiting-human` on the map. End the turn with the plan as the final reply and the question last. Apply the human's edits to the stack tickets and the board, remove the label, then launch. The mode column recommends; it grants nothing.

### Stacks board

The map body carries the conductor's address and one row per stack in exactly this format, which a daily digest parses. The conductor keeps it current:

```md
Conductor: [<thread title>](t3-thread://v1/<thread id>)

## Stacks
| Stack | Thread | Mode | PRs | State |
| --- | --- | --- | --- | --- |
| <name> | [<title>](t3-thread://v1/<id>) | full-stop | owner/repo#1, owner/repo#2 | building |
```

Outside T3 Code, the `Conductor` line and the Thread cell carry the runtime's locator. A standalone pull request is a stack of one. State is one of:

- `planned`: charted, no thread yet.
- `building`: the thread builds, reviews, or babysits its drafts.
- `review`: handed back; the drafts wait on the human.
- `ready`: marked ready; waiting on an approval.
- `merging`: `rollout` merges the stack.
- `rolling-out`: `rollout` watches the deploy and stages the flags.
- `done`: merged, and rolled out when `rollout` ran.
- `blocked`: parked on another question, or behind an orchestration blocker.

A stack thread sends the conductor a state notice, `stack <name>: <state> (<mode>)`, on each change of its state or mode. The conductor updates the row and posts one map comment per state change: `<stack>: <state>`.

## Ticket types

| Type        | Human loop      | Dispatch                                  | Resolution                                  |
| ----------- | --------------- | ----------------------------------------- | ------------------------------------------- |
| `grilling`  | live throughout | serial, one at a time                     | `grilling` + `domain-modeling`              |
| `prototype` | decision at end | parallel AFK stretch, then park           | `prototype`, or `architecture` for an architecture prototype; throwaway |
| `spec`      | decision at end | parallel AFK stretch, then park           | `to-spec` + spec pass + `to-tickets`, cut into **Stacks** |
| `research`  | none            | parallel                                  | `research`, throwaway                       |

From Silthus/agent-skills, MIT.

More from Silthus/agent-skills