@fernado03/zoo-flow 0.11.1 → 0.11.3

package/bin/zoo-flow.js

@@ -770,8 +770,6 @@ Next:
   3. Try a small request, e.g.:
        change a harmless comment in README
   4. Or use a slash command like /tweak or /fix
-
-When workflow choices appear, type the number manually, e.g. 1.
 `);
   }
 }

package/package.json

@@ -1,55 +1,45 @@
-{
-  "name": "@fernado03/zoo-flow",
-  "description": "Workflow control plane for Zoo Code.",
-  "version": "0.11.1",
-  "type": "module",
-  "bin": {
-    "zoo-flow": "bin/zoo-flow.js"
-  },
-  "files": [
-    "bin",
-    "scripts",
-    "templates",
-    "tests",
-    "docs",
-    "examples",
-    "quality",
-    "README.md",
-    "LICENSE"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Fernado03/zoo-flow.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Fernado03/zoo-flow/issues"
-  },
-  "homepage": "https://github.com/Fernado03/zoo-flow#readme",
-  "keywords": [
-    "zoo-code",
-    "zoo",
-    "ai-agents",
-    "coding-agents",
-    "workflow",
-    "slash-commands",
-    "custom-modes",
-    "agent-workflows"
-  ],
-  "scripts": {
-    "check": "node scripts/test-doctor.js && node bin/zoo-flow.js doctor --template-only && node scripts/eval-routing.js && node scripts/check-package-links.js",
-    "pack:check": "npm pack --dry-run",
-    "token-budget": "node scripts/token-budget.js",
-    "package-manifest": "node scripts/check-package-manifest.js",
-    "golden-transcripts": "node scripts/check-golden-transcripts.js",
-    "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"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@fernado03/zoo-flow",
+  "version": "0.11.3",
+  "description": "Structured workflow templates for AI coding assistants",
+  "type": "module",
+  "bin": {
+    "zoo-flow": "./bin/zoo-flow.js"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "scripts/",
+    "tests/"
+  ],
+  "keywords": [
+    "ai",
+    "coding-assistant",
+    "workflow",
+    "claude",
+    "zoo-code",
+    "roo-code"
+  ],
+  "author": "Fernado",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fernado03/zoo-flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Fernado03/zoo-flow/issues"
+  },
+  "homepage": "https://github.com/Fernado03/zoo-flow#readme",
+  "scripts": {
+    "check": "node scripts/test-doctor.js && node bin/zoo-flow.js doctor --template-only && node scripts/eval-routing.js && node scripts/check-package-links.js",
+    "token-budget": "node scripts/token-budget.js",
+    "package-manifest": "node scripts/check-package-manifest.js",
+    "golden-transcripts": "node scripts/check-golden-transcripts.js",
+    "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"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

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

@@ -0,0 +1,28 @@
+---
+description: "Explore and understand a codebase area"
+argument-hint: "<what to explore>"
+---
+
+# Explore — Codebase Understanding
+
+This command systematically explores a codebase area to build understanding and create documentation.
+
+## Behavioral Context: Architect
+
+You are operating in the **Architect profile**:
+- **File access**: Read-only for code, write to `.scratch/` for exploration notes
+- **Scope**: Understand and document code structure
+- **Output**: Exploration report with insights and recommendations
+
+## Procedure
+
+Read and follow the skill file: `.claude/skills/engineering/explore/SKILL.md`
+
+## Expected Outcome
+
+- Deep understanding of the explored area
+- Documentation of structure and patterns
+- Recommendations for improvements or next steps
+- Exploration report in `.scratch/`
+
+$ARGUMENTS

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

@@ -30,7 +30,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - commit hash
 - files changed
 - documentation updated

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

@@ -128,7 +128,8 @@ Write `<session-dir>/root-cause.md`:
 
 Write `<session-dir>/diagnosis.md` with full log (hypotheses, instrumentation results, timeline).
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - `<session-dir>/root-cause.md` path
 - root cause summary
 - fix applied

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

@@ -43,7 +43,7 @@ Look for:
 
 ## 4. Report findings
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
 
 - modules/components identified
 - key dependencies and relationships

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

@@ -50,7 +50,8 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 
 ## 5. Verify and report
 
-Implementer returns completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - feature implemented
 - tests status (all passing)
 - recommended next command (typically `/verify` then `/review` then `/commit-and-document`)

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

@@ -41,7 +41,8 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 
 ## 4. Verify and report
 
-Implementer returns completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - root cause identified
 - fix implemented
 - regression test added

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

@@ -29,7 +29,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -33,7 +33,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - architecture proposal location
 - key improvements identified
 - recommended next command (typically `/refactor` to implement changes)

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

@@ -28,7 +28,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -42,7 +42,8 @@ Delegate to implementer profile via `Agent` tool. Implementer executes:
 
 ## 4. Verify and report
 
-Implementer returns completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - what was refactored
 - structural improvements achieved
 - tests status (all passing)

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

@@ -125,7 +125,8 @@ Write `<session-dir>/synthesis.md` with:
 - Prioritized findings by severity
 - Result line: `approve` / `approve with nits` / `changes requested` / `blocked`
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - `<session-dir>/synthesis.md` path
 - brief result line (approve / approve with nits / changes requested / blocked)
 - recommended next command

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

@@ -38,7 +38,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -42,7 +42,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -54,7 +54,8 @@ After green, suggest `/verify`, then `/review`, then `/commit-and-document` for
 
 ## Complete
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - what was implemented (behaviours, interfaces)
 - tests written (count, pass/fail)
 - status (complete / blocked with reason)

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

@@ -30,7 +30,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - issues directory location
 - issue count and summary
 - dependency graph

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

@@ -33,7 +33,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -30,7 +30,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -19,7 +19,8 @@ Use for small known fixes.
 
 ## Complete
 
-Return a summary with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - what was changed (file paths, line ranges)
 - status (complete / blocked with reason)
 - recommended next command

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

@@ -27,7 +27,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -32,7 +32,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - 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

@@ -68,7 +68,8 @@ Do not re-read unchanged files; use prior findings unless the file changed.
 
 ## Complete
 
-Return completion with:
+**COMPLETION PROTOCOL**: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
+
 - `<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/in-progress/writing-beats/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: writing-beats
