Superpowers — Contributor Guidelines

If You Are an AI Agent

Stop. Read this section before doing anything.

This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like "This pull request is slop that's made of lies."

Your job is to protect your human partner from that outcome. Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human partner's reputation, and the PR will be closed anyway. That is not being helpful. That is being a tool of embarrassment.

Before you open a PR against this repo, you MUST:

1. Read the entire PR template at .github/PULL_REQUEST_TEMPLATE.md and fill in every section with real, specific answers. Not summaries. Not placeholders. (이 포크엔 그 파일이 없습니다 — upstream 에 PR 할 때만 해당합니다. 없으면 이 항목은 건너뛰고 2~5 는 그대로 지키세요.)
2. Search for existing PRs — open AND closed — that address the same problem. If duplicates exist, STOP and tell your human partner. Do not open another duplicate.
3. Verify this is a real problem. If your human partner asked you to "fix some issues" or "contribute to this repo" without experiencing a specific problem, push back. Ask them what broke, what failed, what the user experience was.
4. Confirm the change belongs in core. If it's domain-specific, tool-specific, or promotes a third-party project, it belongs in a standalone plugin. Tell your human partner.
5. Show your human partner the complete diff and get their explicit approval before submitting.

If any of these checks fail, do not open the PR. Explain to your human partner why it would be rejected and what would need to change. They will thank you for saving them the embarrassment.

Pull Request Requirements

Every PR must fully complete the PR template. No section may be left blank or filled with placeholder text. PRs that skip sections will be closed without review.

Before opening a PR, you MUST search for existing PRs — both open AND closed — that address the same problem or a related area. Reference what you found in the "Existing PRs" section. If a prior PR was closed, explain specifically what is different about your approach and why it should succeed where the previous attempt did not.

PRs that show no evidence of human involvement will be closed. A human must review the complete proposed diff before submission.

What We Will Not Accept

Third-party dependencies

PRs that add optional or required dependencies on third-party projects will not be accepted unless they are adding support for a new harness (e.g., a new IDE or CLI tool). Superpowers is a zero-dependency plugin by design. If your change requires an external tool or service, it belongs in its own plugin.

"Compliance" changes to skills

Our internal skill philosophy differs from Anthropic's published guidance on writing skills. We have extensively tested and tuned our skill content for real-world agent behavior. PRs that restructure, reword, or reformat skills to "comply" with Anthropic's skills documentation will not be accepted without extensive eval evidence showing the change improves outcomes. The bar for modifying behavior-shaping content is very high.

Project-specific or personal configuration

Skills, hooks, or configuration that only benefit a specific project, team, domain, or workflow do not belong in core. Publish these as a separate plugin.

Bulk or spray-and-pray PRs

Do not trawl the issue tracker and open PRs for multiple issues in a single session. Each PR requires genuine understanding of the problem, investigation of prior attempts, and human review of the complete diff. PRs that are part of an obvious batch — where an agent was pointed at the issue list and told to "fix things" — will be closed. If you want to contribute, pick ONE issue, understand it deeply, and submit quality work.

Speculative or theoretical fixes

Every PR must solve a real problem that someone actually experienced. "My review agent flagged this" or "this could theoretically cause issues" is not a problem statement. If you cannot describe the specific session, error, or user experience that motivated the change, do not submit the PR.

Domain-specific skills

Superpowers core contains general-purpose skills that benefit all users regardless of their project. Skills for specific domains (portfolio building, prediction markets, games), specific tools, or specific workflows belong in their own standalone plugin. Ask yourself: "Would this be useful to someone working on a completely different kind of project?" If not, publish it separately.

Fork-specific changes

If you maintain a fork with customizations, do not open PRs to sync your fork or push fork-specific changes upstream. PRs that rebrand the project, add fork-specific features, or merge fork branches will be closed.

Fabricated content

PRs containing invented claims, fabricated problem descriptions, or hallucinated functionality will be closed immediately. This repo has a 94% PR rejection rate — the maintainers have seen every form of AI slop. They will notice.

Bundled unrelated changes

PRs containing multiple unrelated changes will be closed. Split them into separate PRs.

New Harness Support

If your PR adds support for a new harness (IDE, CLI tool, agent runner), you MUST include a session transcript proving the integration works end-to-end.

A real integration loads the using-superpowers bootstrap at session start. The bootstrap is what causes skills to auto-trigger at the right moments. Without it, the skills are dead weight — present on disk but never invoked.

The acceptance test. Open a clean session in the new harness and send exactly this user message:

Let's make a react todo list

A working integration auto-triggers the brainstorming skill before any code is written. Paste the complete transcript in the PR.

These are not real integrations and will be closed:

• Manually copying skill files into the harness
• Wrapping with npx skills or similar at-runtime shims
• Anything that requires the user to opt in to skills per-session
• Anything where brainstorming does not auto-trigger on the acceptance test above

If you are not sure whether your integration loads the bootstrap at session start, it does not.

Skill Changes Require Evaluation

Skills are not prose — they are code that shapes agent behavior. If you modify skill content:

• Run adversarial pressure testing across multiple sessions
• Show before/after eval results in your PR
• Do not modify carefully-tuned content (Red Flags tables, rationalization lists, "human partner" language) without evidence the change is an improvement

Understand the Project Before Contributing

Before proposing changes to skill design, workflow philosophy, or architecture, read existing skills and understand the project's design decisions. Superpowers has its own tested philosophy about skill design, agent behavior shaping, and terminology (e.g., "your human partner" is deliberate, not interchangeable with "the user"). Changes that rewrite the project's voice or restructure its approach without understanding why it exists will be rejected.

