execute

Files (28)

• LIMITATIONS.md
• SKILL.md
• codegraph.toml · code-index/providers/
• graphify.toml · code-index/providers/
• orchestrator.py
• adversarial-challenge.md · references/
• cli-tool-mapping.md · references/
• deviation-handling.md · references/
• domain-checklists.md · references/
• dynamic-parallelization.md · references/
• error-recovery.md · references/
• executor-resolution.md · references/
• expertise-injection.md · references/
• flat.md · references/
• plan-validation.md · references/
• research-protocol.md · references/
• resume-protocol.md · references/
• session-project-invariant.md · references/
• single-doc-shape.md · references/
• state-formats.md · references/
• synthesis-checklist.md · references/
• verification-protocol.md · references/
• wave-patterns.md · references/
• waves.md · references/
• code-index-detect.sh · scripts/lib/
• resolve-executor.sh · scripts/
• run-critique-loop.sh · scripts/
• validate-plan.sh · scripts/

SKILL.md (first lines)

<!-- style-exception: mechanical command rename preserves pre-existing prose -->
# Execute

**One command on a plan.** `/execute` executes a plan. It routes between a lightweight single-session executor (the default) and full wave orchestration.

When `$CODEX_THREAD_ID` is nonblank, before any routing or work, Print exactly once:
`codex posture: execute uses spawn_agent for wave tasks when available, with main-thread sequential fallback.`

| Mode | What runs | Use when |
|------|-----------|----------|
| `flat` (default) | lightweight single-session executor: read the plan, make the changes, verify, done | a focused plan: a bug fix, a 1-session feature, a single `.md` plan |
| `waves` (alias `operator`) | wave orchestration: validate the strategy, run waves sequential/parallel, dispatch TDD subagents, verify from a fresh perspective | a multi-phase plan whose Execution Strategy declares `- wave:` entries |

This is a **router**, not a monolith. It parses the first argument token as a mode, announces the resolved mode, then loads that mode's body and follows it in this same context. It never calls another skill at runtime (it dispatches subagents via the Task/Agent tool and loads mode bodies via Read).

> **Multi-CLI:** If not on Claude Code, see [references/cli-tool-mapping.md](references/cli-tool-mapping.md) for tool equivalents.

## Step 0: Location preflight (before any write)

`/execute` writes code. Before resolving the mode, consult the shared location verdict (the SAME one `/target` and `/fix` use, so the canonical-main rule never drifts). Resolve the plugin root portably so the helper is found on non-Claude surfaces too. On those, `CLAUDE_PLUGIN_ROOT` is unset and the project checkout is not the fno plugin. Try `CLAUDE_PLUGIN_ROOT`, then `CODEX_PLUGIN_ROOT`, then the persisted `~/.fno/install/plugin-root` pointer (written by `session-start.sh`), then the git root.

```bash
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cat "$HOME/.fno/install/plugin-root" 2>/dev/null || git rev-parse --show-toplevel 2>/dev/null)}}"
LOC_HELPER="$PLUGIN_ROOT/hooks/helpers/check-impl-location.sh"
[[ -f "$LOC_HELPER" ]] && bash "$LOC_HELPER" || echo "verdict=ok"
```

If the output carries `verdict=canonical-protected` AND `TARGET_LOCATION_OK` is not `main-acknowledged`, REFUSE: do not resolve the mode, do not write. Name the branch (from the `branch=` line) and print the exact escape, then stop. The authorized-worktree path is the primary escape; the in-place branch and the acknowledge override are the last resorts:

```
/execute refused: canonical checkout on '<branch>' (sibling terminals share .fno/).
  worktree:  wt=$(fno agents workspace worktree ensure --repo . --name <slug> --harness <yours>) && cd "$wt"   # for a bound node, `fno do target start <node>` does this
  branch:    git checkout -b feature/<slug>          # in place, last resort
  override:  re-run with TARGET_LOCATION_OK=main-acknowledged   # last resort
```

Otherwise (`verdict=ok`, a linked worktree, or the helper absent) continue to Step 1.

## Step 1: Resolve the mode (ALWAYS announce it)

The default mode `flat` takes a **plan path**. The `waves` mode (and its one-release alias `operator`) is selected by an **exact** leading keyword. Parse the first whitespace-delimited token:

- **no argument** -> error. The plan path is required. Print:
  > "Usage: `/execute <plan>` (flat, default) or `/execute waves <plan>` (wave orchestration). Pass a plan path."

  Stop with a non-zero result.
