nomArmy

/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
    warn_at: 0.8

The General can lower these for one run, never raise them. 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.

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. 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 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. --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.