cfsa-antigravity 2.7.0 → 2.8.0

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

@@ -27,11 +27,12 @@ Build the decision constraints map from the ideation output, then walk through e
 
 Before any tech stack decision, read `docs/plans/ideation/meta/constraints.md` to build the **decision constraints map**.
 
+- **If `meta/constraints.md` does not exist** → **STOP**: "Constraints file missing. Run `/ideate` to completion — constraint exploration is required before tech stack decisions."
+- **If it exists but has no `## Project Surfaces` section** → **STOP**: "Constraints file is missing Project Surfaces. Run `/ideate-validate` to complete constraint exploration."
+
 Also read `docs/plans/ideation/ideation-index.md` — specifically `## Structural Classification` (authoritative surface list and project shape) and `## Engagement Tier` (gate behavior for this session).
 
-**Tier behavior for tech stack decisions:**
-- 🤖 **Auto**: Agent uses constraints + Deep Think to select best-fit option per axis. Records reasoning. Writes decisions. User reviews all stack decisions at end of shard.
-- 🤝 **Hybrid** / 💬 **Interactive**: Present options, wait for user confirmation per axis (current behavior).
+Read the engagement tier protocol (`.agent/skills/prd-templates/references/engagement-tier-protocol.md`) — apply the tier behavior for tech stack decisions.
 
 Build the constraints map:
 
@@ -58,8 +59,10 @@ Score Fit from 1–5 based on how well the option matches the constraints map. I
 1. Ask the constraint questions for this axis
 2. Filter options based on answers
 3. Present the filtered option table with recommendation
-4. **Interactive/Hybrid**: Wait for user confirmation. **Auto**: Select highest-fit option via Deep Think, write reasoning to `architecture-draft.md`, mark as `[AUTO-CONFIRMED]`.
-5. Fire bootstrap with only that key: read `.agent/workflows/bootstrap-agents.md` and call with `PIPELINE_STAGE=create-prd` + the confirmed key
+4. Follow the decision confirmation protocol (`.agent/skills/prd-templates/references/decision-confirmation-protocol.md`) — tier-aware.
+5. Fire bootstrap with only that key: read `.agent/workflows/bootstrap-agents.md` and call with `PIPELINE_STAGE=create-prd` + the confirmed key. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`). If bootstrap verification fails:
+   - **1st failure** → retry bootstrap once with the same key
+   - **2nd failure** → **STOP**: tell the user which key failed verification and ask: "Retry, skip this skill provisioning, or abort?"
 6. Move to next axis
 
 > **Note on backend axis bootstrap keys**: `BACKEND_FRAMEWORK` and `API_LAYER` are distinct bootstrap keys and must each fire as a separate `/bootstrap-agents` call — do not combine them.
@@ -70,21 +73,27 @@ Score Fit from 1–5 based on how well the option matches the constraints map. I
 
 Get explicit user decisions *(Interactive/Hybrid)* or auto-select with Deep Think reasoning *(Auto)* — no "TBD" allowed. Use the brainstorming skill's approach — one decision at a time.
 
+**User indecision handling**: If the user expresses uncertainty ("I don't know", "not sure", "you pick") on any decision:
+- Present your recommendation with clear reasoning
+- If user accepts → proceed with it
+- If user remains uncertain → read `.agent/skills/resolve-ambiguity/SKILL.md` and apply its methodology to narrow the decision space
+- If after ambiguity resolution the user still can't decide → lock your recommendation with a note: "[Agent-recommended, user deferred]" — this can be revisited later via `/propagate-decision`
+
 > **Decision recording**: For each confirmed tech stack decision, read `.agent/skills/session-continuity/protocols/06-decision-analysis.md` and follow the **Decision Effect Analysis Protocol**. Tech stack choices have high downstream impact (they constrain frameworks, skills, deployment, and testing). Record each decision to `memory/decisions.md` with upstream/downstream effects.
 
 ### Database: Persistence Map Interview
 
 Instead of a single DATABASE decision pass, use the following structured persistence map interview to identify all required stores.
 
-Read .agent/skills/database-schema-design/SKILL.md and follow its Persistence Map Interview methodology (Sub-steps A–E). Fire bootstrap per the skill's instructions for each confirmed store.
+Read .agent/skills/database-schema-design/SKILL.md and follow its Persistence Map Interview methodology (Sub-steps A–E). Fire bootstrap per the skill's instructions for each confirmed store. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`) after each store is confirmed.
 
 ### Design Direction
 
