opencastle 0.35.2 → 0.35.3

package/src/orchestrator/prompts/quick-refinement.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Handle follow-up refinements after a roadmap task — bug fixes, UI tweaks, polish, and adjustments that are too small for issue tracking.'
+description: 'Handle follow-up refinements after a roadmap task — bug fixes, UI tweaks, polish, adjustments too small for issue tracking.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Follow-Up Refinement
 
-You are the Team Lead. Handle the follow-up refinement described below. This is a **post-task adjustment** — a bug fix, UI tweak, or polish item that came up after reviewing a completed roadmap task. It does NOT require issue tracking.
+You are the Team Lead. Handle the follow-up refinement described below. This is **post-task adjustment** — a bug fix, UI tweak, or polish item that came up after reviewing a completed roadmap task. Does NOT require issue tracking.
 
 ## Request
 
@@ -25,7 +25,7 @@ You are the Team Lead. Handle the follow-up refinement described below. This is
 | Scope | Multi-step feature | Focused fix or adjustment |
 | Branch strategy | Dedicated feature branch | Current branch (already in progress) |
 
-**Despite being lighter-weight, follow-ups still require the same code quality and verification standards.** Never skip linting, testing, or browser checks just because the change is "small."
+**Despite being lighter-weight, follow-ups still require same code quality and verification standards.** Never skip linting, testing, or browser checks just because change is "small."
 
 ## Workflow
 
@@ -34,11 +34,11 @@ You are the Team Lead. Handle the follow-up refinement described below. This is
 **Create a tracker issue if ANY of these are true:**
 - Affects user-visible behavior, touches >2–3 files, or modifies `libs/`, queries, API routes, or Server Actions
 - Could introduce regressions in other features
-- You want a record for future reference
+- You want record for future reference
 
 **Skip tracking if ALL of these are true:**
 - Pure cosmetic/spacing/copy change with no behavioral impact
-- Isolated to a single component or page
+- Isolated to single component or page
 - Trivial to verify visually
 
 If creating: title `[Follow-up] Short description`, label `follow-up`, priority Low/Medium, description: what changed, why, files
@@ -61,19 +61,19 @@ If creating: title `[Follow-up] Short description`, label `follow-up`, priority
 
 #### Delegation Prompt Must Include
 
-- What to fix, exact file paths, and how to verify the result
+- What to fix, exact file paths, how to verify result
 - Boundaries: "Only modify files listed above. Do not refactor unrelated code."
 - Self-improvement reminder (see **self-improvement** skill)
 
 #### Implementation Rules
 
 - **No scope creep** — Fix only what was asked; note but don't fix adjacent issues
-- **DRY + Visual consistency** — Reuse existing components, utilities, and design system patterns
+- **DRY + Visual consistency** — Reuse existing components, utilities, design system patterns
 - **Cross-app + Accessibility** — Verify `libs/` changes across apps; don't regress keyboard nav/contrast
 
 ### 5. Validate
 
-> Load the **validation-gates** skill for detailed steps on each gate.
+> Load **validation-gates** skill for detailed steps on each gate.
 
 Every follow-up, no matter how small, must pass these gates:
 
@@ -87,24 +87,24 @@ Every follow-up, no matter how small, must pass these gates:
 
 ### 6. Delivery
 
-If tracked: follow the **Delivery Outcome** in the **git-workflow** skill — commit, push, open PR (not merged), tracker linked.
+If tracked: follow **Delivery Outcome** in **git-workflow** skill — commit, push, open PR (not merged), tracker linked.
 
-If untracked: commit to the current branch; Team Lead includes in the parent task's existing PR.
+If untracked: commit to current branch; Team Lead includes in parent task's existing PR.
 
 ### 7. Escalation Triggers
 
-- Requires a database migration or data model changes (CMS schemas, tables)
+- Requires database migration or data model changes (CMS schemas, tables)
 - Involves auth/authorization changes
 - Touches >5 files across multiple libraries
-- Introduces a new dependency or API endpoint
-- Is a systemic issue requiring architectural changes
+- Introduces new dependency or API endpoint
+- Systemic issue requiring architectural changes
 - Decomposes into 3+ subtasks → switch to `implement-feature`
 
 ### 8. Completion
 
-- [ ] The specific request is resolved
-- [ ] Tracker issue created and moved to Done (if triage determined tracking was needed)
-- [ ] **Visual changes verified in Chrome with screenshot taken as proof**
+- [ ] Specific request is resolved
+- [ ] Tracker issue created, moved to Done (if triage determined tracking was needed)
+- [ ] **Visual changes verified in Chrome with screenshot as proof**
 - [ ] Shared component changes tested across all consuming apps
