@fernado03/zoo-flow 0.9.1 → 0.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fernado03/zoo-flow",
   "description": "Workflow control plane for Zoo Code.",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "type": "module",
   "bin": {
     "zoo-flow": "bin/zoo-flow.js"
@@ -16,7 +16,7 @@
     "quality",
     "README.md",
     "LICENSE"
-  ],
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     "project-shapes": "node scripts/test-project-shapes.js",
     "score-quality": "node scripts/score-quality.js",
     "release:check": "npm run check && npm run token-budget && npm run package-manifest && npm run golden-transcripts && npm run project-shapes && npm run score-quality && npm run pack:check"
-  },
+  },
   "engines": {
     "node": ">=18"
   },

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

@@ -0,0 +1,26 @@
+---
+description: "Extreme brevity mode - minimal tokens, maximum information density"
+---
+
+# Caveman — Extreme Brevity Mode
+
+This command activates extreme brevity for all responses.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile** with extreme brevity mode:
+- **Communication style**: Minimal tokens, telegraphic style
+- **Scope**: Answer questions and execute tasks with maximum density
+- **Output**: Shortest possible responses that convey necessary information
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/productivity/caveman/SKILL.md`
+
+## Expected Outcome
+
+- All responses in extreme brevity mode
+- Maximum information density
+- Minimal token usage
+
+This mode remains active until explicitly deactivated.

package/templates/claude-code/.claude/commands/commit-and-document.md

@@ -0,0 +1,27 @@
+---
+description: "Commit changes and update project journal"
+argument-hint: "<commit message or what to document>"
+---
+
+# Commit and Document — Version Control Workflow
+
+This command commits changes and documents them in the project journal.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access
+- **Scope**: Stage, commit, and document changes
+- **Safety**: Never force-push or delete branches
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/commit-and-document/SKILL.md`
+
+## Expected Outcome
+
+- Changes staged and committed with clear message
+- Journal entry documenting what changed and why
+- Reference to relevant issues or decisions
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Diagnose the root cause of a bug or unexpected behavior"
+argument-hint: "<what's broken or unexpected>"
+---
+
+# Diagnose — Bug Investigation
+
+This command systematically investigates the root cause of a bug or unexpected behavior.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for application code
+- **Scope**: Investigate and identify root cause, don't fix yet
+- **Output**: Diagnosis report with root cause and fix recommendations
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/diagnose/SKILL.md`
+
+## Expected Outcome
+
+- Root cause identified
+- Evidence supporting the diagnosis
+- Specific recommendations for fixing
+
+$ARGUMENTS

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

@@ -0,0 +1,46 @@
+---
+description: "Implement a new feature through multi-phase workflow"
+argument-hint: "<what feature to implement>"
+---
+
+# Feature — Feature Development
+
+This command implements a new feature through a multi-phase workflow with planning and implementation.
+
+## Behavioral Context: Architect → Implementer (Multi-Phase)
+
+This command chains two profiles:
+
+**Phase 1: Architect** (Planning)
+- **File access**: Read-only for code, write to documentation and `.scratch/`
+- **Scope**: Analyze requirements, create implementation plan
+- **Output**: Feature plan with architecture decisions and task breakdown
+
+**Phase 2: Implementer** (Implementation)
+- **File access**: Full repository access
+- **Scope**: Implement the feature according to plan
+- **Output**: Working feature with tests
+
+## Execution Flow
+
+1. **Architect Phase**: Plan the feature
+   - Read the feature skill: `.claude/skills/engineering/feature/SKILL.md`
+   - Analyze requirements and codebase
+   - Create implementation plan with architecture decisions
+   - Break down into implementation tasks
+   - **APPROVAL GATE**: Present plan to user and wait for approval
+
+2. **Implementer Phase**: Build the feature
+   - Use `Agent` tool to delegate implementation tasks
+   - Agent follows TDD workflow where appropriate
+   - Implement according to approved plan
+   - Run tests to verify
+
+## Expected Outcome
+
+- Feature requirements documented
+- Architecture decisions recorded
+- Feature implemented with tests
+- Plan document in `.scratch/`
+
+$ARGUMENTS

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

@@ -0,0 +1,45 @@
+---
+description: "Diagnose and fix a bug through multi-phase workflow"
+argument-hint: "<what bug to fix>"
+---
+
+# Fix — Bug Diagnosis and Repair
+
+This command diagnoses the root cause of a bug and implements a fix through a multi-phase workflow.
+
+## Behavioral Context: Architect → Implementer (Multi-Phase)
+
+This command chains two profiles:
+
+**Phase 1: Architect** (Diagnosis)
+- **File access**: Read-only for code, write to `.scratch/` for diagnosis notes
+- **Scope**: Investigate root cause, create hypothesis
+- **Output**: Diagnosis report with fix plan
+
+**Phase 2: Implementer** (Repair)
+- **File access**: Full repository access
+- **Scope**: Implement the fix based on diagnosis
+- **Output**: Fixed code with tests passing
+
+## Execution Flow
+
+1. **Architect Phase**: Diagnose the bug
+   - Read the diagnosis skill: `.claude/skills/engineering/diagnose/SKILL.md`
+   - Follow diagnosis procedure
+   - Present findings and proposed fix to user
+   - **APPROVAL GATE**: Wait for user to approve the fix plan
+
+2. **Implementer Phase**: Apply the fix
+   - Use `Agent` tool to delegate implementation
+   - Agent reads the tweak skill: `.claude/skills/engineering/tweak/SKILL.md`
+   - Implement the fix according to diagnosis
+   - Run tests to verify
+
+## Expected Outcome
+
+- Root cause identified and documented
+- Bug fixed with targeted change
+- Tests passing
+- Diagnosis report in `.scratch/`
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/grill-me.md

@@ -0,0 +1,27 @@
+---
+description: "Challenge assumptions and test ideas through Socratic questioning"
+argument-hint: "<what to challenge or explore>"
+---
+
+# Grill Me — Socratic Challenge
+
+This command challenges assumptions and tests ideas through rigorous questioning.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for code
+- **Scope**: Challenge thinking and explore implications
+- **Output**: Series of challenging questions and insights
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/productivity/grill-me/SKILL.md`
+
+## Expected Outcome
+
+- Assumptions identified and challenged
+- Edge cases and implications explored
+- Stronger, more robust thinking
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/grill-with-docs.md

