@kidsinai/kids-opencode-plugin 0.0.1

package/course-packs/README.md

@@ -0,0 +1,38 @@
+# Course Packs
+
+> Bundled missions distributed with `kids-opencode`. Loaded by the plugin when `KIDS_COURSE_PACK=<pack-id>` is set in the environment (typically via `kids-opencode --course <pack-id>`).
+
+## V0 pack
+
+| ID | Title | Age | Missions | Stars budget | Status |
+|---|---|---|---|---|---|
+| `portfolio-site` | My personal portfolio website | 12+ | 3 | ~40⭐ | 🟡 content drafted, not workshop-tested |
+
+## Structure
+
+Each pack lives in `<pack-id>/` and has:
+
+```
+<pack-id>/
+├── pack.yml                  # Metadata: title, age band, missions, system_prompt overlay
+├── mission-1/
+│   ├── brief.md              # What the kid reads
+│   └── acceptance.yml        # Auto-check rules for completion
+├── mission-2/
+│   ├── brief.md
+│   └── acceptance.yml
+└── mission-3/
+    ├── brief.md
+    └── acceptance.yml
+```
+
+Content authoring: see [`docs/course-pack-authoring.md`](../docs/course-pack-authoring.md) (TODO).
+
+## V1+ candidate packs
+
+- `arduino-on-mbot` — Robotics Bridge first pack (V1+ depends on hardware tooling)
+- `simple-game` — A small JavaScript game (Snake, Pong, or kid-designed)
+- `data-story` — Pyodide-powered first data-vis story (V1+ depends on Pyodide integration)
+- `class-website` — Group project, multi-kid, shared schools setting
+
+Curriculum team owns the priority order.

package/course-packs/portfolio-site/mission-1/acceptance.yml

@@ -0,0 +1,57 @@
+# Acceptance criteria for Mission 1.
+# Evaluated by kids-opencode-plugin after session end, against the kid's project folder.
+
+mission_id: mission-1
+title: "Project setup + first HTML page"
+
+# Each check is an independent boolean. All must pass for the Mission to be marked complete.
+checks:
+  - id: index_html_exists
+    description: "An index.html file exists in the project folder"
+    type: file_exists
+    path: "index.html"
+
+  - id: index_html_has_html_tag
+    description: "index.html is a real HTML document (has the html element)"
+    type: file_contains_regex
+    path: "index.html"
+    pattern: "(?i)<html"
+
+  - id: index_html_has_body
+    description: "index.html has a body section"
+    type: file_contains_regex
+    path: "index.html"
+    pattern: "(?i)<body"
+
+  - id: index_html_has_heading
+    description: "index.html has at least one heading (the kid's name)"
+    type: file_contains_regex
+    path: "index.html"
+    pattern: "(?i)<h[1-6][^>]*>"
+
+  - id: index_html_has_substance
+    description: "index.html has at least 50 characters of actual content in its body"
+    # Heuristic: html minus tags should have >= 50 non-whitespace characters
+    type: file_text_length_min
+    path: "index.html"
+    min_chars: 100  # rough proxy; tag-stripped check is done in plugin
+
+  - id: file_in_project_only
+    description: "All files written in this session are inside the project folder (no path traversal)"
+    type: audit_log_check
+    audit_rule: "all_writes_within_cwd"
+
+# What the kid sees on completion
+completion_message: |
+  Mission 1 complete! 🎉
+
+  You made a real web page from scratch. Your name is now on a thing you can show people.
+
+  Ready for Mission 2 — making it look like *you*?
+
+# What gets logged for the parent dashboard
+parent_summary_fields:
+  - "Mission 1 completed at [timestamp]"
+  - "Total Stars used: [stars]"
+  - "Number of file edits: [count]"
+  - "Total session time: [duration]"

package/course-packs/portfolio-site/mission-1/brief.md

