@fernado03/zoo-flow 0.9.1 → 0.10.0

package/templates/claude-code/.claude/skills/productivity/teach/SKILL.md

@@ -0,0 +1,116 @@
+---
+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.
+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`.
+- `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
+
+- **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.
+
+### 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. 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 `Bash` command.
+
+Each lesson should link via HTML anchors to other lessons and reference documents.
+
+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 via `AskUserQuestion` 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/` via `Read`.
+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
+
+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 via `Write`. Beautiful, glossary-correct. Litter with citations linking external resources backing every claim. Interactive: "try this" callouts to apply the knowledge.
+3. Give one-line `Bash` command to open it.
+4. Take questions; amend explainer or write a new one.
+
+
+## Skills
+
+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
+
+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
+
+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.
+
+## Complete
+
+When the user ends the teaching session or says "done" / "stop teaching":
+
+Return a summary with:
+- lessons created (count, paths)
+- mission status (created / updated)
+- learning records updated (count)
+- status (session complete / paused)

package/templates/claude-code/.claude/skills/productivity/write-a-skill/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: write-a-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Write A Skill
+
+## Process
+
+1. Gather: task/domain; use cases/triggers; scripts needed; references.
+2. Draft: concise `SKILL.md` via `Write`; reference files if `SKILL.md` >100 lines or distinct domains; scripts for deterministic repeated ops.
+3. Review with user via `AskUserQuestion`.
+4. Revise.
+
+## Structure
+
+```text
+skill-name/
+├── SKILL.md
+├── REFERENCE.md
+├── EXAMPLES.md
+└── scripts/
+    └── helper.js
+```
+
+## Frontmatter
+
+```md
+---
+name: skill-name
+description: Brief description. Use when [specific triggers].
+---
+```
+
+Description rules:
+- Max 1024 chars.
+- Third person.
+- First sentence = capability.
+- Second sentence = `Use when ...` triggers.
+
+## Scripts
+
+Add when: deterministic op; repeated code; explicit error handling needed.
+
+## Review checklist
+
+- [ ] Description has triggers.
+- [ ] `SKILL.md` under 100 lines.
+- [ ] No time-sensitive info.
+- [ ] Terminology consistent.
+- [ ] Examples concrete.
+- [ ] References one level deep.
+
+## Complete
+
+Return a summary with:
+- skill created (name, path)
+- files written (SKILL.md, references, scripts)
+- status (complete / blocked with reason)

package/templates/claude-code/.zoo-flow/CONTEXT.md

@@ -0,0 +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." -->

package/templates/claude-code/.zoo-flow/START_HERE.md

@@ -0,0 +1,28 @@
+# Zoo Flow Quick Start
+
+## After installation
+
+### For Claude Code users
+
+1. Open Claude Code in this project.
+2. Run `/scaffold-context` for an existing project, or `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
+3. Then describe tasks normally — Claude Code will read CLAUDE.md automatically.
+4. Slash commands like `/fix`, `/feature`, `/tweak` work the same way.
+
+### For Zoo Code users
+
+1. Reload VS Code and open Zoo Code.
+2. Switch to **Custom Orchestrator** mode.
+3. Run `/scaffold-context` for an existing project, or `/setup-matt-pocock-skills` if using PRDs, issue slicing, or triage.
+4. Then describe tasks normally.
+
+## What's installed
+
+- `.zoo-flow/CONTEXT.md` — domain language and project context
+- `.zoo-flow/project-profile.json` — project shape and configuration
+- `.zoo-flow/docs/adr/` — architecture decision records
+
+## Getting help
+
+Run `/grill-me` to stress-test your understanding of a plan or design.
+Run `/explore` to understand unfamiliar code before making changes.

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

@@ -0,0 +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.

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

