Two files, one repository

andreaswasita/copilot-agents-dojo ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ Copilot instructions

A · AGENTS.md · 1619 words B · .github/copilot-instructions.md · 1007 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	15	16	0%
Commands	0	2	1	0%
Section tags	4	1	4	44%

What each file covers

Sections

0 shared · 15 only in A · 16 only in B

− Copilot Agents Dojo — Contributor Guide
− Project Structure
− Adding a Skill
− Adding a CLI Command
− Testing
− Test Discipline — No Change-Detector Tests
− Supply Chain Policy
− Task Plan Policy
− Cache-Aware Mutations
− Curator (Skill Lifecycle)
− Delegation & Durability
− Profile / Multi-Instance Support
− Rules for profile-safe code
− Known Pitfalls
− Related Files
+ Copilot Instructions
+ Code Standards
+ TypeScript (Default Example)
+ Python
+ Java
+ Go
+ .NET
+ Superpowers Activated
+ Mandatory Workflow Pipeline
+ Core Kata — 基本型 (always active)
+ Flow Waza — 流れ技 (activate in sequence)
+ Practical Kumite — 実践組手 (load on demand)
+ Meta Dō — 道
+ Task Management
+ Helper Scripts
+ Memory Vault

Commands

0 shared · 2 only in A · 1 only in B

− task
− pytest
+ go fmt

Section tags

4 shared · 1 only in A · 4 only in B

− architecture
+ lint-format
+ types
+ performance
+ deployment
test
security
do-not
agent-behaviour

Line diff

+109 added−209 removed33 unchanged13.6% identical

andreaswasita/copilot-agents-dojo · AGENTS.md

@@ −1 @@

1# Copilot Agents Dojo — Contributor Guide

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).

5This file is load-bearing. Reviewers may reject PRs that violate the rules below.

7---

9## Project Structure

11File counts shift constantly — don't treat the tree below as exhaustive. The canonical source is the filesystem.

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```

54---

56## Adding a Skill

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.

66The full reviewer checklist lives in `.github/known-pitfalls.md`.

68---

70## Adding a CLI Command

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.

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.

76---

78## Testing

80**Always use `scripts/verify.sh`** (or `scripts/run-checks.ps1` on Windows). The wrapper enforces hermetic env parity with CI:

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 |

89Direct `pytest` calls on a developer machine diverge from CI in ways that have caused "works locally, fails in CI" incidents in other projects.

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```

98### Test Discipline — No Change-Detector Tests

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

194|---|---|---|---|

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

andreaswasita/copilot-agents-dojo · .github/copilot-instructions.md

@@ +1 @@

1# Copilot Instructions

3## Code Standards

5Customize this section for your stack. Examples for common fighting styles:

7### TypeScript (Default Example)

8- Always use TypeScript with `strict: true`

9- Naming: camelCase for variables/functions, PascalCase for components/types

10- Styling: Tailwind CSS + shadcn/ui components

11- Testing: Write Vitest tests for every new component/logic

12- Architecture: Next.js App Router, Server Actions, React Server Components when possible

13- Security: Never commit secrets, use environment variables

15### Python

16- Type hints on all function signatures

17- Formatting: Black (line length 88)

18- Testing: pytest with fixtures, aim for >80% coverage

19- Linting: ruff or flake8

20- Architecture: FastAPI or Django conventions as applicable

21- Dependency management: pyproject.toml / requirements.txt pinned

23### Java

24- Follow Google Java Style Guide

25- Testing: JUnit 5 + Mockito for unit tests

26- Build: Maven or Gradle (match existing project)

27- Architecture: Spring Boot patterns, constructor injection

28- Security: OWASP dependency check in CI

30### Go

31- Follow standard library conventions and `go fmt`

32- Testing: table-driven tests with `testing` package

33- Error handling: explicit, no panic in library code

34- Architecture: clean package boundaries, interfaces for testability

36### .NET

37- Nullable reference types enabled

38- Testing: xUnit + FluentAssertions

39- Architecture: clean architecture, MediatR for CQRS if applicable

40- Security: never log PII, use IOptions pattern for config

42> **Pick your style.** Delete the others or keep them as reference.

44## Superpowers Activated

