@fernado03/zoo-flow 0.9.1 → 0.11.0

package/templates/claude-code/.claude/commands/verify.md

@@ -0,0 +1,27 @@
+---
+description: "Verify that changes work correctly by running tests"
+argument-hint: "<what to verify>"
+---
+
+# Verify — Test and Validation
+
+This command runs tests and validations to verify changes work correctly.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access (read-only during verification)
+- **Scope**: Run tests, don't modify code
+- **Output**: Test results and verification report
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/verify/SKILL.md`
+
+## Expected Outcome
+
+- All relevant tests executed
+- Clear pass/fail results
+- Report of any issues found
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/write-a-skill.md

@@ -0,0 +1,27 @@
+---
+description: "Create a new reusable skill"
+argument-hint: "<what skill to create>"
+---
+
+# Write Skill — Skill Creation
+
+This command creates a new reusable skill that can be referenced by other commands.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access
+- **Scope**: Create skill documentation in `.claude/skills/`
+- **Output**: New skill with procedure and examples
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/productivity/write-a-skill/SKILL.md`
+
+## Expected Outcome
+
+- New skill created in appropriate bucket (engineering/, productivity/, misc/, personal/, in-progress/)
+- Clear procedure documented
+- Examples and usage guidance provided
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/zoom-out.md

@@ -0,0 +1,27 @@
+---
+description: "High-level architectural overview and zoom-out"
+argument-hint: "<what to overview>"
+---
+
+# Zoom Out — Architectural Overview
+
+This command provides a high-level architectural overview of the codebase or a specific area.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for application code
+- **Scope**: Understand big-picture architecture
+- **Output**: Architectural overview document
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/zoom-out/SKILL.md`
+
+## Expected Outcome
+
+- High-level architecture diagram or description
+- Key components and their relationships
+- Architectural patterns and decisions identified
+
+$ARGUMENTS

package/templates/claude-code/.claude/skills/engineering/commit-and-document/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: commit-and-document
+description: Commit changes and update documentation. Use after implementation is complete and verified.
+---
+
+# Commit and Document
+
+RULE: Never commit without explicit user approval. Never force-push.
+
+## Procedure
+
+1. Review changes using `Bash` with `git status` and `git diff`.
+2. Summarize changes for user.
+3. Ask user for approval via `AskUserQuestion`.
+4. If approved:
+   - Stage changes using `Bash` with `git add`.
+   - Commit using `Bash` with `git commit -m "message"`.
+   - Update relevant documentation using `Write` or `Edit`.
+5. If not approved, stop and wait for further instructions.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+## Complete
+
+Return completion with:
+- commit hash
+- files changed
+- documentation updated
+- status (committed or waiting for approval)

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

@@ -0,0 +1,136 @@
+---
+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.
+
+## 1. Feedback loop
+
+MUST build fast pass/fail loop. Try order:
+1. Failing test at bug-reaching seam.
+2. Curl/HTTP script via `Bash` vs dev server.
+3. CLI fixture + stdout diff via `Bash`.
+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 via `Bash`.
+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.
+
+## 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 (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)
+
+Drop vague hypotheses. Show ranked list. User AFK → proceed top hypothesis.
+
+## 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.
+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.
+
+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)
+
+Delegate to implementer profile via `Agent` tool before this phase. Implementer executes:
+
+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.
+
+Implementer does NOT return completion here — more phases remain. Continue to Phase 6.
+
+## 6. Cleanup
+
+**OWNER: Implementer profile** (requires source-code edits and git commit)
+
+MUST finish:
+- [ ] Original repro passes.
+- [ ] Regression passes or missing seam documented.
+- [ ] `[DEBUG-...]` logs removed from source.
+- [ ] Throwaway harnesses deleted/moved.
+- [ ] Winning hypothesis stated in commit/PR.
+- [ ] Seam/locality blocker → recommend `/improve-codebase-architecture`.
+
+Implementer returns results back to architect profile for Phase 7.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+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 and synthesize
+
+**OWNER: Architect profile** (writes to `.scratch/`)
+
+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:
+- `<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/explore/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: explore
+description: Map the codebase or a specific area to understand structure, dependencies, and key components. Use before planning features or refactors, or when entering an unfamiliar area.
+---
+
+# Explore
+
+Purpose: build a mental map of an area before making changes.
+
+## 1. Identify target
+
+Determine what to explore:
+
+- User-provided area, module, or feature
+- Entire codebase if no specific target
+- Recently changed areas if user says "what changed"
+
+If the target is unclear, ask one short question via `AskUserQuestion` and stop.
+
+## 2. Read structure
+
+Start with:
+
+- `Glob` to find file structure
+- `Grep` to find key patterns (imports, exports, entry points)
+- Targeted `Read` on entry points and key files
+
+Build understanding of:
+
+- Module boundaries
+- Key abstractions
+- Data flow
+- Dependencies
+
+## 3. Identify seams
+
+Look for:
+
+- Public interfaces (exported functions, classes, types)
+- Integration points (API calls, database queries, file I/O)
+- Test locations and coverage
+- Configuration and environment dependencies
+
+## 4. Report findings
+
+Return completion with:
+
+- modules/components identified
+- key dependencies and relationships
+- seams and integration points
+- recommended next command (typically `/fix`, `/feature`, or `/refactor` if changes needed, `/tdd` if implementation needed)
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.

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