-Read `.agent/skills/design-direction/SKILL.md` and follow its interview methodology to determine the project's visual direction. After confirmation, fire bootstrap with `DESIGN_DIRECTION=[confirmed direction]`.
+Read `.agent/skills/design-direction/SKILL.md` and follow its interview methodology to determine the project's visual direction. After confirmation, fire bootstrap with `DESIGN_DIRECTION=[confirmed direction]`. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`).
 
 ### Development tooling
 
-Read `.agent/skills/tech-stack-catalog/references/dev-tooling-decisions.md` for the tooling axes and bootstrap keys. After the user confirms all development tooling, fire bootstrap immediately with all keys listed in that reference file.
+Read `.agent/skills/tech-stack-catalog/references/dev-tooling-decisions.md` for the tooling axes and bootstrap keys. After the user confirms all development tooling, fire bootstrap immediately with all keys listed in that reference file. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`) — verify every key.
 
 ### After each tech decision
 
@@ -94,8 +103,8 @@ Read each installed skill's SKILL.md before proceeding. Append the confirmed dec
 
 Read `.agent/workflows/bootstrap-agents.md` and call it with `PIPELINE_STAGE=create-prd` plus only the keys just decided. Bootstrap runs after **each confirmed decision**, not in a batch at the end. At the end of all tech decisions, call bootstrap once more with `ARCHITECTURE_DOC` set to the dated filename.
 
-### Propose next step
+### Next step
 
-All tech stack decisions are locked. Next: Run `/create-prd-architecture` to design the system architecture and data strategy.
+**STOP** — do NOT proceed to any other workflow. The only valid next step is `/create-prd-architecture`.
 
-> If invoked standalone, surface via `notify_user`.
+> If invoked standalone, surface via `notify_user` and wait for user confirmation.

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

@@ -19,13 +19,7 @@ Transform the ideation output into a production-grade architecture design docume
 **Input**: `docs/plans/ideation/ideation-index.md` (must exist and be approved)
 **Output**: `docs/plans/YYYY-MM-DD-architecture-design.md` + `docs/plans/ENGINEERING-STANDARDS.md` + `docs/plans/data-placement-strategy.md`
 
-> **Depth standard**: Every section of the architecture document must be specified
-> to the point where a developer cannot misinterpret it. If you can write a
-> one-paragraph section summary, it's not detailed enough. Each section should
-> define every field, every flow, every error case, every permission boundary.
-> The specificity-standards rule (`.agent/rules/specificity-standards.md`) applies to every
-> word of the output. One-line placeholders like `[Auth, authorization, rate limits]`
-> are not architecture — they are headings waiting for content.
+> **Depth standard**: Every section must be specified to the point where a developer cannot misinterpret it. The specificity-standards rule (`.agent/rules/specificity-standards.md`) applies to every word of the output.
 
 ---
 
@@ -33,43 +27,30 @@ Transform the ideation output into a production-grade architecture design docume
 
 Read `docs/plans/ideation/ideation-index.md`.
 
-If the file doesn't exist, tell the user to run `/ideate` first. Do not proceed without approved ideation output.
+If the file doesn't exist → **STOP**: tell the user to run `/ideate` first.
 
-Use the **Structure Map** in `ideation-index.md` to locate specific files:
-- Constraints + surface classification → `meta/constraints.md`
-- Personas → `meta/personas.md`
-- Domain details → fractal tree under `domains/` (or `surfaces/` for multi-product). Each domain is a **folder** containing `*-index.md` (children + Role Matrix), `*-cx.md` (cross-cuts), and child feature `.md` files. Walk the tree to the depth needed.
-- Cross-cutting concerns → `ideation-cx.md` (global cross-surface) + per-domain `*-cx.md` files within the fractal tree
-- Role coverage → Role Matrix in each domain index, Role Lens in each feature file (use for RBAC planning in security shard)
+**Completeness validation**: If the file exists, verify it contains these required sections:
+- `## Structural Classification`
+- `## Engagement Tier`
+- `## MoSCoW Summary` (with at least 1 Must Have feature)
 
