@fernado03/zoo-flow 0.2.0 → 0.3.0

package/package.json

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

package/templates/full/.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md

@@ -23,10 +23,8 @@ _Avoid_: Purchase, transaction
 - MUST pick canonical term; aliases under `_Avoid_`.
 - MUST flag ambiguity + resolution.
 - Define term in 1–2 sentences: what it is, not behavior.
-- Include relationships/cardinality when obvious.
 - Include domain terms only; exclude generic programming terms.
 - Group under headings when useful.
-- Include example dialogue.
 
 ## Layout
 

package/templates/full/.roo/skills/in-progress/README.md

@@ -3,6 +3,7 @@
 Draft skills. Excluded from plugin/top README until stable.
 
 - **[review](./review/SKILL.md)** — Review diff on Standards + Spec axes.
+- **[teach](./teach/SKILL.md)** — Stateful teaching workspace (mission, glossary, resources, learning records).
 - **[writing-beats](./writing-beats/SKILL.md)** — Assemble article beat-by-beat.
 - **[writing-fragments](./writing-fragments/SKILL.md)** — Capture raw writing fragments.
 - **[writing-shape](./writing-shape/SKILL.md)** — Shape raw material into article.

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

@@ -0,0 +1,59 @@
+---
+name: teach
+description: Teach a topic over multiple stateful sessions, treating the current directory as a teaching workspace. Tracks mission, glossary, resources, and learning records to ground every session and pace the user inside their zone of proximal development. Use when user asks to be taught a topic, wants to learn something over time, or mentions ongoing study.
+disable-model-invocation: true
+argument-hint: "What would you like to learn about?"
+---
+
+# Teach
+
+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`.
+- `learning-records/NNNN-slug.md` — non-obvious lessons + prior knowledge. Format: `learning-record-format.md`.
+
+## Triad
+
+- **Knowledge** — drawn from `RESOURCES.md`. Never parametric.
+- **Skills** — exercises built from the knowledge.
+- **Wisdom** — real-world community interaction via `RESOURCES.md`.
+
+Topic mix varies: theoretical → knowledge-heavy; practical → skills-heavy.
+
+## Mission first
+
+If `MISSION.md` missing or vague, interview before teaching. No mission = no grounding, abstract exercises, no signal for what's next.
+
+## Zone of proximal development
+
+Pick next topic by:
+1. Read `learning-records/`.
+2. Align to `MISSION.md`.
+3. Pick tightest scope that still stretches the user.
+
+User says "I already know X" → record in `learning-records/`.
+
+## Knowledge loop
+
+1. Pull from `RESOURCES.md`.
+2. Write HTML explainer to local file. Beautiful, glossary-correct.
+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.
+
+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.

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

@@ -0,0 +1,35 @@
+# GLOSSARY.md Format
+
+Canonical language for the workspace. All explainers/exercises/records conform. Building it is itself learning: tight definition = compressed understanding.
+
+## Template
+
+```markdown
+# {Topic} Glossary
+
+{One or two sentence description of what this glossary covers.}
+
+## Terms
+
+**Hypertrophy**:
+Muscle growth driven by mechanical tension and metabolic stress over repeated training sessions.
+_Avoid_: Bulking, getting big
+
+**Progressive overload**:
+Systematically increasing the demand on a muscle over time — via load, volume, or intensity.
+_Avoid_: Pushing harder, levelling up
+
+**RPE (Rate of Perceived Exertion)**:
+A 1–10 self-rating of how hard a set felt, where 10 is failure and 8 means two reps left in the tank.
+_Avoid_: Effort score, intensity rating
+```
+
+## Rules
+
+- Add a term only when user demonstrates understanding. Glossary records compressed knowledge; it is not a dictionary to read.
+- Be opinionated. Pick one canonical term; list rivals as `_Avoid_`.
+- Tight: 1–2 sentences. Define what term IS, not how to do it.
+- Use glossary's own terms inside other definitions. That's how complex terms compress.
+- Group under subheadings when natural clusters emerge (`## Anatomy`, `## Programming`). Flat list fine otherwise.
+- Flag ambiguities. "In this workspace, 'set' means working set."
+- Revise in place. Stale entries lie.

package/templates/full/.roo/skills/in-progress/teach/learning-record-format.md

