opencastle 0.32.12 → 0.33.0

package/src/orchestrator/skills/orchestration-protocols/REFERENCE.md

@@ -0,0 +1,42 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Agent Health Monitoring
+
+### Health Signals
+
+| Signal | Threshold | Recovery |
+|--------|-----------|----------|
+| **Stuck** — no output/changes | Sub: 5 min / BG: 15 min | Nudge; if frozen, abort + re-delegate with simpler scope |
+| **Looping** — same error repeated | 3 consecutive failures | Abort; add context; re-delegate with explicit fix path |
+| **Scope creep** — files outside partition | Any | Redirect: "Only modify files in [partition]. Revert [file]." |
+| **Context exhaustion** — confused/repetitive | Visible instruction amnesia | Checkpoint, end session, resume in fresh context |
+| **Permission loop** — waiting for input | 2+ prompts without progress | Auto-approve if safe; abort + re-delegate |
+
+**Cadence:** Sub-agents — continuous (real-time). Background agents — check at 10 min, then every 10 min. Always review full diff before accepting.
+
+### Escalation Path
+
+1. **Failure 1:** Re-delegate with more specific prompt + error context
+2. **Failure 2:** Downscope (split into smaller pieces), re-delegate
+3. **Failure 3:** Log to `.opencastle/AGENT-FAILURES.md`; if 3× panel BLOCK or conflict, create dispute in `.opencastle/DISPUTES.md` (see **team-lead-reference** § Dispute Protocol)
+
+## Error Recovery Playbook
+
+| Failure | Symptom | Recovery |
+|---------|---------|----------|
+| **Retry loop** | Same command fails 3+ times | Abort; identify root cause; re-delegate with explicit fix; log lesson |
+| **MCP unavailable** | Tool connection/timeout errors | Check server; retry once; fall back to CLI; log to DLQ if critical |
+| **Broken BG output** | Lint/type/test errors on return | Fix inline if small; discard + re-delegate if fundamental; DLQ after 2 fails |
+| **Parallel merge conflict** | Two agents modified overlapping files | Accept complex side first; re-delegate simple side to adapt; log lesson |
+| **Context exhausted** | Confused/repetitive responses | Checkpoint; end session; resume with checkpoint; reduce parallel work |
+| **Post-merge test failure** | Tests pass alone but fail merged | Run affected tests; check import/state conflicts; delegate fix to likely cause |
+
+## Agent Circuit Breaker
+
+| Threshold | Action |
+|-----------|--------|
+| **2 failures** | Investigate: same error class? Model healthy? Prompt pattern? |
+| **3 failures** | Open circuit — stop delegating; reassign or escalate to user |
+| **Next session** | Half-open — resets; re-open + add lesson if fails again |
+
+Judgment-based, not a hard gate. 3 similar failures with the same error is more concerning than 3 unrelated failures.

package/src/orchestrator/skills/orchestration-protocols/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: orchestration-protocols
-description: "Runtime orchestration patterns for the Team Lead: parallel research spawning, agent health monitoring, active steering, background agent management, Context Compaction, Agent Circuit Breaker, and escalation paths."
+description: "Coordinates multiple agents with parallel task spawning, health monitoring, circuit breakers, and escalation paths. Use when managing parallel agents, handling agent timeouts, orchestrate agents, run tasks in parallel, concurrent agent execution, or fan-out tasks. Use when coordinating multi-agent task delegation."
 ---
 
 # Orchestration Protocols
 
-Runtime patterns for managing delegated agents. **Load at:** Execution phase (Step 4+), when monitoring active agents or spawning parallel work.
+Runtime patterns for managing delegated agents.
 
 ## Active Steering
 
@@ -13,11 +13,11 @@ Intervene early when you spot:
 
 | Signal | Action |
 |--------|--------|
-| Failing tests/builds | Can't resolve dependency or breaks existing code |
-| Unexpected file changes | Files outside partition in diff |
-| Scope creep | Refactors code not in scope |
-| Circular behavior | Same failing approach retried without change |
-| Intent misunderstanding | Session log shows wrong prompt interpretation |
+| Failing tests/builds | Check dependency resolution; revert if builds break |
+| Unexpected file changes | Revert; enforce partition |
+| Scope creep | Redirect to scoped files only |
+| Circular behavior | Halt; switch approach |
+| Intent misunderstanding | Clarify prompt; re-delegate |
 
 When redirecting, explain *why* and *how*:
 
