opencastle 0.35.2 → 0.35.3

package/src/orchestrator/agents/team-lead.agent.md

@@ -1,5 +1,5 @@
 ---
-description: 'Task orchestrator that analyzes work, decomposes it into subtasks, and delegates to specialized agents via sub-agents (inline) or background sessions (parallel worktrees).'
+description: 'Task orchestrator: analyzes work, decomposes into subtasks, delegates to specialized agents via sub-agents (inline) or background sessions (parallel worktrees).'
 name: 'Team Lead (OpenCastle)'
 model: Claude Opus 4.7
 tools: [read/problems, read/readFile, agent/runSubagent, edit/createDirectory, edit/createFile, edit/createJupyterNotebook, edit/editFiles, edit/editNotebook, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/searchResults, search/textSearch, search/usages, web/fetch, agent, execute/runInTerminal, execute/getTerminalOutput, read/terminalLastCommand, read/terminalSelection]
@@ -59,7 +59,7 @@ Developer | UI/UX Expert | Content Engineer | Database Engineer | Testing Expert
 
 ## Delegation
 
-**Sub-agents** (`runSubagent`): synchronous, critical-path. **Background agents**: async in isolated worktrees, parallel work. Always name the agent explicitly. Include: issue ID, objective, file paths, acceptance criteria, self-improvement reminder.
+**Sub-agents** (`runSubagent`): synchronous, critical-path. **Background agents**: async in isolated worktrees, parallel work. Always name agent explicitly. Include: issue ID, objective, file paths, acceptance criteria, self-improvement reminder.
 
 **⛔ Hard gates:**
 - Log delegation record immediately after each return/spawn — **observability-logging** (`--mechanism sub-agent` or `--mechanism background`).
@@ -88,11 +88,11 @@ Developer | UI/UX Expert | Content Engineer | Database Engineer | Testing Expert
 
 **Step 5 — Deliver:** See [shared-delivery-phase.md](../agent-workflows/shared-delivery-phase.md). Verify all Done → build/lint/test → commit feature branch → `GH_PAGER=cat gh pr create` — do NOT merge → link PR → clean checkpoint → call **Session Guard**.
 
-**On Resume:** Read `SESSION-CHECKPOINT.md`. Check `AGENT-FAILURES.md` and `DISPUTES.md`. List In Progress / Todo → continue.
+**On Resume:** Read `SESSION-CHECKPOINT.md`. Check `AGENT-FAILURES.md`, `DISPUTES.md`. List In Progress / Todo → continue.
 
 ## Observability
 
-> **⛔ HARD GATE.** Load **observability-logging** for schemas, commands, and pre-response quality gate. Before Session Guard: delegation count + review count = records written.
+> **⛔ HARD GATE.** Load **observability-logging** for schemas, commands, pre-response quality gate. Before Session Guard: delegation count + review count = records written.
 
 ## Rules
 

package/src/orchestrator/agents/testing-expert.agent.md

@@ -1,5 +1,5 @@
 ---
-description: 'Testing expert for E2E tests, integration tests, browser validation, and test suites using browser automation and test file authoring.'
+description: 'Testing expert: E2E tests, integration tests, browser validation, test suites via browser automation, test file authoring.'
 name: 'Testing Expert'
 model: GPT-5.5-Codex
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages']
@@ -12,7 +12,7 @@ Validates UI changes via browser automation; writes E2E/integration suites. TDD-
 
 ## Skills
 
-Resolve all skills via [skill-matrix.json](.opencastle/agents/skill-matrix.json).
+Resolve skills via [skill-matrix.json](.opencastle/agents/skill-matrix.json).
 
 ## Rules
 
@@ -27,7 +27,7 @@ Resolve all skills via [skill-matrix.json](.opencastle/agents/skill-matrix.json)
 
 ## Anti-Patterns
 
-- Assert mock behavior; skip the full suite; test-after; desktop-only testing; test-only prod methods
+- Assert mock behavior; skip full suite; test-after; desktop-only testing; test-only prod methods
 
 ## Test Plan
 
@@ -38,8 +38,8 @@ Every suite covers: Initial State · User Interactions · State Transitions · E
 - `data-testid` for element selection; mock external APIs only (not internal modules)
 - Deterministic tests — no `sleep`/timing hacks; use `waitFor`/expect-based polling
 - Browser: `evaluate_script()` over `take_snapshot()`, max 3 screenshots, clear state between flows
-- Test keyboard navigation and accessibility
-- Load **browser-testing** skill for breakpoint checklists and exact commands
+- Test keyboard navigation, accessibility
+- Load **browser-testing** skill for breakpoint checklists, exact commands
 
 ## When Stuck
 
@@ -60,8 +60,8 @@ Every suite covers: Initial State · User Interactions · State Transitions · E
 
 1. **Test Files** — created/modified
 2. **Coverage** — count, pass/fail, percentage
-3. **Browser Validation** — screenshots and what they prove
+3. **Browser Validation** — screenshots, what they prove
 4. **Edge Cases** — covered and gaps
 5. **Regressions** — adjacent features verified
 
