MAF-19914: docs: separate PRDs/specs/plans roles in skills#1
Merged
Conversation
2026-04-29 Hyeonki 가 결정한 세 디렉토리 역할 분리 (PRDs evergreen / specs dated snapshot / plans ordered task) 를 runes 의 skills 에 반영. AGENTS.md 신설 + brainstorming, writing-plans 두 skill 의 산출물 경로를 docs/superpowers/ 제거된 형태로 갱신. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Codifies a documentation role convention (PRDs/specs/plans) decided 2026-04-29 by adding a root AGENTS.md and updating two skills (brainstorming, writing-plans) so generated paths drop the superpowers/ prefix.
Changes:
- Add
AGENTS.mddocumenting the three doc directories, authoring principles, and background. - Update brainstorming skill paths from
docs/superpowers/specs/todocs/specs/. - Update writing-plans skill paths from
docs/superpowers/plans/todocs/plans/.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| AGENTS.md | New root file describing PRD/specs/plans convention and rationale. |
| skills/brainstorming/SKILL.md | Updates two spec save-path references to docs/specs/. |
| skills/brainstorming/spec-document-reviewer-prompt.md | Updates dispatch-after path to docs/specs/. |
| skills/writing-plans/SKILL.md | Updates two plan save-path references to docs/plans/. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
AGENTS.md 는 agent 가 따라야 할 evergreen rule 만 담는 자리이므로, 특정 사건/결정일 같은 dated context 를 본문에 포함하지 않는다. 사건 자체의 traceability 는 git log / PR description / Jira 가 진원. 이는 본 PR 의 메타 원칙 — "evergreen 문서 (PRD, AGENTS.md, rule 파일) 에 implementation snapshot 또는 dated incident 를 섞지 않는다" — 의 self-application. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Translate AGENTS.md to English and add a Language section establishing English as the default for all in-repo artifacts (source, docs, SKILL.md, commit messages, code comments, skill outputs). GitHub pull request bodies and inline review replies stay in Korean to match the team's review workflow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The English-only authoring policy is the author's individual operational decision rather than a settled repo-level convention, so do not codify it in AGENTS.md for now. The English text of AGENTS.md itself is kept unchanged; only the Language section is removed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a short Workflow section that names the PRD → spec → plan flow so a new operator can build the right mental model from AGENTS.md alone, and pin spec/plan filename dates to Asia/Seoul so the team agrees on which calendar day each dated file belongs to. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace "Claude Code skills" / "Claude" mentions in AGENTS.md with the broader "agent" / "agent skills" wording so the conventions apply to any AI agent that consumes these skills, not just Claude. The skills can be authored or invoked by other coding agents (Cursor, Aider, Continue, etc.) and the role separation rules are agent-agnostic. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…TS.md and brainstorming Both AGENTS.md and `skills/brainstorming/SKILL.md` describe the same dated spec file but with different naming patterns: the directory table uses `YYYY-MM-DD-<topic>.md`, while the brainstorming output instructions and AGENTS.md rule 4 used `YYYY-MM-DD-<topic>-design.md`. The two are the same file, so agents would have generated inconsistent filenames. Drop the `-design` suffix everywhere so the table, the rule, and the brainstorming output share one pattern. The `-design` qualifier was already implicit (a brainstorming output is a design spec by definition) and the reference layout in huginn PR #17 follows the same suffix-less convention. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hhk7734
requested changes
May 19, 2026
Member
잘못된 의도 같은데 수정해주세요 |
…ILL.md Consolidate the documentation role conventions into the brainstorming skill (the natural source-of-intent skill) and drop AGENTS.md so each piece of guidance lives next to the skill that needs it. Per team feedback on PR #1. - Delete AGENTS.md. - Add a Documentation Roles section to skills/brainstorming/SKILL.md with the PRD/spec/plan table, Asia/Seoul date convention, spec immutability, and PRD evergreen + human-curated policy. - Augment the Explore step so the skill scans docs/PRDs/ for an existing PRD before producing a spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Earlier rounds intentionally left these two example paths on the old docs/superpowers/plans/ convention as out-of-scope. The exclusion was the wrong call: example paths should follow the same naming pattern the rest of the codebase advertises, otherwise readers infer that the old convention is still valid. Update both example paths to docs/plans/YYYY-MM-DD-<name>.md so every plan path in the repository points at the same convention.
Contributor
Author
지적해주신 잘못된 분류 정정 진행했습니다.
|
Member
|
PRDs는 읽기만하고 생성하거나 업데이트하는 포인트가 없는 것 같네요 |
…ated spec Make the brainstorming skill write design content to two destinations with distinct semantics: a read-mostly PRD for long-lived intent (architecture, business logic, interface contracts) and a dated spec for the implementation snapshot that accumulates over time. Aligns the entry point with the evergreen-vs-dated separation the Documentation Roles table already advertises, and closes the gap noted in PR review — PRDs previously had no write path defined in any skill. - Documentation Roles table: PRD Author cell now states the skill proposes PRD changes for user approval (was "Human-curated" only). - Checklist item 6: names both destinations and the user-approval gate for PRD changes. - After the Design > Documentation: restructured into two destinations (PRD vs dated spec) with one-line guidance on what each holds and how it evolves. - Process Flow graphviz unchanged; "Write design doc" node still represents both writes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Author
PRD write 흐름을 brainstorming SKILL.md 에 추가했습니다 — 9421ddf.
PRD = human-curated 원칙은 유지하되, write 흐름이 명시적 user approval gate 로 정의됩니다. |
The previous commit added the PRD/spec split across three places (table, checklist item, Documentation section), repeating roughly the same guidance with growing verbosity. Compress the latter two sections so the Documentation Roles table remains the single source of detail and the other two are short pointers. - Author cell: drop redundant "this skill" / "changes" / "user". - Checklist item 6: keep both paths, drop split rationale (it now lives in the Documentation section only). - Documentation section: collapse the two long paragraphs into two one-line bullets and a one-line tail. Net effect: ~50% character reduction across the three edits of the prior commit, no loss of information available at the table.
hhk7734
previously approved these changes
May 19, 2026
…ntent categories
The previous compression dropped two units that did not survive elsewhere
in the skill:
- PRD anti-patterns ("no dated incidents or implementation snapshots
here") — this is the core message of the broader PR (the Round 0
motivation) and was not present in the Documentation Roles table.
- Spec content categories (decisions, alternatives, trade-offs) — gave
the dated spec its concrete shape; the table only says "implementation
snapshot".
Restore both as short clauses appended to the existing bullets. Net
char count of the Documentation section is 469 (vs 378 after the prior
compression and 700 before), so the section remains substantially
shorter than the original verbose form while keeping the operational
guidance complete.
Contributor
Author
|
brainstorming SKILL.md 의 PRD/spec split 가이드 본문이 verbose 해 압축한 뒤, 압축 과정에서 빠진 핵심 정보를 회복했습니다.
회복한 두 정보:
|
hhk7734
approved these changes
May 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
요약
2026-04-29 결정된 문서 역할 분리 컨벤션 (Hyeonki) —
docs/PRDs/evergreen /docs/specs/dated snapshot /docs/plans/ordered task — 을 runes 의 skills 에 반영합니다.변경 사항
수정
skills/brainstorming/SKILL.md— (1) 산출물 경로docs/superpowers/specs/...→docs/specs/..., (2) HARD-GATE 직후 새## Documentation Roles섹션 (PRD/spec/plan 역할 표 + Asia/Seoul timezone + spec immutability + PRD evergreen) 추가, (3) "Understanding the idea" 첫 bullet 에docs/PRDs/점검 지침 추가skills/brainstorming/spec-document-reviewer-prompt.md—docs/superpowers/specs/→docs/specs/(line 7)skills/writing-plans/SKILL.md—docs/superpowers/plans/...→docs/plans/...(line 18, 138)추가 수정 — example path 통일 (9969def)
초기 PR description 에서 "scope 밖" 으로 의도적 미수정 처리했던 두 example path 가 같은 저장소가 advertise 하는 컨벤션과 inconsistency 를 남기는 잘못된 분류였습니다. 정정:
skills/subagent-driven-development/SKILL.md:133→docs/plans/YYYY-MM-DD-feature-plan.mdskills/requesting-code-review/SKILL.md:60→docs/plans/YYYY-MM-DD-deployment-plan.md배경
컨벤션이 codify 되지 않으면 Claude 가 PRD 에 implementation snapshot (파일 경로, 함수 시그니처 등) 까지 적고, 코드와 어긋날 때 drift 를 "used to do A, now B" history 로 PRD 에 누적시키는 패턴이 발생 (2026-04-29 Odin repo 에서 실제 발생). 본 PR 은 runes 의 skills 가 새 컨벤션을 명시적으로 반영하여 Claude 가 자동으로 올바른 위치에 올바른 내용만 작성하도록 유도.
참고 reference: huginn PR #17 (moreh-dev/huginn#17) — 같은 컨벤션을 verification 도메인에 적용한 사례.
검증 결과
```
grep -n 'docs/specs/YYYY-MM-DD' skills/brainstorming/SKILL.md
41, 123 (2 hits)
grep -n 'docs/plans/YYYY-MM-DD' skills/writing-plans/SKILL.md
18 (1 hit)
grep -n 'docs/plans/' skills/writing-plans/SKILL.md
138 (1 hit)
grep -rn 'docs/superpowers/specs' skills/
0 줄
grep -rn 'docs/superpowers/plans' skills/
0 줄
```
brainstorming SKILL.md 의
## Documentation Roles섹션이 PRD/spec/plan 세 디렉토리의 역할을 codify.Test plan
## Documentation Roles섹션이 자동 로드되어 새 컨벤션을 인지하는지 확인🤖 Generated with Claude Code