@@ -35,7 +35,7 @@ Run autonomously in isolated Git worktrees. Reserve for well-scoped tasks >5 min
 
 ## Parallel Research Protocol
 
-Spawn multiple research sub-agents in parallel when 3+ independent questions must be answered before implementation. **Use when:** 3+ independent research questions, broad codebase exploration, or multi-area analysis (frontend/backend/CMS). **Skip when:** single-file investigation, answer in one known location, sequential results, or fewer than 3 questions.
+Spawn multiple research sub-agents in parallel when 3+ independent questions must be answered before implementation. **Spawn if:** ≥3 independent questions AND answers span multiple codebase areas — otherwise handle sequentially.
 
 ### Spawn Strategy
 
@@ -56,9 +56,11 @@ Return: key findings, relevant file paths (with line numbers), patterns, unanswe
 ### Result Merge Protocol
 
 1. Collect all results into single context
-2. Deduplicate (same file/pattern counts once)
-3. Resolve conflicts — specific evidence beats general observations
-4. Synthesize into concise context block for implementation prompts
+2. **Checkpoint:** verify every researcher returned a result (no timeout or error); re-run any that failed before proceeding.
+3. Deduplicate (same file/pattern counts once)
+4. Resolve conflicts — specific evidence beats general observations
+5. Synthesize into concise context block for implementation prompts
+6. **Checkpoint:** confirm synthesized block covers every original question; mark any unanswered questions as blockers.
 
 ## Batch Reviews
 
@@ -80,43 +82,54 @@ Summarize prior phase output before passing to the next agent. **Extract:** file
 - Blockers: [none | list]
 ```
 
-## Agent Health Monitoring
+**Concrete example:**
+```
+### Prior Phase Output
+**Phase 2 — Researcher A — Find usages of `calculateTotal()`**
+- Files changed: none (read-only research)
+- Decisions: `calculateTotal` lives in `libs/cart/src/lib/total.ts`; new logic should live in `libs/cart/src/lib/discounts.ts`
+- Verification: lint ✅ | types ✅ | unit smoke test (cart total) ✅
+- Blockers: design question on rounding behavior (see `docs/rounding.md`)
+```
+
+## Health & Recovery Reference
 
-### Health Signals
+Detailed Agent Health Monitoring, Error Recovery Playbook, and Agent Circuit Breaker tables have been moved to REFERENCE.md to keep this skill concise. See REFERENCE.md in this directory for thresholds, recovery steps, and escalation flows.
 
-| Signal | Threshold | Recovery |
-|--------|-----------|----------|
-| **Stuck** — no output/changes | Sub: 5 min / BG: 15 min | Nudge; if frozen, abort + re-delegate with simpler scope |
-| **Looping** — same error repeated | 3 consecutive failures | Abort; add context; re-delegate with explicit fix path |
-| **Scope creep** — files outside partition | Any | Redirect: "Only modify files in [partition]. Revert [file]." |
-| **Context exhaustion** — confused/repetitive | Visible instruction amnesia | Checkpoint, end session, resume in fresh context |
-| **Permission loop** — waiting for input | 2+ prompts without progress | Auto-approve if safe; abort + re-delegate |
 
-**Cadence:** Sub-agents — continuous (real-time). Background agents — check at 10 min, then every 10 min. Always review full diff before accepting.
+### CLI examples (spawn & monitor)
 
-### Escalation Path
+These use the OpenCastle CLI (`npx opencastle` or `bin/cli.mjs`):
 
-1. **Failure 1:** Re-delegate with more specific prompt + error context
-2. **Failure 2:** Downscope (split into smaller pieces), re-delegate
-3. **Failure 3:** Log to `.opencastle/AGENT-FAILURES.md`; if 3× panel BLOCK or conflict, create dispute in `.opencastle/DISPUTES.md` (see **team-lead-reference** § Dispute Protocol)
+```bash
+opencastle run --file convoy.yml --dry-run
+opencastle run --file convoy.yml --verbose
+opencastle run --resume
+opencastle run --status
+opencastle run --retry-failed
+```
+
+**Post-run verification (copy-paste checks):**
 
-## Error Recovery Playbook
+```bash
+if [ $? -ne 0 ]; then
+  echo "opencastle run failed — inspect .opencastle/convoy.log" \
+	 && tail -n 200 .opencastle/convoy.log && exit 1
+fi
 
