@fernado03/zoo-flow 0.7.14 → 0.7.16

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "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/rules-code-tweaker/01-completion.md

@@ -11,7 +11,21 @@ If you entered this window via `switch_mode` (you are mid-chain, not the entry p
 
 Before any `attempt_completion`, re-read the command body and confirm no later phase is assigned to another mode. If one is, `switch_mode` instead.
 
-`attempt_completion` must include:
+## How to call attempt_completion
+
+`attempt_completion` is a tool call with a `result` parameter. You MUST call it as a tool, not as plain text. Example:
+
+```
+attempt_completion(result="Done. Changed X in file Y. Status: complete. Next: /verify")
+```
+
+Do NOT:
+- Use `ask_followup_question` to present results (this keeps the subtask alive)
+- Write the result as plain text without calling the tool
+- Use `switch_mode` to return to the orchestrator (use `attempt_completion` instead)
+- Stop without calling any completion tool
+
+## What attempt_completion must include
 
 - what was done (exact scope)
 - files changed or inspected (paths)
@@ -20,10 +34,10 @@ Before any `attempt_completion`, re-read the command body and confirm no later p
 - remaining risk (what was not checked or is uncertain)
 - recommended next command (one only, no auto-launch)
 
-Write long output (verification report, diff summary) to `.scratch/` with a descriptive path. `attempt_completion` must include: file path where output was saved, brief status, and recommended next command. The user will open the file to see full details.
-
-Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.
-
+Write long output (verification report, diff summary) to `.scratch/` with a descriptive path. `attempt_completion` must include: file path where output was saved, brief status, and recommended next command. The user will open the file to see full details.
+
+Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.
+
 For non-trivial `/tdd`, `/fix`, `/feature`, `/refactor`, or R3+ `/tweak` work, recommend `/verify` before `/review` before `/commit-and-document`. Do not auto-launch those commands.
 
 If the user explicitly says to remember a project rule, or the same mistake has repeated, ask before appending a short lesson to `.zoo-flow/LESSONS.md`. Do not read or write lessons by default.

package/templates/full/.roo/rules-system-architect/02-completion.md

@@ -11,10 +11,26 @@ If you entered this window via `switch_mode` (you are mid-chain, not the entry p
 
 Before any `attempt_completion`, re-read the command body and confirm no later phase is assigned to another mode. If one is, `switch_mode` instead.
 
+## How to call attempt_completion
+
+`attempt_completion` is a tool call with a `result` parameter. You MUST call it as a tool, not as plain text. Example:
+
+```
+attempt_completion(result="Done. Explored X. Status: complete. Next: /feature")
+```
+
+Do NOT:
+- Use `ask_followup_question` to present results (this keeps the subtask alive)
+- Write the result as plain text without calling the tool
+- Use `switch_mode` to return to the orchestrator (use `attempt_completion` instead)
+- Stop without calling any completion tool
+
+## What attempt_completion must include
+
 Do not use `attempt_completion` to avoid required implementation work. Write the full output (review findings, exploration map, diagnosis, plan) to `.scratch/` with a descriptive path. `attempt_completion` must include: file path where output was saved, brief status, and recommended next command. The user will open the file to see full details.
 
-Halt for explicit user approval before testing a bug hypothesis, finalizing an architecture plan, publishing issues, or making irreversible decisions.
-
+Halt for explicit user approval before testing a bug hypothesis, finalizing an architecture plan, publishing issues, or making irreversible decisions.
+
 For non-trivial completed plans or reviews, recommend the next command only. Typical chain: implementation command -> `/verify` -> `/review` -> `/commit-and-document`. Do not auto-launch those commands.
 
 If the user explicitly says to remember a project rule, or the same mistake has repeated, ask before appending a short lesson to `.zoo-flow/LESSONS.md`. Do not read or write lessons by default.

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