@fernado03/zoo-flow 0.5.1 → 0.5.3

package/templates/full/.roo/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md

@@ -1,63 +1,61 @@
-# CONTEXT.md Format
-
-## Shape
-
-```md
-# {Context Name}
-
-{1-2 sentences: context purpose.}
-
-## Language
-
-**Order**:
-{1-2 sentence definition}
-_Avoid_: Purchase, transaction
-
-## Flagged ambiguities
-
-**Account** means Customer here, not User.
-```
-
-## Rules
-
-- MUST pick canonical term; aliases under `_Avoid_`.
-- MUST flag ambiguity + resolution.
-- Define term in 1–2 sentences: what it is, not behavior.
-- Include domain terms only; exclude generic programming terms.
-- Group under headings when useful.
-
-## Slots
-
-| Slot | File (if present) | Authored by | Default location |
-|---|---|---|---|
-| Domain language | `CONTEXT.md` | User via /grill-with-docs | `.zoo-flow/CONTEXT.md` |
-| Decisions | `docs/adr/<NNNN-slug>.md` | User via /grill-with-docs | `.zoo-flow/docs/adr/` |
-| Subsystem flow | `FLOW.md` | Subsystem owner | Next to the code |
-| App map | `APP_MAP.md` | User via /update-docs | `.zoo-flow/APP_MAP.md` |
-| Architecture | `ARCHITECTURE.md` | User via /update-docs | `.zoo-flow/ARCHITECTURE.md` |
-| Setup | `README.md` | Project owner | Project root |
-
-## Discovery rule (used by /explore, /update-docs, /grill-with-docs)
-
-For each slot, in this order:
-
-1. If the file exists at the documented location, read it.
-2. If the slot is empty/missing, that is **not an error**. The user has
-   not authored it yet. Do not invent content. Do not lazy-create unless
-   the calling command explicitly says so (e.g. /grill-with-docs on a
-   first resolved term).
-3. If the calling command depends on a populated slot and none exist,
-   surface once: "Slot `<name>` not yet authored. Run /grill-with-docs
-   to fill, or continue without."
-
-## Multi-context (rare)
-
-A single project can hold multiple domain contexts when subsystems do
-not share language. Use:
-
-- `.zoo-flow/CONTEXT-MAP.md` — index of contexts.
-- `.zoo-flow/contexts/<slug>/CONTEXT.md` — per-context.
-- `.zoo-flow/contexts/<slug>/docs/adr/` — per-context ADRs.
-
-`/grill-with-docs` and `/explore` consult the map first, then the
-relevant per-context file.
+# CONTEXT.md Format
+
+## Shape
+
+```md
+# {Context Name}
+
+{1-2 sentences: context purpose.}
+
+## Language
+
+**Order**:
+{1-2 sentence definition}
+_Avoid_: Purchase, transaction
+
+## Flagged ambiguities
+
+**Account** means Customer here, not User.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid`.
+- Define term in 1–2 sentences: what it is, not behavior.
+- Include domain terms only; exclude generic programming terms.
+
+## Slots
+
+| Slot | File (if present) | Authored by | Default location |
+|---|---|---|---|
+| Domain language | `CONTEXT.md` | User via /grill-with-docs | `.zoo-flow/CONTEXT.md` |
+| Decisions | `docs/adr/<NNNN-slug>.md` | User via /grill-with-docs | `.zoo-flow/docs/adr/` |
+| Subsystem flow | `FLOW.md` | Subsystem owner | Next to the code |
+| App map | `APP_MAP.md` | User via /update-docs | `.zoo-flow/APP_MAP.md` |
+| Architecture | `ARCHITECTURE.md` | User via /update-docs | `.zoo-flow/ARCHITECTURE.md` |
+| Setup | `README.md` | Project owner | Project root |
+
+## Discovery rule (used by /explore, /update-docs, /grill-with-docs)
+
+For each slot, in this order:
+
+1. If the file exists at the documented location, read it.
+2. If the slot is empty/missing, that is **not an error**. The user has
+   not authored it yet. Do not invent content. Do not lazy-create unless
+   the calling command explicitly says so (e.g. /grill-with-docs on a
+   first resolved term).
+3. If the calling command depends on a populated slot and none exist,
+   surface once: "Slot `<name>` not yet authored. Run /grill-with-docs
+   to fill, or continue without."
+
+## Multi-context (rare)
+
+A single project can hold multiple domain contexts when subsystems do
+not share language. Use:
+
+- `.zoo-flow/CONTEXT-MAP.md` — index of contexts.
+- `.zoo-flow/contexts/<slug>/CONTEXT.md` — per-context.
+- `.zoo-flow/contexts/<slug>/docs/adr/` — per-context ADRs.
+
+`/grill-with-docs` and `/explore` consult the map first, then the
+relevant per-context file.

