cfsa-antigravity 1.0.0

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

@@ -0,0 +1,82 @@
+---
+description: Directory structure, shard skeletons, and layer index creation for the decompose-architecture workflow
+parent: decompose-architecture
+shard: structure
+standalone: true
+position: 1
+pipeline:
+  position: 3.1
+  stage: architecture
+  predecessors: [create-prd]
+  successors: [decompose-architecture-validate]
+  skills: [technical-writer, prd-templates]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Decompose Architecture — Structure
+
+Create directory structure, shard skeleton files, and all layer indexes.
+
+**Prerequisite**: Read the approved domain boundaries from `docs/plans/ia/decomposition-plan.md`. If this file does not exist, the boundaries have not been approved — tell the user to run `/decompose-architecture` Steps 3-4.5 first.
+
+---
+
+## 5. Create directory structure and shard skeletons
+
+> **Note**: The standard directories (`docs/plans/ia/deep-dives/`, `docs/plans/be/`, `docs/plans/fe/`, `docs/plans/phases/`, `docs/audits/`) are pre-scaffolded. No directory creation needed for single-surface projects.
+
+### Multi-surface projects
+
+For each surface identified in the architecture design, plus a `shared/` surface, create the per-surface subdirectories (e.g., `docs/plans/shared/ia/deep-dives/`, `docs/plans/desktop/fe/`, `docs/plans/web/be/`, etc.). Each new directory must include a `.gitkeep` file and a `README.md`.
+
+Each surface gets its own independent spec pipeline. The `shared/` surface contains cross-surface domain models and API contracts that both surfaces depend on.
+
+### Mandatory: 00-infrastructure shard (all project types)
+
+This shard is **always** created for every project, regardless of what the architecture design says. It must be numbered `00` and created before any feature shards.
+
+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.
+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.
+4. Project scaffolding (directory structure, base configuration files)
+5. Database initialization (schema creation, migration tooling setup)
+
+> _"This shard must be the first slice in Phase 1 — it is the foundation everything else builds on."_
+
+### Shard skeletons (all project types)
+
+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 ideation.md into shard ## Features sections.
+
+Fallback for domains not in ideation.md is defined in the skill's Shard Seeding Procedure.
+
+## 6. Create IA index
+
+Read `.agent/skills/prd-templates/references/decomposition-templates.md` for the **IA Index** template. Create `docs/plans/ia/index.md` using the template, populating the shards table with all shards created in Step 5.
+
+## 7. Create BE index skeleton
+
+Read `.agent/skills/prd-templates/references/decomposition-templates.md` for the **BE Index Skeleton** template. Create `docs/plans/be/index.md` using the template.
+
+## 8. Create FE index skeleton
+
+Read `.agent/skills/prd-templates/references/decomposition-templates.md` for the **FE Index Skeleton** template. Create `docs/plans/fe/index.md` using the template.
+
+## 9. Create master index
+
+Read `.agent/skills/prd-templates/references/decomposition-templates.md` for the **Master Index** template (single-surface or multi-surface variant as appropriate). Create or update `docs/plans/index.md` using the template.
+
+For multi-surface projects, each surface's own `index.md` contains the standard three-layer table (IA/BE/FE) scoped to that surface, following the same format as the single-surface master index.
+
+### Propose next step
+
+Directory structure, shard skeletons, and all layer indexes are created. Next: Run `/decompose-architecture-validate` to identify deep dive candidates, annotate shard types, validate the dependency graph, and generate the spec pipeline tracker.
+
+> If this shard was invoked standalone (not from `/decompose-architecture`), surface this via `notify_user`.

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

