cfsa-antigravity 2.19.0 → 2.19.2

package/template/.claude/skills/api-versioning/references/typescript.md

@@ -0,0 +1,157 @@
+# TypeScript API Versioning Patterns
+
+Language-specific patterns for the `api-versioning` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## URL Path Versioning
+
+```typescript
+// src/pages/api/v1/models/[id].ts
+export async function GET({ params }: APIContext) {
+  return new Response(JSON.stringify({
+    id: params.id,
+    name: model.name,
+    provider: model.provider,
+    price_per_token: model.pricePerToken, // V1 flat field
+  }));
+}
+
+// src/pages/api/v2/models/[id].ts
+export async function GET({ params }: APIContext) {
+  return new Response(JSON.stringify({
+    id: params.id,
+    name: model.name,
+    provider: model.provider,
+    pricing: { // V2 structured pricing
+      input: model.inputPrice,
+      output: model.outputPrice,
+      currency: 'USD',
+      unit: 'per_million_tokens',
+    },
+  }));
+}
+```
+
+## Header Versioning Middleware
+
+```typescript
+function versionRouter(handlers: Record<string, Handler>): Handler {
+  return async (context) => {
+    const version = context.request.headers.get('API-Version')
+      ?? context.url.searchParams.get('version')
+      ?? DEFAULT_VERSION;
+
+    const handler = handlers[version];
+    if (!handler) {
+      return new Response(JSON.stringify({
+        type: 'https://api.example.com/problems/unsupported-version',
+        title: 'Unsupported API Version',
+        status: 400,
+        detail: `API version '${version}' is not supported.`,
+      }), { status: 400, headers: { 'Content-Type': 'application/problem+json' } });
+    }
+
+    const response = await handler(context);
+    response.headers.set('API-Version', version);
+    return response;
+  };
+}
+```
+
+## Sunset Headers
+
+```typescript
+function addDeprecationHeaders(response: Response, sunsetDate: string, docUrl: string): Response {
+  response.headers.set('Deprecation', 'true');
+  response.headers.set('Sunset', sunsetDate);
+  response.headers.set('Link', `<${docUrl}>; rel="sunset"`);
+  return response;
+}
+
+function sunsetResponse(migrationUrl: string): Response {
+  return new Response(JSON.stringify({
+    type: 'https://api.example.com/problems/gone',
+    title: 'API Version Removed',
+    status: 410,
+    detail: 'This API version has been sunset. Please migrate.',
+    migrationGuide: migrationUrl,
+  }), {
+    status: 410,
+    headers: {
+      'Content-Type': 'application/problem+json',
+      'Link': `<${migrationUrl}>; rel="successor-version"`,
+    },
+  });
+}
+```
+
+## Consumer-Driven Contract Tests (Vitest)
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('Model API Contract (Consumer: Dashboard)', () => {
+  it('GET /api/v1/models/:id returns expected shape', async () => {
+    const response = await fetch(`${API_URL}/api/v1/models/gpt-4`);
+    const data = await response.json();
+
+    expect(data).toMatchObject({
+      id: expect.any(String),
+      name: expect.any(String),
+      provider: expect.any(String),
+    });
+  });
+
+  it('returns 404 for unknown model', async () => {
+    const response = await fetch(`${API_URL}/api/v1/models/nonexistent`);
+    expect(response.status).toBe(404);
+  });
+});
+```
+
+## Full Version Routing Middleware
+
+```typescript
+export function createVersionedRoute(
+  handlers: Record<string, Handler>,
+  options: {
+    defaultVersion?: string;
+    deprecated?: Record<string, { sunset: string; migrationUrl: string }>;
+  } = {}
+): Handler {
+  const { defaultVersion, deprecated = {} } = options;
+
+  return async (context) => {
+    const version = resolveVersion(context.request) ?? defaultVersion;
+
+    if (!version) {
+      return problemResponse({
+        type: 'https://api.example.com/problems/version-required',
+        title: 'API Version Required', status: 400,
+        detail: 'Please specify an API version via the API-Version header.',
+      });
+    }
+
+    if (!(version in handlers)) {
+      return problemResponse({
+        type: 'https://api.example.com/problems/unsupported-version',
+        title: 'Unsupported API Version', status: 400,
+        detail: `Version '${version}' is not supported.`,
+      });
+    }
+
+    const response = await handlers[version](context);
+    response.headers.set('API-Version', version);
+
+    if (version in deprecated) {
+      const { sunset, migrationUrl } = deprecated[version];
+      response.headers.set('Deprecation', 'true');
+      response.headers.set('Sunset', sunset);
+      response.headers.set('Link', `<${migrationUrl}>; rel="sunset"`);
+    }
+
+    return response;
+  };
+}
+```

package/template/.claude/skills/architecture-mapping/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: architecture-mapping
+description: Analyzes codebase structure, data flow, module relationships, and key patterns to generate and maintain a living architecture document (ARCHITECTURE.md).
+---
+
+# Architecture Mapping Skill
+
+You are an expert software architect acting as a cartographer for the codebase. Your job is to analyze the current state of a repository and produce a "living map" of its architecture.
+
+## Core Responsibilities
+
+When invoked, you must:
+
+1.  **Analyze structural layout at a granular level:** Identify exactly where specific functionality lives, listing out key files (e.g., `src/api/worker.ts`, specific domain schemas, core components). **Do not just list directories; list the critical files within them**.
+2.  **Trace data flow explicitly:** Determine how information moves through the system down to the exact environment bindings, database connections (e.g., SurrealDB KV bindings, Worker `Env` interfaces), and request interceptors.
+3.  **Map relationships & contracts:** Detail the actual contract/validation schemas and API routes present in the codebase. If an API worker exists, document its exposed routes, rate limiting, and exact CORS configurations.
+4.  **Extract key patterns:** Identify the architectural decisions and conventions in use, providing exact file references where these patterns are implemented (e.g., CFPA, React Islands).
+5.  **Generate/Update Document:** Write these highly granular findings into a structured `docs/ARCHITECTURE.md` file. Avoid generic boilerplate; if the project only has 3 files, document precisely what those 3 files do.
+
+## Execution Strategy
+
+Follow these strictly granular steps to perform an architecture mapping:
+
+### Step 1: Deep Codebase Reconnaissance
+- **Do not just list directories.** Use your file exploration tools (`list_dir`, `view_file_outline`, `grep_search`) to survey the repository, but immediately follow up by reading the *contents* of key files (`view_file`).
+- Identify exact entry points (`src/api/worker.ts`, `src/pages/index.astro`), configuration files (`astro.config.mjs`, `wrangler.toml`), and trace their imports.
+- Locate exact schemas (contract library schemas, type interfaces, or data models) defining the data models.
+
+### Step 2: Component & Contract Analysis
+- Group files logically, but identify the specific files governing these components.
+- For each component, trace its exact validation schemas, API routes, or component props.
+- Document exact environment variables and secrets expected by the code.
+
+### Step 3: Granular Dependency Tracing
+- Trace exactly how components interact (e.g., "The `login` Astro page fetches data directly from SurrealDB using the `surrealdb.js` client in `src/lib/db.ts`").
+- Explicitly catalog external integrations down to the binding name (e.g., "KVNamespace RATE_LIMITS").
+
+### Step 4: Pattern Extraction
+- Read the implementation details of representative files to prove use of architectural patterns.
+- If the project uses CFPA, locate the schema, the test, and the implementation file as proof.
+
+## 5. Document Generation
+Create or update `docs/ARCHITECTURE.md` using the following structure:
+
+```markdown
+# [Project Name] - Living Architecture Map
+
+**Last Updated:** [Current Date]
+**Purpose:** Deep, granular code context, environmental bindings, and exact architectural tracing.
+
+---
+
+## 1. Codebase Topography & Critical Files
+
+### Directory Tree
+(You MUST include a full, comprehensive file/folder tree of the `src/` directory and any other relevant project directories. Do not summarize this; show the actual files.)
+```text
+/
+├── src/
+│   ├── api/
+│   │   └── worker.ts
+│   └── ...
+```
+
+### Critical Files
+(Identify exactly where specific functionality lives, listing out key files defined in the tree above. Do not just list directories; explain what the critical files within them do.)
+
+## 2. Infrastructure & Explicit Data Flow
+(Determine how information moves through the system down to the exact environment bindings, database connections, and request interceptors.)
+
+## 3. Module Relationships & Contracts
+(Detail the actual contract/validation schemas and API routes present. Document exposed routes, rate limiting, and exact CORS configurations.)
+
+## 4. Key Patterns & Implementation Evidence
+(Identify architectural decisions, providing exact file references where these patterns are implemented.)
+```
+
+## Best Practices
+
+*   **Granularity is Mandatory:** Do not describe the system abstractly. Use exact file paths, exact schema names, and exact environment binding names.
+*   **Trace the Code:** Never guess architectural boundaries. Use `grep_search` and `view_file` to trace imports and confirm how modules interact before documenting them.
+*   **Be Explicit:** Avoid boilerplate. If an API has 3 endpoints, list the 3 endpoints and their exact validation schemas.
+*   **Living Document:** If updating an *existing* `ARCHITECTURE.md`, do not simply append. Integrate new, granular findings holistically into the existing structure. Update the "Last Updated" date.
+
+## Domain Boundary Protocol
+
+### Purpose
+
+Run this protocol before proposing domain boundaries. Uses a domain inventory record to evaluate every candidate domain.
+
+### Domain Inventory Record Format
+
+For each candidate domain, build a record in the following format:
+
+```
+Domain: [name]
+Architecture description: [one-line summary from architecture design]
+Ideation sub-features:
+  1. [Actor] can [goal] → primary data: [entity/table]
+  2. [Actor] can [goal] → primary data: [entity/table]
+  ...
+Split trigger: [none | review | mandatory-split]
+```
+
+Read the relevant ideation domain folders (use `ideation-index.md` Structure Map for correct paths — folders may be under `domains/` or `surfaces/{name}/`). For each domain, read the `*-index.md` for the children table, then each child feature file for sub-feature details. Use the architecture design as secondary context to build each record.
+
+### Split Trigger Rules
+
+Apply all three rules to every domain:
+
+1. **Child-count proxy** — If the ideation domain folder contains ≥6 direct child feature files (or the fractal tree has depth ≥3 levels below this domain), flag as `mandatory-split`.
+
+2. **3-table rule** — If the domain's sub-features touch ≥3 independent database tables with no shared queries, flag as `mandatory-split`.
+
+3. **No-shared-query test** — If two sub-feature groups within a domain could each be assigned to a different developer without coordination (no shared API endpoints, no shared data mutations), flag as `review`.
+
+### Domain Boundary Table Template
+
+| # | Domain | Features Included | Sub-feature Count | Complexity | Split Candidate? | Needs Deep Dive? |
+|---|--------|-------------------|-------------------|------------|-----------------|------------------|
+| 00 | Cross-cutting | Auth, API conventions, error handling | — | Medium | — | No |
+| 01 | [Domain] | [Features] | [N] | [Low/Med/High] | [Yes/No — reason] | [Yes/No] |
+
+### User Approval Protocol
+
+Present split candidates to the user before finalising the domain boundary table. For each candidate show:
+
+- Domain name
+- Sub-feature list
+- Proposed split boundary
+- Rationale
+
+User must approve or reject each split before the table is locked.
+
+### Shard Numbering Convention
+
+- `00-*` for cross-cutting concerns (may be multiple)
+- `01-*` through `NN-*` for feature domains ordered by dependency (dependencies first)
+
+## Sub-Feature Reconciliation Protocol
+
+### Purpose
+
+Run this protocol when beginning any architecture spec shard. The ideation domain's feature files (within the fractal tree) are the primary source of truth for sub-features — the architecture design is secondary context.
+
+### Sources to Read
+
+1. The relevant ideation domain folder for this shard (path from `ideation-index.md` Structure Map) — read the `*-index.md` then each child feature file
+2. The shard's `## Features` section
+3. `docs/plans/ideation/ideation-index.md` Must Have features for this domain
+
+### Reconciliation Table
+
+| Sub-feature | Ideation domain tree | Shard ## Features | Must Have? | Decision |
+|-------------|-------------|-------------------|------------|----------|
+| [name] | ✅ Listed | ✅ Listed | Yes/No | Keep |
+| [name] | ✅ Listed | ❌ Missing | Yes | **Add to shard immediately** |
+| [name] | ✅ Listed | ❌ Missing | No | Add to shard — ideation is authoritative |
+| [name] | ❌ Not listed | ✅ Listed | — | `[Architecture-only — not in ideation]` — keep but audit |
+
+### Mismatch Handling Rules
+
+1. If a sub-feature appears in the ideation domain tree but not in the shard's `## Features` → **add it to the shard's `## Features` section immediately** before proceeding. Do not wait for user confirmation to add ideation-sourced sub-features.
+
+2. If a sub-feature appears in the shard's `## Features` but not in the ideation domain tree → **keep it** but mark it with `[Architecture-only — not in ideation]` as an audit trail. These items need explicit user confirmation.
+
+### Scope Confirmation Presentation Format
+
+Present the reconciled scope to the user in the following format:
+
+> **Reconciled features for [Shard NN — Domain Name]:**
+>
+> [bullet list of all sub-features, with `[Architecture-only]` markers where applicable]
+>
+> **[N] sub-features added from ideation** that were missing from the shard skeleton.
+> **[M] sub-features marked `[Architecture-only]`** — not found in ideation domain tree, added during decomposition.
+>
+> "Does this feature list match your intent for this domain? Any sub-features to add, remove, or re-scope?"
+
+Wait for explicit user confirmation before proceeding. If the user modifies the list, update the shard file immediately.
+
+## Sub-Feature Complexity Split Protocol
+
+### Purpose
+
+Run this protocol after reconciliation when the confirmed sub-feature count is **≥ 10**. This threshold indicates the shard is too complex for a single spec pass and must be split before writing proceeds.
+
+### Counting Rule
+
+Count every bullet or named item under the confirmed feature list, excluding group headers. Use the same counting rule as `/decompose-architecture-validate` Step 12.
+
+### Split Proposal Format
+
+Present to the user:
+
+```
+Shard [NN] — [domain name] has [N] sub-features (threshold: ≥10 → mandatory split)
+
+Current sub-features:
+  1. [sub-feature]
+  2. [sub-feature]
+  ...
+
+Proposed split:
+  [NN]a — [new domain name] → file: docs/plans/ia/[NN]a-[domain].md
+    Sub-features: 1, 3, 5
+  [NN]b — [new domain name] → file: docs/plans/ia/[NN]b-[domain].md
+    Sub-features: 2, 4, 6
+
+Split rationale: [why these groups are independent]
+
+Does this split make sense, or would you prefer a different boundary?
+```
+
+### Approval Gate
+
+**Wait for explicit user approval of the split before proceeding.** Do NOT continue spec writing with an oversized shard.
+
+If the user approves: stop the current workflow and run `/decompose-architecture-validate` to formally register the new shards (it will re-run the Must Have coverage gate and update the decomposition plan). Then run `/remediate-shard-split` to update all downstream cross-references — do NOT restart spec work until zero stale parent references remain. Then restart the spec workflow for each new shard individually.

