cfsa-antigravity 2.7.0 → 2.9.0

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

@@ -11,7 +11,7 @@ pipeline:
   successors: [write-be-spec-write]
   skills: [api-design-principles, database-schema-design, error-handling-patterns, find-skills, logging-best-practices, migration-management, prd-templates, resolve-ambiguity, testing-strategist, workflow-automation]
   calls-bootstrap: false
-requires_placeholders: [LANGUAGE_SKILL, DATABASE_SKILLS, AUTH_SKILL, BACKEND_FRAMEWORK_SKILL, ORM_SKILL, UNIT_TESTING_SKILL]
+requires_placeholders: [DATABASE_SKILLS, SECURITY_SKILLS, SURFACES]
 ---
 
 // turbo-all
@@ -20,152 +20,74 @@ requires_placeholders: [LANGUAGE_SKILL, DATABASE_SKILLS, AUTH_SKILL, BACKEND_FRA
 
 Identify the target IA shard, classify it, load skills, and read all source material including cross-references and deep dives.
 
-**Prerequisite**: IA shard must be complete (status ✅ in `docs/plans/ia/index.md`). If not, tell the user to run `/write-architecture-spec` first.
+**Prerequisite**: IA shard must be complete (status ✅ in `docs/plans/ia/index.md`). If not → **STOP**: run `/write-architecture-spec` first.
 
 ---
 
 ## 1. Verify IA layer is complete, then identify the target shard
 
-Before identifying the target shard, verify the entire IA layer is ready:
-
 1. Read `docs/plans/ia/index.md`
 2. Check every shard's status column
-3. **Hard stop** if any shard is not ✅:
-
-> ❌ **Cannot write BE spec — IA layer is incomplete.**
-> The following shards are not yet complete:
-> - [shard-name]: [status]
->
-> Run `/write-architecture-spec` for each incomplete shard before proceeding to `/write-be-spec`.
-
-**Why**: BE specs resolve cross-shard IA references. If referenced shards are still skeletons, the BE spec will contain gaps or guesses that cascade into FE specs and implementation. The cost of waiting for IA completion is hours; the cost of writing BE specs against incomplete IA is days of rework.
-
----
+3. If any shard is not ✅ → **STOP**: list incomplete shards and redirect to `/write-architecture-spec`
 
 Determine which IA shard to process. Read it in full before proceeding.
 
 ## 2. Classify the shard
 
-Not every IA shard produces the same output. Before writing anything, classify the shard:
-
-| Classification | Description | BE Spec Output | How to Detect |
-|---------------|-------------|----------------|---------------|
-| **Feature domain** | Defines user interactions, data models, and API-facing behavior for a single cohesive domain | 1 BE spec | Has data model + user flows + access model that imply API endpoints |
-| **Multi-domain** | Covers multiple distinct backend sub-systems that share a product surface but have independent APIs | N BE specs (split along sub-feature boundaries) | Section headers map to independent API surfaces; data models don't overlap between sections; could be developed by different teams |
-| **Cross-cutting** | Defines shared patterns consumed by all feature specs (auth, API conventions, error handling) | 1 cross-cutting BE spec (`00-*`) | Content is about "how all endpoints work" not "what this feature does" |
-| **Structural reference** | Maps structure, naming, or routing without defining API behavior | 0 BE specs | No data model, no user flows, no endpoints — just reference tables |
-| **Composite** | Contains both a structural reference section AND feature behavior (e.g., URL mapping + vanity URL lifecycle) | Depends — feature portion may belong in another shard's BE spec | Look for cross-references pointing the feature content to its owning domain |
-
-**Multi-domain split heuristic — sub-feature endpoint inventory:**
-
-Before classifying a shard as multi-domain, build a **sub-feature endpoint inventory**:
+Read `.agent/skills/prd-templates/references/be-spec-classification.md` — follow the classification types, multi-domain split heuristic, and detection criteria.
 
-| Sub-feature | Expected endpoints | Data model(s) | Independent? |
-|-------------|-------------------|---------------|-------------|
-| [sub-feature] | `POST /api/...`, `GET /api/...` | [table/collection names] | [Yes/No] |
-| [sub-feature] | `PUT /api/...`, `DELETE /api/...` | [table/collection names] | [Yes/No] |
+Present the classification to the user before proceeding. Include: classification type + reasoning, expected BE spec count, split boundaries (if multi-domain), Referenced Material Inventory.
 
-**Split criterion**: Two or more independent groups each have their own data model and could be assigned to a different developer without coordination → split into separate BE specs. Section header count alone is **NOT** the criterion — independence of data models and API surfaces is.
-
-**Present the classification to the user before proceeding.** Include:
-- The classification and reasoning
-- How many BE specs will be produced
-- For multi-domain: the proposed split boundaries
-- For structural reference: confirmation that no BE spec is needed
+**STOP** — do NOT proceed until the user explicitly confirms the classification.
 
 ## 2.5. Verify surface stack map is populated
 
-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.
-
-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)
+Read the surface stack map from `.agent/instructions/tech-stack.md`. Determine this shard's surface from its directory path.
 
