Skip to content

Commit 273b961

Browse files
maxgfrmaxgfr
committed
fix(skills): clarify /implement and /ship workflow documentation
1 parent 60c209c commit 273b961

4 files changed

Lines changed: 60 additions & 262 deletions

File tree

‎.claude/rules/automation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,4 +134,4 @@ Two skills split the lifecycle into "code" and "deliver":
134134
| Command | When to use |
135135
|---|---|
136136
| `/implement [#N]` | Fetch issue, create branch, code, validate (4 agents). |
137-
| `/ship` | Create PR (single/split), watch reviews, wrap up. Run after `/implement`. |
137+
| `/ship` | Create PR (single/split), handle review cycle. Run after `/implement`. |

‎.claude/skills/implement/SKILL.md‎

Lines changed: 23 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -5,136 +5,55 @@ description: "Implement a GitHub issue: fetch, branch, code, validate. Usage: /i
55

66
# /implement
77

8-
Implements a GitHub issue from start to validated code. Handles sub-tasks, Figma designs, and runs all quality gates.
8+
Implements a GitHub issue end-to-end: understand the issue, code it, validate it.
99

1010
## Arguments
1111

12-
`$ARGUMENTS` — optional: GitHub issue number (`#123`), URL, or just `123`.
12+
`$ARGUMENTS` — GitHub issue number (`#123`, URL, or `123`). If omitted, infer from branch name (`feat/issue-{N}-*`) or ask.
1313

1414
---
1515

16-
# Step 0 — Detect state
16+
# Step 1 — Understand the issue
1717

18-
Run this **before anything else** to figure out where we are:
18+
Extract `{owner}/{repo}` from `git remote get-url origin` (needed for API calls below).
1919

20-
```bash
21-
BRANCH=$(git branch --show-current)
22-
git diff origin/master...HEAD --name-only
23-
git diff --name-only HEAD
24-
```
20+
Fetch the issue **including comments** (requirements, Figma links, acceptance criteria often live there).
2521

26-
Also try to infer the issue number from the branch name if no `$ARGUMENTS` given (e.g. `feat/issue-{N}-*`).
27-
28-
### Routing
29-
30-
| State | Action |
31-
|---|---|
32-
| Issue number given + no changes on branch | **Phase 1** — implement |
33-
| Issue number given + changes already exist | **Phase 2** — validate |
34-
| No arg + changes exist + no open PR | **Phase 2** — validate (infer issue from branch) |
35-
| No arg + no changes | Ask: "Which issue? (`#123`)" |
36-
37-
**Always announce** which phase was detected:
38-
> "Branch `feat/issue-42-...`, no changes yet. Starting at **Phase 1 — Implement**."
39-
40-
---
41-
42-
# Phase 1 — Implement
43-
44-
## 1.1 — Resolve issue
45-
46-
1. Extract issue number from `$ARGUMENTS` (URL, `#N`, or `N`)
47-
2. If owner/repo not in URL: `git remote get-url origin`
48-
49-
## 1.2 — Fetch issue and detect tasks
50-
51-
```bash
52-
gh issue view {N} --json number,title,body,state,labels,comments
53-
```
54-
55-
Treat **comments** as part of the context (requirements, Figma links, acceptance criteria).
56-
57-
Detect sub-tasks in order:
22+
Detect sub-tasks in priority order:
5823

5924
1. **Native sub-issues**: `gh api repos/{owner}/{repo}/issues/{N}/sub_issues`
6025
2. **Checkboxes**: `- [ ] task` in body + comments
6126
3. **Single task**: the issue itself
6227

