cfsa-antigravity 2.0.0 → 2.2.0

package/template/.agent/workflows/bootstrap-agents-provision.md

@@ -1,5 +1,5 @@
 ---
-description: Skill library provisioning, workflow placeholder filling, and result reporting for the bootstrap-agents workflow
+description: Skill library provisioning using 4-tier resolution chain and map cell filling for the bootstrap-agents workflow
 parent: bootstrap-agents
 shard: provision
 standalone: true
@@ -9,7 +9,7 @@ pipeline:
   stage: provisioning
   predecessors: [bootstrap-agents-fill]
   successors: []
-  skills: [prd-templates]
+  skills: [prd-templates, find-skills]
   calls-bootstrap: false
 ---
 
@@ -17,9 +17,9 @@ pipeline:
 
 # Bootstrap Agents — Provision Skills
 
-Read the skill library manifest, provision matching skills, fill workflow placeholders, and report results.
+Read the surface stack map, resolve each skill using the 4-tier chain, provision from the library, and report results.
 
-**Prerequisite**: If invoked standalone, the caller must have template values available (from a previous `/bootstrap-agents-fill` run or direct invocation with stack/surface keys).
+**Prerequisite**: The surface stack map in `.agent/instructions/tech-stack.md` must have at least one row with filled cells (from a previous `/bootstrap-agents-fill` run).
 
 ---
 
@@ -27,112 +27,111 @@ Read the skill library manifest, provision matching skills, fill workflow placeh
 
 Read `.agent/skill-library/MANIFEST.md` to load the trigger tables.
 
-If `.agent/skill-library/MANIFEST.md` does not exist (e.g., user deleted it or is using a minimal kit), skip steps 7-8 and go to step 9.
+If `.agent/skill-library/MANIFEST.md` does not exist (e.g., user deleted it or is using a minimal kit), use only Tier 2-4 resolution (no manifest matching).
 
 ---
 
-## 7. Provision skills from library
+## 7. Provision skills — 4-Tier Resolution Chain
 
-For each stack key provided in the template values, check the **Stack Triggers** table in the manifest:
+Read the surface stack map from `.agent/instructions/tech-stack.md`. For **every skill name** referenced in any cell of both the Per-Surface Skills table and Cross-Cutting Skills table, resolve it:
 
-1. Match the provided value against the manifest's `Value Pattern` (case-insensitive)
-2. If a match is found AND the skill is NOT already in `.agent/skills/[installed-as]/`:
-   - Copy the entire directory from `.agent/skill-library/[library-path]/` → `.agent/skills/[installed-as]/`
-   - Fill any `{{PLACEHOLDER}}`s in the newly-copied `SKILL.md` with current template values
-3. If the skill already exists in `.agent/skills/`, skip it (idempotent)
+### Tier 1: Exact Match
 
-For each surface type provided in `SURFACES`, check the **Surface Triggers** table:
+Check `.agent/skills/{name}/` (already installed) and `.agent/skill-library/{name}/`:
 
-1. Match the surface type against the manifest's `Surface Type` column
-2. Copy matching skills that don't already exist, same as above
+- **Already installed** → skip (idempotent) ✅
+- **Found in library** → copy directory to `.agent/skills/{name}/`, fill any `{{PLACEHOLDER}}`s in the copied SKILL.md ✅
+- **Not found** → check manifest `Value Pattern` matches (glob-style, case-insensitive) → if matched, install the mapped skill → update the map cell to use the installed directory name ✅
+- **Still not found** → proceed to Tier 2
 
-### Matching rules
+### Tier 2: Partial Match + Adequacy Check
 
-| Manifest Pattern | Matches |
-|-----------------|---------|
-| `*surrealdb*` | "SurrealDB", "surrealdb (self-hosted)", "SurrealDB Cloud" |
-| `*cloudflare*` | "Cloudflare Workers", "Cloudflare Pages + Workers" |
-| `*tailwind*` | "Tailwind CSS v4", "Tailwind CSS" |
-| `*vercel*` OR `*ai-sdk*` | "Vercel AI SDK", "AI SDK" |
-| `*three*` OR `*r3f*` | "Three.js", "React Three Fiber", "R3F" |
+Search `.agent/skills/` and `.agent/skill-library/` for skills whose name contains the base term (e.g., for `surrealdb-embedded`, check `surrealdb`):
 
-Pattern matching is glob-style with `*` as wildcard, case-insensitive.
+1. **Partial match found** → read its `SKILL.md`
+2. **Assess adequacy**: Does the skill cover the needed variant? Check for:
+   - Keywords matching the variant (e.g., "embedded", "WASM", "Rust-native")
+   - Sections addressing the use case
+   - Examples relevant to the variant
+3. **Adequate** → use the existing skill. Report: `"{name}" resolved by existing "{partial}" skill (covers {variant})` ✅
+4. **Falls short** → the skill doesn't address the variant. Proceed to Tier 3.
 
