Amiral AI Orchestration Team

English | Türkçe

Amiral is a persistent, dependency-aware multi-agent engineering workflow for OpenCode. Its amiral CLI plans work, assigns tasks to specialized agents in isolated Git worktrees, integrates their results, and enforces independent review and QA gates.

The most important distinction: plan does not execute

amiral plan creates and validates a reusable plan, writes it under plans/, prints the plan ID, and exits. It intentionally does not create or execute a workflow.

amiral run executes. Given a request, it first plans and then creates and runs a workflow. It can also execute a saved plan or resume a persisted workflow.

Choose the command by intent:

| You want to... | Use | | --- | --- | | Inspect or approve a task graph before any implementation starts | amiral plan "Add authentication" | | Execute that approved plan | amiral run --plan feature-ab12cd34 | | Plan and execute in one command | amiral run "Add authentication" | | Continue an interrupted, paused, or retried workflow | amiral run --workflow feature-ab12cd34 | | Continue the currently selected workflow | amiral run |

# Two-step, review-before-execution flow
amiral plan "Add authentication" --type feature
# Output includes: Plan created: feature-ab12cd34
amiral run --plan feature-ab12cd34

# One-step flow: the same request is planned and then executed
amiral run "Add authentication" --type feature

--plan on run accepts either a plan ID under plans/ or an existing plan/graph file. Do not use amiral run --plan ... expecting it to create a plan; it consumes one.

Prerequisites

• Node.js 20 or newer and npm.
• Git, with the target directory initialized as a repository. amiral init never runs git init.
• The configured provider CLI. The supplied configuration uses the opencode executable; install it, authenticate it according to OpenCode's instructions, and ensure it is on PATH.
• A clean working tree before integration. Amiral preserves unrelated user changes and will not integrate into a dirty tree.
• Provider access, models, and credentials appropriate to your OpenCode setup. Do not put secrets in tracked configuration.

Confirm readiness with amiral doctor and amiral config validate after initialization.

Installation and invocation

Global installation

npm install --global amiral-ai
amiral --version
amiral --help

Project-local installation

npm install --save-dev amiral-ai
npx amiral --version

You can also add a package script, for example "amiral": "amiral", then run npm run amiral -- status.

Run without installing

npx --yes amiral-ai --version
npx --yes amiral-ai init --minimal

npm run build is only for developing this repository; it is not required after installing the published package. With a local install, prefer npx amiral so the project-local binary is used. With no local install, npx amiral-ai ... identifies the npm package unambiguously.

Verify the package and version

amiral --version                         # active global/PATH binary
npx amiral --version                     # local binary, when installed
npm view amiral-ai version               # current registry version
npm list amiral-ai                       # local installed version
npm list --global amiral-ai              # global installed version

The package version is read from its installed package.json; this repository currently declares 0.1.2. If an upgrade still reports an old version, determine which executable is being resolved (where amiral on Windows, which -a amiral on macOS/Linux), remove conflicting global/local installs, clear only npm's normal cache if npm reports corruption, and reinstall. Avoid blindly combining a stale global binary with a newer local package.

npm update --save-dev amiral-ai           # update a local dependency within its range
npm install --global amiral-ai@latest     # replace the global package
npx --yes amiral-ai@latest --version      # explicitly use the latest registry release

Reinstalling the CLI does not migrate or delete project runtime state. Review release changes before using a newer CLI against existing tasks/ data.

Initialize a project

Run initialization in the intended project root:

git init                                  # only if this is not already a Git repository
amiral init --minimal
amiral doctor
amiral config validate

amiral init [--minimal] [--force]

• --minimal: install only team.yaml, workflow definitions, schemas, and the machine planning agent; bundled skills are not read, validated, or installed.
• --force: overwrite existing template files. Use carefully; without it, existing files are retained.

