@fernado03/zoo-flow 0.10.0 → 0.11.0

package/README.md

@@ -85,12 +85,36 @@ npx @fernado03/zoo-flow@latest doctor
 
 ## Using Zoo Flow
 
-First run:
+### First run (both platforms)
 
 - Run `/scaffold-context` when the project needs local context docs.
 - Run `/setup-matt-pocock-skills` when tracker or triage config is needed.
 
-Daily use:
+### Claude Code
+
+Claude Code reads `CLAUDE.md` automatically on startup. No mode switching needed.
+
+**Daily use:**
+
+- Open Claude Code in your project directory
+- Describe tasks naturally: "Fix the login bug" → Claude proposes `/fix` workflow
+- Or use slash commands directly: `/tweak`, `/fix`, `/feature`, `/review`, etc.
+- Claude uses **behavioral profiles** (Architect/Implementer) defined in CLAUDE.md
+- Multi-phase commands (like `/fix`, `/feature`) use the `Agent` tool to delegate between profiles
+
+**Example:**
+```
+You: "Fix the login bug"
+Claude: "I'll use the /fix workflow. The architect will diagnose, then the implementer will fix it. Proceed?"
+You: "Yes"
+Claude: [Runs diagnostic, proposes fix, implements after approval]
+```
+
+### Zoo Code
+
+Zoo Code uses three custom modes defined in `.roomodes`.
+
+**Daily use:**
 
 - Start in `custom-orchestrator`, describe the task normally.
 - The orchestrator proposes a plain-language workflow; approve by number.

package/package.json

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

package/templates/claude-code/.claude/skills/engineering/diagnose/SKILL.md

@@ -3,6 +3,8 @@ name: diagnose
 description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
 ---
 
+Uses scratch working memory for hypothesis tracking.
+
 # Diagnose
 
 RULE: glossary + ADRs. Skip phase only with explicit reason. DO NOT hypothesise before deterministic loop.
@@ -33,15 +35,26 @@ Rules:
 4. Capture exact error/output/timing.
 5. DO NOT continue until reproduced.
 
-## 3. Hypotheses
+## 3. Hypotheses (with working memory)
+
+Initialize session: `.scratch/diagnoses/<YYYY-MM-DD>/diagnose-<slug>/`
+
+Write `<session-dir>/session.md` with symptom, repro steps, error signatures.
+
+Generate 3–5 ranked falsifiable hypotheses. Write each to `<session-dir>/hypothesis-<N>.md`:
+
+- **Statement**: `If {cause}, then {probe} will {result}`
+- **Rank and confidence**
+- **Rationale**
+- **Instrumentation plan**: specific probe and expected outcome
+- **Status**: pending / confirmed / rejected
+- **Results**: (filled during phase 4)
 
-1. Generate 3–5 ranked falsifiable hypotheses.
-2. Format: `If {cause}, then {probe/change} will {observable result}`.
-3. Drop vague hypotheses.
-4. Show ranked list.
-5. User AFK → proceed top hypothesis.
+Drop vague hypotheses. Show ranked list. User AFK → proceed top hypothesis.
 
-## 4. Instrument
+## 4. Instrument (with tracking)
+
+Before each probe, read all `<session-dir>/hypothesis-*.md` files to maintain context.
 
 1. Map one probe to one hypothesis.
 2. Change one variable at a time.
@@ -51,6 +64,13 @@ Rules:
 6. DO NOT log everything.
 7. Perf: baseline/profiler/query plan before logs.
 
+After each probe, update the corresponding hypothesis file with:
+- Evidence observed
+- Status update (confirmed / rejected)
+- Next steps
+
+Continue until root cause is confirmed or all hypotheses are rejected.
+
 ## 5. Fix + regression
 
 **OWNER: Implementer profile** (requires source-code edits)
@@ -93,10 +113,24 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 For logs or large outputs, search for the failing marker/error first using `Grep`. Read only surrounding ranges needed to prove or disprove a hypothesis.
 
-## 7. Save
+## 7. Save and synthesize
 
 **OWNER: Architect profile** (writes to `.scratch/`)
 
