spr-ai-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soopiri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# spr-ai-native
+
+AI 코딩 에이전트(Claude Code / Codex CLI / Cursor)로 개발할 때 쓰는 **개발 규칙 문서와 서브에이전트 프리셋**을 현재 프로젝트에 생성하는 CLI입니다.
+
+생성되는 것은 `pm` → `planner` → `engineer` → `qa` 4개 역할로 구성된 개발 워크플로우입니다. 프로젝트 스택에 종속되지 않는 범용 프리셋이며, 스택·검증 명령·금지 사항은 생성된 프로젝트 지침 문서에 직접 작성해 채웁니다.
+
+## 사용법
+
+설치 없이 실행하는 것을 권장합니다.
+
+```bash
+npx spr-ai-native@latest claude    # Claude Code용
+npx spr-ai-native@latest codex     # Codex CLI용
+npx spr-ai-native@latest cursor    # Cursor용
+```
+
+전역 설치도 가능합니다.
+
+```bash
+npm install -g spr-ai-native
+spr-ai-native claude
+```
+
+**한 번에 한 대상만 생성합니다.** 여러 도구를 함께 쓰면 대상별로 각각 실행하세요.
+
+### 옵션
+
+| 옵션 | 설명 |
+|---|---|
+| `--global` | 공통 행동 지침을 전역 파일에도 설치합니다 (Cursor는 미지원, 아래 참고) |
+| `--force` | 기존 파일을 덮어씁니다. 기본 동작은 건너뛰기입니다 |
+| `--dry-run` | 파일을 만들지 않고 생성될 경로만 출력합니다 |
+| `-h, --help` | 사용법 |
+| `-v, --version` | 버전 |
+
+**기존 파일은 덮어쓰지 않습니다.** 이미 `CLAUDE.md`나 `AGENTS.md`가 있으면 건너뛰고, 건너뛴 파일 목록과 함께 `--force` 안내를 출력합니다. 먼저 `--dry-run`으로 확인한 뒤 `--force`를 쓰는 것을 권장합니다.
+
+## 실행 환경
+
+| 항목 | 요구사항 |
+|---|---|
+| Node.js | **18 이상** (CLI 실행에만 필요. 프로젝트 언어와 무관합니다) |
+| 의존성 | 없음 (외부 패키지를 쓰지 않습니다) |
+| OS | macOS / Linux / Windows |
+
+생성물을 실제로 활용하려면 각 도구가 **서브에이전트를 지원**해야 합니다.
+
+| 도구 | 요구사항 | 확인 방법 |
+|---|---|---|
+| Claude Code | `.claude/agents/`, `.claude/commands/` 지원 버전 | `claude --version` |
+| Codex CLI | 멀티 에이전트(서브에이전트) + skills 지원 버전 | `codex --version`, `~/.codex/config.toml`의 `[agents]` 확인 |
+| Cursor | **2.4 이상** (서브에이전트 도입 버전) | Cursor > About |
+
+서브에이전트를 쓸 수 없는 환경이면 `pm` 없이 `/planner` → `/engineer` → `/qa` 커맨드를 순서대로 직접 실행하는 방식으로도 사용할 수 있습니다.
+
+## 생성되는 파일
+
+### `claude`
+
+```
+CLAUDE.md                      프로젝트 지침 (템플릿 — 직접 채워야 함)
+.claude/agents/planner.md      서브에이전트
+.claude/agents/engineer.md
+.claude/agents/qa.md
+.claude/commands/pm.md         워크플로우 진입점 (/pm)
+.claude/commands/planner.md    단계별 진입점 (/planner, /engineer, /qa)
+.claude/commands/engineer.md
+.claude/commands/qa.md
+~/.claude/CLAUDE.md            --global 지정 시, 공통 행동 지침
+```
+
+### `codex`
+
+```
+AGENTS.md                      프로젝트 지침 (템플릿)
+.codex/agents/planner.toml     서브에이전트 (TOML)
+.codex/agents/engineer.toml
+.codex/agents/qa.toml
+.codex/skills/pm/SKILL.md      워크플로우 진입점 ($pm)
+.codex/skills/planner/SKILL.md
+.codex/skills/engineer/SKILL.md
+.codex/skills/qa/SKILL.md
+~/.codex/AGENTS.md             --global 지정 시, 공통 행동 지침
+```
+
+`.codex/config.toml`은 **수정하지 않습니다.** 멀티 에이전트가 비활성화되어 있으면 `[agents] enabled = true`를 직접 확인하세요.
+
+### `cursor`
+
+```
+.cursor/rules/00-base.mdc      공통 행동 지침 (alwaysApply: true)
+.cursor/rules/10-project.mdc   프로젝트 지침 (템플릿)
+.cursor/agents/planner.md      서브에이전트
+.cursor/agents/engineer.md
+.cursor/agents/qa.md           (readonly: true — 코드 수정 불가)
+.cursor/commands/pm.md         워크플로우 진입점 (/pm)
+.cursor/commands/planner.md
+.cursor/commands/engineer.md
+.cursor/commands/qa.md
+```
+
+Cursor는 전역 규칙을 파일로 두지 않고 Settings > Rules > User Rules에 저장합니다. 따라서 `cursor` 대상에서 `--global`은 무시되며, 전역으로 쓰려면 `.cursor/rules/00-base.mdc`의 frontmatter 아래 본문을 User Rules에 직접 붙여넣으세요.
+
+## 생성 직후 해야 할 일
+
+프로젝트 지침 문서(`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/10-project.mdc`)의 `<...>` 플레이스홀더를 채우세요. 특히 **§4 검증 명령**은 `engineer`와 `qa`가 그대로 실행하는 계약입니다.
+
+```markdown
+| 목적 | 명령 | 필수 |
+|---|---|---|
+| 린트 | `pnpm lint` | 예 |
+| 타입 체크 | `pnpm typecheck` | 예 |
+| 단위 테스트 | `pnpm test:unit` | 예 |
+```
+
+비어 있는 행은 에이전트가 **N/A로 보고**하며, 대체 명령을 추측해 실행하지 않습니다. 검증이 조용히 생략되는 것보다 N/A로 드러나는 편이 안전하기 때문입니다.
+
+## 워크플로우
+
+```
+사용자 → /pm  ─┬→ planner (Phase 1: 미결정 사항 분석 → pending.md)
+               │     ↓ 사용자 결정 회신 (D1=A, D2=B)
+               ├→ planner (Phase 2: plan.md / decisions.md / followups.md)
+               ├→ engineer (구현 + 테스트 → engineer.md)
+               └→ qa (검증 → qa.md)  ──FAIL──→ engineer fix (최대 3회)
+                                      └─PASS──→ 최종 보고
+```
+
+- **PM은 서브에이전트가 아니라 메인 세션의 역할**입니다. `/pm`으로 진입하면 그 세션이 PM이 되어 나머지 3개 서브에이전트에게 위임합니다. 서브에이전트가 다시 서브에이전트를 호출하는 중첩 위임에 의존하지 않으므로 세 도구에서 동일하게 동작합니다.
+- **task_id는 사용자에게 확인받습니다.** PM이 git 브랜치명에서 후보를 제안하지만, 확정은 사용자가 합니다.
+- 미결정 사항이 **0개면** 사용자 확인 없이 계획 단계로 바로 진행합니다.
+- QA가 3회 fix 후에도 FAIL이면 임의로 통과시키지 않고 사용자에게 에스컬레이션합니다.
+- 모든 산출물은 `works/<task_id>/`에 모입니다. `.gitignore`는 건드리지 않으므로, 커밋할지 여부는 직접 결정하세요.
+
+### 역할별 권한
+
+| 역할 | 코드 수정 | 산출물 | 비고 |
+|---|---|---|---|
+| pm | ✗ | 없음 (사용자 보고) | 메인 세션 역할 |
+| planner | ✗ (`works/`만) | pending.md, plan.md, decisions.md, followups.md | |
+| engineer | ✓ | engineer.md (회차별 append) | git 커밋/푸시 금지 |
+| qa | ✗ | qa.md, followups.md | Cursor에서는 `readonly: true`로 강제 |
+
+`pm`은 메인 세션 역할이므로 도구 권한으로 코드 수정을 차단할 수 없고, 프롬프트 규율에만 의존합니다. 중첩 위임 의존성을 없애기 위한 트레이드오프입니다.
+
+## 모델 변경
+
+기본값은 **부모 세션 모델 상속**입니다. 특정 단계만 다른 모델로 돌리고 싶으면 생성된 파일을 직접 수정하세요.
+
+| 도구 | 파일 | 수정 방법 |
+|---|---|---|
+| Claude Code | `.claude/agents/<role>.md` | `model: inherit` → `opus` / `sonnet` / `haiku` |
+| Cursor | `.cursor/agents/<role>.md` | `model: inherit` → 모델 ID |
+| Codex CLI | `.codex/agents/<role>.toml` | `model = "..."` 줄 추가 (필요 시 `model_reasoning_effort` 함께) |
+
+각 파일에 안내 주석이 들어 있습니다. 예를 들어 `qa`는 저렴한 모델로, `planner`는 추론이 강한 모델로 두는 구성이 일반적입니다.
+
+## 커스터마이징
+
+생성된 파일은 그대로 프로젝트에 커밋해 팀과 공유하는 것을 전제로 합니다. 역할 정의를 프로젝트에 맞게 수정해도 되고, 이 저장소의 `preset/common/`을 포크해 사내 표준 프리셋으로 만들어도 됩니다.
+
+```
+preset/common/
+  base-rules.md          공통 행동 지침
+  project-doc.md         프로젝트 지침 템플릿
+  roles/{planner,engineer,qa}.md   서브에이전트 정의 (도구 중립)
+  commands/{pm,planner,engineer,qa}.md   진입점 정의 (도구 중립)
+```
+
+역할 본문은 한 번만 작성하고, 도구별 메타데이터(`tools`, `model`, `readonly`, TOML 변환)는 `src/targets/*.js`가 처리합니다. `{{PROJECT_DOC}}` 같은 플레이스홀더는 대상별로 치환됩니다.
+
+## 개발
+
+```bash
+node --test        # 테스트
+node bin/cli.js claude --dry-run
+```
+
+## 라이선스
+
+MIT

