@fernado03/zoo-flow 0.11.0 → 0.11.2

package/README.md

@@ -130,9 +130,36 @@ For team usage, see `docs/team-mode.md`.
 npx @fernado03/zoo-flow@latest update
 ```
 
-Backs up your current `.roomodes` and `.roo/` to
-`.zoo-flow-backup/<timestamp>/`, then replaces them with the latest
-template. Preview with `--dry-run`.
+Backs up your current Zoo Flow files to `.zoo-flow-backup/<timestamp>/`, then replaces them with the latest template. Preview with `--dry-run`.
+
+- **Zoo Code**: Backs up `.roomodes` and `.roo/`
+- **Claude Code**: Backs up `CLAUDE.md` and `.claude/`
+
+## Scratch working memory
+
+Certain skills (like `/review`, `/diagnose`, and `/zoom-out`) use a scratch working memory pattern for deeper analysis. These skills:
+
+- Create structured `.scratch/` subdirectories with date and context
+- Write intermediate findings to separate files during multi-pass analysis
+- Read back previous passes before synthesizing final insights
+
+**Example structure:**
+```
+.scratch/
+  reviews/
+    2026-06-14_auth-refactor/
+      01_security.md      # Security analysis pass
+      02_architecture.md  # Architecture review pass
+      03_synthesis.md     # Final insights from both passes
+```
+
+This enables:
+- **Cross-angle insights**: Later passes reference earlier findings, catching issues that span multiple perspectives
+- **Persistent reasoning**: Findings aren't lost in context window limits
+- **Audit trail**: You can review the reasoning process, not just final conclusions
+- **Ultracode-level depth**: Achieves thorough analysis within Zoo Flow's single-agent architecture
+
+See `templates/full/.roo/rules/07-scratch-working-memory.md` for the protocol details.
 
 ## Token discipline
 
@@ -213,6 +240,8 @@ For command-addition rules, see [`docs/command-design.md`](docs/command-design.m
 
 If you would rather copy the template by hand:
 
+### Zoo Code
+
 ```sh
 git clone https://github.com/Fernado03/zoo-flow.git /tmp/zoo-flow
 cp /tmp/zoo-flow/templates/full/.roomodes .