-See [Base Output Contract](../snippets/base-output-contract.md) for the standard closing items.
+See [Base Output Contract](../snippets/base-output-contract.md) for standard closing items.

package/src/orchestrator/agents/ui-ux-expert.agent.md

@@ -1,5 +1,5 @@
 ---
-description: 'UI/UX expert for designing and building accessible, consistent UI components with deep knowledge of the design system.'
+description: 'UI/UX expert: designs, builds accessible, consistent UI components with deep design system knowledge.'
 name: 'UI/UX Expert'
 model: Claude Sonnet 4.6
 tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages']
@@ -9,11 +9,11 @@ user-invocable: false
 # UI/UX Expert
 
 ## Critical Rules
-1. **Design system first** — check existing tokens, components, and patterns before creating new
+1. **Design system first** — check existing tokens, components, patterns before creating new
 2. **Semantic HTML before ARIA** — fix structure first; only add ARIA when semantic HTML is insufficient
-3. **Mobile-first always** — design at the smallest breakpoint; never start at desktop
-4. **Place shared components in the UI library** — never in app-specific directories
-5. **Validate at all breakpoints** — load the **e2e-testing** skill for resize commands and checklists
+3. **Mobile-first always** — design at smallest breakpoint; never start at desktop
+4. **Place shared components in UI library** — never in app-specific directories
+5. **Validate at all breakpoints** — load **e2e-testing** skill for resize commands, checklists
 
 ## Anti-Patterns
 - Generic AI aesthetics (Inter font, purple gradients, card grids) — be distinctive
@@ -21,25 +21,25 @@ user-invocable: false
 - Adding ARIA before fixing semantic HTML; desktop-first development
 
 ## Skills
-Resolve all skills (slots and direct) via [skill-matrix.json](.opencastle/agents/skill-matrix.json).
+Resolve skills (slots, direct) via [skill-matrix.json](.opencastle/agents/skill-matrix.json).
 
 ## When Stuck
 | Problem | Solution |
 |---------|----------|
-| Can't find the design token | Check the UI library's token file before hardcoding |
+| Can't find the design token | Check UI library's token file before hardcoding |
 | Component looks generic / AI-generated | Add one distinctive element: type scale, spacing, or brand motion |
-| Keyboard navigation is broken | Trace focus order from the first focusable element |
+| Keyboard navigation is broken | Trace focus order from first focusable element |
 | Responsive breakpoint fails | Check `testing-config.md` for project-defined breakpoints |
 
 ## Guidelines
-- Export all components from the UI library index; use `clsx` for conditional classes
-- Implement hover, focus, and active states for all interactive elements
-- Co-locate component styles with the component file; test with keyboard-only navigation
+- Export all components from UI library index; use `clsx` for conditional classes
+- Implement hover, focus, active states for all interactive elements
+- Co-locate component styles with component file; test with keyboard-only navigation
 
 ### Multi-Page Convoy Consistency
-- **Foundation task:** create design tokens, shared layout, and UI component library — choices are the project contract
-- **Page task:** import from foundation — no new tokens, layouts, or design values
-- Load the **project-consistency** skill for full guidance
+- **Foundation task:** create design tokens, shared layout, UI component library — choices are project contract
+- **Page task:** import from foundation — no new tokens, layouts, design values
+- Load **project-consistency** skill for full guidance
 
 ## Done When
 - Components render at all defined responsive breakpoints