63-
Present the task list with `AskUserQuestion` and ask for confirmation.
64-
65-
## 1.3 — Branch
66-
67-
Ask with `AskUserQuestion`:
68-
> "Create branch `feat/issue-{N}-{slug}` or stay on `{current_branch}`?"
69-
70-
## 1.4 — Task loop
71-
72-
For each pending task:
73-
74-
### Fetch details
75-
- Sub-issue: `gh issue view {task_number} --json number,title,body,labels,comments`
76-
- Checkbox: use text as description
77-
78-
### Analyze scope
79-
- Identify affected files, modules, patterns
80-
- Load `packages/app/CLAUDE.md` if working in app
81-
- **Figma**: if UI task + Figma URL in body/comments -> `get_design_context`. If UI task + no URL -> ask user for link.
82-
83-
### Implement
84-
- Follow all conventions from `CLAUDE.md` and `packages/app/CLAUDE.md`
85-
- Write code, tests, migrations
86-
- Use existing codebase patterns
87-
88-
### Report progress
89-
```
90-
[{current}/{total}] #{task_number} {task_title} DONE
91-
```
92-
93-
-> Continue to **Phase 2**.
28+
Present the task list and confirm with the user before starting.
9429

9530
---
9631

97-
# Phase 2 — Validate
32+
# Step 2 — Branch
9833

99-
## 2.1 — Scope
34+
Create `feat/issue-{N}-{slug}` from `origin/master`. If the current branch already tracks this issue, stay on it.
10035

101-
```bash
102-
git diff origin/master...HEAD --name-only
103-
```
104-
Fallback: `git diff --name-only HEAD`
36+
---
10537

106-
## 2.2 — Launch 4 parallel agents
38+
# Step 3 — Implement
10739

108-
1. **Validator** — `.claude/agents/validator/AGENT.md` (typecheck + test + lint + format)
109-
2. **Structural auditor** — `.claude/agents/structural-auditor/AGENT.md` on all changed files
110-
3. **RGAA auditor** — `.claude/agents/rgaa-auditor/AGENT.md` on changed `.tsx`. Auto-fix `[ERROR]`.
111-
4. **Security auditor** — `.claude/agents/security-auditor/AGENT.md` on changed `.ts/.tsx`. Auto-fix `[CRITICAL]` and `[HIGH]`.
40+
For each task:
11241

113-
## 2.3 — Fix loop
42+
1. **Fetch details** — if the task is a sub-issue, fetch its full content individually (`gh issue view {task_number}`). For checkboxes, use the text as description.
43+
2. **Analyze scope** — identify affected files, modules, patterns
44+
3. **Figma** — if UI task with a Figma URL in the issue, follow `.claude/rules/figma-workflow.md` strictly. If UI task without URL, ask for the link.
45+
4. **Code** — write code, tests, migrations
46+
5. **Commit** — one commit per logical unit of work (not per file, not one giant commit at the end). Conventional messages: `feat:`, `fix:`, `refactor:`. Clean commit boundaries make split PRs easier in `/ship`.
47+
6. **Report** — `[{current}/{total}] #{task} — done`
11448

115-
1. Fix all violations
116-
2. Re-run only failing agents
117-
3. If auto-fixes applied, re-run validator too
118-
4. **Loop until zero violations**
49+
---
11950

120-
## 2.4 — Lighthouse (if dev server running)
51+
# Step 4 — Validate
12152

122-
```bash
123-
pnpm test:lighthouse # must score 100% accessibility
124-
```
53+
Run the quality gates defined in `.claude/rules/automation.md`: 4 parallel agents (validator, structural, RGAA, security).
12554

126-
## 2.5 — Report
55+
**Fix loop**: fix all violations, re-run only the failing agents, and if auto-fixes were applied also re-run the validator. Loop until zero violations.
12756

128-
```
129-
## Validation: PASS
130-
| Check | Status |
131-
|------------|--------|
132-
| Typecheck | PASS |
133-
| Tests | PASS |
134-
| Lint | PASS |
135-
| Structure | PASS |
136-
| RGAA | PASS |
137-
| Security | SECURE |
138-
```
57+
If the dev server is running, also run `pnpm test:lighthouse` (must score 100% accessibility).
13958

14059
Done. Code is validated and ready to ship via `/ship`.

‎.claude/skills/ship/SKILL.md‎

Lines changed: 34 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,42 @@
11
---
22
name: ship
3-
description: "Ship validated code: create PR (single/split), watch reviews, wrap up. Usage: /ship"
3+
description: "Ship validated code: create PR, watch reviews. Usage: /ship"
44
---
55

66
# /ship
77

