cfsa-antigravity 2.0.0 → 2.1.0

package/template/.agent/skills/migration-management/references/relational.md

@@ -0,0 +1,214 @@
+# Relational Database Migration Patterns
+
+Paradigm-specific patterns for the `migration-management` skill. Read `SKILL.md` first for universal methodology.
+
+Covers: **PostgreSQL**, **MySQL**
+
+---
+
+## Migration Tracking Tables
+
+### PostgreSQL
+
+```sql
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INTEGER,
+  checksum VARCHAR(64)
+);
+
+CREATE TABLE migration_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  version BIGINT NOT NULL,
+  status VARCHAR(20) NOT NULL,
+  error_message TEXT,
+  rolled_back_at TIMESTAMP,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE OR REPLACE FUNCTION record_migration(
+  p_version BIGINT, p_name VARCHAR, p_duration_ms INTEGER
+) RETURNS void AS $$
+BEGIN
+  INSERT INTO schema_migrations (version, name, duration_ms)
+  VALUES (p_version, p_name, p_duration_ms)
+  ON CONFLICT (version) DO UPDATE SET executed_at = CURRENT_TIMESTAMP;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### MySQL
+
+```sql
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INT,
+  checksum VARCHAR(64)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE migration_status (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  version BIGINT NOT NULL,
+  status ENUM('pending', 'completed', 'failed', 'rolled_back'),
+  error_message TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+---
+
+## Adding Columns
+
+### PostgreSQL
+
+```sql
+-- Non-blocking column addition
+ALTER TABLE users ADD COLUMN phone VARCHAR(20) DEFAULT '';
+ALTER TABLE users ADD CONSTRAINT phone_format
+  CHECK (phone = '' OR phone ~ '^\+?[0-9\-\(\)]{10,}$');
+CREATE INDEX CONCURRENTLY idx_users_phone ON users(phone);
+
+-- Rollback:
+-- DROP INDEX CONCURRENTLY idx_users_phone;
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+### MySQL
+
+```sql
+ALTER TABLE users
+ADD COLUMN phone VARCHAR(20) DEFAULT '',
+ADD INDEX idx_phone (phone);
+
+-- Rollback:
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+---
+
+## Renaming Columns
+
+```sql
+-- PostgreSQL
+ALTER TABLE users RENAME COLUMN user_name TO full_name;
+REINDEX TABLE users;
+
+-- Rollback:
+-- ALTER TABLE users RENAME COLUMN full_name TO user_name;
+```
+
+---
+
+## Creating Indexes Non-Blocking
+
+### PostgreSQL (CONCURRENTLY)
+
+```sql
+CREATE INDEX CONCURRENTLY idx_orders_user_created
+ON orders(user_id, created_at DESC);
+
+CREATE INDEX CONCURRENTLY idx_products_category_active
+ON products(category_id) WHERE active = true;
+
+-- Verify
+SELECT schemaname, tablename, indexname, idx_scan
+FROM pg_stat_user_indexes WHERE indexname LIKE 'idx_%';
+```
+
+### MySQL (INPLACE)
+
+```sql
+ALTER TABLE orders
+ADD INDEX idx_user_created (user_id, created_at),
+ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+---
+
+## Data Transformations
+
+### PostgreSQL
+
+```sql
+-- Normalize emails
+UPDATE users SET email = LOWER(TRIM(email))
+WHERE email != LOWER(TRIM(email));
+
+-- Deduplicate (keep latest)
+DELETE FROM users WHERE id NOT IN (
+  SELECT DISTINCT ON (LOWER(email)) id
+  FROM users ORDER BY LOWER(email), created_at DESC
+);
+```
+
+### MySQL
+
+```sql
+UPDATE products p
+JOIN category_mapping cm ON p.old_category = cm.old_name
+SET p.category_id = cm.new_category_id
+WHERE p.old_category IS NOT NULL;
+```
+
+---
+
+## Testing in Transaction
+
+```sql
+BEGIN;
+ALTER TABLE users ADD COLUMN test_column VARCHAR(255);
+SELECT COUNT(*) FROM users;
+-- ROLLBACK if issues, COMMIT if good
+ROLLBACK;
+```
+
+---
+
+## Bidirectional Migration Example
+
+```sql
+-- ===== UP =====
+CREATE TYPE user_status AS ENUM ('active', 'suspended', 'deleted');
+ALTER TABLE users ADD COLUMN status user_status DEFAULT 'active';
+
+-- ===== DOWN =====
+-- ALTER TABLE users DROP COLUMN status;
+-- DROP TYPE user_status;
+```
+
+---
+
+## Production Safety
+
+```sql
+-- PostgreSQL: Prevent hanging migrations
+SET statement_timeout = '30min';
+SET lock_timeout = '5min';
+```
+
+---
+
+## Combined Migration Example
+
+```sql
+BEGIN;
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
+UPDATE users SET full_name = first_name || ' ' || last_name;
+CREATE INDEX idx_users_full_name ON users(full_name);
+ALTER TABLE users ADD CONSTRAINT email_unique UNIQUE(email);
+COMMIT;
+```
+
+---
+
+## Tools
+
+- [PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)
+- [MySQL ALTER TABLE](https://dev.mysql.com/doc/refman/8.0/en/alter-table.html)
+- [Flyway](https://flywaydb.org/) — Java
+- [Alembic](https://alembic.sqlalchemy.org/) — Python
+- [Knex.js](https://knexjs.org/) — Node.js

package/template/.agent/skills/parallel-feature-development/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: parallel-feature-development
-description: Prevent tool call conflicts when making concurrent edits across a codebase. Establishes strict file ownership, interface contracts, and merge strategies. Use with parallel-agents when executing concurrent `replace_file_content` calls.
+description: Prevent tool call conflicts when making concurrent edits across a codebase. Establishes strict file ownership, interface contracts, and merge strategies. Use with parallel-agents when executing concurrent code changes.
 ---
 
 # Concurrent Feature Development
 
 ## Overview
 
-When making concurrent code edits (e.g. implementing the frontend and backend of a slice simultaneously), the #1 risk is **file hash conflicts** — trying to execute multiple `replace_file_content` calls on the same file, which causes the operation to fail. This skill prevents that with strict file ownership, typed interface contracts, and batched execution.
+When making concurrent code edits (e.g. implementing the frontend and backend of a slice simultaneously), the #1 risk is **file conflicts** — trying to modify the same file from multiple streams, which causes the operation to fail. This skill prevents that with strict file ownership, typed interface contracts, and batched execution.
 
 **Core principle:** One concurrent stream per file, always. No exceptions. If two streams need the same file, they're not independent — restructure the decomposition.
 
@@ -36,58 +36,51 @@ If Stream A owns `src/auth/login.ts`, no other stream may modify that file — n
 
 ### 1. Ownership Declaration
 
-Before writing code concurrently, create an explicit mental or written ownership manifest:
+Before writing code concurrently, create an explicit ownership manifest:
 
 ```markdown
 ## File Ownership Manifest
 
 | Stream | Owned Files | Interface Files |
 |--------|-------------|-----------------|
-| Stream 1 (Auth) | `src/auth/*`, `src/middleware/auth.ts` | `src/types/auth.ts` |
-| Stream 2 (API) | `src/api/*`, `src/middleware/api.ts` | `src/types/api.ts` |
-| Stream 3 (UI) | `src/components/*`, `src/pages/*` | `src/types/ui.ts` |
+| Stream 1 (Auth) | `src/auth/*`, `src/middleware/auth.*` | `src/types/auth.*` |
+| Stream 2 (API) | `src/api/*`, `src/middleware/api.*` | `src/types/api.*` |
+| Stream 3 (UI) | `src/components/*`, `src/pages/*` | `src/types/ui.*` |
 
 ### Shared Files (Frozen)
-- `src/types/shared.ts` — modify only in synthesis step
-- `src/config.ts` — frozen during parallel work
-- `package.json` — frozen during parallel work
+- `src/types/shared.*` — modify only in synthesis step
+- `src/config.*` — frozen during parallel work
+- Package manifest — frozen during parallel work
 ```
 
 **Rules:**
-- Every source file to be edited appears in exactly ONE workstream
-- Shared files are **frozen** — do not mutate them concurrently
+- Every source file appears in exactly ONE workstream
+- Shared files are **frozen** — do not mutate concurrently
 - If a stream needs a change to a shared file, document it as a `// BOUNDARY:` stub
 - Interface files define the contract between streams
 
 ### 2. Interface Contracts
 
-Before generating concurrent edits, define the typed interfaces they'll communicate through:
-
-```typescript
-// src/types/auth.ts — Stream 1 PRODUCES this, Stream 2 CONSUMES it
-export interface AuthResult {
-  userId: string;
-  roles: string[];
-  token: string;
-}
-
-// src/types/api.ts — Stream 2 PRODUCES this, Stream 3 CONSUMES it
-export interface UserResponse {
-  id: string;
-  name: string;
-  email: string;
-}
+Before generating concurrent edits, define the typed interfaces they'll communicate through.
+
+**Example (pseudocode — adapt to your language):**
+```
+// src/types/auth — Stream 1 PRODUCES, Stream 2 CONSUMES
+AuthResult { userId: string, roles: string[], token: string }
+
+// src/types/api — Stream 2 PRODUCES, Stream 3 CONSUMES
+UserResponse { id: string, name: string, email: string }
 ```
 
 **Contract rules:**
-- Interfaces are strictly defined BEFORE generating logic
-- Do NOT change interface files during the concurrent implementation phase
+- Interfaces defined BEFORE generating logic
+- Do NOT change interface files during the concurrent phase
 - Each interface has exactly one PRODUCER and one or more CONSUMERS
 - Develop against the interface, not assumptions
 
 ### 3. Batched Tool Execution
 
-When generating concurrent tool calls in the same turn:
+When generating concurrent tool calls:
 
 ```markdown
 ## Stream: [Role]
@@ -110,7 +103,7 @@ If you need something from another stream's domain:
 
 ### 4. Merge Protocol
 
-Always execute edits that don't overlap in a single batched `multi_replace_file_content` call, but conceptually process dependencies:
+Process dependencies in order:
 
 ```
 1. Interface files (already defined, verify no changes)
@@ -127,19 +120,17 @@ Always execute edits that don't overlap in a single batched `multi_replace_file_
 
 ### 5. Conflict Resolution
 
-If despite everything, a conflict is detected:
-
 | Conflict Type | Resolution |
 |---------------|-----------|
-| **Same file modified** | `replace_file_content` block. Separate edits into sequential tool calls. |
+| **Same file modified** | Separate edits into sequential tool calls |
 | **Interface mismatch** | Producer's implementation doesn't match contract → fix producer |
 | **Missing dependency** | Assumed something exists that doesn't → add BOUNDARY stub |
-| **Mutual dependency** | A needs B's output AND B needs A's output → can't go concurrent, code sequentially |
+| **Mutual dependency** | A needs B's output AND B needs A's → can't go concurrent, code sequentially |
 
 ## Integration with Kit
 
-- **With `session-continuity` Protocol 9 (Parallel Claim):** When tasks in progress files have surface tags (`BE`, `FE`, `QA`) and claim markers (`[!]`), the `files:` blocks under claimed tasks serve as your live ownership manifest. By analyzing these blocks, you can safely batch `replace_file_content` calls for both `FE` and `BE` tasks simultaneously.
-- **With `boundary-not-placeholder`:** Use `// BOUNDARY:` stubs for cross-stream dependencies you can't resolve concurrently. Resolve them sequentially afterward.
+- **With `session-continuity` Protocol 9 (Parallel Claim):** Surface tags (`BE`, `FE`, `QA`) and claim markers (`[!]`) in progress files serve as your live ownership manifest.
+- **With `boundary-not-placeholder`:** Use `// BOUNDARY:` stubs for cross-stream dependencies. Resolve them sequentially afterward.
 - **With `implement-slice`:** When a slice enters parallel mode (step 1.5), claim all tags concurrently. The synthesis step (6.5) resolves BOUNDARY stubs on frozen files.
 
 ## Example: Concurrent Vertical Slice
@@ -148,19 +139,19 @@ If despite everything, a conflict is detected:
 
 | Stream | Surface | Owned Files | Produces | Consumes |
 |--------|---------|-------------|----------|----------|
-| DB Stream | Schema | `migrations/003-profile.sql`, `src/db/profile.ts` | `ProfileRecord` type | — |
-| API Stream | Endpoint | `src/api/profile.ts`, `src/api/profile.test.ts` | `GET /api/profile` | `ProfileRecord` |
-| UI Stream | Component | `src/components/Profile.tsx`, `src/pages/profile.astro` | Rendered page | `GET /api/profile` |
+| DB | Schema | `migrations/003-profile.*`, `src/db/profile.*` | `ProfileRecord` type | — |
+| API | Endpoint | `src/api/profile.*`, `src/api/profile.test.*` | `GET /api/profile` | `ProfileRecord` |
+| UI | Component | `src/components/Profile.*`, `src/pages/profile.*` | Rendered page | `GET /api/profile` |
 
 **Merge order:** DB → API → UI (dependency chain)
 
-**Frozen files:** `src/types/shared.ts`, `astro.config.mjs`, `package.json`
+**Frozen files:** `src/types/shared.*`, config, package manifest
 
 ## Common Mistakes
 
 | Mistake | Consequence | Fix |
 |---------|-------------|-----|
-| Two sub-tasks mutate the same file | Tool call conflict, lost edits | ONE STREAM PER FILE. NO EXCEPTIONS. |
+| Two streams mutate the same file | Tool call conflict, lost edits | ONE STREAM PER FILE |
 | No interface contracts | Mismatched assumptions | Define types BEFORE editing |
 | Skipping integration tests | Interfaces match but behavior doesn't | Full suite after batch edits |
-| Parallelizing tightly coupled code | Constant blocking, BOUNDARY stubs everywhere | Code sequentially |
+| Parallelizing tightly coupled code | Constant blocking, stubs everywhere | Code sequentially |

package/template/.agent/skills/pipeline-rubrics/references/be-rubric.md

@@ -3,7 +3,7 @@
 | # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
 |---|---|---|---|---|
 | 1 | Upstream Traceability | (a) Every endpoint cites its IA source shard + section. (b) Every schema field traces to an IA data model field. No endpoint is "inferred" from context. (c) Every sub-feature listed in the IA shard's `## Features` is represented by at least one endpoint in the BE spec — a sub-feature with zero endpoints and no explicit `[Deferred to Phase N]` note is a gap. | Some endpoints or fields missing IA citations, or ≤20% of sub-features lack endpoint representation | Orphan endpoints with no IA source, or >20% of sub-features have no endpoint and no deferral note |
-| 2 | Contract Completeness | Every endpoint has: Zod request schema (all fields typed) + Zod response schema (all fields typed) + error schema. No field uses `any`, `unknown`, or untyped `string` where a more specific type exists. | Some schemas present but fields untyped or missing | Major schemas absent |
+| 2 | Contract Completeness | Every endpoint has: {{CONTRACT_LIBRARY}} request schema (all fields typed) + {{CONTRACT_LIBRARY}} response schema (all fields typed) + error schema. No field uses `any`, `unknown`, or untyped `string` where a more specific type exists. | Some schemas present but fields untyped or missing | Major schemas absent |
 | 3 | Error Exhaustiveness | Every endpoint has: HTTP status code + application error code (not just HTTP) + error message format + retry guidance. No endpoint uses "standard error handling" without defining it. | Some endpoints missing error codes or retry guidance | Generic 500s or no error section |
 | 4 | Schema Completeness | Every database table has: all fields with types + constraints (nullable, unique, indexed) + relationships with foreign keys + indexes for every query pattern. No field uses "standard" constraints without defining them. | Constraints or indexes missing | Sketched only |
 | 5 | Middleware Explicitness | Every endpoint has an explicit middleware matrix: auth required (yes/no) + rate limit (number/window) + input validation (where it runs) + CORS policy. No endpoint inherits "default middleware" without defining it. | Some endpoints missing middleware entries | No matrix |

package/template/.agent/skills/pipeline-rubrics/references/ia-rubric.md

@@ -14,6 +14,6 @@
 > **Deep Dive audit note**: When auditing dimension 7, read each deep dive file directly — do not infer its completeness from the parent shard's reference to it. A parent shard that links to a deep dive scores ⚠️ (not ✅) if the deep dive file itself is still a skeleton. Score ✅ only when the deep dive file contains exhaustive subsystem detail that an implementer could work from without asking questions.
 
 > **Dimension 1 audit procedure**:
-> 1. Read `docs/plans/ideation/ideation-index.md` and the relevant domain files in `docs/plans/ideation/domains/` to extract the authoritative list of Level-1 sub-features per domain.
+> 1. Read `docs/plans/ideation/ideation-index.md` and the relevant ideation domain files (use Domain Documents table for correct paths — files may be in `domains/` or `surfaces/{name}/`) to extract the authoritative list of Level-1 sub-features per domain.
 > 2. For each shard, open `docs/plans/ia/[NN-domain-name].md` and confirm every sub-feature from step 1 appears in the `## Features` section. Score ❌ if Must Have sub-features are missing entirely.
 > 3. For each sub-feature listed in `## Features`, verify it is represented in at least one section body (User Interactions, Data Model, Access Control, or Edge Cases). A sub-feature that appears only as a headline in `## Features` but has no corresponding detail in any section body scores ⚠️ — headline only = warning, not pass.

package/template/.agent/skills/prd-templates/SKILL.md

@@ -52,7 +52,12 @@ Run this procedure when filling the `## Features` section of each shard skeleton
 
 ### Source
 
-Read `docs/plans/ideation/ideation-index.md` and locate the relevant domain file in `docs/plans/ideation/domains/` for each shard's domain.
+Read `docs/plans/ideation/ideation-index.md` — specifically the `## Structural Classification` and `## Domain Documents` sections.
+
+- **Single-surface projects**: Locate the relevant domain file in `docs/plans/ideation/domains/` for each shard's domain.
+- **Multi-product projects**: Use the path from the Domain Documents table in `ideation-index.md`. Domain files may be in `docs/plans/ideation/surfaces/{surface-name}/` (surface-exclusive) or `docs/plans/ideation/domains/` (shared).
+
+Match each shard to its ideation domain by name. If the ideation structure is `surfaces/`, the shard's decomposition surface (from `decompose-architecture`) tells you which surface subfolder to look in.
 
 ### Actor + Goal Format Rule
 
@@ -68,7 +73,7 @@ List sub-features as bullet points in the `## Features` section. Group by functi
 
 ### `[THIN — review with user]` Fallback Rule
 
-If a shard's domain has no corresponding file in `docs/plans/ideation/domains/` (the domain was introduced during architecture design, not ideation), mark the skeleton with `[THIN — review with user]` at the top of `## Features` and seed from the architecture design description instead.
+If a shard's domain has no corresponding ideation domain file (the domain was introduced during architecture design, not ideation — check the `ideation-index.md` Domain Documents table for both `domains/` and `surfaces/` paths), mark the skeleton with `[THIN — review with user]` at the top of `## Features` and seed from the architecture design description instead.
 
 At the validation step, the user must confirm whether to:
 - Keep the shard separate
@@ -77,8 +82,9 @@ At the validation step, the user must confirm whether to:
 
 ### Directory Example
 
-Seeded skeletons live in the `docs/plans/ia/` directory:
+Seeded skeletons live in the `docs/plans/ia/` directory (or per-surface directories for multi-product):
 
+**Single-surface:**
 ```
 docs/plans/ia/
 ├── 00-infrastructure.md
@@ -86,3 +92,14 @@ docs/plans/ia/
 ├── 02-content-library.md    ← ## Features seeded from ideation/domains/content-library.md
 ├── ...
 ```
+
+**Multi-product:**
+```
+docs/plans/desktop/ia/
+├── 00-infrastructure.md
+├── 01-operations.md         ← ## Features seeded from ideation/surfaces/desktop/operations.md
+├── 02-inventory.md          ← ## Features seeded from ideation/surfaces/desktop/inventory.md
+
+docs/plans/shared/ia/
+├── 01-device-history.md     ← ## Features seeded from ideation/domains/device-history.md
+```

package/template/.agent/skills/prd-templates/references/be-spec-template.md

@@ -24,7 +24,7 @@ that lets a reviewer verify nothing was missed or invented.]
 | [specific subsystem] | [deep-dive.md] | § Key Decisions |
 
 ## API Endpoints