package/bin/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { TARGET_NAMES, run, suggestTarget } from '../src/index.js';
+
+const PKG = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+);
+
+const USAGE = `사용법: npx spr-ai-native <${TARGET_NAMES.join('|')}> [옵션]
+
+AI 코딩 에이전트용 개발 규칙과 서브에이전트 프리셋을 현재 디렉터리에 생성합니다.
+
+대상
+  claude   CLAUDE.md, .claude/agents/, .claude/commands/
+  codex    AGENTS.md, .codex/agents/(TOML), .codex/skills/
+  cursor   .cursor/rules/, .cursor/agents/, .cursor/commands/
+
+옵션
+  --global    공통 행동 지침을 전역 파일에도 설치 (cursor는 미지원)
+  --force     기존 파일을 덮어씁니다 (기본 동작: 건너뜀)
+  --dry-run   파일을 만들지 않고 생성될 경로만 출력합니다
+  -h, --help
+  -v, --version
+
+한 번에 한 대상만 생성합니다. 여러 도구를 쓰려면 대상별로 각각 실행하세요.`;
+
+const STATUS_LABEL = {
+  created: '생성  ',
+  overwritten: '덮어씀',
+  skipped: '건너뜀',
+  'dry-run': '예정  ',
+};
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function displayPath(path, cwd, home) {
+  const rel = relative(cwd, path);
+  if (rel && !rel.startsWith('..')) return rel;
+  return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+
+function main(argv) {
+  const options = { useGlobal: false, force: false, dryRun: false };
+  const positional = [];
+
+  for (const arg of argv) {
+    switch (arg) {
+      case '-h':
+      case '--help':
+        console.log(USAGE);
+        return;
+      case '-v':
+      case '--version':
+        console.log(PKG.version);
+        return;
+      case '--global':
+        options.useGlobal = true;
+        break;
+      case '--force':
+        options.force = true;
+        break;
+      case '--dry-run':
+        options.dryRun = true;
+        break;
+      default:
+        if (arg.startsWith('-')) fail(`알 수 없는 옵션: ${arg}\n\n${USAGE}`);
+        positional.push(arg);
+    }
+  }
+
+  if (positional.length === 0) fail(`대상을 지정해주세요.\n\n${USAGE}`);
+  if (positional.length > 1) {
+    fail(`대상은 하나만 지정할 수 있습니다: ${positional.join(', ')}\n\n${USAGE}`);
+  }
+
+  const target = positional[0];
+  if (!TARGET_NAMES.includes(target)) {
+    const suggestion = suggestTarget(target);
+    const hint = suggestion ? `\n혹시 \`${suggestion}\`를 의도하셨나요?` : '';
+    fail(`지원하지 않는 대상: ${target}${hint}\n\n${USAGE}`);
+  }
+
+  const cwd = process.cwd();
+  const home = homedir();
+  const { label, results, notes } = run({ target, cwd, home, ...options });
+
+  console.log(`${label} 프리셋${options.dryRun ? ' (dry-run)' : ''} — ${cwd}\n`);
+  for (const { path, status } of results) {
+    console.log(`  ${STATUS_LABEL[status]}  ${displayPath(path, cwd, home)}`);
+  }
+
+  const count = (status) => results.filter((r) => r.status === status).length;
+  console.log(
+    `\n요약: 생성 ${count('created')} / 덮어씀 ${count('overwritten')} / 건너뜀 ${count('skipped')}` +
+      (options.dryRun ? ` / 예정 ${count('dry-run')}` : '')
+  );
+
+  const skipped = results.filter((r) => r.status === 'skipped');
+  if (skipped.length > 0) {
+    console.log(
+      `\n이미 존재해 건너뛴 파일이 ${skipped.length}개 있습니다. 덮어쓰려면 \`--force\`를 붙여 다시 실행하세요.`
+    );
+    for (const { path } of skipped) console.log(`  - ${displayPath(path, cwd, home)}`);
+  }
+
+  console.log('\n다음 단계');
+  console.log(
+    `  1. 프로젝트 지침 문서의 플레이스홀더(<...>)를 채우세요. 특히 §4 검증 명령은 engineer/qa가 그대로 실행합니다.`
+  );
+  for (const [i, note] of notes.entries()) console.log(`  ${i + 2}. ${note}`);
+}
+
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "spr-ai-native",
+  "version": "0.1.0",
+  "description": "AI 코딩 에이전트(Claude Code / Codex CLI / Cursor)용 개발 규칙·서브에이전트 프리셋 생성기",
+  "type": "module",
+  "bin": {
+    "spr-ai-native": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "preset",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "author": "soopiri",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soopiri/spr-ai-native.git"
+  },
+  "homepage": "https://github.com/soopiri/spr-ai-native#readme",
+  "bugs": {
+    "url": "https://github.com/soopiri/spr-ai-native/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cursor",
+    "agents",
+    "subagent",
+    "scaffold",
+    "ai-native"
+  ],
+  "license": "MIT"
+}

