opencastle 0.32.12 → 0.33.0

package/src/orchestrator/skills/context-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: context-map
-description: "Generate a structured file impact map before making changes. Identifies all files that will be affected, their relationships, and cascade effects — improving file partitioning for parallel work and reducing unexpected side effects."
+description: "Maps file dependencies, flags shared imports, and groups files for safe parallel editing before code changes. Use when planning a refactoring, analyzing change impact, or understanding which files a modification will affect."
 ---
 
 # Skill: Context Map
@@ -22,72 +22,45 @@ Generate a **file impact map** before code changes to identify affected files, r
 Identify files that MUST change from the task description.
 
 ### 2 — Trace Outward (dependents)
-Use `grep_search` / `list_code_usages`: imports, type consumers, route references, query consumers, test files.
+Find consumers of entry-point exports:
+```
+grep_search("import.*from.*places", isRegexp=true)   # find importers
+vscode_listCodeUsages("PlaceCard")                     # find component consumers
+grep_search("places.*route|/places", isRegexp=true)    # find route references
+```
 
 ### 3 — Trace Inward (sources)
-CMS schemas, `libs/` utilities, config files.
-### 4 — Build the Map
-
-```markdown
-## Context Map: [Task Name]
-
-### Entry Points (MUST change)
-| File | Reason | Owner |
-|------|--------|-------|
-| `libs/queries/src/lib/places.ts` | Add query field | Content Engineer |
-| `libs/ui-kit/.../PlaceCard/` | Display new field | UI/UX Expert |
-
-### Cascade Effects (WILL change)
-| File | Triggered By | Reason | Owner |
-|------|-------------|--------|-------|
-| `apps/web-app/places/page.tsx` | PlaceCard | Update props | Frontend Dev |
-| `libs/queries/src/lib/__tests__/places.test.ts` | Query | Update test | Testing Expert |
-
-### Shared Boundaries (WATCH)
-| File | Risk | Mitigation |
-|------|------|------------|
-| `libs/ui-kit/src/lib/index.ts` | Barrel export conflict | Merge sequentially |
-
-### Unaffected
-| Area | Why |
-|------|-----|
-| `db/migrations/` | No DB changes |
-| `libs/auth/` | No auth changes |
+Find what entry points depend on:
+```
+grep_search("from.*libs/", includePattern="src/places/**")  # shared lib deps
+grep_search("from.*config", includePattern="src/places/**")  # config deps
 ```
 
-### 5 — Derive File Partitions
-
-Assign ownership — no file in two partitions; shared boundaries to one agent (merged first); test files to Testing Expert unless tightly coupled.
+### 4 — Build the Map
 
-```
-Agent A: libs/queries/src/lib/places.ts
-Agent B: libs/ui-kit/.../PlaceCard/
-Agent C: apps/web-app/places/, apps/admin-panel/places/
-Agent D: **/*test*, **/*spec*
-```
+Produce a compact Context Map for the Team Lead and downstream agents. Example minimal map (inline):
 
-## Depth Levels
+```markdown
+Context Map — Feature: Add priceRange
 
-| Complexity | Files | Depth |
-|------------|-------|-------|
-| Small | 1–3 | Entry points + direct imports |
-| Medium | 4–8 | Entry + 1-hop cascade |
-| Large | 9+ | Full dependency graph |
+- Entry points:
+	- src/lib/place/schema.ts
+	- src/components/PriceRangeFilter/PriceRangeFilter.tsx
 
-## Team Lead Integration
+- Dependents (trace outward):
+	- src/pages/places/page.tsx
+	- src/components/PlacesList/PlaceCard.tsx
 
-Produced in **Phase 1**; consumed by:
-- **Decomposition** — informs file partitions
-- **Delegation prompts** — agents receive their map section
-- **QA Gate** — compare actual changes against map to detect scope creep
+- Sources (trace inward):
+	- src/lib/filters.ts
+	- src/shared/types/place.ts
 
-Delegation prompt snippet:
-```markdown
-## Your File Partition
-Modify only: `libs/queries/src/lib/places.ts`, `libs/queries/src/lib/__tests__/places.test.ts`
-Do NOT modify: `libs/ui-kit/` (UI/UX Expert), `apps/` (Developer)
+- Unaffected (optional):
+	- src/components/Account/**
 ```
 
+Validation checkpoint: run `grep_search` and `vscode_listCodeUsages` results into the map and confirm all listed files open without errors (CI: `pnpm typecheck`). For full template and Team Lead integration snippets see REFERENCE.md in this directory.
+
 ## Anti-Patterns
 
 - Skipping for "obvious" tasks — shared libs cascade unexpectedly

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

@@ -0,0 +1,55 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Data Engineering Reference
+
+This file contains detailed code examples and schemas migrated from the skill doc.
+
+### Minimal Scraper: `scrape-to-ndjson.js` (Playwright)
+
+```js
+const fs = require('fs');
+const { chromium } = require('playwright');
+const out = process.argv[2] || 'data.ndjson';
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const fh = fs.createWriteStream(out, { flags: 'w' });
+  await page.goto('https://example.com/list');
+  const items = await page.$$eval('.item', (nodes) => nodes.map(n => ({
+    name: n.querySelector('.title')?.textContent?.trim(),
+    source: 'example',
+    sourceId: n.getAttribute('data-id')
+  })));
+  for (const it of items) fh.write(JSON.stringify(it) + '\n');
+  fh.end();
+  await browser.close();
+})();
+```
+
+### NDJSON Validator: `validate-ndjson.js` (Node)
+
+```js
+const fs = require('fs');
+const readline = require('readline');
+const { z } = require('zod');
+const schema = z.object({ name: z.string(), source: z.string(), sourceId: z.string() });
+const path = process.argv[2];
+if (!path) throw new Error('Usage: node validate-ndjson.js <file.ndjson>');
+const rl = readline.createInterface({ input: fs.createReadStream(path), crlfDelay: Infinity });
+let line = 0; let errors = 0;
+(async () => {
+  for await (const l of rl) {
+    line++;
+    try { const obj = JSON.parse(l); schema.parse(obj); }
+    catch (e) { console.error('Line', line, e.message); errors++; }
+  }
+  if (errors) { console.error(errors, 'validation errors'); process.exit(2); }
+  console.log('OK');
+})();
+```
+
+### NDJSON Schema
+
+For project-specific schemas, add JSON Schema files here.
+
+Last Updated: 2026-03-31

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.