-Write the full diagnosis (hypotheses, instrumentation, root cause, fix) to `.scratch/diagnoses/<date>/diagnose-<slug>.md`.
+Read all `<session-dir>/hypothesis-*.md` files.
+
+Write `<session-dir>/root-cause.md`:
+- Confirmed hypothesis with evidence trail
+- Rejected hypotheses and why they failed
+- Root cause explanation
+- Fix applied (from phase 5-6)
+- Preventive measures
+
+Write `<session-dir>/diagnosis.md` with full log (hypotheses, instrumentation results, timeline).
 
-Return completion with: diagnosis file path, root cause summary, fix applied, status, and recommended next command (typically `/verify` then `/review` then `/commit-and-document`).
+Return completion with:
+- `<session-dir>/root-cause.md` path
+- root cause summary
+- fix applied
+- status
+- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)

package/templates/claude-code/.claude/skills/engineering/review/SKILL.md

@@ -3,6 +3,8 @@ name: review
 description: Review a diff, branch, PR, or work-in-progress change against the requested spec, repo standards, architecture, and likely regressions. Use before committing non-trivial work.
 ---
 
+Uses scratch working memory.
+
 # Review
 
 Purpose: answer whether the diff matches the spec, standards, architecture, and project intent.
@@ -37,9 +39,15 @@ Then read targeted diffs only:
 
 Read relevant specs, issues, PRDs, standards, docs, ADRs, security notes, or project conventions only when they affect the changed area or the user requested that axis.
 
-## 3. Review axes
+## 3. Review axes (multi-pass with working memory)
+
+Initialize session: `.scratch/reviews/<YYYY-MM-DD>/review-<slug>/`
+
+Write `<session-dir>/session.md` with review target, base ref, scope.
 
-Standards axis:
+### Pass 1: Standards axis
+
+Analyze and write `<session-dir>/standards.md`:
 
 - style
 - architecture
@@ -48,14 +56,24 @@ Standards axis:
 - security
 - project conventions
 
-Spec axis:
+### Pass 2: Spec axis
+
+Read `<session-dir>/standards.md` for context.
+
+Analyze and write `<session-dir>/spec.md`:
 
 - did it solve the requested problem?
 - did it change public behavior unexpectedly?
 - did it miss edge cases?
 - did it violate PRD, issue, or user intent?
 
-Security/Risk axis:
+Cross-reference standards findings where relevant.
+
+### Pass 3: Security/Risk axis
+
+Read `<session-dir>/standards.md` and `<session-dir>/spec.md`.
+
+Analyze and write `<session-dir>/security.md`:
 
 - does the change touch auth, payments, PII, session data, or external API contracts?
 - does it introduce new dependencies or entitlements?
@@ -63,7 +81,9 @@ Security/Risk axis:
 - is there a regression path that would be hard to detect?
 - does the change affect audit logs or compliance obligations?
 
-For every Security/Risk finding, include the severity and a concrete mitigation suggestion. Omitting this axis is allowed when the change clearly cannot affect security (copy changes, comment fixes, test-only additions, docs-only updates).
+For every Security/Risk finding, include severity and mitigation. Cross-reference previous passes.
+
+Omit this axis when the change clearly cannot affect security (copy changes, comment fixes, test-only additions, docs-only updates).
 
 ## 4. Findings
 
@@ -94,12 +114,19 @@ End with exactly one result line:
 - `Review result: changes requested`
 - `Review result: blocked`
 
-## 6. Save and complete
+## 6. Synthesize and complete
+
+Read all angle files from `<session-dir>/` (standards.md, spec.md, security.md if present).
+
+Write `<session-dir>/synthesis.md` with:
 
-Write the full review (findings, axes, result) to `.scratch/reviews/<date>/review-<slug>.md`.
+- Summary of each axis
+- Cross-cutting findings (issues spanning multiple axes)
+- Prioritized findings by severity
+- Result line: `approve` / `approve with nits` / `changes requested` / `blocked`
 
 Return completion with:
-- file path where review was saved
+- `<session-dir>/synthesis.md` path
 - brief result line (approve / approve with nits / changes requested / blocked)
 - recommended next command
 

package/templates/claude-code/.claude/skills/engineering/zoom-out/SKILL.md

@@ -3,6 +3,8 @@ name: zoom-out
 description: Map the codebase at a high level to understand structure, modules, and relationships. Use when entering an unfamiliar codebase or planning large changes.
 ---
 
