opencastle 0.32.4 → 0.32.6

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

@@ -5,154 +5,106 @@ description: "Task decomposition patterns for the Team Lead: dependency resoluti
 
 # Task Decomposition
 
-Detailed decomposition and delegation patterns for the Team Lead. **Load at:** Decompose & Partition phase (Step 2) or when writing delegation prompts (Step 3).
+Load at: Decompose & Partition phase (Step 2) or when writing delegation prompts (Step 3).
 
 ## Dependency Resolution
 
-Declare dependencies between subtasks using arrow notation: `TaskB → TaskA` means B depends on A (A must finish first).
+`TaskB → TaskA` = B depends on A (must finish first).
 
-**Topological sort rules:**
-1. Tasks with no dependencies go in Phase 1 (can run in parallel)
-2. Tasks depending only on Phase 1 tasks go in Phase 2
-3. Continue until all tasks are assigned to phases
-4. Tasks in the same phase with no mutual dependencies run in parallel
+**Topological sort:** No-dep tasks → Phase 1. Tasks depending only on Phase N → Phase N+1. Same-phase tasks with no mutual deps run in parallel.
 
-**Cycle detection:** If A → B → C → A, break the cycle by: (a) finding a task that can partially complete independently, (b) splitting that task into an independent part and a dependent part.
-
-**Visual example:**
+**Cycle detection:** If A → B → C → A, split one task into an independent part + a dependent part.
 
 ```
-Dependency Graph:        Execution Plan:
-E → C → A               Phase 1: A, B (parallel)
-D → B                   Phase 2: C, D (parallel, depend on Phase 1)
-F → C, D                Phase 3: E, F (parallel, depend on Phase 2)
+Graph:        Plan:
+E → C → A    Phase 1: A, B (parallel)
+D → B        Phase 2: C, D (parallel)
+F → C, D     Phase 3: E, F (parallel)
 ```
 
-Always draw the dependency graph before assigning phases. Missed dependencies cause agents to block on missing inputs; redundant sequencing wastes time.
-
-## Delegation Spec Template
+## Delegation Spec (Score 5+)
 
-For complex tasks (score 5+), generate a structured spec rather than a free-form prompt:
+For score 1-3, objective + files + criteria is sufficient.
 
 ```
 ## Delegation Spec: [Task Title]
-
 **Tracker Issue:** TAS-XX — [Title]
 **Complexity:** [score]/13 → [tier] tier
 **Agent:** [Agent Name]
 
 ### Objective
-What to build/change and why. 1-3 sentences max.
+1-3 sentences: what to build/change and why.
 
 ### Context
-- Key files to read first: [list]
-- Related patterns to follow: [file:line references]
-- Prior phase output (compacted): [summary from Context Compaction protocol if this task depends on a prior phase]
-- Relevant lessons: [LES-XXX references from LESSONS-LEARNED.md]
+- 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] to be Done first
+- Dependencies: Requires [TAS-XX] Done first
 
 ### Acceptance Criteria
-- [ ] Criterion 1 (copied from tracker issue)
-- [ ] Criterion 2
-- [ ] Criterion 3
+- [ ] Criterion 1
 
 ### Expected Output
-Return a structured summary with:
-- Files changed (path + one-line description)
-- Verification results (lint/test/build pass/fail)
-- Acceptance criteria status (each item ✅/❌)
-- Discovered issues (if any)
-- Lessons applied or added
-
-**Note:** Follow the Structured Output Contract from the team-lead-reference skill. Include all standard fields plus agent-specific extensions.
-
-### Self-Improvement
-Read `.opencastle/LESSONS-LEARNED.md` before starting. If you retry any command/tool with a different approach that works, use the **self-improvement** skill to add a lesson immediately.
+Files changed · Verification (lint/test/build) · AC status (✅/❌) · Discovered issues · Lessons applied
 ```
 
-For simpler tasks (score 1-3), the existing prompt format (objective + files + criteria) is sufficient. Don't over-engineer delegation for trivial work.
-
-**For sub-agents** — also specify what information to return in the result message.
-
-**For background agents** — include full self-contained context since they cannot ask follow-up questions.
-
-## Prompt Quality Examples
-
-**Strong prompt (simple task, score 2):**
-> "**Tracker issue:** TAS-42 — [Auth] Fix token refresh logic
-> Users report 'Invalid token' errors after 30 minutes. JWT tokens are configured with 1-hour expiration in `libs/auth/src/server.ts`. Investigate why tokens expire early and fix the refresh logic. Only modify files under `libs/auth/`. Run the auth library tests to verify."
+Read `.opencastle/LESSONS-LEARNED.md` before starting. Add a lesson if you retry any approach.
 