-Pay special attention to the **Project Surfaces** section in `meta/constraints.md` — it determines which tech stack axes apply.
+If any required section is missing → **STOP**: "ideation-index.md is incomplete — missing `[section]`. Run `/ideate` to complete ideation before proceeding."
 
-Also read `## Engagement Tier` from `ideation-index.md`. If not set during ideation, ask now:
+Use the **Structure Map** in `ideation-index.md` to locate: constraints, personas, domain details (fractal tree), cross-cutting concerns, and role coverage.
 
-> **How involved do you want to be?**
-> 1. 🤖 **Auto** — I design the full architecture via Deep Think. You review the compiled output.
-> 2. 🤝 **Hybrid** *(recommended)* — Structural steps auto. Architecture/product decisions pause for you.
-> 3. 💬 **Interactive** — I pause at every step.
+Pay special attention to **Project Surfaces** in `meta/constraints.md` — it determines which tech stack axes apply.
 
-**Wait for user answer.** If an ideation tier exists, present it as default. Write to `ideation-index.md` immediately.
+Read `## Engagement Tier` from `ideation-index.md`. If not set, ask the user and write immediately.
 
-Each shard reads the tier and adapts gates: **Auto** = all gates auto-confirm with Deep Think reasoning. **Hybrid** = structural auto, architecture/product pause. **Interactive** = all pause.
+Read `.agent/skills/prd-templates/references/engagement-tier-protocol.md` — each shard reads the tier and adapts gates.
 
 ---
 
 ## 2. Load skills
 
-### Bundled skills
+Read each skill SKILL.md listed in the frontmatter `skills` array.
 
-These skills are included in the kit — read each SKILL.md:
-1. `.agent/skills/api-design-principles/SKILL.md` — API design principles
-3. `.agent/skills/security-scanning-security-hardening/SKILL.md` — Security model
-4. `.agent/skills/clean-code/SKILL.md` — Architecture principles
-5. `.agent/skills/brainstorming/SKILL.md` — For collaborative decisions
-
-### Stack-specific skill discovery
-
-Check `.agent/skills/` for relevant skills. Read `.agent/skills/find-skills/SKILL.md` for guidance on discovering community skills for your chosen stack.
+Check `.agent/skills/` for stack-specific skills. Read `.agent/skills/find-skills/SKILL.md` for community skill discovery.
 
 ---
 
