cfsa-antigravity 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,57 @@
+# CFSA Antigravity
+
+> Constraint-First Specification Architecture — production-grade from line one
+
+A pipeline that turns a raw idea into exhaustively specified, test-driven, production-quality code through progressive gates. Stack-agnostic. Agent-agnostic. Cross-platform. Every line of code is production-grade from the moment it's written.
+
+## Quick Install
+
+```bash
+npx cfsa-antigravity init
+```
+
+Or install globally:
+
+```bash
+npm install -g cfsa-antigravity
+cfsa-antigravity init
+```
+
+This installs the `.agent/` folder, `docs/` structure, and agent config files into your project.
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `cfsa-antigravity init` | Install the pipeline into your project |
+| `cfsa-antigravity status` | Check installation + unfilled placeholders |
+| `cfsa-antigravity init --force` | Overwrite existing installation |
+| `cfsa-antigravity init --dry-run` | Preview what would be installed |
+| `cfsa-antigravity init --path ./dir` | Install into specific directory |
+
+## Get Started
+
+```
+/ideate
+```
+
+The pipeline tells you what to run next at every step. You never have to guess.
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [Pipeline Guide](docs/README.md) | Full walkthrough — every command, every stage |
+| [Kit Architecture](docs/kit-architecture.md) | How the kit's internals work |
+
+## Five Principles
+
+1. **Constraints before decisions** — map what's decided before presenting options
+2. **Exhaustive iteration over shallow speed** — no ambiguity moves forward
+3. **Work shifted left** — design decisions made in spec, not in code
+4. **Progressive decision locking** — each stage locks decisions for downstream
+5. **TDD as the implementation contract** — Red → Green → Refactor, every slice
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cfsa-antigravity",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
     "bin": {
         "cfsa-antigravity": "./bin/cli.mjs"

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

@@ -9,7 +9,7 @@
 
 # Kit Sync State
 
-upstream: https://github.com/RepairYourTech/Anti-MVP-Vibe-Pipeline
+upstream: https://github.com/RepairYourTech/cfsa-antigravity
 last_synced_commit: FIRST_SYNC_PENDING
 last_synced_at: FIRST_SYNC_PENDING
 kit_version: main

package/template/.agent/skills/prd-templates/SKILL.md

@@ -19,7 +19,7 @@ Canonical markdown templates for all pipeline output documents. Workflows refere
 
 ## Conventions
 
-**Dated File Convention**: Compiled artifacts (e.g., `architecture-design.md`, `vision.md`, `data-placement-strategy.md`, `ENGINEERING-STANDARDS.md`, audit reports) are always prefixed with `YYYY-MM-DD-`. Any workflow reading these files must use a glob pattern (e.g., `docs/plans/*-architecture-design.md`). See `KIT-ARCHITECTURE.md` Section 2 — Dated File Convention for the full rule and table.
+**Dated File Convention**: Compiled artifacts (e.g., `architecture-design.md`, `vision.md`, `data-placement-strategy.md`, `ENGINEERING-STANDARDS.md`, audit reports) are always prefixed with `YYYY-MM-DD-`. Any workflow reading these files must use a glob pattern (e.g., `docs/plans/*-architecture-design.md`). See `docs/kit-architecture.md` Section 2 — Dated File Convention for the full rule and table.
 
 ## How to Use
 

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

@@ -4,11 +4,11 @@ description: Sync improvements from the upstream starter kit into this project's
 
 # Sync Kit
 
-Pull improvements from the upstream [Anti-MVP-Vibe-Pipeline](https://github.com/RepairYourTech/Anti-MVP-Vibe-Pipeline) kit into this project. The sync covers the **entire upstream repo** — `.agent/` directory, root-level files (`AGENTS.md`, `GEMINI.md`, `KIT-*.md`), and `docs/` scaffolding.
+Pull improvements from the upstream [cfsa-antigravity](https://github.com/RepairYourTech/cfsa-antigravity) kit into this project. The sync covers the **entire upstream repo** — `.agent/` directory, root-level files (`AGENTS.md`, `GEMINI.md`), and `docs/` (including `kit-architecture.md` and pipeline guide).
 
 **The problem:** The kit was born from this project, but has since evolved past it. The kit uses `{{PLACEHOLDER}}` markers; this project has real values. A blind copy would destroy project-specific content. This workflow does a semantic merge — apply the kit's *intent* while preserving project values.
 
-**Input:** Upstream kit repo (default: `RepairYourTech/Anti-MVP-Vibe-Pipeline`, branch `main`)
+**Input:** Upstream kit repo (default: `RepairYourTech/cfsa-antigravity`, branch `main`)
 **Output:** Updated project with kit improvements merged, sync state recorded
 
 ---
@@ -38,14 +38,14 @@ Compare the **entire upstream repo** against the project. Scan at minimum:
 
 | Upstream Path | What to Compare |
 |--------------|-----------------|
-| Root files | `AGENTS.md`, `GEMINI.md`, `KIT-ARCHITECTURE.md`, `KIT-README.md` |
+| Root files | `AGENTS.md`, `GEMINI.md` |
 | `.agent/instructions/` | All 5 markdown files |
 | `.agent/rules/` | All 9 markdown files |
 | `.agent/workflows/` | All workflow files |
 | `.agent/skills/` | All skill directories (SKILL.md + sub-files) |
 | `.agent/skill-library/` | MANIFEST.md, README.md, subdirectories |
 | `.agent/progress/` | Directory structure |
-| `docs/` | README.md, audits/, plans/ scaffolding |
+| `docs/` | README.md, kit-architecture.md, audits/, plans/ scaffolding |
 
 Compare using SHA hashes or byte-level diff. Classify each file per Step 2.
 
@@ -189,7 +189,7 @@ Write or update `.agent/kit-sync.md`:
 ```markdown
 # Kit Sync State
 
-upstream: https://github.com/RepairYourTech/Anti-MVP-Vibe-Pipeline
+upstream: https://github.com/RepairYourTech/cfsa-antigravity
 last_synced_commit: <current HEAD commit hash>
 last_synced_at: <ISO 8601 timestamp>
 kit_version: main

package/template/AGENTS.md

@@ -1,4 +1,4 @@
-# Vibe to Production — the anti-MVP spec pipeline
+# CFSA Antigravity — Constraint-First Specification Architecture
 
 This is a **Constraint-First Specification Architecture (CFSA)** pipeline. It turns a raw idea into exhaustively specified, test-driven, production-quality code through a series of progressive gates. Stack-agnostic. Agent-agnostic. Cross-platform. Every line of code, every spec, every test is production-grade from the moment it's written. Phases control scope, never quality. There is no "fix it later."
 
@@ -29,7 +29,7 @@ Decisions in this pipeline are **progressively locked**. Each pipeline stage bui
 
 Once a stage is locked, downstream stages may not contradict it. To change a locked decision, re-run the originating stage and cascade changes downstream.
 
-<!-- Pipeline table maintained by: (1) bootstrap-agents-fill.md Step 4 for project-config sections, (2) kit maintainer checklist for workflow rows — see KIT-ARCHITECTURE.md Kit Maintenance Checklist -->
+<!-- Pipeline table maintained by: (1) bootstrap-agents-fill.md Step 4 for project-config sections, (2) kit maintainer checklist for workflow rows — see docs/kit-architecture.md Kit Maintenance Checklist -->
 ### Pipeline Workflow Table
 
 | # | Command | Input | Output | Stage |

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-# Vibe to Production — the anti-MVP spec pipeline
+# CFSA Antigravity — Constraint-First Specification Architecture
 
 This is a **Constraint-First Specification Architecture (CFSA)** pipeline. It turns a raw idea into exhaustively specified, test-driven, production-quality code through a series of progressive gates. Stack-agnostic. Agent-agnostic. Cross-platform. Every line of code, every spec, every test is production-grade from the moment it's written. Phases control scope, never quality. There is no "fix it later."
 
@@ -29,7 +29,7 @@ Decisions in this pipeline are **progressively locked**. Each pipeline stage bui
 
 Once a stage is locked, downstream stages may not contradict it. To change a locked decision, re-run the originating stage and cascade changes downstream.
 
-<!-- Pipeline table maintained by: (1) bootstrap-agents-fill.md Step 4 for project-config sections, (2) kit maintainer checklist for workflow rows — see KIT-ARCHITECTURE.md Kit Maintenance Checklist -->
+<!-- Pipeline table maintained by: (1) bootstrap-agents-fill.md Step 4 for project-config sections, (2) kit maintainer checklist for workflow rows — see docs/kit-architecture.md Kit Maintenance Checklist -->
 ### Pipeline Workflow Table
 
 | # | Command | Input | Output | Stage |

package/template/docs/README.md

@@ -1,5 +1,5 @@
-# Vibe to Production
-### the anti-MVP spec pipeline
+# CFSA Antigravity
+### Constraint-First Specification Architecture — production-grade from line one
 
 > Designed for Antigravity — adaptable to other agents
 
@@ -140,29 +140,31 @@ The pipeline is a linear sequence of commands. Each step tells you what to run n
 
 ### Prerequisites
 
+- Node.js 18+ (for the installer)
 - Antigravity IDE (or any compatible agent that can read files, write files, and execute commands)
 
 ### Installation
 
-Copy the `.agent/` and `docs/` directories into your target project:
-
-**Windows:**
-```cmd
-xcopy /E /I spec-pipeline-starter\.agent your-project\.agent
-xcopy /E /I spec-pipeline-starter\docs your-project\docs
+**Recommended:**
+```bash
+npx cfsa-antigravity init
 ```
 
-**macOS / Linux:**
+**Manual (without npm):**
 ```bash
-cp -r spec-pipeline-starter/.agent /path/to/your-project/
-cp -r spec-pipeline-starter/docs /path/to/your-project/
+git clone https://github.com/RepairYourTech/cfsa-antigravity.git
+cp -r cfsa-antigravity/.agent /path/to/your-project/
+cp -r cfsa-antigravity/docs /path/to/your-project/
+cp cfsa-antigravity/GEMINI.md /path/to/your-project/
+cp cfsa-antigravity/AGENTS.md /path/to/your-project/
 ```
 
 ### Agent Setup
 
 | Agent | What to Do |
 |-------|------------|
-| **Antigravity** | Copy `GEMINI.md` to your project root — it's the system prompt |
+| **Antigravity** | Both `AGENTS.md` and `GEMINI.md` are present — bootstrap fills both during `/create-prd`. |
+| **Gemini CLI** | `GEMINI.md` is your agent config. Bootstrap fills it during `/create-prd`. |
 | **Claude Code** | Copy rules/instructions into `.claude/` using Claude's format |
 | **Cursor** | Reference from `.cursorrules` or your Cursor config |
 | **Windsurf** | Reference from `.windsurfrules` or equivalent |
@@ -185,3 +187,23 @@ The pipeline tells you what to run next at every step. You never have to guess.
 **Skill library** lives in `.agent/skill-library/`. These are stack-specific and surface-specific skills that get provisioned by bootstrap as tech decisions are confirmed during `/create-prd`. They're never loaded directly — bootstrap copies the relevant ones into `.agent/skills/` and fills any placeholders with your project's confirmed values.
 
 Bootstrap fires once per confirmed decision — it fills only what was just decided and leaves everything else untouched.
+
+### Bootstrap & Template System
+
+Instruction files in `.agent/instructions/` are **templates**, not static files — they ship with `{{PLACEHOLDER}}` markers that bootstrap fills as tech decisions are confirmed during `/create-prd`.
+
+| File | Filled by | When |
+|------|-----------|------|
+| `AGENTS.md` + `GEMINI.md` | `bootstrap-agents-fill` | After each confirmed tech decision |
+| `commands.md` | `bootstrap-agents-fill` | After dev tooling decisions |
+| `workflow.md` | `bootstrap-agents-fill` | After dev tooling decisions |
+| `tech-stack.md` | `bootstrap-agents-fill` + `bootstrap-agents-provision` | After each decision + after skill provisioning |
+| `structure.md` | `bootstrap-agents-fill` | After Step 9.5 of `/create-prd-compile` |
+| `patterns.md` | `bootstrap-agents-provision` | After a frontend-capable framework skill is provisioned (`FRONTEND_FRAMEWORK`, `MOBILE_FRAMEWORK`, etc.) |
+
+**The placeholder verification gate**: Before any implementation begins, `/implement-slice` scans all seven instruction files for unfilled `{{` patterns. If any are found, it stops and tells you exactly which file, which placeholder, and which command to run. This gate prevents implementation from proceeding with broken agent context.
+
+**Diagnosing unfilled placeholders**: For existing projects with unfilled placeholders, run:
+- `/create-prd-compile` — fills `structure.md` (Step 9.5 generates and locks the directory structure)
+- `/bootstrap-agents-provision` — fills `patterns.md` (composes framework patterns from the provisioned frontend-capable skill — `FRONTEND_FRAMEWORK`, `MOBILE_FRAMEWORK`, etc.)
+- `/bootstrap-agents-fill` with confirmed stack values — fills `AGENTS.md` and `GEMINI.md`

package/template/docs/kit-architecture.md

@@ -0,0 +1,223 @@
+# CFSA Antigravity - Architecture
+
+**Purpose:** Provide a high-level map of the agentic machinery that powers CFSA Antigravity.
+
+This document serves as a guide to understanding how the various components within the `.agent/` directory interlock to provide a robust, agent-agnostic development environment.
+
+---
+
+## 1. Code Organization
+
+The intelligence of the kit lives entirely within the `.agent/` directory.
+
+```text
+.agent/
+├── instructions/    # Core directives (the "brainstem")
+├── progress/        # State and memory (the "hippocampus")
+├── rules/           # Non-negotiable constraints (the "laws")
+├── skills/          # Reusable capabilities (the "tools")
+└── workflows/       # Structured processes (the "playbooks")
+```
+
+### Core Components
+
+*   **Instructions:** (`workflow.md`, `tech-stack.md`, `structure.md`, `patterns.md`, etc.) Baseline knowledge the agent needs to operate in the specific environment. These files ship as templates with `{{PLACEHOLDER}}` markers — they are not static files. The bootstrap system fills them progressively as tech decisions are confirmed during `/create-prd`. An instruction file with unfilled placeholders is a broken agent context. `workflow.md` enforces the mandatory execution sequence: Understand Context -> Check Skills -> Execute -> Validate.
+*   **Rules:** Preemptively loaded constraints that apply to *every* task. Includes security best practices (`security-first.md`), TDD mandates (`tdd-contract-first.md`), and vertical-slice enforcement (`vertical-slices.md`).
+*   **Skills:** Modular capabilities (e.g., `technical-writer`, `brainstorming`). Agents load these explicitly when a task requires them, preventing context bloat.
+*   **Workflows:** Step-by-step markdown checklists invoked via `/slash-commands` (e.g., `/create-prd`, `/implement-slice`). They chain skills together to achieve complex, multi-stage goals.
+
+---
+
+## 2. Data Flow & State Management
+
+Agents are inherently stateless across conversations. The kit uses the **Session Continuity** protocol to provide a persistent memory system.
+
+### The `.agent/progress/` Directory
+
+This directory acts as the agent's long-term and working memory.
+
+```text
+.agent/progress/
+├── index.md                      # Master checklist — phases + overall %
+├── spec-pipeline.md              # Spec completion tracker (IA/BE/FE per shard)
+├── phases/
+│   └── phase-NN.md               # Per-phase slice checklist
+├── slices/
+│   └── phase-NN-slice-NN.md      # Per-slice log (only if ≥3 acceptance criteria)
+├── sessions/
+│   └── YYYY-MM-DD.md             # Session log for resumption
+└── memory/
+    ├── patterns.md
+    ├── blockers.md
+    └── decisions.md
+```
+
+> **Adaptive Granularity Rule**: A slice gets its own file in `slices/` only when it has ≥3 acceptance criteria. Slices with 1–2 criteria are tracked inline in the phase file. This prevents file explosion for simple specs while giving granular tracking for complex ones.
+
+> **Runtime vs. pre-shipped files**: The `phases/`, `slices/`, and `sessions/` directories and their contents are created at runtime by `/plan-phase` (Protocol 2: Progress Generation) and `/implement-slice` (Protocol 3: Progress Update). They do not ship pre-created. The only files that ship as part of the kit in `memory/` are the three empty seed files (`patterns.md`, `blockers.md`, `decisions.md`).
+
+### Flow
+
+1.  **Resume**: On session start, workflows invoke Session Resumption (Protocol 1) — read `index.md` for overall status, find the latest `sessions/YYYY-MM-DD.md` log, check `memory/blockers.md` for unresolved blockers.
+2.  **Act**: The agent executes the workflow against the phase plan in `phases/phase-NN.md`.
+3.  **Persist**: At implementation checkpoints (Protocol 3: Progress Update via `/implement-slice`), the agent marks criteria `[x]`, updates phase progress, and logs findings into `memory/patterns.md`, `decisions.md`, and `blockers.md`.
+4.  **Close**: At session end, the agent writes `sessions/YYYY-MM-DD.md` (Protocol 5: Session Close) to enable clean resumption next session.
+
+### Cross-references
+
+- **Dated File Convention** — See below in this section (Section 2) — governs which artifact paths use glob patterns vs. hardcoded names.
+- **Placeholder Verification Gate Protocol** — See Section 3.5 — governs the Step 0 guard that prevents workflows from reading `{{PLACEHOLDER}}`-dependent skills before bootstrap has run.
+- **Kit Maintenance Checklist** — See Section 5 — governs what must be updated when new workflows or skills are added.
+- **Surface Model** — `.agent/skills/prd-templates/references/surface-model.md` — The authoritative reference for surface types (web/mobile/cli/etc.) and implementation layers, and how the two models relate.
+
+### Dated File Convention
+
+A document is dated (prefixed with `YYYY-MM-DD-`) if and only if it is a **compiled artifact** — one that can be superseded by a newer version and both versions might need to coexist temporarily. Living documents that are updated in place are never dated.
+
+| Document | Dated? | Rationale |
+|---|---|---|
+| `architecture-design.md` | ✅ Yes | Can be re-run with new stack; old version referenced during migration |
+| `vision.md` | ✅ Yes | Evolution creates a new version; audit trail needed |
+| `data-placement-strategy.md` | ✅ Yes | Same pattern |
+| `ENGINEERING-STANDARDS.md` | ✅ Yes | Standards are versioned |
+| Audit reports (`docs/audits/`) | ✅ Yes | Versioned snapshots by definition |
+| Propagation scan reports | ✅ Yes | Same |
+| IA shards (`docs/plans/ia/`) | ❌ No | Living documents; updated in place by `/evolve-feature` |
+| BE specs (`docs/plans/be/`) | ❌ No | Living documents |
+| FE specs (`docs/plans/fe/`) | ❌ No | Living documents |
+| Phase plans (`docs/plans/phases/`) | ❌ No | Operational; history lives in progress tracking files |
+
+Any workflow that reads a compiled artifact must use a glob pattern (e.g., `docs/plans/*-architecture-design.md`), never a hardcoded non-dated path. The agent does not know the date the file was created, so the glob is the only reliable way to locate it.
+
+---
+
+## 3. Module Relationships
+
+The power of the kit comes from how these modules interact:
+
+*   **Workflows call Skills:** A workflow like `/create-prd` will explicitly instruct the agent to use the `technical-writer` and `brainstorming` skills.
+*   **Rules constrain Workflows:** While a workflow dictates the *steps*, the rules dictate *how* those steps are performed (e.g., `/implement-slice` must obey `tdd-contract-first.md`).
+*   **State informs Execution:** Workflows read from `.agent/progress/` to contextualize their execution based on past decisions and current active phases.
+
+---
+
+## 3.5. Bootstrap System
+
+The bootstrap system transforms the kit from a generic template into a project-specific configuration. It runs as a utility workflow called by other pipeline workflows — never directly by the user.
+
+### Components
+
+*   **`bootstrap-agents-fill`**: Receives template key-value pairs and fills `{{PLACEHOLDER}}` markers across all instruction files and root agent config files (`AGENTS.md`, `GEMINI.md`). Idempotent — only fills what's provided, leaves other placeholders untouched.
+*   **`bootstrap-agents-provision`**: Reads the skill library manifest, copies matching skills from `.agent/skill-library/` into `.agent/skills/`, fills skill-specific placeholders, composes `FRAMEWORK_PATTERNS` from the installed frontend framework skill, and updates the installed skills list in all root config files.
+
+### Invocation Model
+
+Bootstrap fires **progressively** — once per confirmed tech decision during `/create-prd-stack`, not in a batch at the end:
+
+1. **Database confirmed** → fills DB placeholders (`DATABASE`, `ORM`, etc.) + provisions database skill from `.agent/skill-library/` (e.g., `stack/databases/surrealdb-expert`, `stack/databases/postgresql-patterns`)
+2. **Frontend framework confirmed** → fills framework placeholders + provisions framework skill + composes `FRAMEWORK_PATTERNS` for `patterns.md`
+3. **Step 9.5 of `/create-prd-compile`** → fills `PROJECT_STRUCTURE` and `ARCHITECTURE_TABLE` in `structure.md`
+
+### Auto-filled vs. "If Provided" Keys
+
+| Key | Auto-filled? | Generated by |
+|-----|-------------|--------------|
+| `VALIDATION_COMMAND`, `TEST_COMMAND`, etc. | Yes | Derived from confirmed dev tooling |
+| `DATABASE`, `AUTH_PROVIDER`, etc. | Yes | Confirmed tech decisions |
+| `INSTALLED_SKILLS` | Yes | After skill provisioning |
+| `PROJECT_STRUCTURE`, `ARCHITECTURE_TABLE` | **No — requires Step 9.5** | `/create-prd-compile` Step 9.5 |
+| `FRAMEWORK_PATTERNS` | **No — requires framework skill** | `bootstrap-agents-provision` after framework provisioning |
+
+### Placeholder Verification Gate Protocol
+
+Workflows that read `{{PLACEHOLDER}}`-dependent skill paths declare their dependencies in frontmatter via the `requires_placeholders:` key — a machine-readable list of which placeholder values must be filled before the workflow can run.
+
+```yaml
+requires_placeholders: [DATABASE_SKILLS, SECURITY_SKILLS]
+```
+
+Two distinct gate types enforce placeholder readiness at different pipeline stages:
+
+| Gate type | Where it runs | When | Purpose |
+|---|---|---|---|
+| **Spec-phase gate** | Step 0 of specification workflows (`create-prd-architecture`, `write-architecture-spec-design`, `write-fe-spec-classify`) | Before any skill reads | Guard spec authoring from unfilled stack placeholders |
+| **Implementation-phase gate** | `/implement-slice-setup` Step -1 | Before any code is written | Guard code generation from broken agent context across all seven instruction files |
+
+Both gates emit a **four-part hard stop message** per unfilled placeholder:
+
+1. **Which exact `{{PLACEHOLDER}}` is unfilled** — the literal placeholder name
+2. **Which pipeline stage fills it** — the `/create-prd-stack` decision that triggers bootstrap
+3. **The exact recovery command** — e.g., `/bootstrap-agents` with `DATABASE=<your-db-choice>`
+4. **The consequence of proceeding without it** — what downstream step would produce incorrect output
+
+**Key constraint:** No auto-refire of bootstrap. The agent stops and tells the user exactly what to run.
+
+For detailed per-workflow placeholder mappings and recovery commands, see `.agent/skills/session-continuity/protocols/10-placeholder-verification-gate.md`.
+
+**Reference implementation:** `write-be-spec-classify.md` Step 2.5 is the canonical example of a correctly implemented placeholder guard.
+
+### Implementation-Phase Placeholder Gate
+
+Before any implementation begins, `/implement-slice-setup` (Step -1) scans all seven instruction files for unfilled `{{` patterns. If any are found, implementation stops with a specific remediation path per file. This gate is the last line of defense against broken agent context reaching the implementation phase.
+
+---
+
+## 4. Key Patterns
+
+### Test-Driven Contract-First (CFPA)
+
+The defining architectural pattern of the code produced by this kit.
+
+1.  **Contract (Zod):** Define the schema first.
+2.  **Tests (Failing):** Write tests that assert against the contract.
+3.  **Implementation:** Write the code to make the tests pass.
+
+*Never reverse this order.*
+
+### Explicit Handoffs
+
+Workflows are designed to end with explicit NEXT STEPS. An agent shouldn't guess what happens after `/ideate`; the workflow tells it to propose `/create-prd`. This ensures continuous, unbroken pipeline progression.
+
+---
+
+## 5. Kit Maintenance Checklist
+
+**When a new workflow or shard is added to `.agent/workflows/`:**
+
+- [ ] Add a row to the `AGENTS.md` Pipeline Workflow Table
+- [ ] Add a matching row to the `GEMINI.md` Pipeline Workflow Table (must stay in sync with `AGENTS.md`)
+- [ ] If the workflow introduces a new system component or new convention, update the relevant section of `docs/kit-architecture.md`
+- [ ] If the workflow uses new prd-template reference files, add them to `prd-templates/SKILL.md`
+- [ ] If the workflow introduces a new skill, add it to `.agent/skill-library/MANIFEST.md`
+
+**When adding a `{{PLACEHOLDER}}` to any `.agent/rules/*.md`**
+
+- [ ] Add the placeholder name and the rule file it lives in to the "Currently applicable" note in `bootstrap-agents-fill.md` Step 3 (the rules scan step)
+- [ ] Add the corresponding bootstrap key to the `bootstrap-agents-fill.md` Step 1 key table if it doesn't already exist
+
+**When `bootstrap-agents-fill.md` fills a placeholder in `AGENTS.md` or `GEMINI.md`:**
+
+- Bootstrap handles project-specific value substitution automatically
+- Kit-level structural changes (new rows, new sections) require manual update per this checklist
+
+**Note**: Both `AGENTS.md` and `GEMINI.md` are co-maintained: project-specific sections by `bootstrap-agents-fill.md` Step 4, and structural/workflow sections by this checklist.
+
+---
+
+## 6. Git Integration
+
+### Excluding `.agent/` from Git Without `.gitignore`
+
+The `.agent/` directory should be indexed by the IDE (for agent context loading) but excluded from version control. Instead of adding it to `.gitignore` (which affects all contributors and may conflict with other entries), use the repository-local exclude file:
+
+```bash
+echo '.agent/' >> .git/info/exclude
+```
+
+**Why this matters:**
+- `.git/info/exclude` is local to your clone — it won't appear in diffs or affect collaborators
+- The IDE still sees and indexes `.agent/` for full agent functionality
+- No `.gitignore` pollution or merge conflicts from differing agent setups
+- Each developer can manage their own agent directory independently
+
+> **Note:** If the project *ships* with `.agent/` as part of the kit (like this starter), you may want `.agent/` tracked in Git. In that case, use `.git/info/exclude` only for runtime-generated files like `.agent/progress/sessions/` and `.agent/progress/slices/`.