ACE - Assign

Multi-step assignment execution with nesting, fork delegation, and inspectable traces. ACE Logo

Gem Version Ruby License: MIT

Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates

ace-assign turns work into a multi-step assignment with nested substeps, fork delegation to long-running agent subprocesses, and inspectable session traces. Steps are defined from a step catalog and assembled via presets or composed manually. Each step can reference a workflow instruction for execution details. Assignments are restartable -- failed steps keep their lineage so you can retry or inject fixes without losing history.


❯ ace-assign status
8qm5rt work-on-task-8qm.t.5nx-job.yml | running | 64/71 done | current: 100.01 review-pr | last: 070.03 release
hidden: 66 | done: 64 active: 1 pending: 5 failed: 1
100.01 active review-pr
100.02 next apply-feedback
100.03 next release
130 next reorganize-commits
140 next push-to-remote

Use ace-assign status --mode full when you need the whole tree, and ace-assign step when you need the raw instructions for the current or next step.

The easiest way to start is through ace-overseer -- define a task and run ace-overseer work-on --task <ref> --preset work-on-task , which creates the assignment, worktree, and tmux window in one shot.

Testing Contract

  • ace-test ace-assign runs the default deterministic package loop (test/fast).
  • ace-test ace-assign feat runs deterministic feature/contract coverage (test/feat).
  • ace-test ace-assign all runs full package deterministic coverage (fast + feat).
  • ace-test-e2e ace-assign runs scenario workflows under test/e2e.

Assignment verification uses deterministic commands only:

  • modified packages: ace-test <package> all --profile 6
  • monorepo gate: ace-test-suite --target all

How It Works

  1. Define steps from a preset or compose from the step catalog -- steps can nest into substeps and reference workflow instructions for execution details.
  2. Expand the definition into a session with explicit per-step instructions, state tracking (pending → in_progress → done/failed), and numbered hierarchy (e.g., 010, 010.01, 010.01.01).
  3. Drive execution with /as-assign-drive -- fork long-running steps to isolated agent subprocesses, advance the queue on completion, and retry or inject fix steps on failure.

Use Cases

Define assignments from presets - pick a preset like work-on-task or release-only, pass parameters (task refs, packages), and run ace-assign create --task ... or ace-assign create --yaml ... to expand them into a concrete step queue. Steps are defined in the catalog (e.g., work-on-task.step.yml) and ordered by composition rules. Compose custom assignments with /as-assign-compose.

work-on-task release steps resolve wfi://release/publish from shipped workflow sources by default, and project-level wfi:// source overrides registered under .ace/nav/protocols/wfi-sources/ are honored by both ace-bundle and ace-assign.

Run with orchestrator and fork agents - use /as-assign-drive to walk through steps, forking long-running work (implementation, review, release) to isolated agent subprocesses with configurable execution defaults or per-step fork.provider overrides. Forks can run sequentially or as parallel batches, each producing inspectable traces and session reports under .ace-local/assign/.

Recover from failure without losing history - keep failed-step lineage intact, inject targeted retries or fix steps, and continue execution with auditable failure evidence.

Compose assignments from templates - use /as-assign-compose and /as-assign-prepare to build assignment plans from reusable patterns, then pair with ace-task for task lifecycle, ace-bundle for context loading, and ace-review for quality checks.

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates | Part of ACE