@fernado03/zoo-flow 0.1.0

package/templates/full/.roo/rules-code-tweaker/01-completion.md

@@ -0,0 +1,14 @@
+# Code Tweaker Completion
+
+If created by `custom-orchestrator` via `new_task`, use `attempt_completion` when done or blocked.
+
+Include:
+
+- what was done
+- files changed or inspected
+- commands/tests run
+- status
+- blockers
+- recommended next command
+
+Before running `git commit` or `git push`, halt and wait for explicit user approval. Never push unless explicitly asked.

package/templates/full/.roo/rules-custom-orchestrator/00-routing.md

@@ -0,0 +1,14 @@
+# Orchestrator Routing
+
+The orchestrator is a router only.
+
+Do not inspect implementation files, edit files, run shell commands, or answer technical implementation questions directly.
+
+If the user gives a technical request without an explicit command, offer 1-2 numbered workflow choices and ask for a typed number.
+
+Delegate only with `new_task` to:
+
+- `code-tweaker`
+- `system-architect`
+
+After a subtask returns, summarize and stop. Do not auto-launch another subtask.

package/templates/full/.roo/rules-custom-orchestrator/01-delegation-message.md

@@ -0,0 +1,12 @@
+# Delegation Message
+
+Every delegated task must include:
+
+- command with slash
+- normalized command name
+- user context
+- instruction to follow `.roo/rules/01-command-protocol.md`
+- reminder that skills live under `.roo/skills/...`
+- completion rule to use `attempt_completion` with summary, files inspected/changed, commands/tests run, blockers, and recommended next command
+
+Ignore slash commands mentioned only inside subtask summaries.

package/templates/full/.roo/rules-system-architect/00-scope.md

@@ -0,0 +1,9 @@
+# System Architect Scope
+
+Plan, diagnose, explore, refactor-design, and triage.
+
+Do not edit application source code.
+
+Edits are limited to Markdown files, `.scratch/`, and `docs/`.
+
+Use `switch_mode` to `code-tweaker` for implementation, test-writing, runnable prototypes, or source-code edits.

package/templates/full/.roo/rules-system-architect/01-feature-prototype.md

@@ -0,0 +1,10 @@
+# Feature Prototype Handoff
+
+During `/feature`, do not run prototype implementation directly.
+
+If the user chooses Prototype:
+
+1. Summarize the prototype question and constraints.
+2. Use `switch_mode` to `code-tweaker`.
+3. Have `code-tweaker` execute `/prototype`.
+4. Resume architecture flow after the prototype result returns.

package/templates/full/.roo/rules-system-architect/02-completion.md

@@ -0,0 +1,11 @@
+# System Architect Completion
+
+Use `switch_mode` to `code-tweaker` for same-window implementation handoffs.
+
+If created by `custom-orchestrator` via `new_task`, use `attempt_completion` when the delegated task is complete or blocked.
+
+Do not use `attempt_completion` to avoid required implementation work.
+
+Halt for explicit user approval before testing a bug hypothesis, finalizing an architecture plan, publishing issues, or making irreversible decisions.
+
+If diagnosis fails after 3 attempts, halt and request user intervention with attempts, evidence, and needed input.

package/templates/full/.roo/skills/docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md

@@ -0,0 +1,18 @@
+# ADR-0001: Explicit setup pointer only for hard dependencies
+
+RULE: explicit `/setup-matt-pocock-skills` pointer only for hard deps.
+
+MUST include pointer:
+- `to-issues`
+- `to-prd`
+- `triage`
+
+Required wording: mapping/config should exist; run `/setup-matt-pocock-skills` if missing.
+
+MUST NOT include pointer:
+- `diagnose`
+- `tdd`
+- `improve-codebase-architecture`
+- `zoom-out`
+
+Soft deps: reference glossary/ADRs only.

package/templates/full/.roo/skills/engineering/README.md

