cfsa-antigravity 2.0.0 → 2.1.0

package/README.md

@@ -30,6 +30,20 @@ This installs the `.agent/` folder, `docs/` structure, and agent config files in
 
 The pipeline tells you what to run next at every step. You never have to guess.
 
+## Keeping Up to Date
+
+The kit evolves independently of your project. To pull improvements into an existing project:
+
+```
+/sync-kit
+```
+
+This performs a **semantic merge** — it applies new workflows, skills, and rules from the upstream kit while preserving your project-specific values (tech stack, validation commands, filled placeholders). It will never overwrite your project decisions.
+
+- First sync does a full comparison; subsequent syncs are incremental (commit-scoped)
+- Tracks sync state in `.agent/kit-sync.md` so it knows what changed since last update
+- Flags any structural migrations needed (e.g., ideation format changes)
+
 ## Documentation
 
 | Document | Contents |

package/package.json

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

package/template/.agent/instructions/commands.md

@@ -2,44 +2,20 @@
 
 <!-- 
   THIS FILE IS A TEMPLATE.
-  The /bootstrap-agents workflow will fill in your project-specific commands.
-  Replace {{PLACEHOLDERS}} with your actual commands.
+  The /bootstrap-agents workflow fills per-surface command sections below.
+  For single-surface projects, one flat section is written.
+  For multi-surface projects, one section per surface.
 -->
 
-## Package Manager: {{PACKAGE_MANAGER}}
+<!-- Bootstrap writes command sections here. Each surface from the map gets its own section. -->
+<!-- Single-surface projects get a flat layout (no surface header). -->
 
-## Development
-
-```bash
-{{DEV_COMMAND}}                    # Start dev server
-```
-
-## Testing
-
-```bash
-{{TEST_COMMAND}}                   # Run all tests
-{{TEST_WATCH_COMMAND}}             # Watch mode
-{{TEST_COVERAGE_COMMAND}}          # With coverage report
-```
-
-## Linting & Formatting
-
-```bash
-{{LINT_COMMAND}}                   # Lint check
-{{LINT_FIX_COMMAND}}               # Lint with auto-fix
-{{FORMAT_COMMAND}}                 # Format check
-{{TYPE_CHECK_COMMAND}}             # TypeScript type validation
-```
-
-## Build & Preview
-
-```bash
-{{BUILD_COMMAND}}                  # Production build
-{{PREVIEW_COMMAND}}                # Preview production build locally
-```
+{{COMMAND_SECTIONS}}
 
 ## Validation (run after every code change)
 