8-
Ships validated code to GitHub. Creates PR, watches reviews, and wraps up. Run after `/implement` has validated the code.
8+
Ships validated code to GitHub. Creates the PR and handles the review cycle. Run after `/implement`.
99

1010
## Arguments
1111

12-
`$ARGUMENTS` — optional: not typically needed (state is inferred from branch/PR).
12+
`$ARGUMENTS` — not typically needed. State is inferred from branch and PR status.
1313

1414
---
1515

1616
# Step 0 — Detect state
1717

18-
Run this **before anything else** to figure out where we are:
18+
Check branch, commits, and existing PR. Route accordingly:
1919

20-
```bash
21-
BRANCH=$(git branch --show-current)
22-
gh pr view --json number,title,url,reviewDecision,comments,reviews 2>/dev/null
23-
git diff origin/master...HEAD --name-only
24-
git log --oneline --reverse origin/master..HEAD
25-
```
26-
27-
Also try to infer the issue number from the branch name (e.g. `feat/issue-{N}-*`).
28-
29-
### Routing
20+
- **Commits on branch, no open PR** -> Step 1 (create PR)
21+
- **Open PR with unresolved review comments** -> Step 2 (review)
22+
- **Open PR, nothing unresolved** -> done, report status
23+
- **No commits on branch** -> nothing to ship, suggest `/implement`
3024

31-
| State | Action |
32-
|---|---|
33-
| Changes exist + no open PR | **Phase 1** — create PR |
34-
| Open PR + unresolved review comments | **Phase 2** — review |
35-
| Open PR + no unresolved comments | **Phase 3** — done |
36-
| No changes + no PR | Nothing to ship. Suggest `/implement` first. |
37-
38-
**Always announce** which phase was detected:
39-
> "Branch `feat/issue-42-...`, open PR #87, 3 unresolved comments. Starting at **Phase 2 — Review**."
25+
Announce what was detected before proceeding.
4026

4127
---
4228

43-
# Phase 1 — PR
44-
45-
## 1.1 — Analyze
29+
# Step 1 — Create PR
4630

47-
```bash
48-
git log --oneline --reverse origin/master..HEAD
49-
git diff origin/master..HEAD --stat
50-
```
51-
52-
## 1.2 — Ask strategy
53-
54-
Ask with `AskUserQuestion`:
55-
> "Ship as:"
56-
> 1. **Single PR**
57-
> 2. **Split** into multiple PRs
58-
> 3. **Skip** for now
31+
Analyze commits on the branch, then ask: **single PR** or **split**?
5932

6033
### Single PR
6134