----
-
-## 8. Update installed skills list
-
-After provisioning, build a markdown list of all installed skills (both defaults and library-provisioned) and update `{{INSTALLED_SKILLS}}` in the tech stack instruction.
-
-Also update `{{INSTALLED_SKILLS}}` in `AGENTS.md` and `GEMINI.md` with the same installed skills list. These root agent config files must reflect the full skill inventory so agents reading them have complete context.
-
-Read `.agent/skills/prd-templates/references/operational-templates.md` for the **Installed Skills List** template. Use the template structure, filling in actual installed skill names and descriptions.
+### Tier 3: External Discovery
 
-### 8.5. Compose and fill FRAMEWORK_PATTERNS
+Read `.agent/skills/find-skills/SKILL.md` and invoke its methodology:
 
-Identify any frontend-capable framework skill provisioned or matched during this invocation by checking across all relevant stack axes:
+1. Search for the skill externally
+2. **Found** → install → fill map cell with resolved name ✅
+3. **Not found** → proceed to Tier 4
 
-| Stack Axis | Example Skills |
-|------------|---------------|
-| `FRONTEND_FRAMEWORK` | `nextjs`, `astro-framework`, `sveltekit`, `nuxt`, `react-best-practices` |
-| `MOBILE_FRAMEWORK` | `expo-react-native` |
+### Tier 4: Human Escalation
 
-If any of these axes resolved to a provisioned skill in Step 7, use that skill for composition.
+Mark the map cell with `⚠️ {name} [not found]`. Add to the report:
 
-**If a frontend-capable framework skill is present:**
-1. Read the installed skill's `SKILL.md` from `.agent/skills/[installed-as]/SKILL.md`
-2. Extract the component patterns section (file structure, naming conventions, composition patterns, what to avoid)
-3. Compose a `FRAMEWORK_PATTERNS` markdown block summarising these component conventions
-4. Fire `bootstrap-agents-fill` with `FRAMEWORK_PATTERNS=[composed value]` to fill the `## Components` section of `.agent/instructions/patterns.md`
-5. If multiple frontend-capable skills are present (e.g., `FRONTEND_FRAMEWORK` + `MOBILE_FRAMEWORK`), merge their patterns into a single `FRAMEWORK_PATTERNS` block with clearly labelled sections per surface
+> 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 `—`)
 
-This step is idempotent — it can be re-run on existing projects to fill `patterns.md` without re-provisioning the skill. For remediation flows, provide the relevant stack axis value(s) so this step resolves the correct skill(s).
+---
 
-**If no frontend-capable framework skill is present:** Skip — `patterns.md` already has a sensible fallback for non-visual projects.
+## 8. Update installed skills list
 
----
+After provisioning, build a markdown list of all installed skills and update `{{INSTALLED_SKILLS}}` in:
+- `.agent/instructions/tech-stack.md`
+- `AGENTS.md`
+- `GEMINI.md`
 
-## 9. Fill workflow skill placeholders
+Read `.agent/skills/prd-templates/references/operational-templates.md` for the **Installed Skills List** template. Organize skills by:
 
-In the generic workflows, replace the following placeholders with the **directory name** of the installed skill (e.g., `surrealdb-expert`, `typescript-advanced-patterns`). The surrounding path `.agent/skills/.../SKILL.md` is hardcoded in each workflow. If no skill was installed for a given category, instruct the agent to skip it or provide a reasonable default.
+```markdown
+### Default Skills
+- fix-bug — TDD bug fix workflow
+- refactor — Safe refactoring with test verification
+- ...
 
-### DATABASE_SKILLS accumulation logic
+### Stack Skills (Per-Surface)
+- [skill-name] — [description] (surface: [surface], column: [column])
+- ...
 
-`{{DATABASE_SKILLS}}` is a comma-separated list of installed skill directory names (one per confirmed database store, e.g., `postgresql,qdrant,redis`). Bootstrap appends the new skill name to the existing list value rather than overwriting it. If the list is empty, set it to the single name. If the name is already present, skip (idempotent).
+### Stack Skills (Cross-Cutting)
+- [skill-name] — [description] (category: [category])
+- ...
 
-The following sub-keys all trigger the `{{DATABASE_SKILLS}}` accumulation logic:
-- `DATABASE_PRIMARY` — Main relational/document/multi-model store
-- `DATABASE_VECTOR` — Semantic search, embeddings, similarity
-- `DATABASE_GRAPH` — Graph traversal, relationship queries
-- `DATABASE_CACHE` — Caching layer
-- `DATABASE_TIMESERIES` — Time-ordered data, metrics, IoT
+### Surface Skills
+- [skill-name] — [description] (installed for [surface] surface)
+- ...
+```
 
-> **Backward compatibility**: If the incoming key is `DATABASE`, treat it as `DATABASE_PRIMARY` and proceed identically.
+---
 
-### SECURITY_SKILLS accumulation logic
+## 8.5. Compose and fill FRAMEWORK_PATTERNS
 
-`{{SECURITY_SKILLS}}` is a comma-separated list of all security skill directory names provisioned for this project. Bootstrap appends the new skill name to the existing list value rather than overwriting it. If the list is empty, set it to the single name. If the name is already present, skip (idempotent).
+Identify any frontend-capable framework skill provisioned during this invocation:
 