@@ -57,4 +57,4 @@ Resolve all skills (slots and direct) via [skill-matrix.json](.opencastle/agents
 3. **Responsive** — breakpoints tested (per project testing config)
 4. **Visual Evidence** — screenshots at each breakpoint
 
-See [Base Output Contract](../snippets/base-output-contract.md) for the standard closing items.
+See [Base Output Contract](../snippets/base-output-contract.md) for standard closing items.

package/src/orchestrator/prompts/assess-complexity.prompt.md

@@ -8,7 +8,7 @@ output: json
 
 # Assess PRD Complexity
 
-Analyze the PRD below and produce a complexity assessment as a **single JSON object**. This JSON is consumed programmatically by the pipeline to decide whether to generate one convoy spec or a chain of convoy specs.
+Analyze the PRD below; produce complexity assessment as **single JSON object**. Consumed programmatically by pipeline to decide whether to generate one convoy spec or chain of convoy specs.
 
 ## PRD to Analyze
 
@@ -22,7 +22,7 @@ Analyze the PRD below and produce a complexity assessment as a **single JSON obj
 
 ## Output Rules
 
-**CRITICAL:** Return ONLY a single fenced JSON block — no prose, no explanation, no markdown headings. Start your response with the opening fence and end with the closing fence.
+**CRITICAL:** Return ONLY single fenced JSON block — no prose, no explanation, no markdown headings. Start with opening fence; end with closing fence.
 
 ## Required JSON Schema
 
@@ -57,7 +57,7 @@ Analyze the PRD below and produce a complexity assessment as a **single JSON obj
 
 ## Field Rules
 
-- `original_prompt`: Copy the user's original feature request verbatim from the "Original User Prompt" section above. If that section is empty, extract a one-sentence summary from the PRD's Overview section.
+- `original_prompt`: Copy user's original feature request verbatim from "Original User Prompt" section above. If empty, extract one-sentence summary from PRD's Overview section.
 - `total_tasks`: Count of individual workstreams in the Task Breakdown.
 - `total_phases`: Count of phases in the Task Breakdown.
 - `domains`: List of technical domains involved (e.g., "frontend", "api", "database", "testing", "config").
@@ -66,15 +66,15 @@ Analyze the PRD below and produce a complexity assessment as a **single JSON obj
 - `recommended_strategy`:
   - `"single"` when: total tasks ≤ 8, OR total phases ≤ 3, OR all tasks are tightly coupled with heavy cross-phase file sharing.
   - `"chain"` when: total tasks > 8 AND total phases > 3 AND domains have natural boundaries — AND splitting improves failure isolation, observability, or retry granularity.
-- `chain_rationale`: Only filled when `recommended_strategy` is `"chain"` — explain WHY splitting benefits this specific feature.
+- `chain_rationale`: Only filled when `recommended_strategy` is `"chain"` — explain WHY splitting benefits this feature.
 - `convoy_groups`:
   - When `"single"`: exactly one group covering all phases.
   - When `"chain"`: 2–4 groups with explicit `depends_on` order. Each group covers a coherent domain boundary.
-  - **Minimum 3 tasks per group.** Never create a group that would produce a convoy with only 1–2 tasks — merge small groups with adjacent ones. A convoy with a single task is pointless overhead.
-  - **Do NOT map phases 1:1 to groups.** Groups should bundle multiple related phases when tasks are tightly coupled (e.g., config + data in one group, components + pages in another). Only split at genuine domain boundaries where failure isolation matters.
+  - **Minimum 3 tasks per group.** Never create a group producing a convoy with only 1–2 tasks — merge small groups with adjacent ones. Single-task convoy is pointless overhead.
+  - **Do NOT map phases 1:1 to groups.** Bundle multiple related phases when tasks are tightly coupled (e.g., config + data in one group, components + pages in another). Only split at genuine domain boundaries where failure isolation matters.
   - Maximum 3 groups for projects with ≤ 15 tasks. Maximum 4 groups for 16+ tasks.
 - `task_complexity`: Array of per-workstream complexity assessments using Fibonacci scale.
-  - `workstream`: Exact workstream title from the PRD's Task Breakdown section.
-  - `phase`: Phase number the workstream belongs to.
+  - `workstream`: Exact workstream title from PRD's Task Breakdown section.
+  - `phase`: Phase number workstream belongs to.
   - `complexity`: Fibonacci score: `1` (trivial — single file edit), `2` (simple — small fix, one test), `3` (moderate — new component/endpoint), `5` (significant — multi-file feature), `8` (complex — cross-cutting), `13` (epic — architecture-level).
   - `rationale`: One sentence explaining the score.

package/src/orchestrator/prompts/bootstrap-customizations.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Deep-analyze the project to complete the .opencastle/ configuration with schema details, API routes, environment variables, and other information that requires reading actual config files. The programmatic bootstrap (run during opencastle init) has already populated the deterministic parts — do not redo that work.'
+description: 'Deep-analyze project to complete .opencastle/ configuration with schema details, API routes, environment variables, other info requiring reading actual config files. Programmatic bootstrap (run during opencastle init) already populated deterministic parts — do not redo that work.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Complete Project Customizations
 
-You are completing the AI agent framework setup for a new project. The programmatic bootstrap (run automatically during `opencastle init`) has already populated the `.opencastle/` configuration files with everything it could determine automatically. Your job is to **deep-analyze** the project — reading actual config files, schemas, and source code — to **fill in the details** that require reading real file contents.
+Complete AI agent framework setup for a new project. Programmatic bootstrap (run automatically during `opencastle init`) already populated `.opencastle/` configuration files with everything it could determine automatically. Your job: **deep-analyze** project — reading actual config files, schemas, source code — to **fill in details** requiring reading real file contents.
 
 ## Additional Context (optional)
 
@@ -17,9 +17,9 @@ You are completing the AI agent framework setup for a new project. The programma
 
 ## Background
 
-The `.opencastle/` directory holds project-specific configuration that skills load at runtime. Skills contain generic methodology (how to write migrations, how to test, how to deploy); customizations hold the concrete values (which database, which endpoints, which project IDs).
+The `.opencastle/` directory holds project-specific configuration that skills load at runtime. Skills contain generic methodology (how to write migrations, how to test, how to deploy); customizations hold concrete values (which database, which endpoints, which project IDs).
 
-Without customizations, agents operate blind — they don't know the project's table schema, API routes, deployment target, or task board. This prompt fixes that.
+Without customizations, agents operate blind — they don't know project's table schema, API routes, deployment target, task board. This prompt fixes that.
 
 ## Pre-Existing Setup
 
@@ -27,10 +27,10 @@ Without customizations, agents operate blind — they don't know the project's t
 
 The project root contains **`.opencastle.json`** with a `repoInfo` field populated by `opencastle init`. It merges two sources:
 
-1. **Auto-detected tooling** — the init command scanned config files, `package.json` dependencies, and directory structures
-2. **User-declared choices** — the user selected CMS, database, project management, and notifications via the interactive questionnaire
+1. **Auto-detected tooling** — init command scanned config files, `package.json` dependencies, and directory structures
+2. **User-declared choices** — user selected CMS, database, project management, notifications via interactive questionnaire
 
-The result is a single unified view of the project's tech stack:
+Result: single unified view of project's tech stack:
 
 ```json
 {
@@ -63,17 +63,17 @@ The result is a single unified view of the project's tech stack:
 **Use `repoInfo` to:**
 - Know which technologies are present — skip re-scanning, go straight to reading their config files
 - Identify `configFiles` to read for deep inspection
-- Know which `project/` config files to create if they're missing (e.g., if `repoInfo.pm` includes `"linear"`, ensure `project/linear-config.md` exists)
+- Know which `project/` config files to create if missing (e.g., if `repoInfo.pm` includes `"linear"`, ensure `project/linear-config.md` exists)
 
 **`stack` vs `repoInfo`:** The `stack` field holds the raw user questionnaire answers (used internally for MCP server filtering and skill selection). The `repoInfo` field is the combined view you should use — it includes everything from `stack` plus all auto-detected tooling.
 
 **Still inspect:** `repoInfo` detects presence, not configuration details. You still need to read the actual config files for schemas, IDs, routes, etc.
 
-The skill matrix (`.opencastle/agents/skill-matrix.json`) will already have the `cms` and `database` binding entries pre-filled. The appropriate task management and notifications skills will already be installed. Verify they are correct and fill in any remaining empty bindings.
+Skill matrix (`.opencastle/agents/skill-matrix.json`) already has `cms`, `database` binding entries pre-filled. Appropriate task management, notifications skills already installed. Verify correctness; fill in remaining empty bindings.
 
 ### Pre-populated `.opencastle/` Files — What's Already Done
 
-The programmatic bootstrap that runs during `opencastle init` has already created and partially filled these files. **Do not regenerate them from scratch — update them instead.**
+Programmatic bootstrap running during `opencastle init` already created, partially filled these files. **Do not regenerate from scratch — update them instead.**
 
 | File | What's already there | What's missing |
 |------|---------------------|----------------|
@@ -92,25 +92,25 @@ The programmatic bootstrap that runs during `opencastle init` has already create
 - `stack/data-pipeline-config.md` — requires reading pipeline scripts
 - `agents/agent-registry.md`, `agents/skill-matrix.json`, `agents/skill-matrix.md` — if `.github/agents/` and `.github/skills/` exist
 
-Any template file for a technology NOT detected (no DB, no CMS, etc.) has already been removed.
+Any template file for technology NOT detected (no DB, no CMS, etc.) already removed.
 
 ## Workflow
 
 ### Phase 1: Discovery
 
-The programmatic bootstrap has already detected the tech stack. **Skip re-scanning** — focus on reading actual file contents to extract details.
+Programmatic bootstrap already detected tech stack. **Skip re-scanning** — focus on reading actual file contents to extract details.
 
 #### 1.1 Read Pre-populated Files
 
 - **First**: Read all existing `.opencastle/` files to understand what's already filled in
-- Read `.opencastle/project.instructions.md` to see the current tech stack table and gaps
+- Read `.opencastle/project.instructions.md` to see current tech stack table, gaps
 - Read each `stack/*.md` file — note any `<!-- TODO: verify -->` markers and empty table rows
 - Read `.opencastle.json` for `repoInfo` and `configFiles` — use `configFiles` as your reading list
 - Note what's missing (empty sections, placeholders, TODO markers)
 
 #### 1.2 Deep Inspection
 
-For each technology listed in the pre-populated files, read its actual config files to extract the details that couldn't be auto-detected:
+For each technology in pre-populated files, read its actual config files to extract details that couldn't be auto-detected:
 
 - **Database**: Read migration files, schema definitions, RLS policies, auth setup — extract table names, column types, policy names
 - **CMS**: Read schema files, document types, plugin config — extract content model names, field definitions, project/space IDs
@@ -122,7 +122,7 @@ For each technology listed in the pre-populated files, read its actual config fi
 
 ### Phase 2: Complete Customization Files
 
-Update the existing `.opencastle/` files using the deep inspection data gathered in Phase 1. **Do not regenerate files that already exist** — update them.
+Update existing `.opencastle/` files using deep inspection data from Phase 1. **Do not regenerate files that already exist** — update them.
 
 Target file structure for reference:
 
@@ -174,7 +174,7 @@ Target file structure for reference:
 5. **`agents/skill-matrix.json`** — If `.github/skills/` exists with skill definitions:
    - Capability slot bindings and `directSkills` per agent role (in JSON format)
    - Which agents load which skills (slots for plugin skills, directSkills for process skills)
-   - Note: `skill-matrix.md` is a companion documentation file — the JSON is the source of truth
+   - Note: `skill-matrix.md` is companion documentation file — JSON is source of truth
 
 #### `stack/` — Update Existing, Create Missing
 
@@ -271,7 +271,7 @@ Now that your `.opencastle/` configuration is complete, here's what you can do:
 
 - **Discover, don't assume.** Read actual config files. Don't guess that the project uses Supabase because it's a Next.js app.
 - **Skip what doesn't exist.** If there's no CMS, don't create a CMS config file.
-- **Names, not secrets.** Document environment variable names (`SUPABASE_URL`) but never their values.
+- **Names, not secrets.** Document environment variable names (`SUPABASE_URL`) but never values.
 - **Be specific.** Write actual table names, actual endpoint paths, actual file paths — not placeholders.
 - **Flag uncertainty.** If you can't determine something from the code, add a `<!-- TODO: verify -->` comment rather than guessing.
 - **Keep files focused.** Each file covers one domain. Don't put database schema in the deployment config.

package/src/orchestrator/prompts/brainstorm.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Collaborative brainstorm to explore requirements, approaches, and trade-offs BEFORE committing to a plan. Use when the task has ambiguity, multiple valid approaches, or significant design decisions.'
+description: 'Collaborative brainstorm to explore requirements, approaches, trade-offs BEFORE committing to a plan. Use when task has ambiguity, multiple valid approaches, or significant design decisions.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Brainstorm
 
-You are the Team Lead. Before planning or writing any code, run a structured brainstorm to explore the request described below. The goal is to **surface assumptions, alternative approaches, and trade-offs** before locking in a plan.
+You are the Team Lead. Before planning or writing any code, run structured brainstorm to explore the request below. Goal: **surface assumptions, alternative approaches, trade-offs** before locking in a plan.
 
 ## Request
 
@@ -17,17 +17,17 @@ You are the Team Lead. Before planning or writing any code, run a structured bra
 
 ## Why Brainstorm?
 
-Planning too early locks in assumptions. A brainstorm phase catches misunderstandings, reveals better approaches, and aligns on scope — paying for 10 minutes of thinking instead of hours of rework.
+Planning too early locks in assumptions. Brainstorm phase catches misunderstandings, reveals better approaches, aligns on scope — 10 minutes of thinking instead of hours of rework.
 
 ## Workflow
 
 ### 1. Clarify the Problem
 
-Before exploring solutions, make sure the problem is well-understood:
+Before exploring solutions, ensure problem is well-understood:
 
 1. **Restate the request** in your own words — verify you understand what's being asked
 2. **Identify the user's goals** — what outcome do they want? (not just what they asked for)
-3. **Surface assumptions** — what are you assuming about scope, constraints, and priorities?
+3. **Surface assumptions** — what are you assuming about scope, constraints, priorities?
 4. **Ask clarifying questions** — if anything is ambiguous, ask now (max 3 questions, batch them)
 
 ### 2. Explore the Solution Space
@@ -37,7 +37,7 @@ Research before proposing. Gather data, don't guess:
 1. **Search existing code** — is there already a partial implementation, similar pattern, or relevant utility?
 2. **Check documentation** — read `.opencastle/project.instructions.md`, `.opencastle/project/decisions.md`, `.opencastle/KNOWN-ISSUES.md` for constraints
 3. **Check lessons learned** — read `.opencastle/LESSONS-LEARNED.md` for pitfalls in this area
-4. **Identify affected layers** — which apps, libs, data stores, and third-party services are involved?
+4. **Identify affected layers** — which apps, libs, data stores, third-party services are involved?
 5. **Research unknown topics** — if the request involves a real-world person, place, organization, or topic you don't have confident knowledge about, **search the internet** using any available web search or fetch tools (e.g. `fetch_webpage`, web search MCP, or similar) to gather accurate facts. Never fabricate content about real-world subjects.
 
 ### 3. Generate Alternatives
@@ -53,16 +53,16 @@ Propose 2-3 approaches, not just the obvious one:
 For each approach, consider:
 - **Simplicity** — which is the boring, proven solution? (prefer this per Constitution #2)
 - **Reversibility** — which is easiest to undo if wrong?
-- **Impact on future work** — which makes the next task easier or harder?
+- **Impact on future work** — which makes next task easier or harder?
 - **Risk** — which has the most unknowns?
 
 ### 4. Evaluate Trade-offs
 
-Pick the recommended approach and defend it:
+Pick recommended approach; defend it:
 
-1. **Why this approach?** — articulate the key reason (1-2 sentences)
-2. **What are we giving up?** — name the trade-off explicitly
-3. **What could go wrong?** — the biggest risk and how to mitigate it
+1. **Why this approach?** — articulate key reason (1-2 sentences)
+2. **What are we giving up?** — name trade-off explicitly
+3. **What could go wrong?** — biggest risk + mitigation
 4. **What's the exit strategy?** — if this approach fails, what's plan B?
 
 ### 5. Define Scope
@@ -75,7 +75,7 @@ Draw a clear boundary:
 
 #### Design Direction (for multi-page projects)
 
-If the request involves building 2+ pages or UI sections, define the design direction during brainstorming — not during implementation:
+If request involves building 2+ pages or UI sections, define design direction during brainstorming — not during implementation:
 
 - **Aesthetic direction:** 2-3 words (e.g., "warm editorial", "clean minimal", "brutalist edge")
 - **Typography pairing:** display font + body font (avoid generic defaults like Inter/Roboto)
@@ -83,11 +83,11 @@ If the request involves building 2+ pages or UI sections, define the design dire
 - **Content tone:** formal/casual, active/passive, target audience voice
 - **Key terminology:** terms that could be said multiple ways — pick one (e.g., "projects" not "portfolio")
 
-Include this in the Brainstorm Report so the planning phase can inject it into convoy foundation tasks.
+Include this in Brainstorm Report so planning phase can inject into convoy foundation tasks.
 
 ### 6. Output
 
-Summarize the brainstorm as a **Brainstorm Report** — this becomes the input for the planning/decomposition phase:
+Summarize the brainstorm as **Brainstorm Report** — becomes input for planning/decomposition phase:
 
 ```markdown
 ## Brainstorm Report: [Title]
@@ -105,7 +105,7 @@ Summarize the brainstorm as a **Brainstorm Report** — this becomes the input f
 ### Affected Areas
 - Apps: [list]
 - Libs: [list]
-- Data: [which data layers are affected — see `project.instructions.md` for the tech stack]
+- Data: [which data layers are affected — see `project.instructions.md` for tech stack]
 - Routes: [list]
 
 ### Open Questions
@@ -120,11 +120,11 @@ Summarize the brainstorm as a **Brainstorm Report** — this becomes the input f
 
 ## When to Skip Brainstorming
 
-Not every task needs a brainstorm. Skip this prompt and go directly to `implement-feature` or `quick-refinement` when:
+Not every task needs brainstorm. Skip this prompt; go directly to `implement-feature` or `quick-refinement` when:
 
 - The task is a well-defined bug with clear reproduction steps
 - The task is a simple config change or docs update
-- The technical approach is obvious and unambiguous
+- Technical approach is obvious and unambiguous
 - The scope is a single file or component with no design decisions
 - The task is well-understood and can be expressed as a convoy spec directly → use `generate-convoy` instead
 

package/src/orchestrator/prompts/bug-fix.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Investigate and fix a reported bug with proper triage, root cause analysis, issue tracking, and verification.'
+description: 'Investigate and fix reported bug with proper triage, root cause analysis, issue tracking, verification.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Fix Bug
 
-You are the Team Lead. Investigate and fix the bug described below. Bugs are real defects that affect users — treat them seriously with proper triage, tracking, and verification.
+You are the Team Lead. Investigate and fix the bug described below. Bugs are real defects affecting users — treat seriously with proper triage, tracking, verification.
 
 ## Bug Report
 
@@ -32,7 +32,7 @@ You are the Team Lead. Investigate and fix the bug described below. Bugs are rea
 ### 1. Triage & Reproduce
 
 1. **Check known issues** — Search `.opencastle/KNOWN-ISSUES.md` for an existing entry. If found, note workarounds and decide if a fix is now feasible
-2. **Check tracker** — Search for existing bug tickets. If one exists, take it over instead of creating a duplicate
+2. **Check tracker** — Search for existing bug tickets. If one exists, take it over instead of creating duplicate
 3. **Read lessons learned** — Check `.opencastle/LESSONS-LEARNED.md` for related pitfalls
 4. **Reproduce the bug** — Start the dev server (see **codebase-tool** skill), navigate to the affected page in Chrome, follow the repro steps, and screenshot the broken state
 5. **Determine scope** — Which apps are affected? (see `project.instructions.md` for the app inventory)
@@ -40,9 +40,9 @@ You are the Team Lead. Investigate and fix the bug described below. Bugs are rea
 
 ### 2. Create Tracker Issue
 
-Every bug gets tracked. Create a tracker issue with:
+Every bug gets tracked. Create tracker issue with:
 
-- **Title**: `[Bug] Short description of the symptom`
+- **Title**: `[Bug] Short description of symptom`
 - **Label**: `bug`; **Priority**: based on severity
 - **Description**: Symptom, reproduction steps, expected vs actual behavior, affected apps + files, screenshot
 
@@ -56,7 +56,7 @@ Every bug gets tracked. Create a tracker issue with:
 
 ### 4. Implement the Fix
 
-All bug fixes are executed via the convoy engine — even single-task fixes — to ensure observability and crash recovery.
+All bug fixes execute via convoy engine — even single-task fixes — for observability, crash recovery.
 
 1. **Generate a convoy spec** — use the `generate-convoy` prompt with the root cause analysis, fix approach, and file paths as context.
 2. **Hand the spec to the user** — tell them to run: `npx opencastle run -f .opencastle/convoys/<name>.convoy.yml`
@@ -64,7 +64,7 @@ All bug fixes are executed via the convoy engine — even single-task fixes —
 
 #### Convoy Task Prompt Must Include
 
-- Tracker issue ID and title, root cause, fix approach, file paths, reproduction steps
+- Tracker issue ID, title, root cause, fix approach, file paths, reproduction steps
 - Boundaries: "Only modify files listed above. Fix the bug, do not refactor surrounding code."
 - Self-improvement reminder (see **self-improvement** skill)
 
@@ -76,7 +76,7 @@ All bug fixes are executed via the convoy engine — even single-task fixes —
 
 ### 5. Validate
 
-> Load the **validation-gates** skill for detailed steps on each gate.
+> Load **validation-gates** skill for detailed steps on each gate.
 
 1. **Secret Scanning** — block if API keys/tokens/passwords found in diff
 2. **Deterministic Checks** — lint, test, build — zero errors (see **codebase-tool** skill)
@@ -90,7 +90,7 @@ All bug fixes are executed via the convoy engine — even single-task fixes —
 
 ### 6. Delivery
 
-Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit, push, open PR (not merged), and link to the tracker.
+Follow **Delivery Outcome** in **git-workflow** skill — commit, push, open PR (not merged), link to tracker.
 
 ### 7. Wrap Up
 
@@ -100,7 +100,7 @@ Follow the **Delivery Outcome** defined in the **git-workflow** skill — commit
 
 ### 8. Completion Criteria
 
-The bug fix is complete when:
+Bug fix is complete when:
 
 - [ ] Bug is reproduced and root cause identified
 - [ ] Tracker issue created with full details
@@ -108,7 +108,7 @@ The bug fix is complete when:
 - [ ] Test added covering the bug scenario
 - [ ] Bug verified fixed in the browser
 - [ ] Both apps checked if shared code was modified
-- [ ] Delivery Outcome completed (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
+- [ ] Delivery Outcome completed (see **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
 - [ ] Tracker issue moved to Done
 - [ ] Known issues updated if applicable
 - [ ] Lessons learned captured if any retries occurred

package/src/orchestrator/prompts/create-skill.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Scaffold a new skill file with proper frontmatter, structure, and registration. Use when adding a new domain skill to the AI configuration.'
+description: 'Scaffold new skill file with proper frontmatter, structure, registration. Use when adding new domain skill to AI configuration.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Create Skill
 
-Scaffold a new skill for the AI agent configuration. Skills encode domain-specific knowledge that agents load on demand.
+Scaffold new skill for AI agent configuration. Skills encode domain-specific knowledge agents load on demand.
 
 ## Skill Request
 
@@ -17,14 +17,14 @@ Scaffold a new skill for the AI agent configuration. Skills encode domain-specif
 
 ## Skill Types
 
-OpenCastle has two kinds of skills with different locations and registration paths:
+OpenCastle has two skill kinds with different locations, registration paths:
 
 | Type | Location | Bound Via | Purpose |
 |------|----------|-----------|---------|
 | **Process skill** | `skills/<name>/SKILL.md` | `directSkills` in skill-matrix.json | Stack-agnostic methodology (testing workflow, self-improvement, validation gates) |
 | **Plugin skill** | `plugins/<plugin>/SKILL.md` | Capability slot in the skill matrix | Technology-specific knowledge (CMS queries, database patterns, deployment config) |
 
-> **Rule of thumb:** If the skill would need to be rewritten when switching technologies (e.g., Supabase → Convex), it belongs in a **plugin**. If it's useful regardless of stack, it's a **process skill**.
+> **Rule of thumb:** If skill would need rewriting when switching technologies (e.g., Supabase → Convex), it belongs in a **plugin**. If useful regardless of stack, it's a **process skill**.
 
 ---
 
@@ -45,7 +45,7 @@ Determine the type:
 - Use `kebab-case`
 - **Process skills:** descriptive domain name (e.g., `testing-workflow`, `context-map`, `security-hardening`)
 - **Plugin skills:** `skillName` field in the plugin's `config.ts` (e.g., `sanity-cms`, `supabase-database`, `nx-workspace`)
-- Check existing skills in `skills/` and `plugins/` to avoid overlap
+- Check existing skills in `skills/`, `plugins/` to avoid overlap
 
 ### Step 3: Create the Skill File
 
@@ -96,7 +96,7 @@ description: "<Verb1> X, <verb2> Y, and <verb3> Z. Use when <scenario1>, <scenar
 | **<related-skill>** skill | <What it contributes> |
 ```
 
-If the skill has large code examples (>30 lines), schema tables, or verbose reference material, create a companion `REFERENCE.md` in the same directory and link to it from SKILL.md. Keep SKILL.md as the lean operational overview. Companion files must start with a backlink: `> Parent: [SKILL.md](./SKILL.md)`.
+If skill has large code examples (>30 lines), schema tables, or verbose reference material, create companion `REFERENCE.md` in same directory; link to it from SKILL.md. Keep SKILL.md as lean operational overview. Companion files must start with backlink: `> Parent: [SKILL.md](./SKILL.md)`.
 
 ### Step 4: Register the Skill
 
@@ -104,30 +104,30 @@ Registration differs by type:
 
 #### Process Skill
 
-1. **Add to the skill matrix** — Add the skill name to the `directSkills` array of each relevant agent in `.opencastle/agents/skill-matrix.json`
-2. **Optional: reference in instructions** — If the skill should be loaded by default, add it to the appropriate `.github/instructions/` file
+1. **Add to skill matrix** — Add skill name to `directSkills` array of each relevant agent in `.opencastle/agents/skill-matrix.json`
+2. **Optional: reference in instructions** — If skill should load by default, add to appropriate `.github/instructions/` file
 
 #### Plugin Skill
 
-1. **Set `skillName` in the plugin's `config.ts`** — This connects the skill to the plugin
-2. **Update the skill matrix** — Add an entry to the matching capability slot's `entries` array in `.opencastle/agents/skill-matrix.json`
-3. **No agent changes needed** — Agents resolve plugin skills through capability slots automatically
+1. **Set `skillName` in plugin's `config.ts`** — Connects skill to plugin
+2. **Update skill matrix** — Add entry to matching capability slot's `entries` array in `.opencastle/agents/skill-matrix.json`
+3. **No agent changes** — Agents resolve plugin skills through capability slots automatically
 
 ### Step 5: Validate
 
-- [ ] File created at the correct path (`skills/` or `plugins/`)
+- [ ] File created at correct path (`skills/` or `plugins/`)
 - [ ] Frontmatter has `name` and `description` fields
-- [ ] Description is a single line (no line breaks)
-- [ ] Content follows the template structure
+- [ ] Description is single line (no line breaks)
+- [ ] Content follows template structure
 - [ ] No overlap with existing skills
 - [ ] Skill matrix updated (`directSkills` array or capability slot binding)
 - [ ] For process skills: at least one agent's `directSkills` array includes it in skill-matrix.json
-- [ ] For plugin skills: `config.ts` `skillName` matches the `name` in frontmatter
+- [ ] For plugin skills: `config.ts` `skillName` matches `name` in frontmatter
 - [ ] Run `npx tessl skill review <path>` — target 100 score (see Scoring Criteria below)
 
 ## Scoring Criteria
 
-Skills are evaluated by `npx tessl skill review` across 8 criteria (3 pts each = 24 total). Target 100.
+Skills evaluated by `npx tessl skill review` across 8 criteria (3 pts each = 24 total). Target 100.
 
 ### Description (frontmatter `description` field)
 
@@ -155,10 +155,10 @@ Skills are evaluated by `npx tessl skill review` across 8 criteria (3 pts each =
 - **Include executable examples** — At least one copy-paste-ready code block (5-15 lines). CLI commands with real flags, not placeholders
 - **Keep it scannable** — Tables over prose. Headings, bullets, code blocks. Agents parse structure, not paragraphs
 - **Number your workflows** — Every multi-step process needs numbered steps, checkpoints ("Gate: X passes"), and recovery ("Fail → fix → re-run step N")
-- **Don't explain what Claude knows** — Skip "what is X" explanations, obvious anti-pattern justifications, and concept definitions. Jump straight to the rules
-- **Avoid duplication** — If a rule exists in another skill or instruction file, reference it: "Load **security-hardening** skill for CSP configuration"
-- **Use REFERENCE.md for bulk** — Large code examples, schema tables, worked examples, and template libraries go in a companion `REFERENCE.md`. Link once from SKILL.md
+- **Don't explain what Claude knows** — Skip "what is X" explanations, obvious anti-pattern justifications, concept definitions. Jump straight to the rules
+- **Avoid duplication** — If rule exists in another skill or instruction file, reference it: "Load **security-hardening** skill for CSP configuration"
+- **Use REFERENCE.md for bulk** — Large code examples, schema tables, worked examples, template libraries go in companion `REFERENCE.md`. Link once from SKILL.md
 - **Stay stack-agnostic in process skills** — Use capability slot references ("the **database** skill" not "Supabase")
-- **Size target** — 80-200 lines in SKILL.md. Under 80 is too thin; over 200 should split content to REFERENCE.md. Over 300 should be split into multiple skills
-- **No standalone trigger-term sections** — Weave trigger terms naturally into the description's `Use when...` clause
+- **Size target** — 80-200 lines in SKILL.md. Under 80 too thin; over 200 split content to REFERENCE.md. Over 300 split into multiple skills
+- **No standalone trigger-term sections** — Weave trigger terms naturally into description's `Use when...` clause
 - **Third-person voice in descriptions** — "Creates X" not "Create X" or "This skill creates X"