@geraldmaron/construct 1.0.4 → 1.0.6

package/skills/exploration/repo-map.md

@@ -1,9 +1,9 @@
 <!--
-skills/exploration/repo-map.md — Repo Exploration — Codebase Mapping Playbook — Use this skill when entering an unfamiliar codebase, doing deep investigation wo
+skills/exploration/repo-map.md (Repo Exploration) Codebase Mapping Playbook: Use this skill when entering an unfamiliar codebase, doing deep investigation wo
 
 Use this skill when entering an unfamiliar codebase, doing deep investigation work, or producing a `.cx/codebase-map.md` artifact for future sessions. Agents: `
 -->
-# Repo Exploration — Codebase Mapping Playbook
+# Repo Exploration: Codebase Mapping Playbook
 
 Use this skill when entering an unfamiliar codebase, doing deep investigation work, or producing a `.cx/codebase-map.md` artifact for future sessions.
 
@@ -51,14 +51,14 @@ find . -maxdepth 2 -type d \
 ```
 
 Classify each top-level directory as one of:
-- **entry** — main executables, CLIs, servers (cmd/, bin/, app/, main.*)
-- **lib** — shared library code (lib/, pkg/, src/, internal/)
-- **ui** — frontend/views (web/, frontend/, views/, components/)
-- **config** — configuration, env templates (.env.example, config/, etc/)
-- **infra** — deployment, CI/CD, Docker (deploy/, k8s/, .github/, terraform/)
-- **test** — test-only code (test/, tests/, __tests__/, spec/)
-- **docs** — documentation (docs/, .cx/)
-- **generated** — auto-generated, do not read (dist/, build/, .next/, vendor/)
+- **entry**: main executables, CLIs, servers (cmd/, bin/, app/, main.*)
+- **lib**: shared library code (lib/, pkg/, src/, internal/)
+- **ui**: frontend/views (web/, frontend/, views/, components/)
+- **config**: configuration, env templates (.env.example, config/, etc/)
+- **infra**: deployment, CI/CD, Docker (deploy/, k8s/, .github/, terraform/)
+- **test**: test-only code (test/, tests/, __tests__/, spec/)
+- **docs**: documentation (docs/, .cx/)
+- **generated**: auto-generated, do not read (dist/, build/, .next/, vendor/)
 
 ### 2b. Entry points
 
@@ -254,7 +254,7 @@ If you're about to {do Y}, start with: {file or path}
 
 ---
 
-## Quick Reference — Useful One-Liners
+## Quick Reference: Useful One-Liners
 
 ```bash
 # File count by extension

package/skills/frameworks/django.md

@@ -1,5 +1,5 @@
 <!--
-skills/frameworks/django.md — Django — ```
+skills/frameworks/django.md (Django) ```
 
 ## Project Structure ```
 -->
@@ -37,10 +37,10 @@ Keep apps small and feature-bounded. Do not put everything in one app.
 
 ### Field choices
 
-- `CharField` / `TextField` — strings; always set `blank=False` unless optional
-- `UUIDField(default=uuid.uuid4, primary_key=True)` — preferred over auto-increment for external-facing IDs
-- `JSONField` — use sparingly; prefer normalized columns for queryable data
-- `select_related` for FK, `prefetch_related` for M2M — avoid N+1 queries
+- `CharField` / `TextField`: strings; always set `blank=False` unless optional
+- `UUIDField(default=uuid.uuid4, primary_key=True)`: preferred over auto-increment for external-facing IDs
+- `JSONField`: use sparingly; prefer normalized columns for queryable data
+- `select_related` for FK, `prefetch_related` for M2M: avoid N+1 queries
 
 ### Migrations
 
@@ -115,13 +115,13 @@ class ItemSerializer(serializers.ModelSerializer):
 
 ## Security
 
-- `SECRET_KEY` from env — never commit
+- `SECRET_KEY` from env: never commit
 - `ALLOWED_HOSTS` locked down in production
 - `DEBUG = False` in production (template errors expose internals)
 - CSRF: enabled by default for form views; DRF uses `SessionAuthentication` + CSRF for browser clients
 - `django-environ` or `python-decouple` for settings from environment variables
 - Content security policy: `django-csp` middleware
-- SQL: always use ORM or parameterized `raw()` — never string-format user input into queries
+- SQL: always use ORM or parameterized `raw()`: never string-format user input into queries
 
 ## Testing
 
