cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/session-continuity/protocols/10-placeholder-verification-gate.md

@@ -0,0 +1,83 @@
+# Protocol 10: Surface Stack Map Verification Gate
+
+## Purpose
+
+Specification and implementation workflows must verify the surface stack map is populated **before** any skill reads. This prevents spec authoring from running with empty map cells, which would produce patterns incompatible with the chosen tech stack.
+
+> **Note**: As of v3, workflows no longer use `{{PLACEHOLDER}}` values for skill paths. Instead, they read skill names from the surface stack map in `.codex/instructions/tech-stack.md`. This gate verifies map completeness.
+
+## How to Apply
+
+Add a **Step 0 — Map guard** to any specification or implementation workflow that reads skills from the surface stack map. The guard runs before all other steps, including re-run checks and prerequisite validations.
+
+## Guard Logic
+
+### 1. Read the surface stack map
+
+Read `.codex/instructions/tech-stack.md` and parse both tables:
+- **Per-Surface Skills** — One row per surface
+- **Cross-Cutting Skills** — Project-wide categories
+
+### 2. Determine required cells
+
+Based on the workflow type, identify which columns/categories must have filled values:
+
+| Workflow Type | Required Per-Surface Columns | Required Cross-Cutting Categories |
+|---|---|---|
+| **IA spec** (`write-architecture-spec-*`) | Databases | Security, Surfaces |
+| **BE spec** (`write-be-spec-*`) | Languages, Databases, BE Frameworks, ORMs, Unit Tests | Auth |
+| **FE spec** (`write-fe-spec-*`) | Languages, FE Frameworks, FE Design, State Mgmt | Accessibility |
+| **Implementation** (`implement-slice-*`) | Languages, Unit Tests, E2E Tests + surface-specific | All |
+| **Validation** (`validate-phase`) | All | All |
+| **Architecture** (`create-prd-architecture`) | Databases, ORMs | Hosting |
+| **Security** (`create-prd-security`) | — | Security, Auth |
+| **Compile** (`create-prd-compile`) | Unit Tests, E2E Tests | CI/CD |
+
+### 3. Check for empty cells
+
+For each required cell, verify it contains at least one skill name (not `—`, not empty, not a `{{` literal).
+
+### 4. Hard stop on empty cells
+
+When ANY required cell is empty, emit this message for **each** empty cell:
+
+> **Empty map cell:** `{column}` for surface `{surface}`
+> **Filled by:** `/create-prd-stack` when the {component} is confirmed
+> **Recovery:** Run `/create-prd-stack` first to make tech stack decisions, then `/bootstrap-agents` to populate the map.
+> **Impact:** Without this skill, {downstream impact description}.
+
+Then emit:
+
+> ⛔ **HARD STOP** — {N} map cell(s) are empty. This workflow cannot proceed without populated stack data. See recovery steps above.
+
+### 5. Timing fallback (create-prd context)
+
+During `/create-prd`, the map is being built incrementally. If a cell is empty but the value was just confirmed in the current conversation (from `/create-prd-stack`), the workflow may proceed using the conversation-confirmed value. Bootstrap will fill the map after `/create-prd` completes.
+
+This fallback **only** applies to workflows invoked within the `/create-prd` orchestrator. Standalone invocations must have the map populated.
+
+## Recovery Table
+
+| Empty Cell (Per-Surface) | Recovery Command |
+|---|---|
+| Languages | `/create-prd-stack` → confirm language |
+| Databases | `/create-prd-stack` → confirm database(s) |
+| BE Frameworks | `/create-prd-stack` → confirm backend framework |
+| FE Frameworks | `/create-prd-stack` → confirm frontend framework |
+| ORMs | `/create-prd-stack` → confirm ORM |
+| Unit Tests | `/create-prd-stack` → confirm unit testing framework |
+| E2E Tests | `/create-prd-stack` → confirm E2E testing framework |
+| FE Design | `/create-prd-stack` → confirm frontend design approach |
+| State Mgmt | `/create-prd-stack` → confirm state management library |
+
+| Empty Cell (Cross-Cutting) | Recovery Command |
+|---|---|
+| Auth | `/create-prd-stack` → confirm auth provider |
+| Security | `/create-prd-stack` → confirm security framework |
+| CI/CD | `/create-prd-stack` → confirm CI/CD platform |
+| Hosting | `/create-prd-stack` → confirm hosting provider |
+| Accessibility | `/create-prd-stack` → confirm accessibility tooling |
+
+## Commands verification
+
+Additionally verify that `.codex/instructions/commands.md` has non-template values. If the commands section still contains `{{COMMAND_SECTIONS}}`, run `/bootstrap-agents` to fill it.

