opencastle 0.32.12 → 0.33.0

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

@@ -1,6 +1,6 @@
 ---
 name: agent-hooks
-description: "Lifecycle hooks for AI agent sessions — reusable actions that run at specific points (session start, session end, pre-delegation, post-delegation). Defines what to do at each lifecycle event so agents behave consistently."
+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"
 ---
 
 # Agent Lifecycle Hooks
@@ -15,88 +15,64 @@ on-session-start → [work loop] → on-session-end
 
 ---
 
-## on-session-start — First action in any session
 
-| # | Action | Detail |
-|---|--------|--------|
-| 1 | Read lessons | Scan `.opencastle/LESSONS-LEARNED.md` for task-relevant entries. |
-| 2 | Check checkpoint | If `.opencastle/SESSION-CHECKPOINT.md` exists, resume from it. |
-| 3 | Check pending approvals | If checkpoint has `## Pending Approvals`, check replies via messaging provider (`stack.teamTools` in `.opencastle.json`). Skip if no messaging configured. |
-| 4 | Check DLQ | Scan `.opencastle/AGENT-FAILURES.md` for failures in current scope. |
-| 5 | Validate skill-matrix | Open `.opencastle/agents/skill-matrix.json` — if all `bindings` entries are empty, **warn** user to run *"Bootstrap Customizations"* prompt first. |
-| 6 | Check project context | If `.opencastle/project.instructions.md` has only empty template rows, warn bootstrap hasn't run. |
-| 7 | Load domain skills | Load appropriate skills before writing code. |
+## on-session-start
 
-**Delegation reminder:**
-```
-Session Start: Read `.opencastle/LESSONS-LEARNED.md`. Check `.opencastle/SESSION-CHECKPOINT.md` for prior state and pending approvals. Validate `.opencastle/agents/skill-matrix.json` — warn if bindings empty. Load relevant skills before coding.
-```
+| # | Action |
+|---|--------|
+| 1 | `rg -n "keyword" .opencastle/LESSONS-LEARNED.md` |
+| 2 | `cat .opencastle/SESSION-CHECKPOINT.md` (resume if exists) |
+| 3 | `rg -n "ERROR\|FAIL" .opencastle/AGENT-FAILURES.md \|\| true` |
+| 4 | `cat .opencastle/agents/skill-matrix.json \| jq '.bindings'` — load domain skills |
 
----
+See [HOOKS-REFERENCE.md](HOOKS-REFERENCE.md) for extended startup checks (approval polling, skill-matrix verification).
 
-## on-session-end — Before yielding control, every time unconditionally
+---
 
-> **⛔ HARD GATE** — See [logging-mandatory](../../snippets/logging-mandatory.md). Run the Pre-Response Quality Gate from the **observability-logging** skill.
+## on-session-end
 
-| # | Action | Who |
-|---|--------|-----|
-| 1 | Call Session Guard with session summary; execute fix commands it returns | Team Lead only |
-| 2 | Run Pre-Response Quality Gate checklist from **observability-logging** skill | Specialists only |
-| 3 | Write `.opencastle/SESSION-CHECKPOINT.md` if work is incomplete (load **session-checkpoints** skill) | Team Lead only |
-| 4 | Flag for memory merge if 5+ new lessons this session | All |
-| 5 | Remove temp files created during session | All |
+> **⛔ HARD GATE** — See [logging-mandatory](../../snippets/logging-mandatory.md). Load **observability-logging** for the Pre-Response Quality Gate.
 
-**Delegation reminder (specialists):**
-```
-Session End: Log session via observability-logging skill (Constitution rule #6). Add lesson via self-improvement if retried. Track discovered issues in KNOWN-ISSUES.md or tracker. Clean up temp files.
-```
+| # | Action |
+|---|--------|
+| 1 | `opencastle doctor --fix` (session guard) |
+| 2 | `opencastle log --type session ...` |
+| 3 | Write `.opencastle/SESSION-CHECKPOINT.md` if work is incomplete |
+| 4 | Flag for memory merge if 5+ new lessons |
 
 ---
 
