@fernado03/zoo-flow 0.11.3 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/bin/zoo-flow.js +25 -25
  2. package/docs/architecture.md +380 -0
  3. package/docs/bloat-control.md +49 -0
  4. package/docs/command-design.md +38 -0
  5. package/docs/command-flow.md +133 -0
  6. package/docs/comparison.md +86 -0
  7. package/docs/context-packs.md +35 -0
  8. package/docs/dogfood/01-small-library.md +28 -0
  9. package/docs/dogfood/02-web-app.md +29 -0
  10. package/docs/dogfood/03-mixed-monorepo.md +29 -0
  11. package/docs/mode-rules.md +86 -0
  12. package/docs/npm-publishing.md +79 -0
  13. package/docs/out-of-scope/mainstream-issue-trackers-only.md +25 -0
  14. package/docs/out-of-scope/question-limits.md +18 -0
  15. package/docs/out-of-scope/setup-skill-verify-mode.md +15 -0
  16. package/docs/overview.md +61 -0
  17. package/docs/philosophy.md +73 -0
  18. package/docs/quality-scorecard.md +23 -0
  19. package/docs/skill-maintenance.md +32 -0
  20. package/docs/skills-index.md +64 -0
  21. package/docs/team-mode.md +46 -0
  22. package/docs/token-budget.md +22 -0
  23. package/docs/troubleshooting.md +288 -0
  24. package/examples/demo-transcripts/01-small-tweak.md +37 -0
  25. package/examples/demo-transcripts/02-unknown-bug-fix.md +37 -0
  26. package/examples/demo-transcripts/03-new-feature.md +37 -0
  27. package/examples/demo-transcripts/04-refactor.md +37 -0
  28. package/examples/demo-transcripts/05-review-and-verify.md +37 -0
  29. package/examples/feature-flow.md +117 -0
  30. package/examples/fix-flow.md +139 -0
  31. package/package.json +5 -2
  32. package/scripts/check-package-links.js +1 -1
  33. package/scripts/eval-routing.js +1 -1
  34. package/scripts/score-quality.js +3 -3
  35. package/scripts/test-doctor.js +5 -5
  36. package/templates/full/.roo/commands/{explore.md → zoo-explore.md} +18 -18
  37. package/templates/full/.roo/commands/{scaffold-context.md → zoo-scaffold-context.md} +16 -16
  38. package/templates/full/.roo/commands/{setup-matt-pocock-skills.md → zoo-setup-matt-pocock-skills.md} +7 -7
  39. package/templates/full/.roo/commands/{update-docs.md → zoo-update-docs.md} +22 -22
  40. package/templates/full/.roo/rules-custom-orchestrator/00-routing.md +22 -22
  41. package/templates/full/.roo/skills/engineering/commit-and-document/SKILL.md +163 -163
  42. package/templates/full/.roo/skills/engineering/diagnose/SKILL.md +3 -3
  43. package/templates/full/.roo/skills/engineering/grill-with-docs/SKILL.md +1 -1
  44. package/templates/full/.roo/skills/engineering/improve-codebase-architecture/SKILL.md +1 -1
  45. package/templates/full/.roo/skills/engineering/prototype/SKILL.md +47 -47
  46. package/templates/full/.roo/skills/engineering/review/SKILL.md +7 -7
  47. package/templates/full/.roo/skills/engineering/scaffold-context/SKILL.md +228 -228
  48. package/templates/full/.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md +2 -2
  49. package/templates/full/.roo/skills/engineering/tdd/SKILL.md +1 -1
  50. package/templates/full/.roo/skills/engineering/to-issues/SKILL.md +2 -2
  51. package/templates/full/.roo/skills/engineering/to-prd/SKILL.md +66 -66
  52. package/templates/full/.roo/skills/engineering/triage/SKILL.md +2 -2
  53. package/templates/full/.roo/skills/engineering/tweak/SKILL.md +1 -1
  54. package/templates/full/.roo/skills/engineering/update-docs/SKILL.md +76 -76
  55. package/templates/full/.roo/skills/engineering/verify/SKILL.md +2 -2
  56. package/templates/full/.roo/skills/engineering/zoom-out/SKILL.md +1 -1
  57. package/templates/full/.roo/skills/productivity/caveman/SKILL.md +1 -1
  58. package/templates/full/.roo/skills/productivity/teach/SKILL.md +119 -119
  59. package/templates/full/.roomodes +3 -3
  60. package/tests/fixtures/doctor/helper-not-permitted/fixture.json +1 -1
  61. /package/templates/claude-code/.claude/commands/{caveman.md → zoo-caveman.md} +0 -0
  62. /package/templates/claude-code/.claude/commands/{commit-and-document.md → zoo-commit-and-document.md} +0 -0
  63. /package/templates/claude-code/.claude/commands/{diagnose.md → zoo-diagnose.md} +0 -0
  64. /package/templates/claude-code/.claude/commands/{explore.md → zoo-explore.md} +0 -0
  65. /package/templates/claude-code/.claude/commands/{feature.md → zoo-feature.md} +0 -0
  66. /package/templates/claude-code/.claude/commands/{fix.md → zoo-fix.md} +0 -0
  67. /package/templates/claude-code/.claude/commands/{grill-me.md → zoo-grill-me.md} +0 -0
  68. /package/templates/claude-code/.claude/commands/{grill-with-docs.md → zoo-grill-with-docs.md} +0 -0
  69. /package/templates/claude-code/.claude/commands/{handoff.md → zoo-handoff.md} +0 -0
  70. /package/templates/claude-code/.claude/commands/{improve-codebase-architecture.md → zoo-improve-codebase-architecture.md} +0 -0
  71. /package/templates/claude-code/.claude/commands/{prototype.md → zoo-prototype.md} +0 -0
  72. /package/templates/claude-code/.claude/commands/{refactor.md → zoo-refactor.md} +0 -0
  73. /package/templates/claude-code/.claude/commands/{review.md → zoo-review.md} +0 -0
  74. /package/templates/claude-code/.claude/commands/{scaffold-context.md → zoo-scaffold-context.md} +0 -0
  75. /package/templates/claude-code/.claude/commands/{setup-matt-pocock-skills.md → zoo-setup-matt-pocock-skills.md} +0 -0
  76. /package/templates/claude-code/.claude/commands/{tdd.md → zoo-tdd.md} +0 -0
  77. /package/templates/claude-code/.claude/commands/{teach.md → zoo-teach.md} +0 -0
  78. /package/templates/claude-code/.claude/commands/{to-issues.md → zoo-to-issues.md} +0 -0
  79. /package/templates/claude-code/.claude/commands/{to-prd.md → zoo-to-prd.md} +0 -0
  80. /package/templates/claude-code/.claude/commands/{triage.md → zoo-triage.md} +0 -0
  81. /package/templates/claude-code/.claude/commands/{tweak.md → zoo-tweak.md} +0 -0
  82. /package/templates/claude-code/.claude/commands/{update-docs.md → zoo-update-docs.md} +0 -0
  83. /package/templates/claude-code/.claude/commands/{verify.md → zoo-verify.md} +0 -0
  84. /package/templates/claude-code/.claude/commands/{write-a-skill.md → zoo-write-a-skill.md} +0 -0
  85. /package/templates/claude-code/.claude/commands/{zoom-out.md → zoo-zoom-out.md} +0 -0
  86. /package/templates/full/.roo/commands/{caveman.md → zoo-caveman.md} +0 -0
  87. /package/templates/full/.roo/commands/{commit-and-document.md → zoo-commit-and-document.md} +0 -0
  88. /package/templates/full/.roo/commands/{diagnose.md → zoo-diagnose.md} +0 -0
  89. /package/templates/full/.roo/commands/{feature.md → zoo-feature.md} +0 -0
  90. /package/templates/full/.roo/commands/{fix.md → zoo-fix.md} +0 -0
  91. /package/templates/full/.roo/commands/{grill-me.md → zoo-grill-me.md} +0 -0
  92. /package/templates/full/.roo/commands/{grill-with-docs.md → zoo-grill-with-docs.md} +0 -0
  93. /package/templates/full/.roo/commands/{handoff.md → zoo-handoff.md} +0 -0
  94. /package/templates/full/.roo/commands/{improve-codebase-architecture.md → zoo-improve-codebase-architecture.md} +0 -0
  95. /package/templates/full/.roo/commands/{prototype.md → zoo-prototype.md} +0 -0
  96. /package/templates/full/.roo/commands/{refactor.md → zoo-refactor.md} +0 -0
  97. /package/templates/full/.roo/commands/{review.md → zoo-review.md} +0 -0
  98. /package/templates/full/.roo/commands/{tdd.md → zoo-tdd.md} +0 -0
  99. /package/templates/full/.roo/commands/{teach.md → zoo-teach.md} +0 -0
  100. /package/templates/full/.roo/commands/{to-issues.md → zoo-to-issues.md} +0 -0
  101. /package/templates/full/.roo/commands/{to-prd.md → zoo-to-prd.md} +0 -0
  102. /package/templates/full/.roo/commands/{triage.md → zoo-triage.md} +0 -0
  103. /package/templates/full/.roo/commands/{tweak.md → zoo-tweak.md} +0 -0
  104. /package/templates/full/.roo/commands/{verify.md → zoo-verify.md} +0 -0
  105. /package/templates/full/.roo/commands/{write-a-skill.md → zoo-write-a-skill.md} +0 -0
  106. /package/templates/full/.roo/commands/{zoom-out.md → zoo-zoom-out.md} +0 -0