-| Failure | Symptom | Recovery |
-|---------|---------|----------|
-| **Retry loop** | Same command fails 3+ times | Abort; identify root cause; re-delegate with explicit fix; log lesson |
-| **MCP unavailable** | Tool connection/timeout errors | Check server; retry once; fall back to CLI; log to DLQ if critical |
-| **Broken BG output** | Lint/type/test errors on return | Fix inline if small; discard + re-delegate if fundamental; DLQ after 2 fails |
-| **Parallel merge conflict** | Two agents modified overlapping files | Accept complex side first; re-delegate simple side to adapt; log lesson |
-| **Context exhausted** | Confused/repetitive responses | Checkpoint; end session; resume with checkpoint; reduce parallel work |
-| **Post-merge test failure** | Tests pass alone but fail merged | Run affected tests; check import/state conflicts; delegate fix to likely cause |
+npx opencastle run --status
+
+grep -i "error\|failed" .opencastle/convoy.log || echo "no obvious errors in logs"
+```
 
-## Agent Circuit Breaker
+## Validation & Verification Checkpoints
 
-| Threshold | Action |
-|-----------|--------|
-| **2 failures** | Investigate: same error class? Model healthy? Prompt pattern? |
-| **3 failures** | Open circuit — stop delegating; reassign or escalate to user |
-| **Next session** | Half-open — resets; re-open + add lesson if fails again |
+| Phase | Check | Command / Action |
+|-------|-------|-----------------|
+| Pre-spawn | Inputs present (task, scope, ACs) | `test -s convoy.yml \|\| exit 1` |
+| During-run | Tail for fatal errors | `tail -F .opencastle/convoy.log \| grep -i "fatal\|error"` |
+| Pre-merge | All agents exited 0 | `jq -e '.agents[] \| .exit_code == 0' .opencastle/results.json` |
+| Output schema | Required fields present | `jq -e '.agents[] \| (.findings and .file_paths)' .opencastle/results.json` |
+| Post-merge | Lint + smoke tests pass | `npm run lint && npm test -- -t "smoke"` |
+| Blocker | Any failure | Block merge; reopen to original researcher(s) |
 
-Judgment-based, not a hard gate. 3 similar failures with the same error is more concerning than 3 unrelated failures.

package/src/orchestrator/skills/panel-majority-vote/REFERENCE.md

@@ -0,0 +1,55 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Panel — Weighted Consensus Variant (Reference)
+
+Use this reference when a simple head-count majority is insufficient and domain expertise must influence the verdict.
+
+### When to Use
+
+| Decision Type | Mode |
+|--------------|------|
+| Security vulnerability, code correctness | Simple majority |
+| UI/UX, architecture tradeoffs, data model, naming | Weighted |
+
+### Weight Assignment
+
+Base weight: 1. Add bonuses:
+
+| Factor | Bonus |
+|--------|-------|
+| Domain expertise (relevant to review) | +2 |
+| Confidence high / med / low | +1 / 0 / -1 |
+| Prior success rate >80% (AGENT-PERFORMANCE.md) | +1 |
+
+Example: Security Expert + high = 4; Architect + med = 2.
+
+### Voting Protocol
+
+1. Assign weights before spawning.
+2. Spawn with same prompt; collect PASS/BLOCK + confidence.
+3. Score: sum weights by verdict; PASS if PASS score > BLOCK score.
+4. Tie: highest individual weight breaks tie; if equal, default BLOCK.
+
+### Conflict Resolution
+
+| Scenario | Outcome |
+|----------|---------|
+| Low-weight BLOCKs, high-weight PASSes | PASS; move BLOCK's MUST-FIX → SHOULD-FIX |
+| Domain expert BLOCKs, generalists PASS | BLOCK |
+| All equal weight | Simple majority (2/3 wins) |
+
+### Report Extension (template)
+
+```markdown
+### Weighting
+| Reviewer | Role | Domain | Confidence | Prior Success | Final Weight |
+|----------|------|--------|------------|---------------|-------------|
+| 1 | [Agent] | +X | +X | +X | X |
+
+### Weighted Score
+- PASS: X (reviewers: ...)
+- BLOCK: X (reviewers: ...)
+- **Overall: PASS/BLOCK** (weighted)
+```
+
+Last Updated: 2026-03-31

package/src/orchestrator/skills/panel-majority-vote/SKILL.md

@@ -1,20 +1,10 @@
 ---
 name: panel-majority-vote
-description: "Run 3 isolated reviewer sub-agents against the same question and decide PASS/BLOCK by majority vote (2/3 wins). Use when deterministic verification is insufficient."
+description: "Runs 3 isolated reviewer sub-agents and consolidates a PASS/BLOCK verdict by majority. Use when the user requests an independent review of code changes, pull requests, design documents, or release notes."
 ---
 
 # Skill: Panel majority vote
 
-## Contract
-
-| Rule | Detail |
-|------|--------|
-| Scope | One run root, one panel key |
-| Artifacts | Reviewers use only declared in-scope artifacts |
-| Runners | Exactly 3 isolated reviewer runs |
-| Verdict | Majority (2/3 wins) |
-| On BLOCK | Consolidated report must include retry summary |
-
 ## Inputs / Outputs
 
 **Inputs:** `<runRoot>`, `<panelKey>` (filesystem-safe), question text, artifact list. Panel dir default: `<runRoot>/panel/`.
@@ -25,84 +15,49 @@ description: "Run 3 isolated reviewer sub-agents against the same question and d
 | Raw reviewer outputs | `<panelDir>/<panelKey>-reviewer-outputs.md` |
 | Consolidated report | `<panelDir>/<panelKey>.md` |
 
-## Procedure
-
-1. **Validate scope** — every artifact path is under `<runRoot>`; list is sufficient to answer the question.
-2. **Spawn 3 reviewers in parallel** — identical prompt to 3 isolated subagents. Optionally write payload to `<panelDir>/<panelKey>-panel-prompt.md`. Required output sections (no others): `VERDICT: PASS | BLOCK`, `MUST-FIX:`, `SHOULD-FIX:`, `QUESTIONS:`, `TEST IDEAS:`, `CONFIDENCE: low | med | high`.
-3. **Persist outputs** — write `<panelDir>/<panelKey>-reviewer-outputs.md` with header (run root, panel key, question, artifacts) and each reviewer output verbatim, separated.
-4. **Consolidate** — count PASS/BLOCK; overall PASS if ≥ 2. Deduplicate MUST-FIX/SHOULD-FIX with reviewer counts. Record disagreements. Include determinize-next recs. If BLOCK, add retry summary.
-5. **Write report** — create `<panelDir>/<panelKey>.md` using `panel-report.template.md`.
-6. **Print summary** — overall verdict + vote tally + report path.
-7. **Log (⛔ hard gate)** — use **observability-logging** skill panel command. Fields: `panel_key`, `verdict`, `pass_count`, `block_count`, `must_fix`, `should_fix`, `reviewer_model`, `weighted`, `attempt`, `tracker_issue`, `artifacts_count`, `report_path`. Link report as verification evidence.
-
-## Notes
-
-- On BLOCK: change the underlying work and re-run; do not re-word the question.
-- After 3 consecutive BLOCKs on the same panel key: create a dispute record per **team-lead-reference** § Dispute Protocol.
 
-## Model Selection
+## Procedure
 
-| Domain | Model |
-|--------|-------|
-| Security, architecture, complex logic | Quality (Claude Sonnet 4.6) × 3 |
-| Feature implementation, UI, queries | Standard (Gemini 3.1 Pro) × 3 |
-| Mixed-domain | Quality × 1, Standard × 2 |
+1. **Validate scope** — every artifact path is under `<runRoot>` and the list is sufficient to answer the question.
 
-Use same model for all 3 reviewers.
+2. **Spawn 3 reviewers in parallel** — start three isolated subagents with identical prompts. Spawn 3 reviewers using `runSubagent` with identical prompts; each reviewer receives the same question, artifact list, and constraints but runs in isolation. Required reviewer output sections (no others): `VERDICT: PASS | BLOCK`, `MUST-FIX:`, `SHOULD-FIX:`, `QUESTIONS:`, `TEST IDEAS:`, `CONFIDENCE: low | med | high`.
 
-## Weighted Consensus Variant
+3. **Persist outputs** — write `<panelDir>/<panelKey>-reviewer-outputs.md` with a header (run root, panel key, question, artifacts) and each reviewer output verbatim, separated.
 
-For subjective decisions where domain expertise should weight more than head-count.
+4. **Consolidate** — parse each reviewer output for its `VERDICT:` line and count PASS votes. Overall verdict = PASS if pass_count ≥ 2; otherwise BLOCK. Deduplicate `MUST-FIX:` and `SHOULD-FIX:` items and annotate each item with `(N/3 reviewers)`.
 
-### When to Use
+```bash
+# count PASS/BLOCK from combined outputs
+pass_count=$(grep -o "VERDICT: PASS" panel/run123-reviewer-outputs.md | wc -l)
+block_count=$(grep -o "VERDICT: BLOCK" panel/run123-reviewer-outputs.md | wc -l)
+verdict=$([ "$pass_count" -ge 2 ] && echo PASS || echo BLOCK)
 