+Uses scratch working memory for multi-dimension mapping.
+
 # Zoom Out
 
 RULE: Produce a high-level map, not detailed code analysis. Focus on structure and relationships.
@@ -12,9 +14,47 @@ RULE: Produce a high-level map, not detailed code analysis. Focus on structure a
 1. Use `Glob` to identify directory structure and file organization.
 2. Use `Grep` to find key patterns (entry points, exports, configurations).
 3. Use targeted `Read` on key files (README, package.json, main entry points).
-4. Identify major modules, components, and their relationships.
-5. Document map in `.scratch/zoom-out/<date>.md` using `Write`.
-6. Include text-based diagrams showing structure and dependencies.
+
+## Multi-dimension mapping
+
+Initialize session directory: `.scratch/zoom-out/<YYYY-MM-DD>-<slug>/`
+
+Use `Write` to create `<session-dir>/session.md` with:
+- Target area or scope
+- Initial observations from step 3
+
+### Dimension 1: Architecture
+
+Analyze and `Write` to `<session-dir>/architecture.md`:
+- Module boundaries and responsibilities
+- Key interfaces and abstractions
+- Separation of concerns
+
+### Dimension 2: Data flow
+
+Analyze and `Write` to `<session-dir>/data-flow.md`:
+- Entry points (API endpoints, CLI commands, event handlers)
+- Data transformations and processing steps
+- State management and persistence
+- External integrations
+
+### Dimension 3: Call graph
+
+Analyze and `Write` to `<session-dir>/call-graph.md`:
+- Key functions and their call chains
+- Control flow patterns
+- Dependencies between components
+- Error propagation paths
+
+### Synthesis
+
+`Read` all dimension files and synthesize insights.
+
+`Write` to `<session-dir>/synthesis.md`:
+- Cross-cutting architectural patterns
+- Key dependencies and integration points
+- Potential areas of concern or technical debt
+- Recommended areas for deeper exploration
 
 ## Context economy
 
@@ -29,6 +69,6 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 ## Complete
 
 Return completion with:
-- map document location
+- `<session-dir>/synthesis.md` file path
 - high-level structure summary
 - recommended next command (typically `/explore` for deeper dive, or `/feature`/`/refactor` if changes needed)

package/templates/full/.roo/rules/07-scratch-working-memory.md

@@ -0,0 +1,39 @@
+# Scratch Working Memory
+
+Use persistent multi-pass analysis for complex tasks. Skills opt in by declaring "Uses scratch working memory" after YAML frontmatter.
+
+## Protocol
+
+### 1. Initialize session
+Create `.scratch/<category>/<YYYY-MM-DD>/<skill>-<slug>/` and write `session.md` with task summary and target.
+
+### 2. Write phase (per angle)
+For each analysis angle:
+- Perform analysis
+- Write findings to `<session-dir>/<angle>.md` (e.g., `standards.md`, `spec.md`, `security.md`)
+- Include: observations, issues (with severity), recommendations, cross-references to other angles
+
+### 3. Read phase (before next angle)
+Before analyzing each new angle:
+- Read all previous angle files from session directory
+- Cross-reference findings
+- Note reinforcements or contradictions
+
+### 4. Synthesize phase (final)
+After all angles complete:
+- Read all angle files
+- Write `<session-dir>/synthesis.md`:
+  - Summary of each angle
+  - Cross-cutting concerns (issues spanning multiple angles)
+  - Prioritized recommendations (Blocker → High → Medium → Low → Nit)
+  - Confidence level per finding
+- Write result summary
+- Call `attempt_completion` with synthesis path and recommendations
+
+## Example
+Review skill session: `.scratch/reviews/2026-01-15/review-auth-module/`
+- `session.md` — task summary
+- `standards.md` — style, architecture, test quality
+- `spec.md` — problem solved? behavior changed? edge cases?
+- `security.md` — auth, payments, PII, regressions
+- `synthesis.md` — cross-cutting findings and prioritized recommendations

package/templates/full/.roo/skills/engineering/diagnose/SKILL.md

@@ -3,6 +3,8 @@ name: diagnose
 description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
 ---
 
+Uses scratch working memory for hypothesis tracking.
+
 # Diagnose
 
 RULE: glossary + ADRs. Skip phase only with explicit reason. DO NOT hypothesise before deterministic loop.
