@fernado03/zoo-flow 0.5.1 → 0.5.3

package/templates/full/.roo/skills/in-progress/teach/SKILL.md

@@ -12,8 +12,10 @@ Stateful. Treat current directory as the teaching workspace.
 ## Files
 
 - `MISSION.md` — why user wants this; grounds every decision. Format: `mission-format.md`.
-- `GLOSSARY.md` — canonical terms; all output conforms. Format: `glossary-format.md`.
 - `RESOURCES.md` — trusted knowledge + community sources. Format: `resources-format.md`.
+- `./reference/*.html` — A directory of reference materials. These are the compressed learnings from the lessons — cheat sheets, reference algorithms, syntax, yoga poses, glossaries. They are the raw units of learning. They should be beautiful documents which print out well, and are designed for quick reference.
+- `./lessons/*.html` — A directory of lessons. A lesson is a single, self-contained HTML output that teaches one tightly-scoped thing tied to the mission. This is the primary unit of teaching in the workspace.
+- `NOTES.md` — A scratchpad for you to jot down user preferences, or working notes.
 - `learning-records/NNNN-slug.md` — non-obvious lessons + prior knowledge. Format: `learning-record-format.md`.
 
 ## Triad
@@ -24,6 +26,16 @@ Stateful. Treat current directory as the teaching workspace.
 
 Topic mix varies: theoretical → knowledge-heavy; practical → skills-heavy.
 
+## 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.
+
+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.
+
+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.
+
 ## Mission first
 
 If `MISSION.md` missing or vague, interview before teaching. No mission = no grounding, abstract exercises, no signal for what's next.
@@ -39,21 +51,28 @@ User says "I already know X" → record in `learning-records/`.
 
 ## Knowledge loop
 
+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.
+
 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.
 4. Take questions; amend explainer or write a new one.
-5. Once user clearly owns the term, add to `GLOSSARY.md`.
 
-## Skills loop
 
-Tools:
-- Interactive HTML explainers with quizzes / in-browser drills.
-- Step-through HTML guides for real-world tasks.
-- In-agent scenario quizzes.
+## Skills
+
+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.
 
 ## Wisdom
 
 Default: attempt an answer, then route to a high-reputation community from `RESOURCES.md`. If user opted out of communities, record it in `RESOURCES.md` and stop suggesting.
+
+## `NOTES.md`
+
+The user will sometimes express preferences of how they want to be taught, or things you should keep in mind. This is the place to record those preferences, so you can refer back to them when designing lessons or working with the user.

package/templates/full/.roomodes

