opencastle 0.32.12 → 0.33.0

package/src/orchestrator/skills/project-consistency/TEMPLATES.md

@@ -0,0 +1,39 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Prompt Templates — Foundation & Page Tasks
+
+### Foundation Setup — Prompt (copy-paste)
+
+````markdown
+## Foundation Setup — [project description]
+
+**Aesthetic:** [2-3 word direction] — [one sentence]
+
+Create `[path]/tokens.css`: palette (intent-named), fluid typography (clamp()), spacing (4px base), motion, shadows, radius, breakpoints.
+Create `[path]/Layout.[tsx|astro|vue]`: responsive container, site header (nav: [labels]), footer, document head.
+Create `[path]/ui/`: Button, Card, Heading, Text, Link, Section, Container, Grid — tokens only, zero hardcoded values; `variant`/`size`/`className` API.
+
+**Style Guide:** Tone: [formal/casual]. Terminology: [key terms]. Page structure: [hero → ... → CTA].
+
+**Acceptance Criteria:** Zero hardcoded hex/px · Layout responsive at 320/768/1280px · Fluid typography via clamp() · Fonts loaded efficiently
+````
+
+### Page Task — Prompt (copy-paste)
+
+````markdown
+## Build [Page Name] Page — [purpose, audience, primary action]
+
+**MANDATORY refs:** tokens: `[path]/tokens.css` (no new values) · Layout: `[path]/Layout.[ext]` (wrap all content) · UI: `[path]/ui/` (import, don't recreate) · Aesthetic: [2-3 words] · Tone: [tone] · Terms: [glossary]
+
+**Content:** [sections, copy direction, media]  **Structure:** [hero → ... → CTA]
+
+**Acceptance Criteria:** Shared Layout used · Zero hardcoded values · UI components imported · Tone/terminology match · Responsive 320/768/1280px · [page-specific]
+````
+
+### How to use
+
+- Copy the appropriate template into the foundation or page task tracker issue.
+- Replace bracketed placeholders (`[path]`, `[Aesthetic]`) with exact values from the foundation task outputs.
+- Attach paths to tokens, Layout, and UI component library explicitly in the prompt.
+
+Last Updated: 2026-03-31

package/src/orchestrator/skills/react-development/REFERENCE.md

@@ -0,0 +1,7 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Reference materials for React development guidance.
+
+- See `src/orchestrator/skills/react-development/SKILL.md` for concise rules and quick examples.
+
+Examples, deep-dive topics, and extended patterns (performance, forms, advanced typing) live here when needed.

package/src/orchestrator/skills/react-development/SKILL.md

@@ -1,71 +1,79 @@
 ---
 name: react-development
-description: "React development standards for functional components, hooks, TypeScript integration, state management, styling, and testing patterns. Use when creating or modifying React components, custom hooks, or component tests."
+description: "Enforces naming conventions, prop typing patterns, file structure, and test coverage standards. Use when creating or modifying React components, custom hooks, or component tests. Trigger terms: React app, .tsx files, testing library, custom hooks, functional components"
 ---
 
 # React Development Standards
 
-Modern React patterns — https://react.dev.
+<!-- Concrete actions moved into description and workflows; trigger terms are in frontmatter -->
 
-## Architecture & Components
+## New Component Workflow
 
-- Functional components + hooks; composition over inheritance.
-- Feature/domain folders; separate presentational and container components.
-- PascalCase names; single responsibility; destructure props; never mutate props/state.
-- `<>...</>` to avoid extra DOM nodes; props validated via TypeScript.
+1. **Create file** — `ComponentName.tsx` in the feature folder; co-locate `ComponentName.module.scss` and `ComponentName.test.tsx`
+2. **Define interface** — export `ComponentNameProps` with TypeScript; destructure in function signature
+3. **Implement** — functional component with hooks; use CSS Modules for styling
+4. **Test** — RTL behavioral tests; cover render, interaction, edge cases, accessibility
+5. **Verify** — lint + type-check + test pass; visually confirm in browser if UI
 
-## TypeScript
+## Architecture & Components (concise)
 
-- Interfaces for props, state, event handlers, refs, and API responses.
-- Generic components where appropriate; union types for variants.
-- Built-ins: `React.FC`, `React.ComponentProps`, etc.
-- Strict mode in `tsconfig.json`; shared types in `interfaces/`.
+- Functional components with hooks. Follow domain/feature folder structure and co-locate tests/styles with components.
+- PascalCase names; destructure props; use TypeScript interfaces for props.
 
-## State & Hooks
+```tsx
+interface UserCardProps { name: string; role: string }
+export function UserCard({ name, role }: UserCardProps) {
+  return (
+    <div data-testid="user-card">
+      <h3>{name}</h3>
+      <span>{role}</span>
+    </div>
+  );
+}
+```
 
-| Concern | Tool |
-|---------|------|
-| Local state | `useState` |
-| Complex state | `useReducer` |
-| Cross-tree state | `useContext` |
-| Server state | React Query |
-| DOM / mutable ref | `useRef` |
-| Perf optimization | `useMemo` / `useCallback` |
+## TypeScript
 
-- `useEffect`: proper deps, cleanup to prevent leaks.
-- Hooks only at top level; extract reusable logic to custom hooks.
+- Use interfaces for props and shared types; keep strict mode enabled in `tsconfig.json`. See [REFERENCE.md](REFERENCE.md) for detailed TypeScript patterns.
 
 ## Styling
 
 - **CSS Modules** (`.module.scss`) co-located with components.
 - Sass for advanced features; variables/mixins from shared libraries.
-- Mobile-first responsive; CSS custom properties for theming.
+- CSS custom properties for theming.
 
-## Performance
+<!-- Performance guidance trimmed; follow project-specific conventions and benchmark when needed. -->
 
-- Stable `key` props; `React.memo` where warranted.
-- Code-split with `React.lazy` + `Suspense`; dynamic imports.
-- Avoid anonymous functions in render; virtual scrolling for large lists.
-- `ErrorBoundary` for graceful degradation.
+## Testing
 
-## Data Fetching
+- React Testing Library (behavior, not implementation); Jest runner.
+- Co-locate tests next to components; mock external deps and API calls.
+- Test accessibility and keyboard navigation; verify component public surface via unit tests.
 
-- Libraries: React Query, SWR, or Apollo Client.
-- Always handle loading/error/success; cancel on unmount; optimistic updates.
+```tsx
+import { render, screen } from '@testing-library/react';
+import { UserCard } from './UserCard';
 
-## Forms
+test('renders user info', () => {
+  render(<UserCard name="Alice" role="Admin" />);
+  expect(screen.getByText('Alice')).toBeInTheDocument();
+  expect(screen.getByTestId('user-card')).toBeInTheDocument();
+});
+```
 
-- Controlled components; React Hook Form + Zod for validation.
-- Accessibility: labels, ARIA attributes; debounced validation.
+## Verification commands + error recovery
 
-## Testing
+Run these as part of your PR validation pipeline or locally:
 
-- React Testing Library (behavior, not implementation); Jest runner.
-- Co-locate tests in `__tests__`; mock external deps and API calls.
-- Test accessibility and keyboard navigation.
-- **CRITICAL**: Never mix static imports and `require()` for lazy-loaded libs in tests — use `jest.requireMock()` / `jest.requireActual()`.
+```bash
+pnpm lint        # fixable issues: pnpm lint --fix
+pnpm typecheck   # run `pnpm tsc --noEmit` if alias not present
+pnpm test        # rerun failing tests with `pnpm test -- -t <name>`
+pnpm build       # ensure production build succeeds
+```
+
+If `lint` fails: run `pnpm lint --fix` and re-run. If `typecheck` fails: inspect reported files; add missing types. If tests fail: run with `--runInBand` to collect stack traces and reproduce locally.
 
 ## Security
 
-- Sanitize inputs (XSS); validate/escape before rendering.
-- HTTPS for external APIs; no sensitive data in localStorage/sessionStorage; CSP headers.
+- Follow project conventions for input sanitization, secret handling, and CSP. See **api-patterns** for validation patterns.

package/src/orchestrator/skills/security-hardening/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-hardening
-description: "Security architecture including authentication, authorization, RLS policies, security headers, CSP, input validation, API security, and OAuth patterns. Use when implementing auth flows, writing RLS policies, configuring security headers, validating inputs, or auditing security."
+description: "Security architecture including authentication, authorization, RLS policies, CSP, input validation, and API security. Use when implementing auth flows, writing RLS policies, configuring CSP/headers, validating inputs, or auditing security. Trigger terms: RLS, CSP, Server Actions, Zod, auth flow"
 ---
 
 # Security Hardening
@@ -43,6 +43,39 @@ Principle of least privilege. External domains are project-specific (see deploym
 
 **Note:** `'unsafe-inline'`/`'unsafe-eval'` may be required in dev mode — use nonces/hashes in production.
 
+**Examples** — Next.js `next.config.js` headers and middleware pattern:
+
+```js
+// next.config.js
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/(.*)',
+        headers: [
+          {
+            key: 'Content-Security-Policy',
+            // minimal example; restrict further per app needs
+            value: "default-src 'self'; script-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https://api.example.com;",
+          },
+        ],
+      },
+    ];
+  },
+};
+```
+
+```js
+// middleware.js (Next.js Edge middleware example)
+import { NextResponse } from 'next/server';
+
+export function middleware(request) {
+  const res = NextResponse.next();
+  res.headers.set('Content-Security-Policy', "default-src 'self'; img-src 'self' data:;");
+  return res;
+}
+```
+
 ## RLS
 
 > **SQL examples and role system:** See the **database** skill (authoritative source for RLS).
@@ -51,6 +84,51 @@ Principle of least privilege. External domains are project-specific (see deploym
 - Use `auth.uid()` for auth checks; EXISTS subqueries for role checks
 - Never rely solely on client-side authorization; never disable RLS in production
 
+**RLS verification & test pattern**
+
+1. Confirm RLS is enabled for a table (Postgres):
+
+```sql
+-- run in psql
+SELECT relname, relrowsecurity
+FROM pg_class
+WHERE relname = 'your_table_name';
+```
+
+`relrowsecurity = true` indicates RLS enabled.
+
+2. Test pattern: verify a user without privileges cannot read rows.
+
+```sql
+-- As owner (create test row)
+INSERT INTO your_table_name (id, owner_id, data) VALUES (1, 'owner-uid', 'secret');
+
+-- As another_role (should return zero rows if RLS correct)
+SET ROLE other_role;
+SELECT * FROM your_table_name WHERE id = 1;
+-- expected: 0 rows
+```
+
+Automate this check in CI: run the enabling query and a simple positive/negative test as part of the security gate.
+
+## Server Action Zod example
+
+```ts
+'use server';
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const schema = z.object({ name: z.string().min(1), price: z.number().positive() });
+
+export async function createItem(formData: FormData) {
+  const parsed = schema.safeParse(Object.fromEntries(formData.entries()));
+  if (!parsed.success) return { error: 'Validation failed', details: parsed.error.format() };
+  // insert into DB ...
+  revalidatePath('/items');
+  return { success: true };
+}
+```
+
 ## API Security
 
 ```typescript
@@ -74,3 +152,12 @@ Input: Zod schemas in all Server Actions and route handlers; React Hook Form cli
 5. Sanitize user content (escape HTML).
 6. Parameterized queries (DB client handles automatically).
 7. Rotate secrets quarterly.
+
+## Implementation checklist
+1. Enable RLS on tables and add an automated enablement check in CI (example: `SELECT relrowsecurity FROM pg_class WHERE relname = 'your_table'`).
+2. Configure authentication and session middleware; verify via an integration smoke test against a protected endpoint (e.g., `/api/me`).
+3. Add CSP and security headers in `next.config.js` or middleware; validate headers with `curl -I` against a preview URL.
+4. Add Zod validation to all Server Actions and route handlers (see Zod example above).
+5. Run a security audit (RLS positive/negative tests, header validation, and input fuzzing) and block merges on failing gates.
+
+Cross-reference: see [api-patterns/SKILL.md](../api-patterns/SKILL.md#architecture) for Server Action patterns and [session-checkpoints/SKILL.md](../session-checkpoints/SKILL.md) for checkpointing security-sensitive work.

package/src/orchestrator/skills/self-improvement/LESSON-CATEGORIES.md

@@ -0,0 +1,36 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Lesson Categories & Severity
+
+Use these tables when tagging lessons in `LESSONS-LEARNED.md`.
+
+## Categories
+
+| Category | When to use |
+|----------|------------|
+| `bug` | Runtime errors, incorrect behavior, regressions |
+| `pattern` | Reusable code or workflow pattern discovered |
+| `architecture` | Structural decisions, module boundaries, data flow |
+| `tooling` | Build tools, CLI, IDE, MCP, CI/CD issues |
+| `testing` | Test strategy, flaky tests, coverage gaps |
+| `security` | Auth, RLS, headers, secrets, input validation |
+| `performance` | Rendering, bundle size, query optimization |
+| `deployment` | Hosting, env vars, caching, rollback |
+| `process` | Workflow, delegation, review, orchestration |
+| `documentation` | Docs structure, templates, stale content |
+
+## Severity
+
+| Severity | Criteria |
+|----------|---------|
+| `critical` | Blocks all work or causes data loss |
+| `high` | Blocks a task or causes significant rework |
+| `medium` | Causes friction or minor rework |
+| `low` | Nice-to-know; minor efficiency improvement |
+
+## Tagging Format
+
+```
+### LES-XXX: <title>
+**Category:** <category> | **Severity:** <severity> | **Date:** YYYY-MM-DD
+```

package/src/orchestrator/skills/self-improvement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: self-improvement
-description: "Protocol for reading and updating the lessons-learned knowledge base. MUST be followed by ALL agents — read lessons before work, write lessons after retries. This makes the agent team self-improving across sessions."
+description: "Appends new entries to LESSONS-LEARNED.md via the opencastle lesson CLI, searches past lessons for matching errors, and proposes skill updates when retry patterns exceed thresholds. Use when consulting or updating LESSONS-LEARNED.md, after task failures, when capturing retrospective insights, or when a retry succeeds."
 ---
 
 # Self-Improvement Protocol
@@ -23,30 +23,24 @@ Required: `--title`, `--category`, `--severity`, `--problem` · Optional: `--wro
 
 After writing: if the lesson reveals a gap in a skill/instruction file, update that file too (prevents the pitfall at source).
 
-## Categories
-
-| Category | Covers |
-|----------|--------|
-| `task-management` | Task tracker tools, issue management, workflow states |
-| `jira` | Jira MCP tools (Atlassian Rovo) |
-| `mcp-tools` | MCP server tool quirks (deferred loading, parameters) |
-| `codebase-tool` | Task runner CLI commands, caching, build tools |
-| `terminal` | Shell commands, port/process management |
-| `framework` | App framework, build, dev server, SSR |
-| `cms` | CMS content queries, schema deployment |
-| `database` | Database auth, migrations, RLS, SQL |
-| `git` | Git operations, branching, merge conflicts |
-| `deployment` | Deployment, environment variables, edge config |
-| `browser-testing` | E2E testing, screenshots, browser automation |
-| `general` | Anything else |
-
-## Severity
-
-| Level | Impact |
-|-------|--------|
-| `high` | Blocks work — agent cannot proceed without the workaround |
-| `medium` | Wastes 5+ minutes |
-| `low` | Minor friction |
+## Workflow
+
+1. Search LESSONS-LEARNED.md for matching entries or similar errors.
+2. Attempt the task with conservative flags/options informed by lessons.
+3. On failure: retry with modified approach (up to threshold), capture error details and context.
+4. On success: run `opencastle lesson` to record the working approach.
+5. Verify: `tail -1 .opencastle/LESSONS-LEARNED.md` — confirm entry has title, category, and severity. If malformed → re-run with corrected flags.
+6. If the lesson indicates a needed skill/instruction update: draft that change and propose a PR.
+
+Quick search example:
+
+```bash
+rg "missing CRON_SECRET" .opencastle/LESSONS-LEARNED.md || true
+```
+
+## Categories & Severity
+
+Category and severity tables moved to [LESSON-CATEGORIES.md](LESSON-CATEGORIES.md). Use that file when tagging lessons.
 
 ## Quality Rules
 

package/src/orchestrator/skills/seo-patterns/REFERENCE.md

@@ -0,0 +1,54 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# SEO Reference: Structured Data & Anti-Patterns
+
+## Structured Data Examples (JSON-LD)
+
+### Breadcrumb + Article example
+
+```tsx
+function StructuredData({ breadcrumbs, article }: Props) {
+  const breadcrumbLd = {
+    '@context': 'https://schema.org', '@type': 'BreadcrumbList',
+    itemListElement: breadcrumbs.map((crumb, i) => ({ '@type': 'ListItem', position: i + 1, name: crumb.label, item: crumb.url })),
+  };
+  const articleLd = {
+    '@context': 'https://schema.org', '@type': 'Article',
+    headline: article.title, description: article.summary,
+    image: article.imageUrl, datePublished: article.publishedAt,
+    dateModified: article.updatedAt, author: { '@type': 'Person', name: article.author },
+  };
+  return (
+    <>
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbLd) }} />
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(articleLd) }} />
+    </>
+  );
+}
+```
+
+### FAQPage example (minimal)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    { "@type": "Question", "name": "Q?", "acceptedAnswer": { "@type": "Answer", "text": "A." } }
+  ]
+}
+```
+
+## Validation
+
+- Validate with Google's Rich Results Test: https://search.google.com/test/rich-results
+- CLI quick-check: `curl -s https://example.com/page | pup 'script[type=application/ld+json] text{}'` then `jq .`
+
+## Anti-Patterns (trimmed)
+
+- Duplicate titles across pages — produce unique, descriptive titles.
+- Missing canonical URLs — add `<link rel="canonical">` to avoid duplicate content.
+- Client-only rendered primary content — server-render or prerender indexable content.
+- Unvalidated structured data — validate before merge and include tests in PRs.
+
+Last Updated: 2026-03-31

package/src/orchestrator/skills/seo-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: seo-patterns
-description: "Technical SEO patterns for meta tags, structured data, sitemaps, URL strategy, and rendering. Use when optimizing pages for search engines or implementing SEO features."
+description: "Implements technical SEO: meta tags, JSON-LD structured data, sitemaps, and crawlability fixes. Use when adding schema markup, JSON-LD, robots.txt updates, canonical URLs, Open Graph tags, or improving crawlability."
 ---
 
 # SEO Patterns
@@ -9,8 +9,20 @@ description: "Technical SEO patterns for meta tags, structured data, sitemaps, U
 
 - Every public page MUST have a unique `<title>` and `<meta name="description">`.
 - Structured data MUST validate against Google's Rich Results Test before shipping.
-- Server-render all content critical for indexing — never rely on client-side JS for primary content.
-- Canonical URLs are mandatory on every page to prevent duplicate content issues.
+- Server-render all content critical for indexing.
+- Canonical URLs are mandatory on every page.
+
+## Implementation Workflow
+
+1. Add meta tags and canonical URLs in server-rendered HTML.
+  - Checkpoint: every page has unique `<title>` and `<meta name="description">`.
+2. Add structured data (JSON-LD) for the page type and keep blocks server-rendered.
+  - Checkpoint: Rich Results Test passes with zero errors.
+3. Generate / update sitemap and reference it from `robots.txt`.
+  - Checkpoint: sitemap URL present in `robots.txt` and accessible.
+4. Verify robots.txt rules and ensure public pages are allowed.
+  - Recovery: remove accidental `Disallow:` entries and re-submit sitemap.
+5. Monitor Search Console for warnings and enhancement reports post-deploy.
 
 ## Meta Tags & Open Graph
 
@@ -33,45 +45,8 @@ export const metadata: Metadata = {
 
 **Checklist:** unique title (50-60 chars) · unique description (150-160 chars) · canonical URL · `og:title/description/image` (1200×630 px) · `og:type` · `twitter:card/title/image` · `noindex` only on admin/draft pages.
 
-## Structured Data (JSON-LD)
-
-Use JSON-LD `<script>` blocks — never microdata or RDFa.
-
-| Page Type | Schema Type(s) | Required Properties |
-|-----------|----------------|---------------------|
-| Homepage | `WebSite`, `Organization` | `name`, `url`, `searchAction`, `logo` |
-| Detail page | `Product`, `Article`, or domain type | `name`, `description`, `image` |
-| Listing page | `ItemList` + `ListItem` | `itemListElement`, `position`, `url` |
-| Breadcrumbs | `BreadcrumbList` | `itemListElement`, `position`, `name` |
-| Blog post | `Article` / `BlogPosting` | `headline`, `datePublished`, `author` |
-| FAQ page | `FAQPage` | `mainEntity` with `Question` + `Answer` |
-
-### Example: Breadcrumb + Article
-
-```tsx
-function StructuredData({ breadcrumbs, article }: Props) {
-  const breadcrumbLd = {
-    '@context': 'https://schema.org', '@type': 'BreadcrumbList',
-    itemListElement: breadcrumbs.map((crumb, i) => ({ '@type': 'ListItem', position: i + 1, name: crumb.label, item: crumb.url })),
-  };
-  const articleLd = {
-    '@context': 'https://schema.org', '@type': 'Article',
-    headline: article.title, description: article.summary,
-    image: article.imageUrl, datePublished: article.publishedAt,
-    dateModified: article.updatedAt, author: { '@type': 'Person', name: article.author },
-  };
-  return (
-    <>
-      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbLd) }} />
-      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(articleLd) }} />
-    </>
-  );
-}
-```
-
-Validate every block via [Google's Rich Results Test](https://search.google.com/test/rich-results) before merging. Check Search Console **Enhancements** after deployment.
-
-## Sitemap & Crawlability
+## Structured Data & Crawlability
+For structured data reference examples and detailed anti-patterns see [REFERENCE.md](./REFERENCE.md).
 
 - Generate XML sitemap dynamically from your data source (CMS, DB, filesystem).
 - Use a **sitemap index** when >50,000 URLs or >50 MB.
@@ -86,50 +61,7 @@ Disallow: /preview/
 Sitemap: https://example.com/sitemap.xml
 ```
 
-**Checklist:** robots.txt allows all public pages · blocks admin/API/preview · XML sitemap auto-generated and current · referenced in robots.txt · no orphan pages · page load < 3s.
-
-## URL Strategy
-
-| Pattern | Good | Bad |
-|---------|------|-----|
-| Slug format | `/products/blue-widget` | `/products/Blue_Widget` |
-| Hierarchy | `/blog/2026/seo-tips` | `/blog?id=42` |
-| Consistency | Always `/path/` or `/path` | Mixed trailing slashes |
-| Parameters | `/products?sort=price` | `/products/sort/price/asc` |
-
-```ts
-// next.config.ts
-const redirects = [
-  { source: '/old-page', destination: '/new-page', permanent: true },
-  { source: '/blog/:slug/amp', destination: '/blog/:slug', permanent: true },
-];
-```
-
-## Rendering & Indexability
-
-Server-render all indexed content. Use semantic HTML (`<h1>`–`<h6>`, `<article>`, `<nav>`, `<main>`) for crawler structure.
-
-| Image Attribute | Purpose | Example |
-|-----------------|---------|---------|
-| `alt` | Describes for crawlers + screen readers | `alt="Blue widget on white background"` |
-| `loading` | Lazy-load below-fold | `loading="lazy"` |
-| `width` / `height` | Prevents CLS | `width={800} height={600}` |
-| File name | Keyword signal | `blue-widget-front.webp` |
-| Format | Performance + quality | WebP/AVIF with JPEG fallback |
-
-**Checklist:** primary content in initial HTML · unique `<h1>` with primary keyword · structured data in SSR HTML · descriptive `alt` on all images · no stray `noindex` · hydration preserves structured data scripts.
-
-## Anti-Patterns
+**Crawlability checklist:** robots.txt allows public pages · blocks admin/API/preview · XML sitemap auto-generated · referenced in robots.txt · no orphan pages · primary content in initial HTML · unique `<h1>` with keyword · structured data in SSR HTML · descriptive `alt` on images · no stray `noindex` · page load < 3s.
 
-| Anti-Pattern | Why It's Bad | Correct Approach |
-|---|---|---|
-| Duplicate `<title>` | Dilutes ranking signals | Unique, keyword-specific title per page |
-| Missing canonical URL | Duplicate content penalties | Add `<link rel="canonical">` to every page |
-| Client-only rendered content | Googlebot may miss JS | Server-render all indexable content |
-| Hardcoded sitemap | Goes stale | Generate sitemap dynamically |
-| `noindex` as "temporary" fix | Often forgotten | Fix the underlying issue |
-| Keyword stuffing in meta tags | Penalized by search engines | Natural, user-focused descriptions |
-| Missing `alt` on images | Lost image traffic + a11y failure | Descriptive alt on every meaningful image |
-| Unvalidated structured data | Silent errors = rich result loss | Validate with Rich Results Test before merge |
-| Blocking CSS/JS in robots.txt | Prevents page rendering | Only block admin/API routes |
-| Mixed trailing slash URLs | Splits link equity | Pick one convention, 301-redirect other |
+## Anti-Patterns & Structured Data Reference
+See `REFERENCE.md` for detailed structured data examples, validation commands, and a trimmed anti-pattern checklist.

package/src/orchestrator/skills/session-checkpoints/CHECKPOINT-TEMPLATE.md

@@ -0,0 +1,58 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Session Checkpoint Template
+
+**Last Updated:** YYYY-MM-DD HH:MM
+**Feature:** Short feature name
+**Branch:** git branch name
+**Tracker Issues:** TAS-XX, TAS-YY
+
+## Current Phase
+
+## Completed Work
+
+| Task | Tracker | Agent | Status | Files |
+|------|---------|-------|--------|-------|
+| Description | TAS-XX | Agent | ✅ Done | file1.ts |
+
+## In Progress
+
+| Task | Tracker | Agent | Status | Notes |
+|------|---------|-------|--------|-------|
+| Description | TAS-ZZ | Agent | 🔄 In Progress | what's done |
+
+## Remaining Work
+
+| Task | Tracker | Agent | Dependencies | Files |
+|------|---------|-------|-------------|-------|
+| Description | TAS-AA | Agent | TAS-ZZ | file4.ts |
+
+## Pending Approvals
+
+| Provider | Channel | Thread ID | Question | Posted At |
+|----------|---------|-----------|----------|-----------|
+| slack | C0AHAQFJ7C1 | 1772393542.345149 | Run migration on production? | 2026-03-01 14:30 |
+
+Remove row once answered (VS Code chat reply also counts as resolved).
+
+## Decisions & Blockers
+
+- Decision: rationale
+- Blocker: what's needed to unblock
+
+## Delegation Cost Log
+
+| # | Agent | Tracker | Model Tier | Est. Tokens | Duration | Status |
+|---|-------|---------|------------|-------------|----------|--------|
+| 1 | Content Engineer | TAS-XX | Standard | ~20K | 8 min | ✅ Done |
+
+## File Partitions
+
+Agent A: dir1/, dir2/
+Agent B: dir3/
+
+## Resume Instructions
+
+1. Check out branch `feat/xxx`
+2. Read tracker issues TAS-XX for context
+3. Start Phase N+1: [specific instructions]