+description: Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.
+---
+
+# Writing Beats
+
+## Setup
+
+1. Use `Read` to read raw markdown fully.
+2. If article output path missing, ask once.
+3. Never edit raw material.
+4. Use `Read` to re-read article before every `Write`.
+
+## Loop
+
+1. Offer 2–3 starting beats from raw material.
+2. Preview likely next pivots for each.
+3. User picks.
+4. Use `Write` to write only selected beat to article.
+5. Use `Read` to re-read article.
+6. Offer 2–3 next beats from current ending.
+7. Loop until natural end.
+
+## Rules
+
+- Beat = one move: scene/point/question/aside/twist.
+- Size to need: sentence, paragraph, or short vignette.
+- If needs headings/5 paragraphs, split.
+- Pull/paraphrase/split/merge raw fragments.
+- Leave unused raw material.
+- Rewrite/go back → edit specific beat; preserve rest.

package/templates/claude-code/.claude/skills/in-progress/writing-fragments/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: writing-fragments
+description: Grilling session that mines the user for fragments — heterogeneous nuggets of writing (claims, vignettes, sharp sentences, half-thoughts) — and appends them to a single document as raw material for a future article. Use when the user wants to develop ideas before imposing structure, or mentions "fragments", "ideate", or "raw material" for writing.
+---
+
+# Writing Fragments
+
+## Setup
+
+1. Capture fragments from initial prompt onward.
+2. If output path missing, ask once.
+3. First write: one H1 working title; no metadata/TOC/date.
+4. Use `Read` to re-read file before every `Write`.
+5. Use `Write` to append only unless user requests specific edit.
+
+## Fragment forms
+
+- Sharp sentence.
+- Claim + one-line reason.
+- Vignette/scenario/analogy/code snippet.
+- Half-thought.
+- Quote/dialogue.
+- Observation cluster.
+- Complaint/confession/punchline.
+
+## File format
+
+```markdown
+# Working title
+
+Fragment one.
+
+---
+
+Fragment two.
+```
+
+Rules:
+- Separate fragments with `---`.
+- No body headings/tags.
+- Order = capture order.
+- Append silently; mention briefly.
+- Preserve user edits.
+- Support `cut last`, `rewrite`, `merge` immediately.
+- DO NOT impose outline/structure.

