Repository navigation
docs: multi-manifest repo layout + tag-pin install contract - #36
Merged
Merged
Conversation
The repo already ships the Agent Plugins 1.0 manifest at the root (plugin.json + mcp.json + skills/) alongside the four existing per-harness manifests, and HARNESSES.md documents the full mapping. The README did not surface either the multi-manifest posture or the "install pins to a tag, never main" contract that the AI-install playbook at akka.ai/ relies on. Add two sections to README.md: - Repository layout โ one repo, four manifests: table of which manifest each harness reads, points at HARNESSES.md for detail, and names skills/setup/SKILL.md as the canonical path that akka.ai/setup aliases. - Version pinning โ install pins to a tag, never main: states the contract and points at RELEASING.md for the tag-cutting workflow. No manifest, skill, or generator changes โ the AP 1.0 tree is already in place and reuses the same skills/ directory the Codex target emits, so there is no duplicated content to add. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Review feedback on the layout section: - Heading said "four manifests" while the table had five rows. - Antigravity was on the `.agents/` row, but `.agents/` is Codex's directory; Antigravity reads `plugin.json` + `mcp_config.json`. - `mcp_config.json` was missing from the table entirely. - AP 1.0 row listed shipping harnesses as consumers, but HARNESSES.md explicitly notes no harness reads AP 1.0 files today. Rewritten to match HARNESSES.md exactly and to be honest about AP 1.0 being additive. Version-pinning section: lead with `@stable` (matches RELEASING.md's floating-tag contract and the `akka specify init --channel stable` CLI mechanism); use `vX.Y.Z` as the alternative form so the example doesn't bit-rot on the next release. Extended the disclaimer about unpinned snippets to name all of them, not just Claude Code, and flagged pinning them as follow-up. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Second review pass. Changes:
- Pin the Claude Code and Antigravity install snippets at the top of
the README to `akka/ai-marketplace@stable`. The visible contract
("every install command references stable") no longer disagrees
with the visible snippets; the "follow-up will pin" caveat is
dropped as unnecessary.
- Remove "and Claude Tag" from the layout table row: HARNESSES.md
lists Claude Code only for that manifest, and the two files must
agree.
- Explain HOW `plugin.json` serves both Antigravity and AP 1.0: the
schema URL declared in the file itself points at
`agent-plugins.org/schemas/1.0.0/plugin.schema.json`, and
Antigravity's plugin metadata schema aligns with it.
- Move the `/akka:setup` skill paragraph into its own subsection so
it is no longer orphaned inside the manifest-layout table.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Third review pass. Fixes: - `agy plugin install` does not accept a git-ref pin today (verified from Antigravity docs โ install accepts a URL but not `@ref`). Reverted the top-of-README agy snippet to the bare URL and added a short caveat pointing at the version-pinning section, which now names `agy` and `gemini` explicitly as the two harnesses whose installers cannot pin yet, treats that gap as an upstream request, and calls release cadence the mitigation. - Softened the version-pinning lead from "every install command references stable" to "where a harness's install command accepts a git ref, we pin to stable" โ matches reality across README and HARNESSES.md. - Pinned the Claude Code and Codex entries in HARNESSES.md's install table to `@stable` (both harnesses support git-ref pinning) so the README's claim holds across both files. Added the same "installs from default branch" caveat next to the agy and gemini rows in HARNESSES.md. - Moved `/akka:setup` out of the Repository-layout section entirely; it is now its own top-level `## /akka:setup skill โ stable path for aliases` heading. Prior "orphaned inside manifest-layout" finding fully resolved. - Reordered the layout table (Claude Code / Antigravity / Gemini / Codex / AP 1.0) to match HARNESSES.md's own row order. - Compressed the AP 1.0 table cell to one line; the detail moves to a short paragraph beneath the table (was overstuffed as a cell). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Fourth review pass, small fixes: - Installation walkthrough was missing Gemini CLI even though HARNESSES.md treats it as first-class. Added a Gemini section next to Codex with the same install command and the same "no git-ref pinning today" caveat that agy carries. - Softened the version-pinning-section wording from "tracked as an upstream request in each harness" to "not yet available" โ no linked issue to cite for either harness, so the softer claim is the honest one. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- HARNESSES.md line 16: revert my `@stable` on the Codex marketplace command. The `codex plugin marketplace add` git-ref pinning syntax is not verified from public docs, so leaving it pinned overstates the guarantee. Added the same caveat next to it that agy and gemini carry, and named Codex in the README's pinning-gap paragraph. - HARNESSES.md line 58: replace the hard-coded "22 skills" count with "the skills under `skills/`" so the sentence doesn't bit-rot when the skill inventory changes. - README layout-table lead: add a short qualifier that Cursor and GitHub Copilot in VS Code install into the workspace via `akka specify init` and don't read a repo-root manifest, so the "must stay in sync with HARNESSES.md" claim covers the harnesses the table actually enumerates. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
ennru
reviewed
Sep 14, 2026
Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com>
ennru
reviewed
Sep 14, 2026
Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com>
ennru
approved these changes
Sep 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Background
Akka's website has grown busy enough that the Get-Started sequence is hard to find.
doc.akka.iodocuments several installation techniques and we have simplified them substantially, but visitors are still struggling to land on the right page.What we are doing. Instead of directing humans to a docs page, we give a single instruction to their AI coding assistant, and the AI handles the rest โ regardless of which harness they run. The CTA on
akka.iowill become:The user pastes "install Akka from akka.ai" into their harness. Their AI fetches the playbook at
akka.ai/, identifies the harness, picks the right install path, previews the whole plan to the user, then walks them through it with a consent prompt at every step.Why
akka.ai. Search engines conflate "install Akka" with the CLI, the SDK libraries, the Claude plugin, and several other install paths. A dedicated domain removes the ambiguity. The only content onakka.aiis the AI-facing install playbook and the small set of artifacts it references. Marketing content stays onakka.io; SDK reference stays ondoc.akka.io.What this PR changes
Docs-only changes to
README.mdandHARNESSES.md. No code, tests, or manifests touched.README.mdโ Repository layout section. Documents that the repo carries multiple root manifests side by side, one per harness (Claude Code, Antigravity CLI, Gemini CLI, Codex CLI, and the additive AP 1.0 manifest). Explains thatplugin.jsonat the root does double duty for Antigravity and AP 1.0 (both align withagent-plugins.org/schemas/1.0.0/plugin.schema.json). Names the harnesses that install viaakka specify initrather than a root manifest (Cursor, GitHub Copilot in VS Code) so the "must stay in sync with HARNESSES.md" claim covers exactly what the table enumerates.README.mdโ/akka:setupskill section. Documents the canonical stable pathskills/setup/SKILL.mdthatakka.ai/setupwill alias.README.mdโ Version pinning section. Documents the "install pins to@stable, nevermain" contract fromRELEASING.md. Names the harnesses whose installers do not yet accept a@ref(agy plugin install,gemini extensions install,codex plugin marketplace addโ Codex is unverified from public docs) and treats those as a "whenmainis safe" path pending upstream support.README.mdโ Installation walkthrough. Adds Gemini CLI section for parity withHARNESSES.md. Claude Code snippet now pins to@stable.HARNESSES.mdโ Install table. Pinned Claude Code entry to@stable. Added the same "installs from default branch" caveat to agy, gemini, and codex rows. Replaced the hard-coded "22 skills" count with a reference toskills/.Sibling PRs (AI-install rollout)
feat: akka mcp serve tool surface, agent-neutral AGENTS.md, verified --agent profilesโ https://github.com/akka/cli/pull/193docs: AI-install support matrix, MCP registration reference, akka.ai entryโ docs: AI-install harness matrix, MCP registration reference, akka.ai entryย akka-sdk#1877The three PRs are safe to merge independently. This PR is docs-only; the CLI PR is the load-bearing capability work; the akka-sdk PR is the docs-site companion.
Follow-ups (not in this PR)
stablerelease via the version-bump workflow so the playbook's@stablereferences resolve to a version that includes any related runtime changes. (Owner: Enno.)agy,gemini, andcodexmarketplace commands as those harnesses' installers evolve.akka.ai/setupas an alias toskills/setup/SKILL.md.Reviewed
Six rounds of
/akka-pr-review(independent read-only agent). Verdict: READY TO PUSH; remaining findings are nits that are yours to take or leave.๐ค Generated with Claude Code