Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Improve plan skills/commands to auto-track publish Github Roadmap and Linear tracking

Damian Legawiec160c75122cdb
diff --git a/.claude/commands/create-plan.md b/.claude/commands/create-plan.md
index 5062c1175c..b645829fae 100644
--- a/.claude/commands/create-plan.md
+++ b/.claude/commands/create-plan.md
@@ -7,7 +7,9 @@ Follow this process:
2. Create a new plan file in `docs/plans/` with a kebab-case filename
3. Fill in all sections based on our discussion and any existing context
4. **Resolve every open question interactively before finishing** — see below
-5. If the plan affects specific areas of the codebase, add cross-references in relevant directory-level CLAUDE.md files
+5. **Open the tracking issues in Linear and GitHub** and record them in the
+ plan's `Tracking` header line — see below
+6. If the plan affects specific areas of the codebase, add cross-references in relevant directory-level CLAUDE.md files
The filename should follow the pattern: `{release}-{feature-slug}.md`
(e.g., `6.0-cart-order-split.md`, `future-mcp-server.md`)
@@ -46,6 +48,63 @@ Then fold the answers back into the plan:
Only skip the interactive pass if the draft genuinely raised no open questions —
which is rare, and worth double-checking before concluding.
+## Tracking the plan in Linear and GitHub (required)
+
+Every plan is tracked as one Linear issue and one GitHub issue, opened once
+the open questions are settled so the issue describes the finished design.
+Record both in the plan's `**Tracking:**` header line, as
+`Linear V-NNNN · GitHub spree/spree#NNNN`. This section is the single
+description of how the trackers are shaped; `/project:update-plan` and
+`/project:implement-plan` refer back to it.
+
+**Milestones follow the plan's Target.** A target of `Spree X.Y` maps to the
+Linear milestone `X.Y` and the GitHub milestone `vX.Y`. If a milestone does
+not exist yet, create it rather than leaving the issue unassigned. A plan
+spanning two releases (`6.0-6.1-…`) goes on the earlier milestone.
+
+### Linear
+
+Use the Linear MCP tools (`save_issue`, `save_milestone`, `get_project`).
+Load them with `ToolSearch` first. If no Linear tools are available in this
+session, skip this half, write `Linear —` in the header, and say so in the
+final message so the author can open it by hand.
+
+- Team `Vendo`, project `Spree` (slug `spree-941226e25ecf`), milestone as
+ above.
+- Title is the plan's H1 exactly, with no release prefix — the milestone
+ already says which release it is.
+- Description, in plain words: the plan's Summary paragraph, its status line,
+ what it depends on, the Migration Path steps, and a link to the plan file
+ at `https://github.com/spree/spree/blob/main/docs/plans/<file>`. Add the
+ same link through `links` so it shows as an attachment.
+- Status follows the plan's status: `Draft` and `Design finalized` → Backlog,
+ `In Progress` → In Progress, `Implemented` → Done, `Superseded` → Canceled.
+- Leave priority, assignee and labels unset unless the author asks.
+
+### GitHub
+
+- `gh issue create --repo spree/spree --title "<H1>" --milestone "vX.Y"`.
+ No `Feature Request` label: the Roadmap membership already says what it
+ is. Add `💼 B2B` or `🤝 Multi Vendor` when the plan belongs to that
+ track. The body is the same summary as the Linear issue,
+ the link to the plan file, and a line `Tracked in Linear as V-NNNN`.
+ The description is public: no customer names, no credentials, no local
+ URLs.
+- Add the issue to the Roadmap project (organisation project number 2) and
+ set its Status to `Todo`. The `gh project` subcommands fail here with
+ "unknown owner type", so go through GraphQL with `gh api graphql`:
+ `addProjectV2ItemById` with the project id `PVT_kwDN3X7OACniig` and the
+ issue's `node_id` (from `gh api repos/spree/spree/issues/<n>`), then
+ `updateProjectV2ItemFieldValue` on the returned item with the Status
+ field `PVTSSF_lADN3X7OACniis4BoTjq` and option `f75ad846` (Todo; In
+ Progress is `47fc9ee4`, Done is `98236657`). This needs a token with the
+ `project` scope; if the call fails with a scope error, keep going, write
+ the GitHub issue number in the header anyway, and tell the author to add
+ `project` to the token that `GITHUB_TOKEN` in their shell profile points
+ at, then re-add the item.
+- Once both exist, attach the GitHub issue URL to the Linear issue through
+ `save_issue` `links`, so each tracker points at the other.
+
## Recording decisions
When a new plan settles something significant — a decision other plans will need
diff --git a/.claude/commands/implement-plan.md b/.claude/commands/implement-plan.md
index bf294dc23c..10bb53b4e6 100644
--- a/.claude/commands/implement-plan.md
+++ b/.claude/commands/implement-plan.md
@@ -28,8 +28,15 @@ stack per worktree is what exhausts the machine when several runs are active.
finished before it.
- Do every stage in order and do not skip one because it looks unnecessary.
Each stage has a clear "done" condition; move on only when it is met.
-- Work happens in a git worktree (`wt switch -c <branch>`), never on `main`,
- on a `feature/`, `fix/` or `chore/` branch named after the plan.
+- Work happens in a git worktree (`wt switch -c <branch>`), never on `main`.
+ The branch name is the one Linear generates for the plan's issue
+ (`gitBranchName` on the issue, shaped like
+ `feature/v-1234-b2b-order-documents`), so Linear attaches the branch and
+ the pull request to the issue on its own. Without a Linear issue, fall back
+ to a `feature/`, `fix/` or `chore/` branch named after the plan.
+- The plan's trackers move with the run: the Linear issue goes to
+ **In Progress** when implementation starts and to **In Review** when the
+ pull request is open; the pull request carries the Linear id in its title.
- Keep servers running at the end. The user opens the URLs from the report;
shutting the environment down is their call, not yours.
@@ -47,6 +54,14 @@ stack per worktree is what exhausts the machine when several runs are active.
- Write down, in your own words, the list of deliverables before touching code.
If the plan has phases, say which ones this run covers. The default is
everything the plan targets for the current release.
+- Read the plan's `**Tracking:**` header and note the Linear issue id
+ (`V-NNNN`) and the GitHub issue number: every later stage refers to them.
+ If the line is missing or says `Linear —` / `GitHub —`, open the missing
+ tracker now following "Tracking the plan in Linear and GitHub" in
+ `/project:create-plan` and write it into the header — the branch name in
+ stage 3 comes from the Linear issue. If the Linear MCP tools are not
+ available in this session, carry on without the Linear steps and list
+ them in the final report as work left for the user.
## 2. Settle open questions interactively
@@ -70,6 +85,11 @@ reason.
## 3. Implement
+- Before the first commit, set the Linear issue's status to **In Progress**
+ (`save_issue` with `state: "In Progress"`) and set the plan's own status
+ line to `In Progress` naming what this run builds, so the plan, the
+ tracker and the branch agree about what is underway. Create the worktree
+ on the issue's `gitBranchName` (read it with `get_issue`).
- Start with `/goal` so the run has a stated goal to check itself against:
the deliverables from stage 1 plus green changed specs and green CI.
- Follow the plan's phase order and every convention in `CLAUDE.md` (models,
@@ -170,10 +190,23 @@ Print, in one block the user can act on directly:
## 10. Open the pull request and monitor it
- Squash fixups, make sure the branch is pushed to `spree/spree`, then open the
- PR with `gh pr create --repo spree/spree --base main`. The body: what the
+ PR with `gh pr create --repo spree/spree --base main`. The title ends with
+ the Linear id in parentheses, the way the repository already does it:
+ `Add order stages to the dashboard (V-1234)`. The body: what the
change does and why, which plan it implements and which phases, the
decisions settled in stage 2, how it was tested, and the QA walkthrough from
- stage 9. Link the plan file. Keep implementation detail out of it.
+ stage 9. Link the plan file. Reference the trackers on their own lines:
+ `Linear: V-1234` and `Closes #NNNN` when this PR completes everything the
+ plan targets for the release, or `Part of #NNNN` when later phases remain,
+ so GitHub does not close the issue early. Keep implementation detail out
+ of it.
+- With the PR open, move the Linear issue to **In Review** and attach the PR
+ URL to it through `save_issue` `links` (Linear usually picks the PR up
+ from the branch name, so check the issue first and add the link only if
+ it is not already there). Comment the PR URL on the GitHub issue so a
+ reader coming from the Roadmap finds the code. When the PR merges, the
+ plan's status becomes `Implemented` through `/project:update-plan`, which
+ moves the trackers to Done and closes the GitHub issue.
- Run `/autofix-pr` to watch review comments (humans, Bugbot, CodeRabbit) and
CI, fix what comes back, and push. Stop and report clearly if something
needs the user — a required review, a failing check you cannot reproduce
@@ -181,7 +214,8 @@ Print, in one block the user can act on directly:
## Final report
-End with a summary that stands on its own: the PR URL, what was built (by
-deliverable), the decisions recorded, the review findings acted on and the
-ones deliberately skipped, the QA block from stage 9, and anything left for a
-follow-up with the reason.
+End with a summary that stands on its own: the PR URL, the Linear and GitHub
+issue links with the status each is in, what was built (by deliverable), the
+decisions recorded, the review findings acted on and the ones deliberately
+skipped, the QA block from stage 9, and anything left for a follow-up with
+the reason.
diff --git a/.claude/commands/update-plan.md b/.claude/commands/update-plan.md
index 23e2bc62e9..1ef07464f0 100644
--- a/.claude/commands/update-plan.md
+++ b/.claude/commands/update-plan.md
@@ -9,6 +9,7 @@ Instructions: $ARGUMENTS
5. **Resolve open questions interactively before finishing** — see below
6. Update the `Last updated` date
7. If status changed, update the plan's status accordingly
+8. **Mirror the change to the plan's trackers** — see below
## Resolving open questions (required)
@@ -39,6 +40,35 @@ If a question genuinely cannot be answered yet — it depends on work that hasn'
landed, or on information nobody has — say so and leave it deferred with the
reason. That is a resolution too; silently leaving it unexamined is not.
+## Keeping the trackers in step (required)
+
+The plan's `**Tracking:**` header names its Linear issue and its GitHub
+issue. After editing the plan, make the trackers say the same thing the plan
+now says. The shape of both issues, the milestone mapping and the fallbacks
+when a tool is unavailable are described in `/project:create-plan` under
+"Tracking the plan in Linear and GitHub"; read that section rather than
+inventing a variant here.
+
+- **Target changed** (the plan moved to another release): move the Linear
+ issue to milestone `X.Y` and the GitHub issue to milestone `vX.Y`,
+ creating either milestone if it is missing.
+- **Status changed:** set the Linear issue's status through the mapping in
+ `/project:create-plan` (`Implemented` → Done, `Superseded` → Canceled, and
+ so on). Close the GitHub issue when the plan becomes Implemented or
+ Superseded; reopen it if the plan goes back to In Progress.
+- **Title changed:** rename both issues to the new H1.
+- **Summary, dependencies or migration steps changed:** refresh the issue
+ descriptions with the `patch` operations on `save_issue`, and edit the
+ GitHub body with `gh issue edit`, so a reader of either tracker sees the
+ current design.
+- **The header has no trackers** (a plan written before this rule, or one
+ marked `Linear —` / `GitHub —`): create the missing tracker now following
+ `/project:create-plan`, and fill the header in.
+
+If the Linear MCP tools are not available in this session, update GitHub
+only, leave the Linear half of the header as it was, and say in the final
+message what still needs doing by hand.
+
## Recording decisions
When an update settles something significant — a reversal, a cross-plan
diff --git a/CLAUDE.md b/CLAUDE.md
index 6761e45e9c..167f826919 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,6 +12,8 @@ When proposing significant architectural changes:
Use `/project:create-plan` and `/project:update-plan` for plan management, and `/project:implement-plan <plan>` to deliver a plan end to end (open questions → implementation → reviews → running QA environment → pull request).
+Every plan is tracked as one Linear issue (Spree project, milestone = the plan's target version) and one GitHub issue (milestone `vX.Y`, on the org Roadmap project), both named in the plan's `**Tracking:**` header. The skills open and update them; a pull request that implements a plan carries the Linear id in its title, `Title (V-1234)`.
+
## Monorepo Structure
| Directory | Description |
diff --git a/docs/plans/6.1-b2b-order-documents.md b/docs/plans/6.1-b2b-order-documents.md
index 6f34f52b46..8a2afcaaf9 100644
--- a/docs/plans/6.1-b2b-order-documents.md
+++ b/docs/plans/6.1-b2b-order-documents.md
@@ -5,6 +5,7 @@
**Depends on:** Customer PO Numbers (6.0-b2b-customer-po-numbers.md — `po_document`, the first order attachment), B2B Wholesale Shipping (6.0-b2b-wholesale-shipping.md — freight summary feeds the packing list), B2B Payment Terms (6.0-6.1-b2b-payment-terms.md — schedule + bank reference feed the payment sheet)
**Author:** Damian + Claude
**Last updated:** 2026-08-30
+**Tracking:** Linear V-3613 · GitHub spree/spree#14609
## Summary
diff --git a/docs/plans/6.1-exchange-rates.md b/docs/plans/6.1-exchange-rates.md
index af131390bd..8db78e90c5 100644
--- a/docs/plans/6.1-exchange-rates.md
+++ b/docs/plans/6.1-exchange-rates.md
@@ -5,6 +5,7 @@
**Depends on:** `6.0-integrations-admin.md` (credential surface), `6.0-multi-vendor-marketplace.md` (the commission-VAT case that constrains this)
**Author:** Damian + Claude
**Last updated:** 2026-08-17
+**Tracking:** Linear V-3614 · GitHub spree/spree#14610
## Summary
diff --git a/docs/plans/6.1-marketplace-message-relay.md b/docs/plans/6.1-marketplace-message-relay.md
index 53ed9afd3d..774b735858 100644
--- a/docs/plans/6.1-marketplace-message-relay.md
+++ b/docs/plans/6.1-marketplace-message-relay.md
@@ -5,6 +5,7 @@
**Depends on:** `6.0-multi-vendor-marketplace.md`, `6.0-seller-product-submission.md`
**Author:** Damian Legawiec
**Last updated:** 2026-08-26
+**Tracking:** Linear V-3615 · GitHub spree/spree#14512
## Summary
diff --git a/docs/plans/6.1-order-change-substrate.md b/docs/plans/6.1-order-change-substrate.md
index be075b6258..f916927559 100644
--- a/docs/plans/6.1-order-change-substrate.md
+++ b/docs/plans/6.1-order-change-substrate.md
@@ -5,6 +5,7 @@
**Depends on:** 6.0-service-workflows.md (workflow tier), 6.0-returns-exchanges-claims.md (first consumer), 6.0-cart-order-split.md (Order is immutable-by-default after placement)
**Author:** Damian + Claude
**Last updated:** 2026-08-30 (Phase 5 superseded — substrate is strictly post-placement; applier pricing rulings added)
+**Tracking:** Linear V-3616 · GitHub spree/spree#14611
## Summary
diff --git a/docs/plans/6.1-order-stages.md b/docs/plans/6.1-order-stages.md
index 046d364e23..9e5ac2bc15 100644
--- a/docs/plans/6.1-order-stages.md
+++ b/docs/plans/6.1-order-stages.md
@@ -5,6 +5,7 @@
**Depends on:** Service Workflows (6.0-service-workflows.md — statuses doctrine), B2B Wholesale Shipping (6.0-b2b-wholesale-shipping.md — the orders this serves), Events system
**Author:** Damian + Claude
**Last updated:** 2026-08-30
+**Tracking:** Linear V-3617 · GitHub spree/spree#14612
## Summary
diff --git a/docs/plans/6.1-product-market-availability.md b/docs/plans/6.1-product-market-availability.md
index edb7a5d14c..62e4d72186 100644
--- a/docs/plans/6.1-product-market-availability.md
+++ b/docs/plans/6.1-product-market-availability.md
@@ -5,6 +5,7 @@
**Depends on:** Markets (shipped), Channels/ProductPublication (shipped), Products::ForContext (shipped), Channel-Markets allowlist (6.0-channel-markets.md — adjacent axis, in progress)
**Author:** Damian + Claude
**Last updated:** 2026-09-07
+**Tracking:** Linear V-3618 · GitHub spree/spree#14613
## Summary
diff --git a/docs/plans/6.1-vies-vat-validation.md b/docs/plans/6.1-vies-vat-validation.md
index c1cbe30e30..082cc52b9c 100644
--- a/docs/plans/6.1-vies-vat-validation.md
+++ b/docs/plans/6.1-vies-vat-validation.md
@@ -5,6 +5,7 @@
**Depends on:** `6.0-tax-provider.md` (shipped `Spree::TaxIdentifier` + `Spree.tax_id_validators` registry, `TaxIdentifiers::Validate` service, `ValidateJob`, validation subscriber, `POST …/tax_identifiers/:id/validate`); `6.0-b2b-companies-and-catalogs.md` (company-owned identifiers, `legal_entity` resolution)
**Author:** Damian + Claude
**Last updated:** 2026-09-05
+**Tracking:** Linear V-3619 · GitHub spree/spree#14614
## Summary
diff --git a/docs/plans/_template.md b/docs/plans/_template.md
index 3ca79fb8c7..7c815f634d 100644
--- a/docs/plans/_template.md
+++ b/docs/plans/_template.md
@@ -5,6 +5,13 @@
**Depends on:** (other plans or features)
**Author:** (who drove the design)
**Last updated:** YYYY-MM-DD
+**Tracking:** Linear V-NNNN · GitHub spree/spree#NNNN
+
+<!-- Tracking names the Linear issue (Spree project, milestone = target
+ version) and the GitHub issue (milestone vX.Y, on the Roadmap project).
+ /project:create-plan opens both; /project:update-plan and
+ /project:implement-plan keep them in step. Write "Linear —" or
+ "GitHub —" when one could not be created, never leave the line out. -->
<!-- Status is exactly one of the four labels, with detail after an em dash:
Draft — designed, nothing built