@@ -33,15 +35,26 @@ Rules:
 4. Capture exact error/output/timing.
 5. DO NOT continue until reproduced.
 
-## 3. Hypotheses
+## 3. Hypotheses (with working memory)
+
+Initialize session: `.scratch/diagnoses/<YYYY-MM-DD>/diagnose-<slug>/`
+
+Write `<session-dir>/session.md` with symptom, repro steps, error signatures.
+
+Generate 3–5 ranked falsifiable hypotheses. Write each to `<session-dir>/hypothesis-<N>.md`:
+
+- **Statement**: `If {cause}, then {probe} will {result}`
+- **Rank and confidence**
+- **Rationale**
+- **Instrumentation plan**: specific probe and expected outcome
+- **Status**: pending / confirmed / rejected
+- **Results**: (filled during phase 4)
 
-1. Generate 3–5 ranked falsifiable hypotheses.
-2. Format: `If {cause}, then {probe/change} will {observable result}`.
-3. Drop vague hypotheses.
-4. Show ranked list.
-5. User AFK → proceed top hypothesis.
+Drop vague hypotheses. Show ranked list. User AFK → proceed top hypothesis.
 
-## 4. Instrument
+## 4. Instrument (with tracking)
+
+Before each probe, read all `<session-dir>/hypothesis-*.md` files to maintain context.
 
 1. Map one probe to one hypothesis.
 2. Change one variable at a time.
@@ -51,6 +64,13 @@ Rules:
 6. DO NOT log everything.
 7. Perf: baseline/profiler/query plan before logs.
 
+After each probe, update the corresponding hypothesis file with:
+- Evidence observed
+- Status update (confirmed / rejected)
+- Next steps
+
+Continue until root cause is confirmed or all hypotheses are rejected.
+
 ## 5. Fix + regression
 
 **OWNER: code-tweaker** (requires source-code edits)
@@ -93,10 +113,24 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 For logs or large outputs, search for the failing marker/error first. Read only surrounding ranges needed to prove or disprove a hypothesis.
 
-## 7. Save
+## 7. Save and synthesize
 
 **OWNER: system-architect** (writes to `.scratch/`)
 
-Write the full diagnosis (hypotheses, instrumentation, root cause, fix) to `.scratch/diagnoses/<date>/diagnose-<slug>.md`.
+Read all `<session-dir>/hypothesis-*.md` files.
+
+Write `<session-dir>/root-cause.md`:
+- Confirmed hypothesis with evidence trail
+- Rejected hypotheses and why they failed
+- Root cause explanation
+- Fix applied (from phase 5-6)
+- Preventive measures
+
+Write `<session-dir>/diagnosis.md` with full log (hypotheses, instrumentation results, timeline).
 
-Call `attempt_completion` with: diagnosis file path, root cause summary, fix applied, status, and recommended next command (typically `/verify` then `/review` then `/commit-and-document`).
+Call `attempt_completion` with:
+- `<session-dir>/root-cause.md` path
+- root cause summary
+- fix applied
+- status
+- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)

package/templates/full/.roo/skills/engineering/review/SKILL.md

@@ -3,6 +3,8 @@ name: review
 description: Review a diff, branch, PR, or work-in-progress change against the requested spec, repo standards, architecture, and likely regressions. Use before committing non-trivial work.
 ---
 
+Uses scratch working memory.
+
 # Review
 
 Purpose: answer whether the diff matches the spec, standards, architecture, and project intent.
@@ -37,9 +39,15 @@ Then read targeted diffs only:
 
 Read relevant specs, issues, PRDs, standards, docs, ADRs, security notes, or project conventions only when they affect the changed area or the user requested that axis.
 
-## 3. Review axes
+## 3. Review axes (multi-pass with working memory)
+
+Initialize session: `.scratch/reviews/<YYYY-MM-DD>/review-<slug>/`
+
+Write `<session-dir>/session.md` with review target, base ref, scope.
 
-Standards axis:
+### Pass 1: Standards axis
+
+Analyze and write `<session-dir>/standards.md`:
 
 - style
 - architecture
@@ -48,14 +56,24 @@ Standards axis:
 - security
 - project conventions
 
-Spec axis:
+### Pass 2: Spec axis
+
+Read `<session-dir>/standards.md` for context.
+
+Analyze and write `<session-dir>/spec.md`:
 
 - did it solve the requested problem?
 - did it change public behavior unexpectedly?
 - did it miss edge cases?
 - did it violate PRD, issue, or user intent?
 
