Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions .claude/commands/handoff-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <project> --filter "FullyQualifiedName~<Test>" -- 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) <path>`." 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/<name>/`, so `..` from it is `.claude/worktrees/`, and `../<repository>` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) <repository>`, 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, `<short title>: <what to change, where (file or symbol), and why it matters>`, 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.

Expand All @@ -57,9 +59,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and
```markdown
# Plan: <title, 2-10 words>
Issue: <issue reference, such as #42, or up to three separated by spaces, such as #25 #24 #26; only when the request names issues>
Release: <version, such as v1.4.0; only when AGENTS.md's Landing section releases>
Release: <version, such as v1.4.0; only when AGENTS.md's Landing section releases and the plan changes something a release ships>
Refs: <issue reference, or several separated by spaces, such as owner/repo#90; only when the request names an issue the plan relates to but doesn't resolve>
Completes: <open follow-up issues the plan's work completes, separated by spaces, such as #77 #78; only `/ship-plan` writes it, and its pull request closes them, or, with `integrate: direct`, `/ship-plan` closes them once the commits land>
Completes: <open follow-up issues the plan's work completes, separated by spaces, such as #77 #78; written by `/ship-plan`, by `/run-issues` after it pushes fix steps, or before a push made without `/ship-plan`, never by a planner or an executor; the plan's pull request closes them, or, with `integrate: direct`, `/ship-plan` closes them once the commits land, as the session that pushed does after a push made without `/ship-plan`>

## Goal
<What changes for the user or system, and why. 2-4 sentences.>
Expand Down
8 changes: 5 additions & 3 deletions .claude/commands/plan-bugfix.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <project> --filter "FullyQualifiedName~<Test>" -- 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) <path>`." 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/<name>/`, so `..` from it is `.claude/worktrees/`, and `../<repository>` works only in the main checkout. Write `Join-Path (Split-Path -Parent (Split-Path -Parent (git rev-parse --path-format=absolute --git-common-dir))) <repository>`, 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, `<short title>: <what to change, where (file or symbol), and why it matters>`, 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.

Expand All @@ -59,9 +61,9 @@ Use exactly this structure; the step runner parses the `### [ ] N.` headings and
```markdown
# Plan: <title, 2-10 words>
Issue: <issue reference, such as #42, or up to three separated by spaces, such as #25 #24 #26; only when the request names issues>
Release: <version, such as v1.4.0; only when AGENTS.md's Landing section releases>
Release: <version, such as v1.4.0; only when AGENTS.md's Landing section releases and the plan changes something a release ships>
Refs: <issue reference, or several separated by spaces, such as owner/repo#90; only when the request names an issue the plan relates to but doesn't resolve>
Completes: <open follow-up issues the plan's work completes, separated by spaces, such as #77 #78; only `/ship-plan` writes it, and its pull request closes them, or, with `integrate: direct`, `/ship-plan` closes them once the commits land>
Completes: <open follow-up issues the plan's work completes, separated by spaces, such as #77 #78; written by `/ship-plan`, by `/run-issues` after it pushes fix steps, or before a push made without `/ship-plan`, never by a planner or an executor; the plan's pull request closes them, or, with `integrate: direct`, `/ship-plan` closes them once the commits land, as the session that pushed does after a push made without `/ship-plan`>

## Goal
<What changes for the user or system, and why. 2-4 sentences.>
Expand Down
Loading