@@ -0,0 +1,66 @@
+---
+name: feature
+description: Multi-phase workflow for implementing new features. Explore codebase, design solution, propose plan, approve, and implement. Use for new features, major enhancements, or functionality that requires architectural decisions.
+---
+
+# Feature
+
+RULE: Understand the codebase and design before implementing. Features often require architectural decisions.
+
+## 1. Explore (Architect profile)
+
+**OWNER: Architect profile** (read-only analysis)
+
+1. Use `explore` skill to map the relevant area.
+2. Understand existing patterns, seams, and dependencies.
+3. Identify where the feature fits.
+
+## 2. Design (Architect profile)
+
+**OWNER: Architect profile** (read-only design)
+
+1. Propose design with rationale.
+2. Document design in `.scratch/features/<date>/design.md`.
+3. Include architectural decisions and trade-offs.
+4. Present design to user.
+5. Wait for user approval via `AskUserQuestion`.
+
+## 3. Plan implementation (Architect profile)
+
+**OWNER: Architect profile** (read-only planning)
+
+1. Break feature into implementable steps.
+2. Each step should be independently testable.
+3. Document plan in `.scratch/features/<date>/plan.md`.
+4. Present plan to user.
+5. Wait for user approval via `AskUserQuestion`.
+
+## 4. Implement (Implementer profile)
+
+**OWNER: Implementer profile** (requires source-code edits)
+
+Delegate to implementer profile via `Agent` tool. Implementer executes:
+
+1. For each step in the plan:
+   - Write tests first if using TDD approach.
+   - Implement the change using `Edit` or `Write`.
+   - Run tests via `Bash` to verify.
+   - Commit if tests pass.
+2. If tests fail, stop and report.
+
+## 5. Verify and report
+
+Implementer returns completion with:
+- feature implemented
+- tests status (all passing)
+- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.

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

@@ -0,0 +1,59 @@
+---
+name: fix
+description: Multi-phase workflow for bug diagnosis and repair. Diagnose root cause, propose fix, approve, and implement. Use for bugs, regressions, or unexpected behavior.
+---
+
+# Fix
+
+RULE: Understand the bug before proposing a fix. Never guess at root cause.
+
+## 1. Diagnose (Architect profile)
+
+**OWNER: Architect profile** (read-only analysis)
+
+1. Use `diagnose` skill to investigate the bug.
+2. Follow the diagnose skill's phases: feedback loop, reproduce, hypothesize, instrument.
+3. Identify root cause and propose fix.
+4. Present findings to user.
+5. Wait for user approval via `AskUserQuestion`.
+
+## 2. Plan fix (Architect profile)
+
+**OWNER: Architect profile** (read-only planning)
+
+1. Document the fix plan in `.scratch/fixes/<date>/plan.md`.
+2. Include root cause, proposed solution, and test strategy.
+3. Present plan to user.
+4. Wait for user approval via `AskUserQuestion`.
+
+## 3. Implement fix (Implementer profile)
+
+**OWNER: Implementer profile** (requires source-code edits)
+
+Delegate to implementer profile via `Agent` tool. Implementer executes:
+
+1. Write regression test first using `Write` or `Edit`.
+2. Run test via `Bash` to verify it fails (red phase).
+3. Implement fix using `Edit` or `Write`.
+4. Run test via `Bash` to verify it passes (green phase).
+5. Run full test suite via `Bash`.
+6. If all tests pass, commit.
+
+## 4. Verify and report
+
+Implementer returns completion with:
+- root cause identified
+- fix implemented
+- regression test added
+- all tests passing
+- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.