-## Request/Response Contracts (Zod schemas)
+## Request/Response Contracts ({{CONTRACT_LIBRARY}} schemas)
 ## Database Schema
 ## Middleware & Policies
 ## Data Flow
@@ -42,7 +42,7 @@ that lets a reviewer verify nothing was missed or invented.]
 
 Apply after writing every BE spec:
 
-- [ ] Every endpoint has a Zod request AND response schema
+- [ ] Every endpoint has a {{CONTRACT_LIBRARY}} request AND response schema
 - [ ] Every database table has defined fields, indexes, and permissions
 - [ ] Security constraints from IA shard reflected in middleware section
 - [ ] Error codes are specific (not generic 500s)

package/template/.agent/skills/prd-templates/references/decomposition-templates.md

@@ -18,7 +18,7 @@ For each shard, create at `docs/plans/ia/[NN-domain-name].md`:
 [1-2 sentence description of this domain's scope]
 
 ## Features
-[Level-1 sub-features from the relevant domain file in `docs/plans/ideation/domains/` for this domain. NOT architecture-level headlines. See /decompose-architecture-structure Step 5 for seeding instructions.]
+[Level-1 sub-features from the relevant ideation domain file for this domain. Check `ideation-index.md` Domain Documents table for the correct path — files may be in `domains/` or `surfaces/{name}/` depending on structural classification. NOT architecture-level headlines. See /decompose-architecture-structure Step 5 for seeding instructions.]
 
 ## User Interactions
 [To be filled during /write-architecture-spec]
@@ -101,7 +101,7 @@ Read cross-cutting specs first, then feature specs in numerical order.
 
 Every BE spec MUST include:
 - API Endpoints (method, path, description)
-- Request/Response Contracts (Zod schemas)
+- Request/Response Contracts ({{CONTRACT_LIBRARY}} schemas)
 - Database Schema (tables, fields, indexes, permissions)
 - Middleware & Policies (auth, rate limits, validation)
 - Data Flow (request lifecycle)

package/template/.agent/skills/prd-templates/references/fe-spec-template.md

@@ -44,7 +44,7 @@ Use this template when writing FE specs to `docs/plans/fe/[NN-feature-name].md`.
 [Server state, client state, URL state, loading/error/empty]
 
 ## Interaction Specification
-[Click, hover, keyboard, form validation matching Zod]
+[Click, hover, keyboard, form validation matching {{CONTRACT_LIBRARY}}]
 
 ## Responsive Behavior
 [Breakpoints, component behavior per breakpoint]

package/template/.agent/skills/prd-templates/references/ideation-domain-template.md

@@ -2,6 +2,7 @@
 
 > **Status**: `[SURFACE]` / `[BREADTH]` / `[DEEP]` / `[EXHAUSTED]`
 > **Domain number**: NN
+> **Surface**: _surface name (e.g., "web", "desktop", "mobile") or "shared"_
 > **Last updated**: _timestamp_
 
 ## Overview
@@ -35,8 +36,13 @@ _Vertical drill content — features, behaviors, edge cases, failure modes._
 
 #### Cross-Cut Notes
 
-- Touches **Domain NN** ([domain-file.md](../domains/NN-domain.md)) because: _reason_
-- Touches **Domain NN** ([domain-file.md](../domains/NN-domain.md)) because: _reason_
+> **Path note:** Use the path from `ideation-index.md` Domain Documents table for cross-references.
+> For single-surface: `../domains/NN-domain.md`. For multi-product: paths vary by location
+> (same surface = `../NN-domain.md`, different surface = `../../surfaces/{name}/NN-domain.md`,
+> shared = `../../domains/NN-domain.md`). Always verify against the index.
+
+- Touches **Domain NN** ([domain-file.md](path-from-index)) because: _reason_
+- Touches **Domain NN** ([domain-file.md](path-from-index)) because: _reason_
 
 ---
 

package/template/.agent/skills/prd-templates/references/ideation-index-template.md

@@ -16,6 +16,12 @@
 - Cross-cut Detection: always-on
 - Deep Think Protocol: active
 
+## Structural Classification
+
+- **Project Shape**: [single-surface | multi-surface-shared | multi-product]
+- **Surfaces**: [list of identified surfaces, e.g., "Web (Astro/React), Desktop (Rust/Tauri), Mobile (React Native)" — or "N/A" for single-surface]
+- **Classification Basis**: [how this was determined — "detected from document", "user interview", "inferred from one-liner"]
+
 ## Progress Summary
 
 | Metric | Value |
@@ -44,9 +50,27 @@
 
 ### Domain Documents
 
+> **Path convention:** For single-surface projects, domains live in `domains/NN-slug.md`.
+> For multi-product projects, surface-exclusive domains live in `surfaces/{surface}/NN-slug.md`
+> and shared domains live in `domains/NN-slug.md`.
+
+| # | Domain | Surface | Path | Status | Sub-areas | Deep Think |
+|---|--------|---------|------|--------|-----------|------------|
+| 01 | _Domain Name_ | _surface or shared_ | [01-domain-slug.md](domains/01-domain-slug.md) | `[SURFACE]` | _N_ sub-areas | _N_ hypotheses |
+
+_For multi-product projects, group domains by surface:_
+
+#### Surface: _Surface Name_
+
 | # | Domain | Path | Status | Sub-areas | Deep Think |
 |---|--------|------|--------|-----------|------------|
-| 01 | _Domain Name_ | [01-domain-slug.md](domains/01-domain-slug.md) | `[SURFACE]` | _N_ sub-areas | _N_ hypotheses |
+| 01 | _Domain Name_ | [01-slug.md](surfaces/{surface}/01-slug.md) | `[SURFACE]` | _N_ | _N_ |
+
+#### Shared Domains
+
+| # | Domain | Consumed By | Path | Status | Sub-areas | Deep Think |
+|---|--------|-------------|------|--------|-----------|------------|
+| 01 | _Domain Name_ | _surface list_ | [01-slug.md](domains/01-slug.md) | `[SURFACE]` | _N_ | _N_ |
 
 ### Cross-Cut Ledger
 

package/template/.agent/skills/prd-templates/references/operational-templates.md

@@ -14,7 +14,7 @@ Use when writing slice entries during `/plan-phase` Step 4:
 **Surfaces**: Contract, API, DB, UI
 
 #### Tasks
-- [ ] Contract: Zod schema for [entity] ← no tag (orchestrator handles sequentially)
+- [ ] Contract: {{CONTRACT_LIBRARY}} schema for [entity] ← no tag (orchestrator handles sequentially)
 - [ ] `BE` API endpoints for [entity] ← backend agent
 - [ ] `FE` [entity] page and components ← frontend agent
 - [ ] `QA` Integration tests for [entity] ← QA agent (runs FIRST to write failing tests, AND after BE+FE to verify)

package/template/.agent/skills/prd-templates/references/placeholder-workflow-mapping.md

@@ -1,21 +1,50 @@
-# Placeholder → Workflow Mapping
-
-Maps tech stack placeholders to the source keys and consuming workflows.
-
-| Placeholder | Source Key | Workflows |
-|---|---|---|
-| `{{DATABASE_SKILLS}}` | `DATABASE_*` (accumulated) | create-prd, write-architecture-spec, write-be-spec-classify |
-| `{{AUTH_SKILL}}` | `AUTH_PROVIDER` | create-prd, write-be-spec-classify |
-| `{{BACKEND_FRAMEWORK_SKILL}}` | `BACKEND_FRAMEWORK` / `API_LAYER` | write-be-spec-classify |
-| `{{API_DESIGN_SKILL}}` | `API_LAYER` (default: `api-design-principles`) | create-prd, create-prd-architecture, write-architecture-spec-design, write-be-spec-classify |
-| `{{FRONTEND_FRAMEWORK_SKILL}}` | `FRONTEND_FRAMEWORK` | write-fe-spec-classify |
-| `{{FRONTEND_DESIGN_SKILL}}` | `CSS_FRAMEWORK` / `UI_LIBRARY` | write-fe-spec-classify |
-| `{{ACCESSIBILITY_SKILL}}` | surface: `accessibility-compliance` | write-fe-spec-classify, write-fe-spec-write, write-architecture-spec-design, validate-phase |
-| `{{LANGUAGE_SKILL}}` | `LANGUAGE` | implement-slice-setup, implement-slice-tdd, write-be-spec-classify, write-fe-spec-classify, evolve-contract |
-| `{{CI_CD_SKILL}}` | `CI_CD` | create-prd-compile, decompose-architecture-structure, plan-phase, verify-infrastructure, validate-phase |
-| `{{HOSTING_SKILL}}` | `HOSTING` | create-prd-architecture, decompose-architecture-structure, plan-phase, verify-infrastructure, validate-phase |
-| `{{ORM_SKILL}}` | `ORM` | create-prd-architecture, write-be-spec-classify, implement-slice-setup, verify-infrastructure, validate-phase |
-| `{{UNIT_TESTING_SKILL}}` | `UNIT_TESTING` | create-prd-compile, implement-slice-setup, implement-slice-tdd, write-be-spec-classify, evolve-contract |
-| `{{E2E_TESTING_SKILL}}` | `E2E_TESTING` | create-prd-compile, implement-slice-tdd, validate-phase |
-| `{{STATE_MANAGEMENT_SKILL}}` | `STATE_MANAGEMENT` | write-fe-spec-classify, implement-slice-setup |
-| `{{SECURITY_SKILLS}}` | `SECURITY` + surface triggers (accumulated) | create-prd-security, write-architecture-spec-design, validate-phase |
+# Map Column Reference
+
+Maps surface stack map columns and cross-cutting categories to the workflows that consume them.
+
+> **How workflows use the map**: See `.agent/instructions/tech-stack.md` for the surface stack map format and resolution rules. Workflows determine their surface context (from shard directory or slice surface tag), then look up the corresponding row and column.
+
+## Per-Surface Columns
+
+| Column | Workflows That Consume It |
+|--------|--------------------------|
+| **Languages** | write-be-spec-classify, write-fe-spec-classify, implement-slice-setup, implement-slice-tdd, evolve-contract |
+| **BE Frameworks** | write-be-spec-classify |
+| **FE Frameworks** | write-fe-spec-classify |
+| **FE Design** | write-fe-spec-classify |
+| **ORMs** | create-prd-architecture, write-be-spec-classify, implement-slice-setup, verify-infrastructure, validate-phase |
+| **State Mgmt** | write-fe-spec-classify, implement-slice-setup |
+| **Databases** | create-prd-architecture, write-architecture-spec-design, write-be-spec-classify |
+| **Unit Tests** | create-prd-compile, write-be-spec-classify, implement-slice-setup, implement-slice-tdd, evolve-contract |
+| **E2E Tests** | create-prd-compile, implement-slice-tdd, validate-phase |
+| **Test Cmd** | implement-slice-tdd, validate-phase, evolve-contract |
+| **Validation Cmd** | implement-slice-tdd, validate-phase, evolve-contract |
+| **Lint Cmd** | validate-phase |
+| **Build Cmd** | validate-phase |
+| **Dev Cmd** | verify-infrastructure |
+| **Package Mgr** | bootstrap-agents-fill |
+
+## Cross-Cutting Categories
+
+| Category | Workflows That Consume It |
+|----------|--------------------------|
+| **Auth** | create-prd-security, write-be-spec-classify |
+| **CI/CD** | create-prd-compile, decompose-architecture-structure, plan-phase-write, verify-infrastructure, validate-phase |
+| **Hosting** | create-prd-architecture, decompose-architecture-structure, plan-phase-write, verify-infrastructure, validate-phase |
+| **Security** | create-prd-security, write-architecture-spec-design, validate-phase |
+| **API Design** | create-prd-architecture, write-architecture-spec-design, write-be-spec-classify |
+| **Accessibility** | write-fe-spec-classify, write-fe-spec-write, write-architecture-spec-design, validate-phase |
+| **Contract Library** | tdd-contract-first rule, implement-slice-setup |
+
+## Surface Context Resolution
+
+How each workflow determines which surface's row to read:
+
+| Workflow Type | Resolution Method |
+|--------------|-------------------|
+| Spec-writing (`write-be-spec`, `write-fe-spec`) | Shard directory path: `docs/plans/desktop/be/` → surface `desktop`; flat `docs/plans/be/` → surface `shared` |
+| Implementation (`implement-slice`) | Slice's `surface:` tag from the phase plan |
+| Planning (`plan-phase`) | Iterates ALL surfaces in the map |
+| Validation (`validate-phase`) | Runs per-surface commands for all surfaces |
+| Cross-cutting (`verify-infrastructure`) | Uses cross-cutting table + primary surface for commands |
+| Architecture (`create-prd-*`) | Map may be incomplete during these workflows — falls back to inline conversation context |