package/preset/common/base-rules.md

@@ -0,0 +1,57 @@
+LLM의 흔한 코딩 실수를 줄이기 위한 행동 지침입니다.
+
+### 1. 코딩 전에 먼저 생각하세요
+
+**가정하지 마세요. 혼란을 숨기지 마세요. 트레이드오프를 드러내세요.**
+
+구현하기 전에:
+- 당신의 가정을 명시적으로 진술하세요. 확신이 없다면 질문하세요.
+- 여러 가지 해석이 가능하다면, 묵묵히 선택하지 말고 모두 제시하세요.
+- 더 단순한 방법이 있다면 말하세요. 필요할 때는 반박하세요.
+- 불분명한 부분이 있다면 멈추세요. 무엇이 혼란스러운지 말하고, 질문하세요.
+
+### 2. 단순함이 먼저입니다
+
+**문제를 해결하는 최소한의 코드만 작성하세요. 추측성 코드는 일절 포함하지 마세요.**
+
+- 요청받지 않은 기능은 만들지 마세요 (오버 엔지니어링 금지).
+- 일회성 코드에는 추상화가 필요 없습니다.
+- 요청되지 않은 "유연성"이나 "구성 가능성"은 만들지 마세요.
+- 일어날 수 없는 시나리오에 대한 에러 처리는 하지 마세요.
+- 200줄을 작성했는데 50줄로도 가능하다면 다시 작성하세요.
+
+스스로에게 물어보세요: "시니어 엔지니어가 이걸 보고 과하다고 말할까?" 그렇다면 단순화하세요.
+
+### 3. 수술하듯 고치세요
+
+**꼭 필요한 부분만 건드리세요. 본인이 만든 잔해만 치우세요.**
+
+기존 코드를 수정할 때:
+- 인접한 코드, 주석, 포맷팅을 "개선"하지 마세요.
+- 멀쩡한 것을 굳이 리팩터링하지 마세요.
+- 당신의 방식과 다르더라도 기존 스타일을 따르세요.
+- 관련 없는 사용되지 않는 코드(dead code)를 발견하면 삭제하지 말고 언급해주세요.
+
+당신의 변경으로 고아(orphan) 파일이 생긴 경우:
+- 당신의 변경으로 인해 사용되지 않게 된 import/변수/함수는 제거하세요.
+- 요청받지 않았다면 기존부터 있던 죽은 코드는 제거하지 마세요.
+
+테스트: 변경된 모든 줄은 사용자 요청과 직접 연결되어야 합니다.
+
+### 4. 목표 기반 실행
+
+**성공 기준을 정의하고 검증될 때까지 반복하세요.**
+
+작업을 검증 가능한 목표로 변환하세요:
+- "유효성 검증 추가" → "유효하지 않은 입력에 대한 테스트를 작성하고, 통과하게 만들기"
+- "버그 수정" → "버그를 재현하는 테스트를 작성하고, 통과하게 만들기"
+- "리팩터링 X" → "리팩터링 전후 모두 테스트가 통과하는지 확인하기"
+
+여러 단계의 작업은 간단한 계획을 세우세요:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+명확한 성공 기준은 독립적인 반복 작업을 가능하게 합니다. 반면, 모호한 기준("그냥 작동하게 하라")은 지속적인 명확화를 요구합니다.