46At session start: read [SOUL.md](../SOUL.md) first — the identity charter defining **who the agent is, how it reasons, and where its limits are** — then load all skills from `skills/`. Follow the mandatory workflow. Never improvise.

48See [skills.md](../skills.md) for the full skills index. Each skill is a self-contained folder under `skills/` with a `SKILL.md` file. Load the relevant skill when its trigger conditions are met.

50### Mandatory Workflow Pipeline

52Every non-trivial task follows this sequence:

54```

55BRAINSTORM → WORKTREE → PLAN → EXECUTE → TEST → REVIEW → FINISH → LEARN

56```

581. **[Brainstorming](../skills/brainstorming/SKILL.md)** → Socratic design refinement, get approval

592. **[Using git worktrees](../skills/using-git-worktrees/SKILL.md)** → Isolated workspace on feature branch

603. **[Plan before code](../skills/plan-before-code/SKILL.md)** → Break into tasks in `tasks/todo.md`

614. **[Executing plans](../skills/executing-plans/SKILL.md)** → One task at a time, verify each

625. **[Test writing](../skills/test-writing/SKILL.md)** → RED-GREEN-REFACTOR for every change

636. **[Requesting code review](../skills/requesting-code-review/SKILL.md)** → Self-review against plan

647. **[Finishing a development branch](../skills/finishing-a-development-branch/SKILL.md)** → Verify, merge decision, cleanup

658. **[Self-improvement](../skills/self-improvement/SKILL.md)** → Log lessons, update metrics

67### Core Kata — 基本型 (always active)

68- **[Plan before code](../skills/plan-before-code/SKILL.md)**: Enter plan mode for any non-trivial task (3+ steps). Write plan to `tasks/todo.md`.

69- **[Verify before done](../skills/verify-before-done/SKILL.md)**: Run tests, check logs, diff against main. Never mark complete without proof.

70- **[Subagent strategy](../skills/subagent-strategy/SKILL.md)**: Offload research and parallel analysis to subagents. Keep context clean.

71- **[Self-improvement](../skills/self-improvement/SKILL.md)**: Capture lessons in `tasks/lessons.md` after any correction. Review at session start.

72- **[Demand elegance](../skills/demand-elegance/SKILL.md)**: Challenge shortcuts on non-trivial changes. Skip for simple fixes — don't over-engineer.

73- **[Autonomous bug fix](../skills/autonomous-bug-fix/SKILL.md)**: Reproduce → diagnose → fix → verify. Zero hand-holding. No context switching from the user.

75### Flow Waza — 流れ技 (activate in sequence)

76- **[Brainstorming](../skills/brainstorming/SKILL.md)**: Refine ideas via Socratic questioning before code

77- **[Using git worktrees](../skills/using-git-worktrees/SKILL.md)**: Isolated workspace for every session

78- **[Executing plans](../skills/executing-plans/SKILL.md)**: Dispatch and execute tasks from todo.md

79- **[Requesting code review](../skills/requesting-code-review/SKILL.md)**: Self-review against plan between tasks

80- **[Receiving code review](../skills/receiving-code-review/SKILL.md)**: Process feedback and iterate

81- **[Finishing a development branch](../skills/finishing-a-development-branch/SKILL.md)**: Final verification + merge + cleanup

82- **[Dispatching parallel agents](../skills/dispatching-parallel-agents/SKILL.md)**: Concurrent sub-agent work when beneficial

84### Practical Kumite — 実践組手 (load on demand)

85- **[Code review](../skills/code-review/SKILL.md)**: For reviewing PRs or diffs

86- **[Refactoring](../skills/refactoring/SKILL.md)**: For restructuring code safely

87- **[Test writing](../skills/test-writing/SKILL.md)**: For writing meaningful tests

88- **[PR workflow](../skills/pr-workflow/SKILL.md)**: For preparing merge-ready PRs

89- **[Debugging](../skills/debugging/SKILL.md)**: For systematic complex debugging

90- **[Codebase onboarding](../skills/codebase-onboarding/SKILL.md)**: For understanding unfamiliar repos

92### Meta Dō — 道

93- **[Skill creator](../skills/skill-creator/SKILL.md)**: For creating new custom skills