@@ -0,0 +1,83 @@
+# Mission 1 — Project setup + first HTML page
+
+> **Estimated time**: 30 minutes · **Estimated Stars**: 10 · **Goal**: see your name on a real web page in your browser within 5 minutes.
+
+---
+
+## What you're going to build
+
+A single file called `index.html` that has your name in big text, and a few sentences about you. Open it in your browser. Refresh the page when you change something. Show it to a parent or a friend at the end.
+
+That's it for Mission 1. We'll make it pretty in Mission 2 and add interactivity in Mission 3.
+
+---
+
+## How this works (read once)
+
+You're going to ask the AI mentor to help you. The AI won't just write the code for you — it'll ask what you want, then propose what to write, then ask **you** to approve before it writes anything.
+
+You'll see prompts like:
+
+> "I'm about to create a file called `index.html` with your name as the heading. OK to write?"
+
+Type **y** to approve, **n** to say no.
+
+If you don't know what something means, ask. The AI's job is to teach you, not just to crank out code.
+
+---
+
+## Steps (you'll go through these with the AI)
+
+1. **Get a project folder ready.** You should already be in one. If you don't know, type `pwd` (Mac/Linux) and see what folder you're in. The AI will help.
+
+2. **Start the agent.** From this folder:
+   ```
+   kids-opencode --course portfolio-site --mission mission-1
+   ```
+
+3. **Talk to the AI about what you want.** When it asks, tell it your name (whatever you want to put on the page — a nickname is fine), and a sentence or two about you. Examples:
+   - "I'm Mia, I'm 12, and I love making animations."
+   - "My name is Alex. I want to be a game designer when I grow up."
+   - "I'm into chess and origami and my dog Maple."
+
+4. **Approve the file create.** The AI will say "I'm going to make `index.html` with [your text]". Approve it.
+
+5. **Open the file in your browser.** On Mac: `open index.html`. On Linux: `xdg-open index.html`. Or just drag the file into a browser window.
+
+6. **Look at it!** Your text should appear in big letters. That's a real web page. You made it.
+
+7. **Show it.** Show a parent, a sibling, or a friend. Then come back and start Mission 2.
+
+---
+
+## When you get stuck
+
+- **The AI says it's going to do something I don't understand.** Ask it: "what does that mean?" Its job is to explain. If it doesn't explain well, ask again.
+- **My page is blank in the browser.** Tell the AI. It can read your `index.html` and check what's there.
+- **I made a typo and now nothing works.** Tell the AI. It will help you find the typo. Don't delete the whole file in panic.
+- **The AI is going too fast.** Tell it: "slow down" or "explain that step by step."
+- **I want to quit and come back later.** Press Ctrl+D or type `/quit`. Your file stays where it is. Run `kids-opencode --course portfolio-site --mission mission-1` again to come back.
+
+---
+
+## What you'll learn in this mission
+
+- HTML files are just text files with tags like `<h1>` (big heading) and `<p>` (paragraph)
+- A web browser reads an HTML file and shows it
+- Coding is mostly typing the right text in the right place
+- Working with an AI mentor means proposing, approving, and watching the result
+
+---
+
+## What's next
+
+Mission 2 — make it look beautiful with CSS. You'll pick your colours, your fonts, your layout.
+
+---
+
+## For parents / teachers
+
+This Mission targets:
+- **AU Digital Technologies F-10 curriculum** — knowledge & understanding of digital systems (ACTDIK023), production of digital solutions (ACTDIP030 / ACTDIP031), implementation of programs (ACTDIP031)
+- **Plan/approve UX habituation** — every Mission reinforces the kid's role as approver, not just consumer of AI output
+- **Concrete output for fridge-display** — within 30 minutes, a kid has produced and viewed real artifact on their own device. Fast positive feedback is critical for return engagement.

package/course-packs/portfolio-site/mission-2/acceptance.yml