package/templates/claude-code/.claude/skills/engineering/grill-with-docs/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: grill-with-docs
+description: Deep-dive exploration of a specific area with documentation. Use when you need to thoroughly understand a complex component, algorithm, or subsystem.
+---
+
+# Grill with Docs
+
+RULE: Produce comprehensive documentation, not just code exploration.
+
+## Procedure
+
+1. Identify the target area for deep exploration.
+2. Use `Glob` and `Grep` to locate all relevant files.
+3. Use `Read` to understand each component in detail.
+4. Trace data flow, control flow, and dependencies.
+5. Document findings in `.scratch/grills/<date>/<topic>.md` using `Write`.
+6. Include diagrams (text-based), code examples, and explanations.
+7. Identify key insights, potential issues, and recommendations.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+## Complete
+
+Return completion with:
+- documentation location
+- key findings and insights
+- recommended next command (typically `/feature` or `/refactor` if changes needed)

package/templates/claude-code/.claude/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: improve-codebase-architecture
+description: Analyze and improve codebase architecture. Use for structural improvements, better organization, or architectural refactoring.
+---
+
+# Improve Codebase Architecture
+
+RULE: Architecture changes should improve maintainability, testability, or clarity without changing behavior.
+
+## Procedure
+
+1. Explore current architecture using `explore` skill.
+2. Identify architectural issues:
+   - Poor separation of concerns
+   - Tight coupling
+   - Code duplication
+   - Unclear boundaries
+   - Inconsistent patterns
+3. Propose architectural improvements with rationale.
+4. Document improvements in `.scratch/architecture/<date>/proposal.md` using `Write`.
+5. Review with user via `AskUserQuestion`.
+6. If approved, create implementation plan and delegate to implementer profile.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+## Complete
+
+Return completion with:
+- architecture proposal location
+- key improvements identified
+- recommended next command (typically `/refactor` to implement changes)

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

@@ -0,0 +1,34 @@
+---
+name: prototype
+description: Create a quick prototype or proof-of-concept. Use for exploratory coding, trying out ideas, or validating approaches before committing to a design.
+---
+
+# Prototype
+
+RULE: Prototypes are throwaway code. Mark them clearly. Don't polish or test them.
+
+## Procedure
+
+1. Clarify what to prototype and the goal.
+2. Create prototype in isolated location (e.g., `.scratch/prototypes/<name>/`).
+3. Write minimal code to demonstrate the idea.
+4. Use `Write` to create files.
+5. Run prototype via `Bash` to demonstrate behavior.
+6. Document findings and recommendations.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.
+
+## Complete
+
+Return completion with:
+- prototype location
+- findings and insights
+- recommendations for next steps (proceed with design, explore alternative, or abandon)

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

@@ -0,0 +1,59 @@
+---
+name: refactor
+description: Multi-phase workflow for improving code structure. Diagnose structural issues, propose solutions, approve, and implement. Use for code smells, architectural improvements, or structural changes that don't change behavior.
+---
+
+# Refactor
+
+RULE: Refactoring changes structure, not behavior. All tests must pass before and after.
+
+## 1. Diagnose structural issues (Architect profile)
+
+**OWNER: Architect profile** (read-only analysis)
+
+1. Read relevant code via `Glob`, `Grep`, and targeted `Read`.
+2. Identify code smells, architectural issues, or improvement opportunities.
+3. Propose refactoring plan with rationale.
+4. Present findings to user.
+5. Wait for user approval via `AskUserQuestion`.
+
+## 2. Plan refactoring (Architect profile)
+
+**OWNER: Architect profile** (read-only planning)
+
+1. Break refactoring into safe, incremental steps.
+2. Each step should preserve behavior and pass tests.
+3. Document the plan in `.scratch/refactors/<date>/plan.md`.
+4. Present plan to user.
+5. Wait for user approval via `AskUserQuestion`.
+
+## 3. Implement refactoring (Implementer profile)
+
+**OWNER: Implementer profile** (requires source-code edits)
+
+Delegate to implementer profile via `Agent` tool. Implementer executes:
+
+1. For each step in the plan:
+   - Make the change using `Edit` or `Write`.
+   - Run tests via `Bash` to verify behavior preserved.
+   - Commit if tests pass.
+2. If tests fail, stop and report.
+3. Do not proceed to next step until current step verified.
+
+## 4. Verify and report
+
+Implementer returns completion with:
+- what was refactored
+- structural improvements achieved
+- tests status (all passing)
+- recommended next command (typically `/verify` then `/review` then `/commit-and-document`)
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `Glob`, `Grep`, or targeted file reads.
+
+Prefer targeted `Read` with line ranges or block reads once the relevant area is known.
+
+Read full files only when structure, ordering, or surrounding context is required for correctness.
+
+Do not re-read unchanged files; use prior findings unless the file changed.