-## on-pre-delegate — Team Lead only, before every delegation
+## on-pre-delegate — Team Lead only
+
+| # | Check |
+|---|-------|
+| 1 | Tracker issue exists (`gh issue view TAS-XX`) |
+| 2 | File partition clean (`comm -12 <(sort agent1-files) <(sort agent2-files)` = empty) |
+| 3 | Upstream deps Done (`gh issue view TAS-XX --json state -q '.state'` = CLOSED) |
+| 4 | Prompt has exact file paths + acceptance criteria |
+| 5 | Prompt includes "Read LESSONS-LEARNED.md first" |
+| 6 | 5+ files → load **context-map** skill |
 
-Run the 5-point Pre-Delegation Checks from the Team Lead agent file: (1) Tracker issue exists, (2) File partition clean, (3) Dependencies verified Done, (4) Prompt has file paths + acceptance criteria, (5) Self-improvement reminder included. For 5+ files, generate a context map.
+All 6 must pass before `runSubagent`. See [HOOKS-REFERENCE.md](HOOKS-REFERENCE.md) for example commands per check.
 
-## on-post-delegate — Team Lead only, after receiving delegation results
+## on-post-delegate — Team Lead only
 
 | # | Action |
 |---|--------|
-| 0 | **⛔ Log delegation** via observability-logging skill — BLOCKING |
-| 1 | **Fast review (mandatory)** — run `fast-review` skill; **⛔ log review** — BLOCKING. Escalate to panel if needed; **⛔ log panel** — BLOCKING |
-| 2 | Read changed files; verify within file partition |
-| 3 | Run lint, type-check, tests |
-| 4 | Verify each acceptance criterion against tracker issue |
-| 5 | Confirm Discovered Issues Policy followed (KNOWN-ISSUES.md or tracker ticket) |
-| 6 | If agent retried, verify lesson added via **self-improvement** skill |
-| 7 | Move issue to Done or re-delegate; on 3rd failure → log to `.opencastle/AGENT-FAILURES.md` |
-| 8 | Update `.opencastle/AGENT-EXPERTISE.md` (strong/weak area + file familiarity) |
-| 9 | Append file relationships to `.opencastle/KNOWLEDGE-GRAPH.md` |
-
-**Quick checklist:**
-```
-☐ ⛔ Delegation logged (verify: tail -1 events.ndjson) — BLOCKING
-☐ Changed files reviewed; within partition
-☐ Lint/test/build passes
-☐ Fast review PASS; ⛔ Review logged — BLOCKING
-☐ ⛔ Panel logged if escalated — BLOCKING
-☐ Acceptance criteria met
-☐ Discovered issues tracked
-☐ Lessons captured (if retries)
-☐ Issue updated
-☐ AGENT-EXPERTISE.md updated
-☐ KNOWLEDGE-GRAPH.md appended
-```
+| 1 | **⛔** `opencastle log --type=delegation --issue=TAS-XX --status=complete` |
+| 2 | Run **fast-review** skill |
+| 3 | `pnpm lint && pnpm typecheck && pnpm test` |
+| 4 | `gh issue view TAS-XX --json body -q '.body'` — verify each AC met |
+| 5 | If agent retried → verify lesson added via **self-improvement** |
+| 6 | Move to Done or re-delegate; 3rd failure → `.opencastle/AGENT-FAILURES.md` |
+
+See [HOOKS-REFERENCE.md](HOOKS-REFERENCE.md) for detailed verification commands.
 
 ---
 
 ## Anti-Patterns
 
-| Anti-pattern | Why it matters |
+| Anti-pattern | Impact |
 |---|---|
-| Skipping on-session-start | Repeated mistakes already in lessons learned |
-| Forgetting session logging | Observability dashboard empty; #1 most common failure |
-| Treating logging as optional | Every session logged — no threshold, no exceptions |
-| Batch-logging retrospectively | Log each task as it completes, not all at end |
-| Partial post-delegate checks | Must verify acceptance criteria, not just "it compiled" |
-| No cleanup | Temp files accumulate and confuse future sessions |
-| Hooks as blockers | Hooks add ~2 min overhead — skip optional parts if needed |
+| Batch-logging retrospectively | Loses per-task provenance |
+| Partial post-delegate checks | False positives — build passes but ACs fail |

