@fernado03/zoo-flow 0.7.15 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.7.15",
+  "version": "0.8.0",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"

package/templates/full/.roo/commands/teach.md

@@ -0,0 +1,8 @@
+---
+description: "Teach a topic over multiple stateful sessions. Tracks mission, glossary, resources, and learning records. Use when user asks to be taught a topic, wants to learn something, or mentions ongoing study."
+argument-hint: "What would you like to learn about?"
+---
+
+Skill: `.roo/skills/productivity/teach/SKILL.md`
+
+$ARGUMENTS

package/templates/full/.roo/skills/{in-progress → productivity}/teach/SKILL.md

@@ -26,22 +26,47 @@ Stateful. Treat current directory as the teaching workspace.
 
 Topic mix varies: theoretical → knowledge-heavy; practical → skills-heavy.
 
+### Fluency vs Storage Strength
+
+You should be careful to split between two types of learning:
+
+- **Fluency strength**: in-the-moment retrieval of knowledge
+- **Storage strength**: long-term retention of knowledge
+
+Fluency can give the user an illusory sense of mastery, but storage strength is the real goal. Try to design lessons which build long-term retention by desirable difficulty:
+
+- Using retrieval practice (recall from memory)
+- Spacing (distributing practice over time)
+- Interleaving (mixing up different but related topics in practice - for skill practice only)
+
 ## Lessons
 
 A lesson is the main thing you produce — the unit in which knowledge and skills reach the user. Each lesson is one self-contained HTML file, saved to `./lessons/` and titled `0001-<dash-case-name>.html`, where the number increments each time.
 
-A lesson should be beautiful — clean, readable typography and layout — since the user will return to these later to review.
+A lesson should be **beautiful** - clean, readable typography and layout since the user will return to these later to review. Think Tufte.
+
+The lesson should be short, and completable very quickly. Learners' working memory is very small, and we need to stay within it. But each lesson should give the user a single tangible win that they can build on. It should be directly tied to the mission, and should be in the user's zone of proximal development.
+
+If possible, open the lesson file for the user by running a CLI command.
 
-The lesson should teach ONE THING only. It should be completable very quickly, but give the user a tangible win that they can build on. It should be directly tied to the mission, and should be in the user's zone of proximal development.
+Each lesson should link via HTML anchors to other lessons and reference documents.
 
-Make opening a lesson as easy as possible — ideally a single CLI command the user can run to open the HTML file in their browser.
+Each lesson should recommend a primary source for the user to read or watch. This should be the most high-quality, high-trust resource you found on the topic.
+
+Each lesson should contain a reminder to ask followup questions to the agent. The agent is their teacher, and can assist with anything that's unclear.
 
 ## Mission first
 
 If `MISSION.md` missing or vague, interview before teaching. No mission = no grounding, abstract exercises, no signal for what's next.
 
+Missions may change as the user develops more skills and knowledge. This is normal - make sure to update the `MISSION.md` and add a learning record to capture the change. Confirm with the user before changing the mission.
+
 ## Zone of proximal development
 
+The user may specify an exact thing they want to learn. If they don't, figure out their zone of proximal development.
+
+Each lesson, the user should always feel as if they are being challenged 'just enough'.
+
 Pick next topic by:
 1. Read `learning-records/`.
 2. Align to `MISSION.md`.
@@ -49,10 +74,12 @@ Pick next topic by:
 
 User says "I already know X" → record in `learning-records/`.
 
-## Knowledge loop
+## Knowledge
 
 Knowledge should first be gathered from trusted resources. Use `RESOURCES.md` to keep track of them. Lessons should be littered with citations - links to external resources to back up any claim made. This increases the trustworthiness of the lesson, and gives the user a path to acquire more knowledge if they want to go deeper.
 
+For acquiring knowledge, difficulty is the enemy. It eats working memory you need for understanding.
+
 1. Pull from `RESOURCES.md`.
 2. Write HTML explainer to local file. Beautiful, glossary-correct. Litter with citations linking external resources backing every claim. Interactive: "try this" callouts to apply the knowledge.
 3. Give one-line CLI command to open it.
@@ -61,13 +88,15 @@ Knowledge should first be gathered from trusted resources. Use `RESOURCES.md` to
 
 ## Skills
 
-Skills should be taught through interactive lessons. There are several tools at your disposal:
+For skill acquisition, difficulty is the tool. Effortful retrieval is what builds storage strength. Skills should be taught through interactive lessons. There are several tools at your disposal:
 
 - Interactive lessons, using quizzes and light in-browser tasks
 - Lessons which guide the user through a list of real-world steps to take (for instance, yoga poses)
 - In-agent quizzes, where you ask the user scenario-based questions about what they've learned
 
-Every exercise closes a tight feedback loop.
+Each of these should be based on a **feedback loop**, where the user receives feedback on their performance. This feedback loop should be as tight as possible, giving feedback immediately - and ideally automatically.
+
+For quizzes, each answer should be exactly the same number of words (and characters, if possible). Don't give the user any clues about the answer through formatting.
 
 ## Wisdom