@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.
- package/.agent-src/rules/no-cheap-questions.md +11 -2
- package/.agent-src/skills/readme-writing-package/SKILL.md +24 -0
- package/.claude-plugin/marketplace.json +1 -1
- package/CHANGELOG.md +69 -0
- package/README.md +71 -6
- package/docs/DISTRIBUTION_CHECKLIST.md +7 -6
- package/docs/architecture.md +1 -1
- package/docs/contracts/tier-3-contrib-plugin.md +129 -0
- package/docs/decisions/ADR-007-agent-discovery-scopes.md +286 -0
- package/docs/decisions/ADR-008-installed-tools-manifest.md +160 -0
- package/docs/decisions/INDEX.md +2 -0
- package/docs/getting-started.md +1 -1
- package/docs/guidelines/agent-infra/asking-and-brevity-examples.md +32 -0
- package/docs/guidelines/agent-infra/installed-tools-manifest.md +135 -0
- package/docs/installation.md +83 -27
- package/docs/setup/per-ide/aider.md +1 -1
- package/docs/setup/per-ide/claude-code.md +1 -1
- package/docs/setup/per-ide/claude-desktop.md +8 -4
- package/docs/setup/per-ide/cline.md +2 -2
- package/docs/setup/per-ide/codex.md +1 -1
- package/docs/setup/per-ide/copilot.md +2 -2
- package/docs/setup/per-ide/cursor.md +2 -2
- package/docs/setup/per-ide/gemini-cli.md +1 -1
- package/docs/setup/per-ide/windsurf.md +2 -2
- package/docs/troubleshooting.md +4 -4
- package/package.json +1 -1
- package/scripts/_cli/cmd_export.py +157 -0
- package/scripts/_cli/cmd_sync.py +162 -0
- package/scripts/_cli/cmd_update.py +23 -1
- package/scripts/_cli/cmd_validate.py +164 -0
- package/scripts/_lib/installed_lock.py +160 -0
- package/scripts/_lib/installed_tools.py +237 -0
- package/scripts/agent-config +78 -1
- package/scripts/install +43 -10
- package/scripts/install.py +975 -14
- package/templates/agent-config-wrapper.sh +1 -1
- package/templates/consumer-settings/README.md +1 -1
- 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
|
-
|
|
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
|
-
|
|
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
|
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>
|
|
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 — = not available ☑️ = text reference only
|
|
436
|
-
(commands
|
|
437
|
-
|
|
491
|
+
(commands listed in `AGENTS.md`, tool cannot invoke them as native
|
|
492
|
+
slash-commands) 📌 = 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,
|
|
442
|
-
> commands are available
|
|
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/
|
|
77
|
+
### npm: `@event4u/agent-config`
|
|
78
78
|
|
|
79
79
|
- **Status:** Prepared
|
|
80
80
|
- **Owner:** maintainer
|
|
81
81
|
- **Last Reviewed:** 2026-05-12
|
|
82
|
-
- **Substrate:**
|
|
83
|
-
|
|
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:**
|
|
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/
|
|
92
|
+
@event4u/agent-config init` in an empty directory before
|
|
92
93
|
declaring Live.
|
|
93
94
|
|
|
94
95
|
### GitHub repo topics + tagline
|
package/docs/architecture.md
CHANGED
|
@@ -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** |
|
|
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.
|