araemer/recipe-platform
1
0
Fork 0
Code Issues 13 Pull requests 3 Projects Releases Packages Wiki Activity Actions

feat(skills) Share cross-repo workflow skills through a recipe-workflow plugin #14

Merged
araemer merged 6 commits from shared-workflow-plugin into main 2026-09-27 04:50:58 +00:00
Conversation 2 Commits 6 Files changed 29 +1080 -114
araemer commented 2026-09-26 07:09:38 +00:00
Owner
Copy link

Shares the workflow skills that more than one repo needs through a Claude Code plugin marketplace hosted in this repo. Decision and alternatives: docs/adr/2026-09-26-shared-workflow-plugin.md. Please read the ADR first.

What changes

  • Marketplace: .claude-plugin/marketplace.json publishes plugins/recipe-workflow/. .claude/settings.json registers it by the Forgejo git URL and enables recipe-workflow@recipe-platform.
  • Plugin skills:
    • pr-feedback: moved; references updated.
    • check-workspace: new; replaces check-siblings here and check-platform in both siblings.
    • adr: new; owns the template (moved from docs/adr/template.md), file naming and the supersede procedure, for all three docs/adr/ directories.
    • implement-plan: new; the implementer procedure. Ends with an open PR (--no-pr stops before it) and counts every verification the repo's CLAUDE.md requires.
    • review-implementation: new; the reviewer procedure. Read-only, and checks against the repo's own CLAUDE.md instead of a copied checklist.
  • Platform skills: implement-feature and review-feature now spawn one sub-agent per sibling that runs those skills. plan-feature and architect.md point to the adr skill.
  • Docs: CLAUDE.md, README.md, ONBOARDING.md (new install step for the plugin).

Verification

  • claude plugin validate passes for the marketplace and the plugin. The only warning is the missing version, left out on purpose (see below).
  • Test spawn from the ADR: a session in recipe-backend with --plugin-dir plugins/recipe-workflow spawned a general-purpose sub-agent. It listed all five recipe-workflow: skills (the review skill was then still called review-plan) and had the backend CLAUDE.md loaded.
  • Not yet verified: installing through the marketplace itself, since the git source points at main. This can only be tested after merge.

