@fernado03/zoo-flow 0.11.3 → 0.12.1

package/docs/comparison.md

@@ -0,0 +1,86 @@
+# Comparison and positioning
+
+A few projects in the agentic-coding space share vocabulary with Zoo
+Flow — "skills", "agents", "commands". They are doing different things.
+This page is meant to make the differences clear so you can pick the
+right tool for the job.
+
+## Short version
+
+- **Superpowers** is a broad methodology and skills library. The center
+  of gravity is the *skills*: a large, well-curated collection of named
+  techniques the agent can pull in.
+- **ECC (Extended Coding Companion / "extended coding context")** is a
+  large agent harness. The center of gravity is the *runtime*: a rich
+  agent loop, memory, and tooling stack.
+- **Zoo Flow** is a Zoo Code-native workflow control plane. It focuses
+  on mode-safe delegation, slash-command routing, and path-safe skill
+  loading. The center of gravity is the
+  *contract*: three modes, a routing matrix, a command protocol, and a
+  path-safety guarantee.
+
+These projects are complementary more than competitive. You can run a
+broad skills library inside Zoo Flow's three-mode contract, and you can
+plug Zoo Flow's commands into a richer harness if you have one.
+
+## What Zoo Flow is not
+
+- It is not a replacement for a methodology like Superpowers. If you
+  want a long, opinionated guide to *how to think* about agentic
+  coding, look there.
+- It is not a runtime. Zoo Flow runs inside Zoo Code; it does not ship
+  its own agent loop, memory store, or tool registry.
+- It is not a giant skills pack. The bundled skills are a starting
+  point. The control plane is the product.
+
+## What Zoo Flow is
+
+- A `.roomodes` file that defines three custom modes with deliberate
+  tool-group boundaries.
+- A handful of always-on rules: path safety, command protocol,
+  three-failure guardrail, manual reply safety, and context economy.
+- A directory layout for slash commands and on-demand skills.
+
+If you only adopt one piece of Zoo Flow, adopt the path-safety rule and
+the command protocol. Those two files alone fix most of the "agent
+hallucinated a path" problems.
+
+## When to pick Zoo Flow
+
+- You are using Zoo Code as your primary host.
+- You want a small, validated control plane more than a big skill set.
+- You care about the mode boundary between planning and implementation.
+- You want explicit human-in-the-loop checkpoints in multi-phase flows
+  like `/fix` and `/feature`.
+
+## When to pick something else
+
+- You want a comprehensive methodology and a broad skill set out of the
+  box. Superpowers and similar projects are a better fit.
+- You are not on Zoo Code and you do not plan to be. Zoo Flow leans on
+  `customModes`, `run_slash_command`, `new_task`, and `switch_mode`
+  semantics from that host.
+- You want a full agent runtime with its own loop and memory layer.
+  ECC-style harnesses are aimed at that.
+
+## Working alongside other projects
+
+Zoo Flow plays well with broader skills libraries. The skills under
+`templates/full/.roo/skills/` follow a standard `SKILL.md` format and
+are loaded by command. If you want to bring in a skill from another
+project, drop it under the right bucket, add a one-line entry to the
+bucket `README.md` and to `docs/skills-index.md`, and reference it from
+a command file. The control plane does not care where the skill came
+from.
+
+The opposite direction works too: if you want to take just the modes
+and the command protocol into a different setup, that is two files
+(`.roomodes` and `01-command-protocol.md`) plus the path-safety rule
+(`00-paths.md`).
+
+## Respect
+
+The projects mentioned here are the work of people who care about this
+problem space. Zoo Flow exists because their work raised the bar.
+Where Zoo Flow disagrees with them, it disagrees on tradeoffs, not on
+intent.

package/docs/context-packs.md

@@ -0,0 +1,35 @@
+# Context Packs
+
+Context packs are optional reusable groups of documentation, rules,
+commands, and skills that can be layered on top of Zoo Flow for
+specific project needs.
+
+## When to use
+
+- A project needs specialized workflow patterns (e.g., writing
+  workflows, database migrations, CI/CD).
+- A team wants to share a common set of conventions across repos.
+- A user wants optional extras without modifying core Zoo Flow files.
+
+## How it works
+
+Context packs live under `.roo/templates/context-packs/`. Each pack is a
+directory with its own `manifest.json` declaring what it adds.
+
+The `/scaffold-context` command detects candidate packs based on project
+shape and offers them as optional additions.
+
+## Built-in candidate packs
+
+These are templates evaluated by `/scaffold-context` but never applied
+without user confirmation:
+
+- **Writing patterns** — shapes, beats, fragments for content projects
+- **ADR starter** — minimal ADR template and convention
+- **Setup docs** — setup conventions beyond the boiletplate
+
+## Quality gate
+
+Context packs must follow the same quality rules as core Zoo Flow:
+canonical `Skill:` markers, correct mode declarations, no built-in
+delegation. They are validated by `doctor`.