@@ -0,0 +1,12 @@
+# Engineering
+
+- **[diagnose](./diagnose/SKILL.md)** — Repro loop → hypotheses → probes → fix → regression.
+- **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grill plan; update glossary/ADRs.
+- **[triage](./triage/SKILL.md)** — Issue state machine.
+- **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Deep-module candidates.
+- **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Seed tracker/labels/domain docs.
+- **[tdd](./tdd/SKILL.md)** — Red-green-refactor slices.
+- **[to-issues](./to-issues/SKILL.md)** — Plan/PRD → tracer issues.
+- **[to-prd](./to-prd/SKILL.md)** — Context → PRD issue.
+- **[zoom-out](./zoom-out/SKILL.md)** — Map modules/callers.
+- **[prototype](./prototype/SKILL.md)** — Throwaway logic/UI prototype.

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

@@ -0,0 +1,73 @@
+---
+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.
+---
+
+# Diagnose
+
+RULE: glossary + ADRs. Skip phase only with explicit reason. DO NOT hypothesise before deterministic loop.
+
+## 1. Feedback loop
+
+MUST build fast pass/fail loop. Try order:
+1. Failing test at bug-reaching seam.
+2. Curl/HTTP script vs dev server.
+3. CLI fixture + stdout diff.
+4. Headless browser: DOM/console/network assertions.
+5. Replay trace/request/payload/event log.
+6. Throwaway minimal subsystem harness.
+7. Property/fuzz loop.
+8. `git bisect run` harness.
+9. Differential loop: old vs new/config A vs B.
+10. HITL bash script from `scripts/hitl-loop.template.sh`.
+
+Rules:
+- MUST make loop faster/sharper/deterministic.
+- Flake: run 100x, parallelise, stress, add sleeps, raise repro rate.
+- 3 failed loop attempts → STOP; ask env/HAR/log/core/screen recording/temp prod instrumentation.
+
+## 2. Reproduce
+
+1. Run loop.
+2. Match symptom to report.
+3. Confirm repeatability/flake rate.
+4. Capture exact error/output/timing.
+5. DO NOT continue until reproduced.
+
+## 3. Hypotheses
+
+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.
+
+## 4. Instrument
+
+1. Map one probe to one hypothesis.
+2. Change one variable at a time.
+3. Prefer debugger/REPL.
+4. Else add targeted logs only.
+5. Tag logs `[DEBUG-xxxx]`.
+6. DO NOT log everything.
+7. Perf: baseline/profiler/query plan before logs.
+
+## 5. Fix + regression
+
+1. If correct seam exists, write regression test before fix.
+2. Correct seam = real call-site bug pattern.
+3. If seam shallow/missing, document architecture gap.
+4. Watch regression fail.
+5. Apply minimal fix.
+6. Watch regression pass.
+7. Rerun original loop.
+
+## 6. Cleanup
+
+MUST finish:
+- [ ] Original repro passes.
+- [ ] Regression passes or missing seam documented.
+- [ ] `[DEBUG-...]` logs removed.
+- [ ] Throwaway harnesses deleted/moved.
+- [ ] Winning hypothesis stated in commit/PR.
+- [ ] Seam/locality blocker → recommend `/improve-codebase-architecture`.

package/templates/full/.roo/skills/engineering/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

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

@@ -0,0 +1,33 @@
+# ADR Format
+
+Path: `docs/adr/NNNN-slug.md`. Create dir lazily.
+
+## Template
+
+```md
+# {Short title}
+
+{1-3 sentences: context, decision, why.}
+```
+
+Optional:
+- `Status: proposed | accepted | deprecated | superseded by ADR-NNNN`
+- `Considered Options`
+- `Consequences`
+
+## Numbering
+
+1. Scan `docs/adr/`.
+2. Find max `NNNN`.
+3. Create next number.
+
+## Gate
+
+Offer ADR only if all:
+- Hard to reverse.
+- Surprising without context.
+- Real trade-off.
+
+Qualifies: architecture shape; cross-context integration; lock-in tech; scope ownership; non-obvious deviation/constraint/rejected option.
+
+DO NOT create ADR for obvious/easy/no-tradeoff choices.

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

