cfsa-antigravity 1.0.0

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

@@ -0,0 +1,88 @@
+---
+name: prd-templates
+description: "Document templates for all pipeline output documents — specs, indexes, reports, and strategy docs. Use when any workflow needs to produce a structured document."
+category: templates
+risk: none
+source: self
+date_added: "2026-02-28"
+---
+
+# PRD Templates
+
+Canonical markdown templates for all pipeline output documents. Workflows reference these templates instead of inlining them — the template defines structure, the workflow fills content.
+
+## When to Use This Skill
+
+- During any workflow step that produces a structured document
+- When writing specs (BE, FE), indexes, reports, or strategy documents
+- During classification steps that seed spec file stubs
+
+## 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.
+
+## How to Use
+
+1. Read the appropriate template from `references/`
+2. Fill each section with content gathered during prior workflow steps
+3. Apply the depth rule: every section should have ≥200 words for architecture docs; no section should use TBD or placeholder values
+
+## Reference Files
+
+| Template | File | Used By |
+|----------|------|---------|
+| Architecture Design | `references/architecture-design-template.md` | `/create-prd-compile` Step 10 |
+| Engineering Standards | `references/engineering-standards-template.md` | `/create-prd-compile` Step 11 |
+| Vision Document | `references/vision-template.md` | `/ideate-validate` Step 11 |
+| BE Spec + Seed Stub | `references/be-spec-template.md` | `/write-be-spec-write` Step 7, `/write-be-spec-classify` |
+| FE Spec + Seed Stub | `references/fe-spec-template.md` | `/write-fe-spec-write` Step 6, `/write-fe-spec-classify` |
+| Data Placement Strategy | `references/data-placement-template.md` | `/create-prd-architecture` Step 5 |
+| Design System Decision Options | `references/design-system-decisions.md` | `/create-prd-design-system` Step 1 (option menus + output template); downstream: `write-fe-spec-classify` Step 0.75 prerequisite check |
+| Infrastructure Report | `references/infrastructure-report-template.md` | `/verify-infrastructure` Steps 0.6, 8 |
+| Decomposition (shards + indexes) | `references/decomposition-templates.md` | `/decompose-architecture-structure` Steps 5-9 |
+| Operational (slices, remediation, skills, sync) | `references/operational-templates.md` | `/plan-phase`, `/remediate-pipeline-assess`, `/bootstrap-agents-provision`, `/sync-kit` |
+
+## Depth Standards
+
+> **Template depth rule**: Section headings in templates are MINIMUM headings, not maximum content. Each section must contain the full detail gathered during prior steps. If a section is under 200 words, it's almost certainly too shallow. Apply the two-implementer test: could a developer interpret this two different ways? If yes, add more detail.
+
+## Shard Seeding Procedure
+
+Run this procedure when filling the `## Features` section of each shard skeleton during `/decompose-architecture-structure`.
+
+### Source
+
+Read `docs/plans/ideation.md` and locate the section corresponding to the shard's domain.
+
+### Actor + Goal Format Rule
+
+Extract every Level-1 sub-feature as a concrete capability a user would recognise, written in actor + goal format with primary data noted.
+
+**Example:** `"Creator can upload a video → primary data: media asset"`
+
+Do NOT use architecture-level headlines or implementation details.
+
+### Grouping Rule
+
+List sub-features as bullet points in the `## Features` section. Group by functional area if the ideation content suggests natural groupings.
+
+### `[THIN — review with user]` Fallback Rule
+
+If a shard's domain has no corresponding section in `ideation.md` (the domain was introduced during architecture design, not ideation), mark the skeleton with `[THIN — review with user]` at the top of `## Features` and seed from the architecture design description instead.
+
+At the validation step, the user must confirm whether to:
+- Keep the shard separate
+- Merge it into an adjacent shard
+- Add missing sub-features from ideation
+
+### Directory Example
+
+Seeded skeletons live in the `docs/plans/ia/` directory:
+
+```
+docs/plans/ia/
+├── 00-infrastructure.md
+├── 01-user-accounts.md      ← ## Features seeded from ideation.md § User Accounts
+├── 02-content-library.md    ← ## Features seeded from ideation.md § Content Library
+├── ...
+```

package/template/.agent/skills/prd-templates/references/architecture-design-template.md