General

• Read .github/PULL_REQUEST_TEMPLATE.md before submitting (upstream 에 PR 할 때. 이 포크엔 없음)
• One problem per PR
• Test on at least one harness and report results in the environment table
• Describe the problem you solved, not just what you changed

intent-locked-workflow 내부 skill 주의사항

위 섹션은 upstream Superpowers 기여 룰. 아래는 intent-locked-workflow 포크 내부 skill 설계 관련 메모.

⚠️ 본 CLAUDE.md 의 적용 범위 (꼭 읽고 시작)

이 파일은 intent-locked-workflow 플러그인 자체를 개발하는 contributor 용 메모입니다. 플러그인 사용자가 자기 프로젝트에서 intent-locked-workflow 를 쓸 때는 이 파일이 자동 로드되지 않습니다. 플러그인 cache 에 같이 들어가긴 하지만 사용자 환경의 CLAUDE.md 만 메인 시야에 들어와요. 그래서 여기에 룰을 박는다고 사용자 환경에 영향이 가는 게 아닙니다.

사용자 환경에 영향 줄 룰 / 안내 / 톤 / 워크플로우 / 안티 패턴 catch — 이런 것들은 모두 사용자 환경에 실제로 전달되는 파일 (skills/*/SKILL.md skill 본문 / commands/*.md 슬래시 명령 설명 / scripts/*.py helper / hooks/*.json) 에 직접 박아주세요. 본 CLAUDE.md 에는 contributor 결합 메모 (atomic patch 범위 / 회귀 catch grep / skill 간 의존관계) 와 우리 자체 개발 시 메인 시야의 자기 참조 (톤 룰 / 보고 양식 / 안전성 원칙) 정도만 박습니다.

미래 세션 catch 패턴

"사용자가 이 안내문 어렵다고 catch 했으니 CLAUDE.md 에 톤 룰 박자" 같은 흐름 전에 — 그 룰이 가야 할 진짜 위치가 어디인지 한 번 더 생각해주세요. 보통 skill body 또는 commands 입니다.

회귀 사례: v2.4 의 한국어 친화 톤 룰 (A-1~A-5) 을 CLAUDE.md 에만 박았는데 효과 미흡했음. 진짜 이유는 사용자 환경에 안 전달돼서. v2.4.2 에서 사용자 catch + 정정 (skill body + commands 의 실제 본문 정리로 전환).

generating-html ↔ change-history 결합

generating-html skill은 "doc이 still 초안 단계인지" 판정하는 신호로 ## 변경이력 footer가 비어 있는지 여부를 직접 사용한다 (skills/generating-html/SKILL.md line 27/60/167/197). 즉:

• footer entry 0건 → 초안 → generating-html 발동
• footer entry 1건 이상 → live doc → generating-html skip

이 결합 때문에 change-history skill의 "doc 최초 생성 시 자동으로 boilerplate entry를 logging하는 룰"을 제거하려면 반드시 generating-html의 발동/중단 신호도 동시에 교체해야 한다 (예: frontmatter status 플래그 / 첫 git commit 존재 여부 / 자동 발동 자체 폐지). 한쪽만 건드리면 다음 회귀가 발생한다:

• footer가 영구적으로 빈 채로 남음 → 이후 사용자가 부분 수정을 요청할 때마다 generating-html가 재발동 (의도와 반대)

요약: 이 두 skill의 룰 변경은 atomic하게 묶어 처리할 것.

writing-plans **Model**: 필드 ↔ subagent-driven 결합

writing-plans 의 task block **Model**: 필드 (v1.1.14+) 는 v2.0.0 이후 dispatch 에 쓰이지 않는다 — implementer 는 haiku 고정이고 (skills/subagent-driven/implementer-prompt.md:7 이 정본), 이 필드는 사람이 읽는 참고 메타데이터로만 남는다. 즉:

• writing-plans 의 평가 룰을 바꿔도 subagent-driven 의 dispatch 는 안 바뀐다 (고정값). 바꾸려면 implementer-prompt.md 를 고쳐야 한다
• 한쪽만 건드리면 다음 회귀 발생: plan 작성 시 의도한 모델과 실제 dispatch 모델 불일치

요약: 이 두 skill 의 **Model**: 룰 변경은 atomic 하게 묶어 처리할 것.

scripts/preflight.py ↔ 4 skill Pre-flight 결합

v1.1.14+ 에서 scripts/preflight.py 가 generating-html / code-pretty / executing-plans / subagent-driven 4 skill 의 Pre-flight 검사를 deterministic 코드로 통합. 즉:

• scripts/preflight.py 의 함수 시그니처 (반환값 형식 / exit code 룰) 변경 시 4 skill 본문의 bash one-liner 도 동시 수정
• helper 의 매개변수 추가 시 모든 caller 의 호출 라인 동기화 필요

요약: 이 helper 와 4 skill 의 Pre-flight 섹션 변경은 atomic 하게 묶어 처리할 것.

v1.1.15+ — human_reason 필드 + 사용자 게이트 결합

scripts/preflight.py 의 PreflightResult.human_reason 필드 추가 (v1.1.15+) 와 4 skill 의 user-gate boilerplate (FR-4) 는 결합되어 있다:

• helper 의 human_reason 필드 시그니처 변경 시 4 skill bash one-liner 의 result.human_reason 출력 표현식도 동시 수정
• user-gate boilerplate 의 AskUserQuestion choices 변경 시 4 skill 동시 적용 (한 군데만 누락 시 사용자 마찰 일관성 깨짐)

요약: helper schema + user-gate boilerplate 변경은 atomic 하게 묶어 처리할 것. 5 파일 (preflight.py + 4 skill SKILL.md) 동시 push.

TaskCreate 명칭 룰 (v1.1.15+, FR-6)

intent-locked-workflow 자체 skill 의 Checklist 본문에 박힌 task 명칭은 사용자 시야 (TaskCreate UI) 에 직접 노출됨. 다음 룰 적용:

• 사용자 친화 한국어 표현 사용 — 내부 용어 (Invoke ... skill, Gate #N, CH-id, verifying-spec, generating-html 등 영어 식별자) 미노출
• 본문의 다른 부분 (Process Flow, Detailed Step) 의 영어 식별자는 유지 — 메인 에이전트가 정확한 skill 호출에 필요
• upstream og- skill 들 (verbatim)* — 손대지 않음
• 변경이력 footer 의 entry tag ([요구사항-수정] 등) — schema 매직 키워드라 유지

신규 skill 작성 시도 본 룰 따를 것. 회귀 시 grep -nE "Invoke .* skill|Gate #|CH-[0-9]" <skill 본문 Checklist> 로 catch.

auto-flow ↔ 기존 4 skill mirror 결합 (v1.1.17+)

auto-flow 4 신규 skill (skills/auto-{brainstorming,tech-design,writing-plans,executing-plans}/) 은 기존 4 skill 의 핵심 로직을 mirror 한 패턴 (og-* 와 동일). 다음 룰 적용:

• 기존 4 skill body 변경 0 — auto-* 본문은 self-contained mirror. 본 4 skill 어떤 라인도 손대지 않음. 회귀 catch: git diff HEAD~1 HEAD -- skills/{brainstorming,tech-design,writing-plans,executing-plans}/SKILL.md empty 보장.
• Gate #14 (실행 모드 선택) override 명시 — v1.1.12+ "자동승인 절대 X" 룰을 auto-executing-plans 가 명시 override. 일반 /executing-plans 영향 0 (게이트 그대로). auto-* 명시적 invoke 시에만 작동.
• generating-html fire-and-forget dispatch (v2.3.2+, v1.1.17 D9 amend 반전) — auto-brainstorming Step 4.5 / auto-tech-design Step 4.5 / auto-writing-plans Step 4.6 에서 run_in_background: true 로 dispatch. 메인 latency 거의 0 + 사용자가 transition notice 시점에 .html 검토 가능 (Type "stop" abort). auto-executing-plans 는 제외 (코드 실행 단계 — 의미 없음). 동기 호출 (sync wait) 은 여전히 금지. 회귀 catch: 3 skill 본문에 Step 4.5\|Step 4.6 + run_in_background: true 매치 필수.
• AskUserQuestion 호출 부재 — auto-* 본문 어디에도 AskUserQuestion 호출 X. clarifying Q 는 메인 turn 의 일반 prose 질의로 처리.
• Visual Companion / 카테고리 미니질문 / question plan 동의 등 PRD-mode 분기 부재 — Socratic only (D3).

요약: auto-* 추가 / 변경은 atomic 으로 묶어 처리. 기존 4 skill 변경 + auto-* 변경 같이 commit X (분리 release).

implementer-prompt + reorder-prompt + plan_byte_check 결합 (v2.0.0+)

v2.0.0 메이저에서 subagent dispatch 패턴이 LLM transcription → byte-copy + reorder 3-stage 분담 으로 근본 변경. 다음 4 파일은 atomic 변경 규칙 적용:

1. skills/subagent-driven/implementer-prompt.md — STRICT BYTE-COPY 룰 + haiku 고정 + Status enum BLOCKED
2. skills/subagent-driven/reorder-prompt.md — Status NEEDS_USER 형식 + sonnet 고정 + silent overwrite 차단
3. scripts/plan_byte_check.py — **원본** 블록 byte-equal 검증 helper (writing-plans + auto-writing-plans 의 Self-Review)
4. skills/subagent-driven/SKILL.md — Per-wave Sequence W-2 의 Stage 1/2/3 분기

회귀 패턴 (한쪽만 변경 시)

Test fixture

skills/subagent-driven/tests/H11-user-edit-reorder/README.md — 사용자 mid-flight 수정 시뮬레이션 + reorder dispatch 발화 검증.

영향 범위

• byte-copy + reorder 는 subagent 모드에만 적용 (subagent-driven-development + auto-executing-plans).
• 일반 /executing-plans (executing-plans inline) 영향 0 — 사용자 LLM 자율 보정 선호 케이스 보존.
• og-* skill 영향 0 — upstream mirror 보존.

요약: 4 파일 변경은 묶어서 처리. 분리 release X.

writing-plans + auto-writing-plans same-file 묶음 룰 결합 (v2.0.1+)

D1 (3 조건 AND — 같은 파일 / test 경계 X / mechanical) 룰 은 두 skill 본문에 동일하게 박힘. 한쪽만 수정 시 회귀.

회귀 catch

• writing-plans 의 룰 본문 / Self-Review 5번 항목 ↔ auto-writing-plans 의 Step 2 본문 룰 / Step 2 끝 자체 검토 동기화
• grep "Same-file mechanical 묶음 룰 (v2.0.1+)" → 양 skill 모두 1 매치

영향 범위

• subagent 모드 plan 작성 흐름만 영향 — executing-plans (inline) 영향 0
• og-* skill 영향 0
• v2.0.0 byte-copy 룰 (multi-step 정합성 D3 가정) 와 결합 — 가정 깨지면 BLOCKED → reorder dispatch

Test fixture

skills/subagent-driven/tests/H12-same-file-merge/README.md — 같은 파일 4 mechanical 변경 plan → 1 task multi-step 묶음 검증 (positive + negative).

요약: 2 skill + fixture + CLAUDE.md 변경은 묶어서 처리.

8 skill AskUserQuestion 강제 룰 결합 (v2.0.3+)

v2.0.3+ 에서 4 intent-locked-workflow 신규 skill + 4 auto-* 변형 skill 의 사용자 질문 시 AskUserQuestion 도구 호출 강제. 8 skill body 의 "사용자 질문 룰 (v2.0.3+)" boilerplate 가 동기. 변경 시 atomic patch.

회귀 패턴 (한 곳만 누락 시)

영향 범위

• 8 skill body 변경. og-* / subagent-driven / 보조 skill 영향 0
• AskUserQuestion 도구 schema 자체 변경 X (호출 빈도만 ↑)
• Notification.elicitation_dialog 매처 + repeat-alert.sh — 변경 X (기존 인프라 활용)

Other / 모호 응답 처리 룰 결합 (v2.1.1+)

v2.1.1+ 에서 5곳 (4 skill + 1 command) 에 "Other / 모호 응답 처리" boilerplate 추가. AskUserQuestion 묶음 응답 중 사용자가 "Other" 자유 응답 또는 "모르겠음 / 이해 안 됨" 류 답변 시 → 그 질문만 단독 재호출 + prose 설명 추가. 자동 진행 X.

적용 5곳

• skills/brainstorming/SKILL.md
• skills/tech-design/SKILL.md
• skills/writing-plans/SKILL.md
• skills/auto-brainstorming/SKILL.md
• commands/fast-tasks.md

회귀 패턴

영향 범위

• 5곳 본문 변경. 다른 skill / og-* / auto-* (auto-brainstorming 외) 영향 0
• AskUserQuestion 도구 schema 변경 X (호출 패턴만 추가)
• Notification.elicitation_dialog 매처 / repeat-alert.sh — 변경 X

Regression catch grep

grep -c "Other / 모호 응답 처리 (v2.1.1+)" \
  skills/brainstorming/SKILL.md \
  skills/tech-design/SKILL.md \
  skills/writing-plans/SKILL.md \
  skills/auto-brainstorming/SKILL.md \
  commands/fast-tasks.md
# expected: 각 1 (5곳 모두 박혀 있어야 함)

요약: 5 파일 + CLAUDE.md 결합 메모 변경은 묶어서 처리. 7+ 파일 atomic patch.

위 "8 skill body + CLAUDE.md" 요약은 v2.0.3 섹션 것이다 (아래 섹션이 끼어들면서 소속이 흐려졌다).

generating-html .html companion 결합 (v2.2.0 → v2.2.2+)

v2.2.0: generating-html 가 두 subagent 병렬 dispatch (A .md format-only + B .html 시각화). v2.2.1+: A 제거 + B fire-and-forget — 메인 latency 거의 0 + 비용 절반. 신규 /sync-html slash command + change-propagation 자동 호출 + 디바운스 3초 + silent log.

AI 흐름 영향 0 (v2.2.0 답습 — 모든 skill .md 만 읽음).

다음 5 파일 결합 변경 atomic patch 룰 (v2.2.1+):

1. skills/generating-html/SKILL.md — Procedure Step 2 (병렬 두 dispatch → 단일 fire-and-forget) + Step 3 (A+B reconcile 제거 → 즉시 return + silent log) + Anti-Patterns 갱신
2. skills/generating-html/html-companion-prompt.md — Subagent B prompt 그대로 보존 (v2.2.0 룰)
3. skills/change-propagation/SKILL.md — Acceptance 5번 + Related Skills 끝에 /sync-html 라인 추가
4. commands/sync-html.md — 신규 slash command (fire-and-forget B dispatch 명시 호출)
5. CLAUDE.md — 본 섹션

.gitignore 변경 X (v2.2.0 의 docs/features/**/*.html 그대로 + .intent-locked/html-regen.log 는 기존 .intent-locked/ glob 흡수).

