Skip to main content

moai spec Document Management

UPDATED 2026-08-13 3 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.md...]Lint for EARS compliance and structural validity
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.md...]
FlagDescription
--jsonJSON-format output
--sarifSARIF 2.1.0 format output
--strictTreat warnings as errors
--format <fmt>Output format (table)

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