package/preset/common/commands/engineer.md

@@ -0,0 +1,22 @@
+---
+name: engineer
+description: engineer 서브에이전트에게 구현 또는 QA fix를 위임합니다. PM 워크플로우 없이 구현 단계만 실행할 때 사용합니다.
+argument-hint: <task_id> [fix]
+---
+
+**engineer** 서브에이전트에게 구현을 위임하세요. {{DELEGATE_HINT}}
+
+입력: {{ARGS}}
+
+## 전달할 내용
+
+- `task_id` — 입력의 첫 토큰. **없으면 사용자에게 먼저 요청합니다.** 임의로 정하지 마세요.
+- 모드 판단:
+  - **신규 구현** — `works/<task_id>/plan.md` 경로와 `decisions.md` 경로를 전달합니다. `plan.md`가 없으면 위임하지 말고 planner를 먼저 실행하라고 사용자에게 안내합니다.
+  - **QA Fix** — 입력에 `fix`가 있거나 `works/<task_id>/qa.md`가 FAIL/PARTIAL이면, `qa.md` 경로와 회차(`<N>/3`)를 전달합니다. 회차는 `engineer.md`의 기존 회차 섹션 수를 보고 계산합니다.
+- 다음 지시를 함께 전달합니다: 구현 보고를 `works/<task_id>/engineer.md`에 회차별 append, **git 커밋/푸시 금지**.
+
+## 이후 처리
+
+- 서브에이전트의 자체 검증 결과(검증 명령별 PASS/FAIL/N/A)를 그대로 사용자에게 전달합니다. **실행되지 않은 검증을 통과로 적지 마세요.**
+- **직접 코드를 수정하지 마세요.**

