@fernado03/zoo-flow 0.5.2 → 0.7.0

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

@@ -1,152 +1,218 @@
----
-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.
+
+## Context-pack selector
+
+After detecting project shape and proposing CONTEXT.md terms + ADRs, recommend the smallest useful set of optional context docs.
+
+Rules:
+
+- Templates live under `.roo/skills/engineering/scaffold-context/templates/` (candidates only, never installed by default).
+- Missing optional docs are **not an error**.
+- Recommend a doc only when code evidence shows it would change future agent behavior.
+- Prefer one compact doc over many thin docs.
+- Better to create zero optional docs than wrong docs.
+- Ask for confirmation before writing any optional doc.
+
+Consider optional docs only with code evidence:
+
+| Doc | When to recommend |
+|---|---|
+| `TESTING.md` | unusual verification setup, multiple test layers, important seams |
+| `DATA_MODEL.md` | schemas, lifecycle states, ownership, migrations visible in code |
+| `API_CONTRACTS.md` | public routes, SDK exports, webhooks, event payloads |
+| `RUNBOOK.md` | deploys, jobs, queues, cron, recovery procedures |
+| `SECURITY_NOTES.md` | auth, permissions, tenant isolation, secrets, payments |
+| `INTEGRATIONS.md` | third-party APIs, OAuth, Stripe, email, queues, LLM providers |
+| `MONOREPO_MAP.md` | multiple apps/packages/services with different responsibilities |
+
+### Output shape
+
+```
+## Suggested context pack
+
+Detected shape: <shape>
+
+Recommended:
+1. `.zoo-flow/CONTEXT.md`
+   Reason: repeated domain terms found.
+2. `.zoo-flow/DATA_MODEL.md`
+   Reason: schema migration logic found in 4 files.
+
+Maybe:
+1. `.zoo-flow/SECURITY_NOTES.md`
+   Reason: auth middleware exists, but permission model appears simple.
+
+Skipped:
+- `RUNBOOK.md` — no deployment or operational recovery surface found.
+- `DATA_MODEL.md` — schema is simple; terms fit in CONTEXT.md.
+
+Choose:
+1. Create recommended only
+2. Choose manually
+3. Cancel
+```
+
+### Selection matrix by shape
+
+| Shape | Likely recommended | Likely maybe | Likely skipped |
+|---|---|---|---|
+| web app | CONTEXT.md | SECURITY_NOTES.md, INTEGRATIONS.md | RUNBOOK.md, MONOREPO_MAP.md |
+| library | CONTEXT.md, API_CONTRACTS.md | TESTING.md | RUNBOOK.md, MONOREPO_MAP.md |
+| CLI tool | CONTEXT.md | RUNBOOK.md | DATA_MODEL.md, MONOREPO_MAP.md |
+| data pipeline | CONTEXT.md, DATA_MODEL.md | RUNBOOK.md | API_CONTRACTS.md |
+| serverless | CONTEXT.md, INTEGRATIONS.md | SECURITY_NOTES.md | MONOREPO_MAP.md |
+| monorepo | CONTEXT.md, MONOREPO_MAP.md | INTEGRATIONS.md, API_CONTRACTS.md | RUNBOOK.md |
+
+Do not let this selector delay the core CONTEXT.md + ADR proposal. Present the pack selection after the main confirm flow.
+
+## MUST
+
+- Ask confirm before writing `CONTEXT.md` (show full proposed list + diff against existing)
+- Ask confirm per ADR before writing
+- Ask confirm per optional doc 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/scaffold-context/templates/writing-patterns.md

@@ -0,0 +1,17 @@
+---
+name: writing-patterns
+description: "Optional context pack for writing/editorial projects. Adds shapes, beats, and fragments skills for structured content creation."
+selector: project-shape
+match-keywords: ["writing", "content", "editorial", "blog", "documentation", "docs-site"]
+---
+
+# Writing Patterns Context Pack
+
+This pack adds structured writing workflows:
+
+- **Shapes** — reusable content architecture templates
+- **Beats** — narrative/argument sequencing patterns
+- **Fragments** — reusable content components
+
+None of these are activated by default. Run `/scaffold-context` and
+select "writing-patterns" to install.

package/templates/full/.roo/skills/engineering/setup-matt-pocock-skills/SKILL.md

@@ -14,8 +14,8 @@ Read/check:
 1. `git remote -v` + `.git/config`.
 2. Root `AGENTS.md`, `CLAUDE.md`.
 3. Existing `## Agent skills` blocks.
