feat(agents-canon): AGENTS.md canon everywhere — bootstrap v2.0.0 writes AGENTS.md + CLAUDE.md pointer; 15 skills retarget triggers/rule refs from CLAUDE.md to AGENTS.md (semver bumps); dist rebuilt
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
Initializes or upgrades a project workspace in one pass: git, `.gitignore`,
|
||||
`README.md`, `.wiki/` (Karpathy's LLM Wiki layout), `.tasks/` (per-task board),
|
||||
and `CLAUDE.md` with skill triggers.
|
||||
and `AGENTS.md` (canon) with skill triggers + `CLAUDE.md` legacy pointer.
|
||||
|
||||
Operates in two modes, picked automatically:
|
||||
|
||||
@@ -44,23 +44,24 @@ projects bootstrapped at different times debuggable.
|
||||
| `README.md` | minimal stub | Skipped if file exists. |
|
||||
| `.wiki/` | delegated to `setup-wiki` | Karpathy LLM Wiki layout — `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/`, `entities/`, `concepts/`, `packages/`, `sources/`. |
|
||||
| `.tasks/` | delegated to `setup-tasks` | Canonical board — `STATUS.md` plus per-task `<task-slug>.md` files. |
|
||||
| `CLAUDE.md` | `assets/CLAUDE.md.template` | Skill triggers (`use project wiki`, `use task management system`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. On upgrade, the template is treated as a canonical set and merged idempotently — only missing trigger lines are appended after user confirm. Re-runs are no-ops. |
|
||||
| `AGENTS.md` | `assets/AGENTS.md.template` | **Canon** — skill triggers (`use project wiki`, `use task management system`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. On upgrade, the template is treated as a canonical set and merged idempotently — only missing trigger lines are appended after user confirm. Re-runs are no-ops. |
|
||||
| `CLAUDE.md` | generated pointer | `Canon is AGENTS.md. Read AGENTS.md.` — legacy pointer for tooling that looks for the old name. |
|
||||
| `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. |
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Detect mode.** Inspect the current directory — git, `.wiki/`, `.tasks/`,
|
||||
`CLAUDE.md`, `README.md` — and print a single summary block: what was
|
||||
`AGENTS.md`, `CLAUDE.md`, `README.md` — and print a single summary block: what was
|
||||
found, what will be created, what will be skipped.
|
||||
2. **Confirm.** One question, one confirmation. Nothing is written before the
|
||||
user agrees.
|
||||
3. **Steps 1–5.** Create or skip each piece in order — git, README, `.wiki/`,
|
||||
`.tasks/`, `CLAUDE.md`. Steps 3 and 4 delegate to the setup-skills.
|
||||
`.tasks/`, `AGENTS.md` + `CLAUDE.md` pointer. Steps 3 and 4 delegate to the setup-skills.
|
||||
4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of
|
||||
`project-bootstrap`, `setup-wiki`, `setup-tasks`, `project-discipline`,
|
||||
`setup-interns`, and `using-interns` used.
|
||||
5. **Step 5.6.** Skill dependencies check. Walk the canonical trigger list
|
||||
in `CLAUDE.md`, look each up in an embedded `trigger → fulfiller` map,
|
||||
in `AGENTS.md`, look each up in an embedded `trigger → fulfiller` map,
|
||||
detect what's missing on this host (`~/.claude/skills/<name>/SKILL.md`
|
||||
for skills, `~/.claude/plugins/installed_plugins.json` for plugins),
|
||||
and print one chat-only block listing every missing fulfiller with a
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
name: project-bootstrap
|
||||
author: ours
|
||||
version: 1.13.0
|
||||
version: 2.0.0
|
||||
description: >
|
||||
Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
|
||||
.wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers.
|
||||
.wiki/ using Karpathy's method, .tasks/ for task tracking, AGENTS.md (canon) with
|
||||
skill triggers + CLAUDE.md legacy pointer.
|
||||
Creates remote Gitea repo and syncs projects-meta cache for greenfield projects.
|
||||
Use this skill when the user says "initialize project", "bootstrap", "setup project",
|
||||
"upgrade project", "add wiki", "add tasks", "start project", "set everything up",
|
||||
@@ -46,7 +47,7 @@ Show the user a summary in one block — what was found, what will be created:
|
||||
Mode: greenfield-full (new project + remote create)
|
||||
|
||||
Found: (empty directory)
|
||||
Create: git .wiki .tasks CLAUDE.md .gitignore README.md remote
|
||||
Create: git .wiki .tasks AGENTS.md CLAUDE.md .gitignore README.md remote
|
||||
```
|
||||
|
||||
Ask one question: "Looks right? Shall we proceed?" — and wait for confirmation.
|
||||
@@ -320,22 +321,41 @@ If `setup-tasks` is not installed, **stop** and tell the user — same rule as S
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — CLAUDE.md
|
||||
## Step 5 — AGENTS.md (canon) + CLAUDE.md pointer
|
||||
|
||||
Two paths, picked by file presence:
|
||||
**Canon is `AGENTS.md`** (cross-agent standard: pi prefers `AGENTS.md` over
|
||||
`CLAUDE.md` when both exist — confirmed in pi's `resource-loader`; Claude Code
|
||||
reads `AGENTS.md` as fallback). `CLAUDE.md` is a legacy pointer file for
|
||||
tooling that looks for it by name. Both files are always written together;
|
||||
the canon content lives only in `AGENTS.md`.
|
||||
|
||||
### Init (file does not exist)
|
||||
Three paths, picked by file presence:
|
||||
|
||||
Create `CLAUDE.md` from `assets/CLAUDE.md.template`. Substitute the platform line
|
||||
on non-Windows hosts (`we're on Linux` / `we're on macOS` instead of
|
||||
`we're on Windows`).
|
||||
### Init (neither file exists)
|
||||
|
||||
### Upgrade (file exists) — idempotent merge
|
||||
Create `AGENTS.md` from `assets/AGENTS.md.template` (canon content). Substitute
|
||||
the platform line on non-Windows hosts (`we're on Linux` / `we're on macOS`
|
||||
instead of `we're on Windows`). Then write the `CLAUDE.md` pointer:
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md — legacy pointer
|
||||
|
||||
Canon is `AGENTS.md`. Read `AGENTS.md` — it contains all project instructions.
|
||||
```
|
||||
|
||||
### Migrate (CLAUDE.md exists, AGENTS.md does not)
|
||||
|
||||
The project predates the AGENTS.md canon. Offer to migrate: `git mv CLAUDE.md
|
||||
AGENTS.md`, fix the first-line header if it was `# CLAUDE.md`, then write the
|
||||
`CLAUDE.md` pointer. Ask one question — "Migrate CLAUDE.md → AGENTS.md?" —
|
||||
and wait for confirmation. On confirm, proceed to the Upgrade merge below.
|
||||
|
||||
### Upgrade (AGENTS.md exists) — idempotent merge
|
||||
|
||||
Treat the template as the canonical trigger set and reconcile the existing file
|
||||
against it. Re-runs are no-ops once the file is in canon.
|
||||
|
||||
1. Read the existing `CLAUDE.md`.
|
||||
1. Read the existing `AGENTS.md`.
|
||||
2. For each non-empty, non-comment line in the template, decide whether it's
|
||||
already present:
|
||||
- **Trigger lines** (everything except the platform line) — present iff any
|
||||
@@ -346,19 +366,20 @@ against it. Re-runs are no-ops once the file is in canon.
|
||||
matches `we're on (windows|linux|macos)` case-insensitively. If the user
|
||||
pinned a different platform on purpose, **leave it alone**. Only append
|
||||
the host-appropriate platform line when none of the three is present.
|
||||
3. Collect missing lines. If none → print `CLAUDE.md already canon — no changes`
|
||||
3. Collect missing lines. If none → print `AGENTS.md already canon — no changes`
|
||||
and skip to Step 5.5.
|
||||
4. Show the user the diff (N lines, exact text to append) and ask one question:
|
||||
"Append these N missing canonical triggers to the end of CLAUDE.md?" Wait
|
||||
"Append these N missing canonical triggers to the end of AGENTS.md?" Wait
|
||||
for explicit confirmation before writing.
|
||||
5. On confirm: append a single newline (if the file doesn't end with one) and
|
||||
then the missing lines, one per line. Don't rewrite the file — only append.
|
||||
Don't reorder existing lines. Don't dedupe within the existing file.
|
||||
6. Ensure the `CLAUDE.md` pointer exists; if missing, write it.
|
||||
|
||||
Template contents (`assets/CLAUDE.md.template` — source of truth):
|
||||
Template contents (`assets/AGENTS.md.template` — source of truth):
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
# AGENTS.md
|
||||
# Agent instructions. Each line is a trigger for an installed skill.
|
||||
|
||||
talk like a caveman
|
||||
@@ -388,8 +409,8 @@ if `pulling-before-work` is not in `~/.claude/skills/`; otherwise the trigger is
|
||||
silently dead like any other absent skill.
|
||||
|
||||
The `follow project discipline` line activates the `project-discipline` skill,
|
||||
which codifies four cross-project rules: (1) project CLAUDE.md / .wiki/CLAUDE.md
|
||||
/ .tasks/ override defaults from any other skill; (2) all work on master/main,
|
||||
which codifies four cross-project rules: (1) project AGENTS.md / CLAUDE.md /
|
||||
.wiki/CLAUDE.md / .tasks/ override defaults from any other skill; (2) all work on master/main,
|
||||
no feature branches without explicit user approval; (3) version bump on every
|
||||
edit of versioned artifacts per semver, recorded in commit; (4) commit freely,
|
||||
push only after explicit per-session approval. Install the skill on the host
|
||||
@@ -468,7 +489,7 @@ If a delegated setup-skill is unavailable on this machine (e.g. user installed o
|
||||
|
||||
## Step 5.6 — Skill dependencies check (chat-only, never auto-install)
|
||||
|
||||
The `CLAUDE.md` template just written contains canonical trigger lines.
|
||||
The `AGENTS.md` template just written contains canonical trigger lines.
|
||||
Each one is a no-op unless the corresponding skill or plugin is installed
|
||||
on the host. On a fresh machine these are often absent, and the user
|
||||
won't know the trigger is silently dead. Detect what's missing on this
|
||||
@@ -477,11 +498,11 @@ project file, never auto-install.
|
||||
|
||||
### Trigger → fulfiller map
|
||||
|
||||
Source of truth for this map is the canonical `assets/CLAUDE.md.template`.
|
||||
Source of truth for this map is the canonical `assets/AGENTS.md.template`.
|
||||
When a new trigger is added there, also add a row here in the same commit.
|
||||
Mismatch between template and map → silent gaps in the recommendation.
|
||||
|
||||
| Trigger line in `CLAUDE.md` | Fulfiller | Kind | Detection path | Install command |
|
||||
| Trigger line in `AGENTS.md` | Fulfiller | Kind | Detection path | Install command |
|
||||
|---|---|---|---|---|
|
||||
| `talk like a caveman` | `caveman` | skill | `~/.claude/skills/caveman/SKILL.md` | `bash scripts/install.sh caveman` |
|
||||
| `use project wiki` | `using-wiki` | skill | `~/.claude/skills/using-wiki/SKILL.md` | `bash scripts/install.sh using-wiki` |
|
||||
@@ -497,7 +518,7 @@ Mismatch between template and map → silent gaps in the recommendation.
|
||||
|
||||
### Algorithm
|
||||
|
||||
1. Read the project's `CLAUDE.md` (just-written or pre-existing). Extract
|
||||
1. Read the project's `AGENTS.md` (just-written or pre-existing). Extract
|
||||
every non-empty, non-comment line — these are the active triggers for
|
||||
THIS project. The user may have removed canonical lines on purpose;
|
||||
respect that — only check what's actually in the file.
|
||||
@@ -515,7 +536,7 @@ Mismatch between template and map → silent gaps in the recommendation.
|
||||
- **All present** — print one line:
|
||||
|
||||
```
|
||||
✅ all skill dependencies satisfied — every CLAUDE.md trigger has its fulfiller on this host.
|
||||
✅ all skill dependencies satisfied — every AGENTS.md trigger has its fulfiller on this host.
|
||||
```
|
||||
|
||||
Skip to Step 6.
|
||||
@@ -524,9 +545,9 @@ Mismatch between template and map → silent gaps in the recommendation.
|
||||
write it into any project file:
|
||||
|
||||
```
|
||||
ℹ️ Recommended: install the following to fulfill CLAUDE.md triggers
|
||||
ℹ️ Recommended: install the following to fulfill AGENTS.md triggers
|
||||
|
||||
The triggers below are present in CLAUDE.md but their fulfillers are
|
||||
The triggers below are present in AGENTS.md but their fulfillers are
|
||||
missing on this machine — they're silently no-ops until installed:
|
||||
|
||||
trigger fulfiller (kind)
|
||||
@@ -555,7 +576,7 @@ Mismatch between template and map → silent gaps in the recommendation.
|
||||
skill, and silently mutating user-level skill / plugin state without
|
||||
consent is overreach. The recommendation is informational. The user can
|
||||
install some / all / none of the recommendations, or remove canonical
|
||||
lines from `CLAUDE.md` to lean the project's trigger set down.
|
||||
lines from `AGENTS.md` to lean the project's trigger set down.
|
||||
|
||||
## Step 6 — Commit
|
||||
|
||||
@@ -567,7 +588,7 @@ git commit -m "chore: bootstrap project structure"
|
||||
If the repo already had commits — commit only the files just created:
|
||||
|
||||
```bash
|
||||
git add .wiki/ .tasks/ CLAUDE.md .gitignore README.md
|
||||
git add .wiki/ .tasks/ AGENTS.md CLAUDE.md .gitignore README.md
|
||||
git commit -m "chore: upgrade project structure"
|
||||
```
|
||||
|
||||
@@ -581,7 +602,8 @@ Print a final report:
|
||||
✅ Done! Created:
|
||||
.wiki/ — project wiki (Karpathy method)
|
||||
.tasks/ — task tracking system
|
||||
CLAUDE.md — skill triggers
|
||||
AGENTS.md — skill triggers (canon)
|
||||
CLAUDE.md — legacy pointer
|
||||
.gitignore — standard template
|
||||
README.md — starter file
|
||||
remote — Gitea repo created and pushed
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# CLAUDE.md
|
||||
# AGENTS.md
|
||||
# Agent instructions. Each line is a trigger for an installed skill.
|
||||
|
||||
talk like a caveman
|
||||
Reference in New Issue
Block a user