package/src/orchestrator/skills/agent-memory/KNOWLEDGE-GRAPH.md

@@ -0,0 +1,49 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Knowledge Graph Reference
+
+File dependency graph and cross-agent relationships stored in `.opencastle/KNOWLEDGE-GRAPH.md`.
+
+## Entity Types
+
+| Entity | Format | Example |
+|--------|--------|---------|
+| **File** | `[file:path/to/file.ts]` | `[file:src/components/Button.tsx]` |
+| **Agent** | `[agent:Name]` | `[agent:Developer]` |
+| **Task** | `[task:TAS-XX]` | `[task:TAS-42]` |
+
+## Relationship Types
+
+| Relationship | Meaning |
+|-------------|---------|
+| `imports` | File A imports from File B |
+| `renders` | Component A renders Component B |
+| `queries` | File reads from data source |
+| `mutates` | File writes to data source |
+| `tested-by` | Source file tested by test file |
+| `owned-by` | File primarily maintained by agent |
+
+## Entry Template
+
+```markdown
+## [file:src/components/PriceFilter.tsx]
+- imports: [file:src/hooks/useFilters.ts], [file:src/lib/api.ts]
+- renders: [file:src/components/ui/Slider.tsx]
+- tested-by: [file:src/components/PriceFilter.test.tsx]
+- owned-by: [agent:Developer] (TAS-42, 2026-03-30)
+```
+
+## Triggers
+
+| Event | Action |
+|-------|--------|
+| New file created | Add node + import edges |
+| File deleted | Remove node + all edges |
+| Agent completes task | Update `owned-by` with task ID and date |
+| Delegation | Query graph for related files to include in prompt |
+
+## Queries
+
+- **What depends on X?** — Find all files with `imports: [file:X]`
+- **Who last touched X?** — Check `owned-by` for the most recent task
+- **What's the blast radius?** — Traverse `imports`/`renders` edges transitively

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

@@ -1,97 +1,60 @@
 ---
 name: agent-memory
-description: "Agent expertise tracking and cross-session knowledge graph. Use when delegating tasks to track agent strengths/weaknesses, or when building context about file relationships and patterns."
+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."
 ---
 
 # Agent Memory Protocol
 
 ## Expertise File
 
-**Location:** `.opencastle/AGENT-EXPERTISE.md`
+**Location:** `.opencastle/AGENT-EXPERTISE.md` — one section per agent with Strong Areas, Weak Areas, and File Familiarity tables.
 
-```markdown
-# Agent Expertise Registry
-
-## Developer
-### Strong Areas
-| Area | Evidence | Last Updated |
-|------|----------|-------------|
-| Feature implementation | Built 5 pages (TAS-XX, TAS-YY) | YYYY-MM-DD |
-
-### Weak Areas
-| Area | Evidence | Last Updated |
-|------|----------|-------------|
-| Styling | 2 retries on TAS-AA | YYYY-MM-DD |
-
-### File Familiarity
-- `apps/web-app/places/` — 3 tasks
-```
+Entry format: `Area | Evidence | Last Updated` — e.g. `Server Components | Built TAS-42 | 2026-03-15`. File familiarity: `- src/lib/search/ — 3 tasks`.
 
 ## Update Triggers
 
 | Trigger | Action |
 |---------|--------|
-| First-attempt success | Add/update Strong Area |
-| 2+ retries | Add/update Weak Area |
-| File modified | Increment File Familiarity |
-| DLQ failure | Add Weak Area with ref |
+| First-attempt success | Update Strong |
+| 2+ retries | Update Weak |
+| File modified | Increment familiarity |
+| DLQ failure | Add Weak with ref |
 | >3 months stale | Mark as "stale" |
 
 ## Retrieval & Delegation
 
-Check `.opencastle/AGENT-EXPERTISE.md` before delegating. Add to prompt:
+Query before delegating, then include a concise context block in the prompt:
 
+```sh
+grep -A5 "## Developer" .opencastle/AGENT-EXPERTISE.md
 ```