@@ -83,103 +64,50 @@ Check `.agent/skills/` for relevant skills. Read `.agent/skills/find-skills/SKIL
 | 3 | [`create-prd-security`](.agent/workflows/create-prd-security.md) | Security model, compliance escalation, integration points |
 | 4 | [`create-prd-compile`](.agent/workflows/create-prd-compile.md) | Development methodology, phasing, compile architecture-design.md + ENGINEERING-STANDARDS.md |
 
-> **Progressive working artifact**: `docs/plans/architecture-draft.md` is written incrementally by shards 1–3 (stack decisions, system architecture, data strategy, security model, integration points) and read by shard 4 (compile) to produce the final dated `architecture-design.md`.
+> **Progressive working artifact**: `docs/plans/architecture-draft.md` is written incrementally by shards 1–3 and read by shard 4 to compile the final dated `architecture-design.md`.
 
 ---
 
 ## Orchestration
 
 ### Step A — Run `.agent/workflows/create-prd-stack.md`
-
-Builds the constraints map from `ideation/meta/constraints.md`, presents tech stack options per axis, gets user decisions, fires bootstrap after each confirmation.
-
 ### Step A.5 — Run `.agent/workflows/create-prd-design-system.md`
-
-Establishes the structural UI architecture — navigation paradigm, layout grid, page archetypes, global component inventory, motion language, data density philosophy, and global state design language. Produces `docs/plans/design-system.md` which all FE specs must consume.
-
 ### Step B — Run `.agent/workflows/create-prd-architecture.md`
-
-Designs system architecture (components, data flow, deployment topology, API surface) and data strategy (placement, schema, queries, migrations, PII boundaries). Creates `docs/plans/data-placement-strategy.md`.
-
 ### Step C — Run `.agent/workflows/create-prd-security.md`
-
-Defines the security model (auth, authorization, validation, rate limits). Escalates compliance-heavy domains to full-depth sections. Documents integration points with failure modes and fallbacks.
-
 ### Step D — Run `.agent/workflows/create-prd-compile.md`
 
-Documents development methodology and phasing strategy. Compiles `docs/plans/YYYY-MM-DD-architecture-design.md` and `docs/plans/ENGINEERING-STANDARDS.md`.
-
 ---
 
 ## Step E — Quality gate
 
 ### Self-check against Architecture rubric
 
-Read .agent/skills/pipeline-rubrics/SKILL.md and apply its Architecture rubric for the self-check.
-
-Before presenting to the user, self-check both documents against the **Architecture Rubric** (12 dimensions) from `/audit-ambiguity`:
+Read `.agent/skills/pipeline-rubrics/references/architecture-rubric.md` and apply all 15 dimensions as the self-check.
 
-| # | Dimension | Check |
-|---|-----------|-------|
-| 1 | Tech Stack Decisiveness | Is every applicable axis decided with rationale? No TBDs? |
-| 2 | System Architecture | Are all components, flows, and failure modes documented? |
-| 3 | Data Strategy | Are placement, schema, queries, migrations, and PII boundaries defined? |
-| 4 | Security Model | Are auth, authz, validation, rate limits, and CSP fully specified? |
-| 5 | Compliance Depth | Are regulated domains (minors, payments, health) given full-depth sections? |
-| 6 | API Design | Are surface, versioning, conventions, errors, and pagination defined? |
-| 7 | Integration Robustness | Do all externals have failure + fallback plans? |
-| 8 | Phasing Clarity | Are phases dependency-ordered with entry/exit criteria? |
-| 9 | Engineering Standards | Are all thresholds concrete? No TBDs in ENGINEERING-STANDARDS.md? |
-| 10 | Persistence Architecture | Is the persistence map complete? Do all cross-store entities have a consistency contract (canonical ID, creation sequence, deletion cascade, read join)? |
-| 11 | Error Architecture | Is the global error envelope defined with all four fields? Are all five error decisions confirmed (envelope, propagation chain, unhandled exceptions, client fallback, error boundaries)? |
-| 12 | Attack Surface Coverage | Is the attack surface review complete? Are OWASP Top 10 (web) and API Top 10 (API) addressed with named mechanisms? Are security headers configured? Is the observability architecture documented? |
+Read `.agent/skills/prd-templates/references/architecture-completeness-checklist.md` and verify all items.
 
-Also verify completeness:
+For any dimension that scores ⚠️ or ❌ → resolve it NOW. Loop back to the relevant shard.
 
-- [ ] Every "Must Have" feature from `ideation-index.md` MoSCoW list has a home in the architecture
-- [ ] Security model addresses all compliance constraints from `ideation/meta/constraints.md`
-- [ ] Compliance-heavy domains have their own top-level sections (not buried as sub-bullets)
-- [ ] All relevant skills installed for chosen stack
-- [ ] Validation command in Engineering Standards matches `AGENTS.md` validation command
-- [ ] For multi-surface: sync strategy defined, data ownership clear, conflict resolution specified
-- [ ] For cross-platform: platform-specific considerations documented for each target OS
-- [ ] Design system document exists at docs/plans/design-system.md and all seven decision areas are filled (no placeholders)
+**Remediation loop guard**: Track remediation attempts per dimension. After **3 failed attempts** on the same dimension → **STOP**: present the dimension to the user as a known gap with context on what was tried. Include it in the review presentation as an unresolved item for user decision.
 
-For any dimension that scores ⚠️ or ❌, resolve it NOW. Loop back to the relevant step and resolve with the user.
-
-> ❌ STOP — do not call notify_user until all dimensions score ✅.
+> ❌ STOP — do not call notify_user until all dimensions score ✅ and all checklist items pass.
 
 ### Depth audit
 
-Before presenting to the user, re-read the entire architecture document and for EACH section ask:
-
-> "Could a developer implement this without asking a single clarifying question?"
-
-If the answer is no for ANY section:
-1. Identify what's missing (field types? flow steps? error cases? permission rules?)
-2. Add the missing detail NOW — do not flag it, resolve it
-3. Re-check the section
-
-This is the single most important step. The difference between a useful architecture document and a useless one is whether this audit is done honestly. A 2,000-word architecture doc is almost certainly too shallow for any non-trivial project.
+Re-read the entire architecture document and for EACH section ask: "Could a developer implement this without asking a single clarifying question?"
 
-If gaps are found, loop back to the relevant step and resolve with the user.
+If no → identify what's missing, add the detail NOW, re-check.
 
-> **Note**: This is an internal self-check, not a formal audit. For a rigorous,
-> independent audit with evidence citations, run `/audit-ambiguity architecture` as a
-> separate step after this workflow completes.
+> **Note**: This is an internal self-check. For a rigorous independent audit, run `/audit-ambiguity architecture` after this workflow completes.
 
 ## Step F — Request review and next steps
 
-Use `notify_user` to present to the user:
-- **Both** the architecture design document and the Engineering Standards document
-- Summary of the self-check results (all 12 dimensions + completeness checklist)
-- Any areas where you resolved gaps during the self-check
+Use `notify_user` to present both documents with self-check results.
 
-Both documents must be approved before proceeding. 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.
+**STOP** — do NOT proceed until the user explicitly approves.
 
-### Proposed next steps
+### Next step
 
-Once approved, present the user with the appropriate next step:
+**STOP** — do NOT propose `/decompose-architecture` or any other pipeline workflow. The only valid next step is:
 
-- **Default recommendation**: Run `/audit-ambiguity architecture` — recommended for all projects, especially those with compliance constraints
-- **Skip condition**: Only skip `/audit-ambiguity architecture` if all 12 dimensions scored ✅ AND the project has zero compliance constraints. In that case, recommend `/decompose-architecture` directly.
+- `/audit-ambiguity architecture` — unconditionally mandatory. The self-check above cannot replace an independent audit. After the audit passes, the next step is `/decompose-architecture`.

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

@@ -19,7 +19,10 @@ pipeline:
 
 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.
+**Prerequisite**: Read the approved domain boundaries from `docs/plans/ia/decomposition-plan.md`.
+
+- If this file does not exist → **STOP**: "Decomposition plan missing. Run `/decompose-architecture` Steps 3-4.5 first."
+- If the file exists but contains no `## Domain Boundary Table` → **STOP**: "Decomposition plan is incomplete — no domain boundary table found. Run `/decompose-architecture` Step 3 to generate domain boundaries."
 
 ---
 