회귀 패턴 (안전성 손상 시)

영향 범위

• generating-html Procedure + change-propagation Acceptance + 신규 /sync-html command 만 영향
• code-pretty / 4 워크플로 skill (brainstorming/tech-design/writing-plans/executing-plans) / change-history / auto-* / og-* 영향 0
• AI 흐름 모든 skill .md 만 읽음 (영향 0 보장)
• .html 은 사람 전용 derived view, gitignored
• silent log (.intent-locked/html-regen.log) — gitignored, debug 용

Regression catch grep

# Anti-Pattern: 외부 CDN / .html 의존성
grep -nE "https?://.*\.(css|js)|read_file.*\.html|Read.*\.html" \
  skills/generating-html/SKILL.md skills/generating-html/html-companion-prompt.md
# expected: 0 (Anti-Pattern catch 라인만 허용)

# Anti-Pattern: 다른 skill 본문에 .html 참조
grep -rn "\.html" \
  skills/{brainstorming,tech-design,writing-plans,executing-plans,og-*}/SKILL.md   # auto-* 제외 — v2.3.2+ 는 .html dispatch 가 필수라 매치가 나는 게 정상
# expected: 0 (.html 흐름은 generating-html 전용)

# v2.2.1+ Anti-Pattern: 메인이 결과 대기 (fire-and-forget 위반)
grep -nE "await.*Task|sync.*dispatch.*\.html" skills/generating-html/SKILL.md
# expected: 0