@@ -0,0 +1,88 @@
+# Architecture Design Template
+
+Use this template when compiling `docs/plans/YYYY-MM-DD-architecture-design.md`.
+
+```markdown
+# [Project Name] — Architecture Design
+
+> **Vision**: [link to vision.md]
+> **Date**: YYYY-MM-DD
+> **Status**: Draft | Review | Approved
+> **Project Type**: [Single-surface: web/desktop/mobile/CLI/API | Multi-surface: list surfaces]
+
+## Tech Stack
+[Explicit decision for each applicable axis with rationale — not just the choice,
+but WHY this choice over alternatives, what trade-offs were accepted, and what
+constraints drove the decision. For multi-surface projects, organized by surface.]
+
+## System Architecture
+[Component diagram, data flow, deployment topology — every service named, every
+communication path documented, every failure mode identified. For multi-surface:
+include surface interconnection diagram and shared domain boundary.]
+
+## Data Strategy
+[Placement, schema design, query patterns, migrations — which data lives where
+and why, what the hot paths are, how schema evolves. For multi-surface: data
+ownership, sync protocol, conflict resolution.]
+
+## Error Architecture
+[Global error envelope with locked example JSON — all four fields defined with types. Error
+propagation chain per layer (DB → service → API handler → transport → client) — what is caught,
+logged, and exposed at each layer. Unhandled exception strategy — process-level catch, log fields,
+client response, alerting timeline. Client fallback contract per surface — offline mode decision,
+UI behaviour on network failure, retry strategy, timeout threshold. Error boundary strategy per
+applicable surface — boundary placement and fallback rendering.]
+
+## Security Model
+[Auth, authorization, validation, rate limits — every flow specified step-by-step,
+every permission rule scoped, every error case handled]
+
+## Compliance & Safety
+[If applicable — full depth on minors/payments/health/regulated domains.
+This section may be the largest in the document if compliance constraints
+are significant. Every account type, every consent flow, every content filter,
+every notification trigger, every audit requirement.]
+
+## API Design
+[Surface type, versioning, conventions — endpoint naming, request/response shapes,
+error format, pagination strategy. For multi-surface: shared API contract format.]
+
+## Integration Points
+[External services, failure modes, fallbacks, cost models — for each: what it
+provides, what happens when it's down, what the fallback is]
+
+## Observability Architecture
+[Logging strategy — library named, structured JSON (yes/no for prod), log levels per environment,
+PII field names that are never logged (named explicitly), log destination. Tracing strategy —
+service boundaries traced, sampling rate per environment, trace ID propagation to API clients.
+Alerting thresholds — error rate %, latency threshold + duration, queue depth warning, delivery
+mechanism named. Launch dashboards — minimum required panels named, tool named, owner named.
+Retention — log retention duration, trace retention duration, compliance alignment.]
+
+## Development Methodology
+[Contract-first, TDD, vertical slices, spec layers, quality gates — the full
+process, not just labels]
+
+## Phasing
+[Phase breakdown with feature allocation, dependency order, and timeline estimates.
+Each phase has explicit entry/exit criteria. For multi-surface: per-surface or
+cross-surface phasing strategy.]
+
+## Directory Structure
+[The approved source directory tree from Step 9.5, with one-line descriptions per directory.
+Includes: contracts directory path, test layout, build output path, surface subtrees for multi-surface projects.]
+
+## Architecture Separation
+[The concern/location/runtime table from Step 9.5 — maps each architectural concern to its
+directory and the runtime where it executes.]
+
+## Installed Skills
+[List of skills installed during this workflow with versions]
+
+## Decisions Log
+[Every decision made during this workflow with rationale — not just what was
+decided, but what alternatives were considered and why they were rejected]
+
+## Open Questions
+[Anything needing resolution before decomposition — with owner and deadline]
+```

package/template/.agent/skills/prd-templates/references/be-spec-template.md

