From 17d8e52b7cba0b7dff6ceb516ca4fc9a0eb264d1 Mon Sep 17 00:00:00 2001 From: vam Date: Sat, 5 Sep 2026 11:54:33 +0800 Subject: [PATCH] docs: map shared core to native adapters --- README.md | 52 +++++++++++---------------------------- docs/antigravity-setup.md | 3 ++- docs/gemini-cli-setup.md | 3 ++- docs/getting-started.md | 1 + 4 files changed, 20 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 0d3b2a38..aa6872d6 100644 --- a/README.md +++ b/README.md @@ -349,43 +349,21 @@ Every skill follows a consistent anatomy: ## Project Structure -``` -agent-skills/ -├── skills/ # 25 skills (24 lifecycle + 1 meta) -│ ├── interview-me/ # Define -│ ├── idea-refine/ # Define -│ ├── spec-driven-development/ # Define -│ ├── constraint-driven-development/ # Define -│ ├── planning-and-task-breakdown/ # Plan -│ ├── incremental-implementation/ # Build -│ ├── context-engineering/ # Build -│ ├── source-driven-development/ # Build -│ ├── doubt-driven-development/ # Build -│ ├── frontend-ui-engineering/ # Build -│ ├── test-driven-development/ # Build -│ ├── api-and-interface-design/ # Build -│ ├── browser-testing-with-devtools/ # Verify -│ ├── debugging-and-error-recovery/ # Verify -│ ├── code-review-and-quality/ # Review -│ ├── code-simplification/ # Review -│ ├── security-and-hardening/ # Review -│ ├── performance-optimization/ # Review -│ ├── git-workflow-and-versioning/ # Ship -│ ├── ci-cd-and-automation/ # Ship -│ ├── deprecation-and-migration/ # Ship -│ ├── documentation-and-adrs/ # Ship -│ ├── observability-and-instrumentation/ # Ship -│ ├── shipping-and-launch/ # Ship -│ └── using-agent-skills/ # Meta: how to use this pack -├── agents/ # 4 specialist personas -├── references/ # 7 supplementary checklists -├── hooks/ # Session lifecycle hooks -├── .claude/commands/ # 8 slash commands (Claude Code) -├── .gemini/commands/ # 8 slash commands (Gemini CLI) -├── commands/ # 8 slash commands (Antigravity CLI) -├── plugin.json # Antigravity plugin manifest -└── docs/ # Setup guides per tool -``` +The portable core stays in shared directories. Host-specific paths are native discovery conventions, not branding aliases; renaming or merging them would break the tools that scan those exact locations. + +| Layer / consumer | Repository paths | Purpose | +|---|---|---| +| Shared workflow core | `skills/` (25 skills) | Portable `SKILL.md` workflows used by every integration | +| Shared review material | `agents/` (4 personas), `references/` (7 checklists) | Specialist reviewers and pack-level checklists carried by whole-repo installs | +| Claude Code adapter | `.claude/commands/` (9 commands), `.claude-plugin/`, `hooks/` | Slash-command wrappers, marketplace metadata, and lifecycle hooks | +| Gemini CLI adapter | `.gemini/commands/` (9 commands) | Gemini-native TOML command wrappers | +| Antigravity CLI adapter | `commands/` (9 commands), `plugin.json` | Legacy TOML wrappers and the root plugin manifest; see the [known wrapper limitation](docs/antigravity-setup.md#lifecycle-workflows-and-command-compatibility) | +| Codex adapter | `.codex-plugin/`, `.agents/plugins/` | Codex plugin metadata and marketplace registration; Codex consumes `skills/` directly | +| GitHub Copilot CLI adapter | `plugin.json` | Root plugin metadata; Copilot CLI discovers `skills/` by convention and does not register the lifecycle wrappers | +| Contributor tooling | `scripts/` (13 scripts), `evals/` (25 case files), `.github/workflows/` | Validation, routing evals, and CI | +| Documentation | `docs/` | Universal guidance and per-tool setup guides | + +Tools without a checked-in adapter directory install or copy the shared `skills/` core into their own native location. The [Quick Start](#quick-start) links the setup guide for each supported host. --- diff --git a/docs/antigravity-setup.md b/docs/antigravity-setup.md index 44b29352..ac0e4611 100644 --- a/docs/antigravity-setup.md +++ b/docs/antigravity-setup.md @@ -45,13 +45,14 @@ agy plugin list ## Lifecycle Workflows and Command Compatibility -Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 8 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/build` and the other short wrappers are available. This is tracked in [agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788). +Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 9 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/build` and the other short wrappers are available. This is tracked in [agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788). Use the native plugin skills directly while that importer limitation applies: | Intended wrapper | Direct Antigravity invocation | Notes | |------------------|-------------------------------|-------| | `/spec` | `/agent-skills:spec-driven-development` | Writes a structured spec before code | +| `/constraints` | `/agent-skills:constraint-driven-development` | Defines and enforces the project's quality bar | | `/planning` | `/agent-skills:planning-and-task-breakdown` | Antigravity's built-in `/planning` command is a separate plan-mode control | | `/build` | `/agent-skills:incremental-implementation` | Also invoke `/agent-skills:test-driven-development`; wrapper-only `/build auto` orchestration is unavailable | | `/test` | `/agent-skills:test-driven-development` | Runs the red-green-refactor workflow | diff --git a/docs/gemini-cli-setup.md b/docs/gemini-cli-setup.md index 7ad9d562..4722488a 100644 --- a/docs/gemini-cli-setup.md +++ b/docs/gemini-cli-setup.md @@ -107,11 +107,12 @@ This is useful when you want to ensure a specific workflow is followed without w ## Slash Commands -The repo ships 8 slash commands under `.gemini/commands/`: 7 lifecycle commands plus the `/webperf` specialist audit. Gemini CLI auto-discovers them when you run from the project root. +The repo ships 9 slash commands under `.gemini/commands/`: 8 lifecycle commands plus the `/webperf` specialist audit. Gemini CLI auto-discovers them when you run from the project root. | Command | What it does | |---------|--------------| | `/spec` | Write a structured spec before writing code | +| `/constraints` | Define and enforce the project's quality bar | | `/planning` | Break work into small, verifiable tasks | | `/build` | Implement the next task incrementally | | `/test` | Run TDD workflow — red, green, refactor | diff --git a/docs/getting-started.md b/docs/getting-started.md index 8572898a..19f849d3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -109,6 +109,7 @@ The `.claude/commands/` directory contains slash commands for Claude Code: | Command | Skill Invoked | |---------|---------------| | `/spec` | spec-driven-development | +| `/constraints` | constraint-driven-development | | `/plan` | planning-and-task-breakdown | | `/build` | incremental-implementation + test-driven-development | | `/build auto` | planning-and-task-breakdown → incremental-implementation + test-driven-development (whole plan, one approval) |