package/template/.codex/skills/session-continuity/protocols/11-parallel-synthesis.md

@@ -0,0 +1,21 @@
+# Protocol 11: Parallel Synthesis
+
+Run after all parallel agents have completed and QA-GREEN has passed.
+
+## Pre-Synthesis Plan
+
+Before beginning any synthesis work, write a `## Synthesis Plan` section to the slice file (`.memory/pipeline/progress/slices/phase-NN-slice-NN.md`) listing:
+- All `// BOUNDARY:` stubs found across agent outputs (file path + stub description)
+- All cross-surface integrations to wire (e.g., "BE auth middleware → FE token refresh handler")
+
+This gives you a checklist to resume from if the session is interrupted during synthesis.
+
+## Synthesis Steps
+
+1. **Verify no file conflicts** — confirm no file was modified by multiple agents
+2. **Resolve `// BOUNDARY:` stubs** — agents may have created boundary stubs for frozen files (contracts, config). Resolve these now:
+   - Update shared contracts if needed
+   - Install any new dependencies
+   - Wire cross-surface integrations
+3. **Run full validation** — run the Validation Cmd from `.codex/instructions/commands.md` after synthesis
+4. **Create synthesis report** per the `parallel-agents` skill (Synthesize step)

package/template/.codex/skills/session-continuity/protocols/ambiguity-gates.md

@@ -0,0 +1,48 @@
+> **Framework context required**: This is a protocol excerpt. Before following these steps, read `.codex/skills/session-continuity/SKILL.md` for the complete framework — including the Adaptive Granularity Rule, Level Hierarchy Reference, Frozen Files concept, and Parallel Claim protocol. Protocol files are reference documents for specific steps, not standalone instructions.
+
+# Ambiguity Gates (Micro + Macro)
+
+> Part of [Session Continuity](../SKILL.md) — read the index for overview, directory structure, and integration points.
+
+**Invoked by**: Every `write-*-spec` workflow, before "Request review"
+
+**Purpose**: Ensure no guesses pass downstream. Two levels:
+
+## Micro Ambiguity Check
+
+Walk **each individual element** in the spec and ask:
+> "Would an implementer need to guess about this?"
+
+| Workflow | What to check |
+|----------|---------------|
+| `/write-architecture-spec` | Each feature, interaction, data model field, access rule, edge case |
+| `/write-be-spec` | Each endpoint, request/response field, error code, schema constraint, middleware rule |
+| `/write-fe-spec` | Each component, prop, interaction, state transition, responsive breakpoint, a11y rule |
+
+For every element where the answer is "yes" → **fix it now**. Add the missing
+detail, type, behavior, or constraint. Don't flag it — resolve it.
+
+For every element where the answer is "no" — apply the **two-implementer test**: *"Would two different developers, reading only this spec with no other context, make the same implementation decision for this element?"* If the answer is "probably not" or "maybe not" — fix it now. The bar is not "text exists" — it is "unambiguous to any implementer reading cold."
+
+## Macro Ambiguity Check
+
+Step back and ask about the **entire spec**:
+> "Does the next downstream phase have everything it needs?"
+
+| Workflow | Downstream question |
+|----------|---------------------|
+| `/write-architecture-spec` | Would the BE spec writer need to guess anything from this IA shard? |
+| `/write-be-spec` | Would the FE spec writer need to guess anything from this BE spec? |
+| `/write-fe-spec` | Would an implementer running `/implement-slice` need to guess anything? |
+
+If the answer is "yes" → **fix it now**. The spec is not complete until the
+downstream phase can work from it without assumptions.
+
+## Relationship to `/audit-ambiguity`
+
+The ambiguity gates are **inline, lightweight, fix-it-now** checks. The
+`/audit-ambiguity` workflow is a **standalone, scored, report-generating**
+audit you run across multiple documents at once. They complement each other:
+
+- Gates: prevent ambiguity from entering (at write time)
+- Audit: detect ambiguity that slipped through (after the fact)