package/docs/dogfood/01-small-library.md

@@ -0,0 +1,28 @@
+# Dogfood Report: Small Library
+
+**Date:** YYYY-MM-DD
+**Project shape:** library (npm package, ~2K LOC, 10 exports)
+**Zoo Flow version:** 0.7.0
+
+## Commands tested
+
+- `/scaffold-context` — should detect library shape, propose 5-8 domain terms, 0-1 ADRs
+- `/verify` — should detect package.json, run npm test
+- `/commit-and-document` — should stage, commit, write journal entry
+
+## What Zoo Flow routed correctly
+
+
+## What it over-read
+
+
+## What it tried to create unnecessarily
+
+
+## Token budget impact
+
+
+## Fixes made to Zoo Flow
+
+
+## Remaining risk

package/docs/dogfood/02-web-app.md

@@ -0,0 +1,29 @@
+# Dogfood Report: Web App
+
+**Date:** YYYY-MM-DD
+**Project shape:** web app (Next.js, auth, payments, ~20K LOC)
+**Zoo Flow version:** 0.7.0
+
+## Commands tested
+
+- `/feature` — new payment flow with phase gates
+- `/fix` — checkout crash diagnosis
+- `/review` — branch review with Security/Risk axis
+- `/verify` — targeted test run
+
+## What Zoo Flow routed correctly
+
+
+## What it over-read
+
+
+## What it tried to create unnecessarily
+
+
+## Token budget impact
+
+
+## Fixes made to Zoo Flow
+
+
+## Remaining risk

package/docs/dogfood/03-mixed-monorepo.md

@@ -0,0 +1,29 @@
+# Dogfood Report: Mixed Monorepo
+
+**Date:** YYYY-MM-DD
+**Project shape:** monorepo (apps/web, services/api, workers/billing, packages/core)
+**Zoo Flow version:** 0.7.0
+
+## Commands tested
+
+- `/scaffold-context` — should detect monorepo shape, propose MONOREPO_MAP.md as recommended
+- `/explore` — should map unfamiliar sub-package
+- `/refactor` — should plan cross-package design change
+- `/tweak` — should handle localized change in one package
+
+## What Zoo Flow routed correctly
+
+
+## What it over-read
+
+
+## What it tried to create unnecessarily
+
+
+## Token budget impact
+
+
+## Fixes made to Zoo Flow
+
+
+## Remaining risk

package/docs/mode-rules.md