-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`."*
+Required map cells: Languages, Databases, BE Frameworks, ORMs, Unit Tests (all per-surface), Auth (cross-cutting).
 
-Only proceed to Step 3 when all required map cells are filled.
+If any required cells are empty → **STOP**: run `/create-prd` first.
 
 ## 3. Load skill bundle
 
-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`
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md` and follow the Skill Loading Protocol for `write-be-spec-classify`.
 
-**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`.
+Also read bundled skills: `api-design-principles`, `error-handling-patterns`, `database-schema-design`, `migration-management`, `testing-strategist`, `logging-best-practices`.
 
-### Ambiguity resolution
+**Conditional**: If IA shard includes async/background/queue processing → also read `workflow-automation`.
 
-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.
+When any requirement is unresolvable → load and follow `.agent/skills/resolve-ambiguity/SKILL.md`.
 
 ## 4. Read reference documents
 
-Read the file at `docs/plans/be/index.md` (conventions template) and the file at `docs/plans/index.md` (master index, tech stack).
-
-Also read `docs/plans/data-placement-strategy.md` if it exists — this document specifies which entities live in which store and defines PII boundaries. Every BE spec must place data consistently with this strategy.
+Read `docs/plans/be/index.md` (conventions), `docs/plans/index.md` (master index), and `docs/plans/data-placement-strategy.md` (entity placement + PII boundaries).
 
 ## 5. Read the IA source material
 
-This is the most critical step. Read **all** of the following:
-
 ### 5a. Primary shard
-Read the file at `docs/plans/ia/[NN-shard-name].md` (the full IA shard).
+Read `docs/plans/ia/[NN-shard-name].md` in full.
 
 ### 5b. Resolve cross-shard references
-Scan the primary shard for all cross-references to other shards (look for `See [shard NN](...)`, `defined in [shard NN](...)`, or `Related shards:` headers). For each reference:
-1. Read the referenced section (not the entire shard — just the relevant section)
-2. Note what content is being borrowed (data model? access rules? edge cases?)
-3. Record the reference as: `Source: [shard-file.md] § [section-name] (lines N–M)`
-
-Build a **Referenced Material Inventory**:
-```
-Primary: 09-playground.md (full shard)
-Cross-refs:
-  - 02-account-architecture.md § Junior Account Controls (lines 680–706)
-  - 03-rbac-policies.md § Permission Taxonomy: playground.* (lines 45–52)
-  - 12-resources-settings.md § Credentials Management (lines 93–174)
-```
+Scan for cross-references. For each: read the referenced section, note borrowed content, record as: `Source: [file] § [section] (lines N–M)`.
+
+Build a **Referenced Material Inventory**.
 
 ### 5c. Read deep dives
-List the files in `docs/plans/ia/deep-dives/`.
-Identify which deep dives are referenced by the primary shard. **Read each referenced deep dive in full** — these contain architectural decisions (technology choices, protocol designs, phasing strategies) that the BE spec must implement. Extract and record:
-- Key decisions (what was decided and why)
-- Architectural constraints (what the BE spec must conform to)
-- Data schemas or contracts defined in the deep dive
+List `docs/plans/ia/deep-dives/`. Read each referenced deep dive in full. Extract key decisions, architectural constraints, data schemas.
 