package/template/.codex/skills/setup/README.md

@@ -0,0 +1,24 @@
+# Setup Skills
+
+This directory contains Codex setup/bootstrap skills for the CFSA pipeline.
+
+## Files
+
+- `setup-cfsa.md` — Orchestrates full bootstrap flow
+- `setup-fill-placeholders.md` — Fills placeholders and stack map values
+- `setup-provision-skills.md` — Provisions skills from skill library via resolver
+- `setup-verify.md` — Verifies installation and readiness
+
+## Extension Pattern
+
+When adding a setup skill:
+1. Use `setup-<name>.md`
+2. Add frontmatter: `name`, `description`, `parameters`
+3. Define deterministic step order and completion checklist
+4. Link from `setup-cfsa.md` orchestration and this README
+
+## Conventions
+
+- Keep setup skills idempotent
+- Do not overwrite existing user values without confirmation
+- Use `.codex/instructions/tech-stack.md` as the source of truth

package/template/.codex/skills/setup/setup-cfsa.md

@@ -0,0 +1,200 @@
+---
+name: setup-cfsa
+description: Main setup workflow for Codex CFSA pipeline — gather project info, fill placeholders, provision skills, verify installation
+parameters:
+  - name: project_name
+    type: string
+    required: true
+    description: Project name
+  - name: description
+    type: string
+    required: true
+    description: Project description
+  - name: surfaces
+    type: array
+    required: true
+    description: List of surfaces (e.g., ["web"], ["web", "api"], ["desktop"])
+  - name: tech_preferences
+    type: object
+    required: false
+    description: Optional tech stack preferences
+---
+
+## Overview
+
+The setup-cfsa skill is the main entry point for configuring the CFSA pipeline in Codex. It gathers project information, fills global placeholders, provisions skills from the skill library, and verifies the installation is ready for pipeline execution.
+
+This is the Codex equivalent of Antigravity's `/bootstrap-agents` workflow.
+
+## Prerequisites
+
+1. Codex is installed and project is open
+2. `.codex/` directory structure exists (created by `cfsa-antigravity init --agent codex`)
+3. User has project idea and tech stack preferences ready
+
+## Step-by-Step
+
+### Step 1 — Gather Project Information
+
+If not provided as parameters, ask the user for:
+
+1. **Project name** — What should we call this project?
+2. **Description** — One-sentence summary of what this project does
+3. **Surfaces** — Which surfaces does this project have?
+   - Single-surface: `["web"]`, `["api"]`, `["desktop"]`, `["mobile"]`
+   - Multi-surface: `["web", "api"]`, `["desktop", "api"]`, `["web", "mobile"]`
+4. **Tech stack preferences** (optional) — Any framework/database preferences?
+
+**Example response:**
+```
+Project: TaskFlow
+Description: AI-powered task management with multi-agent orchestration
+Surfaces: ["web", "api"]
+Preferences: Next.js for frontend, Supabase for database, TypeScript everywhere
+```
+
+### Step 2 — Initialize Global Placeholders
+
+Call skill: `setup/setup-fill-placeholders`
+- Input: `{project_name, description, surfaces, tech_preferences}`
+- Output: Global placeholders filled in root config files
+
+**What gets filled:**
+- `{{PROJECT_NAME}}` → Project name
+- `{{DESCRIPTION}}` → Project description
+- `{{SURFACES}}` → Comma-separated surface list
+- `{{TECH_STACK_SUMMARY}}` → Auto-generated summary from preferences
+
+### Step 3 — Fill Surface Stack Map
+
+Call skill: `setup/setup-fill-placeholders`
+- Surface: Each surface from Step 1
+- Category: All categories (Languages, BE Frameworks, etc.)
+- Input: Tech stack preferences from Step 1
+
+**What gets filled:**
+- Per-Surface Skills table in `.codex/instructions/tech-stack.md`
+- Cross-Cutting Skills table (Auth, CI/CD, Hosting, etc.)
+- Global Settings table
+
+**Handling preferences:**
+- If user provided preferences → Fill those cells
+- If no preferences → Leave cells as `⚠️` (not yet resolved)
+- Prompt user to confirm or provide values for each empty cell
+
+### Step 4 — Provision Skills from Library
+
+Call skill: `setup/setup-provision-skills`
+- Input: Surface Stack Map from Step 3
+- Output: Skills installed from skill library
+
+**Provisioning process:**
+1. Read Surface Stack Map
+2. For each skill name in every cell:
+   - Attempt 4-tier resolution (exact → partial → external → human)
+   - Install matching skills from `.codex/skill-library/`
+   - Fill skill-internal placeholders
+3. Update `{{INSTALLED_SKILLS}}` list
+4. Report results
+
+### Step 5 — Verify Installation
+
+Call skill: `setup/setup-verify`
+- Input: Filled Surface Stack Map + Installed skills
+- Output: Installation verification report
+
+**Verification checks:**
+- [ ] All required directories exist
+- [ ] Surface Stack Map has at least one row
+- [ ] All cells are either filled or marked `—` (not applicable)
+- [ ] No `⚠️` cells remain (unresolved)
+- [ ] All referenced skills are installed
+- [ ] Skill resolver can resolve test case
+- [ ] Root config files have no remaining `{{PLACEHOLDER}}` values
+
+**If verification fails:**
+- Report specific failures
+- Prompt user to fix issues
+- Re-run verification until all checks pass
+
+### Step 6 — Create Initial Progress Tracking
+
+After successful verification, initialize progress tracking:
+
+1. Create master progress file at `.memory/pipeline/progress/spec-pipeline.md`
+2. Set initial state: "Ready to start ideation"
+3. Create session log for today
+4. Recommend next step: `/ideate`
+
+**Progress file structure:**
+```markdown
+# CFSA Pipeline Progress
+
+## Project: {{PROJECT_NAME}}
+
+## Current Stage: ideate
+Last Updated: [ISO timestamp]
+
+## Pipeline Gates
+- [ ] ideate — Discovery phase
+- [ ] create-prd — Architecture and tech stack
+- [ ] decompose-architecture — Shard structure
+- [ ] write-architecture-spec — Interaction specs
+- [ ] write-be-spec — Backend contracts
+- [ ] write-fe-spec — Frontend components
+- [ ] plan-phase — Implementation slices
+- [ ] setup-workspace — Project scaffold
+- [ ] implement-slice — TDD implementation
+- [ ] validate-phase — Quality gates
+
+## Sessions
+- [2026-04-05] — Initial setup completed
+```
+
+## Completion Checklist
+
+- [ ] All parameters collected from user
+- [ ] Global placeholders filled in root configs
+- [ ] Surface Stack Map filled with no `⚠️` cells
+- [ ] All skills provisioned from library
+- [ ] Installation verification passed
+- [ ] Progress tracking initialized
+- [ ] User informed of next steps
+
+## Next Steps
+
+After setup completion, inform the user:
+
+```
+✅ CFSA Pipeline is ready for Codex!
+
+Your project has been configured with:
+- Surfaces: {{SURFACES}}
+- Tech stack: {{TECH_STACK_SUMMARY}}
+- Installed skills: {{INSTALLED_SKILLS_COUNT}}
+
+Next steps:
+1. Run /ideate to start the discovery phase
+2. Or run /status to check your installation status
+
+Documentation:
+- .codex/README.md — Codex version guide
+- docs/ — Project documentation directory
+```
+
+## Error Handling
+
+| Error | Handling |
+|-------|----------|
+| User cancels during Step 1 | Save partial progress, offer to resume |
+| Surface Stack Map can't be read | Fail with clear error — run `cfsa-antigravity init --agent codex` |
+| Skill library missing | Use 4-tier resolution without manifest, warn user |
+| Verification fails | Report specific failures, prompt fixes, don't proceed |
+| Progress tracking already exists | Ask to overwrite or resume existing pipeline |
+
+## See Also
+
+- `.codex/skills/setup/setup-fill-placeholders.md` — Surface Stack Map filling
+- `.codex/skills/setup/setup-provision-skills.md` — Skill provisioning
+- `.codex/skills/setup/setup-verify.md` — Installation verification
+- `.codex/skills/utilities/resolve-skill.md` — 4-tier resolution chain