@@ -1,76 +1,76 @@
1
- ---
2
- name: update-docs
3
- description: Update repo documentation (flow, app map, architecture, README, module docs) so it matches current code. Use when docs are stale and need to be reconciled with the codebase.
4
- ---
5
-
6
- # Update Docs
7
-
8
- Edit repo docs that explain how code works (flow docs, app/module maps, architecture overviews, README, module-local markdown). Surgical edits, not rewrites.
9
-
10
- ## 1. Identify target
11
-
12
- Infer or ask for the target doc. Prefer existing docs over new ones:
13
-
14
- - Subsystem flow → nearby flow doc.
15
- - App-wide navigation/module map → app map doc.
16
- - System-level structure → architecture doc.
17
- - Setup/usage → `README.md`.
18
-
19
- If the doc does not exist, ask before creating. Never invent a new doc location silently.
20
-
21
- ## 2. Read first
22
-
23
- Read the target fully before editing. Also read nearby related docs (neighbouring flow docs, app/architecture docs, README, module-local docs). Match the existing style, structure, vocabulary, and detail level.
24
-
25
- ## 3. Verify against code
26
-
27
- Inspect the code the doc describes. Update from code reality, not guesses. Check entrypoints, main functions/classes, data flow, state changes, side effects, deps, error/fallback paths, files involved.
28
-
29
- Unverifiable claims → remove or move to an `Open questions` section. Never present guesses as facts.
30
-
31
- ## 4. Surgical edits
32
-
33
- Default to small edits: keep useful sections, update stale ones, add missing flows, remove false claims, preserve heading style and tone. Rewrite the whole file only if it is too stale to salvage; if so, say why before editing.
34
-
35
- ## 5. Freshness block
36
-
37
- If it fits the doc's style, add or update at the bottom:
38
-
39
- ```md
40
- ## Freshness
41
-
42
- Last checked against code: YYYY-MM-DD
43
- Relevant files checked:
44
- - `path/to/file.py`
45
- - `path/to/other_file.py`
46
- ```
47
-
48
- Use today's date. Include only files actually inspected.
49
-
50
- ## 6. Sanity check
51
-
52
- After editing: re-read, confirm referenced paths exist, every major claim maps to code or a cited doc, no stale contradiction with nearby docs. Summarise the change.
53
-
54
- ## 7. Recommend next step
55
-
56
- Recommend one: `/explore` (still unclear), `/feature` (plan emerged), `/refactor` (tangled-but-working code), `/fix` (bug found), `/commit-and-document` (done). Do not auto-run.
57
-
58
- ## Complete
59
-
60
- Call `attempt_completion` with:
61
- - docs updated (file paths)
62
- - what changed (summary)
63
- - status (complete / blocked with reason)
64
- - recommended next command
65
-
66
- Do NOT use `ask_followup_question` or write results as plain text without calling the tool.
67
-
68
- ## Context economy
69
-
70
- Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
71
-
72
- Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
73
-
74
- Read full files only when structure, ordering, or surrounding context is required for correctness.
75
-
76
- Do not re-read unchanged files; use prior findings unless the file changed.
1
+ ---
2
+ name: update-docs
3
+ description: Update repo documentation (flow, app map, architecture, README, module docs) so it matches current code. Use when docs are stale and need to be reconciled with the codebase.
4
+ ---
5
+
6
+ # Update Docs
7
+
8
+ Edit repo docs that explain how code works (flow docs, app/module maps, architecture overviews, README, module-local markdown). Surgical edits, not rewrites.
9
+
10
+ ## 1. Identify target
11
+
12
+ Infer or ask for the target doc. Prefer existing docs over new ones:
13
+
14
+ - Subsystem flow → nearby flow doc.
15
+ - App-wide navigation/module map → app map doc.
16
+ - System-level structure → architecture doc.
17
+ - Setup/usage → `README.md`.
18
+
19
+ If the doc does not exist, ask before creating. Never invent a new doc location silently.
20
+
21
+ ## 2. Read first
22
+
23
+ Read the target fully before editing. Also read nearby related docs (neighbouring flow docs, app/architecture docs, README, module-local docs). Match the existing style, structure, vocabulary, and detail level.
24
+
25
+ ## 3. Verify against code
26
+
27
+ Inspect the code the doc describes. Update from code reality, not guesses. Check entrypoints, main functions/classes, data flow, state changes, side effects, deps, error/fallback paths, files involved.
28
+
29
+ Unverifiable claims → remove or move to an `Open questions` section. Never present guesses as facts.
30
+
31
+ ## 4. Surgical edits
32
+
33
+ Default to small edits: keep useful sections, update stale ones, add missing flows, remove false claims, preserve heading style and tone. Rewrite the whole file only if it is too stale to salvage; if so, say why before editing.
34
+
35
+ ## 5. Freshness block
36
+
37
+ If it fits the doc's style, add or update at the bottom:
38
+
39
+ ```md
40
+ ## Freshness
41
+
42
+ Last checked against code: YYYY-MM-DD
43
+ Relevant files checked:
44
+ - `path/to/file.py`
45
+ - `path/to/other_file.py`
46
+ ```
47
+
48
+ Use today's date. Include only files actually inspected.
49
+
50
+ ## 6. Sanity check
51
+
52
+ After editing: re-read, confirm referenced paths exist, every major claim maps to code or a cited doc, no stale contradiction with nearby docs. Summarise the change.
53
+
54
+ ## 7. Recommend next step
55
+
56
+ Recommend one: `/zoo-explore` (still unclear), `/zoo-feature` (plan emerged), `/zoo-refactor` (tangled-but-working code), `/zoo-fix` (bug found), `/zoo-commit-and-document` (done). Do not auto-run.
57
+
58
+ ## Complete
59
+
60
+ Call `attempt_completion` with:
61
+ - docs updated (file paths)
62
+ - what changed (summary)
63
+ - status (complete / blocked with reason)
64
+ - recommended next command
65
+
66
+ Do NOT use `ask_followup_question` or write results as plain text without calling the tool.
67
+
68
+ ## Context economy
69
+
70
+ Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
71
+
72
+ Prefer targeted `read_file` ranges or indentation/block reads once the relevant area is known.
73
+
74
+ Read full files only when structure, ordering, or surrounding context is required for correctness.
75
+
76
+ Do not re-read unchanged files; use prior findings unless the file changed.
@@ -65,7 +65,7 @@ Status: pass | fail | partial | blocked
65
65
 
