sunjin12 · sunjin12 · Apr 20, 2026 · Apr 20, 2026
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
@@ -1,6 +1,6 @@
 # Ossmate — project memory for Claude Code
 
-You are working inside **Ossmate**, an OSS Maintainer's toolkit that simultaneously serves as a reference implementation of every Claude Code extension surface. Read [README.md](../README.md) and [memory/project_phases.md](../memory/project_phases.md) (in user-level memory) before making non-trivial changes.
+You are working inside **Ossmate**, an OSS Maintainer's toolkit that simultaneously serves as a reference implementation of every Claude Code extension surface. Read [README.md](../README.md) and [docs/project_phases.md](../docs/project_phases.md) before making non-trivial changes.
 
 ## Persona
 
@@ -37,4 +37,4 @@ gh release create vX.Y.Z --notes-file CHANGELOG.md
 
 - Don't bypass the PreToolUse hook with `--no-verify` or by editing `.claude/settings.json` to remove deny rules.
 - Don't add dependencies to `mcp/` that the CLI also pulls — keep MCP lean.
-- Don't create new markdown design docs. README + this CLAUDE.md + memory files are the only persistent prose.
+- Don't create new markdown design docs. README + this CLAUDE.md + memory files + `docs/` are the only persistent prose. `docs/` is reserved for public-facing explainers referenced from README / CONTRIBUTING; don't add speculative design docs there.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # Contributing to Ossmate
 
-Thanks for your interest! Ossmate is built in public, in phases — see [memory/project_phases.md](memory/project_phases.md).
+Thanks for your interest! Ossmate is built in public, in phases — see [docs/project_phases.md](docs/project_phases.md).
 
 ## Development setup
 

diff --git a/README.en.md b/README.en.md
@@ -110,7 +110,24 @@ The same MCP server backs both the plugin and the standalone CLI — write tools
 
 ## Why each surface?
 
-Ossmate uses every harness extension because the OSS-maintainer domain genuinely needs each one. This isn't a contrived demo — read [docs/architecture.md](docs/architecture.md) for the per-surface justification.
+All 12 harness extensions pull their weight — each removes a specific friction in the OSS-maintainer workflow. Not a contrived demo mapping. The table below justifies each surface by **what friction shows up when it's missing**.
+
+| Surface | Friction if absent |
+|---|---|
+| **Skills** (slash commands) | Repeated workflows (triage / release notes / stale sweep) retyped into every prompt |
+| **Subagents** | One-size-fits-all model — Opus for bulk classification, Haiku for security audit: cost mismatch |
+| **Hooks** | One `git push origin main` mistake = hours of recovery. Relies on human willpower alone |
+| **MCP server** | Slash / CLI / other AI clients each re-implement gh · OSV · lockfile parsing |
+| **Plugin packaging** | Onboarding = `pip install` + `.claude/` copy + settings edit (multi-step) |
+| **Agent SDK CLI** | CI / remote shell / non-Claude-Code environments have to rebuild the same workflow |
+| **Status line** | PR count · stale count · last tag visible only via browser-tab round-trip |
+| **Output styles** | Keep-a-Changelog format and reviewer tone hand-corrected every release |
+| **Scheduled triggers** | Daily checks dependent on willpower — skipping a few days cascades |
+| **Memory templates** | Persona · branch protection · commit convention re-explained every session |
+| **Settings & permissions** | Destructive `gh` verbs only blocked at hook layer — no allowlist baseline |
+| **Keybindings** | No power-user gestures for maintainer actions (optional — lowest value surface) |
+
+For the build order and motivation behind each surface, see this repo's PR log and the `phase-0` ~ `phase-9` git tags.
 
 ---
 
@@ -137,7 +154,7 @@ The release workflow refuses to publish if the tag's version disagrees with `pyp
 
 ## Development status
 