package/template/.codex/skills/setup/setup-fill-placeholders.md

@@ -0,0 +1,192 @@
+---
+name: setup-fill-placeholders
+description: Fill {{PLACEHOLDER}} values in Surface Stack Map, instructions, rules, and root config files
+parameters:
+  - name: values
+    type: object
+    required: true
+    description: Key-value pairs of placeholders to fill (e.g., {"PROJECT_NAME": "MyApp", "DATABASE": "supabase"})
+  - name: surface
+    type: string
+    required: false
+    description: Surface name for Per-Surface table updates (omit for global/cross-cutting)
+  - name: column
+    type: string
+    required: false
+    description: Column name in Per-Surface table (e.g., "Databases", "FE Frameworks")
+---
+
+## Overview
+
+This skill surgically fills `{{PLACEHOLDER}}` values across the Codex kit. It is idempotent — already-filled placeholders are not overwritten, and new values are only applied where explicitly provided.
+
+Equivalent to Antigravity's `bootstrap-agents-fill.md` shard 1.
+
+## Principles
+
+1. **Surgical** — Only fill placeholders for keys explicitly provided
+2. **Idempotent** — Already-filled values are not touched
+3. **Append-mode** — For table cells, new values are appended to existing (comma-separated)
+4. **Never-destructive** — No placeholder is cleared without a replacement
+
+## Step-by-Step
+
+### Step 1 — Classify Incoming Values
+
+For each key-value pair in the input `values`, classify it:
+
+| Key Pattern | Target |
+|------------|--------|
+| `PROJECT_NAME`, `DESCRIPTION`, `TECH_STACK_SUMMARY`, `SURFACES`, `ARCHITECTURE_DOC` | Global Settings table |
+| `AUTH`, `CI_CD`, `HOSTING`, `SECURITY`, `API_DESIGN`, `ACCESSIBILITY`, `CONTRACT_LIBRARY` | Cross-Cutting Skills table |
+| `CONTRACT_LIBRARY` (also fills `.codex/rules/tdd-contract-first.md`) | Rule templates |
+| `VALIDATION_COMMAND` | `.codex/instructions/commands.md`, root configs |
+| `FRAMEWORK_PATTERNS` | `.codex/instructions/patterns.md` |
+| `PROJECT_STRUCTURE`, `ARCHITECTURE_TABLE` | `.codex/instructions/structure.md` |
+| Surface + column (e.g., `web→Databases=supabase`) | Per-Surface Skills table |
+| `INSTALLED_SKILLS` | tech-stack.md, root configs |
+
+### Step 2 — Fill Per-Surface Skills Table
+
+**Target**: `.codex/instructions/tech-stack.md`
+
+For each surface + column combination:
+
+1. **Row exists, cell has value** → Append new value with `, ` separator if not already present
+   - Example: cell `supabase` + new `surrealdb` → `supabase, surrealdb`
+2. **Row exists, cell is `—`** → Replace with new value
+3. **Row exists, cell is `⚠️...`** → Replace with new value
+4. **Row doesn't exist** → Add new row, fill provided columns, use `—` for others
+
+**Example table manipulation:**
+```markdown
+Before:
+| Surface | Databases | ORMs |
+|---------|-----------|------|
+| web | supabase | drizzle |
+
+After adding web→Databases=surrealdb:
+| Surface | Databases | ORMs |
+|---------|-----------|------|
+| web | supabase, surrealdb | drizzle |
+```
+
+### Step 3 — Fill Cross-Cutting Skills Table
+
+**Target**: `.codex/instructions/tech-stack.md` → Cross-Cutting Skills table
+
+For each cross-cutting key:
+1. **Category exists with value** → Append (skip duplicates)
+2. **Category exists, empty/placeholder** → Set value
+3. **Category doesn't exist** → Add new row
+
+### Step 4 — Fill Global Settings Table
+
+**Target**: `.codex/instructions/tech-stack.md` → Global Settings table
+
+Direct replacement for each key. If key is already filled with a different value, warn the user before overwriting.
+
+### Step 5 — Fill Instruction Templates
+
+For each instruction template:
+
+**`.codex/instructions/commands.md`:**
+```markdown
+## [Surface] Commands
+
+| Command | Value |
+|---------|-------|
+| Package Manager | [from map] |
+| Dev | [from map] |
+| Test | [from map] |
+| Lint | [from map] |
+| Build | [from map] |
+| Validation | [from map] |
+```
+
+Single-surface → flat table, no surface header.
+
+**`.codex/instructions/workflow.md`:**
+- Fill `{{VALIDATION_COMMAND}}` with primary surface's validation command
+
+**`.codex/instructions/patterns.md`:**
+- Replace `{{FRAMEWORK_PATTERNS}}` if provided
+
+**`.codex/instructions/structure.md`:**
+- Replace `{{PROJECT_STRUCTURE}}`, `{{ARCHITECTURE_TABLE}}` if provided
+
+### Step 6 — Fill Rule Templates
+
+Scan `.codex/rules/*.md` for `{{PLACEHOLDER}}` values:
+- `tdd-contract-first.md` → `{{CONTRACT_LIBRARY}}`
+- `security-first.md` → `{{CONTRACT_LIBRARY}}`
+
+Replace each with the resolved value.
+
+### Step 7 — Fill Root Agent Config Files
+
+If `AGENTS.md` and `GEMINI.md` exist at project root, replace in both:
+- `{{PROJECT_NAME}}`
+- `{{DESCRIPTION}}`
+- `{{TECH_STACK_SUMMARY}}`
+- `{{VALIDATION_COMMAND}}`
+- `{{ARCHITECTURE_DOC}}`
+- `{{CONTRACT_LIBRARY}}`
+- `{{INSTALLED_SKILLS}}` (if provided)
+
+Keep both files in sync.
+
+### Step 8 — Fill Skill Templates
+
+Scan all `.codex/skills/*/SKILL.md` for `{{PLACEHOLDER}}` values and fill matches:
+
+| Placeholder | Found In |
+|------------|----------|
+| `{{VALIDATION_COMMAND}}` | fix-bug, main-workflow, deploy, refactor |
+| `{{PACKAGE_MANAGER}}` | refactor, security-audit |
+| `{{TEST_COVERAGE_COMMAND}}` | refactor |
+| `{{BUILD_COMMAND}}` | deploy |
+| `{{DEPLOY_COMMAND}}` | deploy |
+| `{{BUILD_OUTPUT_DIR}}` | deploy |
+
+### Step 9 — Report Results
+
+Return:
+```markdown
+## Placeholder Fill Results
+
+### Map Cells Filled
+- Per-Surface: web→Databases = "supabase, surrealdb"
+- Cross-Cutting: Auth = "lucia-auth"
+
+### Instruction Templates Updated
+- commands.md: Added web commands section
+- workflow.md: Filled validation command
+
+### Rule Templates Updated
+- tdd-contract-first.md: Filled contract library = "zod"
+
+### Remaining Placeholders
+- tech-stack.md: {{SURFACE_ROW}} (no surfaces confirmed yet)
+- tech-stack.md: {{INSTALLED_SKILLS}} (pending provision step)
+
+### Warnings
+- None
+```
+
+## Idempotency Contract
+
+| Scenario | Behavior |
+|----------|----------|
+| Placeholder already filled with same value | No-op, skip silently |
+| Placeholder already filled with different value | Warn user, ask before overwriting |
+| Placeholder is `{{PLACEHOLDER}}` | Fill with value |
+| Placeholder is `—` | Replace with value |
+| Key not provided | Leave as-is, no warning |
+| Table cell already has value, same key appended | Skip duplicate |
+
+## See Also
+
+- `setup-cfsa.md` — Main setup that calls this skill
+- `setup-provision-skills.md` — Skill provisioning (fires after fill)
+- `resolve-skill.md` — 4-tier skill resolution

