cfsa-antigravity 2.0.0 → 2.2.0

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

@@ -0,0 +1,167 @@
+---
+description: Production readiness gates — API docs, accessibility, performance, security, dependency audit, results for the validate-phase workflow
+parent: validate-phase
+shard: readiness
+standalone: true
+position: 2
+pipeline:
+  position: 8.2
+  stage: verification
+  predecessors: [validate-phase-quality]
+  successors: [update-architecture-map]
+  skills: [adversarial-review, security-scanning-security-hardening, verification-before-completion]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Validate Phase — Production Readiness Gates
+
+Run all production readiness checks for a completed implementation phase.
+
+**Prerequisite**: Code quality gates (from `/validate-phase-quality` or equivalent) must pass first.
+
+---
+
+## 5.9. API documentation sync (surfaces with API endpoints)
+
+Read the surface stack map from `.agent/instructions/tech-stack.md`. **Skip this step** if the project has no API surface and no BE endpoints exposed to external consumers.
+
+1. Read `docs/plans/ENGINEERING-STANDARDS.md` → `## Code Quality` → `Required documentation` field
+2. If API documentation is required or the project exposes public API endpoints:
+   - Verify an OpenAPI spec file exists (e.g., `openapi.yaml`, `openapi.json`, or a generated equivalent)
+   - If the project uses a schema-first or code-first generation approach (documented in architecture-design.md), verify the generation tool produces output matching the implemented endpoints
+   - For each new endpoint in this phase, verify it appears in the OpenAPI spec with:
+     - Request body schema matching the {{CONTRACT_LIBRARY}} contract
+     - Response schema matching the contract
+     - All error codes documented
+   - Run OpenAPI linter if configured (e.g., the tool named in ENGINEERING-STANDARDS.md or the project's `lint` scripts)
+3. If API documentation is not required and no public API surface exists → skip
+
+**Pass criteria**: OpenAPI spec exists and is in sync with implemented contracts for this phase's endpoints, or API documentation is not applicable.
+
+---
+
+## 6. Accessibility audit (if UI changes)
+
+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
+
+### 7a. Performance budget verification (mandatory when budgets are defined)
+
+Read `docs/plans/ENGINEERING-STANDARDS.md` section `## Performance Budgets`.
+
+**If the section does not exist or contains only unfilled template placeholders** → Log: "No performance budgets defined in ENGINEERING-STANDARDS.md — skipping budget verification." Proceed to 7b.
+
+**If budgets are defined**, read the `### CI Enforcement` table. For each row where the enforcement tool is named:
+
+1. Check if the named enforcement tool is installed/available in the project
+2. **If tool is available** → run it against the staging deployment (from Step 5.6) using the thresholds in the corresponding budget table:
+   - **Web Vitals** (LCP, INP, CLS) → run against staging URLs, one per page type defined in the budget
+   - **JS Bundle Size** → measure build output against per-page-type caps
+   - **API Response Time** → run the named load test tool with a baseline scenario against staging endpoints
+   - **DB Query Time** → run EXPLAIN ANALYZE (or equivalent) on critical queries and verify against tier thresholds
+   - **Desktop/Mobile/CLI metrics** → run the named platform profiler against the built artifact
+3. **If tool is not available** → log which tool is missing and recommend installation, but do not block
+
+**Verdict per budget row**:
+- `Fail` classification in CI Enforcement table AND threshold exceeded → **STOP.** Mark step 7a as `❌`. The phase cannot pass until budgets are met.
+- `Warn` classification AND threshold exceeded → Log as a finding, do not block.
+- Tool not available → Log as a finding, do not block, recommend installation.
+
+**Pass criteria**: All `Fail`-classified budgets pass their thresholds. All `Warn`-classified findings are logged.
+
+### 7b. Deep performance audit (optional)
+
+Check if the `performance-optimization` skill is installed (look for `.agent/skills/performance-optimization/SKILL.md`).
+
+**If installed**:
+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**:
+- 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
+
+Read .agent/skills/adversarial-review/SKILL.md and follow its structured methodology for generating attack scenarios, abuse cases, and race conditions against the phase's changes. Produce spec-level gap items for any identified risks. Feed these into the defense-in-depth audit below.
+
+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 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.
+
+**Surface-conditional DAST scan (if applicable)**: Read `docs/plans/ENGINEERING-STANDARDS.md` → `## Security` → `Security testing tool` field. If a DAST or security scanning tool is defined:
+1. Run it against the staging deployment from Step 5.6
+2. Report findings with severity levels consistent with the core audit
+3. Block the phase if any Critical or High severity findings are discovered
+
+If no security testing tool is defined in ENGINEERING-STANDARDS → skip and log: "No DAST/security testing tool configured."
+
+## 8.5. Dependency audit
+
+### Core audit (mandatory — no skill required)
+
+Run the package manager's built-in vulnerability audit tool. Use the appropriate command for the project's language/package manager:
+
+| Package Manager | Audit Command |
+|----------------|---------------|
+| npm | `npm audit --audit-level=high` |
+| pnpm | `pnpm audit --audit-level=high` |
+| yarn | `yarn npm audit --severity high` |
+| pip | `pip-audit` or `safety check` |
+| cargo | `cargo audit` |
+| go | `govulncheck ./...` |
+| bundler | `bundle audit check` |
+| composer | `composer audit` |
+
+If the project uses a package manager not listed above, check its documentation for a built-in vulnerability audit command.
+
+**If any HIGH or CRITICAL vulnerabilities are found in production dependencies** → **STOP.** Mark step 8.5 as `❌`. List affected packages and recommended fixes (upgrade version, patch, or replace).
+
+**If only LOW or MODERATE vulnerabilities are found** → Log as findings, do not block.
+
+**If the audit tool is not available** (e.g., language has no built-in audit) → Log: "No built-in dependency audit available for [language]. Recommend installing a dependency auditing tool." Do not block.
+
+### Supplemental audit (conditional)
+
+If the `dependency-auditing` skill is installed (`.agent/skills/dependency-auditing/SKILL.md`):
+1. Read the skill and run its full audit protocol (Snyk, Socket.dev, SBOM generation, lockfile integrity)
+2. Report any additional findings with severity levels
+
+**Pass criteria**: Zero HIGH/CRITICAL vulnerabilities in production dependencies.
+
+## 9. Document results
+
+**Note on report file**: `docs/audits/phase-N-validation.md` is written progressively. Step 5.8 creates the file and appends the `## Spec Coverage` section. Step 9 appends all remaining sections. Do not recreate or overwrite the file in Step 9 — append only.
+
+- Test results and coverage
+- Lint and type-check status
+- Build status
+- Accessibility findings
+- Performance budget results (7a) and deep audit findings (7b)
+- Security review findings (including DAST results if applicable)
+- Dependency audit results
+- API documentation sync status (if applicable)
+- Deployment strategy compliance (if applicable)
+- CI/CD pipeline status
+- Staging deployment result
+- Migration verification status
+- Pass/fail verdict
+
+## 10. Present results and next steps
+
+Read .agent/skills/verification-before-completion/SKILL.md and follow its methodology.
+
+Use `notify_user` to present the validation report.
+
+### Proposed next steps
+
+- **If all checks pass**: "Phase N validation complete. Next: Run `/update-architecture-map` to ensure the project's living architecture document is up-to-date."
+- **If any checks fail**: "Fix the failures listed in the validation report and re-run `/validate-phase` for Phase N."
+- **If new requirements were discovered during validation** (scope gaps, missing features, behavioral corrections): Use `/evolve-feature` to add them at the correct entry point layer. Do not attempt to add them directly to specs — evolution must go through the classify → cascade flow to maintain layer consistency.

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

@@ -8,6 +8,7 @@ pipeline:
   loop: true # one validate per phase
   skills: [adversarial-review, code-review-pro, deployment-procedures, security-scanning-security-hardening, testing-strategist, verification-before-completion]
   calls-bootstrap: false
+shards: [validate-phase-quality, validate-phase-readiness]
 ---
 
 // turbo-all
@@ -16,175 +17,36 @@ pipeline:
 
 Comprehensive validation of a completed implementation phase.
 
----
-
-## 0. Load validation skills
-
-Read these skills before running checks:
-1. `.agent/skills/testing-strategist/SKILL.md` — Coverage strategy and test quality
-2. `.agent/skills/code-review-pro/SKILL.md` — Review checklist for self-audit
-3. `.agent/skills/deployment-procedures/SKILL.md` — Build and release readiness
+**Input**: A completed phase with all slices implemented
+**Output**: Validation report with pass/fail verdict
 
 ---
 
-## 0.5. Parallel dispatch option
-
-If the phase contains independent slices that don't share files, validation can run in parallel:
-
-1. **Identify independent slices** — slices that don't import from or export to each other
-2. **Dispatch parallel validation** — run Steps 1–5 concurrently for independent slices using the `parallel-agents` skill
-3. **Sequential for shared** — slices that share contracts or utilities must validate sequentially
-
-This is an optimization, not a requirement. Sequential validation is always correct.
-
-## 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.
-
-## 2. Check coverage
-
-Read .agent/skills/{{UNIT_TESTING_SKILL}}/SKILL.md and follow its test writing conventions.
-
-Run `{{TEST_COVERAGE_COMMAND}}`.
-
-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%
-- Branches: 90% (critical paths: auth, payments, data mutations, permission checks), 75% (non-critical paths)
-- Functions: 80%
-- Lines: 80%
-
-Critical paths are defined as: auth flows, payment processing, data mutations, and permission/authorization checks.
+## Shard Overview
 
-## 3. Lint
-
-Run `{{LINT_COMMAND}}`.
-
-Zero lint errors. Warnings should be reviewed and addressed.
-
-## 4. Type check
-
-Run `{{TYPE_CHECK_COMMAND}}`.
-
-Zero type errors. Strict mode must be enabled.
-
-## 5. Build
-
-Run `{{BUILD_COMMAND}}`.
-
-Build must succeed with no errors.
+| # | Shard | What It Does |
+|---|-------|-------------|
+| 1 | [`validate-phase-quality`](.agent/workflows/validate-phase-quality.md) | Code quality gates: tests, coverage, mutation testing, lint, type-check, build, CI/CD, staging deploy, deployment strategy, migrations, spec coverage |
+| 2 | [`validate-phase-readiness`](.agent/workflows/validate-phase-readiness.md) | Production readiness gates: API doc sync, accessibility, performance budgets, security review, DAST, dependency audit, results documentation, next steps |
 
 ---
 
-## 5.5. CI/CD pipeline verification
-
-Read .agent/skills/{{CI_CD_SKILL}}/SKILL.md and follow its pipeline configuration conventions.
+## Orchestration
 
-Verify the CI/CD pipeline is green for this phase's changes:
+### Step A — Run `.agent/workflows/validate-phase-quality.md`
 
-1. Check that a CI/CD configuration file exists (e.g., `.github/workflows/`, `.gitlab-ci.yml`)
-2. Verify the pipeline has run for the latest commit in this phase
-3. Verify ALL CI/CD jobs are passing (not just the test job — include lint, type-check, build, and any deployment jobs)
+Loads validation skills, runs all code quality checks (tests, coverage, mutation testing, lint, type-check, build), verifies CI/CD pipeline, deploys to staging, verifies deployment strategy compliance, checks migrations, and runs the spec coverage sweep.
 
-**If CI/CD is red** → red path: **STOP immediately.** Do not mark this phase as complete. List the failing jobs and their error output. Fix them and re-run `/validate-phase` after fixes.
+### Step B — Run `.agent/workflows/validate-phase-readiness.md`
 
-**Pass criteria**: CI/CD pipeline is green for the latest commit in this phase.
+Runs production readiness checks: API documentation sync, accessibility audit, performance budget enforcement, deep performance audit, security review (including surface-conditional DAST), dependency supply chain audit. Documents all results and presents the validation report with next steps.
 
 ---
 
-## 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`)
-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
-   - At least one authenticated route works with a valid token
-   - At least one protected route returns 401/403 for unauthenticated requests
-4. **If smoke tests fail** → red path: Capture the failing test output, rollback the staging deployment, and fix the issue before re-running `/validate-phase`
-5. **If deployment fails** → red path: Do not mark this phase as complete — diagnose the deployment failure, fix it, and re-run `/validate-phase`
-
-**Pass criteria**: Staging deployment succeeds and all smoke tests pass.
-
----
-
-## 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)
-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
-5. If migrations are pending or failed → red path: do not mark this phase as complete — run the pending migrations, verify they succeed, and re-run `/validate-phase`
-
-**Pass criteria**: Migration status is clean. All migrations from this phase ran successfully in the CI/CD environment. Rollback scripts are present.
-
----
-
-## 5.8. Spec coverage sweep
-
-Read `.agent/skills/prd-templates/references/spec-coverage-sweep.md` and follow its full procedure for FE spec, BE spec, and IA shard coverage. Apply its hard-stop rule for any uncovered items.
-
----
-
-## 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.
-
-## 7. Performance check (if web surface exists)
-
-Check if the `web-performance-optimization` skill is installed (look for `.agent/skills/web-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)
-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)
-- If performance is critical for this project, recommend installing the skill via `find-skills`
-
-## 8. Security review
-
-Read .agent/skills/adversarial-review/SKILL.md and follow its structured methodology for generating attack scenarios, abuse cases, and race conditions against the phase's changes. Produce spec-level gap items for any identified risks. Feed these into the defense-in-depth audit below.
-
-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.
-
-Report any additional findings from supplemental audits with the same severity classification.
-
-## 9. Document results
-
-**Note on report file**: `docs/audits/phase-N-validation.md` is written progressively. Step 5.8 creates the file and appends the `## Spec Coverage` section. Step 9 appends all remaining sections. Do not recreate or overwrite the file in Step 9 — append only.
-
-- Test results and coverage
-- Lint and type-check status
-- Build status
-- Accessibility findings
-- Performance findings
-- Security review findings
-- CI/CD pipeline status
-- Staging deployment result
-- Migration verification status
-- Pass/fail verdict
-
-## 10. Present results and next steps
-
-Read .agent/skills/verification-before-completion/SKILL.md and follow its methodology.
-
-Use `notify_user` to present the validation report.
-
-### Proposed next steps
+## Quality Gate
 
-- **If all checks pass**: "Phase N validation complete. Next: Run `/update-architecture-map` to ensure the project's living architecture document is up-to-date."
-- **If any checks fail**: "Fix the failures listed in the validation report and re-run `/validate-phase` for Phase N."
-- **If new requirements were discovered during validation** (scope gaps, missing features, behavioral corrections): Use `/evolve-feature` to add them at the correct entry point layer. Do not attempt to add them directly to specs — evolution must go through the classify → cascade flow to maintain layer consistency.
+You may not call `notify_user` until:
+- [ ] All code quality checks pass (Shard 1)
+- [ ] All production readiness checks pass (Shard 2)
+- [ ] Validation report written to `docs/audits/phase-N-validation.md`
+- [ ] Pass/fail verdict determined

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,13 @@ 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` Structure Map to find the correct domain folder path (may be under `domains/` or `surfaces/{name}/` for multi-product projects). The ideation domain's feature files are 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 folder for this shard (path from `ideation-index.md` Structure Map):
+   - Read the domain's `*-index.md` for the children table and Role Matrix
+   - Read each child **feature `.md` file** for sub-feature details (Role Lens, behavior, edge cases)
+   - Read the domain's `*-cx.md` for cross-domain interactions relevant to this shard
+   - If the domain has sub-domain folders, recurse into them and aggregate all descendant feature files
 2. The shard's `## Features` section (from `/decompose-architecture-structure`)
 3. `docs/plans/ideation/ideation-index.md` — Must Have features for this domain
 
@@ -56,8 +65,8 @@ Present the reconciled `## Features` list to the user, including a count of newl
 > **Reconciled features for [Shard NN — Domain Name]:**
 > [bullet list of all sub-features, with `[Architecture-only]` markers]
 > 
-> **[N] sub-features added from ideation domain file** that were missing from the shard skeleton.
-> **[M] sub-features marked `[Architecture-only]`** — not found in ideation domain file, added during decomposition.
+> **[N] sub-features added from ideation domain tree** 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?"
 
@@ -85,30 +94,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 +129,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.