{"_id":"@aexos/core","name":"@aexos/core","dist-tags":{"latest":"5.3.0"},"versions":{"5.3.0":{"name":"@aexos/core","version":"5.3.0","description":"AEXOS - Agentic eXecution & Orchestration System: AI-Orchestrated System for Full Stack Development - Core Framework","bin":{"core":"bin/aexos.js","aexos":"bin/aexos.js","aexos-core":"bin/aexos.js","aexos-minimal":"bin/aexos-minimal.js","aexos-graph":"bin/aexos-graph.js","aexos-delegate":"bin/aexos-delegate.js"},"preferGlobal":false,"workspaces":["packages/*"],"exports":{"./resilience":"./.aexos-core/core/resilience/index.js","./resilience/agent-immortality":"./.aexos-core/core/resilience/agent-immortality.js","./bin/*":"./bin/*","./installer/aexos-core-installer":"./packages/installer/src/installer/aexos-core-installer.js","./installer/enterprise-detector":"./packages/installer/src/enterprise/enterprise-detector.js","./installer/enterprise-errors":"./packages/installer/src/enterprise/enterprise-errors.js","./installer/enterprise-manifest-loader":"./packages/installer/src/enterprise/enterprise-manifest-loader.js","./installer/enterprise-rollback":"./packages/installer/src/enterprise/enterprise-rollback.js","./installer/enterprise-upgrader":"./packages/installer/src/enterprise/enterprise-upgrader.js","./installer/enterprise-upgrade-plan":"./packages/installer/src/enterprise/enterprise-upgrade-plan.js","./installer/pro-scaffolder":"./packages/installer/src/pro/pro-scaffolder.js","./package.json":"./package.json"},"scripts":{"format":"prettier --write \"**/*.md\"","build":"node bin/utils/validate-publish.js","test":"jest","test:ci":"jest --runInBand --forceExit","test:watch":"jest --watch","test:coverage":"jest --coverage","test:e2e:installed-skills":"node scripts/e2e/installed-skills-smoke.js","test:e2e:pro-enterprise-upgrade":"node scripts/e2e/pro-to-enterprise-upgrade-smoke.js","test:health-check":"mocha tests/health-check/**/*.test.js --timeout 30000","lint":"eslint . --cache --cache-location .eslintcache","typecheck":"tsc --noEmit","release":"semantic-release","release:test":"semantic-release --dry-run --no-ci || echo 'Config test complete - authentication errors are expected locally'","generate:manifest":"node scripts/generate-install-manifest.js","validate:manifest":"node scripts/validate-manifest.js","validate:registry-determinism":"node scripts/validate-registry-determinism.js","validate:agents":"node .aexos-core/infrastructure/scripts/validate-agents.js","sync:ide":"node .aexos-core/infrastructure/scripts/ide-sync/index.js sync","sync:ide:validate":"node .aexos-core/infrastructure/scripts/ide-sync/index.js validate","sync:ide:check":"node .aexos-core/infrastructure/scripts/ide-sync/index.js validate --strict","sync:ide:claude":"node .aexos-core/infrastructure/scripts/ide-sync/index.js sync --ide claude-code","sync:ide:codex":"node .aexos-core/infrastructure/scripts/ide-sync/index.js sync --ide codex","sync:ide:gemini":"node .aexos-core/infrastructure/scripts/ide-sync/index.js sync --ide gemini","sync:ide:github-copilot":"node .aexos-core/infrastructure/scripts/ide-sync/index.js sync --ide github-copilot","sync:ide:antigravity":"node .aexos-core/infrastructure/scripts/ide-sync/index.js sync --ide antigravity","validate:claude-sync":"node .aexos-core/infrastructure/scripts/ide-sync/index.js validate --ide claude-code --strict","validate:claude-integration":"node .aexos-core/infrastructure/scripts/validate-claude-integration.js","validate:codex-sync":"node .aexos-core/infrastructure/scripts/ide-sync/index.js validate --ide codex --strict","validate:codex-integration":"node .aexos-core/infrastructure/scripts/validate-codex-integration.js","validate:gemini-sync":"node .aexos-core/infrastructure/scripts/ide-sync/index.js validate --ide gemini --strict","validate:github-copilot-sync":"node .aexos-core/infrastructure/scripts/ide-sync/index.js validate --ide github-copilot --strict","validate:antigravity-sync":"node .aexos-core/infrastructure/scripts/ide-sync/index.js validate --ide antigravity --strict","validate:gemini-integration":"node .aexos-core/infrastructure/scripts/validate-gemini-integration.js","sync:skills:codex":"node .aexos-core/infrastructure/scripts/codex-skills-sync/index.js","sync:skills:codex:global":"node .aexos-core/infrastructure/scripts/codex-skills-sync/index.js --global --global-only","setup:codex-skills":"node .aexos-core/infrastructure/scripts/codex-skills-sync/bootstrap.js","setup:codex-skills:dry":"node .aexos-core/infrastructure/scripts/codex-skills-sync/bootstrap.js --dry-run","validate:codex-skills":"node .aexos-core/infrastructure/scripts/codex-skills-sync/validate.js --strict","validate:codex-skills:self-test":"node .aexos-core/infrastructure/scripts/codex-skills-sync/validate.js --strict --self-test","sync:skills:grok":"node .aexos-core/infrastructure/scripts/grok-skills-sync/index.js","sync:skills:grok:dry":"node .aexos-core/infrastructure/scripts/grok-skills-sync/index.js --dry-run","repair:agent-references":"node .aexos-core/infrastructure/scripts/repair-agent-references.js","validate:paths":"node .aexos-core/infrastructure/scripts/validate-paths.js","validate:parity":"node .aexos-core/infrastructure/scripts/validate-parity.js","validate:hooks":"node scripts/validate-hooks.js","validate:package-completeness":"node scripts/validate-package-completeness.js","validate:semantic-lint":"node scripts/semantic-lint.js","manifest:ensure":"node scripts/ensure-manifest.js","sync:ide:cursor":"node .aexos-core/infrastructure/scripts/ide-sync/index.js sync --ide cursor","validate:publish":"node bin/utils/validate-publish.js","prepublishOnly":"node bin/utils/validate-publish.js && npm run generate:manifest && npm run validate:manifest","prepare":"husky || true","validate:aexos-core-namespace":"node scripts/validate-aexos-core-namespace.js","validate:port-denylist":"node scripts/validate-port-denylist.js","diff:framework-3way":"node .aexos-core/infrastructure/scripts/framework-3way-diff.js","sdc":"node bin/aexos.js sdc","wave":"node bin/aexos.js wave","generate:squad-registry":"node scripts/generate-squad-registry.js","validate:squad-registry":"node scripts/generate-squad-registry.js --check","generate:squad-manifests":"node scripts/normalize-squad-manifests.js","validate:squad-manifests":"node scripts/normalize-squad-manifests.js --check","sync:squad-agents":"node scripts/sync-squad-agents.js","validate:squad-agents":"node scripts/sync-squad-agents.js --check","validate:squads":"node scripts/validate-squads.js"},"dependencies":{"@clack/prompts":"^0.11.0","@kayvan/markdown-tree-parser":"^1.5.0","ajv":"^8.17.1","ajv-formats":"^3.0.1","ansi-to-html":"^0.7.2","asciichart":"^1.5.25","chalk":"^4.1.2","chokidar":"^3.5.3","cli-progress":"^3.12.0","commander":"^12.1.0","execa":"^5.1.1","fast-glob":"^3.3.3","fs-extra":"^11.3.2","glob":"^10.4.4","handlebars":"^4.7.8","inquirer":"^8.2.6","js-yaml":"^4.1.0","node-machine-id":"^1.1.12","ora":"^5.4.1","picocolors":"^1.1.1","proper-lockfile":"^4.1.2","semver":"^7.7.2","validator":"^13.15.15"},"keywords":["ai","aexos","agile","agents","orchestrator","fullstack","development","cli","cross-platform","interactive","wizard","modern-ux","vite-style","automation"],"author":{"name":"Cyryx Labs LLC"},"license":"SEE LICENSE IN LICENSE","repository":{"type":"git","url":"git+https://github.com/CyryxLabs/AEXOS.git"},"bugs":{"url":"https://github.com/CyryxLabs/AEXOS/issues"},"homepage":"https://github.com/CyryxLabs/AEXOS#readme","engines":{"node":">=18.0.0","npm":">=9.0.0"},"devDependencies":{"@semantic-release/changelog":"^6.0.3","@semantic-release/exec":"^7.1.0","@semantic-release/git":"^10.0.1","@types/jest":"^30.0.0","@typescript-eslint/eslint-plugin":"^8.46.2","@typescript-eslint/parser":"^8.46.2","conventional-changelog-conventionalcommits":"^9.1.0","eslint":"^9.38.0","husky":"^9.1.7","jest":"^30.2.0","lint-staged":"^16.1.1","mocha":"^11.7.5","prettier":"^3.5.3","semantic-release":"^25.0.2","typescript":"^5.9.3","yaml-lint":"^1.7.0"},"lint-staged":{"*.{js,mjs,cjs,ts}":["eslint --fix --cache --cache-location .eslintcache","prettier --write"],"*.md":["prettier --write","node scripts/semantic-lint.js --staged"],".aexos-core/development/agents/*.md":["npm run sync:ide"]},"overrides":{"tar":"^7.5.20","diff":"^8.0.3","fast-uri":"^3.1.2","serialize-javascript":"^7.0.5","test-exclude":"^7.0.1","undici":"^7.28.0"},"gitHead":"e8755df0d990c42f30a234de1a1f7a42e6cbc139","_id":"@aexos/core@5.3.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-IzCaQQXKQfBq/oUMzmFb1YnrLzM9XOPUapvP52l/d9stkr7LlxEt2y/wyzzkXCi86HplxefveFFdiOrH5NdJyw==","shasum":"cd7e6be2f569676c9e3e2990d487dd3b9f566f77","tarball":"https://registry.npmjs.org/@aexos/core/-/core-5.3.0.tgz","fileCount":2196,"unpackedSize":29556470,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGttqMs3EW/npbdA/YKzoiDxb0to/Iv15qgu9yPCfuCmAiEAu0BA6Ja6TLcDTMebVwh4J6xc+nwdzKpNzCVR+s/fjQw="}]},"_npmUser":{"name":"cyryx","email":"contact@cyryxlabs.com"},"directories":{},"maintainers":[{"name":"cyryx","email":"contact@cyryxlabs.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_5.3.0_1785726883583_0.22099552230443642"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T03:14:43.422Z","5.3.0":"2026-08-03T03:14:43.869Z","modified":"2026-08-03T03:14:44.091Z"},"maintainers":[{"name":"cyryx","email":"contact@cyryxlabs.com"}],"description":"AEXOS - Agentic eXecution & Orchestration System: AI-Orchestrated System for Full Stack Development - Core Framework","homepage":"https://github.com/CyryxLabs/AEXOS#readme","keywords":["ai","aexos","agile","agents","orchestrator","fullstack","development","cli","cross-platform","interactive","wizard","modern-ux","vite-style","automation"],"repository":{"type":"git","url":"git+https://github.com/CyryxLabs/AEXOS.git"},"author":{"name":"Cyryx Labs LLC"},"bugs":{"url":"https://github.com/CyryxLabs/AEXOS/issues"},"license":"SEE LICENSE IN LICENSE","readme":"

\n \"AEXOS\n

\n\n

\n \"Version\n \"Node\n \"9,306\n \"64\n \"AEXOS\n

\n\n

\n AEXOS — Agentic eXecution & Orchestration System, by Cyryx Labs.
\n A CLI-first framework that runs 64 specialised AI agents from one command layer.\n

\n\n---\n\n## Contents\n\n- [Start Here (10 Min)](#start-here-10-min)\n- [What AEXOS is](#what-aexos-is)\n- [How it works — the mental model](#how-it-works--the-mental-model)\n- [The constitution](#the-constitution)\n- [Install](#install)\n- [Your first session, step by step](#your-first-session-step-by-step)\n- [Activating an agent in your IDE](#activating-an-agent-in-your-ide)\n- [The core team](#the-core-team)\n- [The squads](#the-squads)\n- [Workflows](#workflows)\n- [Quality gates](#quality-gates)\n- [Building your own squad](#building-your-own-squad)\n- [CLI reference](#cli-reference)\n- [Framework and project boundary](#framework-and-project-boundary)\n- [Documentation](#documentation)\n\n---\n\n## What AEXOS is\n\nAEXOS is an orchestration framework for AI agents that lives in your terminal and in your IDE's\nagent surface. You install it into a project; it scaffolds a team of specialists, the procedures\nthey follow, and the routing layer that decides who handles what.\n\nYou do not manage the team member by member. You address the orchestrator — `@aexos-master` — and\nit reads a generated registry, matches your request to a domain, and routes it to the specialist\nthat owns it.\n\n**The problem it addresses.** Most AI-assisted development fails in two places. Planning is\ninconsistent, because each conversation reinvents the shape of the requirement. And context is\nlost, because the agent that implements never sees what the agent that planned understood.\n\n**How AEXOS answers it.**\n\n1. **Agentic planning.** Dedicated agents — analyst, product manager, architect — work with you to\n produce PRD and architecture documents that are consistent because they are produced by the same\n procedure every time, not by a fresh improvisation.\n2. **Engineering-contextualised development.** The scrum master agent turns those plans into\n development stories that carry everything the developer agent needs: complete context,\n implementation detail and architectural guidance, embedded in the story file itself. The\n developer opens one file and knows what to build, how, and why.\n\n**What makes it different from a prompt library.** Three things, and each is enforced rather than\nrecommended:\n\n- **The command line is the whole product.** No dashboard is ever required to operate the system.\n- **The expertise lives in procedures, not in personalities.** An agent is a router; the method it\n applies is a file you can read and change.\n- **Every squad specialist cites the published method it applies**, so its output can be checked\n against a source instead of taken on trust.\n\n## How it works — the mental model\n\nSix concepts. Learn these and the rest of the framework reads itself.\n\n| Concept | What it is | Where it lives |\n| --- | --- | --- |\n| **Agent** | A role with a persona, a scope of authority, and a list of procedures it may run. It routes; it does not itself hold the expertise. | `.aexos-core/development/agents/`, `squads/*/agents/` |\n| **Task** | An executable procedure with declared inputs, outputs and a completion checklist. This is where the method actually lives. | `.aexos-core/development/tasks/`, `squads/*/tasks/` |\n| **Template** | The shape of the document a task produces. | `.../templates/` |\n| **Checklist** | The validation a task must pass before it is considered done. | `.../checklists/` |\n| **Data** | The knowledge base a task reads from — reference tables, signal lists, decision models. | `.../data/` |\n| **Workflow** | A sequence of connected tasks, with the conditions for moving between them. | `.../workflows/` |\n\n### Task-first, not agent-first\n\nThis is the design decision everything else follows from:\n\n> Workflows are composed of **connected tasks**, not connected agents. Each task defines its own\n> inputs, outputs, pre/post-conditions and execution modes. The agents are the *default executors*\n> of those tasks — but the sequence, the rules and the dependencies come from the task definitions.\n\nA validated task is binding. It runs as configured, with its dependencies respected, regardless of\nwho executes it — an agent, a worker, a clone or a human. Swap the executor and the method is\nunchanged; that is the point.\n\nHere is a real task contract, from `squads/ceo/tasks/strategy-kernel.md`:\n\n```yaml\ntask: Build Strategy Kernel\nowner: \"@strategy-lead\"\natomic_layer: task\nInput: |\n - situation: What changed, what is not working, what the numbers say (required)\n - evidence_sources: Data, documents and observations available, each with origin and date (required)\n - constraints: Resource, contractual and capability limits already known (optional)\nOutput: |\n - diagnosis: A falsifiable claim about what is critical, with its evidence table\n - rejected_rival: The rival diagnosis considered in full, rejected with reasons or kept live\n - guiding_policy: The overall approach, and what it rules out\n - prediction: The falsifiable claim, its indicator, its disconfirming observation and check date\nChecklist:\n - \"[ ] Diagnosis stated as a claim a named observation could contradict\"\n - \"[ ] At least one rival diagnosis generated in full before the first was evaluated\"\n```\n\nInputs are named. Outputs are named. The checklist is the exit gate. Nothing about that depends on\nwhich model or which agent runs it.\n\n### Method, not impersonation\n\nAll 52 squad specialists declare a `based_on` field naming the published work their method comes\nfrom — COSO for risk oversight, the Cadbury Report for governance, and so on. Eight orchestrator\nroles declare `Original (Orchestrator)` rather than borrowing an authority they do not have.\n\nThis is load-bearing. An agent that follows a named method can be audited against the source; an\nagent doing celebrity impersonation has nothing to be verified against. The same discipline governs\nfigures: numbers from a source work are read from the publication or left unstated, because a\ncoefficient quoted from memory is a defect, not a detail.\n\n### What gets installed\n\n| | |\n| --- | --- |\n| **9** squads | Domain teams, each with a single entry agent |\n| **64** agents | 12 core roles + 52 squad specialists |\n| **291** tasks | 213 core + 78 squad-level |\n| **33** workflows | 14 core + 19 squad-level |\n| **110** templates | 35 core + 75 squad-level |\n| **62** checklists | 5 core + 57 squad-level |\n| **9,306** tests | Across 383 suites, green on `npm test` |\n\nEvery figure is counted from the tree rather than asserted. From a clone of this repository, reproduce them with\n`node scripts/validate-squads.js` (squads), `npm test` (suites and tests), and by reading the\ngenerated `.aexos-core/data/squad-registry.yaml` (agents per squad). Task, workflow, template and\nchecklist counts are the definition files under `.aexos-core/development/` and `squads/*/`.\n\n## The constitution\n\nAEXOS has a formal constitution at [`.aexos-core/constitution.md`](.aexos-core/constitution.md).\nIt is not a style guide — automatic gates block violations of the non-negotiable articles.\n\n| Article | Principle | Severity | What it means in practice |\n| --- | --- | --- | --- |\n| **I** | CLI First | NON-NEGOTIABLE | Every capability works from the command line before it has any UI |\n| **II** | Agent Authority | NON-NEGOTIABLE | Exclusive authorities cannot be assumed by another agent |\n| **III** | Story-Driven Development | MUST | Development begins and ends with a story |\n| **IV** | No Invention | MUST | Every statement in a spec traces to a requirement, constraint or research finding |\n| **V** | Quality First | MUST | Lint, typecheck and tests pass before push |\n| **VI** | Absolute Imports | SHOULD | No relative import paths |\n| **XI** | Squad-First Portability | NON-NEGOTIABLE | Artifacts stay runtime-agnostic, never locked to one IDE |\n| **XII** | Model Governance | MUST | Budget ceilings, routing authority and intent scanning when auto-dispatch is active |\n\nGate severity is graded: `BLOCK` stops execution and requires a fix; lower levels warn. See the\nconstitution for the full text, the amendment process and the gate table.\n\n### The priority hierarchy\n\n```text\nCLI First → Observability Second → UI Third\n```\n\n| Layer | Priority | What it is |\n| --- | --- | --- |\n| **CLI** | Highest | Where the intelligence lives. All execution, decisions and automation. |\n| **Observability** | Secondary | Watches what the CLI is doing, in real time. Never drives it. |\n| **UI** | Tertiary | Point management and visualisation, where a screen genuinely beats a command. |\n\nA capability that does not work from the command line does not exist yet. Dashboards observe; they\nnever control. And no UI is ever a requirement for operating the system.\n\n## Start Here (10 Min)\n\nIf this is your first time with AEXOS, follow this linear path. The target is **first value in ten\nminutes**, defined as a binary: an agent activated, a valid greeting received, and one command\nreturning useful output.\n\n### 1. Install from the repository\n\n```bash\nnpx github:CyryxLabs/AEXOS init my-project\n```\n\nThis is the only command that works from a standing start — it fetches the package straight from\nthe public repository, so nothing needs to be installed first. Verified against this revision:\n`npx github:CyryxLabs/AEXOS --version` prints `5.3.0`.\n\n> **Why the short form works.**\n> npx reads the fetched `package.json`, sees the name `@aexos/core`, and infers a binary called\n> `core` from the unscoped half of the name. `package.json` declares an explicit `core` alias in\n> `bin` for exactly that reason; without it npx exits with `could not determine executable to\n> run`. If you ever see that error, name the binary explicitly against the same spec:\n> `npx -p github:CyryxLabs/AEXOS aexos `. (`npx -p @aexos/core aexos ` is the\n> equivalent once the package is published — see [Which install command applies to\n> you](#which-install-command-applies-to-you).)\n\n### 2. Pick your IDE and activate one agent\n\n- **Claude Code:** `/agent-name`\n- **Gemini CLI:** `/aexos-menu` → `/aexos-`\n- **Codex CLI:** `/skills` → `aexos-`\n- **Cursor / Copilot / AntiGravity:** follow the constraints in [`docs/ide-integration.md`](docs/ide-integration.md)\n\n### 3. Confirm the greeting, then run one command\n\n```text\n@aexos-master\n*help\n```\n\nIf the agent greets you by persona and `*help` lists commands, you have first value. If not, run\n`aexos doctor`.\n\nDeeper walkthrough: [Getting Started](docs/getting-started.md).\n\n## Install\n\n### Prerequisites\n\n- **Node.js** 18.0.0 or later (20+ recommended)\n- **npm** 9.0.0 or later\n- **GitHub CLI** — optional, needed for team collaboration flows\n\n### Which install command applies to you\n\nThe three contexts are genuinely different, and a command from one will not work in another:\n\n| Your situation | Command | Status |\n| --- | --- | --- |\n| Nothing installed yet | `npx github:CyryxLabs/AEXOS init my-project` | Works today |\n| Package already resolvable (local link, or a registry you have access to) | `npx github:CyryxLabs/AEXOS install` | Needs the package to resolve first |\n| Contributing to AEXOS itself | `git clone` → `npm install` → `npm link` | Works today |\n\n`@aexos/core` is **not yet published to the public npm registry** — the earlier names\n`aexos-core` and `@aexos-squads/core` return 404 there. That is a distribution decision, not a\nlicensing one: the\n[LICENSE](LICENSE) grants the Core Edition free of charge, and Section 2 expressly permits\ninstalling it from a package registry. So `npx github:CyryxLabs/AEXOS install` is the documented form for reinstalling or updating\ninside a project that already resolves the package (it is what `docs/installation/` uses), not a\nfirst-run command.\n\nTo work on the framework itself, or to get the `aexos` binary on your PATH:\n\n```bash\ngit clone https://github.com/CyryxLabs/AEXOS.git\ncd AEXOS\nnpm install\nnpm link\ncd your-project && aexos install\n```\n\nThe installer is an interactive wizard. It detects an existing installation and updates in place\nrather than overwriting, so re-running it is safe. Useful flags:\n\n```bash\naexos install --dry-run # show what would change, touch nothing\naexos install --yes # accept defaults, no prompts\naexos install --ide claude # configure one IDE explicitly\naexos install --ci # non-interactive, for pipelines\n```\n\n### Step 2 — verify\n\nThese need the `aexos` binary on your PATH, which `npm link` or a global install provides. Inside a\nproject that has AEXOS but no global binary, prefix them with `npx`.\n\n```bash\naexos doctor # diagnostics: Node, npm, git, install integrity\naexos validate # verify installation integrity file by file\naexos info # what is installed, and where\n```\n\n`aexos doctor --fix` and `aexos validate --repair` resolve most problems without reinstalling.\n\n### Step 3 — keep it current\n\n```bash\naexos update --check # is there a newer version?\naexos update --dry-run # what would change\naexos update # apply\n```\n\nFull platform matrix for Linux, macOS and Windows:\n[Installation Guide](docs/installation/README.md). If something goes wrong:\n[Troubleshooting](docs/troubleshooting.md).\n\n## Your first session, step by step\n\n[Start Here](#start-here-10-min) gets you to first value. This is the same path with the reasoning\nfilled in, plus what comes after it.\n\n**1. Open your agent surface.** Claude Code, Gemini CLI, Codex CLI or another supported platform —\nsee [the table below](#activating-an-agent-in-your-ide) for the activation syntax yours uses.\n\n**2. Activate the orchestrator.**\n\n```text\n@aexos-master\n```\n\nYou should get a greeting naming the persona (Zeus) and its role. If you do not, the install did\nnot complete — run `aexos doctor`.\n\n**3. Ask it what it can do.** Every agent responds to `*`-prefixed commands:\n\n```text\n*help\n```\n\n**4. Ask for something in plain language.** The orchestrator reads the squad registry, matches your\nrequest to a domain and routes it:\n\n```text\nI need to decide whether to build this feature or buy it.\n```\n\nThat is a capital allocation question, so it routes to `@ceo-chief`, which triages to\n`@capital-allocator`. You never had to know the handle.\n\n**5. Or address a specialist directly**, when you already know who you want:\n\n```text\n@architect\n*assess-complexity\n```\n\n**6. Work from a story.** Development in AEXOS begins with a story — a file that carries the full\ncontext an implementing agent needs. The standard cycle:\n\n```text\n@sm *draft → create the story from an epic or PRD\n@po *validate-story-draft → 10-point check, GO or NO-GO\n@dev *develop → implement against the acceptance criteria\n@qa *gate → quality gate: PASS / CONCERNS / FAIL / WAIVED\n@devops *push → the only agent permitted to push\n```\n\n**7. Exit an agent** with `*exit` when you want to switch personas.\n\nNew to the workflow? The [User Guide](docs/guides/user-guide.md) walks the planning phase and the\ndevelopment cycle end to end. [Getting Started](docs/getting-started.md) covers the first session in\nmore depth.\n\n## Activating an agent in your IDE\n\nAdvanced behaviour depends on lifecycle hooks, and platforms differ in what they expose. Where hooks\nare unavailable the framework still works — you run the validators yourself instead of having them\nfire automatically.\n\n| Platform | How to activate | Lifecycle hooks | What you give up |\n| --- | --- | --- | --- |\n| **Claude Code** | `/agent-name` | Full (reference) | Nothing — full automation, guardrails, audit trail |\n| **Gemini CLI** | `/aexos-menu` → `/aexos-` | Native events | Minor timing differences only |\n| **Codex CLI** | `/skills` → `aexos-` | Partial | Some checks need a manual trigger; leans on `AGENTS.md` and MCP |\n| **Cursor** | `@agent` + synced rules | None | No pre/post-action checks; run validators manually |\n| **GitHub Copilot** | Chat modes + repo instructions | None | As Cursor, plus more manual workflow |\n| **AntiGravity** | Workflow-driven | Workflow-based | No hook equivalents; use the generated workflows |\n\nFastest path for a new user: **Claude Code** or **Gemini CLI**. Detail, per-capability consequences\nand workarounds: [IDE Integration Guide](docs/ide-integration.md).\n\nAgent definitions are synced into each platform's own format, so the same roster is available\neverywhere:\n\n```bash\nnpm run sync:ide:codex # regenerate Codex skills\nnpm run validate:parity # confirm every platform is in step\n```\n\n## The core team\n\nTwelve roles covering the software lifecycle. Each has a persona, a scope, and a set of tasks it is\nthe default executor for.\n\nEvery agent responds to `*`-prefixed commands. `*help` lists the full set for whichever agent is\nactive; the column below is a representative sample, not the whole surface.\n\n| Handle | Persona | Role | Sample commands |\n| --- | --- | --- | --- |\n| `@aexos-master` | Zeus | Master orchestrator & framework developer | `*help`, `*status`, `*kb`, `*guide` |\n| `@analyst` | Sirius | Business analyst | `*create-project-brief`, `*research-deps`, `*extract-patterns` |\n| `@pm` | Janus | Product manager | `*create-prd`, `*create-epic`, `*execute-epic`, `*write-spec` |\n| `@po` | Themis | Product owner | `*validate-story-draft`, `*backlog-prioritize`, `*close-story` |\n| `@sm` | Chronos | Scrum master | `*draft`, `*story-checklist` |\n| `@architect` | Vega | Architect | `*create-plan`, `*create-full-stack-architecture`, `*assess-complexity`, `*document-project` |\n| `@dev` | Vulcan | Full stack developer | `*develop`, `*execute-subtask`, `*apply-qa-fixes` |\n| `@qa` | Argus | Test architect & quality advisor | `*review`, `*gate`, `*risk-profile`, `*critique-spec` |\n| `@data-engineer` | Ceres | Database architect & operations engineer | `*create-schema`, `*create-rls-policies`, `*design-indexes` |\n| `@devops` | Polaris | Repository manager & DevOps specialist | `*pre-push`, `*push`, `*create-pr`, `*release`, `*create-worktree` |\n| `@ux-design-expert` | Iris | UX/UI designer & design system architect | `*audit`, `*tokenize`, `*build`, `*a11y-check` |\n| `@squad-creator` | Arkantos | Squad creator | `*design-squad`, `*create-squad`, `*validate-squad` |\n\n### Authority is exclusive by design\n\nArticle II is non-negotiable, and the boundaries are real:\n\n| Operation | Exclusive to | Everyone else |\n| --- | --- | --- |\n| `git push`, `git push --force` | `@devops` (Polaris) | Blocked — delegate |\n| `gh pr create`, `gh pr merge` | `@devops` | Blocked — delegate |\n| Releases and tags | `@devops` | Blocked |\n| MCP add / remove / configure | `@devops` | Blocked |\n| Story creation (`*draft`) | `@sm` | Delegate |\n| Story validation | `@po` | Delegate |\n| Epic orchestration | `@pm` | Delegate |\n| Architecture decisions | `@architect` | Delegate |\n| Quality verdicts | `@qa` | Delegate |\n\n`@dev` may `add`, `commit`, `branch`, `checkout`, `merge` and `stash` locally — but never push. Full\nmatrix and escalation rules: [`.claude/rules/agent-authority.md`](.claude/rules/agent-authority.md).\n\n## The squads\n\nNine squads extend the framework past software delivery into the rest of a company. Each has one\nfront door — the chief — which triages the incoming question and distributes internally. You address\nthe chief; you do not need to know the roster.\n\n| Entry agent | Squad | Agents | Domain |\n| --- | --- | ---: | --- |\n| `@ceo-chief` | CEO | 5 | Strategy, capital allocation and organisation design |\n| `@board-chief` | Board | 5 | Governance, risk oversight, audit and succession |\n| `@products-chief` | Products | 7 | Discovery, positioning, monetisation, experimentation |\n| `@marketing-chief` | Marketing | 7 | Brand, demand and measurement |\n| `@sales-chief` | Sales | 5 | Qualification, method and negotiation |\n| `@ops-chief` | Operations | 5 | Reliability, flow and continuous improvement |\n| `@cs-chief` | Customer Success | 5 | Onboarding, retention and expansion |\n| `@admin-chief` | Business Administration | 5 | Finance, people, legal operations and process |\n| `@claude-mastery-chief` | Claude Code Mastery | 8 | Hooks, MCP, config, swarm, plugins, integration |\n\nEach squad ships its own `README.md` describing its philosophy and its agents — start with\n[`squads/ceo/README.md`](squads/ceo/README.md) or\n[`squads/products/README.md`](squads/products/README.md) for the pattern.\n\n### Routing is generated, not hardcoded\n\n`.aexos-core/data/squad-registry.yaml` is generated from `squads/*/squad.yaml` by\n`scripts/generate-squad-registry.js` and must never be hand-edited. The orchestrator reads it to\nroute by domain and keyword.\n\nThe consequence: **adding a squad requires no change to the orchestrator.** Creating the squad and\nregenerating the registry is what registers it. A squad on disk that never reached the registry is\nnot reachable — which is why the registry, not the directory listing, is the source of truth.\n\n## Workflows\n\nFour primary workflows. Each is a sequence of connected tasks with defined transitions.\n\n### 1. Story Development Cycle — the primary path\n\n| Phase | Agent | Task | Output |\n| --- | --- | --- | --- |\n| 1. Create | `@sm` | `create-next-story.md` | `{epic}.{story}.story.md`, status Draft |\n| 2. Validate | `@po` | `validate-next-story.md` | GO (≥7 of 10) or NO-GO with required fixes |\n| 3. Implement | `@dev` | `dev-develop-story.md` | Status Ready → InProgress |\n| 4. QA gate | `@qa` | `qa-gate.md` | PASS / CONCERNS / FAIL / WAIVED → Done |\n\n`@dev` runs the implement phase in one of three modes — `*develop-interactive`, `*develop-yolo` or\n`*develop-preflight` — depending on how much you want to be consulted along the way.\n\n### 2. QA Loop — iterative review\n\nDefined in [`workflows/qa-loop.yaml`](.aexos-core/development/workflows/qa-loop.yaml). An automated\nreview-fix cycle after the initial gate: `@qa` reviews and returns a verdict, `@dev` fixes,\nre-review — to a maximum of five iterations before escalation.\n\n```text\n@qa *review → verdict on the implementation\n@qa *create-fix-request → a structured, addressable fix list\n@dev *apply-qa-fixes → work the list\n@qa *gate → re-gate\n```\n\nVerdicts route the loop: approve and it completes; reject and it returns to `@dev`; blocked and it\nescalates immediately rather than burning iterations.\n\n### 3. Spec Pipeline — before implementation\n\nTurns an informal requirement into an executable spec. Complexity is scored across five dimensions\n— scope, integration, infrastructure, knowledge and risk — and the score decides how many phases run.\n\n| Score | Class | Phases |\n| --- | --- | --- |\n| ≤ 8 | SIMPLE | gather → spec → critique (3) |\n| 9–15 | STANDARD | all 6 |\n| ≥ 16 | COMPLEX | all 6, plus a revision cycle |\n\nThe pipeline runs `@pm *gather-requirements` → `@architect *assess-complexity` →\n`@analyst *research-deps` → `@pm *write-spec` → `@qa *critique-spec` → `@architect *create-plan`,\nwhich is the phase-to-command mapping declared in\n[`spec-pipeline.yaml`](.aexos-core/development/workflows/spec-pipeline.yaml) itself.\n\nThe critique phase yields `APPROVED` (≥ 4.0), `NEEDS_REVISION` (3.0–3.9) or `BLOCKED` (< 3.0). The\nconstitutional gate here is Article IV: every statement in the spec must trace to a requirement, a\nconstraint or a research finding. No invented features.\n\n### Running stories in parallel\n\nIndependent stories can be worked in isolated git worktrees rather than serialised on one branch.\n`@devops *create-worktree` provisions one (`*list-worktrees`, `*merge-worktree`, `*cleanup-worktrees`\nmanage the rest); `@dev` has its own `*worktree-create` and `*waves` for planning a multi-story\nbatch, and `aexos wave plan --stories a,b` produces the execution DAG from the command line.\n\n### 4. Brownfield Discovery — assessing an existing codebase\n\nTen phases across data collection, drafting, specialist validation and finalisation, producing a\ntechnical debt assessment, an executive report, and an epic with stories ready for development.\n\nWhich one to use:\n\n| Situation | Workflow |\n| --- | --- |\n| New story from an epic | Story Development Cycle |\n| QA found issues needing iteration | QA Loop |\n| Complex feature needing a spec | Spec Pipeline, then SDC |\n| Joining an existing project | Brownfield Discovery |\n| Simple bug fix | SDC in YOLO mode |\n\nDefinitions: [`.aexos-core/development/workflows/`](.aexos-core/development/workflows/). Rules:\n[`.claude/rules/workflow-execution.md`](.claude/rules/workflow-execution.md).\n\n## Quality gates\n\nThree layers, defence in depth:\n\n| Layer | When | What runs |\n| --- | --- | --- |\n| **1. Pre-commit** | Local, fast | ESLint, TypeScript — fast enough to stay in the loop |\n| **2. Pre-push** | Local | Story acceptance criteria and status checks |\n| **3. CI** | Cloud, merge gate | Full suite plus the structural validators below |\n\nThe framework also validates its own shape. Squad manifests are checked against a JSON schema,\nevery dependency an agent declares must resolve on disk, generated registries must be\nbyte-reproducible, and the per-IDE syncs must stay in step with the agent definitions.\n\nThese run **inside a clone of this repository** — `tests/` and the Jest config are not in the\npackage's `files` list, so they are not present in a project that merely installed AEXOS:\n\n```bash\nnpm run lint # ESLint\nnpm run typecheck # TypeScript\nnpm test # Jest — 9,306 tests across 383 suites\nnpm run validate:squads # manifests, registry determinism, agent dependencies\nnpm run validate:parity # IDE compatibility contract\n```\n\nWarnings are treated as failures: each one names a missing field, a stale reference or a deprecated\nshape.\n\n## Building your own squad\n\nA squad is a directory. Its shape is the mental model made concrete:\n\n```text\nsquads/your-squad/\n├── squad.yaml # identity, domain, keywords, entry agent — feeds the registry\n├── agents/ # the specialists, one file each\n├── tasks/ # the procedures — where the method lives\n├── templates/ # the documents tasks produce\n├── checklists/ # the validation tasks must pass\n├── data/ # the knowledge base tasks read from\n├── workflows/ # task sequences\n├── README.md # what this squad is for\n└── CHANGELOG.md\n```\n\nThen regenerate the registry and validate — from a clone of this repository, where `scripts/` sits at the root:\n\n```bash\nnode scripts/generate-squad-registry.js\nnode scripts/validate-squads.js\n```\n\n`@squad-creator` (Arkantos) scaffolds this for you. Full instructions:\n[Squads Guide](docs/guides/squads-guide.md) and\n[Contributing Squads](docs/guides/contributing-squads.md).\n\n## CLI reference\n\nAll of these need the `aexos` binary, so they assume a global install or `npm link`;\notherwise prefix with `npx`. See [which install command applies to you](#which-install-command-applies-to-you).\n\n```bash\n# Lifecycle\naexos install [--dry-run|--yes|--ci|--ide ] # install or update in this project\naexos init # scaffold a new project\naexos update [--check|--dry-run|--force] # update to the latest version\naexos uninstall [--force|--dry-run|--keep-data] # remove AEXOS\n\n# Health\naexos doctor [--fix] # diagnostics\naexos validate [--repair|--detailed] # installation integrity\naexos info # system information\naexos --version [-d] # version, optionally detailed\n\n# Configuration\naexos config show [--debug] # resolved configuration\naexos config diff --levels L1,L2 # compare configuration levels\naexos config validate # validate config files\n\n# Execution\naexos sdc plan # plan a story development cycle\naexos sdc next # next SDC phase and its skill\naexos wave plan --stories a,b # multi-story execution DAG\naexos workers search # service discovery\naexos-delegate codex -t # delegate to an external executor\n```\n\n`aexos --help` prints the complete surface.\n\n## Framework and project boundary\n\nAEXOS separates its own artifacts from yours across four layers. Deny rules in\n`.claude/settings.json` enforce this deterministically rather than by convention.\n\n| Layer | Mutability | Paths |\n| --- | --- | --- |\n| **L1** Framework core | Never modify | `.aexos-core/core/`, `.aexos-core/constitution.md`, `bin/` |\n| **L2** Framework templates | Never modify — extend only | `.aexos-core/development/{tasks,templates,checklists,workflows}/`, `.aexos-core/infrastructure/` |\n| **L3** Project config | Mutable, with exceptions | `.aexos-core/data/`, `agents/*/MEMORY.md`, `core-config.yaml` |\n| **L4** Project runtime | Always modify | `docs/stories/`, `packages/`, `squads/`, `tests/` |\n\nThe toggle is `core-config.yaml` → `boundary.frameworkProtection`, which defaults to `true` for\nprojects and `false` for framework contributors.\n\n## Documentation\n\n| | |\n| --- | --- |\n| [User Guide](docs/guides/user-guide.md) | Planning phase, development cycle, all agent roles |\n| [Getting Started](docs/getting-started.md) | First session, end to end |\n| [Installation Guide](docs/installation/README.md) | Linux, macOS, Windows |\n| [IDE Integration](docs/ide-integration.md) | Platform matrix, capabilities and workarounds |\n| [Squads Guide](docs/guides/squads-guide.md) | Building a squad for your own domain |\n| [Agent Selection Guide](docs/guides/agent-selection-guide.md) | Which agent for which job |\n| [Quality Gates](docs/guides/quality-gates.md) | The validation pipeline in detail |\n| [Guiding Principles](docs/GUIDING-PRINCIPLES.md) | Philosophy and practice |\n| [Glossary](docs/glossary.md) | Terminology |\n| [Troubleshooting](docs/troubleshooting.md) | When something does not come up |\n| [Security](docs/security.md) | Reporting and hardening |\n| [CHANGELOG](CHANGELOG.md) | Release history |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Note Article II:\nonly `@devops` opens pull requests and pushes to the remote.\n\n## Licence\n\n[AEXOS Licence v1.0](LICENSE) © 2026 Cyryx Labs LLC. All rights reserved.\n\nThe Core Edition is free of charge for personal, internal and commercial use,\nincluding work you deliver commercially to third parties. You are not required to\ndisclose or share what you build with it. The Pro Edition requires a separate\npaid agreement. Redistributing AEXOS itself — forks, mirrors, or hosted products\nwhose value is AEXOS's own functionality — is not permitted; see Section 3.\n\n

\n AEXOS by Cyryx Labs · CLI First · Observability Second · UI Third\n

\n","readmeFilename":"README.md","_rev":"1-2193898ed2ee6423adf2030b650ea705"}