-The following keys all contribute to `{{SECURITY_SKILLS}}` accumulation:
-- `SECURITY` — Explicit user-named security skill (e.g., `SECURITY=owasp-web-security`)
-- Surface trigger: web → appends `owasp-web-security`, `csp-cors-headers`, `input-sanitization`
-- Surface trigger: api → appends `input-sanitization` (if not already present)
-- Surface trigger: desktop → appends `desktop-security-sandboxing`
-- Surface trigger: any → appends `dependency-auditing`
+| Stack Axis | Example Skills |
+|------------|---------------|
+| FE Frameworks | `nextjs`, `astro-framework`, `sveltekit`, `nuxt`, `react-best-practices` |
+| BE Frameworks (with desktop UI) | `tauri` |
 
-`{{SECURITY_SKILLS}}` is used in `create-prd-security.md` Step 6 to load all relevant security skills before designing the security model.
+Check the map's FE Frameworks and BE Frameworks columns across ALL surfaces. If any resolved to a skill with component patterns:
 
-### Placeholder → Workflow mapping
+1. Read the installed skill's `SKILL.md`
+2. Extract component patterns (file structure, naming, composition, what to avoid)
+3. Compose a `FRAMEWORK_PATTERNS` markdown block
+4. Fire `bootstrap-agents-fill` with `FRAMEWORK_PATTERNS=[composed value]`
+5. If multiple frontend-capable skills across surfaces → merge with labelled sections per surface
 
-Read `.agent/skills/prd-templates/references/placeholder-workflow-mapping.md` for the full mapping table of placeholders → source keys → consuming workflows.
+---
 
-### 9.1. CONTRACT_LIBRARY resolution
+## 9. CONTRACT_LIBRARY resolution
 
-This step fires when the `LANGUAGE` key is confirmed (either from the current invocation or from an already-filled `tech-stack.md`).
+This step fires when ANY Languages cell is confirmed.
 
-Derive `CONTRACT_LIBRARY` using the following mapping table:
+For each unique language across all surfaces, derive `CONTRACT_LIBRARY`:
 
-| `LANGUAGE` value | `CONTRACT_LIBRARY` value |
+| Language | Contract Library |
 |---|---|
 | TypeScript / JavaScript | Zod |
 | Python | Pydantic |
@@ -140,43 +139,27 @@ Derive `CONTRACT_LIBRARY` using the following mapping table:
 | Rust | Serde |
 | Java | Jakarta Bean Validation |
 | Kotlin | kotlinx.serialization |
-| C / C++ | (prompt user — no dominant standard) |
-| Bash / Shell | (none — validate inline with functions) |
+| C / C++ | (prompt user) |
+| Bash / Shell | (none) |
 
