Structural profile
The default refresh profile. It preserves codebase.md, index.jsonl,
symbols.json, search.md, and map.json, then adds
semantic-index.json and semantic-index.sqlite.
LEGION
Ascended
"My Name Is Legion, For We Are Many"
A guided execution layer for AI-assisted software work. One Legion command surface.
v9.4.1 · Readable maps & brownfield reports
Legion is still the word. Ascended is the evolution: a guided execution layer that keeps the human in command while the many help brainstorm, plan, build, review, remember, and prepare work for ship-readiness.
Grok Build, Bound Precisely
Grok Build is a first-class Legion target: Legion manages its
native skill install, bounded detection, headless executor, and packed-install smoke.
That is a Legion support claim, not a claim of stable upstream parity. The verified
upstream CLI is grok 1.0.10 (5992780042ca) [alpha], so the alpha caveat remains.
Native skill paths. Local installs use
$PROJECT/.grok/skills/legion/SKILL.md. Global installs use
$GROK_HOME/skills/legion/SKILL.md; when $GROK_HOME is unset,
use the fallback path <home>/.grok/skills/legion/SKILL.md. The generated skill
appears to Grok as /legion. Plugins and .grok/commands are
separate surfaces and are not written by the Legion installer.
Headless contract. Legion passes argv, never a shell string:
grok --prompt-file <path> --cwd <repo> --output-format json --permission-mode bypassPermissions.
The completed json envelope is distinct from
streaming-json newline-delimited session updates and from
grok agent stdio, the separate ACP JSON-RPC surface.
Authentication and dispatch. Grok owns browser authentication and
API-key configuration. Legion never reads, stores, or transmits
XAI_API_KEY; it only performs the bounded version probe and lets Grok
report authentication diagnostics. Grok has no native parallel-subagent primitive,
so Legion executes its build and review waves sequentially.
Summon The Legion
Install once, open any project, and use the same Legion words everywhere. The command surface is always legion. Requires Node.js >=24 <26.
# Install or update the current release on PATH npm i -g legion-ascended@latest # Or run the CLI without a global install npx legion-ascended map --check # See the recommended first-class hosts legion install --list-targets # Install Grok Build's native Legion skill grok --version legion install --target grok --local # Preview before writing host files legion install --target codex --local --dry-run # The rite: intake is reviewed and accepted by a human, never assumed legion start --goal "<what you are building>" legion start --accept-draft legion start --answer "<node>=<value>" legion start --finalize # Plan, then approve the spec before the work runs, not after legion plan 1 --from-roadmap ROADMAP.md legion approve spec --approver <your-id> # Build picks claude, codex, hermes, grok, then manual legion build legion build --executor grok legion review legion review --accept --approver <your-id> legion ship
Release 9.4.1 · Readable maps, graphs, and brownfield reports
Semantic Map v2
Give the human reviewer a stable codebase index before the work begins. Semantic Map v2
keeps the legacy inventory files, then adds a hash-pinned structural snapshot and a local
FTS5 accelerator. codebase.md is now a module index, import/export reference
graph, and directory tree rather than a first-content file dump.
Inventory profile
The v1 compatibility path. It writes only the five legacy inventory artifacts for tools that do not need structural facts or FTS-backed retrieval.
legion map --refresh --profile structural
legion map --refresh --profile inventory
legion map --check --profile structural
legion map --query "resolve asset"
legion map --why sym_<fact-id>
Read-only by design. --check, --query, and
--why do not create workflow runs or rewrite artifacts. Refresh is the only
map mode that writes. --scope belongs on refresh, freshness checks, or a bare
summary; query and why use the stored dataset and reject a new scope.
Provenance is not proof. Results identify source paths, hashes, extractor
versions, fact IDs, and exact ranges. Open those files and verify behavior before a human
approves the plan. The map focuses inspection; legion review and explicit
human acceptance still provide the evidence that legion ship evaluates.
The Commands
Twenty-one commands: five in the core loop, three governance, nine guidance, four diagnostics. Each still spoken as Legion.
| Command | Purpose |
|---|---|
| legion start | Prepare an intake draft for human review, ask only the unresolved questions, then write requirements, constitution, and ROADMAP.md. |
| legion plan <N> | Turn a roadmap phase into delta specs, a change bundle, an oracle, and task contracts. |
| legion build | Execute the latest taskgraph through the claude, codex, hermes, grok, manual, or fake adapter and record evidence. |
| legion review | Submit structured review decisions through claude, codex, hermes, grok, manual, or fake and require explicit human acceptance by a named approver. |
| legion ship | Derive the risk tier's gate set and report each gate satisfied, unsatisfied, or unevaluable. Publishes nothing. |
| legion approve | Record a human decision about delta specs, the oracle, the verification surface, or protected paths. |
| legion attest | Record that a named human asserts specific hash-pinned files are this change's evidence. |
| legion release | Record how the change's release is observed and taken back. |
| legion explore | Create read-only design discovery and handoff notes. |
| legion map | Refresh a readable module map, reference graph, and directory tree, plus the structural index; check freshness; query facts; explain one structural fact with provenance. |
| legion assess | Run a read-only brownfield assessment and print an evidence-bound report. Finding counts are not the audit. |
| legion quick | Create a one-task ad-hoc change for the normal build/review loop. |
| legion advise | Produce read-only advisory guidance. |
| legion polish | Create scoped polish work that still goes through build and review. |
| legion learn | Record durable lessons consumed by later context packs. |
| legion retro | Analyze recent evidence and write follow-up actions. |
| legion milestone | Define, inspect, complete, and archive lifecycle milestones. |
| legion council | Record structured governance decisions. |
| legion status | Show workflow stage, map freshness, guidance records, and next action. |
| legion validate | Validate committed Legion project state. |
| legion doctor | Validate project state plus .legion/var and bundle-index path presence. |
Every workflow command takes --json and --repository-root, and refuses any flag it does not declare. Typed internals live under legion dev.
The Rite Of Execution
The sacred cycle is explicit: legion start -> legion plan -> legion build -> legion review -> legion ship. Guidance commands enrich the loop and governance commands gate it; neither bypasses it.
legion exploreResearch, constraints, approaches, handoff notes
↓
legion mapReadable module map, reference graph, tree, Semantic v2 provenance, and freshness checks
↓
legion startProject truth record
↓
legion planDelta specs, typed taskgraph, and verification contracts
↓
legion approveNamed human signs the spec before the work runs, not after
↓
legion buildContext pack, executor result, redacted logs, pending evidence
↓
legion reviewSubmitted decision, human accept or reject
↓
legion attestHash-pinned evidence, plus legion release for the observation plan, at R3
↓
legion shipReadiness gate, not a deploy button
The Sacred Powers
Fresh Context
Maps, lessons, records, and guidance runs become focused context packs.
Typed Execution
Taskgraphs flow through the claude, codex, hermes, grok, manual, or fake adapter and leave durable task-run artifacts.
Guarded Dispatch
Control artifacts are snapshotted before a writable run and restored after; a run that edits them is blocked and told which paths it touched.
Risk-Tiered Gates
Each tier from R0 to R3 names its own gate set. Ship reports every gate satisfied, unsatisfied, or unevaluable — absent evidence blocks.
Evidence Trails
Builds record prompts, outputs, redacted logs, hashes, and pending evidence.
Human Review
Review decisions are submitted before evidence can be accepted.
Guided Memory
Learn, retro, milestone, and council records feed future work.
Unified Install
First-class targets expose one Legion entrypoint instead of uneven command names.
The Tithe
The Legion asks not for blood, but for sustenance.
Those who have commanded the many and found them worthy
may offer tribute, that the voices may continue to serve.
Your sacrifice sustains the many.