# v2.2.1+ Anti-Pattern: A (.md format-only) 부활
grep -nE "format-only pass on .*\.md|Subagent A" skills/generating-html/SKILL.md
# expected: 0

# v2.2.1+ change-propagation 자동 호출 보장
grep -c "/sync-html" skills/change-propagation/SKILL.md
# expected: ≥ 1

요약: 5 파일 (generating-html/SKILL.md + html-companion-prompt.md 보존 + change-propagation/SKILL.md + commands/sync-html.md + CLAUDE.md) + H17 patch + H18 신규 + 2 manifest 변경은 atomic patch.

generating-html 디자인 톤 자유 + 인터랙션 허용 (v2.2.4+)

v2.2.4+ 에서 skills/generating-html/html-companion-prompt.md 본문 재작성 — "사무 / 회의록 / 보고서 톤 금지" 명시 + 톤 inspiration 6종 (docs portal / dashboard / editorial / playful / brutalist / experimental) 매 호출 자유 선택 + 인터랙션 허용 (기존 "정적 페이지만" 룰 해제). 적극 시각 요소 (hero / glassmorphism / aurora bg / card grid / animated typography) + 인터랙션 (<details> / tab / sticky TOC / copy 버튼 / smooth scroll / scroll-spy) 명시.

핵심: 고정 톤 없음, 매번 다르게 = variety as feature.

