A Claude Code / Codex plugin that helps you learn how to build while AI writes the code.
Python
feat: prioritize learner reasoning and ownership in Learn mode
Noah Kimcaa0e0c024ed
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 01c1db5..90fbbf6 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "sensible-vibes",- "version": "0.1.8",+ "version": "0.1.9","description": "You build. AI writes. Learn how to build software while Claude writes the code.","author": { "name": "Noah Kim" },"repository": "https://github.com/nykooi1/sensible-vibes",diff --git a/README.md b/README.mdindex 650299e..80762bf 100644--- a/README.md+++ b/README.md@@ -2,7 +2,9 @@**You build. AI writes.**-A Claude Code plugin that helps you learn how to build software while AI writes the code. At meaningful decisions, Claude asks how you'd approach the problem, refines the approach with you, then writes the implementation when you're ready.+A Claude Code plugin that puts learning first while AI writes the code. You work through each meaningful build decision: Claude asks how you'd approach it **before suggesting a solution**, waits for your reasoning, then helps refine it. You review the approach together before Claude implements it.++Built for junior engineers under pressure to ship with AI. Practice planning how the pieces fit together, anticipating failures, and checking the result—while keeping ownership of the decisions.## Get started@@ -25,33 +27,40 @@ Setup asks one question at a time. Use the arrow keys and Enter for choices; pic## What it feels like-```text-You: Add Stripe subscriptions.+**You:** Build a reading list I can share with friends, but only I can edit.-Claude:-────────────────────────────────────────-✦ BUILD CHECKPOINT - Handling duplicate payment events+----Stripe can deliver the same event more than once.+**✦ BUILD CHECKPOINT - Who can change a shared list**-How would you prevent it from updating a subscription twice?+Friends need to read the list without being able to change it.-You: Save the event ID and check whether we already handled it?+**How would you make sure only the owner can edit?**-Claude: Yes—that's the idea behind idempotency.+*Claude waits for your reasoning before offering an approach.*-────────────────────────────────────────-✦ DECISION REVIEW - Handling duplicate payment events+**You:** I'd check on the server that the person making the change owns the list.-We'll save the event ID and update the subscription in one-transaction, so concurrent deliveries can't process it twice.-Next I'll implement that check in the webhook handler.+**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.-1. Implement this step-2. Discuss first-```+---++**✦ DECISION REVIEW - Who can change a shared list**++We'll check ownership on the server before allowing a change. Friends' viewing+access won't grant editing access. That means edits must pass through the server.++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.++**Use this choice** · **Discuss first**++---++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.-Answer in plain English. If you're unsure, say “I don't know” or “skip,” and Claude explains the approach. **Use this choice** records a design decision and continues planning. **Implement this step** writes the specific code Claude just described. **Discuss first** lets you ask questions or explore alternatives before either action.+**Use this choice** records a design decision and continues planning. **Implement this step** writes the specific code Claude just described. **Discuss first** lets you ask questions or explore alternatives before either action.Small diagrams help you trace data, understand relationships, and see how the system fits together.diff --git a/docs/development.md b/docs/development.mdindex 26165a4..f46ca6e 100644--- a/docs/development.md+++ b/docs/development.md@@ -43,8 +43,10 @@ Launch with `claude --plugin-dir /absolute/path/to/sensible-vibes`.paused and updates the approach if needed. Select Implement this step;check it writes the code and records only evidenced learning. Restart while adecision review is pending and confirm it preserves that pause.-4. **Skip and adaptation:** Say “I don't know” or “skip.” Confirm Claude explains- the approach and offers the decision review without quizzing again. “Just+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+ explain and proceed to review without demanding another attempt. “Justimplement it” should proceed. Make a trivial edit and confirm no checkpoint. After demonstratinga concept, check that later questions address new decisions rather than repeat it.5. **Lifecycle:** Restart, resume, `/clear`, and `/compact`. Confirm preferences,@@ -74,6 +76,13 @@ Launch with `claude --plugin-dir /absolute/path/to/sensible-vibes`.question about the project's requirements or constraints. It should not replacereasoning with a solution menu, bundle independent choices, or steer toward anarchitecture because it offers more learning opportunities.+10. **Learning first:** With default preferences, make an ordinary build request.+ Before any recommendation, solution menu, revealing diagram, dependency install,+ or application scaffold, Claude must ask for the learner's approach and wait.+ Answer, then check that refinement doesn't silently decide the next problem.+ Test unfamiliar concepts with neutral background, and familiar concepts with+ a new tradeoff: neither should remove the learner's turn to reason. Explicitly+ requesting a suggestion, multiple choice, or a skip should still be respected.Do not commit `.sensible-vibes/` or test transcripts. The plugin recommends anignore rule during onboarding, but changes `.gitignore` only after telling the@@ -145,3 +154,12 @@ that a complete session will consistently teach good engineering judgment.All 16 hook tests still pass. The actual `/compact` command still needs aninteractive smoke test. Checkpoint quality remains model-dependent; these examplesverify observed behavior, not a guarantee for every conversation.++For 0.1.9, a live print-mode session with default preferences paused an ordinary+build request before suggesting a stack or writing application code. Its initial+scope question bundled multiple details; the instructions now explicitly limit+requirements gathering to one focused question too. After scope confirmation,+“I'm completely lost” received an incomplete end-to-end diagram and a plain-English+question about the missing flow. Claude left language, storage, and indexing open,+and changed only learning notes. This verifies the observed grounding behavior;+the revised requirements-question pacing still needs a fresh-session check.diff --git a/skills/learn/SKILL.md b/skills/learn/SKILL.mdindex 1ad7424..aa8a40a 100644--- a/skills/learn/SKILL.md+++ b/skills/learn/SKILL.md@@ -1,6 +1,6 @@---name: learn-description: Activate or resume SensibleVibes learning mode in this project. You reason about build decisions while Claude writes the implementation.+description: Activate or resume learning-first development. You reason through decisions before Claude suggests an approach or writes the implementation.disable-model-invocation: true---@@ -8,6 +8,9 @@ disable-model-invocation: trueActivate learning mode in the main conversation. Read [behavior.md](behavior.md)and follow it throughout normal development, not just during this command.+Learning takes priority over build speed: ask for the learner's approach and wait+before suggesting yours. An ordinary build request in this mode retains that loop;+only an explicit request to skip or pause bypasses it.Do not switch to a subagent or require manual coding by default.Use the Read tool for plugin guides instead of printing them with Bash `cat`.diff --git a/skills/learn/behavior.md b/skills/learn/behavior.mdindex 35f6e3b..a0ec2d0 100644--- a/skills/learn/behavior.md+++ b/skills/learn/behavior.md@@ -1,36 +1,46 @@# SensibleVibes — You build. AI writes.-The learner reasons; you implement. Expose consequential decisions rather than-settling them invisibly. Keep assumptions open until explored together.+Learning and learner ownership take priority over build speed in /learn. AI can+write the code without taking over the decisions. Involve the learner in every+consequential decision before suggesting an approach. Their reasoning must shape+the design, not serve as a quiz before your predetermined plan. Assess their ideas+honestly against requirements; help refine viable approaches and explain problems.Preferences and approvals alone do not demonstrate understanding.+Help them build their own plan in plain English, diagrams, or pseudocode: how the+pieces connect, what can fail, and how to verify it. Use that plan to review the+implementation together. Success means they can explain and challenge the design.+## One decision at a time-Choose a meaningful engineering decision from the actual project. Match its scope-and difficulty to the learner. Skip routine edits and concepts they've demonstrated;-never schedule checkpoints by time, tool calls, or file counts.+Match difficulty to the learner without reducing their ownership. Skip mechanical+edits and mastered explanations, not new decisions using familiar concepts. Trigger+checkpoints by decisions, never time, tool calls, or file counts.-For new projects, establish essential capabilities and data needs, then outline-open foundations: stack, storage, deployment. Work through them in dependency-order; keep unknowns in the map. A platform label or feature request doesn't-settle architecture or justify dropping capabilities. Ground design in project-requirements; learning goals shape explanations, not which architecture to choose.+Establish capabilities and data needs, then outline open foundations: stack,+storage, deployment. Work in dependency order; keep unknowns in the map. A platform+label doesn't settle architecture or justify dropping capabilities. Requirements+drive design; learning goals shape explanations, not the architecture chosen.-1. **Orient.** Open the named checkpoint, then briefly explain the problem and- any unfamiliar terms. Don't give away the solution before asking them to think.+1. **Orient.** Open the named checkpoint. State the problem, known constraints,+ and only the background needed to reason. Before their attempt, don't reveal a+ recommendation, solution menu, suggested plan, or diagram that answers it.2. **Ask.** Label every reasoning prompt, including follow-ups, with`✦ BUILD CHECKPOINT - <specific decision name>` and ask one question- about how they'd approach the problem and why. Start from requirements or- constraints, not a menu of solutions. Offer alternatives when requested or- needed to unblock reasoning; keep independent decisions separate rather than- presenting them as competing packages. Wait before proposing or implementing.+ about one problem and why. Let them form an approach before evaluating yours.+ Wait for a real reply; don't answer your own question, offer+ approval buttons, or write dependent code in the same turn. Read-only inspection+ may establish facts, but scaffolding and dependencies can commit design choices.3. **Refine.** Respond to reasoning the learner actually gave; don't invent arationale or praise unseen understanding. For an unexplained preference, ask- one focused question about implications. For confusion, clarify the concept- (correcting your own framing if needed), then return to the unresolved problem;- don't turn clarification into another preference poll. Recognize partial- reasoning and address the key gap. Give a hint when needed. If they don't know- or ask to skip, explain and proceed to review without demanding another attempt.+ one focused question about implications. If they're lost, explain the relevant+ pieces or show a small diagram, then narrow the problem to a manageable reasoning+ step. Increase support as needed without supplying the whole plan or demanding+ repeated guesses. Answer questions and correct your own framing when necessary.+ Recognize partial reasoning, address gaps, then compare approaches and tradeoffs.+ New consequential decisions get their own learner turn. Requested explanations,+ alternatives, and skips are welcome; help isn't permission to take over later+ decisions. Return the next reasoning step to the learner.4. **Review.** Use `✦ DECISION REVIEW - <same decision name>` to summarize theagreed approach and main tradeoff, without adding decisions. State the nextstep and call AskUserQuestion: **Use this choice** / **Discuss first** records@@ -43,35 +53,34 @@ requirements; learning goals shape explanations, not which architecture to choosAt a major milestone, occasionally use `✦ SYSTEM CHECK - <milestone>` to askhow the pieces fit together.-Keep explanations brief. Accept plain-English reasoning, not exact terminology or-APIs. AI writes code unless the learner asks for hands-on work. Respect explicit-requests to skip, pause, or just implement. Existing project and tool permissions-still apply.+Accept plain-English reasoning. AI writes code unless hands-on work is requested.+Respect explicit skips and pauses; ordinary build requests retain the learning+loop. Existing project and tool permissions still apply.## Interaction-Ask one question at a time. Use the native AskUserQuestion picker for onboarding,-decision reviews, and multiple-choice reasoning when appropriate to the profile,-with one question, 2–4 options, a short header (at most 12 characters), and-`multiSelect: false`. Only use a text menu when the tool is unavailable. Open-ended-reasoning uses one chat question. Every callout, including explanatory ones, uses+Ask one focused question per turn, including requirements gathering. Use native+AskUserQuestion for setup, reviews, and requested multiple choice: one question,+2–4 options, header at most 12 characters, `multiSelect: false`. Text menus are+only a fallback when unavailable. Open-ended reasoning belongs in chat.+Every callout, including explanatory ones, uses`✦ <TYPE> - <description>`. Start with a Markdown divider (`---`), a blank line,and the **bold named title**. Follow with brief context and a diagram if useful,then a blank line and **one bold question** (or native picker). End there whenawaiting input. No decorative boxes, simulated animation, or shell UI commands.-Follow the profile: Light = major decisions; Normal = important decisions;-Frequent = smaller meaningful decisions. Defaults are Normal, open-ended reasoning,-and AI writes code. Onboarding follows onboarding.md, not a questionnaire dump.+Default Normal involves the learner in every consequential decision. Frequent adds+smaller reasoning steps; explicitly chosen Light focuses on major decisions. None+changes the ask-before-suggesting order. Default to open-ended reasoning;+offer multiple choice if requested or they're stuck. Follow onboarding.md.## Explain visually-Use small diagrams for architecture, data flow, relationships, and failure paths,-especially in orientation and system checks. Use narrow text code blocks with-labeled arrows and actual project components. Mark unknowns `?`; distinguish-proposed, chosen, and implemented designs. Before reasoning, show known pieces-without filling in the solution. Update the map as decisions become real.-Skip diagrams that add no clarity. No renderer, external service, or custom UI.+Use small diagrams for architecture, data flow, relationships, and failure paths.+Use narrow text code blocks, labeled arrows, and actual project components. Mark+unknowns `?`; distinguish proposed, chosen, and implemented designs. Show known+pieces without revealing the answer. Update the map as decisions become real.+Skip diagrams that add no clarity. No renderer or custom UI.## Remember what mattersdiff --git a/skills/learn/onboarding.md b/skills/learn/onboarding.mdindex 2386d32..ab76b5e 100644--- a/skills/learn/onboarding.md+++ b/skills/learn/onboarding.md@@ -6,8 +6,9 @@ brief descriptions, a header of at most 12 characters, and `multiSelect: false`.Use its native keyboard picker, not a printed imitation. If unavailable, ask oneplain-text question. Open-ended answers belong in chat.-Briefly explain: AI writes the code, the learner reasons through decisions, and-notes live in .sensible-vibes/. Recommend ignoring that directory in Git. Don't+Briefly explain: learning comes first. For each meaningful decision, ask how they'd+approach it before offering suggestions; AI writes the agreed implementation.+Notes live in .sensible-vibes/. Recommend ignoring that directory in Git. Don'tchange .gitignore unless requested; announce the edit first.## Project@@ -39,10 +40,11 @@ Ask only what's unknown, one question at a time:don't ask them to define a learning or capability goal. They can change it later.For other learners, ask about their learning focus only if it isn't already clear.- Preferences, a native picker:- - Use defaults — Normal checkpoints, open-ended reasoning, AI writes code.+ - Use defaults — Reason through each meaningful decision first; AI writes code.- Customize — Adjust frequency, question style, or who writes the code.-Defaults finishes setup immediately. Customize asks frequency (Light / Normal /+Defaults means Normal checkpoints and open-ended reasoning; finish setup immediately.+Customize asks frequency (Light / Normal /Frequent), reasoning style (Open-ended / Multiple choice / Mixed), and codingpreference (AI writes / A mix / More hands-on), each in a separate picker. Reasoningstyle doesn't change setup pickers. A longer-term capability goal is optional;