-For any language **not in this table**: prompt the user — "What is your preferred schema validation / contract library for [LANGUAGE]?" — and use their confirmed answer as the `CONTRACT_LIBRARY` value.
-
-Once the value is confirmed, invoke `bootstrap-agents-fill` with `CONTRACT_LIBRARY=[value]` so that `tdd-contract-first.md` is filled at the same time as the language skill is provisioned (the fill workflow's extended Step 3 scan will now reach `.agent/rules/`).
-
----
+For languages **not in this table**: prompt the user.
 
-## 9.5. Fill workflow command placeholders
-
-Workflows use `{{COMMAND}}` placeholders for test, lint, build, and validation commands. Replace them with the values gathered during tech stack decisions (step 1).
-
-In `.agent/workflows/implement-slice-tdd.md`:
-- `{{TEST_COMMAND}}` → the project's test runner command
-- `{{VALIDATION_COMMAND}}` → the full validation pipeline command
-
-In `.agent/workflows/validate-phase.md`:
-- `{{TEST_COMMAND}}` → the project's test runner command
-- `{{TEST_COVERAGE_COMMAND}}` → the test runner with coverage enabled
-- `{{LINT_COMMAND}}` → the linter command
-- `{{TYPE_CHECK_COMMAND}}` → the type checker command
-- `{{BUILD_COMMAND}}` → the production build command
-
-In `.agent/workflows/evolve-contract.md`:
-- `{{TEST_COMMAND}}` → the project's test runner command
-- `{{VALIDATION_COMMAND}}` → the full validation pipeline command
+> **Multi-language**: If the project uses multiple languages (e.g., TypeScript + Rust), set `CONTRACT_LIBRARY` to a comma-separated list: `zod, serde`. Update `tdd-contract-first.md` to reference the appropriate library based on the file's language.
 
+Fire `bootstrap-agents-fill` with `CONTRACT_LIBRARY=[value]` to fill `tdd-contract-first.md`.
 
 ---
 
 ## 10. Report results
 
-Return to the calling workflow a summary:
-
-- Which `{{PLACEHOLDER}}`s were filled (and their values)
-- Which `{{PLACEHOLDER}}`s remain unfilled
-- Which skills were provisioned from the library (if any)
-- Which skills were already installed and skipped
-- Any errors (missing files, missing library paths)
+Return to the calling workflow:
+
+- **Map cells filled** — which surface/column combinations were resolved
+- **Skills provisioned** — installed from library (Tier 1)
+- **Skills resolved by adequacy** — existing skill covers variant (Tier 2), with justification
+- **Skills discovered externally** — found via find-skills (Tier 3)
+- **⚠️ Cells requiring attention** — skills not found (Tier 4)
+- **Skills skipped** — already installed
+- **Contract library** — resolved value(s)
+- **Framework patterns** — composed and filled (if applicable)
+- **Errors** — missing files, missing library paths

package/template/.agent/workflows/create-prd-architecture.md

@@ -9,9 +9,9 @@ pipeline:
   stage: architecture
   predecessors: [create-prd-stack]
   successors: [create-prd-security]
-  skills: [api-design-principles, database-schema-design, error-handling-patterns, prd-templates, technical-writer]
+  skills: [api-design-principles, database-schema-design, error-handling-patterns, prd-templates, session-continuity, technical-writer]
   calls-bootstrap: false
-requires_placeholders: [HOSTING_SKILL, ORM_SKILL, DATABASE_SKILLS]
+requires_map_columns: [Databases, ORMs, Hosting]
 ---
 
 // turbo-all
@@ -22,38 +22,43 @@ Design the high-level system architecture and data strategy. Create the data pla
 
 ---
 
-## 0. Placeholder guard
+## 0. Map guard
 
-Before any skill reads, verify that the following placeholder values have been filled by `/bootstrap-agents`. For each placeholder, check whether the literal characters `{{` still appear in the value. If **any** are unfilled, emit a **HARD STOP** and do not proceed to Step 4.
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Check the following columns/categories for filled values:
 
-| Placeholder | Filled by | Recovery | Why this matters |
+| Map Location | Column/Category | Recovery | Why this matters |
 |---|---|---|---|
-| `{{HOSTING_SKILL}}` | `/create-prd-stack` when hosting provider is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed hosting provider, then run `/bootstrap-agents HOSTING=<confirmed-provider>`. Otherwise run `/create-prd-stack` first. | Data strategy and schema design steps (Steps 4 and 5) cannot run without the hosting skill — deployment topology decisions will lack provider-specific conventions. |
-| `{{ORM_SKILL}}` | `/create-prd-stack` when ORM is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed ORM, then run `/bootstrap-agents ORM=<confirmed-orm>`. Otherwise run `/create-prd-stack` first. | Migration strategy (Step 5.4) cannot run without the ORM skill — schema conventions and migration patterns will be generic instead of stack-specific. |
-| `{{DATABASE_SKILLS}}` | `/create-prd-stack` when database technology is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed database, then run `/bootstrap-agents DATABASE=<confirmed-db>`. Otherwise run `/create-prd-stack` first. | Data strategy (Step 5) cannot run without the database skill — schema design patterns will be incompatible with the chosen database. |
+| Cross-Cutting | Hosting | Run `/create-prd-stack` to confirm hosting provider, then bootstrap. | Deployment topology (Step 4.3) needs hosting-specific conventions. |
+| Per-Surface (shared) | ORMs | Run `/create-prd-stack` to confirm ORM, then bootstrap. | Migration strategy (Step 5.4) needs ORM-specific schema conventions. |
+| Per-Surface (shared) | Databases | Run `/create-prd-stack` to confirm database(s), then bootstrap. | Data strategy (Step 5) needs database-specific schema design patterns. |
 
-For the hard stop message format and recovery instructions, see `.agent/skills/prd-templates/references/placeholder-guard-template.md`.
+> **Timing fallback**: During `/create-prd`, the map may be partially populated. If a cell is empty but the value was just confirmed in the current conversation (from `/create-prd-stack`), proceed using the conversation-confirmed value. Bootstrap will fill the map after `/create-prd` completes.
 
-Only proceed to Step 4 when all three placeholders report no literal `{{` characters.
+If cells are empty AND the value hasn't been confirmed in conversation → **HARD STOP**: tell the user to run `/create-prd-stack` first.
 
 ---
 
 ## 4. System architecture
 
-Read .agent/skills/{{API_DESIGN_SKILL}}/SKILL.md and .agent/skills/api-design-principles/SKILL.md for API surface design.
+Read `.agent/skills/api-design-principles/SKILL.md` for API surface design.
 
 Design the high-level system. Each sub-item requires full exploration, not a summary sentence:
 
 1. **Component diagram** — What services exist? How do they communicate? What protocols? What happens if one is down?
 2. **Data flow** — Request lifecycle from client to database and back. Every hop, every transformation, every auth check along the way. Draw the full sequence.
 3. **Deployment topology** — What runs where? Edge? Origin? External? Local machine? App Store? What are the latency implications? What are the cost implications?
-   Read .agent/skills/{{HOSTING_SKILL}}/SKILL.md and follow its deployment conventions.
+   Load the Hosting skill(s) from the cross-cutting section per the skill loading protocol (`.agent/skills/prd-templates/references/skill-loading-protocol.md`).
    Read .agent/skills/technical-writer/SKILL.md and follow its methodology.
 4. **API surface** — REST? GraphQL? RPC? Versioning strategy? Error format? Pagination? Rate limit headers?
+5. **Deployment strategy** — Rolling? Blue-green? Canary? Read `.agent/skills/deployment-procedures/SKILL.md` Section 6 for the strategy options and selection matrix. Ask:
+   - "Which zero-downtime deployment strategy fits your risk profile? Rolling (standard), Blue-Green (easy rollback), or Canary (validate with real traffic)?"
+   - "Do you want feature flags for controlled rollout of risky features? If yes, which provider (or build your own)?"
+   - "What is your rollback trigger? Error rate spike above N%? Latency threshold? Manual decision?"
+   Write the confirmed strategy to `docs/plans/architecture-draft.md` under `## Deployment Strategy`.
 
 For multi-surface projects, additionally define:
-5. **Surface interconnection** — How do surfaces communicate? What is the source of truth for shared data? What happens when a surface is offline?
-6. **Shared domain boundary** — Which entities/models are shared across surfaces vs surface-specific?
+6. **Surface interconnection** — How do surfaces communicate? What is the source of truth for shared data? What happens when a surface is offline?
+7. **Shared domain boundary** — Which entities/models are shared across surfaces vs surface-specific?
 
 For each component, also define:
 - What it owns (data, logic, auth decisions)
@@ -69,6 +74,8 @@ Refine based on discussion before proceeding.
 
 Write the completed `## System Architecture` section to `docs/plans/architecture-draft.md` (create the file if it does not exist). Do not wait until the end — write this section as soon as it is completed and confirmed by the user.
 
+> **Decision recording**: For each non-trivial architecture decision (technology choices, deployment topology, API style, failure handling strategy), read `.agent/skills/session-continuity/protocols/06-decision-analysis.md` and follow the **Decision Effect Analysis Protocol**. Architecture decisions have the highest downstream impact in the pipeline — record them to `memory/decisions.md` with the Philosopher + Devil's Advocate deliberation.
+
 ## 4.5. Error architecture
 
 > **Hard gate.** This step is mandatory for every project. All five decisions below must be confirmed by the user before `## 5. Data strategy` begins. Do not proceed to Data Strategy until every decision is explicitly approved.
@@ -81,13 +88,13 @@ Write the completed decisions to `docs/plans/architecture-draft.md` under a new
 
 Read .agent/skills/database-schema-design/SKILL.md and follow its schema design methodology.
 
-Read each skill listed in `{{DATABASE_SKILLS}}` (comma-separated). For each skill directory name, read `.agent/skills/[skill]/SKILL.md` before proceeding. Each sub-item must be explored to field-level depth:
+Load the Databases skill(s) from the `shared` surface row per the skill loading protocol. Each sub-item must be explored to field-level depth:
 
 1. **Data placement** — What lives in the database vs cache vs object storage vs external service vs local device storage? For each entity: which service owns it and why
 2. **Schema approach** — Strict schema vs schemaless vs hybrid? Field types, constraints, indexes, relations with cardinality
 3. **Query patterns** — Read-heavy? Write-heavy? What are the hot paths? What needs caching? What are the N+1 risks?
 4. **Migration strategy** — How will schema evolve? Backward compatibility approach? Zero-downtime migration plan?
-   Read .agent/skills/{{ORM_SKILL}}/SKILL.md and follow its migration and schema conventions.
+   Load the ORMs skill(s) from the `shared` surface row per the skill loading protocol.
 5. **PII boundaries** — Which fields contain PII? Where is PII stored vs where is it NOT stored? How is PII isolated from AI/analytics pipelines?
 
 For multi-surface projects, additionally define:

package/template/.agent/workflows/create-prd-compile.md

@@ -11,7 +11,7 @@ pipeline:
   successors: [decompose-architecture]
   skills: [performance-budgeting, pipeline-rubrics, prd-templates, tdd-workflow, technical-writer]
   calls-bootstrap: true
-requires_placeholders: [UNIT_TESTING_SKILL, E2E_TESTING_SKILL, CI_CD_SKILL]
+requires_map_columns: [Unit Tests, E2E Tests, CI/CD]
 ---
 
 // turbo-all
@@ -24,19 +24,19 @@ Document the development methodology and phasing strategy. Compile the architect
 
 ---
 
-## 0. Placeholder guard
+## 0. Map guard
 
-Before any skill reads, verify that the following placeholder values have been filled by `/bootstrap-agents`. For each placeholder, check whether the literal characters `{{` still appear in the value. If **any** are unfilled, emit a **HARD STOP** and do not proceed to Step 8.
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Check the following columns/categories for filled values:
 
-| Placeholder | Filled by | Recovery | Why this matters |
+| Map Location | Column/Category | Recovery | Why this matters |
 |---|---|---|---|
-| `{{UNIT_TESTING_SKILL}}` | `/create-prd-stack` when the unit testing framework is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed unit testing framework, then run `/bootstrap-agents UNIT_TESTING=<confirmed-framework>`. Otherwise run `/create-prd-stack` first. | Development methodology (Step 8) cannot document correct test conventions without the unit testing skill — TDD patterns will be generic instead of framework-specific. |
-| `{{E2E_TESTING_SKILL}}` | `/create-prd-stack` when the E2E testing framework is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed E2E testing framework, then run `/bootstrap-agents E2E_TESTING=<confirmed-framework>`. Otherwise run `/create-prd-stack` first. | Development methodology (Step 8) cannot document correct E2E test conventions without the E2E testing skill — integration test patterns will be generic. |
-| `{{CI_CD_SKILL}}` | `/create-prd-stack` when CI/CD platform is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed CI/CD platform, then run `/bootstrap-agents CI_CD=<confirmed-platform>`. Otherwise run `/create-prd-stack` first. | Phasing strategy (Step 9) cannot produce correct pipeline configuration without the CI/CD skill — deployment and quality gate patterns will lack platform-specific conventions. |
+| Per-Surface (any) | Unit Tests | Run `/create-prd-stack` to confirm unit testing framework, then bootstrap. | Development methodology (Step 8) needs framework-specific TDD patterns. |
+| Per-Surface (any) | E2E Tests | Run `/create-prd-stack` to confirm E2E testing framework, then bootstrap. | Development methodology (Step 8) needs E2E-specific test conventions. |
+| Cross-Cutting | CI/CD | Run `/create-prd-stack` to confirm CI/CD platform, then bootstrap. | Phasing strategy (Step 9) needs platform-specific pipeline patterns. |
 
-For the hard stop message format and recovery instructions, see `.agent/skills/prd-templates/references/placeholder-guard-template.md`.
+> **Timing fallback**: During `/create-prd`, the map may be partially populated. If a cell is empty but the value was just confirmed in the current conversation (from `/create-prd-stack`), proceed using the conversation-confirmed value. Bootstrap will fill the map after `/create-prd` completes.
 
-Only proceed to Step 8 when all three placeholders report no literal `{{` characters.
+If cells are empty AND the value hasn't been confirmed in conversation → **HARD STOP**: tell the user to run `/create-prd-stack` first.
 
 ---
 
@@ -48,15 +48,14 @@ Document the agreed approach:
 
 1. **Contract-first** — Zod schemas (or equivalent) before implementation
 2. **TDD** — Failing tests before code
-   Read .agent/skills/{{UNIT_TESTING_SKILL}}/SKILL.md and follow its test writing conventions.
-   Read .agent/skills/{{E2E_TESTING_SKILL}}/SKILL.md and follow its E2E test conventions.
+   Load the Unit Tests and E2E Tests skill(s) from the surface stack map per the skill loading protocol (`.agent/skills/prd-templates/references/skill-loading-protocol.md`).
 3. **Vertical slices** — All surfaces per feature
 4. **Spec layers** — IA → BE → FE pipeline
 5. **Quality gates** — What must pass before merge
 
 ## 9. Phasing strategy
 
-Read .agent/skills/{{CI_CD_SKILL}}/SKILL.md and follow its pipeline configuration conventions.
+Load the CI/CD skill(s) from the cross-cutting section per the skill loading protocol.
 
 Break the feature inventory from `docs/plans/ideation/ideation-index.md` (MoSCoW Summary) into dependency-ordered phases.
 

package/template/.agent/workflows/create-prd-design-system.md

@@ -9,7 +9,7 @@ pipeline:
   stage: architecture
   predecessors: [create-prd-stack]
   successors: [create-prd-architecture]
-  skills: [brand-guidelines, design-direction, prd-templates, technical-writer]
+  skills: [brand-guidelines, design-anti-cliche, design-direction, prd-templates, technical-writer]
   calls-bootstrap: false
 ---
 

package/template/.agent/workflows/create-prd-security.md

@@ -11,7 +11,7 @@ pipeline:
   successors: [create-prd-compile]
   skills: [logging-best-practices, prd-templates, resolve-ambiguity, security-scanning-security-hardening]
   calls-bootstrap: true
-requires_placeholders: [SECURITY_SKILLS, AUTH_SKILL]
+requires_map_columns: [Security, Auth]
 ---
 
 // turbo-all
@@ -24,18 +24,18 @@ Define the security model with full compliance escalation, and document all inte
 
 ---
 
-## 0. Placeholder guard
+## 0. Map guard
 
-Before any skill reads, verify that the following placeholder values have been filled by `/bootstrap-agents`. For each placeholder, check whether the literal characters `{{` still appear in the value. If **any** are unfilled, emit a **HARD STOP** and do not proceed to Step 6.
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Check the following cross-cutting categories for filled values:
 
-| Placeholder | Filled by | Recovery | Why this matters |
+| Map Location | Category | Recovery | Why this matters |
 |---|---|---|---|
-| `{{SECURITY_SKILLS}}` | `/create-prd-stack` when security tooling is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed security framework, then run `/bootstrap-agents SECURITY=<confirmed-framework>`. Otherwise run `/create-prd-stack` first. | Security model (Step 6) cannot produce stack-specific threat analysis without the security skill — the model will miss framework-specific attack vectors. |
-| `{{AUTH_SKILL}}` | `/create-prd-stack` when auth provider is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed auth provider, then run `/bootstrap-agents AUTH=<confirmed-provider>`. Otherwise run `/create-prd-stack` first. | Authentication design (Step 6.1) cannot produce correct auth flows without the auth skill — identity provider conventions and token handling will be generic. |
+| Cross-Cutting | Security | Run `/create-prd-stack` to confirm security framework, then bootstrap. | Security model (Step 6) needs stack-specific threat analysis patterns. |
+| Cross-Cutting | Auth | Run `/create-prd-stack` to confirm auth provider, then bootstrap. | Authentication design (Step 6.1) needs provider-specific auth flow patterns. |
 
-For the hard stop message format and recovery instructions, see `.agent/skills/prd-templates/references/placeholder-guard-template.md`.
+> **Timing fallback**: During `/create-prd`, the map may be partially populated. If a cell is empty but the value was just confirmed in the current conversation (from `/create-prd-stack`), proceed using the conversation-confirmed value. Bootstrap will fill the map after `/create-prd` completes.
 
-Only proceed to Step 6 when both placeholders report no literal `{{` characters.
+If cells are empty AND the value hasn't been confirmed in conversation → **HARD STOP**: tell the user to run `/create-prd-stack` first.
 
 ---
 
@@ -43,9 +43,7 @@ Only proceed to Step 6 when both placeholders report no literal `{{` characters.
 
 Read .agent/skills/security-scanning-security-hardening/SKILL.md and follow its defense-in-depth methodology.
 
-Using `{{AUTH_SKILL}}`:
-
-Read each skill listed in `{{SECURITY_SKILLS}}` (comma-separated). For each skill directory name, read `.agent/skills/[skill]/SKILL.md` before proceeding.
+Load the Auth and Security skill(s) from the cross-cutting section per the skill loading protocol (`.agent/skills/prd-templates/references/skill-loading-protocol.md`).
 
 1. **Authentication** — How do users prove identity?
 2. **Authorization** — RBAC vs ABAC? Permission model?

package/template/.agent/workflows/create-prd-stack.md

@@ -8,8 +8,8 @@ pipeline:
   position: 2.1
   stage: architecture
   predecessors: [ideate]
-  successors: [create-prd-architecture]
-  skills: [database-schema-design, design-direction, tech-stack-catalog]
+  successors: [create-prd-design-system]
+  skills: [database-schema-design, design-direction, session-continuity, tech-stack-catalog]
   calls-bootstrap: true
 ---
 
@@ -25,10 +25,14 @@ Build the decision constraints map from the ideation output, then walk through e
 
 ## 2.5. Constraint-first discovery
 
-Before any tech stack decision, read `docs/plans/ideation/meta/constraints.md` to build the **decision constraints map**:
+Before any tech stack decision, read `docs/plans/ideation/meta/constraints.md` to build the **decision constraints map**.
+
+Also read `docs/plans/ideation/ideation-index.md` — specifically the `## Structural Classification` section. This is the **authoritative source** for the project's surface list and project shape (`single-surface`, `multi-surface-shared`, `multi-product-hub`, or `multi-product-peer`). Use this to determine which decision axes apply and whether tech stack decisions need to be made per-surface.
+
+Build the constraints map:
 
 1. **Hard constraints** — decisions already locked by compliance, team, or budget
-2. **Surface constraints** — the project surfaces constrain framework choices
+2. **Surface constraints** — the project surfaces (from structural classification) constrain framework choices. For multi-product projects, some axes may need separate decisions per surface (e.g., different frontend frameworks for web vs desktop vs mobile).
 3. **Soft constraints** — preferences that should bias decisions but aren't hard rules
 
 Present the constraints map to the user before starting tech decisions. Constraints narrow the option space — some decisions may be obvious. Skip those with a brief rationale.
@@ -62,6 +66,8 @@ Score Fit from 1–5 based on how well the option matches the constraints map. I
 
 Get explicit user decisions — no "TBD" allowed. Use the brainstorming skill's approach — one decision at a time.
 
+> **Decision recording**: For each confirmed tech stack decision, read `.agent/skills/session-continuity/protocols/06-decision-analysis.md` and follow the **Decision Effect Analysis Protocol**. Tech stack choices have high downstream impact (they constrain frameworks, skills, deployment, and testing). Record each decision to `memory/decisions.md` with upstream/downstream effects.
+
 ### Database: Persistence Map Interview
 
 Instead of a single DATABASE decision pass, use the following structured persistence map interview to identify all required stores.

package/template/.agent/workflows/create-prd.md

@@ -4,8 +4,8 @@ pipeline:
   position: 2
   stage: architecture
   predecessors: [ideate]
-  successors: [decompose-architecture]
-  skills: [api-design-principles, brainstorming, brand-guidelines, clean-code, database-schema-design, design-direction, error-handling-patterns, find-skills, logging-best-practices, performance-budgeting, pipeline-rubrics, prd-templates, resolve-ambiguity, security-scanning-security-hardening, tdd-workflow, tech-stack-catalog, technical-writer]
+  successors: [audit-ambiguity, decompose-architecture] # audit-ambiguity recommended before decompose
+  skills: [api-design-principles, brainstorming, brand-guidelines, clean-code, database-schema-design, design-anti-cliche, design-direction, error-handling-patterns, find-skills, logging-best-practices, performance-budgeting, pipeline-rubrics, prd-templates, resolve-ambiguity, security-scanning-security-hardening, tdd-workflow, tech-stack-catalog, technical-writer]
   calls-bootstrap: true # tech stack decisions trigger skill provisioning
 shards: [create-prd-stack, create-prd-design-system, create-prd-architecture, create-prd-security, create-prd-compile]
 ---
@@ -35,11 +35,12 @@ Read `docs/plans/ideation/ideation-index.md`.
 
 If the file doesn't exist, tell the user to run `/ideate` first. Do not proceed without approved ideation output.
 
-Use the **Document Map** in `ideation-index.md` to locate specific files:
+Use the **Structure Map** in `ideation-index.md` to locate specific files:
 - Constraints + surface classification → `meta/constraints.md`
 - Personas → `meta/personas.md`
-- Domain details → individual domain files in `domains/`
-- Cross-cutting concerns → `cross-cuts/cross-cut-ledger.md`
+- Domain details → fractal tree under `domains/` (or `surfaces/` for multi-product). Each domain is a **folder** containing `*-index.md` (children + Role Matrix), `*-cx.md` (cross-cuts), and child feature `.md` files. Walk the tree to the depth needed.
+- Cross-cutting concerns → `ideation-cx.md` (global cross-surface) + per-domain `*-cx.md` files within the fractal tree
+- Role coverage → Role Matrix in each domain index, Role Lens in each feature file (use for RBAC planning in security shard)
 
 Pay special attention to the **Project Surfaces** section in `meta/constraints.md` — it determines which tech stack axes apply.
 
@@ -50,8 +51,7 @@ Pay special attention to the **Project Surfaces** section in `meta/constraints.m
 ### Bundled skills
 
 These skills are included in the kit — read each SKILL.md:
-1. `.agent/skills/{{API_DESIGN_SKILL}}/SKILL.md` — API conventions
-2. `.agent/skills/api-design-principles/SKILL.md` — API design principles
+1. `.agent/skills/api-design-principles/SKILL.md` — API design principles
 3. `.agent/skills/security-scanning-security-hardening/SKILL.md` — Security model
 4. `.agent/skills/clean-code/SKILL.md` — Architecture principles
 5. `.agent/skills/brainstorming/SKILL.md` — For collaborative decisions
@@ -100,7 +100,7 @@ Documents development methodology and phasing strategy. Compiles `docs/plans/YYY
 
 ---
 
-## 12. Quality gate
+## Step E — Quality gate
 
 ### Self-check against Architecture rubric
 
@@ -157,7 +157,7 @@ If gaps are found, loop back to the relevant step and resolve with the user.
 > independent audit with evidence citations, run `/audit-ambiguity architecture` as a
 > separate step after this workflow completes.
 
-## 13. Request review and next steps
+## Step F — Request review and next steps
 
 Use `notify_user` to present to the user:
 - **Both** the architecture design document and the Engineering Standards document

package/template/.agent/workflows/decompose-architecture-structure.md

@@ -39,11 +39,9 @@ This shard is **always** created for every project, regardless of what the archi
 
 The `00-infrastructure` skeleton must contain these five items:
 
-1. CI/CD pipeline setup (using the confirmed CI/CD skill from bootstrap)
-   Read .agent/skills/{{CI_CD_SKILL}}/SKILL.md and follow its pipeline configuration conventions.
+1. CI/CD pipeline setup — load the CI/CD skill(s) from the cross-cutting section per the skill loading protocol (`.agent/skills/prd-templates/references/skill-loading-protocol.md`)
 2. Environment configuration (`.env.example`, environment variable documentation)
-3. Deployment pipeline (using the confirmed hosting skill)
-   Read .agent/skills/{{HOSTING_SKILL}}/SKILL.md and follow its deployment conventions.
+3. Deployment pipeline — load the Hosting skill(s) from the cross-cutting section per the skill loading protocol
 4. Project scaffolding (directory structure, base configuration files)
 5. Database initialization (schema creation, migration tooling setup)
 
@@ -53,9 +51,9 @@ The `00-infrastructure` skeleton must contain these five items:
 
 Read `.agent/skills/prd-templates/references/decomposition-templates.md` for the **Shard Skeleton** template. For each shard, create a skeleton file at `docs/plans/ia/[NN-domain-name].md` using the template.
 
-Read .agent/skills/prd-templates/SKILL.md and follow its Shard Seeding Procedure for Level-1 sub-feature extraction from the relevant domain files in `docs/plans/ideation/domains/` into shard ## Features sections.
+Read `.agent/skills/prd-templates/SKILL.md` and follow its Shard Seeding Procedure for Level-1 sub-feature extraction. The procedure reads `ideation-index.md` to find the correct domain path — the ideation folder uses a fractal structure where each domain is a folder (with `{slug}-index.md`, `{slug}-cx.md`, and child features/sub-domains) rather than a flat file. For multi-product projects, domains may be in `surfaces/{name}/` (surface-exclusive or hub-owned) or `shared/` (peer mode).
 
-Fallback for domains not covered in the ideation domain files is defined in the skill's Shard Seeding Procedure.
+Fallback for domains not covered in the ideation domain folders is defined in the skill's Shard Seeding Procedure.
 
 ## 6. Create IA index