@@ -0,0 +1,101 @@
+# BE Spec Template
+
+Use this template when writing BE specs to `docs/plans/be/[NN-feature-name].md`.
+
+```markdown
+# [Feature] — Backend Specification
+
+> **IA Source**: [link to IA shard]
+> **Deep Dives**: [links to consumed deep dives, if any]
+> **Status**: Draft | Review | Complete
+
+## IA Source Map
+
+[Which IA shard sections, deep dives, and cross-shard references
+inform each part of this BE spec. This is the traceability record
+that lets a reviewer verify nothing was missed or invented.]
+
+| BE Spec Section | IA Source | Section/Lines |
+|-----------------|----------|---------------|
+| API Endpoints | [primary-shard.md] | § User Flows |
+| Database Schema | [primary-shard.md] | § Data Model |
+| Middleware | [cross-ref-shard.md] | § Access Control (lines N–M) |
+| Error Handling | [primary-shard.md] | § Edge Cases |
+| [specific subsystem] | [deep-dive.md] | § Key Decisions |
+
+## API Endpoints
+## Request/Response Contracts (Zod schemas)
+## Database Schema
+## Middleware & Policies
+## Data Flow
+## Error Handling
+## Open Questions
+
+## Changelog
+
+| Date | Change | Workflow | Sections Affected |
+|------|--------|----------|-------------------|
+| [date] | Initial creation | /write-be-spec | All |
+```
+
+## Quality Gates Checklist
+
+Apply after writing every BE spec:
+
+- [ ] Every endpoint has a Zod request AND response schema
+- [ ] Every database table has defined fields, indexes, and permissions
+- [ ] Security constraints from IA shard reflected in middleware section
+- [ ] Error codes are specific (not generic 500s)
+- [ ] Rate limits specified per endpoint
+- [ ] Access control requirements mapped to middleware checks
+- [ ] Every deep dive key decision is reflected in the spec (not ignored)
+- [ ] Every cross-shard reference has been resolved (no dangling pointers)
+- [ ] IA Source Map is complete — no BE spec section lacks a traceable IA source
+- [ ] Testability criteria from IA shard reflected as performance targets
+
+## BE Spec Seed Stub
+
+Use when creating a spec file during classification:
+
+```markdown
+# [Feature] — Backend Specification
+
+> **IA Source**: [link to IA shard]
+> **Deep Dives**: [links, if any]
+> **Status**: Classifying
+
+## Classification
+- **Type**: [single-domain | multi-domain-split | cross-cutting | structural reference]
+- **IA Source**: [shard name]
+- **BE Spec(s) to produce**: [list]
+
+## Referenced Material Inventory
+[Primary shard, cross-refs with file + section + line numbers]
+```
+
+## FE Spec Seed Stub
+
+Use when creating a spec file during FE classification:
+
+```markdown
+# [Feature] — Frontend Specification
+
+> **BE Source**: [link to BE spec(s)]
+> **IA Source**: [link to IA shard]
+> **Status**: Classifying
+
+## Classification
+- **Type**: [feature spec | cross-cutting]
+- **BE Source(s)**: [list]
+- **IA Source**: [shard name]
+
+## Referenced Material Inventory
+[same format as BE classify stub]
+
+## Design Requirements (extracted from brand-guidelines)
+**Direction**: [confirmed direction]
+**Typography**: [extracted]
+**Colors**: [extracted]
+**Motion**: [extracted]
+**Anti-patterns**: [extracted]
+```

package/template/.agent/skills/prd-templates/references/data-placement-template.md