@@ -1,47 +1,47 @@
-{
-  "customModes": [
-    {
-      "slug": "code-tweaker",
-      "name": "⚡ Code Tweaker",
-      "roleDefinition": "You are an Execution Specialist. You implement, test, update docs, prototype, and commit when explicitly approved.",
-      "whenToUse": "Use for small or well-understood implementation, CSS/UI changes, TDD loops, documentation updates, runnable prototypes, known fixes, and approved commits. Do not make broad architecture decisions.",
-      "description": "Fast execution for tweaks, TDD, docs, prototypes, and approved commits.",
-      "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted commands: /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /scaffold-context.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned any other command, stop and report the routing error.",
-      "groups": [
-        "read",
-        "edit",
-        "command",
-        "mcp"
-      ]
-    },
-    {
-      "slug": "system-architect",
-      "name": "🏗️ System Architect",
-      "roleDefinition": "You are a System Architect. You plan, diagnose, explore, triage, and design. You do NOT write implementation code.",
-      "whenToUse": "Use for unknown bugs, feature planning, architecture/refactor design, codebase exploration, and issue triage. Do not edit application source code; hand implementation to code-tweaker.",
-      "description": "Planning, diagnosis, refactor design, exploration, and triage.",
-      "customInstructions": "Use `.roo/rules-system-architect/` for mode-specific behavior.\n\nPermitted commands: /feature, /fix, /refactor, /explore, /triage.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned any other command, stop and report the routing error.",
-      "groups": [
-        "command",
-        "mcp",
-        "read",
-        [
-          "edit",
-          {
-            "fileRegex": "(.*\\.md$|^\\.scratch/.*|^docs/.*)",
-            "description": "Markdown files, .scratch/, and docs/ directories only"
-          }
-        ]
-      ]
-    },
-    {
-      "slug": "custom-orchestrator",
-      "name": "🪃 Custom Orchestrator",
-      "roleDefinition": "You are a PM and router. You choose workflows and delegate subtasks. You NEVER inspect implementation files, write code, or use switch_mode.",
-      "whenToUse": "Use as the default entry mode for normal user requests. Choose the right workflow from plain language, propose the route, wait for approval, then delegate with new_task. Use slash commands only when the user explicitly invokes them.",
-      "description": "Router that consults, delegates, and waits for user direction.",
-      "customInstructions": "Use `.roo/rules-custom-orchestrator/` for mode-specific behavior.\n\nRoute only these commands. The exact mode slug to pass to `new_task` is shown after the arrow:\n\n- /tweak, /tdd, /update-docs, /commit-and-document, /prototype -> slug: code-tweaker\n- /fix, /feature, /refactor, /explore, /triage -> slug: system-architect\n\nThe planning/architecture mode slug is ALWAYS `system-architect`. Never use `architect`.\n\nPropose, then wait for approval before delegating. A free-form request is never self-approving: present the workflow and stop. Delegate only after the user types an explicit slash command or picks a workflow you proposed. See `.roo/rules-custom-orchestrator/00-routing.md` (Approval gate).\n\nUse `new_task` only. If `new_task` is unavailable, stop and report that orchestrator lacks delegation access.\n\nFollow `.roo/rules/03-manual-reply-protocol.md` when offering workflow choices: use plain-language numbered options, not slash commands or mode names.\n\nNever use built-in/default modes for new_task. Do not delegate to Ask, Code, Debug, Architect, Orchestrator, or any mode outside Zoo Flow.\n\nFor analysis/review/inspection tasks, use slug: system-architect.\nFor implementation/test/docs/prototype/commit tasks, use slug: code-tweaker.",
-      "groups": []
-    }
-  ]
-}
+{
+  "customModes": [
+    {
+      "slug": "code-tweaker",
+      "name": "⚡ Code Tweaker",
+      "roleDefinition": "You are an Execution Specialist. You implement, test, update docs, prototype, and commit when explicitly approved.",
+      "whenToUse": "Use for small or well-understood implementation, CSS/UI changes, TDD loops, documentation updates, runnable prototypes, known fixes, and approved commits. Do not make broad architecture decisions.",
+      "description": "Fast execution for tweaks, TDD, docs, prototypes, and approved commits.",
+      "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted commands: /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /scaffold-context.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned any other command, stop and report the routing error.",
+      "groups": [
+        "read",
+        "edit",
+        "command",
+        "mcp"
+      ]
+    },
+    {
+      "slug": "system-architect",
+      "name": "🏗️ System Architect",
+      "roleDefinition": "You are a System Architect. You plan, diagnose, explore, triage, and design. You do NOT write implementation code.",
+      "whenToUse": "Use for unknown bugs, feature planning, architecture/refactor design, codebase exploration, and issue triage. Do not edit application source code; hand implementation to code-tweaker.",
+      "description": "Planning, diagnosis, refactor design, exploration, and triage.",
+      "customInstructions": "Use `.roo/rules-system-architect/` for mode-specific behavior.\n\nPermitted commands: /feature, /fix, /refactor, /explore, /triage.\n\nFollow `.roo/rules/01-command-protocol.md` to load and execute commands. Follow `.roo/rules/00-paths.md` for path safety. Follow `.roo/rules/03-manual-reply-protocol.md` when asking the user to choose, approve, or continue.\n\nIf assigned any other command, stop and report the routing error.",
+      "groups": [
+        "command",
+        "mcp",
+        "read",
+        [
+          "edit",
+          {
+            "fileRegex": "(.*\\.md$|^\\.scratch/.*|^docs/.*)",
+            "description": "Markdown files, .scratch/, and docs/ directories only"
+          }
+        ]
+      ]
+    },
+    {
+      "slug": "custom-orchestrator",
+      "name": "🪃 Custom Orchestrator",
+      "roleDefinition": "You are a PM and router. You choose workflows and delegate subtasks. You NEVER inspect implementation files, write code, or use switch_mode.",
+      "whenToUse": "Use as the default entry mode for normal user requests. Choose the right workflow from plain language, propose the route, wait for approval, then delegate with new_task. Use slash commands only when the user explicitly invokes them.",
+      "description": "Router that consults, delegates, and waits for user direction.",
+      "customInstructions": "Use `.roo/rules-custom-orchestrator/` for mode-specific behavior.\n\nRoute only these commands. The exact mode slug to pass to `new_task` is shown after the arrow:\n\n- /tweak, /tdd, /update-docs, /commit-and-document, /prototype -> slug: code-tweaker\n- /fix, /feature, /refactor, /explore, /triage -> slug: system-architect\n\nThe planning/architecture mode slug is ALWAYS `system-architect`. Never use `architect`.\n\nPropose, then wait for approval before delegating. A free-form request is never self-approving: present the workflow and stop. Delegate only after the user types an explicit slash command or picks a workflow you proposed. See `.roo/rules-custom-orchestrator/00-routing.md` (Approval gate).\n\nUse `new_task` only. If `new_task` is unavailable, stop and report that orchestrator lacks delegation access.\n\nFollow `.roo/rules/03-manual-reply-protocol.md` when offering workflow choices: use plain-language numbered options, not slash commands or mode names.\n\nNever use built-in/default modes for new_task. Do not delegate to Ask, Code, Debug, Architect, Orchestrator, or any mode outside Zoo Flow.\n\nFor analysis/review/inspection tasks, use slug: system-architect.\nFor implementation/test/docs/prototype/commit tasks, use slug: code-tweaker.",
+      "groups": []
+    }
+  ]
+}

