opencastle 0.32.11 → 0.32.13

package/src/orchestrator/skills/data-engineering/SKILL.md

@@ -1,36 +1,19 @@
 ---
 name: data-engineering
-description: "Data pipeline ETL workflows, web scraping, NDJSON processing, and CMS data import. Use when building scrapers, processing data, running CLI tools, or importing to a CMS."
+description: "Transforms, validates, and loads data in ETL pipelines. Use when building scrapers, validating NDJSON feeds, or importing data into CMS/DB targets."
 ---
 
 # Data Engineering
 
-Generic pipeline patterns. For project-specific sources, CLI commands, and data status see [data-pipeline-config.md](../../.opencastle/stack/data-pipeline-config.md).
+Generic pipeline patterns. For project-specific sources and full schema references see [REFERENCE.md](./REFERENCE.md).
 
 ## Scraper Architecture
 
-```typescript
-interface ScraperConfig {
-  source: string; query: string; maxPages: number; concurrency: number;
-  delay: { min: number; max: number }; outputPath: string; headless: boolean;
-}
-abstract class BaseScraper {
-  abstract scrape(config: ScraperConfig): Promise<void>;
-  abstract extractVenue(page: Page): Promise<RawVenue>;
-  abstract getNextPage(page: Page): Promise<string | null>;
-}
-```
-
 Launch a headless browser cluster (Puppeteer Cluster / Playwright) with `retryLimit: 3`, `retryDelay: 5000`, `timeout: 30000`, `args: ['--no-sandbox', '--disable-setuid-sandbox']`.
 
-**Anti-detection:** rotate user-agents; random 2–5 s delays; randomize viewport; block images/fonts/CSS; use stealth plugin.
-
-**Error recovery:** exponential backoff (3 retries); log failed URLs; save partial results; checkpoint/resume for long runs.
-
 ## NDJSON Output
 
-One record per line: `{"name":"…","lat":50.0755,"lng":14.4378,"source":"google-maps","sourceId":"ChIJ…","category":"bar","address":"…","rating":4.5,"reviewCount":120}`
-
+One record per line. Schema:
 | Field | Type | Notes |
 |-------|------|-------|
 | `name` | Required | Preserve original encoding |