-- [ ] Delivery Outcome completed if tracked (see the **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
-- [ ] Lessons learned captured and known issues updated if applicable
+- [ ] Delivery Outcome completed if tracked (see **git-workflow** skill) — branch pushed, PR opened (not merged), tracker linked
+- [ ] Lessons learned captured, known issues updated if applicable

package/src/orchestrator/prompts/resolve-pr-comments.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Resolve GitHub PR review comments by reading them, grouping by file, and applying fixes systematically.'
+description: 'Resolve GitHub PR review comments by reading them, grouping by file, applying fixes systematically.'
 agent: 'Team Lead (OpenCastle)'
 ---
 
@@ -7,7 +7,7 @@ agent: 'Team Lead (OpenCastle)'
 
 # Resolve PR Comments
 
-You are the Team Lead. A pull request has review comments that need to be resolved. Read the comments, group them by file, and delegate fixes efficiently.
+You are the Team Lead. A pull request has review comments needing resolution. Read comments, group by file, delegate fixes efficiently.
 
 ## PR Reference
 
@@ -36,7 +36,7 @@ You are the Team Lead. A pull request has review comments that need to be resolv
 
 ### Phase 3: Apply Fixes
 
-For each file group, delegate to the appropriate specialist agent:
+For each file group, delegate to appropriate specialist agent:
 
 ```
 Fix the following PR review comments in [file path]:
@@ -53,11 +53,11 @@ Acceptance criteria:
 - [ ] New tests added if the comment identified a gap
 ```
 
-**Discussion comments** — Do not fix these. Instead, compile them into a summary for the human reviewer with your recommendation.
+**Discussion comments** — Do not fix these. Compile into summary for human reviewer with your recommendation.
 
 ### Phase 4: Verify & Report
 
-> Load the **validation-gates** skill for detailed steps on each gate.
+> Load **validation-gates** skill for detailed steps on each gate.
 
 All fixes must pass applicable gates before pushing:
 
@@ -109,8 +109,8 @@ After resolving comments, report:
 
 ## Rules
 
-- **Never dismiss a must-fix comment** — if you disagree, flag it for discussion instead
-- **Preserve the reviewer's intent** — don't just technically satisfy the comment, address the underlying concern
-- **Don't over-fix** — resolve only what was commented on. Save unrelated improvements for a separate PR
+- **Never dismiss a must-fix comment** — if you disagree, flag for discussion instead
+- **Preserve reviewer's intent** — don't just technically satisfy the comment, address underlying concern
+- **Don't over-fix** — resolve only what was commented on. Save unrelated improvements for separate PR
 - **Respond to every comment** — nothing should be silently ignored
-- **Self-improvement** — Follow the **self-improvement** skill
+- **Self-improvement** — Follow **self-improvement** skill

package/src/orchestrator/prompts/validate-convoy.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Validate a convoy task plan for semantic correctness. Outputs VALID or INVALID with specific errors.'
+description: 'Validate convoy task plan for semantic correctness. Outputs VALID or INVALID with specific errors.'
 agent: 'Reviewer'
 output: validation
 ---
@@ -8,9 +8,9 @@ output: validation
 
 # Validate Task Plan
 
-> **Note:** Schema validation (field types, YAML syntax, dependency cycles, glob patterns) has already passed. The generator already enforces prompt quality, agent matching, and file list completeness. Focus ONLY on the structural and logical checks below.
+> **Note:** Schema validation (field types, YAML syntax, dependency cycles, glob patterns) already passed. Generator already enforces prompt quality, agent matching, file list completeness. Focus ONLY on structural and logical checks below.
 
-You are a senior technical reviewer. Validate the task plan below for **structural correctness**. Pass the plan if the structure is sound — do not fail for prompt wording, style, or verbosity.
+You are a senior technical reviewer. Validate the task plan below for **structural correctness**. Pass plan if structure is sound — do not fail for prompt wording, style, or verbosity.
 
 ## Task Plan to Validate
 
@@ -20,9 +20,9 @@ You are a senior technical reviewer. Validate the task plan below for **structur
 
 ## Validation Checks
 
-> If the spec contains `<!-- validation-pass: N -->`, this is pass N. On pass 2+, verify previous fixes were applied — do NOT invent new issues.
+> If spec contains `<!-- validation-pass: N -->`, this is pass N. On pass 2+, verify previous fixes were applied — do NOT invent new issues.
 
-Evaluate the checks below. If ALL pass, respond `VALID`. Only fail for checks marked BLOCKING.
+Evaluate checks below. If ALL pass, respond `VALID`. Only fail for checks marked BLOCKING.
 
 ### Partition Conflicts (BLOCKING)
 
@@ -33,22 +33,22 @@ Two tasks that can run in parallel (no direct or transitive `depends_on` edge be
 
 ### Dependency Completeness (BLOCKING)
 
-If a task's prompt imports, references, or builds on files produced by another task, a `depends_on` edge to that producing task must exist.
+If task's prompt imports, references, or builds on files produced by another task, `depends_on` edge to that producing task must exist.
 
 - [ ] Scan every prompt for cross-task file references
-- [ ] Each such reference must be covered by a `depends_on` edge
+- [ ] Each such reference must be covered by `depends_on` edge
 
 ### Logical Soundness (BLOCKING)
 
-- [ ] No redundant tasks doing the same work
-- [ ] No obvious missing tasks that would leave the goal unachievable
+- [ ] No redundant tasks doing same work
+- [ ] No obvious missing tasks that would leave goal unachievable
 - [ ] No tasks with empty or stub prompts (`...`, placeholder text)
 
 ---
 
 ## Output Format
 
-Your entire response must be a single fenced JSON block — no text before or after:
+Your entire response must be single fenced JSON block — no text before or after:
 
 ```json
 {

package/src/orchestrator/prompts/validate-prd.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: 'Validate a PRD for completeness, clarity, and implementability before generating a convoy spec. Outputs VALID or INVALID with specific issues.'
+description: 'Validate PRD for completeness, clarity, implementability before generating convoy spec. Outputs VALID or INVALID with specific issues.'
 agent: 'Reviewer'
 output: validation
 ---
@@ -8,9 +8,9 @@ output: validation
 
 # Validate PRD
 
-You are a senior technical reviewer. Your job is to validate the PRD below against strict quality criteria before it is used to generate an automated convoy spec. A PRD that passes this gate will produce a clean, executable convoy spec. A PRD that fails will produce bad tasks.
+You are a senior technical reviewer. Validate the PRD below against strict quality criteria before it is used to generate an automated convoy spec. PRD that passes this gate will produce clean, executable convoy spec. PRD that fails will produce bad tasks.
 
-Focus on **structural completeness** only — the PRD generator already enforces language quality and style. Your job is to catch structural problems that would break convoy spec generation. **Pass the PRD if sections exist and the structure is internally consistent.** Do not fail for stylistic preferences, word choice, or minor phrasing.
+Focus on **structural completeness** only — PRD generator already enforces language quality and style. Your job: catch structural problems that would break convoy spec generation. **Pass PRD if sections exist and structure is internally consistent.** Do not fail for stylistic preferences, word choice, or minor phrasing.
 
 ## PRD to Validate
 
@@ -20,32 +20,32 @@ Focus on **structural completeness** only — the PRD generator already enforces
 
 ## Validation Checklist
 
-> If the PRD contains `<!-- validation-pass: N -->`, this is pass N. On pass 2+, only verify previous fixes were applied — do NOT invent new issues.
+> If PRD contains `<!-- validation-pass: N -->`, this is pass N. On pass 2+, only verify previous fixes were applied — do NOT invent new issues.
 
-Evaluate the checks below. If ALL pass, respond `VALID`. Only fail for checks marked BLOCKING.
+Evaluate checks below. If ALL pass, respond `VALID`. Only fail for checks marked BLOCKING.
 
 ### Required Sections (BLOCKING)
 
-All of these sections must exist and contain real content (not just the heading):
+All these sections must exist and contain real content (not just the heading):
 `Overview`, `Goals`, `Non-Goals`, `User Stories & Acceptance Criteria`, `Technical Requirements`, `Implementation Scope`, `Task Breakdown`, `Success Criteria`, `Risks & Open Questions`.
 
 ### Structural Integrity (BLOCKING)
 
-- [ ] No two parallel workstreams (same phase) claim the same file
+- [ ] No two parallel workstreams (same phase) claim same file
 - [ ] No circular dependencies between phases
-- [ ] No conflicting requirements across sections (e.g., a Non-Goal contradicts a Technical Requirement)
+- [ ] No conflicting requirements across sections (e.g., Non-Goal contradicts Technical Requirement)
 - [ ] Section content is not placeholder/template text (e.g., "2–3 sentences about…", "Description here")
 
 ### Implementation Coherence (BLOCKING)
 
 - [ ] Implementation Scope lists specific files or subdirectories (not just `src/` or `the frontend`)
-- [ ] Each workstream lists the files it will modify
+- [ ] Each workstream lists files it will modify
 
 ---
 
 ## Output Format
 
-Your entire response must be a single fenced JSON block — no text before or after:
+Your entire response must be single fenced JSON block — no text before or after:
 
 ```json
 {

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

@@ -1,6 +1,6 @@
 ---
 name: accessibility-standards
-description: "WCAG 2.2 Level AA accessibility patterns for React/HTML/CSS. Use when creating or modifying UI components, forms, navigation, tables, images, or any user-facing elements. Covers keyboard navigation, screen reader semantics, low vision contrast, voice access, and inclusive language."
+description: "WCAG 2.2 Level AA accessibility patterns for React/HTML/CSS. Use when creating or modifying UI components, forms, navigation, tables, images, or any user-facing elements. Covers keyboard navigation, screen reader semantics, low vision contrast, voice access, inclusive language."
 ---
 
 # Accessibility Standards
@@ -13,7 +13,7 @@ Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
 
 ## Cognitive
 
-Plain language; consistent landmarks and nav order across pages; minimal distractions.
+Plain language; consistent landmarks, nav order across pages; minimal distractions.
 
 ## Keyboard
 
@@ -21,14 +21,14 @@ Plain language; consistent landmarks and nav order across pages; minimal distrac
 - No `tabindex` on static elements; `tabindex="-1"` only for elements receiving programmatic focus.
 - Hidden elements must not be focusable.
 
-**Composite components** and detailed complex patterns have been moved to REFERENCE.md to keep this skill focused. See REFERENCE.md for roving tabindex, `aria-activedescendant`, and composite widget examples.
+**Composite components** + detailed complex patterns moved to REFERENCE.md to keep this skill focused. See REFERENCE.md for roving tabindex, `aria-activedescendant`, composite widget examples.
 
 ### Validation checkpoints (run-fix-repeat)
 
-- Run an automated audit: `npx axe-core` or integrate `axe-core`/`axe-playwright` in CI — fix high/critical findings.
-- Verify keyboard tab order manually: `Tab` through the page, ensure logical order and visible focus.
-- Confirm contrast ratios (spot-check key pages): use `axe`, `pa11y`, or `contrast` tools and ensure ≥4.5:1 for body text.
-- Fix, re-run audits, and repeat until no high/critical a11y issues remain.
+- Run automated audit: `npx axe-core` or integrate `axe-core`/`axe-playwright` in CI — fix high/critical findings.
+- Verify keyboard tab order manually: `Tab` through page, ensure logical order, visible focus.
+- Confirm contrast ratios (spot-check key pages): use `axe`, `pa11y`, or `contrast` tools; ensure ≥4.5:1 for body text.
+- Fix; re-run audits; repeat until no high/critical a11y issues remain.
 
 **Skip link** (first focusable element):
 
@@ -66,7 +66,7 @@ Plain language; consistent landmarks and nav order across pages; minimal distrac
 ## Voice Access
 
 - Interactive element accessible name must contain its visible label text.
-- `aria-label` must include the visible label.
+- `aria-label` must include visible label.
 
 ## Forms
 

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-hooks
-description: "Four lifecycle hooks every agent runs: on-session-start scans LESSONS-LEARNED.md and resumes checkpoints, on-pre-delegate verifies tracker issues and file partitions, on-post-delegate runs fast-review and CI checks, on-session-end executes the session guard and writes logs. Use when starting a new session, running pre-flight checks before delegation, coordinating between agents, reviewing a completed handoff, or wrapping up a session. Trigger terms: multi-agent setup, delegate tasks, agent coordination, session management, run pre-flight checks, start a new session, coordinate between agents, wrap up session"
+description: "Four lifecycle hooks every agent runs: on-session-start scans LESSONS-LEARNED.md, resumes checkpoints; on-pre-delegate verifies tracker issues, file partitions; on-post-delegate runs fast-review, CI checks; on-session-end executes session guard, writes logs. Use when starting a new session, running pre-flight checks before delegation, coordinating between agents, reviewing a completed handoff, or wrapping up a session. Trigger terms: multi-agent setup, delegate tasks, agent coordination, session management, run pre-flight checks, start a new session, coordinate between agents, wrap up session"
 ---
 
 # Agent Lifecycle Hooks

package/src/orchestrator/skills/agent-memory/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: agent-memory
-description: "Creates and queries agent expertise profiles in AGENT-EXPERTISE.md, increments file-familiarity counters after each task, and ranks candidate agents by recency and task-area match. Use when deciding which agent should handle a file, checking who last worked on a module, recording task outcomes, or assigning work based on past performance."
+description: "Creates, queries agent expertise profiles in AGENT-EXPERTISE.md; increments file-familiarity counters after each task; ranks candidate agents by recency, task-area match. Use when deciding which agent should handle a file, checking who last worked on a module, recording task outcomes, or assigning work based on past performance."
 ---
 
 # Agent Memory Protocol
 
 ## Expertise File
 
-**Location:** `.opencastle/AGENT-EXPERTISE.md` — one section per agent with Strong Areas, Weak Areas, and File Familiarity tables.
+**Location:** `.opencastle/AGENT-EXPERTISE.md` — one section per agent with Strong Areas, Weak Areas, File Familiarity tables.
 
 Entry format: `Area | Evidence | Last Updated` — e.g. `Server Components | Built TAS-42 | 2026-03-15`. File familiarity: `- src/lib/search/ — 3 tasks`.
 
@@ -23,7 +23,7 @@ Entry format: `Area | Evidence | Last Updated` — e.g. `Server Components | Bui
 
 ## Retrieval & Delegation
 
-Query before delegating, then include a concise context block in the prompt:
+Query before delegating; include concise context block in prompt:
 
 ```sh
 grep -A5 "## Developer" .opencastle/AGENT-EXPERTISE.md
@@ -44,17 +44,17 @@ awk '/src\/lib\/search\// { if (match($0, /[0-9]+/)) { n = substr($0, RSTART, RL
 
 ## Workflow
 
-1. **Before delegating:** Read `.opencastle/AGENT-EXPERTISE.md`, check Strong/Weak areas, add concise `Agent Context` to the prompt.
-  - Validate: the selected agent has a Strong area matching the task or no conflicting Weak entries.
-2. **After task completes:** Update expertise (success → Strong, 2+ retries → Weak, files → Familiarity) and append file relationships to `.opencastle/KNOWLEDGE-GRAPH.md`.
-  - Validate: the expertise file contains the new entry and the timestamp is today's date.
-3. **On DLQ failure:** Add Weak Area with reference to the failure ID and link to logs.
-  - Validate: failure ID and link appear in the Weak Area entry.
+1. **Before delegating:** Read `.opencastle/AGENT-EXPERTISE.md`; check Strong/Weak areas; add concise `Agent Context` to prompt.
+  - Validate: selected agent has Strong area matching task or no conflicting Weak entries.
+2. **After task completes:** Update expertise (success → Strong, 2+ retries → Weak, files → Familiarity); append file relationships to `.opencastle/KNOWLEDGE-GRAPH.md`.
+  - Validate: expertise file contains new entry; timestamp is today's date.
+3. **On DLQ failure:** Add Weak Area with reference to failure ID, link to logs.
+  - Validate: failure ID, link appear in Weak Area entry.
 
 ## Pruning
 
-Prune entries older than 6 months, remove familiarity for deleted paths, and consolidate duplicates.
+Prune entries older than 6 months; remove familiarity for deleted paths; consolidate duplicates.
  - Validate: run `rg "— [0-9]+ tasks" .opencastle/AGENT-EXPERTISE.md` after pruning to confirm no stale paths remain.
 ## Knowledge Graph
 
-File dependency graph and cross-agent relationships. See [KNOWLEDGE-GRAPH.md](./KNOWLEDGE-GRAPH.md) for entity types, templates, triggers, and queries.
+File dependency graph, cross-agent relationships. See [KNOWLEDGE-GRAPH.md](./KNOWLEDGE-GRAPH.md) for entity types, templates, triggers, queries.

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

@@ -1,6 +1,6 @@
 ---
 name: api-patterns
-description: "Creates API route handlers, implements Server Actions with Zod schema validation, and integrates external REST APIs with error handling. Use when adding endpoints, building request handlers, or wiring external services (endpoint, REST API, request handling, fetch, .ts route files)."
+description: "Creates API route handlers, implements Server Actions with Zod schema validation, integrates external REST APIs with error handling. Use when adding endpoints, building request handlers, or wiring external services (endpoint, REST API, request handling, fetch, .ts route files)."
 ---
 
 # API Patterns
@@ -66,9 +66,9 @@ export async function submitAction(formData: FormData) {
 
 ## Quick Workflow
 1. Create route file: `app/api/<name>/route.ts` or `app/<segment>/route.ts`
-2. Add a Zod schema and validate input at the top of the handler
+2. Add Zod schema; validate input at top of handler
 3. Implement handler logic with explicit error/response shapes
-4. Add unit/integration tests for validation and happy/error paths
+4. Add unit/integration tests for validation, happy/error paths
 5. Verification: run a quick smoke test (example):
 
 ```bash
@@ -78,11 +78,11 @@ curl -fsS "http://localhost:3000/api/<name>?query=test" || (echo "route failed"
 ## Design Rules
 
 - Server Actions for mutations; Route Handlers for external/public endpoints
-- Validate all input with Zod on the server
+- Validate all input with Zod on server
 - RESTful nouns: `/api/v1/places/:slug`; HTTP methods: `GET` read, `POST` create, `PATCH` update, `DELETE` remove
 - Response envelope: `{ "data": ..., "meta": { "total": 42, "page": 1 } }`
 - Error shape: `{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }`
 - Status codes: 400, 401, 403, 404, 422, 429, 500 — never leak stack traces
 - Pagination: cursor-based preferred; params: `limit`, `cursor`, `sort`, `order`
 - Versioning: `/api/v1/...`; add fields only, never remove/rename; deprecation headers before removal
-- Rate-limit public endpoints; set `Cache-Control` and `ETag`/`If-None-Match` headers
+- Rate-limit public endpoints; set `Cache-Control`, `ETag`/`If-None-Match` headers

package/src/orchestrator/skills/backbone-scaffolding/SKILL.md

@@ -12,7 +12,7 @@ description: "Scaffolds production-ready monorepo projects using the backbone CL
 
 ## How to Use the CLI
 
-Backbone is **interactive** — it uses `@clack/prompts` to ask a series of questions. Agents must run the command and respond to each prompt in sequence.
+Backbone is **interactive** — uses `@clack/prompts` to ask series of questions. Agents must run command, respond to each prompt in sequence.
 
 ### Prompt Sequence
 
@@ -46,70 +46,43 @@ Backbone is **interactive** — it uses `@clack/prompts` to ask a series of ques
 
 ## OpenCastle TechTool → Backbone Mapping
 
-Most TechTool names map 1:1 to backbone prompt choices (e.g. `nextjs` → select Next.js, `supabase` → select Supabase). Exceptions:
+Most TechTool names map 1:1 to backbone prompt choices (e.g. `nextjs` → Next.js, `supabase` → Supabase). Non-1:1 exceptions:
 
-| TechTool | Backbone mapping | Notes |
-|----------|-----------------|-------|
-| `resend` | Select `emailLib` in Packages prompt | Only non-obvious mapping |
-| `drizzle` | Select `drizzle` in Backend prompt | Direct 1:1 mapping |
-| `cloudflare` | Select `cloudflare` in Deployment prompt | Direct 1:1 mapping |
-| `coolify` | Select `coolify` in Deployment prompt | Direct 1:1 mapping |
-| `expo` | Select `expo` in Mobile prompt | Direct 1:1 mapping; incompatible with `astro` |
-| `stripe` | Select `stripe` in Payments prompt | Direct 1:1 mapping |
-| `sentry` | Select `sentry` in Observability prompt | Direct 1:1 mapping |
-| `vitest` | — | Always included automatically |
-| `figma`, `chrome-devtools` | — | Not handled by backbone; configure separately |
+| TechTool | Backbone mapping |
+|----------|-----------------|
+| `resend` | `emailLib` in Packages prompt |
+| `vitest` | Always included automatically |
+| `figma`, `chrome-devtools` | Not handled by backbone; configure separately |
 
 ## Generated Project Structure
 
-After backbone runs, the output directory contains:
+`apps/` (`web`, conditional `mobile`), `packages/` (conditional `ui`, `email`, `llm`, `stripe`), `backend/` (one of `convex`/`supabase`/`prisma`/`drizzle`), `e2e/`, `.github/workflows/`. Always at root: `vitest.config.ts`, `tsconfig.base.json`, `package.json`, `turbo.json`/`nx.json`, ESLint, Prettier. Conditional root files: `wrangler.toml` (cloudflare), `Dockerfile` (coolify), `sentry.*.config.ts` (sentry, in `apps/web/`).
 
-```
-<project-name>/
-  apps/
-    web/          # Next.js or Astro application
-    mobile/       # (if ionic or expo selected)
-  packages/
-    ui/           # (if uiLib selected) shared React component library
-    email/        # (if emailLib selected) Resend/React Email package
-    llm/          # (if llmLib selected) LLM integration package
-    stripe/       # (if stripe selected) Stripe client + webhook handler
-  backend/
-    convex/       # (if convex selected)
-    supabase/     # (if supabase selected)
-    prisma/       # (if prisma selected)
-    drizzle/      # (if drizzle selected) schema, config, migrations
-  e2e/            # Playwright or Cypress tests
-  .github/
-    workflows/    # GitHub Actions CI pipelines (always included)
-  vitest.config.ts          # Always included
-  tsconfig.base.json        # Always included
-  package.json              # Monorepo root package.json
-  turbo.json / nx.json      # Monorepo tool config
-  wrangler.toml             # (if cloudflare selected)
-  Dockerfile                # (if coolify selected)
-  sentry.*.config.ts        # (if sentry selected) in apps/web/
-```
-
-**Always included regardless of options:** Vitest configuration, GitHub Actions CI workflows, root `tsconfig.base.json`, ESLint, Prettier.
-
-Agents working on post-scaffolding tasks must **not recreate** any of these files — they already exist. Build on top of the generated structure.
+Agents on post-scaffolding tasks **must not recreate** these — they already exist. Import and extend.
 
 ## Post-Scaffolding Steps
 
 After `npx @monkilabs/backbone <project-name>` completes:
 
-1. `cd <project-name>` into the generated directory
-2. Run `npm install` to install all dependencies
-3. Verify the project builds: run the monorepo build command (e.g. `npx turbo build` or `npx nx build`)
-4. All subsequent agent tasks should **import and extend** the generated boilerplate — never overwrite it
+1. `cd <project-name>` into generated directory
+2. Run `npm install` for all dependencies
+3. Verify project builds: run monorepo build command (e.g. `npx turbo build` or `npx nx build`)
+4. All subsequent agent tasks should **import and extend** generated boilerplate — never overwrite
 
 **If something fails:**
 - `npm install` errors → verify Node.js >= 22.5.0 (`node -v`)
-- Build errors → check that no incompatible options were selected (see Astro constraint above); re-run backbone with corrected choices if needed
-- Wrong option selected → delete the generated directory and re-run `npx @monkilabs/backbone` with the correct selections
+- Build errors → check no incompatible options selected (see Astro constraint above); re-run backbone with corrected choices if needed
+- Wrong option selected → delete generated directory; re-run `npx @monkilabs/backbone` with correct selections
 
 ## Example Convoy Task
 
-See [EXAMPLES.md](EXAMPLES.md) for a complete scaffolding task JSON.
+```json
+{
+  "id": "scaffold-monorepo",
+  "agent": "developer",
+  "prompt": "Run `npx @monkilabs/backbone my-app` interactively. Select: nx · nextjs · supabase · sanity · playwright · vercel · uiLib · stripe · sentry. Then `cd my-app && npm install && npx nx build`. Verify clean build before continuing.",
+  "files": ["my-app/"],
+  "timeout": "30m"
+}
+```
 

package/src/orchestrator/skills/code-commenting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-commenting
-description: "Guidelines for writing self-explanatory code with minimal comments. Covers when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, and public API documentation. Use when writing or reviewing code comments, docstrings, TODO/FIXME tags, code readability, or inline comments."
+description: "Guidelines for writing self-explanatory code with minimal comments. Covers when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, public API documentation. Use when writing or reviewing code comments, docstrings, TODO/FIXME tags, code readability, or inline comments."
 ---
 
 # Code Commenting
@@ -78,6 +78,6 @@ function calculateCompoundInterest(principal, rate, time, n = 1) { ... }
 ## Checklist
 
 - [ ] Explains WHY, not WHAT
-- [ ] Still accurate after the change
+- [ ] Still accurate after change
 - [ ] Adds genuine value
-- [ ] Placed above the code it describes
+- [ ] Placed above code it describes

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

@@ -1,8 +1,8 @@
 > Parent: [SKILL.md](./SKILL.md)
 
-Context Map REFERENCE: full markdown template, Team Lead integration snippet, and partition examples.
+Context Map REFERENCE: full markdown template, Team Lead integration snippet, partition examples.
 
-Use this file for the verbose context-map template referenced from `SKILL.md`.
+Use this file for verbose context-map template referenced from `SKILL.md`.
 ## Context Map Template
 
 ## Context Map: [Task Name]

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

@@ -1,11 +1,11 @@
 ---
 name: context-map
-description: "Maps file dependencies, flags shared imports, and groups files for safe parallel editing before code changes. Use when planning a refactoring, analyzing change impact, or understanding which files a modification will affect."
+description: "Maps file dependencies, flags shared imports, groups files for safe parallel editing before code changes. Use when planning a refactoring, analyzing change impact, or understanding which files a modification will affect."
 ---
 
 # Skill: Context Map
 
-Generate a **file impact map** before code changes to identify affected files, relationships, and cascades — improving agent file partitions for parallel work.
+Generate **file impact map** before code changes to identify affected files, relationships, cascades — improves agent file partitions for parallel work.
 
 ## When to Use
 
@@ -19,7 +19,7 @@ Generate a **file impact map** before code changes to identify affected files, r
 ## Steps
 
 ### 1 — Entry Points
-Identify files that MUST change from the task description.
+Identify files that MUST change from task description.
 
 ### 2 — Trace Outward (dependents)
 Find consumers of entry-point exports:
@@ -38,7 +38,7 @@ grep_search("from.*config", includePattern="src/places/**")  # config deps
 
 ### 4 — Build the Map
 
-Produce a compact Context Map for the Team Lead and downstream agents. Example minimal map (inline):
+Produce compact Context Map for Team Lead, downstream agents. Example minimal map (inline):
 
 ```markdown
 Context Map — Feature: Add priceRange
@@ -59,7 +59,7 @@ Context Map — Feature: Add priceRange
 	- src/components/Account/**
 ```
 
-Validation checkpoint: run `grep_search` and `vscode_listCodeUsages` results into the map and confirm all listed files open without errors (CI: `pnpm typecheck`). For full template and Team Lead integration snippets see REFERENCE.md in this directory.
+Validation checkpoint: run `grep_search`, `vscode_listCodeUsages` results into map; confirm all listed files open without errors (CI: `pnpm typecheck`). For full template, Team Lead integration snippets see REFERENCE.md in this directory.
 
 ## Anti-Patterns
 

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

@@ -1,11 +1,11 @@
 ---
 name: data-engineering
-description: "Transforms, validates, and loads data in ETL pipelines. Use when building scrapers, validating NDJSON feeds, or importing data into CMS/DB targets."
+description: "Transforms, validates, loads data in ETL pipelines. Use when building scrapers, validating NDJSON feeds, or importing data into CMS/DB targets."
 ---
 
 # Data Engineering
 
-Generic pipeline patterns. For project-specific sources and full schema references see [REFERENCE.md](./REFERENCE.md).
+Generic pipeline patterns. For project-specific sources, full schema references see [REFERENCE.md](./REFERENCE.md).
 
 ## Scraper Architecture
 
@@ -26,17 +26,17 @@ One record per line. Schema:
 
 ## Recommended Workflow (numbered, with validation)
 
-1. Scrape: run scraper in `--dry-run` to collect a sample (50–200 records).
-   - Checkpoint: sample contains expected fields and geo data.
-   - Recovery: fix extractor selectors, re-run sample.
+1. Scrape: run scraper in `--dry-run` to collect sample (50–200 records).
+   - Checkpoint: sample contains expected fields, geo data.
+   - Recovery: fix extractor selectors; re-run sample.
 2. Validate NDJSON: run line-by-line JSON parse + schema validator (see `validate-ndjson.js` example).
    - Checkpoint: 0 parse errors, required fields present.
-   - Recovery: run `ndjson-filter` to isolate failing records and inspect source HTML.
-3. Dry-run import: import into staging with `createOrReplace` disabled; check counts and duplicates.
-   - Checkpoint: counts match expectation ±5% and no duplicates inserted.
-   - Recovery: revert staging and adjust dedupe key.
-4. Backup: snapshot current target (DB export) and store with timestamp.
-5. Import: run import with idempotent keys and monitor logs; on failure revert to backup.
+   - Recovery: run `ndjson-filter` to isolate failing records; inspect source HTML.
+3. Dry-run import: import into staging with `createOrReplace` disabled; check counts, duplicates.
+   - Checkpoint: counts match expectation ±5%; no duplicates inserted.
+   - Recovery: revert staging; adjust dedupe key.
+4. Backup: snapshot current target (DB export); store with timestamp.
+5. Import: run import with idempotent keys; monitor logs; on failure revert to backup.
 
 ## Quick executable pipeline (copy & adapt)
 
@@ -59,5 +59,5 @@ if (errors) { console.error(`${errors} errors`); process.exit(2); }
 console.log('OK');
 ```
 
-Full scraper and extended validator: see [REFERENCE.md](./REFERENCE.md).
+Full scraper, extended validator: see [REFERENCE.md](./REFERENCE.md).