94- **[Writing skills](../skills/writing-skills/SKILL.md)**: SKILL.md template and spec compliance

95- **[Using superpowers](../skills/using-superpowers/SKILL.md)**: Framework activator — loads everything

97## Task Management

991. **Session Start**: Load superpowers. Read `memory/INDEX.md`. Review `tasks/lessons.md`. Check git status.

1002. **Brainstorm**: For new features, refine design via Socratic questioning. Get approval.

1013. **Isolate**: Create git worktree or feature branch. Verify clean test baseline.

1024. **Plan**: Write plan to `tasks/todo.md` with checkable items.

1035. **Execute**: One task at a time. Verify after each. Commit per task.

1046. **Review**: Self-review against plan after each task/batch.

1057. **Verify Before Done**: Run `scripts/verify.sh` or manually run tests/diffs.

1068. **Finish**: Present merge options. Clean up worktree. Log lessons.

1079. **Learn**: Update `tasks/lessons.md` after corrections. Promote 3+ patterns to `memory/patterns/`. Record decisions in `memory/decisions/`. Write session summary to `memory/sessions/`. Run `scripts/link-index.sh`.

108

109## Helper Scripts

110

111The `/scripts/` directory contains automation helpers. Reference them in your workflow:

112

113- **`scripts/init.sh`** — Scaffolds `tasks/todo.md` and `tasks/lessons.md` on first clone.

114- **`scripts/lesson-updater.sh`** — Scans `tasks/lessons.md` for recurring patterns (3+ occurrences) and proposes rule amendments to `skills.md`.

115- **`scripts/verify.sh`** — Pre-PR verification: runs tests, checks for uncommitted changes, validates that `tasks/todo.md` has a plan.

116- **`scripts/link-index.sh`** — Builds the memory vault link graph. Scans `memory/` for markdown links, generates backlink sections, updates `memory/INDEX.md` stats, and writes `memory/.link-graph.json` for programmatic queries.

117- **`scripts/memory-query.sh`** — Query the memory vault by tag, type, date, status, or free text. Use `--backlinks-for` to find what references a file. Lightweight Dataview replacement.

118- **`scripts/obsidian-sync.sh`** — Syncs `tasks/lessons.md` into the memory vault as `memory/patterns/` candidates.

119

120Use these for all sessions to ensure consistency.

121

122## Memory Vault

123

124The `memory/` directory is the agent's persistent knowledge graph. It replaces flat-file memory with structured, linked knowledge.

125

126```

127memory/

128├── INDEX.md ← Map of Content (read this first)

129├── .link-graph.json ← Machine-readable link graph

130├── decisions/ ← Architectural decisions with context

131├── patterns/ ← Proven rules promoted from lessons (3+ occurrences)

132├── preferences/ ← User behavioral preferences (learned over time)

133└── sessions/ ← Session summaries linking to everything above

134```

135

136**Rules:**

137- Read `memory/INDEX.md` at every session start

138- Use relative markdown links between files (not wikilinks)

139- Run `scripts/link-index.sh` after creating or editing memory files

140- Query with `scripts/memory-query.sh` before reading every file manually

141- Templates in each subdirectory (`_template.md`) define the required structure

142

@@ −1 +1 @@

1−# Copilot Agents Dojo — Contributor Guide

1+# Copilot Instructions

3−Authoritative 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).

3+## Code Standards

5−This file is load-bearing. Reviewers may reject PRs that violate the rules below.

5+Customize this section for your stack. Examples for common fighting styles:

7−---

7+### TypeScript (Default Example)

8+- Always use TypeScript with `strict: true`

9+- Naming: camelCase for variables/functions, PascalCase for components/types

10+- Styling: Tailwind CSS + shadcn/ui components

11+- Testing: Write Vitest tests for every new component/logic

12+- Architecture: Next.js App Router, Server Actions, React Server Components when possible

13+- Security: Never commit secrets, use environment variables

814

9−## Project Structure

15+### Python

16+- Type hints on all function signatures

17+- Formatting: Black (line length 88)

18+- Testing: pytest with fixtures, aim for >80% coverage

19+- Linting: ruff or flake8

20+- Architecture: FastAPI or Django conventions as applicable

21+- Dependency management: pyproject.toml / requirements.txt pinned

1022