@@ -55,6 +58,13 @@ Read `.agent/skills/prd-templates/SKILL.md` and follow its Shard Seeding Procedu
 
 Fallback for domains not covered in the ideation domain folders is defined in the skill's Shard Seeding Procedure.
 
+**Post-creation verification**: After all skeletons are created, list the `docs/plans/ia/` directory. Verify:
+- Every shard in the decomposition plan has a corresponding `.md` file
+- `00-infrastructure.md` exists regardless of domain decomposition
+- No empty files (0 bytes)
+
+If any skeleton is missing → create it now. Do not proceed to index creation with missing skeletons.
+
 ## 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.
@@ -73,8 +83,8 @@ Read `.agent/skills/prd-templates/references/decomposition-templates.md` for the
 
 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
+### 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.
+**STOP** — do NOT proceed to any other workflow. The only valid next step is `/decompose-architecture-validate`.
 
-> If this shard was invoked standalone (not from `/decompose-architecture`), surface this via `notify_user`.
+> If invoked standalone, surface via `notify_user` and wait for user confirmation.

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

@@ -19,118 +19,67 @@ pipeline:
 
 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.
+**Prerequisite**: Directory structure, shard skeletons, and layer indexes must exist (from `/decompose-architecture-structure`).
 
 ---
 
 ## 9.5. Proactive shard load pre-check (ideation signal)
 