- **`flat`** -> mode is `flat` (explicit). Print `running flat (single-session)`. Consume the token; the remaining text is the plan path (error as above if empty). Go to Step 2.
- **`waves`** (or the alias **`operator`**) -> mode is `waves`. Print `running waves (wave orchestration)`. Consume the token; the remaining text is the plan path. An **empty** remainder is allowed here (unlike flat): bare `/execute waves` runs wave orchestration on the current-directory plan. Go to Step 3.
- **a first token that is none of `flat`/`waves`/`operator` AND resolves as a path** (an existing file or directory) -> mode is `flat` (default). Print `running flat (default)`. The entire argument is the plan path. Go to Step 2.
- **a first token that is none of the above AND does not resolve as a path** -> this is an unknown mode / unresolvable plan (almost always a typo'd mode keyword or a wrong path). Do NOT default, do NOT guess. Print:

  ```
  unknown do mode / unresolvable plan: '<token>'
  valid modes: flat (default), waves (alias operator)
  usage: /execute <plan>   |   /execute waves <plan>
  ```

  and stop with a non-zero result (run nothing, dispatch nothing). This is the locked router contract: an unknown non-empty first token that is not a real plan path never silently falls through.

## Step 1.5: do provenance is stamped at claim release

The `do` lifecycle row is no longer stamped here. The session writes it upon releasing its claim at a finished terminal: `DonePRGreen`, `DoneAdvisory`, `DoneDelivery`, or `NoWork`. `started_at` uses claim acquisition time. `ended_at` uses release time. This records a per-session hold window: how long a user touched the node.

This is the third code choke point. Ship writes `pr_number`. Blueprint writes `plan_path`. Claim release writes `do`. If a direct CLI call or non-Claude worker skips this skill, the row still records.

A session that stops before finishing keeps the claim and has no `do` window yet. This includes an open PR or more work ahead. `fno-agents finalize` remains the ship-terminal backstop.

## Step 2: flat mode (lightweight single-session, default)

### 2a. Wave-declaration notice (flat on a wave plan)

Before executing, check whether the resolved plan declares waves. A plan "declares waves" when its single-doc body carries an Execution Strategy with `- wave:` entries - the same wave declarations target's blueprint treats as the source of truth. If it does, print a one-line notice and **proceed flat anyway** (flat is never silently upgraded to parallel):

```bash
PLAN_ARG="$1"  # the single .md plan path resolved in Step 1
if [[ -f "$PLAN_ARG" ]]; then
  # grep -c prints "0" AND exits 1 on zero matches, so `|| echo 0` would
  # append a second line ("0\n0") and break the numeric test. `|| true`
  # keeps grep's own single-line count; ${WAVES:-0} covers a grep error
  # (exit 2, no output).
  WAVES=$(grep -cE '^[[:space:]]*-[[:space:]]*wave:' "$PLAN_ARG" 2>/dev/null || true)
  if [[ "${WAVES:-0}" -gt 0 ]]; then
    echo "notice: this plan declares $WAVES waves; run \`/execute waves $PLAN_ARG\` to parallelize. Proceeding flat."
  fi
fi
```

Defensive: an absent plan file or one with no wave entries yields zero waves and prints no notice - flat proceeds without crashing.

### 2b. Run the flat executor

Load [flat.md](references/flat.md) and execute it in full, in this context. That body is the lightweight single-session flow: read the plan, resolve the executor (frontend craft pass when the surface matches), execute each numbered change atomically (evaluating kill criteria first), verify, and report. It dispatches no subagents and tracks no STATE.md - you ARE the executor.

## Step 3: waves mode (wave orchestration)

Load [waves.md](references/waves.md) and execute it in full, in this context. That body is the canonical wave-orchestration flow: validate the plan structure, load the execution strategy from the plan's Execution Strategy section, optimize parallelism from the file ownership map, run waves in sequential/parallel mode, dispatch per-task executors (archer / frontend-executor) via Task/Agent, verify from a fresh perspective, and report completion.

**Self-containment (no recursion).** The router loads the waves flow **inline via Read** and follows it here. It never re-invokes a skill to reach wave orchestration; per-task work is dispatched via the Task/Agent tool.

**Zero-wave plan.** `/execute waves` on a plan with no declared waves runs it as a single wave (the waves flow falls back to sequential execution of all phases when no execution strategy is found).

## Known Limitations and Deferred Work

- Unsupported harnesses force waves into sequential execution. See [LIMITATIONS.md](LIMITATIONS.md).

## Multi-CLI

Claude-Code primary. Both modes need `fno` and `git`. If a dependency is missing, the mode fails loud and reports it - it never fakes execution. On a CLI without parallel subagent dispatch (e.g. Gemini sequential fallback), waves mode degrades to main-thread sequential execution with an explicit downgrade reason; the rest of each flow is markdown the runtime follows directly.

From bllshttng/fno, Apache-2.0.

More from bllshttng/fno