@@ -0,0 +1,53 @@
+mission_id: mission-2
+title: "Style your page with CSS"
+
+checks:
+  - id: style_css_exists
+    description: "A style.css file exists in the project folder"
+    type: file_exists
+    path: "style.css"
+
+  - id: index_links_to_style_css
+    description: "index.html includes a link to style.css"
+    type: file_contains_regex
+    path: "index.html"
+    pattern: '<link\s+[^>]*href=["'']style\.css["'']'
+
+  - id: style_css_has_rules
+    description: "style.css has at least 5 CSS rules"
+    # Crude heuristic: each rule has a `{`. 5 opening braces ≈ 5 rules.
+    type: file_contains_count_min
+    path: "style.css"
+    pattern: '\{'
+    min_count: 5
+
+  - id: style_css_uses_colour
+    description: "style.css uses at least one colour property"
+    type: file_contains_regex
+    path: "style.css"
+    pattern: '(color|background|background-color)\s*:'
+
+  - id: style_css_uses_font
+    description: "style.css makes some choice about typography"
+    type: file_contains_regex
+    path: "style.css"
+    pattern: '(font-family|font-size|font-weight)\s*:'
+
+  - id: project_still_intact
+    description: "index.html from Mission 1 still has heading + body + content"
+    type: file_contains_regex
+    path: "index.html"
+    pattern: "(?i)<h[1-6]"
+
+completion_message: |
+  Mission 2 complete! 🎨
+
+  Your page looks like *you* now. That's design.
+
+  One more thing — let's make something happen when you click. Ready for Mission 3?
+
+parent_summary_fields:
+  - "Mission 2 completed at [timestamp]"
+  - "Total Stars used (this mission): [stars]"
+  - "Number of style changes proposed: [count]"
+  - "Total session time: [duration]"

package/course-packs/portfolio-site/mission-2/brief.md