@@ -0,0 +1,26 @@
+# Zoo Flow No-Regression Checklist
+
+Before accepting workflow changes, verify:
+
+- [ ] Users can describe tasks naturally and Claude Code reads CLAUDE.md.
+- [ ] Slash commands are optional power-user overrides.
+- [ ] Free-form requests require route proposal and user approval before delegation.
+- [ ] Explicit slash commands route immediately.
+- [ ] Architect profile does not edit application source code.
+- [ ] Implementer profile does not make architecture decisions without approval.
+- [ ] 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.
+- [ ] START_HERE.md includes both Claude Code and Zoo Code quick start sections.
+- [ ] `.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`.
+- [ ] Analysis, review, inspection, and safety-check subtasks use architect profile.
+- [ ] Implementation, tests, docs, prototype, and commit subtasks use implementer profile.
+- [ ] Verification requests use implementer profile.
+- [ ] Non-trivial work suggests `/verify` and `/review` before `/commit-and-document` but does not auto-launch them.
+- [ ] CLAUDE.md contains behavioral profiles, routing guide, delegation protocol, and global rules.
+- [ ] `.claude/commands/` contains all 25 command files with proper frontmatter.
+- [ ] `.claude/skills/` contains adapted skill files with Claude Code tool references.

package/templates/claude-code/.zoo-flow/evals/routing-cases.jsonl

@@ -0,0 +1,18 @@
+{"name":"small implementation","user":"Fix typo in README heading","expected_workflow":"small implementation","expected_command":"/tweak","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/tweak","implementer"],"risk":"R1","context_required":false}
+{"name":"test-first","user":"Add a slugify helper for article URLs. I want it test-first.","expected_workflow":"test-first","expected_command":"/tdd","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/tdd","implementer"],"risk":"R2","context_required":false}
+{"name":"documentation update","user":"The architecture docs describe an old checkout flow. Bring them in line with code.","expected_workflow":"documentation update","expected_command":"/update-docs","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/update-docs","implementer"],"risk":"R2","context_required":true}
+{"name":"commit and journal","user":"Commit the finished change and add a journal entry.","expected_workflow":"commit and journal","expected_command":"/commit-and-document","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/commit-and-document","implementer"],"risk":"R1","context_required":false}
+{"name":"prototype","user":"I am not sure if search ranking should run inline or in a queue. Try both.","expected_workflow":"prototype","expected_command":"/prototype","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/prototype","implementer"],"risk":"R2","context_required":false}
+{"name":"diagnosis","user":"Checkout randomly crashes after payment. It used to work.","expected_workflow":"diagnosis","expected_command":"/fix","expected_profile":"architect","must_require_approval":true,"must_not_include":["/fix","architect"],"risk":"R3","context_required":true}
+{"name":"feature planning","user":"Add team invitations with email invites and pending invite states.","expected_workflow":"feature planning","expected_command":"/feature","expected_profile":"architect","must_require_approval":true,"must_not_include":["/feature","architect"],"risk":"R4","context_required":true}
+{"name":"refactor planning","user":"The auth module is hard to change. Decouple provider-specific logic.","expected_workflow":"refactor planning","expected_command":"/refactor","expected_profile":"architect","must_require_approval":true,"must_not_include":["/refactor","architect"],"risk":"R4","context_required":true}
+{"name":"exploration","user":"I need to change billing but I do not know where that logic lives.","expected_workflow":"exploration","expected_command":"/explore","expected_profile":"architect","must_require_approval":true,"must_not_include":["/explore","architect"],"risk":"R2","context_required":false}
+{"name":"issue triage","user":"Triage these incoming support bugs into tracker issues.","expected_workflow":"issue triage","expected_command":"/triage","expected_profile":"architect","must_require_approval":true,"must_not_include":["/triage","architect"],"risk":"R2","context_required":false}
+{"name":"review","user":"Review this branch before I commit it.","expected_workflow":"review","expected_command":"/review","expected_profile":"architect","must_require_approval":true,"must_not_include":["/review","architect"],"risk":"R2","context_required":true}
+{"name":"verification","user":"Run tests for this change and make sure nothing broke.","expected_workflow":"verification","expected_command":"/verify","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/verify","implementer"],"risk":"R2","context_required":false}
+{"name":"R5 auth security migration","user":"Migrate auth session storage and preserve existing user sessions.","expected_workflow":"feature planning","expected_command":"/feature","expected_profile":"architect","must_require_approval":true,"must_not_include":["/feature","architect"],"risk":"R5","context_required":true}
+{"name":"explicit slash command approval","user":"/tweak rename the cancel button to close.","expected_workflow":"small implementation","expected_command":"/tweak","expected_profile":"implementer","must_require_approval":false,"must_not_include":["approval pending"],"risk":"R1","context_required":false}
+{"name":"free-form approval required","user":"Rename the cancel button to close.","expected_workflow":"small implementation","expected_command":"/tweak","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/tweak","implementer"],"risk":"R1","context_required":false}
+{"name":"no doc bloat for small tweak","user":"Change the Save button text to Submit.","expected_workflow":"small implementation","expected_command":"/tweak","expected_profile":"implementer","must_require_approval":true,"must_not_include":["architecture docs","domain docs","CONTEXT.md"],"risk":"R1","context_required":false,"no_doc_bloat":true}
+{"name":"diagnosis with cause unknown","user":"The payment webhook stopped firing after the last deploy.","expected_workflow":"diagnosis","expected_command":"/fix","expected_profile":"architect","must_require_approval":true,"must_not_include":["/fix","architect"],"risk":"R4","context_required":true}
+{"name":"context scaffolding","user":"This project has no CONTEXT.md yet. Bootstrap one.","expected_workflow":"context scaffolding","expected_command":"/scaffold-context","expected_profile":"implementer","must_require_approval":true,"must_not_include":["/scaffold-context","implementer"],"risk":"R2","context_required":false}

