diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 07f0507..81502a8 100644 --- 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 index d0e0ea4..133f887 100644 --- 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 index c6cf9a4..f81eb69 100644 --- 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 index dc11bc5..189bf09 100644 --- 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 new file mode 100644 index 0000000..0b3feb7 --- /dev/null +++ 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.