-| Decision Type | Mode |
-|--------------|------|
-| Security vulnerability, code correctness | Simple majority |
-| UI/UX, architecture tradeoffs, data model, naming | Weighted |
+# emit a minimal JSON summary using jq (install jq if needed)
+jq -n --arg panel_key "run123-panel" --arg verdict "$verdict" --argjson pass_count $pass_count --argjson block_count $block_count '{panel_key:$panel_key, verdict:$verdict, pass_count:$pass_count, block_count:$block_count}' > panel/run123-summary.json
+```
 
-### Weight Assignment
+5. **Write report** — create `<panelDir>/<panelKey>.md` with the minimal structure below and reference the generated summary.
 
-Base weight: 1. Add bonuses:
+- Title: Panel `<panelKey>` — Verdict: `PASS | BLOCK` (pass_count/block_count)
+- Highlights: top deduplicated `MUST-FIX` and `SHOULD-FIX` items
+- Evidence: paths to reviewer outputs and `panel/run123-summary.json`
 
-| Factor | Bonus |
-|--------|-------|
-| Domain expertise (relevant to review) | +2 |
-| Confidence high / med / low | +1 / 0 / -1 |
-| Prior success rate >80% (AGENT-PERFORMANCE.md) | +1 |
+6. **Print summary** — overall verdict + vote tally + report path.
 
-Example: Security Expert + high = **4**; Architect + med = **2**.
+7. **Log (⛔ hard gate)** — call the **observability-logging** skill with `panel_key`, `verdict`, `pass_count`, `block_count`, `must_fix`, `should_fix`, `reviewer_model`, `weighted`, `attempt`, `tracker_issue`, `artifacts_count`, `report_path` for verification.
 
-### Voting Protocol
+## Notes
 
-1. Assign weights before spawning.
-2. Spawn with same prompt; collect PASS/BLOCK + confidence.
-3. Score: sum weights by verdict; PASS if PASS score > BLOCK score.
-4. Tie: highest individual weight breaks tie; if equal, default BLOCK.
+- On BLOCK: change the underlying work and re-run; do not re-word the question.
+- After 3 consecutive BLOCKs on the same panel key: create a dispute record per **team-lead-reference** § Dispute Protocol.
+- Model selection: use the same model for all 3 reviewers. See **team-lead-reference** for model routing.
 
-### Conflict Resolution
+## Related Resources
 
-| Scenario | Outcome |
+| Resource | Purpose |
 |----------|---------|
-| Low-weight BLOCKs, high-weight PASSes | PASS; move BLOCK's MUST-FIX → SHOULD-FIX |
-| Domain expert BLOCKs, generalists PASS | BLOCK |
-| All equal weight | Simple majority (2/3 wins) |
-
-### Report Extension
-
-```markdown
-### Weighting
-| Reviewer | Role | Domain | Confidence | Prior Success | Final Weight |
-|----------|------|--------|------------|---------------|-------------|
-| 1 | [Agent] | +X | +X | +X | X |
-
-### Weighted Score
-- PASS: X (reviewers: 1, 3)
-- BLOCK: X (reviewer: 2)
-- **Overall: PASS/BLOCK** (weighted)
-```
-
-### Integration
-
-Same steps 1–7 as standard panel. Differences: assign weights in step 2; use weighted calculation in step 4; add weighting table to report. Team Lead decides simple vs. weighted; include rationale in delegation prompt.
+| `panel-report.template.md` | Report template for step 5 |
+| `REFERENCE.md` | Weighted consensus variant and weighting details |
+| **observability-logging** skill | Panel logging command (step 7) |
+| **team-lead-reference** skill | Model routing and dispute protocol |
 

package/src/orchestrator/skills/performance-optimization/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: performance-optimization
-description: "Frontend and backend performance optimization patterns including rendering, asset optimization, JavaScript performance, caching, profiling, and code review checklist. Use when optimizing components, reviewing code for performance, or analyzing bundle size and Core Web Vitals."
+description: "Profiles and reduces frontend/backend costs: split bundles, optimize assets, apply caching, and fix Core Web Vitals regressions. Use when profiling Lighthouse/CI regressions, reducing bundle size, or fixing high CLS/LCP/TTI metrics."
 ---
 
 # Performance Optimization
 
 **Rule:** Measure first (`Chrome DevTools`, `Lighthouse`, `Datadog`), optimize second. Set budgets (load time, memory, API latency). Automate in CI/CD.
 
+Domain-specific patterns (rendering, JS, Node optimizations) are referenced in REFERENCE.md to keep this skill concise.
+
 ## Patterns by Domain
 
 | Domain | Key patterns |
@@ -25,6 +27,44 @@ input.addEventListener('input', (e) => fetch(`/search?q=${e.target.value}`));
 let t; input.addEventListener('input', (e) => { clearTimeout(t); t = setTimeout(() => fetch(`/search?q=${e.target.value}`), 300); });
 ```
 