보존 룰: self-contained (inline only) / 의미 1:1 / offline 렌더 / 헤더·코드 블록 count 검증. AI 흐름 / skill schema / fire-and-forget 모드 변경 0.

회귀 catch grep:

grep -c "Wow first\|variety = feature\|사무 / 회의록 / 보고서 톤" skills/generating-html/html-companion-prompt.md
# expected: ≥ 3

요약: html-companion-prompt.md 만 변경. atomic patch 1 파일 + CLAUDE.md 결합 메모 + 2 manifest bump.

generating-html Visual heuristics 적극 시각화 (v2.2.3+)

v2.2.3+ 에서 skills/generating-html/html-companion-prompt.md 의 Visual heuristics 룰 강화 — 보수적 (typography + color) → 적극 시각화 (비교 카드 / 콘셉트 도식 / 위험 카테고리 색깔 / stepper / 체크박스). .md 본문 패턴 ↔ .html 시각 표현 매핑 12 항목 표 + Anti-Patterns "typography + color 만 = 회귀" 명시.

영향: html-companion-prompt.md 본문만. AI 흐름 + skill schema / 발동 boundary / fire-and-forget 모드 모두 변경 X.

회귀 catch grep:

grep -c "적극 시각화 v2.2.3" skills/generating-html/html-companion-prompt.md
# expected: ≥ 1

요약: html-companion-prompt.md 만 변경. atomic patch 1 파일 + CLAUDE.md 결합 메모 + 2 manifest bump.

generating-html naming 일관성 결합 (v2.2.2+)

v2.2.2+ 에서 docs-pretty → generating-html skill 명칭 + /regen-html → /sync-html slash command 명칭 일괄 교체. 다음 룰 atomic patch:

• 5 항목 atomic — skill 디렉토리 rename + slash command rename + 13 파일 단어 swap + CLAUDE.md 결합 메모 + manifest 항목
• 단어 grep 검증 — 픽스처(tests/)는 옛 단어를 일부러 보존하므로 통째로 제외한다. --exclude-dir=og-* 는 디렉터리만 걸러 commands/og-*.md 파일을 못 거르므로 이름을 하나씩 적는다:

grep -rn "docs-pretty\|regen-html" skills/ commands/ CLAUDE.md README.md \
  --exclude-dir=og-brainstorming --exclude-dir=og-writing-plans \
  --exclude-dir=og-executing-plans --exclude-dir=tests
# expected: CLAUDE.md 3건만 (이 규칙 문단 자신 — 금지어를 이름으로 부르는 곳)
# 그 외 파일이 한 줄이라도 나오면 회귀다

• Acceptance 5번 자동→안내 — change-propagation 마지막 단계의 /sync-html 자동 호출 → 사용자 안내로 완화 (auto-fire X). 사용자가 명시 호출
• commands/regen-html.md 삭제 — old slash command 제거 (sync-html.md 신규 생성으로 대체)

AskUserQuestion 도구 우선 (v2.3.5+)

메인 에이전트가 사용자에게 결정 / 선택 / 동의 를 요청하는 모든 경우 → AskUserQuestion 도구 호출 default. skill body 외 ad-hoc 결정에도 동일 적용.

적용 대상

• 모든 skill body 안 게이트 (기존 v2.0.3+ 8 skill boilerplate)
• 메인 turn 의 ad-hoc 결정 요청 (skill body 무관)
• v2.3.5+ execute-plan 룰 1 (critical 7 케이스) 재질문
• 사용자가 모호 응답 시 재질문 (v2.1.1+ Other 룰)
• 모드 선택 게이트 진입 시점
• BLOCKED → self-correct / reorder 도 실패 시 사용자 개입

prose 예외 (좁게)

• 자유 텍스트 / 긴 응답 요구 (open brainstorming question 등)
• 사용자 응답 직후 확인용 단순 ack (단 AskUserQuestion yes/no 권장)
• 상태 보고 / 진행 알림 (질문 형식 아님)