package/templates/full/.roo/skills/engineering/prototype/SKILL.md

@@ -1,37 +1,37 @@
----
-name: prototype
-description: Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
----
-
-# Prototype
-
-RULE: Prototype answers one question. Throw away or absorb after answer.
-
-## Branch
-
-- Logic/state/data-model → `LOGIC.md`.
-- Visual/layout/UI → `UI.md`.
-- Ambiguous → ask.
-- User AFK → infer + state assumption.
-
-## Context economy
-
-Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
-
-Prefer targeted `read_file` ranges or indentation/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.
-
-## Rules
-
-1. Mark throwaway clearly.
-2. Place under `.scratch/prototypes/<slug>/` (logic/state/data-model) or near the real module/page (UI). UI prototypes need the real route, data fetching, and auth, so they stay adjacent to the page they mock up; logic prototypes have no such constraint, so they go in `.scratch/` with the other throwaway work.
-3. Follow existing routing/tooling.
-4. Provide one run command.
-5. Default no persistence; state in memory.
-6. Persistence target → scratch DB/file named `PROTOTYPE — wipe me` in the prototype folder.
-7. No polish: no tests, minimal errors, no abstractions.
-8. Surface full relevant state after each action/variant switch.
-9. Done → capture answer in commit/ADR/issue/`NOTES.md`; delete or fold into real code.
+---
+name: prototype
+description: Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
+---
+
+# Prototype
+
+RULE: Prototype answers one question. Throw away or absorb after answer.
+
+## Branch
+
+- Logic/state/data-model → `LOGIC.md`.
+- Visual/layout/UI → `UI.md`.
+- Ambiguous → ask.
+- User AFK → infer + state assumption.
+
+## Context economy
+
+Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or indentation/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.
+
+## Rules
+
+1. Mark throwaway clearly.
+2. Place under `.scratch/prototypes/<slug>/` (logic/state/data-model) or near the real module/page (UI). UI prototypes need the real route, data fetching, and auth, so they stay adjacent to the page they mock up; logic prototypes have no such constraint, so they go in `.scratch/` with the other throwaway work.
+3. Follow existing routing/tooling.
+4. Provide one run command.
+5. Default no persistence; state in memory.
+6. Persistence target → scratch DB/file named `PROTOTYPE — wipe me` in the prototype folder.
+7. No polish: no tests, minimal errors, no abstractions.
+8. Surface full relevant state after each action/variant switch.
+9. Done → capture answer in commit/ADR/issue/`NOTES.md`; delete or fold into real code.

package/templates/full/.roo/skills/engineering/scaffold-context/SKILL.md