+## Executable Examples
+
+### Dynamic import splitting (example)
+
+```js
+// Lazy-load a heavy chart only on client
+import dynamic from 'next/dynamic';
+const Chart = dynamic(() => import('../components/Chart'), { ssr: false, loading: () => <div>Loading chart…</div> });
+export default function Page(){ return <Chart />; }
+```
+
+### React.memo + profiler pattern
+
+```jsx
+import React, { Profiler } from 'react';
+const Item = React.memo(function Item({data}){ return <div>{data.title}</div>; });
+function onRender(id, phase, actualDuration){ console.log(id, phase, actualDuration); }
+export default function List({items}){
+	return (
+		<Profiler id="List" onRender={onRender}>
+			{items.map(i=> <Item key={i.id} data={i} />)}
+		</Profiler>
+	);
+}
+```
+
+## Profiling Workflow (step-by-step)
+
+1. Run Lighthouse (or CI perf job) and record baseline.
+	 - Checkpoint: failing metric(s) identified (LCP/CLS/FID/TTI).
+	 - Recovery: if noisy, reproduce locally with `--emulated-form-factor=mobile`.
+2. Profile with DevTools Profiler / React profiler or Node `clinic` for backend.
+	 - Checkpoint: hotspot call stacks / long tasks located.
+3. Apply minimal fix (code-split, memoize, reduce payloads, defer non-critical work).
+	 - Checkpoint: targeted change reduces measured hotspot time in profiler.
+4. Re-run Lighthouse/CI perf job and compare; set threshold (e.g., 10% improvement or within budget).
+5. If regression persists, iterate and create a rollback plan; note fixes in changelog.
+
 ## Review Checklist
 
 - [ ] No O(n²)+ algorithms; appropriate data structures

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