-Before identifying deep dives, read the ideation domain folders that fed each shard. The sub-area count from ideation is a **leading indicator** of shard complexity.
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` → **Shard Load Thresholds** table.
 
 For each shard skeleton:
-1. Read the corresponding ideation domain folder (use the path from `ideation-index.md` Structure Map — may be under `domains/` or `surfaces/{name}/`). Read the folder's `*-index.md` for the children table.
-2. Count the child feature files and sub-domain folders listed in the domain index
-3. Compare against the shard load thresholds:
-
-| Ideation Sub-Areas | Pre-Check Action |
-|---|---|
-| ≤6 | ✅ No concern — proceed to skeleton validation |
-| 7–9 | ⚠️ **Pre-flag for split review** — note in the shard skeleton: `> ⚠️ Ideation source has [N] sub-areas — likely split candidate. Review at calibration gate.` |
-| ≥10 | 🚩 **Proactive split proposal** — present a split proposal to the user NOW, before the calibration gate. Use the same split format as Step 12. If the user approves, create the split shards immediately and update the decomposition plan. |
-
-> **Why proactive?** The reactive calibration gate (Step 12) catches overloaded shards, but only after skeletons are fully seeded. By reading ideation sub-area counts first, we avoid creating a massive skeleton only to immediately split it. For multi-product projects where a single surface domain (e.g., "Operations" in a desktop shop app) might have 15+ sub-areas, this saves significant rework.
+1. Read the corresponding ideation domain folder via `ideation-index.md` Structure Map
+2. Count child feature files and sub-domain folders in the domain index
+3. Compare against the load thresholds table and take the specified action
 
 ## 10. Identify deep dive candidates
 
-Read .agent/skills/architecture-mapping/SKILL.md and follow its methodology.
+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
+1. Create empty deep dive skeleton at `docs/plans/ia/deep-dives/[feature-name].md`
+2. Add reference in parent shard's "Deep Dives Needed" section
+3. Add to 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.
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` → **Shard Document Type Classification** table. Add preliminary Document Type annotation to each shard skeleton.
 
 ## 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.
+Read `.agent/skills/architecture-mapping/SKILL.md` and follow its dependency graph validation methodology.
 
-- **Must Have coverage gate**: Read `docs/plans/ideation/ideation-index.md` and extract every feature listed under "Must Have" in the MoSCoW Summary. 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 ideation-index.md are not covered by any shard: [list]. Add them to the appropriate shards before proceeding."
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` → **Sub-feature Count Thresholds** and **Split Proposal Format**.
 
-- **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). If Step 9.5 pre-flagged any shards, they should be reviewed first. Compare against the following thresholds:
+- **Must Have coverage gate**: Read `ideation-index.md` MoSCoW Summary. Every Must Have feature must appear in at least one shard. If any missing → **STOP**.
 
-  | 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. |
+- **Shard load calibration gate**: Count sub-features in each shard using the bullet/named-item rule (defined in the analysis reference). If Step 9.5 pre-flagged shards, review first. Apply the thresholds. For ≥10, use the split proposal format from the reference.
 
-  > **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?"
+  **After any split**: Update `docs/plans/ia/decomposition-plan.md` and re-run Must Have coverage gate.
 
-  **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.
+  **Split loop guard**: Track how many times the same shard has been split.
+  - **1st split** → normal. Apply the split.
+  - **2nd split on the same shard** → warn: "Shard `[name]` has been split twice. This may indicate the domain boundary is wrong. Present to user: re-split, or merge back and redraw the domain boundary?"
+  - If the total number of shards exceeds 20 → warn: "Shard count is [N]. Projects with 20+ shards are unusually large. Verify this is correct with the user."
 
+Verify structural integrity:
 - [ ] 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
+- [ ] Deep dive candidates are referenced from parent shards
+- [ ] BE/FE indexes exist with conventions templates
+- [ ] Multi-surface: shared shards have lower numbers; cross-surface deps point to shared/
 
 ## 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.
+Read `.agent/skills/session-continuity/protocols/07-spec-pipeline-generation.md` and follow the Spec Pipeline Generation Protocol.
 
 ## 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`
+Use `notify_user` to present: IA directory, BE index, FE index, master index, spec pipeline tracker.
+
+**STOP** — do NOT proceed until the user explicitly approves.
 
-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.
+### Next step
 
-**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.
+**STOP** — do NOT proceed to any other workflow. The only valid next step is `/write-architecture-spec` starting with the lowest-numbered shard per `.agent/progress/spec-pipeline.md`.

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

@@ -17,7 +17,7 @@ shards: [decompose-architecture-structure, decompose-architecture-validate]
 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)
+**Output**: `docs/plans/ia/`, `docs/plans/be/`, `docs/plans/fe/` directories with indexes and shard skeletons
 
 ---
 
@@ -25,84 +25,56 @@ Break the architecture design document into domain-bounded IA shards and create
 
 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.
+If no architecture design exists → **STOP**: tell the user to run `/create-prd` first.
 
