cfsa-antigravity 2.2.1 → 2.3.0

package/README.md

@@ -22,6 +22,14 @@ This installs the `.agent/` folder, `docs/` structure, and agent config files in
 | `cfsa-antigravity init --dry-run` | Preview what would be installed |
 | `cfsa-antigravity init --path ./dir` | Install into specific directory |
 
+### ⚠️ Important Note on `.gitignore`
+If you are using AI-powered editors like **Cursor** or **Windsurf**, adding the `.agent/` folder to your `.gitignore` may prevent the IDE from indexing the workflows. This results in slash commands (like `/plan`, `/debug`) not appearing in the chat suggestion dropdown.
+
+**Recommended Solution:**
+To keep the `.agent/` folder local (not tracked by Git) while maintaining AI functionality:
+1. Ensure `.agent/` is **NOT** in your project's `.gitignore`.
+2. Instead, add it to your local exclude file: `.git/info/exclude`
+   
 ## Get Started
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
   "scripts": {
     "changeset": "changeset",

package/template/.agent/skills/idea-extraction/SKILL.md

@@ -191,6 +191,11 @@ The key question: **"Does this thing have its own internal features that interac
 | Creating a domain for every feature mentioned | Grouping related features under their parent domain/sub-domain |
 | Pre-creating 4 levels of empty folders | Creating depth reactively as complexity is discovered |
 | Putting a shared domain in `shared/` when hub-and-spoke is active | Putting it inside the hub surface, with CX references from spokes |
+| Using source document headings as the domain map | Extracting concepts from the content and classifying each through the gate |
+| Creating a domain folder for every heading in the source | Only creating domain folders for concepts that pass the gate as true domains |
+| Collapsing a rich multi-system area into a single domain | Recognizing 2+ interacting capabilities = sub-domain or promoted domain |
+| Creating "Data Architecture" or "Tech Stack" as product domains | Noting architectural concerns for `/create-prd` — they are not product domains |
+| Creating folders before presenting the classification to the user | Always presenting the classification table and getting user confirmation first |
 
 ---
 
@@ -268,16 +273,68 @@ Before starting, classify what the user has provided and select the right mode.
 
 **The job:** Don't lose information. Organize, validate, and fill gaps.
 
-**Process:**
+> **CRITICAL**: Extraction mode uses the SAME interview question framework as Interview mode.
+> The document is the interviewee. The only difference is that the document provides answers
+> silently (the agent reads them) instead of interactively (the agent asks the user). Every
+> answer extracted from the document must cite where in the document it came from. Every
+> question the document doesn't answer becomes a real interview question for the user in Phase 2.
+>
+> **The source document's organization is a hint, not the truth.** Headings, section numbers,
+> and document structure tell you where to LOOK for concepts. They do NOT tell you what those
+> concepts ARE (domain, sub-domain, feature, cross-cut, or not-a-product-domain). The Node
+> Classification Gate determines what each concept is. NEVER mirror source headings as domains.
+
+**Process — Phase 1: Interview the Document** (silent — no user interaction)
+
 1. Read/ingest every document provided
 2. **Run Structural Classification** — determine project shape before creating any files
-3. Identify natural domain boundaries in the content
-4. Create fractal folder structure — run the **Node Classification Gate** for each domain
-5. Seed each domain folder (index + CX + feature files) with content from the source
-6. Present the organized inventory: "Here's what I extracted, organized by domain"
-7. Identify gaps — domains/sub-topics not covered
-8. For each gap, switch to Interview Mode
-9. Run Deep Think: "Based on your content, I would also expect [X] and [Y]. Are those relevant?"
+3. **BLOCKING GATE — Extract concepts, not headings.** Read the entire document and identify every concept — a capability, system, feature, workflow, cross-cutting concern, or architectural note. For each concept, record:
+   - Concept name (what it is, in your words — not the source heading)
+   - Source location (line numbers or section reference — this is the citation)
+   - What the document says about it (summary of the content)
+   - How many distinct interacting capabilities it contains (the sub-domain test)
+   - Whether it is surface-exclusive, shared, or cross-cutting
+   Do NOT use source document headings as concept names unless they happen to be accurate after classification. The concept name must reflect what the thing actually IS after gate analysis.
+4. **BLOCKING GATE — Classify every concept.** Run the Node Classification Gate on EACH extracted concept individually. For each concept, answer the gate questions explicitly:
+   - "Does it belong to an EXISTING domain?" → if YES, it's a sub-domain or feature of that domain
+   - "Does it have 2+ distinct capabilities that interact with each other?" → if YES, it's a sub-domain (folder); if NO, it's a feature (file)
+   - "Is it surface-exclusive?" → determines placement
+   - "Is it an architectural concern, not a product domain?" → note for `/create-prd`, do NOT create a domain
+   - "Is it a cross-cutting concern?" → log in CX files, do NOT create a domain
+   Produce a **classification table**:
+
+   | Concept | Source Location | Gate Result | Reasoning |
+   |---------|----------------|-------------|----------|
+   | Inventory System | lines 982–1017 | Sub-domain of Shop Software | 4+ interacting capabilities (purgatory model, alerts, visibility, pre-auth billing) |
+   | In-Platform Messaging | lines 759–788 | Feature of Consumer Platform | Single capability with role-based routing, no internal sub-features |
+   | Data Architecture | lines 1261–1282 | NOT a product domain | Architectural concern — database selection, sync strategy → note for /create-prd |
+   | Analytics & Insights | lines 730–758 | Cross-cutting concern | Three tiers serving all domains, no exclusive features of its own |
+
+5. **BLOCKING GATE — Build proposed domain map.** From the classification table, group concepts into a proposed domain hierarchy:
+   - Only concepts classified as **domain** become domain folders
+   - Concepts classified as **sub-domain** nest inside their parent domain
+   - Concepts classified as **feature** become leaf files inside their parent
+   - Concepts classified as **cross-cut** go in the appropriate CX files
+   - Concepts classified as **not-a-product-domain** are noted in `meta/constraints.md` for `/create-prd`
+6. **Identify gaps** — interview questions the document doesn't answer. These become Phase 2 interview questions.
+
+**Process — Phase 2: Present and Interview the User**
+
+7. **BLOCKING GATE — Present classification and get confirmation.** Show the user:
+   - The classification table (every concept, its source, its gate result, and reasoning)
+   - The proposed domain map (the folder hierarchy that would be created)
+   - The gap list (questions the document didn't answer)
+   Ask: "Here's how I classified your content. Does this look right?" **Wait for user confirmation or corrections. Do NOT create any folders until the user confirms.**
+8. **Apply corrections** — if the user reclassifies any concept, update the table and domain map
+9. **Create fractal folder structure** from the CONFIRMED domain map and seed with content from the source document
+10. **Interview the user for gaps** — switch to Interview Mode for every gap identified in step 6. Use the same Deep Think questions, same exhaustion protocol, targeted at what the document didn't cover.
+11. Run Deep Think: "Based on your content, I would also expect [X] and [Y]. Are those relevant?"
+
+**Enforcement rules:**
+- Do NOT create any domain folders before Step 9 (after user confirmation in Step 7)
+- Do NOT mirror source document headings as domains — they are hints for finding concepts, not the classification itself
+- Every concept in the classification table MUST show which gate questions were asked and how they were answered
+- If a concept's classification is uncertain, present it to the user in Phase 2 with your best guess and reasoning — do not silently guess
 
 ### Expansion Mode — Thin Input
 

package/template/.agent/workflows/ideate-discover.md

@@ -19,7 +19,7 @@ pipeline:
 
 Explore domains through recursive breadth-before-depth with the Deep Think protocol. Write to the fractal folder structure — every node gets an index, CX file, and children.
 
-**Prerequisite**: If invoked standalone, verify `docs/plans/ideation/ideation-index.md` exists with the fractal folder structure seeded. If not, prompt the user to run `/ideate-extract` first.
+**Prerequisite**: If invoked standalone, verify `docs/plans/ideation/ideation-index.md` exists with the fractal folder structure seeded. If this file does not exist → **STOP**: "Extraction output missing — the fractal folder structure has not been seeded. Run `/ideate-extract` first before proceeding to discovery." Do not proceed without this output.
 
 ---
 

package/template/.agent/workflows/ideate-extract.md

@@ -38,9 +38,9 @@ Classify what the user has provided. This determines which mode the `idea-extrac
 **For rich inputs (Extraction mode):**
 1. Read/ingest all provided documents
 2. **Proportionality check**: If source >50KB, total ideation output must be ≥30% of source line count
-3. Identify natural domain boundaries in the content
-4. Present organized inventory for user confirmation
-5. Identify gaps — note for Interview Mode in `/ideate-discover`
+3. **Interview the document**: Run the interview question framework from `idea-extraction/SKILL.md` Extraction Mode Phase 1. Extract concepts (not headings) with citations. Classify every concept through the Node Classification Gate. Build the classification table and proposed domain map.
+4. **BLOCKING GATE — Do NOT proceed to Step 1.5 until the classification table is built.** The classification table is a required artifact. No domain folders can be created without it.
+5. Identify gaps — questions the document doesn't answer → these become Phase 2 user interview questions
 6. Use idea-extraction skill to refine, not re-derive
 
 **For thin inputs (Expansion mode):**
@@ -90,6 +90,29 @@ Before seeding, check whether `docs/plans/ideation/ideation-index.md` already ex
   - **Start fresh** → archive to `docs/plans/ideation-archive-[timestamp]/`, then seed
 - If it **does not exist**: proceed with seeding.
 
+## 1.4.5. Classification Confirmation (Extraction mode only)
+
+> **BLOCKING GATE**: Before creating ANY domain folder, you MUST complete this step.
+> This step exists because the test revealed that the Node Classification Gate was being
+> bypassed — the agent mirrored source document headings as domains instead of classifying
+> each concept. This gate makes classification a hard prerequisite for folder creation.
+
+1. **Verify the classification table exists.** Step 1 item 3 must have produced a completed classification table. If it doesn't exist, STOP — go back and run Extraction Mode Phase 1 from `idea-extraction/SKILL.md`.
+2. **Present the classification table and proposed domain map to the user.** Show:
+   - Every concept with its source location, gate result, and reasoning
+   - The proposed domain hierarchy (what folders would be created and where)
+   - The gap list (questions the document didn't answer)
+3. **Ask**: "Here's how I classified your content. Does this look right?"
+4. **Wait for user confirmation or corrections.** Do NOT proceed until the user responds.
+5. **Apply any corrections** the user provides — update the classification table and domain map.
+
+**The classification table must show for each concept:**
+- Concept name and source location (line numbers or section reference)
+- Gate result: domain / sub-domain / feature / cross-cut / not-a-product-domain
+- Gate reasoning: which gate questions were asked and how they were answered
+
+**Do NOT mirror source document headings as domains.** Source headings are hints for finding concepts. The Node Classification Gate determines what each concept is.
+
 ## 1.5. Seed fractal `ideation/` folder
 
 Read these templates:
@@ -101,13 +124,17 @@ Read these templates:
 
 Read `.agent/skills/technical-writer/SKILL.md` and follow its methodology.
 
-**Create the base structure** (all project shapes):
+**ADDITIVE ONLY** — The `docs/plans/ideation/` directory already exists in the kit with `.gitkeep` and `README.md`. You are ADDING files into this existing directory. Do NOT delete, overwrite, or replace the directory itself. Do NOT remove any existing files. Create new files alongside what already exists.
+
+**Create the base structure** (all project shapes). This is what the folder should contain AFTER seeding — kit-shipped files plus new pipeline files:
 
 ```
 docs/plans/ideation/
-├── ideation-index.md       ← super-index (from ideation-index-template)
-├── ideation-cx.md          ← global cross-cuts (from ideation-crosscut-template)
-└── meta/
+├── .gitkeep                ← KIT-SHIPPED — do not touch
+├── README.md               ← KIT-SHIPPED — do not touch
+├── ideation-index.md       ← NEW: super-index (from ideation-index-template)
+├── ideation-cx.md          ← NEW: global cross-cuts (from ideation-crosscut-template)
+└── meta/                   ← NEW: created by this step
     ├── problem-statement.md
     ├── personas.md
     ├── competitive-landscape.md
@@ -116,20 +143,29 @@ docs/plans/ideation/
 
 **For multi-product projects**, additionally create `surfaces/` with sub-folders per surface.
 
-**Seed domains using the Node Classification Gate** (from `idea-extraction/SKILL.md`):
+**Post-seeding verification gate**: After creating all files, verify that `docs/plans/ideation/.gitkeep` and `docs/plans/ideation/README.md` still exist. If EITHER file is missing → **STOP**: "Kit-shipped files were destroyed during seeding. Restore `.gitkeep` and/or `README.md` to `docs/plans/ideation/` before continuing."
+
+**Seed domains from CONFIRMED classification table** (not from source headings):
+
+> **CRITICAL**: The domain list comes from the classification table confirmed in Step 1.4.5.
+> Do NOT re-derive domains from the source document. Do NOT fall back to source headings.
+> If Step 1.4.5 was not completed, STOP — you cannot seed without a confirmed classification.
 
-For each domain identified in Step 1:
-1. Run the Classification Gate — determine placement:
+For each concept classified as **domain** in the confirmed table:
+1. Determine placement from the structural classification:
    - Single-surface → create `docs/plans/ideation/{NN}-{slug}/`
    - Hub-and-spoke → surface-exclusive in `surfaces/{surface}/{NN}-{slug}/`, shared in hub surface
    - Peer → surface-exclusive in `surfaces/{surface}/{NN}-{slug}/`, shared in `shared/{NN}-{slug}/`
 2. Create the domain folder with: `{slug}-index.md` + `{slug}-cx.md`
-3. For rich document inputs, parse sub-areas into feature files within each domain folder
-4. Update `ideation-index.md` structure map with paths
+3. For concepts classified as **sub-domain**, create sub-domain folders nested inside their parent domain
+4. For concepts classified as **feature**, create feature files inside their parent domain or sub-domain
+5. For concepts classified as **cross-cut**, add entries to the appropriate CX files (domain-level or global)
+6. For concepts classified as **not-a-product-domain**, add notes to `meta/constraints.md` for `/create-prd`
+7. Update `ideation-index.md` structure map with paths
 
-**Seeding behavior by input type:**
+**Seeding content by input type:**
 
-- **Rich document**: Parse by domain → create fractal folders + feature files → seed with content. Run fidelity check: every major source section maps to a domain folder. Add `> Source: path/to/original.md` to index.
+- **Rich document**: Seed each domain/sub-domain/feature with content from the source document using the source citations in the classification table. Run fidelity check: every major concept in the source must map to SOMETHING in the output (domain, sub-domain, feature, CX entry, or `/create-prd` note). Add `> Source: path/to/original.md` to index.
 - **Chat transcript**: Noise filter → extract signal → seed domain folders with structured output.
 - **Thin document**: Create domain folders with depth markers on feature files.
 - **Verbal / one-liner**: Create domain folders with scaffolding. Feature files are `[SURFACE]`.

package/template/.agent/workflows/ideate.md

@@ -42,6 +42,23 @@ Transform a raw idea into comprehensive, structured ideation output through exha
 
 ---
 
+## 0. Prerequisite gate
+
+Check whether `docs/plans/ideation/ideation-index.md` already exists.
+
+- **If it does NOT exist** → This is a fresh ideation. Proceed to Shard 1.
+- **If it DOES exist** → **STOP**. Present to the user:
+
+> ⚠️ **Ideation output already exists** at `docs/plans/ideation/ideation-index.md`.
+>
+> Running `/ideate` again will overwrite the existing ideation output.
+>
+> **Overwrite** (start fresh) or **Abort**?
+
+**Do not proceed** to any shard until the user explicitly confirms "Overwrite." If the user says "Abort," end the workflow immediately.
+
+---
+
 ## Shard Overview
 
 | # | Shard | What It Does |

package/template/.agent/workflows/implement-slice.md

@@ -45,7 +45,7 @@ Executes the TDD cycle (RED: write failing tests → GREEN: implement → REFACT
 
 ## Quality Gate
 
-You may not call `notify_user` until:
+**BLOCKING GATE** — You may NOT call `notify_user` until ALL items pass:
 - [ ] All tests pass (Test Cmd from surface stack map)
 - [ ] Full validation passes (Validation Cmd from surface stack map)
 - [ ] All 4 progress tracking files updated (slice, phase, index, memory)

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

@@ -21,6 +21,13 @@ Break a phase into TDD vertical slices, each spanning all four surfaces (contrac
 **Input**: Approved specs (IA + BE + FE) and the phasing section from architecture design
 **Output**: Phase plan with ordered slices and acceptance criteria
 
+**Prerequisite**: Approved specs across all three layers must exist. Verify:
+1. `docs/plans/ia/index.md` exists and all shards show ✅
+2. `docs/plans/be/index.md` exists and all specs show ✅
+3. `docs/plans/fe/index.md` exists and all specs show ✅
+
+If any index is missing or contains incomplete specs → **STOP**: "Spec layers are not complete. Run `/write-architecture-spec`, `/write-be-spec`, and/or `/write-fe-spec` to complete all specs before planning a phase."
+
 ---
 
 ## Shard 1: Pre-flight — `/plan-phase-preflight`

package/template/.agent/workflows/sync-kit.md

@@ -130,10 +130,7 @@ If `docs/plans/ideation/` doesn't exist, create the scaffold:
 ```
 docs/plans/ideation/
 ├── .gitkeep
-├── README.md          ← copy from upstream
-├── domains/.gitkeep
-├── meta/.gitkeep
-└── cross-cuts/.gitkeep
+└── README.md          ← copy from upstream
 ```
 
 ### 4.5c. Flag for re-ideation

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

@@ -45,7 +45,7 @@ Runs production readiness checks: API documentation sync, accessibility audit, p
 
 ## Quality Gate
 
-You may not call `notify_user` until:
+**BLOCKING GATE** — You may NOT call `notify_user` until ALL items pass:
 - [ ] All code quality checks pass (Shard 1)
 - [ ] All production readiness checks pass (Shard 2)
 - [ ] Validation report written to `docs/audits/phase-N-validation.md`

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

@@ -51,7 +51,7 @@ Runs multiple deepening passes (cross-section consistency, "what if" scenarios,
 
 ## Quality Gate
 
-Before presenting to the user, verify:
+**BLOCKING GATE** — Do NOT call `notify_user` or proceed to the next step until ALL items pass:
 
 Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review discipline.
 

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

@@ -35,7 +35,7 @@ Write the BE spec(s) to `docs/plans/be/`, update indexes, run quality checks, an
 
 **Rule**: For every unspecced expected endpoint, either add it to the spec immediately or add an explicit `[Deferred to Phase N — reason]` note in the Notes column. An empty Notes column for an unspecced endpoint is a spec failure.
 
-**Gate**: Do not write the spec sections until every expected endpoint is either specced or explicitly deferred. This reconciliation table becomes the first section of the spec file after `## Classification`.
+**BLOCKING GATE**: Do NOT write the spec sections until every expected endpoint is either specced or explicitly deferred. This reconciliation table becomes the first section of the spec file after `## Classification`.
 
 Read .agent/skills/technical-writer/SKILL.md and follow its methodology.
 Read .agent/skills/spec-writing/SKILL.md and follow its completeness testing and cross-reference checking methodology.

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

@@ -62,7 +62,7 @@ Writes the BE spec(s) to `docs/plans/be/`, updates the BE index, runs cross-refe
 
 ## Quality Gate
 
-Before presenting to the user, verify:
+**BLOCKING GATE** — Do NOT call `notify_user` or proceed to the next step until ALL items pass:
 
 Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review discipline to each checklist item.
 

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

@@ -59,7 +59,7 @@ Writes the FE spec to `docs/plans/fe/`, updates the FE index, runs cross-referen
 
 ## Quality Gate
 
-Before presenting to the user, verify:
+**BLOCKING GATE** — Do NOT call `notify_user` or proceed to the next step until ALL items pass:
 
 Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review discipline to each checklist item.