@@ -0,0 +1,46 @@
+# Learning Record Format
+
+Live in `learning-records/`. Sequential numbering: `0001-slug.md`, `0002-slug.md`. Create directory lazily on first record.
+
+Teaching equivalent of ADRs. Capture non-obvious lessons, key insights, stated prior knowledge. Steer future sessions; calibrate ZPD.
+
+## Template
+
+```markdown
+# {Short title of what was learned or established}
+
+{1-3 sentences: what was learned (or what prior knowledge was established), and why it matters for future sessions.}
+```
+
+That is the whole format. A single paragraph counts. Value is recording _that_ this is now known and _why_ it changes what to teach next.
+
+## Optional sections
+
+Use only when they add value. Most records skip these.
+
+- **Status** frontmatter (`active | superseded by LR-NNNN`) — when an earlier understanding is replaced.
+- **Evidence** — how the user demonstrated understanding. Useful when the claim might be revisited.
+- **Implications** — what this unlocks/rules out. Worth recording when non-obvious.
+
+## Numbering
+
+Scan `learning-records/`, take highest number, increment.
+
+## When to write
+
+Write when any are true:
+
+1. User demonstrated genuine understanding of something non-trivial — evidence, not exposure. Sets a new floor.
+2. User disclosed prior knowledge — "I already know X." Record it + claimed depth.
+3. Misconception corrected — high-value; predicts future stumbles.
+4. Mission shifted in response to learning — cross-link to `MISSION.md` and update it.
+
+### Skip
+
+- Material merely covered. Coverage ≠ learning.
+- Anything tersely captured in `GLOSSARY.md`. No duplication.
+- Session activity logs. Records are decision-grade, not a journal.
+
+## Supersession
+
+When a later record contradicts an earlier one, mark old one `Status: superseded by LR-NNNN`. Don't delete. The history is itself signal.

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

@@ -0,0 +1,30 @@
+# MISSION.md Format
+
+Lives at workspace root. Captures _why_ the user is learning this. Every teaching decision traces back here.
+
+## Template
+
+```markdown
+# Mission: {Topic}
+
+## Why
+{1-3 sentences. Concrete real-world goal. What changes in user's life/work when they have this skill? Avoid "to understand X" — push for the underlying outcome.}
+
+## Success looks like
+- {Specific observable thing user will be able to do}
+- {Another}
+
+## Constraints
+- {Time, budget, prior commitments, learning preferences}
+
+## Out of scope
+- {Adjacent topics user explicitly skips — protects ZPD}
+```
+
+## Rules
+
+- One mission per workspace. Two unrelated topics = two workspaces.
+- Concrete over abstract. "Run a half marathon by October" beats "get fitter."
+- Push back on vagueness. Bad mission > no mission.
+- Revise when goal moves. Stale mission steers wrong.
+- One screen max. Past that, it's a plan, not a compass.

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

@@ -0,0 +1,32 @@
+# RESOURCES.md Format
+
+Curated trusted sources. Knowledge for explainers comes from here, not parametric guesses. Wisdom routes to communities listed here.
+
+## Template
+
+```markdown
+# {Topic} Resources
+
+## Knowledge
+
+- [Book: _The Science and Practice of Strength Training_ — Zatsiorsky & Kraemer](https://example.com)
+  Foundational text on programming and adaptation. Use for: periodisation, recovery, intensity zones.
+- [Article: "How Much Should I Train?" — Greg Nuckols (Stronger By Science)](https://example.com)
+  Evidence-based review of volume landmarks. Use for: weekly set targets per muscle group.
+
+## Wisdom (Communities)
+
+- [r/weightroom](https://reddit.com/r/weightroom)
+  High-signal subreddit, moderated against bro-science. Use for: programme critique, plateau troubleshooting.
+- Local: Tuesday strength class at {gym name}
+  Use for: real-time coaching feedback on lifts.
+```
+
+## Rules
+
+- High-trust only. Primary sources, recognised experts, peer-reviewed work, well-moderated communities. Marketing-as-education stays out.
+- Annotate every entry. One line: what it covers + when to reach for it.
+- Group `## Knowledge` / `## Wisdom`. Mirrors the triad in `SKILL.md`. Single-group entries fine.
+- Surface gaps. `## Gaps` section lists missing areas the mission needs. Drives future search.
+- Prune ruthlessly. Remove wrong/shallow/off-mission. Five sharp > thirty mediocre.
+- Record community opt-out here so future sessions stop proposing them.