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
Command
Description
moai spec status
Update or list SPEC status
moai spec drift
Detect drift between frontmatter status and the git log
SPEC era classification and modern-era status drift audit
moai spec archive
Archive closed SPECs out of .moai/specs/
moai spec status
bash
moai spec status <SPEC-ID> <new-status> # Update statusmoai spec status --list # List all SPECsmoai spec status --sync-git # Sync status from the git log
Flag
Description
--dry-run
Preview changes without writing
--list
List all SPECs and their status
--sync-git
Sync SPEC status from main’s git log
--yes
Non-interactive auto-confirmation for --sync-git (required for CI/pipes)
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-baseline
Recompute 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 shape
Example
SPEC-ID
SPEC-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.
Flag
Description
--backfill-only
Perform only the progress.md backfill
--dry-run
Preview without committing
--force
Force closure without confirmation
--json
JSON-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.
Flag
Description
--json
JSON-format output
--filter-era <era>
Filter by era
--filter-spec <id>
Filter by SPEC ID
--include-grandfathered
Include grandfather-era SPECs
--strict
Strict 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).