@@ -1,152 +1,152 @@
----
-name: scaffold-context
-description: Bootstrap .zoo-flow/CONTEXT.md from an existing codebase by detecting project shape and scanning for domain terms and cross-cutting decisions. Proposes 5-12 terms + 0-2 ADRs, asks for confirm before writing. Use on projects with no CONTEXT.md, or to expand a thin one.
----
-
-# Scaffold Context
-
-## Loop
-
-1. Read existing context via slot discovery rule (see `CONTEXT-FORMAT.md`).
-2. Detect project shape (see Detection).
-3. Scan codebase for terms (see Detection).
-4. Propose 5-12 terms with one-line definitions + evidence (file:line counts).
-5. Show inline, ask: confirm / edit / cancel.
-6. On confirm, write to `.zoo-flow/CONTEXT.md` (preserve any existing entries in merge mode).
-7. If 1-2 cross-cutting decisions are visible in code, propose ADRs (see ADR gate).
-8. Show ADR draft(s) inline, ask confirm per ADR.
-9. On confirm, write to `.zoo-flow/docs/adr/NNNN-slug.md` using `ADR-FORMAT.md` numbering.
-10. Report what was written, with file paths.
-
-## Detection
-
-### Step 1: Detect project shape
-
-Inspect (in order):
-- `package.json` `keywords`, `name`, `scripts` (Node/JS)
-- `pyproject.toml` / `setup.py` / `setup.cfg` (Python)
-- `Cargo.toml` (Rust)
-- `go.mod` (Go)
-- Top-level folder names
-- `README.md` first paragraph
-
-Pick the dominant shape:
-
-| Signal folders / files | Shape | Priority sources for terms |
-|---|---|---|
-| `app/`, `pages/`, `routes/`, `controllers/`, `api/` | web app | API routes, page names, URL paths, model types |
-| `lib/`, `pkg/`, `src/` (no `app/`) | library | exported types, public API surface |
-| `cmd/`, `bin/`, `commands/`, `cli/` | CLI tool | subcommand names, flag names |
-| `workers/`, `jobs/`, `tasks/`, `etl/`, `pipelines/` | data pipeline | job/queue/event names |
-| `services/`, `lambda/`, `functions/`, `handlers/` | serverless | function names, event sources, triggers |
-| `services/` + `web/` + `workers/` | monorepo | treat each top-level as a sub-shape; ask user if unclear |
-
-If signals are mixed, prefer the shape that owns the entry point (`main.*`, `index.*`, `server.*`).
-
-### Step 2: Extract candidate terms
-
-For the chosen shape, prefer:
-- **Web app**: route paths (`/accounts/:id`), controller class names, view/component names
-- **Library**: exported type/class/interface names
-- **CLI**: subcommand names, top-level argument names
-- **Data pipeline**: job names, queue names, event types
-- **Serverless**: function names, event source names
-
-Universal signals (any shape):
-- Type/class/struct/interface definitions with noun names
-- Database table/model names (migrations, `schema.prisma`, `models/`, SQL files)
-- Top-level module/folder names that are nouns
-- README/docs that state purpose ("we manage X for Y")
-
-### Step 3: Filter
-
-Drop without showing:
-- Generic: `utils`, `helpers`, `common`, `base`, `lib`, `core`, `misc`, `types`, `models`, `helpers`, `shared`, `internal`, `errors`, `tests`
-- Single-letter or unexpanded acronym: `T`, `M`, `VM`, `DTO` (unless defined in code)
-- Already-defined terms in existing `CONTEXT.md` (merge mode)
-- Framework-required boilerplate: `App`, `Server`, `Router`, `Config`
-
-Keep candidates that:
-- Appear in 2+ distinct files OR
-- Appear in 1 file but are central (entry point, root config, README)
-- Are domain nouns (Account, Order, Tenant, Invoice) over technical nouns (Worker, Queue)
-
-### Step 4: Score and rank
-
-For each kept candidate, count:
-- Type/def files where it appears
-- Route/file references
-- DB schema references
-
-Take the top 5-12. Show the count in the proposal so the user can judge.
-
-## ADR gate
-
-Propose an ADR only if ALL:
-- You can point at code: a single pattern/import/module used across N+ files
-- The pattern is not obvious from the framework (e.g. "uses Express" is obvious, "all errors go through `Result<T, AppError>`" is not)
-- A reasonable engineer would be surprised to learn it from scratch
-- It maps to `ADR-FORMAT.md` "Qualifies" criteria (hard to reverse, real trade-off)
-
-Do NOT propose ADRs for:
-- Framework defaults
-- Single-file patterns
-- Speculative "this might be a decision" guesses
-- Anything where the README doesn't hint at reasoning
-
-Cap at 0-2 ADRs per scaffold. Zero is fine. Better to ship no ADR than a wrong one.
-
-## MUST
-
-- Ask confirm before writing `CONTEXT.md` (show full proposed list + diff against existing)
-- Ask confirm per ADR before writing
-- Never overwrite non-empty `CONTEXT.md` without explicit "replace"
-- Never invent cross-cutting decisions; only propose ADRs you can point at code
-- Keep `CONTEXT.md` glossary-only; no impl/spec notes
-- Use `ADR-FORMAT.md` for any proposed ADR (template + numbering)
-- Report file paths and section headers at the end
-- In merge mode, append new terms below existing ones; do not reorder
-
-## Context economy
-
-Before broad reads, locate candidates with `list_files`, `search_files`, or `codebase_search`.
-
-Prefer targeted `read_file` ranges or block reads once the candidate 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.
-
-## Output shape (for the inline confirm step)
-
-```
-## Proposed CONTEXT.md entries (N)
-
-1. **Account** — a tenant-scoped record of a customer relationship.
-   Evidence: 12 type defs, 4 routes, 1 DB table.
-2. **Order** — a request to purchase one or more SKUs.
-   Evidence: 8 type defs, 3 routes, 1 DB table.
-...
-
-Confirm? (yes / edit / cancel)
-```
-
-```
-## Proposed ADR (1 of N)
-
-# Use Result type for all fallible operations
-
-We use a Rust-style `Result<T, AppError>` for all operations that can
-fail, instead of throwing exceptions. This is enforced by a linter
-rule and visible in every service module.
-
-Considered Options:
-- Exceptions
-- Error codes (Go-style)
-- Result type (chosen)
-
-Consequences: easier to reason about error paths; verbose for happy
-paths.
-
-Confirm? (yes / edit / cancel)
-```
+---
+name: scaffold-context
+description: Bootstrap .zoo-flow/CONTEXT.md from an existing codebase by detecting project shape and scanning for domain terms and cross-cutting decisions. Proposes 5-12 terms + 0-2 ADRs, asks for confirm before writing. Use on projects with no CONTEXT.md, or to expand a thin one.
+---
+
+# Scaffold Context
+
+## Loop
+
+1. Read existing context via slot discovery rule (see `CONTEXT-FORMAT.md`).
+2. Detect project shape (see Detection).
+3. Scan codebase for terms (see Detection).
+4. Propose 5-12 terms with one-line definitions + evidence (file:line counts).
+5. Show inline, ask: confirm / edit / cancel.
+6. On confirm, write to `.zoo-flow/CONTEXT.md` (preserve any existing entries in merge mode).
+7. If 1-2 cross-cutting decisions are visible in code, propose ADRs (see ADR gate).
+8. Show ADR draft(s) inline, ask confirm per ADR.
+9. On confirm, write to `.zoo-flow/docs/adr/NNNN-slug.md` using `ADR-FORMAT.md` numbering.
+10. Report what was written, with file paths.
+
+## Detection
+
+### Step 1: Detect project shape
+
+Inspect (in order):
+- `package.json` `keywords`, `name`, `scripts` (Node/JS)
+- `pyproject.toml` / `setup.py` / `setup.cfg` (Python)
+- `Cargo.toml` (Rust)
+- `go.mod` (Go)
+- Top-level folder names
+- `README.md` first paragraph
+
+Pick the dominant shape:
+
+| Signal folders / files | Shape | Priority sources for terms |
+|---|---|---|
+| `app/`, `pages/`, `routes/`, `controllers/`, `api/` | web app | API routes, page names, URL paths, model types |
+| `lib/`, `pkg/`, `src/` (no `app/`) | library | exported types, public API surface |
+| `cmd/`, `bin/`, `commands/`, `cli/` | CLI tool | subcommand names, flag names |
+| `workers/`, `jobs/`, `tasks/`, `etl/`, `pipelines/` | data pipeline | job/queue/event names |
+| `services/`, `lambda/`, `functions/`, `handlers/` | serverless | function names, event sources, triggers |
+| `services/` + `web/` + `workers/` | monorepo | treat each top-level as a sub-shape; ask user if unclear |
+
+If signals are mixed, prefer the shape that owns the entry point (`main.*`, `index.*`, `server.*`).
+
+### Step 2: Extract candidate terms
+
+For the chosen shape, prefer:
+- **Web app**: route paths (`/accounts/:id`), controller class names, view/component names
+- **Library**: exported type/class/interface names
+- **CLI**: subcommand names, top-level argument names
+- **Data pipeline**: job names, queue names, event types
+- **Serverless**: function names, event source names
+
+Universal signals (any shape):
+- Type/class/struct/interface definitions with noun names
+- Database table/model names (migrations, `schema.prisma`, `models/`, SQL files)
+- Top-level module/folder names that are nouns
+- README/docs that state purpose ("we manage X for Y")
+
+### Step 3: Filter
+
+Drop without showing:
+- Generic: `utils`, `helpers`, `common`, `base`, `lib`, `core`, `misc`, `types`, `models`, `helpers`, `shared`, `internal`, `errors`, `tests`
+- Single-letter or unexpanded acronym: `T`, `M`, `VM`, `DTO` (unless defined in code)
+- Already-defined terms in existing `CONTEXT.md` (merge mode)
+- Framework-required boilerplate: `App`, `Server`, `Router`, `Config`
+
+Keep candidates that:
+- Appear in 2+ distinct files OR
+- Appear in 1 file but are central (entry point, root config, README)
+- Are domain nouns (Account, Order, Tenant, Invoice) over technical nouns (Worker, Queue)
+
+### Step 4: Score and rank
+
+For each kept candidate, count:
+- Type/def files where it appears
+- Route/file references
+- DB schema references
+
+Take the top 5-12. Show the count in the proposal so the user can judge.
+
+## ADR gate
+
+Propose an ADR only if ALL:
+- You can point at code: a single pattern/import/module used across N+ files
+- The pattern is not obvious from the framework (e.g. "uses Express" is obvious, "all errors go through `Result<T, AppError>`" is not)
+- A reasonable engineer would be surprised to learn it from scratch
+- It maps to `ADR-FORMAT.md` "Qualifies" criteria (hard to reverse, real trade-off)
+
+Do NOT propose ADRs for:
+- Framework defaults
+- Single-file patterns
+- Speculative "this might be a decision" guesses
+- Anything where the README doesn't hint at reasoning
+
+Cap at 0-2 ADRs per scaffold. Zero is fine. Better to ship no ADR than a wrong one.
+
+## MUST
+
+- Ask confirm before writing `CONTEXT.md` (show full proposed list + diff against existing)
+- Ask confirm per ADR before writing
+- Never overwrite non-empty `CONTEXT.md` without explicit "replace"
+- Never invent cross-cutting decisions; only propose ADRs you can point at code
+- Keep `CONTEXT.md` glossary-only; no impl/spec notes
+- Use `ADR-FORMAT.md` for any proposed ADR (template + numbering)
+- Report file paths and section headers at the end
+- In merge mode, append new terms below existing ones; do not reorder
+
+## Context economy
+
+Before broad reads, locate candidates with `list_files`, `search_files`, or `codebase_search`.
+
+Prefer targeted `read_file` ranges or block reads once the candidate 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.
+
+## Output shape (for the inline confirm step)
+
+```
+## Proposed CONTEXT.md entries (N)
+
+1. **Account** — a tenant-scoped record of a customer relationship.
+   Evidence: 12 type defs, 4 routes, 1 DB table.
+2. **Order** — a request to purchase one or more SKUs.
+   Evidence: 8 type defs, 3 routes, 1 DB table.
+...
+
+Confirm? (yes / edit / cancel)
+```
+
+```
+## Proposed ADR (1 of N)
+
+# Use Result type for all fallible operations
+
+We use a Rust-style `Result<T, AppError>` for all operations that can
+fail, instead of throwing exceptions. This is enforced by a linter
+rule and visible in every service module.
+
+Considered Options:
+- Exceptions
+- Error codes (Go-style)
+- Result type (chosen)
+
+Consequences: easier to reason about error paths; verbose for happy
+paths.
+
+Confirm? (yes / edit / cancel)
+```