@@ -137,8 +137,8 @@ class ItemAPITest(APITestCase):
     self.assertEqual(Item.objects.count(), 1)
 ```
 
-- Use `APITestCase` (DRF) for API tests — wraps each test in a transaction that rolls back
-- `factory_boy` for fixtures — more maintainable than raw `create()`
+- Use `APITestCase` (DRF) for API tests: wraps each test in a transaction that rolls back
+- `factory_boy` for fixtures: more maintainable than raw `create()`
 - `pytest-django` with `@pytest.mark.django_db` for pytest-style tests
 - `django-silk` or `django-debug-toolbar` for query profiling in development
 
@@ -146,14 +146,14 @@ class ItemAPITest(APITestCase):
 
 - Database: add `db_index=True` for filtered columns; `select_related`/`prefetch_related` to eliminate N+1
 - Caching: `django.core.cache` with Redis backend (`django-redis`)
-- Async views: `async def` views supported in Django 4.1+ — use for I/O-bound operations with `asyncio`
+- Async views: `async def` views supported in Django 4.1+: use for I/O-bound operations with `asyncio`
 - Task queues: `Celery` + Redis/RabbitMQ for background jobs; `django-celery-beat` for scheduling
 - `gunicorn` + `uvicorn` workers for async support in production
 
 ## Common Pitfalls
 
-- `objects.all()` in views without pagination — always use `Paginator` or DRF `pagination_class`
-- Accessing related objects in a loop without `select_related` — profile with `django-debug-toolbar`
-- `settings.DEBUG` checks in production-like environments — use environment-specific settings modules
-- File uploads to local storage in production — use `django-storages` with S3/GCS
-- Signals for business logic — prefer explicit service functions; signals are invisible and hard to test
+- `objects.all()` in views without pagination: always use `Paginator` or DRF `pagination_class`
+- Accessing related objects in a loop without `select_related`: profile with `django-debug-toolbar`
+- `settings.DEBUG` checks in production-like environments: use environment-specific settings modules
+- File uploads to local storage in production: use `django-storages` with S3/GCS
+- Signals for business logic: prefer explicit service functions; signals are invisible and hard to test

package/skills/frameworks/nextjs.md

@@ -1,5 +1,5 @@
 <!--
-skills/frameworks/nextjs.md — Next.js (App Router) — ```
+skills/frameworks/nextjs.md (Next.js (App Router)) ```
 
 ## App Router Mental Model ```
 -->
@@ -46,9 +46,9 @@ Caching behaviors:
 
 | Option | Behavior |
 |---|---|
-| `cache: 'force-cache'` | Static — cache forever (default) |
-| `next: { revalidate: N }` | ISR — revalidate after N seconds |
-| `cache: 'no-store'` | Dynamic — always fresh |
+| `cache: 'force-cache'` | Static: cache forever (default) |
+| `next: { revalidate: N }` | ISR: revalidate after N seconds |
+| `cache: 'no-store'` | Dynamic: always fresh |
 | `next: { tags: ['items'] }` | Tag for on-demand revalidation |
 
 ### On-demand revalidation
