Skip to content

Commit 623ce24

Browse files
alexizationalexization
authored
(#19) add core planning and parallel-agent skill pack
* docs: 코어 planning 병렬 agent 스킬 팩 추가 - issue-to-exec-plan, parallel-work-split, api-contract-sync 스킬 문서 추가 - skills/README.md에 추천 사용 순서와 canonical contract 기준 반영 - GRW-S02 완료 exec plan과 검증 기록 추가 * docs: 리뷰 반영으로 skill 검증 명령과 repo 예시 수정 - issue-to-exec-plan의 gh issue create 예시를 target repo placeholder로 일반화 - api-contract-sync의 TypeScript 검증 명령을 client tsconfig 기준으로 수정 - GRW-S02 완료 exec plan에 리뷰 follow-up 기록 추가
1 parent 2cb3cd9 commit 623ce24

5 files changed

Lines changed: 476 additions & 0 deletions

File tree

‎docs/exec-plans/completed/2026-03-26-grw-s02-core-planning-skill-pack.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# 2026-03-26-grw-s02-core-planning-skill-pack
2+
3+
- Issue ID: `GRW-S02`
4+
- GitHub Issue: `#18`
5+
- Status: `Completed`
6+
- Repository: `git-ranker-workflow`
7+
- Branch Name: `feat/grw-s02-core-planning-skill-pack`
8+
- Task Slug: `2026-03-26-grw-s02-core-planning-skill-pack`
9+
10+
## Problem
11+
12+
workflow 저장소에는 issue를 exec plan으로 고정하고, 병렬 agent ownership을 나누고, backend API 계약 변경을 client/workflow와 동기화하는 coordination skill이 아직 없다. 이 상태에서는 같은 종류의 작업을 시작할 때마다 입력, 산출물, 증거 규칙을 다시 설명해야 하고, 병렬 작업 충돌이나 계약 drift를 일관되게 막기 어렵다.
13+
14+
## Why Now
15+
16+
`GRB-01`, `GRW-03`, `GRW-04`, `GRC-01`까지 기준 문서와 계약 경로가 생겼다. 이제 `GRB-02`, `GRC-02`, `GRC-04`, `GRW-05` 이후 작업을 안정적으로 시작하려면 planning/coordination skill을 먼저 고정해야 한다.
17+
18+
## Scope
19+
20+
- `skills/issue-to-exec-plan/SKILL.md` 작성
21+
- `skills/parallel-work-split/SKILL.md` 작성
22+
- `skills/api-contract-sync/SKILL.md` 작성
23+
- 각 skill에 입력/출력 예시와 병렬 수행 시 금지 사항 추가
24+
- `skills/README.md`에 추천 사용 시점과 현재 skill registry 반영
25+
- `GRW-S02` 실행 기록 남기기
26+
27+
## Non-scope
28+
29+
- ranking harness execution skill 작성
30+
- batch triage skill 작성
31+
- backend/frontend 코드 생성 자동화 추가
32+
- workflow가 backend OpenAPI canonical source를 대체하도록 구조 변경
33+
34+
## Write Scope
35+
36+
- `skills/`
37+
- `docs/exec-plans/`
38+
39+
## Outputs
40+
41+
- `skills/issue-to-exec-plan/SKILL.md`
42+
- `skills/parallel-work-split/SKILL.md`
43+
- `skills/api-contract-sync/SKILL.md`
44+
- `skills/README.md`
45+
- `GRW-S02` 실행/완료 기록
46+
47+
## Working Decisions
48+
49+
- backend OpenAPI canonical source는 계속 `git-ranker/docs/openapi/openapi.json`으로 둔다.
50+
- `git-ranker-client`는 canonical spec의 consumer이며, generated type 또는 manual mirror만 관리한다.
51+
- `git-ranker-workflow`는 canonical spec을 복제해 소유하지 않고, sync 절차, evidence, 필요 시 파생 generated artifact만 관리한다.
52+
- `GRW-07` freshness check는 backend spec regeneration 책임과 workflow sync 책임을 분리하는 방향을 전제로 한다.
53+
54+
## Verification
55+
56+
- `find skills -maxdepth 2 -type f | sort`
57+
- 결과: `skills/api-contract-sync/SKILL.md`, `skills/issue-to-exec-plan/SKILL.md`, `skills/parallel-work-split/SKILL.md`가 registry 문서와 함께 기대 경로에 생성된 것을 확인했다.
58+
- `cat skills/issue-to-exec-plan/SKILL.md`
59+
- 결과: exec plan 생성 절차, required evidence, 병렬 수행 금지 사항, `GRC-04` 기준 example input/output이 포함된 것을 확인했다.
60+
- `cat skills/parallel-work-split/SKILL.md`
61+
- 결과: disjoint write set, cross-repo 분리, critical path 우선 규칙, ownership 표 예시가 포함된 것을 확인했다.
62+
- `cat skills/api-contract-sync/SKILL.md`
63+
- 결과: canonical backend contract를 `git-ranker/docs/openapi/openapi.json`으로 고정하고, workflow는 sync 절차/evidence만 관리한다는 역할 분리가 명시된 것을 확인했다.
64+
- `rg -n "Recommended Use|issue-to-exec-plan|parallel-work-split|api-contract-sync" skills/README.md skills/issue-to-exec-plan/SKILL.md skills/parallel-work-split/SKILL.md skills/api-contract-sync/SKILL.md`
65+
- 결과: skill index의 registry entry, 추천 사용 순서, 각 skill의 example/parallel 금지 사항 섹션이 모두 grep 결과에 포함되는 것을 확인했다.
66+
- sample issue를 exec plan으로 바꾸는 시뮬레이션 검토
67+
- 결과: `issue-to-exec-plan`의 `GRC-04` 예시가 issue metadata, scope/non-scope, verification까지 포함한 exec plan skeleton으로 충분히 변환 가능한 것을 확인했다.
68+
- contract-sync checklist가 backend canonical source 기준으로 동작하는지 문서 리뷰
69+
- 결과: `api-contract-sync` 예시가 backend canonical spec, client consumer, workflow review, no-op generated note까지 분리해 체크리스트를 만들 수 있음을 확인했다.
70+
- PR review follow-up
71+
- 결과: `issue-to-exec-plan`의 issue 생성 명령을 target repo placeholder로 일반화했고, `api-contract-sync`의 TypeScript 검증 명령을 `npx tsc --noEmit -p git-ranker-client/tsconfig.json`으로 바꿔 workflow 루트에서도 실제 client config를 검증하도록 수정했다.
72+
- `gh issue create --repo alexization/git-ranker-workflow ...`
73+
- 결과: `GRW-S02` GitHub issue `#18`을 생성했다.
74+
75+
## Evidence
76+
77+
문서 전용 Issue라 브라우저, 로그, 메트릭 artifact는 필수는 아니다. 대신 skill 문서 내용, 검증 명령 결과, backend canonical contract에 대한 역할 분리 결정을 이 실행 문서에 남긴다.
78+
79+
- GitHub Issue: `#18`
80+
- canonical backend contract: `git-ranker/docs/openapi/openapi.json`
81+
- workflow role: canonical spec 소유가 아니라 sync 절차와 evidence 관리
82+
83+
## Risks or Blockers
84+
85+
- `api-contract-sync`는 현재 workflow 내부에 tracked generated mirror가 없는 상태를 다뤄야 한다. 따라서 “현재는 no-op인 workflow generated update”와 “실제 drift”를 혼동하지 않게 문구를 정교하게 써야 한다.
86+
- `parallel-work-split`는 cross-repo worktree 규칙과 file ownership 규칙을 함께 다뤄야 하므로, 예시가 너무 추상적이면 재사용 가치가 떨어진다.
87+
- `GRW-07`에서 freshness check를 구현할 때 backend spec freshness와 workflow sync freshness를 하나의 fail 조건으로 뭉개지 않도록 주의해야 한다.
88+
89+
## Next Preconditions
90+
91+
- `GRB-02`, `GRC-02`, `GRC-04`, `GRW-05` 시작 시 새 coordination skill이 실제 진입 절차로 재사용 가능해야 한다.
92+
- `GRW-07`에서는 backend canonical spec freshness와 workflow sync freshness를 분리해 검사해야 한다.
93+
94+
## Docs Updated
95+
96+
- `skills/README.md`
97+
- `skills/issue-to-exec-plan/SKILL.md`
98+
- `skills/parallel-work-split/SKILL.md`
99+
- `skills/api-contract-sync/SKILL.md`
100+
- `docs/exec-plans/completed/2026-03-26-grw-s02-core-planning-skill-pack.md`
101+
102+
## Skill Consideration
103+
104+
이번 Issue 자체가 coordination skill pack을 추가하는 작업이다. 따라서 새 skill의 목적은 구현을 대신하는 것이 아니라, 반복되는 planning/splitting/sync 절차를 같은 입력/출력/증거 규칙으로 고정하는 데 있다. 특히 `api-contract-sync`는 canonical backend spec을 workflow로 복제해 소유하지 않는다는 현재 결정을 명시함으로써, 이후 `GRW-07`의 freshness guardrail 책임 경계를 분명하게 남긴다.

‎skills/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,10 +71,29 @@ skills/promql-logql-evidence/
7171

7272
현재 등록된 project skill은 아래와 같다.
7373

74+
- `issue-to-exec-plan` (`GRW-S02`): 새 Issue를 `docs/exec-plans/active/*.md` 실행 문서로 고정할 때 사용
75+
- `parallel-work-split` (`GRW-S02`): 여러 agent가 같은 Issue를 나눠 작업하기 전에 ownership과 write set을 분리할 때 사용
76+
- `api-contract-sync` (`GRW-S02`): backend OpenAPI 변경을 client 타입과 workflow 문서에 동기화할 때 사용
7477
- `red` (`GRW-S05`): failing test file 하나만 남기는 TDD red turn
7578
- `green` (`GRW-S05`): test 수정 없이 최소 구현으로 green을 만드는 턴
7679
- `refactor` (`GRW-S05`): green 유지 하에 구조를 정리하는 refactor 턴
7780

81+
## Recommended Use
82+
83+
coordination skill은 구현 전에 먼저 쓴다.
84+
85+
1. `issue-to-exec-plan`
86+
2. `parallel-work-split`
87+
3. `api-contract-sync` if backend contract changed
88+
89+
구현 skill은 그 다음 slice에 맞춰 쓴다.
90+
91+
1. `red`
92+
2. `green`
93+
3. `refactor`
94+
95+
`api-contract-sync`의 canonical backend contract는 `git-ranker/docs/openapi/openapi.json`이다. workflow는 canonical spec을 복제해 소유하지 않고, sync 절차와 evidence를 관리한다.
96+
7897
후속 작업에서 아래 skill pack을 순서대로 채운다.
7998

8099
- `GRW-S02`: `issue-to-exec-plan`, `parallel-work-split`, `api-contract-sync`

‎skills/api-contract-sync/SKILL.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
name: api-contract-sync
3+
description: Use this skill when a backend API contract change must be synchronized with client types and workflow source-of-truth updates.
4+
---
5+
6+
# API Contract Sync
7+
8+
## Purpose
9+
10+
backend API 계약 변경이 생겼을 때 canonical source, client consumer, workflow 문서/evidence를 같은 기준으로 맞춘다. 목적은 새 자동화를 발명하는 것이 아니라, drift를 같은 절차로 줄이는 것이다.
11+
12+
## Trigger
13+
14+
- `git-ranker/docs/openapi/openapi.json`이 바뀌었다.
15+
- `/api/v1/**` request, response, enum, auth, error envelope가 바뀌었다.
16+
- client 타입이나 validation에서 backend와 drift가 의심된다.
17+
- workflow source of truth 문서가 현재 계약과 맞지 않을 가능성이 있다.
18+
19+
## Inputs and Preconditions
20+
21+
- canonical backend contract는 `git-ranker/docs/openapi/openapi.json`이다.
22+
- backend 쪽 spec regeneration 책임은 `git-ranker`에 있고, workflow는 그 결과를 기준 입력으로 읽는다.
23+
- 관련 client consumer 파일을 확인한다.
24+
- `git-ranker-client/src/shared/types/api.ts`
25+
- `git-ranker-client/src/shared/lib/validations.ts`
26+
- 직접 계약을 소비하는 화면/서비스 파일
27+
- 관련 workflow 문서를 확인한다.
28+
- `docs/domain/ranking-read-flow.md`
29+
- `docs/domain/frontend-data-flows.md`
30+
- 계약을 직접 설명하는 exec plan 또는 source of truth 문서
31+
- 계약 의미가 애매하면 필드 의도나 backward compatibility를 사용자에게 질문한다.
32+
33+
## Output and Artifact Location
34+
35+
- 산출물은 세 가지 중 하나 또는 조합이다.
36+
- client 타입/validation 업데이트
37+
- workflow 문서 업데이트
38+
- exec plan/PR의 contract sync evidence 기록
39+
- 현재 workflow 저장소에는 tracked generated contract mirror가 없으므로, 기본 출력은 “canonical backend spec 확인 + consumer/doc sync 결과”다.
40+
- 향후 `docs/generated/` 아래 파생 artifact가 생기더라도 그것은 derived copy이며 canonical source가 아니다.
41+
42+
## Standard Commands
43+
44+
반복적으로 쓰는 기본 명령 예시:
45+
46+
```bash
47+
rg -n '"/api/v1/ranking"|EMERALD|AuthMeResponse' git-ranker/docs/openapi/openapi.json git-ranker-client/src/shared/types/api.ts git-ranker-client/src/shared/lib/validations.ts
48+
sed -n '1,200p' git-ranker/docs/openapi/README.md
49+
npx tsc --noEmit -p git-ranker-client/tsconfig.json
50+
rg -n "ranking|auth callback|tier" docs/domain docs/operations docs/exec-plans
51+
```
52+
53+
backend spec freshness 자체는 backend 저장소에서 확인한다. workflow는 canonical spec을 읽고 consumer/doc sync를 확인한다.
54+
55+
## Required Evidence
56+
57+
- canonical spec 경로를 무엇으로 봤는지
58+
- 어떤 endpoint/schema/enum이 바뀌었는지
59+
- 어떤 client file을 확인하거나 수정했는지
60+
- 어떤 workflow 문서를 확인하거나 수정했는지
61+
- 실행한 verification 명령과 결과
62+
- workflow 쪽 generated artifact가 없으면 그 사실과 no-op 사유
63+
64+
## Forbidden Shortcuts
65+
66+
- workflow 복제본이나 기억에 의존해 계약을 해석하지 않는다.
67+
- backend spec을 읽지 않고 client 타입만 먼저 수정하지 않는다.
68+
- `docs/generated/`를 canonical source처럼 다루지 않는다.
69+
- 관련 문서를 확인하지 않고 “문서 변경 없음”이라고 쓰지 않는다.
70+
- 계약 변경과 무관한 대규모 refactor를 sync 작업에 섞지 않는다.
71+
72+
## Parallel Ownership Rule
73+
74+
- backend contract delta 요약 owner, client consumer owner, workflow doc/evidence owner를 나눌 수 있다.
75+
- backend spec이 확정되기 전에는 client/doc owner가 추정치로 수정하지 않는다.
76+
- `git-ranker-client/src/shared/types/api.ts`와 같은 단일 계약 파일은 한 agent만 수정한다.
77+
- 같은 source of truth 문서는 한 agent만 수정하고, 나머지는 review input만 제공한다.
78+
79+
## Parallel Execution Don'ts
80+
81+
- stale spec을 기준으로 client/doc 작업을 병렬 시작하지 않는다.
82+
- backend spec regeneration과 client type 수정이 서로 다른 가정으로 동시에 진행되게 두지 않는다.
83+
- 계약 의미가 미정인데 각 agent가 필드 의미를 따로 정하게 두지 않는다.
84+
- workflow generated artifact가 없는데도 존재하는 것처럼 체크리스트를 작성하지 않는다.
85+
86+
## Example Input
87+
88+
- backend change:
89+
- `/api/v1/ranking`에 새 query param `size` 추가
90+
- `RankingUserInfo`에 `country` 필드 추가
91+
- changed canonical file:
92+
- `git-ranker/docs/openapi/openapi.json`
93+
94+
## Example Output
95+
96+
```md
97+
Contract sync checklist
98+
99+
- Canonical spec: `git-ranker/docs/openapi/openapi.json`
100+
- Client updates:
101+
- `git-ranker-client/src/shared/types/api.ts`
102+
- direct ranking consumer review
103+
- Workflow review:
104+
- `docs/domain/ranking-read-flow.md`
105+
- `docs/domain/frontend-data-flows.md`
106+
- Verification:
107+
- `npx tsc --noEmit -p git-ranker-client/tsconfig.json`
108+
- Note:
109+
- workflow `docs/generated/`에는 현재 tracked mirror가 없어 no-op
110+
```
111+
112+
## Handoff
113+
114+
sync 작업을 넘길 때는 아래를 함께 전달한다.
115+
116+
- canonical spec 경로와 변경 요약
117+
- client에서 영향 받는 파일 목록
118+
- workflow에서 영향 받는 문서 목록
119+
- “backend freshness”와 “workflow sync freshness” 책임 분리

‎skills/issue-to-exec-plan/SKILL.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
name: issue-to-exec-plan
3+
description: Use this skill when a roadmap item or GitHub issue must be turned into an actionable exec plan before implementation starts.
4+
---
5+
6+
# Issue To Exec Plan
7+
8+
## Purpose
9+
10+
새 Issue나 roadmap 항목을 `docs/exec-plans/active/*.md`의 실행 문서로 고정한다. 목적은 구현 아이디어를 늘리는 것이 아니라, 범위, 비범위, write scope, 검증, evidence, 다음 전제조건을 먼저 잠그는 것이다.
11+
12+
## Trigger
13+
14+
- 새 GitHub Issue를 시작한다.
15+
- `docs/product/work-item-catalog.md`의 항목을 실제 작업으로 착수한다.
16+
- 작업 대상이 여러 저장소나 여러 문서로 퍼질 수 있어 먼저 write scope를 좁혀야 한다.
17+
- 후속 agent에게 같은 범위를 전달할 기준 문서가 아직 없다.
18+
19+
## Inputs and Preconditions
20+
21+
- `AGENTS.md`, `PLANS.md`, `docs/operations/workflow-governance.md`를 먼저 확인한다.
22+
- 관련 `docs/product/*.md`, 완료된 exec plan, source of truth 문서를 읽는다.
23+
- 대상 Issue ID, 저장소, 권장 브랜치/slug, 왜 지금 필요한지 알고 있어야 한다.
24+
- 관련 GitHub Issue가 없으면 governance 규칙에 따라 먼저 만든다.
25+
- 요구사항이나 canonical source가 애매하면 exec plan을 쓰기 전에 사용자에게 질문한다.
26+
27+
## Output and Artifact Location
28+
29+
- 산출물은 `docs/exec-plans/active/YYYY-MM-DD-<issue-id-lower>-<slug>.md` 문서다.
30+
- 문서에는 최소한 아래를 남긴다.
31+
- Issue ID, GitHub Issue, Status, Repository, Branch Name, Task Slug
32+
- Problem, Why Now, Scope, Non-scope, Write Scope
33+
- Outputs, Verification, Evidence, Risks or Blockers
34+
- Next Preconditions, Docs Updated, Skill Consideration
35+
- 작업이 끝나면 `Completed`로 갱신하고 `docs/exec-plans/completed/`로 이동한다.
36+
37+
## Standard Commands
38+
39+
반복적으로 확인하는 기본 명령 예시:
40+
41+
```bash
42+
rg -n "GRW-S02|GRC-04|GRB-02" docs/product docs/exec-plans
43+
find docs/exec-plans/active docs/exec-plans/completed -maxdepth 1 -type f | sort
44+
gh issue create --repo <owner>/<target-repo> --title "[Task] <issue-id> ..."
45+
git checkout -b feat/grw-s02-core-planning-skill-pack
46+
```
47+
48+
명령 자체보다 중요한 것은 "어떤 문서를 읽고 어떤 범위를 고정했는지"를 exec plan에 남기는 것이다.
49+
50+
`gh issue create`의 `--repo`는 항상 대상 저장소와 맞아야 한다. 예를 들어 `GRW-*`는 `alexization/git-ranker-workflow`, `GRB-*`는 `alexization/git-ranker`, `GRC-*`는 `alexization/git-ranker-client`를 쓴다.
51+
52+
## Required Evidence
53+
54+
- 어떤 source of truth 문서를 읽었는지
55+
- 이 Issue의 scope와 non-scope를 어떻게 고정했는지
56+
- 허용 write scope
57+
- 예정된 verification 명령
58+
- 남아 있는 질문이나 blocker
59+
- 관련 GitHub Issue와 branch/slug
60+
61+
## Forbidden Shortcuts
62+
63+
- exec plan 없이 바로 코드나 문서를 수정하지 않는다.
64+
- roadmap 문장을 그대로 복사하고 write scope나 검증을 비워두지 않는다.
65+
- verification을 `문서 확인`, `테스트 실행`처럼 추상적으로 쓰지 않는다.
66+
- 선행조건이 불명확한데 `Ready` 또는 `In Progress`로 올리지 않는다.
67+
- 애매한 요구사항을 임의 해석해 plan 본문에 박지 않는다.
68+
69+
## Parallel Ownership Rule
70+
71+
- exec plan 파일 편집 ownership은 한 agent만 가진다.
72+
- 다른 agent가 관련 문서를 읽고 요약할 수는 있지만, plan 본문 최종 통합은 plan owner가 한다.
73+
- 동일 작업의 scope/non-scope를 여러 agent가 따로 정의하지 않는다.
74+
- plan owner가 고정한 write scope 없이 병렬 구현 작업을 시작하지 않는다.
75+
76+
## Parallel Execution Don'ts
77+
78+
- 같은 exec plan 파일을 여러 agent가 동시에 수정하지 않는다.
79+
- unanswered question이 남아 있는 상태에서 agent마다 다른 가정을 두고 병렬 탐색하지 않는다.
80+
- GitHub Issue 번호, 브랜치명, slug를 agent별로 다르게 기록하지 않는다.
81+
82+
## Example Input
83+
84+
- Issue: `GRC-04`
85+
- Goal: ranking read Playwright harness 도입
86+
- Relevant docs:
87+
- `docs/product/work-item-catalog.md`
88+
- `docs/domain/frontend-data-flows.md`
89+
- `docs/operations/frontend-runtime-reference.md`
90+
- `docs/exec-plans/completed/2026-03-25-grw-04-frontend-routes-data-flow-docs.md`
91+
92+
## Example Output
93+
94+
```md
95+
# 2026-03-26-grc-04-ranking-read-playwright-harness
96+
97+
- Issue ID: `GRC-04`
98+
- Status: `Ready`
99+
100+
## Scope
101+
- Playwright config 추가
102+
- ranking read spec 추가
103+
- artifact 규칙 연결
104+
105+
## Non-scope
106+
- 인증 포함 전체 여정 자동화
107+
- 디자인 변경
108+
109+
## Verification
110+
- `npm run playwright -- ranking-read`
111+
- trace/screenshot 생성 확인
112+
```
113+
114+
## Handoff
115+
116+
구현 단계로 넘길 때는 아래를 함께 전달한다.
117+
118+
- active exec plan 경로
119+
- 확정된 write scope
120+
- verification 명령
121+
- 남은 open question 또는 blocker

0 commit comments

Comments
 (0)