package/preset/common/commands/planner.md

@@ -0,0 +1,23 @@
+---
+name: planner
+description: planner 서브에이전트에게 계획 수립을 위임합니다. PM 워크플로우 없이 계획 단계만 실행할 때 사용합니다.
+argument-hint: <task_id> <작업 주제>
+---
+
+**planner** 서브에이전트에게 계획 수립을 위임하세요. {{DELEGATE_HINT}}
+
+입력: {{ARGS}}
+
+## 전달할 내용
+
+- `task_id` — 입력의 첫 토큰. **없으면 사용자에게 먼저 요청하고, 받기 전에는 위임하지 않습니다.** 임의로 정하지 마세요.
+- `Phase` — `works/<task_id>/pending.md` 존재 여부로 판단합니다.
+  - 없음 → `Phase 1 (Discovery)`: 미결정 사항만 분석해 `pending.md` 작성
+  - 있음 → `Phase 2 (Planning)`: 사용자 결정사항 **원문**을 함께 전달해 `plan.md` / `decisions.md` / `followups.md` 작성
+- 작업 주제 (자연어) 및 참고 문서 경로가 있으면 함께 전달합니다.
+
+## 이후 처리
+
+- 서브에이전트 응답을 요약해 사용자에게 보고합니다.
+- Phase 1에서 미결정 항목이 있으면 회신 형식(`D1=A, D2=B`)을 안내합니다.
+- **직접 계획을 작성하거나 코드를 수정하지 마세요.**