@@ -91,15 +91,15 @@ export async function createItem(formData: FormData) {
 </form>
 ```
 
-Validate Server Action inputs — they are network endpoints.
+Validate Server Action inputs: they are network endpoints.
 
 ## Rendering Strategies
 
 | Strategy | When |
 |---|---|
-| Static (SSG) | Marketing pages, docs — no user-specific data |
-| ISR | Listings, product pages — stale-ok, periodic refresh |
-| Dynamic (SSR) | Dashboards, auth-gated pages — always fresh |
+| Static (SSG) | Marketing pages, docs: no user-specific data |
+| ISR | Listings, product pages: stale-ok, periodic refresh |
+| Dynamic (SSR) | Dashboards, auth-gated pages: always fresh |
 | Client | Highly interactive UIs, real-time, after-hydration only |
 
 Prefer static/ISR by default; reach for dynamic only when the data must be per-request.
@@ -129,20 +129,20 @@ export function middleware(req: NextRequest) {
 export const config = { matcher: ['/dashboard/:path*'] };
 ```
 
-Middleware runs on the Edge Runtime — no Node.js APIs. Keep it fast; no DB calls.
+Middleware runs on the Edge Runtime: no Node.js APIs. Keep it fast; no DB calls.
 
 ## Performance
 
 - Enable Partial Prerendering (PPR) in Next.js 15 for shell + streaming content
-- Use `next/image` for all images — automatic WebP, lazy loading, CLS prevention
-- Use `next/font` for self-hosted fonts — eliminates FOUT and external requests
+- Use `next/image` for all images: automatic WebP, lazy loading, CLS prevention
+- Use `next/font` for self-hosted fonts: eliminates FOUT and external requests
 - Bundle analysis: `ANALYZE=true next build`
 - Streaming: wrap slow data-dependent sections in `<Suspense>`
 
 ## Common Pitfalls
 
-- Importing client-only code (browser APIs, hooks) in Server Components — add `'use client'`
-- Large `layout.tsx` re-renders — use `memo` on stable child subtrees
-- Fetching the same data in multiple components — hoist to the nearest shared ancestor Server Component (fetch is deduplicated within a request)
-- Dynamic routes missing `generateStaticParams` for static builds — causes runtime 404
-- Server Actions called without input validation — treat as untrusted user input
+- Importing client-only code (browser APIs, hooks) in Server Components: add `'use client'`
+- Large `layout.tsx` re-renders: use `memo` on stable child subtrees
+- Fetching the same data in multiple components: hoist to the nearest shared ancestor Server Component (fetch is deduplicated within a request)
+- Dynamic routes missing `generateStaticParams` for static builds: causes runtime 404
+- Server Actions called without input validation: treat as untrusted user input

package/skills/frameworks/react.md

@@ -1,5 +1,5 @@
 <!--
-skills/frameworks/react.md — React — By default, components are **Server Components** — they run on the server, have
+skills/frameworks/react.md (React) By default, components are **Server Components**: they run on the server, have
 
 ## Component Design ### Server vs Client Components (React 19 / Next.js App Router)
 -->
@@ -9,7 +9,7 @@ skills/frameworks/react.md — React — By default, components are **Server Com
 
 ### Server vs Client Components (React 19 / Next.js App Router)
 
-By default, components are **Server Components** — they run on the server, have no state, and can fetch data directly. Add `'use client'` only when you need interactivity, browser APIs, or hooks.
+By default, components are **Server Components**: they run on the server, have no state, and can fetch data directly. Add `'use client'` only when you need interactivity, browser APIs, or hooks.
 
 ```tsx
 // Server Component — no directive needed
@@ -53,7 +53,7 @@ See decision matrix:
 | URL state | `useSearchParams` / router |
 | Component-local state | `useState` / `useReducer` |
 
-Do not put server data in a client store — TanStack Query is the cache. Derive don't duplicate.
+Do not put server data in a client store: TanStack Query is the cache. Derive don't duplicate.
 
 ## Performance
 
@@ -95,8 +95,8 @@ export function useItems() {
 
 ### Controlled vs uncontrolled
 
-- Controlled: React owns value via `state` — use for forms with validation, derived fields
-- Uncontrolled: DOM owns value via `ref` — use for file inputs and simple browser-owned fields
+- Controlled: React owns value via `state`: use for forms with validation, derived fields
+- Uncontrolled: DOM owns value via `ref`: use for file inputs and simple browser-owned fields
 
 ## Testing
 
@@ -113,20 +113,20 @@ test('submits search query', async () => {
 });
 ```
 
-- Use `@testing-library/react` — test behavior, not implementation
-- `userEvent` over `fireEvent` — simulates real user interactions
+- Use `@testing-library/react`: test behavior, not implementation
+- `userEvent` over `fireEvent`: simulates real user interactions
 - Mock at the network boundary (`msw`) not the component boundary
 
 ## Tooling
 
 - **Vite** for non-Next apps; fast HMR, native ESM
 - **Biome** for lint + format in a single fast tool (replaces ESLint + Prettier)
-- **TypeScript strict mode** — enables `noUncheckedIndexedAccess`, `strictNullChecks`, etc.
+- **TypeScript strict mode**: enables `noUncheckedIndexedAccess`, `strictNullChecks`, etc.
 - React DevTools Profiler for recomposition analysis
 
 ## Common Pitfalls
 
-- Stale closures in `useEffect` — include all reactive values in the dependency array or use `useEffectEvent` (React 19)
-- `useEffect` for data fetching — use TanStack Query instead
-- Direct DOM mutation inside render — causes tearing with concurrent mode
-- Key prop as array index — breaks reconciliation on reorder/insert
+- Stale closures in `useEffect`: include all reactive values in the dependency array or use `useEffectEvent` (React 19)
+- `useEffect` for data fetching: use TanStack Query instead
+- Direct DOM mutation inside render: causes tearing with concurrent mode
+- Key prop as array index: breaks reconciliation on reorder/insert

package/skills/frameworks/spring-boot.md

@@ -1,5 +1,5 @@
 <!--
-skills/frameworks/spring-boot.md — Spring Boot — ```
+skills/frameworks/spring-boot.md (Spring Boot) ```
 
 ## Project Structure ```
 -->
@@ -80,9 +80,9 @@ interface ItemRepository : JpaRepository<Item, UUID> {
 }
 ```
 
-- Default `FetchType.LAZY` for associations — never `EAGER`
+- Default `FetchType.LAZY` for associations: never `EAGER`
 - Use `JOIN FETCH` in queries when you need the association
-- Enable `spring.jpa.open-in-view=false` — prevents lazy-loading in the web layer
+- Enable `spring.jpa.open-in-view=false`: prevents lazy-loading in the web layer
 - Use Flyway or Liquibase for schema migrations; never `ddl-auto=update` in production
 
 ## Transactions
@@ -101,8 +101,8 @@ class ItemService(private val repo: ItemRepository) {
 ```
 
 - `@Transactional` on service layer, not repository or controller
-- `readOnly = true` as class-level default; override on writes — signals no dirty-check needed
-- Do not call `@Transactional` methods via `this` — Spring proxy won't intercept it
+- `readOnly = true` as class-level default; override on writes: signals no dirty-check needed
+- Do not call `@Transactional` methods via `this`: Spring proxy won't intercept it
 
 ## Security (Spring Security 6)
 
@@ -145,12 +145,12 @@ class ItemControllerIT(@Autowired val restTemplate: TestRestTemplate) {
 
 - `@WebMvcTest` for controller-only tests (fast, no DB)
 - `@DataJpaTest` for repository tests against a real embedded or Testcontainers DB
-- `@SpringBootTest` for integration tests — use Testcontainers for realistic DB
+- `@SpringBootTest` for integration tests: use Testcontainers for realistic DB
 - `MockMvc` + `@AutoConfigureMockMvc` for HTTP-layer testing without a real port
 
 ## Performance
 
-- Connection pool: `HikariCP` (default) — tune `maximumPoolSize` based on load testing
+- Connection pool: `HikariCP` (default): tune `maximumPoolSize` based on load testing
 - N+1 queries: use `JOIN FETCH` or `@EntityGraph`; verify with `spring.jpa.show-sql=true` in dev
 - Caching: `@Cacheable` + Spring Cache with Redis (`spring-boot-starter-data-redis`)
 - Async: `@EnableAsync` + `@Async` on service methods for fire-and-forget; use `CompletableFuture<T>` return type
@@ -158,8 +158,8 @@ class ItemControllerIT(@Autowired val restTemplate: TestRestTemplate) {
 
 ## Common Pitfalls
 
-- `LazyInitializationException` after transaction closes — resolve with `JOIN FETCH` or DTO projection
-- `@Transactional` on private methods — Spring AOP proxy can't intercept; move to public
-- Bean cycle injection — restructure or use `@Lazy`
-- Returning JPA entities directly from controllers — exposes internal model; always map to DTOs
-- `findAll()` without pagination on large tables — always use `Pageable`
+- `LazyInitializationException` after transaction closes: resolve with `JOIN FETCH` or DTO projection
+- `@Transactional` on private methods: Spring AOP proxy can't intercept; move to public
+- Bean cycle injection: restructure or use `@Lazy`
+- Returning JPA entities directly from controllers: exposes internal model; always map to DTOs
+- `findAll()` without pagination on large tables: always use `Pageable`

package/skills/frontend-design/accessibility.md

@@ -1,5 +1,5 @@
 <!--
-skills/frontend-design/accessibility.md — Accessibility (WCAG 2.2 / Inclusive Design) — Target **WCAG 2.1 AA** as the minimum for any public-facing product. WCAG 2.2 AA
+skills/frontend-design/accessibility.md (Accessibility (WCAG 2.2 / Inclusive Design)) Target **WCAG 2.1 AA** as the minimum for any public-facing product. WCAG 2.2 AA
 
 ## Compliance Baseline Target **WCAG 2.1 AA** as the minimum for any public-facing product. WCAG 2.2 AA is the current standard (published October 2023) and req
 -->
@@ -25,7 +25,7 @@ ARIA augments semantics it can't add natively; it cannot fix broken semantics.
 
 ## ARIA Rules
 
-1. If a native HTML element provides the required semantics, use it — do not add ARIA to a `<div>` when `<button>` exists.
+1. If a native HTML element provides the required semantics, use it: do not add ARIA to a `<div>` when `<button>` exists.
 2. Do not change native semantics: `<h2 role="button">` is invalid.
 3. All interactive ARIA widgets must be keyboard-operable.
 4. Do not hide focusable elements with `aria-hidden="true"`.
@@ -84,11 +84,11 @@ function trapFocus(modal: HTMLElement) {
 |---|---|---|
 | Normal text (< 18pt / 14pt bold) | 4.5:1 | 7:1 |
 | Large text (≥ 18pt / 14pt bold) | 3:1 | 4.5:1 |
-| UI components / graphical objects | 3:1 | — |
+| UI components / graphical objects | 3:1 |: |
 
 Tools: Figma Contrast plugin, axe DevTools, APCA calculator for sophisticated use cases.
 
-Do not convey information by color alone — add shape, pattern, or text.
+Do not convey information by color alone: add shape, pattern, or text.
 
 ## Motion
 
@@ -136,11 +136,11 @@ if (!prefersReduced) gsap.to(el, { y: -20, duration: 0.3 });
 
 ## Testing Checklist
 
-- [ ] Run `axe` or `Lighthouse Accessibility` — fix all violations
+- [ ] Run `axe` or `Lighthouse Accessibility`: fix all violations
 - [ ] Navigate entire flow with keyboard only
 - [ ] Test with VoiceOver (macOS/iOS) or NVDA/JAWS (Windows)
 - [ ] Verify color contrast meets 4.5:1 for body text
-- [ ] Test with browser zoom at 200% — no horizontal scroll, no content loss
+- [ ] Test with browser zoom at 200%: no horizontal scroll, no content loss
 - [ ] Test with `prefers-reduced-motion: reduce` enabled
 - [ ] All form errors are announced by screen reader
 

package/skills/frontend-design/component-patterns.md

@@ -1,5 +1,5 @@
 <!--
-skills/frontend-design/component-patterns.md — Component Patterns — Use this skill when designing component architecture, building design systems, o
+skills/frontend-design/component-patterns.md (Component Patterns) Use this skill when designing component architecture, building design systems, o
 
 Use this skill when designing component architecture, building design systems, or structuring reusable UI. ## Component Hierarchy
 -->

package/skills/frontend-design/engineering.md

@@ -1,5 +1,5 @@
 <!--
-skills/frontend-design/engineering.md — Frontend Engineering — Use this skill when working on build tooling, bundling, rendering strategies, or
+skills/frontend-design/engineering.md (Frontend Engineering) Use this skill when working on build tooling, bundling, rendering strategies, or
 
 Use this skill when working on build tooling, bundling, rendering strategies, or frontend infrastructure. ## Build Tools
 -->

package/skills/frontend-design/state-management.md

@@ -1,5 +1,5 @@
 <!--
-skills/frontend-design/state-management.md — Frontend State Management — Use this skill when choosing state management tools, structuring application sta
+skills/frontend-design/state-management.md (Frontend State Management) Use this skill when choosing state management tools, structuring application sta
 
 Use this skill when choosing state management tools, structuring application state, or debugging state issues. ## State Categories
 -->

package/skills/frontend-design/ui-aesthetics.md

@@ -1,5 +1,5 @@
 <!--
-skills/frontend-design/ui-aesthetics.md — UI Aesthetics — Use this skill when making visual design decisions: color, typography, layout, s
+skills/frontend-design/ui-aesthetics.md (UI Aesthetics) Use this skill when making visual design decisions: color, typography, layout, s
 
 Use this skill when making visual design decisions: color, typography, layout, spacing, and visual hierarchy. ## Color
 -->

package/skills/frontend-design/ux-principles.md

@@ -1,5 +1,5 @@
 <!--
-skills/frontend-design/ux-principles.md — UX Principles — Use this skill when designing user flows, evaluating usability, or planning info
+skills/frontend-design/ux-principles.md (UX Principles) Use this skill when designing user flows, evaluating usability, or planning info
 
 Use this skill when designing user flows, evaluating usability, or planning information architecture. ## Core Heuristics
 -->

package/skills/operating/orchestration-reference.md

@@ -1,5 +1,5 @@
 <!--
-skills/operating/orchestration-reference.md — detailed orchestration reference loaded on demand.
+skills/operating/orchestration-reference.md: detailed orchestration reference loaded on demand.
 
 Holds the execution contract, handoff template, intent and work-category
 classification, parallel dispatch, horizontal routing, and efficiency
@@ -12,7 +12,7 @@ stay in sharedGuidance so they load every turn.
 
 Loaded on demand via `get_skill("operating/orchestration-reference")`.
 
-This is the detailed reference for Construct's orchestration contract. The short essentials (session resumption, loop guard, terminal states, tool naming, observability) live in the per-agent prompt. Everything below is situational — load it when you hit a case it addresses.
+This is the detailed reference for Construct's orchestration contract. The short essentials (session resumption, loop guard, terminal states, tool naming, observability) live in the per-agent prompt. Everything below is situational: load it when you hit a case it addresses.
 
 ## System model
 
@@ -20,14 +20,14 @@ Construct is the underlying orchestration system for the **current project**. Tr
 
 The two task-shaped surfaces are siblings, not duplicates:
 
-- **`.cx/workflow.json`** — single project-wide workflow file. Holds the cross-cutting task ledger and intent / category metadata. Drives `workflow_status` and `project_context` MCP tools.
-- **`.cx/task-graphs/<id>.json`** — per-incoming-signal plan generated by `construct graph from-intake <intake-id>`. One graph per triaged inbox file, one node per persona in the recommendedChain, evidence records gating `done`. See [Concepts → Intake and triage](/concepts/intake-and-triage).
+- **`.cx/workflow.json`**: single project-wide workflow file. Holds the cross-cutting task ledger and intent / category metadata. Drives `workflow_status` and `project_context` MCP tools.
+- **`.cx/task-graphs/<id>.json`**: per-incoming-signal plan generated by `construct graph from-intake <intake-id>`. One graph per triaged inbox file, one node per persona in the recommendedChain, evidence records gating `done`. See [Concepts → Intake and triage](/concepts/intake-and-triage).
 
 A signal that becomes durable cross-session work crosses over: the graph nodes are executed, the resulting work is tracked in `.cx/workflow.json` and in beads. The intake queue and task graphs are how new signals enter the loop; the workflow ledger and beads are how durable work is carried.
 
 ## Perspective architecture
 
-Each specialist carries a distinct cognitive profile shaped by professional prior, characteristic suspicion, and productive tension with adjacent roles. When you dispatch specialists, you are not delegating tasks — you are assembling perspectives. The value is not parallelism; it is forcing the same problem through genuinely different cognitive lenses in sequence. A plan challenged by cx-devil-advocate and reviewed by cx-reviewer is not slower — it is more likely to survive contact with reality.
+Each specialist carries a distinct cognitive profile shaped by professional prior, characteristic suspicion, and productive tension with adjacent roles. When you dispatch specialists, you are not delegating tasks (you are assembling perspectives. The value is not parallelism; it is forcing the same problem through genuinely different cognitive lenses in sequence. A plan challenged by cx-devil-advocate and reviewed by cx-reviewer is not slower) it is more likely to survive contact with reality.
 
 ## Execution contract
 
@@ -35,11 +35,11 @@ For every non-trivial task: classify intent, create or update `.cx/workflow.json
 
 ### Intent classes
 
-- `research` — read-only investigation
-- `implementation` — code changes
-- `investigation` — debugging, tracing
-- `evaluation` — quality gates, review
-- `fix` — bug repair
+- `research`: read-only investigation
+- `implementation`: code changes
+- `investigation`: debugging, tracing
+- `evaluation`: quality gates, review
+- `fix`: bug repair
 
 Tag every workflow task with its intent class. Let intent drive agent selection and depth of work.
 
@@ -69,24 +69,24 @@ Do not duplicate skill internals inside agent prompts. Reference the relevant sk
 
 Every producer→consumer pair has an explicit contract in `agents/contracts.json`, loaded via `lib/agent-contracts.mjs`. Specialists call the MCP tool `agent_contract` at the start of a handoff to see:
 
-- `input.mustContain` — fields the packet must carry
-- `input.schema` — JSON schema (when applicable) from `lib/schemas/`
-- `preconditions` — what must be true before work starts
-- `output.schema` / `output.shape` — expected return shape
-- `postconditions` — what must be true before marking DONE
+- `input.mustContain`: fields the packet must carry
+- `input.schema`: JSON schema (when applicable) from `lib/schemas/`
+- `preconditions`: what must be true before work starts
+- `output.schema` / `output.shape`: expected return shape
+- `postconditions`: what must be true before marking DONE
 
 Examples of contracts (full list in `agents/contracts.json`):
 
-- `researcher-to-architect` — research brief with ≥2 primary sources → decision
-- `product-manager-to-architect` — PRD handoff → decision with Rejected alternatives
-- `architect-to-devil-advocate` — framing proposal → challenge report (blocks if framing is weak)
-- `architect-to-engineer` — decision → implementation
-- `engineer-to-reviewer` — implementation → review verdict
-- `engineer-to-qa` — implementation → test report
-- `reviewer-to-security` — review with auth/secrets scope → specialized security review
-- `any-to-docs-keeper` — any DONE mutation that changed core docs → doc sync
+- `researcher-to-architect`: research brief with ≥2 primary sources → decision
+- `product-manager-to-architect`: PRD handoff → decision with Rejected alternatives
+- `architect-to-devil-advocate`: framing proposal → challenge report (blocks if framing is weak)
+- `architect-to-engineer`: decision → implementation
+- `engineer-to-reviewer`: implementation → review verdict
+- `engineer-to-qa`: implementation → test report
+- `reviewer-to-security`: review with auth/secrets scope → specialized security review
+- `any-to-docs-keeper`: any DONE mutation that changed core docs → doc sync
 
-`routeRequest` returns a `contractChain` that enumerates which of these fire for a given request. Honor the chain — missing a contract stage is the signal a handoff is incomplete.
+`routeRequest` returns a `contractChain` that enumerates which of these fire for a given request. Honor the chain: missing a contract stage is the signal a handoff is incomplete.
 
 ## Legacy handoff contract (fallback)
 
@@ -120,7 +120,7 @@ When your output directly feeds another specialist (e.g. security findings → c
 These are enforced by hooks, not advisory:
 
 - `context-watch` hook (UserPromptSubmit) injects compaction guidance at ~60% / ~80% of the context window.
-- `repeated-read-guard` hook (PreToolUse on Read) blocks broad re-reads of files already read twice in this session — steers to Grep or offset+limit.
+- `repeated-read-guard` hook (PreToolUse on Read) blocks broad re-reads of files already read twice in this session: steers to Grep or offset+limit.
 - `bash-output-logger` hook (PostToolUse on Bash) persists outputs >4KB to `~/.cx/bash-logs/` and tells the model to grep the log rather than re-run.
 
 Advisory companions:
@@ -136,11 +136,11 @@ If you reason about the same decision across two consecutive turns without a new
 
 ## Speculation rule
 
-When choosing between named options (SDK vs SDK, library vs library, pattern vs pattern), the answer comes from `context7_query-docs`, `WebFetch`, the user, or an explicit default — never from internal reasoning rounds alone.
+When choosing between named options (SDK vs SDK, library vs library, pattern vs pattern), the answer comes from `context7_query-docs`, `WebFetch`, the user, or an explicit default: never from internal reasoning rounds alone.
 
 ## Dispatch-first test
 
-If work touches 3+ files across 2+ modules, or introduces a new contract/dependency/SDK, the persona must not produce the implementation plan itself — dispatch cx-architect. In-persona implementation planning for complex work is the primary failure mode this rule exists to prevent.
+If work touches 3+ files across 2+ modules, or introduces a new contract/dependency/SDK, the persona must not produce the implementation plan itself: dispatch cx-architect. In-persona implementation planning for complex work is the primary failure mode this rule exists to prevent.
 
 ## Executive communication
 

package/skills/quality-gates/review-work.md

@@ -1,5 +1,5 @@
 <!--
-skills/quality-gates/review-work.md — Parallel Adversarial Review — Use this methodology when a change needs rigorous pre-merge validation. Five ind
+skills/quality-gates/review-work.md (Parallel Adversarial Review) Use this methodology when a change needs rigorous pre-merge validation. Five ind
 
 Use this methodology when a change needs rigorous pre-merge validation. Five independent review roles run concurrently. All must pass. ## When to use
 -->
@@ -46,13 +46,13 @@ Use this methodology when a change needs rigorous pre-merge validation. Five ind
 
 ### 5. Quality (cx-accessibility for UI; cx-trace-reviewer for non-UI)
 
-**UI changes — cx-accessibility:**
+**UI changes: cx-accessibility:**
 - Keyboard navigation
 - Screen reader compatibility
 - Color contrast and focus visibility
 - Reduced motion support
 
-**Non-UI changes — cx-trace-reviewer:**
+**Non-UI changes: cx-trace-reviewer:**
 - N+1 queries or unbounded loops
 - Memory or connection leaks
 - Missing caching for expensive operations

package/skills/quality-gates/verify-change.md

@@ -1,5 +1,5 @@
 <!--
-skills/quality-gates/verify-change.md — Verify Change — Use this skill to analyze the impact of code changes and verify documentation an
+skills/quality-gates/verify-change.md (Verify Change) Use this skill to analyze the impact of code changes and verify documentation an
 
 Use this skill to analyze the impact of code changes and verify documentation and tests are in sync. ## Change Inventory
 -->

package/skills/quality-gates/verify-module.md

@@ -1,5 +1,5 @@
 <!--
-skills/quality-gates/verify-module.md — Verify Module — Use this skill to check that a module or package is structurally complete and re
+skills/quality-gates/verify-module.md (Verify Module) Use this skill to check that a module or package is structurally complete and re
 
 Use this skill to check that a module or package is structurally complete and ready for use. ## Exports
 -->

package/skills/quality-gates/verify-quality.md

@@ -1,5 +1,5 @@
 <!--
-skills/quality-gates/verify-quality.md — Verify Quality — Use this skill to check code quality, complexity, and maintainability after chan
+skills/quality-gates/verify-quality.md (Verify Quality) Use this skill to check code quality, complexity, and maintainability after chan
 
 Use this skill to check code quality, complexity, and maintainability after changes. ## Complexity
 -->

package/skills/quality-gates/verify-security.md

@@ -1,5 +1,5 @@
 <!--
-skills/quality-gates/verify-security.md — Verify Security — Use this skill to scan code for security vulnerabilities before commits or relea
+skills/quality-gates/verify-security.md (Verify Security) Use this skill to scan code for security vulnerabilities before commits or relea
 
 Use this skill to scan code for security vulnerabilities before commits or releases. ## Scan Scope
 -->

package/skills/roles/architect.ai-systems.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/architect.ai-systems.md — Anti-pattern guidance for the Architect.ai-systems (ai systems) role.
+skills/roles/architect.ai-systems.md. Anti-pattern guidance for the Architect.ai-systems (ai systems) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the architect.ai-systems (ai systems) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-architect.
 role: architect.ai-systems
 applies_to: [cx-architect]
 inherits: architect
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # AI Systems Architect Overlay
 

package/skills/roles/architect.data.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/architect.data.md — Anti-pattern guidance for the Architect.data (data) role.
+skills/roles/architect.data.md. Anti-pattern guidance for the Architect.data (data) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the architect.data (data) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-architect.
 role: architect.data
 applies_to: [cx-architect]
 inherits: architect
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Data Architect Overlay
 

package/skills/roles/architect.enterprise.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/architect.enterprise.md — Anti-pattern guidance for the Architect.enterprise (enterprise) role.
+skills/roles/architect.enterprise.md. Anti-pattern guidance for the Architect.enterprise (enterprise) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the architect.enterprise (enterprise) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-architect.
 role: architect.enterprise
 applies_to: [cx-architect]
 inherits: architect
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Enterprise Architect Overlay
 

package/skills/roles/architect.integration.md

@@ -1,5 +1,5 @@
 <!--
-skills/roles/architect.integration.md — Anti-pattern guidance for the Architect.integration (integration) role.
+skills/roles/architect.integration.md. Anti-pattern guidance for the Architect.integration (integration) role.
 
 Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
 Covers common failure modes for the architect.integration (integration) domain and counter-moves to avoid them.
@@ -9,7 +9,9 @@ Applies to: cx-architect.
 role: architect.integration
 applies_to: [cx-architect]
 inherits: architect
-version: 1
+version: 2
+profiles: [rnd]
+cap: 1
 ---
 # Integration Architect Overlay