@@ -0,0 +1,45 @@
+# CONTEXT.md Format
+
+## Shape
+
+```md
+# {Context Name}
+
+{1-2 sentences: context purpose.}
+
+## Language
+
+**Order**:
+{1-2 sentence definition}
+_Avoid_: Purchase, transaction
+
+## Flagged ambiguities
+
+**Account** means Customer here, not User.
+```
+
+## Rules
+
+- MUST pick canonical term; aliases under `_Avoid_`.
+- MUST flag ambiguity + resolution.
+- Define term in 1–2 sentences: what it is, not behavior.
+- Include relationships/cardinality when obvious.
+- Include domain terms only; exclude generic programming terms.
+- Group under headings when useful.
+- Include example dialogue.
+
+## Layout
+
+Single-context:
+- `CONTEXT.md`
+- `docs/adr/`
+
+Multi-context:
+- `CONTEXT-MAP.md`
+- Per-context `CONTEXT.md` + optional `docs/adr/`
+
+Detection:
+1. If `CONTEXT-MAP.md`, read map + relevant contexts.
+2. Else if root `CONTEXT.md`, use it.
+3. Else create root `CONTEXT.md` lazily on first resolved term.
+4. If context ambiguous, ask.

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

@@ -0,0 +1,32 @@
+---
+name: grill-with-docs
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+---
+
+# Grill With Docs
+
+## Loop
+
+1. Read relevant `CONTEXT.md`/`CONTEXT-MAP.md` + ADRs.
+2. Ask one question at a time.
+3. Include recommended answer.
+4. Inspect code instead of asking when code can answer.
+5. Continue until design branches resolved.
+6. Update docs inline when terms/decisions crystallise.
+
+## Docs
+
+- Single-context: root `CONTEXT.md`, root `docs/adr/`.
+- Multi-context: root `CONTEXT-MAP.md` → per-context `CONTEXT.md` + ADRs.
+- Create docs lazily only when recording needed.
+
+## MUST
+
+- Challenge glossary conflicts.
+- Sharpen fuzzy/overloaded terms.
+- Use scenarios/edge cases.
+- Cross-check claims against code.
+- Surface code/doc contradictions.
+- Update `CONTEXT.md` immediately for resolved terms.
+- Keep `CONTEXT.md` glossary-only; no impl/spec notes.
+- Offer ADR only when hard to reverse + surprising + real trade-off; use `ADR-FORMAT.md`.

package/templates/full/.roo/skills/engineering/improve-codebase-architecture/DEEPENING.md

@@ -0,0 +1,24 @@
+# Deepening
+
+Vocabulary: `LANGUAGE.md`.
+
+## Dependency categories
+
+1. In-process: pure/local memory/no I/O → deepen directly; test interface.
+2. Local-substitutable: local stand-in exists → test with stand-in; keep seam internal unless callers need it.
+3. Remote owned: owned network service → port at seam; prod adapter HTTP/gRPC/queue; test adapter in-memory; logic inside deep module.
+4. True external: third-party → inject port; tests use mock adapter.
+
+## Seam rules
+
+- One adapter = hypothetical seam; avoid.
+- Two adapters = real seam; allow.
+- Internal seams stay private.
+- DO NOT expose test seams through external interface.
+
+## Tests
+
+- Replace shallow-module unit tests with deep-module interface tests.
+- Interface is test surface.
+- Assert observable outcomes only.
+- Tests must survive internal refactor.

