AGENTS.md

1# Copilot Agents Dojo — Contributor Guide
2 
3Authoritative reference for humans (and AI assistants) **modifying** the dojo itself. If you're just *using* the dojo in your own repo, start with [`README.md`](README.md). If you're inside an agent session running on the dojo, the runtime prompt is [`.github/copilot-instructions.md`](.github/copilot-instructions.md).
4 
5This file is load-bearing. Reviewers may reject PRs that violate the rules below.
6 
7---
8 
9## Project Structure
10 
11File counts shift constantly — don't treat the tree below as exhaustive. The canonical source is the filesystem.
12 
13```
14copilot-agents-dojo/
15├── AGENTS.md                          # this file — contributor reference
16├── README.md                          # user-facing onboarding
17├── SOUL.md                            # agent identity charter (who / how / limits)
18├── skills.md                          # GENERATED — skills index grouped by tier
19├── spec/
20│   └── copilot-skills-spec.md         # the HARDLINE skill spec (v1)
21├── template/
22│   └── SKILL.md                       # canonical starter for new skills
23├── skills/                            # core + practical skills (always discoverable)
24│   ├── plan-before-code/SKILL.md      # tier: core
25│   ├── code-review/SKILL.md           # tier: practical
26│   └── …
27├── optional-skills/                   # heavy / niche skills (installed explicitly)
28├── scripts/
29│   ├── init.sh                        # scaffold tasks/{todo,lessons}.md
30│   ├── verify.sh                      # the lint/test/invariant gate
31│   ├── run-checks.ps1                 # Windows parity for verify.sh
32│   ├── regen-skills-index.sh          # rebuilds skills.md from frontmatter
33│   ├── lesson-updater.sh              # cache-aware skill amendments
34│   └── curator.sh                     # skill lifecycle (pin/archive/restore)
35├── tasks/
36│   ├── todo.md                        # current plan (rollup of tasks/board/)
37│   ├── lessons.md                     # postmortem log
38│   └── board/                         # durable per-task markdown files
39├── agents/                            # persona briefs (architect, TPM, etc.)
40├── mcp/
41│   ├── registry.yaml                  # MCP server catalog
42│   ├── servers/                       # per-server JSON manifests
43│   └── scripts/                       # mcp-subprocess wrappers
44├── cli/
45│   └── dojo_cli/                      # optional Python CLI (marketplace + scanner)
46├── .github/
47│   ├── copilot-instructions.md        # runtime prompt for sessions in this repo
48│   ├── known-pitfalls.md              # imperative DO NOT register
49│   └── workflows/dojo-enforce.yml     # PR enforcement
50└── .dojo/                             # per-clone state (telemetry, profiles); gitignored
51    └── skill-usage.json               # curator telemetry sidecar
52```
53 
54---
55 
56## Adding a Skill
57 
581. Copy `template/SKILL.md` to `skills/<name>/SKILL.md` (or `optional-skills/<name>/` for heavyweight skills).
592. Fill in **all required frontmatter** — see [`spec/copilot-skills-spec.md`](spec/copilot-skills-spec.md) §1.
603. Write the body in the **required section order** — spec §2.
614. Reference real Copilot tools in backticks (`view`, `edit`, `grep`, `glob`, `powershell`, `web_fetch`, `task`). NOT bare shell utilities — spec §3.
625. If the skill needs deterministic logic, add `scripts/` (ship `.sh` + `.ps1` for cross-platform) and `tests/`.
636. Run `scripts/verify.sh` locally. It must pass.
647. Open the PR. Reviewer checks against `.github/known-pitfalls.md` + the spec.
65 
66The full reviewer checklist lives in `.github/known-pitfalls.md`.
67 
68---
69 
70## Adding a CLI Command
71 
72The optional Python CLI lives in `cli/dojo_cli/`. Commands are centralized in `cli/dojo_cli/registry.py` (see Phase 5 of the roadmap) — adding a command is one entry in `COMMAND_REGISTRY`. `app.py`, `--help`, `marketplace.py`, and shell completion all derive from it.
73 
74Until that registry exists, follow the per-file pattern in `app.py` but keep new commands tiny and dependency-free — the CLI is a convenience, never a hard dependency.
75 
76---
77 
78## Testing
79 
80**Always use `scripts/verify.sh`** (or `scripts/run-checks.ps1` on Windows). The wrapper enforces hermetic env parity with CI:
81 
82| | Without wrapper | With wrapper |
83|---|---|---|
84| Credentials | Whatever is in your env | All `*_TOKEN` / `*_API_KEY` unset |
85| Timezone | Local | UTC |
86| Locale | Local | C.UTF-8 |
87| `DOJO_ROOT` | Inherited | Temp dir per skill test |
88 
89Direct `pytest` calls on a developer machine diverge from CI in ways that have caused "works locally, fails in CI" incidents in other projects.
90 
91```bash
92scripts/verify.sh                       # full gate
93scripts/verify.sh tests                 # only the pytest suite
94scripts/verify.sh spec                  # only the spec/frontmatter invariants
95scripts/verify.sh --check               # CI mode: fail on any drift
96```
97 
98### Test Discipline — No Change-Detector Tests
99 
100A test that snapshots current data (skill count, list contents, version literal) fails every time the data legitimately changes. Write **invariants** instead. Concrete examples in [`.github/known-pitfalls.md`](.github/known-pitfalls.md#do-not-write-change-detector-tests).
101 
102---
103 
104## Supply Chain Policy
105 
106Adopted after the litellm and Shai-Hulud incidents to limit attack surface on PR builds.
107 
108| Source | Treatment | Example |
109|---|---|---|
110| GitHub Actions | Commit SHA + version comment | `uses: actions/checkout@<sha>  # v4` |
111| PyPI (CLI deps) | `>=floor,<next_major` | `httpx>=0.28.1,<1` |
112| npm (any tooling) | `>=floor,<next_major`, lockfile committed | — |
113| Shell binaries | Document expected version in `Prerequisites` | — |
114 
115`.github/workflows/dojo-enforce.yml` greps for unpinned `uses:` lines and fails the build. Bare `>=X.Y.Z` without a ceiling is rejected at review.
116 
117---
118 
119## Task Plan Policy
120 
121`tasks/todo.md` in this repository is a **canonical scaffold template**, not a working plan for the dojo's own development. Downstream consumers (anyone who runs `bash scripts/init.sh` against their own project) fill it in for their actual work; the version that ships in this repo must stay in its scaffold form.
122 
123Rules:
124 
125- **PRs to this repo MUST NOT replace `tasks/todo.md` with a real plan.** Branch protection enforces this via the `Plan sanity` required check, which runs `scripts/verify.sh plan` in canonical-repo mode.
126- **Working plans for dojo PRs live elsewhere:** the agent's session folder (`~/.copilot/session-state/<session-id>/plan.md`), a scratch branch outside the canonical scaffold, or PR descriptions/issues. Not in `tasks/todo.md`.
127- **`tasks/lessons.md` IS expected to evolve** in this repo — it's the dojo's own learning log. The plan check only asserts presence, not content.
128 
129`scripts/verify.sh` detects canonical-repo mode by the presence of `spec/copilot-skills-spec.md`, `skills/`, and `scripts/init.sh` together. In any other repo (a downstream consumer's clone), the same script inverts the assertion: the scaffold template warns, a real plan passes.
130 
131---
132 
133## Cache-Aware Mutations
134 
135Copilot caches the prompt — including the skills it loads at session start. Anything that mutates a skill, the `skills.md` index, or `.github/copilot-instructions.md` mid-session invalidates that cache and dramatically increases cost.
136 
137**Rule:** skill amendments default to **deferred** invalidation. The change is written to disk now; it takes effect on the next Copilot session.
138 
139`scripts/lesson-updater.sh` honors this by default. Pass `--now` only when correctness requires immediate effect — the script prints a warning about the cache-invalidation cost when you do.
140 
141This mirrors the equivalent policy in `hermes-agent` (`/skills install --now` is the canonical pattern there).
142 
143---
144 
145## Curator (Skill Lifecycle)
146 
147Agent-created skills (those with `created_by: agent` in frontmatter) flow through a **state machine** managed by `scripts/curator.sh`:
148 
149```
150active  ──(no use for STALE_DAYS, default 30)──▶  stale
151stale   ──(no use for ARCHIVE_DAYS, default 90)─▶ archived  → skills/.archive/<name>/
152```
153 
154State is stored per-entry in `.dojo/skill-usage.json`. Any `record`/`view` resets state to `active`.
155 
156**Three-layer provenance guard.** A skill is exempt from every auto-transition if any of these is true:
157 
1581. Frontmatter `created_by: human` (legacy guard).
1592. Folder name appears in `.dojo/bundled-manifest.txt` — regenerated by `scripts/regen-skills-index.sh` from `skills/` + `optional-skills/`. This is the source of truth for "ships with the dojo."
1603. `pinned: true` in the usage sidecar.
161 
162Invariants (all enforced by `scripts/curator.sh`):
163 
164- The curator NEVER deletes — max destructive action is archive to `skills/.archive/`.
165- Every mutating run takes a tarball backup to `.dojo/curator-backups/<UTC>/skills.tgz` first (keeps last 5; tunable via `DOJO_CURATOR_BACKUP_KEEP`). `rollback` is reversible — it backs up the *current* state before restoring.
166- Every transition run writes a per-run report to `.dojo/logs/curator/<UTC>-transition/REPORT.md` + `run.json` (keeps last 20).
167 
168**Verbs:** `status`, `record`, `pin`, `unpin`, `archive`, `restore`, `transition` (alias: `prune`), `backup`, `rollback`, `report`. Full lifecycle docs live in `skills/self-improvement/SKILL.md`.
169 
170**Idle-based trigger** (the hermes pattern). Don't run the curator on every prompt — let it fire only when the agent is quiet for a while:
171 
172```bash
173bash scripts/curator-tick.sh                     # gated: 168h interval, 2h idle defaults
174bash scripts/curator-tick.sh --force --dry-run   # preview without gates
175pwsh scripts/curator-tick.ps1                    # Windows wrapper
176```
177 
178Wire it into one of: shell rc (`zsh-defer`/PowerShell `$PROFILE`), a `pre-commit` hook, `cron`/`launchd`, or Windows Task Scheduler. Per-environment overrides go in `.dojo/curator.env` (sourced if present): `DOJO_CURATOR_STALE_DAYS`, `DOJO_CURATOR_ARCHIVE_DAYS`, `DOJO_CURATOR_INTERVAL_HOURS`, `DOJO_CURATOR_MIN_IDLE_HOURS`, `DOJO_CURATOR_BACKUP_KEEP`, `DOJO_CURATOR_REPORT_KEEP`.
179 
180**Prerequisite:** `jq` must be on `PATH`.
181- macOS: `brew install jq`
182- Linux (apt): `sudo apt install jq`
183- Windows: `winget install jqlang.jq` (or `scoop install jq`)
184 
185The Windows wrappers (`scripts/curator.ps1`, `scripts/curator-tick.ps1`) add the WinGet shim directory to `PATH` automatically; for direct `bash` use on Windows, ensure `jq` resolves in git-bash.
186 
187---
188 
189## Delegation & Durability
190 
191The dojo distinguishes three execution scopes. **Pick the right one.**
192 
193| Scope | Tool | Durable across turn? | Use when |
194|---|---|---|---|
195| Sub-agent | `task` (Copilot's built-in) | **No** — cancelled if parent interrupted | Focused research / parallel reads inside this turn |
196| Durable board | `scripts/board.sh` + `tasks/board/` | Yes, survives session | Work assigned to another agent or resumed later |
197| Scheduled | GitHub Actions workflow | Yes, survives everything | Recurring or time-based work |
198 
199Default sub-agent limits: `max_spawn_depth: 2`, `max_concurrent_children: 3`. Don't exceed without justification. See `skills/subagent-strategy/SKILL.md` and `skills/durable-work/SKILL.md`.
200 
201---
202 
203## Profile / Multi-Instance Support
204 
205The dojo can live anywhere — not just at the repo root. All scripts and the CLI resolve paths from `${DOJO_ROOT:-$PWD}`. Use the env var when running multiple dojo instances side-by-side (e.g., one per monorepo subproject):
206 
207```bash
208DOJO_ROOT=apps/backend  scripts/verify.sh
209DOJO_ROOT=apps/frontend scripts/verify.sh
210```
211 
212The CLI accepts `--profile <name>` as syntactic sugar for `DOJO_ROOT=~/.dojo/profiles/<name>`.
213 
214### Rules for profile-safe code
215 
2161. NEVER hardcode `.github/`, `tasks/`, `skills/` in scripts. Use `${DOJO_ROOT:-$PWD}/…`.
2172. Tests must isolate to a temp `DOJO_ROOT`.
2183. User-facing messages reference `${DOJO_ROOT}/…` so the output is correct for the active profile.
219 
220---
221 
222## Known Pitfalls
223 
224The complete imperative `DO NOT` register lives in [`.github/known-pitfalls.md`](.github/known-pitfalls.md). Skim it before any non-trivial PR.
225 
226When you discover a new pitfall:
227 
2281. Add an entry there.
2292. Add a regression check in `scripts/verify.sh` if it's machine-checkable.
2303. Reference it from the relevant `SKILL.md`'s `Pitfalls` section.
231 
232---
233 
234## Related Files
235 
236- [`README.md`](README.md) — user-facing onboarding
237- [`spec/copilot-skills-spec.md`](spec/copilot-skills-spec.md) — the HARDLINE skill spec
238- [`template/SKILL.md`](template/SKILL.md) — starter for new skills
239- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) — runtime prompt
240- [`.github/known-pitfalls.md`](.github/known-pitfalls.md) — DO NOT register
241- [`CONTRIBUTING.md`](CONTRIBUTING.md) — PR mechanics (branch naming, signoff, etc.)
242