11−File counts shift constantly — don't treat the tree below as exhaustive. The canonical source is the filesystem.

23+### Java

24+- Follow Google Java Style Guide

25+- Testing: JUnit 5 + Mockito for unit tests

26+- Build: Maven or Gradle (match existing project)

27+- Architecture: Spring Boot patterns, constructor injection

28+- Security: OWASP dependency check in CI

1229

13−```

14−copilot-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−```

30+### Go

31+- Follow standard library conventions and `go fmt`

32+- Testing: table-driven tests with `testing` package

33+- Error handling: explicit, no panic in library code

34+- Architecture: clean package boundaries, interfaces for testability

5335

54−---

36+### .NET

37+- Nullable reference types enabled

38+- Testing: xUnit + FluentAssertions

39+- Architecture: clean architecture, MediatR for CQRS if applicable

40+- Security: never log PII, use IOptions pattern for config

5541

56−## Adding a Skill

42+> **Pick your style.** Delete the others or keep them as reference.

5743

58−1. Copy `template/SKILL.md` to `skills/<name>/SKILL.md` (or `optional-skills/<name>/` for heavyweight skills).

59−2. Fill in **all required frontmatter** — see [`spec/copilot-skills-spec.md`](spec/copilot-skills-spec.md) §1.

60−3. Write the body in the **required section order** — spec §2.

61−4. Reference real Copilot tools in backticks (`view`, `edit`, `grep`, `glob`, `powershell`, `web_fetch`, `task`). NOT bare shell utilities — spec §3.

62−5. If the skill needs deterministic logic, add `scripts/` (ship `.sh` + `.ps1` for cross-platform) and `tests/`.

63−6. Run `scripts/verify.sh` locally. It must pass.

64−7. Open the PR. Reviewer checks against `.github/known-pitfalls.md` + the spec.

44+## Superpowers Activated

6545

66−The full reviewer checklist lives in `.github/known-pitfalls.md`.

46+At session start: read [SOUL.md](../SOUL.md) first — the identity charter defining **who the agent is, how it reasons, and where its limits are** — then load all skills from `skills/`. Follow the mandatory workflow. Never improvise.

6747

68−---

48+See [skills.md](../skills.md) for the full skills index. Each skill is a self-contained folder under `skills/` with a `SKILL.md` file. Load the relevant skill when its trigger conditions are met.

6949

70−## Adding a CLI Command

50+### Mandatory Workflow Pipeline

7151

72−The 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.

52+Every non-trivial task follows this sequence:

7353

74−Until 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−

89−Direct `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

92−scripts/verify.sh # full gate

93−scripts/verify.sh tests # only the pytest suite

94−scripts/verify.sh spec # only the spec/frontmatter invariants

95−scripts/verify.sh --check # CI mode: fail on any drift

9654 ```

55+BRAINSTORM → WORKTREE → PLAN → EXECUTE → TEST → REVIEW → FINISH → LEARN