-**Strong prompt (complex task, score 8):**
-> Use the Delegation Spec Template above. Fill in all sections for tasks scoring 5+.
+## Prompt Quality
 
-**Weak prompt:**
-> "Fix the authentication bug."
+| Quality | Example |
+|---------|---------|
+| Strong (score 2) | "**TAS-42** — Fix token refresh. Users get 'Invalid token' after 30 min. JWT 1h expiry in `libs/auth/src/server.ts`. Fix refresh logic. Only `libs/auth/`. Run auth tests." |
+| Strong (score 8) | Use Delegation Spec Template above (all sections). |
+| Weak | "Fix the authentication bug." |
 
-## Delegation Mechanism Selection
+## Delegation Mechanism
 
 ```
-                         Need result immediately?
-                        /                        \
-                      YES                         NO
-                       |                           |
-              Is it a dependency              Expected duration
-              for the next step?              > 5 minutes?
-                /           \                  /          \
-              YES            NO              YES           NO
-               |              |               |             |
-          Sub-Agent      Sub-Agent       Background     Sub-Agent
-          (inline)    (if small enough,   Agent        (sequential)
-                       else Background)
+Need result immediately?
+ YES → Is dependency for next step?
+         YES → Sub-Agent (inline)
+         NO  → Sub-Agent or Background (if large)
+ NO  → Expected > 5 min?
+         YES → Background Agent
+         NO  → Sub-Agent (sequential)
 ```
 
-## Mixed Delegation Orchestration
+## Mixed Delegation
 
-Combine sub-agents and background agents for maximum efficiency:
+| Phase | Mode | Work |
+|-------|------|------|
+| 1 | sub-agent | Research — context, patterns, file map |
+| 2 | background | Foundation — DB migration + scaffolding (parallel) |
+| 3 | sub-agent | Integration — wire components to data |
+| 4 | background | Validation — security audit + tests + docs (parallel) |
+| 5 | sub-agent | QA gate — verify phases, run builds |
+| 6 | sub-agent | Panel review — load panel-majority-vote skill |
 
-```
-Phase 1 (sub-agent):     Research — gather context, identify patterns, map files
-Phase 2 (background):    Foundation — DB migration + Component scaffolding (parallel)
-Phase 3 (sub-agent):     Integration — wire components to data (needs Phase 2 results)
-Phase 4 (background):    Validation — Security audit + Tests + Docs (parallel)
-Phase 5 (sub-agent):     QA gate — verify all phases, run builds, self-review
-Phase 6 (sub-agent):     Panel review — load panel-majority-vote skill for high-stakes validation
-```
-
-## Foundation-First Decomposition
-
-When decomposing a multi-page or multi-component project, always apply the Foundation-First Pattern to maintain cross-agent consistency:
+## Foundation-First Pattern
 
-### When to apply
-
-- Goal involves 2+ pages, views, or UI sections
-- Multiple agents (same or different phase) will produce visual output
-- The project doesn't have an existing design system
-
-### Phase structure
+Apply when: 2+ pages/views/UI sections · multiple agents produce visual output · no existing design system.
 
 ```
 Phase 1: foundation-setup
-├── Creates: design tokens, layout, UI component library
-├── Defines: style guide brief (aesthetic, tone, terminology)
+├── Creates: design tokens, layout, UI component library, style guide brief
 └── All visual tasks → depends_on: [foundation-setup]
 
 Phase 2+: page tasks (parallel)
 ├── Each prompt includes 5 Foundation References
-└── Agents consume tokens — never create new values
+└── Consume tokens — never create new values
 ```
 
-### Partition rules for foundation
-
-- Foundation task owns: `src/styles/`, `src/components/Layout.*`, `src/components/ui/`
-- Page tasks own: their specific page file + page-specific components only
+**Partition rules:**
+- Foundation owns: `src/styles/`, `src/components/Layout.*`, `src/components/ui/`
+- Page tasks own: their page file + page-specific components only
 - No page task may list a foundation-owned path in its `files[]`
 
-### Common mistake
-
-Decomposing pages as independent Phase 1 tasks (no foundation). This produces partition-clean, dependency-valid specs that fail aesthetically — each agent invents its own design. Always add the foundation task as the root of the DAG for visual work.
+**Common mistake:** Decomposing pages as independent Phase 1 tasks → each agent invents its own design.
 
 > Load the **project-consistency** skill for the full Foundation Phase pattern, prompt templates, and anti-patterns.

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