@@ -0,0 +1,74 @@
+# Data Placement Strategy Template
+
+Use this template to create `docs/plans/data-placement-strategy.md` during `/create-prd-architecture`.
+
+```markdown
+# Data Placement Strategy
+
+## N-Tier Model Responsibilities
+
+Define each tier in the system and what it is responsible for:
+
+| Tier | Responsibility | Examples |
+|------|---------------|----------|
+| [Client / Edge / API / Database / Cache / Object Storage / External Service] | [What this tier owns and manages] | [Specific technologies] |
+
+## Complete Data Placement Map
+
+For every data type in the system, specify its canonical owner:
+
+| Data Type | Canonical Owner | Stored Content | Encryption | Rationale |
+|-----------|----------------|----------------|------------|-----------|
+| [e.g., User profile] | [e.g., Database] | [Fields stored] | [at-rest / in-transit / both / none] | [Why this placement] |
+| [e.g., Session tokens] | [e.g., Cache] | [Token data] | [encryption approach] | [Why this placement] |
+| [e.g., Uploaded files] | [e.g., Object storage] | [File content + metadata] | [encryption approach] | [Why this placement] |
+
+## Security Boundaries
+
+For each tier, explicitly state what it stores AND what it does NOT store:
+
+| Tier | Stores | Does NOT Store |
+|------|--------|---------------|
+| [Client] | [e.g., UI state, cached display data] | [e.g., raw PII, API secrets, decryption keys] |
+| [Edge/CDN] | [e.g., static assets, cached public responses] | [e.g., user-specific data, PII] |
+| [API Server] | [e.g., request context, short-lived auth tokens] | [e.g., persistent user data, raw credentials] |
+| [Database] | [e.g., user records, PII (encrypted)] | [e.g., API secrets, session tokens] |
+| [Cache] | [e.g., computed values, session data] | [e.g., PII, source-of-truth records] |
+
+## PII Boundaries
+
+- Which fields contain PII (enumerate every one)
+- Where PII is stored vs where it is NOT stored
+- How PII is isolated from AI/analytics pipelines
+- PII access logging requirements
+
+## GDPR/Compliance Data Lifecycle
+
+| Data Category | Retention Period | Deletion Trigger | Deletion Responsibility | Verification |
+|--------------|-----------------|-----------------|------------------------|-------------|
+| [e.g., Account data] | [e.g., Account lifetime + 30 days] | [e.g., Account deletion request] | [e.g., API server → database cascade] | [How deletion is verified] |
+| [e.g., Usage analytics] | [e.g., 90 days] | [e.g., TTL expiry] | [e.g., Database auto-purge] | [How deletion is verified] |
+
+## Tenancy Model
+
+[Single-tenant / Multi-tenant / Hybrid]
+- Isolation mechanism: [e.g., row-level security, schema-per-tenant, database-per-tenant]
+- Data co-mingling rules: [What data is shared vs isolated]
+- Cross-tenant query prevention: [How enforced]
+
+## Sync Protocol (multi-surface only)
+
+- What data syncs between surfaces
+- Sync frequency and mechanism
+- Conflict resolution strategy
+- Network partition behavior
+
+## Summary Table
+
+| Layer | Stores | Does NOT Store |
+|-------|--------|---------------|
+| [Layer 1] | [List] | [List] |
+| [Layer 2] | [List] | [List] |
+```
+
+This document is consumed by `/write-be-spec` and `/write-architecture-spec` to ensure every spec places data consistently.

package/template/.agent/skills/prd-templates/references/decomposition-templates.md

