From 6f48d320d3a7836079a0430b2378a5e3196f7770 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 28 Aug 2026 20:38:59 +0000 Subject: [PATCH] fix(guides): keep catalog out of the plugin skills tree Move the user-facing catalog from skills/guides to docs/guides so it is not shipped with the plugin package. Hosts install the skills/ tree as payload; a sibling directory without SKILL.md still goes out with every install. Co-authored-by: Kieran Klaassen --- .../ce-skill-work/references/new-skill.md | 2 +- AGENTS.md | 7 +-- CONTRIBUTING.md | 2 +- README.md | 44 +++++++++---------- {skills => docs}/guides/README.md | 0 {skills => docs}/guides/ce-babysit-pr.md | 0 {skills => docs}/guides/ce-brainstorm.md | 0 {skills => docs}/guides/ce-code-review.md | 0 {skills => docs}/guides/ce-commit-push-pr.md | 0 {skills => docs}/guides/ce-commit.md | 0 .../guides/ce-compound-refresh.md | 0 {skills => docs}/guides/ce-compound.md | 0 {skills => docs}/guides/ce-debug.md | 0 {skills => docs}/guides/ce-doc-review.md | 0 {skills => docs}/guides/ce-dogfood.md | 0 {skills => docs}/guides/ce-explain.md | 0 {skills => docs}/guides/ce-handoff.md | 0 {skills => docs}/guides/ce-ideate.md | 0 {skills => docs}/guides/ce-optimize.md | 0 {skills => docs}/guides/ce-plan.md | 0 {skills => docs}/guides/ce-polish.md | 0 {skills => docs}/guides/ce-pov.md | 0 {skills => docs}/guides/ce-product-pulse.md | 0 {skills => docs}/guides/ce-promote.md | 0 {skills => docs}/guides/ce-proof.md | 0 {skills => docs}/guides/ce-prototype.md | 0 .../guides/ce-resolve-pr-feedback.md | 0 {skills => docs}/guides/ce-retune.md | 0 .../guides/ce-riffrec-feedback-analysis.md | 0 {skills => docs}/guides/ce-setup.md | 0 {skills => docs}/guides/ce-simplify-code.md | 0 {skills => docs}/guides/ce-strategy.md | 0 {skills => docs}/guides/ce-sweep.md | 0 {skills => docs}/guides/ce-test-browser.md | 0 {skills => docs}/guides/ce-test-xcode.md | 0 {skills => docs}/guides/ce-work.md | 0 {skills => docs}/guides/ce-worktree.md | 0 {skills => docs}/guides/configuration.md | 0 {skills => docs}/guides/lfg.md | 0 ...oring-auto-invoke-standing-instructions.md | 4 +- tests/ce-test-browser-driver-policy.test.ts | 4 +- tests/docs-root-literals.test.ts | 6 +-- tests/release-metadata.test.ts | 17 ++++++- tests/review-skill-contract.test.ts | 2 +- tests/scratch-root-contract.test.ts | 1 - tests/scratch-root-preamble-executes.test.ts | 1 - .../ce-brainstorm-section-order.test.ts | 2 +- .../skills/ce-doc-review-html-editing.test.ts | 4 +- tests/skills/ce-proof-contract.test.ts | 4 +- tests/skills/ce-prototype-protocol.test.ts | 1 - tests/skills/ce-setup-check-health.test.ts | 18 ++++---- tests/skills/ce-work-outcome-spine.test.ts | 2 +- tests/skills/cross-model-review-mode.test.ts | 6 +-- tests/skills/flatten-safety.test.ts | 1 - .../skill-body-extraction-contract.test.ts | 2 +- .../unified-plan-artifact-contract.test.ts | 2 +- 56 files changed, 71 insertions(+), 61 deletions(-) rename {skills => docs}/guides/README.md (100%) rename {skills => docs}/guides/ce-babysit-pr.md (100%) rename {skills => docs}/guides/ce-brainstorm.md (100%) rename {skills => docs}/guides/ce-code-review.md (100%) rename {skills => docs}/guides/ce-commit-push-pr.md (100%) rename {skills => docs}/guides/ce-commit.md (100%) rename {skills => docs}/guides/ce-compound-refresh.md (100%) rename {skills => docs}/guides/ce-compound.md (100%) rename {skills => docs}/guides/ce-debug.md (100%) rename {skills => docs}/guides/ce-doc-review.md (100%) rename {skills => docs}/guides/ce-dogfood.md (100%) rename {skills => docs}/guides/ce-explain.md (100%) rename {skills => docs}/guides/ce-handoff.md (100%) rename {skills => docs}/guides/ce-ideate.md (100%) rename {skills => docs}/guides/ce-optimize.md (100%) rename {skills => docs}/guides/ce-plan.md (100%) rename {skills => docs}/guides/ce-polish.md (100%) rename {skills => docs}/guides/ce-pov.md (100%) rename {skills => docs}/guides/ce-product-pulse.md (100%) rename {skills => docs}/guides/ce-promote.md (100%) rename {skills => docs}/guides/ce-proof.md (100%) rename {skills => docs}/guides/ce-prototype.md (100%) rename {skills => docs}/guides/ce-resolve-pr-feedback.md (100%) rename {skills => docs}/guides/ce-retune.md (100%) rename {skills => docs}/guides/ce-riffrec-feedback-analysis.md (100%) rename {skills => docs}/guides/ce-setup.md (100%) rename {skills => docs}/guides/ce-simplify-code.md (100%) rename {skills => docs}/guides/ce-strategy.md (100%) rename {skills => docs}/guides/ce-sweep.md (100%) rename {skills => docs}/guides/ce-test-browser.md (100%) rename {skills => docs}/guides/ce-test-xcode.md (100%) rename {skills => docs}/guides/ce-work.md (100%) rename {skills => docs}/guides/ce-worktree.md (100%) rename {skills => docs}/guides/configuration.md (100%) rename {skills => docs}/guides/lfg.md (100%) diff --git a/.agents/skills/ce-skill-work/references/new-skill.md b/.agents/skills/ce-skill-work/references/new-skill.md index a3bd9430d..5ce96d415 100644 --- a/.agents/skills/ce-skill-work/references/new-skill.md +++ b/.agents/skills/ce-skill-work/references/new-skill.md @@ -29,7 +29,7 @@ Contrast pair (the only description example): ## Repo inventory (all in the same change) -A user-facing skill needs: `skills/guides/.md` (purpose, novel mechanics, when to use, chain position), a catalog row in `skills/guides/README.md`, a root `README.md` inventory row, and the skill-count bump in `tests/release-metadata.test.ts`. Run `bun run release:validate` and `bun run test`. +A user-facing skill needs: `docs/guides/.md` (purpose, novel mechanics, when to use, chain position), a catalog row in `docs/guides/README.md`, a root `README.md` inventory row, and the skill-count bump in `tests/release-metadata.test.ts`. Run `bun run release:validate` and `bun run test`. ## Validate diff --git a/AGENTS.md b/AGENTS.md index 52414c88c..7e5257645 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,7 +63,7 @@ bun run codex:dev -- remove # remove both supported CE installation surfaces ``` src/ CLI entry point, parsers, converters, target writers skills/ Compound Engineering plugin skills -skills/guides/ User-facing skill catalog +docs/guides/ User-facing plugin guides (catalog and configuration) .claude-plugin/ Claude plugin manifest and marketplace catalog metadata .codex-plugin/ Codex plugin manifest .cursor-plugin/ Cursor plugin manifest and marketplace catalog metadata @@ -89,8 +89,8 @@ Do not assume a repo change is "just CLI" or "just plugin" without checking whic When changing plugin content: - Update substantive docs like `README.md` when the plugin behavior, inventory, or usage changes. -- When adding a user-facing skill, document it: create a `skills/guides/.md` page (purpose, novel mechanics, when to use, chain position — follow the shape of the existing pages), add a catalog row under the right category in `skills/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`. `skills/guides/README.md` is the **only** place a skill's prose description is maintained. The root `README.md` carries a grouped overview that lists skill *names* under a category, so a new skill also needs its name added to the right group row and the three stated skill counts bumped (badge, intro, section lead). `tests/release-metadata.test.ts` enforces that every skill name appears in that overview exactly once, that no unknown name appears, and that the three counts match the skill directories under `skills/` (each with a `SKILL.md`) — so the suite catches a missing name, a stale count, or a name left behind during a move. Choosing the *right* group is yours; a test that knew the correct category per skill would be the second inventory this arrangement exists to avoid — the previous three-way sync of full descriptions was unenforced and had already drifted, which is why descriptions now live in exactly one place. Every current user-facing skill has a page, including `lfg` and `ce-dogfood`. -- When adding, removing, renaming, or changing the meaning/default/consumer of a `.compound-engineering/config.yaml` option, update `skills/ce-setup/references/config-template.yaml`, its byte-identical `.compound-engineering/config.example.yaml` copy, the centralized `skills/guides/configuration.md` reference, and the affected consumer skill docs in the same change. Ordinary keys may also live in optional checkout-local `config.local.yaml` (overrides the repo file). `docs_root` belongs only in `config.yaml`. Durable team instructions still belong in the project's normal agent-instructions mechanism. +- When adding a user-facing skill, document it: create a `docs/guides/.md` page (purpose, novel mechanics, when to use, chain position — follow the shape of the existing pages), add a catalog row under the right category in `docs/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`. `docs/guides/README.md` is the **only** place a skill's prose description is maintained. The root `README.md` carries a grouped overview that lists skill *names* under a category, so a new skill also needs its name added to the right group row and the three stated skill counts bumped (badge, intro, section lead). `tests/release-metadata.test.ts` enforces that every skill name appears in that overview exactly once, that no unknown name appears, and that the three counts match the skill directories under `skills/` (each with a `SKILL.md`) — so the suite catches a missing name, a stale count, or a name left behind during a move. Choosing the *right* group is yours; a test that knew the correct category per skill would be the second inventory this arrangement exists to avoid — the previous three-way sync of full descriptions was unenforced and had already drifted, which is why descriptions now live in exactly one place. Every current user-facing skill has a page, including `lfg` and `ce-dogfood`. +- When adding, removing, renaming, or changing the meaning/default/consumer of a `.compound-engineering/config.yaml` option, update `skills/ce-setup/references/config-template.yaml`, its byte-identical `.compound-engineering/config.example.yaml` copy, the centralized `docs/guides/configuration.md` reference, and the affected consumer skill docs in the same change. Ordinary keys may also live in optional checkout-local `config.local.yaml` (overrides the repo file). `docs_root` belongs only in `config.yaml`. Durable team instructions still belong in the project's normal agent-instructions mechanism. - Do not hand-bump release-owned versions in plugin or marketplace manifests. - Do not hand-add release entries to `CHANGELOG.md` or treat it as the canonical source for new releases. - Run `bun run release:validate` if agents, commands, skills, MCP servers, or release-owned descriptions/counts may have changed. @@ -343,6 +343,7 @@ So: a skill's *core* behavior **can** live in a bundled script across hosts — ## Repository Docs Convention +- **Guides** live in `docs/guides/` — the user-facing skill catalog and configuration reference. Keep them here, not under `skills/`, so they do not ship inside the plugin package. - **Plans** live in `docs/plans/` — unified plan artifacts. New `ce-brainstorm` outputs are requirements-only unified plans (`artifact_readiness: requirements-only`); `ce-plan` enriches them to implementation-ready plans (`artifact_readiness: implementation-ready`). Historical `docs/brainstorms/*-requirements.*` files remain readable legacy inputs and should not be migrated just because a new plan is created. - **Brainstorm evidence / legacy requirements** may live in `docs/brainstorms/` — historical requirements docs and specialized analysis artifacts such as `docs/brainstorms/riffrec-feedback/`. Do not treat this as the canonical output path for new `ce-brainstorm` artifacts. - **Solutions** live in `docs/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b55c08c8b..2f09bd768 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ Do not hand-bump versions in plugin or marketplace manifests, and do not hand-wr Skills live in `skills//SKILL.md` and are authored once, then distributed to every supported host. That makes them different from ordinary code: a skill is a set of goals, not a state machine, and it has to work on harnesses with different capabilities. Read `AGENTS.md` before changing anything under `skills/`. -When you add a user-facing skill, document it: add a `skills/guides/.md` page and a catalog row in `skills/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`. +When you add a user-facing skill, document it: add a `docs/guides/.md` page and a catalog row in `docs/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`. ## Reporting security issues diff --git a/README.md b/README.md index c4175f804..39d92bad7 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![Build Status](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE) -[![Skills](https://img.shields.io/badge/skills-33-black.svg)](skills/guides/README.md) +[![Skills](https://img.shields.io/badge/skills-33-black.svg)](docs/guides/README.md) @@ -125,12 +125,12 @@ The core loop is six steps: **brainstorm** the requirements, **plan** the implem | Skill | Purpose | |-------|---------| -| [`/ce-brainstorm`](skills/guides/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a requirements-only unified plan before planning | -| [`/ce-plan`](skills/guides/ce-plan.md) | Enrich feature ideas or requirements-only plans into implementation-ready plans | -| [`/ce-work`](skills/guides/ce-work.md) | Execute implementation-ready plans natively or through a qualified cross-model author while retaining host verification, commits, and shipping | -| [`/ce-simplify-code`](skills/guides/ce-simplify-code.md) | Refine the freshly written code for clarity and reuse before review | -| [`/ce-code-review`](skills/guides/ce-code-review.md) | Report-only multi-agent review against the plan before merging; local apply is explicit | -| [`/ce-compound`](skills/guides/ce-compound.md) | Capture the learning into `docs/solutions/` so the next loop starts smarter | +| [`/ce-brainstorm`](docs/guides/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a requirements-only unified plan before planning | +| [`/ce-plan`](docs/guides/ce-plan.md) | Enrich feature ideas or requirements-only plans into implementation-ready plans | +| [`/ce-work`](docs/guides/ce-work.md) | Execute implementation-ready plans natively or through a qualified cross-model author while retaining host verification, commits, and shipping | +| [`/ce-simplify-code`](docs/guides/ce-simplify-code.md) | Refine the freshly written code for clarity and reuse before review | +| [`/ce-code-review`](docs/guides/ce-code-review.md) | Report-only multi-agent review against the plan before merging; local apply is explicit | +| [`/ce-compound`](docs/guides/ce-compound.md) | Capture the learning into `docs/solutions/` so the next loop starts smarter | Each cycle compounds: `/ce-compound` writes learnings that the next `/ce-brainstorm` and `/ce-plan` read as grounding -- brainstorms sharpen plans, plans inform future plans, reviews catch more issues, patterns get documented. That return arrow is the whole point. @@ -140,7 +140,7 @@ Each cycle compounds: `/ce-compound` writes learnings that the next `/ce-brainst Replayed from a real pair of sessions 18 days apart, with names and paths anonymized and the six-minute run compressed to about 30 seconds. Nothing shown is behavior the skills don't have — see assets/demo for the source and the substitutions. -> Artifact folders like `docs/solutions/` and `docs/plans/` are the **defaults**. A project whose `docs/` is tracked content can relocate every CE artifact folder under one repo-relative root via the `docs_root` setting -- see [configuration](skills/guides/configuration.md#artifact-root). +> Artifact folders like `docs/solutions/` and `docs/plans/` are the **defaults**. A project whose `docs/` is tracked content can relocate every CE artifact folder under one repo-relative root via the `docs_root` setting -- see [configuration](docs/guides/configuration.md#artifact-root). ## Try it @@ -166,26 +166,26 @@ After installing, run `/ce-setup` in any project. It reports optional tool capab `/lfg` runs the loop hands-off: it plans, works through the plan, simplifies, runs code review and applies the fixes, runs browser tests, then commits. When a git remote exists it pushes, opens a PR, and watches CI with a bounded repair loop (it does not merge, and it can finish with leftovers if the repair budget is hit). With no remote it stops at local commits. Start it after `/ce-brainstorm` so it plans against real requirements rather than a one-line prompt. -Starting from a bug instead of a feature? Use [`/ce-debug`](skills/guides/ce-debug.md). Not sure what to build yet? Start with [`/ce-ideate`](skills/guides/ce-ideate.md). +Starting from a bug instead of a feature? Use [`/ce-debug`](docs/guides/ce-debug.md). Not sure what to build yet? Start with [`/ce-ideate`](docs/guides/ce-ideate.md). ## Skills at a glance -33 skills, grouped by what they are for. The full catalog, with a page per skill and how each one chains into the others, is in **[skills/guides](skills/guides/README.md)**. +33 skills, grouped by what they are for. The full catalog, with a page per skill and how each one chains into the others, is in **[docs/guides](docs/guides/README.md)**. | Group | Skills | What it covers | |-------|--------|----------------| -| [Core loop](skills/guides/README.md#the-core-loop) | `ce-brainstorm` `ce-plan` `ce-work` `ce-simplify-code` `ce-code-review` `ce-compound` | The six steps of every iteration | -| [Around the loop](skills/guides/README.md#around-the-loop) | `ce-strategy` `ce-product-pulse` `ce-sweep` `ce-compound-refresh` | Anchors and feeds that keep the loop grounded | -| [On demand](skills/guides/README.md#on-demand) | `ce-ideate` `ce-pov` `ce-debug` `ce-explain` `ce-doc-review` `ce-optimize` `ce-prototype` | Reached for when a specific need arises | -| [Git workflow](skills/guides/README.md#git-workflow) | `ce-commit` `ce-commit-push-pr` `ce-babysit-pr` `ce-resolve-pr-feedback` `ce-worktree` | Committing, shipping, and shepherding PRs | -| [Autonomous](skills/guides/README.md#autonomous-pipeline) | `lfg` | The whole pipeline, hands-off | -| [Testing & design](skills/guides/README.md#frontend-design) | `ce-test-browser` `ce-test-xcode` `ce-polish` `ce-dogfood` | Verifying and polishing what you built | -| [Collaboration](skills/guides/README.md#collaboration) | `ce-proof` `ce-handoff` `ce-promote` | Sharing work and handing it off | -| [Utilities](skills/guides/README.md#workflow-utilities) | `ce-setup` `ce-retune` `ce-riffrec-feedback-analysis` | Setup and maintenance | +| [Core loop](docs/guides/README.md#the-core-loop) | `ce-brainstorm` `ce-plan` `ce-work` `ce-simplify-code` `ce-code-review` `ce-compound` | The six steps of every iteration | +| [Around the loop](docs/guides/README.md#around-the-loop) | `ce-strategy` `ce-product-pulse` `ce-sweep` `ce-compound-refresh` | Anchors and feeds that keep the loop grounded | +| [On demand](docs/guides/README.md#on-demand) | `ce-ideate` `ce-pov` `ce-debug` `ce-explain` `ce-doc-review` `ce-optimize` `ce-prototype` | Reached for when a specific need arises | +| [Git workflow](docs/guides/README.md#git-workflow) | `ce-commit` `ce-commit-push-pr` `ce-babysit-pr` `ce-resolve-pr-feedback` `ce-worktree` | Committing, shipping, and shepherding PRs | +| [Autonomous](docs/guides/README.md#autonomous-pipeline) | `lfg` | The whole pipeline, hands-off | +| [Testing & design](docs/guides/README.md#frontend-design) | `ce-test-browser` `ce-test-xcode` `ce-polish` `ce-dogfood` | Verifying and polishing what you built | +| [Collaboration](docs/guides/README.md#collaboration) | `ce-proof` `ce-handoff` `ce-promote` | Sharing work and handing it off | +| [Utilities](docs/guides/README.md#workflow-utilities) | `ce-setup` `ce-retune` `ce-riffrec-feedback-analysis` | Setup and maintenance | **Learn more** -- [Skill documentation catalog](skills/guides/README.md) +- [Skill documentation catalog](docs/guides/README.md) - [Compound engineering: how Every codes with agents](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents) - [The story behind compounding engineering](https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it) @@ -418,7 +418,7 @@ No. Bun is only needed for repo development tasks and converter maintenance. ### Where do I see all available skills? -The grouped overview is [above](#skills-at-a-glance); the full catalog with a page per skill is [`skills/guides/README.md`](skills/guides/README.md). Each skill's authoritative runtime spec lives in `skills//SKILL.md`. +The grouped overview is [above](#skills-at-a-glance); the full catalog with a page per skill is [`docs/guides/README.md`](docs/guides/README.md). Each skill's authoritative runtime spec lives in `skills//SKILL.md`. ### Where is release history? @@ -432,8 +432,8 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, and [`docs/development.md`]( | | | |---|---| -| [Skill catalog](skills/guides/README.md) | A page per skill, and how they chain together | -| [Configuration](skills/guides/configuration.md) | `.compound-engineering/config.yaml` options | +| [Skill catalog](docs/guides/README.md) | A page per skill, and how they chain together | +| [Configuration](docs/guides/configuration.md) | `.compound-engineering/config.yaml` options | | [Installing](#install) · [Upgrading](docs/install/upgrading.md) | Per-host install and refresh | | [Contributing](CONTRIBUTING.md) · [Development](docs/development.md) | Working on the plugin itself | | [Security](SECURITY.md) · [Privacy](PRIVACY.md) | Reporting and data handling | diff --git a/skills/guides/README.md b/docs/guides/README.md similarity index 100% rename from skills/guides/README.md rename to docs/guides/README.md diff --git a/skills/guides/ce-babysit-pr.md b/docs/guides/ce-babysit-pr.md similarity index 100% rename from skills/guides/ce-babysit-pr.md rename to docs/guides/ce-babysit-pr.md diff --git a/skills/guides/ce-brainstorm.md b/docs/guides/ce-brainstorm.md similarity index 100% rename from skills/guides/ce-brainstorm.md rename to docs/guides/ce-brainstorm.md diff --git a/skills/guides/ce-code-review.md b/docs/guides/ce-code-review.md similarity index 100% rename from skills/guides/ce-code-review.md rename to docs/guides/ce-code-review.md diff --git a/skills/guides/ce-commit-push-pr.md b/docs/guides/ce-commit-push-pr.md similarity index 100% rename from skills/guides/ce-commit-push-pr.md rename to docs/guides/ce-commit-push-pr.md diff --git a/skills/guides/ce-commit.md b/docs/guides/ce-commit.md similarity index 100% rename from skills/guides/ce-commit.md rename to docs/guides/ce-commit.md diff --git a/skills/guides/ce-compound-refresh.md b/docs/guides/ce-compound-refresh.md similarity index 100% rename from skills/guides/ce-compound-refresh.md rename to docs/guides/ce-compound-refresh.md diff --git a/skills/guides/ce-compound.md b/docs/guides/ce-compound.md similarity index 100% rename from skills/guides/ce-compound.md rename to docs/guides/ce-compound.md diff --git a/skills/guides/ce-debug.md b/docs/guides/ce-debug.md similarity index 100% rename from skills/guides/ce-debug.md rename to docs/guides/ce-debug.md diff --git a/skills/guides/ce-doc-review.md b/docs/guides/ce-doc-review.md similarity index 100% rename from skills/guides/ce-doc-review.md rename to docs/guides/ce-doc-review.md diff --git a/skills/guides/ce-dogfood.md b/docs/guides/ce-dogfood.md similarity index 100% rename from skills/guides/ce-dogfood.md rename to docs/guides/ce-dogfood.md diff --git a/skills/guides/ce-explain.md b/docs/guides/ce-explain.md similarity index 100% rename from skills/guides/ce-explain.md rename to docs/guides/ce-explain.md diff --git a/skills/guides/ce-handoff.md b/docs/guides/ce-handoff.md similarity index 100% rename from skills/guides/ce-handoff.md rename to docs/guides/ce-handoff.md diff --git a/skills/guides/ce-ideate.md b/docs/guides/ce-ideate.md similarity index 100% rename from skills/guides/ce-ideate.md rename to docs/guides/ce-ideate.md diff --git a/skills/guides/ce-optimize.md b/docs/guides/ce-optimize.md similarity index 100% rename from skills/guides/ce-optimize.md rename to docs/guides/ce-optimize.md diff --git a/skills/guides/ce-plan.md b/docs/guides/ce-plan.md similarity index 100% rename from skills/guides/ce-plan.md rename to docs/guides/ce-plan.md diff --git a/skills/guides/ce-polish.md b/docs/guides/ce-polish.md similarity index 100% rename from skills/guides/ce-polish.md rename to docs/guides/ce-polish.md diff --git a/skills/guides/ce-pov.md b/docs/guides/ce-pov.md similarity index 100% rename from skills/guides/ce-pov.md rename to docs/guides/ce-pov.md diff --git a/skills/guides/ce-product-pulse.md b/docs/guides/ce-product-pulse.md similarity index 100% rename from skills/guides/ce-product-pulse.md rename to docs/guides/ce-product-pulse.md diff --git a/skills/guides/ce-promote.md b/docs/guides/ce-promote.md similarity index 100% rename from skills/guides/ce-promote.md rename to docs/guides/ce-promote.md diff --git a/skills/guides/ce-proof.md b/docs/guides/ce-proof.md similarity index 100% rename from skills/guides/ce-proof.md rename to docs/guides/ce-proof.md diff --git a/skills/guides/ce-prototype.md b/docs/guides/ce-prototype.md similarity index 100% rename from skills/guides/ce-prototype.md rename to docs/guides/ce-prototype.md diff --git a/skills/guides/ce-resolve-pr-feedback.md b/docs/guides/ce-resolve-pr-feedback.md similarity index 100% rename from skills/guides/ce-resolve-pr-feedback.md rename to docs/guides/ce-resolve-pr-feedback.md diff --git a/skills/guides/ce-retune.md b/docs/guides/ce-retune.md similarity index 100% rename from skills/guides/ce-retune.md rename to docs/guides/ce-retune.md diff --git a/skills/guides/ce-riffrec-feedback-analysis.md b/docs/guides/ce-riffrec-feedback-analysis.md similarity index 100% rename from skills/guides/ce-riffrec-feedback-analysis.md rename to docs/guides/ce-riffrec-feedback-analysis.md diff --git a/skills/guides/ce-setup.md b/docs/guides/ce-setup.md similarity index 100% rename from skills/guides/ce-setup.md rename to docs/guides/ce-setup.md diff --git a/skills/guides/ce-simplify-code.md b/docs/guides/ce-simplify-code.md similarity index 100% rename from skills/guides/ce-simplify-code.md rename to docs/guides/ce-simplify-code.md diff --git a/skills/guides/ce-strategy.md b/docs/guides/ce-strategy.md similarity index 100% rename from skills/guides/ce-strategy.md rename to docs/guides/ce-strategy.md diff --git a/skills/guides/ce-sweep.md b/docs/guides/ce-sweep.md similarity index 100% rename from skills/guides/ce-sweep.md rename to docs/guides/ce-sweep.md diff --git a/skills/guides/ce-test-browser.md b/docs/guides/ce-test-browser.md similarity index 100% rename from skills/guides/ce-test-browser.md rename to docs/guides/ce-test-browser.md diff --git a/skills/guides/ce-test-xcode.md b/docs/guides/ce-test-xcode.md similarity index 100% rename from skills/guides/ce-test-xcode.md rename to docs/guides/ce-test-xcode.md diff --git a/skills/guides/ce-work.md b/docs/guides/ce-work.md similarity index 100% rename from skills/guides/ce-work.md rename to docs/guides/ce-work.md diff --git a/skills/guides/ce-worktree.md b/docs/guides/ce-worktree.md similarity index 100% rename from skills/guides/ce-worktree.md rename to docs/guides/ce-worktree.md diff --git a/skills/guides/configuration.md b/docs/guides/configuration.md similarity index 100% rename from skills/guides/configuration.md rename to docs/guides/configuration.md diff --git a/skills/guides/lfg.md b/docs/guides/lfg.md similarity index 100% rename from skills/guides/lfg.md rename to docs/guides/lfg.md diff --git a/docs/solutions/skill-design/authoring-auto-invoke-standing-instructions.md b/docs/solutions/skill-design/authoring-auto-invoke-standing-instructions.md index 037709cf3..9156c0ca2 100644 --- a/docs/solutions/skill-design/authoring-auto-invoke-standing-instructions.md +++ b/docs/solutions/skill-design/authoring-auto-invoke-standing-instructions.md @@ -70,7 +70,7 @@ Apply when adding a "Make It Automatic" section to any CE skill's docs page, or The self-guard is verifiable: a cross-host routing eval (5 resolved-scope scenarios × Claude + Codex, fresh subagents reading the on-disk `SKILL.md`) scored 10/10 — docs-only and lockfile/generated scopes short-circuited, a mixed diff narrowed to its code file, and both a ~5-line explicit-scope case and a normal code diff ran, confirming the guard keys on change kind, not size. -Standing-instruction shape (auto-run variant; the dedicated "Make It Automatic" heading was later folded into a short standing-instruction paragraph on `skills/guides/ce-simplify-code.md`): +Standing-instruction shape (auto-run variant; the dedicated "Make It Automatic" heading was later folded into a short standing-instruction paragraph on `docs/guides/ce-simplify-code.md`): > When you finish a coherent unit of work — a feature is complete, or you're wrapping up to open a PR — and before you review, commit, or hand it off, automatically invoke the `ce-simplify-code` skill on the changed code. Do this at that completion checkpoint only, not after every individual edit or intermediate fix while you're still building. Run it only when the accumulated diff has at least 10 substantive code lines and the skill hasn't already run since the last code edit. Never run it for documentation- or Markdown-only changes; formatting-, lint-, or dependency/lockfile-only changes; generated or vendored files; other purely mechanical changes; or code you've said to keep as written. @@ -81,4 +81,4 @@ Skill-side preflight (from `skills/ce-simplify-code/SKILL.md` Step 1): if the re - [`portable-agent-skill-authoring.md`](./portable-agent-skill-authoring.md) — the canonical cross-model/cross-harness authoring guide these phrasing rules instantiate - [`discoverability-check-for-documented-solutions.md`](./discoverability-check-for-documented-solutions.md) — the sibling pattern of a skill making a small, principled edit to an instruction file - [`post-menu-routing-belongs-inline.md`](./post-menu-routing-belongs-inline.md) — related SKILL.md authoring-placement discipline -- `ce-compound`'s "Make Capture Automatic" section (`skills/guides/ce-compound.md`, PR #1110) — the pattern this generalizes +- `ce-compound`'s "Make Capture Automatic" section (`docs/guides/ce-compound.md`, PR #1110) — the pattern this generalizes diff --git a/tests/ce-test-browser-driver-policy.test.ts b/tests/ce-test-browser-driver-policy.test.ts index 218952d93..c6b91d60c 100644 --- a/tests/ce-test-browser-driver-policy.test.ts +++ b/tests/ce-test-browser-driver-policy.test.ts @@ -108,8 +108,8 @@ describe("ce-test-browser browser-driver policy", () => { }) test("user documentation describes the same hierarchy", async () => { - const docs = await readRepoFile("skills/guides/ce-test-browser.md") - const catalog = await readRepoFile("skills/guides/README.md") + const docs = await readRepoFile("docs/guides/ce-test-browser.md") + const catalog = await readRepoFile("docs/guides/README.md") expect(docs).toMatch(/host-native.+integrated browser/is) expect(docs).toMatch(/embedded in or directly owned by the active harness/i) diff --git a/tests/docs-root-literals.test.ts b/tests/docs-root-literals.test.ts index b568d88bb..04da15da4 100644 --- a/tests/docs-root-literals.test.ts +++ b/tests/docs-root-literals.test.ts @@ -47,10 +47,8 @@ function walk(dir: string): string[] { const out: string[] = [] for (const entry of readdirSync(dir, { withFileTypes: true })) { const full = path.join(dir, entry.name) - if (entry.isDirectory()) { - if (entry.name === "guides" && dir === SKILLS_ROOT) continue - out.push(...walk(full)) - } else if (SCANNED_EXTS.has(path.extname(entry.name))) out.push(full) + if (entry.isDirectory()) out.push(...walk(full)) + else if (SCANNED_EXTS.has(path.extname(entry.name))) out.push(full) } return out } diff --git a/tests/release-metadata.test.ts b/tests/release-metadata.test.ts index f48b187e1..fa6180bc8 100644 --- a/tests/release-metadata.test.ts +++ b/tests/release-metadata.test.ts @@ -221,7 +221,7 @@ describe("release metadata", () => { }) // The root README carries skill *names* in its grouped overview while - // skills/guides/README.md owns the descriptions. That split only holds if the + // docs/guides/README.md owns the descriptions. That split only holds if the // names and the stated count cannot drift, so both are pinned here rather // than left to convention -- the three-way prose sync this replaced had // already drifted before anyone noticed. @@ -277,6 +277,21 @@ describe("release metadata", () => { expect(stated.map(Number)).toEqual([skillCount, skillCount, skillCount]) }) + // Hosts install the repo's skills/ tree as the plugin payload. A sibling + // directory without SKILL.md (the #1551 catalog landing under skills/guides) + // ships user docs with every install. The catalog lives in docs/guides/. + test("skills/ contains only skill directories", async () => { + const { readdir } = await import("fs/promises") + const skillsRoot = path.join(process.cwd(), "skills") + const extras = (await readdir(skillsRoot, { withFileTypes: true })) + .filter((entry) => + entry.isDirectory() && !existsSync(path.join(skillsRoot, entry.name, "SKILL.md")) + ) + .map((entry) => entry.name) + .sort() + expect(extras).toEqual([]) + }) + test("builds a stable compound-engineering manifest description", async () => { const description = await buildCompoundEngineeringDescription(process.cwd()) diff --git a/tests/review-skill-contract.test.ts b/tests/review-skill-contract.test.ts index 3eb4448bc..09baf17f1 100644 --- a/tests/review-skill-contract.test.ts +++ b/tests/review-skill-contract.test.ts @@ -665,7 +665,7 @@ describe("ce-code-review contract", () => { const catalog = await readRepoFile( "skills/ce-code-review/references/persona-catalog.md", ) - const docs = await readRepoFile("skills/guides/ce-code-review.md") + const docs = await readRepoFile("docs/guides/ce-code-review.md") expect(content).toContain("**Core (always-on):** `correctness-reviewer`.") expect(content).toMatch(/project-standards-reviewer.*only when Stage 3b finds/i) diff --git a/tests/scratch-root-contract.test.ts b/tests/scratch-root-contract.test.ts index a54d74c83..f2c758d64 100644 --- a/tests/scratch-root-contract.test.ts +++ b/tests/scratch-root-contract.test.ts @@ -8,7 +8,6 @@ const SKILLS_ROOT = path.join(process.cwd(), "skills") function contractFiles(root: string): string[] { return readdirSync(root, { withFileTypes: true }).flatMap((entry) => { - if (entry.isDirectory() && entry.name === "guides" && root === SKILLS_ROOT) return [] const absolute = path.join(root, entry.name) if (entry.isDirectory()) return contractFiles(absolute) return entry.isFile() && /\.(md|py|sh)$/.test(entry.name) ? [absolute] : [] diff --git a/tests/scratch-root-preamble-executes.test.ts b/tests/scratch-root-preamble-executes.test.ts index 88564c57a..33c147ed1 100644 --- a/tests/scratch-root-preamble-executes.test.ts +++ b/tests/scratch-root-preamble-executes.test.ts @@ -45,7 +45,6 @@ setDefaultTimeout(120_000) function contractFiles(root: string): string[] { return readdirSync(root, { withFileTypes: true }).flatMap((entry) => { - if (entry.isDirectory() && entry.name === "guides" && root === SKILLS_ROOT) return [] const absolute = path.join(root, entry.name) if (entry.isDirectory()) return contractFiles(absolute) return entry.isFile() && /\.(md|py|sh)$/.test(entry.name) ? [absolute] : [] diff --git a/tests/skills/ce-brainstorm-section-order.test.ts b/tests/skills/ce-brainstorm-section-order.test.ts index fcad8aeac..c885a80cc 100644 --- a/tests/skills/ce-brainstorm-section-order.test.ts +++ b/tests/skills/ce-brainstorm-section-order.test.ts @@ -11,7 +11,7 @@ const BODY = readFileSync( ) const DOC_BODY = readFileSync( - path.join(process.cwd(), "skills/guides/ce-brainstorm.md"), + path.join(process.cwd(), "docs/guides/ce-brainstorm.md"), "utf8", ) diff --git a/tests/skills/ce-doc-review-html-editing.test.ts b/tests/skills/ce-doc-review-html-editing.test.ts index 9bf10f462..a2ecc681f 100644 --- a/tests/skills/ce-doc-review-html-editing.test.ts +++ b/tests/skills/ce-doc-review-html-editing.test.ts @@ -15,8 +15,8 @@ const PLAN_HANDOFF = read("skills/ce-plan/references/plan-handoff.md") const BRAINSTORM_HANDOFF = read("skills/ce-brainstorm/references/handoff.md") const PLAN_HTML = read("skills/ce-plan/references/html-rendering.md") const BRAINSTORM_HTML = read("skills/ce-brainstorm/references/html-rendering.md") -const BRAINSTORM_DOCS = read("skills/guides/ce-brainstorm.md") -const DOC_REVIEW_DOCS = read("skills/guides/ce-doc-review.md") +const BRAINSTORM_DOCS = read("docs/guides/ce-brainstorm.md") +const DOC_REVIEW_DOCS = read("docs/guides/ce-doc-review.md") describe("ce-doc-review HTML editing", () => { test("applies review fixes in the document's native format", () => { diff --git a/tests/skills/ce-proof-contract.test.ts b/tests/skills/ce-proof-contract.test.ts index f2bf36bbd..cdd838647 100644 --- a/tests/skills/ce-proof-contract.test.ts +++ b/tests/skills/ce-proof-contract.test.ts @@ -7,8 +7,8 @@ function readRepoFile(relativePath: string): string { } const skill = readRepoFile("skills/ce-proof/SKILL.md") -const catalog = readRepoFile("skills/guides/ce-proof.md") -const skillsIndex = readRepoFile("skills/guides/README.md") +const catalog = readRepoFile("docs/guides/ce-proof.md") +const skillsIndex = readRepoFile("docs/guides/README.md") describe("ce-proof v3 + owner lifecycle contract", () => { test("skill teaches Proof v3 read/edit surfaces", () => { diff --git a/tests/skills/ce-prototype-protocol.test.ts b/tests/skills/ce-prototype-protocol.test.ts index d7210cec6..055ec34d0 100644 --- a/tests/skills/ce-prototype-protocol.test.ts +++ b/tests/skills/ce-prototype-protocol.test.ts @@ -279,7 +279,6 @@ describe("ce-prototype protocol", () => { const offenders: string[] = [] for (const rel of new Glob("**/*.md").scanSync({ cwd: SKILLS_ROOT })) { - if (rel.split(/[\\/]/)[0] === "guides") continue const body = readFileSync(path.join(SKILLS_ROOT, rel), "utf8").toLowerCase() for (const phrase of retired) { if (body.includes(phrase)) offenders.push(`skills/${rel}: "${phrase}"`) diff --git a/tests/skills/ce-setup-check-health.test.ts b/tests/skills/ce-setup-check-health.test.ts index a00062ed5..1ceecb660 100644 --- a/tests/skills/ce-setup-check-health.test.ts +++ b/tests/skills/ce-setup-check-health.test.ts @@ -7,9 +7,9 @@ const repoRoot = path.join(import.meta.dir, "..", "..") const checkHealthScript = path.join(repoRoot, "skills", "ce-setup", "scripts", "check-health") const configTemplate = path.join(repoRoot, "skills", "ce-setup", "references", "config-template.yaml") const configExample = path.join(repoRoot, ".compound-engineering", "config.example.yaml") -const configDocs = path.join(repoRoot, "skills", "guides", "configuration.md") -const ceWorkDocs = path.join(repoRoot, "skills", "guides", "ce-work.md") -const lfgDocs = path.join(repoRoot, "skills", "guides", "lfg.md") +const configDocs = path.join(repoRoot, "docs", "guides", "configuration.md") +const ceWorkDocs = path.join(repoRoot, "docs", "guides", "ce-work.md") +const lfgDocs = path.join(repoRoot, "docs", "guides", "lfg.md") type RunResult = { exitCode: number @@ -60,10 +60,10 @@ describe("ce-setup check-health", () => { test("advertises agent-browser only for its current consumers", async () => { const [script, setupDocs, polishSkill, polishRun, polishDocs] = await Promise.all([ readFile(checkHealthScript, "utf8"), - readFile(path.join(repoRoot, "skills", "guides", "ce-setup.md"), "utf8"), + readFile(path.join(repoRoot, "docs", "guides", "ce-setup.md"), "utf8"), readFile(path.join(repoRoot, "skills", "ce-polish", "SKILL.md"), "utf8"), readFile(path.join(repoRoot, "skills", "ce-polish", "references", "run.md"), "utf8"), - readFile(path.join(repoRoot, "skills", "guides", "ce-polish.md"), "utf8"), + readFile(path.join(repoRoot, "docs", "guides", "ce-polish.md"), "utf8"), ]) const capability = "browser testing and dogfood QA" @@ -93,8 +93,8 @@ describe("ce-setup check-health", () => { const [template, docs, setupDocs, catalog, instructions] = await Promise.all([ readFile(configTemplate, "utf8"), readFile(configDocs, "utf8"), - readFile(path.join(repoRoot, "skills", "guides", "ce-setup.md"), "utf8"), - readFile(path.join(repoRoot, "skills", "guides", "README.md"), "utf8"), + readFile(path.join(repoRoot, "docs", "guides", "ce-setup.md"), "utf8"), + readFile(path.join(repoRoot, "docs", "guides", "README.md"), "utf8"), readFile(path.join(repoRoot, "AGENTS.md"), "utf8"), ]) @@ -107,7 +107,7 @@ describe("ce-setup check-health", () => { expect(docs).toContain("CLAUDE.md") expect(setupDocs).toContain("./configuration.md") expect(catalog).toContain("./configuration.md") - expect(instructions).toContain("skills/guides/configuration.md") + expect(instructions).toContain("docs/guides/configuration.md") for (const consumer of [ "ce-brainstorm", @@ -122,7 +122,7 @@ describe("ce-setup check-health", () => { "ce-work", "lfg", ]) { - const consumerDocs = await readFile(path.join(repoRoot, "skills", "guides", `${consumer}.md`), "utf8") + const consumerDocs = await readFile(path.join(repoRoot, "docs", "guides", `${consumer}.md`), "utf8") expect(consumerDocs).toContain("./configuration.md") } }) diff --git a/tests/skills/ce-work-outcome-spine.test.ts b/tests/skills/ce-work-outcome-spine.test.ts index 07e8c5a8e..9134c16ab 100644 --- a/tests/skills/ce-work-outcome-spine.test.ts +++ b/tests/skills/ce-work-outcome-spine.test.ts @@ -736,7 +736,7 @@ describe("ce-work right-sized routes", () => { test("a mechanical diff passes babysit:off to the shipping skill, and the docs say the same", async () => { const shipping = await readRepoFile("skills/ce-work/references/shipping-workflow.md") expect(shipping).toMatch(/Code review: skipped \(mechanical diff\)`, also pass `babysit:off`/) - const docs = await readRepoFile("skills/guides/ce-work.md") + const docs = await readRepoFile("docs/guides/ce-work.md") expect(docs).toMatch(/purely mechanical diff[^.]*ships without a post-PR watch/) expect(docs).not.toMatch(/Trivial route skips the task list and the post-PR watch/) }) diff --git a/tests/skills/cross-model-review-mode.test.ts b/tests/skills/cross-model-review-mode.test.ts index 8efe9605a..566823fe7 100644 --- a/tests/skills/cross-model-review-mode.test.ts +++ b/tests/skills/cross-model-review-mode.test.ts @@ -52,9 +52,9 @@ describe("cross_model_review_mode egress gate", () => { for (const p of [ "skills/ce-setup/references/config-template.yaml", ".compound-engineering/config.example.yaml", - "skills/guides/configuration.md", - "skills/guides/ce-code-review.md", - "skills/guides/ce-doc-review.md", + "docs/guides/configuration.md", + "docs/guides/ce-code-review.md", + "docs/guides/ce-doc-review.md", ]) { expect(read(p)).toContain("cross_model_review_mode") } diff --git a/tests/skills/flatten-safety.test.ts b/tests/skills/flatten-safety.test.ts index fffd666a9..e9331f884 100644 --- a/tests/skills/flatten-safety.test.ts +++ b/tests/skills/flatten-safety.test.ts @@ -55,7 +55,6 @@ function parsesWhenFlattened(body: string): { ok: true } | { ok: false; error: s } const allBlocks: Block[] = [...new Glob("**/*.md").scanSync({ cwd: SKILLS_DIR })] - .filter((rel) => rel.split(/[\\/]/)[0] !== "guides") .sort() .flatMap((rel) => extractBashBlocks(readFileSync(path.join(SKILLS_DIR, rel), "utf8")).map((b) => ({ file: rel, ...b })), diff --git a/tests/skills/skill-body-extraction-contract.test.ts b/tests/skills/skill-body-extraction-contract.test.ts index 42245b72f..7e917dc96 100644 --- a/tests/skills/skill-body-extraction-contract.test.ts +++ b/tests/skills/skill-body-extraction-contract.test.ts @@ -3,7 +3,7 @@ import fs from "node:fs" import path from "node:path" const ROOT = path.join(import.meta.dir, "..", "..", "skills") -const DOCS_ROOT = path.join(import.meta.dir, "..", "..", "skills", "guides") +const DOCS_ROOT = path.join(import.meta.dir, "..", "..", "docs", "guides") const read = (skill: string, rel = "SKILL.md") => fs.readFileSync(path.join(ROOT, skill, rel), "utf8") const readDocs = (skill: string) => fs.readFileSync(path.join(DOCS_ROOT, `${skill}.md`), "utf8") diff --git a/tests/skills/unified-plan-artifact-contract.test.ts b/tests/skills/unified-plan-artifact-contract.test.ts index 3b2c492eb..88cac9681 100644 --- a/tests/skills/unified-plan-artifact-contract.test.ts +++ b/tests/skills/unified-plan-artifact-contract.test.ts @@ -53,7 +53,7 @@ const ceWorkTriage = readRepoFile("skills/ce-work/references/input-triage.md") const ceWorkReturn = readRepoFile("skills/ce-work/references/return-to-caller.md") const ceWorkLoop = readRepoFile("skills/ce-work/references/implementation-loop.md") const ceWorkStrategy = readRepoFile("skills/ce-work/references/execution-strategy.md") -const ceWorkDocs = readRepoFile("skills/guides/ce-work.md") +const ceWorkDocs = readRepoFile("docs/guides/ce-work.md") const ceWorkEngines = readRepoFile( "skills/ce-work/references/execution-engines.md", )