@@ -41,17 +24,40 @@ One record per line: `{"name":"…","lat":50.0755,"lng":14.4378,"source":"google
 | `category` | Required | Domain category |
 | `rating`, `reviewCount`, `phone`, `website`, `openingHours`, `photos`, `priceLevel` | Optional | — |
 
-## Design Principles
-
-| Principle | Detail |
-|-----------|--------|
-| Composable stages | Single-responsibility pipeline steps |
-| Streams | Use for large files to minimize memory |
-| Idempotent imports | `createOrReplace` + deterministic `_id` |
-| Dry-run mode | Required for all destructive operations |
-| Normalized names | Strip diacritics for search |
-| Structured addresses | `{ street, city, postalCode, country, countryCode }` |
-| Data lineage | Record source and transformation history |
-| Error handling | Skip bad records; don't halt pipeline |
-| Backup | Before all bulk operations |
-| Rate limiting | Respect `robots.txt`; attribute sources |
+## Recommended Workflow (numbered, with validation)
+
+1. Scrape: run scraper in `--dry-run` to collect a sample (50–200 records).
+   - Checkpoint: sample contains expected fields and geo data.
+   - Recovery: fix extractor selectors, re-run sample.
+2. Validate NDJSON: run line-by-line JSON parse + schema validator (see `validate-ndjson.js` example).
+   - Checkpoint: 0 parse errors, required fields present.
+   - Recovery: run `ndjson-filter` to isolate failing records and inspect source HTML.
+3. Dry-run import: import into staging with `createOrReplace` disabled; check counts and duplicates.
+   - Checkpoint: counts match expectation ±5% and no duplicates inserted.
+   - Recovery: revert staging and adjust dedupe key.
+4. Backup: snapshot current target (DB export) and store with timestamp.
+5. Import: run import with idempotent keys and monitor logs; on failure revert to backup.
+
+## Quick executable pipeline (copy & adapt)
+
+```bash
+node ./scripts/scrape-to-ndjson.js --out=data.ndjson --pages=100
+node ./scripts/validate-ndjson.js data.ndjson
+node ./scripts/dry-import.js data.ndjson --target=staging
+node ./scripts/import.js data.ndjson --target=production
+```
+
+## Inline: minimal NDJSON validator
+
+```js
+const fs = require('fs'), rl = require('readline'), { z } = require('zod');
+const schema = z.object({ name: z.string(), source: z.string(), sourceId: z.string() });
+const iface = rl.createInterface({ input: fs.createReadStream(process.argv[2]) });
+let line = 0, errors = 0;
+for await (const l of iface) { line++; try { schema.parse(JSON.parse(l)); } catch(e) { console.error(`Line ${line}:`, e.message); errors++; } }
+if (errors) { console.error(`${errors} errors`); process.exit(2); }
+console.log('OK');
+```
+
+Full scraper and extended validator: see [REFERENCE.md](./REFERENCE.md).
+

package/src/orchestrator/skills/decomposition/REFERENCE.md

@@ -0,0 +1,28 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Delegation Spec — Full Template
+
+## Delegation Spec: [Task Title]
+**Tracker Issue:** TAS-XX — [Title]
+**Complexity:** [score]/13 → [tier] tier
+**Agent:** [Agent Name]
+
+### Objective
+1-3 sentences: what to build/change and why.
+
+### Context
+- Key files: [list]
+- Related patterns: [file:line references]
+- Prior phase output: [compacted summary if applicable]
+- Relevant lessons: [LES-XXX from LESSONS-LEARNED.md]
+
+### Constraints
+- File partition: Only modify files under [paths]
+- Do NOT modify: [explicit exclusions]
+- Dependencies: Requires [TAS-XX] Done first
+
+### Acceptance Criteria
+- [ ] Criterion 1
+
+### Expected Output
+Files changed · Verification (lint/test/build) · AC status (✅/❌) · Discovered issues · Lessons applied

package/src/orchestrator/skills/decomposition/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: decomposition
-description: "Task decomposition patterns for the Team Lead: dependency resolution, phase assignment, delegation spec templates, prompt quality examples, and orchestration patterns."
+description: "Resolves task dependencies, generates machine-actionable delegation specs, and structures phased subtask plans for multi-agent work. Use when writing delegation specs, resolving task dependencies, building phased subtask plans for multi-agent work, assigning work to sub-agents, or partitioning a feature into parallelizable phases."
 ---
 
 # Task Decomposition
 
-Load at: Decompose & Partition phase (Step 2) or when writing delegation prompts (Step 3).
 
 ## Dependency Resolution
 
@@ -22,36 +21,20 @@ D → B        Phase 2: C, D (parallel)
 F → C, D     Phase 3: E, F (parallel)
 ```
 
-## Delegation Spec (Score 5+)
+## Delegation Spec
 
-For score 1-3, objective + files + criteria is sufficient.
+| Field | Content |
+|-------|---------|
+| Tracker | TAS-XX — Title |
+| Complexity | [score]/13 → [tier] |
+| Agent | Agent Name |
+| Objective | 1-3 sentences: what to build/change and why |
+| Context | Key files, related patterns, prior phase output, relevant lessons |
+| Constraints | File partition, explicit exclusions, phase dependencies |
+| Acceptance Criteria | `[ ]` checklist |
+| Expected Output | Files changed · Verification · AC status · Discovered issues |
 
-```
-## Delegation Spec: [Task Title]
-**Tracker Issue:** TAS-XX — [Title]
-**Complexity:** [score]/13 → [tier] tier
-**Agent:** [Agent Name]
-
-### Objective
-1-3 sentences: what to build/change and why.
-
-### Context
-- Key files: [list]
-- Related patterns: [file:line references]
-- Prior phase output: [compacted summary if applicable]
-- Relevant lessons: [LES-XXX from LESSONS-LEARNED.md]
-
-### Constraints
-- File partition: Only modify files under [paths]
-- Do NOT modify: [explicit exclusions]
-- Dependencies: Requires [TAS-XX] Done first
-
-### Acceptance Criteria
-- [ ] Criterion 1
-
-### Expected Output
-Files changed · Verification (lint/test/build) · AC status (✅/❌) · Discovered issues · Lessons applied
-```
+For score 1-3, objective + files + criteria is sufficient. See `REFERENCE.md` for the full delegation spec template.
 
 Read `.opencastle/LESSONS-LEARNED.md` before starting. Add a lesson if you retry any approach.
 
