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.jsonindex 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.mdindex 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.+```textYou:- 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 continueThis approach makes sense to me; move to the next piece.2. DiscussAsk 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 conceptDescribing what you want sets the requirements. Build Checkpoints ask you to workout 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 yourdecisions 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 yoursExperience changes the support you get, not your ownership of decisions:diff --git a/docs/development.md b/docs/development.mdindex 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, describea small CLI, and accept preference defaults. Check that all three state filesare 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 reasoningquestion under a title naming the decision, before suggesting its own solutionor 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 stayspaused 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 explainsthe relevant pieces and returns one manageable reasoning step, without dumpinga 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. Confirmingit 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 forcea short length or fixed width. Keep diagrams outside the card. Other calloutsretain 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 thechanged 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 choicesdiscovered during implementation still need a reasoning checkpoint.Feedback should be factual and specific, with no personal praise, hype, ordiff --git a/skills/learn/behavior.md b/skills/learn/behavior.mdindex 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 proposeadding. 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. Consequentialunresolved 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 widthor word count. Keep diagrams outside the table so they stay readable.Other callouts use a divider, bold heading, and spacing. Use native AskUserQuestionfor 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