@@ -0,0 +1,119 @@
+---
+description: Deep dive identification, shard type annotation, dependency validation, and review for the decompose-architecture workflow
+parent: decompose-architecture
+shard: validate
+standalone: true
+position: 2
+pipeline:
+  position: 3.2
+  stage: architecture
+  predecessors: [decompose-architecture-structure]
+  successors: [write-architecture-spec]
+  skills: [session-continuity]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Decompose Architecture — Validate
+
+Identify deep dive candidates, annotate shard document types, validate the dependency graph, generate the spec pipeline tracker, and request review.
+
+**Prerequisite**: Directory structure, shard skeletons, and layer indexes must exist (from `/decompose-architecture-structure` or equivalent). The IA index at `docs/plans/ia/index.md` and shard files must be in place.
+
+---
+
+## 10. Identify deep dive candidates
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its methodology.
+
+For each shard marked "Needs Deep Dive" in the domain boundary table:
+
+1. Create an empty deep dive skeleton at `docs/plans/ia/deep-dives/[feature-name].md`
+   - **Naming convention**: Use kebab-case derived from the feature name (e.g., `chat-orchestration.md`, `age-verification-flow.md`, `order-state-machine.md`)
+2. Add a reference to it in the parent shard's "Deep Dives Needed" section
+3. Add it to the IA index deep dives column
+
+## 11. Annotate expected shard types
+
+Based on domain boundary analysis, add a **preliminary** `Document Type`
+annotation to each shard skeleton. `/write-architecture-spec` confirms or reclassifies.
+
+| Classification | Expected BE Specs |
+|---------------|-------------------|
+| **Feature domain** | 1 |
+| **Multi-domain** | N (split along sub-feature boundaries) |
+| **Cross-cutting** | 1 (`00-*`) |
+| **Structural reference** | 0 |
+
+```markdown
+> **Document Type** (preliminary): Feature domain | Multi-domain | Cross-cutting | Structural reference
+```
+
+> **Note**: Classification is based on domain analysis, not shard content (which doesn't
+> exist yet). `/write-be-spec` uses the confirmed type to determine spec count.
+
+## 12. Dependency graph validation
+
+Verify the decomposition (structural checks only — content doesn't exist yet):
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its methodology for dependency graph validation.
+
+- **Must Have coverage gate**: Read `docs/plans/vision.md` and extract every feature listed under "Must Have". For each Must Have feature, verify it appears in at least one shard's Features section. If any Must Have feature is not covered by any shard → **STOP**: "The following Must Have features from vision.md are not covered by any shard: [list]. Add them to the appropriate shards before proceeding."
+
+- **Shard load calibration gate**: After the Must Have coverage gate passes, count the sub-features in each shard's `## Features` section using the **bullet/named-item rule**: count every bullet point or named item under `## Features`, **excluding** group headers (lines that introduce a group of sub-features but are not themselves a concrete capability). Compare against the following thresholds:
+
+  | Sub-feature Count | Action |
+  |-------------------|--------|
+  | **≤6** | ✅ OK — proceed |
+  | **7–9** | ⚠️ Flag for user review — present the sub-feature list and ask: "This shard has [N] sub-features. Keep as-is, or split?" |
+  | **≥10** | 🛑 **Hard stop** — do NOT proceed. Present a mandatory split proposal and **wait for the user to approve the split** before continuing. No shard may exit this gate with ≥10 sub-features. |
+
+  > **What counts as a sub-feature**: Count each bullet or named item under `## Features`. Group headers (e.g., "Content Management:") that introduce a cluster of sub-features are **not** counted — only the items beneath them. If a bullet contains sub-bullets, count each sub-bullet independently. When in doubt, ask: "Would a product manager list this as a separate line item in a release note?"
+
+  **Split proposal format:**
+  ```
+  Shard [NN] — [domain name] has [N] sub-features (threshold: ≥10 → mandatory split)
+  
+  Current sub-features:
+    1. [sub-feature]
+    2. [sub-feature]
+    ...
+  
+  Proposed split:
+    [NN]a — [new domain name] → file: docs/plans/ia/[NN]a-[domain].md
+      Sub-features: 1, 3, 5
+    [NN]b — [new domain name] → file: docs/plans/ia/[NN]b-[domain].md
+      Sub-features: 2, 4, 6
+  
+  Split rationale: [why these groups are independent]
+  ```
+
+  **After any split**: Update `docs/plans/ia/decomposition-plan.md` with the revised domain boundary table and re-run the Must Have coverage gate to confirm no features were lost in the split.
+
+- [ ] No circular dependencies between shards
+- [ ] Cross-cutting shards (00-*) don't depend on feature shards
+- [ ] Every shard has a preliminary Document Type annotation
+- [ ] Deep dive candidates are referenced from their parent shards
+- [ ] BE/FE indexes exist with conventions templates (mapping tables will be populated later)
+- [ ] For multi-surface: shared surface shards have lower numbers than surface-specific shards that depend on them
+- [ ] For multi-surface: each surface has its own index.md with IA/BE/FE layer table
+- [ ] For multi-surface: cross-surface dependencies point to shared/ shards, not directly to another surface's shards
+
+## 13. Generate spec pipeline tracker
+
+Read `.agent/skills/session-continuity/protocols/07-spec-pipeline-generation.md` and follow the **Spec Pipeline Generation Protocol**
+to create `.agent/progress/spec-pipeline.md` tracking IA/BE/FE completion per shard.
+
+## 14. Request review and propose next steps
+
+Use `notify_user` to present:
+- The full `docs/plans/ia/` directory (shard skeletons + index)
+- `docs/plans/be/index.md`
+- `docs/plans/fe/index.md`
+- `docs/plans/index.md`
+- `.agent/progress/spec-pipeline.md`
+
+The decomposition must be approved before filling in shards with `/write-architecture-spec`. Do NOT proceed to the next step until the user sends a message explicitly approving this output. Proposing next steps is not the same as receiving approval. Wait for explicit approval before continuing.
+
+**Proposed next step**: Once approved, run `/write-architecture-spec` starting with the lowest-numbered skeleton shard. Read `.agent/progress/spec-pipeline.md` to identify which shard to start with.

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

@@ -0,0 +1,111 @@
+---
+description: Break architecture design into numbered IA shards and create layer indexes — establishes the full docs/plans/ structure
+pipeline:
+  position: 3
+  stage: architecture
+  predecessors: [create-prd]
+  successors: [write-architecture-spec]
+  skills: [technical-writer, resolve-ambiguity]
+  calls-bootstrap: false
+shards: [decompose-architecture-structure, decompose-architecture-validate]
+---
+
+// turbo-all
+
+# Decompose Architecture
+
+Break the architecture design document into domain-bounded IA shards and create the full spec layer structure.
+
+**Input**: `docs/plans/YYYY-MM-DD-architecture-design.md` (must exist and be approved)
+**Output**: `docs/plans/ia/`, `docs/plans/be/`, `docs/plans/fe/` directories with indexes and shard skeletons (or per-surface subdirectories for multi-surface projects)
+
+---
+
+## 1. Read architecture design
+
+Read the file at `docs/plans/*-architecture-design.md`.
+
+If no architecture design exists, tell the user to run `/create-prd` first. Do not proceed without an approved design.
+
+Also check the document's `**Status**:` field. If the status is `Draft` or `Review` → **STOP**: "The architecture design is not yet approved (current status: [status]). Get explicit approval from the user and update the status to `Approved` before decomposing."
+
+Also read the file at `docs/plans/vision.md`.
+
+> **Design system prerequisite (web/mobile/desktop projects)**: Read `.agent/instructions/tech-stack.md` and locate the `SURFACES` value. If surfaces include `web`, `mobile`, or `desktop`, verify that `docs/plans/design-system.md` exists and is not empty.
+>
+> If it does not exist:
+>
+> ⚠️ **Warning**: FE specs for this project require a design system (`docs/plans/design-system.md`). Run `/create-prd-design-system` before writing any FE specs. You may continue with architecture decomposition now, but the design system must be completed before the FE spec writing phase.
+>
+> This is a warning, not a hard stop — architecture decomposition can proceed. API-only, CLI, and extension projects are not affected.
+
+Identify the **Project Type** from the architecture design header:
+- **Single-surface** (web, desktop, mobile, CLI, API) → standard flat structure
+- **Multi-surface** (desktop + web, mobile + web, etc.) → per-surface subdirectories with shared layer
+
+## 2. Load brainstorming skill
+
+Read `.agent/skills/brainstorming/SKILL.md` — domain boundary decisions benefit from collaborative exploration.
+
+## 3. Identify domain boundaries
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its methodology.
+
+Analyze the architecture design and identify natural domain boundaries. Each boundary becomes a numbered IA shard.
+
+**Heuristics for finding boundaries:**
+- Features that share the same data models belong together
+- Features that can be developed/deployed independently are candidates for separation
+- Features that share the same access control model may belong together
+- Cross-cutting concerns (auth, API conventions, error handling) become `00-*` shards
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its Domain Boundary Protocol. Build the domain inventory record, apply all three split trigger rules, and produce the domain boundary table. Present split candidates to the user before locking any boundary.
+
+Present the proposed domain decomposition to the user for validation.
+
+## 4. Assign shard numbers
+
+Follow the numbering convention:
+- `00-*` — Cross-cutting/foundation concerns (may have multiple: `00-api-conventions`, `00-auth-middleware`, etc.)
+- `01-*` through `NN-*` — Feature domains, ordered by dependency (dependencies first)
+
+Order rule: If shard B depends on shard A, then A gets a lower number than B.
+
+## 4.5. Request approval of domain boundaries
+
+**STOP HERE** and present the domain boundary table and shard numbering to the user for explicit approval. Use `notify_user` to present:
+
+1. The complete domain boundary table from Step 3
+2. The proposed shard numbering from Step 4
+3. The dependency ordering rationale
+4. Any shards marked as needing deep dives
+
+Ask:
+- "Does this decomposition capture every feature from the architecture design?"
+- "Are the domain boundaries in the right places, or should any be split/merged?"
+- "Is the dependency ordering correct?"
+
+**Do not proceed** to shard skeleton creation until the user explicitly approves the domain boundaries. If the user requests changes, revise Steps 3-4 and re-present.
+
+**Write `docs/plans/ia/decomposition-plan.md` immediately after user approval of the domain list, before proceeding to skeleton creation. This is a single gate — write the plan once, then proceed to the Shard Overview.**
+
+---
+
+## Shard Overview
+
+| # | Shard | What It Does |
+|---|-------|-------------|
+| 1 | [`decompose-architecture-structure`](.agent/workflows/decompose-architecture-structure.md) | Creates directory structure, shard skeletons, and all layer indexes |
+| 2 | [`decompose-architecture-validate`](.agent/workflows/decompose-architecture-validate.md) | Identifies deep dives, annotates shard types, validates dependencies, generates tracker, requests review |
+
+---
+
+## Orchestration
+
+### Step A — Run `.agent/workflows/decompose-architecture-structure.md`
+
+Creates the directory structure (with multi-surface subdirectories if needed), writes shard skeleton files, and creates the IA, BE, FE, and master index files.
+
+### Step B — Run `.agent/workflows/decompose-architecture-validate.md`
+
+Identifies deep dive candidates, annotates expected shard document types, validates the dependency graph, generates the spec pipeline tracker, and requests user review.

package/template/.agent/workflows/evolve-contract.md

@@ -0,0 +1,98 @@
+---
+description: Safely evolve a Zod schema — identify all consumers, write migration tests, update across all four surfaces
+pipeline:
+  position: utility
+  stage: maintenance
+  predecessors: [] # callable from any stage
+  successors: [] # returns to caller
+  skills: [tdd-workflow, migration-management, testing-strategist, error-handling-patterns]
+  calls-bootstrap: true
+---
+
+# Evolve Contract
+
+Safely modify a Zod schema without breaking existing consumers.
+
+**Input**: The contract to change and the desired modification
+**Output**: Updated contract, migration tests, and all consumers updated
+
+---
+
+## 0. Load contract evolution skills
+
+Read these skills for safe schema migration:
+1. `.agent/skills/migration-management/SKILL.md` — Migration strategy and versioning
+2. `.agent/skills/testing-strategist/SKILL.md` — Migration test coverage
+3. `.agent/skills/error-handling-patterns/SKILL.md` — follow its methodology for schema change error handling
+
+---
+
+## 1. Identify the contract
+
+Read .agent/skills/{{LANGUAGE_SKILL}}/SKILL.md and follow its language conventions.
+
+Determine which Zod schema needs to change and what the change is:
+- **Additive** (new optional field) — Low risk
+- **Narrowing** (tighter validation) — Medium risk
+- **Breaking** (rename, remove, type change) — High risk
+
+## 2. Find all consumers
+
+Search for all usages of `SchemaName` in the source directory (see `.agent/instructions/structure.md` for the root — typically `src/`).
+
+Document all consumers:
+- API endpoint handlers
+- Frontend components
+- Test files
+- Other contracts that reference this one
+
+## 3. Write migration tests
+
+Read .agent/skills/tdd-workflow/SKILL.md and follow its Red→Green→Refactor cycle for contract evolution.
+
+Read .agent/skills/{{UNIT_TESTING_SKILL}}/SKILL.md and follow its test writing conventions.
+
+Before changing anything, write tests that validate:
+- Existing data still passes the new schema (backward compatibility)
+- New data shape is accepted
+- Invalid data is rejected
+
+Run `{{TEST_COMMAND}}` — tests should FAIL until the schema is updated.
+
+## 4. Update the contract
+
+Read .agent/skills/{{LANGUAGE_SKILL}}/SKILL.md and follow its language conventions.
+
+Modify the Zod schema. For breaking changes:
+- Consider versioning (v1 → v2)
+- Add runtime migration helpers if needed
+
+## 4.5. New dependency check
+
+If the contract change introduces a dependency not currently in the skill set — for example, a new Zod plugin, a Pydantic extension, a binary serialization library, or a new validation pattern — read `.agent/workflows/bootstrap-agents.md` and invoke `/bootstrap-agents NEW_DEPENDENCY=[package]` before updating consumers in Step 5.
+
+Confirm the matching skill is installed (or no new dependency was introduced) before proceeding to Step 5.
+
+## 5. Update all consumers
+
+Read .agent/skills/{{LANGUAGE_SKILL}}/SKILL.md and follow its language conventions.
+
+For each consumer found in Step 2:
+- Update the code to use the new schema shape
+- Verify types resolve correctly
+
+## 6. Validate
+
+Run `{{VALIDATION_COMMAND}}` (see `.agent/instructions/commands.md` for the configured validation command).
+
+All must pass.
+
+## 6.5 — Spec cascade check
+
+For each consumer updated in Step 5, identify which BE spec and FE spec reference this contract. Check whether the change (additive/narrowing/breaking) requires updating those specs. For breaking changes, the BE spec and FE spec MUST be updated before proceeding. For additive changes, update the spec if the new field is user-visible or API-facing. Update the IA Source Map in the BE spec to reflect the change.
+
+## 7. Document the change and next steps
+
+Add an entry to the decisions log in `docs/plans/*-architecture-design.md` explaining why the contract changed.
+
+**Proposed next step**: Re-run `/validate-phase` for the affected phase to ensure no regressions were introduced by the contract evolution.

package/template/.agent/workflows/evolve-feature-cascade.md

@@ -0,0 +1,140 @@
+---
+description: Cascade new content through downstream layers, assess implementation impact, run consistency check, and write evolution record
+parent: evolve-feature
+shard: cascade
+standalone: true
+position: 2
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [evolve-feature-classify]
+  successors: []
+  skills: [resolve-ambiguity, technical-writer]
+  calls-bootstrap: true
+---
+
+# Evolve Feature — Cascade
+
+Cascade the new content from the entry point through all downstream layers with existing content, assess implementation impact, run a consistency check, and write the evolution record.
+
+> **Prerequisite**: The entry point document must already contain the new content (written by `/evolve-feature-classify` Step 4). The cascade scope must be determined (Step 5 output).
+
+---
+
+## 1. Cascade through each downstream layer
+
+Read .agent/skills/technical-writer/SKILL.md and apply its writing standards to all spec additions and the evolution record.
+
+For each downstream layer with existing content (in order: architecture → IA → BE → FE → phase plan):
+
+1. **Read existing documents** in the layer
+2. **Determine what the new feature means for this layer** — what sections need additions, what contracts change, what new components are needed
+3. **Write the additions** — new sections, new entries in existing tables, new acceptance criteria, new contracts. Write at the same depth and quality as the existing content in the layer.
+4. **Present additions to user** — show exactly what was added and where
+
+**STOP at each layer** — do not cascade to the next layer until the user approves the current layer's additions.
+
+Layer-specific guidance:
+
+- **Architecture layer**: Add new components, update system diagrams references, add NFRs, update integration points
+- **IA layer**: Add new domain interactions, update contracts, add data model changes, update access control
+- **BE layer**: Add new API endpoints, update schemas, add middleware requirements, update validation rules
+- **FE layer**: Add new components, update state management, add new routes, update accessibility requirements
+- **Phase plan**: Add new slices or update existing slice acceptance criteria (see Step 2)
+
+> After writing additions to any spec document in this step, append a row to that spec's `## Changelog` table recording: today's date, `'Evolution: [brief description of what was added]'`, this workflow (`/evolve-feature-cascade`), and the sections of the spec that were updated. If the spec does not yet have a `## Changelog` section, add one following the template in `.agent/skills/prd-templates/references/be-spec-template.md` (for BE specs) or the equivalent FE/IA template before appending the row.
+
+---
+
+## 2. Assess implementation impact
+
+If `docs/plans/phases/` exists and contains phase plans:
+
+1. **Check in-progress slices** — do any currently in-progress slices need their acceptance criteria updated? List the affected criteria.
+2. **Check completed slices** — do any completed slices that may need revisiting? (This is a red flag — document it clearly with regression risk assessment)
+3. **Determine if new slices are needed** — does the new feature require new implementation slices in the current phase? If yes, draft the slice names and acceptance criteria.
+4. **Determine if phase plan update is required** — does the scope require changes to the phase plan structure?
+
+Present the impact assessment:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Implementation Impact
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+In-progress slices affected:              [list or "none"]
+Completed slices that may need revisiting: [list or "none"]
+New slices needed:                        [list or "none"]
+Phase plan update required:               [yes/no]
+
+Recommended action: [specific next step]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If no phase plans exist, skip this step and note: "No phase plans exist yet — implementation impact will be assessed during `/plan-phase`."
+
+---
+
+## 3. Run consistency check
+
+Read .agent/skills/resolve-ambiguity/SKILL.md and follow its methodology.
+
+For every document that received additions in Step 1:
+
+1. **Re-read the full document** — verify the additions integrate correctly with existing content
+2. **Check for internal contradictions** — do the additions conflict with anything else in the same document?
+3. **Check cross-references between changed documents** — if multiple documents were updated, verify they are consistent with each other
+4. **Check against locked decisions** — do the additions contradict any locked architectural decisions?
+
+Report any issues found. **Do not auto-fix** — present them to the user for review.
+
+---
+
+## 4. Write evolution record
+
+Write `docs/audits/evolve-feature-[name]-[date].md` recording:
+
+- **Feature name** — short identifier for the evolution
+- **Change type** — classification from Step 2 of `/evolve-feature-classify`
+- **Entry point** — which document received the initial content
+- **New content written** — summary of what was added at the entry point
+- **Layers updated** — list of downstream layers that received additions
+- **Per-layer additions** — what was added at each layer (summary, not full content)
+- **Implementation impact** — assessment from Step 2 (if applicable)
+- **Consistency check results** — pass/fail with details
+- **Timestamp** of the evolution run
+
+---
+
+## 4.5. Bootstrap gate — new dependency check
+
+Before closing the cascade, scan every document that was updated in Step 1 for any technology, library, or service referenced in the new content that does not have a corresponding installed skill directory in `.agent/skills/`.
+
+For each missing skill:
+1. Identify the technology (e.g., WebSocket, S3 storage, Stripe, Redis)
+2. Read `.agent/workflows/bootstrap-agents.md` and invoke `/bootstrap-agents NEW_DEPENDENCY=[technology]`
+3. Confirm the matching skill is installed before proceeding to Step 5
+
+If no new unregistered technologies were introduced, skip and proceed to Step 5.
+
+---
+
+## 5. Propose next steps
+
+Display the completion summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Feature Evolution Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Entry point:       [document]
+Layers updated:    [list]
+New content:       [summary]
+Implementation:    [impact summary]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❗ **Mandatory next step — do not skip**: The evolution just added or modified content across [N] layers. Evolution bypasses the normal deepening phase — the audit is the quality gate that replaces it.
+
+Run `/audit-ambiguity` on the affected layers before any implementation work touches these documents. The affected layers are: [list the layers that were updated during the cascade — populated from Step 1's output].
+
+This is not optional. Under-specified evolution content is the single most common source of spec drift. The audit catches what the inline micro check may have missed at a cross-document level.
+```

package/template/.agent/workflows/evolve-feature-classify.md

@@ -0,0 +1,116 @@
+---
+description: Capture the new feature/requirement, classify the change type, identify the entry point document, write new content, and determine cascade scope
+parent: evolve-feature
+shard: classify
+standalone: true
+position: 1
+pipeline:
+  position: utility
+  stage: quality-gate
+  predecessors: [] # callable standalone
+  successors: [evolve-feature-cascade]
+  skills: [technical-writer, brainstorming]
+  calls-bootstrap: false
+---
+
+# Evolve Feature — Classify
+
+Capture the user's new feature, requirement, or constraint. Classify it, identify the correct entry point document, write the new content at proper spec depth, and determine which downstream layers need updating.
+
+> **Prerequisite**: At least `docs/plans/vision.md` must exist. If the pipeline hasn't started, run `/ideate` first — there's nothing to evolve yet.
+
+---
+
+## 1. Capture the new thing
+
+Ask the user to describe what they want to add. Accept free-form input or `@file`.
+
+If the user provides an `@file` reference, read the file and extract the key additions. If free-form, engage briefly to ensure the addition is clear — but this is NOT a full `/ideate` interview. The goal is to understand what's being added, not to explore the entire problem space.
+
+---
+
+## 2. Classify the change
+
+Read .agent/skills/brainstorming/SKILL.md and follow its methodology.
+
+Present the classification menu:
+
+```
+What type of change is this?
+
+[1] New feature — an entirely new capability that doesn't exist in the current specs
+[2] New requirement on an existing feature — additional constraint, behavior, or acceptance criteria for something already specified
+[3] New technical constraint — a non-functional requirement that affects architecture (performance, compliance, infrastructure)
+[4] Scope correction — something was misunderstood or underspecified in existing specs and needs to be fixed
+```
+
+**Do not proceed until the user selects.**
+
+---
+
+## 3. Identify the entry point document
+
+Based on the classification, determine where the new content enters the pipeline:
+
+| Classification | Entry Point Document | Rationale |
+|---------------|---------------------|-----------|
+| **[1] New feature** | `docs/plans/vision.md` | New features start at the vision layer — they affect everything downstream |
+| **[2] New requirement** | The IA shard that owns the affected domain | Requirements on existing features enter at the domain interaction level |
+| **[3] New technical constraint** | `docs/plans/[dated]-architecture-design.md` | Technical constraints affect the architecture and everything below it |
+| **[4] Scope correction** | Ask the user which document contains the misunderstanding | Corrections enter wherever the original misunderstanding lives |
+
+For classification [2], identify which IA shard owns the affected domain by reading `docs/plans/ia/index.md` and matching the feature to a domain.
+
+---
+
+## 4. Write new content at the entry point
+
+Read .agent/skills/technical-writer/SKILL.md and follow its clarity standards for all new spec content.
+
+This is a real spec-writing step — not a placeholder. Write the new content at the appropriate depth for the entry point layer:
+
+**If entry point is vision layer** (`docs/plans/vision.md`):
+- Feature description (what it does, why it matters)
+- Affected personas (who uses this)
+- Success criteria (how we know it works)
+- Constraints (what limits apply)
+
+**If entry point is architecture layer** (`architecture-design.md`):
+- Technical constraint description
+- Affected components (which parts of the system this touches)
+- Non-functional requirements (performance, scalability, compliance)
+- Integration points (how this relates to existing architecture decisions)
+
+**If entry point is IA layer** (specific IA shard):
+- Domain interactions (new user flows or modifications to existing flows)
+- Contracts (new or modified API contracts)
+- Data models (new entities, fields, or relationships)
+- Access control (RBAC implications)
+
+**Inline ambiguity check**: Before presenting this content to the user for approval, apply the Micro Ambiguity Check from `.agent/skills/session-continuity/SKILL.md` (Ambiguity Gates section). Walk each individual element of the new content and ask: "Would an implementer need to guess about this?" For every element where the answer is yes — fix it now. Add the missing detail, type, behavior, or constraint. Only present the content to the user once it passes the micro check.
+
+Present the written content to the user.
+
+**STOP — do not proceed until the user approves the new content.**
+
+---
+
+## 5. Determine cascade scope
+
+Based on the entry point, determine which downstream layers have existing content that needs updating:
+
+| Entry Point | Cascade Layers (in order) |
+|-------------|---------------------------|
+| Vision | Architecture → IA → BE → FE → Phase plan |
+| Architecture | IA → BE → FE → Phase plan |
+| IA shard | BE spec for that shard → FE spec for that shard → Phase plan |
+| BE spec | FE → Phase plan |
+| Scope correction | Depends on the document — all layers below the corrected document |
+
+**Important**: When the entry point is an IA shard, the downstream cascade remains scoped to the affected domain shard's corresponding BE and FE specs. Do not cascade into unrelated domain shards unless the user explicitly broadens scope.
+
+For each downstream layer, check whether content exists (using the same file checks as `/remediate-pipeline-assess` Step 1). Only layers with existing content need updating — layers that haven't been started yet will naturally incorporate the new content when they are written.
+
+Report: "These layers have existing content that will need updating: [list]."
+
+If no downstream layers have content, report: "No downstream layers have existing content — the new content will be incorporated when those layers are written. Evolution complete."