56+```

9757

98−### Test Discipline — No Change-Detector Tests

58+1. **[Brainstorming](../skills/brainstorming/SKILL.md)** → Socratic design refinement, get approval

59+2. **[Using git worktrees](../skills/using-git-worktrees/SKILL.md)** → Isolated workspace on feature branch

60+3. **[Plan before code](../skills/plan-before-code/SKILL.md)** → Break into tasks in `tasks/todo.md`

61+4. **[Executing plans](../skills/executing-plans/SKILL.md)** → One task at a time, verify each

62+5. **[Test writing](../skills/test-writing/SKILL.md)** → RED-GREEN-REFACTOR for every change

63+6. **[Requesting code review](../skills/requesting-code-review/SKILL.md)** → Self-review against plan

64+7. **[Finishing a development branch](../skills/finishing-a-development-branch/SKILL.md)** → Verify, merge decision, cleanup

65+8. **[Self-improvement](../skills/self-improvement/SKILL.md)** → Log lessons, update metrics

9966

100−A 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).

67+### Core Kata — 基本型 (always active)

68+- **[Plan before code](../skills/plan-before-code/SKILL.md)**: Enter plan mode for any non-trivial task (3+ steps). Write plan to `tasks/todo.md`.

69+- **[Verify before done](../skills/verify-before-done/SKILL.md)**: Run tests, check logs, diff against main. Never mark complete without proof.

70+- **[Subagent strategy](../skills/subagent-strategy/SKILL.md)**: Offload research and parallel analysis to subagents. Keep context clean.

71+- **[Self-improvement](../skills/self-improvement/SKILL.md)**: Capture lessons in `tasks/lessons.md` after any correction. Review at session start.

72+- **[Demand elegance](../skills/demand-elegance/SKILL.md)**: Challenge shortcuts on non-trivial changes. Skip for simple fixes — don't over-engineer.

73+- **[Autonomous bug fix](../skills/autonomous-bug-fix/SKILL.md)**: Reproduce → diagnose → fix → verify. Zero hand-holding. No context switching from the user.

10174

102−---

75+### Flow Waza — 流れ技 (activate in sequence)

76+- **[Brainstorming](../skills/brainstorming/SKILL.md)**: Refine ideas via Socratic questioning before code

77+- **[Using git worktrees](../skills/using-git-worktrees/SKILL.md)**: Isolated workspace for every session

78+- **[Executing plans](../skills/executing-plans/SKILL.md)**: Dispatch and execute tasks from todo.md

79+- **[Requesting code review](../skills/requesting-code-review/SKILL.md)**: Self-review against plan between tasks

80+- **[Receiving code review](../skills/receiving-code-review/SKILL.md)**: Process feedback and iterate

81+- **[Finishing a development branch](../skills/finishing-a-development-branch/SKILL.md)**: Final verification + merge + cleanup

82+- **[Dispatching parallel agents](../skills/dispatching-parallel-agents/SKILL.md)**: Concurrent sub-agent work when beneficial

10383

104−## Supply Chain Policy

84+### Practical Kumite — 実践組手 (load on demand)

85+- **[Code review](../skills/code-review/SKILL.md)**: For reviewing PRs or diffs

86+- **[Refactoring](../skills/refactoring/SKILL.md)**: For restructuring code safely

87+- **[Test writing](../skills/test-writing/SKILL.md)**: For writing meaningful tests

88+- **[PR workflow](../skills/pr-workflow/SKILL.md)**: For preparing merge-ready PRs

89+- **[Debugging](../skills/debugging/SKILL.md)**: For systematic complex debugging

90+- **[Codebase onboarding](../skills/codebase-onboarding/SKILL.md)**: For understanding unfamiliar repos

10591

106−Adopted after the litellm and Shai-Hulud incidents to limit attack surface on PR builds.

92+### Meta Dō — 道

93+- **[Skill creator](../skills/skill-creator/SKILL.md)**: For creating new custom skills

94+- **[Writing skills](../skills/writing-skills/SKILL.md)**: SKILL.md template and spec compliance

95+- **[Using superpowers](../skills/using-superpowers/SKILL.md)**: Framework activator — loads everything

10796

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` | — |

97+## Task Management

11498

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.

99+1. **Session Start**: Load superpowers. Read `memory/INDEX.md`. Review `tasks/lessons.md`. Check git status.

100+2. **Brainstorm**: For new features, refine design via Socratic questioning. Get approval.

101+3. **Isolate**: Create git worktree or feature branch. Verify clean test baseline.

102+4. **Plan**: Write plan to `tasks/todo.md` with checkable items.

103+5. **Execute**: One task at a time. Verify after each. Commit per task.

104+6. **Review**: Self-review against plan after each task/batch.

105+7. **Verify Before Done**: Run `scripts/verify.sh` or manually run tests/diffs.

106+8. **Finish**: Present merge options. Clean up worktree. Log lessons.

107+9. **Learn**: Update `tasks/lessons.md` after corrections. Promote 3+ patterns to `memory/patterns/`. Record decisions in `memory/decisions/`. Write session summary to `memory/sessions/`. Run `scripts/link-index.sh`.

116108

117−---

109+## Helper Scripts

118110

119−## Task Plan Policy

111+The `/scripts/` directory contains automation helpers. Reference them in your workflow:

120112

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.

113+- **`scripts/init.sh`** — Scaffolds `tasks/todo.md` and `tasks/lessons.md` on first clone.