@@ -0,0 +1,27 @@
+---
+description: "Deep-dive into documentation with examples and explanations"
+argument-hint: "<what to document or explain>"
+---
+
+# Grill with Docs — Comprehensive Documentation
+
+This command creates detailed documentation with examples, explanations, and context.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for code, write to documentation files
+- **Scope**: Create comprehensive documentation
+- **Output**: Detailed docs with examples and explanations
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/grill-with-docs/SKILL.md`
+
+## Expected Outcome
+
+- Comprehensive documentation covering the topic
+- Code examples demonstrating usage
+- Clear explanations of concepts and trade-offs
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Create a handoff document for another agent or session"
+argument-hint: "<what to hand off>"
+---
+
+# Handoff — Context Transfer
+
+This command creates a comprehensive handoff document to transfer context to another agent or session.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for code, write to `.scratch/` or documentation
+- **Scope**: Capture all relevant context and decisions
+- **Output**: Complete handoff document
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/productivity/handoff/SKILL.md`
+
+## Expected Outcome
+
+- Comprehensive handoff document
+- All relevant context captured
+- Clear next steps for the receiving agent
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/improve-codebase-architecture.md

@@ -0,0 +1,27 @@
+---
+description: "Improve codebase architecture and structure"
+argument-hint: "<what to improve>"
+---
+
+# Improve Codebase Architecture — Structural Improvements
+
+This command identifies and implements architectural improvements to the codebase.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for application code
+- **Scope**: Analyze architecture and recommend improvements
+- **Delegation**: After planning, delegate implementation to implementer
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/improve-codebase-architecture/SKILL.md`
+
+## Expected Outcome
+
+- Analysis of current architecture
+- Identification of improvement opportunities
+- Specific recommendations with implementation guidance
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Create a quick prototype or proof-of-concept"
+argument-hint: "<what to prototype>"
+---
+
+# Prototype — Rapid Prototyping
+
+This command creates a throwaway prototype to test ideas or validate approaches.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access
+- **Scope**: Build a quick prototype, not production-ready code
+- **Escalation**: If prototype reveals architectural insights, summarize for architect review
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/prototype/SKILL.md`
+
+## Expected Outcome
+
+- Working prototype demonstrating the concept
+- Clear indication this is throwaway code
+- Insights about feasibility and approach
+
+$ARGUMENTS

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