-### Agent Context
-- Strong: Server Components, CMS queries (3 tasks)  → "Prior experience from TAS-XX."
-- Weak: Component styling (retry TAS-AA)            → add context or reassign
-- Familiar: libs/queries/src/lib/search/ (2 tasks)  → "You've worked on [file] in TAS-XX."
-```
-
-## Pruning
 
-- Remove entries >6 months old; consolidate repetitive entries; remove familiarity for deleted files
-- Prune at start of major feature work
+Example prompt block: `Agent Context: Strong — Server Components (3 tasks); Weak — Component styling (2 retries); Familiar — src/lib/search/ (2 tasks)`
 
-## Knowledge Graph
+**Update after task completion:**
 
-**Location:** `.opencastle/KNOWLEDGE-GRAPH.md` (append-only)
+```bash
+# Append a Strong Area entry
+printf '| %s | %s | %s |\n' "Server Components" "Built TAS-42" "$(date +%Y-%m-%d)" >> .opencastle/AGENT-EXPERTISE.md
 
-### Entities & Relationships
-
-| Entity | Notation | Relationships |
-|--------|----------|--------------|
-| File | `F:path` | `depends-on`, `blocks` |
-| Agent | `A:name` | `expert-in` |
-| Pattern/Decision | `P:name` / `D:name` | `related-to`, `obsoletes` |
-| Bug/Lesson | `B:id` / `L:id` | `caused-by`, `related-to` |
-
-### Graph Template
-
-```markdown
-# Knowledge Graph
-## Relationships
-| Source | Relationship | Target | Added | Context |
-|--------|-------------|--------|-------|---------|
-| A:Content Engineer | expert-in | P:CMS-queries | 2026-02-23 | 3 tasks |
-| F:searchModule.ts | depends-on | F:cms-client.ts | 2026-02-23 | |
+# Increment file familiarity
+awk '/src\/lib\/search\// { if (match($0, /[0-9]+/)) { n = substr($0, RSTART, RLENGTH) + 1; sub(/[0-9]+[[:space:]]*tasks?/, n " tasks") } found=1 } {print} END { if(!found) print "- `src/lib/search/` — 1 task" }' \
+  .opencastle/AGENT-EXPERTISE.md > tmp && mv tmp .opencastle/AGENT-EXPERTISE.md
 ```
 
-### Add Relationships When
+## Workflow
 
-| Trigger | Record |
-|---------|--------|
-| Task touches multiple files | `depends-on` |
-| Lesson relates to a pattern | `related-to` |
-| Agent demonstrates expertise | `expert-in` |
-| Decision causes known issue | `caused-by` |
-| Pattern supersedes old approach | `obsoletes` |
+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.
 
-### Pre-Delegation Queries
-
-Follow `depends-on` for related reads, `expert-in` to confirm agent, `related-to` for patterns, `blocks` for known issues.
+## Pruning
 
-### Maintenance
+Prune entries older than 6 months, remove familiarity for deleted paths, and consolidate duplicates.
+ - Validate: run `rg "— [0-9]+ tasks" .opencastle/AGENT-EXPERTISE.md` after pruning to confirm no stale paths remain.
+## Knowledge Graph
 
-- Add as discovered; prune between sessions
-- Max ~100 active relationships; archive quarterly
+File dependency graph and cross-agent relationships. See [KNOWLEDGE-GRAPH.md](./KNOWLEDGE-GRAPH.md) for entity types, templates, triggers, and queries.

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

@@ -1,6 +1,6 @@
 ---
 name: api-patterns
-description: "API design patterns for route handlers, Server Actions, Zod validation, and external API integration. Use when creating API routes, Server Actions, or integrating external services."
+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)."
 ---
 
 # API Patterns
@@ -30,6 +30,23 @@ export async function GET(request: NextRequest) {
   if (!result.success) return NextResponse.json({ error: 'Invalid input' }, { status: 400 });
   return NextResponse.json(data);
 }