알람 fire 보장

AskUserQuestion 호출 → Notification.elicitation_dialog 발화 → ~/.claude/settings.json 매처 → repeat-alert.sh fire. 사용자 백그라운드 작업 시 OS 알람 catch → 응답 흐름 보존.

prose 질문은 알람 fire X — 사용자 attention 손실 위험.

회귀 catch grep:

grep -c "AskUserQuestion 도구 우선 (v2.3.5+)" CLAUDE.md
# expected: ≥ 1

execute-plan critical/non-critical + AskUserQuestion 강제 결합 (v2.3.5+)

v2.3.5+ 에서 skills/executing-plans/SKILL.md + skills/subagent-driven/SKILL.md + CLAUDE.md 3 파일 atomic patch. 한쪽만 변경 시 inline vs subagent 모드 동작 불일치 + 글로벌 vs skill body 룰 불일치.

회귀 패턴 (한쪽만 변경 시)

영향 범위

• 3 파일 atomic patch (위 표). 다른 skill / commands / scripts 영향 0
• v1.1.12+ 자동승인 X / v2.0.0+ byte-copy reorder / v2.0.1+ same-file 묶음 / v2.0.3+ 8 skill boilerplate / v2.1.1+ Other 룰 — 모두 그대로
• 알람 시스템 (repeat-alert.sh 4-layer) — fire 빈도만 정상화 (변경 X)
• og-* / auto-* — Socratic only 룰 보존 (auto-* 는 본 룰 명시 예외 — Socratic prose default 유지)
• writing-plans **Model**: 필드 — 룰 2 의 dispatch model 결정 근거 (변경 X)
• scripts/preflight.py / scripts/plan_byte_check.py — 실행 단계 룰만이라 영향 0

Regression catch grep

grep -c "Critical / Non-critical 판정 룰 (v2.3.5+)" \
  skills/executing-plans/SKILL.md skills/subagent-driven/SKILL.md
# expected: 각 1

grep -c "사용자 질문 = AskUserQuestion 도구 (v2.3.5+)" \
  skills/executing-plans/SKILL.md skills/subagent-driven/SKILL.md
# expected: 각 1

grep -nE "병렬.*해도.*될까|묶을까|다음 task.*진입할까" \
  skills/executing-plans/SKILL.md skills/subagent-driven/SKILL.md
# expected: 0 (Anti-Pattern catch 라인만 허용)

grep -nE "이렇게.*할까요\?|어느.*쪽.*인가요\?" \
  skills/executing-plans/SKILL.md skills/subagent-driven/SKILL.md
# expected: 0 (Anti-Pattern catch 라인만 허용)

요약: 3 파일 (executing-plans/SKILL.md + subagent-driven/SKILL.md + CLAUDE.md) atomic patch. 5+ 파일 동시 push (3 + 2 manifest + 백로그 mv).

껍데기 워크플로우 명령 8개 제거 → 스킬 단일화 (v0.9.0+)

v0.9.0 에서 브레인스토밍~실행 워크플로우의 "얇은 명령 wrapper" 8개를 제거하고 스킬 단일 진입으로 전환. 원조 superpowers 철학(스킬 중심)에 정렬. 근거: 스킬이 이미 슬래시 호출 + 자동 발동 둘 다 하므로 wrapper 명령은 기능상 불필요 (유일한 값은 /intent-locked-workflow:이름 접두사 표시뿐).

제거된 8 명령 → 대체 스킬 슬래시

유지 명령 (일부러 명령 — 자동 발동 차단 / 원본 접근 / 유틸)

• 빌더 3 (list-skills / new-skill / remove-skill) — 자동 발동 시 스킬 생성·삭제 사고 방지 (META-BUILDER 룰)
• og-* 3 (og-brainstorm / og-write-plan / og-execute-plan) — upstream 원본 명시 접근
• 유틸: fast-tasks (짝 스킬 없음) / api-test / sync-html / pretty-md / audit-*

참조 일괄 치환 + 미러 보존

• README + CLAUDE.md + skills//SKILL.md + 남은 commands/.md 에서 삭제된 6개 슬래시(/brainstorm /write-plan /execute-plan /auto-brainstorm 등)를 스킬 이름으로 일괄 치환. /tech-design /auto-tech-design 는 스킬 이름이 같아 무변경.
• og-* 스킬 3개 본문 변경 0 (미러 룰 보존 — 짝 슬래시 없어 no-op).
• docs/features(변경이력) · RELEASE-NOTES.md(upstream 과거)는 미변경 (역사 보존). SETUP-WSL.md 스모크 테스트만 /brainstorming 으로 갱신.

회귀 catch grep