+The validation command runs all checks for the primary surface. For multi-surface projects, run each surface's validation command.
+
 // turbo
 ```bash
 {{VALIDATION_COMMAND}}

package/template/.agent/instructions/patterns.md

@@ -9,9 +9,9 @@
 ## TypeScript → skills: `clean-code`, `typescript-advanced-patterns`
 - **Strict mode** everywhere — `strict: true` in tsconfig
 - **Explicit types** — No `any`, no implicit returns
-- **Zod validation** — All API inputs validated with Zod schemas
+- **{{CONTRACT_LIBRARY}} validation** — All API inputs validated with {{CONTRACT_LIBRARY}} schemas
 - **Self-documenting** — Clear naming over comments
-- **Zod inference** — Derive TypeScript types from Zod schemas with `z.infer<typeof schema>`
+- **{{CONTRACT_LIBRARY}} inference** — Derive types from {{CONTRACT_LIBRARY}} schemas (e.g., `z.infer<typeof schema>` for Zod, type inference for Pydantic)
 
 ## File Organization → skill: `clean-code`
 - **File size limits** — Per-type limits (enforced by extensibility rule): 200 lines for components (.tsx), 300 for utilities (.ts), 150 for schemas (.schema.ts), 400 for tests (.test.ts), 100 for config files
@@ -24,7 +24,7 @@
 > ⚠️ **Framework component patterns not yet configured.** Run /bootstrap-agents with FRAMEWORK_PATTERNS to fill this section. Until then, follow the framework's official documentation for component conventions and apply the naming and file organisation rules above.
 
 ## API & Data → skill: `rest-api-design`
-- **Input validation** — Zod schemas on every endpoint
+- **Input validation** — {{CONTRACT_LIBRARY}} schemas on every endpoint
 - **Error format** — Consistent: `{ success: boolean, data?: T, error?: { code, message } }`
 - **No magic strings** — Constants and enums for repeated values
 - **Rate limiting** — On all public-facing endpoints

package/template/.agent/instructions/tech-stack.md

@@ -2,39 +2,87 @@
 
 <!-- 
   THIS FILE IS A TEMPLATE.
-  The /bootstrap-agents workflow will fill in your project-specific stack.
-  Sections marked with {{PLACEHOLDER}} will be replaced.
+  The /bootstrap-agents workflow fills the Surface Stack Map and Global Settings below.
+  Empty cells are marked with — (not applicable) or ⚠️ (not yet resolved).
 -->
 
-## Stack Summary
+## Surface Stack Map
 
-**{{TECH_STACK_SUMMARY}}**
+The surface stack map is the **single source of truth** for all per-surface stack decisions and cross-cutting project-wide skills. Every workflow that needs to load skills or run commands resolves them from this map — NOT from scattered placeholders.
 
-## Core Decisions
+### How Workflows Use This Map
 
-| Axis | Decision |
-|------|----------|
-| **Frontend framework** | {{FRONTEND_FRAMEWORK}} |
-| **Backend runtime** | {{BACKEND_RUNTIME}} |
-| **Database** | {{DATABASE}} |
-| **Auth provider** | {{AUTH_PROVIDER}} |
-| **Hosting** | {{HOSTING}} |
-| **CDN / Assets** | {{CDN_ASSETS}} |
-| **CI/CD** | {{CICD}} |
-| **Monitoring** | {{MONITORING}} |
+**Surface-aware workflows** (spec-writing, implementation):
+1. Determine the shard/slice's surface from its directory path or surface tag
+2. Look up the row for that surface in the Per-Surface table below
+3. Load all skills listed in the required column(s) — cells are comma-separated lists
+4. Skip cells marked `—` (not applicable for this surface)
 
-## Development Tooling
+**Cross-cutting workflows** (validation, infrastructure verification):
+1. Read the Cross-Cutting Skills table below
+2. Load all skills listed in the required category
 
-| Tool | Value |
-|------|-------|
-| Package manager | {{PACKAGE_MANAGER}} |
-| Test runner | {{TEST_RUNNER}} |
-| Linter | {{LINTER}} |
-| Type checker | {{TYPE_CHECKER}} |
+**Single-surface projects**: The Per-Surface table has exactly one row. All lookups resolve identically to a flat scalar model. No conditional logic needed.
+
+### Per-Surface Skills
+
+Each cell is a comma-separated list of skill directory names from `.agent/skills/`. Use `—` for "not applicable."
+
+<!-- Bootstrap fills this table. One row per confirmed surface + a `shared` row for cross-surface backend. -->
+
+| Surface | Languages | BE Frameworks | FE Frameworks | FE Design | ORMs | State Mgmt | Databases | Unit Tests | E2E Tests | Test Cmd | Validation Cmd | Lint Cmd | Build Cmd | Dev Cmd | Package Mgr |
+|---------|-----------|---------------|---------------|-----------|------|------------|-----------|------------|-----------|----------|----------------|----------|-----------|---------|-------------|
+| {{SURFACE_ROW}} |
+
+> **Multi-value cells**: A surface can list multiple skills per column (e.g., `tailwind, vanilla-css` or `supabase, surrealdb, pglite`). Workflows iterate and load ALL listed skills.
+
+> **Shared row**: The `shared` surface represents cross-surface backend infrastructure (API layer, shared database, etc.). Shards in `docs/plans/shared/` resolve against this row.
+
+### Cross-Cutting Skills
+
+Project-wide skills that don't vary per surface. Each value column is also comma-separated.
+
+<!-- Bootstrap fills this table from project-wide tech stack decisions. -->
+
+| Category | Skills |
+|----------|--------|
+| Auth | {{AUTH}} |
+| CI/CD | {{CI_CD}} |
+| Hosting | {{HOSTING}} |
+| Security | {{SECURITY}} |
+| API Design | {{API_DESIGN}} |
+| Accessibility | {{ACCESSIBILITY}} |
+| Contract Library | {{CONTRACT_LIBRARY}} |
+
+### Map Verification
+
+A valid surface stack map must satisfy:
+1. **At least one row** in the Per-Surface table (even single-surface projects)
+2. **Languages column is never empty** — every surface has at least one language
+3. **Test Cmd column is never empty** — every surface must be testable
+4. **No `⚠️` cells** — all skill resolution must be complete before implementation begins
+
+Verification gates in `plan-phase` and `implement-slice` check these conditions. See `.agent/skills/session-continuity/protocols/10-placeholder-verification-gate.md` for the full verification procedure.
+
+---
+
+## Global Settings
+
+<!-- These are project-wide values, not per-surface. Bootstrap fills them. -->
+
+| Setting | Value |
+|---------|-------|
+| Project Name | {{PROJECT_NAME}} |
+| Description | {{DESCRIPTION}} |
+| Stack Summary | {{TECH_STACK_SUMMARY}} |
+| Surfaces | {{SURFACES}} |
+| Architecture Doc | {{ARCHITECTURE_DOC}} |
+
+---
 
 ## Installed Skills
 
-<!-- Updated by /create-prd after skill discovery -->
+<!-- Updated by /bootstrap-agents-provision after skill discovery and provisioning -->
 {{INSTALLED_SKILLS}}
 
 ## Reference

package/template/.agent/instructions/workflow.md

@@ -6,6 +6,7 @@ Before taking any action on a task:
 - Read the agent config file at project root (`AGENTS.md` for Antigravity, `GEMINI.md` for Gemini CLI, or equivalent for your agent)
 - Read relevant `.agent/instructions/` files for the task type
 - Check [Engineering Standards](../../docs/plans/ENGINEERING-STANDARDS.md) for quality bar — if this file doesn't exist yet, the pipeline hasn't reached /create-prd; run /ideate then /create-prd first
+- **Session Resumption**: If `.agent/progress/index.md` exists, read `.agent/skills/session-continuity/protocols/01-session-resumption.md` and follow the **Session Resumption Protocol** to load cross-session context and identify the resumption point
 
 ## 2. Check Skills
 - Scan `.agent/skills/` for applicable skills
@@ -27,11 +28,21 @@ Before taking any action on a task:
 ## 4. Validate (MANDATORY)
 After **every** code change, run:
 ```bash