package/templates/claude-code/.claude/skills/in-progress/writing-shape/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: writing-shape
+description: Take a markdown file of raw material and shape it into an article through a conversational session — drafting candidate openings, growing the piece paragraph by paragraph, arguing about format (lists, tables, callouts, quotes) at each step. Use when the user has a pile of notes, fragments, or a rough draft and wants help turning it into something publishable.
+---
+
+# Writing Shape
+
+## Setup
+
+1. Use `Read` to read raw markdown fully.
+2. Treat raw file read-only.
+3. If article path missing, ask once.
+4. Use `Read` to re-read article before every `Write`.
+
+## Loop
+
+1. Draft 2–3 openings with different thesis/angle.
+2. User picks or composes hybrid.
+3. Opening defines article path.
+4. Ask what reader needs next.
+5. Pull from raw material.
+6. Argue format: prose/list/table/callout/quote/code.
+7. Use `Write` to append agreed block immediately.
+8. Repeat until article done.
+
+## Pressure tests
+
+- What does this paragraph do that previous didn't?
+- If cut, what breaks?
+- Prose/list/table/callout? Why?
+- Sentence doing two jobs? Split or pick one.
+- Opening promised X; current draft drifted to Y?
+
+## Format rules
+
+- Prose carries argument.
+- List only for parallel items.
+- Callout for derailing tips/warnings/asides.
+- Table when same fields repeat 3+ times.
+- Quote when exact wording matters.
+- Code block for multi-line/runnable/illustrative; inline code for single token.
+
+## Rules
+
+- Mine pile; do not follow as script.
+- Paraphrase/split/merge fragments.
+- If pile lacks needed example/info, ask user or cut section.
+- Preserve user edits.
+- Edit specific paragraph in place when requested.
+- DO NOT publish or add unsolicited frontmatter.

package/templates/claude-code/.claude/skills/misc/git-guardrails-claude-code/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: git-guardrails-claude-code
+description: Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.
+---
+
+# Setup Git Guardrails
+
+Block patterns: `git push`, `git reset --hard`, `git clean -f`, `git clean -fd`, `git branch -D`, `git checkout .`, `git restore .`, `push --force`, `reset --hard`.
+
+## Process
+
+1. Ask scope: Project `.claude/settings.json` or Global `~/.claude/settings.json`.
+2. Copy `scripts/block-dangerous-git.sh` to `.claude/hooks/block-dangerous-git.sh` in selected scope.
+3. Use `Bash` to run `chmod +x {script}`.
+4. Merge hook into settings; DO NOT overwrite existing settings.
+
+Project settings:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Global settings:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/block-dangerous-git.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+5. Ask pattern customisation.
+6. Verify:
+
+```bash
+echo '{"tool_input":{"command":"git push origin main"}}' | {path-to-script}
+```
+
+Expected: exit 2 + `BLOCKED` stderr.

package/templates/claude-code/.claude/skills/misc/git-guardrails-claude-code/scripts/block-dangerous-git.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
+
+DANGEROUS_PATTERNS=(
+  "git push"
+  "git reset --hard"
+  "git clean -fd"
+  "git clean -f"
+  "git branch -D"
+  "git checkout \."
+  "git restore \."
+  "push --force"
+  "reset --hard"
+)
+
+for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qE "$pattern"; then
+    echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2
+    exit 2
+  fi
+done
+
+exit 0

package/templates/claude-code/.claude/skills/misc/migrate-to-shoehorn/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: migrate-to-shoehorn
+description: Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
+---
+
+# Migrate to Shoehorn
+
+RULE: Test code only. Never production.
+
+## Install
+
+Use `Bash` to run:
+
+```bash
+npm i @total-typescript/shoehorn
+```
+
+## Mapping
+
+- `as Type` → `fromPartial()`.
+- `as unknown as Type` → `fromAny()`.
+- `fromPartial()` = partial data that should type-check.
+- `fromAny()` = intentionally wrong data.
+- `fromExact()` = full object now, partial later.
+
+## Workflow
+
+1. Ask target test files/use cases if missing.
+2. Use `Bash` to install dependency.
+3. Use `Grep` to find assertions:
+
+```bash
+grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"
+```
+
+4. Use `Edit` to replace `as Type` with `fromPartial()`.
+5. Use `Edit` to replace `as unknown as Type` with `fromAny()`.
+6. Use `Edit` to add imports.
+7. Use `Bash` to run type check.