package/templates/claude-code/.zoo-flow/evals/routing-cases.md

@@ -0,0 +1,211 @@
+# Routing Eval Cases
+
+Use these cases to check whether the orchestrator chooses the expected workflow.
+
+In every case:
+
+- The user did **not** type a slash command.
+- A free-form request is never self-approving. The orchestrator proposes, then waits.
+- Slash commands, mode names, and executable routing text must not appear in clickable suggestions.
+- Slash commands are optional. The user should never be told to type one to use Zoo Flow.
+
+## Case 1 — Tiny copy change
+
+User:
+"Change the Save button text to Submit."
+
+Expected:
+Recommend the small implementation workflow.
+
+Must not:
+- Route to feature.
+- Read architecture docs by default.
+- Ask the user to type a slash command.
+
+## Case 2 — Unknown crash
+
+User:
+"Checkout randomly crashes after payment. It used to work."
+
+Expected:
+Recommend the diagnosis workflow.
+
+Must:
+- Reproduce before hypothesizing.
+- Present hypotheses before fix.
+
+## Case 3 — New capability
+
+User:
+"Add team invitations with email invites and pending invite states."
+
+Expected:
+Recommend feature planning.
+
+Must:
+- Plan before implementation.
+- Use phase gates.
+
+## Case 4 — Structural cleanup
+
+User:
+"The auth module is getting hard to change. I want to decouple provider-specific logic."
+
+Expected:
+Recommend refactor workflow.
+
+Must:
+- Preserve behavior.
+- Explore architecture candidates before implementation.
+
+## Case 5 — Unknown area
+
+User:
+"I need to change billing but I don't know where that logic lives."
+
+Expected:
+Recommend exploration first.
+
+Must:
+- Produce a map before choosing feature/fix/refactor.
+
+## Case 6 — Known mechanical fix
+
+User:
+"The env var name changed from API_KEY to ZOO_API_KEY. Update the config loader."
+
+Expected:
+Recommend small implementation workflow.
+
+Must not:
+- Route to diagnosis.
+- Route to feature.
+
+## Case 7 — TDD with clear interface
+
+User:
+"Add a slugify helper for article URLs. I want it test-first."
+
+Expected:
+Recommend TDD workflow.
+
+Must:
+- Write the failing test first.
+- Confirm the public interface (input, output, edge cases) is clear before coding.
+
+## Case 8 — Stale documentation
+
+User:
+"The ARCHITECTURE.md file describes a checkout flow we removed last quarter. Bring it in line with the code."
+
+Expected:
+Recommend the documentation update workflow.
+
+Must:
+- Audit code first, then make surgical doc edits.
+- Not rewrite the file wholesale.
+
+## Case 9 — Ready to commit
+
+User:
+"I finished the small tweak. Please commit it and add a journal entry."
+
+Expected:
+Recommend the commit + journal workflow.
+
+Must:
+- Propose a Conventional Commit message and wait for approval before running `git commit` or `git push`.
+
+## Case 10 — Issue triage
+
+User:
+"We have 30 incoming bug reports from the support team. Triage them into the issue tracker."
+
+Expected:
+Recommend the triage workflow.
+
+Must:
+- Ask before publishing, labeling, closing, or making any irreversible tracker change.
+
+## Case 11 — Throwaway design probe
+
+User:
+"I'm not sure if the new search ranking should run inline or in a queue. Can we try both and see?"
+
+Expected:
+Recommend a throwaway prototype.
+
+Must:
+- Keep the work on a prototype branch or `.scratch/prototypes/<slug>/` so it is clearly throwaway.
+- Resolve the design question, not commit to a real implementation.
+
+## Case 12 — Explicit slash command
+
+User:
+"/tweak rename the cancel button to close."
+
+Expected:
+Route immediately. Do not second-guess the explicit command.
+
+Must not:
+- Repropose the workflow as a numbered choice.
+- Treat the explicit command as if approval were still pending.
+
+## Case 13 — Ambiguous "fix" for a known mechanical change
+
+User:
+"Fix the typo in the cancel-button label and update the aria-label to match."
+
+Expected:
+Recommend the small implementation workflow, not diagnosis.
+
+Must:
+- Recognize the cause and target are known.
+- Not run a full diagnosis loop for a one-line copy fix.
+
+## Case — Free-form request must not expose slash commands
+
+User:
+"Change the Save button text to Submit."
+
+Expected:
+Recommend the small implementation workflow in plain language.
+
+Good response:
+"This looks like a small implementation change because the target is known and the risk is low.
+
+1. Make the small implementation change
+2. Explore the area first"
+
+Must not:
+- Say "use `/tweak`" in the user-facing recommendation.
+- Offer `/tweak` as a selectable option.
+- Tell the user to type a slash command.
+
+Allowed:
+- Internally delegate using `/tweak` after the user approves.
+- Mention slash commands only if the user explicitly asks for command syntax.
+
+## Case — Review
+
+User:
+"Review this branch before I commit it."
+
+Expected:
+Recommend the review workflow.
+
+Must:
+- Route to architect profile after approval.
+- Report findings by severity.
+
+## Case — Verification
+
+User:
+"Run tests for this change and make sure nothing broke."
+
+Expected:
+Recommend the verification workflow.
+
+Must:
+- Route to implementer profile after approval.
+- Report exact commands run and results.

package/templates/claude-code/.zoo-flow/project-profile.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "projectShape": null,
+  "packageManager": null,
+  "issueTracker": {
+    "kind": null,
+    "project": null
+  },
+  "verification": {
+    "targetedTest": null,
+    "typecheck": null,
+    "lint": null,
+    "build": null,
+    "fullTest": null
+  },
+  "docsPolicy": {
+    "localContext": ".zoo-flow/",
+    "sharedDocs": ["AGENTS.md", "docs/adr/", "docs/architecture/"]
+  },
+  "commitPolicy": {
+    "conventionalCommits": true,
+    "journal": "docs/journal/"
+  }
+}