package/templates/full/.roo/skills/engineering/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,88 @@
+# HTML Report Format
+
+RULE: Write one self-contained HTML file in OS temp dir. Static only except Tailwind CDN + Mermaid CDN.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Include: repo, date, legend: solid box=module; dashed line=seam; red arrow=leakage; dark thick box=deep module.
+
+## Candidate `<article>`
+
+MUST include:
+- Title.
+- Badges: `Strong`/`Worth exploring`/`Speculative`; dependency category.
+- Monospace files list.
+- Before/after diagram side-by-side.
+- Problem: one sentence.
+- Solution: one sentence.
+- Wins: bullets, max 6 words.
+- ADR callout if conflict/reopen.
+
+## Diagrams
+
+Use best fit:
+- Mermaid graph/flow/sequence for call/dependency graphs.
+- Hand-built boxes + SVG arrows if Mermaid layout fails.
+- Cross-section for stacked shallow layers.
+- Mass diagram for interface vs implementation size.
+- Call-graph collapse for before tree → after deep module.
+
+Mermaid example:
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+## Style
+
+- Sparse; visual; whitespace.
+- Accents: emerald/indigo; red leakage; amber warnings.
+- Diagrams ~320px high.
+- Module labels: `text-xs uppercase tracking-wider`.
+
+## Top recommendation
+
+Include candidate name, one-sentence reason, anchor link.
+
+## Vocabulary
+
+Use: module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+Avoid: component, service, unit, API, signature, boundary, layer, wrapper.

package/templates/full/.roo/skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md

@@ -0,0 +1,45 @@
+# Interface Design
+
+Use after candidate selected + user wants interface options.
+
+## 1. Frame
+
+Present:
+- New-interface constraints.
+- Dependencies + categories from `DEEPENING.md`.
+- Rough illustrative code sketch only.
+
+Proceed immediately.
+
+## 2. Spawn 3+ parallel sub-agents
+
+Each agent: radically different interface.
+
+Include:
+- Candidate files/modules.
+- Coupling details.
+- Dependency category.
+- Hidden implementation behind seam.
+- Architecture vocab from `LANGUAGE.md`.
+- Domain vocab from `CONTEXT.md`.
+
+Variants:
+1. Min interface: 1–3 entry points, max leverage.
+2. Max flexibility: many use cases/extensions.
+3. Common caller: default case trivial.
+4. Ports/adapters: if cross-seam deps exist.
+
+Each output MUST include:
+1. Interface: types/methods/params/invariants/ordering/errors.
+2. Usage example.
+3. Hidden implementation.
+4. Dependency/adapters strategy.
+5. Trade-offs: leverage high/thin.
+
+## 3. Present
+
+1. Present designs sequentially.
+2. Compare depth/locality/seam placement.
+3. Recommend strongest.
+4. Propose hybrid if better.
+5. Be opinionated.

package/templates/full/.roo/skills/engineering/improve-codebase-architecture/LANGUAGE.md

@@ -0,0 +1,34 @@
+# Language
+
+RULE: Use exact terms. Avoid substitutions.
+
+## Terms
+
+**Module**: thing with interface + implementation; any scale. Avoid: unit, component, service.
+
+**Interface**: all caller knowledge: types, invariants, ordering, error modes, config, perf. Avoid: API, signature.
+
+**Implementation**: code inside module. Use **adapter** only for seam role.
+
+**Depth**: leverage at interface. Deep = much behaviour behind small interface. Shallow = interface near implementation.
+
+**Seam**: place where behaviour changes without editing there; where module interface lives. Avoid: boundary.
+
+**Adapter**: concrete thing satisfying interface at seam.
+
+**Leverage**: caller gain from depth.
+
+**Locality**: maintainer gain from depth; change/bugs/knowledge/verification concentrate.
+
+## Rules
+
+- Depth belongs to interface, not implementation size.
+- Internal seams may exist; external seam is caller interface.
+- Deletion test: deleting shallow module removes complexity; deleting deep module pushes complexity to callers.
+- Interface is test surface.
+- One adapter = hypothetical seam; two adapters = real seam.
+- Module has one interface.
+- Depth creates leverage + locality.
+- DO NOT frame depth as implementation-lines/interface-lines.
+- DO NOT equate interface with TypeScript `interface` only.
+- DO NOT use boundary; use seam/interface.