@@ -1,119 +1,83 @@
 ---
 name: project-consistency
-description: "Enforce cross-agent consistency in multi-page/multi-component projects. Covers visual design, code patterns, content style, and structural conventions. Essential for convoy parallel execution where multiple agents build different parts of the same app."
+description: "Generates shared CSS variables, validates component naming conventions, and creates layout pattern templates. Use when coordinating a design system, theme, consistent styling, CSS variables, or a component library across parallel agents."
 ---
 
 # Project Consistency
 
-Multiple agents building in parallel make independent decisions about colors, fonts, APIs, and tone. **Consistency must be engineered as shared inputs before parallel work begins — not hoped for afterward.**
+Ensure consistency by producing shared artifacts and automated checks before parallel work begins.
 
 ## Foundation-First Principle
 
-```
-❌ Wrong:  [A] ─┐                    → inconsistent output
-           [B] ─┤→ build in parallel → inconsistent output
-           [C] ─┘                    → inconsistent output
-
-✅ Right:  [foundation] → artifacts → [A] ─┐
-                                      [B] ─┤→ consistent output
-                                      [C] ─┘
-```
-
-**Phase 1 (sequential):** One task creates all shared artifacts.  
-**Phase 2 (parallel):** Every page task imports from Phase 1. No new values, no recreated components.
-
-### The 4 Consistency Dimensions
-
-| Dimension | What drifts | Artifact |
-|-----------|-------------|----------|
-| **Visual** | Color palettes, font choices, spacing units | Design tokens file |
-| **Code** | Component APIs, naming conventions, import paths | UI component library |
-| **Content** | Tone, terminology, heading hierarchy | Style guide brief |
-| **Structural** | Page layout, navigation, responsive breakpoints | Shared layout component |
-
----
-
-## Foundation Phase Artifacts
-
-A foundation task must produce four artifacts. All phase-2 tasks depend on its completion.
-
-| Artifact | Path | Contents |
-|----------|------|----------|
-| **Design tokens** | `src/styles/tokens.css` | CSS custom properties: palette, typography, spacing, motion, shadows, radius, breakpoints. **Rule:** no value outside this file. |
-| **Shared layout** | `src/components/Layout.tsx` (React) · `src/layouts/Layout.astro` (Astro) | Wraps every page: responsive container, header, nav, footer, document head. Import — never recreate. |
-| **UI component library** | `src/components/ui/` | `Button`, `Card`, `Heading`, `Text`, `Link`, `Section`, `Container`, `Grid` — tokens only. API: camelCase props, `variant`/`size`/`className`, no inline `style`. |
-| **Style guide brief** | Inline in foundation prompt (quoted verbatim in page prompts) | Aesthetic direction · typography pairing · content tone · nav labels · page structure pattern · terminology glossary |
-
----
+Phase 1 (sequential): create shared artifacts (tokens, Layout, UI components). Phase 2 (parallel): every page imports from Phase 1; no new tokens or duplicated components.
 