@@ -107,4 +90,6 @@ Phase 2+: page tasks (parallel)
 
 **Common mistake:** Decomposing pages as independent Phase 1 tasks → each agent invents its own design.
 
+**Distinctive note (AI delegation):** This skill focuses on decomposition that produces machine-actionable delegation prompts: file partitions, explicit acceptance criteria, and machine-friendly constraints (exact paths, line ranges, forbidden files). The output should be ready to paste into a sub-agent prompt without additional human translation.
+
 > Load the **project-consistency** skill for the full Foundation Phase pattern, prompt templates, and anti-patterns.

package/src/orchestrator/skills/deployment-infrastructure/SKILL.md

@@ -1,29 +1,17 @@
 ---
 name: deployment-infrastructure
-description: "Deployment architecture, environment variables, cron jobs, security headers, and caching patterns. Use when configuring deployments, managing environment variables, setting up cron jobs, or troubleshooting build/deployment issues."
+description: "Configures deployment pipelines, manages environment variables, schedules cron jobs, applies security headers, and implements caching strategies. Use when working with Docker, Vercel, AWS, Dockerfile, nginx.conf, or platform deployment configs."
 ---
 
 # Deployment Infrastructure
 
-All deployment configuration is project-specific. See [deployment-config.md](../../.opencastle/stack/deployment-config.md) for the full architecture, environment variables, cron jobs, caching headers, and key files.
-
-## Generic Deployment Principles
-
-- Use platform-native Git integration for CI/CD (push to `main` = production, push to branch = preview)
-- Store all secrets as environment variables — never in code, commits, or logs
-- Use `Bearer` token auth for cron job endpoints
-- Apply security headers via framework config (HSTS, CSP, X-Frame-Options, Permissions-Policy)
-- Cache static assets with `max-age=31536000, immutable`; use `max-age=86400` for favicon/manifest
-- Load the **security-hardening** skill for full header inventory and CSP configuration
+See [deployment-config.md](../../.opencastle/stack/deployment-config.md) for full architecture, env vars, cron jobs, and caching headers.
 
 ## Environment Variables
 
 ### Layering & Precedence
 
-1. `.env` — shared defaults; committed, no secrets
-2. `.env.local` — developer overrides; git-ignored
-3. `.env.production` / `.env.preview` — environment-specific values
-4. Platform-injected — set in hosting dashboard (highest priority)
+`.env` (defaults, committed) → `.env.local` (git-ignored) → `.env.production` / `.env.preview` → Platform-injected (highest).
 
 ### Startup Validation
 
@@ -43,8 +31,7 @@ export const env = envSchema.parse(process.env);
 
 ### Naming
 
-- Prefix: `PUBLIC_*`/`NEXT_PUBLIC_*` (browser-safe), `SECRET_*`/`*_SECRET` (server-only), `CRON_SECRET` (cron)
-- `SCREAMING_SNAKE_CASE`; gitignore `.env.local`, `.env.*.local`, `.env.production`
+Prefix: `PUBLIC_*`/`NEXT_PUBLIC_*` (browser-safe), `SECRET_*`/`*_SECRET` (server-only). `SCREAMING_SNAKE_CASE`. Gitignore `.env.local`, `.env.*.local`.
 
 ## CI/CD Pipeline
 