@@ -0,0 +1,77 @@
+# Mission 2 — Style your page with CSS
+
+> **Estimated time**: 45 minutes · **Estimated Stars**: 15 · **Goal**: your page reflects you. Your colours, your fonts, your layout choices.
+
+---
+
+## What you're going to add
+
+CSS — Cascading Style Sheets. The rules that decide how things on your page **look**: colours, fonts, sizes, spacing.
+
+You'll create a new file called `style.css` and link it from your `index.html`.
+
+---
+
+## Steps
+
+1. **Continue from Mission 1.** Your `index.html` is sitting in your folder. Open it in the browser once to remind yourself what it looks like now.
+
+2. **Start the agent.**
+   ```
+   kids-opencode --course portfolio-site --mission mission-2
+   ```
+
+3. **Tell the agent your vibe.** What do you want your page to **feel** like?
+   - Calm? Warm? Cool? Bright? Soft? Bold? Retro? Modern?
+   - What colours do you like? (Pick 2-3. The AI can suggest some combinations if you're stuck.)
+   - What font feels right? Handwritten? Tech? Serif (like books)? Sans-serif (clean)?
+
+4. **Let the AI propose a style.** It will draft `style.css` and propose changes to `index.html` to link to it. You'll see the changes before they happen.
+
+5. **Approve, look, iterate.** Refresh your browser. Don't like it? Tell the AI what to change. "Make the heading bigger." "I want the background a bit warmer — more peach, less pink." "The font feels too formal."
+
+6. **Spend max 5 minutes on each round.** Don't get stuck. If something feels close-enough, move on. You can always come back.
+
+7. **Show it.** When it feels like *yours*, that's done.
+
+---
+
+## Examples to inspire (you don't have to copy any of these)
+
+- A nature lover: olive-green background, cream cards, serif font like Georgia
+- A gamer: dark background, bright accent colours, monospace font
+- A poet: cream background, dark serif, lots of breathing room
+- A maker: white background, primary colours, bold sans-serif headlines
+- A musician: deep purple, neon accents, an italic display font
+
+---
+
+## When you get stuck
+
+- **All my colours look bad together.** Ask the AI: "give me 3 colour palettes I can try" and pick one.
+- **The font won't change.** The AI is using web-safe fonts (Arial, Georgia, Helvetica). If you want fancier ones, that's a V1+ feature — we don't fetch fonts from the web in V0.
+- **My text is unreadable on my background.** Tell the AI. "Make the text darker / lighter so it stands out."
+- **I keep undoing my own changes.** That's OK. Ask the AI: "show me a diff of what we did this session" so you can compare.
+
+---
+
+## What you'll learn
+
+- CSS rules — selectors and properties
+- The cascade — how CSS layers on top of HTML
+- That "design" is choosing, not magic. You can change anything.
+
+---
+
+## What's next
+
+Mission 3 — a button that does something. A little bit of JavaScript.
+
+---
+
+## For parents / teachers
+
+This Mission targets:
+- **AU Digital Technologies F-10** — design thinking, iteration, evaluation against the user's intent (the kid is the user)
+- **Self-expression as motivator** — Mission 2 is the kid's chance to assert taste; that ownership is what brings them back for Mission 3
+- **Beware of perfectionism** — kids will spend 30 minutes on colour-picking if you let them. The 5-minute-per-round guidance is intentional.

package/course-packs/portfolio-site/mission-3/acceptance.yml

@@ -0,0 +1,66 @@
+mission_id: mission-3
+title: "Add an interactive button"
+
+checks:
+  - id: script_js_exists
+    description: "A script.js file exists in the project folder"
+    type: file_exists
+    path: "script.js"
+
+  - id: index_links_to_script_js
+    description: "index.html includes a <script> tag referencing script.js"
+    type: file_contains_regex
+    path: "index.html"
+    pattern: '<script\s+[^>]*src=["'']script\.js["'']'
+
+  - id: index_has_a_button
+    description: "index.html has at least one <button> element"
+    type: file_contains_regex
+    path: "index.html"
+    pattern: '(?i)<button[^>]*>'
+
+  - id: script_has_event_listener
+    description: "script.js wires up an event listener (or onclick) so the button does something"
+    # Allow either modern (addEventListener) or simple (onclick) wiring; both are valid
+    type: file_contains_any_regex
+    path: "script.js"
+    patterns:
+      - 'addEventListener'
+      - 'onclick'
+      - 'onClick'
+
+  - id: portfolio_pages_intact
+    description: "Mission 1 + Mission 2 outputs still present"
+    type: all_must_exist
+    paths:
+      - "index.html"
+      - "style.css"
+      - "script.js"
+
+completion_message: |
+  Mission 3 complete! 🚀
+
+  You built a real interactive web page from scratch. Content, style, and behaviour.
+
+  Open `index.html` in your browser one more time. Click your button. That's something you made.
+
+  📁 Your project lives in this folder. You can keep editing it any time.
+  🎓 You finished the Personal Portfolio Course Pack.
+
+  Want to keep going? Ask the AI: "What should I learn next?"
+
+parent_summary_fields:
+  - "Mission 3 completed at [timestamp]"
+  - "Course Pack 'portfolio-site' completed"
+  - "Total Stars used across pack: [stars_total]"
+  - "Final file count: [count]"
+  - "Total time across pack: [duration_total]"
+
+# Pack-level summary (emitted on Mission 3 completion)
+pack_completion_message: |
+  🎉 You finished the whole Course Pack.
+
+  What you built: a personal portfolio website with HTML, CSS, and JavaScript.
+  What you learned: how a web page works, how to design, how to debug.
+
+  Show your family. Then come back when you're ready for the next pack.

package/course-packs/portfolio-site/mission-3/brief.md

@@ -0,0 +1,89 @@
+# Mission 3 — Add an interactive button
+
+> **Estimated time**: 45 minutes · **Estimated Stars**: 15 · **Goal**: a button on your page that does something when you click it. Real JavaScript.
+
+---
+
+## What you're going to add
+
+A button. When the kid (or anyone) clicks it, something happens on the page.
+
+Pick **one** of these (or invent your own — tell the AI):
+
+- **Pop-up greeting**: Click → an alert says hi back
+- **Hide and show**: Click → a paragraph appears (or disappears)
+- **Random fact**: Click → a different sentence from a list of your own choices appears
+- **Counter**: Click → a number goes up by one
+- **Colour shift**: Click → the page background changes colour
+- **Confetti time**: Click → emoji burst on screen (a small JS confetti effect)
+- **The day teller**: Click → today's date is shown
+- **The compliment**: Click → a random compliment appears
+- **Whatever you want**: Tell the AI what the button should do. If it's doable in HTML/CSS/JS, the AI will help.
+
+---
+
+## Steps
+
+1. **Start the agent.**
+   ```
+   kids-opencode --course portfolio-site --mission mission-3
+   ```
+
+2. **Pick what the button does.** Tell the AI in your own words.
+
+3. **Approve the plan.** The AI will say something like: "I'll add a `<button>` to your `index.html`, write a JavaScript file `script.js`, and link it." Approve.
+
+4. **Try clicking the button.** Refresh the browser, click. Did it work?
+
+5. **If it didn't work**, tell the AI what happened ("nothing happened" or "I got an error in the console"). The AI can read your files and figure out why. **This is the most common bug in your career as a coder. Get used to it.**
+
+6. **Make it yours.** Once it works, tweak. Change the message. Change the colour. Add a second button. Whatever.
+
+---
+
+## A quick word about errors
+
+When something doesn't work in JavaScript, **open the browser console** (`Cmd-Option-J` on Mac, `Ctrl-Shift-J` on Linux/Windows in Chrome). Red text = the error. Tell the AI what the red text says.
+
+This is how all coders work. They don't memorise everything; they read errors and fix them.
+
+---
+
+## When you get stuck
+
+- **The button is there but nothing happens.** Tell the AI; it will read your files and check the wiring.
+- **The console has a red error I don't understand.** Copy-paste the error text to the AI. "What does this mean?"
+- **My button works once, then stops.** Tell the AI; common JS bug.
+- **I want to add a second button.** Go ahead — start a new round with the AI.
+- **I want my button to do something that involves the internet.** Not in V0. The AI will explain why; we keep things local for safety.
+
+---
+
+## What you'll learn
+
+- JavaScript files (`.js`) are linked from HTML the same way CSS is
+- An **event listener** waits for a click and runs code when it happens
+- Debugging — the most-real coding skill — is just reading the error and trying again
+
+---
+
+## What's next
+
+You're done with Mission 3 and the Course Pack! Your portfolio site has:
+- Real content (Mission 1)
+- Your visual style (Mission 2)
+- Something interactive (Mission 3)
+
+Show it to people. Then either:
+- **Pick a new Course Pack** (more coming after V0 launch)
+- **Keep iterating** — add more sections, more buttons, more pages. The AI is happy to keep helping.
+- **Take a break** — your project is saved in this folder; come back anytime.
+
+---
+
+## For parents / teachers
+
+This Mission targets:
+- **AU Digital Technologies F-10** — implementation of programs (ACTDIP031), debugging (ACTDIP030)
+- **Console literacy** — first exposure to browser dev tools is a big leap; expect kids to forget how to open the console multiple times
+- **Resilience to errors** — kids who quit at the first red text in the console are not ready for engineering yet. The agent's job is to model "errors are OK, here's how I read them." Workshop teachers should reinforce this orally.

package/course-packs/portfolio-site/pack.yml

@@ -0,0 +1,82 @@
+# Course Pack — Personal Portfolio Website
+#
+# V0 launch Course Pack. Goal: a 12+ kid builds and ships a single-page
+# HTML/CSS/JS personal portfolio website in 2 hours total, across 3 missions.
+#
+# Loaded by @kidsinai/kids-opencode-plugin when KIDS_COURSE_PACK=portfolio-site.
+
+id: portfolio-site
+version: 0.1.0
+title: "My personal portfolio website"
+short_description: "Build a one-page site about you — your hobbies, projects, what you care about."
+target_age_band: "12+"
+estimated_duration_minutes: 120
+estimated_stars_budget: 40
+
+learning_objectives:
+  - "Understand the basic anatomy of an HTML document (head, body, headings, paragraphs)"
+  - "Use CSS to apply colour, typography, and layout"
+  - "Use a small amount of JavaScript to add interactivity (a button that does something)"
+  - "Experience the agent-mentor workflow: plan, approve, observe, iterate"
+  - "Produce a single-file deliverable you can open in your browser and share with family"
+
+prerequisites:
+  - "Can read English at year-6 level"
+  - "Can use a terminal to type a command (with help)"
+  - "Knows what a web page is"
+  - "Has Kids OpenCode installed (`kids-opencode --version` works)"
+
+missions:
+  - id: mission-1
+    title: "Project setup + first HTML page"
+    estimated_minutes: 30
+    estimated_stars: 10
+    file: mission-1/brief.md
+    acceptance: mission-1/acceptance.yml
+  - id: mission-2
+    title: "Style your page with CSS"
+    estimated_minutes: 45
+    estimated_stars: 15
+    file: mission-2/brief.md
+    acceptance: mission-2/acceptance.yml
+  - id: mission-3
+    title: "Add an interactive button"
+    estimated_minutes: 45
+    estimated_stars: 15
+    file: mission-3/brief.md
+    acceptance: mission-3/acceptance.yml
+
+system_prompt_overlay: |
+  You are running the "My personal portfolio website" Course Pack with a kid who has likely never coded before.
+
+  Cultural context: this is a creative project about who the kid is. Encourage them to put their own personality
+  into it. Their favourite colours, their hobbies, the things they care about.
+
+  Pacing rules specific to this pack:
+  - Mission 1 should feel like a quick win — within 5 minutes of starting, the kid should see something
+    real in their browser. Even just "Hello, my name is …" rendered in big text counts.
+  - Mission 2 should let the kid express themselves visually. Encourage real choices about colours and
+    fonts; don't impose your defaults.
+  - Mission 3 introduces a tiny bit of JavaScript. Aim for celebration when their button works.
+  - At the end of each mission, briefly celebrate. "Look at what you made!" — concretely.
+
+  When the kid asks "what should I write about", offer a few prompts they can pick from:
+  - "What's a hobby you've gotten into recently?"
+  - "What's something you're proud of making or doing?"
+  - "If you could teach a friend one thing, what would it be?"
+  Don't put words in their mouth — let them choose.
+
+  Allowed tools: read, write, edit, glob, grep. Don't try to fetch anything from the web during this pack.
+  Don't use shell commands (you can't anyway).
+
+teacher_notes:
+  - "Pre-pack: ensure each kid has a project folder with write permissions"
+  - "If a workshop: project folders in `~/portfolio-{kidname}/`"
+  - "Plan for 20 minutes of buffer at the end for show-and-tell"
+  - "Common stuck point in Mission 2: kids spend 20 minutes on colour choice — give them a 5-min limit"
+  - "Common stuck point in Mission 3: JavaScript syntax errors — agent will help but teacher should be ready"
+
+revision_history:
+  - version: 0.1.0
+    date: 2026-05-15
+    note: "Initial Course Pack. Engineering-side draft."

package/package.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@kidsinai/kids-opencode-plugin",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "opencode plugin that turns opencode into a kid-safe coding mentor: kid-safe system prompt, tool whitelist (no shell), DeepRouter routing, audit emission.",
+  "license": "MIT",
+  "homepage": "https://github.com/kidsinai/kids-opencode",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kidsinai/kids-opencode.git",
+    "directory": "packages/kids-plugin"
+  },
+  "keywords": ["opencode", "opencode-plugin", "kids", "education", "k-12", "agentic"],
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "course-packs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14.0",
+    "@opencode-ai/sdk": ">=1.14.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.14.51",
+    "@opencode-ai/sdk": "^1.14.51",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}