Full initialization installs the whitelisted templates in team.yaml and .opencode/ (agents, workflows, contracts, orchestration, policies, prompts, schemas, and OpenCode configuration), then copies the packaged vendor/skills/** tree to the target's vendor/skills/**. Initialization also adds a marker-delimited Amiral block to .gitignore; it does not duplicate the block and does not overwrite content outside it. It rejects unsafe symbolic-link destinations and never installs package manifests, dependencies, or runtime state.

Project-root discovery

Except for init, commands can be run in the project root or any nested directory, including paths containing spaces. Amiral walks upward:

1. The nearest ancestor containing team.yaml wins.
2. If no team.yaml is found, the first ancestor containing .amiral or .opencode is a fallback.
3. If none exists, the command fails and suggests amiral init.

The process then operates from the discovered root. doctor is special: it can diagnose the current directory even when no Amiral root is found, and doctor --fix can create missing support directories/minimal files there.

Requests: positional goal versus --request

The complete original user request is authoritative input to planning.

• Use the positional [goal] for the entire request in ordinary usage.
• When the positional goal is only a short title, place the full requirements in --request.
• If both are supplied, non-empty --request is the complete authoritative request; the short goal is not concatenated with it.
• If --request is absent, goal becomes the complete request.
• --plan-file imports a plan and therefore does not require either text argument.

# Full request in the positional argument
amiral plan "Add password reset with expiring one-use tokens and integration tests"

# Short display-level idea plus the complete authoritative request
amiral run "Password reset" \
  --request "Add email-based password reset. Tokens expire after 15 minutes, are one-use, and must be covered by integration tests." \
  --type feature

Shell quoting matters. Quote requests containing spaces; use your shell's continuation syntax or a single line for long requests. Avoid putting secrets in command arguments because shells and process tools may record them.

Operating model

User request
    ↓
Lead / workflow selection
    ↓
Planner → validated dependency graph
    ↓
Specialists in isolated Git worktrees
    ↓
Integration worktree
    ↓
Reviewer ── CHANGES_REQUESTED → fix tasks → review again
    ↓ PASS
QA ──────── FAIL/BLOCKED → stop for input
    ↓ PASS
Complete

Core principles:

• Inspect the existing repository before making architectural decisions; follow existing conventions.
• The Lead is the sole orchestration authority. The Planner analyzes and decomposes but does not implement.
• Frontend, backend, database, and DevOps specialists implement only assigned work.
• A task is schedulable only after all dependencies are complete. Independent tasks may run concurrently only within configured provider/agent capacity and when safe.
• Work is isolated in task worktrees and merged idempotently into an integration worktree.
• Reviewer and QA are independent gates. A non-trivial workflow is complete only after implementation, integration, review PASS, and QA PASS.
• Review CHANGES_REQUESTED creates fix tasks up to quality.max_review_rounds; blocking/exhausted gates do not become false successes.
• Preserve unrelated changes, avoid destructive Git actions, and never expose credentials.

The supplied team.yaml defines agents, capabilities, provider routing/capacity, leases, retries, Git retention, and the feature, bugfix, and refactor workflows. The scheduler uses task dependencies and required capabilities; effective parallelism is bounded by execution.max_parallel_agents and provider concurrency (both default to 1 in the supplied configuration).

Global flags and output

These flags may be placed before or after a subcommand; command-specific --json/--verbose forms are also accepted where declared.

| Flag | Meaning | | --- | --- | | -q, --quiet | Suppress normal output where commands use the standard output renderer. config path and non-JSON config show currently write directly to stdout. | | -v, --verbose | Include diagnostic/progress events where supported. | | --json | Emit one JSON document for successful command output. | | -V, --version | Print the package version. | | -h, --help | Show help; use after any command/subcommand for scoped help. |

For automation, use --json and check the exit code:

amiral --json status > status.json
amiral doctor --json > doctor.json
amiral config show --json > config.json       # secret-like keys are redacted
amiral workflow list --json

Normal JSON output goes to stdout as one document. Errors go to stderr; in JSON mode they have the shape {"error":{"message":"...","code":N}}. Verbose provider progress is suppressed during JSON-producing planning/run/gate commands so stdout remains parseable. Interactive commands still require --force in non-TTY automation where documented.

doctor is a diagnostic exception: it currently exits 0 after completing its checks even when some checks fail. Automation must inspect the JSON failures count or each checks[].state; do not treat its exit code alone as a readiness result.

Exit codes are stable CLI categories:

| Code | Meaning | | ---: | --- | | 0 | Success; also used when run pauses for a scheduled transient retry. | | 1 | General failure or no progress. | | 2 | Invalid usage or declined/required confirmation. | | 3 | Missing/invalid configuration. | | 4 | Workflow blocked, gate not passing, lock/admin conflict, or input required. | | 5 | Provider failure. | | 6 | Validation/schema failure. | | 130 | Interrupted. |

Command reference

amiral plan

amiral plan [goal]
  --type <feature|bugfix|refactor>   default: feature
  --request <text>                   complete original request
  --name <name>                      prefix used in generated plan ID
  --plan-file <file-or-plan-id>      import and validate planner-format JSON
  --json

Runs the planning provider (unless importing), validates and analyzes the graph, saves artifacts under plans/<plan-id>/, reports task count/depth/parallel groups/conflict warnings, and exits without implementation.

amiral plan "Repair duplicate invoice creation" --type bugfix --name invoice-race
amiral plan --plan-file ./approved-plan.json --type refactor --json

Imported --plan-file content must be planner-format JSON; plan writes a new normalized plan directory. To execute an already saved graph directly, use run --plan.

amiral run

amiral run [goal]
  --plan <id-or-file>
  --workflow <id>
  --type <feature|bugfix|refactor>   default: feature
  --request <text>
  --name <name>
  --plan-file <file-or-plan-id>
  --json

Exactly one execution mode may be selected:

1. [goal], --request, or --plan-file: create a plan, create a workflow, then execute it.
2. --plan <id-or-file>: validate a saved planner result/task graph, create a workflow, then execute it.
3. --workflow <id>: resume that persisted workflow.
4. No mode: resume the active workflow (or the sole workflow if none is selected).

--name names newly generated plan/workflow IDs; it does not rename an existing workflow. --type controls new online planning and is the fallback when an imported graph does not carry a workflow type.

amiral run "Add favorites" --type feature
amiral run --plan feature-ab12cd34
amiral run --plan ./plans/reviewed/task-graph.json --name favorites-approved
amiral run --workflow feature-cd34ef56 --verbose
amiral run                              # active workflow

run holds the runtime lock and iterates through scheduling, provider dispatch, integration, review/fix rounds, and QA. It returns when complete or at a safe pause condition; it is not a daemon.

amiral status

amiral status [--workflow <id>] [--json] [--verbose]

Shows workflow status, the configured default provider name, task counts and retry/provider-error details, quality state, and active worktrees. It does not perform a live provider health or authentication check; use doctor for diagnostics. Without --workflow, it resolves the active/sole workflow.

amiral status
amiral status --workflow feature-cd34ef56 --json

amiral workflow

Administrative and inspection subcommands:

amiral workflow list
amiral workflow use <id>
amiral workflow show <id> [--json]
amiral workflow cancel <id> [--force]
amiral workflow reset-task <task-id> [--workflow <id>] [--force]
amiral workflow history [id] [--limit <positive-integer>]   default: 20

• list: list IDs, statuses, active selection, and update times.
• use: write the active workflow selection used by commands without an ID.
• show: show graph goal/summary when available and task details.
• cancel: cancel a workflow and release leases. It prompts in a TTY; non-interactive use requires --force.
• reset-task: manually return one task to retryable state. --workflow disambiguates it; --force permits otherwise restricted reset cases. This subcommand does not prompt.
• history: show newest requested history view up to --limit; omit ID to use active resolution.

amiral workflow list
amiral workflow use feature-cd34ef56
amiral workflow show feature-cd34ef56 --json
amiral workflow history feature-cd34ef56 --limit 50
amiral workflow cancel obsolete-workflow --force
amiral workflow reset-task API-002 --workflow feature-cd34ef56 --force

amiral retry

amiral retry <task-id> [--workflow <id>] [--force]
amiral retry --failed [--workflow <id>]
amiral retry --blocked [--workflow <id>]

Select exactly one task ID, --failed, or --blocked. It resets matching tasks but preserves their worktrees; it does not execute them. Follow with amiral run --workflow <id> (or amiral run for the active workflow).

amiral retry API-002 --workflow feature-cd34ef56
amiral retry --failed --workflow feature-cd34ef56
amiral run --workflow feature-cd34ef56

amiral review and amiral qa

amiral review [--workflow <id>] [--json]
amiral qa     [--workflow <id>] [--json]

Run a standalone gate against the selected workflow/integration workspace. Review reports verdict, summary, and findings; QA reports verdict, checks, and findings. A verdict other than PASS exits with code 4. These commands run a gate only; they do not replace run's complete lifecycle or automatically execute resulting fixes.

amiral review --workflow feature-cd34ef56
amiral qa --workflow feature-cd34ef56 --json

amiral clean

amiral clean [--workflow <id> | --all]
  [--completed] [--remove-failed] [--remove-blocked]
  [--delete-branches] [--dry-run] [--force]

Cleanup is conservative:

• With no cleanup policy selector, it previews completed-worktree cleanup only; no files are deleted.
• --dry-run always previews.
• --completed enables removal of completed worktrees.
• --remove-failed / --remove-blocked opt into deleting retained failed/blocked worktrees.
• --delete-branches opts into branch deletion; branches are kept otherwise.
• Scope defaults to the active workflow; choose one --workflow or --all, never both.
• Actual cleanup prompts in a TTY and requires --force in non-interactive environments.
• The current preview reports overall worktree usage. Its displayed scope is contextual metadata, not an exact per-worktree deletion plan filtered to --workflow.

amiral clean --workflow feature-cd34ef56 --dry-run
amiral clean --workflow feature-cd34ef56 --completed
amiral clean --all --completed --remove-failed --delete-branches --force

amiral doctor

amiral doctor [--json] [--fix]

Checks project layout, Git/provider/configuration health, runtime directories, and stale worktrees. --fix performs limited support repair: ensures .amiral/worktrees, .amiral/integration, and tasks, runs minimal initialization, and ensures the marker-managed .gitignore block. It is not a general auto-repair tool and does not initialize Git or authenticate a provider.

amiral doctor --json
amiral doctor --fix

amiral config

amiral config path
amiral config show [--json]
amiral config validate [--json]

• path: print the discovered absolute team.yaml path.
• show: print normalized configuration, effective execution/provider capacity, and registered providers. Keys matching token/key/secret/password are recursively replaced with [REDACTED].
• validate: verify the default provider is registered/enabled and that configuration contains at least one object-valued agent definition; output includes provider/capacity data. It does not deeply validate every agent field or corresponding agent file.

amiral config path
amiral config show --json
amiral config validate

Redaction is a display safeguard, not permission to store secrets in team.yaml.

Persistence, stopping, and resume

Plans and workflows are different persistent objects:

plans/<plan-id>/
├── planner-result.json
├── task-graph.json
├── planner-result.raw.txt
├── planner-result.raw.json
└── planner-diagnostics.json          # online planning; failed attempts may also be saved

tasks/
├── .active-workflow
└── <workflow-id>/
    ├── state.json
    ├── task-graph.json
    ├── history.json
    ├── requests/                     # directory name is configurable
    └── results/

.amiral/
├── amiral.lock
├── amiral.lock.guard                 # transient internal mutex; stale recovery may remove it
├── worktrees/<workflow-id>/...       # task worktrees
└── integration/<workflow-id>/...     # integrated tree and gate artifacts

These paths are local runtime artifacts and the initializer adds them to .gitignore. There is no documented SQLite state store: JSON files are authoritative. Do not hand-edit state while a command holds .amiral/amiral.lock.

Workflow resolution without --workflow uses tasks/.active-workflow; if absent, a sole workflow is selected automatically, while multiple workflows require amiral workflow use <id> or an explicit ID.

run stops safely for these reasons:

• completed: all implementation/fix work integrated, review passed, and QA passed.
• retry_scheduled: transient provider retry is waiting; exit code 0, with nextRetryAt when known. Run again after that time.
• failed: non-retryable/exhausted task failure; inspect state/results, reset with retry, then run again.
• blocked: workflow/task blocking; inspect status/history and resolve or manually reset as appropriate.
• needs_input: cancelled workflow, blocked/failed gate, review-fix exhaustion, or the 25-iteration safety bound. The safety-bound message explicitly permits another run.
• max_review_rounds: review changes could not progress within configured rounds; workflow is blocked.
• no_progress: no schedulable task and no pending retry; inspect dependencies and history.
• interrupted: the first SIGINT/SIGTERM requests a safe stop before the next mutation and exits 130. A second signal terminates immediately, so use it only when necessary.

Resume does not re-plan:

amiral status --workflow feature-cd34ef56
amiral workflow history feature-cd34ef56 --limit 50
amiral run --workflow feature-cd34ef56

Commands that mutate shared runtime state use a project lock. If another process owns it, wait for that process or diagnose a genuinely stale owner; do not delete an active lock blindly.

Troubleshooting

“No Amiral project found”

Run from the intended tree, verify team.yaml exists in an ancestor, or initialize the project. amiral config path confirms discovery.

Provider executable/authentication failure

Run amiral doctor --verbose and amiral config show; verify providers.<name>.binary, enabled, PATH resolution, and provider login outside Amiral. Provider errors may be retried according to team.yaml; diagnostics are persisted for planning failures.

More than one workflow and none active

amiral workflow list
amiral workflow use <workflow-id>

Alternatively pass --workflow explicitly.

Dirty tree or merge conflict

Commit/stash only your own intended changes, preserve unrelated work, inspect task/integration worktrees, and retry after resolving the underlying Git condition. Do not use destructive resets as a routine fix.

A run returned successfully but is not complete

Check the JSON/text reason. retry_scheduled intentionally returns 0 even though execution is paused. Wait until nextRetryAt, then resume. Only reason: "completed" means all gates passed.

A task failed or blocked

amiral status --workflow <id> --json
amiral workflow history <id> --limit 100
amiral workflow show <id> --json
amiral retry <task-id> --workflow <id>
amiral run --workflow <id>

Use --force only after understanding why a reset/cancellation/cleanup is restricted.

JSON parsing fails

Put --json on the command, parse stdout only, and retain stderr separately. Do not merge streams (2>&1) when consuming JSON. Prompts requiring confirmation need --force in CI.

Architecture and repository layout

AGENTS.md                     team-wide operating rules
team.yaml                     agents, providers, capacities, workflows
.opencode/
├── agents/                   role instructions
├── workflows/                feature, bugfix, refactor processes
├── orchestration/            execution/dependency/error protocols
├── contracts/                task, agent-result, review contracts
├── policies/                 architecture, Git, review, testing rules
├── prompts/ and schemas/     machine prompts and validation contracts
└── opencode.json             OpenCode configuration
src/cli/                      product CLI definitions
scripts/lib/                  orchestration runtime
templates/init/               files installed by `amiral init`
vendor/skills/                bundled skills installed by normal `amiral init`
tests/                        Node test suite
memory/                       architecture, conventions, decisions, lessons

The active packaged workflows are feature, bugfix, and refactor. Agents include Lead, Planner, Frontend, Backend, Database, DevOps, Reviewer, and QA. Agent definitions describe responsibility; workflows describe process; policies impose cross-cutting rules; contracts define machine-readable handoffs; skills provide specialized knowledge only when relevant.

Source development

Clone this repository and install the locked dependencies:

git clone https://github.com/atahandevelopment/opencode-ai-team.git
cd opencode-ai-team
npm ci
npm run typecheck
npm test
npm run build
node dist/src/cli/index.js --help

Useful scripts:

| Script | Purpose | | --- | --- | | npm run typecheck | Type-check without producing the distributable build. | | npm test | Run the Node test suite through tsx. | | npm run build | Compile with tsconfig.build.json into dist/. | | npm run validate:team -- <task-graph|agent-result|review-result|planner-result> <file> | Validate a JSON contract artifact against the selected schema. | | npm pack --dry-run | Inspect publish contents; prepack cleans and rebuilds dist. |

For source-tree CLI testing, build first and invoke node dist/src/cli/index.js ...; the published amiral binary points to that compiled entry. The legacy scripts/*.ts entry points remain compatibility/internal tools, but product usage should prefer the CLI.

License

This package declares the ISC license in package.json.