@@ -65,65 +52,44 @@ export async function GET(request: Request) {
 
 ## Caching Strategy
 
-| Asset Type | `Cache-Control` Header | Rationale |
-|---|---|---|
-| Hashed static assets (JS, CSS) | `public, max-age=31536000, immutable` | Content-addressed; safe to cache forever |
-| Images / fonts | `public, max-age=31536000, immutable` | Typically fingerprinted |
-| Favicon / manifest | `public, max-age=86400` | Refreshes within a day |
-| HTML pages (SSG) | `public, max-age=0, must-revalidate` | Serve stale while revalidating |
-| API responses | `private, no-cache` | User-specific or frequently changing |
-| Prerendered pages (ISR) | `public, s-maxage=3600, stale-while-revalidate=86400` | CDN: 1h cache, 1d stale |
+| Asset Type | `Cache-Control` Header |
+|---|---|
+| Hashed static assets (JS, CSS) | `public, max-age=31536000, immutable` |
+| Images / fonts | `public, max-age=31536000, immutable` |
+| Favicon / manifest | `public, max-age=86400` |
+| HTML pages (SSG) | `public, max-age=0, must-revalidate` |
+| API responses | `private, no-cache` |
+| Prerendered pages (ISR) | `public, s-maxage=3600, stale-while-revalidate=86400` |
 
 Apply via framework `headers()` config or CDN rules.
 
 ## Security Headers
 
-Apply globally via framework config or middleware. See **security-hardening** skill for full CSP configuration.
-
-```javascript
-const securityHeaders = [
-  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
-  { key: 'X-Content-Type-Options', value: 'nosniff' },
-  { key: 'X-Frame-Options', value: 'DENY' },
-  { key: 'X-XSS-Protection', value: '1; mode=block' },
-  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
-  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
-  { key: 'Content-Security-Policy', value: "default-src 'self'; script-src 'self' 'unsafe-inline';" },
-];
-```
-
-- HSTS `max-age` ≥ 31536000 for preload eligibility
-- `X-Frame-Options: DENY` prevents clickjacking; use `SAMEORIGIN` only for self-embeds
-- Keep CSP as restrictive as possible; document each exception
-- Disable unused browser features via `Permissions-Policy`
+Load **security-hardening** skill for full CSP inventory and header configuration.
 
 ## Release Process
 
-1. **Pre-Release Audit** — lint, test, build all affected projects; check `git diff` since last tag; verify no draft PRs
-2. **Regression Check** — spot-check adjacent features; run full test suites; verify critical user flows
-3. **Changelog** — generate from commits/PR titles; categorize (Features, Bug Fixes, Performance, Breaking Changes); include migration notes
-4. **Version** — semver (MAJOR/MINOR/PATCH); tag in git; update version references
-5. **Verify** — smoke-test production URLs; monitor error rates; document rollback steps
+1. **Audit** — lint, test, build; `git diff` since last tag; verify no draft PRs
+   - Gate: all commands exit 0
+2. **Changelog** — generate from commits; categorize (Features, Fixes, Breaking); include migration notes
+3. **Tag** — semver tag; update version references
+4. **Verify** — `curl -sI https://example.com | grep -E 'HTTP|Strict'` — smoke-test production URLs; monitor error rates
+   - Gate: homepage returns 200; headers correct
+   - Fail → rollback immediately
 
-## Rollback Procedures
+## Rollback
 
-1. **Platform rollback** — promote last known-good deployment from hosting dashboard
-2. **Git revert** — `git revert -m 1 HEAD && git push origin main`
+Prefer platform rollback (promote last good deploy). Fallback: `git revert -m 1 HEAD && git push`.
 
-- [ ] Confirm issue is deployment-related (not data or third-party)
-- [ ] Roll back via platform or git revert — never force-push `main`
-- [ ] Smoke-test the rollback deployment
-- [ ] Notify team; create post-mortem ticket
+1. Roll back → 2. Smoke-test (`curl -sI`) → 3. Confirm 200 + correct behavior → 4. If still broken, escalate
+5. Notify team; create post-mortem ticket
 
 ## Anti-Patterns
 
-| Anti-Pattern | Why | Fix |
-|---|---|---|
-| Hardcoding secrets | Leak via git, logs, bundles | Env vars + Zod startup validation |
-| Skipping preview deployments | Bugs reach production unreviewed | Deploy every branch to preview |
-| `Cache-Control: no-store` everywhere | Every request hits origin | Per-asset cache durations (see table) |
-| Force-push `main` to fix a deploy | Destroys history; breaks teammates | `git revert` to undo cleanly |
-| Disabling security headers "temporarily" | Temporary becomes permanent | Keep strict; document exceptions |
-| Builds without `--frozen-lockfile` | Non-deterministic installs | Always use `--frozen-lockfile` in CI |
-| `.env.local` in repository | Developer secrets leak | Gitignore; share via secure vault |
-| No startup env validation | Cryptic late-failure errors | Validate all vars at boot (fail fast) |
+| Anti-Pattern | Fix |
+|---|---|
+| Hardcoding secrets | Env vars + Zod startup validation |
+| Skipping preview deployments | Deploy every branch to preview |
+| `Cache-Control: no-store` everywhere | Per-asset cache durations (see table) |
+| Disabling security headers "temporarily" | Keep strict; document exceptions |
+| Builds without `--frozen-lockfile` | Always use `--frozen-lockfile` in CI |

package/src/orchestrator/skills/documentation-standards/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: documentation-standards
-description: "Documentation templates, structure, and standards for project docs, roadmaps, ADRs, and known issues. Use when writing or updating documentation files."
+description: "Scaffolds issue docs, ADRs, README outlines, changelog entries, roadmap updates, and Mermaid architecture diagrams using project templates. Use when drafting an ADR, writing a changelog, updating the roadmap after a feature ships, creating a README for a new library, or diagramming a system flow."
 ---
 
 # Documentation Standards
 
-Generic documentation templates and writing standards. For project-specific directory structure and practices, see [docs-structure.md](../../.opencastle/project/docs-structure.md).
+For project-specific directory structure and practices, see [docs-structure.md](../../.opencastle/project/docs-structure.md).
+
 
 ## Issue Documentation Template
 
@@ -33,10 +34,14 @@ Generic documentation templates and writing standards. For project-specific dire
 
 ## Roadmap Update Template
 
-When a feature is completed:
-1. Change status to `COMPLETE` and add completion date
-2. List modified files and update the summary table
-3. Move to completed section if applicable
+When a feature is completed: add `COMPLETE` row with date and owner, list files changed with rationale, add validation command + exit status, move to `Completed` section with one-line release note.
+
+```markdown
+- Feature: Add priceRange filter
+  Completed: 2026-03-30 | Owner: @developer
+  Files: src/components/PriceRangeFilter.tsx, src/lib/filters.ts
+  Validation: `pnpm build` (exit 0)
+```
 
 ## Architecture Decision Record Template
 
@@ -68,13 +73,7 @@ High-level overview. Include a Mermaid diagram for non-trivial systems.
 
 ## Mermaid Diagrams
 
-Keep diagrams focused — one concern per diagram.
-
-| Type | Use For | Directive |
-|------|---------|-----------|
-| Flowchart | Decision logic, pipelines | `flowchart TD` (top-down) / `flowchart LR` (left-right) |
-| Sequence | API flows, multi-service interactions | `sequenceDiagram` |
-| ER | Data models, relationships | `erDiagram` |
+Keep diagrams focused — one concern per diagram, max 10–12 nodes.
 
 ```mermaid
 flowchart TD
@@ -83,8 +82,8 @@ flowchart TD
   B -- No --> D[Return 401]
 ```
 
+- `flowchart TD` for pipelines, `LR` for request flows, `sequenceDiagram` for API flows, `erDiagram` for data models
 - Add `%% Title: ...` on complex diagrams; use verb labels on arrows
-- Limit to 10–12 nodes per diagram; `flowchart TD` for pipelines, `LR` for request flows
 
 ## Changelog Entry Template
 
@@ -101,39 +100,21 @@ Group entries by Conventional Commits type under a version heading:
 ```
 
 - One line per change; reference the PR or issue number
-- Imperative mood: "Add", "Fix", "Remove" — not "Added", "Fixed"
-- Groups: `Added`, `Fixed`, `Changed`, `Removed`, `Deprecated`, `Security`; most recent version first
-
-## Writing & Formatting
-
-- Clear, concise prose; avoid jargon; use relative paths for links; tables for structured data; include "Last Updated" dates
-- Archive outdated docs rather than deleting; cross-reference between documents; Mermaid for architecture
-- **Headings:** H2 for sections, H3 for subsections; no H1 (auto-generated from title), no H4+
-- **Lists:** `-` for bullets, `1.` for numbered; 2-space nested indent
-- **Code Blocks:** Fenced with language tag for syntax highlighting
-- **Links:** `[text](URL)` with descriptive text and valid URLs
-- **Images:** `![alt](url)` with brief alt text
-- **Whitespace:** Blank lines between sections; no excessive whitespace
-- **Front Matter:** YAML required for instruction/skill files — `title`/`name`, `description`, `applyTo` (instructions: glob of applicable files)
-
-## Pre-Merge Checklist
-
-- [ ] **Accuracy** — all code snippets, file paths, and commands are correct and tested
-- [ ] **Completeness** — no TODO placeholders or empty sections remain
-- [ ] **Links** — all internal and external links resolve (no 404s)
-- [ ] **Front matter** — YAML front matter is present and valid
-- [ ] **Formatting** — consistent heading levels, list style, whitespace, and Mermaid renders
-- [ ] **Cross-references** — related docs link to each other; "Last Updated" is current
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Bad | Do This Instead |
-|-------------|-------------|-----------------|
-| Wall of text with no headings | Unnavigable; readers skip it | Break into sections with H2/H3 |
-| Duplicating content across files | Copies drift; causes confusion | Link to a single source of truth |
-| Screenshots without alt text | Inaccessible; breaks when UI changes | Use Mermaid diagrams or describe the UI |
-| Documenting implementation details | Becomes stale as code changes | Document intent and contracts |
-| Using absolute file paths | Breaks on other machines | Use relative paths from doc location |
-| Huge monolithic README | Low signal-to-noise | Split into focused docs, link from README |
-| Undated documents | No way to judge currency | Always include "Last Updated" date |
-| Using H1 inside document body | Conflicts with auto-generated title | Start body headings at H2 |
+- Imperative mood; most recent version first
+
+## Documentation workflow
+
+1. **Draft** — create doc using templates above.
+2. **Validate** — run checks:
+   ```bash
+   npx markdown-link-check docs/**/*.md && pnpm prettier --check "docs/**/*.md"
+   ```
+   - Fail → fix broken paths/formatting → re-run step 2.
+3. **Review** — peer review via PR; address comments.
+4. **Publish** — merge; update roadmap/changelog.
+5. **Pre-Merge Checklist** — accuracy ✓, links resolve ✓, front matter valid ✓, no TODO placeholders ✓, formatting consistent ✓.
+
+
+## Writing, Formatting & Anti-Patterns
+
+See [WRITING-GUIDE.md](WRITING-GUIDE.md) for writing guidelines, formatting rules, and anti-patterns.

package/src/orchestrator/skills/documentation-standards/WRITING-GUIDE.md

@@ -0,0 +1,39 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Writing & Formatting Guide
+
+## Voice & Tone
+
+- **Imperative mood** for instructions: "Add the header" not "You should add the header"
+- **Active voice**: "The function returns X" not "X is returned by the function"
+- **Concise**: one idea per sentence; trim filler words (just, simply, basically, very)
+
+## Formatting Rules
+
+| Element | Convention |
+|---------|-----------|
+| Headings | Sentence case (`## Core principles`, not `## Core Principles`). Exception: proper nouns and acronyms. |
+| Lists | Parallel structure — all items start with the same part of speech |
+| Code | Inline backticks for symbols/commands; fenced blocks for multi-line |
+| Links | Descriptive text: `[migration guide](./migrate.md)` not `[click here](./migrate.md)` |
+| Tables | Use for structured comparisons; keep columns ≤5 |
+| Line length | Wrap prose at ~120 characters for diff readability |
+
+## Markdown Standards
+
+- One blank line before and after headings, code blocks, and tables
+- No trailing whitespace
+- Files end with a single newline
+- Use `---` for horizontal rules (sparingly)
+- Prefer `-` for unordered lists
+
+## Anti-Patterns
+
+| Anti-pattern | Fix |
+|-------------|-----|
+| Walls of prose without structure | Break into headings, bullets, or tables |
+| Duplicate content across docs | Link to the canonical source |
+| Stale "Last Updated" dates | Remove or automate; manual dates drift |
+| TODO/FIXME placeholders in published docs | Resolve before merging |
+| Screenshots without alt text | Add descriptive alt text for accessibility |
+| Overly nested headings (h4+) | Flatten; if you need h4, consider splitting the doc |

package/src/orchestrator/skills/fast-review/REFERENCE.md

@@ -0,0 +1,30 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Fast Review — Reviewer Prompt Template
+
+```markdown
+You are a code reviewer. Be concise and specific.
+
+## Task: [ID] — [Title]
+Acceptance Criteria: [list]
+
+## File Partition: [allowed dirs/files]
+## Changed Files: [path + key diff]
+## Deterministic: Lint: [P/F] | Tests: [P/F] | Build: [P/F]
+
+## Checklist
+1. Acceptance criteria met?
+2. Partition respected?
+3. No regressions?
+4. Errors surfaced (no swallowed exceptions)?
+5. Type safety (no `as any`)?
+6. No secrets/injection vectors?
+7. Edge cases handled?
+
+## Prior Feedback (retry only): [previous FAIL]
+
+VERDICT: PASS | FAIL
+ISSUES: - [severity:critical|major|minor] Description
+FEEDBACK: [Actionable feedback.]
+CONFIDENCE: low | medium | high
+```

package/src/orchestrator/skills/fast-review/SKILL.md

@@ -1,7 +1,6 @@
-````skill
 ---
 name: fast-review
-description: "Mandatory single-reviewer gate that runs after every agent delegation. Provides automatic retry with feedback and escalation to panel review after repeated failures. Essential for overnight/long-running autonomous sessions."
+description: "Mandatory post-delegation gate that checks output completeness, verifies acceptance criteria compliance, flags regressions, and produces a PASS/FAIL verdict. Use when checking delegated work against acceptance criteria, running the post-delegation gate, validating agent output before acceptance, verifying a sub-agent completed its assignment, or running a post-delegation QA check."
 ---
 
 # Skill: Fast Review
@@ -14,7 +13,7 @@ description: "Mandatory single-reviewer gate that runs after every agent delegat
 | Reviewer | Single sub-agent; Economy tier (Standard for premium/security work) |
 | Verdict | PASS or FAIL with structured feedback |
 | Retry | ≤2 retries on FAIL; 3rd FAIL → panel review |
-| Budget | ~2–5 min |
+ 
 
 ## Procedure
 
@@ -26,6 +25,10 @@ Issue + acceptance criteria, file diff, file partition, deterministic results (l
 
 Single `runSubagent`. Context = acceptance criteria, diff, partition, deterministic results **only** — no session history, no delegation prompt.
 
+```js
+runSubagent({ agentName: 'Reviewer', prompt: `Review against ACs:\n${criteria}\nDiff:\n${diff}\nGates: lint ✅ test ✅ build ✅` });
+```
+
 ### 3 — Parse Verdict
 
 ```
@@ -54,37 +57,16 @@ CONFIDENCE: low | medium | high
 
 ## Reviewer Prompt Template
 
-```markdown
-You are a code reviewer. Be concise and specific.
-
-## Task: [ID] — [Title]
-Acceptance Criteria: [list]
+See [REFERENCE.md](REFERENCE.md) for the full reviewer prompt template.
 
-## File Partition: [allowed dirs/files]
-## Changed Files: [path + key diff]
-## Deterministic: Lint: [P/F] | Tests: [P/F] | Build: [P/F]
-
-## Checklist
-1. Acceptance criteria met?
-2. Partition respected?
-3. No regressions?
-4. Errors surfaced (no swallowed exceptions)?
-5. Type safety (no `as any`)?
-6. No secrets/injection vectors?
-7. Edge cases handled?
+## Logging
 
-## Prior Feedback (retry only): [previous FAIL]
+> **⛔ HARD GATE — Log the review before proceeding.**
 
-VERDICT: PASS | FAIL
-ISSUES: - [severity:critical|major|minor] Description
-FEEDBACK: [Actionable feedback.]
-CONFIDENCE: low | medium | high
+```sh
+npx opencastle log review --skill <name> --outcome pass|fail --reviewer "Reviewer" --mechanism sub-agent
 ```
 
-## Logging
-
-> **⛔ HARD GATE — Log the review before proceeding.** Use **observability-logging** skill's review record command.
-
 ## Integration & Overnight Mode
 
 `on-post-delegate` Gate 5 (after deterministic Gates 1–4), ~5–15% token overhead. Overnight: upgrade one tier, escalate after 2 FAILs, checkpoint before panel.
@@ -97,5 +79,3 @@ CONFIDENCE: low | medium | high
 - **Ignoring minor issues** — track; 3+ recurrences → ticket.
 - **Force-accepting FAIL** — retry or escalate.
 - **Skipping deterministic checks** — does NOT replace lint/test/build.
-
-````