diff --git a/.claude/commands/handoff-plan.md b/.claude/commands/handoff-plan.md index f1f76ba3..050fcd15 100644 --- a/.claude/commands/handoff-plan.md +++ b/.claude/commands/handoff-plan.md @@ -46,9 +46,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -57,9 +59,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-bugfix.md b/.claude/commands/plan-bugfix.md index 83f1fb71..baee2a3c 100644 --- a/.claude/commands/plan-bugfix.md +++ b/.claude/commands/plan-bugfix.md @@ -48,9 +48,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -59,9 +61,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-docs.md b/.claude/commands/plan-docs.md index 8024c2b0..d62f960d 100644 --- a/.claude/commands/plan-docs.md +++ b/.claude/commands/plan-docs.md @@ -29,6 +29,7 @@ $ARGUMENTS 3. List each document or section to write or update, with the facts it must contain. The executor writes the prose; you supply the facts. 4. Point at an existing document whose structure and tone to follow. 5. Make each Done-when objective: the file exists, it contains the required headings (`Select-String`), links resolve, or the docs build passes. +6. When the plan changes how pages present their text and not what they say, such as a documentation site's layout, components or Markdown structure, give every step that changes pages a Done-when that proves their words are unchanged from the plan's base commit: the commit `git rev-parse HEAD` prints while you plan, written into the command as a literal hash. The command reads each page the step changes, at that commit with `git show :` and in the working tree, removes from both what the step may change, such as labels, Markdown emphasis, list markers, whitespace and case, and compares what is left; it compares component tags, such as each evidence mark, separately, as sorted lists. A step that drops, adds or moves a word then fails. When several steps need the comparison, the first step adds it to the repository as a script, written in the first language ADR-0021 in `docs/decisions/project-template/` lists that fits, and each Done-when runs it with that step's pages. ## Output: PLAN.md for the executor model @@ -45,9 +46,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -56,9 +59,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-feature.md b/.claude/commands/plan-feature.md index a4491442..4a5dbcf6 100644 --- a/.claude/commands/plan-feature.md +++ b/.claude/commands/plan-feature.md @@ -48,9 +48,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -59,9 +61,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-issue.md b/.claude/commands/plan-issue.md index 2818400b..ce648f38 100644 --- a/.claude/commands/plan-issue.md +++ b/.claude/commands/plan-issue.md @@ -112,6 +112,7 @@ the issue above 4. Sequence the change so the build and tests stay green after every step: add the new structure, move callers over in small groups, then delete the old structure. 5. Every step's Done-when runs the full relevant test suite, not only new tests. 6. Under Out of scope, forbid behavior changes, renames beyond the plan, and formatting-only churn. +7. When the plan changes how pages present their text and not what they say, such as a documentation site's layout, components or Markdown structure, give every step that changes pages a Done-when that proves their words are unchanged from the plan's base commit: the commit `git rev-parse HEAD` prints while you plan, written into the command as a literal hash. The command reads each page the step changes, at that commit with `git show :` and in the working tree, removes from both what the step may change, such as labels, Markdown emphasis, list markers, whitespace and case, and compares what is left; it compares component tags, such as each evidence mark, separately, as sorted lists. A step that drops, adds or moves a word then fails. When several steps need the comparison, the first step adds it to the repository as a script, written in the first language ADR-0021 in `docs/decisions/project-template/` lists that fits, and each Done-when runs it with that step's pages. ### Tests @@ -174,6 +175,7 @@ the issue above 3. List each document or section to write or update, with the facts it must contain. The executor writes the prose; you supply the facts. 4. Point at an existing document whose structure and tone to follow. 5. Make each Done-when objective: the file exists, it contains the required headings (`Select-String`), links resolve, or the docs build passes. +6. When the plan changes how pages present their text and not what they say, such as a documentation site's layout, components or Markdown structure, give every step that changes pages a Done-when that proves their words are unchanged from the plan's base commit: the commit `git rev-parse HEAD` prints while you plan, written into the command as a literal hash. The command reads each page the step changes, at that commit with `git show :` and in the working tree, removes from both what the step may change, such as labels, Markdown emphasis, list markers, whitespace and case, and compares what is left; it compares component tags, such as each evidence mark, separately, as sorted lists. A step that drops, adds or moves a word then fails. When several steps need the comparison, the first step adds it to the repository as a script, written in the first language ADR-0021 in `docs/decisions/project-template/` lists that fits, and each Done-when runs it with that step's pages. ### Template Update @@ -219,9 +221,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -230,9 +234,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-migration.md b/.claude/commands/plan-migration.md index 3a47155f..277b64ab 100644 --- a/.claude/commands/plan-migration.md +++ b/.claude/commands/plan-migration.md @@ -46,9 +46,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -57,9 +59,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-performance.md b/.claude/commands/plan-performance.md index 0b7b597e..f79d155f 100644 --- a/.claude/commands/plan-performance.md +++ b/.claude/commands/plan-performance.md @@ -45,9 +45,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -56,9 +58,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-refactor.md b/.claude/commands/plan-refactor.md index 1c672b91..dfbc1932 100644 --- a/.claude/commands/plan-refactor.md +++ b/.claude/commands/plan-refactor.md @@ -30,6 +30,7 @@ $ARGUMENTS 4. Sequence the change so the build and tests stay green after every step: add the new structure, move callers over in small groups, then delete the old structure. 5. Every step's Done-when runs the full relevant test suite, not only new tests. 6. Under Out of scope, forbid behavior changes, renames beyond the plan, and formatting-only churn. +7. When the plan changes how pages present their text and not what they say, such as a documentation site's layout, components or Markdown structure, give every step that changes pages a Done-when that proves their words are unchanged from the plan's base commit: the commit `git rev-parse HEAD` prints while you plan, written into the command as a literal hash. The command reads each page the step changes, at that commit with `git show :` and in the working tree, removes from both what the step may change, such as labels, Markdown emphasis, list markers, whitespace and case, and compares what is left; it compares component tags, such as each evidence mark, separately, as sorted lists. A step that drops, adds or moves a word then fails. When several steps need the comparison, the first step adds it to the repository as a script, written in the first language ADR-0021 in `docs/decisions/project-template/` lists that fits, and each Done-when runs it with that step's pages. ## Output: PLAN.md for the executor model @@ -46,9 +47,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -57,9 +60,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-security.md b/.claude/commands/plan-security.md index 3bab52be..8838d748 100644 --- a/.claude/commands/plan-security.md +++ b/.claude/commands/plan-security.md @@ -45,9 +45,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -56,9 +58,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-template-update.md b/.claude/commands/plan-template-update.md index 7ce18279..7ca81ed5 100644 --- a/.claude/commands/plan-template-update.md +++ b/.claude/commands/plan-template-update.md @@ -60,9 +60,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -71,9 +73,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/plan-tests.md b/.claude/commands/plan-tests.md index 270ce575..293475e8 100644 --- a/.claude/commands/plan-tests.md +++ b/.claude/commands/plan-tests.md @@ -46,9 +46,11 @@ A smaller, cheaper model — a local model or a lower-cost Copilot model — wil - Order steps so each one builds and passes its check on its own. Put tests before or with the code they cover. - Every step ends with one PowerShell command, run from the repository root, that exits 0 only when the step is done and finishes in under two minutes. Prefer a check that fails until the step is done — run the step's new test by name, or assert the new output — over a suite that already passes. A test filter that matches no test exits 0 in most runners, so the check would pass before its test exists: make an empty match fail, such as `dotnet test --filter "FullyQualifiedName~" -- RunConfiguration.TreatNoTestsAsError=true` for one .NET test project, or pytest's exit code 5 for no tests collected. - When `AGENTS.md`'s `## Landing` section sets `prelude` to a command, not `none`, put that command in Context for the executor as its `- Prelude:` line. The executor and the coordinator dot-source it in the same PowerShell before each Done-when command, so a tool it puts on `PATH` is there: never copy a `PATH` or tool-setup guard into a Done-when command instead. +- When a step runs a script, or its Change or Done-when command passes a path to a .NET method, such as `[IO.File]::WriteAllText`, put this line under Gotchas in Context for the executor: "A script or command never passes a relative path to a .NET method, such as `[IO.File]::ReadAllText`, `[IO.File]::WriteAllText` or `[IO.Directory]::GetFiles`: .NET resolves it against the process's folder, which `Set-Location` doesn't move and which in a Copilot session is the main checkout, not the plan's worktree. Use `Get-Content -LiteralPath`, `Set-Content -LiteralPath` or `Get-ChildItem`, or make the path absolute first with `Join-Path (Get-Location) `." Write every Done-when command that way too. +- A step or Done-when command that reaches a sibling repository, a clone next to this one, such as a documentation toolchain's, finds it from the folder that holds the main checkout, never through `..`: a plan's worktree is `.claude/worktrees//`, so `..` from it is `.claude/worktrees/`, and `../` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) `, which names the same folder from the main checkout and from every worktree. - Keep each step under about 25 lines. Split anything bigger. - Expect escalations: when a step needs a decision the plan didn't make, the executor stops, marks it `[?]` with an `- Escalation:` note, and the step comes back to you for re-planning. Every escalation costs a round trip, so settle decisions now. -- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. +- When `AGENTS.md`'s `## Landing` section sets `release` to `tag` or `tag+release`, add the `Release:` line when the plan changes something a release ships: the product's code, a file its package or download carries, such as the `README.md` a package takes as its readme, which nuget.org shows, or what its build puts out, such as a build setting, a dependency or the SDK version. A plan that changes only what reaches its readers without a release, such as documentation-site pages, which deploy from every push to the default branch, CI workflows, decision records, tests or repository docs, such as `CONTRIBUTING.md`, `AGENTS.md`, instruction files or a `README.md` no package carries, gets no `Release:` line: its changelog entries go under `## [Unreleased]`, where the next release's section takes them in, and it lands with no tag and no release, as ADR-0032 in `docs/decisions/project-template/` says. When `AGENTS.md` says what this project's releases ship, follow it. A plan for several issues gets the line when any of them changes something a release ships. Use the newest version tag on `origin`, not one only this clone has (the first `git ls-remote --tags --refs --sort=-version:refname origin` entry whose name after `refs/tags/` is shaped like `v1.2.3` or `1.2.3`, or the first such `git tag --list --sort=-version:refname` entry when the repository has no `origin`; `v0.1.0` when there is none), raised by one patch version for a bugfix, docs, tests or refactor plan, or by one minor version, with the patch set to 0, for any other plan. In a pre-release project, as The Changelog below defines it, a raise keeps the major version at 0: name the first stable version, such as `v1.0.0`, only when the request asks for the first stable release. For a plan that covers several issues, use the largest raise any one of them would get on its own: one issue that needs a minor raise makes the plan's raise minor. When the change breaks how existing users work, ask me which version to use, except in a pre-release project, which has none. The version holds unless another plan lands it, or a later one, first: `/ship-plan` then moves this plan to the next free version, raised the same way, which the state script prints as `renumber`, and adds a step that merges in the default branch and retitles the changelog section, or, in a pre-release project, whose changelog has no release section, only changes the `Release:` line, so a plan can run ahead of one still waiting for review. - Make the last step write the plan's changelog entries as The Changelog below says, for every plan, with or without a `Release:` line. - Under `## Follow-ups`, list only work someone would plan as its own task: a real defect, gap or cleanup you found that this plan doesn't do. Write each as one line, `: `, that a reader who never saw this plan understands; `/ship-plan` files each one as an issue once the plan has landed, where and with the label `AGENTS.md`'s Landing section says (`follow-ups`, `follow-up-label`). Leave out nits, style preferences, ideas for someday, and anything this plan should do itself (add a step for that): mention them in your reply instead. @@ -57,9 +59,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and ```markdown # Plan: Issue: -Release: +Release: Refs: -Completes: +Completes: ## Goal diff --git a/.claude/commands/review-plan-diff.md b/.claude/commands/review-plan-diff.md index 61a9eb10..c90467e8 100644 --- a/.claude/commands/review-plan-diff.md +++ b/.claude/commands/review-plan-diff.md @@ -26,7 +26,7 @@ If empty, use `git merge-base HEAD origin/`, where `` is the d 2. Read the full diff (`git diff ` including uncommitted changes) and the changed files in full where context matters. 3. Check every step was done as written: the right files, the right behavior, and no shortcuts such as skipped or weakened tests, swallowed errors, hard-coded values or leftover TODOs. Flag every deviation from the step text as at least should-fix even when its checks pass — creating something the step said already exists, touching files the step doesn't list, or changing an interface — because a deviation means the executor improvised instead of escalating. 4. Check what the Done-when commands can't: edge cases, error handling, security, performance, API compatibility, and each Review checklist item. In a pre-release project, which `pwsh -NoProfile -File .template/Get-PlanState.ps1` shows as `pre-release: yes`, also check that every text the plan wrote, the changelog included, describes the product as it is, with no `**Breaking:**` label, no conventional-commit `!` marker or `BREAKING CHANGE:` footer in a commit message or the pull request's title, no wording set against an earlier state, no migration note and no compatibility shim, as ADR-0015 says, and that the changelog keeps `## [Unreleased]` a catalog under `### Added` and `### Security` alone. Then check every file the diff changes against the instruction files that apply to it, each read in full: `AGENTS.md` and each instruction file it lists, every `.github/instructions/*.instructions.md` whose `applyTo` glob matches the file's path, such as `csharp.instructions.md` for a `.cs` file and `csharp-tests.instructions.md` for one in a `.Tests` project, and every `.claude/rules/*.md` whose `paths:` match it; where a project's own instruction file differs from a template one, the project's wins. The gate checks only what a machine can, so the rules only a reader can check are this review's to catch: naming, test names, regions and file layout, a call nested inside another call's arguments, and an unused using or import the build doesn't report. Report each departure as should-fix, with its file and line and the rule it breaks, quoted, so its fix step runs before the first push instead of costing a round of review. -5. Run the test suite and the checks listed under Context for the executor, after its `- Prelude:` command, when it has one, dot-sourced in the same PowerShell: `$global:LASTEXITCODE = 0; try { . } catch { $_; "prelude failed"; exit 2 }; if (-not $? -or $LASTEXITCODE) { "prelude failed"; exit 2 }; `, where `` is that line's command. When it exits 2 and the output's last line, apart from any exit code your shell adds, is `prelude failed`, the command never ran: stop the review without adding steps or a `Reviewed:` line, show me the prelude's error, and say to fix the `- prelude:` line in the `## Landing` section of `AGENTS.md`, or the script it names, and the plan's `- Prelude:` line. +5. Run the test suite and the checks listed under Context for the executor, after its `- Prelude:` command, when it has one, dot-sourced in the same PowerShell: `$global:LASTEXITCODE = 0; try { . } catch { $_; "prelude failed"; exit 2 }; if (-not $? -or $LASTEXITCODE) { "prelude failed"; exit 2 }; `, where `` is that line's command. When it exits 2 and the output's last line, apart from any exit code your shell adds, is `prelude failed`, the command never ran: stop the review without adding steps or a `Reviewed:` line, show me the prelude's error, and say to fix the `- prelude:` line in the `## Landing` section of `AGENTS.md`, or the script it names, and the plan's `- Prelude:` line. When the plan changes a documentation site's pages and `AGENTS.md` names a command that builds the site, build it with that command after the checks, then look at each changed page as built, at the widths the project's layout check uses, or at 375 and 1280 pixels when it has none, with a browser or screenshot tool this session has, such as Playwright. Text checks pass a page whose layout broke, so this is the check that finds it: report each break, such as a mark or a word stranded on a line of its own, text cut off or overlapping, or a component that lost its styling, as a should-fix with the page, the width and what you saw, and a build that fails as a blocker. When this session has no tool that shows a page, say so in your reply and name the pages and widths for me to look at before the merge. 6. Report findings as a table: severity (blocker, should-fix, nit), file and line, problem, fix. 7. For every blocker and should-fix, append a new step to the end of the Steps section of `PLAN.md`, numbered in sequence and in the same format as the existing steps (`### [ ] N. …` with Files, Change and a Done-when command), so the executor model can fix it. Delete any `Reviewed:` line from `PLAN.md`. Work this plan shouldn't do but someone would plan as its own task, such as a separate defect or gap, goes under a `## Follow-ups` heading at the end of `PLAN.md`, one line each as `: `, which `/ship-plan` files as an issue; add the heading when it's missing. A nit, a style preference or an idea for someday goes in your reply, not in `PLAN.md`. Change nothing else in the repository. 8. When the review found no blocker or should-fix, record it: put `Reviewed: ` on its own line among the lines under the plan's title, after `Issue:`, `Release:` and `Refs:`, or after `Pull request:` and `Start:` in an `/address-feedback` run's plan, replacing any `Reviewed:` line there. `/ship-plan` lands only work that matches the reviewed commit, so any later change needs another review. Then say the plan is done, and give the next command: `/ship-plan`, which lands it as `AGENTS.md`'s Landing section says. For a plan with a `Pull request:` line, an `/address-feedback` run's, give `/address-feedback ` instead, which pushes the work to that pull request's branch and replies to its items. When `PLAN.md` has an `Issue:` line, also say that the pull request description gets one `Closes ` line per issue on it, one `Refs ` line per reference on its `Refs:` line, and a two-to-five-line summary of the plan's steps and Decisions, which `/ship-plan` writes. diff --git a/.claude/commands/run-issues.md b/.claude/commands/run-issues.md index 75cec5c5..009fa6c8 100644 --- a/.claude/commands/run-issues.md +++ b/.claude/commands/run-issues.md @@ -34,7 +34,7 @@ You coordinate. Each stage runs as the workflow's own command does: read that co - Otherwise delegate `triage-issues` to a subagent with `model: opus` and the request as its arguments. The queue has one entry per `/plan-issue` line it returns, in that order, holding the issues that line names. - Leave out an entry when the folder `.claude/worktrees/issue-` already exists for any of its issues: it holds a plan in progress, which `/continue-plan issue-` shows. - Keep the first five entries. When the queue is empty, say so and stop. -5. Show the run summary, then ask me once whether to go ahead, and wait for my answer. When the state script's `push-branch` isn't `-`, the summary first says that every pull request comes from that branch, one at a time, while each plan is still made on its own branch. The summary lists the queue, each entry with its issues (number, title, and the kind and size when triage gave them); that each issue gets a plan snapshot comment, a draft pull request that waits for my review and merge, for up to the wait limit, in hours, with nothing to answer, and, after the merge, the tag, the release, a closing comment on each issue, and an issue labelled with the `landing` line's `follow-up-label` for each follow-up its plan lists, in this repository or in the one the `landing` line's `follow-ups` names, unless I answer that I want none filed, or, when that line says `follow-ups=none`, the follow-ups listed in the report instead; when the run stops an issue; and the cost: each issue takes about one plan-issue run on Opus, one orchestrate-plan run, up to three reviews, and one more round for each set of review comments I post. Say that while a draft pull request waits, the next entry is planned, executed and reviewed ahead of it and opens its pull request only once the one before has landed, and that when the one before lands with the `Release:` version this entry planned, or a later one, it moves to the next free version with one more step and one more review, or, in a pre-release project, by changing its `Release:` line alone. Say too that an entry whose draft pull request is open moves the same way when a pull request outside the run takes its version, and that its pull request then merges with a merge commit, not by rebasing, unless only a pre-release project's `Release:` line moved. When the `landing` line's `gate` isn't `none`, say that the gate runs before each push and that a failing gate stops the entry. When the default branch has `.github/workflows/code-review.yml` and the `landing` line's `review-bots` names `ncode-review`, say that the run also judges each of NCode Review's unresolved findings against the code, whatever its severity, nits included, and fixes each that holds and is within its issue, never one on CI, the template, agent configuration, the build or the dependencies, which it leaves for me with the change the finding proposes; that it replies at most twice on each of its threads, comments `/review` after each push of fix steps in its first `max-review-rounds` rounds of review feedback, the `landing` line's value, so the bot reviews them, and after those rounds still fixes and replies but asks for no further review; that it lists the findings outside its issue as follow-ups, or, when I answer to fix the follow-ups in the same pull request before merge, fixes those too; and that it recommends the merge in a comment once a check leaves every finding fixed, declined, answered, left as a follow-up or left for me, after NCode Review's review of its last push is in, and still fixes what comes after, as comments of mine always get their fixes. `.claude/settings.json` lets `git push` run without an approval prompt, so after my yes to this summary, no prompt stops the run's pushes. +5. Show the run summary, then ask me once whether to go ahead, and wait for my answer. When the state script's `push-branch` isn't `-`, the summary first says that every pull request comes from that branch, one at a time, while each plan is still made on its own branch. The summary lists the queue, each entry with its issues (number, title, and the kind and size when triage gave them); that each issue gets a plan snapshot comment, a draft pull request that waits for my review and merge, for up to the wait limit, in hours, with nothing to answer, and, after the merge, the tag and the release when its plan has a `Release:` line, a closing comment on each issue, and an issue labelled with the `landing` line's `follow-up-label` for each follow-up its plan lists, in this repository or in the one the `landing` line's `follow-ups` names, unless I answer that I want none filed, or, when that line says `follow-ups=none`, the follow-ups listed in the report instead; when the run stops an issue; and the cost: each issue takes about one plan-issue run on Opus, one orchestrate-plan run, up to three reviews, and one more round for each set of review comments I post. Say that while a draft pull request waits, the next entry is planned, executed and reviewed ahead of it and opens its pull request only once the one before has landed, and that when the one before lands with the `Release:` version this entry planned, or a later one, it moves to the next free version with one more step and one more review, or, in a pre-release project, by changing its `Release:` line alone. Say too that an entry whose draft pull request is open moves the same way when a pull request outside the run takes its version, and that its pull request then merges with a merge commit, not by rebasing, unless only a pre-release project's `Release:` line moved. When the `landing` line's `gate` isn't `none`, say that the gate runs before each push and that a failing gate stops the entry. When the default branch has `.github/workflows/code-review.yml` and the `landing` line's `review-bots` names `ncode-review`, say that the run also judges each of NCode Review's unresolved findings against the code, whatever its severity, nits included, and fixes each that holds and is within its issue, never one on CI, the template, agent configuration, the build or the dependencies, which it leaves for me with the change the finding proposes; that it replies at most twice on each of its threads, comments `/review` after each push of fix steps in its first `max-review-rounds` rounds of review feedback, the `landing` line's value, so the bot reviews them, and after those rounds still fixes and replies but asks for no further review; that it lists the findings outside its issue as follow-ups, or, when I answer to fix the follow-ups in the same pull request before merge, fixes those too; and that it recommends the merge in a comment once a check leaves every finding fixed, declined, answered, left as a follow-up or left for me, after NCode Review's review of its last push is in, and still fixes what comes after, as comments of mine always get their fixes. `.claude/settings.json` lets `git push` run without an approval prompt, so after my yes to this summary, no prompt stops the run's pushes. For the follow-ups, offer me four answers, each saying where the work lands, which hold for every entry, also the ones this run adds: file them as issues, which my yes alone means; fix them in the same pull request before merge; file them and run each as a new entry of this run; or file none. Fix them in the same pull request before merge turns each follow-up into a fix step of the entry that found it, pushed to that entry's draft pull request before I merge, as Fix Follow-ups in the Pull Request below says, so each pull request leaves no follow-up issue behind: each fix costs a step and a review, the `landing` line's `max-review-rounds` bounds the rounds, and a follow-up it can't fix there, or one found after the last round, is filed as the first answer files it, or, with `follow-ups=none`, listed, and named in the report with why. File them and run each as a new entry of this run files each follow-up, and once its entry has landed, takes each filed issue into this run as an entry of its own, at the end of the queue, as Run Follow-ups as Entries below says: the run still takes at most five entries in all, each added entry costs what any entry costs, and the report names any left over with the command that plans it. Offer the third answer only when the `landing` line says `follow-ups=issues`: when that line names another repository, the follow-ups are filed there, and this run lands only this repository's issues. When it says `follow-ups=none`, offer two answers instead: fix them in the same pull request before merge, or list them in the report, which my yes alone means. diff --git a/.claude/commands/ship-plan.md b/.claude/commands/ship-plan.md index c146818c..564da75b 100644 --- a/.claude/commands/ship-plan.md +++ b/.claude/commands/ship-plan.md @@ -22,17 +22,17 @@ Land the plan in `PLAN.md` the way this repository's Landing policy says: push i Extra instructions (may be empty): $ARGUMENTS 1. Read the state: first settle the push branch, as The Push Branch below says, with the extra instructions as the request; then run `pwsh -NoProfile -File .template/Get-PlanState.ps1` from the repository root. It prints `key: value` lines. Below, `` is its `default` value, `` its `pr-branch`, the branch on `origin` the pull request comes from, `` its `branch`, and `` its `release`. Stop when `push-branch` is `invalid`: say to set a valid branch with `git config plan.pushBranch `, or to clear it with `git config --unset plan.pushBranch`. Stop and say what to run instead when `plan` is `-`; when `dirty` is `yes`; when `steps` shows an open, escalated or failed step (run orchestrate-plan, or replan-step); when `reviewed` isn't `current`, because the work changed since its last clean review or never had one (run review-plan-diff); when `next` is `finish-plan`, because everything is done (run finish-plan); or when `feedback` isn't `-`, because the plan belongs to a stopped `/address-feedback` run on pull request ``, whose fixes go to that pull request's branch, with a reply on each item, never to a pull request of their own (run `/address-feedback `, which finishes that run). -2. Read the policy from the `landing` line: `integrate` is `direct` or `pull-request`, `release` is `none`, `tag` or `tag+release`, and `changelog` names the changelog file. `draft` is `yes`, which opens the pull request as a draft, or `no`, the default when the Landing section has no `- draft:` line: it stays `no` so that no template update changes how an existing project lands, a project that wants drafts writes `- draft: yes`, and `run-issues` asks for a draft with its extra instructions either way. `follow-ups` is `issues`, which files the plan's follow-ups as issues in this repository, `none`, which files none, or a repository path such as `owner/repo` or `group/subgroup/project`, which files them there. `follow-up-label` names the label filed follow-ups get, in double quotes when it has a space; below, `