@@ -3,39 +3,31 @@ 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."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # 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)
+- 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)
-- Set immutable cache headers for static assets (`max-age=31536000, immutable`)
-- Use short cache durations for frequently changing assets (e.g., favicon: `max-age=86400`)
+- 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
 
-## Environment Variable Management
+## Environment Variables
 
 ### Layering & Precedence
 
-Environment variables follow a layered override model (lowest to highest priority):
-
-1. `.env` — shared defaults, committed to repo (no secrets)
-2. `.env.local` — developer-specific overrides, git-ignored
+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 variables — set in hosting dashboard, highest priority
+4. Platform-injected — set in hosting dashboard (highest priority)
 
-### Validation at Startup
-
-Validate required variables at application startup. Fail fast with clear messages:
+### Startup Validation
 
 ```typescript
-// src/lib/env.ts
 import { z } from 'zod';
 
 const envSchema = z.object({
@@ -49,71 +41,46 @@ const envSchema = z.object({
 export const env = envSchema.parse(process.env);
 ```
 
-### Naming & .gitignore
-
-- `PUBLIC_*` or `NEXT_PUBLIC_*` — safe to expose to the browser
-- `SECRET_*` or `*_SECRET` — server-only, never bundled into client code
-- `CRON_SECRET` — authenticates scheduled job endpoints
-- Use `SCREAMING_SNAKE_CASE` for all variable names
-- Always gitignore `.env.local`, `.env.*.local`, and `.env.production`
+### Naming
 
-## CI/CD Pipeline Patterns
+- Prefix: `PUBLIC_*`/`NEXT_PUBLIC_*` (browser-safe), `SECRET_*`/`*_SECRET` (server-only), `CRON_SECRET` (cron)
+- `SCREAMING_SNAKE_CASE`; gitignore `.env.local`, `.env.*.local`, `.env.production`
 
-### Branch-Based Deployment
-
-```
-main branch    → Production deployment (auto)
-feature/*      → Preview deployment (auto)
-fix/*          → Preview deployment (auto)
-```
+## CI/CD Pipeline
 
-### Generic Pipeline Stages
+**Branch deployment:** `main` → Production (auto) | `feature/*`, `fix/*` → Preview (auto)
 
-Every pipeline should include these stages in order:
+**Stages (in order):** Install (`--frozen-lockfile`), Lint, Test (unit + integration + coverage), Build (production build), Deploy
 
-1. **Install** — restore dependencies from lockfile (`--frozen-lockfile`)
-2. **Lint** — static analysis and formatting checks
-3. **Test** — unit and integration tests with coverage
-4. **Build** — production build (catches type errors and build-time issues)
-5. **Deploy** — push artifacts to hosting platform
-
-### Cron Job Authentication
-
-Protect scheduled endpoints with a shared secret:
+**Cron auth:**
 
 ```typescript
-// app/api/cron/route.ts
 export async function GET(request: Request) {
   const authHeader = request.headers.get('authorization');
-  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`)
     return new Response('Unauthorized', { status: 401 });
-  }
-  // ... run scheduled task
   return Response.json({ ok: true });
 }
 ```
 
 ## Caching Strategy
 
-### Cache Duration Reference
-
 | Asset Type | `Cache-Control` Header | Rationale |
 |---|---|---|
-| Hashed static assets (JS, CSS) | `public, max-age=31536000, immutable` | Content-addressed filenames; safe to cache forever |
-| Images / fonts | `public, max-age=31536000, immutable` | Typically fingerprinted; long-lived |
-| Favicon / manifest | `public, max-age=86400` | Changes rarely but should refresh within a day |
+| 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 caches for 1 hour, serves stale for up to 1 day |
+| Prerendered pages (ISR) | `public, s-maxage=3600, stale-while-revalidate=86400` | CDN: 1h cache, 1d stale |
 
-Apply cache headers via framework config (e.g., `headers()` in `next.config.js`) or CDN rules. Match each route pattern to the appropriate duration from the table above.
+Apply via framework `headers()` config or CDN rules.
 
 ## Security Headers
 
-Apply these headers globally via framework config or middleware. See the **security-hardening** skill for full CSP configuration.
+Apply globally via framework config or middleware. See **security-hardening** skill for full CSP configuration.
 
 ```javascript