@@ -0,0 +1,46 @@
+---
+description: "Refactor code structure through multi-phase workflow"
+argument-hint: "<what to refactor>"
+---
+
+# Refactor — Code Structure Improvement
+
+This command improves code structure through a multi-phase workflow with analysis and implementation.
+
+## Behavioral Context: Architect → Implementer (Multi-Phase)
+
+This command chains two profiles:
+
+**Phase 1: Architect** (Analysis)
+- **File access**: Read-only for code, write to `.scratch/` for analysis
+- **Scope**: Analyze current structure, identify improvements
+- **Output**: Refactoring plan with rationale and steps
+
+**Phase 2: Implementer** (Implementation)
+- **File access**: Full repository access
+- **Scope**: Apply refactoring according to plan
+- **Output**: Refactored code with tests passing
+
+## Execution Flow
+
+1. **Architect Phase**: Analyze and plan
+   - Read the refactor skill: `.claude/skills/engineering/refactor/SKILL.md`
+   - Analyze current code structure
+   - Identify improvement opportunities
+   - Create refactoring plan with rationale
+   - **APPROVAL GATE**: Present plan to user and wait for approval
+
+2. **Implementer Phase**: Apply refactoring
+   - Use `Agent` tool to delegate implementation
+   - Apply refactoring in small, safe steps
+   - Run tests after each change
+   - Verify no regressions
+
+## Expected Outcome
+
+- Code structure improved
+- Rationale documented
+- All tests passing
+- Refactoring plan in `.scratch/`
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Review code for quality, security, and best practices"
+argument-hint: "<what to review>"
+---
+
+# Review — Code Quality Assessment
+
+This command performs a structured code review checking for quality, security, performance, and adherence to best practices.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for application code
+- **Scope**: Analyze code without modifying it
+- **Output**: Review report with findings and recommendations
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/review/SKILL.md`
+
+## Expected Outcome
+
+- Review report identifying issues and recommendations
+- Categorization by severity (critical, high, medium, low)
+- Specific suggestions for improvements
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/scaffold-context.md

@@ -0,0 +1,27 @@
+---
+description: "Create or update project context documentation"
+argument-hint: "<what context to scaffold>"
+---
+
+# Scaffold Context — Project Documentation Setup
+
+This command creates or updates project context documentation to establish shared understanding.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access
+- **Scope**: Create/update project documentation
+- **Output**: Context documentation files
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/scaffold-context/SKILL.md`
+
+## Expected Outcome
+
+- Project context documentation created or updated
+- Shared understanding of project goals and constraints
+- Reference material for future sessions
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Set up Matt Pocock skills and patterns"
+argument-hint: "<what to set up>"
+---
+
+# Setup Matt Pocock Skills — Pattern Setup
+
+This command sets up Matt Pocock's recommended skills and patterns for the project.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access
+- **Scope**: Set up recommended skills and patterns
+- **Output**: Configured skills and patterns
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/setup-matt-pocock-skills/SKILL.md`
+
+## Expected Outcome
+
+- Matt Pocock skills installed and configured
+- Recommended patterns established
+- Project ready for advanced workflows
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Test-driven development workflow: write tests first, then implement"
+argument-hint: "<what to build or test>"
+---
+
+# TDD — Test-Driven Development
+
+This command follows the red-green-refactor cycle: write failing tests, implement to pass, then refactor.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access
+- **Scope**: Write tests first, then implementation
+- **Escalation**: If tests reveal architectural issues, delegate to architect
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/tdd/SKILL.md`
+
+## Expected Outcome
+
+- Tests written before implementation
+- Implementation that passes all tests
+- Refactored code following best practices
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Teach a concept through structured learning"
+argument-hint: "<what to teach>"
+---
+
+# Teach — Structured Learning
+
+This command teaches a concept through structured explanation, examples, and exercises.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access for examples
+- **Scope**: Teach concepts clearly and thoroughly
+- **Output**: Structured learning material
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/productivity/teach/SKILL.md`
+
+## Expected Outcome
+
+- Clear explanation of the concept
+- Code examples demonstrating usage
+- Exercises for practice
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/to-issues.md

@@ -0,0 +1,27 @@
+---
+description: "Break down a feature into implementable issues"
+argument-hint: "<what feature to break down>"
+---
+
+# To Issues — Issue Breakdown
+
+This command breaks down a feature or task into discrete, implementable issues.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for code, write to issue tracker or `.scratch/`
+- **Scope**: Decompose work into manageable issues
+- **Output**: List of issues with descriptions and acceptance criteria
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/to-issues/SKILL.md`
+
+## Expected Outcome
+
+- Feature broken into discrete issues
+- Each issue clearly scoped and actionable
+- Dependencies and order of implementation identified
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/to-prd.md