@@ -0,0 +1,211 @@
+# Decomposition Templates
+
+Templates for shard skeletons and layer indexes created during `/decompose-architecture-structure`.
+
+---
+
+## Shard Skeleton
+
+For each shard, create at `docs/plans/ia/[NN-domain-name].md`:
+
+```markdown
+# [Shard ##] — [Domain Name]
+
+> **Architecture Source**: [link to architecture-design.md]
+> **Status**: Skeleton | Draft | Review | Complete
+
+## Overview
+[1-2 sentence description of this domain's scope]
+
+## Features
+[Level-1 sub-features from ideation.md for this domain. NOT architecture-level headlines. See /decompose-architecture-structure Step 5 for seeding instructions.]
+
+## User Interactions
+[To be filled during /write-architecture-spec]
+
+## Data Model
+[To be filled during /write-architecture-spec]
+
+## Access Control
+[To be filled during /write-architecture-spec]
+
+## Accessibility
+
+<!-- Filled by /write-architecture-spec-design Step 5.5 -->
+<!-- For web/mobile/desktop surfaces: WCAG 2.1 AA requirements per interaction -->
+<!-- For api/cli/extension only: "Not applicable — no visual surfaces" -->
+
+## Edge Cases
+[To be filled during /write-architecture-spec]
+
+## Cross-Shard Dependencies
+[List which other shards this one depends on or is depended upon by]
+
+## Deep Dives Needed
+[List any features complex enough to warrant a separate deep dive document]
+
+## Changelog
+
+| Date | Change | Workflow | Sections Affected |
+|------|--------|----------|-------------------|
+| [date] | Initial creation | /decompose-architecture-structure | All |
+```
+
+---
+
+## IA Index
+
+Create at `docs/plans/ia/index.md`:
+
+```markdown
+# IA Layer — Information Architecture
+
+> **Architecture Source**: [link to architecture-design.md]
+
+## Reading Order
+
+Read cross-cutting shards first, then feature shards in numerical order.
+
+## Shards
+
+| # | Shard | Status | Deep Dives |
+|---|-------|--------|------------|
+| 00 | [00-shard-name.md](00-shard-name.md) | 🔲 | — |
+| 01 | [01-shard-name.md](01-shard-name.md) | 🔲 | — |
+| ... | ... | ... | ... |
+
+## Conventions
+
+- Every shard must define: features, user interactions, data model, access control, accessibility, edge cases
+- Cross-shard dependencies must be bidirectional (if A references B, B must reference A)
+- Complex features get a separate deep dive in `deep-dives/`
+- Status: 🔲 Skeleton → 📝 Draft → 👀 Review → ✅ Complete
+```
+
+---
+
+## BE Index Skeleton
+
+Create at `docs/plans/be/index.md`:
+
+```markdown
+# BE Layer — Backend Specifications
+
+> **IA Source**: [link to ia/index.md]
+
+## Reading Order
+
+Read cross-cutting specs first, then feature specs in numerical order.
+
+## Conventions Template
+
+Every BE spec MUST include:
+- API Endpoints (method, path, description)
+- Request/Response Contracts (Zod schemas)
+- Database Schema (tables, fields, indexes, permissions)
+- Middleware & Policies (auth, rate limits, validation)
+- Data Flow (request lifecycle)
+- Error Handling (specific error codes, not generic 500s)
+- IA Source Map (which IA shard sections and deep dives inform each part)
+
+## Shard-to-Spec Mapping
+
+Populated by `/write-be-spec`. Mapping depends on shard document type
+(classified during `/write-architecture-spec`):
+
+| IA Shard | Type | BE Spec(s) | Status |
+|----------|------|-----------|--------|
+| *(populated by /write-be-spec)* | | | |
+```
+
+---
+
+## FE Index Skeleton
+
+Create at `docs/plans/fe/index.md`:
+
+```markdown
+# FE Layer — Frontend Specifications
+
+> **BE Source**: [link to be/index.md]
+
+## Reading Order
+
+Read cross-cutting specs first, then feature specs in numerical order.
+
+## Conventions Template
+
+Every FE spec MUST include:
+- Component Inventory (tree with props interfaces)
+- Page/Route Definitions (URL patterns, guards, redirects)
+- State Management (server state, client state, URL state)
+- Interaction Specification (click, hover, keyboard, form validation)
+- Responsive Behavior (breakpoints, component behavior)
+- Accessibility (ARIA roles, keyboard navigation, screen reader)
+- Loading/Error/Empty States
+- Source Map (traceability to BE spec and IA shard sections)
+
+## Spec-to-Source Mapping
+
+Populated by `/write-fe-spec`. FE specs are organized by UI surface, not backend boundary:
+
+| # | FE Spec | BE Source(s) | IA Source | Status |
+|---|---------|-------------|-----------|--------|
+| *(populated by /write-fe-spec)* | | | | |
+```
+
+---
+
+## Master Index — Single-Surface
+
+Create or update `docs/plans/index.md`:
+
+```markdown
+# [Project Name] — Specification Index
+
+## Documents
+
+| Document | Description | Status |
+|----------|-------------|--------|
+| [Vision](vision.md) | Problem, personas, features, constraints | ✅ |
+| [Architecture Design](YYYY-MM-DD-architecture-design.md) | Tech stack, system design, security | ✅ |
+
+## Specification Layers
+
+| Layer | Index | Purpose | Specs |
+|-------|-------|---------|-------|
+| **IA** | [ia/index.md](ia/index.md) | Features, interactions, data models, access control | N shards |
+| **BE** | [be/index.md](be/index.md) | API endpoints, contracts, database schemas, middleware | N specs |
+| **FE** | [fe/index.md](fe/index.md) | Components, routing, state, interactions, a11y | N specs |
+```
+
+## Master Index — Multi-Surface
+
+```markdown
+# [Project Name] — Specification Index
+
+## Documents
+
+| Document | Description | Status |
+|----------|-------------|--------|
+| [Vision](vision.md) | Problem, personas, features, constraints | ✅ |
+| [Architecture Design](YYYY-MM-DD-architecture-design.md) | Tech stack, system design, security | ✅ |
+
+## Surfaces
+
+| Surface | Index | Description | Shards |
+|---------|-------|-------------|--------|
+| **Shared** | [shared/index.md](shared/index.md) | Cross-surface domain models, sync protocol, shared contracts | N |
+| **[Surface 1]** | [surface-1/index.md](surface-1/index.md) | [Surface 1 description] | N |
+| **[Surface 2]** | [surface-2/index.md](surface-2/index.md) | [Surface 2 description] | N |
+
+## Pipeline (per surface)
+
+Each surface follows the same spec pipeline independently:
+IA shards → BE specs → FE specs → audit → plan → implement → validate
+
+Shared surface specs must be completed first — other surfaces depend on them.
+```
+
+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.