# Akka AI Marketplace Plugin marketplace for AI-assisted Akka SDK development. ## Installation ### Claude Code (plugin) ``` /plugin marketplace add akka/ai-marketplace@stable /plugin install akka@ai-marketplace /reload-plugins /akka:setup ``` ### Antigravity (`agy`) ```bash agy plugin install https://github.com/akka/ai-marketplace ``` `agy plugin install` does not accept a git-ref pin today, so this command installs from the default branch. See the version-pinning section below for the gap this introduces and how to work around it. ### Codex Codex can use the same Akka workflow from the `plugins/akka` directory. That plugin package includes a Codex manifest, an Akka MCP config using `akka mcp serve --disable-prompt`, and Codex skill aliases for the Akka workflows. ### Akka CLI (any AI agent) If you're using Cursor, Windsurf, VS Code Copilot, or another AI coding agent — or prefer to set up manually — use the [Akka CLI](https://doc.akka.io/operations/cli/installation.html): ```bash # Install the Akka CLI (see link above for all platform) brew install akka/brew/akka # macOS # Initialize your project — use the --agent flag for your editor akka specify init . --agent cursor akka specify init . --agent vscode-copilot akka specify init . --agent claude-code ``` The `--agent` flag controls where commands are installed: | Agent | Flag | Commands installed to | | --------------- | ------------------------ | --------------------- | | Claude Code | `--agent claude-code` | `.claude/commands/` | | Cursor | `--agent cursor` | `.cursor/rules/` | | VS Code Copilot | `--agent vscode-copilot` | `.github/prompts/` | This produces the same result as the Claude Code plugin: skills, templates, documentation, and MCP server configuration installed in your project directory. For Codex, use the repo-local plugin files under `plugins/akka`. ## Getting Started After installing via either path, run the setup command in your project directory: - **Plugin:** `/akka:setup` - **CLI-installed:** `/akka.setup` It will: 1. Detect your OS and install any missing dependencies (Java 21+, Maven 3.9+, Akka CLI) 2. Configure the Akka download token for Maven 3. Scaffold a new Akka project (or repair/upgrade an existing one) 4. Download SDK documentation and AI context 5. Optionally configure Docker and AI API keys Zero prerequisites beyond having a supported AI coding agent installed. ## Commands | Plugin (Claude Code) | CLI-installed | Description | | -------------------- | -------------------- | -------------------------------------------------------- | | `/akka:setup` | `/akka.setup` | Set up a complete Akka development environment | | `/akka:constitution` | `/akka.constitution` | Create or update the project constitution | | `/akka:specify` | `/akka.specify` | Create or update a feature specification | | `/akka:clarify` | `/akka.clarify` | Resolve open questions in specs or plans | | `/akka:plan` | `/akka.plan` | Generate an implementation plan from a spec | | `/akka:tasks` | `/akka.tasks` | Break a plan into ordered, testable tasks | | `/akka:analyze` | `/akka.analyze` | Analyze codebase for patterns and issues | | `/akka:checklist` | `/akka.checklist` | Generate implementation or review checklists | | `/akka:implement` | `/akka.implement` | Execute tasks from the task list | | `/akka:harnesses` | `/akka.harnesses` | Generate the enterprise-configuration assets required | | `/akka:converge` | `/akka.converge` | Queue remaining work the spec and plan still require | | `/akka:review` | `/akka.review` | Review code against spec and constitution | | `/akka:build` | `/akka.build` | Build, test, and run the service locally | | `/akka:inspect` | `/akka.inspect` | Inspect a deployed service | | `/akka:reliability` | `/akka.reliability` | Add or remove resilience-testing instrumentation | | `/akka:deploy` | `/akka.deploy` | Deploy to the Akka platform | | `/akka:issues` | `/akka.issues` | Track and manage issues | | `/akka:status` | `/akka.status` | Show the definition-of-done rollup, read-only | | `/akka:conform` | `/akka.conform` | Run the auditors and return the ship-readiness verdict | | `/akka:ship` | `/akka.ship` | Run the auditors and, on pass, run the ship steps | | `/akka:mode` | `/akka.mode` | Switch between Enforced and À la carte modes | | `/akka:docs` | `/akka.docs` | Generate rendered project documentation into `docs/` | | `/akka:visualize` | `/akka.visualize` | Generate Mermaid diagrams from a feature's spec and plan | Visualization is optional. Run `/akka:visualize` explicitly to generate or refresh diagrams. Spec and plan commands leave diagrams untouched and mention existing diagrams that may be stale; visualize checks source hashes on its next run. > **Migrating from `akka-specify`?** The `akka-specify` plugin is still available but deprecated. Uninstall it and install `akka` instead. ## Repository layout — one repo, multiple manifests The repo root carries several manifests side by side so a single source of truth ships to every harness. Each harness reads only its own files; [HARNESSES.md](HARNESSES.md) is the authoritative mapping and this table must stay in sync with it. This table covers the harnesses that read a root manifest directly. Cursor and GitHub Copilot in VS Code install into the workspace via `akka specify init --agent cursor` and `--agent vscode-copilot` respectively; they do not read a repo-root manifest. | Root manifest files | Read by | | --- | --- | | `.claude-plugin/marketplace.json` + `plugins/akka/` | Claude Code | | `plugin.json` + `mcp_config.json` | Antigravity CLI (`agy`) | | `.agents/plugins/marketplace.json` + `.codex-plugin/plugin.json` | Codex CLI | | `plugin.json` + `mcp.json` ([Agent Plugins 1.0](https://agent-plugins.org/specification)) | No harness reads these today; additive for future AP 1.0 clients. See the AP 1.0 notes below. | `plugin.json` at the root does double duty: it is the Antigravity manifest *and* the AP 1.0 manifest. Antigravity's plugin metadata schema aligns with `agent-plugins.org/schemas/1.0.0/plugin.schema.json` — the schema URL is declared inside the file itself — so a single `plugin.json` serves both harnesses. `mcp_config.json` and `mcp.json` are distinct files because Antigravity and AP 1.0 look for MCP configuration at different filenames; both carry the same `mcpServers` payload. **Agent Plugins 1.0 posture.** The AP 1.0 files are additive: the `skills//SKILL.md` tree is the same one the Codex target emits, so there is no second copy. Commands are out of scope in AP 1.0 v1, so an AP 1.0 client that ships would reach the workflow through the 23 skills and the MCP toolset, not through `/akka:*` slash commands. ## `/akka:setup` skill — stable path for aliases The canonical location for the `/akka:setup` skill is [`skills/setup/SKILL.md`](skills/setup/SKILL.md). `akka.ai/setup` aliases this path, so link to the repo file rather than copying the content. ## Version pinning — install pins to `@stable` where the harness supports it Where a harness's install command accepts a git ref, this README and every downstream install command pin to `stable` (a floating pointer advanced on each release cut) or a specific `vX.Y.Z` tag: ``` akka/ai-marketplace@stable akka/ai-marketplace@vX.Y.Z ``` `main` moves ahead of what has been validated end-to-end, so an install that resolves against `main` can pull an unreleased marketplace against a released CLI. `stable` and every released `vX.Y.Z` tag are the only refs safe to install from. The tag-cutting workflow and the `stable`-tag contract are in [RELEASING.md](RELEASING.md); the CLI mechanism that consumes them (`akka specify init --channel stable` vs `--channel edge`) is documented in the Akka CLI docs. **Harnesses whose installers do not yet support git-ref pinning.** `agy plugin install` accepts a URL but not a `@ref`, so both install from the default branch today. `codex plugin marketplace add` may accept a `@ref` — the syntax is not verified from public docs — so its install commands are left unpinned until confirmed. Until git-ref pinning is available (or verified) for each of these harnesses, treat those installs as a "when `main` is safe" path — release cadence is the mitigation, not per-install pinning. ## Attribution The spec-driven development workflow (specify, plan, tasks, clarify, analyze, checklist, issues) is built on [SpecKit](https://github.com/github/spec-kit), adapted for the Akka SDK with MCP tool integration. The build, conform, constitution, converge, deploy, docs, harnesses, implement, inspect, mode, reliability, review, setup, ship, and status skills are original to Akka. The visualize skill is adapted from the `diagrams` skill in the [akka-ext plugin](https://github.com/aklikic/akka-ext-plugin). ## License See [LICENSE](LICENSE) for details.