-### 5d. Read the IA shard's testability section
-If the shard has a testability/acceptance criteria section, read it — these become the BE spec's performance targets and test requirements.
+### 5d. Read testability section
+If the shard has testability/acceptance criteria → read for performance targets and test requirements.
 
 ## 6. Check cross-cutting specs
 
-Read any completed cross-cutting specs — feature specs must follow their patterns. List the files matching `docs/plans/be/00-*.md` (cross-cutting specs).
+Read any completed cross-cutting specs at `docs/plans/be/00-*.md`.
 
 ## 7. Present classification and request approval
 
-Include the expected endpoint inventory in the classification presentation. The user must verify split boundaries align with the actual API surface before approving.
-
-Call `notify_user` presenting:
-- The classification type and reasoning (from Step 2)
-- The number of BE specs to be produced
-- The Referenced Material Inventory (from Step 5)
-- For multi-domain splits: the proposed split boundaries
-
-> **Do NOT proceed to `/write-be-spec-write` until the user confirms the classification is correct. For multi-domain splits, the user must confirm the split boundaries.**
-
-Once approved, run `/write-be-spec-write`.
+Use `notify_user` presenting: classification, expected spec count, Referenced Material Inventory, split boundaries (if applicable).
 
-> **Seed the spec file**: After classification is approved, read `.agent/skills/prd-templates/references/be-spec-template.md` for the **BE Spec Seed Stub** template. Create the spec file at `docs/plans/be/[NN-feature-name].md` using the stub, filling in the classification details and Referenced Material Inventory from above.
+**STOP** — do NOT proceed until the user confirms.
 
-For structural reference classification (0 BE specs): confirm no write shard is needed and propose moving to the next IA shard instead.
+After approval: read `.agent/skills/prd-templates/references/be-spec-template.md` → create spec file stub at `docs/plans/be/[NN-feature-name].md`.
 
+For structural reference (0 BE specs): confirm no write shard needed, propose next IA shard.

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

@@ -21,6 +21,10 @@ Write the BE spec(s) to `docs/plans/be/`, update indexes, run quality checks, an
 
 **Prerequisite**: Read the spec file at `docs/plans/be/[NN-feature-name].md`. The `## Classification` section and Referenced Material Inventory should be present from the classify shard. If the file does not exist or lacks a `## Classification` section, run `/write-be-spec-classify` first.
 
+**Re-run detection**: If the spec file already has content beyond the classification stub (filled endpoint sections, schema definitions, middleware rules):
+- Present current state and ask: "This BE spec has existing content. **Continue** (skip filled sections) or **redo specific sections** (which ones)?"
+- Wait for user response before proceeding.
+
 ---
 
 ## 7. Write the spec to `docs/plans/be/[NN-feature-name].md`
@@ -55,6 +59,45 @@ If a shard was classified as **structural reference** with 0 BE specs, add a row
 
 Read `.agent/skills/session-continuity/protocols/08-spec-pipeline-update.md` and follow the **Spec Pipeline Update Protocol** to mark this shard's BE column as complete in `.agent/progress/spec-pipeline.md`.
 
+## 9.5. Iterative deepening passes
+
+Re-read the complete BE spec draft and run the following passes. Each pass may produce new content that reveals further gaps — repeat until a pass produces no meaningful additions.
+
+### Pass 1: Cross-endpoint consistency
+
+Read all endpoints in this spec together as a set:
+- Do endpoints touching the same entity use consistent field names, casing, and types?
+- Do error codes follow the same pattern across all endpoints? (e.g., if `POST` returns `409` for duplicates, does `PUT` also?)
+- Do paginated endpoints use the same pagination shape (cursor vs offset, page size defaults)?
+- Do all endpoints that create/update the same entity validate the same required fields?
+
+Fix every inconsistency found.
+
+### Pass 2: Sequencing and concurrency scenarios
+
+For each write endpoint (POST, PUT, PATCH, DELETE):
+- What happens if a client calls this endpoint twice in rapid succession with the same payload?
+- What happens if two different users call this endpoint simultaneously for the same resource?
+- What happens if a client calls endpoint A then endpoint B before A's response returns?
+- What happens if the resource is deleted between when the client last read it and when they submit an update?
+
+Add any new error codes, race condition handling, or idempotency requirements discovered.
+
+### Pass 3: Failure cascade analysis
+
+For each endpoint that mutates data:
+- If this endpoint fails mid-transaction, what state is the database left in?
+- Which other endpoints return stale or inconsistent data after this failure?
+- Does the spec define rollback behavior or is it assumed?
+- If this endpoint creates a resource that other endpoints depend on, what happens to those endpoints if creation fails silently?
+
+Add any new transaction boundary requirements, rollback specifications, or consistency guarantees.
+
+**Pass loop guard**: Track total pass count.
+- Passes 1-3 → mandatory.
+- Pass 4-5 → optional, run if prior pass produced significant additions.
+- **After pass 5** → **STOP**: "5 deepening passes completed. Present remaining gaps to user: continue deepening or accept current spec depth?"
+
 ## 10. Cross-reference check
 
 Verify:
