@event4u/agent-config 2.1.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/.agent-src/rules/no-cheap-questions.md +11 -2
  2. package/.agent-src/skills/readme-writing-package/SKILL.md +24 -0
  3. package/.claude-plugin/marketplace.json +1 -1
  4. package/CHANGELOG.md +69 -0
  5. package/README.md +71 -6
  6. package/docs/DISTRIBUTION_CHECKLIST.md +7 -6
  7. package/docs/architecture.md +1 -1
  8. package/docs/contracts/tier-3-contrib-plugin.md +129 -0
  9. package/docs/decisions/ADR-007-agent-discovery-scopes.md +286 -0
  10. package/docs/decisions/ADR-008-installed-tools-manifest.md +160 -0
  11. package/docs/decisions/INDEX.md +2 -0
  12. package/docs/getting-started.md +1 -1
  13. package/docs/guidelines/agent-infra/asking-and-brevity-examples.md +32 -0
  14. package/docs/guidelines/agent-infra/installed-tools-manifest.md +135 -0
  15. package/docs/installation.md +83 -27
  16. package/docs/setup/per-ide/aider.md +1 -1
  17. package/docs/setup/per-ide/claude-code.md +1 -1
  18. package/docs/setup/per-ide/claude-desktop.md +8 -4
  19. package/docs/setup/per-ide/cline.md +2 -2
  20. package/docs/setup/per-ide/codex.md +1 -1
  21. package/docs/setup/per-ide/copilot.md +2 -2
  22. package/docs/setup/per-ide/cursor.md +2 -2
  23. package/docs/setup/per-ide/gemini-cli.md +1 -1
  24. package/docs/setup/per-ide/windsurf.md +2 -2
  25. package/docs/troubleshooting.md +4 -4
  26. package/package.json +1 -1
  27. package/scripts/_cli/cmd_export.py +157 -0
  28. package/scripts/_cli/cmd_sync.py +162 -0
  29. package/scripts/_cli/cmd_update.py +23 -1
  30. package/scripts/_cli/cmd_validate.py +164 -0
  31. package/scripts/_lib/installed_lock.py +160 -0
  32. package/scripts/_lib/installed_tools.py +237 -0
  33. package/scripts/agent-config +78 -1
  34. package/scripts/install +43 -10
  35. package/scripts/install.py +975 -14
  36. package/templates/agent-config-wrapper.sh +1 -1
  37. package/templates/consumer-settings/README.md +1 -1
  38. package/templates/marketing-copy.yml +6 -5
@@ -20,9 +20,17 @@ NEVER OFFER NUMBERED CHOICES WITHOUT A REAL TRADE-OFF.
20
20
 
21
21
  ## What counts as cheap
22
22
 