-## Consistency Rules for Page Agents
+### Foundation Artifacts & Page Rules
 
-Every page agent in a multi-agent convoy MUST follow all rules below.
+| Artifact | Path | Page Agent Rules |
+|----------|------|------------------|
+| **Design tokens** | `src/styles/tokens.css` | Import only. Never introduce new color/font/spacing values. |
+| **Shared layout** | `src/components/Layout.tsx` / `Layout.astro` | Wrap every page. Never recreate. |
+| **UI components** | `src/components/ui/` | Import from library. PascalCase components, camelCase props. |
+| **Style guide brief** | Inline in prompts | Match tone + terminology exactly. Follow heading hierarchy. |
 
-| Area | Rules |
-|------|-------|
-| **Visual** | Import tokens only. Never introduce new color, font-size, or spacing values. Flag missing tokens — don't invent inline values. CSS custom properties exclusively; no raw hex or raw `px`. |
-| **Code** | Import `Layout` from shared path — no page-local wrappers. Import UI components from library — don't recreate. PascalCase components, camelCase props, kebab-case CSS classes. Co-locate component files. |
-| **Content** | Match tone from style guide exactly. Use terminology glossary verbatim. Follow heading hierarchy pattern. |
-| **Structural** | Every page uses shared Layout — no exceptions. Follow page structure from brief. Nav labels match brief exactly. Breakpoints from tokens only. |
+**Validation checkpoints:**
+1. Foundation complete: `tokens.css` has all palette/type/spacing vars, Layout renders, UI components compile.
+2. Per-page: `grep -r 'style={{' src/pages/` returns 0 hits (no inline styles). All imports resolve.
 
 ---
 
 ## Convoy Integration
 
