refactor(atelier): split spec into spec-write and spec-review#795
Merged
Conversation
…view (analysis) spec bundled two concerns with nothing in common: authoring spec documents (main agent writes per templates) and analyzing specs against code (L1/L2/audit sub-agents + citation verification). The SKILL.md claimed '공통 도메인 지식' but its body (layer model, citation philosophy, common principles) was review-only, making the router dishonest for write. Split by concern: - spec-write: write/write-detail authoring (authoring.md) — DESIGN/concerns/flows hierarchy. Main agent writes; defers design decisions to interview. - spec-review: review / gap-detect / quality / annotate — L1/L2/audit citation-based spec<->code analysis. Keeps the existing infra. bare 'spec' skill name removed; both concerns get descriptive names, mirroring the earlier interview (dialogue) extraction. Cross-references updated: interview boundary table + brainstorm handoff (spec write -> spec-write), autopilot startup.md + gap-auditor.md (quality-criteria owner -> spec-review), README absorption map. agents/spec/* descriptions point to spec-review (the dir is kept; agents are invoked by name). No plugin.json change (skills auto-discovered). Stacked on #794 (interview skill). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
… router /simplify: spec-write/SKILL.md '공통 원칙' restated authoring.md's rules (저장 금지·related_paths·깊이 분리); reduced to the one routing-level principle (합의 후 형식화) + a pointer to authoring.md as canonical. authoring.md '진입 전 맥락' dropped the write precondition (interview-first), which duplicated the SKILL.md boundary/router note; kept only the write-detail DESIGN.md lookup, which is genuine authoring setup. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
kys0213
added a commit
that referenced
this pull request
Jun 13, 2026
…c authoring (#794) * feat(atelier): add interview skill (quick/grill/brainstorm) Pre-work intent-alignment meta-skill with three modes routed from a single entry point (mirrors the spec skill's intent->reference dispatch): - quick (default, inline): RG-CN-A frame (Restate/Goal/Constraints/Non-goals/Acceptance) -> 5-line mini-spec -> 'go' gate - grill (references/grill.md): interrogate an existing plan branch-by-branch down the decision tree, one question at a time with a recommended answer, exploring the codebase instead of asking when possible - brainstorm (references/brainstorm.md): context exploration -> clarifying questions -> 2-3 approaches with trade-offs -> section-by-section design validation (interface/module structure/dependency direction) with optional visualization -> design self-review -> approval hard gate -> handoff Shared hard gate: no implementation before explicit approval. Boundaries documented vs spec:design (state-based split), Plan Mode, autopilot. Design persistence stays on existing channels (Plan Mode plan file / spec:design document) to avoid duplicating spec's artifact responsibility. grill/brainstorm concepts adapted from obra/superpowers (MIT, (c) 2025 Jesse Vincent) brainstorming/grill-me skills, rewritten for atelier conventions with superpowers-ecosystem dependencies removed. Closes #713 (reinterpreted: standalone deep-interview plugin -> atelier skill, per marketplace consolidation) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(atelier): simplify grill reference to original instruction form The grill-me original derives its power from a single dense instruction, not a procedure. Drop the process steps, contradiction-exposure checklist, output template, and worked example; keep the core instruction (walk the design tree, resolve dependencies one-by-one, recommended answer per question, one at a time, explore codebase instead of asking) plus minimal atelier glue (termination + handoff). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(atelier): port brainstorm reference faithfully from superpowers original The previous thematic rewrite lost substantial original content: scope assessment/decomposition for multi-subsystem requests, the 'too simple to need a design' anti-pattern rationale, task-driven checklist discipline, the process-flow digraph with revise loops, multiple-choice preference, design-for-isolation boundary tests, and existing-codebase rules (targeted improvement, no unrelated refactoring). Replace it with a faithful Korean port preserving the original's full structure. Only four ecosystem bindings are substituted: - writing-plans -> Plan Mode handoff - browser visual companion -> AskUserQuestion(+preview) / markdown / ASCII / mermaid - checklist -> TaskCreate - docs/superpowers/specs/ -> project spec convention, with related_paths frontmatter so the atelier spec skill can consume the design doc (gap analysis / review) Restores the design-doc -> self-review -> user review gate steps (3 of 9 checklist items) dropped earlier; the spec-SRP objection was overzealous since spec owns analysis workflows, not document authorship. MIT attribution header added (close port = substantial portion). SKILL.md boundary table, references guide, and attribution section updated to match. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(atelier): make grill the default inline mode, drop quick scaffolding Restructure the interview skill so the skill body serves the post-invocation reader, not the should-I-invoke decision (that is the frontmatter description's job). - grill becomes the default inline behavior (absorbs references/grill.md, which is removed) - brainstorm stays as the only reference, loaded for from-scratch design - drop the quick/RG-CN-A mode: it was a #713 addition absent from the source skills and overlaps with grill's interrogate-to-shared-understanding - drop the design-first rationale (CLAUDE.md owns it) and the body auto-trigger / skip tables (the description drives invocation; repeating them in the body once loaded is redundant) - keep the responsibility-boundary table and source attribution SKILL.md is now ~40 lines; the validator's 50-line minimum is a non-blocking warning (main.go exits non-zero only on failures), so CI stays green. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(atelier): split design dialogue (interview) from spec authoring (spec write) spec:design bundled two concerns: the design *dialogue* (ping-pong + 6 perspectives + convergence) and the spec *document authoring* convention (DESIGN/concerns/flows templates). The dialogue overlapped with the new interview skill, leaving an ambiguous boundary. Resolve by concern: - interview owns the design dialogue (brainstorm: from-scratch, grill: challenge an existing plan) - spec owns document authoring: rename design/design-detail -> write/write-detail, reframe design-protocol.md -> authoring.md (depth criteria, output templates, related_paths, save rules) Remove the 6-perspective model (S/O/F/B/C/M) entirely: S/O/B duplicate CLAUDE.md SOLID and brainstorm's isolation/YAGNI lenses, F is covered by Fail Fast; concurrency/operability vary by goal and are added per-objective rather than as a fixed lens. The ping-pong loop and perspective-threshold convergence are dropped with it. brainstorm no longer defines its own doc format — it defers to spec's write convention and only persists a doc when a long-lived spec is needed (otherwise the Plan Mode plan file carries the design). Cross-references updated: interview boundary table, spec routing/description/references guide, handoff lines. design-protocol.md removed; no residual referrers (verified). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(atelier): split spec into spec-write and spec-review (#795) * chore(validate): drop obsolete spec convergence invariant, relabel design→write The spec design→write refactor (#794) intentionally removed the 6-perspective ping-pong convergence model, dropping the '3개 이상' token (design-detail convergence threshold). The extraction-invariants guard flagged it as lost load-bearing content, but the removal was deliberate per the design-dialogue/spec-authoring split — so retire that invariant. Also relabel the surviving spec output-structure invariants from spec/design·spec/design-detail to spec-write/write·spec-write/write-detail to match the renamed routes. All their tokens (## OCP 확장점, ## 핵심 로직, spec/concerns/, etc.) still resolve in spec-write/references/authoring.md. Fixes validate-ci failure on #794. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: 김용성 <kys0213@gim-yongseong-ui-MacBookPro.local> Co-authored-by: Claude <noreply@anthropic.com>
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
1 participant
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.
요약
spec스킬을spec-write(스펙 문서 작성) 와spec-review(spec↔code 분석) 두 관심사로 분리합니다.배경 — router 가 정직하지 못했다
specSKILL.md 는 "공통 도메인 지식"이라 주장했지만, 본문(L1/L2/audit 레이어 모델·인용 검증 철학·공통 원칙)이 전부 리뷰/분석 전용이라 write 에는 거짓이었습니다:작성(write)과 분석(review)은 활동·주체·인프라가 전부 다른 별개 관심사입니다. 앞서 설계 대화(interview)를 분리한 것과 같은 논리의 마지막 단계입니다.
분리 결과
spec이름 제거, 둘 다 서술적 이름 (interview 분리와 대칭)spec-review는 기존 분석 인프라(agents/spec/*, references 6개) 그대로 보존spec-write는 authoring.md + 라우팅교차 참조 갱신
spec write→spec-writestartup.md+gap-auditor.md: quality-criteria 소유자 →spec-reviewskills/spec/→spec-write·spec-reviewagents/spec/*description →spec-review(디렉터리는 유지 — 에이전트는 이름으로 호출)검증
skills/spec/·barespec skill참조 0gap-detector에이전트라 영향 없음🤖 Generated with Claude Code