-4. Root `CONTEXT.md`, `CONTEXT-MAP.md`.
-5. `docs/adr/`, `src/*/docs/adr/`.
+4. `.zoo-flow/CONTEXT.md`.
+5. `.zoo-flow/docs/adr/`.
 6. `docs/agents/`.
 7. `.scratch/`.
 
@@ -33,7 +33,7 @@ B. Triage labels:
 
 C. Domain docs:
 - Explain: skills read `CONTEXT.md` + ADRs.
-- Choices: single-context root `CONTEXT.md` + `docs/adr/`; multi-context `CONTEXT-MAP.md` → per-context docs.
+- Choices: single-context `.zoo-flow/CONTEXT.md` + `.zoo-flow/docs/adr/`; multi-context index → per-context docs.
 
 ## Confirm before write
 

package/templates/full/.roo/skills/engineering/setup-matt-pocock-skills/domain.md

@@ -3,9 +3,8 @@
 ## Read before work
 
 If present:
-1. Root `CONTEXT.md`, or root `CONTEXT-MAP.md` then relevant context docs.
-2. Relevant root `docs/adr/` ADRs.
-3. If multi-context, relevant `src/{context}/docs/adr/`.
+1. `.zoo-flow/CONTEXT.md`.
+2. `.zoo-flow/docs/adr/` ADRs.
 
 If missing, proceed silently.
 

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

@@ -50,6 +50,8 @@ Checklist per cycle:
 - [ ] Code minimal.
 - [ ] No speculation.
 
+After green, suggest `/verify`, then `/review`, then `/commit-and-document` for non-trivial work. Do not auto-launch follow-up commands.
+
 ## Context economy
 
 Before broad reads, locate relevant files/symbols with `list_files`, `search_files`, or `codebase_search`.

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 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}
-```
+---
+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}
+```

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

@@ -14,7 +14,8 @@ Use for small known fixes.
 5. If existing test covers touched area, run it.
 6. DO NOT write new tests unless asked.
 7. Confirm change.
-8. Offer `/commit-and-document` only after user satisfied.
+8. For R3+ risk, suggest `/verify` or `/review` before commit. Otherwise offer `/commit-and-document` only after user satisfied.
+9. Do not auto-launch follow-up commands.
 
 ## Context economy
 

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

@@ -0,0 +1,80 @@
+---
+name: verify
+description: Run the smallest useful checks for the current change and report exactly what passed, failed, was partial, or was blocked.
+---
+
+# Verify
+
+Purpose: answer what checks actually passed. Never claim verified unless commands ran and passed.
+
+## 1. Inspect project type
+
+Look for obvious build/test config before choosing commands:
+
+- `package.json`
+- `pyproject.toml`
+- `Cargo.toml`
+- `go.mod`
+- other build, lint, or test config in the changed area
+
+## 2. Inspect changed files
+
+Run:
+
+- `git status --short`
+- `git diff --stat`
+- `git diff --cached --stat` when staged changes exist
+
+## 3. Pick smallest useful checks first
+
+Prefer, in order:
+
+- targeted test for the changed area
+- related test file
+- typecheck
+- lint
+- build
+- full test suite only when appropriate
+
+Use package scripts and project conventions when available. If the user provides a command, prefer it unless unsafe.
+
+## 4. Run checks
+
+Run the chosen commands. Capture enough output to prove pass/fail without dumping noise.
+
+If no verification command is available, report blocked.
+
+## 5. Output format
+
+```md
+## Verification result
+
+Status: pass | fail | partial | blocked
+
+## Commands run
+
+- `<command>` — pass/fail
+
+## Evidence
+
+<short summary of relevant output>
+
+## Remaining risk
+
+<what was not checked>
+
+## Recommended next step
+
+<none | /review | /tweak | /tdd | /fix | /commit-and-document>
+```
+
+Hard rule: never say `verified`, `all good`, or `tests pass` unless commands actually ran and passed.
+
+If no checks are available, use:
+
+```text
+Status: blocked
+Reason: no verification command found
+```
+
+Do not auto-launch any follow-up command.

package/templates/full/.roo/skills/in-progress/README.md

@@ -2,7 +2,6 @@
 
 Draft skills. Excluded from plugin/top README until stable.
 
-- **[review](./review/SKILL.md)** — Review diff on Standards + Spec axes.
 - **[teach](./teach/SKILL.md)** — Stateful teaching workspace (mission, glossary, resources, learning records).
 - **[writing-beats](./writing-beats/SKILL.md)** — Assemble article beat-by-beat.
 - **[writing-fragments](./writing-fragments/SKILL.md)** — Capture raw writing fragments.