66
66
  ## Recommended next step
67
67
 
68
- <none | /review | /tweak | /tdd | /fix | /commit-and-document>
68
+ <none | /zoo-review | /zoo-tweak | /zoo-tdd | /zoo-fix | /zoo-commit-and-document>
69
69
  ```
70
70
 
71
71
  Hard rule: never say `verified`, `all good`, or `tests pass` unless commands actually ran and passed.
@@ -81,7 +81,7 @@ Do not auto-launch any follow-up command.
81
81
 
82
82
  ## 6. Complete
83
83
 
84
- Write the full verification report to `.scratch/verify/<date>/verify-<slug>.md`.
84
+ Write the full verification report to `.scratch/zoo-verify/<date>/zoo-verify-<slug>.md`.
85
85
 
86
86
  Call `attempt_completion` with:
87
87
  - file path where report was saved
@@ -22,7 +22,7 @@ Start with `list_files` and `search_files`/`codebase_search`. Read representativ
22
22
 
23
23
  ## Multi-dimension mapping
24
24
 
25
- Initialize session: `.scratch/explorations/<YYYY-MM-DD>/zoom-out-<slug>/`
25
+ Initialize session: `.scratch/explorations/<YYYY-MM-DD>/zoo-zoom-out-<slug>/`
26
26
 
27
27
  Write `<session-dir>/session.md` with target area, scope, user request.
28
28
 
@@ -4,7 +4,7 @@ description: >
4
4
  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
5
5
  filler, articles, and pleasantries while keeping full technical accuracy.
6
6
  Use when user says "caveman mode", "talk like caveman", "use caveman",
7
- "less tokens", "be brief", or invokes /caveman.
7
+ "less tokens", "be brief", or invokes /zoo-caveman.
8
8
  ---
9
9
 
10
10
  # Caveman
@@ -1,119 +1,119 @@
1
- ---
2
- name: teach
3
- 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.
4
- disable-model-invocation: true
5
- argument-hint: "What would you like to learn about?"
6
- ---
7
-
8
- # Teach
9
-
10
- Stateful. Treat current directory as the teaching workspace.
11
-
12
- ## Files
13
-
14
- - `MISSION.md` — why user wants this; grounds every decision. Format: `mission-format.md`.
15
- - `RESOURCES.md` — trusted knowledge + community sources. Format: `resources-format.md`.
16
- - `./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.
17
- - `./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.
18
- - `NOTES.md` — A scratchpad for you to jot down user preferences, or working notes.
19
- - `learning-records/NNNN-slug.md` — non-obvious lessons + prior knowledge. Format: `learning-record-format.md`.
20
-
21
- ## Triad
22
-
23
- - **Knowledge** — drawn from `RESOURCES.md`. Never parametric.
24
- - **Skills** — exercises built from the knowledge.
25
- - **Wisdom** — real-world community interaction via `RESOURCES.md`.
26
-
27
- Topic mix varies: theoretical → knowledge-heavy; practical → skills-heavy.
28
-
29
- ### Fluency vs Storage Strength
30
-
31
- You should be careful to split between two types of learning:
32
-
33
- - **Fluency strength**: in-the-moment retrieval of knowledge
34
- - **Storage strength**: long-term retention of knowledge
35
-
36
- 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:
37
-
38
- - Using retrieval practice (recall from memory)
39
- - Spacing (distributing practice over time)
40
- - Interleaving (mixing up different but related topics in practice - for skill practice only)
41
-
42
- ## Lessons
43
-
44
- 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.
45
-
46
- A lesson should be **beautiful** - clean, readable typography and layout since the user will return to these later to review. Think Tufte.
47
-
48
- 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.
49
-
50
- If possible, open the lesson file for the user by running a CLI command.
51
-
52
- Each lesson should link via HTML anchors to other lessons and reference documents.
53
-
54
- 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.
55
-
56
- 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.
57
-
58
- ## Mission first
59
-
60
- If `MISSION.md` missing or vague, interview before teaching. No mission = no grounding, abstract exercises, no signal for what's next.
61
-
62
- 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.
63
-
64
- ## Zone of proximal development
65
-
66
- The user may specify an exact thing they want to learn. If they don't, figure out their zone of proximal development.
67
-
68
- Each lesson, the user should always feel as if they are being challenged 'just enough'.
69
-
70
- Pick next topic by:
71
- 1. Read `learning-records/`.
72
- 2. Align to `MISSION.md`.
73
- 3. Pick tightest scope that still stretches the user.
74
-
75
- User says "I already know X" → record in `learning-records/`.
76
-
77
- ## Knowledge
78
-
79
- 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.
80
-
81
- For acquiring knowledge, difficulty is the enemy. It eats working memory you need for understanding.
82
-
83
- 1. Pull from `RESOURCES.md`.
84
- 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.
85
- 3. Give one-line CLI command to open it.
86
- 4. Take questions; amend explainer or write a new one.
87
-
88
-
89
- ## Skills
90
-
91
- 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:
92
-
93
- - Interactive lessons, using quizzes and light in-browser tasks
94
- - Lessons which guide the user through a list of real-world steps to take (for instance, yoga poses)
95
- - In-agent quizzes, where you ask the user scenario-based questions about what they've learned
96
-
97
- 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.
98
-
99
- 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.
100
-
101
- ## Wisdom
102
-
103
- 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.
104
-
105
- ## `NOTES.md`
106
-
107
- 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.
108
-
109
- ## Complete
110
-
111
- When the user ends the teaching session or says "done" / "stop teaching":
112
-
113
- Call `attempt_completion` with:
114
- - lessons created (count, paths)
115
- - mission status (created / updated)
116
- - learning records updated (count)
117
- - status (session complete / paused)
118
-
119
- Do NOT use `ask_followup_question` or write results as plain text without calling the tool.
1
+ ---
2
+ name: teach
3
+ 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.
4
+ disable-model-invocation: true
5
+ argument-hint: "What would you like to learn about?"
6
+ ---
7
+
8
+ # Teach
9
+
10
+ Stateful. Treat current directory as the teaching workspace.
11
+
12
+ ## Files
13
+
14
+ - `MISSION.md` — why user wants this; grounds every decision. Format: `mission-format.md`.
15
+ - `RESOURCES.md` — trusted knowledge + community sources. Format: `resources-format.md`.
16
+ - `./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.
17
+ - `./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.
18
+ - `NOTES.md` — A scratchpad for you to jot down user preferences, or working notes.
19
+ - `learning-records/NNNN-slug.md` — non-obvious lessons + prior knowledge. Format: `learning-record-format.md`.
20
+
21
+ ## Triad
22
+
23
+ - **Knowledge** — drawn from `RESOURCES.md`. Never parametric.
24
+ - **Skills** — exercises built from the knowledge.
25
+ - **Wisdom** — real-world community interaction via `RESOURCES.md`.
26
+
27
+ Topic mix varies: theoretical → knowledge-heavy; practical → skills-heavy.
28
+
29
+ ### Fluency vs Storage Strength
30
+
31
+ You should be careful to split between two types of learning:
32
+
33
+ - **Fluency strength**: in-the-moment retrieval of knowledge
34
+ - **Storage strength**: long-term retention of knowledge
35
+
36
+ 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:
37
+
38
+ - Using retrieval practice (recall from memory)
39
+ - Spacing (distributing practice over time)
40
+ - Interleaving (mixing up different but related topics in practice - for skill practice only)
41
+
42
+ ## Lessons
43
+
44
+ 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.
45
+
46
+ A lesson should be **beautiful** - clean, readable typography and layout since the user will return to these later to review. Think Tufte.
47
+
48
+ 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.
49
+
50
+ If possible, open the lesson file for the user by running a CLI command.
51
+
52
+ Each lesson should link via HTML anchors to other lessons and reference documents.
53
+
54
+ 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.
55
+
56
+ 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.
57
+
58
+ ## Mission first
59
+
60
+ If `MISSION.md` missing or vague, interview before teaching. No mission = no grounding, abstract exercises, no signal for what's next.
61
+
62
+ 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.
63
+
64
+ ## Zone of proximal development
65
+
66
+ The user may specify an exact thing they want to learn. If they don't, figure out their zone of proximal development.
67
+
68
+ Each lesson, the user should always feel as if they are being challenged 'just enough'.
69
+
70
+ Pick next topic by:
71
+ 1. Read `learning-records/`.
72
+ 2. Align to `MISSION.md`.
73
+ 3. Pick tightest scope that still stretches the user.
74
+
75
+ User says "I already know X" → record in `learning-records/`.
76
+
77
+ ## Knowledge
78
+
79
+ 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.
80
+
81
+ For acquiring knowledge, difficulty is the enemy. It eats working memory you need for understanding.
82
+
83
+ 1. Pull from `RESOURCES.md`.
84
+ 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.
85
+ 3. Give one-line CLI command to open it.
86
+ 4. Take questions; amend explainer or write a new one.
87
+
88
+
89
+ ## Skills
90
+
91
+ 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:
92
+
93
+ - Interactive lessons, using quizzes and light in-browser tasks
94
+ - Lessons which guide the user through a list of real-world steps to take (for instance, yoga poses)
95
+ - In-agent quizzes, where you ask the user scenario-based questions about what they've learned
96
+
97
+ 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.
98
+
99
+ 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.
100
+
101
+ ## Wisdom
102
+
103
+ 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.
104
+
105
+ ## `NOTES.md`
106
+
107
+ 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.
108
+
109
+ ## Complete
110
+
111
+ When the user ends the teaching session or says "done" / "stop teaching":
112
+
113
+ Call `attempt_completion` with:
114
+ - lessons created (count, paths)
115
+ - mission status (created / updated)
116
+ - learning records updated (count)
117
+ - status (session complete / paused)
118
+
119
+ Do NOT use `ask_followup_question` or write results as plain text without calling the tool.
@@ -6,7 +6,7 @@
6
6
  "roleDefinition": "You are an Execution Specialist. You implement, test, update docs, prototype, and commit when explicitly approved.",
7
7
  "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.",
8
8
  "description": "Fast execution for tweaks, TDD, docs, prototypes, and approved commits.",
9
- "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted routed commands: /tweak, /tdd, /update-docs, /commit-and-document, /prototype, /scaffold-context, /verify.\n\nPermitted direct helper commands: /write-a-skill, /setup-matt-pocock-skills, /teach.\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 a command outside both lists, stop and report the routing error.",
9
+ "customInstructions": "Use `.roo/rules-code-tweaker/` for mode-specific behavior.\n\nPermitted routed commands: /zoo-tweak, /zoo-tdd, /zoo-update-docs, /zoo-commit-and-document, /zoo-prototype, /zoo-scaffold-context, /zoo-verify.\n\nPermitted direct helper commands: /zoo-write-a-skill, /zoo-setup-matt-pocock-skills, /zoo-teach.\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 a command outside both lists, stop and report the routing error.",
10
10
  "groups": [
11
11
  "read",
12
12
  "edit",
@@ -20,7 +20,7 @@
20
20
  "roleDefinition": "You are a System Architect. You plan, diagnose, explore, triage, and design. You do NOT write implementation code.",
21
21
  "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.",
22
22
  "description": "Planning, diagnosis, refactor design, exploration, and triage.",
23
- "customInstructions": "Use `.roo/rules-system-architect/` for mode-specific behavior.\n\nPermitted routed commands: /feature, /fix, /refactor, /explore, /triage, /review.\n\nPermitted direct helper commands: /diagnose, /grill-with-docs, /improve-codebase-architecture, /to-prd, /to-issues, /zoom-out, /handoff, /grill-me.\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 a command outside both lists, stop and report the routing error.",
23
+ "customInstructions": "Use `.roo/rules-system-architect/` for mode-specific behavior.\n\nPermitted routed commands: /zoo-feature, /zoo-fix, /zoo-refactor, /zoo-explore, /zoo-triage, /zoo-review.\n\nPermitted direct helper commands: /zoo-diagnose, /zoo-grill-with-docs, /zoo-improve-codebase-architecture, /zoo-to-prd, /zoo-to-issues, /zoo-zoom-out, /zoo-handoff, /zoo-grill-me.\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 a command outside both lists, stop and report the routing error.",
24
24
  "groups": [
25
25
  "command",
26
26
  "mcp",
@@ -40,7 +40,7 @@
40
40
  "roleDefinition": "You are a PM and router. You choose workflows and delegate subtasks. You NEVER inspect implementation files, write code, or use switch_mode.",
41
41
  "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.",
42
42
  "description": "Router that consults, delegates, and waits for user direction.",
43
- "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, /scaffold-context, /verify -> slug: code-tweaker\n- /fix, /feature, /refactor, /explore, /triage, /review -> 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/verification tasks, use slug: code-tweaker.",
43
+ "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- /zoo-tweak, /zoo-tdd, /zoo-update-docs, /zoo-commit-and-document, /zoo-prototype, /zoo-scaffold-context, /zoo-verify -> slug: code-tweaker\n- /zoo-fix, /zoo-feature, /zoo-refactor, /zoo-explore, /zoo-triage, /zoo-review -> 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/verification tasks, use slug: code-tweaker.",
44
44
  "groups": []
45
45
  }
46
46
  ]
@@ -1 +1 @@
1
- {"expect":"fail","mutation":"helper-not-permitted","message":"does not permit documented command /diagnose"}
1
+ {"expect":"fail","mutation":"helper-not-permitted","message":"does not permit documented command /zoo-diagnose"}