+
+```
+
+### Fetching external APIs — example with retry and error handling
+
+```ts
+import fetch from 'node-fetch';
+async function fetchWithRetry(url:string, opts={}, retries=2){
+  for(let i=0;i<=retries;i++){
+    try{ const res = await fetch(url, opts); if(!res.ok) throw new Error(`HTTP ${res.status}`); return await res.json(); }
+    catch(e){ if(i===retries) throw e; await new Promise(r=>setTimeout(r, 500*(i+1))); }
+  }
+}
+
+// usage
+const data = await fetchWithRetry('https://api.example.com/data');
+```
 ```
 
 ### Server Action
@@ -47,6 +64,17 @@ 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
+3. Implement handler logic with explicit error/response shapes
+4. Add unit/integration tests for validation and happy/error paths
+5. Verification: run a quick smoke test (example):
+
+```bash
+curl -fsS "http://localhost:3000/api/<name>?query=test" || (echo "route failed" && exit 1)
+```
+
 ## Design Rules
 
 - Server Actions for mutations; Route Handlers for external/public endpoints

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

@@ -0,0 +1,16 @@
+# backbone-scaffolding Examples
+
+## Convoy Scaffolding Task
+
+```json
+{
+  "id": "scaffolding",
+  "description": "Scaffold monorepo with backbone CLI",
+  "agent": "developer",
+  "complexity": 2,
+  "prompt": "Scaffold the project monorepo using the backbone CLI. Ensure Node.js >= 22.5.0 is available. Run: `npx @monkilabs/backbone my-project` and select the following options when prompted:\n- Monorepo: Turborepo\n- Framework: Next.js\n- Backend: Supabase\n- CMS: Sanity\n- Testing: Playwright\n- Deployment: Vercel\n- Mobile: None\n- Packages: Email Library, LLM Library\n\nAfter scaffolding completes, run `npm install` in the generated `my-project/` directory. Then run `npx turbo build` and verify it exits 0.",
+  "files": ["my-project/"]
+}
+```
+
+All subsequent tasks should declare `depends_on: ["scaffolding"]` and build on the generated structure.

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

@@ -0,0 +1,99 @@
+---
+name: backbone-scaffolding
+description: "Scaffolds production-ready monorepo projects using the backbone CLI: configures workspace packages, wires build tooling, sets up CI pipelines, and initializes framework/backend/CMS integrations. Use when creating, bootstrapping, or initializing a new application, project, starter template, or monorepo from scratch. Trigger terms: scaffold, bootstrap, init, new repo, new app, boilerplate, starter, greenfield."
+---
+
+# backbone-scaffolding Skill
+
+## Requirements
+
+- Node.js **>= 22.5.0** must be available in the environment
+- Run backbone with `npx @monkilabs/backbone <project-name>`
+
+## 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.
+
+### Prompt Sequence
+
+1. **Monorepo tool** — `nx` or `turborepo`
+2. **Framework** — `nextjs` or `astro`
+3. **Backend** — `convex`, `supabase`, `prisma`, or `none`
+4. **CMS** — `sanity`, `contentful`, `strapi`, or `none`
+5. **E2E Testing** — `playwright` or `cypress`
+6. **Deployment** — `vercel`, `netlify`, or `none`
+7. **Mobile** — `ionic` or `none` *(only shown for non-Astro frameworks)*
+8. **Packages** — multi-select: `uiLib`, `emailLib`, `llmLib`
+
+## CLI Options & Constraints
+
+| Category    | Choices                                   | Notes                                    |
+|-------------|-------------------------------------------|------------------------------------------|
+| Monorepo    | `nx`, `turborepo`                         | Required                                 |
+| Framework   | `nextjs`, `astro`                         | Required                                 |
+| Backend     | `convex`, `supabase`, `prisma`            | ⛔ `convex` incompatible with `astro`    |
+| CMS         | `sanity`, `contentful`, `strapi`, `none`  | Optional                                 |
+| E2E Testing | `playwright`, `cypress`                   | Required                                 |
+| Deployment  | `vercel`, `netlify`, `none`               | Optional                                 |
+| Mobile      | `ionic`, `none`                           | ⛔ `ionic` incompatible with `astro`     |
+| Packages    | `uiLib`, `emailLib`, `llmLib`             | Multi-select; ⛔ `uiLib` incompatible with `astro` |
+
+**Astro constraint:** `astro` requires React-free options — never combine with `convex`, `ionic`, or `uiLib`.
+
+## OpenCastle TechTool → Backbone Mapping
+
+Most TechTool names map 1:1 to backbone prompt choices (e.g. `nextjs` → select Next.js, `supabase` → select Supabase). Exceptions:
+
+| TechTool | Backbone mapping | Notes |
+|----------|-----------------|-------|
+| `resend` | Select `emailLib` in Packages prompt | Only non-obvious mapping |
+| `vitest` | — | Always included automatically |
+| `figma`, `chrome-devtools` | — | Not handled by backbone; configure separately |
+
+## Generated Project Structure
+
+After backbone runs, the output directory contains:
+
+```
+<project-name>/
+  apps/
+    web/          # Next.js or Astro application
+    mobile/       # (if ionic 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
+  backend/
+    convex/       # (if convex selected)
+    supabase/     # (if supabase selected)
+  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
+```
+
+**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.
+
+## 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
+
+**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
+
+## Example Convoy Task
+
+See [EXAMPLES.md](EXAMPLES.md) for a complete scaffolding task JSON.
+

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."
+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."
 ---
 
 # Code Commenting

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