@@ -227,14 +256,40 @@ grep -qxF "# Zoo Flow — generated config (never committed)" .gitignore 2>/dev/
 
 Windows uses `git clone ... C:\Temp\zoo-flow` and `Copy-Item` (including `Copy-Item -Recurse` for `.roo\` and `.zoo-flow\`) instead. Add `.roomodes`, `.roo/`, and `.zoo-flow/` to `.gitignore`.
 
+### Claude Code
+
+```sh
+git clone https://github.com/Fernado03/zoo-flow.git /tmp/zoo-flow
+cp /tmp/zoo-flow/templates/claude-code/CLAUDE.md .
+cp -R /tmp/zoo-flow/templates/claude-code/.claude .
+cp -R /tmp/zoo-flow/templates/claude-code/.zoo-flow .
+touch .gitignore
+grep -qxF "# Zoo Flow — generated config (never committed)" .gitignore 2>/dev/null || {
+  printf "\n# Zoo Flow — generated config (never committed)\n" >> .gitignore
+  printf ".claude/\n.zoo-flow/\n" >> .gitignore
+}
+```
+
+Windows uses the same approach with `Copy-Item` for `.claude\` and `.zoo-flow\`. Add `.claude/` and `.zoo-flow/` to `.gitignore`.
+
 ## Development
 
-Before publishing, run:
+Before publishing, run validation scripts from the package root:
 
 ```bash
-npm run release:check
+# Run all validation checks
+npm run check
+
+# Run individual validations
+npm run token-budget
+npm run package-manifest
+npm run golden-transcripts
+npm run project-shapes
+npm run score-quality
 ```
 
+Note: These validate the template source, not an installed project. To validate an installation, run `npx @fernado03/zoo-flow@latest doctor` inside the target project.
+
 ## Migration
 
 Zoo Flow started as a Roo Flow template and was renamed for Zoo Code.

package/bin/zoo-flow.js

@@ -61,8 +61,8 @@ const CLAUDE_CODE_GITIGNORE_MARKER = "# Zoo Flow — Claude Code config (never c
 const CLAUDE_CODE_GITIGNORE_ENTRIES = [".claude/", ".zoo-flow/"];
 
 function detectPlatform(projectRoot) {
-  if (pathExists(path.join(projectRoot, "CLAUDE.md"))) return "claude-code";
-  if (pathExists(path.join(projectRoot, ".roomodes"))) return "zoo-code";
+  if (pathExists(path.join(projectRoot, "CLAUDE.md")) || pathExists(path.join(projectRoot, ".claude"))) return "claude-code";
+  if (pathExists(path.join(projectRoot, ".roomodes")) || pathExists(path.join(projectRoot, ".roo"))) return "zoo-code";
   return null;
 }
 
@@ -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.0",
-  "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.2",
+  "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/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.

package/templates/claude-code/.claude/skills/misc/scaffold-exercises/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: scaffold-exercises
+description: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
+---
+
+# Scaffold Exercises
+
+Goal: create exercise dirs passing `pnpm ai-hero-cli internal lint`, then commit.
+
+## Naming
+
+- Sections: `exercises/XX-section-name/`.
+- Exercises: `XX.YY-exercise-name/` inside section.
+- Lowercase dash-case.
+
+## Variants
+
+Each exercise needs ≥1: `problem/`, `solution/`, `explainer/`. Default stub: `explainer/` unless plan says otherwise.
+
+## Required files
+
+- Each variant folder: non-empty `readme.md`.
+- Minimal readme:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+- If folder has code, `main.ts` >1 line required.
+- Readme-only stubs allowed.
+
+## Workflow
+
+1. Parse plan into sections/exercises/variants.
+2. Use `Bash` to `mkdir -p` dirs.
+3. Use `Write` to create readme stubs.
+4. Use `Bash` to run `pnpm ai-hero-cli internal lint`.
+5. Fix until pass.
+6. Use `Bash` to move/rename with `git mv`.
+7. Use `Bash` to commit with `git commit`.
+
+## Lint constraints
+
+- Exercise has subfolder.
+- At least one of `problem/`, `explainer/`, `explainer.1/` exists.
+- Primary readme exists and non-empty.
+- No `.gitkeep`.
+- No `speaker-notes.md`.
+- No broken links.
+- No `pnpm run exercise` in readmes.
+- `main.ts` required only when code present.

package/templates/claude-code/.claude/skills/misc/setup-pre-commit/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: setup-pre-commit
+description: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
+---
+
+# Setup Pre-Commit Hooks
+
+Creates Husky pre-commit, lint-staged Prettier, optional typecheck/test.
+
+## Process
+
+1. Detect package manager: `package-lock.json`→npm; `pnpm-lock.yaml`→pnpm; `yarn.lock`→yarn; `bun.lockb`→bun; default npm.
+2. Use `Bash` to install dev deps, adapting package manager:
+
+```bash
+npm i -D husky lint-staged prettier
+```
+
+3. Use `Bash` to init Husky:
+
+```bash
+npx husky init
+```
+
+4. Use `Write` to write `.husky/pre-commit`, adapting package manager; omit missing scripts and tell user:
+
+```text
+npx lint-staged
+npm run typecheck
+npm run test
+```
+
+5. Use `Write` to create `.lintstagedrc`:
+
+```json
+{
+  "*": "prettier --ignore-unknown --write"
+}
+```
+
+6. Use `Write` to create `.prettierrc` only if no Prettier config:
+
+```json
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "printWidth": 80,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "semi": true,
+  "arrowParens": "always"
+}
+```
+
+7. Verify: executable `.husky/pre-commit`; `.lintstagedrc`; `prepare` script = `husky`; Prettier config; use `Bash` to run `npx lint-staged`.
+8. Use `Bash` to commit:
+
+```bash
+git commit -m "Add pre-commit hooks (husky + lint-staged + prettier)"
+```
+
+RULE: Wait for explicit user approval before commit if current mode requires HITL.

package/templates/claude-code/.claude/skills/personal/edit-article/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: edit-article
+description: Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
+---
+
+# Edit Article
+
+1. Use `Read` to divide article by headings.
+2. Identify main point per section.
+3. Reorder sections/content so dependencies flow first.
+4. Confirm section plan with user.
+5. Use `Edit` to rewrite each section for clarity/coherence/flow.
+6. Max 240 chars per paragraph.

package/templates/claude-code/.claude/skills/personal/obsidian-vault/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: obsidian-vault
+description: Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.
+---
+
+# Obsidian Vault
+
+## Vault path
+
+1. Use `$OBSIDIAN_VAULT_PATH`.
+2. If unset, STOP and ask absolute vault path.
+
+## Naming
+
+- Index notes aggregate related topics: `Ralph Wiggum Index.md`.
+- Title Case filenames.
+- No folders for org; use wikilinks/index notes.
+
+## Linking
+
+- Use `[[wikilinks]]`.
+- Add related/dependency links at bottom.
+- Index notes = wikilink lists.
+
+## Commands
+
+```bash
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*.md" | grep -i "keyword"
+grep -rl "keyword" "/mnt/d/Obsidian Vault/AI Research/" --include="*.md"
+grep -rl "\\[\\[Note Title\\]\\]" "/mnt/d/Obsidian Vault/AI Research/"
+find "/mnt/d/Obsidian Vault/AI Research/" -name "*Index*"
+```
+
+## Create note
+
+1. Title Case filename.
+2. Use `Write` to write one learning unit.
+3. Add related wikilinks at bottom.
+4. If numbered sequence, use hierarchy.