62-
```bash
63-
git push -u origin {branch}
64-
gh pr create --base master --title "<from issue>" --body "$(cat <<'EOF'
35+
Push and create PR. Use this body template:
36+
37+
```
6538
## Summary
66-
<1-3 bullet points>
39+
<1-3 bullet points from the issue/commits>
6740
6841
Closes #{N}
6942
@@ -72,129 +45,35 @@ Closes #{N}
7245
- [x] Structural / RGAA / Security audit
7346
7447
Generated with [Claude Code](https://claude.com/claude-code)
75-
EOF
76-
)"
7748
```
7849

7950
### Split PRs
8051

81-
1. Read each commit's diff, group by **logical concern**
82-
2. Each group: self-contained, single purpose, respects dependency order
83-
3. If only one group -> fall back to single PR
84-
4. Present plan as table, **ask confirmation** via `AskUserQuestion`
85-
5. For each group in order:
86-
- Branch: `split/{original-branch}/{short-name}` (first from `origin/master`, rest from previous)
87-
- Cherry-pick commits (resolve conflicts or ask user)
88-
- Verify green via `.claude/agents/validator/AGENT.md`
89-
- Push + create PR
90-
6. Cross-link all PRs (update each body with ordered list)
91-
7. Return to original branch
92-
93-
### Skip
94-
95-
Continue without PR.
96-
97-
-> Continue to **Phase 2**.
98-
99-
---
100-
101-
# Phase 2 — Review
102-
103-
## 2.1 — Ask
104-
105-
Ask with `AskUserQuestion`:
106-
> "PR ready: {PR_URL}. Watch for reviews?"
107-
108-
If no -> **Phase 3**.
109-
110-
## 2.2 — Gather context (2 parallel agents)
52+
Group commits by logical concern. Present the plan as a table and ask confirmation. For each group in dependency order:
11153

112-
**Agent 1 — PR comments:**
113-
```bash
114-
gh pr view --json number,title,body,headRefName,baseRefName,url,comments,reviews,reviewDecision
115-
gh api repos/{owner}/{repo}/pulls/{number}/comments
116-
```
117-
118-
**Agent 2 — Code review:**
119-
Delegate diff to `.claude/agents/structural-auditor/AGENT.md`.
120-
121-
## 2.3 — Analyze
122-
123-
1. **Human comments** -> categorize: code change, clarification, style fix, resolved
124-
2. **Auditor findings** -> ERROR and WARN items
125-
3. Check if already addressed in subsequent commits
126-
127-
No unresolved comments -> **Phase 3**.
128-
129-
## 2.4 — Fix
130-
131-
For each unresolved issue:
132-
1. Read the file
133-
2. Apply fix following project conventions
134-
3. If ambiguous, ask for clarification
135-
136-
## 2.5 — Re-validate
137-
138-
Re-run validation (4 agents + fix loop) as described in `/implement` Phase 2.
139-
140-
## 2.6 — Reply (user-driven)
54+
- Branch naming: `split/{original-branch}/{short-name}`
55+
- First branch from `origin/master`, each subsequent branch from the previous one
56+
- Cherry-pick commits, validate via the validator agent, push, create PR
14157

142-
**NEVER** reply automatically. Ask with `AskUserQuestion`:
143-
> "Reply to resolved comments on GitHub?"
144-
145-
If yes: `gh api .../comments/{id}/replies -f body="Fixed in latest commit."`
146-
147-
## 2.7 — Push
148-
149-
```bash
150-
git push
151-
```
152-
153-
## 2.8 — Loop
154-
155-
Ask with `AskUserQuestion`:
156-
> "Keep watching for new reviews?"
157-
158-
If yes -> back to 2.2. If no -> **Phase 3**.
58+
Cross-link all PRs in their bodies.
15959

16060
---
16161

162-
# Phase 3 — Done
163-
164-
## 3.1 — Wrap up
62+
# Step 2 — Review cycle
16563

166-
**NEVER** take GitHub actions automatically. Ask with `AskUserQuestion`:
167-
> "Shipped. Anything else?"
64+
Gather context in parallel:
65+
1. Fetch PR comments and review status
66+
2. Run structural auditor on the PR diff
16867

169-
Options:
170-
- **Close sub-issues**
171-
- **Comment on parent issue**
172-
- **Nothing**
68+
For each unresolved comment:
69+
1. Categorize: code change needed / clarification / style fix / already resolved
70+
2. **Check if already addressed** in a subsequent commit before re-fixing
71+
3. Fix what needs fixing
72+
4. Re-validate (quality gates from `.claude/rules/automation.md`)
17373

174-
## 3.2 — Final report
74+
After fixes:
75+
- **Never reply to comments automatically** — ask the user first
76+
- Reply via `gh api repos/{owner}/{repo}/pulls/{number}/comments/{id}/replies`
77+
- Push fixes
17578

176-
```
177-
## #{N}: {title} — SHIPPED
178-
179-
### Tasks
180-
| # | Task | Status |
181-
|---|---|---|
182-
| 1 | #{task_number} {title} | DONE |
183-
184-
### Quality
185-
| Check | Status |
186-
|---|---|
187-
| Typecheck | PASS |
188-
| Tests | PASS |
189-
| Lint | PASS |
190-
| Structure | PASS |
191-
| RGAA | PASS |
192-
| Security | SECURE |
193-
194-
### PR
195-
#{pr_number} — {pr_url} — Review: {APPROVED|PENDING}
196-
197-
### Reviews Addressed
198-
| Author | File | Comment | Action |
199-
|---|---|---|---|
200-
```
79+
Ask whether to keep watching for new reviews. Loop if yes.

0 commit comments

Comments
 (0)