Skip to main content

moai spec Document Management

UPDATED 2026-09-11 4 min read EDIT ON GITHUB ↗

moai spec manages the SPEC documents in the .moai/specs/ directory. It provides subcommands for status updates, drift detection, acceptance-criteria viewing, EARS/GEARS linting, atomic closure, era auditing, and archiving.

A SPEC is both the unit a harness receives work in and the single record a manager agent tracks progress against, so when its status diverges between frontmatter and the actual git history, the entire workflow’s signal breaks. This command provides mechanical checks — drift detection, era audits, atomic closure — to keep that consistency across the SPEC lifecycle. Routing through this command is recommended over hand-editing the frontmatter.

Subcommands

CommandDescription
moai spec statusUpdate or list SPEC status
moai spec driftDetect drift between frontmatter status and the git log
moai spec view <SPEC-ID>View acceptance criteria as a tree
`moai spec lint [SPEC-IDpath/to/spec.md
moai spec close <SPEC-ID>Atomic 4-phase closure (status: completed + progress.md backfill)
moai spec auditSPEC era classification and modern-era status drift audit
moai spec archiveArchive closed SPECs out of .moai/specs/

moai spec status

bash
moai spec status <SPEC-ID> <new-status>   # Update status
moai spec status --list                   # List all SPECs
moai spec status --sync-git               # Sync status from the git log
FlagDescription
--dry-runPreview changes without writing
--listList all SPECs and their status
--sync-gitSync SPEC status from main’s git log
--yesNon-interactive auto-confirmation for --sync-git (required for CI/pipes)

moai spec drift

bash
moai spec drift
FlagDescription
--jsonJSON-format output
--exit-code-on-driftExit code 1 when drift is detected
--countPrint only the drift count
--no-cacheBypass the HEAD-SHA result cache and recompute

moai spec lint

bash
moai spec lint [SPEC-ID | path/to/spec.md | SPEC directory ...]
FlagDescription
--jsonJSON-format output
--sarifSARIF 2.1.0 format output
--strictTreat warnings as errors
--format <fmt>Output format (table)
--baseline <path>Gate on a checked-in per-rule baseline instead of --strict: errors always fail, a rule’s non-advisory warning count is only blocked when it rises above its recorded value, and the standing warning total stays visible in the output
--update-baselineRecompute and rewrite the --baseline file (requires --reason)
--reason "<text>"Mandatory non-empty rationale recorded by --update-baseline; an empty or missing reason is rejected
Argument shapeExample
SPEC-IDSPEC-SPC-001 — resolved to .moai/specs/SPEC-SPC-001/spec.md under the project root (the same rule moai spec view uses)
File path.moai/specs/SPEC-SPC-001/spec.md
SPEC directory.moai/specs/SPEC-SPC-001 — read as the spec.md inside it

The three shapes are mixable in one invocation, and with no argument the whole corpus is scanned as before. An argument that looks like a SPEC-ID but resolves to no file is an argument error (exit code 3) naming the path that was tried — not a finding about a document.

Two advisory-grade warnings originate here. ModalityUnjudged reports a requirement the linter cannot judge instead of passing it over silently. REQTableRowsRejected reports table rows that were not read as REQ definitions. Both are advisory: --strict does not promote them to errors, and neither changes the exit code.

moai spec close

bash
moai spec close SPEC-ID

Atomically transitions a SPEC to status: completed in a single commit.

FlagDescription
--backfill-onlyPerform only the progress.md backfill
--dry-runPreview without committing
--forceForce closure without confirmation
--jsonJSON-format output

moai spec audit

bash
moai spec audit

Scans .moai/specs/SPEC-*/, classifies each SPEC with the era heuristic, and detects modern-era status drift.

FlagDescription
--jsonJSON-format output
--filter-era <era>Filter by era
--filter-spec <id>Filter by SPEC ID
--include-grandfatheredInclude grandfather-era SPECs
--strictStrict mode

moai spec archive

bash
moai spec archive --dry-run   # Check targets (no move)
moai spec archive --yes       # Apply the plan

Archives terminal SPECs older than the grace window (default 90 days).

FlagDescription
--dry-runReport the target set without moving
--yesConfirm the move (required to apply)
--grace-days <n>Grace-window days (0 = default 90)
--jsonOutput the plan as JSON