-// Recommended security headers
 const securityHeaders = [
   { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
   { key: 'X-Content-Type-Options', value: 'nosniff' },
@@ -125,68 +92,38 @@ const securityHeaders = [
 ];
 ```
 
-**Key rules:**
-
-- HSTS `max-age` must be at least 1 year (31536000 seconds) for preload eligibility
-- `X-Frame-Options: DENY` prevents clickjacking — use `SAMEORIGIN` only if you embed your own pages
-- CSP should be as restrictive as possible; expand only when needed, document each exception
+- 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`
 
 ## Release Process
 
-### 1. Pre-Release Audit
-- Run lint, test, and build for all affected projects (see the **codebase-tool** skill for commands)
-- Review all changed files since last release (`git diff` against last tag/release)
-- Check for uncommitted work or unmerged branches
-- Verify no draft PRs are accidentally included
-
-### 2. Regression Check
-- Identify features adjacent to changes and spot-check them
-- Run full test suites for all affected projects (not just changed files)
-- Check deployment preview builds for visual regressions
-- Verify critical user flows still work (e.g., primary navigation, form submissions, authenticated pages)
-
-### 3. Changelog & Release Notes
-- Generate changelog from commit messages and PR titles since last release
-- Categorize changes: Features, Bug Fixes, Performance, Breaking Changes, Internal
-- Write human-readable release notes summarizing impact
-- Include migration notes for any breaking changes
-
-### 4. Version Management
-- Follow semver: MAJOR (breaking), MINOR (features), PATCH (fixes)
-- Tag releases in git with the version number
-- Update version references in relevant files
-
-### 5. Release Verification
-- Confirm deployment succeeded on production
-- Smoke-test production URLs for critical pages
-- Monitor error rates and performance metrics post-release
-- Have rollback steps documented and ready (see § Rollback Procedures)
+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
 
 ## Rollback Procedures
 
-**Two rollback strategies** (prefer platform-level when available):
-
-1. **Platform rollback** — promote the last known-good deployment from the hosting dashboard
-2. **Git revert** — `git revert -m 1 HEAD && git push origin main` (triggers a clean redeploy)
-
-### Rollback Checklist
+1. **Platform rollback** — promote last known-good deployment from hosting dashboard
+2. **Git revert** — `git revert -m 1 HEAD && git push origin main`
 
-- [ ] Confirm the issue is deployment-related (not a data or third-party issue)
-- [ ] Roll back via platform or git revert — never force-push to `main`
-- [ ] Verify the rollback deployment is healthy (smoke tests)
-- [ ] Notify the team with a summary of what was rolled back and why
-- [ ] Create a post-mortem ticket to investigate root cause
+- [ ] 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
 
 ## Anti-Patterns
 
-| Anti-Pattern | Why It's Wrong | Correct Approach |
+| Anti-Pattern | Why | Fix |
 |---|---|---|
-| Hardcoding secrets in source code | Secrets leak via git history, logs, and client bundles | Use environment variables; validate with Zod at startup |
-| Skipping preview deployments | Bugs reach production without visual review | Deploy every branch to a preview environment |
-| Using `Cache-Control: no-store` everywhere | Destroys performance; every request hits origin | Use appropriate cache durations per asset type (see table above) |
-| Force-pushing to `main` to "fix" a bad deploy | Destroys git history; breaks other developers' branches | Use `git revert` to cleanly undo changes |
-| Disabling security headers "temporarily" | Temporary becomes permanent; opens attack surface | Keep headers strict; expand only with documented exceptions |
-| Running builds without `--frozen-lockfile` | Non-deterministic installs; works locally, fails in CI | Always use `--frozen-lockfile` (or equivalent) in CI |
-| Storing `.env.local` in the repository | Developer secrets and tokens leak to all contributors | Add `.env.local` to `.gitignore`; share via secure vault |
-| No startup validation of env vars | App starts but crashes later with cryptic errors | Validate all required variables at boot (fail fast) |
+| 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) |

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

@@ -3,8 +3,6 @@ name: documentation-standards
 description: "Documentation templates, structure, and standards for project docs, roadmaps, ADRs, and known issues. Use when writing or updating documentation files."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Documentation Standards
 
 Generic documentation templates and writing standards. For project-specific directory structure and practices, see [docs-structure.md](../../.opencastle/project/docs-structure.md).
@@ -26,9 +24,7 @@ Generic documentation templates and writing standards. For project-specific dire
 [Technical explanation]
 
 #### Solution Options
-1. **Option A** — [Description]
-   - Pros: ...
-   - Cons: ...
+1. **Option A** — [Description] — Pros: ... Cons: ...
 2. **Option B** — [Description]
 
 #### Related Files
@@ -46,7 +42,6 @@ When a feature is completed:
 
 ```markdown
 ## ADR-NNN: Decision Title
-
 **Date:** YYYY-MM-DD
 **Status:** Accepted | Superseded | Deprecated
 **Context:** [Why this decision was needed]
@@ -57,127 +52,71 @@ When a feature is completed:
 
 ## README Template
 
-Use this structure for library or feature-level READMEs:
-
 ```markdown
 # Feature / Library Name
-
 One-sentence summary of what this does and why it exists.
-
 ## Quick Start
-
 Brief usage example or setup steps.
-
 ## Architecture
-
 High-level overview. Include a Mermaid diagram for non-trivial systems.
-
 ## Key Files
-
 | File | Purpose |
 |------|---------|
 | `src/handler.ts` | Request handling logic |
 | `src/schema.ts` | Validation schemas |
 ```
 
-## Mermaid Diagram Patterns
+## Mermaid Diagrams
 
 Keep diagrams focused — one concern per diagram.
-### Flowchart (decision logic, pipelines)
+
+| 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` |
 
 ```mermaid
 flowchart TD
   A[Receive Request] --> B{Authenticated?}
-  B -- Yes --> C[Process Request]
+  B -- Yes --> C[Process]
   B -- No --> D[Return 401]
-  C --> E{Valid Input?}
-  E -- Yes --> F[Execute Action]
-  E -- No --> G[Return 400]
-```
-
-### Sequence Diagram (API flows, multi-service interactions)
-
-```mermaid
-sequenceDiagram
-  participant Client
-  participant API
-  participant DB
-  Client->>API: POST /resource
-  API->>DB: INSERT record
-  DB-->>API: OK
-  API-->>Client: 201 Created
 ```
 
-### ER Diagram (data models, relationships)
-
-```mermaid
-erDiagram
-  USER ||--o{ ORDER : places
-  ORDER ||--|{ LINE_ITEM : contains
-  USER { string id PK; string email }
-  ORDER { string id PK; date created_at }
-```
-
-### Diagram Guidelines
-
-- Add a title comment (`%% Title: ...`) at the top of complex diagrams
-- Use verb labels on relationship arrows
-- Limit nodes to 10–12 per diagram; split larger systems into sub-diagrams
-- Prefer `flowchart TD` (top-down) for pipelines and `flowchart LR` (left-right) for request flows
+- 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
 
-Follow Conventional Commits format. Group entries by type under a version heading:
+Group entries by Conventional Commits type under a version heading:
 
 ```markdown
 ## [1.2.0] — YYYY-MM-DD
-
 ### Added
 - feat: Add retry logic to API client (#123)
-
 ### Fixed
 - fix: Resolve race condition in queue processor (#127)
-
 ### Changed
 - refactor: Extract validation into shared module (#125)
 ```
 
-### Changelog Rules
-
 - One line per change; reference the PR or issue number
-- Use imperative mood: "Add", "Fix", "Remove" — not "Added", "Fixed"
-- Group under `Added`, `Fixed`, `Changed`, `Removed`, `Deprecated`, `Security`
-- Most recent version at the top
-
-## Writing Guidelines
-
-- Write clear, concise prose — avoid jargon unless necessary
-- Include Mermaid diagrams for architecture
-- Link to related files using relative paths
-- Use tables for structured data; include "Last Updated" dates on all documents
-- Archive outdated docs rather than deleting; cross-reference between documents
-
-### Formatting Rules
-
-- **Headings**: Use H2 for sections, H3 for subsections. Do not use H1 — generated from title. Avoid H4+
-- **Lists**: Use `-` for bullet points and `1.` for numbered lists; indent nested lists with two spaces
-- **Code Blocks**: Use fenced code blocks with language specified for syntax highlighting
-- **Links**: Use `[link text](URL)` with descriptive text and valid URLs
-- **Images**: Use `![alt text](image URL)` with brief descriptive alt text
-- **Tables**: Use `|` tables with properly aligned columns and headers
-- **Whitespace**: Use blank lines to separate sections; avoid excessive whitespace
-
-### Front Matter
-
-Include YAML front matter at the beginning of instruction/skill files:
-
-- `title` / `name`: The title of the document
-- `description`: A brief description of the document content
-- `applyTo`: (for instruction files) Glob pattern for which files the instructions apply to
-
-## Documentation Review Checklist
-
-Before merging docs, verify:
+- 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