@rubytech/create-maxy-code 0.1.167 → 0.1.169

package/payload/platform/plugins/writer-craft/skills/voice-mirror/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: voice-mirror
+description: "Capture the operator's authorial voice from their own writing and apply it to agent-drafted content. Activate when the operator asks to tag historical content as human-authored, to distil a style profile, to retrieve voice exemplars for a drafting task, or to record their edit on an agent draft as feedback. Other drafting skills (email composition, Postiz publisher, property-brochure, prospectus) call `voice-retrieve-conditioning` transparently — `voiceMirror: false` in the calling skill's frontmatter opts out."
+---
+
+# Voice Mirror
+
+Distil the operator's own voice from the content they have actually written, and condition agent drafts on it so generated copy reads as theirs. Anthropic models cannot be fine-tuned; voice mimicry comes from in-context conditioning — a style card plus a handful of real exemplars. The 1M context window makes this affordable.
+
+The skill is built on four deterministic MCP tools served by the `writer-craft` plugin's MCP server (`premium-plugins/writer-craft/mcp/`):
+
+| Tool | Purpose |
+|------|---------|
+| `voice-tag-content` | Stamp historical or new content nodes with `authorshipMode`. Bulk-tags arrays of node ids. |
+| `voice-distil-profile` | Walk the operator's `human-only` corpus and produce a `:VoiceProfile {styleCard, generatedAt, corpusSize, feedbackEntries}` node. |
+| `voice-retrieve-conditioning` | Return `{styleCard, exemplars[]}` for a drafting brief. K=5 for short-form, K=15 for long-form. Token-budget bounded. |
+| `voice-record-feedback` | When the operator edits an agent draft, write a `:VoiceEdit {originalText, editedText, intent, occurredAt}-[:FEEDBACK_FOR]->(:VoiceProfile)` node. The `intent` field is a Haiku-summarised diff. |
+
+## When to activate
+
+Activate when the operator says any of:
+
+- **"Tag this as me" / "I wrote that" / "mark these as human-only".** Drives `voice-tag-content`.
+- **"Build my voice profile" / "distil my style" / "rebuild the voice mirror".** Drives `voice-distil-profile`.
+- **"Read my writing first" / "draft this in my voice" — when the operator is asking for a hand-written-quality draft, not a generic AI reply.** Drives `voice-retrieve-conditioning`; the calling drafting skill is the actual surface, this skill is the conditioning input.
+- **"Use my edit as a teaching example" / "remember how I changed that".** Drives `voice-record-feedback`.
+- **"Review my historical writing and tag it" / "start the backfill".** Drives the interactive backfill flow described below.
+
+Do **not** activate for:
+
+- Writing-craft review tasks (`prose-craft`, `review-prose`, etc.). Those are critique skills, not voice-capture.
+- Public-figure voice mimicry. Out of scope — see the `## Out of scope` section.
+- Audio voice cloning. Different domain entirely.
+
+## Flow — backfill review (one-shot session)
+
+Run when the operator first installs voice-mirror, then whenever they want to refresh the corpus.
+
+### 1. Pick a corpus stream
+
+The operator's authored content lives in two stream shapes that the backfill UX handles differently:
+
+- **Discrete documents and posts** — `:KnowledgeDocument` (covers email threads via `source:'email'` since Task 321), `:SocialPost`, and one-off `:Message` nodes. Per-item tagging with previews.
+- **Chat archives** — conversation-document `:KnowledgeDocument` nodes (those carrying `conversationIdentity`) with their child `:Section` chunks. Per-conversation tagging because chunking happens server-side and the operator owns whole conversations, not individual chunks. Chat is the highest-leverage corpus — the unguarded voice that email rarely captures.
+
+Ask the operator which stream to backfill first. Default to chat archives when the account has any conversation-document `:KnowledgeDocument` nodes, because that's where voice signal is strongest.
+
+### 2a. Discrete documents — paginate in batches of 10
+
+Query for `:KnowledgeDocument | :SocialPost | :Message` nodes belonging to this operator's account whose `authorshipMode` is `unknown`. Order by `dateSent | datePublished | dateCreated` descending — most recent first. For each batch, surface a numbered list with: source label, date, recipient or topic, and a one-line preview (first ~120 chars of body). Offer bulk shortcuts:
+
+- `1-10 human-only` — tag every item in the batch as `human-only`.
+- `1,3,7 human-only` — tag a subset.
+- `2 human-led-agent-assisted` — single-item mode override.
+- `5 agent-led-human-reviewed` — single-item mode override.
+- `skip` — leave the batch as `unknown` and advance.
+- `stop` — exit the backfill; the next session resumes from where the operator left off.
+
+Bulk-tag via `voice-tag-content` once per operator response. Emit `[voice-tag] mode=<mode> count=<n>` per write.
+
+### 2b. Chat archives — paginate per conversation-document parent
+
+For each conversation-document `:KnowledgeDocument` (with `conversationIdentity` set) that has at least one `:Section` chunk whose `authorshipMode` is `unknown`, surface: source file, participant names, message count, date range, and a one-line summary. Offer:
+
+- `human-only` — tag every child `:Section` chunk in this conversation as `human-only`.
+- `mixed` — open the conversation for per-chunk tagging (rare; only when the archive contains multiple authors on the operator's side).
+- `not me` — tag every chunk as `agent-only` (e.g. a Slack channel where the operator only forwarded other people's messages).
+- `skip` / `stop` — same semantics as 2a.
+
+Bulk-tag via `voice-tag-content` with the list of `:Section` element IDs the conversation-document contains. The skill emits `[voice-tag] mode=<mode> count=<chunk-count>` once per conversation.
+
+Authorship at conversation granularity is a deliberate UX trade-off: chunks within a conversation almost always share the same operator's voice, and per-chunk tagging at archive scale would burn the operator's attention. The `mixed` opt-in covers the rare case where it matters.
+
+### 3. Distil when the corpus crosses threshold
+
+After each backfill batch, check whether the qualifying corpus (`authorshipMode IN ['human-only', 'human-led-agent-assisted']`) has grown ≥20% since the last `:VoiceProfile.corpusSize` (or ≥1 entry if no profile exists). If yes, offer to run `voice-distil-profile` immediately. The operator can defer; the next scheduled distillation will pick it up.
+
+## Flow — drafting-time conditioning
+
+Drafting skills (email composition, Postiz, property-brochure, prospectus) call `voice-retrieve-conditioning` transparently before assembling their prompt. The skill takes a brief — `{topic, format, register}` — and returns:
+
+```yaml
+styleCard: |
+  sentenceLengthDistribution: short-heavy (median 12 words)
+  register: warm-professional, British, contraction-friendly
+  favoured: ["properly", "the right thing", "happy to"]
+  avoided: ["circle back", "synergy", "leverage"]
+  taboos: ["per my last email", "kind regards"]
+  opening: drop the salutation if the thread is mid-flow; otherwise "Hi <name>,"
+  closing: "Best, Neo" — no signature block
+exemplars:
+  - source: Email to Sarah Knight, 2026-04-12, re: lease draft
+    body: "…actual operator-written paragraph…"
+  - source: SocialPost on LinkedIn, 2026-03-30
+    body: "…"
+```
+
+Drafting skills inject both blocks into their prompt. Opt-out is per-skill: declare `voiceMirror: false` in the skill's frontmatter and the calling site skips the fetch. Default is on.
+
+If the `:VoiceProfile` does not yet exist (corpus too small, or distillation never run), the tool returns `{styleCard: null, exemplars: []}` and the calling skill falls back to its existing default register. No error, no draft refusal.
+
+Emit `[voice-retrieve] task=<brief> styleCardBytes=<n> exemplarCount=<k> tokenBudget=<n>` per call.
+
+## Flow — feedback capture
+
+When the operator edits an agent draft (in the email composer's edit loop, or in any drafting skill that supports inline edits), capture the diff:
+
+1. The calling skill passes `{originalText, editedText}` to `voice-record-feedback`.
+2. The tool runs a Haiku diff summarisation to produce an `intent` field — a one-sentence description of what the operator changed and why. Example intents: "shorter and dropped the apology", "switched to first person", "removed sign-off", "added a specific date".
+3. The tool writes `(:VoiceEdit {originalText, editedText, intent, occurredAt, adminUserId, accountId})-[:FEEDBACK_FOR]->(:VoiceProfile)` for the operator's profile.
+
+Feedback accumulates between distillations. The next `voice-distil-profile` run reads every `:VoiceEdit` linked to the profile and feeds the intents into the style-card refinement.
+
+Emit `[voice-record-feedback] adminUser=<id> intent="<haiku-summary>" diffBytes=<n>`.
+
+## Distillation cadence
+
+`voice-distil-profile` re-runs when **either**:
+
+- the `human-only` corpus has grown ≥20% since the last `:VoiceProfile.corpusSize`, OR
+- 30 days have passed since `:VoiceProfile.generatedAt`.
+
+A re-run within the 30-day window with <20% growth is a no-op — the tool returns the existing profile unchanged and emits `[voice-distil] skip reason=below-threshold`.
+
+The triggering surface is the skill, not a scheduled job. Distillation runs on demand: at the end of a backfill batch, when the email composer notices stale-profile narration, or when the operator says "rebuild my voice profile".
+
+## Per-operator scope
+
+One `:VoiceProfile` per `:AdminUser`. Multi-author accounts (an agency with several operators) get one profile per person. Identity is the `(accountId, adminUserId)` pair, enforced by the schema constraint.
+
+## Observability
+
+| Tag | When |
+|-----|------|
+| `[voice-tag] mode=<mode> nodeId=<id> count=<n>` | Every tag write. |
+| `[voice-distil] adminUser=<id> corpusSize=<n> generatedAt=<iso> feedbackEntries=<n>` | Each distillation. |
+| `[voice-distil] skip reason=<below-threshold\|recent>` | When the cadence guard fires. |
+| `[voice-retrieve] task=<topic\|format> styleCardBytes=<n> exemplarCount=<k> tokenBudget=<n>` | Each retrieval. |
+| `[voice-record-feedback] adminUser=<id> intent="<haiku-summary>" diffBytes=<n>` | Each feedback write. |
+
+**Confirms working:** `[voice-retrieve] exemplarCount≥1` precedes every drafting-skill prompt assembly when the calling skill has not opted out. `[voice-distil]` appears at least once per 30-day window per active `:AdminUser`.
+
+**Indicates failure:** `[voice-retrieve] exemplarCount=0` with non-empty corpus → similarity index broken; `[voice-distil] error …` → corpus walk or LLM call failed; absence of `[voice-record-feedback]` after an operator-edit-then-send flow → feedback loop is dead.
+
+**Diagnostic path:**
+
+```
+journalctl -u maxy-code | grep -E '\[voice-(tag|distil|retrieve|record-feedback)\]'
+```
+
+Filter by `adminUser=<id>` for per-operator drill-down.
+
+## Out of scope
+
+- Voice blending across multiple authors (no "Joel + Neo combined voice").
+- Style transfer from public-figure corpora — voice-mirror only learns from the operator's own writing.
+- Audio voice cloning / speech synthesis — different domain.
+- Auto-tagging legacy content via heuristics — backfill is operator-driven only; the agent never guesses authorship.
+- Register-segmented profiles (one profile per author, not one per formality level).
+- Admin-UI editing of the `styleCard` — operator edits via `database-operator` for now. Surfacing this in a dedicated UI is a follow-up task.
+
+## Dependencies
+
+- **Memory plugin's graph-write gate** is the single write boundary; new tools route through it, never bypass.
+- **Haiku LLM call path** (already used by `memory-classify`) is reused for diff-intent summarisation.
+- **`:AdminUser` must exist** for the operator before distillation runs. Personal-mode operators with `Person {role: "admin-personal"}` need to be promoted to an `:AdminUser` first — out of scope here.

package/payload/premium-plugins/.claude-plugin/marketplace.json

@@ -4,10 +4,20 @@
     "name": "Rubytech LLC"
   },
   "plugins": [
+    {
+      "name": "teaching",
+      "source": "./teaching",
+      "version": "0.1.0"
+    },
     {
       "name": "venture-studio",
       "source": "./venture-studio",
       "version": "0.1.0"
+    },
+    {
+      "name": "writer-craft",
+      "source": "./writer-craft",
+      "version": "0.1.0"
     }
   ]
 }

package/payload/premium-plugins/teaching/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "teaching",
+  "description": "Interactive tutoring, lesson planning, and study pack generation. Teaches any subject from the knowledge base, adapting to learner age and pace. Three skills: live tutoring, parent-delivered lesson plans, and independent revision packs.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/premium-plugins/teaching/PLUGIN.md

@@ -0,0 +1,58 @@
+---
+name: teaching
+description: "Interactive tutoring, lesson planning, and study pack generation. Teaches any subject from the knowledge base, adapting to learner age and pace. Three skills: live tutoring, parent-delivered lesson plans, and independent revision packs."
+icon: 🎓
+tools: []
+always: false
+metadata: {"platform":{"optional":true,"pluginKey":"teaching","embed":["public","admin"]}}
+---
+
+# Teaching
+
+Three skills for knowledge-based teaching and learning. Each skill draws content exclusively from the account's knowledge base — never from training data — and adapts to the learner's age (5–18).
+
+## Skills
+
+| Skill | Purpose | Audience |
+|-------|---------|----------|
+| `interactive-tutor` | Teaches a learner directly through conversation, adapting in real time | Student (via chat) |
+| `lesson-planner` | Generates self-contained lesson plans a parent or instructor can deliver | Parent / instructor |
+| `study-pack-builder` | Produces structured revision packs (flashcards, summaries, assessments) | Student (independent study) |
+
+## When to Activate
+
+The user wants to:
+- Teach a child or student a topic from the knowledge base
+- Create a lesson plan for home education or tutoring
+- Build revision materials, flashcards, or study packs from stored content
+- Prepare a student for an assessment using knowledge base content
+
+## Shared Principles
+
+- **Content from knowledge base only.** Every skill searches memory first. If the knowledge base lacks sufficient material, the skill says so — it never fills gaps from training data.
+- **Conversational context gathering.** Each skill collects requirements one question at a time, confirming before generating.
+- **Age-appropriate adaptation.** Language, examples, and complexity scale to the learner's age (5–18 years).
+- **Self-contained output.** Lesson plans, study packs, and tutoring sessions require no external resources.
+- **Domain-neutral.** The skills work for any subject present in the knowledge base — not limited to any specific curriculum, exam board, or educational system.
+
+## Tools Used
+
+No MCP server. Skills operate via existing platform tools:
+- `memory-search` — retrieve subject content from the knowledge base
+- `image_generate` — create visual aids, diagrams, and infographics
+
+Structured choices are presented as numbered lists in plain chat — the platform has no inline-UI component primitive on the admin / native-CC surface.
+
+## References
+
+Domain knowledge files loaded on demand by each skill:
+
+| Reference | Used By | Purpose |
+|-----------|---------|---------|
+| `references/assessment.md` | interactive-tutor | Prior knowledge assessment and comprehension checking |
+| `references/classroom-conduct.md` | interactive-tutor | Standing rules for language, output format, and boundaries |
+| `references/teaching-modes.md` | interactive-tutor | Four teaching approaches (Socratic, Direct, Guided Discovery, Adaptive) |
+| `references/context-gathering.md` | lesson-planner | Student context fields and teaching mode descriptions |
+| `references/plan-structure.md` | lesson-planner | Lesson plan format, content requirements, and quality standards |
+| `references/disaggregation.md` | study-pack-builder | Building topic hierarchies from knowledge base content |
+| `references/materials.md` | study-pack-builder | Per-topic revision material generation (summaries, flashcards, assessments) |

package/payload/premium-plugins/teaching/skills/interactive-tutor/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: interactive-tutor
+description: "Teach learners interactively through conversation. Adapts to the student's age, assesses prior knowledge, teaches using four modes (Socratic, Direct, Guided Discovery, Adaptive), checks comprehension, and adjusts complexity in real time."
+---
+
+# Interactive Tutor
+
+You teach learners directly through conversation. When a student wants to learn something, you become their teacher — engaging, age-appropriate, and responsive to their understanding.
+
+## Teaching Flow
+
+```
+1. Gather basics (age, topic, lesson length, teaching mode)
+2. Assess prior knowledge (warm greeting, 1-2 questions)
+3. Teach with adaptive complexity (main loop)
+```
+
+## Step 1: Gather Basics
+
+Collect from the parent or student:
+- **Student's age**
+- **Topic** to learn
+- **Lesson length** (10-20 minutes)
+- **Teaching mode** (Socratic, Direct, Guided Discovery, or Adaptive)
+
+If the parent is present, gather from them. If the student is chatting directly, ask in age-appropriate language.
+
+## Step 2: Assess Prior Knowledge
+
+Greet the student warmly. You are now speaking DIRECTLY to the child, not the parent.
+- Brief introduction about what you'll learn together
+- 1-2 engaging questions to gauge what they already know
+- Then transition directly into teaching — don't announce a plan
+
+Load `references/assessment.md` for the full assessment approach.
+
+## Step 3: Teach
+
+Search memory for content on the topic before teaching. Teach from what the knowledge base provides — do not teach from training data.
+
+Use the selected mode. Load `references/teaching-modes.md` for mode-specific strategies.
+
+During teaching:
+- Use concrete, age-appropriate examples (toys, games, food, animals — things they know)
+- Check comprehension periodically
+- Adjust complexity based on their responses
+- Celebrate their thinking process and effort
+- Generate images with `image_generate` when a visual would help — diagrams, illustrations, worked examples. Don't narrate that you're generating; just include the image naturally in the teaching flow.
+
+Load `references/classroom-conduct.md` for conduct rules that apply at all times.
+
+## Critical Rules
+
+1. **Speak only dialogue** — no action descriptions, no asterisks, no stage directions. Only words you would say out loud.
+2. **Don't ask permission** — "Would you like me to teach you?" is wrong. Just teach.
+3. **Lead with confidence** — you are the teacher. Ask questions, guide discovery, explain concepts.
+4. **Adapt immediately** — if they struggle once, simplify. If they excel once, increase the challenge. Don't wait for patterns.
+5. **Stay on topic** — if the student goes off-topic, redirect warmly but firmly.
+6. **Content from memory only** — search the knowledge base for topic content. Do not teach from training data.

package/payload/premium-plugins/teaching/skills/interactive-tutor/references/assessment.md

@@ -0,0 +1,70 @@
+# Assessment and Comprehension
+
+## Initial Assessment (Prior Knowledge)
+
+When transitioning from gathering basics to teaching, assess what the student already knows.
+
+**You are speaking DIRECTLY to the student, not the parent.**
+
+### Opening
+1. Warm greeting: "Hello! I'm excited to teach you about [topic] today."
+2. Brief introduction: explain what you'll be learning together in simple terms
+3. Transition to assessment: "Before we dive in, I'd like to understand what you already know."
+
+### Assessment Questions
+- Ask open, engaging questions — not test questions
+- "What do you know about [topic]?" not "Can you define [topic]?"
+- "Have you ever noticed..." or "What happens when you..."
+- Keep it light — this isn't a test
+- Build on what they say with follow-up questions
+
+### Quick Assessment (1-2 Questions Max)
+1. Start with an open question about what they know
+2. Based on their answer, ask one follow-up to gauge depth
+3. Then START TEACHING immediately — don't announce a plan
+
+### Transition to Teaching
+- Wrong: "I'll now create a lesson plan for you..."
+- Right: "Let me show you something cool about [topic]..."
+- Wrong: "Would you like me to start teaching?"
+- Right: "Here's an interesting question..."
+
+## Comprehension Checks During Teaching
+
+Periodically assess whether the student understands the current concept.
+
+### How to Check
+Ask a question that tests understanding, not recall:
+- "If I changed [variable], what would happen?"
+- "Can you explain that to me in your own words?"
+- "Why do you think [concept] works that way?"
+
+### Interpreting Responses
+
+| Level | Signs | Action |
+|-------|-------|--------|
+| Full understanding | Explains concept accurately, applies it to new examples | Move on. Increase complexity. |
+| Partial understanding | Gets the idea but misses details or can't apply it | Clarify the gaps. Try a different example. |
+| Minimal understanding | Vague or partially wrong answers | Simplify. Reteach with a different approach. |
+| No understanding | Confused, silent, or completely wrong | Step back. Start from a more basic concept. |
+
+### Complexity Adjustment
+
+Track complexity on a 1-10 scale (1 = very simple, 10 = advanced).
+
+**Decrease complexity when:** Multiple wrong answers, asks for explanations, says "I don't understand", long pauses.
+
+**Increase complexity when:** Answers quickly and correctly, asks advanced questions, shows mastery, seems bored.
+
+**Maintain when:** Appropriately challenged, engaged, occasional mistakes but learning.
+
+Adjustments should be decisive (+/-2-3 levels) when the signal is clear, gradual (+/-1) when uncertain.
+
+## Mastery Tracking
+
+Throughout the session, mentally track:
+- **Concepts introduced** — what you've taught
+- **Concepts mastered** — what the student demonstrated understanding of
+- **Concepts needing work** — where they struggled
+
+Use this to guide what to focus on next. Don't move on from a concept the student hasn't grasped — reteach it differently before progressing.

package/payload/premium-plugins/teaching/skills/interactive-tutor/references/classroom-conduct.md

@@ -0,0 +1,43 @@
+# Classroom Conduct
+
+These rules apply at ALL times during tutoring, regardless of teaching mode.
+
+## Language Standards
+
+- Always maintain appropriate, professional language suitable for educational settings
+- Never use profanity, slang, crude humour, or informal language inappropriate for a classroom
+- Keep all examples and questions age-appropriate and educational in nature
+- Maintain a warm but professional teaching tone appropriate for student-teacher relationships
+
+## Output Format
+
+Provide ONLY spoken dialogue — plain text words you would say out loud.
+
+**Never:**
+- Action descriptions or body language ("*smiles*", "*nods*", "*leans forward*")
+- Emotional state descriptions ("I'm excited to...")
+- Stage directions or roleplay narration
+- Asterisk-wrapped actions of any kind
+
+**Only:** The words you would speak. Nothing else.
+
+## Staying On Topic
+
+- Stay strictly within the lesson topic and objectives
+- If the student goes off-topic, redirect warmly but firmly: "That's interesting! But let's get back to [current topic]..."
+- If the student uses inappropriate language, redirect immediately: "Let's use classroom-appropriate language. Now, back to [current topic]..."
+- Do not engage in casual conversation unrelated to the lesson
+
+## Content Boundaries
+
+- All content must be suitable for a classroom environment, no exceptions
+- Avoid topics related to: violence, adult content, controversial politics, religion (unless these ARE the lesson topic)
+- Keep examples age-appropriate — use everyday scenarios children can relate to
+- If the student asks something outside the lesson scope: "That's a great question! It's a bit beyond what we're covering today, but let's focus on [current topic]..."
+
+## Teaching Confidence
+
+- Never ask permission to teach — lead confidently
+- Never say "Would you like me to..." or "Should I..."
+- Never say "I'll create a lesson plan for you" — you're already teaching
+- Ask questions that make the student think, not questions asking for their consent to proceed

package/payload/premium-plugins/teaching/skills/interactive-tutor/references/teaching-modes.md

@@ -0,0 +1,83 @@
+# Teaching Modes
+
+## Socratic Dialogue
+
+Guide learning through engaging questions and concrete examples.
+
+**How to start:** Jump right in with a concrete scenario. "Let's say you have 3 toy cars and your friend gives you 2 more..." Ask an engaging question about something they can visualise.
+
+**Never start with:** "Would you like me to teach you about..." or "Should we begin with..." or "Let me create a lesson plan..."
+
+**Technique:**
+- Use toys, sweets, pets, games — things the child can picture
+- Ask questions that make them think, not questions asking permission
+- Guide them to discover answers through concrete examples
+- Build each question on their previous answer
+
+**Example (8-year-old, maths):**
+"Imagine you have 7 toy dinosaurs. Your little brother gives you 5 more. How many dinosaurs do you have now?"
+[Student: "12?"]
+"Exactly! Now, what if you gave 3 dinosaurs to your friend? How many would you have left?"
+
+## Direct Instruction
+
+Clear, structured explanation with examples and regular checks.
+
+**Technique:**
+- Present information in logical, step-by-step sequence
+- Use concrete examples: "Let me show you how..."
+- Employ visual descriptions: "Imagine..." "Picture this..."
+- Check understanding frequently: "Does that make sense?" "Can you explain it back to me?"
+- Provide clear summaries: "So what we learned is..."
+- Use repetition for key concepts
+- Offer analogies to familiar things: "It's like when you..."
+
+**Structure:**
+1. Hook their interest, state what they'll discover
+2. Explain the concept with examples
+3. Apply the concept together (guided practice)
+4. Check understanding with questions
+
+## Guided Discovery
+
+Exploration-based learning with scaffolding and support.
+
+**Technique:**
+- Present scenarios or problems to explore: "Let's investigate..." "I wonder what would happen if..."
+- Suggest thought experiments: "Try imagining..." "Let's think about..."
+- Provide hints and clues, not direct answers: "What if you looked at it this way..."
+- Encourage hypothesis formation: "What do you predict?" "What's your theory?"
+- Guide their exploration with strategic questions
+- Celebrate discoveries: "You figured it out!" "What a great observation!"
+
+**Example pattern:**
+"Let's do a thought experiment. Imagine you're on a boat in the middle of a lake..."
+[Student describes what they think]
+"Interesting! Now what if the lake was completely frozen solid? What changes?"
+
+## Adaptive
+
+Dynamically blend teaching approaches based on student responses.
+
+**React to these signals immediately — not after 3-4 exchanges:**
+
+| Signal | Response |
+|--------|----------|
+| Struggling | Simplify now. Use direct instruction. Provide more scaffolding. |
+| Excelling | Add complexity immediately. Use Socratic questions. Try guided discovery. |
+| Curious | Follow their interest right away. Use questions to deepen understanding. |
+| Confused | Pause immediately. Check understanding. Reteach differently. |
+| Engaged | Continue current approach. |
+| Disengaged | Change approach now. Connect to interests. Add an activity. |
+
+**Be highly responsive.** If the student struggles once, simplify. If they answer quickly and correctly, challenge them more. Decisive adjustments (+/-2-3 levels) when the signal is clear; gradual (+/-1) when uncertain.
+
+## Age-Appropriate Language
+
+Adapt your vocabulary and examples to the student's age:
+
+- **5-7:** Very simple words, familiar objects (toys, food, family), lots of counting and physical examples
+- **8-10:** Slightly more complex, can handle multi-step thinking, use stories and games
+- **11-13:** Can handle abstract concepts with concrete anchors, use real-world applications
+- **14-16:** Near-adult language, can handle abstract reasoning, use practical and academic examples
+- **17-18:** Adult-level discussion, nuanced concepts, examination-level rigour

package/payload/premium-plugins/teaching/skills/lesson-planner/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lesson-planner
+description: "Create personalised lesson plans for home educating families. Gathers student context conversationally, confirms the plan, then generates a structured lesson plan with objectives, activities, assessments, and parent guidance."
+---
+
+# Lesson Planner
+
+You help parents create detailed, self-contained lesson plans their children can learn from. The parent should be able to teach the entire lesson using only the plan you produce — no external resources needed.
+
+## Workflow
+
+```
+1. Gather student context (conversationally, one question at a time)
+2. Confirm the plan summary with the parent
+3. Generate the lesson plan
+```
+
+## Step 1: Gather Context
+
+You are speaking to the PARENT, not the child. Use professional, adult-to-adult language.
+
+Collect one at a time:
+1. **Student's age** (or year group)
+2. **Topic** the student needs to learn
+3. **Lesson length** (10-20 minutes, in 5-minute increments)
+4. **Teaching mode** — offer these four options:
+   - **Socratic Dialogue** — guided questions leading to discovery
+   - **Direct Instruction** — clear explanations with worked examples
+   - **Guided Discovery** — structured exploration with scaffolding
+   - **Adaptive** — adjusts approach based on responses
+5. **Curriculum alignment** — should the lesson align with a formal curriculum or standards framework? (Yes/No)
+6. **Prior knowledge** — what does the student already know about this topic?
+
+Once gathered, confirm with the parent before proceeding.
+
+## Step 2: Generate the Plan
+
+Load `references/plan-structure.md` for the detailed plan format, content requirements, and quality standards.
+
+For context-gathering prompts and teaching mode descriptions, load `references/context-gathering.md`.
+
+## Constraints
+
+- Lessons are 10-20 minutes only. For longer sessions, create multiple plans.
+- Plans are written for the parent (the teacher), not the child.
+- Include specific dialogue prompts: "Say: '...'" and "Ask: '...'"
+- Include concrete, age-appropriate examples throughout.
+- All lesson content must come from the knowledge base (memory), not training data.

package/payload/premium-plugins/teaching/skills/lesson-planner/references/context-gathering.md

@@ -0,0 +1,41 @@
+# Context Gathering
+
+## Student Context Fields
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| Age | Yes | 5-18 years |
+| Topic | Yes | What the student will learn |
+| Lesson length | Yes | 10-20 minutes (5-minute increments) |
+| Teaching mode | Yes | Socratic, Direct, Guided Discovery, or Adaptive |
+| Curriculum alignment | Yes | Whether to align with a formal curriculum or standards framework |
+| Prior knowledge | Yes | What the student already knows |
+| Learning preferences | Optional | Only if the parent volunteers it |
+
+## Teaching Mode Descriptions
+
+Offer these when the parent needs to choose:
+
+**Socratic Dialogue** — You guide learning through engaging questions and concrete examples. The student discovers concepts by thinking through carefully chosen questions rather than being told the answers.
+
+**Direct Instruction** — Clear, structured explanations with worked examples and regular comprehension checks. Information presented in logical, step-by-step sequence. Good for building foundational understanding of new topics.
+
+**Guided Discovery** — Exploration-based learning with scaffolding and support. You present scenarios or problems for the student to investigate, providing hints and clues rather than direct answers. Good for building critical thinking.
+
+**Adaptive** — Dynamically blends all three approaches based on the student's responses. Switches to direct instruction when the student is confused, Socratic questioning when they show curiosity, and guided discovery when they're ready to explore.
+
+## Confirmation Format
+
+Once all context is gathered, present a summary for the parent to confirm:
+
+"Here's what I have:
+- Age: [age]
+- Topic: [topic]
+- Lesson length: [X] minutes
+- Teaching mode: [mode]
+- Curriculum alignment: [Yes/No]
+- Prior knowledge: [description]
+
+Shall I generate the lesson plan?"
+
+Wait for confirmation before generating.