@@ -0,0 +1,27 @@
+---
+description: "Create a Product Requirements Document"
+argument-hint: "<what feature or product to document>"
+---
+
+# To PRD — Product Requirements Document
+
+This command creates a comprehensive Product Requirements Document for a feature or product.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for code, write to documentation files
+- **Scope**: Define requirements, user stories, and acceptance criteria
+- **Output**: Complete PRD document
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/to-prd/SKILL.md`
+
+## Expected Outcome
+
+- Clear product requirements and user stories
+- Acceptance criteria for each requirement
+- Technical constraints and dependencies identified
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Triage and prioritize issues or tasks"
+argument-hint: "<what to triage>"
+---
+
+# Triage — Issue Prioritization
+
+This command helps triage and prioritize issues, bugs, or tasks.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for code, write to issue tracker or `.scratch/`
+- **Scope**: Analyze and categorize issues, don't fix them
+- **Output**: Prioritized issue list with recommendations
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/triage/SKILL.md`
+
+## Expected Outcome
+
+- Issues categorized by severity and priority
+- Clear recommendations for next actions
+- Identification of blockers or dependencies
+
+$ARGUMENTS

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

@@ -0,0 +1,27 @@
+---
+description: "Make a small, targeted code change"
+argument-hint: "<what to tweak>"
+---
+
+# Tweak — Small Code Change
+
+This command makes small, targeted changes to existing code.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access
+- **Scope**: Make targeted code changes
+- **Output**: Modified code with tests passing
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/tweak/SKILL.md`
+
+## Expected Outcome
+
+- Small change implemented successfully
+- Tests passing
+- No unintended side effects
+
+$ARGUMENTS

package/templates/claude-code/.claude/commands/update-docs.md

@@ -0,0 +1,27 @@
+---
+description: "Update project documentation to reflect current state"
+argument-hint: "<what documentation to update>"
+---
+
+# Update Docs — Documentation Maintenance
+
+This command updates project documentation to match the current implementation.
+
+## Behavioral Context: Implementer
+
+You are operating in the **Implementer profile**:
+- **File access**: Full repository access for documentation files
+- **Scope**: Update docs, README, comments, or other documentation
+- **Escalation**: If doc updates reveal architectural confusion, delegate to architect
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/update-docs/SKILL.md`
+
+## Expected Outcome
+
+- Documentation updated to match current code
+- Clear, accurate descriptions of functionality
+- Consistent terminology throughout
+
+$ARGUMENTS