-Currently building in phases — see [memory/project_phases.md](https://github.com/sunjin12/ossmate/blob/main/memory/project_phases.md) for the plan. Each phase is tagged (`phase-0`, `phase-1`, …) so you can browse the project's evolution.
+Currently building in phases — see [docs/project_phases.md](docs/project_phases.md) for the plan. Each phase is tagged (`phase-0`, `phase-1`, …) so you can browse the project's evolution.
 
 ---
 

diff --git a/README.md b/README.md
@@ -110,7 +110,24 @@ flowchart LR
 
 ## 왜 모든 표면을 사용했나?
 
-Ossmate가 모든 하네스 확장을 사용하는 이유는 OSS 메인테이너 도메인이 각각을 *진짜로* 필요로 하기 때문입니다. 단순 데모가 아닙니다 — 표면별 정당화는 [docs/architecture.md](docs/architecture.md)를 참조하세요.
+12개 하네스 확장 각각이 OSS 메인테이너 도메인의 특정 마찰을 제거합니다. 단순 데모 매핑이 아닙니다 — 아래 표는 **각 표면이 없을 때 어떤 마찰이 생기는지**로 정당화합니다.
+
+| 표면 | 없으면 발생할 마찰 |
+|---|---|
+| **Skills** (슬래시 명령) | 반복 워크플로(triage / release notes / stale sweep)를 매번 프롬프트 처음부터 작성 |
+| **Subagents** | 모든 업무를 단일 모델로 — bulk 분류에 Opus, 보안 감사에 Haiku 같은 모델 미스매치 비용 |
+| **Hooks** | `git push origin main` 실수 1건이 수 시간 복구 비용. 인간 의지력에만 의존 |
+| **MCP 서버** | slash / CLI / 다른 AI 클라이언트가 gh · OSV · lockfile 파싱을 각자 재구현 |
+| **플러그인 패키징** | 온보딩이 `pip install` + `.claude/` 복사 + settings 편집 다단계 |
+| **Agent SDK CLI** | CI · 원격 shell · non-Claude-Code 환경에서 동일 워크플로 재구성 필요 |
+| **Status line** | 현재 저장소의 PR 수 · stale 수가 매번 브라우저 탭으로만 확인 |
+| **Output styles** | CHANGELOG의 Keep-a-Changelog 포맷 · 리뷰 tone을 매번 수동 교정 |
+| **Scheduled triggers** | 의지력에 의존한 일간 체크 — 며칠 skip되면 악순환 |
+| **Memory templates** | persona · 브랜치 보호 정책 · 커밋 컨벤션을 매 세션 다시 설명 |
+| **Settings & permissions** | destructive `gh` 차단을 매번 훅으로만 방어 — 허용목록 baseline 없음 |
+| **Keybindings** | 파워유저 전용 gesture 부재 (옵션 — 가장 낮은 가치) |
+
+각 표면의 빌드 순서와 동기는 이 저장소의 PR 이력과 `phase-0` ~ `phase-9` 태그를 참조하세요.
 
 ---
 
@@ -137,7 +154,7 @@ git tag v0.2.0 && git push --tags      # PreToolUse 훅이 명시적 승인 없
 
 ## 개발 현황
 
-단계별로 빌드되었습니다 — 계획은 [memory/project_phases.md](https://github.com/sunjin12/ossmate/blob/main/memory/project_phases.md)에 있습니다. 각 단계는 태그(`phase-0`, `phase-1`, …)로 마킹되어 있어 프로젝트의 진화 과정을 따라가볼 수 있습니다.
+단계별로 빌드되었습니다 — 계획은 [docs/project_phases.md](docs/project_phases.md)에 있습니다. 각 단계는 태그(`phase-0`, `phase-1`, …)로 마킹되어 있어 프로젝트의 진화 과정을 따라가볼 수 있습니다.
 
 **v0.1.0 (2026-04-19)** — 첫 공개 릴리스. 모든 12개 표면 작동, PyPI 발행 완료.
 

diff --git a/docs/project_phases.md b/docs/project_phases.md
@@ -0,0 +1,39 @@
+# Ossmate build phases
+
+Ossmate was built incrementally in 10 phases (Phase 0 through Phase 9). Each phase produces an **independently demoable artifact** — development can stop at any phase boundary and still leave a shippable product. This gating rule kept scope from sprawling.
+
+Every completed phase is tagged `phase-N` in git so you can `git checkout phase-5` to see the repo's state at that snapshot.
+
+## Phase plan
+
+| Phase | Deliverable |
+|---|---|
+| 0 | `git init`, two `pyproject.toml` (CLI + MCP), LICENSE, `.gitignore`, README skeleton, minimal `.claude/settings.json` + `CLAUDE.md` |
+| 1 | Output style (`maintainer`, `changelog`) + `statusline.{sh,cmd}` + keybindings sample (immediate visual feedback) |
+| 2 | First Skill `/triage-issue` — Bash-only, no MCP yet (learn frontmatter + `allowed-tools`) |
+| 3 | Five hooks: PreToolUse guard, PostToolUse audit, UserPromptSubmit router, SessionStart brief, Stop summary |
+| 4 | MCP server `ossmate_mcp` on FastMCP (started with `repo.detect_project_type`, grew to 11 tools + 3 resource templates) |
+| 5 | Six subagents (Haiku / Sonnet / Opus tier) + remaining seven skills refactored to delegate via `Task` tool |
+| 6 | Plugin packaging (`.claude-plugin/plugin.json` + `marketplace.json`, installable via GitHub raw URL) |
+| 7 | Agent SDK CLI (`cli/ossmate`) — shares `.claude/commands/*.md` skill bodies so slash command + CLI subcommand stay in sync |
+| 8 | Scheduled triggers via `CronCreate` — daily digest, weekly stale sweep, release radar (all opt-in) |
+| 9 | CI/CD (3-OS × 3-Python matrix), PyPI trusted publishing via OIDC, README polish, v0.1.0 cut |
+
+## Design rationale
+
+**Why this order?** Earlier phases (output style, status line) produce **immediate visual feedback** — you can see the tool working within a session. This sustains motivation through the harder middle phases (MCP server, subagent orchestration) where the payoff is delayed.
+
+**Why independently demoable?** Each phase's artifact can be shown off standalone in a portfolio or talk. Phase 2 alone is "a single slash command that triages GitHub issues" — already a complete demo. Phase 5 is "multi-agent system with model-tier routing" — another complete demo. You don't need all 10 phases to have a story.
+
+**Why no "Phase 10"?** After Phase 9 the project enters post-v0.1.0 maintenance — new work goes into `[Unreleased]` in CHANGELOG and ships as patch/minor releases rather than large phase commits. The `ossmate doctor` subcommand (PR #3) is an example: a v0.1.x feature shipped as a regular PR, not as a new phase.
+
+## Git tags
+
+All ten phases are tagged. Browse:
+
+```bash
+git tag -l 'phase-*'
+git checkout phase-5  # inspect repo state at end of Phase 5
+```
+
+Or see GitHub's [tags page](https://github.com/sunjin12/ossmate/tags) for tagged releases.