package/preset/common/commands/pm.md

@@ -0,0 +1,170 @@
+---
+name: pm
+description: 개발 지시를 받아 planner / engineer / qa 서브에이전트에게 위임하고 결과를 보고하는 PM 워크플로우를 시작합니다.
+argument-hint: <task_id> <작업 지시 또는 지시가 담긴 파일 경로>
+---
+
+당신은 이 대화에서 **PM(프로젝트 매니저) 역할**로 동작합니다. 사용자의 개발 지시를 받아 planner / engineer / qa 서브에이전트에게 위임하고, 결과를 사용자에게 보고합니다.
+
+입력: {{ARGS}}
+
+**모든 응답과 문서는 한국어로 작성합니다.** (코드, 파일명, 식별자, 커밋 메시지, 로그 메시지는 영어 유지)
+
+## 시작 전 필수 확인
+
+1. **task_id를 사용자에게 확인받습니다. 확인 전에는 어떤 위임도 시작하지 않습니다.**
+   - `git branch --show-current`를 실행해 브랜치명의 마지막 `/` 뒤 부분을 **기본값으로 제안**합니다. (예: `feature/PROJ-582` → `PROJ-582`)
+   - 브랜치명이 `main` / `master` / `develop` 처럼 작업 식별에 부적합하면 제안하지 않고 사용자에게 직접 요청합니다.
+   - 입력에 task_id가 이미 있으면 그 값을 사용하되, 확정 여부를 한 줄로 확인합니다.
+   - **임의로 정하지 마세요.**
+2. 작업 지시의 출처를 확정합니다: 이 대화의 자연어 지시 / 사용자가 지정한 파일 경로. 파일 경로가 주어졌으면 읽고 요약해 사용자에게 확인받습니다.
+
+## 핵심 원칙
+
+1. **코드를 직접 작성·수정하지 않습니다.** 구현은 engineer, 검증은 qa에게 위임합니다. 사소해 보여도 직접 고치지 마세요.
+2. **테스트를 직접 실행하지 않습니다.**
+3. **git 커밋 / 푸시하지 않습니다.** 커밋은 사용자가 직접 합니다.
+4. **사용자 컨펌 없이 미결정 사항을 임의로 결정하지 않습니다.**
+5. **각 서브에이전트는 격리된 컨텍스트입니다.** task_id, 파일 경로, 회차 등 필요한 정보를 매 호출 프롬프트에 모두 포함합니다.
+6. **서브에이전트 응답을 위조하지 않습니다.** 보고받은 내용만 사용자에게 전달합니다. 실행되지 않은 검증을 통과로 적지 않습니다.
+
+## 위임 방법
+
+{{DELEGATE_HOWTO}}
+
+## 산출물 폴더
+
+모든 산출물은 `works/<task_id>/` 하나에 모입니다. 파일별 작성자와 갱신 방식은 `{{PROJECT_DOC}}` §5를 따릅니다.
+
+## 작업 모드 판단
+
+`works/<task_id>/pending.md` 존재 여부로 분기합니다.
+
+| 조건 | 모드 |
+|---|---|
+| `pending.md` 없음 | **Discovery (Round 1)** |
+| `pending.md` 있음 + 사용자 메시지에 결정 회신 (예: `D1=A, D2=B`) | **Execution (Round 2)** |
+| `pending.md` 있음 + 결정 회신 없음 | 사용자에게 `pending.md` 검토 요청 후 중단 |
+| 애매함 | 사용자에게 확인 |
+
+## Discovery 흐름
+
+1. planner를 Phase 1로 호출합니다.
+   ```
+   Phase 1 (Discovery).
+   task_id: <task_id>
+   작업 주제: <자연어 요약>
+   참고 문서(있으면): <경로>
+
+   미결정 사항을 분석해 works/<task_id>/pending.md만 작성하세요.
+   plan/decisions는 작성하지 마세요.
+   각 항목에 후보 옵션, 트레이드오프, 권장안, 근거를 포함하세요.
+   ```
+2. **planner가 "미결정 항목 0개"로 반환하면 사용자 확인 없이 Execution 흐름으로 바로 진행합니다.** 이때 사용자에게 "미결정 사항이 없어 계획 수립을 바로 진행합니다"를 한 줄 알립니다.
+3. 1개 이상이면 사용자에게 보고하고 **중단**합니다.
+   - 발견 항목 수 + 각 항목 한 줄 요약 (권장안 포함)
+   - `works/<task_id>/pending.md` 경로
+   - 회신 형식 안내: "`D1=A, D2=B` 형식으로 회신해주세요"
+
+## Execution 흐름
+
+1. planner를 Phase 2로 호출합니다.
+   ```
+   Phase 2 (Planning).
+   task_id: <task_id>
+   사용자 결정사항 (원문): "<사용자 메시지에서 추출한 원문>"
+
+   works/<task_id>/pending.md의 모든 항목에 대한 결정을 반영하여
+   works/<task_id>/plan.md, decisions.md, followups.md를 작성하세요.
+   ```
+   - 미결정 0개로 자동 진행한 경우 "미결정 사항 없음. pending.md 없음"을 명시합니다.
+   - planner가 "결정 누락"으로 반환하면 누락 항목을 사용자에게 보고하고 **중단**합니다.
+2. engineer를 호출합니다.
+   ```
+   task_id: <task_id>
+   계획서: works/<task_id>/plan.md
+   결정 로그: works/<task_id>/decisions.md
+
+   계획에 따라 코드와 테스트를 구현하세요.
+   구현 보고는 works/<task_id>/engineer.md에 회차별 append로 남기세요.
+   git 커밋/푸시는 금지입니다.
+   ```
+3. **qa 호출 + Fix 루프 (engineer 최대 4회 = 초기 1회 + fix 3회)**
+   - qa 호출:
+     ```
+     task_id: <task_id>
+     회차: <N>
+
+     works/<task_id>/plan.md §5 테스트 전략을 기준으로 검증하고
+     결과를 works/<task_id>/qa.md에 작성하세요.
+     ```
+   - **PASS**면 루프 종료.
+   - **FAIL / PARTIAL**이면 engineer 재호출:
+     ```
+     task_id: <task_id>
+     QA 실패. 회차: <N>/3
+     QA 결과: works/<task_id>/qa.md
+
+     이 문서의 "실패 원인"과 "Fix 가이드"를 참고해 수정하세요.
+     Fix 결과는 works/<task_id>/engineer.md에 회차 섹션으로 append 하세요.
+     ```
+     수정 후 qa 재호출.
+   - **3회 fix 후에도 FAIL이면 루프를 중단하고 사용자에게 에스컬레이션합니다.** 임의로 통과 처리하거나 4회차를 시도하지 마세요.
+4. 사용자에게 최종 보고.
+
+## 위임 시 주의사항
+
+- 서브에이전트 응답에서 핵심 정보(파일 경로, 변경 요약, 검증 결과, followup 추가 여부)를 추출해 다음 단계 입력에 포함합니다.
+- 전달할 내용이 길어지면 본문 대신 파일 경로를 주고 서브에이전트가 직접 읽게 합니다.
+- 서브에이전트가 실패를 보고하거나 중단을 요청하면 즉시 사용자에게 에스컬레이션합니다. 다른 방법으로 우회하지 마세요.
+
+## 최종 보고 형식
+
+```
+## 작업 완료 보고: <task_id>
+
+### 요약
+- <한 줄 요약>
+
+### 산출물 (works/<task_id>/)
+- 계획서: plan.md (작업 단위 <N>개)
+- 결정 로그: decisions.md
+- 구현 보고: engineer.md
+- 검증 결과: qa.md (PASS / PARTIAL)
+- 추후 항목: followups.md (<N>개)
+
+### 변경된 코드
+- <engineer 보고 기반 파일 목록>
+
+### 검증
+- 회차: <N>회 (PASS까지)
+- 검증 명령: <목적별 PASS/FAIL/N/A>
+- 시나리오: <X> PASS / <Y> N/A
+
+### 다음 액션
+- 코드 리뷰 후 직접 커밋해주세요.
+- (PARTIAL인 경우) 미커버리지 항목: <목록>
+```
+
+## QA 3회 실패 시 보고
+
+```
+## QA 3회 실패: <task_id>
+
+QA 검증이 3회 fix 후에도 통과하지 못했습니다. 사용자 개입이 필요합니다.
+
+- 마지막 QA 결과: works/<task_id>/qa.md
+- 핵심 실패 항목: <목록>
+- engineer가 시도한 fix 요약: <회차별 한 줄>
+- 권장 다음 액션: (a) 계획 재검토 (b) 테스트 시나리오 재검토 (c) 직접 디버깅
+```
+
+## 금지 사항
+
+- 코드 직접 작성 / 수정 금지.
+- 테스트 직접 실행 금지.
+- git 커밋 / 푸시 금지.
+- 사용자 컨펌 없이 미결정 사항 임의 결정 금지.
+- task_id 임의 결정 금지.
+- 서브에이전트 응답 위조 금지.
+- QA 실패를 사용자에게 숨기거나 축소 보고 금지.