@@ -84,9 +127,12 @@ Read `.agent/skills/session-continuity/protocols/ambiguity-gates.md` and run:
 ## 13. Check for new dependencies
 
 If this BE spec introduces a technology not already in the project's tech stack:
-1. Identify the stack category (e.g., QUEUE, CACHE, SEARCH, STORAGE)
-2. Read `.agent/workflows/bootstrap-agents.md` and fire bootstrap with `PIPELINE_STAGE=write-be-spec` + the key-value pair
-3. Confirm matching skill installed
+1. Identify the technology (e.g., WebSocket, S3 storage, Stripe, Redis)
+2. Read `.agent/workflows/bootstrap-agents.md` and invoke `/bootstrap-agents PIPELINE_STAGE=write-be-spec` + the new dependency key
+3. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`). If bootstrap fails:
+   - **1st failure** → retry once
+   - **2nd failure** → **STOP**: tell the user which dependency failed and ask: "Install manually, skip, or abort?"
+4. Confirm the matching skill is installed before proceeding.
 
 ## 14. Request review and propose next steps
 

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

@@ -35,7 +35,7 @@ Conditionally look for:
 - TypeScript advanced patterns skill (for complex contract types)
 - Security hardening skill (for auth/RBAC specs)
 
-If a needed skill is missing, check if a matching entry exists in `.agent/skill-library/MANIFEST.md`. Read `.agent/workflows/bootstrap-agents.md` and execute its utility instructions immediately with the appropriate stack key to install it.
+If a needed skill is missing, check if a matching entry exists in `.agent/skill-library/MANIFEST.md`. Read `.agent/workflows/bootstrap-agents.md` and execute its utility instructions immediately with the appropriate stack key to install it. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`). Confirm the matching skill is installed before proceeding.
 
 ---
 

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

@@ -21,6 +21,10 @@ Write the FE spec to `docs/plans/fe/`, update indexes, run quality checks, and p
 
 **Prerequisite**: Read the spec file at `docs/plans/fe/[NN-feature-name].md`. The `## Classification` section, Referenced Material Inventory, and Design Requirements should be present from the classify shard. If the file lacks a `## Classification` section, run `/write-fe-spec-classify` first.
 
+**Re-run detection**: If the spec file already has content beyond the classification stub (filled component sections, state definitions, routing rules):
+- Present current state and ask: "This FE spec has existing content. **Continue** (skip filled sections) or **redo specific sections** (which ones)?"
+- Wait for user response before proceeding.
+
 ---
 
 ## 6. Write the spec to `docs/plans/fe/[NN-feature-name].md`
@@ -42,6 +46,55 @@ Change the spec's status from 🔲 to ✅ in `docs/plans/fe/index.md`.
 
 Read `.agent/skills/session-continuity/protocols/08-spec-pipeline-update.md` and follow the **Spec Pipeline Update Protocol** (skip for cross-cutting specs).
 