-Security/Risk axis:
+Cross-reference standards findings where relevant.
+
+### Pass 3: Security/Risk axis
+
+Read `<session-dir>/standards.md` and `<session-dir>/spec.md`.
+
+Analyze and write `<session-dir>/security.md`:
 
 - does the change touch auth, payments, PII, session data, or external API contracts?
 - does it introduce new dependencies or entitlements?
@@ -63,10 +81,9 @@ Security/Risk axis:
 - is there a regression path that would be hard to detect?
 - does the change affect audit logs or compliance obligations?
 
-For every Security/Risk finding, include the severity and a concrete
-mitigation suggestion. Omitting this axis is allowed when the change
-clearly cannot affect security (copy changes, comment fixes, test-only
-additions, docs-only updates).
+For every Security/Risk finding, include severity and mitigation. Cross-reference previous passes.
+
+Omit this axis when the change clearly cannot affect security (copy changes, comment fixes, test-only additions, docs-only updates).
 
 ## 4. Findings
 
@@ -97,12 +114,19 @@ End with exactly one result line:
 - `Review result: changes requested`
 - `Review result: blocked`
 
-## 6. Save and complete
+## 6. Synthesize and complete
+
+Read all angle files from `<session-dir>/` (standards.md, spec.md, security.md if present).
+
+Write `<session-dir>/synthesis.md` with:
 
-Write the full review (findings, axes, result) to `.scratch/reviews/<date>/review-<slug>.md`.
+- Summary of each axis
+- Cross-cutting findings (issues spanning multiple axes)
+- Prioritized findings by severity
+- Result line: `approve` / `approve with nits` / `changes requested` / `blocked`
 
 Call `attempt_completion` with:
-- file path where review was saved
+- `<session-dir>/synthesis.md` path
 - brief result line (approve / approve with nits / changes requested / blocked)
 - recommended next command
 

package/templates/full/.roo/skills/engineering/zoom-out/SKILL.md

@@ -4,7 +4,9 @@ description: Tell the agent to zoom out and give broader context or a higher-lev
 disable-model-invocation: true
 ---
 
-Zoom out: map relevant modules + callers at higher abstraction. Use glossary vocabulary.
+Uses scratch working memory for multi-dimension mapping.
+
+Zoom out: map relevant modules + callers at higher abstraction using multi-dimension working memory. Use glossary vocabulary.
 
 ## Context economy
 
@@ -18,9 +20,61 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 Start with `list_files` and `search_files`/`codebase_search`. Read representative files and key entrypoints, not every file in the area.
 
+## Multi-dimension mapping
+
+Initialize session: `.scratch/explorations/<YYYY-MM-DD>/zoom-out-<slug>/`
+
+Write `<session-dir>/session.md` with target area, scope, user request.
+
+### Dimension 1: Architecture
+
+Map to `<session-dir>/architecture.md`:
+- Module boundaries and responsibilities
+- Dependency direction (who depends on whom)
+- Seams (integration points, interfaces)
+- Layers (presentation, business, data)
+
+### Dimension 2: Data flow
+
+Read `<session-dir>/architecture.md` for context.
+
+Map to `<session-dir>/data-flow.md`:
+- Entry points (API, UI, CLI)
+- Data transformations
+- Persistence boundaries
+- External integrations
+
+Cross-reference architecture modules.
+
+### Dimension 3: Call graph
+
+Read architecture and data-flow files.
+
+Map to `<session-dir>/call-graph.md`:
+- Key functions/methods
+- Call chains (entry → core → exit)
+- Async boundaries (events, queues, callbacks)
+- Error propagation paths
+
+Cross-reference previous dimensions.
+
+### Synthesis
+
+Read all dimension files.
+
+Write `<session-dir>/synthesis.md`:
+- High-level structure (text diagram)
+- Key patterns identified
+- Coupling hotspots
+- Open questions
+- Recommended exploration paths
+
+Write the exact file path to `.scratch/LAST-EXPLORATION.md` so next commands can find it.
+
 ## Complete
 
 Call `attempt_completion` with:
+- `<session-dir>/synthesis.md` path
 - modules mapped (list)
 - key findings (summary)
 - status (complete / blocked with reason)