@@ -0,0 +1,70 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Context Map REFERENCE: full markdown template, Team Lead integration snippet, and partition examples.
+
+Use this file for the verbose context-map template referenced from `SKILL.md`.
+## Context Map Template
+
+## Context Map: [Task Name]
+
+### Entry Points (MUST change)
+| File | Reason | Owner |
+|------|--------|-------|
+| `libs/queries/src/lib/places.ts` | Add query field | Content Engineer |
+| `libs/ui-kit/.../PlaceCard/` | Display new field | UI/UX Expert |
+
+### Cascade Effects (WILL change)
+| File | Triggered By | Reason | Owner |
+|------|-------------|--------|-------|
+| `apps/web-app/places/page.tsx` | PlaceCard | Update props | Frontend Dev |
+| `libs/queries/src/lib/__tests__/places.test.ts` | Query | Update test | Testing Expert |
+
+### Shared Boundaries (WATCH)
+| File | Risk | Mitigation |
+|------|------|------------|
+| `libs/ui-kit/src/lib/index.ts` | Barrel export conflict | Merge sequentially |
+
+### Unaffected (optional)
+| Area | Why |
+|------|-----|
+| `db/migrations/` | No DB changes |
+| `libs/auth/` | No auth changes |
+
+### 4b — Validate Map
+- [ ] Every file appears in exactly one section (Entry/Cascade/Shared/Unaffected)
+- [ ] No file appears in two agents' partitions
+- [ ] Test files are listed for every changed source file
+- [ ] Shared boundaries have explicit mitigation strategies
+
+### 5 — Derive File Partitions
+
+Assign ownership — no file in two partitions; shared boundaries to one agent (merged first); test files to Testing Expert unless tightly coupled.
+
+```
+Agent A: libs/queries/src/lib/places.ts
+Agent B: libs/ui-kit/.../PlaceCard/
+Agent C: apps/web-app/places/, apps/admin-panel/places/
+Agent D: **/*test*, **/*spec*
+```
+
+## Depth Levels
+
+| Complexity | Files | Depth |
+|------------|-------|-------|
+| Small | 1–3 | Entry points + direct imports |
+| Medium | 4–8 | Entry + 1-hop cascade |
+| Large | 9+ | Full dependency graph |
+
+## Team Lead Integration
+
+Produced in **Phase 1**; consumed by:
+- **Decomposition** — informs file partitions
+- **Delegation prompts** — agents receive their map section
+- **QA Gate** — compare actual changes against map to detect scope creep
+
+Delegation prompt snippet:
+```markdown
+## Your File Partition
+Modify only: `libs/queries/src/lib/places.ts`, `libs/queries/src/lib/__tests__/places.test.ts`
+Do NOT modify: `libs/ui-kit/` (UI/UX Expert), `apps/` (Developer)
+```