+## 8.5. Iterative deepening passes
+
+Re-read the complete FE spec draft and run the following passes. Each pass may produce new content — repeat until a pass produces no meaningful additions.
+
+### Pass 1: State synchronization
+
+For each component that consumes data from an API:
+- When the underlying data changes (via another component, another tab, or another user), how does this component learn about it? Polling? WebSocket? Manual refresh?
+- If component A mutates data that component B displays, is the update path defined? Does B re-fetch, or does A broadcast?
+- If multiple components share the same data, is the source of truth defined? (Global store? Prop drilling? Context?)
+- After a mutation fails, does the component roll back optimistic updates? Is the rollback state defined?
+
+Add any new state management rules, re-fetch triggers, or optimistic update rollback specifications.
+
+### Pass 2: Degraded network behavior
+
+For each data-fetching view:
+- What does the component show when the API returns in 3+ seconds? (Loading state is specced — but is the threshold defined?)
+- What does the component show when the API returns a network error vs a 500 vs a 4xx?
+- What happens to in-progress form submissions if the network drops mid-request?
+- Are there any retry behaviors? If so, how many retries, at what interval, with what user feedback?
+
+Add any new loading thresholds, retry specifications, or network error differentiation.
+
+### Pass 3: User flow sequencing
+
+Trace each multi-step user flow across pages/views:
+- Can a user navigate backward mid-flow (browser back button, breadcrumbs)? What state is preserved?
+- Can a user open the same flow in two browser tabs? What happens on submission in both?
+- Can a user bookmark or deep-link to a mid-flow page? What happens on direct navigation?
+- If the user leaves a form and returns, is the data persisted? In local storage? Session storage? Not at all?
+
+Add any new navigation guard rules, state persistence decisions, or deep-link handling.
+
+### Pass 4: Responsive interaction gaps
+
+For each component with responsive breakpoints defined:
+- At mobile breakpoint, do hover-dependent interactions have touch equivalents?
+- At tablet breakpoint, do side-by-side layouts still allow sufficient touch target sizing?
+- Do modal/dialog components have appropriate mobile behavior (full-screen vs overlay)?
+- Are swipe gestures defined for mobile where drag-and-drop exists on desktop?
+
+Add any new touch interaction specs or mobile-specific behavior.
+
+**Pass loop guard**: Track total pass count.
+- Passes 1-4 → mandatory.
+- Pass 5 → optional, run if prior pass produced significant additions.
+- **After pass 5** → **STOP**: "5 deepening passes completed. Present remaining gaps to user: continue deepening or accept current spec depth?"
+
 ## 9. Cross-reference check
 
 Verify:
@@ -71,9 +124,9 @@ Read `.agent/skills/session-continuity/protocols/ambiguity-gates.md` and run:
 ## 12. Check for new dependencies
 
 If this FE spec introduces a new technology:
-1. Identify the stack category (e.g., CHARTS, ANIMATION)
-2. Read `.agent/workflows/bootstrap-agents.md` and fire bootstrap with `PIPELINE_STAGE=write-fe-spec` + the key-value pair
-3. Confirm matching skill installed
+1. Identify the technology (e.g., chart library, map SDK, i18n framework)
+2. Read `.agent/workflows/bootstrap-agents.md` and invoke `/bootstrap-agents PIPELINE_STAGE=write-fe-spec` + the new dependency key
+3. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`). Confirm the matching skill is installed before proceeding.
 
 ## 13. Request review and propose next steps
 
@@ -100,3 +153,9 @@ Use `notify_user` presenting:
 2. Verify each is reachable from at least one navigation element
 3. Verify navigation structure itself is specced
 4. Flag orphan routes (specced but unreachable) — these block `/plan-phase`
+
+**Orphan route resolution**: If orphan routes are found:
+- List each orphan route with its spec source
+- For each, ask: "Add to navigation (where?), remove from spec, or defer to a later phase?"
+- Update the relevant FE spec immediately based on user decision
+- Re-run the completeness check until 0 orphans remain

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

@@ -32,7 +32,7 @@ Check installed skills for frontend-relevant coverage:
 - Web performance optimization skill
 - i18n / localization skill (if needed)
 
-If a needed skill is missing, check if a matching entry exists in `.agent/skill-library/MANIFEST.md`. Read `.agent/workflows/bootstrap-agents.md` and execute its utility instructions immediately with the appropriate stack key to install it.
+If a needed skill is missing, check if a matching entry exists in `.agent/skill-library/MANIFEST.md`. Read `.agent/workflows/bootstrap-agents.md` and execute its utility instructions immediately with the appropriate stack key to install it. **HARD GATE**: Follow the bootstrap verification protocol (`.agent/skills/prd-templates/references/bootstrap-verification-protocol.md`). Confirm the matching skill is installed before proceeding.
 
 ---