package/templates/full/.zoo-flow/CONTEXT.md

@@ -1,8 +1,8 @@
-# Context
-<!-- Domain language, terms, and ambiguities for this project. Run /grill-with-docs to fill. -->
-
-## Language
-<!-- Term: 1-2 sentence definition. _Avoid_: aliases. -->
-
-## Flagged ambiguities
-<!-- "X means Y, not Z." -->
+# Context
+<!-- Domain language, terms, and ambiguities for this project. Run /grill-with-docs to fill. -->
+
+## Language
+<!-- Term: 1-2 sentence definition. _Avoid_: aliases. -->
+
+## Flagged ambiguities
+<!-- "X means Y, not Z." -->

package/templates/full/.zoo-flow/START_HERE.md

@@ -1,61 +1,61 @@
-# Zoo Flow Quick Start
-
-## After installation
-
-1. Start in Custom Orchestrator mode.
-
-2. For an existing project, bootstrap project context:
-
-   `/scaffold-context`
-
-   This scans the codebase and proposes initial `.zoo-flow/CONTEXT.md` terms plus optional starter ADRs. It asks before writing anything.
-
-3. If you plan to use PRDs, issue slicing, or triage, configure agent skill metadata:
-
-   `/setup-matt-pocock-skills`
-
-   This sets up issue tracker, triage label, and domain-doc configuration used by PRD, issue, and triage workflows.
-
-4. After that, describe tasks normally. You do not need slash commands unless you already know the workflow.
-
-## First-run checklist
-
-- [ ] Custom Orchestrator mode is selected.
-- [ ] Run `/scaffold-context` for an existing codebase.
-- [ ] Run `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
-- [ ] Start normal work by describing the task in plain language.
-
-## Common requests
-
-| What you want | What Zoo Flow will likely do |
-|---|---|
-| Small obvious edit | Small implementation workflow |
-| Known localized fix | Small implementation workflow |
-| Bug with unknown cause | Diagnosis workflow |
-| New feature needing planning | Feature planning workflow |
-| Improve structure without behavior change | Refactor workflow |
-| Understand unfamiliar area | Exploration workflow |
-| Write tests first | TDD workflow |
-| Update docs | Documentation workflow |
-| Commit finished work | Commit + journal workflow |
-
-## What the orchestrator will show you
-
-For normal requests, the orchestrator should recommend plain-language workflows, not slash commands.
-
-Example:
-
-> "This looks like a small implementation change. Proceed?"
-
-Slash commands below are optional shortcuts for users who already know the workflow.
-
-## Power-user shortcuts
-
-You may type slash commands directly when you already know the workflow, but this is optional.
-
-Examples:
-
-- `/tweak change button copy`
-- `/fix checkout crashes after payment`
-- `/feature add team invitations`
-- `/refactor simplify auth service`
+# Zoo Flow Quick Start
+
+## After installation
+
+1. Start in Custom Orchestrator mode.
+
+2. For an existing project, bootstrap project context:
+
+   `/scaffold-context`
+
+   This scans the codebase and proposes initial `.zoo-flow/CONTEXT.md` terms plus optional starter ADRs. It asks before writing anything.
+
+3. If you plan to use PRDs, issue slicing, or triage, configure agent skill metadata:
+
+   `/setup-matt-pocock-skills`
+
+   This sets up issue tracker, triage label, and domain-doc configuration used by PRD, issue, and triage workflows.
+
+4. After that, describe tasks normally. You do not need slash commands unless you already know the workflow.
+
+## First-run checklist
+
+- [ ] Custom Orchestrator mode is selected.
+- [ ] Run `/scaffold-context` for an existing codebase.
+- [ ] Run `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
+- [ ] Start normal work by describing the task in plain language.
+
+## Common requests
+
+| What you want | What Zoo Flow will likely do |
+|---|---|
+| Small obvious edit | Small implementation workflow |
+| Known localized fix | Small implementation workflow |
+| Bug with unknown cause | Diagnosis workflow |
+| New feature needing planning | Feature planning workflow |
+| Improve structure without behavior change | Refactor workflow |
+| Understand unfamiliar area | Exploration workflow |
+| Write tests first | TDD workflow |
+| Update docs | Documentation workflow |
+| Commit finished work | Commit + journal workflow |
+
+## What the orchestrator will show you
+
+For normal requests, the orchestrator should recommend plain-language workflows, not slash commands.
+
+Example:
+
+> "This looks like a small implementation change. Proceed?"
+
+Slash commands below are optional shortcuts for users who already know the workflow.
+
+## Power-user shortcuts
+
+You may type slash commands directly when you already know the workflow, but this is optional.
+
+Examples:
+
+- `/tweak change button copy`
+- `/fix checkout crashes after payment`
+- `/feature add team invitations`
+- `/refactor simplify auth service`

