From 0559e497f6227da11816cb73133541347cada92f Mon Sep 17 00:00:00 2001 From: castrojo Date: Tue, 8 Sep 2026 09:47:38 -0400 Subject: [PATCH 1/2] docs: add Copilot workflow instructions Assisted-by: GPT-5.6 Terra via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 34 +++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..db54f7e7 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,34 @@ +# Copilot instructions + +Read `AGENTS.md` first. It is the authoritative repository contract. Then use +`docs/SKILL.md` to load only the skill that matches the task. + +## Project shape + +This is a Docusaurus site. User-facing docs and blog pages are built with +React components under `src/`; build-time fetchers under `scripts/` populate +data consumed by dashboard and catalog components. Do not hand-edit generated +data under `static/data/`. + +## Live pages and audits + +- Audit an externally visible page from the live, cache-busted route and the + matching `origin/main` source. A local branch or tracked seed is not + evidence of the deployed state. +- For standalone docs UI, use `src/css/custom.css`, Infima variables, and + established local components as the visual source of truth. Keep styling for + external services isolated; it must not reshape the documentation site. +- If a task asks for a live, deployed, shipped, or merged result, completion + requires the merge to `main`, a successful Pages deployment, and a + cache-busted request to the requested route. A local commit, branch, or open + pull request is not completion. + +## Worktrees and validation + +- Use a linked worktree for changes when the main checkout is not already + isolated. In a new worktree, run `npm install --legacy-peer-deps` before + broad checks: release-card tests resolve assets from that worktree's own + `node_modules`. +- Use focused `node --test scripts/.test.js` checks during development. + Run `just check` before every commit. Use `npm run build:ci` to validate a + build without refetching remote data. From f059ec89f68c298e4f7e64191a0e91c6f41d10c8 Mon Sep 17 00:00:00 2001 From: castrojo Date: Tue, 8 Sep 2026 09:56:00 -0400 Subject: [PATCH 2/2] docs: require skill and agent improvements Assisted-by: GPT-5.6 Terra via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 8 ++++++++ docs/skills/skill-improvement.md | 16 +++++++++++----- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index db54f7e7..5c95047b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -32,3 +32,11 @@ data under `static/data/`. - Use focused `node --test scripts/.test.js` checks during development. Run `just check` before every commit. Use `npm run build:ci` to validate a build without refetching remote data. + +## Learning capture + +- Every completed engineering task updates the smallest relevant + `docs/skills/` procedure when it yields a reusable lesson. If the lesson + changes how an agent investigates, validates, designs, or ships work, update + the applicable agent instructions in the same change. Neither update + substitutes for the other. diff --git a/docs/skills/skill-improvement.md b/docs/skills/skill-improvement.md index 4abd9274..c4485088 100644 --- a/docs/skills/skill-improvement.md +++ b/docs/skills/skill-improvement.md @@ -40,8 +40,11 @@ that, every session starts from zero. 1. Ship the requested work and verify it. 2. Extract one reusable, non-obvious lesson from the work. 3. Put that lesson in the smallest relevant `docs/skills/` file. -4. Commit the skill update with the work in the same pull request. -5. Re-read the skill as a new agent and remove status reports, dates, and +4. Update the applicable agent instruction file when the lesson changes how an + agent must investigate, validate, design, or ship work. +5. Commit the skill and agent-instruction updates with the work in the same + pull request. +6. Re-read the skill as a new agent and remove status reports, dates, and resolved issue lists. ## The two-output rule @@ -49,10 +52,12 @@ that, every session starts from zero. Every session produces two outputs: 1. **The work** — the PR, fix, or feature. -2. **The learning** — what a future agent needs to know. +2. **The learning** — what a future agent needs to know, in the relevant skill + and, when applicable, agent instructions. Output 1 without output 2 means the factory did not improve. The learning goes -in `docs/skills/`, in the **same pull request**, never a follow-up. +in `docs/skills/` and any applicable agent instructions, in the **same pull +request**, never a follow-up. ## What earns a skill file @@ -142,7 +147,8 @@ agent. That is the bar. ## Red Flags -- The session ends with implementation changes but no skill update. +- The session ends with implementation changes but no skill and agent + instruction updates when the lesson applies to both. - A skill contains dates, resolved work items, live status, or a running backlog. - The learning is a summary of changed files rather than an operating rule.