package/templates/full/.roo/skills/engineering/to-prd/SKILL.md

@@ -1,57 +1,57 @@
----
-name: to-prd
-description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
----
-
-# To PRD
-
-Issue tracker + label vocabulary should exist; run `/setup-matt-pocock-skills` if missing.
-
-RULE: Do not interview user. Synthesize current context.
-
-## Process
-
-1. Explore repo if needed; use glossary; respect ADRs.
-2. Sketch test seams. Prefer existing seams; use highest seam possible. Propose new seams at highest point.
-3. Check with user: seams match expectations?
-4. Write PRD.
-5. Publish to issue tracker.
-6. Apply `ready-for-agent`.
-
-## PRD template
-
-```markdown
-## Problem Statement
-
-{user-facing problem}
-
-## Solution
-
-{user-facing solution}
-
-## User Stories
-
-1. As a {actor}, I want {feature}, so that {benefit}
-
-## Implementation Decisions
-
-- Modules/interfaces changed.
-- Technical clarifications.
-- Architecture/schema/API/contracts/interactions.
-- No file paths.
-- Prototype snippets allowed only if decision-rich and trimmed.
-
-## Testing Decisions
-
-- Good tests verify external behaviour, not implementation.
-- Seams to test; prefer existing/highest seam.
-- Similar tests/prior art.
-
-## Out of Scope
-
-{excluded work}
-
-## Further Notes
-
-{other notes}
-```
+---
+name: to-prd
+description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context.
+---
+
+# To PRD
+
+Issue tracker + label vocabulary should exist; run `/setup-matt-pocock-skills` if missing.
+
+RULE: Do not interview user. Synthesize current context.
+
+## Process
+
+1. Explore repo if needed; use glossary; respect ADRs.
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+3. Check with the user that these seams match their expectations.
+4. Write PRD.
+5. Publish to issue tracker.
+6. Apply `ready-for-agent`.
+
+## PRD template
+
+```markdown
+## Problem Statement
+
+{user-facing problem}
+
+## Solution
+
+{user-facing solution}
+
+## User Stories
+
+1. As a {actor}, I want {feature}, so that {benefit}
+
+## Implementation Decisions
+
+- Modules/interfaces changed.
+- Technical clarifications.
+- Architecture/schema/API/contracts/interactions.
+- No file paths.
+- Prototype snippets allowed only if decision-rich and trimmed.
+
+## Testing Decisions
+
+- Good tests verify external behaviour, not implementation.
+- Seams to test; prefer existing/highest seam.
+- Similar tests/prior art.
+
+## Out of Scope
+
+{excluded work}
+
+## Further Notes
+
+{other notes}
+```