Skip to content

docs: multi-manifest repo layout + tag-pin install contract - #36

Merged
ennru merged 8 commits into
mainfrom
feat/ap-1-0-manifest
Sep 14, 2026
Merged

ennru merged 8 commits into
mainfrom
feat/ap-1-0-manifest

Conversation

@TylerJewell

@TylerJewell TylerJewell commented Sep 13, 2026 •

Copy link
Copy Markdown
Contributor

Background

Akka's website has grown busy enough that the Get-Started sequence is hard to find. doc.akka.io documents 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.io will become:

Ask your AI to install Akka from akka.ai.

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 on akka.ai is the AI-facing install playbook and the small set of artifacts it references. Marketing content stays on akka.io; SDK reference stays on doc.akka.io.

What this PR changes

Docs-only changes to README.md and HARNESSES.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 that plugin.json at the root does double duty for Antigravity and AP 1.0 (both align with agent-plugins.org/schemas/1.0.0/plugin.schema.json). Names the harnesses that install via akka specify init rather 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:setup skill section. Documents the canonical stable path skills/setup/SKILL.md that akka.ai/setup will alias.
  • README.md โ€” Version pinning section. Documents the "install pins to @stable, never main" contract from RELEASING.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 "when main is safe" path pending upstream support.
  • README.md โ€” Installation walkthrough. Adds Gemini CLI section for parity with HARNESSES.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 to skills/.

Sibling PRs (AI-install rollout)

The 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)

  • Cut the next stable release via the version-bump workflow so the playbook's @stable references resolve to a version that includes any related runtime changes. (Owner: Enno.)
  • Verify or link the git-ref pinning story for agy, gemini, and codex marketplace commands as those harnesses' installers evolve.
  • Publish akka.ai/setup as an alias to skills/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

TylerJewell and others added 6 commits September 13, 2026 07:37
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>
Comment thread README.md Resolved
Comment thread HARNESSES.md Resolved
Comment thread HARNESSES.md Resolved
Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com>
Comment thread HARNESSES.md Resolved
Comment thread README.md Resolved
Comment thread README.md Resolved
Co-authored-by: Enno Runne <458526+ennru@users.noreply.github.com>
@ennru
ennru merged commit 765e35d into main Sep 14, 2026
7 checks passed
@ennru
ennru deleted the feat/ap-1-0-manifest branch September 14, 2026 14:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants