@angar2/taskery 0.8.1 → 1.0.0

package/README.md

@@ -1,288 +1,523 @@
 # taskery
 
-AI 코딩 에이전트의 자율 개발을 위한 Task 기반의 가드레일 시스템.
+taskery는 AI 코딩 에이전트에게 일을 맡길 때, 그 일을 **태스크** 단위로 열고, 진행하고, 마무리하게 해 주는 작업 체계입니다. Claude Code와 Codex에서 쓸 수 있습니다.
+
+> **태스크** = 하나의 목적을 가진 작업 단위입니다. 버그 하나, 화면 하나, 기능 하나가 각각 태스크가 됩니다.
 
 ---
 
-## 해결하는 문제
+## taskery가 하는 일
 
-- Task 단위 라이프사이클의 가이드를 제시한다.
-- 메인 세션을 단독으로 운영할 때 자주 발생하는 사고를 사전 차단한다.
+taskery는 일을 둘로 나눕니다.
 
-| 문제 | taskery 대응 |
-|------|------------|
-| AI 협업 작업이 매번 즉흥적이라 일관된 체계가 없음 | task 단위 라이프사이클로 작업 흐름 구조화 — 단계별 자동화 가능 |
-| 작업 컨텍스트가 휘발되어 이전 결정·사유를 추적하기 어려움 | task 문서로 컨텍스트와 히스토리 기록 — 작업 중 참조 가능 |
-| 에이전트가 catastrophic 사고를 일으킬 수 있음 | 필수 hook으로 차단 — 정상 흐름에는 무간섭 |
-| 에이전트가 작성한 코드의 자가검증으로 인해 문제를 놓침 (confirmation bias) | 테스트 시 별도 격리 세션 호출(`/task-test`) — 메인 세션의 가정 없이 독립 검증 |
-| 단일 메인 세션 운영으로 인해 task를 직렬로 진행해야 하는 병목 | 같은 프로젝트에서 여러 메인 세션이 독립 작업 폴더(worktree)로 병렬 진행 — 머지 시점에 직렬화로 정합성 유지 |
-| 검수 중 한 줄만 고쳐도 전체 테스트를 다시 돌려 대기 시간이 길어짐 | 수정 구간에는 변경이 닿는 테스트만 실행 — 전체 실행은 task당 1회로 제한 |
-| 테스트가 앱 화면을 띄우고 조작해 그동안 컴퓨터를 쓸 수 없음 | 화면·입력을 점유하는 테스트는 창을 띄우지 않는 실행 경로가 준비된 경우에만 자동 실행 — 없으면 사용자 승인 후 실행 |
-| 프로젝트마다 개발·테스트 방식이 다른데 공통 규칙만 적용됨 | 프로젝트 전용 규칙 파일(`*.local.md`)을 각 스킬이 읽어 우선 적용 — 패키지를 갱신해도 덮어쓰지 않음 |
+| 누가 | 무엇을 | 예 |
+|---|---|---|
+| **AI 에이전트** | 생각과 판단이 필요한 일 | 요구 정리, 코드 작성, 완료 기준 작성, 병합 충돌 해결 |
+| **taskery 명령** | 누가 해도 결과가 같은 일 | 번호 붙이기, 브랜치·작업 폴더 만들기, 기록, 커밋, 병합, 정리 |
 
-> catastrophic 사고 예시 — git 운영 정책 위반, 검증 우회, 완료된 task 문서 재수정 등
+에이전트는 "이 단계에서 무엇을 판단하고 어떤 명령을 부를지"만 압니다. 실수하기 쉬운 반복 작업은 명령이 정확하게 처리합니다.
 
 ---
 
-## 워크플로우
+## 이런 문제를 해결합니다
+
+| AI에게 그냥 맡기면 | taskery를 쓰면 |
+|---|---|
+| 무엇을 왜 바꿨는지가 긴 대화 속에 묻혀, 나중에 다시 찾기 어렵습니다 | 태스크마다 문서 한 장(15~30줄)에 목표, 완료 기준, 고친 파일, 내린 결정, 결과가 남습니다 |
+| AI가 "완료했습니다"라고 하지만, 기능이 처음부터 끝까지 실제로 되는지는 아무도 해 보지 않았습니다 | 사용자가 화면에서 보게 될 결과로 완료 기준을 적고, 실제로 해 봅니다. 증거가 없으면 통과로 인정하지 않습니다 |
+| 확인한다며 앱 화면을 띄우는 느린 테스트까지 매번 돌려 한참 기다립니다 | 개발 중에는 화면을 켜지 않는 코드 테스트만 돌리고, 3분을 넘으면 알려 줍니다 |
+| AI가 어디까지 하고 멈출지 예측할 수 없습니다 | 사용자가 말한 데까지만 합니다. 말하지 않으면 한 단계만 하고 멈춥니다 |
+| 여러 일을 동시에 맡기면 한 폴더에서 변경이 섞이고 병합이 엉킵니다 | 태스크마다 브랜치와 작업 폴더를 따로 만들고, 병합은 한 번에 하나씩 합니다 |
+| 커밋 형식, 병합 방식, 브랜치 정리를 매번 다시 말해야 합니다 | 프로젝트의 git 규칙 표를 명령이 읽고 그대로 커밋·병합·정리합니다 |
+| 프로젝트마다 다른 앱 실행 방법과 코딩 규칙을 매번 다시 설명합니다 | 프로젝트 전용 규칙 파일 두 장을 AI가 단계마다 읽습니다 |
+
+---
 
-task 단위 라이프사이클은 7 상태로 구성된다.
+## 일을 나누는 구조
 
-**task 상태**
+taskery는 일을 세 층으로 나눕니다.
 
 ```
-draft → planned → developing → developed → testing → tested → closed
+프로젝트 (리포 하나)
+│
+├─ 백로그 (BACKLOG.md)     떠오른 문제와 할 일을 모아 두는 곳 — 프로젝트에 하나
+│
+└─ 플랜
+   └─ 001_mvp/
+      ├─ PLAN.md            이 기능 묶음의 목표와 태스크 목록
+      └─ tasks/             태스크 문서들 (TASK-001, TASK-002 …)
 ```
 
-| 상태 | 의미 |
-|------|------|
-| `draft` | 새 task 생성 직후 |
-| `planned` | 작업 기획 완료 |
-| `developing` | 구현 진행 중 |
-| `developed` | 구현 완료 (자가 검증 통과) |
-| `testing` | 독립 검증 진행 중 |
-| `tested` | 독립 검증 완료 |
-| `closed` | git 커밋 + 부모 브랜치 병합 완료 |
+| 층 | 뜻 | 예 |
+|---|---|---|
+| 프로젝트 | taskery를 설치한 리포 하나 | 클립보드 관리 앱 |
+| 플랜 | 기능 묶음 하나의 목표와 태스크 목록 | "고정 기능 강화" |
+| 태스크 | 하나의 목적을 가진 작업 단위 | "고정한 항목을 사이드바에 보여 주기" |
+| 백로그 | 아직 태스크가 되지 않은 문제와 할 일 | "백업 파일이 지워지지 않고 쌓인다" |
+
+`PLAN.md`의 태스크 목록에는 먼저 끝나야 하는 항목(선행)을 함께 적습니다.
+
+```markdown
+## 태스크 목록
+1. 로그인 화면 — 선행: 없음
+2. 로그인 API 연결 — 선행: 1
+```
 
-> 상태별 전이 조건과 task 문서 양식은 [TASK-DOC.md](https://github.com/angar2/taskery/blob/main/plan/TASK-DOC.md)에서 확인 가능
+taskery는 이 목록을 읽어 **지금 시작할 수 있는 태스크**를 알려 줍니다. 위 예에서는 1번이 끝나야 2번을 시작할 수 있습니다.
 
 ---
 
-## 빠른 시작
+## 태스크가 진행되는 과정
 
-> **요구 사항**: Node.js ≥ 18, git ≥ 2.31 (멀티세션 워크트리 기능 사용 시).
+모든 태스크는 다섯 단계를 거칩니다. 단계마다 AI가 읽는 짧은 안내서(**스킬**)가 하나씩 있고, 단계 끝에는 정해진 명령을 부릅니다.
 
-### npx
+```
+① 시작 ──▶ ② 기획 ──▶ ③ 개발 ──▶ ④ 테스트 ──▶ ⑤ 마무리
+```
 
-특정 프로젝트에 일회성 다운로드 방식.
+| 단계 | AI가 하는 일 | 끝에 부르는 명령 | 명령이 하는 일 |
+|---|---|---|---|
+| ① 시작 | 요청이나 백로그 항목을 읽고, 태스크 하나로 묶을 범위·종류·크기·이름을 정합니다 | `prepare-task` | 겹치지 않는 번호를 발급하고, 전용 브랜치와 작업 폴더를 만들고, 태스크 문서를 만듭니다 |
+| ② 기획 | 목표, 완료 기준, 고칠 파일을 문서에 적고 사용자 확인을 받습니다 | `approve-plan` | 필요한 내용이 다 적혔는지 검사하고, 기획이 끝났다고 기록합니다 |
+| ③ 개발 | 코드를 고치고 필요한 단위 테스트를 씁니다 | `test-code` | 등록된 코드 테스트를 돌리고, 통과한 순간의 코드 상태를 기록합니다 |
+| ④ 테스트 | 앱을 한 번 켜서 완료 기준을 실제로 해 보고 증거를 남깁니다 | `test-scenario` | 완료 기준마다 결과와 증거를 기록합니다. 증거 없는 통과는 받지 않습니다 |
+| ⑤ 마무리 | 태스크 중 내린 결정 가운데 앞으로도 지킬 것을 프로젝트 문서에 반영합니다 | `verify-close` → `commit-task` → `merge-task` → `close-task` | 검사하고, 커밋하고, 병합하고, 작업 폴더를 치운 뒤 걸린 시간을 보고합니다 |
 
-```bash
-# 새 프로젝트
-npx -p @angar2/taskery create-taskery <project-name>
+마무리 명령 네 개는 각각 이런 일을 합니다.
 
-# 기존 프로젝트에 도입 (init 시 에이전트 플랫폼 선택)
-cd <project-name>
-npx @angar2/taskery init
+| 명령 | 하는 일 |
+|---|---|
+| `verify-close` | 기획 확인이 있었는지, 코드 테스트 뒤에 코드가 바뀌지 않았는지, 모든 완료 기준에 결과와 증거가 있는지 검사합니다 |
+| `commit-task` | 작업 묶음마다 커밋을 만들고, 병합 전에 볼 요약(커밋 목록, 바뀐 파일, 단계별 시간, 기획 뒤 늘어난 파일)을 보여 줍니다 |
+| `merge-task` | 병합 잠금을 잡고, 그사이 들어온 다른 변경을 먼저 반영한 뒤 병합합니다. 충돌이 나면 멈추고, AI가 고친 뒤 다시 부르면 이어 갑니다 |
+| `close-task` | 작업 폴더와 병합된 브랜치를 지우고, 태스크를 닫고, 백로그와 변경 기록을 갱신하고, 단계별 걸린 시간을 보고합니다 |
 
-# 다른 플랫폼 자산 추가 (예: 기존 설치에 Codex 추가)
-npx @angar2/taskery add codex
+---
 
-# 최신 버전 머지 갱신
-npx @angar2/taskery update
+## 어디까지 하고 멈추는지
 
-# 멀티세션 보조 명령
-npx @angar2/taskery status   # 진행중 태스크 / 워크트리 / 머지 락 현황
-npx @angar2/taskery prune    # stale 워크트리 / 브랜치 대화형 정리
-```
+AI가 어디서 멈출지는 사용자의 말로 정해집니다.
 
-### 글로벌 npm install
+| 사용자의 말 | AI의 동작 |
+|---|---|
+| (범위를 말하지 않음) | 한 단계만 하고 멈춰서 보고합니다 |
+| "개발까지 해 줘" | 그 단계까지 멈추지 않고 이어 갑니다 |
+| "끝까지 해 줘" | 병합과 정리까지 합니다. 기획 확인과 병합 확인도 맡긴 것으로 봅니다 |
 
+범위와 상관없이 반드시 멈추는 곳은 세 군데뿐입니다.
 
-```bash
-# 글로벌 설치
-npm install -g @angar2/taskery
+1. 사용자가 눈으로 확인해야 하는 완료 기준이 있을 때
+2. 테스트가 실패했을 때
+3. AI가 풀지 못한 병합 충돌이 났을 때
 
-# 새 프로젝트
-create-taskery <project-name>
+강제 푸시처럼 되돌릴 수 없는 git 명령은 범위와 상관없이 언제나 사용자에게 먼저 묻습니다.
 
-# 기존 프로젝트에 도입 (init 시 에이전트 플랫폼 선택)
-cd <project-name>
-taskery init
+**대화 예시**
 
-# 다른 플랫폼 자산 추가 (예: 기존 설치에 Codex 추가)
-taskery add codex
+```
+사용자: "설정 화면의 저장 버튼 색을 바꿔 줘"
+  → 태스크를 열고 작업 폴더를 만든 뒤 멈춥니다 (범위를 말하지 않았으므로 한 단계)
 
-# 최신 버전 머지 갱신
-taskery update
+사용자: "개발까지 해 줘"
+  → 기획을 적고, 코드를 고치고, 코드 테스트를 통과시킨 뒤 멈춥니다
 
-# 멀티세션 보조 명령
-taskery status
-taskery prune
+사용자: "끝까지 해 줘"
+  → 완료 기준을 실제로 해 보고, 커밋·병합·정리까지 마칩니다
 ```
 
 ---
 
-## 패키지 디렉토리 구조
+## 일의 크기에 맞추는 법 — 크기와 스위치
 
-`taskery init` 직후 골격 (아래는 Claude Code 선택 시 예시):
+### 크기 — 문서에 얼마나 적을지
 
-```
-my-app/
-├─ AGENTS.md                              # AI 에이전트 진입 문서 (본문 단일 소스)
-├─ CLAUDE.md                              # Claude Code용 — `@AGENTS.md` 임포트 한 줄
-├─ .taskery-manifest.json                 # 패키지 업데이트 추적
-├─ .gitignore
-├─ .claude/
-│   ├─ settings.json                      # hook 등록 (PreToolUse 매칭)
-│   ├─ skills/<skill-name>/SKILL.md       # 9 skill (+ Claude 전용 run-team)
-│   └─ hooks/<hook-name>.sh               # 2 hook
-└─ .project/
-    ├─ PROJECT.md                         # 프로젝트 개요
-    ├─ LINKED-REPOS.md                    # 관계 리포지토리 정보
-    ├─ GLOSSARY.md                        # 도메인 용어집 (영문/한글 표기 일관성)
-    ├─ .env                               # 사용자 설정 환경변수 (관계 리포지토리 환경변수 등)
-    ├─ SERVICE-POLICY.md / TECH-STACK.md / ARCHITECTURE.md   # 제품 관통 문서 — 정적 (project-init 작성)
-    ├─ DATA-MODEL.md / API-SPEC.md / FEATURES.md / UX-UI.md  # 제품 관통 문서 — 성장 (골격 → plan·task가 채움)
-    ├─ rules/
-    │   ├─ TASKERY_RULE.md                # taskery 사용 설명서 (세션 필독)
-    │   ├─ TASK_DOC_RULE.md               # task 문서 작성 규칙
-    │   ├─ GIT_RULE.md                    # 로컬 깃 운영 규칙
-    │   ├─ CHANGELOG_RULE.md              # CHANGELOG 작성 규칙
-    │   ├─ MOCKUP_RULE.md                 # UX/UI HTML 목업 규칙
-    │   ├─ DEV_RULE.local.md              # 이 프로젝트의 구현 정책 (모든 리포 필수)
-    │   ├─ TEST_RULE.local.md             # 이 프로젝트의 검증 실행 경로·범위 (모든 리포 필수)
-    │   └─ *.local.md                     # 사용자 오버라이드 규칙 (패키지 업데이트 대상 제외)
-    ├─ plans/                             # plan(기능 그룹)별 PLAN.md / ROADMAP.md (<NNN_slug>/)
-    ├─ tasks/                             # task 문서 (<NNN_slug>/BACKLOG.md / spec-diffs / screenshots / mockup 포함)
-    ├─ flows/                             # 서비스 로직 플로우 정보
-    ├─ changelog/                         # 수정사항 정보
-    ├─ shared/                            # 관계 리포지토리 소통 메세지함
-    │   ├─ sent/completed/
-    │   └─ received/completed/
-    └─ FRICTION_LOG.md                    # taskery 불편사항 누적 로그 (/log-friction 첫 기록 시 생성)
-```
+| | small | medium · large |
+|---|---|---|
+| 태스크 문서 | 목표, 완료 기준, 고칠 파일, 결정, 결과 | 위에 더해 요구사항과 작업 묶음(Phase) |
+| 커밋 | 1개 | 작업 묶음마다 1개 |
 
-`.project/`는 플랫폼 무관 공통 자산이다. 진입 문서와 에이전트 자산 위치는 선택한 플랫폼에 따라 갈린다.
+크기는 AI가 제안합니다.
 
-| 플랫폼 | 진입 문서 | 스킬 위치 | hook 위치 | hook 등록 |
-|--------|----------|----------|----------|----------|
-| Claude Code | `CLAUDE.md` (→ `AGENTS.md` 임포트) | `.claude/skills/` | `.claude/hooks/` | `.claude/settings.json` |
-| Codex | `AGENTS.md` | `.agents/skills/` | `.codex/hooks/` | `.codex/config.toml` |
+### 스위치 — 그 단계를 정식으로 거칠지
 
-진입 문서 본문은 `AGENTS.md` 한 벌이다. Claude Code는 `AGENTS.md`를 자동으로 읽지 않으므로 `CLAUDE.md`가 이를 임포트한다.
+| 스위치 | 켜짐 (기본) | 꺼짐 |
+|---|---|---|
+| 기획 | 요구를 정리하고, 필요하면 되묻고, 기획 확인을 받습니다 | 요청 내용으로 짧게 적고 멈추지 않고 넘어갑니다 |
+| 개발 | 코드를 고치고 코드 테스트를 합니다 | 코드를 바꾸지 않습니다. 점검만 하는 태스크에 씁니다 |
+| 테스트 | 완료 기준을 실제로 해 봅니다 | 실제 확인 없이 마무리하거나 사용자에게 검수를 부탁합니다 |
 
-> 스킬 9종과 `git-guard.sh`는 양 플랫폼 동일 자산이다. 진입 문서, hook 등록 방식, 완료 보호 hook(`closed-immutable.sh`)의 구현만 플랫폼별로 다르다. `init`에서 둘 다 선택하면 폴더가 갈려 충돌 없이 공존한다.
+- 기본은 모두 켜짐입니다. 사용자가 말했거나 요청에서 분명히 드러날 때만 AI가 한 줄로 묻고 바꿉니다.
+- 개발과 테스트를 둘 다 끌 수는 없습니다. 할 일이 없는 태스크이기 때문입니다.
 
 ---
 
-## 멀티세션 (병렬 작업)
+## 태스크 문서
+
+태스크마다 마크다운 문서 한 장이 생깁니다.
+
+```markdown
+# TASK-012 설정 화면 저장 버튼 색 변경
+<!-- taskery: plan=001_mvp type=improve size=small switch=plan,dev,test range=끝까지 parent=dev by=taskery -->
+
+| 시작·기획 | 개발 | 테스트 | 닫기 |
+|---|---|---|---|
+| ✅ 2분 | ✅ 3분 | ⏳ | – |
+
+## 목표
+저장 버튼이 다른 버튼과 구분되지 않아 눈에 띄는 파란색으로 바꾼다.
+
+## 완료 기준
+1. [AUTO] 설정 화면 → 저장 버튼을 본다 → 버튼이 파란색으로 보인다
+2. [USER] 설정 화면 → 이름을 바꾸고 저장 → 목록에 바뀐 이름이 보인다
 
-같은 프로젝트에서 여러 메인 세션을 동시에 운영해 독립 task를 병렬로 진행한다.
+## 만질 파일
+- src/ui/SettingsView.tsx
 
-- 새 task를 시작하면(`/task-init`) 작업 폴더(`~/.taskery/worktrees/<projectId>/TASK-NNN_<출처>_<슬러그>/`)와 작업 브랜치를 함께 분기한다.
-- 작업 폴더에서 새 메인 세션을 열어 진행하거나, 메인 세션 1개로 모든 작업을 지휘하거나, 메인이 서브 세션을 호출해 병렬로 진행한다 — 운영 방식은 자유. 메인 워크트리(원본 폴더)는 task를 시작한 브랜치(*부모 브랜치*, 기본은 `dev`)를 그대로 유지한다.
-- task 완료(`/task-close`) 시 머지 락으로 직렬화한 후 **그 부모 브랜치**에 `--no-ff` 병합한다(개인은 `dev`, 회사/로드맵은 서 있던 브랜치). 다른 세션이 먼저 머지해 충돌이 발생하면 본 세션이 단순/의미적/판단 불가 3단계로 해결을 시도한다.
-- 머지 직후 작업 폴더와 작업 브랜치는 자동 정리된다(보존 키워드 사용 시 양쪽 유지). 안전망으로 복구 명령이 함께 출력된다.
+## 결정
+- 파란색은 디자인 토큰 primary를 쓴다 — 다크 모드에서도 대비가 유지된다
 
-요건: git ≥ 2.31. 보조 명령 `npx @angar2/taskery status` / `prune`로 진행 현황과 stale 정리를 확인한다.
+## 결과
+```
+
+| 부분 | 누가 쓰나 |
+|---|---|
+| 맨 위 두 줄(종류, 크기, 스위치, 범위, 부모 브랜치 등) | 명령 |
+| 단계 표 | 명령 — 명령이 성공했을 때만 칸이 채워집니다 |
+| 목표, 완료 기준, 만질 파일, 결정 | AI |
+| 결과 | 명령 (`test-scenario`) |
+
+단계 표는 AI의 "했습니다"가 아니라 **명령이 실제로 통과한 기록**입니다. 그래서 문서만 보면 태스크가 정말 어디까지 왔는지 알 수 있습니다. 태스크 상태는 열림과 닫힘 둘뿐이고, 손으로 바꾸는 상태는 없습니다.
 
 ---
 
-## 백로그 메모
+## 테스트 방식
+
+taskery는 테스트를 두 종류로 나눕니다.
+
+| | 코드 테스트 | 실사용 테스트 |
+|---|---|---|
+| 언제 | 개발 단계 | 테스트 단계 |
+| 무엇을 | 코드가 깨지지 않았는지 — 린트, 타입 검사, 빌드, 단위 테스트 | 사용자가 원한 일이 처음부터 끝까지 되는지 |
+| 기준 | 앱 화면을 켜지 않는 것만 등록합니다. 3분을 넘으면 알려 줍니다(끊지는 않습니다) | 완료 기준 최대 5개 |
+| 증거 | 명령 출력이 자동으로 기록됩니다 | 실행 출력, 화면 캡처 경로, 또는 사용자가 확인한 시각 |
+
+### 완료 기준 쓰는 법
+
+한 줄 형식은 `[AUTO 또는 USER] 시작 → 행동 → 기대하는 끝 상태`입니다.
 
-작업 흐름 중 발견되는 추가 기능과 버그를 *그 자리에서 짧게 적어 둔다*. 메인 세션이 사용자 발화를 받아 `/add-backlog`로 1건씩 활성 plan(기능 그룹)의 `tasks/<NNN_slug>/BACKLOG.md`에 누적한다.
+- `[AUTO]`는 AI가 직접 해 보고 확인합니다.
+- `[USER]`는 사용자가 눈으로 확인합니다. 디자인이 보기 좋은지 같은 것입니다.
+- 한 줄에는 의도 하나, 한 번의 흐름만 담습니다.
+- 기대하는 결과는 **사용자가 화면에서 보는 것**으로만 적습니다. "DB에 행이 생긴다" 같은 내부 값은 코드 테스트에서 확인합니다.
+- 무언가를 없애는 태스크는 대신 무엇이 보여야 하는지를 함께 적습니다.
 
-- 항목 형식: 체크박스 + 식별자(BL-NNN) + 유형 + 제목 + 슬러그. 그 아래 *개요*(추정 원인 / 구상)와 *대상 영역*(관여할 파일·모듈) 2줄.
-- 시작 시점: 사용자가 *"BL-NNN 진행"*이라고 말하면 `/task-init`이 그 항목 메타로 task를 분기하고 BACKLOG.md 항목을 *확인* 마킹(`[x]`)하며 `- TASK: TASK-NNN`을 함께 남긴다. *완료*가 아니라 *task로 옮겼다*는 의미만 담는다.
-- 완료 추적: git 머지 히스토리와 `taskery status`. BACKLOG.md는 메모지 역할만 한다.
-- 다음 기능 그룹 후보 카탈로그(글로벌 `.project/BACKLOG.md`)는 다음 plan 기획용으로 분리 관리한다.
+### 실사용 테스트에서 지키는 것
+
+- 의도를 정면으로 해 봅니다. "빠져나갈 수 없다"가 목표라면 실제로 빠져나가 보고, 버튼이 회색인지만 보고 통과로 적지 않습니다.
+- 앱은 한 번 켜서 완료 기준을 전부 확인합니다. 끌 때는 자기가 띄운 앱만 끕니다.
+- 같은 결과가 두 번 연속 기대와 다르면 실패로 기록하고 멈춥니다. 원인 찾기는 개발 단계에서 합니다.
+- "버튼이 눌리는가" 같은 부품 확인, 코드에 그 줄이 있는지 검색하는 확인, 요청하지 않은 화면 픽셀 비교는 하지 않습니다.
+- 사용자가 실패를 알고도 마무리하자고 하면, 실패를 통과로 바꾸지 않고 "사용자가 알고 넘어갔다"는 기록을 그 말 그대로 남깁니다.
 
 ---
 
-## Skills
+## 여러 태스크를 동시에
+
+### 태스크마다 자기 작업 폴더
+
+```
+my-app/                             ← 본진 (리포 원래 폴더, dev 브랜치에 그대로)
+~/.taskery/worktrees/…/TASK-012/    ← TASK-012 전용 작업 폴더 (전용 브랜치)
+~/.taskery/worktrees/…/TASK-013/    ← TASK-013 전용 작업 폴더 (전용 브랜치)
+```
+
+- **작업 폴더(워크트리)** = git이 같은 리포를 다른 폴더에 하나 더 펼친 것입니다. 태스크마다 따로 있어 서로의 변경이 섞이지 않습니다.
+- **본진** = 리포의 원래 폴더입니다. 끝난 태스크가 병합되어 들어오는 자리라서 그대로 둡니다.
+- **부모 브랜치** = 본진이 서 있는 브랜치입니다. 태스크는 여기서 갈라져 나와 여기로 병합됩니다.
+- 한 줄 수정도 작업 폴더를 만듭니다. 생략은 사용자가 직접 말할 때만 합니다.
+- Orca(작업 폴더마다 AI 탭을 여는 터미널 앱) 안에서 쓰면 작업 폴더를 Orca가 만들고 탭으로 묶어 보여 줍니다.
 
-스킬은 호출 시점에 따라 4 카테고리(`project` / `plan` / `task` / `meta`)로 분류된다.
+### 동시에 돌려도 섞이지 않는 이유
 
-- `project` — 프로젝트 첫 도입 시 1회만 호출
-- `plan` — 새 기능 그룹(작업 묶음) 시작 시 호출
-- `task` — 새 task 작업 진행 단계에서 호출
-- `meta` — 그 외 taskery 관리
+| 걱정 | taskery의 처리 |
+|---|---|
+| 두 세션이 동시에 태스크를 열어 같은 번호를 받으면? | 번호를 잠금 안에서 발급하므로 겹치지 않습니다 |
+| 두 태스크가 동시에 병합하면? | 병합 잠금이 있어 한 번에 하나씩 들어갑니다 |
+| 먼저 병합된 변경과 충돌하면? | 명령이 멈추고, 그 태스크의 AI가 충돌 파일을 고친 뒤 다시 부르면 이어 갑니다 |
+| 다른 태스크가 고친 용어집이 내 작업 폴더에는 없으면? | taskery 문서는 모든 작업 폴더가 본진의 한 벌을 함께 봅니다. 고치면 바로 공유됩니다 |
 
-| 스킬 | 레벨 | 역할 |
-|------|------|------|
-| `/project-init` | project | 프로젝트 첫 도입 시 메타 문서 + 제품 관통 기획 문서(정책/스택/구조 작성, 데이터/API/기능/UI 골격) 생성 (1회성) |
-| `/plan-init` | plan | 새 기능 그룹의 PLAN.md / ROADMAP.md + 제품 관통 문서(FEATURES/UX-UI)에 기능 의도 추가 |
-| `/task-init` | task | 새 task의 빈 문서 생성 |
-| `/task-plan` | task | task의 요구사항·범위·개발 계획·테스트 계획 작성 |
-| `/task-dev` | task | 계획에 따른 단계별 구현 + 자가 검증 |
-| `/task-test` | task | 별도 격리 세션에서 독립 검증 (메인 가정 차단) |
-| `/task-close` | task | 최종 검증 후 git 커밋 + 부모 브랜치 `--no-ff` 병합 |
-| `/add-backlog` | meta | 사용자 발화로 plan(기능 그룹)별 `tasks/<NNN_slug>/BACKLOG.md`에 task 후보 1건씩 추가 (0.1.2+) |
-| `/log-friction` | meta | 사용자 불편을 `.project/FRICTION_LOG.md`에 한 행 기록 |
-| `/run-team` | meta | 여러 작업을 묶을 수 있는 단위로 task로 나눠 자동 병렬 처리 — 리더 세션이 팀원(독립 세션)에게 task를 1건씩 분배하고 흐름을 관리 (Claude 전용 · 실험 기능 전제 · 0.3.x+) |
+### 작업 폴더 준비 시간 줄이기
 
-각 스킬은 슬래시로 직접 호출하거나, 사용자 발화의 의미가 스킬의 frontmatter description과 매칭되면 메인 세션이 자동으로 발동시킨다.
+새 작업 폴더에서 처음부터 빌드하면 오래 걸립니다. taskery는 다음 방법으로 이 시간을 줄입니다.
 
-> `/run-team`은 Claude의 실험적 멀티 세션 기능(agent teams)을 사용하는 Claude 전용 스킬이다. 기본 흐름이 아니라 *"이 작업들 한 번에 팀으로 진행해"* 같은 발화가 있을 때만 발동하며, 활성화에는 환경 변수(`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) 설정이 필요하다. Codex 설치에는 포함되지 않는다.
+1. 설치할 때 프로젝트를 보고 빌드 결과 폴더(Rust `target`, Xcode `DerivedData`)를 등록합니다.
+2. 새 작업 폴더를 만들 때 본진의 빌드 결과 폴더를 **APFS 복제**로 심습니다. APFS 복제는 macOS가 파일을 실제로 복사하지 않고 1초 만에 복사본처럼 보이게 만드는 기능입니다. 바뀐 부분만 디스크를 씁니다.
+3. 각 작업 폴더는 자기 복사본으로 이어서 빌드하므로 처음부터 빌드하지 않습니다.
+4. 태스크가 끝나 닫힐 때 그 빌드 결과를 본진으로 다시 복제해, 다음 태스크의 출발점으로 씁니다.
 
-`/project-init`, `/plan-init`, `/task-init` 세 스킬은 호출 시 다음 문서를 생성한다.
+Node 프로젝트는 `package-lock.json`이 있으면 `npm ci`로 설치합니다. macOS가 아니면 복제를 건너뛰고 평소처럼 빌드합니다.
 
-| 스킬 | 생성 위치 | 생성 문서 |
-|------|---------|---------|
-| `/project-init` | `.project/` | PROJECT.md / LINKED-REPOS.md / GLOSSARY.md / .env + 제품 관통 문서(SERVICE-POLICY / TECH-STACK / ARCHITECTURE 작성, DATA-MODEL / API-SPEC / FEATURES / UX-UI 골격 — 타입 해당분) + 리포 로컬 룰 초안(TEST_RULE.local.md / DEV_RULE.local.md) |
-| `/plan-init` | `.project/plans/<NNN_slug>/` | PLAN.md / ROADMAP.md + 제품 관통 문서 FEATURES/UX-UI에 기능 그룹 의도 추가 (제품 관통 문서 전체를 한꺼번에 만들지는 않음) |
-| `/task-init` | `.project/tasks/<NNN_slug>/` | `<NNN>_<slug>.md` (단일 파일) 또는 `TASK-<NNN>_<slug>/task.md` (사용자 명시 시 폴더 승격) |
+---
+
+## 오케스트레이션 — 한 줄 지시로 여러 태스크를 나눠 맡기기
 