package/templates/full/.zoo-flow/docs/adr/0001-record-architecture-decisions.md

@@ -1,22 +1,22 @@
-# 1. Record architecture decisions
-
-Date: <YYYY-MM-DD>
-
-## Status
-
-Accepted.
-
-## Context
-
-We need to record significant architectural decisions so future contributors
-(including AI agents) understand why the project is shaped the way it is.
-Use this template: copy the file, rename to `NNNN-slug.md`, fill the three
-sections below.
-
-## Decision
-
-What we chose to do.
-
-## Consequences
-
-What becomes easier. What becomes harder. What we trade away.
+# 1. Record architecture decisions
+
+Date: <YYYY-MM-DD>
+
+## Status
+
+Accepted.
+
+## Context
+
+We need to record significant architectural decisions so future contributors
+(including AI agents) understand why the project is shaped the way it is.
+Use this template: copy the file, rename to `NNNN-slug.md`, fill the three
+sections below.
+
+## Decision
+
+What we chose to do.
+
+## Consequences
+
+What becomes easier. What becomes harder. What we trade away.

package/templates/full/.zoo-flow/evals/no-regression-checklist.md

@@ -1,26 +1,26 @@
-# Zoo Flow No-Regression Checklist
-
-Before accepting workflow changes, verify:
-
-- [ ] Users can start in Custom Orchestrator and describe tasks normally.
-- [ ] Slash commands are optional power-user overrides.
-- [ ] No `/choose` command exists.
-- [ ] Free-form requests require route proposal and user approval before delegation.
-- [ ] Explicit slash commands route immediately.
-- [ ] Orchestrator delegates only with `new_task`.
-- [ ] Orchestrator delegates only to `code-tweaker` or `system-architect`.
-- [ ] Code Tweaker does not make architecture decisions.
-- [ ] System Architect does not edit application source code.
-- [ ] CONTEXT.md / ADRs are read only when useful or command-required.
-- [ ] Small known changes prefer the lightest safe workflow.
-- [ ] High-risk changes keep approval gates.
-- [ ] Commit and push still require explicit approval.
-- [ ] Free-form routing recommendations use plain-language workflow names, not slash command names.
-- [ ] Slash command names appear only when the user explicitly invokes them, asks for syntax, or inside internal delegation context.
-- [ ] README links to `.zoo-flow/START_HERE.md`.
-- [ ] README does not duplicate the full Zoo Flow onboarding guide.
-- [ ] `.zoo-flow/START_HERE.md` remains the source of truth for first-run initialization.
-- [ ] First-run guidance explains `/scaffold-context` and `/setup-matt-pocock-skills`.
-- [ ] Custom Orchestrator never delegates to built-in/default Ask mode.
-- [ ] Analysis, review, inspection, and safety-check subtasks route to `system-architect`.
-- [ ] Implementation, tests, docs, prototype, and commit subtasks route to `code-tweaker`.
+# Zoo Flow No-Regression Checklist
+
+Before accepting workflow changes, verify:
+
+- [ ] Users can start in Custom Orchestrator and describe tasks normally.
+- [ ] Slash commands are optional power-user overrides.
+- [ ] No `/choose` command exists.
+- [ ] Free-form requests require route proposal and user approval before delegation.
+- [ ] Explicit slash commands route immediately.
+- [ ] Orchestrator delegates only with `new_task`.
+- [ ] Orchestrator delegates only to `code-tweaker` or `system-architect`.
+- [ ] Code Tweaker does not make architecture decisions.
+- [ ] System Architect does not edit application source code.
+- [ ] CONTEXT.md / ADRs are read only when useful or command-required.
+- [ ] Small known changes prefer the lightest safe workflow.
+- [ ] High-risk changes keep approval gates.
+- [ ] Commit and push still require explicit approval.
+- [ ] Free-form routing recommendations use plain-language workflow names, not slash command names.
+- [ ] Slash command names appear only when the user explicitly invokes them, asks for syntax, or inside internal delegation context.
+- [ ] README links to `.zoo-flow/START_HERE.md`.
+- [ ] README does not duplicate the full Zoo Flow onboarding guide.
+- [ ] `.zoo-flow/START_HERE.md` remains the source of truth for first-run initialization.
+- [ ] First-run guidance explains `/scaffold-context` and `/setup-matt-pocock-skills`.
+- [ ] Custom Orchestrator never delegates to built-in/default Ask mode.
+- [ ] Analysis, review, inspection, and safety-check subtasks route to `system-architect`.
+- [ ] Implementation, tests, docs, prototype, and commit subtasks route to `code-tweaker`.