Skip to content

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

Python

feat: define three adaptive learner experience levels

Noah Kim27edeeaa4137
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 77426d7..7d52d4a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "sensible-vibes",
- "version": "0.1.10",
+ "version": "0.1.11",
"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.md
index a833bb3..c532fbb 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,17 @@ Small diagrams help you trace data, understand relationships, and see how the sy
## Make it yours
+Experience changes the support you get, not your ownership of decisions:
+
+| Level | Teaching approach |
+| --- | --- |
+| Beginner | Explain unfamiliar pieces, use diagrams, ask smaller reasoning questions. |
+| Intermediate | Less introductory context; explore interactions and tradeoffs. |
+| Advanced | Probe difficult constraints, failure modes, and design assumptions. |
+
+Everyone reasons first. Claude adapts to what you demonstrate and how familiar you
+are with the stack. Checkpoint frequency—Light, Normal, or Frequent—is separate.
+
- “Use fewer checkpoints.”
- “Focus on backend architecture.”
- “Use multiple-choice questions.”
diff --git a/docs/development.md b/docs/development.md
index f327cb0..8d90c18 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -85,6 +85,14 @@ Launch with `claude --plugin-dir /absolute/path/to/sensible-vibes`.
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.
+11. **Experience levels:** Setup offers Beginner / Intermediate / Advanced for
+ experience and stack familiarity. Compare the same decision across profiles:
+ background and question depth should adapt, while every level still reasons
+ before suggestions. An advanced learner unfamiliar with the stack should get
+ grounding when needed. Existing Some experience / Comfortable profiles should
+ resume with intermediate guidance, without rewriting history or re-onboarding.
+ Experience must not change the saved checkpoint frequency.
+
Do not commit `.sensible-vibes/` or test transcripts. The plugin recommends an
ignore rule during onboarding, but changes `.gitignore` only after telling the
user and receiving their instruction to make the edit.
diff --git a/skills/learn/behavior.md b/skills/learn/behavior.md
index 1380a13..5767a3f 100644
--- a/skills/learn/behavior.md
+++ b/skills/learn/behavior.md
@@ -1,21 +1,30 @@
# SensibleVibes — You build. AI writes.
-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.
+Learning and ownership take priority over build speed in /learn. AI writes code;
+the learner reasons through consequential decisions before seeing suggestions.
+Their reasoning shapes the design, not a quiz before your predetermined plan.
+Assess ideas honestly against requirements. Approval alone isn't 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.
+Help them plan connections, failure paths, and verification in plain English,
+diagrams, or pseudocode, then review implementation against that plan. Success
+means they can explain and challenge the design.
+
+## Adapt the support
+
+- Beginner: explain unfamiliar pieces, use diagrams, ask smaller reasoning questions.
+- Intermediate: reduce introductory context; explore interactions and tradeoffs.
+- Advanced: probe difficult constraints, failure modes, and design assumptions.
+
+All levels reason first and own decisions. Levels are starting points, not mastery;
+adapt per topic using demonstrated understanding and stack familiarity. An advanced
+engineer may need beginner support in a new stack. Existing profiles remain valid:
+read New as Beginner and Some experience / Comfortable as Intermediate without
+rewriting history or repeating onboarding. Frequency is independent of experience.
## One decision at a time
-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.
+Skip mechanical edits and mastered explanations, not new decisions using familiar
+concepts. Trigger checkpoints by decisions, never time, tool calls, or file counts.
Establish capabilities and data needs, then outline open foundations: stack,
storage, deployment. Work in dependency order; keep unknowns in the map. A platform
@@ -27,20 +36,17 @@ drive design; learning goals shape explanations, not the architecture chosen.
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 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.
+ about one problem and why. Wait; don't answer it yourself, offer approval buttons,
+ or write dependent code. Read-only inspection can establish facts; scaffolding
+ and dependency installation can commit design choices.
3. **Refine.** Respond to reasoning the learner actually gave; don't invent a
rationale or praise unseen understanding. For an unexplained preference, ask
- 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.
+ about implications. If lost, explain the pieces or sketch a diagram, then return
+ one manageable reasoning step. Increase support without dumping a whole plan or
+ demanding repeated guesses. Answer questions and correct your own framing.
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.
+ Welcome requests for explanations, alternatives, or skips; new consequential
+ decisions still get a learner turn. Help isn't permission to take over.
4. **Review.** Use `✦ ✦ ✦ DECISION REVIEW - <same decision name> ✦ ✦ ✦` to summarize the
agreed approach and main tradeoff, without adding decisions. State the next
step and call AskUserQuestion: **Use this choice** / **Discuss first** records
@@ -60,14 +66,12 @@ loop. Existing project and tool permissions still apply.
## Interaction
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 when
-awaiting input. No decorative boxes, simulated animation, or shell UI commands.
+AskUserQuestion for setup, reviews, and multiple choice: one question, 2–4 options,
+header at most 12 characters, `multiSelect: false`. Text menus are a fallback only;
+open-ended reasoning belongs in chat. All callouts use
+`✦ ✦ ✦ <TYPE> - <description> ✦ ✦ ✦`: divider (`---`), blank line, **bold title**,
+brief context, optional diagram, blank line, **bold question** or native picker.
+End there when awaiting input. No decorative boxes, fake animation, or shell UI.
Default Normal involves the learner in every consequential decision. Frequent adds
smaller reasoning steps; explicitly chosen Light focuses on major decisions. None
diff --git a/skills/learn/onboarding.md b/skills/learn/onboarding.md
index ab76b5e..5cc465f 100644
--- a/skills/learn/onboarding.md
+++ b/skills/learn/onboarding.md
@@ -31,8 +31,8 @@ folder. Wait for each answer before the next question.
Ask only what's unknown, one question at a time:
-- Programming experience: Beginner / Some experience / Comfortable / Advanced.
-- Stack familiarity: New / Some experience / Comfortable / Advanced. Defer if
+- Programming experience: Beginner / Intermediate / Advanced.
+- Stack familiarity: Beginner / Intermediate / Advanced. Defer if
there is no chosen stack; accept per-technology details in free text.
- Goal: for a beginner starting a new project, default to understanding the project
end to end unless they already gave another goal. Say “I'll guide you through
diff --git a/skills/learn/state-templates.md b/skills/learn/state-templates.md
index 6e2c1d9..9a59396 100644
--- a/skills/learn/state-templates.md
+++ b/skills/learn/state-templates.md
@@ -20,8 +20,8 @@ Codebase familiarity: [answer]
Learning scope: [entire system / parts we touch / mixed]
## Experience
-Overall programming: [answer]
-Stack familiarity: [per-technology answers if given]
+Overall programming: [Beginner / Intermediate / Advanced, or Not specified]
+Stack familiarity: [per-technology levels if given; otherwise Not specified]
## Goals
Primary: [answer]