package/template/.claude/skills/bootstrap-agents/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: bootstrap-agents
+description: "Utility — fill the surface stack map in tech-stack.md and provision skills using intelligent resolution. Called by pipeline commands when tech stack info changes."
+version: 3.0.0
+---
+
+# Bootstrap Agents
+
+**This is a utility command, not an entry point.** It gets called by other pipeline commands (like `/create-prd`, `/write-be-spec`, `/write-fe-spec`, `/implement-slice`) whenever they make tech stack decisions or introduce new dependencies.
+
+Bootstrap does two things:
+1. **Fill the surface stack map** in `.agent/instructions/tech-stack.md` with stack decisions
+2. **Provision skills** from `skill-library/` using the 4-tier resolution chain
+
+**Input**: Surface-keyed stack values + optional global values
+**Output**: Filled map cells + newly installed skills in `.agent/skills/`
+
+---
+
+## 1. Receive values
+
+The calling command provides values in two categories:
+
+### Surface-Keyed Values (fill the Per-Surface Skills table)
+
+Each value is tagged with a surface. Format: `SURFACE=<surface> KEY=<value>`
+
+Example invocation from `/create-prd-stack`:
+```
+SURFACE=shared  LANGUAGES=typescript  BE_FRAMEWORKS=hono  DATABASES=supabase,surrealdb  ORMS=drizzle
+SURFACE=web     LANGUAGES=typescript  FE_FRAMEWORKS=astro  FE_DESIGN=tailwind,vanilla-css  STATE_MGMT=nanostores  DATABASES=supabase,surrealdb  UNIT_TESTS=vitest  E2E_TESTS=playwright
+SURFACE=desktop LANGUAGES=typescript,rust  FE_FRAMEWORKS=—  BE_FRAMEWORKS=tauri  DATABASES=supabase,surrealdb,pglite,surrealdb-embedded  UNIT_TESTS=vitest,cargo-test
+```
+
+Per-surface column keys:
+
+| Column Key | Map Column | Example |
+|-----------|------------|---------|
+| `LANGUAGES` | Languages | typescript, rust |
+| `BE_FRAMEWORKS` | BE Frameworks | hono, tauri |
+| `FE_FRAMEWORKS` | FE Frameworks | astro, react-native |
+| `FE_DESIGN` | FE Design | tailwind, vanilla-css |
+| `ORMS` | ORMs | drizzle |
+| `STATE_MGMT` | State Mgmt | nanostores, zustand |
+| `DATABASES` | Databases | supabase, surrealdb, pglite |
+| `UNIT_TESTS` | Unit Tests | vitest, cargo-test |
+| `E2E_TESTS` | E2E Tests | playwright, detox |
+| `TEST_CMD` | Test Cmd | npm test |
+| `VALIDATION_CMD` | Validation Cmd | npm run validate |
+| `LINT_CMD` | Lint Cmd | npm run lint |
+| `BUILD_CMD` | Build Cmd | npm run build |
+| `DEV_CMD` | Dev Cmd | npm run dev |
+| `PACKAGE_MGR` | Package Mgr | npm |
+
+### Cross-Cutting Values (fill the Cross-Cutting Skills table)
+
+These are project-wide, not per-surface:
+
+| Key | Map Category | Example |
+|-----|-------------|---------|
+| `AUTH` | Auth | clerk, supabase-auth |
+| `CI_CD` | CI/CD | github-actions |
+| `HOSTING` | Hosting | vercel, tauri-updater |
+| `SECURITY` | Security | owasp-web, desktop-sandboxing |
+| `API_DESIGN` | API Design | api-design-principles |
+| `ACCESSIBILITY` | Accessibility | accessibility |
+| `CONTRACT_LIBRARY` | Contract Library | zod |
+
+### Global Values (fill Global Settings in tech-stack.md + root configs)
+
+| Key | Example |
+|-----|---------|
+| `PROJECT_NAME` | RepairYour.Tech |
+| `DESCRIPTION` | One-line description |
+| `TECH_STACK_SUMMARY` | Supabase + SurrealDB + Astro + Tauri |
+| `SURFACES` | web, desktop, mobile |
+| `ARCHITECTURE_DOC` | docs/plans/2026-03-13-architecture-design.md |
+
+### Structural Values (fill instruction templates — unchanged from v2)
+
+| Key | Example |
+|-----|---------|
+| `FRAMEWORK_PATTERNS` | Framework-specific patterns block |
+| `PROJECT_STRUCTURE` | Directory layout block |
+| `ARCHITECTURE_TABLE` | Concern/Location/Runtime table rows |
+
+### Infrastructure Values (fill instruction templates — unchanged from v2)
+
+| Key | Example |
+|-----|---------|
+| `SSH_HOST` | my-vps |
+| `DB_PORT` | 19000 |
+| `CREDENTIAL_TOOL` | agent-auth ssh-add |
+| `SECRET_MANAGEMENT` | wrangler secret |
+| `DEPLOY_COMMAND` | wrangler deploy |
+
+If any values are missing, leave those cells empty — they'll be filled on a future invocation.
+
+---
+
+## 2. Fill the surface stack map
+
+Open `.agent/instructions/tech-stack.md` and update:
+
+### 2a. Per-Surface Skills table
+
+For each `SURFACE=<name>` received:
+1. If a row for `<name>` exists → update the cells for the provided column keys only (don't overwrite cells that already have values unless explicitly re-provided)
+2. If no row exists → add a new row with the provided values, `—` for unprovided columns
+
+### 2b. Cross-Cutting Skills table
+
+For each cross-cutting key received, update the corresponding category row. If the value is additive (e.g., adding a second database), **append** to the comma-separated list rather than overwriting. If the value is already present, skip (idempotent).
+
+### 2c. Global Settings
+
+Fill the Global Settings table with any provided global values.
+
+---
+
+## 3. Fill root agent config files
+
+Replace in **both** `AGENTS.md` and `GEMINI.md`:
+- `{{PROJECT_NAME}}`
+- `{{DESCRIPTION}}`
+- `{{TECH_STACK_SUMMARY}}`
+- `{{VALIDATION_COMMAND}}` — use the **primary surface's** validation command from the map (first non-shared row, or shared if only shared exists)
+- `{{ARCHITECTURE_DOC}}`
+- `{{CONTRACT_LIBRARY}}`
+- `{{INSTALLED_SKILLS}}` (if provided; otherwise leave for step 8)
+
+> **Note**: Both files serve as root agent config. Both must be kept in sync — any value filled in one must be filled in the other.
+
+---
+
+## 4. Fill instruction templates
+
+### `.agent/instructions/commands.md`
+Write per-surface command sections. For each surface in the map, create a section with its commands (Test Cmd, Validation Cmd, Lint Cmd, Build Cmd, Dev Cmd, Package Mgr).
+
+### `.agent/instructions/workflow.md`
+Fill `{{VALIDATION_COMMAND}}` with the primary surface's validation command.
+
+### `.agent/instructions/patterns.md`
+Replace `{{FRAMEWORK_PATTERNS}}` if provided.
+
+### `.agent/instructions/structure.md`
+Replace `{{PROJECT_STRUCTURE}}`, `{{ARCHITECTURE_TABLE}}` if provided.
+
+---
+
+## 5. Fill operational skill and rule templates
+
+Scan `.agent/skills/*/SKILL.md` and `.agent/rules/*.md` for `{{PLACEHOLDER}}` values and fill any that match the provided values. Currently applicable:
+
+- `{{VALIDATION_COMMAND}}` — in `fix-bug`, `main-workflow`, `deploy`, `refactor`
+- `{{PACKAGE_MANAGER}}` — in `refactor`, `security-audit`
+- `{{CONTRACT_LIBRARY}}` — in `tdd-contract-first.md`
+- Other command/infra placeholders as documented in v2
+
+---
+
+## 6. Read skill library manifest
+
+Read `skill-library/MANIFEST.md` to load the trigger tables.
+
+If `skill-library/MANIFEST.md` does not exist, skip steps 7-8 and go to step 9.
+
+---
+
+## 7. Provision skills — 4-Tier Resolution Chain
+
+For each skill name referenced in ANY cell of the surface stack map, resolve it using this chain:
+
+### Tier 1: Exact Match
+Check `.agent/skill-library/{name}/` (or `.agent/skills/{name}/` if already installed).
+- **Found in library** AND not yet installed → copy to `.agent/skills/{name}/`, fill any `{{PLACEHOLDER}}`s in the copied SKILL.md
+- **Already installed** → skip (idempotent)
+- **Not found** → proceed to Tier 2
+
+### Tier 2: Partial Match + Adequacy Check
+Search `.agent/skill-library/` and `.agent/skills/` for skills whose name contains the base term. E.g., for `surrealdb-embedded`, check if `surrealdb` exists.
+
+- **Partial match found** → Read its `SKILL.md`. Assess: does it cover the needed variant? Check for keywords related to the specific need (e.g., "embedded", "WASM", "Rust-native" for `surrealdb-embedded`).
+  - **Adequate** — the existing skill covers the variant → use it. Note in the report: `"{name}" resolved by existing "{partial}" skill (covers {variant})`.
+  - **Falls short** — the skill doesn't address the specific variant → proceed to Tier 3
+- **No partial match** → proceed to Tier 3
+
+### Tier 3: External Discovery
+Read `.agent/skills/find-skills/SKILL.md` and invoke its discovery methodology to search for the skill externally.
+
+- **Found** → install → fill map cell with resolved name
+- **Not found** → proceed to Tier 4
+
+### Tier 4: Human Escalation
+Mark the map cell with `⚠️ {name} [not found]`. Include in the report:
+
+> "Skill `{name}` was not found in the skill library, via partial match, or externally. Options:
+> 1. Create it with `/skill-creator`
+> 2. Provide an alternative skill name
+> 3. Mark as not needed (change cell to `—`)"
+
+### Resolution reporting
+After resolving all skills, report:
+- Which skills were installed (Tier 1)
+- Which skills were resolved by adequacy check (Tier 2) — include justification
+- Which skills were discovered externally (Tier 3)
+- Which skills need human attention (Tier 4) — include the `⚠️` cells
+
+---
+
+## 8. Update installed skills list
+
+After provisioning, build a markdown list of all installed skills and update `{{INSTALLED_SKILLS}}` in `tech-stack.md`:
+
+```markdown
+### Default Skills
+- fix-bug — TDD bug fix workflow
+- refactor — Safe refactoring with test verification
+- ...
+
+### Stack Skills (Per-Surface)
+- [skill-name] — [description] (surface: [surface], column: [column])
+- ...
+
+### Stack Skills (Cross-Cutting)
+- [skill-name] — [description] (category: [category])
+- ...
+
+### Surface Skills
+- [skill-name] — [description] (installed for [surface] surface)
+- ...
+```
+
+---
+
+## 9. Report results
+
+Present the results to the calling command (not directly to the user — the calling command handles user communication):
+
+- Which map cells were filled (and their values)
+- Which map cells remain empty
+- Skill resolution report (from step 7)
+- Which skills were already installed and skipped
+- Any `⚠️` cells requiring user attention
+- Any errors (missing files, missing library paths)
+
+---
+
+## Idempotency
+
+Bootstrap is safe to call multiple times:
+
+- **Already-filled map cells**: Cells with values are NOT overwritten unless the calling command explicitly re-provides a value for that surface + column
+- **Already-installed skills**: Skills that already exist in `.agent/skills/` are not re-copied from the library
+- **New surface rows**: New surfaces trigger new row creation without affecting existing rows
+- **Appending values**: Cross-cutting skills and accumulated columns append to existing comma-separated lists without duplicating
+- **Partial invocation**: Bootstrap can be called with just one surface or one key — it only fills what's provided