package/template/.codex/skills/setup/setup-provision-skills.md

@@ -0,0 +1,82 @@
+---
+name: setup-provision-skills
+description: Provision skills from the shared skill library using the Surface Stack Map and 4-tier resolution
+parameters:
+  - name: surfaces
+    type: array
+    required: true
+    description: Surfaces to provision for (e.g. ["web", "api"])
+  - name: strict
+    type: boolean
+    required: false
+    description: If true, fail when any required skill is unresolved
+---
+
+## Overview
+
+This skill provisions Codex skills from `.codex/skill-library/` (shared via symlink to `.codex/skill-library/`) based on `.codex/instructions/tech-stack.md`.
+
+Equivalent to Antigravity's `bootstrap-agents-provision.md` shard.
+
+## Step-by-Step
+
+### 1) Load map and manifest
+
+1. Read `.codex/instructions/tech-stack.md`
+2. Read `.codex/skill-library/MANIFEST.md`
+3. Collect all referenced skill names from:
+   - Per-Surface Skills table for the requested surfaces
+   - Cross-Cutting Skills table
+
+### 2) Resolve each skill
+
+For each referenced skill name, resolve with:
+
+1. **Tier 1 (exact):** `.codex/skills/{name}/SKILL.md` exists or exact manifest mapping exists
+2. **Tier 2 (partial):** partial name match + adequacy check against surface/category
+3. **Tier 3 (external):** discover additional match from skill library taxonomy
+4. **Tier 4 (human):** unresolved → ask user to pick custom path / skip / alternative
+
+Use `.codex/skills/utilities/resolve-skill.md` for resolution behavior.
+
+### 3) Provision
+
+For each resolved library path:
+
+1. Copy library directory into `.codex/skills/{installed-name}/`
+2. Skip copy if already installed (idempotent)
+3. Fill placeholders in copied `SKILL.md` when matching values are available
+
+### 4) Update installed skills list
+
+Write installed skills summary into:
+- `.codex/instructions/tech-stack.md` (`{{INSTALLED_SKILLS}}`)
+- `AGENTS.md` and `GEMINI.md` (if present)
+
+Use sections:
+- Default Skills
+- Stack Skills (Per-Surface)
+- Stack Skills (Cross-Cutting)
+- Surface Skills
+
+### 5) Report
+
+Return:
+- Provisioned skills (new)
+- Already installed skills (skipped)
+- Resolved by partial match (warnings)
+- Unresolved skills (`⚠️`) and required user action
+
+## Idempotency
+
+- Re-running does not duplicate skills
+- Existing installs are preserved
+- New map values add only missing skills
+
+## Completion Checklist
+
+- [ ] Loaded tech stack map and manifest
+- [ ] Resolved all referenced skills via 4-tier chain
+- [ ] Provisioned all resolvable skills
+- [ ] Updated installed-skills lists
+- [ ] Returned unresolved list with action guidance