Merge order

  1. This PR (the siblings' settings point at this marketplace on main)
  2. The sibling PRs in recipe-backend and recipe-app (they remove their local copies)

Open points

  • No version in plugin.json (verified against the plugin docs): with no version set, Claude Code uses the commit SHA as the version, so every merged change counts as an update. A pinned version would keep users on the cached copy until it's bumped. Auto-update is off by default for non-Anthropic marketplaces, so autoUpdate: true is now set in all three repos' settings. ONBOARDING.md describes the update path.
  • build-contract-for-node overlap: resolved. main is merged in. Its "Superseding an ADR" section in CLAUDE.md is now the ### ADRs section: a pointer to the adr skill that keeps the supersede wording and the Why: line.

Addition: an ADR for every skill and agent

New rule in CLAUDE.md (### ADRs): creating or changing a skill or agent requires an ADR explaining why it is built the way it is, written with recipe-workflow:adr.

  • Skill ADRs: <skill-dir>/adr/
  • Agent ADRs: .claude/agent-adr/<agent>/. Claude Code loads every .md in .claude/agents/ as an agent, so they can't sit next to the agent file.

The adr skill knows both locations. Initial ADRs are included for:

  • the five plugin skills
  • plan-feature, implement-feature and review-feature
  • the po and architect agents

The same rule is added to recipe-backend #17 and recipe-app #40; #40 also adds an ADR for verify-ui.

Addition: workflow howto

docs/howto-feature-workflow.md walks through the feature pipeline step by step: which agent or skill runs in each step, where to start it (platform or sibling), what it produces, and what you need to do at each gate. It's linked from README.md and ONBOARDING.md.

It also records a known gap: no step in the pipeline commits the spec, the plans or the repo ADRs.

Addition: review feedback (review 38)

  • Affected repos: the architect agent fills in a new "Affected Repos" section of the spec, and you approve it at GATE A. plan-feature, implement-feature and review-feature spawn sub-agents only in affected repos, using one prompt per role with the repo as a parameter.
  • PRs by default: implement-plan now opens its PR by default.
  • Verification: implement-plan counts every verification the repo's CLAUDE.md requires (e.g. verify-ui) and reports what it couldn't run.
  • Rename: review-plan is now review-implementation.
  • No history in ADRs: skill and agent ADRs state reasons, not history, and the adr skill says so.

🤖 Generated with Claude Code

Shares the workflow skills that more than one repo needs through a Claude Code plugin marketplace hosted in this repo. Decision and alternatives: `docs/adr/2026-09-26-shared-workflow-plugin.md`. Please read the ADR first. ## What changes - **Marketplace**: `.claude-plugin/marketplace.json` publishes `plugins/recipe-workflow/`. `.claude/settings.json` registers it by the Forgejo git URL and enables `recipe-workflow@recipe-platform`. - **Plugin skills**: - `pr-feedback`: moved; references updated. - `check-workspace`: new; replaces `check-siblings` here and `check-platform` in both siblings. - `adr`: new; owns the template (moved from `docs/adr/template.md`), file naming and the supersede procedure, for all three `docs/adr/` directories. - `implement-plan`: new; the implementer procedure. Ends with an open PR (`--no-pr` stops before it) and counts every verification the repo's `CLAUDE.md` requires. - `review-implementation`: new; the reviewer procedure. Read-only, and checks against the repo's own `CLAUDE.md` instead of a copied checklist. - **Platform skills**: `implement-feature` and `review-feature` now spawn one sub-agent per sibling that runs those skills. `plan-feature` and `architect.md` point to the `adr` skill. - **Docs**: `CLAUDE.md`, `README.md`, `ONBOARDING.md` (new install step for the plugin). ## Verification - `claude plugin validate` passes for the marketplace and the plugin. The only warning is the missing `version`, left out on purpose (see below). - Test spawn from the ADR: a session in `recipe-backend` with `--plugin-dir plugins/recipe-workflow` spawned a general-purpose sub-agent. It listed all five `recipe-workflow:` skills (the review skill was then still called `review-plan`) and had the backend `CLAUDE.md` loaded. - Not yet verified: installing through the marketplace itself, since the git source points at `main`. This can only be tested after merge. ## Merge order 1. This PR (the siblings' settings point at this marketplace on `main`) 2. The sibling PRs in recipe-backend and recipe-app (they remove their local copies) ## Open points - **No `version` in `plugin.json` (verified against the plugin docs)**: with no version set, Claude Code uses the commit SHA as the version, so every merged change counts as an update. A pinned version would keep users on the cached copy until it's bumped. Auto-update is off by default for non-Anthropic marketplaces, so `autoUpdate: true` is now set in all three repos' settings. `ONBOARDING.md` describes the update path. - **`build-contract-for-node` overlap: resolved.** `main` is merged in. Its "Superseding an ADR" section in `CLAUDE.md` is now the `### ADRs` section: a pointer to the `adr` skill that keeps the supersede wording and the **Why:** line. ## Addition: an ADR for every skill and agent New rule in `CLAUDE.md` (`### ADRs`): creating or changing a skill or agent requires an ADR explaining why it is built the way it is, written with `recipe-workflow:adr`. - Skill ADRs: `<skill-dir>/adr/` - Agent ADRs: `.claude/agent-adr/<agent>/`. Claude Code loads every `.md` in `.claude/agents/` as an agent, so they can't sit next to the agent file. The `adr` skill knows both locations. Initial ADRs are included for: - the five plugin skills - `plan-feature`, `implement-feature` and `review-feature` - the `po` and `architect` agents The same rule is added to recipe-backend #17 and recipe-app #40; #40 also adds an ADR for `verify-ui`. ## Addition: workflow howto `docs/howto-feature-workflow.md` walks through the feature pipeline step by step: which agent or skill runs in each step, where to start it (platform or sibling), what it produces, and what you need to do at each gate. It's linked from `README.md` and `ONBOARDING.md`. It also records a known gap: no step in the pipeline commits the spec, the plans or the repo ADRs. ## Addition: review feedback (review 38) - **Affected repos:** the `architect` agent fills in a new "Affected Repos" section of the spec, and you approve it at GATE A. `plan-feature`, `implement-feature` and `review-feature` spawn sub-agents only in affected repos, using one prompt per role with the repo as a parameter. - **PRs by default:** `implement-plan` now opens its PR by default. - **Verification:** `implement-plan` counts every verification the repo's `CLAUDE.md` requires (e.g. `verify-ui`) and reports what it couldn't run. - **Rename:** `review-plan` is now `review-implementation`. - **No history in ADRs:** skill and agent ADRs state reasons, not history, and the `adr` skill says so. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(skills) Share cross-repo workflow skills through a recipe-workflow plugin
All checks were successful
/ typecheck-contract (pull_request) Successful in 10s
Details
aeb8c0638f 
Publish recipe-platform as a Claude Code plugin marketplace with one plugin,
recipe-workflow, holding the skills more than one repo needs: pr-feedback
(moved), check-workspace (replaces check-siblings and check-platform), adr
(owns the ADR template and supersede procedure), implement-plan and
review-plan (the implementer and reviewer procedures, startable from either
the platform or a sibling). implement-feature and review-feature now spawn
sub-agents that run those skills. Recorded in
docs/adr/2026-09-26-shared-workflow-plugin.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	CLAUDE.md
#	ONBOARDING.md
docs(skills) Add skill and agent ADR locations to the adr skill
All checks were successful
/ typecheck-contract (pull_request) Successful in 19s
Details
92096ec65e 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs(skills) Add an ADR for every skill and agent
All checks were successful
/ typecheck-contract (pull_request) Successful in 18s
Details
c67c7cc75e 
Each skill gets <skill-dir>/adr/, each agent .claude/agent-adr/<agent>/,
stating why it is built the way it is. Covers the five plugin skills, the
three platform workflow skills, and the po and architect agents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs(workflow) Add a step-by-step howto for the feature pipeline
All checks were successful
/ typecheck-contract (pull_request) Successful in 18s
Details
7ff5a3817f 
Covers each pipeline step with the agent or skill that runs it, where to
start it, its output, and what the user has to do, plus a known gap:
nothing in the pipeline commits the spec, plans, or repo ADRs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
araemer reviewed 2026-09-27 04:36:01 +00:00
.claude/skills/implement-feature/SKILL.md
@ -28,3 +33,3 @@
### Step 2 — Spawn implementers (parallel)
**Backend implementer** (working directory: `../recipe-backend`):
**Backend implementer** (working directory: `../recipe-backend`) and **frontend
araemer commented 2026-09-26 17:17:31 +00:00
Author
Owner
Copy link

Only backend implementer is left.... If I understand this skill correctly, it's the orchestrator for implementation inf frontend and backend. If that is correct, it should check for plans in both repos. If both exist, it can spawn implementers, if theres only a single plan in one of the repos, it needs to ask the user, if it's correct that there is no backend/frontend work to do (or either be able to deduce it from the feature spec, but I'm not sure, that this is possible. If no plan exists in either repo, it needs to ask the user to plan first.

Only backend implementer is left.... If I understand this skill correctly, it's the orchestrator for implementation inf frontend and backend. If that is correct, it should check for plans in both repos. If both exist, it can spawn implementers, if theres only a single plan in one of the repos, it needs to ask the user, if it's correct that there is no backend/frontend work to do (or either be able to deduce it from the feature spec, but I'm not sure, that this is possible. If no plan exists in either repo, it needs to ask the user to plan first.
araemer marked this conversation as resolved
.claude/skills/implement-feature/adr/2026-09-26-implement-feature.md
@ -0,0 +6,4 @@
## Context
After plans are approved at GATE C, both repos are implemented independently against the
same contract. The implementer procedure used to be inlined here; it moved into the shared
araemer commented 2026-09-26 17:18:29 +00:00
Author
Owner
Copy link

No history please. That's unecessary. just the why and why is it done like this plus alternatives

No history please. That's unecessary. just the why and why is it done like this plus alternatives
araemer marked this conversation as resolved
.claude/skills/plan-feature/SKILL.md
@ -59,3 +58,1 @@
Never edit an existing ADR — if a prior decision is being superseded, write a new ADR
that names the one it replaces, then add a single "Superseded by: <path>" line to the
top of the old ADR as the only permitted post-acceptance change.
If a new decision is required: write it with the recipe-workflow:adr skill, which
araemer commented 2026-09-26 17:19:50 +00:00
Author
Owner
Copy link

this skill also only references the backend. Will this work as intended?

this skill also only references the backend. Will this work as intended?
araemer marked this conversation as resolved
plugins/recipe-workflow/skills/implement-plan/SKILL.md
@ -0,0 +19,4 @@
/recipe-workflow:implement-plan <NNN>-<slug> [--open-pr]
```
`--open-pr` is the go-ahead to push and open the PR at the end (Step 6). Without it, stop
araemer commented 2026-09-27 04:30:43 +00:00
Author
Owner
Copy link

I'd like for this to be the default. I like work to end in a pr that we can discuss. Only stop if you're told so.

I'd like for this to be the default. I like work to end in a pr that we can discuss. Only stop if you're told so.
araemer marked this conversation as resolved
plugins/recipe-workflow/skills/implement-plan/SKILL.md
@ -0,0 +55,4 @@
## Step 4 — Verify
Success is **the full build and the full test suite passing** — not a clean compile. A
araemer commented 2026-09-27 04:32:31 +00:00
Author
Owner
Copy link

Will this work with the frontend, where the UI needs to be verified as well? It should due to the frontend's claude.md, right?

Will this work with the frontend, where the UI needs to be verified as well? It should due to the frontend's claude.md, right?
araemer marked this conversation as resolved
plugins/recipe-workflow/skills/review-plan/SKILL.md
@ -0,0 +1,69 @@
---
name: review-plan
araemer commented 2026-09-27 04:35:43 +00:00
Author
Owner
Copy link

The name is a bit confusing. For me review-plan would just review the plan. "If i'd implement it, would all adrs be fullfilled, all ACs covered" For me this is review-plan-implementation

The name is a bit confusing. For me review-plan would just review the plan. "If i'd implement it, would all adrs be fullfilled, all ACs covered" For me this is review-plan-implementation
araemer marked this conversation as resolved
chore(claude) Auto-update the recipe-workflow plugin marketplace
All checks were successful
/ typecheck-contract (pull_request) Successful in 19s
Details
719f6664cd 
Claude Code leaves auto-update off for non-Anthropic marketplaces. With it
on, merged plugin changes install in the background. The plugin has no
version on purpose: Claude Code then uses the commit SHA, so every merged
change counts as an update. ONBOARDING's update step named only the
marketplace refresh, not the plugin update; it now describes auto-update
and the manual `claude plugin update` command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
araemer commented 2026-09-27 04:51:46 +00:00
Author
Owner
Copy link

Addressed in c6b2e6a:

  • #519 (PR by default): agreed and done. implement-plan ends with an open PR; --no-pr or an instruction to stop ends after the report. --open-pr is gone.
  • #520 (UI verification): partly covered by recipe-app's CLAUDE.md before, but Step 4 read as "build + tests only". It now counts every verification the repo's CLAUDE.md requires, e.g. verify-ui. A verification that can't run is reported as not verified instead of being counted as done. That is the usual case when started from the platform: the sub-agent lacks recipe-app's verify-ui skill and browser setup, and the feature's backend must be running. review-implementation treats a missing verification as a finding, and the howto says to run it in a recipe-app session.
  • #521 (rename): renamed to review-implementation, here and in recipe-backend #17 and recipe-app #40.
  • #515 (only backend left?): the diff view cut the line off; both implementers were spawned. The underlying gap is fixed: the architect decides the Affected Repos in the spec, you approve it at GATE A, and implement/review spawn only in those repos. A missing plan for an affected repo stops the skill.
  • #516 (no history in ADRs): all 10 skill and agent ADRs are rewritten to cover the problem, reasons and alternatives. The adr skill now requires this, and the verify-ui ADR in #40 is updated too.
  • #517 (plan-feature only backend?): the frontend was covered by "same prompt, adapted", which was too vague. Steps 3 and 4 now use one prompt per role with the repo as a parameter, spawned only for affected repos.

🤖 Generated with Claude Code

Addressed in c6b2e6a: - **#519 (PR by default):** agreed and done. `implement-plan` ends with an open PR; `--no-pr` or an instruction to stop ends after the report. `--open-pr` is gone. - **#520 (UI verification):** partly covered by recipe-app's `CLAUDE.md` before, but Step 4 read as "build + tests only". It now counts every verification the repo's `CLAUDE.md` requires, e.g. `verify-ui`. A verification that can't run is reported as not verified instead of being counted as done. That is the usual case when started from the platform: the sub-agent lacks recipe-app's `verify-ui` skill and browser setup, and the feature's backend must be running. `review-implementation` treats a missing verification as a finding, and the howto says to run it in a recipe-app session. - **#521 (rename):** renamed to `review-implementation`, here and in recipe-backend #17 and recipe-app #40. - **#515 (only backend left?):** the diff view cut the line off; both implementers were spawned. The underlying gap is fixed: the architect decides the **Affected Repos** in the spec, you approve it at GATE A, and implement/review spawn only in those repos. A missing plan for an affected repo stops the skill. - **#516 (no history in ADRs):** all 10 skill and agent ADRs are rewritten to cover the problem, reasons and alternatives. The `adr` skill now requires this, and the verify-ui ADR in #40 is updated too. - **#517 (plan-feature only backend?):** the frontend was covered by "same prompt, adapted", which was too vague. Steps 3 and 4 now use one prompt per role with the repo as a parameter, spawned only for affected repos. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
araemer/recipe-platform!14
No description provided.