cfsa-antigravity 2.0.0 → 2.1.0

package/template/.agent/workflows/plan-phase-write.md

@@ -53,9 +53,9 @@ Read .agent/skills/concise-planning/SKILL.md and follow its methodology.
 Sort slices so each builds on the last:
 - Infrastructure slices first (DB schema, auth middleware)
 
-**Phase 1 special rule**: Before applying this rule, verify that `{{CI_CD_SKILL}}` and `{{HOSTING_SKILL}}` contain filled values (no literal `{{` characters). If unfilled, emit a **HARD STOP**: these placeholders are filled by `/create-prd-stack` — run it first.
+**Phase 1 special rule**: Before applying this rule, read the surface stack map from `.agent/instructions/tech-stack.md` and verify that the **CI/CD** and **Hosting** cross-cutting categories have filled values. If empty, emit a **HARD STOP**: these are filled by `/create-prd-stack` — run it first.
 
-The `00-infrastructure` shard is always the first slice. Verify it covers: (1) CI/CD pipeline setup — read `.agent/skills/{{CI_CD_SKILL}}/SKILL.md`, (2) environment configuration (`.env.example`), (3) deployment pipeline — read `.agent/skills/{{HOSTING_SKILL}}/SKILL.md`, (4) project scaffolding from `.agent/instructions/structure.md` (directories, `README.md` files, base configs), (5) database initialization. Add missing items before proceeding.
+The `00-infrastructure` shard is always the first slice. Verify it covers: (1) CI/CD pipeline setup — read the CI/CD skill(s) from the cross-cutting section of the surface stack map, (2) environment configuration (`.env.example`), (3) deployment pipeline — read the Hosting skill(s) from the cross-cutting section of the surface stack map, (4) project scaffolding from `.agent/instructions/structure.md` (directories, `README.md` files, base configs), (5) database initialization. Add missing items before proceeding.
 
 **Verification gates** (hard gates — add explicitly to the phase plan):
 - `/verify-infrastructure` MUST pass after the infrastructure slice, before any feature slice.
@@ -96,14 +96,12 @@ Read `.agent/skills/session-continuity/protocols/02-progress-generation.md` and
 ## 6.5. Bootstrap Completeness Gate
 
 Scan these four files for literal `{{` occurrences of `LANGUAGE_SKILL`, `HOSTING_SKILL`, `CI_CD_SKILL`, `ORM_SKILL`, `UNIT_TESTING_SKILL`, `E2E_TESTING_SKILL`:
-- `.agent/workflows/implement-slice-setup.md`
-- `.agent/workflows/implement-slice-tdd.md`
-- `.agent/workflows/verify-infrastructure.md`
-- `.agent/workflows/validate-phase.md`
 
-For each unfilled placeholder, read `docs/plans/*-architecture-design.md` to extract the confirmed value, then run `/bootstrap-agents` (see `.agent/workflows/bootstrap-agents.md`) with the corresponding key.
+> **Note**: As of v3, these files no longer contain literal `{{` placeholders — they reference the surface stack map. This gate now verifies that the surface stack map itself is fully populated for all surfaces involved in this phase.
 
-> ❌ STOP — Re-scan the four files. Only proceed to Step 7 when zero `{{` patterns remain. If any remain unfilled after bootstrap, tell the user which placeholders could not be provisioned.
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Verify all per-surface and cross-cutting cells are filled. Verify `.agent/instructions/commands.md` has non-template values.
+
+> ❌ STOP — Only proceed to Step 7 when the map is fully populated. If any cells are empty after bootstrap, tell the user which cells could not be provisioned.
 
 ## 7. Request review and next steps
 

package/template/.agent/workflows/resolve-ambiguity.md

