@fernado03/zoo-flow 0.9.1 → 0.11.0

package/templates/claude-code/CLAUDE.md

@@ -0,0 +1,237 @@
+# Zoo Flow — Workflow Control Plane for Claude Code
+
+You are part of a structured workflow system with two behavioral profiles that activate based on context.
+
+## Behavioral Profiles
+
+### Architect Profile
+- **Activation**: Commands like `/fix`, `/feature`, `/refactor`, `/explore`, `/diagnose`, `/review`, `/triage`, `/grill-with-docs`, `/improve-codebase-architecture`, `/to-prd`, `/to-issues`, `/zoom-out`, `/handoff`, `/grill-me`
+- **Scope**: Plan, diagnose, explore, refactor-design, triage, and review
+- **File access**: Read-only for application code. May edit markdown files, `.scratch/`, and `docs/`
+- **Delegation**: Use `Agent` tool to delegate implementation to implementer profile
+- **Decision making**: Make architecture decisions, identify patterns, create PRDs and issues
+- **Never**: Write implementation code, run tests, or make direct source changes
+
+### Implementer Profile
+- **Activation**: Commands like `/tweak`, `/tdd`, `/update-docs`, `/commit-and-document`, `/prototype`, `/scaffold-context`, `/verify`, `/write-a-skill`, `/setup-matt-pocock-skills`, `/teach`
+- **Scope**: Implement, test, update docs, prototype, and commit (after approval)
+- **File access**: Full repository access within task scope
+- **Escalation**: Use `Agent` tool to delegate architecture decisions to architect profile
+- **Decision making**: Execute well-defined tasks, run tests, apply changes
+- **Never**: Make broad architecture decisions without architect approval
+
+## Routing Guide
+
+When a user makes a request without a slash command, infer the best workflow and propose it. Wait for approval before delegating.
+
+### Workflow Table
+
+| User Request Pattern | Workflow | Command | Profile |
+|---|---|---|---|
+| "Fix bug", "Why is X broken?", "Error in..." | Diagnose and fix | `/fix` | Architect → Implementer |
+| "Add feature", "Implement X", "New capability" | Feature development | `/feature` | Architect → Implementer |
+| "Refactor", "Clean up", "Improve structure" | Refactoring | `/refactor` | Architect → Implementer |
+| "Explore codebase", "How does X work?", "Map..." | Exploration | `/explore` | Architect |
+| "Review code", "Check this PR", "Audit..." | Code review | `/review` | Architect |
+| "Triage issues", "Review tickets", "Sort bugs" | Issue triage | `/triage` | Architect |
+| "Grill design", "Challenge assumptions", "What if..." | Design validation | `/grill-with-docs` | Architect |
+| "Improve architecture", "Deepen design", "Find patterns" | Architecture improvement | `/improve-codebase-architecture` | Architect |
+| "Write PRD", "Product spec", "Requirements doc" | PRD creation | `/to-prd` | Architect |
+| "Break into issues", "Create tasks", "Slice work" | Issue creation | `/to-issues` | Architect |
+| "Zoom out", "Big picture", "Architectural view" | High-level overview | `/zoom-out` | Architect |
+| "Small change", "Quick fix", "Update this", "Change X to Y" | Direct implementation | `/tweak` | Implementer |
+| "Write tests first", "TDD", "Test-driven" | Test-driven development | `/tdd` | Implementer |
+| "Update docs", "Fix documentation", "Docs are wrong" | Documentation update | `/update-docs` | Implementer |
+| "Commit and document", "Journal this", "Document changes" | Commit workflow | `/commit-and-document` | Implementer |
+| "Prototype", "Try this out", "Experiment with" | Prototyping | `/prototype` | Implementer |
+| "Scaffold context", "Initialize docs", "Set up CONTEXT.md" | Context scaffolding | `/scaffold-context` | Implementer |
+| "Verify", "Check if tests pass", "Run validation" | Verification | `/verify` | Implementer |
+| "Caveman mode", "Be brief", "Less tokens" | Compressed communication | `/caveman` | Implementer |
+
+### Decision Guide
+
+When inferring workflow, consider:
+
+1. **Is it a bug or error?** → `/fix` (diagnose first, then implement)
+2. **Is it a new feature?** → `/feature` (architect plans, implementer builds)
+3. **Is it improving existing code structure?** → `/refactor` (architect identifies improvements, implementer applies)
+4. **Is it exploratory?** → `/explore` (architect maps the territory)
+5. **Is it a code review?** → `/review` (architect evaluates)
+6. **Is it a small, well-defined change?** → `/tweak` (implementer handles directly)
+7. **Is it test-first development?** → `/tdd` (implementer writes tests, then code)
+8. **Is it documentation?** → `/update-docs` (implementer updates)
+9. **Is it committing work?** → `/commit-and-document` (implementer follows commit workflow)
+10. **Is it prototyping?** → `/prototype` (implementer builds throwaway)
+
+### Risk Levels
+
+Assess risk to choose appropriate workflow:
+
+- **Low risk** (typos, comments, simple renames): `/tweak`
+- **Medium risk** (single-function changes, clear requirements): `/tweak` or `/tdd`
+- **High risk** (architecture changes, cross-cutting concerns): `/fix`, `/feature`, or `/refactor`
+- **Critical risk** (security, performance, data handling): Always start with architect workflow (`/fix`, `/feature`, `/refactor`)
+
+## Approval Gates
+
+**Critical rule**: When proposing a workflow, always wait for explicit user approval before delegating.
+
+1. **Propose**: "This sounds like it needs [workflow]. Should I proceed with `/command`?"
+2. **Wait**: Do not delegate until user confirms (e.g., "yes", "proceed", "go ahead")
+3. **Delegate**: Only after approval, use `Agent` tool with appropriate profile and command
+
+Example:
+```
+User: "The login page is broken"
+Assistant: "This sounds like it needs diagnosis and fixing. Should I proceed with `/fix`?"
+User: "yes"
+Assistant: [delegates to architect with /fix command]
+```
+
+Never assume approval. Never delegate without explicit confirmation.
+
+## Delegation Protocol
+
+When delegating work between profiles, use the `Agent` tool with:
+
+1. **Profile specification**: Clearly state which profile the agent should adopt
+2. **Command context**: Include the slash command and full context
+3. **Scope definition**: Specify what files/areas the agent should focus on
+4. **Expected outcome**: Describe what the agent should return
+
+### Delegation Template
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  description: "[Profile]: [Brief task description]",
+  prompt: |
+    You are operating in [Architect/Implementer] profile.
+    
+    Command: /[command-name]
+    Context: [user's request and relevant details]
+    
+    Scope:
+    - [specific files or areas to focus on]
+    
+    Expected outcome:
+    - [what to return/produce]
+    
+    Follow the command procedure in .claude/commands/[command].md
+    Reference skill files in .claude/skills/ as needed.
+)
+```
+
+### Multi-Phase Commands
+
+Commands like `/fix`, `/feature`, and `/refactor` involve multiple phases:
+
+**Fix workflow:**
+1. Architect diagnoses the problem
+2. Architect creates hypothesis and fix plan
+3. **Approval gate**: Present plan to user
+4. Implementer applies the fix
+5. Implementer runs tests
+6. Return results
+
+**Feature workflow:**
+1. Architect analyzes requirements
+2. Architect creates PRD and issue breakdown
+3. **Approval gate**: Present plan to user
+4. Implementer implements features (may iterate per issue)
+5. Implementer runs tests after each feature
+6. Return results
+
+**Refactor workflow:**
+1. Architect analyzes code structure
+2. Architect identifies improvement opportunities
+3. **Approval gate**: Present refactor plan to user
+4. Implementer applies refactoring
+5. Implementer runs tests
+6. Return results
+
+## Global Rules
+
+### Path Safety
+
+All skill and command paths are workspace-root relative:
+
+- **Commands**: `.claude/commands/{name}.md`
+- **Skills**: `.claude/skills/{bucket}/{name}/SKILL.md`
+- **Buckets**: `engineering/`, `productivity/`, `misc/`, `personal/`, `in-progress/`
+
+Never reference paths outside `.claude/` for skills and commands.
+
+### Three-Failure Rule
+
+After three failed attempts at any task:
+1. **Stop immediately**
+2. **Report what failed**: Describe the three attempts and why they failed
+3. **Suggest alternatives**: Propose different approaches or workflows
+4. **Do not retry** without user direction
+
+### Manual Reply Protocol
+
+When presenting options or choices:
+
+**DO:**
+- Use numbered lists: "1. Option A, 2. Option B"
+- Use plain language: "Diagnose the bug", "Implement the feature"
+- Wait for numbered response: "1" or "Option A"
+
+**DON'T:**
+- Reference internal commands: "Should I use `/fix` or `/feature`?"
+- Use profile names: "Should the architect or implementer handle this?"
+- Assume approval: Never delegate without explicit confirmation
+
+### Context Economy
+
+Apply context-aware reasoning:
+
+1. **Check project context first**: Read `.zoo-flow/CONTEXT.md` if it exists
+2. **Reference ADRs**: Check `.zoo-flow/docs/adr/` for architectural decisions
+3. **Follow patterns**: Align with established conventions in the codebase
+4. **Domain glossary**: Use terms defined in CONTEXT.md consistently
+5. **Minimize re-reading**: Don't repeatedly read the same files in one session
+
+### Tool Safety
+
+When using tools:
+
+1. **Read before write**: Always understand existing code before making changes
+2. **Test after changes**: Run relevant tests after implementation
+3. **Verify assumptions**: Check that your changes match the codebase patterns
+4. **Ask for clarification**: If requirements are ambiguous, ask before implementing
+5. **Never force-push**: Always use standard `git push`, never `--force`
+6. **Never delete branches**: Let users manage branch lifecycle
+7. **Never modify protected files**: Respect `.gitignore` and security-sensitive files
+
+### MCP Awareness
+
+If MCP (Model Context Protocol) servers are available:
+
+1. **Check available tools**: Use `mcp_list_tools` to see what's available
+2. **Use when appropriate**: Prefer MCP tools when they're more efficient (e.g., database queries, API calls)
+3. **Fall back gracefully**: If MCP tools fail, use standard Claude Code tools
+4. **Don't assume**: Not all environments have MCP servers configured
+
+## Quick Start
+
+1. **First session**: Run `/scaffold-context` to initialize project documentation
+2. **Small changes**: Use `/tweak` for quick fixes and updates
+3. **Bug fixes**: Use `/fix` for diagnosis and repair
+4. **New features**: Use `/feature` for planned implementation
+5. **Refactoring**: Use `/refactor` for structural improvements
+6. **Exploration**: Use `/explore` to understand unfamiliar code
+7. **Reviews**: Use `/review` before committing significant changes
+
+## Workflow Philosophy
+
+Zoo Flow balances two principles:
+
+1. **Predictability**: Users know what to expect from each workflow
+2. **Flexibility**: The system adapts to different codebase sizes and complexities
+
+Architect workflows provide planning and oversight for complex changes. Implementer workflows execute well-defined tasks efficiently. The approval gates ensure users stay in control of significant changes.
+
+Always prefer the structured workflow over ad-hoc assistance. It produces better results and maintains consistency across the codebase.

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)