-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."
+**Multi-file handling**: If the glob matches multiple files (e.g., multiple dated versions):
+- Use the file with the most recent date prefix
+- Warn: "Multiple architecture-design files found. Using `[filename]` (most recent). If this is wrong, specify the correct file."
 
-Also read `docs/plans/ideation/ideation-index.md` for the fractal domain map and structural classification. The ideation folder uses a fractal structure — read domain indexes (not flat files) to understand depth, child counts, and cross-cut density.
+Check the document's `**Status**:` field.
+- If `Draft` or `Review` → **STOP**: "Architecture design not yet approved. Get explicit approval first."
+- If the `**Status**:` field does not exist → **STOP**: "Architecture design document has no Status field. Add `**Status**: Approved` after explicit review, or run `/create-prd` to regenerate."
 
-> **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.
+Read `docs/plans/ideation/ideation-index.md` for the fractal domain map and structural classification.
+
+> **Design system prerequisite (web/mobile/desktop projects)**: Read `.agent/instructions/tech-stack.md` → `SURFACES`. If surfaces include `web`, `mobile`, or `desktop`, verify `docs/plans/design-system.md` exists.
 >
-> This is a warning, not a hard stop — architecture decomposition can proceed. API-only, CLI, and extension projects are not affected.
+> If not: ⚠️ **Warning** — run `/create-prd-design-system` before writing FE specs. Architecture decomposition can proceed. API-only/CLI/extension projects unaffected.
+
+Identify **Project Type** from the architecture design header:
+- **Single-surface** → standard flat structure
+- **Multi-surface** → per-surface subdirectories with shared layer
 
-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
+**Surface consistency check**: Compare the Project Type derived here with `## Structural Classification` in `ideation-index.md`. If they conflict (e.g., ideation says single-surface but architecture says multi-surface) → **STOP**: "Surface classification mismatch between ideation (`[ideation value]`) and architecture design (`[arch value]`). Resolve via `/propagate-decision` before decomposing."
 
 ## 2. Load brainstorming skill
 
-Read `.agent/skills/brainstorming/SKILL.md` — domain boundary decisions benefit from collaborative exploration.
+Read `.agent/skills/brainstorming/SKILL.md`.
 
 ## 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.
-
-**Fractal tree analysis for shard boundaries:**
-
-The ideation folder uses a fractal structure. Walk the tree to inform shard granularity:
+Read `.agent/skills/architecture-mapping/SKILL.md` and follow its Domain Boundary Protocol.
 
-| Signal | What It Means for Sharding |
-|--------|---------------------------|
-| Deep fractal tree (3+ levels) | Domain is complex enough for its own shard |
-| Many children (5+ features) | Consider splitting into multiple shards |
-| Dense CX file (5+ cross-cuts) | This domain has high coupling — keep it together in one shard, or isolate carefully |
-| Rich Role Matrix (3+ roles with access) | Shard needs multi-role IA spec coverage |
-| Hub-and-spoke shared domains | Shared domains often become `00-*` cross-cutting shards |
-| Leaf features marked `[EXHAUSTED]` | Most confident for shard scoping — behavior is fully defined |
+Read `.agent/skills/prd-templates/references/shard-boundary-analysis.md` for fractal tree signals and standard heuristics.
 
-**Standard heuristics also apply:**
-- 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
+Walk the ideation fractal tree to inform shard granularity. Build the domain inventory record, apply split trigger rules, produce the domain boundary table.
 
-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.
-
-> **Important**: Ideation does NOT prescribe shard boundaries. It provides the raw data (depth, features, cross-cuts, roles). This workflow makes the shard boundary decisions based on architectural analysis.
+> **Important**: Ideation does NOT prescribe shard boundaries. It provides raw data. This workflow makes boundary decisions based on architectural analysis.
 
 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.
+- `00-*` — Cross-cutting/foundation concerns
+- `01-*` through `NN-*` — Feature domains, dependency-ordered (lower = fewer deps)
 
 ## 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?"
+**STOP** — present domain boundary table, shard numbering, dependency ordering, and deep dive candidates to the user via `notify_user`.
 
-**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.
+**Do not proceed** until the user explicitly approves.
 
-**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.**
+**Write `docs/plans/ia/decomposition-plan.md` immediately after approval**, before proceeding to skeleton creation.
 
 ---
 
@@ -118,9 +90,4 @@ Ask:
 ## 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.