@@ -29,7 +29,7 @@ Targeted ambiguity resolution for any pipeline document or layer. Uses the `reso
 If no argument was provided, ask the user which document or layer to resolve. Accept a layer name (`vision`, `architecture`, `ia`, `be`, `fe`) or a direct `@file` path.
 
 For layer names, resolve to the canonical document(s):
-- `ideation` → `docs/plans/ideation/ideation-index.md` + all domain files in `docs/plans/ideation/domains/`
+- `ideation` → `docs/plans/ideation/ideation-index.md` + all domain files (in `docs/plans/ideation/domains/` and `docs/plans/ideation/surfaces/*/` for multi-product projects)
 - `architecture` → `docs/plans/YYYY-MM-DD-architecture-design.md` + `docs/plans/ENGINEERING-STANDARDS.md` + `docs/plans/data-placement-strategy.md`
 - `ia` → all files in `docs/plans/ia/` (excluding `index.md`)
 - `be` → all files in `docs/plans/be/` (excluding `index.md`)

package/template/.agent/workflows/update-architecture-map.md

@@ -39,7 +39,7 @@ Analyze the project structure using file exploration tools. Do not just stop at
 Read .agent/skills/architecture-mapping/SKILL.md and follow its component analysis methodology.
 
 Group files logically into components, but extract their exact contracts:
-- Use `grep_search` to find `z.object` or `interface` definitions.
+- Use `grep_search` to find contract/validation schema definitions. Search for patterns appropriate to the project's contract library (e.g., `z.object` for Zod, `BaseModel` for Pydantic, `Joi.object` for Joi, `schema(` for Yup, `struct` for Rust/Go, or `interface`/`type` definitions for TypeScript). Check `.agent/instructions/tech-stack.md` for the project's confirmed contract library if unsure.
 - Document exact schema names, required environment variables, and binding names (e.g., KV namespaces, R2 buckets).
 
 ## 3. Map Explicit Data Flow and Relationships
@@ -65,10 +65,27 @@ Create or update `docs/ARCHITECTURE.md`.
 
 Ensure the document is human-readable, well-structured, and focuses on high-level system interactions rather than low-level functional documentation.
 
-## 6. Present Results and Next Steps
+## 6. Phase completion gate
 
-Use `notify_user` to present a summary of the architecture map updates.
+Read `docs/plans/*-architecture-design.md` → **Phasing** section to determine the total number of planned phases.
+Read `.agent/progress/index.md` to determine the current phase number N and how many phases have `status: complete`.
 
-### Proposed next steps
+### If completed phases < total phases
 
-"Architecture map updated. Next: Run `/plan-phase` for the next phase, or if all phases are complete, the project is ready for deployment — refer to your CI/CD pipeline configuration and the deployment procedures documented in `docs/plans/ENGINEERING-STANDARDS.md`."
+The pipeline has more phases to implement. Present:
+
+> "Architecture map updated for Phase N. **Next**: Run `/plan-phase` for Phase [N+1]."
+
+### If completed phases = total phases
+
+All phases are complete. The pipeline has reached its terminal state. Present:
+
+> "✅ **All phases complete.** Architecture map updated. The project is ready for deployment.
+>
+> - Refer to `docs/plans/ENGINEERING-STANDARDS.md` for deployment procedures
+> - Refer to your CI/CD pipeline configuration for automated deployment
+> - Run `/validate-phase` for the final phase if not already done
+>
+> No further `/plan-phase` iterations are needed."
+
+**Do NOT propose `/plan-phase` after the final phase.** The loop terminates here.

package/template/.agent/workflows/validate-phase.md

@@ -39,17 +39,11 @@ This is an optimization, not a requirement. Sequential validation is always corr
 
 ## 1. Run test suite
 
-Read .agent/skills/{{E2E_TESTING_SKILL}}/SKILL.md and follow its E2E test conventions.
-
-Run `{{TEST_COMMAND}}`.
-
-All tests must pass. Zero tolerance for failing tests.
+Run the Test Cmd from `.agent/instructions/commands.md`. All tests must pass. Zero tolerance.
 
 ## 2. Check coverage
 
-Read .agent/skills/{{UNIT_TESTING_SKILL}}/SKILL.md and follow its test writing conventions.
-
-Run `{{TEST_COVERAGE_COMMAND}}`.
+Run the Test Coverage Cmd from `.agent/instructions/commands.md`.
 
 Read `docs/plans/ENGINEERING-STANDARDS.md` and use the coverage thresholds defined in the "Test Coverage" section. If the file doesn't exist or thresholds aren't defined, fall back to these defaults:
 - Statements: 80%
@@ -59,21 +53,31 @@ Read `docs/plans/ENGINEERING-STANDARDS.md` and use the coverage thresholds defin
 
 Critical paths are defined as: auth flows, payment processing, data mutations, and permission/authorization checks.
 
+## 2.5. Mutation testing (critical paths)
+
+**Optional but recommended.** If the project's test tooling supports mutation testing (e.g., Stryker for JS/TS, mutmut for Python, cargo-mutants for Rust):
+
+1. Run the mutation testing tool against critical path modules only (auth, payments, data mutations, permission checks)
+2. **Required**: Mutation score ≥ 70% on critical paths — if below, the tests are passing but not actually catching bugs
+3. **Recommended**: Mutation score ≥ 50% on non-critical paths — log as a finding but don't block
+
+If mutation testing is not available in the project's tooling, skip and note in the validation report that mutation testing was not run.
+
 ## 3. Lint
 
-Run `{{LINT_COMMAND}}`.
+Run the Lint Cmd from the surface stack map.
 
 Zero lint errors. Warnings should be reviewed and addressed.
 
 ## 4. Type check
 
-Run `{{TYPE_CHECK_COMMAND}}`.
+Run the Type Check Cmd from the surface stack map.
 
 Zero type errors. Strict mode must be enabled.
 
 ## 5. Build
 
-Run `{{BUILD_COMMAND}}`.
+Run the Build Cmd from the surface stack map.
 
 Build must succeed with no errors.
 
@@ -81,8 +85,6 @@ Build must succeed with no errors.
 
 ## 5.5. CI/CD pipeline verification
 
-Read .agent/skills/{{CI_CD_SKILL}}/SKILL.md and follow its pipeline configuration conventions.
-
 Verify the CI/CD pipeline is green for this phase's changes:
 
 1. Check that a CI/CD configuration file exists (e.g., `.github/workflows/`, `.gitlab-ci.yml`)
@@ -97,9 +99,7 @@ Verify the CI/CD pipeline is green for this phase's changes:
 
 ## 5.6. Staging deployment gate
 
-Read .agent/skills/{{HOSTING_SKILL}}/SKILL.md and follow its deployment conventions.
-
-1. Deploy to staging using the deployment skill (`.agent/skills/deployment-procedures/SKILL.md`)
+1. Deploy to staging using `.agent/skills/deployment-procedures/SKILL.md`
 2. Verify deployment succeeded (no rollback triggered, no error logs in the deployment output)
 3. Run smoke tests against the staging environment:
    - Health check endpoint returns 200
@@ -114,9 +114,7 @@ Read .agent/skills/{{HOSTING_SKILL}}/SKILL.md and follow its deployment conventi
 
 ## 5.7. Migration verification
 
-Read .agent/skills/{{ORM_SKILL}}/SKILL.md and follow its migration and schema conventions.
-
-1. Run the migration status command (e.g., `prisma migrate status`, `drizzle-kit status`, or equivalent for your ORM)
+1. Run the migration status command (e.g., `prisma migrate status`, `drizzle-kit status`, or equivalent)
 2. Verify there are no pending migrations and no failed migrations
 3. Verify the CI/CD pipeline ran migrations successfully as part of this phase's deployment
 4. Check that rollback scripts exist for each migration in this phase
@@ -134,22 +132,21 @@ Read `.agent/skills/prd-templates/references/spec-coverage-sweep.md` and follow
 
 ## 6. Accessibility audit (if UI changes)
 
-Read .agent/skills/{{ACCESSIBILITY_SKILL}}/SKILL.md and follow its methodology.
-Audit all new UI components in this phase for WCAG 2.1 AA compliance.
+Audit all new UI components in this phase for WCAG 2.1 AA compliance using the Accessibility skill(s) from the cross-cutting section.
 
-## 7. Performance check (if web surface exists)
+## 7. Performance check
 
-Check if the `web-performance-optimization` skill is installed (look for `.agent/skills/web-performance-optimization/SKILL.md`).
+Check if the `performance-optimization` skill is installed (look for `.agent/skills/performance-optimization/SKILL.md`).
 
 **If installed**:
-1. Read `.agent/skills/web-performance-optimization/SKILL.md`
-2. Run the skill's audit protocol against the phase's changed pages/routes
-3. Compare results to the targets in `docs/plans/ENGINEERING-STANDARDS.md` (LCP, FID, CLS, bundle size)
+1. Read `.agent/skills/performance-optimization/SKILL.md`
+2. Run the skill's audit protocol against the phase's changed pages/routes/endpoints
+3. Compare results to the targets in `docs/plans/ENGINEERING-STANDARDS.md` (response time budgets, bundle sizes, memory limits, or other surface-appropriate metrics)
 4. Report any metrics that exceed the defined thresholds
 
 **If not installed**:
-- Note: "No web performance skill installed. Skipping automated performance audit."
-- Manually verify that no obviously expensive operations were added (large synchronous imports, unoptimized images, missing lazy loading)
+- Note: "No performance optimization skill installed. Skipping automated performance audit."
+- Manually verify that no obviously expensive operations were added (large synchronous imports, unoptimized assets, missing lazy loading, N+1 queries, unbounded loops)
 - If performance is critical for this project, recommend installing the skill via `find-skills`
 
 ## 8. Security review
@@ -158,7 +155,7 @@ Read .agent/skills/adversarial-review/SKILL.md and follow its structured methodo
 
 Read .agent/skills/security-scanning-security-hardening/SKILL.md and run its full defense-in-depth audit protocol against the phase's changes (new endpoints, new data flows, new auth checks). Report findings with severity levels. Block the phase if any Critical or High severity issues are found.
 
-**Supplemental security checks (conditional)**: After the core audit completes, read `{{SECURITY_SKILLS}}` (comma-separated list of security skill directory names). For each skill directory name in the list, read `.agent/skills/[skill]/SKILL.md` and run its audit protocol as a supplement to the core audit.
+**Supplemental security checks (conditional)**: After the core audit completes, read the Security skill(s) from the cross-cutting section of the surface stack map. For each listed skill directory name, read `.agent/skills/[skill]/SKILL.md` and run its audit protocol as a supplement to the core audit.
 
 Report any additional findings from supplemental audits with the same severity classification.
 

package/template/.agent/workflows/verify-infrastructure.md

@@ -1,7 +1,7 @@
 ---
 description: Verify operational infrastructure after the infrastructure or auth slice — CI/CD green, staging live, migrations clean, auth working
 pipeline:
-  position: 9.5
+  position: 7.5
   stage: verification
   predecessors: [implement-slice]
   successors: [implement-slice, validate-phase]
@@ -19,15 +19,15 @@ Operational verification gate that runs after the `00-infrastructure` slice and
 
 ## 0. Placeholder audit
 
-Scan the repository for any remaining `{{PLACEHOLDER}}` values:
+Scan the surface stack map (`.agent/instructions/tech-stack.md`) for completeness:
 
-```bash
-grep -rn '{{' --include='*.md' --include='*.ts' --include='*.json' . | grep -v node_modules | grep -v '.git/'
-```
+1. Verify all per-surface rows have filled values for required columns
+2. Verify cross-cutting categories (Auth, Security, CI/CD, Hosting) have filled values
+3. Verify `.agent/instructions/commands.md` has non-template values
 
-**If any `{{PLACEHOLDER}}` values are found** → **STOP.** Run `/bootstrap-agents` to fill them before proceeding.
+**If any map cells are empty** → **STOP.** Run `/bootstrap-agents` to populate them before proceeding.
 
-**Pass criteria**: Zero `{{PLACEHOLDER}}` values in the repository (excluding `node_modules` and `.git`).
+**Pass criteria**: Surface stack map fully populated for all project surfaces.
 
 > Update report: Mark check 0 as `✅` in the report file.
 
@@ -55,7 +55,7 @@ Read `.agent/skills/prd-templates/references/infrastructure-report-template.md`
 Read .agent/skills/testing-strategist/SKILL.md and follow its methodology.
 Read .agent/skills/systematic-debugging/SKILL.md and follow its methodology.
 
-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 (`.agent/skills/prd-templates/references/skill-loading-protocol.md`).
 
 Locate the CI/CD configuration file (e.g., `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`).
 
@@ -98,7 +98,7 @@ Verify the CI/CD pipeline has run for the latest commit and ALL jobs are passing
 
 ## 4. Migration check
 
-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.
 
 1. Run the migration status command (e.g., `prisma migrate status`, `drizzle-kit status`, or equivalent)
 2. Verify no pending or failed migrations
@@ -115,7 +115,7 @@ Read .agent/skills/{{ORM_SKILL}}/SKILL.md and follow its migration and schema co
 
 ## 5. Staging deployment
 
-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.
 Read .agent/skills/deployment-procedures/SKILL.md and follow its pre-deployment checklist and verification protocol.
 
 1. Deploy to staging using the project's deployment process

package/template/.agent/workflows/write-architecture-spec-design.md

@@ -22,9 +22,14 @@ Explore requirements, map all interactions, and define contracts, data models, a
 
 **Prerequisite**: Skeleton IA shard must exist in `docs/plans/ia/`. If it does not, tell the user to run `/decompose-architecture` first.
 
-## 0. Placeholder guard
+## 0. Map guard
 
-Verify `{{DATABASE_SKILLS}}`, `{{SECURITY_SKILLS}}`, and `{{SURFACES}}` are filled (no literal `{{` characters). If any are unfilled → **HARD STOP**. For format and recovery mappings, see `.agent/skills/prd-templates/references/placeholder-guard-template.md` and `.agent/skills/session-continuity/protocols/10-placeholder-verification-gate.md`.
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Verify that the following have filled values:
+- **Databases** column (per-surface, any row)
+- **Security** category (cross-cutting)
+- **Global Settings → Surfaces** list
+
+If any are empty → **HARD STOP**: tell the user to run `/create-prd` first.
 
 ---
 
@@ -41,9 +46,9 @@ Before loading skills, check whether the shard file at `docs/plans/ia/[shard-nam
 
 ### 1a. Read the authoritative sources
 
-Read the following files and build a **reconciliation table** comparing what each source says about this shard's features. The relevant domain file in `docs/plans/ideation/domains/` is the **primary source of truth** for sub-features — the architecture design is secondary context.
+Read the following files and build a **reconciliation table** comparing what each source says about this shard's features. Use the `ideation-index.md` Domain Documents table to find the correct domain file path (may be in `domains/` or `surfaces/{name}/` for multi-product projects). The ideation domain file is the **primary source of truth** for sub-features — the architecture design is secondary context.
 
-1. The relevant domain file in `docs/plans/ideation/domains/`
+1. The relevant ideation domain file for this shard (path from `ideation-index.md` Domain Documents table)
 2. The shard's `## Features` section (from `/decompose-architecture-structure`)
 3. `docs/plans/ideation/ideation-index.md` — Must Have features for this domain
 
@@ -85,30 +90,28 @@ For each feature in the shard, document:
 
 ## 3. Define contracts
 
-Read .agent/skills/{{API_DESIGN_SKILL}}/SKILL.md and follow its methodology.
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md` and load the API Design skill(s) from the cross-cutting section.
 
 For each interaction, define the contract shape:
 - Request shape (params, query, body)
 - Response shape (all fields typed)
 - Error shape (specific error codes)
-- Note: actual Zod schemas written in BE spec phase
+- Note: actual {{CONTRACT_LIBRARY}} schemas written in BE spec phase
 
 **Review questions**: "Are there fields I'm missing from these requests/responses?" / "Are these error codes specific enough?"
 
 ## 4. Design data models
 
-Read each skill listed in `{{DATABASE_SKILLS}}` (comma-separated). For each skill directory name, read `.agent/skills/[skill]/SKILL.md` before proceeding. Also load these community skills for guidance:
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md` and load the Databases skill(s) for this shard's surface. Also load:
 - `.agent/skills/database-schema-design/SKILL.md` — Schema design principles
 - `.agent/skills/error-handling-patterns/SKILL.md` — Error categories for contracts
 - `.agent/skills/technical-writer/SKILL.md` — Specification clarity
-- Tables/collections, fields, types
-- Relationships (graph edges, foreign keys, etc.)
-- Indexes for query patterns
-- Constraints and validation rules
+
+Define for each entity: tables/collections, fields, types, relationships, indexes, constraints and validation rules.
 
 **Review questions**: "Does this schema capture everything this domain needs to store?" / "Are the relationships and cardinalities correct?" / "Are there derived/computed fields I should account for?"
 
-**Missing skill fallback**: If any database or security skill listed above is not installed and not in the MANIFEST, read `.agent/skills/find-skills/SKILL.md` and follow its discovery methodology before proceeding.
+> **Decision recording**: For non-trivial data model decisions (schema approach, denormalization trade-offs, index strategy), read `.agent/skills/session-continuity/protocols/06-decision-analysis.md` and follow the **Decision Effect Analysis Protocol**.
 
 ## 5. Design access control
 
@@ -122,6 +125,8 @@ Read .agent/skills/security-scanning-security-hardening/SKILL.md and apply its a
 
 **Review questions**: "Can you think of a scenario where a user should be blocked that this matrix allows?" / "Can you think of a scenario where a user should be allowed that this matrix blocks?"
 
+> **Decision recording**: For access control architecture decisions (role hierarchy, ownership model, escalation paths), read `.agent/skills/session-continuity/protocols/06-decision-analysis.md` and follow the **Decision Effect Analysis Protocol**. Record to `memory/decisions.md`.
+
 ## 5.5. Accessibility specifications
 
 Read `{{SURFACES}}` to determine the project's target surfaces.

package/template/.agent/workflows/write-be-spec-classify.md

@@ -73,37 +73,41 @@ Before classifying a shard as multi-domain, build a **sub-feature endpoint inven
 - For multi-domain: the proposed split boundaries
 - For structural reference: confirmation that no BE spec is needed
 
-## 2.5. Verify tech stack skills are provisioned
+## 2.5. Verify surface stack map is populated
 
-Before loading the skill bundle, scan the skill bundle list in Step 3 for any values still containing literal `{{` characters.
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Determine this shard's surface from its directory path:
+- `docs/plans/shared/be/` or `docs/plans/be/` → surface `shared`
+- `docs/plans/web/be/` → surface `web`
+- `docs/plans/desktop/be/` → surface `desktop`
+- etc.
 
-If `{{LANGUAGE_SKILL}}`, `{{DATABASE_SKILLS}}`, `{{AUTH_SKILL}}`, `{{BACKEND_FRAMEWORK_SKILL}}`, `{{ORM_SKILL}}`, or `{{UNIT_TESTING_SKILL}}` are still unfilled → **stop** and tell the user: *"Tech stack skills haven't been provisioned yet. The skill bundle placeholders are still unfilled. Run `/create-prd` first to make tech stack decisions and trigger bootstrap provisioning, then return to `/write-be-spec`."*
+Check that the following map cells have filled values for this shard's surface:
+- **Languages** (per-surface)
+- **Databases** (per-surface)
+- **BE Frameworks** (per-surface)
+- **ORMs** (per-surface)
+- **Unit Tests** (per-surface)
+- **Auth** (cross-cutting)
 
-Only proceed to Step 3 when all skill bundle placeholders are filled with actual skill directory names.
+If any required cells are empty → **stop** and tell the user: *"Surface stack map is not fully populated for the `{surface}` surface. Run `/create-prd` first to make tech stack decisions and trigger bootstrap provisioning, then return to `/write-be-spec`."*
 
-## 3. Load skill bundle
+Only proceed to Step 3 when all required map cells are filled.
 
-Read .agent/skills/{{LANGUAGE_SKILL}}/SKILL.md and follow its language conventions.
-Read each skill listed in `{{DATABASE_SKILLS}}` (comma-separated). For each skill directory name, read `.agent/skills/[skill]/SKILL.md` before proceeding.
-Read .agent/skills/{{AUTH_SKILL}}/SKILL.md
-Read .agent/skills/{{BACKEND_FRAMEWORK_SKILL}}/SKILL.md
-Read .agent/skills/{{API_DESIGN_SKILL}}/SKILL.md
-Read .agent/skills/api-design-principles/SKILL.md
-Read .agent/skills/error-handling-patterns/SKILL.md
-Read .agent/skills/database-schema-design/SKILL.md
-Read .agent/skills/migration-management/SKILL.md
-Read .agent/skills/{{ORM_SKILL}}/SKILL.md and follow its migration and schema conventions.
-Read .agent/skills/{{UNIT_TESTING_SKILL}}/SKILL.md and follow its test writing conventions.
-Read .agent/skills/testing-strategist/SKILL.md
-Read .agent/skills/logging-best-practices/SKILL.md
+## 3. Load skill bundle
 
-**Missing skill fallback**: If any skill in the bundle above is not installed in `.agent/skills/` and is not in `.agent/skill-library/MANIFEST.md`, read `.agent/skills/find-skills/SKILL.md` and follow its discovery methodology to search for a community equivalent before proceeding without it.
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md` and follow the **Skill Loading Protocol** for the `write-be-spec-classify` workflow. Load all categories listed in its table for this workflow, plus these bundled skills:
+- `.agent/skills/api-design-principles/SKILL.md`
+- `.agent/skills/error-handling-patterns/SKILL.md`
+- `.agent/skills/database-schema-design/SKILL.md`
+- `.agent/skills/migration-management/SKILL.md`
+- `.agent/skills/testing-strategist/SKILL.md`
+- `.agent/skills/logging-best-practices/SKILL.md`
 
-**Async/background processing (conditional)**: If the IA shard includes background processing, async operations, event-driven workflows, scheduled tasks, or queue-based processing, read `.agent/skills/workflow-automation/SKILL.md` and follow its methodology for durable workflow patterns (step functions, retry strategies, idempotency, fan-out).
+**Async/background processing (conditional)**: If the IA shard includes background processing, async operations, event-driven workflows, or queue-based processing, also read `.agent/skills/workflow-automation/SKILL.md`.
 
 ### Ambiguity resolution
 
-When writing the BE spec, if any requirement cannot be resolved from `ideation-index.md`, `architecture-design.md`, `data-placement-strategy.md`, or upstream IA specs, **do not guess**. Instead, load and follow `.agent/skills/resolve-ambiguity/SKILL.md` to systematically resolve the ambiguity before proceeding.
+When writing the BE spec, if any requirement cannot be resolved from `ideation-index.md`, `architecture-design.md`, `data-placement-strategy.md`, or upstream IA specs, **do not guess**. Load and follow `.agent/skills/resolve-ambiguity/SKILL.md` to resolve it first.
 
 ## 4. Read reference documents
 

package/template/.agent/workflows/write-be-spec.md

@@ -66,7 +66,7 @@ Before presenting to the user, verify:
 
 Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review discipline to each checklist item.
 
-- [ ] Every endpoint has a Zod request AND response schema
+- [ ] Every endpoint has a {{CONTRACT_LIBRARY}} request AND response schema
 - [ ] Every database table has defined fields, indexes, and permissions
 - [ ] Security constraints from IA shard reflected in middleware section
 - [ ] Error codes are specific (not generic 500s)

package/template/.agent/workflows/write-fe-spec-classify.md

@@ -72,22 +72,16 @@ Not every FE spec maps 1:1 to a BE feature spec. Before writing anything, classi
 - For feature specs: the BE spec(s) and IA shard it maps to
 - For cross-cutting specs: confirmation that BE spec/IA shard mapping is skipped
 
-## 3. Load skill bundle
+Determine this shard's surface from its directory path (e.g., `docs/plans/web/fe/` → surface `web`; flat `docs/plans/fe/` → surface `shared` or the project's single surface).
 
-Read .agent/skills/{{LANGUAGE_SKILL}}/SKILL.md and follow its language conventions.
-Read .agent/skills/{{FRONTEND_FRAMEWORK_SKILL}}/SKILL.md
-Read .agent/skills/{{FRONTEND_DESIGN_SKILL}}/SKILL.md and follow its design methodology.
-Read .agent/skills/{{ACCESSIBILITY_SKILL}}/SKILL.md
-Read .agent/skills/{{STATE_MANAGEMENT_SKILL}}/SKILL.md and follow its state management conventions.
-Read .agent/skills/error-handling-patterns/SKILL.md
-Read .agent/skills/testing-strategist/SKILL.md
-Read .agent/skills/technical-writer/SKILL.md
-
-**Missing skill fallback**: If any skill in the bundle above is not installed in `.agent/skills/` and is not in `.agent/skill-library/MANIFEST.md`, read `.agent/skills/find-skills/SKILL.md` and follow its discovery methodology to search for a community equivalent before proceeding without it.
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md` and follow the **Skill Loading Protocol** for the `write-fe-spec-classify` workflow. Load all categories listed in its table for this workflow, plus these bundled skills:
+- `.agent/skills/error-handling-patterns/SKILL.md`
+- `.agent/skills/testing-strategist/SKILL.md`
+- `.agent/skills/technical-writer/SKILL.md`
 
 ### Ambiguity resolution
 
-When writing the FE spec, if any requirement cannot be resolved from `ideation-index.md`, `architecture-design.md`, `data-placement-strategy.md`, or upstream IA/BE specs, **do not guess**. Instead, load and follow `.agent/skills/resolve-ambiguity/SKILL.md` to systematically resolve the ambiguity before proceeding.
+When writing the FE spec, if any requirement cannot be resolved from `ideation-index.md`, `architecture-design.md`, `data-placement-strategy.md`, or upstream IA/BE specs, **do not guess**. Load and follow `.agent/skills/resolve-ambiguity/SKILL.md` to resolve it first.
 
 ## 4. Read source documents
 

package/template/.agent/workflows/write-fe-spec-write.md

@@ -27,7 +27,7 @@ Write the FE spec to `docs/plans/fe/`, update indexes, run quality checks, and p
 
 Read .agent/skills/technical-writer/SKILL.md and follow its methodology.
 Read .agent/skills/spec-writing/SKILL.md and follow its completeness testing and cross-reference checking methodology.
-Read .agent/skills/{{ACCESSIBILITY_SKILL}}/SKILL.md and follow its methodology.
+Load the Accessibility skill(s) from the cross-cutting section per the skill loading protocol (`.agent/skills/prd-templates/references/skill-loading-protocol.md`).
 Read .agent/skills/testing-strategist/SKILL.md and follow its methodology.
 
 **Naming convention**: Numbered prefix matching feature position + kebab-case name (e.g., `01-auth-ui.md`). Cross-cutting: `00-` prefix.

package/template/AGENTS.md

@@ -173,4 +173,4 @@ graph TD
 
 ### Mandatory Validation
 
-**CRITICAL:** Run `{{VALIDATION_COMMAND}}` after **EVERY** code change. Do not finish a task until all pass.
+**CRITICAL:** Run the Validation Cmd from `.agent/instructions/commands.md` after **EVERY** code change. Do not finish a task until all pass.

package/template/GEMINI.md

@@ -81,9 +81,9 @@ Once a stage is locked, downstream stages may not contradict it. To change a loc
 | 9 | `/implement-slice` | Slice acceptance criteria | Working code via Red→Green→Refactor | Implementation |
 | ↳ | `/implement-slice-setup` | Slice from phase plan | Progress check + skills + contracts + parallel mode | Implementation |
 | ↳ | `/implement-slice-tdd` | Contract + tests | Red→Green→Refactor + validation + progress tracking | Implementation |
-| 9.5 | `/verify-infrastructure` | Implemented infra or auth slice | Operational verification report | Verification |
+| 7.5 | `/verify-infrastructure` | Implemented infra or auth slice | Operational verification report | Verification |
 | 10 | `/validate-phase` | Completed phase | Full validation gate | Verification |
-| 11 | `/evolve-contract` | Changed Zod schema | Safe schema migration | Maintenance |
+| 11 | `/evolve-contract` | Changed `{{CONTRACT_LIBRARY}}` schema | Safe schema migration | Maintenance |
 
 
 > **Note**: Rows marked with ↳ are independently-invocable sub-workflows (shards)
@@ -176,4 +176,4 @@ graph TD
 
 ### Mandatory Validation
 
-**CRITICAL:** Run `{{VALIDATION_COMMAND}}` after **EVERY** code change. Do not finish a task until all pass.
+**CRITICAL:** Run the Validation Cmd from `.agent/instructions/commands.md` after **EVERY** code change. Do not finish a task until all pass.

package/template/docs/kit-architecture.md

@@ -15,14 +15,16 @@ The intelligence of the kit lives entirely within the `.agent/` directory.
 ├── instructions/    # Core directives (the "brainstem")
 ├── progress/        # State and memory (the "hippocampus")
 ├── rules/           # Non-negotiable constraints (the "laws")
-├── skills/          # Reusable capabilities (the "tools")
+├── skill-library/   # Installable skill packages (the "toolbox")
+├── skills/          # Active capabilities (the "tools")
 └── workflows/       # Structured processes (the "playbooks")
 ```
 
 ### Core Components
 
-*   **Instructions:** (`workflow.md`, `tech-stack.md`, `structure.md`, `patterns.md`, etc.) Baseline knowledge the agent needs to operate in the specific environment. These files ship as templates with `{{PLACEHOLDER}}` markers — they are not static files. The bootstrap system fills them progressively as tech decisions are confirmed during `/create-prd`. An instruction file with unfilled placeholders is a broken agent context. `workflow.md` enforces the mandatory execution sequence: Understand Context -> Check Skills -> Execute -> Validate.
+*   **Instructions:** (`workflow.md`, `tech-stack.md`, `structure.md`, `patterns.md`, `commands.md`) Baseline knowledge the agent needs to operate in the specific environment. These files ship as templates with `{{PLACEHOLDER}}` markers — they are not static files. The bootstrap system fills them progressively as tech decisions are confirmed during `/create-prd`. An instruction file with unfilled placeholders is a broken agent context. `workflow.md` enforces the mandatory execution sequence: Understand Context -> Check Skills -> Execute -> Validate.
 *   **Rules:** Preemptively loaded constraints that apply to *every* task. Includes security best practices (`security-first.md`), TDD mandates (`tdd-contract-first.md`), and vertical-slice enforcement (`vertical-slices.md`).
+*   **Skill Library:** (`.agent/skill-library/`) Installable skill packages organized by category (e.g., `stack/databases/`, `stack/frontend-frameworks/`). Skills are provisioned from here into `.agent/skills/` by the bootstrap system when tech decisions are confirmed. Contains `MANIFEST.md` with the full taxonomy.
 *   **Skills:** Modular capabilities (e.g., `technical-writer`, `brainstorming`). Agents load these explicitly when a task requires them, preventing context bloat.
 *   **Workflows:** Step-by-step markdown checklists invoked via `/slash-commands` (e.g., `/create-prd`, `/implement-slice`). They chain skills together to achieve complex, multi-stage goals.
 
@@ -136,7 +138,7 @@ This directory acts as the agent's long-term and working memory.
 
 ### Cross-references
 
-- **Dated File Convention** — See below in this section (Section 2) — governs which artifact paths use glob patterns vs. hardcoded names.
+- **Dated File Convention** — See below in this section (Section 3) — governs which artifact paths use glob patterns vs. hardcoded names.
 - **Placeholder Verification Gate Protocol** — See Section 4.5 — governs the Step 0 guard that prevents workflows from reading `{{PLACEHOLDER}}`-dependent skills before bootstrap has run.
 - **Kit Maintenance Checklist** — See Section 6 — governs what must be updated when new workflows or skills are added.
 - **Surface Model** — `.agent/skills/prd-templates/references/surface-model.md` — The authoritative reference for surface types (web/mobile/cli/etc.) and implementation layers, and how the two models relate.
@@ -183,6 +185,29 @@ Workflow files declare skills in two places with different semantics:
 
 **Leaf workflows (shards)** should have body reads that match their frontmatter — if a skill is listed in a shard's frontmatter, the shard body should contain a corresponding `Read` instruction.
 
+### Shared References (`prd-templates/references/`)
+
+The `prd-templates` skill contains a `references/` directory with 23 shared reference files that are consumed by multiple workflows. These references eliminate content duplication by centralizing:
+
+| Reference Category | Examples | Used By |
+|---|---|---|
+| **Document templates** | `architecture-design-template.md`, `be-spec-template.md`, `fe-spec-template.md` | Spec and PRD writing workflows |
+| **Shared policies** | `tdd-testing-policy.md`, `slice-completion-gates.md` | Implementation and validation workflows |
+| **Classification procedures** | `fe-classification-procedures.md`, `placeholder-guard-template.md` | Classify shards of spec workflows |
+| **Design system** | `design-system-decisions.md`, `design-system-prerequisite-check.md` | FE spec and PRD workflows |
+| **Cross-cutting protocols** | `skill-loading-protocol.md`, `spec-coverage-sweep.md`, `surface-model.md` | 15+ workflows |
+
+When a workflow needs a policy, template, or procedure, it references the shared file rather than inlining the content. This keeps workflows focused on orchestration logic and keeps shared policies maintainable in one place.
+
+### Skill Loading Protocol
+
+Workflows that need stack-specific skills (Languages, Databases, FE Frameworks, etc.) reference `.agent/skills/prd-templates/references/skill-loading-protocol.md` instead of repeating the loading instructions inline. The protocol centralizes:
+
+- How to read the surface stack map in `tech-stack.md`
+- Which skill categories to load per workflow
+- The missing-skill fallback procedure
+- Surface stack map verification before loading
+
 ---
 
 ## 4.5. Bootstrap System
@@ -224,10 +249,11 @@ Two distinct gate types enforce placeholder readiness at different pipeline stag
 
 | Gate type | Where it runs | When | Purpose |
 |---|---|---|---|
-| **Spec-phase gate** | Step 0 of specification workflows (`create-prd-architecture`, `write-architecture-spec-design`, `write-fe-spec-classify`) | Before any skill reads | Guard spec authoring from unfilled stack placeholders |
-| **Implementation-phase gate** | `/implement-slice-setup` Step -1 | Before any code is written | Guard code generation from broken agent context across all seven instruction files |
+| **Spec-phase gate** | Step 0 of specification workflows (`write-architecture-spec-design`, `write-be-spec-classify`, `write-fe-spec-classify`) | Before any skill reads | Guard spec authoring from unfilled stack placeholders |
+| **Planning-phase gate** | `/plan-phase-write` | Before slice planning | Guard phase planning from unfilled CI/CD and Hosting skill placeholders |
+| **Implementation-phase gate** | `/implement-slice-setup` Step -1 | Before any code is written | Guard code generation from broken agent context across all five instruction files |
 
-Both gates emit a **four-part hard stop message** per unfilled placeholder:
+All three gates emit a **four-part hard stop message** per unfilled placeholder:
 
 1. **Which exact `{{PLACEHOLDER}}` is unfilled** — the literal placeholder name
 2. **Which pipeline stage fills it** — the `/create-prd-stack` decision that triggers bootstrap
@@ -242,7 +268,7 @@ For detailed per-workflow placeholder mappings and recovery commands, see `.agen
 
 ### Implementation-Phase Placeholder Gate
 
-Before any implementation begins, `/implement-slice-setup` (Step -1) scans all seven instruction files for unfilled `{{` patterns. If any are found, implementation stops with a specific remediation path per file. This gate is the last line of defense against broken agent context reaching the implementation phase.
+Before any implementation begins, `/implement-slice-setup` (Step -1) scans all five instruction files for unfilled `{{` patterns. If any are found, implementation stops with a specific remediation path per file. This gate is the last line of defense against broken agent context reaching the implementation phase.
 
 ---
 
@@ -252,7 +278,7 @@ Before any implementation begins, `/implement-slice-setup` (Step -1) scans all s
 
 The defining architectural pattern of the code produced by this kit.
 
-1.  **Contract (Zod):** Define the schema first.
+1.  **Contract ({{CONTRACT_LIBRARY}}):** Define the schema first.
 2.  **Tests (Failing):** Write tests that assert against the contract.
 3.  **Implementation:** Write the code to make the tests pass.