-```
-Phase 1: foundation-setup  (1 task, blocks Phase 2)
-├── Agent:  UI-UX Expert or Developer
-├── Creates: tokens.css, Layout, UI component library
-├── Defines: style guide brief (aesthetic, tone, nav labels, terminology)
-└── Output:  all paths documented for Phase 2 prompts
-
-Phase 2: page-building  (N tasks, all parallel)
-├── home-page · about-page · projects-page · contact-page · ...
-└── [every prompt contains the 5 mandatory references below]
-```
-
-### 5 Mandatory References in Every Page Task Prompt
+Phase 1 (sequential): foundation-setup creates tokens, Layout, UI library, and style guide brief. Phase 2 (parallel): every page task imports from Phase 1. Include these 5 references in every page prompt:
 
 ```
-1. Design tokens:  `[path/tokens.css]` — use ONLY these tokens. No new values.
-2. Layout:         `[path/Layout]` — wrap all page content in this component.
-3. UI components:  `[path/src/components/ui/]` — import; do not recreate.
-4. Aesthetic:      [2-3 word direction from foundation]
-5. Content tone:   [tone description from foundation]
+1. Design tokens path   2. Layout path   3. UI components path
+4. Aesthetic direction   5. Content tone
 ```
 
----
-
-## Prompt Template: Foundation Task
+Prompt templates: see [TEMPLATES.md](./TEMPLATES.md).
 
-````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].
+## Executable Examples
 
-**Acceptance Criteria:** Zero hardcoded hex/px · Layout responsive at 320/768/1280px · Fluid typography via clamp() · Fonts loaded efficiently
-````
+### Example: `src/styles/tokens.css`
 
----
+```css
+:root {
+	/* Palette */
+	--color-bg: #ffffff;
+	--color-foreground: #0f172a;
+	--color-primary: #0ea5e9;
+	--color-primary-600: #0284c7;
 
-## Prompt Template: Page Task
+	/* Typography */
+	--font-base: 'Inter, system-ui, -apple-system, sans-serif';
+	--text-sm: 0.875rem;
+	--text-base: 1rem;
 
-````markdown
-## Build [Page Name] Page — [purpose, audience, primary action]
+	/* Spacing */
+	--space-1: 4px;
+	--space-2: 8px;
+	--space-3: 16px;
 
-**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]
+	/* Radius */
+	--radius-sm: 6px;
+	--radius-md: 12px;
+}
+```
 
-**Content:** [sections, copy direction, media]  **Structure:** [hero → ... → CTA]
+### Minimal Button component example (React)
 
-**Acceptance Criteria:** Shared Layout used · Zero hardcoded values · UI components imported · Tone/terminology match · Responsive 320/768/1280px · [page-specific]
-````
+```tsx
+import './tokens.css';
+type ButtonProps = { children: React.ReactNode; variant?: 'primary' | 'ghost'; className?: string };
+export function Button({ children, variant = 'primary', className = '' }: ButtonProps) {
+	const base = 'px-4 py-2 rounded';
+	const variantCls = variant === 'primary' ? 'bg-[var(--color-primary)] text-white' : 'bg-transparent';
+	return <button className={`${base} ${variantCls} ${className}`}>{children}</button>;
+}
+```
 
 ---
 
@@ -122,10 +86,7 @@ Create `[path]/ui/`: Button, Card, Heading, Text, Link, Section, Container, Grid
 | Anti-pattern | Fix |
 |-------------|-----|
 | Agents pick their own fonts/colors | Foundation creates tokens first |
-| Page-local `styles/global.css` | One shared tokens file, imported once |
 | Copy-pasting `Button` between pages | Import from shared library |
 | Inline `style={{ color: '#...' }}` | CSS class with token variable |
-| Skipping foundation "for a simple site" | Foundation takes 1 task, saves N fixes |
-| Different terminology per page | Terminology glossary in style guide brief |
 | Foundation and page tasks run in parallel | Foundation phase must fully complete first |