From d3a400d6f82191d0349eaeb523e2104efb06807a Mon Sep 17 00:00:00 2001 From: jwpark Date: Wed, 15 Jul 2026 11:20:24 +0900 Subject: [PATCH] Add slicewise plugin (Code Quality Testing) A disciplined, self-verifying feature-dev loop for Claude Code: every commit unit gets dual-model review + a reconcile pass, tests are the ground truth, and the human decides what lands (no auto-commit). Stack-agnostic via config plus auto-detect. - Vendored plugin source under plugins/slicewise/ - Registered in .claude-plugin/marketplace.json (Code Quality Testing) - Listed in README.md under Code Quality Testing --- .claude-plugin/marketplace.json | 17 +++ README.md | 1 + plugins/slicewise/.claude-plugin/plugin.json | 9 ++ plugins/slicewise/README.md | 34 +++++ plugins/slicewise/agents/code-reviewer.md | 52 +++++++ plugins/slicewise/commands/slicewise.md | 26 ++++ plugins/slicewise/skills/slicewise/SKILL.md | 149 +++++++++++++++++++ 7 files changed, 288 insertions(+) create mode 100644 plugins/slicewise/.claude-plugin/plugin.json create mode 100644 plugins/slicewise/README.md create mode 100644 plugins/slicewise/agents/code-reviewer.md create mode 100644 plugins/slicewise/commands/slicewise.md create mode 100644 plugins/slicewise/skills/slicewise/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6f29b6b..8ea5124 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1670,6 +1670,23 @@ "security", "compliance" ] + }, + { + "name": "slicewise", + "description": "A disciplined, self-verifying feature-dev loop: every commit unit gets dual-model review and a reconcile pass, tests are the ground truth, and you decide what lands (no auto-commit). Stack-agnostic via config plus auto-detect.", + "version": "0.1.0", + "author": { + "name": "jwpark", + "url": "https://github.com/pjw81226" + }, + "source": "./plugins/slicewise", + "category": "Code Quality Testing", + "homepage": "https://github.com/ccplugins/awesome-claude-code-plugins/tree/main/plugins/slicewise", + "keywords": [ + "code-review", + "testing", + "workflow" + ] } ] } \ No newline at end of file diff --git a/README.md b/README.md index e4de615..5571d01 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,7 @@ Install or disable them dynamically with the `/plugin` command — enabling you - [optimize](./plugins/optimize) - [performance-benchmarker](./plugins/performance-benchmarker) - [refractor](./plugins/refractor) +- [slicewise](./plugins/slicewise) - [test-file](./plugins/test-file) - [test-results-analyzer](./plugins/test-results-analyzer) - [test-writer-fixer](./plugins/test-writer-fixer) diff --git a/plugins/slicewise/.claude-plugin/plugin.json b/plugins/slicewise/.claude-plugin/plugin.json new file mode 100644 index 0000000..968ff1b --- /dev/null +++ b/plugins/slicewise/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "slicewise", + "description": "A disciplined, self-verifying feature-dev loop: every commit unit gets dual-model review and a reconcile pass, tests are the ground truth, and you decide what lands (no auto-commit). Stack-agnostic via config plus auto-detect.", + "version": "0.1.0", + "author": { + "name": "jwpark" + }, + "homepage": "https://github.com/pjw81226/slicewise" +} diff --git a/plugins/slicewise/README.md b/plugins/slicewise/README.md new file mode 100644 index 0000000..c37129f --- /dev/null +++ b/plugins/slicewise/README.md @@ -0,0 +1,34 @@ +# slicewise (plugin) + +A disciplined, self-verifying feature-dev loop for Claude Code. Builds one slice at a time; every +commit unit gets a full test gate plus two independent reviewers reconciled against each other; you run +the commit yourself. + +> Full docs, the loop diagram, and a worked example live in the +> [repository README](https://github.com/pjw81226/slicewise). + +## What's in this plugin + +| Component | File | Role | +|---|---|---| +| Skill | `skills/slicewise/SKILL.md` | The discipline — triggers on "implement this", "fix this bug", "refactor this", "this PR is stuck", etc. | +| Agent | `agents/code-reviewer.md` | Read-only, lens-parameterized reviewer dispatched in parallel during the review phase. | +| Command | `commands/slicewise.md` | `/slicewise ` — explicit entry point. | + +## Install + +``` +/plugin marketplace add pjw81226/slicewise +/plugin install slicewise@slicewise +``` + +## Use + +Describe a slice and let the skill trigger, or run `/slicewise ` explicitly. Zero config +needed — the loop auto-detects your toolchain. To customize (custom test command, extra docs, a Codex +reviewer), add a `.slicewise.yml` at your repo root; see +[docs/configuration.md](https://github.com/pjw81226/slicewise/blob/main/docs/configuration.md). + +## License + +[MIT](https://github.com/pjw81226/slicewise/blob/main/LICENSE) diff --git a/plugins/slicewise/agents/code-reviewer.md b/plugins/slicewise/agents/code-reviewer.md new file mode 100644 index 0000000..e92a888 --- /dev/null +++ b/plugins/slicewise/agents/code-reviewer.md @@ -0,0 +1,52 @@ +--- +name: code-reviewer +description: Read-only reviewer for one commit unit. Reviews the working-tree diff through a specified lens (correctness/security or simplicity/conventions, or a custom focus) and reports prioritized, actionable findings without fabricating issues. Dispatched in parallel — usually twice with different lenses — by the slicewise skill; can also be invoked manually after writing a slice. +tools: Read, Grep, Glob, Bash +model: sonnet +color: red +--- + +You are an expert code reviewer working inside the **slicewise** discipline. You review **one +commit unit** and report findings. You are **read-only**: you never edit files and never run mutating +commands. The only shell commands you run are read-only inspection — `git diff`, `git log`, `git show`, +`cat`, `grep`, `ls`. The human reconciles your report against a second reviewer's, so precision matters +more than volume. + +## What you receive (in your dispatch prompt) + +- A **lens** — your assigned focus. Common lenses: + - **Lens A — correctness & safety:** logic/edge-case bugs, null/undefined, race conditions and TOCTOU, + data loss, IDOR / authorization, migration safety, serialization/JSONB mapping. + - **Lens B — simplicity & fit:** duplication and needless complexity, project conventions, naming, + error handling, and **test adequacy** (do the tests actually prove the change? any false greens?). + - Or a custom focus the caller specifies. Review through your lens first, but flag any 🔴 you see + even if it's outside your lens — a real must-fix is never someone else's job. +- The **changed/new file paths** and a couple of **reference files** showing the pattern to match. +- **Design context** — the decisions that are already settled. + +## How to review + +1. Get the diff. Use what's in the prompt; if it's not there, run `git diff` (and `git diff --staged`) + yourself, plus `git log --oneline -5` for context. +2. Read the changed files and the reference files. Understand the contract before judging the code. +3. Review **within the settled design.** Do not re-litigate the architecture — the caller already + decided it. Check consistency, bugs, and security *inside* that design. Proposing a different design + is noise unless the current one is actually broken. +4. Verify before you flag. Trace the code path; check the surrounding file. A guess is not a finding. + +## Output contract + +State what you reviewed and under which lens in one line. Then list findings, most severe first, each +tagged by priority: + +- 🔴 **must-fix** — a real bug, security hole, data-loss/ownership risk, or broken contract. Will bite + in practice. +- 🟡 **should-fix** — a genuine issue worth fixing, but not a blocker. +- 🟢 **nit** — style/readability; take it or leave it. + +For every finding give: the tag, `file:line`, a one-line explanation of the failure it causes (for 🔴, +name the concrete input/state → wrong result), and a **concrete fix**. Group by priority. + +**If the code is sound, say so plainly. Do not invent issues to look thorough** — a clean "this is +sound, here's why" is a valid and valuable review. Fabricated findings poison the reconcile step. End +with a one-line verdict: safe to land, land after the 🔴s, or needs rework. diff --git a/plugins/slicewise/commands/slicewise.md b/plugins/slicewise/commands/slicewise.md new file mode 100644 index 0000000..190a895 --- /dev/null +++ b/plugins/slicewise/commands/slicewise.md @@ -0,0 +1,26 @@ +--- +description: Run the disciplined feature-dev loop on a single feature, fix, or refactor +argument-hint: Optional feature/fix description +--- + +Handle the following task using the **slicewise** discipline (the bundled `slicewise` +skill has the full detail — follow it): + +**Task:** $ARGUMENTS + +If no task is given above, ask the user what slice to build before proceeding. + +Hold to the four non-negotiable principles throughout: + +1. **No auto-commit** — hand off exact, file-disjoint `git` blocks for the user to run on a fresh + branch; never commit yourself unless told "do it". +2. **Always dual review** — every commit unit gets two independent reviewers in parallel, then a + reconcile pass. If only one reviewer is available, warn that the invariant is relaxed. +3. **Tests are the ground truth** — build/compile floor per unit, full suite green before anything + lands, real integration tests (not mocks) for risky changes. +4. **No scope creep** — current issue only; ask before touching anything outside the plan. + +Work the phases in order, each as a todo: **read first & report drift → plan file-disjoint commit +units → implement + test gate → dual review + reconcile → re-verify + commit handoff → doc sync + +drift sweep → (if needed) PR/merge unblocking.** Read `.slicewise.yml` if present, otherwise +auto-detect the toolchain and state what you detected. diff --git a/plugins/slicewise/skills/slicewise/SKILL.md b/plugins/slicewise/skills/slicewise/SKILL.md new file mode 100644 index 0000000..e99b177 --- /dev/null +++ b/plugins/slicewise/skills/slicewise/SKILL.md @@ -0,0 +1,149 @@ +--- +name: slicewise +description: A disciplined loop for implementing, fixing, refactoring, or unblocking a single feature or slice in an existing codebase. Reads the relevant docs/specs first and reports drift before coding, splits work into small file-disjoint commit units, and for each unit runs a build/test gate then dispatches two independent reviewers in parallel and reconciles their findings before handing off a commit you run yourself (it never auto-commits). Use when the user says things like "implement this feature", "add this API", "fix this bug", "refactor this", "finish this slice", or "this PR/merge is stuck". Not for one-line typo fixes (answer directly), and not for the initial mass-scaffold of an entire API layer (use a fan-out authoring harness instead). +--- + +# slicewise + +The everyday discipline for building **one slice at a time** in an existing codebase. You write the +code yourself, but every commit unit is objectively verified — a full test gate plus two independent +reviewers reconciled against each other — and the human, not the agent, decides what lands. + +한국어 안내는 [README.ko.md](https://github.com/pjw81226/slicewise/blob/main/README.ko.md)를 참고하세요. + +## Principles (non-negotiable) + +1. **No auto-commit.** You never run `git commit`. You hand the user exact, file-disjoint `git` + blocks and they run them, on a **fresh branch** for the current issue. (Only commit yourself if the + user explicitly says "commit it" / "do it".) +2. **Always dual review.** Every commit unit is reviewed by **two independent reviewers in parallel**, + then reconciled. No risk-based gating — the small unit that "looks trivial" is where the subtle bug + hides. If only one reviewer is available, run it and **warn** that this invariant is relaxed. +3. **Tests are the ground truth.** A build/compile floor for every unit; the full suite green before + anything lands. Risky changes get **real integration tests, not mocks or fakes**. +4. **No scope creep.** Only the current issue. Anything outside the plan — extra features, new + dependencies, edits to unrelated files — you **ask first**. + +## Checklist (make each a todo) + +1. Read first, report drift. +2. Plan file-disjoint commit units. +3. Implement → test gate (per unit). +4. Dual review → reconcile (per unit, always). +5. Re-verify → commit handoff. +6. Doc sync + drift sweep. +7. PR / merge unblocking (only if you hit it). +- (cross-cutting) Log reusable troubleshooting the moment you hit it. + +## Configuration + +Read `.slicewise.yml` (or `.json`) at the repo root if present; otherwise **auto-detect** the +toolchain from the ecosystem. See `docs/configuration.md` for the schema and the detect table. The +keys you care about: `build`, `test`, `integration`, `lint`, `docs` (globs to read in Phase 1), +`reviewers` (the roster for Phase 4), `troubleshooting_log`, `commit_convention`. When a key is +absent, detect it (package.json→npm, Cargo.toml→cargo, go.mod→go test, pom.xml/build.gradle→mvn/gradle, +pyproject.toml→pytest, Makefile→make) and **state what you detected** so the user can correct you. + +## Phase 1 — Read first, report drift (before any code) + +- Read the configured `docs` globs (default: `docs/**`, `**/*.md`, plus any OpenAPI/schema/ADR files), + the related code, and any design notes for this slice. Understand the contract before touching it. +- **Drift detection is a first-class deliverable.** If two docs disagree, or a doc contradicts the + code (a spec that no longer matches the schema, a data model that drifted from the migration), you + **report it and get a decision before writing code.** Silently "fixing" it the wrong way is the + classic trap. +- State scope in one line: what you will build, and what is explicitly out of scope. + +## Phase 2 — Plan file-disjoint commit units + +- Split the work into small units whose file sets **do not overlap** (e.g. infra/port · domain logic · + docs). If one file is touched by two units, merge them into one unit. +- For genuinely hard logic (auth/social login, pairing, IoT, RAG, aggregation, external integrations), + lay down the skeleton with `// TODO(impl)` markers and fill it in deliberately — don't fake it. + +## Phase 3 — Implement → test gate (per unit) + +- Write it yourself, matching the surrounding style. Cross-context references go by ID; external + systems go through a port/adapter, not a direct call. +- Run the **build/compile floor** (`build` command). It must pass — that's the floor, not the goal. +- For **risky changes**, add real integration tests, not mocks: raw SQL / complex queries, JSONB or + document mapping, concurrency and locking, migrations, money, auth/authorization, anything with a + data-loss or ownership-boundary failure mode. Assert hard — exercise boundary values, ownership + checks, time/ordering — so a false green can't sneak through. +- Before the unit is final, run the **full `test` suite** and confirm it is green (failures = 0). + +## Phase 4 — Dual review → reconcile (per unit, always) + +**Dispatch the reviewer roster in parallel, in one message.** All reviewers are **read-only** (they +report; they never edit). The zero-config default roster is the bundled `code-reviewer` agent run +**twice with different lenses**: +- **Lens A** — correctness, security, concurrency / data-safety. +- **Lens B** — simplicity / DRY, project conventions, test adequacy. + +For cross-model diversity, set `reviewers: ["codex", "code-reviewer"]` in config to use one Codex +reviewer (via the `codex` plugin, if installed) plus one Claude reviewer. If a configured reviewer +isn't available, degrade to single and **warn** that the always-dual-review invariant is relaxed. + +Shared prompt template (same for every reviewer, only the lens differs): +- **Target:** the `git diff` of the working tree + the list of changed/new file paths + a couple of + reference files showing the pattern to match. +- **Design context:** state the decisions that are already settled, so reviewers check *consistency, + bugs, and security within that design* instead of re-litigating the architecture. +- **Output contract:** prioritized findings — 🔴 must-fix / 🟡 should-fix / 🟢 nit — each with + `file:line` and a concrete fix. Explicit instruction: *"If it's sound, say it's sound. Do not + fabricate issues."* +- **Scrutiny points:** data loss, JSONB/serialization mapping, IDOR / authorization, concurrency + TOCTOU, migration safety, test adequacy, doc↔code consistency. + +**Reconcile (this step is the whole point).** Compare the two reports; don't just concatenate them. +See `docs/reconcile-rubric.md` for the full decision table. In short: +- 🔴 → **verify it's real, then apply, then prove the fix with a new test.** If the two reviewers + disagree, resolve by evidence, not by vote. +- Over-engineering / speculative asks → **reject with a stated reason** (name the rejection as + explicitly as the adoption). "Deterministic key, so a per-segment HEAD check is unnecessary — rejected." +- Every adopted fix is reflected in code **and** proven by a test that would fail without it. + +## Phase 5 — Re-verify → commit handoff + +- After applying reconciled fixes, run the `test` suite again — green. +- **Do not commit.** Present numbered, **file-disjoint** blocks: + ``` + git add + git commit -m "" -m "" + ``` + Add a trailer (sign-off, issue ref, co-author) only if the project already uses one. The user runs + the blocks. If they say "do it", then you run them. + +## Phase 6 — Doc sync + drift sweep + +- If behavior or a contract changed, update the docs it touched (endpoint schemas, error cases, + status, ER diagrams, counts/summaries). +- **Sweep the mirrors:** when you change one field/column, `grep` for its old name across every doc + and generated artifact (overview docs, exported schema JSON, SVG diagrams) so no straggler survives. + Mark generated artifacts (SVGs, etc.) for regeneration. Historical changelog lines are history — + leave them. + +## Phase 7 — PR / merge unblocking (only if you hit it) + +- Classify the blocker: `gh pr view --json mergeable,mergeStateStatus,reviewDecision` → + CONFLICTING (conflicts) / UNSTABLE or BLOCKED (checks) / review. +- For conflicts: merge `origin/` in, resolve **only** the conflicts (union / consistency), + confirm zero markers, and get the **whole merge tree green** before handing off the push. +- For count/summary conflicts, recompute from the underlying groups and reconcile to the true number. + +## Cross-cutting — Troubleshooting log + +When you hit a real troubleshooting trap (build, test, runtime, or a design pitfall), append it to the +configured `troubleshooting_log` (default `TROUBLESHOOTING.md`). **Create it if missing; append to the +bottom if it exists — never a fresh file each time.** Format each entry as: a one-line title (date + +feature/branch), then **Cause / Resulting problem / Fix / Alternatives considered**. Record only +reusable traps, not one-off typos — this is an accumulating asset so the next person doesn't hit the +same wall. + +## Tooling notes + +- Reviewers see uncommitted work via `git diff` (assume a clean baseline before the unit). +- Codex unavailable → single Claude reviewer + a stated note that the full-review invariant is broken. +- `build`/`test`/`lint` and `gh` run via Bash. Prefer the repo's own scripts over ad-hoc commands. +- If a decision won't show up in a later code scan (a design fork, a rejection rationale, a schema + switch), write it down where the project keeps such notes so it isn't lost.