23
- Nine classes — sequencing · format-only · commit asks (forbidden by [`commit-policy`](commit-policy.md)) · CI / test asks ([`verify-before-complete`](verify-before-complete.md) decides) · fenced-step re-asks ([`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates)) · Iron-Law option (breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`) · context-derived · dominant option · re-ask after decline ([`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task)).
23
+ Ten classes — sequencing · format-only · commit asks · CI / test asks · fenced-step re-asks · Iron-Law option · context-derived · dominant option · re-ask after decline · **paternalistic state-assuming option** (Iron Law 3 below). Per-class detail + governing rule: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
24
24
 
25
- Per-class patterns and examples: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
25
+ ## Iron Law 3 No Paternalistic State-Assuming Options
26
+
27
+ ```
28
+ NEVER FABRICATE USER STATE TO JUSTIFY AN OPTION.
29
+ "TAKE A BREAK", "SLEEP ON IT", "COME BACK FRESH" — FORBIDDEN.
30
+ THE USER DECIDES WHEN TO STOP. THE AGENT DECIDES WHAT TO BUILD NEXT.
31
+ ```
32
+
33
+ Every numbered option = technical / scope / sequencing choice with real trade-off, not mood-management nudge. Forbidden patterns + carve-outs: [`asking-and-brevity-examples § iron-law-3`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#no-cheap-questions--iron-law-3-detail-paternalistic-state-options).
26
34
 
27
35
  ## Pre-Send Self-Check — MANDATORY before every question
28
36
 
@@ -34,6 +42,7 @@ Run silently before any numbered-options block:
34
42
  4. One option obviously dominant?
35
43
  5. User fenced next step (*"plan only"*, *"review first"*) → deliver + handback per `scope-control § fenced step`.
36
44
  6. User already declined? Re-ask forbidden per `scope-control § decline = silence`.
45
+ 7. Any option assumes user fatigue / frustration / "had enough" without in-message citation? Iron Law 3 — drop it.
37
46
 
38
47
  Any "yes" → **do not ask**. Pick the dominant path, state assumption inline (*"assuming X — adjust if wrong"*), hand back. One-question-per-turn from [`ask-when-uncertain`](ask-when-uncertain.md) still applies when the question is genuine.
39
48
 
@@ -146,6 +146,30 @@ install, first example, or requirements.
146
146
  deep-link-table pattern, collapsibles, and anti-patterns (premature
147
147
  splitting, duplication between README and `/docs/`).
148
148
 
149
+ #### Per-AI catalog pattern (multi-platform AI / CLI packages)
150
+
151
+ For packages targeting many AI assistants or platforms (CLI installers,
152
+ agent-config tools, language SDKs with 10+ targets), prefer flat per-AI
153
+ catalog over giant matrix. One line per target, install command on left,
154
+ aligned trailing comment naming platform:
155
+
156
+ ```bash
157
+ npx <package> init --tools=claude-code # Claude Code
158
+ npx <package> init --tools=cursor # Cursor
159
+ npx <package> init --tools=windsurf # Windsurf
160
+ # ... one line per supported target
161
+ ```
162
+
163
+ Pair catalog with separate "Global install" subsection (same flags plus
164
+ `--global`) and "Other commands" subsection. Reference example:
165
+ [`README.md § Pick specific AIs`](../../../README.md#pick-specific-ais) in
166
+ this repo. Inspiration:
167
+ [`ui-ux-pro-max-skill § Installation`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill#installation).
168
+
169
+ Use catalog when package's primary install action varies by platform; use
170
+ matrix table (Tool / Rules / Skills / Commands) for capability comparison.
171
+ Different jobs — install vs. coverage.
172
+
149
173
  README = enough to adopt. Docs = enough to master.
150
174
 
151
175
  ### 8. Validate
@@ -6,7 +6,7 @@
6
6
  },
7
7
  "metadata": {
8
8
  "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
9
- "version": "2.1.0"
9
+ "version": "2.2.1"
10
10
  },
11
11
  "plugins": [
12
12
  {
package/CHANGELOG.md CHANGED
@@ -9,6 +9,31 @@ versioning policy is documented in [CONTRIBUTING.md](CONTRIBUTING.md#versioning-
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ Four roadmaps land in this release.
13
+
14
+ **Package consolidation** — the standalone wrapper package
15
+ `@event4u/create-agent-config` is retired. `npx @event4u/agent-config init`
16
+ is now the canonical one-shot entrypoint; the bundle package gains an
17
+ `init` subcommand that delegates to `scripts/install`. `packages/create-agent-config/`
18
+ is removed from the repo, and every doc / template / help string is
19
+ updated to the new command. Existing users running the old wrapper
20
+ should switch — the old package name will stop receiving releases.
21
+
22
+ **Global-First Install (R4)** — `npx @event4u/agent-config init`
23
+ now defaults to a **global** install (`~/.claude/`, `~/.cursor/`, …)
24
+ when run outside a project, and a **project** install when run inside
25
+ one. A new global lockfile at `~/.config/agent-config/installed.lock`
26
+ records `agent_config_version` + `tools[]` and refuses mismatched
27
+ re-installs (exit 1) until `update` or `--force` realigns it. New
28
+ `agent-config export --tool=<id> --output=<path>` subcommand ejects a
29
+ named tool's resolved content into the project tree (idempotent;
30
+ `--force` overrides drift). 12 supported tool ids (claude-code,
31
+ cursor, windsurf, cline, aider, codex, gemini, copilot,
32
+ claude-desktop, continue, kilocode, zed, jetbrains, kiro). Windows
33
+ CI matrix added for the lockfile + export paths. See
34
+ [`docs/decisions/ADR-007-agent-discovery-scopes.md`](docs/decisions/ADR-007-agent-discovery-scopes.md)
35
+ and [`docs/decisions/ADR-008-installed-tools-manifest.md`](docs/decisions/ADR-008-installed-tools-manifest.md).
36
+
12
37
  Three roadmaps land in this release.
13
38
 
14
39
  **Universal Execution Engine (R1)** — the `/implement-ticket` runtime is
@@ -318,6 +343,50 @@ our recommendation order, not its support status.
318
343
  users" tension without removing any path that an existing user
319
344
  might rely on.
320
345
 
346
+ ## [2.2.1](https://github.com/event4u-app/agent-config/compare/2.2.0...2.2.1) (2026-05-12)
347
+
348
+ ### Documentation
349
+
350
+ * changelog + ADR-007 note for package consolidation ([1d0d6fb](https://github.com/event4u-app/agent-config/commit/1d0d6fb8882431ee11a6b034f6157ae9f8ccea4d))
351
+ * update install commands to npx @event4u/agent-config init ([b9956c6](https://github.com/event4u-app/agent-config/commit/b9956c6ff827433bff7dc9aa1f40ba3454ef5154))
352
+
353
+ ### Chores
354
+
355
+ * consolidate npm package into @event4u/agent-config init ([d3188ce](https://github.com/event4u-app/agent-config/commit/d3188ced3edac5b670b68e22f51295ef831471d6))
356
+
357
+ Tests: 3350 (+0 since 2.2.0)
358
+
359
+ ## [2.2.0](https://github.com/event4u-app/agent-config/compare/2.1.0...2.2.0) (2026-05-12)
360
+
361
+ ### Features
362
+
363
+ * **npx:** expand --tools validator to 13 supported AI ids ([7af69a7](https://github.com/event4u-app/agent-config/commit/7af69a766f575c30d8f29ea04052647b6a1b8a19))
364
+ * **cli:** add sync and validate subcommands for installed-tools manifest ([62a5c66](https://github.com/event4u-app/agent-config/commit/62a5c66a131bcf8866be2a8c0e76ba6e054017af))
365
+ * **cli:** add export subcommand and update version-drift handling ([6110f3b](https://github.com/event4u-app/agent-config/commit/6110f3b0ee454ca215c569d8f42ca38ffce577e8))
366
+ * **install:** global-first install with lockfile + installed-tools manifest engine ([6200d42](https://github.com/event4u-app/agent-config/commit/6200d42225d5712a10d5458dc608da3f5cd0164c))
367
+
368
+ ### Bug Fixes
369
+
370
+ * **rules:** trim no-cheap-questions to satisfy 12% concentration cap ([4abf946](https://github.com/event4u-app/agent-config/commit/4abf94628838c027da13d190e5e7b27738070db2))
371
+
372
+ ### Documentation
373
+
374
+ * **rules:** add no-cheap-questions Iron Law 3 against paternalistic state options ([b98687b](https://github.com/event4u-app/agent-config/commit/b98687bd397d39eae6811e54eb743a095fa33b8b))
375
+ * README + installation + manifest guideline for global-first install ([cdc52ff](https://github.com/event4u-app/agent-config/commit/cdc52ffc5abb9cff6fda9133dd0b8dc524794d18))
376
+ * **contracts:** add tier-3 contrib plugin contract ([2dbf9cd](https://github.com/event4u-app/agent-config/commit/2dbf9cd2ec772dc2248de2b8f17248e97a67a60b))
377
+ * **adr:** add ADR-007 global-first install + ADR-008 installed-tools manifest ([e214de2](https://github.com/event4u-app/agent-config/commit/e214de27bd8d19858fdc16cecc4ebfeaaebce136))
378
+
379
+ ### CI
380
+
381
+ * **windows:** add lockfile + export tests on Windows runner ([e5802a5](https://github.com/event4u-app/agent-config/commit/e5802a56f45bcfd5eb845c7af816bb12a0b4492b))
382
+
383
+ ### Chores
384
+
385
+ * **taskfile:** add test-install-local for offline one-liner smoke test ([594ac69](https://github.com/event4u-app/agent-config/commit/594ac69c8682f106dee9ebc9ce3e55bb0083e254))
386
+ * **roadmap:** archive road-to-global-first-install (24/24 complete) ([71d8cf2](https://github.com/event4u-app/agent-config/commit/71d8cf2966976c286ffecc1646cb7990255cccd1))
387
+
388
+ Tests: 3350 (+97 since 2.1.0)
389
+
321
390
  ## [2.1.0](https://github.com/event4u-app/agent-config/compare/2.0.0...2.1.0) (2026-05-12)
322
391
 
323
392
  ### Features
package/README.md CHANGED
@@ -14,7 +14,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
14
14
  > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
15
15
 
16
16
  <p align="center">
17
- <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>69 Guidelines</strong> · <strong>8 AI Tools</strong>
17
+ <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>70 Guidelines</strong> · <strong>8 AI Tools</strong>
18
18
  </p>
19
19
 
20
20
  ---
@@ -36,6 +36,14 @@ If none of those apply yet — start with the [Quickstart](#quickstart) and pick
36
36
  Two minutes from `npx` to a better-behaved agent — no install, no
37
37
  vendored package, no postinstall hook.
38
38
 
39
+ **v2.1+ — global-first by default.** Running `init` outside a project
40
+ defaults to a user-scope install (`~/.claude/`, `~/.cursor/`, …) and
41
+ records itself in `~/.config/agent-config/installed.lock`. Running it
42
+ inside a project (a `package.json` / `composer.json` / `pyproject.toml`
43
+ manifest is present) defaults to a project-scope install. Override with
44
+ `--scope=global` or `--scope=project`. See
45
+ [`docs/installation.md`](docs/installation.md) for the full matrix.
46
+
39
47
  ### For teams (recommended)
40
48
 
41
49
  Run once in the project root — `npx` resolves the runtime against the
@@ -77,6 +85,48 @@ Copilot fallback) is wired through one universal dispatcher per
77
85
  `--format json` for tooling). The installer also dry-fires the
78
86
  dispatcher per bridge as a post-install smoke test (skip: `--no-smoke`).
79
87
 
88
+ ### Pick specific AIs
89
+
90
+ Default `init` wires every supported AI. To install just one, pass
91
+ `--tools=<name>`:
92
+
93
+ ```bash
94
+ npx @event4u/agent-config init --tools=claude-code # Claude Code
95
+ npx @event4u/agent-config init --tools=cursor # Cursor
96
+ npx @event4u/agent-config init --tools=windsurf # Windsurf
97
+ npx @event4u/agent-config init --tools=cline # Cline
98
+ npx @event4u/agent-config init --tools=gemini-cli # Gemini CLI
99
+ npx @event4u/agent-config init --tools=copilot # GitHub Copilot
100
+ npx @event4u/agent-config init --tools=augment # Augment Code
101
+ npx @event4u/agent-config init --tools=roocode # Roo Code
102
+ npx @event4u/agent-config init --tools=aider # Aider
103
+ npx @event4u/agent-config init --tools=codex # Codex CLI
104
+ npx @event4u/agent-config init --tools=claude-desktop # Claude Desktop
105
+ npx @event4u/agent-config init --tools=continue # Continue
106
+ ```
107
+
108
+ Multiple AIs in one shot: `--tools=claude-code,cursor,augment`.
109
+
110
+ #### Global install (user-scope, available across projects)
111
+
112
+ Add `--global` to write to the user-scope paths from
113
+ [`ADR-007`](docs/decisions/ADR-007-agent-discovery-scopes.md) (`~/.claude/`,
114
+ `~/.cursor/`, …) instead of the current project:
115
+
116
+ ```bash
117
+ npx @event4u/agent-config init --global # all tools, user-scope
118
+ npx @event4u/agent-config init --tools=claude-code --global # → ~/.claude/
119
+ npx @event4u/agent-config init --tools=cursor --global # → ~/.cursor/
120
+ ```
121
+
122
+ Per-AI scope support varies — Claude Desktop, for example, is
123
+ global-only (no project-local discovery on macOS), while Roo Code and
124
+ Continue.dev are project-local. The Supported Tools table below
125
+ documents per-AI scope. Incompatible combinations (e.g.
126
+ `--tools=roocode --global` or `--tools=claude-desktop` without
127
+ `--global`) are rejected with a directive error; `--tools=all`
128
+ silently filters to the scope's compatible subset.
129
+
80
130
  ### For individual use (optional)
81
131
 
82
132
  Skills-only, global across projects — installs into the agent itself,
@@ -431,16 +481,31 @@ Every developer gets the same behavior. No per-user setup needed —
431
481
  | **Windsurf** | ✅ | — | ☑️ | Reads `.windsurfrules` + commands via AGENTS.md |
432
482
  | **Gemini CLI** | ✅ | — | ☑️ | Reads `GEMINI.md` (includes commands reference) |
433
483
  | **GitHub Copilot** | ✅ | — | ☑️ | Reads `.github/copilot-instructions.md` (includes commands) |
484
+ | **Roo Code** | ✅ | — | ☑️ | Auto-discovers `.roo/rules/*.md` + AGENTS.md |
485
+ | **Codex CLI** | ✅ | — | ☑️ | Auto-discovers `AGENTS.md` at project root |
486
+ | **Continue.dev** | ✅ | — | ☑️ | Auto-discovers `.continue/rules/*.md` + AGENTS.md |
487
+ | **Aider** | 📌 | — | — | Marker + manual `read:` in `.aider.conf.yml` |
488
+ | **Claude Desktop** | 📌 | — | — | Global-only — install with `--global` (see ADR-007) |
434
489
 
435
490
  ✅ = native support &nbsp; — = not available &nbsp; ☑️ = text reference only
436
- (commands are listed in `AGENTS.md`, but the tool cannot invoke them as
437
- native slash-commands)
491
+ (commands listed in `AGENTS.md`, tool cannot invoke them as native
492
+ slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
493
+ or manual wiring required)
438
494
 
439
495
  > **What this means in practice:** Augment Code and Claude Code get the full
440
496
  > package (rules + 174 skills + 106 native commands). Cursor, Cline, Windsurf,
441
- > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
442
- > commands are available to them as documentation the agent can read, not as
443
- > first-class features.
497
+ > Gemini CLI, GitHub Copilot, Roo Code, Codex CLI, and Continue.dev only get
498
+ > the **rules** natively; skills and commands are available as documentation
499
+ > the agent can read, not as first-class features. Aider and Claude Desktop
500
+ > ship marker-only bridges — Aider needs a one-line `read:` entry in
501
+ > `.aider.conf.yml`; Claude Desktop is global-scope and pairs with `--global`.
502
+
503
+ > **Team reproducibility (ADR-008):** every tool you `init` is also recorded in
504
+ > `agents/installed-tools.lock` — committed, machine-managed. New team members
505
+ > run `npx @event4u/agent-config sync` after cloning and every bridge in the
506
+ > table above is replayed locally. CI can gate drift with `agent-config validate`.
507
+ > Schema, workflow, and drift catalog:
508
+ > [`docs/guidelines/agent-infra/installed-tools-manifest.md`](docs/guidelines/agent-infra/installed-tools-manifest.md).
444
509
 
445
510
  ### Plugin-installed (optional, for global use)
446
511
 
@@ -74,21 +74,22 @@ are not roadmap steps.
74
74
  - **Notes:** **Do not submit before the gate.** Premature listing
75
75
  produces a bad first impression and is hard to retract.
76
76
 
77
- ### npm: `@event4u/create-agent-config`
77
+ ### npm: `@event4u/agent-config`
78
78
 
79
79
  - **Status:** Prepared
80
80
  - **Owner:** maintainer
81
81
  - **Last Reviewed:** 2026-05-12
82
- - **Substrate:** [`packages/create-agent-config/`](../packages/create-agent-config/)
83
- source is ready; the wrapper clones the repo to a temp dir, runs
84
- `scripts/install`, then deletes the temp dir.
82
+ - **Substrate:** root `package.json` — `bin: scripts/agent-config` exposes
83
+ `init`, `sync`, `validate`, `mcp:render`, `roadmap:progress`,
85
84
  - **Doc anchor:** [`docs/installation.md`](installation.md) §
86
85
  "npx one-liner".
87
- - **Action:** `npm publish --access public` from `packages/create-agent-config/`.
86
+ - **Action:** routine releases auto-publish via `publish-npm.yml` on tag
87
+ push; manual fallback is `npm publish --access public` after
88
+ `task npm:login`.
88
89
  - **Pre-conditions:** npm registry credentials for the `@event4u`
89
90
  scope.
90
91
  - **Notes:** Public scope, MIT-licensed. Verify `npx
91
- @event4u/create-agent-config init` in an empty directory before
92
+ @event4u/agent-config init` in an empty directory before
92
93
  declaring Live.
93
94
 
94
95
  ### GitHub repo topics + tagline
@@ -145,7 +145,7 @@ fails on any source-side violation, without producing artifacts.
145
145
  | **Skills** | 174 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
146
146
  | **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
147
147
  | **Commands** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
148
- | **Guidelines** | 69 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
148
+ | **Guidelines** | 70 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
149
149
  | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
150
150
  | **Contexts** | 5 | Shared knowledge about the system itself |
151
151
 
@@ -0,0 +1,129 @@
1
+ ---
2
+ stability: beta
3
+ ---
4
+
5
+ # Tier-3 contrib plugin pattern
6
+
7
+ **Purpose.** Document the deferred-implementation contract for
8
+ **Tier-3 community AIs** — surfaces that have been named in scoping
9
+ discussions or council rounds but have **not yet been requested by
10
+ a real user**. Tier-3 ships when the first user request lands, not
11
+ on speculation.
12
+
13
+ **Scope.** Defines the candidate list, the manifest shape, the
14
+ promotion path from Tier-3 → Tier-2, and the non-implementation
15
+ guarantee. Does **not** ship code: `agents/manifests/contrib/` is
16
+ unmanifested until a user asks for an entry by name.
17
+
18
+ Last refreshed: 2026-05-12.
19
+
20
+ ## Tier definitions
21
+
22
+ | Tier | Status | Trigger | Implementation |
23
+ |---|---|---|---|
24
+ | **Tier-1** | Shipped | First-class surfaces with daily users | Imperative bridge in `scripts/install.py` |
25
+ | **Tier-2** | Shipped | Named in roadmaps + has plausible audience | Imperative bridge, same pattern as Tier-1 |
26
+ | **Tier-3** | **Deferred** | Named in scoping/council but zero user demand | Manifest YAML in `agents/manifests/contrib/` (not yet implemented) |
27
+
28
+ Phase 2.1 + 2.2 of
29
+ [`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
30
+ closed Tier-1 and Tier-2 at **16 AIs**. Tier-3 is the explicit
31
+ overflow bucket.
32
+
33
+ ## Candidate list (frozen at proposal time)
34
+
35
+ The following surfaces are Tier-3 candidates as of 2026-05-12. They
36
+ were surfaced during the
37
+ [`2026-05-12-installer-expansion`](../../agents/council-sessions/2026-05-12-installer-expansion/synthesis.md)
38
+ council round and have **no entries** in `_VALID_TOOLS`,
39
+ `USER_SCOPE_PATHS`, `SCOPE_SUPPORT`, or the bash `VALID_TOOLS` set.
40
+
41
+ - `qoder` — community fork, no public adoption signal
42
+ - `trae` — ByteDance IDE, behind login wall
43
+ - `opencode` — bundled into VS Code variants; coverage already via `vscode`
44
+ - `codebuddy` — Tencent-internal, no public install path
45
+ - `droid` — proposed CLI agent, alpha
46
+ - `warp` — terminal-with-AI; integration shape unclear (PTY vs file marker)
47
+ - `antigravity` — Google research project, no shipping surface
48
+
49
+ Inclusion in this list is **not** a commitment to ship. Promotion
50
+ requires a real user asking by name (issue, PR, council session, or
51
+ recorded ask).
52
+
53
+ ## Manifest shape (when implemented)
54
+
55
+ When the first user request lands, the responder MUST:
56
+
57
+ 1. Create `agents/manifests/contrib/<tool-id>.yml` matching the
58
+ schema below.
59
+ 2. Add the tool ID to `_VALID_TOOLS`, `USER_SCOPE_PATHS`,
60
+ `SCOPE_SUPPORT`, and the bash `VALID_TOOLS` set.
61
+ 3. Implement `ensure_<tool>_bridge` in `scripts/install.py` (≤60 LOC
62
+ — if larger, escalate via ADR per Phase 2.5 gate).
63
+ 4. Append a row to the `README.md` "Supported Tools" table.
64
+ 5. Re-run `task lint-skills` + `python3 -m pytest tests/test_install_py.py`.
65
+
66
+ ```yaml
67
+ # agents/manifests/contrib/<tool-id>.yml
68
+ tool_id: <slug> # lowercase, hyphen-separated
69
+ display_name: <Pretty> # for README + CLI catalog
70
+ scope: project | global | both
71
+ discovery: marker | hook | config-merge
72
+ marker_path: <relative> # e.g. .tool-id/agent-config.md
73
+ requested_by: <ref> # GitHub issue, PR, council session, etc.
74
+ requested_date: YYYY-MM-DD
75
+ notes: |
76
+ Short rationale, integration shape, known limitations.
77
+ ```
78
+
79
+ ## Non-implementation guarantee
80
+
81
+ `agents/manifests/contrib/` does **not** exist until needed. CI does
82
+ not enforce its presence. The pattern is documented, not scaffolded.
83
+
84
+ This prevents two failure modes:
85
+
86
+ 1. **Empty-shell drift** — a directory of YAML stubs with no
87
+ corresponding code, where the manifest claims support but the
88
+ installer silently no-ops.
89
+ 2. **Speculative breadth** — adding 7 IDs to `_VALID_TOOLS` "in
90
+ case" a user asks, then carrying maintenance cost on dead code.
91
+
92
+ ## Promotion path
93
+
94
+ Tier-3 → Tier-2 promotion happens in a single PR:
95
+
96
+ 1. The first user request anchors the PR (link in commit body).
97
+ 2. Manifest YAML lands alongside the bridge.
98
+ 3. README + roadmap update in the same commit.
99
+ 4. After two reported successful installs (or one release cycle of
100
+ no bug reports), the tool moves out of `contrib/` and the manifest
101
+ YAML is deleted — the bridge stands on its own under the Tier-2
102
+ contract.
103
+
104
+ There is no Tier-3 → Tier-3 churn: a candidate either gets
105
+ requested and promoted, or stays unimplemented indefinitely. We do
106
+ not "preemptively scaffold" Tier-3 entries.
107
+
108
+ ## Out of scope
109
+
110
+ - **Capability matrices** — the manifest does not describe what the
111
+ tool _can_ do, only what the installer must emit. Capability docs
112
+ live in the consumer tool's own documentation.
113
+ - **Auto-discovery** — there is no plugin loader. The installer is
114
+ imperative (see Phase 2.5 gate); manifests are a documentation
115
+ contract, not a runtime input.
116
+ - **Third-party contribution channel** — this contract governs the
117
+ package maintainer's response to user requests, not a community
118
+ plugin marketplace. External plugins would require ADR-009+ to
119
+ introduce a stable extension surface.
120
+
121
+ ## Cross-references
122
+
123
+ - [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md) —
124
+ project / global / both scope taxonomy that Tier-3 entries inherit.
125
+ - [`ADR-008`](../decisions/ADR-008-installed-tools-manifest.md) —
126
+ `agents/installed-tools.lock` for per-project state, distinct
127
+ from this maintainer-side contract.
128
+ - [`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
129
+ Phase 2.6 — completion trigger for this contract.