Skip to content

A Claude Code / Codex plugin that helps you learn how to build while AI writes the code.

Python

feat: distinguish design confirmation from implementation approval

Noah Kim7f2585cf8beb
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 5c40fd9..5649197 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "vibe-wise",
- "version": "0.1.26",
+ "version": "0.1.27",
"description": "You build. AI writes. Learn how to build software while Claude writes the code.",
"author": { "name": "Noah Kim" },
"repository": "https://github.com/nykooi1/vibe-wise",
diff --git a/README.md b/README.md
index c0c6115..e509bed 100644
--- a/README.md
+++ b/README.md
@@ -27,39 +27,91 @@ Setup asks one question at a time. Use the arrow keys and Enter for choices; pic
## What it feels like
+A condensed example adapted from a real notes-app learning session. Later
+implementation steps are illustrative; intervening design discussions are omitted.
+
```text
You:
- Build a reading list I can share with friends, but only I can edit.
+ A note can be in several folders. Deleting a folder should delete its notes.
Claude:
- | ✦ Build checkpoint: Who can change a shared list |
+ | ✦ Build checkpoint: Deleting a shared note |
| :--- |
- | Friends need to read the list without being able to change it. |
- | **How would you make sure only the owner can edit?** |
+ | |
+ | "Trip ideas" is in both Travel and Summer. Deleting it removes it from both. |
+ | **When someone deletes Travel, what should happen to that note in Summer?** |
+ | |
+
+You:
+ Keep it in Summer. If it has no folders left, keep the note outside any folder.
+
+Claude:
+ That separates deleting a folder from deleting a note.
-[Claude waits for your reasoning before responding.]
+ | ✦ Build checkpoint: Connecting notes and folders |
+ | :--- |
+ | |
+ | **How would you represent which folders a note belongs to, without copying the note?** |
+ | |
You:
- I'd check on the server that the person making the change owns the list.
+ A links table with note_id and folder_id. Deleting a folder removes its links,
+ not the notes.
Claude:
- That puts the check somewhere visitors can't change it. We'd need to
- check every request that changes the list, even if the UI hides the edit button.
+ Each link records one membership. Several links can point to the same note;
+ a note with no links is unfiled.
+
+ notes ← folder links → folders
────────────────────────────────────────────────────────────
- ✦ Decision checkpoint: Who can change a shared list
+ ✦ Decision checkpoint: Folder membership
- Proposed: check ownership on the server before allowing a change. This keeps
- friends' viewing access separate from editing. Edits must pass through the server.
+ Proposed: store notes once and track folder membership in a links table.
+ Deleting a folder removes its links and keeps the notes. This supports multiple
+ folders per note; loading a folder's notes needs a lookup through those links.
- If confirmed, we'll record this access rule. Next, we'll work through how the
- server knows who's making the request; we haven't chosen that yet.
+ Confirming records this design. We still need to work through access rules
+ and technology choices before writing code.
❯ 1. Confirm and continue
This approach makes sense to me; move to the next piece.
2. Discuss
Ask questions or clarify anything that doesn't make sense before deciding.
+
+You:
+ Confirm and continue.
+
+[Later, after the remaining choices for this step are worked through...]
+
+Claude:
+ ────────────────────────────────────────────────────────────
+
+ ✦ Implementation checkpoint: Folder membership
+
+ I'll add the agreed tables and folder-deletion operation, then test that deleting
+ a folder preserves its notes and their membership in other folders.
+ This step builds storage behavior; the UI comes later.
+
+ ❯ 1. Implement this step
+ This approach makes sense to me; write the code for this step.
+ 2. Discuss
+ Ask questions or clarify anything that doesn't make sense before deciding.
+
+You:
+ Implement this step.
+
+[Claude writes the code and runs the tests.]
+
+Claude:
+ ────────────────────────────────────────────────────────────
+
+ ✦ Implementation report: Folder membership
+
+ - Added the schema migration: each membership references one note and one folder.
+ - Added folder deletion: removes the folder and its links, preserving note content.
+ - Added and ran tests for shared notes and notes left without a folder; both passed.
```
You don't need to know the answer already. Claude can explain unfamiliar concepts, sketch the relevant pieces, and help you tackle a smaller question. You stay involved in forming the plan. Answer in plain English; ask for more help or say “skip” whenever you want.
@@ -67,17 +119,30 @@ You don't need to know the answer already. Claude can explain unfamiliar concept
Describing what you want sets the requirements. Build Checkpoints ask you to work
out how it should function; a feature preference doesn't approve an architecture.
-**Confirm and continue** means the approach makes sense to you and you're ready for the next design decision. **Implement this step** writes the specific code Claude just described. **Discuss** gives you room to ask questions, clarify anything confusing, or explore alternatives before deciding.
+| Checkpoint | What happens |
+| --- | --- |
+| **Build** | You reason through how to approach the problem with Claude. |
+| **Decision** | Review the design. **Confirm and continue** records it and continues planning; no code yet. |
+| **Implementation** | Review the specific code changes. **Implement this step** authorizes Claude to make them. |
+
+These aren't three mandatory stops. When ready to code, the Implementation
+checkpoint also confirms the design, skipping a separate Decision checkpoint.
+Both confirmations offer **Discuss** to ask questions, clarify anything confusing,
+or explore alternatives before deciding.
When Claude proposes additional implementation details, it separates them from your
decisions in a short list or table explaining each addition and why it matters.
You can question or change any item before proceeding.
After implementation, Claude briefly explains what changed, how the key code works,
-why it fits your decision, and what was tested. Ask to dig deeper anywhere it's unclear.
+why it fits your decision, any tests it added or updated and what they cover, and
+which checks ran with their results. Ask to dig deeper anywhere it's unclear.
Small diagrams help you trace data, understand relationships, and see how the system fits together.
+[Recreate the notes-app demo](docs/demos/notion-dupe.md), including discussing
+password storage and questioning details Claude proposes.
+
## Make it yours
Experience changes the support you get, not your ownership of decisions:
diff --git a/docs/development.md b/docs/development.md
index 2f7349e..26a0764 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -31,6 +31,11 @@ backup/write failures, and restoring incomplete onboarding after reset.
Use an authenticated Claude Code session and temporary copies of projects.
Launch with `claude --plugin-dir /absolute/path/to/vibe-wise`.
+For a reusable walkthrough and opt-in live checks based on the playground notes
+app, see the [Notion-style demo](demos/notion-dupe.md). Its fixtures live in
+`tests/scenarios/notion-dupe.json`; `scripts/notion_demo.py` prepares fresh temporary
+projects and keeps generated conversations outside the repository.
+
1. **Fresh project:** Run `/vibe-wise:learn`. Choose a new project, describe
a small CLI, and accept preference defaults. Check that all three state files
are created, the map separates proposed from implemented components, and no
@@ -45,12 +50,13 @@ Launch with `claude --plugin-dir /absolute/path/to/vibe-wise`.
storage or retrying an external request. Confirm Claude asks one reasoning
question under a title naming the decision, before suggesting its own solution
or implementing the decision. Give a partial answer; check that
- it refines the answer, names the coding scope, and offers Implement this step /
+ it refines the answer, names the coding scope in an Implementation checkpoint,
+ and offers Implement this step /
Discuss. Select Discuss,
ask for clarification or propose an alternative, and confirm it stays
paused and updates the approach if needed. Select Implement this step;
check it writes the code and records only evidenced learning. Restart while a
- Decision Checkpoint is pending and confirm it preserves that pause.
+ confirmation is pending and confirm it preserves that pause.
4. **Skip and adaptation:** Say “I'm completely lost.” Confirm Claude explains
the relevant pieces and returns one manageable reasoning step, without dumping
a complete plan or repeatedly demanding guesses. Ask for an explanation or say “skip”; it should
@@ -68,7 +74,9 @@ Launch with `claude --plugin-dir /absolute/path/to/vibe-wise`.
into an implementation approval. Use different projects to avoid overfitting.
A design-only Decision Checkpoint should offer Confirm and continue / Discuss. Confirming
it records the choice and continues to unresolved decisions without writing
- application code. Implementation approval must name a concrete coding scope.
+ application code. An Implementation checkpoint must name a concrete coding scope.
+ When ready to code, it also confirms the design; don't require a separate
+ Decision checkpoint first. Several Build checkpoints may lead to one confirmation.
Option descriptions should invite clarification and express readiness to proceed;
choosing confirmation alone must not be recorded as demonstrated understanding.
If Claude proposes additional implementation details, check that a concise list
@@ -84,7 +92,8 @@ Launch with `claude --plugin-dir /absolute/path/to/vibe-wise`.
stay explicit; diagrams before reasoning must not silently decide the solution.
Build Checkpoints use a one-column Markdown table: the named title is the header,
context is an optional body row, and the bold question has its own row. Render
- the table directly, not in a code fence. Questions may be detailed; don't force
+ the table directly, not in a code fence, with empty table rows above and below
+ the content for spacing. Questions may be detailed; don't force
a short length or fixed width. Keep diagrams outside the card. Other callouts
retain the divider, bold title, and spacing. Every title keeps one leading `✦`
and its full label in sentence case, followed by a colon, without emojis
@@ -146,7 +155,9 @@ Launch with `claude --plugin-dir /absolute/path/to/vibe-wise`.
own structure, including through an explanatory diagram.
15. **Implementation report:** After an approved step, Claude should explain the
changed files, important code mechanics, connection to the learner's design,
- and actual verification results. Keep it concise, with optional deeper detail;
+ any tests added or updated and what they cover, and actual verification results.
+ Distinguish tests written from checks run; unrun checks must be explicit.
+ Keep it concise, with optional deeper detail;
avoid a line-by-line lecture or another mandatory approval. New design choices
discovered during implementation still need a reasoning checkpoint.
Feedback should be factual and specific, with no personal praise, hype, or
diff --git a/skills/learn/behavior.md b/skills/learn/behavior.md
index 7ee2619..32c6d2d 100644
--- a/skills/learn/behavior.md
+++ b/skills/learn/behavior.md
@@ -38,29 +38,40 @@ understanding. Skip mastered explanations, not new engineering decisions.
## Agree, implement, explain
-A **Build checkpoint** asks one focused reasoning question, which can invite a whole
-approach. Follow up only to resolve meaningful gaps.
-
-Before acting on a design, use a **Decision checkpoint**: briefly state the proposal,
-tradeoffs, and scope. Separate the learner's decisions from details you propose
+Use the checkpoint that matches the next step:
+
+- **Build checkpoint:** ask how the learner would approach the problem. Follow up
+ only to resolve meaningful gaps; one focused question can invite a whole approach.
+- **Decision checkpoint:** summarize the proposed design and tradeoffs. Offer
+ **Confirm and continue** ("This approach makes sense to me; move to the next piece.")
+ to record the design and continue planning. This does not authorize code changes.
+- **Implementation checkpoint:** describe the specific code changes you're ready
+ to make. Offer **Implement this step** ("This approach makes sense to me; write
+ the code for this step.") to authorize that scope.
+
+These aren't three mandatory stops. Several Build checkpoints may lead to one
+confirmation. When ready to code, the Implementation checkpoint also confirms the
+design; skip a separate Decision checkpoint.
+
+At either confirmation, briefly state the proposal, tradeoffs, and scope.
+Separate the learner's decisions from details you propose
adding. When adding details, show a compact **Proposed additions** table with
**Detail / Proposal / Why it matters**, or a short list for one or two items.
Keep each item brief so the learner can name anything to question or change;
omit boilerplate. These are proposals, not finalized decisions. Consequential
unresolved design choices still need learner reasoning, not just a row to approve.
-Offer **Confirm and continue** ("This approach makes sense to
-me; move to the next piece.") to record a design and continue planning, or
-**Implement this step** ("This approach makes sense to me; write the code for this
-step.") to authorize the named code changes. Pair either with **Discuss**
+Pair either confirmation with **Discuss**
("Ask questions or clarify anything that doesn't make sense before deciding.").
Wait for the answer; additions need discussion before confirmation.
Combine evaluation and confirmation when the reasoning already suffices.
Confirmation indicates readiness to proceed, not demonstrated understanding.
-After implementing, give up to three short, flat bullets: changed files, key code
-mechanics and why they fit, and actual verification. Offer deeper detail without
-another approval gate. A **System check** connects the pieces at milestones.
+After implementing, give an **Implementation report** with up to three short, flat
+bullets: changed files, key code mechanics and why they fit, and tests added or
+updated (if any), what they cover, and actual verification results. Distinguish
+writing tests from running them; say when checks weren't run. Offer deeper detail
+without another approval gate. A **System check** connects the pieces at milestones.
## Presentation and pace
@@ -74,15 +85,19 @@ a body row, and the bold question in its own row:
| ✦ Build checkpoint: <description> |
| :--- |
+| |
| <Context, when needed> |
| **<Reasoning question>** |
+| |
+Use empty table rows above and below the content for spacing, not blank lines
+that would break the table.
The question can be as detailed as needed; don't shorten it to fit a fixed width
or word count. Keep diagrams outside the table so they stay readable.
Other callouts use a divider, bold heading, and spacing. Use native AskUserQuestion
for choices (text fallback if unavailable). Reports need no question.
Headings use `✦ <Type>: <description>` with exact labels:
-`Build checkpoint`, `Decision checkpoint`, `System check`,
+`Build checkpoint`, `Decision checkpoint`, `Implementation checkpoint`, `System check`,
`Why this matters`, `Implementation report`.
Normal covers meaningful decisions; Light covers major ones; Frequent adds smaller