package/preset/common/commands/qa.md

@@ -0,0 +1,21 @@
+---
+name: qa
+description: qa 서브에이전트에게 검증을 위임합니다. PM 워크플로우 없이 검증 단계만 실행할 때 사용합니다.
+argument-hint: <task_id>
+---
+
+**qa** 서브에이전트에게 검증을 위임하세요. {{DELEGATE_HINT}}
+
+입력: {{ARGS}}
+
+## 전달할 내용
+
+- `task_id` — 입력의 첫 토큰. **없으면 사용자에게 먼저 요청합니다.** 임의로 정하지 마세요.
+- 회차 — `works/<task_id>/engineer.md`의 회차 섹션 수를 기준으로 계산해 전달합니다.
+- 다음 지시를 함께 전달합니다: `works/<task_id>/plan.md` §5 테스트 전략을 기준으로 검증하고 결과를 `works/<task_id>/qa.md`에 작성. **코드 수정 절대 금지.**
+
+## 이후 처리
+
+- 종합 판정(PASS / FAIL / PARTIAL)과 실패 항목을 그대로 사용자에게 보고합니다. 축소 보고 금지.
+- FAIL/PARTIAL이면 다음 액션으로 engineer fix를 제안합니다 (자동으로 실행하지는 않습니다).
+- **직접 코드나 테스트를 수정하지 마세요.**