package/templates/full/.roo/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+---
+
+# Improve Codebase Architecture
+
+RULE: Use `LANGUAGE.md` terms. Use glossary. Respect ADRs; surface only reopen-worthy conflicts.
+
+## Explore
+
+1. Read relevant `CONTEXT.md`/`CONTEXT-MAP.md`.
+2. Read relevant ADRs.
+3. Explore code organically.
+4. Find friction:
+   - Concept requires many-module bouncing.
+   - Module shallow: interface ≈ implementation.
+   - Pure fns exist only for tests; no locality.
+   - Tight modules leak across seams.
+   - Tests absent/hard through current interface.
+5. Apply deletion test.
+6. Keep candidates where deepening improves leverage/locality/testability.
+
+## Report
+
+1. Temp dir: `$TMPDIR` else `/tmp` (Windows `%TEMP%`).
+2. Write fresh `{tmpdir}/architecture-review-{timestamp}.html`.
+3. Use Tailwind CDN + Mermaid CDN.
+4. Include candidate cards with before/after visuals.
+5. Per candidate include: files/modules; problem; solution; locality/leverage/testing benefits; diagram; strength `Strong`/`Worth exploring`/`Speculative`; ADR conflict only if real.
+6. Include Top recommendation.
+7. Open file: Linux `xdg-open {path}`, macOS `open {path}`, Windows `start {path}`.
+8. Tell user absolute path.
+9. DO NOT propose interfaces yet.
+10. Ask: `Which of these would you like to explore?`
+
+## After candidate chosen
+
+1. Walk constraints/deps/seam/hidden implementation/surviving tests.
+2. If module name introduces unresolved domain term, update `CONTEXT.md` lazily.
+3. If term sharpened, update `CONTEXT.md` immediately.
+4. Durable rejected reason useful later → offer ADR.
+5. Interface options requested → run `INTERFACE-DESIGN.md`.

package/templates/full/.roo/skills/engineering/prototype/LOGIC.md

@@ -0,0 +1,28 @@
+# Logic Prototype
+
+Use for business logic/state/data-model questions.
+
+## Process
+
+1. State question in README/top comment: state model? uncertainty?
+2. Use host language/runtime/tooling; ask if unclear.
+3. Isolate portable pure logic: reducer, state machine, pure fns, or class/module with small surface.
+4. DO NOT put terminal/IO/console in logic module.
+5. Build minimal TUI:
+   - Init in-memory state.
+   - Render whole frame on start and after each action.
+   - State first, shortcuts second.
+   - ANSI bold/dim ok.
+   - Read one key/line at a time.
+   - Loop until quit.
+6. Add one command via existing task runner: `pnpm run {prototype-name}`.
+7. If no runner, document command at top of README.
+8. Hand over run command.
+9. If verdict unknown, write `NOTES.md` beside prototype.
+
+## Rules
+
+- No tests.
+- No real DB unless persistence is question; then scratch DB/file clearly marked prototype.
+- No generalising.
+- TUI shell throwaway; portable logic may be lifted.

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

@@ -0,0 +1,27 @@
+---
+name: prototype
+description: Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
+---
+
+# Prototype
+
+RULE: Prototype answers one question. Throw away or absorb after answer.
+
+## Branch
+
+- Logic/state/data-model → `LOGIC.md`.
+- Visual/layout/UI → `UI.md`.
+- Ambiguous → ask.
+- User AFK → infer + state assumption.
+
+## Rules
+
+1. Mark throwaway clearly.
+2. Place near real module/page.
+3. Follow existing routing/tooling.
+4. Provide one run command.
+5. Default no persistence; state in memory.
+6. Persistence target → scratch DB/file named `PROTOTYPE — wipe me` or equivalent.
+7. No polish: no tests, minimal errors, no abstractions.
+8. Surface full relevant state after each action/variant switch.
+9. Done → capture answer in commit/ADR/issue/`NOTES.md`; delete or fold into real code.