# CLAUDE.md 는 제외 — 본 메모가 삭제된 명령 이름을 표로 문서화하므로 매치됨 (정상)
grep -rE "/(brainstorm|write-plan|execute-plan|auto-brainstorm|auto-write-plan|auto-execute-plan)\b" \
  README.md SETUP-WSL.md skills/*/SKILL.md commands/*.md
# expected: 0 (스킬 이름 /brainstorming, /writing-plans 등만 존재)

ls commands/*.md | wc -l   # expected: 12 (20 → 12, 8 제거)

요약: 8 명령 삭제 + 참조 치환 + SETUP-WSL 1곳 + CLAUDE.md 메모 + 2 manifest bump = atomic patch. og-* 미러 보존.

한국어 친화 안내 톤 (v2.4+)

intent-locked-workflow 의 사용자 노출 안내문 (메인이 사용자에게 직접 보여주는 모든 문구) 은 다음 룰을 따른다.

A-1: 짧은 한국어 문장

• 한 문장에 정보 1~2개. 한 문단은 4 문장 이하.
• 영어 식별자는 꼭 필요할 때만 사용하고, 처음 등장 시 한국어 설명을 함께 적는다.

A-2: 메모 / 슬래시 / 콜론 다발 금지

• 사용자에게 보고할 때는 완전 문장으로 쓴다. →, ✅ 같은 마커는 진행 노트 한 줄 안에서만 허용.
• 콜론 다발 (결과: X / 다음: Y) 보다 풀어쓰기를 우선.

A-3: 한국어-영어 mix 최소

• 사용자 시야에 보이는 표현은 한국어 우선.
• 시스템 용어도 가능한 한 한국어로 풀어쓴다:
  • fire-and-forget → 백그라운드 호출
  • dispatch → 호출
  • byte-copy → 원본 그대로 보존
  • wave-parallel → 여러 작업 동시 진행
  • override → 자동 통과 또는 덮어쓰기 (맥락 따라)
  • subagent → 보조 에이전트
  • Anti-Pattern → 안티 패턴 또는 금지 패턴
  • Gate #N → 승인 게이트 (번호 자체가 사용자에게 의미 없으면 번호 생략)
• 도구 / 함수 / 파일 이름 (AskUserQuestion, parse_interrupt, plan_byte_check 등) 은 영어 그대로 유지.
• 단순 git 용어 (commit, push, merge, tag) 도 영어 그대로 유지.

A-4: 사용자 친화 보고

• 무엇을 했는지 (1~2 문장) + 왜 그랬는지 (필요 시 1 문장) + 다음 단계 (1 문장).
• 그 외 세부는 사용자가 자세히 묻기 전까지 생략.

A-5: 적용 영역 구분 (중요)

Before / After 예시

❌ Before (영어-한국어 mix + 메모 패턴):

✅ fire-and-forget dispatch 완료. byte-copy 룰 보존. → 다음 단계 진행.

✅ After (한국어 친화):

백그라운드 호출이 끝났습니다. 원본 보존 룰을 그대로 따랐고, 다음 단계로 넘어갑니다.

회귀 catch grep:

grep -c "한국어 친화 안내 톤 (v2.4+)" CLAUDE.md
# expected: ≥ 1

비동기 .html 신뢰성 룰 (v2.4+)

generating-html 백그라운드 호출이 처음 .md 생성 시 가끔 실패하던 회귀를 해결한 4 룰입니다.

• B-1 dispatch 결과 verify: 호출 직후 메인이 id 를 받았는지 확인하고, 시간 경과 후 .html 파일 존재를 확인.
• B-2 race condition 해결: dispatch 후 5초 delay 를 두고 그 다음 change-history footer 를 추가. background subagent 가 footer 0건 시점에 .md 를 읽도록 보장.
• B-3 silent log monitor: .intent-locked/html-regen.log 에 호출 / 성공 / 실패 entry 를 자동 append. /sync-html --check 으로 사용자 조회 가능.
• B-4 메인 응답에 dispatch 결과 명시: transition notice 시점에 "백그라운드 호출 완료 (N KB)" 또는 "실패 — 사용자가 /sync-html 으로 재시도 필요" 를 함께 알림.

자동 retry 는 도입하지 않습니다 (사용자 의도 외 비용 누적 위험). 사용자가 명시 호출 (/sync-html) 으로 재시도. 자동 retry 는 v2.4.x 후속 후보.

회귀 catch grep:

grep -c "5초 delay" skills/auto-brainstorming/SKILL.md skills/auto-tech-design/SKILL.md skills/auto-writing-plans/SKILL.md
# expected: 각 ≥ 1

grep -c "silent log monitor (v2.4+)" skills/generating-html/SKILL.md
# expected: ≥ 1

요약: v2.4 메이저 — A 광범위 (10+ skill + 10+ commands + README + CLAUDE.md) + B 4 룰 (generating-html + auto-* 3 race delay + /sync-html --check). atomic 처리.

--no-ask 플래그 ↔ 8 skill body 결합 (v2.5+)

--no-ask 플래그는 8 skill body 의 분기 sub-section 으로 구현. 사용자가 슬래시 명령에 --no-ask 토큰 명시 시에만 진입. 메인 자체 판단 활성화 X.

적용 범위 (8 skill)

• anchor 본격 4 (brain / design / write / auto-brain): "사용자 질문 룰" 섹션 직후 sub-section
• anchor 짧은 reference 4 (executing / auto-design / auto-write / auto-execute): body 끝 sub-section
• og-* / fast-tasks — 비적용 (회귀 catch grep 으로 보장)

핵심 룰

• 도구 호출 0 보장 (AskUserQuestion 흐름 전 구간 호출 X)
• 게이트 자체는 살아 있음 (질문은 그대로, 도구만 우회)
• skill 진입 시 1회 boilerplate prose (ℹ️ --no-ask 모드 진입 ...)
• 위험 명령 진입 직전 prose 보강 (⚠️ 위험 명령 진입 — 응답 기다림)
• auto-* 4 의 내부 escalation 경로 (BLOCKED 자가복구 / critical 7 재질문 / Other 모호 응답) 도 도구 호출 0 보장

회귀 catch grep (release 직전 메인 dogfood)

grep -c "--no-ask 플래그 (v2.5+)" \
  skills/brainstorming/SKILL.md \
  skills/tech-design/SKILL.md \
  skills/writing-plans/SKILL.md \
  skills/executing-plans/SKILL.md \
  skills/auto-brainstorming/SKILL.md \
  skills/auto-tech-design/SKILL.md \
  skills/auto-writing-plans/SKILL.md \
  skills/auto-executing-plans/SKILL.md
# expected: 각 ≥ 1

grep -l "--no-ask" \
  skills/og-brainstorming/SKILL.md \
  skills/og-writing-plans/SKILL.md \
  skills/og-executing-plans/SKILL.md \
  commands/fast-tasks.md 2>/dev/null
# expected: empty

요약: 8 skill body 분기 + 8 commands 안내 + CLAUDE.md 결합 메모 + 2 manifest bump = 23 파일 atomic patch.

TaskCreate Checklist ↔ 9 skill body 결합 (v2.5.2+)

v2.5.2+ 에서 9 skill body 에 ## Checklist 섹션 신규 추가 — using-superpowers 의 "Has checklist? yes → TaskCreate per item" 분기 자동 발동 보장. 사용자 시야에 진행 상황 자동 노출.

적용 범위 (9 skill)

• auto- 4* — auto-brainstorming, auto-tech-design, auto-writing-plans, auto-executing-plans (auto-flow 4 단계)
• 반쪽 페어 1 — executing-plans (writing-plans 페어, v2.5.1 까지 비대칭이었음)
• cascading 1 — change-propagation (impact matrix → 갱신 cascading)
• subagent 1 — subagent-driven (Wave 별 진행)
• og- 2* — og-writing-plans, og-executing-plans (upstream mirror 룰 예외 — 아래 참조)

비적용 영역 (의도적 제외)

• og-brainstorming — 이미 Checklist 보유 (upstream 그대로 답습)
• api-auto-testing, finishing-a-development-branch, subagent-driven-development — 사용자 의사 미선택
• 1회성 / 메타 skill — change-history, risk-annotation, generating-html, verifying-spec, using-superpowers 등 (task 분해 의미 없음)

og-* mirror 룰 예외 (D-4)

og-writing-plans / og-executing-plans 는 upstream superpowers 5.0.7 mirror — 본문 변경 절대 X 가 기본 룰 (다른 CLAUDE.md 섹션에 명시). v2.5.2+ 가 이 룰의 명시 예외:

• Checklist 섹션 한정 추가만 예외. 다른 영역 (Procedure / Anti-Patterns / Related Skills / 영어 식별자 / 본문 룰) 변경 절대 X
• 향후 upstream 본문 변경 시 mirror 답습은 그대로. Checklist 섹션만 intent-locked-workflow 고유 추가로 유지

핵심 룰

• Checklist 항목 형식: - [ ] Step N — <헤더 + 짧은 요약 1줄>
• 위치: 각 skill body 의 ## Process 섹션 직전
• 신규 분기 / 신규 도구 호출 패턴 도입 X — 기존 Process 흐름을 사용자 시야에 노출하는 단순 패턴
• 메인 행동 변화: TaskCreate 도구 호출이 자동 발동 (v2.5.1 dogfood 세션에서 사용자 catch — "왜 태스크 생성안하고 했어?")

Process Step 헤더 ↔ Checklist 항목 동기화 룰 (R-4)

각 skill body 의 Process Step 헤더 변경 시 Checklist 항목 본문도 동기화 필수. drift 회귀 catch grep:

# 각 skill 의 Step 헤더 ↔ Checklist 항목 매치
for f in skills/auto-brainstorming/SKILL.md skills/auto-tech-design/SKILL.md \
         skills/auto-writing-plans/SKILL.md skills/auto-executing-plans/SKILL.md \
         skills/executing-plans/SKILL.md skills/change-propagation/SKILL.md \
         skills/subagent-driven/SKILL.md skills/og-writing-plans/SKILL.md \
         skills/og-executing-plans/SKILL.md; do
  echo "=== $f ==="
  echo "-- Process Step 헤더 --"
  grep -E "^### Step [0-9]" "$f"
  echo "-- Checklist 항목 --"
  grep -E "^- \[ \] Step [0-9]" "$f"
done

회귀 catch grep (release 직전, -F fixed string)

# 9 skill 모두 ## Checklist 섹션 존재
grep -lF "## Checklist" \
  skills/auto-brainstorming/SKILL.md \
  skills/auto-tech-design/SKILL.md \
  skills/auto-writing-plans/SKILL.md \
  skills/auto-executing-plans/SKILL.md \
  skills/executing-plans/SKILL.md \
  skills/change-propagation/SKILL.md \
  skills/subagent-driven/SKILL.md \
  skills/og-writing-plans/SKILL.md \
  skills/og-executing-plans/SKILL.md
# expected: 9 lines (모두 매치)

# og-* mirror 룰 예외 명시
grep -cF "og-* mirror 룰 예외" CLAUDE.md
# expected: >= 1

영향 범위

• 10 본문 (9 skill + CLAUDE.md) + 2 manifest. 다른 skill / commands / scripts 영향 0
• using-superpowers 본문 변경 X (기존 "Has checklist?" 분기 답습)
• TaskCreate 도구 schema 변경 X (호출 빈도만 ↑)
• Notification 매처 / repeat-alert.sh — 변경 X
• AskUserQuestion / --no-ask 플래그 / 8 skill body 결합 (v2.5+) — 영향 0

요약: 10 본문 + 2 manifest = 16 파일 atomic patch (Wave 0~2 + spec + [log] 묶음 commit).