114+- **`scripts/lesson-updater.sh`** — Scans `tasks/lessons.md` for recurring patterns (3+ occurrences) and proposes rule amendments to `skills.md`.

115+- **`scripts/verify.sh`** — Pre-PR verification: runs tests, checks for uncommitted changes, validates that `tasks/todo.md` has a plan.

116+- **`scripts/link-index.sh`** — Builds the memory vault link graph. Scans `memory/` for markdown links, generates backlink sections, updates `memory/INDEX.md` stats, and writes `memory/.link-graph.json` for programmatic queries.

117+- **`scripts/memory-query.sh`** — Query the memory vault by tag, type, date, status, or free text. Use `--backlinks-for` to find what references a file. Lightweight Dataview replacement.

118+- **`scripts/obsidian-sync.sh`** — Syncs `tasks/lessons.md` into the memory vault as `memory/patterns/` candidates.

122119

123−Rules:

120+Use these for all sessions to ensure consistency.

124121

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.

122+## Memory Vault

128123

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.

124+The `memory/` directory is the agent's persistent knowledge graph. It replaces flat-file memory with structured, linked knowledge.

130125

131−---

132−

133−## Cache-Aware Mutations

134−

135−Copilot 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−

141−This mirrors the equivalent policy in `hermes-agent` (`/skills install --now` is the canonical pattern there).

142−

143−---

144−

145−## Curator (Skill Lifecycle)

146−

147−Agent-created skills (those with `created_by: agent` in frontmatter) flow through a **state machine** managed by `scripts/curator.sh`:

148−

149126 ```

150−active ──(no use for STALE_DAYS, default 30)──▶ stale

151−stale ──(no use for ARCHIVE_DAYS, default 90)─▶ archived → skills/.archive/<name>/

127+memory/

128+├── INDEX.md ← Map of Content (read this first)

129+├── .link-graph.json ← Machine-readable link graph

130+├── decisions/ ← Architectural decisions with context

131+├── patterns/ ← Proven rules promoted from lessons (3+ occurrences)

132+├── preferences/ ← User behavioral preferences (learned over time)

133+└── sessions/ ← Session summaries linking to everything above

152134 ```

153135

154−State 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−

158−1. Frontmatter `created_by: human` (legacy guard).

159−2. 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."

160−3. `pinned: true` in the usage sidecar.

161−

162−Invariants (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

173−bash scripts/curator-tick.sh # gated: 168h interval, 2h idle defaults

174−bash scripts/curator-tick.sh --force --dry-run # preview without gates

175−pwsh scripts/curator-tick.ps1 # Windows wrapper

176−```

177−

178−Wire 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−

185−The 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−

191−The dojo distinguishes three execution scopes. **Pick the right one.**

192−

194−|---|---|---|---|

198−

199−Default 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−

205−The 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

208−DOJO_ROOT=apps/backend scripts/verify.sh

209−DOJO_ROOT=apps/frontend scripts/verify.sh

210−```

211−

212−The CLI accepts `--profile <name>` as syntactic sugar for `DOJO_ROOT=~/.dojo/profiles/<name>`.

213−

214−### Rules for profile-safe code

215−

216−1. NEVER hardcode `.github/`, `tasks/`, `skills/` in scripts. Use `${DOJO_ROOT:-$PWD}/…`.

217−2. Tests must isolate to a temp `DOJO_ROOT`.

218−3. User-facing messages reference `${DOJO_ROOT}/…` so the output is correct for the active profile.

219−

220−---

221−

222−## Known Pitfalls

223−

224−The complete imperative `DO NOT` register lives in [`.github/known-pitfalls.md`](.github/known-pitfalls.md). Skim it before any non-trivial PR.

225−

226−When you discover a new pitfall:

227−

228−1. Add an entry there.

229−2. Add a regression check in `scripts/verify.sh` if it's machine-checkable.

230−3. 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.)

136+**Rules:**

137+- Read `memory/INDEX.md` at every session start

138+- Use relative markdown links between files (not wikilinks)

139+- Run `scripts/link-index.sh` after creating or editing memory files

140+- Query with `scripts/memory-query.sh` before reading every file manually

141+- Templates in each subdirectory (`_template.md`) define the required structure

242142

Two files, one repository

Built for the same person as RuleStack