Skip to content

Commit 8408afb

Browse files
amir-yogev-ghclaude
amir-yogev-gh
and
claude
committed
Add project-level phase override support to all workflow controllers
Teams can now customize individual workflow phases without forking by placing override files at .workflows/{workflow}/skills/{phase}.md in their project repo. Controllers check for overrides before falling back to built-in defaults. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent ab01692 commit 8408afb

13 files changed

Lines changed: 306 additions & 48 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ workflow-name/
4747
3. **Relative paths**: All file references must be relative to the file's location (for symlink compatibility)
4848
4. **Phase-based execution**: Most workflows operate through discrete phases with explicit transitions
4949
5. **Shared resources**: Cross-cutting concerns live in `_shared/` and are referenced by relative path
50+
6. **Phase overrides**: Projects can override individual phases by placing a replacement skill file at `.workflows/{workflow}/skills/{phase}.md` in their repo root. The controller checks for this override before falling back to the built-in default. See CONTRIBUTING.md for details
5051

5152
### Shared Resources (`_shared/`)
5253

‎CONTRIBUTING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,13 @@ workflow-name/
1414
phase-name.md # One file per phase
1515
commands/
1616
phase-name.md # Thin wrappers that invoke the controller or SKILL.md for a specific phase
17+
18+
Project-level phase overrides (in the consuming repo):
19+
20+
.workflows/
21+
workflow-name/
22+
skills/
23+
phase-name.md # Overrides the built-in phase skill (see "Phase Overrides" below)
1724
```
1825

1926
The installer auto-discovers any directory with a `SKILL.md`. No script changes are needed when adding a workflow.
@@ -82,6 +89,39 @@ All internal file references must be **relative to the file's own location**:
8289

8390
This ensures symlinks resolve paths correctly regardless of where the workflow is installed.
8491

92+
**Exception:** Phase override paths (`.workflows/{workflow}/skills/{phase}.md`) are relative to the consuming project's repo root, not to the controller file's location. This is intentional — overrides live outside the workflow directory tree.
93+
94+
## Phase Overrides
95+
96+
Projects can override individual phase skills without forking the workflow. When a controller dispatches a phase, it checks for a project-level override before falling back to the built-in default:
97+
98+
1. **`.workflows/{workflow}/skills/{phase}.md`** — project-level override at the repo root
99+
2. **`{phase}.md`** — workflow's built-in default (sibling file in `skills/`)
100+
101+
For example, a team that needs a custom `/sync` phase for the design workflow drops a file at `.workflows/design/skills/sync.md` in their repo. The controller picks it up automatically and announces the override to the user.
102+
103+
### Rules for Override Files
104+
105+
- **Full replacement.** An override replaces the entire phase — it is not merged with the built-in. The override file must be self-contained.
106+
- **Same contract.** The override must read the same input artifacts and write the same output artifacts as the built-in phase. Downstream phases and the controller depend on this contract (see the Artifacts table in each controller).
107+
- **Same exit behavior.** End the override file with the same "report findings and re-read the controller" instruction so the controller can recommend next steps.
108+
- **No cross-references to built-in internals.** The override should not reference sibling files in the workflow's `skills/` directory — it lives in the project repo and should be self-contained.
109+
110+
### Example Project Layout
111+
112+
```
113+
my-project/
114+
├── .workflows/
115+
│ ├── design/
116+
│ │ └── skills/
117+
│ │ └── sync.md ← custom sync, all other phases use the built-in
118+
│ └── bugfix/
119+
│ └── skills/
120+
│ └── fix.md ← custom fix phase
121+
├── src/
122+
└── ...
123+
```
124+
85125
## Installation Internals
86126

87127
The installer (`install.sh`) auto-discovers workflows by scanning for `*/SKILL.md` at the repo root. No script changes are needed when adding a workflow.

‎bugfix/skills/controller.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,20 @@ Phases can be skipped or reordered at the user's discretion.
4646

4747
1. **Announce** the phase to the user before doing anything else, e.g., "Starting the /fix phase."
4848
This is very important so the user knows that the workflow is working and learns about the commands.
49-
2. **Read** the skill file from the list above
50-
3. **Execute** the skill's steps directly — the user should see your progress
51-
4. When the skill is done, it will tell you to report your findings and
49+
2. **Locate** the skill file — check for a project-level override before
50+
falling back to the workflow default. Use the first match found:
51+
1. **`.workflows/bugfix/skills/{phase}.md`** — project-level override at the
52+
repo root (e.g., `.workflows/bugfix/skills/fix.md`)
53+
2. **`{phase}.md`** — workflow's built-in default (sibling file)
54+
55+
If using a project override, announce it: *"Using project override for /{phase}."*
56+
3. **Read** the resolved skill file
57+
4. **Execute** the skill's steps directly — the user should see your progress
58+
5. When the skill is done, it will tell you to report your findings and
5259
re-read this controller. Do that — then use "Recommending Next Steps"
5360
below to offer options.
54-
5. Present the skill's results and your recommendations to the user
55-
6. **Stop and wait** for the user to tell you what to do next
61+
6. Present the skill's results and your recommendations to the user
62+
7. **Stop and wait** for the user to tell you what to do next
5663

5764
## Recommending Next Steps
5865

‎cherry-picker/skills/controller.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
name: controller
3+
description: Top-level workflow controller that manages phase transitions.
4+
---
5+
6+
# Cherry-picker Workflow Controller
7+
8+
You are the workflow controller. Your job is to manage the cherry-picker workflow by executing phases and handling transitions between them.
9+
10+
## Phases
11+
12+
0. **Start** (`/start`) — `start.md`
13+
Present available phases, gather parameters (label, target branch, source branch).
14+
15+
1. **Scan** (`/scan`) — `scan.md`
16+
Find merged PRs with the specified label, identify commits not yet backported.
17+
18+
2. **Exclude** (`/exclude`) — `exclude.md` *(optional, after scan)*
19+
Remove a commit (by hash) from the backport list and move it to "Manually excluded commits" in the scan-results file. Optional phase following scan when the user wants to drop specific commits.
20+
21+
3. **Include** (`/include`) — `include.md` *(optional, after scan)*
22+
Add a commit (by hash) to the backport set and record it in "Manually included commits" in the scan-results file (with optional Reason for visibility). Optional phase following scan when the user wants to add commits not in the label scan (e.g. unlabeled PRs).
23+
24+
4. **Pick** (`/pick`) — `pick.md`
25+
Cherry-pick the identified commits to a working branch off the target.
26+
27+
5. **PR** (`/pr`) — `pr.md`
28+
Push the working branch and create a pull request.
29+
30+
Phases can be skipped or reordered at the user's discretion.
31+
32+
## Parameters
33+
34+
These parameters are gathered during `/start` or `/scan` and carried through the workflow:
35+
36+
| Parameter | Required | Default | Gathered in |
37+
|-----------|----------|---------|-------------|
38+
| PR label | Yes | — | `/start` |
39+
| Target branch | Yes | — | `/start` |
40+
| Source branch | No | `main` | `/start` |
41+
| Working branch name | No | suggested at `/pick` time | `/pick` |
42+
| PR title | No | suggested at `/pr` time | `/pr` |
43+
| Last backported commit | No | — | `/start` |
44+
45+
If the user provides parameters in their initial message, use them directly — don't
46+
ask again.
47+
48+
**Working branch name** and **PR title** are arbitrary — the workflow suggests a default
49+
but the user can override it. See the `/pick` and `/pr` skills for details.
50+
51+
## How to Execute a Phase
52+
53+
1. **Announce** the phase to the user before doing anything else, e.g., "Starting the /scan phase." This is very important so the user knows that the workflow is working and learns about the commands.
54+
2. **Locate** the skill file — check for a project-level override before
55+
falling back to the workflow default. Use the first match found:
56+
1. **`.workflows/cherry-picker/skills/{phase}.md`** — project-level override at the
57+
repo root (e.g., `.workflows/cherry-picker/skills/scan.md`)
58+
2. **`{phase}.md`** — workflow's built-in default (sibling file)
59+
60+
If using a project override, announce it: *"Using project override for /{phase}."*
61+
3. **Read** the resolved skill file
62+
4. **Execute** the skill's steps directly — the user should see your progress
63+
5. When the skill is done, it will tell you to report your findings and re-read this controller. Do that — then use "Recommending Next Steps" below to offer options.
64+
6. Present the skill's results and your recommendations to the user
65+
7. **Stop and wait** for the user to tell you what to do next
66+
67+
## Recommending Next Steps
68+
69+
After each phase completes, present the user with **options** — not just one next step. Use the typical flow as a baseline, but adapt to what actually happened.
70+
71+
### Typical Flow
72+
73+
```text
74+
start → scan → [exclude / include] → pick → pr
75+
```
76+
77+
The **exclude** and **include** phases are optional and follow scan when the user wants to remove or add specific commits (by hash) before picking.
78+
79+
### What to Recommend
80+
81+
After presenting results, consider what just happened, then offer options that make sense:
82+
83+
**Continuing to the next step** — often the next phase in the flow is the best option
84+
85+
**Skipping forward** — sometimes phases aren't needed:
86+
87+
- User already provided all parameters → skip `/start`, go straight to `/scan`
88+
- Scan found no commits to backport → workflow is done, nothing to pick
89+
90+
**Excluding a commit** — optional phase after scan; user wants to drop one commit from the backport list:
91+
92+
- After scan, if the user asks to exclude a commit by hash → run `/exclude <hash>`; the exclude skill updates the scan-results file and moves the commit to "Manually excluded commits". Then recommend `/pick` when done excluding.
93+
94+
**Including a commit** — optional phase after scan; user wants to add one commit to the backport set (e.g. unlabeled PR):
95+
96+
- After scan, if the user asks to include a commit by hash → run `/include <hash>` (optionally with a reason); the include skill adds the commit to "Manually included commits" in the scan-results file. Then recommend `/pick` when done including.
97+
98+
**Going back** — sometimes earlier work needs revision:
99+
100+
- Pick had conflicts that changed the scope → offer `/scan` to re-verify
101+
- PR review revealed issues → offer `/pick` to redo the cherry-picks
102+
103+
**Ending early** — not every run needs the full pipeline:
104+
105+
- Scan found nothing → done (idempotent exit)
106+
- User wants to pick but create the PR manually → stop after `/pick`
107+
108+
### How to Present Options
109+
110+
Lead with your top recommendation, then list alternatives briefly:
111+
112+
```text
113+
Recommended next step: /pick — cherry-pick the 3 commits to release-1.0.
114+
115+
Other options:
116+
- /pr — if you've already cherry-picked manually and just need the PR
117+
- /scan — re-scan with different parameters
118+
```
119+
120+
## Starting the Workflow
121+
122+
When the user runs `/start` or asks to begin without providing specific context:
123+
124+
1. Execute the **start** phase to present options and gather parameters
125+
2. After the user provides parameters, dispatch `/scan`
126+
127+
When the user provides parameters directly (label, target branch):
128+
129+
1. Execute the **scan** phase with the provided parameters
130+
2. After scan, present results and wait
131+
132+
If the user invokes a specific command (e.g., `/pick`, `/exclude <hash>`, `/include <hash>`), execute that phase directly — don't force them through earlier phases.
133+
134+
## Rules
135+
136+
- **Never auto-advance.** Always wait for the user between phases.
137+
- **Recommendations come from this file, not from skills.** Skills report findings; this controller decides what to recommend next.

‎code-review/skills/controller.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,21 @@ Code changes happen directly in the working tree during `/continue`.
4343
## How to Execute a Phase
4444

4545
1. **Announce** the phase to the user: *"Starting /start."*
46-
2. **Read** the skill file from the list above (e.g., `start.md`)
47-
3. **Execute** the skill's steps -- the user should see your progress
48-
4. When the skill is done, it will tell you to report findings and
46+
2. **Locate** the skill file -- check for a project-level override before
47+
falling back to the workflow default. Use the first match found:
48+
1. **`.workflows/code-review/skills/{phase}.md`** -- project-level override at the
49+
repo root (e.g., `.workflows/code-review/skills/start.md`)
50+
2. **`{phase}.md`** -- workflow's built-in default (sibling file)
51+
52+
If using a project override, announce it: *"Using project override
53+
for /{phase}."*
54+
3. **Read** the resolved skill file
55+
4. **Execute** the skill's steps -- the user should see your progress
56+
5. When the skill is done, it will tell you to report findings and
4957
re-read this controller. Do that -- then use "Recommending Next Steps"
5058
below to offer options.
51-
5. Present the skill's results and your recommendations to the user
52-
6. **Stop and wait** for the user to tell you what to do next
59+
6. Present the skill's results and your recommendations to the user
60+
7. **Stop and wait** for the user to tell you what to do next
5361

5462
## Recommending Next Steps
5563

‎cve-fix/skills/controller.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -37,13 +37,20 @@ Phases can be skipped or reordered at the user's discretion.
3737

3838
1. **Announce** the phase to the user before doing anything else, e.g., "Starting the /patch phase."
3939
This is very important so the user knows that the workflow is working and learns about the commands.
40-
2. **Read** the skill file from the list above
41-
3. **Execute** the skill's steps directly — the user should see your progress
42-
4. When the skill is done, it will tell you to report your findings and
40+
2. **Locate** the skill file — check for a project-level override before
41+
falling back to the workflow default. Use the first match found:
42+
1. **`.workflows/cve-fix/skills/{phase}.md`** — project-level override at the
43+
repo root (e.g., `.workflows/cve-fix/skills/patch.md`)
44+
2. **`{phase}.md`** — workflow's built-in default (sibling file)
45+
46+
If using a project override, announce it: *"Using project override for /{phase}."*
47+
3. **Read** the resolved skill file
48+
4. **Execute** the skill's steps directly — the user should see your progress
49+
5. When the skill is done, it will tell you to report your findings and
4350
re-read this controller. Do that — then use "Recommending Next Steps"
4451
below to offer options.
45-
5. Present the skill's results and your recommendations to the user
46-
6. **Stop and wait** for the user to tell you what to do next
52+
6. Present the skill's results and your recommendations to the user
53+
7. **Stop and wait** for the user to tell you what to do next
4754

4855
## Recommending Next Steps
4956

‎design/skills/controller.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -84,13 +84,21 @@ published copy in the docs repo.
8484
## How to Execute a Phase
8585

8686
1. **Announce** the phase to the user: *"Starting /draft."*
87-
2. **Read** the skill file from the list above (e.g., `draft.md`)
88-
3. **Execute** the skill's steps — the user should see your progress
89-
4. When the skill is done, it will tell you to report findings and
87+
2. **Locate** the skill file — check for a project-level override before
88+
falling back to the workflow default. Use the first match found:
89+
1. **`.workflows/design/skills/{phase}.md`** — project-level override at the
90+
repo root (e.g., `.workflows/design/skills/draft.md`)
91+
2. **`{phase}.md`** — workflow's built-in default (sibling file)
92+
93+
If using a project override, announce it: *"Using project override
94+
for /{phase}."*
95+
3. **Read** the resolved skill file
96+
4. **Execute** the skill's steps — the user should see your progress
97+
5. When the skill is done, it will tell you to report findings and
9098
re-read this controller. Do that — then use "Recommending Next Steps"
9199
below to offer options.
92-
5. Present the skill's results and your recommendations to the user
93-
6. **Stop and wait** for the user to tell you what to do next
100+
6. Present the skill's results and your recommendations to the user
101+
7. **Stop and wait** for the user to tell you what to do next
94102

95103
## Recommending Next Steps
96104

‎docs-writer/skills/controller.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,20 @@ Phases can be skipped or reordered at the user's discretion.
8888

8989
1. **Announce** the phase to the user before doing anything else, e.g., "Starting the /gather phase." This is important so the user knows the workflow is working and learns the commands.
9090
2. **Check prerequisites** — verify the required input artifacts exist (see the Artifacts table). If any are missing, tell the user which phase to run first and stop. If this phase's output artifact already exists, warn that re-running will overwrite it — wait for confirmation, then delete all artifacts from this phase and later phases before proceeding.
91-
3. **Read** the skill file from the list above.
92-
4. **Execute** the skill's steps directly — the user should see your progress.
93-
5. When the skill is done, follow "When This Phase Is Done" below.
94-
6. **Stop and wait** for the user to tell you what to do next.
91+
3. **Locate** the skill file — check for a project-level override before
92+
falling back to the workflow default. Use the first match found:
93+
1. **`.workflows/docs-writer/skills/{skill-file}`** — project-level override at the
94+
repo root (e.g., `.workflows/docs-writer/skills/gather-context.md`)
95+
2. **`{skill-file}`** — workflow's built-in default (sibling file)
96+
97+
`{skill-file}` is the filename from the Phases list above (e.g.,
98+
`gather-context.md` for `/gather`, `plan-structure.md` for `/plan`).
99+
100+
If using a project override, announce it: *"Using project override for /{phase}."*
101+
4. **Read** the resolved skill file.
102+
5. **Execute** the skill's steps directly — the user should see your progress.
103+
6. When the skill is done, follow "When This Phase Is Done" below.
104+
7. **Stop and wait** for the user to tell you what to do next.
95105

96106
## When The Phase Is Done
97107

‎e2e/skills/controller.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,13 +60,21 @@ the source repo:
6060
## How to Execute a Phase
6161

6262
1. **Announce** the phase to the user: *"Starting /plan."*
63-
2. **Read** the skill file from the list above (e.g., `plan.md`)
64-
3. **Execute** the skill's steps — the user should see your progress
65-
4. When the skill is done, it will tell you to report findings and
63+
2. **Locate** the skill file — check for a project-level override before
64+
falling back to the workflow default. Use the first match found:
65+
1. **`.workflows/e2e/skills/{phase}.md`** — project-level override at the
66+
repo root (e.g., `.workflows/e2e/skills/plan.md`)
67+
2. **`{phase}.md`** — workflow's built-in default (sibling file)
68+
69+
If using a project override, announce it: *"Using project override
70+
for /{phase}."*
71+
3. **Read** the resolved skill file
72+
4. **Execute** the skill's steps — the user should see your progress
73+
5. When the skill is done, it will tell you to report findings and
6674
re-read this controller. Do that — then use "Recommending Next Steps"
6775
below to offer options.
68-
5. Present the skill's results and your recommendations to the user
69-
6. **Stop and wait** for the user to tell you what to do next
76+
6. Present the skill's results and your recommendations to the user
77+
7. **Stop and wait** for the user to tell you what to do next
7078

7179
## Recommending Next Steps
7280

‎implement/skills/controller.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -58,13 +58,21 @@ the source repo:
5858
## How to Execute a Phase
5959

6060
1. **Announce** the phase to the user: *"Starting /plan."*
61-
2. **Read** the skill file from the list above (e.g., `plan.md`)
62-
3. **Execute** the skill's steps — the user should see your progress
63-
4. When the skill is done, it will tell you to report findings and
61+
2. **Locate** the skill file — check for a project-level override before
62+
falling back to the workflow default. Use the first match found:
63+
1. **`.workflows/implement/skills/{phase}.md`** — project-level override at the
64+
repo root (e.g., `.workflows/implement/skills/plan.md`)
65+
2. **`{phase}.md`** — workflow's built-in default (sibling file)
66+
67+
If using a project override, announce it: *"Using project override
68+
for /{phase}."*
69+
3. **Read** the resolved skill file
70+
4. **Execute** the skill's steps — the user should see your progress
71+
5. When the skill is done, it will tell you to report findings and
6472
re-read this controller. Do that — then use "Recommending Next Steps"
6573
below to offer options.
66-
5. Present the skill's results and your recommendations to the user
67-
6. **Stop and wait** for the user to tell you what to do next
74+
6. Present the skill's results and your recommendations to the user
75+
7. **Stop and wait** for the user to tell you what to do next
6876

6977
## Recommending Next Steps
7078

0 commit comments

Comments
 (0)