/feature runs, and watching jobs #

/feature: a feature, end to end #

/feature add join partners to the schema context

The General runs the army's whole workflow on its own and comes back when it's done: a plan, the build (Sr Dev, Jr Dev, UI/UX), the reviews that apply (data architect, security analyst, then the PM against the plan) and acceptance (PO, stakeholder), sending fixes back to the builders along the way. It ends with a branch for you to review and merge. nomArmy never merges or pushes, and never deploys or touches cloud credentials; those are hard stops. Any other decision it would normally ask you about, it makes conservatively, records, and keeps going, and every such decision is in the final report.

nomarmy connect installs it: /feature in Claude Code, a nomarmy-feature skill in Codex, and /feature in Cursor (Cursor's path follows its documentation and hasn't been tested against a real install). A command of your own with the same name is never overwritten.

Limits. Each feature is a run (run_start), and its jobs join it automatically. Admission enforces the run's limits and warns at 80%:

# ~/.config/nomarmy/config.yml (or .nomarmy.local.yml; never the committed .nomarmy.yml)
army:
  run_limits:
    max_jobs: 40        # the defaults
    max_api_usd: 10     # api agents only; a subscription isn't billed per call
    max_hours: 6        # hours with at least one job running
    warn_at: 0.8

max_hours counts only time when the run has a job running: time between jobs, such as planning, review or a wait at a human gate, doesn't count. The General can lower these for one run, never raise them; to allow more, raise run_limits here. When a vendor answers with a usage-limit error, that agent is paused for the rest of the run and the General stops and tells you; it never moves the role to another vendor to get around it. The one limit no tool can see is your coordinator's own seat. If that runs out mid-feature, the run log (kept current after every phase) lets /feature resume <run-id> in a fresh session carry on.

Redoing accepted work after a conflict. When an accepted job's commit no longer integrates (the branch moved on), the General dispatches a redo on the current head with reference_commits: [<that job id or commit>]. The worker can't read git history in its sandbox, so nomArmy hands it each commit as a patch file under .openclaw/reference/ (never committed; a file matching a secret rule is withheld) and names them in the brief. The General names the job or SHA instead of pasting the diff; to read a change itself, it uses commit_show.

Reviews see the change. A scout sent with reviews: <job id> gets that job's diff against its base as .openclaw/reference/reviewed-<job id>.patch, so it can check removed lines and edited test expectations. Without a base_ref, it reads the tree at the reviewed job's commit rather than the default branch.

A General that ends between wakes. Jobs run inside the MCP server of the session that started them. local_worker_start with detach: true runs the job in its own process instead: the session can end, and any later session reads it with local_worker_status or nomarmy jobs --wait.

Finishing a job that came back unfinished. A build job that ends partial, blocked or failing verification keeps its worktree, uncommitted. The General finishes it with a new job carrying continue_from: <that job id> and a brief of just the correction (say, the one wrong expected value in its test). The new worktree starts from the old job's base with its changes in place, and the finished whole is verified and committed together, so the foundation doesn't land outside nomArmy's checks. The commit carries a nomArmy-Continues: trailer naming the earlier job.

What a run added up to. nomarmy stats --since 7d (or the stats tool, for the General) fits on one screen: how many "done, tests pass" claims held up and how many nomArmy caught, tests shown to fail without their change, high-stakes work still needing a review, the top routing tips and spend. --details adds volume by role and model, code committed, time, tokens, what didn't finish, and what reviewers and review flags found. Filter with --role, --model, --repo and --run <id>. The one thing it can't count is what the General caught at integration; the report says so.

Sharing it. run_finish returns a prBlock, a "Verified by nomArmy" table for the pull request's description, scoped to that run; the playbook tells the General to use it as is. nomarmy stats --share prints the same block for any period or run, and nomarmy stats --badge [path] writes an SVG badge (default .github/nomarmy-badge.svg) plus the README line for it. Re-run it to refresh the numbers. If your README is also shown on npm, point the image at the file's raw GitHub URL, since npm doesn't resolve relative image paths (nomArmy's own README does this).

Acceptance contracts #

A contract records a feature's durable promises in acceptance/<feature>.yml. Each criterion has a stable ID, a description, a recorded status and proven_by evidence. A test proof names the exact file and full test name:

feature: Example feature
criteria:
  - id: EX-1
    text: The command reports its result
    proven_by:
      - file: tests/example.test.mjs
        test: command reports its result
        platforms: [linux, darwin, posix]
    status: met

A command proof uses command: "npm run build" and can set cwd: packages/example relative to the repository. A manual proof uses manual: "real device installation", checked_by: "Reviewer Name", and date: "2026-09-30"; optional expires_days: 90 expires it after that many days. A current manual proof counts as met and is reported as manual, while an expired one is unproven with a note. Manual evidence never overrides a broken automated proof. Use manual evidence for checks that cannot be automated.

Each proven_by entry, whether { file, test }, { command } or { manual, checked_by, date }, may have an optional platforms list of Node process.platform names or posix (every platform except win32). Entries outside the current platform are not run or counted. The human report marks how many proofs were not run, and --json lists their references under notApplicable. If none apply, the criterion is unproven with a no proof applies on <platform> note. An entry without platforms runs everywhere; an applicable test that passes zero times is broken.

Run nomarmy acceptance check to check all contracts, or pass one or more files to select them. The check runs each criterion's referenced tests: met means they pass, broken means one fails, missing means a named test or file is gone, and unproven means there are no references applicable to the current platform. A retired criterion is reported as retired without running tests. It may carry an optional retired record of the decision: decision (defer or drop), decided_by, comment_url and date (YYYY-MM-DD), plus optional reason and moved_to. The record is allowed only on a retired criterion. Broken and missing fail the command; unproven fails only with --strict. Use --json for the same report as data. CI runs nomarmy acceptance check on every platform job. Every automatic check runs in the sandbox, never on the host.

The General writes the contract in the operator checkout during planning and assigns each implement job its criteria IDs in its brief, including parallel jobs; workers do not allocate the next free ID. Unknown IDs are refused at admission. A job with base_ref takes its contracts from that commit, so a story branch can carry its own contract before it reaches the default branch; a job without one uses the operator checkout's working tree. A committed job whose revert check passed records proposed test references for all its criteria, including exact names and templates matched by their fixed prefix.

After integrating accepted jobs, preview nomarmy acceptance fill <run-id> --dry-run, then run it without --dry-run to append proofs (or supply one job ID). Existing references and comments stay intact; duplicate references are skipped. An unproven criterion is marked met only when its updated proofs pass the real checker. The General reviews and prunes the broad mapping after filling, since every changed test is proposed for every criterion its job carries, then commits the contract with the feature. A CONTRACT BROKEN: issue means the change is wrong or the contract must intentionally change in the same pull request. CONTRACT NOT CHECKED: means the check couldn't run (its reason follows); it still needs review, but it is evidence of nothing. --json returns the additions as data. run_finish checks the checkout again and includes its acceptance verdict in the PR block; check errors are shown, not hidden.

Watching what nomArmy is doing #

Storage looks after itself. OpenClaw's scratch files (about 1.2 GB for a Codex job) go when each call ends, and each health check removes finished jobs' remaining runtime data after a day (NOMARMY_AUTO_PRUNE_HOURS, 0 to turn it off), keeping every job's record and report. nomarmy jobs --prune --older-than 0 does it for every finished job now.