-{{VALIDATION_COMMAND}}
+See `.agent/instructions/commands.md` for the validation command.
 ```
 
 Do NOT mark a task complete until all validations pass.
 
+## 5. Learn (MANDATORY)
+
+After completing a workflow or substantial task:
+
+- **Pattern Extraction**: Read `.agent/skills/session-continuity/protocols/04-pattern-extraction.md` and follow the **Pattern Extraction Protocol**. Reflect on what worked, what didn't, and log reusable patterns to `memory/patterns.md`. Skip only if the task was trivial (routine, nothing new learned).
+- **Session Close**: Read `.agent/skills/session-continuity/protocols/05-session-close.md` and follow the **Session Close Protocol**. Write a session log to `.agent/progress/sessions/` so the next session can resume cleanly.
+
+> These steps are **not optional**. They are what differentiate a pipeline that gets
+> smarter over time from one that repeats the same mistakes.
+
 ## Principles
 
 - **Ask before assuming** — Clarify ambiguous requirements

package/template/.agent/rules/completion-checklist.md

@@ -38,6 +38,11 @@ A unit of work is only DONE when:
    - Overall progress fractions updated
 4. **The Locks**: All task claims (`[!]` flags and `files:` blocks) are removed.
 5. **The Memory**: Blockers and patterns are logged to `.agent/progress/memory/`.
+   - Follow `.agent/skills/session-continuity/protocols/04-pattern-extraction.md` — reflect on what worked, what didn't, classify, and write to `memory/patterns.md`
+   - Log any new blockers or resolutions to `memory/blockers.md`
+   - If decisions were made using Protocol 6 (Decision Effect Analysis), verify they're recorded in `memory/decisions.md`
+6. **The Session Log**: A session close log exists in `.agent/progress/sessions/`.
+   - Follow `.agent/skills/session-continuity/protocols/05-session-close.md` — write what was accomplished, deferred, and where the next session should start
 
 ## Enforcement
 
@@ -46,3 +51,4 @@ updating progress files, **you may not skip it**.
 
 If you skip the progress tracking steps, you have failed the task, regardless of how
 good the code is.
+

package/template/.agent/rules/security-first.md

@@ -14,15 +14,15 @@ trigger: always_on
 | Rule | Implementation |
 |------|---------------|
 | **No PII in AI payloads** | User data (email, name, DOB, payment info) is NEVER included in AI model requests |
-| **PII fields tagged in schemas** | Zod schemas mark sensitive fields with `.describe('PII')` for automated auditing |
+| **PII fields tagged in schemas** | {{CONTRACT_LIBRARY}} schemas mark sensitive fields for automated auditing |
 | **No PII in logs** | Structured logging with automatic PII redaction |
 | **No PII in error messages** | Error responses never include user data — use IDs and codes only |
 | **Encrypted at rest** | All PII fields encrypted in database |
 
 ## Input Validation
 
-- **Every** API endpoint validates input with Zod — no exceptions
-- **Every** form validates client-side with Zod AND server-side with the same schema
+- **Every** API endpoint validates input with {{CONTRACT_LIBRARY}} — no exceptions
+- **Every** form validates client-side with {{CONTRACT_LIBRARY}} AND server-side with the same schema
 - **No** raw user input reaches a database query — always parameterized
 - **No** user input is rendered as HTML — always escaped
 - **Rate limiting** — Every public-facing endpoint must have rate limiting configured. No exceptions. Use the project's configured rate limiting utility (see `patterns.md` for the approach). Unauthenticated endpoints must have stricter limits than authenticated ones.

package/template/.agent/rules/vertical-slices.md

@@ -25,7 +25,7 @@ trigger: always_on
 A feature slice is complete when:
 
 - [ ] Data layer: schema defined, permissions set, seed data exists
-- [ ] API layer: endpoints exist, validated with Zod, tested
+- [ ] API layer: endpoints exist, validated with {{CONTRACT_LIBRARY}}, tested
 - [ ] User-facing: component renders, handles loading/error/empty states
 - [ ] Admin: can create/read/update/delete the resource
 - [ ] Tests pass at all levels (contract, unit, integration, E2E)

package/template/.agent/skill-library/MANIFEST.md

@@ -220,7 +220,13 @@ Note: `DESIGN_DIRECTION` does not copy a skill from the library — it fills pla
 | Stack Key | Value Pattern | Library Path | Installed As |
 |-----------|--------------|-------------|-------------|
 | `CI_CD` | `*github*` | `stack/devops/github-actions` | `github-actions` |
+| `CI_CD` | `*github*` | `stack/devops/git-workflow` | `git-workflow` |
+| `CI_CD` | `*github*` | `stack/devops/git-advanced` | `git-advanced` |
 | `CI_CD` | `*terraform*` | `stack/devops/terraform` | `terraform` |
+| `CI_CD` | `*gitlab*` | `stack/devops/git-workflow` | `git-workflow` |
+| `CI_CD` | `*gitlab*` | `stack/devops/git-advanced` | `git-advanced` |
+| `CI_CD` | `*bitbucket*` | `stack/devops/git-workflow` | `git-workflow` |
+| `CI_CD` | `*bitbucket*` | `stack/devops/git-advanced` | `git-advanced` |
 
 ### DevOps / Infrastructure