-> 각 스킬의 호출 시점, 입력 처리 방식, 단계별 절차, 주의사항은 [SKILLS.md](https://github.com/angar2/taskery/blob/main/plan/SKILLS.md)에서 확인 가능
+**오케스트레이션** = 한 세션(관리 세션)이 백로그를 태스크로 나누고, 태스크마다 새 AI 탭을 띄워 맡기고, 보고를 받아 정리하는 방식입니다. Orca 안에서 씁니다.
+
+```
+                          👤 사용자
+          ① 한 줄 지시 ↙               ↘ ⑥ 확인은 그 탭에서 직접 답
+┌─ 🏠 본진 ───────────────┐          ┌─ 🪟 Orca ──────────────────┐
+│ 🎛 관리 세션             │ ③ ─────▶ │ TASK-107 탭  📁 + 🧠 Claude │
+│   ↑ ② 읽고 나눔          │ ─────▶   │ TASK-108 탭  📁 + 🧠 Codex  │
+│ 📥 BACKLOG   🗂 PLAN    │ ─────▶   │ TASK-109 탭  📁 + 🧠 Claude │
+│ 📬 보고함  ◀───── ④ 한 줄 보고 ──── │                             │
+│   ⑤ 보고가 오면 깨어남    │          │                             │
+│ 🌿 dev  ◀──── ⑦ 하나씩 병합 ────── │                             │
+└─────────────────────────┘          └─────────────────────────────┘
+```
+
+| 순서 | 무슨 일이 일어나나 |
+|---|---|
+| ① | 사용자가 관리 세션에 한 줄로 지시합니다. 예: "백로그 BL-1~3을 끝까지 진행해" |
+| ② | 관리 세션이 백로그와 `PLAN.md`를 읽고 태스크로 나눕니다. 어떤 태스크를 어떤 순서와 AI로 진행할지 표로 보여 주고 확인받습니다. 지시에 이미 정해져 있으면 다시 묻지 않습니다 |
+| ③ | 태스크마다 작업 폴더를 만들고(`prepare-task`), Orca 새 탭에 Claude나 Codex를 띄워 첫 지시를 보냅니다(`orca-dispatch-task`) |
+| ④ | 각 탭이 자기 작업 폴더에서 기획부터 마무리까지 진행합니다. 끝났을 때, 확인을 기다릴 때, 질문이 있을 때, 막혔을 때 보고함에 한 줄 남깁니다(`report-task`) |
+| ⑤ | 관리 세션은 기다리는 동안 잠들어 있어 토큰을 쓰지 않습니다(`wait-reports`). 보고가 오거나 10분이 지나면 깨어나 처리합니다 |
+| ⑥ | 사용자 확인이 필요하면 관리 세션이 "TASK-108 탭에서 화면 확인해 주세요"라고 알립니다. 사용자는 그 탭에서 직접 답합니다 |
+| ⑦ | 끝난 태스크는 병합 잠금 안에서 하나씩 dev에 병합됩니다(`merge-task`) |
+| ⑧ | 관리 세션이 끝난 태스크의 작업 폴더와 탭을 치우고(`close-task`), 시작할 수 있는 다음 태스크로 빈자리를 채웁니다. 그리고 ③으로 돌아갑니다 |
+
+- **왜 서브에이전트가 아니라 탭인가요?** 서브에이전트는 맡긴 쪽과 주고받는 대화가 없고, 사용자가 중간에 들여다보거나 끼어들 수 없습니다. 탭으로 띄운 세션은 사용자가 언제든 열어 보고 직접 말할 수 있습니다.
+- **승인은 사용자만 합니다.** 관리 세션이 탭에 보내는 말은 `[오케스트레이션]`으로 시작하고, 태스크 세션은 이 말을 승인으로 받아들이지 않습니다.
+- **순서를 지킵니다.** 선행 태스크가 끝나지 않은 태스크는 열지 않습니다. 같은 파일을 크게 고치는 태스크끼리는 차례로 진행합니다.
 
 ---
 
-## Hooks
+## 백로그
 
-| Hook | 작동 시점 | 차단 대상 |
-|------|---------|---------|
-| `git-guard.sh` | git 명령 실행 직전 | 주력 브랜치 직접 커밋 / `--force` / `--no-verify` / 강제 브랜치 삭제 / `reset --hard` / `clean -fd` |
-| `closed-immutable.sh` | 파일 수정 직전 | 완료(`closed`)된 task.md 본 파일 재수정 (관련 spec-diff·스크린샷은 자유) |
+떠오른 문제와 할 일은 `.taskery/BACKLOG.md` 한 곳에 모읍니다.
 
-hook은 catastrophic 사고만 차단한다. 정상 흐름에는 간섭하지 않는다. 등록 방식은 플랫폼별로 다르다 — Claude Code는 `.claude/settings.json`, Codex는 `.codex/config.toml`(최초 1회 `/hooks` 신뢰 승인 필요).
+```markdown
+### BL-3 [feature] 클립보드 확인 주기(500ms) 설정 노출
+- 상태: 대기
+- 등록: 2026-10-01
+- 현상: 확인 주기가 500ms로 고정돼 있어 사용자가 바꿀 수 없다.
+- 연결 태스크: –
+```
 
-> 각 hook의 영역 분리 정신, 등록 매칭, 차단 정책, 예외 처리 절차는 [HOOKS.md](https://github.com/angar2/taskery/blob/main/plan/HOOKS.md)에서 확인 가능
+```
+대기 ──(태스크로 옮김)──▶ 진행 ──(연결된 태스크가 끝나 닫힘)──▶ 완료 ("끝난 항목"으로 이동)
+                             └──(연결된 태스크를 모두 포기)──▶ 대기로 돌아감
+```
+
+- `add-backlog` 스킬이 번호를 받아 종류, 제목, 현상을 채웁니다. 우선순위 같은 선택 칸은 근거가 있을 때만 적고, 지어내서 채우지 않습니다.
+- 상태는 명령이 바꿉니다. 사람이 직접 적는 상태는 `보류`와 `취소`뿐입니다.
 
 ---
 
-## 워크플로우 예시
+## 쓰는 방식 다섯 가지
+
+상황에 맞게 섞어 쓰면 됩니다.
+
+| 방식 | 모습 | 이렇게 말합니다 |
+|---|---|---|
+| 한 단계씩 | 단계마다 결과를 보고 다음을 지시합니다 | "로그인 버튼 색 바꿔 줘" → "다음" → "다음" |
+| 범위 맡기기 | 어디까지 할지 정해 맡깁니다 | "개발까지 해 줘", "끝까지 해 줘" |
+| 백로그 | 의논하며 할 일을 쌓아 두고, 나중에 꺼내 태스크로 엽니다 | "이거 백로그에 적어 둬" → "BL-3 태스크로 열어서 끝까지 해 줘" |
+| 병렬 | 세션 여러 개를 열어 각자 다른 태스크를 진행합니다 | 세션마다 "BL-1 끝까지", "BL-2 끝까지" |
+| 오케스트레이션 | 한 세션이 여러 태스크를 새 탭에 나눠 맡깁니다 | "BL-1~3을 오케스트레이션으로 끝까지 진행해" |
+
+---
+
+## 빠른 시작
+
+> **준비물**: Node.js 18 이상, git 2.31 이상, 위 두 에이전트 중 하나 이상. 오케스트레이션을 쓰려면 Orca가 필요합니다.
+
+### 1. 설치
 
 ```bash
-# 사용자 프로젝트 첫 셋업
-cd <project-name>
+# 새 프로젝트 — 폴더를 만들고 그 안에 설치합니다
+npx -p @angar2/taskery create-taskery my-app
+
+# 기존 프로젝트 — 리포 루트에서 설치합니다 (어떤 에이전트를 쓸지 묻습니다)
+cd my-app
 npx @angar2/taskery init
+
+# 다른 에이전트를 추가합니다
+npx @angar2/taskery add codex
+
+# 새 버전이 나오면 갱신합니다
+npx @angar2/taskery update
+```
+
+- 빈 폴더에서 `init`을 부르면 git 시작, 빈 첫 커밋, 통합 브랜치(기본 `dev`) 만들기까지 한 번에 합니다.
+- 파일은 있는데 git이나 첫 커밋이 없는 폴더에서는 멈춥니다. 첫 커밋에 무엇을 넣을지(예: `.env` 같은 비밀값을 넣을지)는 사용자가 정할 일이기 때문입니다. 첫 커밋을 직접 만든 뒤 다시 부르면 됩니다.
+- 전역으로 설치하면(`npm install -g @angar2/taskery`) `npx @angar2/taskery` 대신 `taskery`로 부를 수 있습니다.
+
+### 2. 프로젝트 소개하기
+
+AI 세션을 열고 `project-init` 스킬을 부릅니다(예: `/project-init`). 기획 문서가 있으면 그것을 읽고, 없으면 무엇을 만드는지, 누가 쓰는지, 핵심 기능과 기술 스택이 무엇인지 짧게 묻습니다. 그러면 다음이 만들어집니다.
+
+- 프로젝트 소개, 용어집, 필요한 제품 문서
+- 코드 테스트 명령 등록
+- 프로젝트 전용 규칙(앱 실행 방법, 구현 규칙)
+- 첫 플랜과 태스크 목록
+
+### 3. 첫 태스크
+
 ```
+사용자: "설정 화면에 다크 모드 토글을 추가해 줘. 끝까지 해 줘."
+```
+
+AI가 태스크를 열고 기획, 개발, 테스트, 마무리까지 진행합니다. 끝나면 무엇을 바꿨는지와 단계별 걸린 시간을 보고합니다. 진행 중에는 언제든 `npx @angar2/taskery status`로 열린 태스크와 진행 상황을 볼 수 있습니다.
 
-이후 메인 세션에 진입(진입 문서 자동 정독 — 사용법 전체는 `.project/rules/TASKERY_RULE.md`)하여 다음 시퀀스로 호출한다. task 5 스킬은 호출과 동시에 상태를 전이시킨다.
+---
+
+## 설치되는 것
 
 ```
-/project-init                  # 진입 메타 문서와 디렉토리 골격 생성
-/plan-init mvp                 # 첫 plan(기능 그룹) — PLAN/ROADMAP + 제품 문서에 기능 의도 추가
-/task-init                     # draft : 첫 task의 빈 문서 생성
-/task-plan TASK-001            # draft → planned : 요구사항·범위·개발 계획·테스트 계획 작성
-/task-dev TASK-001             # planned → developed : 단계별 구현과 자체 검증
-/task-test TASK-001            # developed → tested : 별도 격리 세션으로 독립 검증
-/task-close TASK-001           # tested → closed : 최종 검증 후 git 커밋과 부모 브랜치 병합
-
-# 불편 발생 시 등록
-/log-friction                  # 사용자 불편 한 행 기록
+my-app/
+├─ AGENTS.md                 AI가 세션마다 읽는 짧은 지침 (약 15줄)
+├─ CLAUDE.md                 AGENTS.md를 불러오는 한 줄
+├─ .mcp.json                 AI가 taskery 명령을 도구로 부르게 하는 연결 설정
+├─ .claude/                  스킬 10장과 설정
+├─ .codex/                   스킬 10장과 도구 연결 (Codex를 고른 경우)
+└─ .taskery/
+   ├─ manifest.json          설치 정보, 코드 테스트 명령, 빌드 결과 폴더 등록
+   ├─ rules/                 규칙 문서 7장
+   ├─ BACKLOG.md             백로그
+   └─ (쓰면서 생기는 것)     PROJECT.md · GLOSSARY.md · spec/ · plans/ · changelog/ …
 ```
 
-**자동 발동 예시** — 사용자 발화 의미가 스킬 description과 매칭되면 메인이 슬래시 직접 호출 없이 다음 스킬을 자동 발동한다.
+### 모두 git 밖에 둡니다
+
+taskery 파일은 그 리포에만 적용되는 git 무시 목록(`.git/info/exclude`)에 들어가 git이 추적하지 않습니다. `.gitignore`는 건드리지 않습니다.
 
-- *"로그인 기능 추가해줘"* / *"이 버그 고쳐줘"* → `/task-init` 자동 발동 (새 task 시작 의도)
-- *"기획 다 됐으니 이제 구현 시작해"* → `/task-dev` 자동 발동 (planned task의 다음 단계)
-- *"이 부분도 백로그에 추가해줘"* / *"나중에 할 일로 적어둬"* → `/add-backlog` 자동 발동 (백로그 추가 의도)
-- *"이거 진짜 불편하다"* / *"이 부분 답답하네"* → `/log-friction` 자동 발동 (불만 발화 캐치)
+- 설치해도 리포의 추적 파일이 하나도 바뀌지 않습니다. 커밋되는 것은 코드뿐입니다.
+- 모든 작업 폴더가 본진의 taskery 문서 한 벌을 함께 봅니다. 한 태스크가 고친 용어집을 다른 태스크가 곧바로 봅니다.
+- 그 대신 태스크 문서와 백로그는 git 이력에 남지 않습니다. 다른 사람과 git으로 공유해야 하는 문서는 `.taskery/` 밖(예: `docs/`)에 두면 됩니다.
+- git이 이미 이 파일들 중 하나를 추적하고 있으면 `init`은 설치를 멈추고 어떤 파일인지 알려 줍니다. 추적 해제는 리포 이력을 바꾸는 일이라 사용자가 직접 합니다.
 
-**실패·불확정 분기** — `/task-test`가 FAIL 또는 UNCERTAIN을 반환하면 메인 세션이 사용자에게 판단을 묻고, 사용자의 자연어 답변에서 의도를 해석해 다음 흐름을 *자동 발동*한다(별도 슬래시 호출 없이 진행됨).
+### 규칙 문서 7장
 
-- 사용자가 재구현을 요청하면 → `testing` → `developing`으로 회귀해 `/task-dev`가 자동 발동된다.
-- 사용자가 결함을 인지한 채 종결을 지시하면 → `testing` → `tested`로 진행하고 결함을 명시한 후 `/task-close`로 이행된다.
-- UNCERTAIN(자동 검증이 불가능한 시나리오)은 사용자가 직접 검수한 결과를 답하면 메인 세션이 PASS/FAIL로 해석해 위 두 흐름 중 하나로 합류시킨다.
-- 검증에 필요한 테스트가 화면·입력을 점유해 실행을 보류한 경우에는, 지금 실행할지 / 자리를 비울 때로 미룰지 / 창을 띄우지 않는 실행 경로를 마련할지를 사용자가 고른다. 승인 없이 임의로 실행하지 않는다.
+| 문서 | 내용 | 갱신 |
+|---|---|---|
+| `TASKERY_RULE.md` | taskery 참고서 — 막혔을 때만 읽습니다 | `update`가 새 버전으로 바꿉니다 |
+| `GIT_RULE.md` | 이 리포의 git 규칙. 맨 위 표(통합 브랜치, 브랜치 이름, 커밋 메시지, 병합 방식)를 명령이 읽어 따릅니다 | `update`가 바꿉니다(고쳤으면 먼저 묻습니다) |
+| `TASK_DOC_RULE.md` | 태스크 문서 쓰는 법 | `update`가 바꿉니다 |
+| `CHANGELOG_RULE.md` | 변경 기록 형식 | `update`가 바꿉니다 |
+| `MOCKUP_RULE.md` | 화면 목업의 위치와 형식 — 목업을 요청했을 때만 씁니다 | `update`가 바꿉니다 |
+| `TEST_RULE.local.md` | **이 프로젝트의** 앱 실행 방법과 실사용 테스트 방식 | 프로젝트 소유 — `update`가 건드리지 않습니다 |
+| `DEV_RULE.local.md` | **이 프로젝트의** 구현 규칙 | 프로젝트 소유 — `update`가 건드리지 않습니다 |
 
 ---
 
-## 상세 문서
+## 스킬
+
+**스킬** = AI가 어느 단계에서 무엇을 판단하고 어떤 명령을 부를지 알려 주는 짧은 안내서입니다. 이름으로 직접 부르거나(예: `/task-init`), 요청 내용이 맞으면 AI가 스스로 고릅니다.
+
+| 스킬 | 쓰는 때 | 하는 일 |
+|---|---|---|
+| `project-init` | 처음 한 번 | 프로젝트 정보, 용어집, 제품 문서, 코드 테스트 등록, 프로젝트 전용 규칙, 첫 플랜을 만듭니다 |
+| `plan-init` | 새 기능 묶음을 시작할 때 | 플랜 폴더와 `PLAN.md`(목표, 선행 관계가 있는 태스크 목록)를 만듭니다 |
+| `task-init` | 태스크를 열 때 | 요청이나 백로그 항목을 태스크 하나로 정리해 엽니다 |
+| `task-plan` | 기획 단계 | 목표, 완료 기준, 고칠 파일을 적습니다 |
+| `task-dev` | 개발 단계 | 구현하고 코드 테스트를 통과시킵니다 |
+| `task-test` | 테스트 단계 | 완료 기준을 실제로 해 보고 증거를 남깁니다 |
+| `task-close` | 마무리 단계 | 검사, 커밋, 병합을 하고, 태스크를 연 쪽이 작업 폴더를 정리합니다 |
+| `task-orche` | 여러 태스크를 나눠 맡길 때 | 백로그를 태스크로 나누고, 새 탭에 맡기고, 보고를 받아 정리합니다 |
+| `add-backlog` | 할 일을 적어 둘 때 | 백로그에 항목 하나를 등록합니다 |
+| `log-friction` | taskery가 불편할 때 | 사용자가 겪은 불편을 `.taskery/FRICTION_LOG.md`에 한 줄로 남깁니다(사용자가 원할 때만) |
+
+---
+
+## 명령
+
+명령은 AI가 스킬을 따라 부릅니다. 사용자가 직접 부를 일은 주로 설치 명령과 `status`입니다. AI는 명령을 도구(MCP — AI가 외부 도구를 직접 부르는 연결 방식)로 부르고, 도구가 없으면 `npx @angar2/taskery <명령>`으로 부릅니다.
+
+| 명령 | 하는 일 |
+|---|---|
+| `status` | 열린 태스크, 단계 표, 단계별 시간, 문서와 작업 폴더 경로, 플랜별로 지금 시작할 수 있는 태스크를 보여 줍니다 |
+| `plan-init <이름>` | 다음 번호로 플랜 폴더와 `PLAN.md` 틀을 만듭니다 |
+| `prepare-task "<제목>" --slug --type --size …` | 태스크를 엽니다 — 번호, 브랜치, 작업 폴더, 태스크 문서, 백로그 연결 |
+| `approve-plan <TASK>` | 태스크 문서를 검사하고 기획 끝을 기록합니다 |
+| `test-code [TASK]` | 등록된 코드 테스트를 돌립니다. `--register "<명령>"`으로 테스트 명령을 등록합니다 |
+| `test-scenario <TASK> <번호> pass\|fail "증거"` | 완료 기준의 결과를 기록합니다. 사용자가 실패를 알고 넘어가기로 하면 `accept "<사용자가 한 말>"`로 남깁니다 |
+| `verify-close <TASK>` | 마무리 전 검사를 합니다 |
+| `commit-task <TASK>` | 작업 묶음별로 커밋하고 병합 전 요약을 보여 줍니다 |
+| `merge-task <TASK>` | 잠금 안에서 최신 변경을 반영하고 병합합니다. 충돌 뒤 다시 부르면 이어 갑니다 |
+| `close-task <TASK>` | 작업 폴더와 브랜치를 정리하고, 태스크를 닫고, 백로그와 변경 기록을 갱신하고, 걸린 시간을 보고합니다 |
+| `prune` | 닫힌 태스크에 남은 작업 폴더와 브랜치를 정리합니다(항목마다 묻습니다) |
+| `backlog-add` · `backlog-get` · `backlog-mark` | 백로그 항목을 만들고, 읽고, 태스크에 연결합니다 |
+| `orca-dispatch-task` · `report-task` · `wait-reports` | 오케스트레이션용 — 탭 띄우기, 보고 남기기, 보고 기다리기 |
+| `init` · `update` · `add <claude\|codex>` | 설치, 갱신, 에이전트 추가 |
+
+전체 옵션은 `npx @angar2/taskery help`로 볼 수 있습니다. 명령이 멈출 때는 왜 멈췄는지와 다음에 무엇을 하면 되는지를 함께 알려 줍니다.
+
+---
+
+## 실제로 돌려 본 결과
+
+실제 앱 프로젝트 두 개의 복사본으로 시험했습니다. 하나는 macOS 클립보드 앱(Swift, Xcode, 코드 테스트 600여 개)이고, 하나는 데스크톱 앱(Rust·Tauri와 Node)입니다.
+
+| 시험 | 결과 |
+|---|---|
+| 작은 태스크 하나를 "끝까지" | 요청부터 닫기까지 약 10분 걸렸습니다. 태스크 열기 28초, 기획 2분, 개발과 실사용 테스트 6분 30초, 마무리 1분 30초입니다 |
+| 작업 폴더 준비(Swift 앱) | 요청부터 준비 완료까지 약 38초 걸렸습니다. 1.1GB 빌드 결과를 복제하는 데 4초가 들었습니다 |
+| 작업 폴더 준비(Rust 앱) | 6.7초 걸렸습니다. 그 폴더에서 빌드하는 데 26.8초가 걸렸습니다. 처음부터 빌드하면 130초입니다 |
+| 두 태스크 동시 진행 | 번호가 겹친 일은 없었습니다. 병합 충돌 1건은 명령이 멈추고 AI가 고친 뒤 이어 갔습니다 |
+| 오케스트레이션으로 백로그 3건 "끝까지" | 관리 세션에 한 줄로 지시하자 1분 안에 탭 3개가 배분됐습니다. 2건은 12분, 17분 만에 병합됐고(서로 충돌한 부분도 스스로 해결), 1건은 사용자 화면 확인에서 멈췄다가 확인 뒤 병합됐습니다. 사용자 확인을 기다린 16분을 포함해 모두 35분 걸렸습니다 |
+| 끝난 뒤 남은 것 | 작업 폴더, 브랜치, 탭, 테스트 앱 모두 0개였습니다 |
+
+---
+
+## 하지 않는 것
+
+- PR로 병합하는 방식은 다루지 않습니다. 병합은 로컬에서만 합니다.
+- 태스크 문서와 백로그는 git 이력에 남지 않습니다.
+- 빌드 결과 복제는 macOS에서만 됩니다. 다른 환경에서는 평소처럼 빌드합니다.
+- 오케스트레이션은 Orca 안에서만 됩니다.
+- Codex는 작업 폴더로 옮겨 갈 수 없습니다. Codex로 태스크를 하려면 오케스트레이션이 Codex 탭을 띄우거나, 사용자가 그 작업 폴더에서 Codex를 엽니다.
+
+---
+
+## 자주 묻는 질문
+
+**한 줄만 고치는 일도 태스크를 열어야 하나요?**
+네. 한 줄 수정도 브랜치와 작업 폴더를 만들어야 동시에 다른 태스크가 돌아가도 섞이지 않습니다. 대신 크기를 small로 하고 스위치로 단계를 줄일 수 있습니다. 작업 폴더를 꼭 생략하고 싶으면 그렇게 말하면 됩니다.
+
+**AI가 "통과했다"고 잘못 말하면 어떻게 되나요?**
+통과에는 증거가 필요합니다. 마무리 검사는 모든 완료 기준에 결과와 증거가 있는지, 코드 테스트 뒤에 코드가 바뀌지 않았는지를 확인합니다. 단계 표도 명령이 성공했을 때만 채워집니다.
+
+**taskery가 강제로 막는 것은 무엇인가요?**
+네 가지뿐입니다. 번호가 겹치는 것, 두 태스크가 동시에 병합되는 것, 증거 없이 마무리하는 것, 개발도 테스트도 하지 않는 태스크를 여는 것입니다. 나머지는 AI의 판단에 맡깁니다.
+
+**걸린 시간은 어떻게 알 수 있나요?**
+명령마다 시각을 기록해 두었다가, 태스크를 닫을 때 단계별 시간과 합계를 보고합니다. 일하는 중인 AI에게는 시간 목표를 보여 주지 않습니다. 재촉받은 AI는 확인을 건너뛰기 쉽기 때문입니다.
+
+**두 에이전트를 섞어 써도 되나요?**
+됩니다. 설치할 때 둘 다 고르거나 나중에 `npx @angar2/taskery add codex`로 추가합니다. 오케스트레이션에서는 태스크마다 다른 에이전트와 모델을 맡길 수 있습니다.
+
+**우리 프로젝트만의 앱 실행 방법이나 코딩 규칙은 어디에 적나요?**
+`.taskery/rules/TEST_RULE.local.md`(앱 실행과 테스트 방식)와 `DEV_RULE.local.md`(구현 규칙)에 적습니다. 업데이트가 덮어쓰지 않는 프로젝트 전용 파일입니다. 일하다 새 규칙이 필요해지면 AI가 문장을 제안하고, 사용자가 승인하면 들어갑니다.
+
+**taskery를 쓰다 불편한 점이 있으면요?**
+`log-friction` 스킬로 그 불편을 한 줄 기록해 둡니다. 사용자가 실제로 겪은 불편만 적습니다.
+
+---
+
+## 0.8.x에서 옮겨 오는 경우
+
+1.0은 0.8.x와 호환되지 않으며, 자동으로 옮겨 주는 기능도 없습니다.
 
-spec 문서는 GitHub에서 참고할 수 있다.
+1. 옛 taskery 파일(`AGENTS.md`·`CLAUDE.md`·`.claude/`·`.codex/`·`.agents/`·`.project/`·`.mcp.json`·`.taskery-manifest.json`)을 리포 밖으로 옮깁니다. git이 추적하고 있었다면 추적을 해제해 커밋합니다.
+2. `npx @angar2/taskery init`으로 새로 설치합니다.
+3. 필요한 옛 백로그와 제품 문서는 옮겨 둔 곳에서 새 `.taskery/`로 직접 가져옵니다.
 
-- [OVERVIEW.md](https://github.com/angar2/taskery/blob/main/plan/OVERVIEW.md) — 시스템 진입 가이드와 전체 구조 개요.
-- [SKILLS.md](https://github.com/angar2/taskery/blob/main/plan/SKILLS.md) — 스킬 9종의 상세 명세와 호출 흐름.
-- [TASK-DOC.md](https://github.com/angar2/taskery/blob/main/plan/TASK-DOC.md) — task 문서의 작성 양식과 7 상태 머신의 동작 정의.
-- [HOOKS.md](https://github.com/angar2/taskery/blob/main/plan/HOOKS.md) — catastrophic hook 2종의 정책과 예외 처리 절차.
-- [DISTRIBUTION.md](https://github.com/angar2/taskery/blob/main/plan/DISTRIBUTION.md) — npx 배포 메커니즘과 자산 갱신 로직.
-- [DECISIONS.md](https://github.com/angar2/taskery/blob/main/plan/DECISIONS.md) — 시스템 설계의 핵심 의사결정과 변경 이력.
-- [PLAYBOOK.md](https://github.com/angar2/taskery/blob/main/plan/PLAYBOOK.md) — 향후 도입 가능한 기능 후보 목록.
+0.x로 설치된 리포에서 `update`를 부르면 아무 파일도 바꾸지 않고 이 절차를 알려 준 뒤 멈춥니다.
 
 ---
 
-## 라이센스
+## 라이선스
 
 [MIT](LICENSE)