@fernado03/zoo-flow 0.9.1 → 0.11.0

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

@@ -0,0 +1,144 @@
+---
+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.
+
+Review only. Do not patch application source. As architect profile, edits are limited to Markdown, `.scratch/`, and `docs/`.
+
+## 1. Identify target
+
+Use the narrowest target that fits the request:
+
+- User-provided base ref, PR, issue, files, or review focus.
+- Staged diff when staged changes exist.
+- Unstaged diff when unstaged changes exist.
+- Branch diff against the likely base (`main`, `master`, or merge-base) when asked to review a branch.
+- Specific files/specs/PRDs when provided.
+
+If the target is unclear, ask one short question via `AskUserQuestion` and stop.
+
+## 2. Read needed context only
+
+Start with:
+
+- `git status --short` via `Bash`
+- `git diff --stat` via `Bash`
+- `git diff --cached --stat` via `Bash` when staged changes exist
+
+Then read targeted diffs only:
+
+- `git diff -- <file>` via `Bash`
+- `git diff --cached -- <file>` via `Bash`
+- `git diff <base>...HEAD -- <file>` via `Bash`
+
+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 (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.
+
+### Pass 1: Standards axis
+
+Analyze and write `<session-dir>/standards.md`:
+
+- style
+- architecture
+- test quality
+- maintainability
+- security
+- project conventions
+
+### 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?
+
+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?
+- are there error paths that could leak information?
+- 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 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
+
+Order findings by severity:
+
+- Blocker
+- High
+- Medium
+- Low
+- Nit
+
+For every finding include:
+
+- file/path
+- line or symbol when possible
+- problem
+- why it matters
+- suggested fix
+
+Prefer concrete findings over commentary. If no findings exist for a severity, omit that severity.
+
+## 5. Result
+
+End with exactly one result line:
+
+- `Review result: approve`
+- `Review result: approve with nits`
+- `Review result: changes requested`
+- `Review result: blocked`
+
+## 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:
+
+- 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:
+- `<session-dir>/synthesis.md` path
+- brief result line (approve / approve with nits / changes requested / blocked)
+- recommended next command
+
+## Recommended next command
+
+If fixes are needed, recommend one next command only:
+
+- small fix -> `/tweak`
+- behavior fix -> `/tdd`
+- unknown cause -> `/fix`
+- design issue -> `/refactor`
+- ready for evidence -> `/verify`
+- ready to commit -> `/commit-and-document`
+
+Do not auto-launch any follow-up command.

package/templates/claude-code/.claude/skills/engineering/scaffold-context/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: scaffold-context
+description: Bootstrap or expand the project CONTEXT.md with domain language, key decisions, and conventions. Use when starting a new project, onboarding to an existing one, or when CONTEXT.md is missing/thin.
+---
+
+# Scaffold Context
+
+RULE: CONTEXT.md is the project's shared vocabulary. Keep it concise, accurate, and useful for both humans and agents.
+
+## Procedure
+
+1. Check if `.zoo-flow/CONTEXT.md` exists via `Glob`.
+2. If exists and non-empty:
+   - Read current content via `Read`.
+   - Ask user via `AskUserQuestion`: expand existing or replace entirely.
+3. If missing or thin:
+   - Explore codebase via `Glob`, `Grep`, and targeted `Read`.
+   - Identify domain language, key abstractions, conventions.
+   - Draft CONTEXT.md content.
+4. Structure CONTEXT.md with:
+   - Project purpose and scope
+   - Domain language and terminology
+   - Key architectural decisions
+   - Conventions and standards
+   - Common patterns
+5. Review with user via `AskUserQuestion`.
+6. Write to `.zoo-flow/CONTEXT.md` via `Write`.
+
+## 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 a summary with:
+- CONTEXT.md location
+- sections added/updated
+- recommended next command (typically `/explore` to deepen understanding, or `/feature`/`/refactor` to start work)

package/templates/claude-code/.claude/skills/engineering/setup-matt-pocock-skills/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: setup-matt-pocock-skills
+description: Configure Matt Pocock's TypeScript/React workflow preferences and conventions. Use when user wants to adopt Matt Pocock's coding style, TypeScript patterns, or React best practices.
+---
+
+# Setup Matt Pocock Skills
+
+RULE: Apply Matt Pocock's TypeScript and React conventions consistently. These are opinionated but battle-tested patterns.
+
+## Procedure
+
+1. Read user's current configuration via `Glob` and `Read`:
+   - `tsconfig.json`
+   - `.eslintrc` or `eslint.config.js`
+   - `package.json`
+   - Existing `.prettierrc` or similar
+2. Apply TypeScript preferences via `Edit` or `Write`:
+   - Strict mode enabled
+   - No implicit any
+   - Explicit function return types
+   - Prefer type inference for locals
+3. Apply React preferences:
+   - Functional components only
+   - Custom hooks for shared logic
+   - Proper prop typing with interfaces
+   - Avoid inline object/function definitions in JSX
+4. Apply ESLint preferences:
+   - Recommended rulesets
+   - Custom rules for common pitfalls
+5. Document conventions in `.zoo-flow/matt-pocock-conventions.md` via `Write`.
+6. Review changes with user via `AskUserQuestion`.
+
+## 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 a summary with:
+- configuration files updated
+- conventions document location
+- recommended next command (typically `/verify` to ensure config is valid)

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

@@ -0,0 +1,81 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+RULE: Test observable behaviour through public interfaces. No implementation-detail tests. Use glossary. Respect ADRs.
+
+## Planning
+
+Before code:
+1. Confirm public interface changes.
+2. Confirm behaviours; prioritise critical paths/complex logic.
+3. Identify deep-module opportunities.
+4. Design for testability.
+5. List behaviours, not implementation steps.
+6. Get user approval via `AskUserQuestion`.
+
+Ask: `What should the public interface look like? Which behaviours matter most?`
+
+## Loop
+
+DO NOT write all tests then all code.
+
+For each slice:
+1. RED: write one failing behaviour test.
+2. GREEN: write minimal code to pass.
+3. Repeat next behaviour.
+
+Rules:
+- One test at a time.
+- Public interface only.
+- Minimal code only.
+- No speculative features.
+
+## Refactor
+
+Only after green:
+1. Remove duplication.
+2. Deepen shallow modules.
+3. Apply SOLID where natural.
+4. Refactor problematic existing code revealed.
+5. Run tests after each refactor via `Bash`.
+
+Checklist per cycle:
+- [ ] Test describes behaviour.
+- [ ] Test uses public interface.
+- [ ] Test survives internal refactor.
+- [ ] Code minimal.
+- [ ] No speculation.
+
+After green, suggest `/verify`, then `/review`, then `/commit-and-document` for non-trivial work. Do not auto-launch follow-up commands.
+
+## Complete
+
+Return a summary with:
+- what was implemented (behaviours, interfaces)
+- tests written (count, pass/fail)
+- status (complete / blocked with reason)
+- recommended next command
+
+## 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.
+
+Read the public interface and nearest existing tests first. Avoid reading unrelated implementation until a failing test or search result points there.
+
+## References
+
+- `tests.md` — what to assert and what not to.
+- `mocking.md` — when (and when not) to mock.
+- `interface-design.md` — designing testable interfaces.
+- `deep-modules.md` — interface vs implementation depth.
+- `refactoring.md` — refactor candidates after green.

package/templates/claude-code/.claude/skills/engineering/to-issues/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: to-issues
+description: Break down a feature or project into implementable issues/tasks. Use after creating a PRD to plan implementation work.
+---
+
+# To Issues
+
+RULE: Each issue should be independently implementable and testable. Avoid vague or oversized issues.
+
+## Procedure
+
+1. Read PRD or requirements from `.scratch/prd/` or user input.
+2. Break down into discrete issues:
+   - Each issue has clear scope and acceptance criteria.
+   - Issues are sized appropriately (not too large, not too small).
+   - Dependencies between issues are identified.
+3. Write issues to `.scratch/issues/<feature-name>/` using `Write`.
+4. Create issue index with dependency graph.
+5. Review with user via `AskUserQuestion`.
+
+## 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:
+- issues directory location
+- issue count and summary
+- dependency graph
+- recommended next command (typically `/tdd` or `/tweak` to start implementing first issue)

package/templates/claude-code/.claude/skills/engineering/to-prd/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: to-prd
+description: Convert requirements or ideas into a Product Requirements Document. Use when defining what to build before starting implementation.
+---
+
+# To PRD
+
+RULE: PRD defines what to build, not how to build it. Implementation details belong in design docs.
+
+## Procedure
+
+1. Gather requirements from user input, discussions, or existing documentation.
+2. Structure PRD with standard sections:
+   - Problem statement
+   - Goals and objectives
+   - User stories or use cases
+   - Functional requirements
+   - Non-functional requirements
+   - Constraints and assumptions
+   - Success metrics
+3. Write PRD to `.scratch/prd/<feature-name>.md` using `Write`.
+4. Review with user via `AskUserQuestion`.
+
+## 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:
+- PRD location
+- summary of requirements
+- recommended next command (typically `/to-issues` to break down into tasks)

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

@@ -0,0 +1,36 @@
+---
+name: triage
+description: Prioritize and categorize issues, bugs, or tasks. Use when managing a backlog or deciding what to work on next.
+---
+
+# Triage
+
+RULE: Be decisive. Every item needs a clear priority and category.
+
+## Procedure
+
+1. Review list of issues/bugs/tasks (from user input, issue tracker, etc.).
+2. For each item:
+   - Assess severity (critical, high, medium, low).
+   - Categorize (bug, feature, tech debt, documentation, etc.).
+   - Estimate effort (small, medium, large).
+   - Identify dependencies or blockers.
+3. Prioritize based on impact and urgency.
+4. Document triage results in `.scratch/triage/<date>.md` using `Write`.
+
+## 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:
+- triage document location
+- prioritized list summary
+- recommended next command (typically `/fix` for bugs, `/feature` for features, or `/refactor` for tech debt)

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

@@ -0,0 +1,37 @@
+---
+name: tweak
+description: Direct implementation mode for small, known fixes or UI updates. Bypasses heavy diagnosis or PRD creation.
+---
+
+# Tweak
+
+Use for small known fixes.
+
+1. Locate target files quickly using `Glob` and `Grep`.
+2. Ask only if multiple identical matches.
+3. Implement exact requested fix.
+4. DO NOT rewrite surrounding logic unless requested.
+5. If existing test covers touched area, run it via `Bash`.
+6. DO NOT write new tests unless asked.
+7. Confirm change.
+8. For R3+ risk, suggest `/verify` before `/review` before `/commit-and-document`. Do not auto-launch. Otherwise offer `/commit-and-document` only after user satisfied.
+9. Do not auto-launch follow-up commands.
+
+## Complete
+
+Return a summary with:
+- what was changed (file paths, line ranges)
+- status (complete / blocked with reason)
+- recommended next command
+
+## 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 small changes, audit only the named files and nearby call sites. Expand search only if the first audit shows hidden dependencies.

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

@@ -0,0 +1,33 @@
+---
+name: update-docs
+description: Update documentation to reflect code changes. Use when implementation changes require documentation updates.
+---
+
+# Update Docs
+
+RULE: Documentation must match the current implementation. Stale docs are worse than no docs.
+
+## Procedure
+
+1. Identify which documentation needs updating (README, API docs, inline comments, etc.).
+2. Read existing documentation via `Glob` and `Read`.
+3. Read relevant code to understand current behavior.
+4. Update documentation using `Edit` or `Write` to match implementation.
+5. Verify documentation accuracy against code.
+
+## 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 files updated
+- summary of changes
+- recommended next command (typically `/verify` to ensure docs are accurate)

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

@@ -0,0 +1,38 @@
+---
+name: verify
+description: Run the smallest meaningful verification suite. Use after implementation to ensure changes work correctly.
+---
+
+# Verify
+
+RULE: Never claim verified unless you actually ran the checks and they passed.
+
+## Procedure
+
+1. Identify what to verify (changed files, new features, bug fixes).
+2. Determine appropriate verification commands:
+   - `Bash` with test commands (pytest, jest, etc.)
+   - `Bash` with type checking (mypy, tsc, etc.)
+   - `Bash` with linting (ruff, eslint, etc.)
+   - `Bash` with build commands if applicable
+3. Run verification commands via `Bash`.
+4. Parse output to determine pass/fail status.
+5. If any check fails, stop and report failures.
+6. If all checks pass, report success.
+
+## 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:
+- verification commands run
+- pass/fail status for each
+- recommended next command (typically `/review` if passed, or `/fix` if failed)

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

@@ -0,0 +1,74 @@
+---
+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.
+
+## Procedure
+
+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).
+
+## 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
+
+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:
+- `<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/claude-code/.claude/skills/productivity/caveman/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: caveman
+description: Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman.
+---
+
+# Caveman
+
+ACTIVE until user says stop/normal mode.
+
+Rules:
+- Drop articles/filler/pleasantries/hedging.
+- Keep technical accuracy + exact terms.
+- Fragments OK.
+- Use short synonyms.
+- Abbrev: DB/auth/config/req/res/fn/impl.
+- Use arrows for causality.
+- Code blocks unchanged.
+- Quote errors exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Auto-clarity:
+- Use normal clarity briefly for security warnings/irreversible actions/risky multi-step/repeated clarification.
+- Resume caveman after.

package/templates/claude-code/.claude/skills/productivity/grill-me/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: grill-me
+description: Interview the user about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+# Grill Me
+
+1. Interview plan/design until shared understanding.
+2. Walk design tree branch-by-branch.
+3. Resolve dependency order between decisions.
+4. Ask one question at a time via `AskUserQuestion`.
+5. Include recommended answer.
+6. Inspect code via `Read` and `Grep` instead of asking when code can answer.
+
+## Complete
+
+Return a summary with:
+- decision tree branches resolved (count)
+- key decisions made (summary)
+- status (complete / blocked with reason)
+- recommended next command

package/templates/claude-code/.claude/skills/productivity/handoff/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+---
+
+# Handoff
+
+1. Write handoff for fresh agent.
+2. Save in OS temp dir via `Bash`, not workspace.
+3. Tailor to user args.
+4. Include suggested skills section.
+5. Reference artifacts by path/URL; do not duplicate.
+6. Redact secrets/API keys/passwords/PII.
+
+## Complete
+
+Return a summary with:
+- handoff file path (OS temp dir)
+- status (complete / blocked with reason)