orchestrate

Files (2)

• SKILL.md
• openai.yml · agents/

SKILL.md (first lines)

# Orchestrate

Execute all tasks in a plan using parallel TDD workers. Fully autonomous after invocation.

## Usage

```bash
orchestrate {plan-name}
```

Example: `orchestrate user-auth`

## Prerequisites

**First, resolve the plans directory and the project root,** once each. The plans directory is `.farseer/plans` unless the project overrides it in `.farseer/config.json`. Both scripts print an absolute path resolved from the project root, so the result does not depend on the working directory:

```bash
"{skill-base-dir}/../../hooks/resolve-plans-dir.sh"
"{skill-base-dir}/../../hooks/resolve-project-dir.sh"
```

**Shell variables do not survive between Bash calls.** Every `$PLANS_DIR` and `$PROJECT_DIR` below stands for the path these scripts printed: write that literal path, quoted, into each later command. Never run a command with an unset `$PLANS_DIR`. An empty value turns `"$PLANS_DIR/{plan-name}"` into `/{plan-name}` and `git reset -- "$PLANS_DIR"` into an error.

**Never substitute a hand-written `jq` line or a literal `.farseer/plans`.** A non-zero exit means the project root or the configured value is unusable; surface the script's stderr verbatim and stop. Quote every path, since a configured directory may contain spaces.

Then:

1. Plan must exist at `$PLANS_DIR/{plan-name}/`
2. Project must be configured (`.farseer/testing.md` exists)
3. Plan status must be `ready` or `in_progress`

Check prerequisites:

```bash
ls "$PLANS_DIR/{plan-name}/_plan.md" "$PROJECT_DIR/.farseer/testing.md"
```

If not found, output error and stop.

4. Must be on the correct feature branch

Verify the current branch matches `feature/{plan-name}`:

```bash
git branch --show-current
```

If the current branch is not `feature/{plan-name}`:

- Output an error explaining which branch is expected
- Ask the user if they'd like to check out `feature/{plan-name}`
- Do NOT proceed until on the correct branch

## Project Configuration

The orchestrator does not load `testing.md` or `code-standards.md` up front. It reads `testing.md` at [Step 4a](#step-4a-end-of-run-hooks-post-implementation--tests--commit), when it needs the full-suite command. Subagents read the rules files on their own from the [Project Rules](#project-rules) list.

### Project Rules

Build the rules file list once, before the first spawn. Each entry is an absolute path under `$PROJECT_DIR`, included **only if the file exists**:

```bash
for f in testing.md code-standards.md; do
  if [ -f "$PROJECT_DIR/.farseer/$f" ]; then printf '%s\n' "$PROJECT_DIR/.farseer/$f"; fi
done
```

Every subagent prompt carries this list under a `## Project Rules` heading, and the subagent reads each file itself. **Never paste or summarize the files' contents into a prompt.** A pasted copy is where paraphrase drift creeps in, and the subagent can read the original. Pass the concrete paths, not `$PROJECT_DIR`. As with `## Task File Path`, one resolver runs in this skill and every subagent gets a finished path.

## Execution Algorithm

### Step 0: Suggest Unattended Completion via /goal

Claude Code's built-in `/goal` command keeps a session working toward a verifiable end state — its evaluator runs after each turn and pushes execution to continue until the condition is met. Only the user can set a goal (`/goal` is a user-typed command and cannot be invoked from a skill), so surface a command tip the user can copy-paste and continue immediately. This is informational, never a gate. Do not wait for a response.

Display:

```text
Tip: for large plans, you can keep this run going unattended with Claude Code's
built-in /goal command (interrupt me now to set it, or set it before a future run):

  /goal the {plan-name} plan run reached a terminal state: /farseer:orchestrate output ALL_TASKS_COMPLETE or TASKS_BLOCKED

Either way, an interrupted run resumes from disk. Just re-run /farseer:orchestrate {plan-name}.
```

The suggested condition deliberately names **both** terminal outputs. A goal phrased as only `ALL_TASKS_COMPLETE` leaves the evaluator demanding more turns after a legitimately blocked run, when the correct behavior is to stop and report the blockage.

### Step 1: Load Plan Context

Read plan files:

- `$PLANS_DIR/{plan-name}/_plan.md` - Plan overview
- `$PLANS_DIR/{plan-name}/issues/*.md` - All task files

Build the [Project Rules](#project-rules) list now.

Parse each task file to extract:

- Task number (from filename)
- Status (pending | in_progress | completed | blocked)
- Dependencies (from `Depends on` field)
- Requirements (checkboxes)
- Retry count

Build a dependency graph as a data structure.

### Step 2: Update Plan Status

If plan status is `ready`, change to `in_progress`:

- Edit `$PLANS_DIR/{plan-name}/_plan.md`
- Set `## Status` to `in_progress`

**Check the run fingerprint.** Every hook call reads `$PLANS_DIR/{plan-name}/.hook-fingerprint` and passes it as `--expect=` (see [Hook Discovery](#hook-discovery)), so agent files changing mid-run halt the orchestration rather than silently swapping the pipeline. If the file is **missing**, capture one now so a resumed run is covered too:

```bash
"{skill-base-dir}/../../hooks/discover-hooks.sh" --fingerprint > "$PLANS_DIR/{plan-name}/.hook-fingerprint"
```

From petemcw/farseer, MIT.

More from petemcw/farseer