From 7cd16611be0e6400f2b7fbf27ddf41b20783c36a Mon Sep 17 00:00:00 2001 From: testtest126 <44771568+testtest126@users.noreply.github.com> Date: Mon, 13 Jul 2026 12:52:01 +0200 Subject: [PATCH] chore: dogfood agent-ready onto its own repo Install the kit into its own root via `./install.sh .` so the project follows the conventions it ships: - AGENTS.md filled in with real values (POSIX-sh kit; test with `bats tests/install.bats`; lint with `shellcheck install.sh`; the no-dependencies promise; the templates/-derived copy list). - Per-tool adapters (CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/agents.mdc) that point at AGENTS.md. - memory/ scaffold (MEMORY.md index + EXAMPLE.md format reference). Verified: `shellcheck install.sh` clean, `bats tests/install.bats` 10/10. Co-Authored-By: Claude Opus 4.8 --- .cursor/rules/agents.mdc | 9 +++++ .github/copilot-instructions.md | 8 ++++ AGENTS.md | 68 +++++++++++++++++++++++++++++++++ CLAUDE.md | 8 ++++ memory/EXAMPLE.md | 18 +++++++++ memory/MEMORY.md | 12 ++++++ 6 files changed, 123 insertions(+) create mode 100644 .cursor/rules/agents.mdc create mode 100644 .github/copilot-instructions.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 memory/EXAMPLE.md create mode 100644 memory/MEMORY.md diff --git a/.cursor/rules/agents.mdc b/.cursor/rules/agents.mdc new file mode 100644 index 0000000..06e7910 --- /dev/null +++ b/.cursor/rules/agents.mdc @@ -0,0 +1,9 @@ +--- +description: Project working agreement — always applied +alwaysApply: true +--- + +The conventions for this repository live in `AGENTS.md` at the root. Follow it: +the build / test / run commands, the code conventions, and the working agreement +(verify don't assume; silence is never consent; green at your branch is not green +at the merge; no secrets or personal data in the repo). diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..5efabf7 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,8 @@ + + +Follow the working agreement and conventions in **AGENTS.md** at the repository +root: the build / test / run commands, the code conventions, and the rules — +especially "verify, don't assume" and "no secrets or personal data in the repo." diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b947504 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# AGENTS.md + + + +## What this project is +**agent-ready** is a dependency-free kit of drop-in conventions that make any +repository ready for AI collaboration: an `AGENTS.md`, a memory scaffold, and +thin per-tool adapters. `install.sh` copies the files under `templates/` into a +target repo. The kit itself is what you see here — this repo dogfoods it (the +`AGENTS.md`, `CLAUDE.md`, `memory/`, and adapters at the root were installed by +running `./install.sh .`). + +## Build, run, test +- **Setup:** `brew install shellcheck bats-core` (macOS) · `apt-get install -y shellcheck bats` (Linux). The kit ships with **zero** runtime dependencies; these are dev-only, for lint + tests. +- **Build:** none — pure POSIX shell plus static `templates/` and `docs/`. Nothing to compile. +- **Test:** `bats tests/install.bats` ← run this before calling any change "done" +- **Run:** `./install.sh [--force] [TARGET_DIR]` — installs the kit into `TARGET_DIR` (default `.`); never overwrites an existing file unless `--force`. +- **Lint / format:** `shellcheck install.sh` + +> If a change is observable when the project runs, run it and confirm the +> behavior — not just that tests pass. For installer changes, run +> `./install.sh` against a scratch dir and inspect what landed. + +## Conventions +- **Code:** POSIX `sh` only — `#!/usr/bin/env sh`, `set -eu`, no bashisms. Must pass `shellcheck` clean. Otherwise match the surrounding file. +- **Commits:** `scope: summary`, lowercase, imperative (e.g. `install.sh: …`, `tests: …`, `ci: …`, `docs: …`, `README: …`). Small, reversible, one idea each. +- **Branches / PRs:** work on a branch; PR into `main`. CI (shellcheck + bats) must be green. +- **Layout:** `install.sh` (the installer) · `templates/` (what gets installed: `AGENTS.md`, `adapters/`, `memory/`) · `docs/` (principles, scaling, + the rendered GitHub Pages site) · `tests/install.bats` · `.github/workflows/ci.yml`. + +## The working agreement +These hold for every change, whoever — or whatever — makes it: + +1. **Verify, don't assume.** "Tests pass" is not "it works." Exercise the real + change; for a bug fix, first confirm the test *fails without the fix*. +2. **Silence is never consent.** Before anything irreversible or outward-facing + — publish, delete, send, deploy, merge, change access — get an + explicit yes. A missing objection is not approval. +3. **Green at your branch is not green at the merge.** Re-verify against the + current tip of `main` before integrating. +4. **Say what actually happened.** Failed tests are reported with output; skipped + steps are named; uncertainty is stated as uncertainty. +5. **No secrets or personal data** in the repo, logs, commits, or anything + shared. Scan before publishing. +6. **Security-sensitive changes** (auth, tokens, crypto, sessions, access) get a + review and tests that can actually fail on the bug class. + +## Do not +- Don't hand-maintain the installer's copy list — it's derived from `templates/` + at runtime (drop a file under `templates/` and it installs automatically). + Keep that property; don't hard-code filenames in `install.sh`. +- Don't add runtime dependencies — "no dependencies" is a stated promise (and a + README badge). Dev tooling (shellcheck, bats) is the only exception. +- Don't introduce bashisms or anything shellcheck flags. +- Don't work around required checks or branch protection. +- Don't automate an irreversible action (arming auto-merge *is* merging). + +## Memory (optional) +Durable, non-obvious facts live in `/memory` (read `memory/MEMORY.md` at the +start of a session). See the kit's `docs/` if you adopt it. + +## Scaling to many agents (optional) +Only if several agents work here at once do you need coordination rules; see +`docs/scaling.md`. Most projects don't — don't add ceremony you can't yet +justify. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..34e8a9c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,8 @@ + + +See **[AGENTS.md](AGENTS.md)** for how to work in this repository: build / test / +run commands, code conventions, and the working agreement (verify don't assume; +silence is never consent; no secrets in the repo). Follow it as if written here. diff --git a/memory/EXAMPLE.md b/memory/EXAMPLE.md new file mode 100644 index 0000000..b2b2687 --- /dev/null +++ b/memory/EXAMPLE.md @@ -0,0 +1,18 @@ +--- +name: example-fact +description: One line used to decide whether this memory is relevant to recall +type: reference # one of: user | feedback | project | reference +--- + +The durable fact goes here — something true about this project that isn't obvious +from the code and would cost a future session (human or AI) real time to +re-derive: a decision and its reasoning, a non-obvious gotcha, a constraint that +isn't written anywhere else. + +Convert relative dates to absolute ("last week" → a real date). Link related +notes with double brackets like [[another-memory-name]]. + +Then add a one-line pointer to this file in `MEMORY.md`. + +Delete this example once you have real memories — and delete any memory that +turns out to be wrong. A stale memory is worse than none. diff --git a/memory/MEMORY.md b/memory/MEMORY.md new file mode 100644 index 0000000..f1137aa --- /dev/null +++ b/memory/MEMORY.md @@ -0,0 +1,12 @@ + + +# Memory index + + + +_No memories yet. Add the first durable fact you'd hate to re-derive._