@@ -0,0 +1,86 @@
+# Mode-specific rules
+
+Zoo Flow uses three rule scopes, each loaded by Zoo Code automatically:
+
+- `.roo/rules/` — loaded for **every** mode, every turn.
+- `.roo/rules-{modeSlug}/` — loaded **only** when that mode is active.
+- `.roo/skills/` — **on-demand**, loaded by slash commands. Never auto-loaded.
+
+> Zoo Flow uses the preferred `.roo/rules-{modeSlug}/` directory form
+> only. Legacy single-file fallbacks such as `.roorules-{modeSlug}` and
+> `.clinerules-{modeSlug}` are not used by this template.
+
+Mode-specific behavior lives in dedicated folders under `.roo/`:
+
+- `.roo/rules-custom-orchestrator/` — routing rules and the delegation
+  message contract for the orchestrator.
+- `.roo/rules-system-architect/` — scope, feature-prototype handoff, and
+  completion rules for the architect.
+- `.roo/rules-code-tweaker/` — scope and completion rules for the
+  tweaker, including the git hard stop.
+
+Files inside these folders are short on purpose. They are concatenated
+into the model's context every turn the matching mode is active, so each
+extra paragraph costs tokens for the entire session.
+
+## What belongs in a mode rules folder
+
+- Standing instructions specific to that mode's job (e.g. "the architect
+  cannot edit application source").
+- Short hard stops (e.g. "halt for explicit user approval before
+  publishing issues").
+- Pointers to global rules the mode must follow.
+
+## What does NOT belong here
+
+- **On-demand skills.** Those live under `.roo/skills/` and are loaded
+  explicitly by slash commands.
+- **Workspace-wide always-on rules** that apply to every mode. Those
+  stay in `.roo/rules/`.
+- **Long policy or knowledge files.** If a policy is long enough to need
+  multiple paragraphs of explanation, write it under `docs/` and
+  reference it from the rule. The mode rule should be a short reminder,
+  not a full essay.
+- **Duplicates of the global command protocol or path safety.** Those
+  live in `.roo/rules/01-command-protocol.md` and
+  `.roo/rules/00-paths.md` respectively.
+
+## Why `.roomodes` is intentionally minimal
+
+Each `customInstructions` block in `.roomodes` is loaded with the mode
+metadata. Putting detailed behavior there duplicates what already lives
+in `.roo/rules-{modeSlug}/`, costs tokens twice, and creates two places
+to keep in sync.
+
+The current `.roomodes` keeps four things per mode:
+
+1. `slug`, `name`, `roleDefinition`, `whenToUse`, `description`,
+   `groups` — these can't move.
+2. A short `customInstructions` that:
+   - points at the matching `.roo/rules-{modeSlug}/` folder,
+    - lists permitted routed commands and permitted direct helper commands
+      (or the routing matrix, for the orchestrator),
+   - references the global rules it calls out directly (`00-paths.md`,
+     `01-command-protocol.md`, `03-manual-reply-protocol.md`). Other
+     global rules, such as `02-three-failure-rule.md` and
+     `04-context-economy.md`, are loaded automatically from
+     `.roo/rules/`.
+    - says what to do if an unsupported command is assigned.
+
+Documented helper commands must have `mode:` frontmatter unless they are
+explicitly modeless utilities such as `/caveman`.
+
+Everything else lives in the mode rules folder.
+
+## Related directories
+
+- [`.roo/rules/`](../templates/full/.roo/rules/) — always-on rules for **all** modes.
+- [`.roo/skills/`](../templates/full/.roo/skills/) — on-demand skills, invoked by slash commands.
+- [`.roo/commands/`](../templates/full/.roo/commands/) — slash command definitions
+  (e.g. `/tweak`, `/fix`).
+- [`.roo/rules-custom-orchestrator/`](../templates/full/.roo/rules-custom-orchestrator/) —
+  router-only rules.
+- [`.roo/rules-system-architect/`](../templates/full/.roo/rules-system-architect/) —
+  architect rules.
+- [`.roo/rules-code-tweaker/`](../templates/full/.roo/rules-code-tweaker/) —
+  tweaker rules.

package/docs/npm-publishing.md

@@ -0,0 +1,79 @@
+# npm Publishing
+
+Zoo Flow is published as a CLI installer.
+
+## Package name
+
+```text
+@fernado03/zoo-flow
+```
+
+## Local validation
+
+```bash
+npm run release:check
+```
+
+## Publish
+
+```bash
+npm login
+npm publish --access public
+```
+
+## Test install after publish
+
+From a separate test project:
+
+```bash
+npx @fernado03/zoo-flow@latest init
+```
+
+If the project already has `.roomodes` or `.roo/`, test:
+
+```bash
+npx @fernado03/zoo-flow@latest init --force
+```
+
+## Test update after publish
+
+From a temporary directory:
+
+```bash
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+
+npx @fernado03/zoo-flow@latest init
+npx @fernado03/zoo-flow@latest update --dry-run
+npx @fernado03/zoo-flow@latest update
+
+test -f .roomodes
+test -d .roo
+test -d .zoo-flow-backup
+```
+
+## What ships in the package
+
+The `files` field in `package.json` controls what npm publishes:
+
+- `bin/` — the CLI entry point
+- `scripts/` — validation and release checks
+- `templates/` — the runtime template (`.roomodes` and `.roo/`)
+- `docs/` — product documentation linked from the README
+- `examples/` — worked examples linked from the README
+- `README.md`
+- `LICENSE`
+
+`node_modules/`, `.git/`, `.scratch/`, backups, and generated tarballs are not shipped.
+
+## Versioning
+
+Bump `version` in `package.json` before each publish, following
+[Semantic Versioning](https://semver.org/):
+
+- patch: bug fixes in the CLI or template content
+- minor: new commands, new modes, new skills
+- major: breaking changes to mode slugs, command names, or routing
+
+Update `CHANGELOG.md` under `## [Unreleased]` with the change, then
+move it under a new versioned section when you publish.

package/docs/out-of-scope/mainstream-issue-trackers-only.md

@@ -0,0 +1,25 @@
+# Issue tracker integrations are limited to mainstream tools
+
+`setup-matt-pocock-skills` only offers first-class support for **mainstream** issue trackers. Requests to add support for niche, new, or single-vendor experimental trackers are out of scope.
+
+## Why this is out of scope
+
+Every issue-tracker backend hard-codes a CLI shape into the skills (commands, flags, output parsing). Each new backend is permanent maintenance surface — it has to keep working as the tool's CLI evolves, and it has to keep being tested against `/to-prd`, `/to-issues`, `/triage`, and friends. That cost is only worth paying for trackers a meaningful fraction of users actually have.
+
+"Mainstream" is a judgment call, not a numeric bar:
+
+- GitHub, GitLab, and Backlog.md are the kind of tools we'd consider mainstream — broadly known, widely used, well past the experimental phase.
+- A brand-new agent-focused tool with a few hundred GitHub stars is not, no matter how interesting the design.
+
+Stars, age, and download counts are useful signals when making the call but none of them is the rule. The rule is: would a typical engineer recognise this tool and have plausibly chosen it for their team?
+
+The escape hatches for non-mainstream trackers already exist:
+
+- `local markdown` for lightweight in-repo tracking.
+- `other/custom` for users who want to wire something up themselves.
+
+Neither requires the core skills to know about the specific tool.
+
+## Prior requests
+
+- #99 — "Add dex as an issue tracker backend" (dex was ~3 months old and ~300 stars at the time of the request)

package/docs/out-of-scope/question-limits.md

@@ -0,0 +1,18 @@
+# Hard limits on the number of questions during grilling
+
+The `/grill-me` skill (and grilling sessions inside other skills) does not enforce a maximum number of questions. Requests to add a configurable cap or hard ceiling are out of scope.
+
+## Why this is out of scope
+
+Grilling is intentionally open-ended. The point is to keep digging until each branch of the decision tree is resolved — some plans need three questions, some need fifty. A fixed cap would either cut off useful exploration on hard problems or feel arbitrary on easy ones.
+
+If a session feels too long, the right escape hatches already exist:
+
+- The user can stop the session at any time and accept the current state of the plan.
+- The user can tell the model to wrap up, summarise, and move on — natural-language steering is the intended control surface, not a numeric limit.
+
+Adding a hard cap would also conflate two different failure modes: a model that asks too many questions because the plan is genuinely under-specified (working as intended) vs. a model that asks redundant or low-value questions (a prompt-quality issue, not a quantity issue). The fix for the latter belongs in the skill prompt, not in a counter.
+
+## Prior requests
+
+- #44 — "Codex just asked me 200 questions"

package/docs/out-of-scope/setup-skill-verify-mode.md

@@ -0,0 +1,15 @@
+# Verify/Check Mode for `setup-matt-pocock-skills`
+
+This project will not add a dedicated verify/check mode (or a separate verify skill) for `setup-matt-pocock-skills`.
+
+## Why this is out of scope
+
+A second skill — or a `--verify` flag — for checking whether `docs/agents/*.md` artifacts still match the seed-template schema would duplicate work the existing setup skill already handles in conversation.
+
+The intended workflow is: **run `/setup-matt-pocock-skills` and tell it to verify your current setup.** The skill is prompt-driven, so the maintainer can scope it to a verification pass ("don't rewrite anything, just check my existing files against the current seed templates and report drift") without needing a separate code path. Adding a flag or a sibling skill would split the surface area of a feature that's already expressible through the natural-language entry point.
+
+Keeping configuration management to a single skill also avoids the maintenance cost of two skills drifting from each other when seed templates evolve.
+
+## Prior requests
+
+- #106 — Feature request: verify/check mode for setup-matt-pocock-skills

package/docs/overview.md

@@ -0,0 +1,61 @@
+# Overview
+
+Zoo Flow is a small, opinionated template that turns
+[Zoo Code](https://docs.zoocode.dev/) into a predictable mode +
+command + skill orchestrator. It defines three modes, a fixed routing
+matrix, a command protocol, and path-safety rules. Drop it into a
+workspace and your AI assistant stops freelancing.
+
+## Why this exists
+
+Out of the box, AI coding assistants tend to skip planning when you
+want planning, plan when you want a tweak, and quietly invent file
+paths that do not exist. Adding a pile of skills makes it worse.
+
+Zoo Flow takes a different bet:
+
+- A **router mode** chooses the workflow.
+- An **architect mode** plans, diagnoses, and triages — and cannot
+  edit source code.
+- A **tweaker mode** implements, runs tests, prototypes, and commits —
+  only when explicitly approved.
+- A small set of **slash commands** acts as the public API between
+  you and the modes. Free-form requests go through the orchestrator;
+  typing a slash command jumps straight to its configured mode.
+- A few **always-on rules** keep the path layout honest and stop
+  skill paths from drifting under `.roo/rules/`.
+
+Everything else is optional. The skills bundled in the template are a
+sensible starting point, not the point of the project.
+
+## Core workflow
+
+```mermaid
+flowchart TD
+    User([User])
+    Orchestrator[🪃 custom-orchestrator<br/>router only]
+    Architect[🏗️ system-architect<br/>plan / diagnose / triage<br/>Markdown edits only]
+    Tweaker[⚡ code-tweaker<br/>implement / test / prototype / commit]
+
+    User -- "free-form request" --> Orchestrator
+    Orchestrator -- "proposes /command, waits" --> User
+    User -- "/tweak, /tdd, /update-docs,<br/>/commit-and-document, /prototype, /verify" --> Orchestrator
+    User -- "/fix, /feature, /refactor,<br/>/explore, /triage, /review" --> Orchestrator
+
+    Orchestrator -- "new_task" --> Tweaker
+    Orchestrator -- "new_task" --> Architect
+
+    Architect -- "switch_mode (same window)" --> Tweaker
+    Tweaker -- "switch_mode (same window)" --> Architect
+
+    Tweaker -- "attempt_completion" --> Orchestrator
+    Architect -- "attempt_completion" --> Orchestrator
+    Orchestrator -- "summarize, HALT" --> User
+```
+
+For the deeper "why", see [`philosophy.md`](philosophy.md). For the
+component-level reference, see [`architecture.md`](architecture.md).
+
+For non-trivial work, the normal endgame is implementation, then
+`/verify`, then `/review`, then `/commit-and-document`. These are
+recommendations only; Zoo Flow does not auto-run follow-up commands.

package/docs/philosophy.md

@@ -0,0 +1,73 @@
+# Philosophy
+
+Zoo Flow is built around a small number of opinions. They are listed here so
+you can decide whether the template is a good fit before you adopt it.
+
+## 1. The router should not write code
+
+Most failure modes in agentic coding come from a single agent trying to do
+three jobs at once: deciding what to do, planning how to do it, and doing
+it. Zoo Flow splits those into three modes and refuses to collapse them.
+
+- `custom-orchestrator` decides **what** to do, by mapping a request to a
+  command from a fixed routing matrix.
+- `system-architect` decides **how** to do it, in Markdown.
+- `code-tweaker` does it.
+
+The orchestrator has no `read`, `edit`, `command`, or `mcp` tool groups.
+It cannot freelance into implementation work even if it wants to.
+
+## 2. Slash commands are the public API
+
+Free-form requests are fine, but the moment work starts, it goes through a
+slash command. Commands are the only way the orchestrator delegates and
+the only way modes know which workflow they are running.
+
+This has two payoffs:
+
+- A command name in chat is a checkable artifact. You can grep your history
+  for `/fix` or `/feature` and know exactly which workflow ran.
+- Each command file is a single, readable place to change behavior. No
+  hunting through prompts.
+
+Commands live at `templates/full/.roo/commands/{command}.md` and are loaded
+through the protocol described in
+[`architecture.md`](architecture.md#command-protocol).
+
+## 3. Path safety beats cleverness
+
+Skills always live at `templates/full/.roo/skills/{bucket}/{skill}/SKILL.md`.
+Never under `.roo/rules/`. Never relative to the command file. Never invented
+by the model.
+
+This is enforced by `00-paths.md`, which ships as an always-on rule. If a
+skill path drifts, the rule catches it. The cost is one rule file. The
+benefit is no more `ENOENT` rabbit holes.
+
+## 4. Same-window switches for tight loops, `new_task` for clean boundaries
+
+There are two delegation primitives in Zoo Code:
+
+- `switch_mode` keeps the same task window and hands the keyboard to a
+  different mode. Cheap. Good for `/fix` going architect → tweaker → architect.
+- `new_task` opens a delegated subtask with its own window. Expensive. Good
+  for orchestrator handing real work to architect or tweaker.
+
+Zoo Flow uses both, deliberately. The orchestrator only ever uses
+`new_task`. Modes only ever use `switch_mode`. They never cross.
+
+## 5. HITL hard stops are features
+
+Several commands force a halt. `/feature` halts after sharpening, after
+prototype, after PRD, after issues. `/fix` halts after diagnosis. The git
+flow halts before commit. These are not friction; they are the points
+where a human review is cheaper than a rollback.
+
+## 6. The skill set is replaceable
+
+The bundled skills are a starting point. You should expect to delete some,
+add some, and rename a bucket. The control plane — modes, commands, rules —
+is the part that should be stable.
+
+If a skill cannot be invoked through a command, it does not belong in the
+template.

package/docs/quality-scorecard.md

@@ -0,0 +1,23 @@
+# Quality Scorecard
+
+Zoo Flow uses a deterministic rule-based quality scorecard to gate releases. Every
+category must score >= 9.5/10 for `release:check` to pass.
+
+## Categories
+
+| Category | Weight | What it measures |
+|---|---|---|
+| command_integrity | 20% | Every command has a correct `mode:` declaration matching the command-policy map. Required rules exist. Routing table is in sync. |
+| skill_quality | 20% | Skills use canonical `Skill:` marker. Referenced skills exist. Skills have purpose, steps, and output format. No thin wrappers. Bucket layout. |
+| validation_depth | 20% | Doctor validates files, skill refs, mode slugs, built-in bans, .roomodes permission, routing rows, old-doc leakage, ADR path consistency. |
+| token_economy | 10% | Context-economy rule exists. Domain-doc read gate. Completion evidence format. Risk-based routing. |
+| verification | 10% | Verify command + skill with evidence output and no-claim-unless-run rule. Fixture tests. Routing evals. Package-link check. |
+| review_process | 10% | Review command + skill with standards/spec/Security-Risk axes. Severity-ordered findings. Canonical result line. |
+| release_readiness | 10% | `release:check` runs all validation scripts. Score thresholds enforced. `npm pack --dry-run` passes. |
+
+## How scoring works
+
+- Each category defines specific checks (see `quality/scorecard.json`).
+- Each check is pass/fail. Missing items reduce the category score toward 0.
+- The weighted composite score must be >= 9.5 for `npm run release:check` to pass.
+- Scoring is fully deterministic — no AI grading, no subjective evaluation.

package/docs/skill-maintenance.md

@@ -0,0 +1,32 @@
+# Skill maintenance policy
+
+This is repo-maintenance policy for the bundled skill set. It does not
+need to be in the model's context on every turn, so it lives in `docs/`
+rather than `.roo/rules/`. The runtime path-safety contract is in
+[`templates/full/.roo/rules/00-paths.md`](../templates/full/.roo/rules/00-paths.md).
+
+## Skill bucket layout
+
+Skills are organized into bucket folders under `.roo/skills/`:
+
+- `.roo/skills/engineering/` — daily code work
+- `.roo/skills/productivity/` — daily non-code workflow tools
+- `.roo/skills/misc/` — kept around but rarely used
+- `.roo/skills/personal/` — tied to a maintainer's setup, not promoted
+- `.roo/skills/in-progress/` — drafts not yet ready to ship
+- `.roo/skills/deprecated/` — no longer used
+
+## Promotion rules
+
+Skills in `.roo/skills/personal/`, `.roo/skills/in-progress/`, and
+`.roo/skills/deprecated/` must not appear in the top-level `README.md`
+as promoted skills. They may appear in internal indexes only when
+clearly marked as personal, in-progress, or deprecated.
+
+Every skill in `.roo/skills/engineering/`, `.roo/skills/productivity/`,
+or `.roo/skills/misc/` must have a reference in the top-level
+`README.md`.
+
+Each bucket folder has a `README.md` that lists every skill in the
+bucket with a one-line description, with the skill name linked to its
+`SKILL.md`.