cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/tech-stack-catalog/references/constraint-questions.md

@@ -0,0 +1,237 @@
+# Constraint Questions
+
+Per-axis constraint questions with mandatory ideation grounding. Every axis has two tiers of questions and a citation gate.
+
+## How to Use This File
+
+For **each** tech stack axis:
+
+1. **Tier 1 — Self-answer from ideation**: Answer these questions by reading the ideation files listed in the **Required Reads** column. Do NOT ask the user these questions — you already have the answers in the ideation output. Write a 3-5 bullet **Ideation Synthesis** summarizing what you found.
+2. **Cite-or-Stop Gate**: Your Ideation Synthesis must contain ≥ 2 project-specific findings with file citations (e.g., "From `diagnostics/diagnostics-index.md`: multi-agent orchestration requires persistent task queues"). If you cannot produce 2 citations → you have not read deeply enough → **STOP** and read the deep dives and CX files before continuing.
+3. **Tier 2 — Ask the user**: Only after passing the citation gate, ask these questions to the user. These are things only the user can answer (budget, team expertise, preferences).
+4. **Present options**: Combine ideation synthesis + user answers to filter and score options. Your recommendation MUST cite ideation findings as supporting evidence.
+
+> ❌ **Anti-pattern**: Presenting generic strengths/risks like "Good ecosystem support" or "Scalable" without tying them to a specific ideation finding. Every strength/risk in the option table must reference a concrete project requirement from the ideation output.
+
+---
+
+## Hosting
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| `meta/constraints.md` → `## Project Surfaces` | Which surfaces need hosting (web, API, desktop distribution, mobile distribution) |
+| `meta/constraints.md` → compliance section | Data residency, regulatory requirements that constrain hosting region/provider |
+| Every domain `{domain}-index.md` | Features requiring edge compute, real-time, WebSocket, or heavy compute |
+| CX files (`ideation-cx.md` + domain CX) | Cross-surface data flow that affects deployment topology |
+| Deep dives with latency or performance mentions | P95 requirements, geographic distribution needs |
+
+### Tier 1 — Self-answer from ideation
+
+- What surfaces need hosting and what type of hosting each requires (static, SSR, API, worker)?
+- Are there latency-sensitive features that require edge deployment?
+- Are there compliance or data residency constraints that limit hosting geography?
+- Do any features require persistent connections (WebSocket, SSE) that affect hosting choice?
+- What is the deployment topology implied by the architecture (monolith, microservices, serverless)?
+
+### Tier 2 — Ask the user
+
+- Is there an existing cloud provider or hosting preference?
+- What is the monthly hosting budget ceiling?
+- How much operational complexity is acceptable (managed vs self-hosted)?
+
+---
+
+## Database / Persistence
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| Every domain `{domain}-index.md` | Entity types, relationship complexity, data cardinality |
+| Deep dives with data model mentions | Graph relationships, hierarchical data, polymorphic entities |
+| Deep dives with search/query mentions | Full-text search, faceted search, complex query patterns |
+| Deep dives with sync/real-time mentions | Offline-first, CRDT, conflict resolution, real-time subscriptions |
+| CX files | Cross-domain entity ownership, shared entities, data flow direction |
+| `meta/constraints.md` | PII fields, compliance (HIPAA/PCI/GDPR) affecting data placement |
+
+### Tier 1 — Self-answer from ideation
+
+- What are the primary entity types and their relationships (flat, hierarchical, graph)?
+- Are there features requiring graph traversal (e.g., dependency chains, social connections, multi-hop queries)?
+- Are there features requiring full-text search, vector similarity, or faceted filtering?
+- What are the read/write patterns implied by the feature workflows (read-heavy dashboards, write-heavy logging, balanced CRUD)?
+- Are there real-time or offline-first requirements that affect database choice?
+- Do any entities require time-series storage (metrics, audit logs, sensor data)?
+- What PII fields exist and what isolation boundaries are required?
+
+### Tier 2 — Ask the user
+
+- Is there existing database expertise or infrastructure to leverage?
+- Are there multi-tenancy requirements the ideation didn't capture?
+- Budget constraints for managed database services?
+
+> **Note**: Database is handled by the Persistence Map Interview in `create-prd-stack.md`. These questions feed into that interview — they do not replace it.
+
+---
+
+## Auth Provider
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| Every domain `{domain}-index.md` → Role Matrix | All roles, permission levels (Full/Config/Read-only/None), per-domain access |
+| `meta/constraints.md` → compliance section | COPPA, GDPR, age restrictions, SSO requirements |
+| Domain deep dives with access control mentions | Multi-tenant isolation, resource ownership, escalation paths |
+| CX files | Trust boundaries across domains, cross-domain permission handoff |
+
+### Tier 1 — Self-answer from ideation
+
+- How many distinct roles exist and what are their permission boundaries?
+- Is there a multi-tenant model (org-level isolation, workspace-level, etc.)?
+- Are there age restrictions or minor-handling requirements (COPPA)?
+- Do any features require granular resource-level permissions (ABAC) vs role-based (RBAC)?
+- Are there third-party integration points that need OAuth/API key authentication?
+- Does the app need social login, SSO/SAML, or enterprise federation?
+
+### Tier 2 — Ask the user
+
+- Is social login (Google, GitHub, Apple, etc.) required? Which providers?
+- Is SSO/SAML needed for enterprise customers?
+- Budget for auth provider (free tier vs paid)?
+- Team experience with specific auth providers?
+
+---
+
+## Frontend Framework
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| `meta/constraints.md` → `## Project Surfaces` | Web surface type (app, content site, hybrid), SEO requirements |
+| Every domain `{domain}-index.md` | UI complexity per domain — forms, dashboards, real-time views, interactive editors |
+| Deep dives with UI/interaction mentions | Complex interaction patterns (drag-drop, canvas, WYSIWYG, collaborative editing) |
+| Deep dives with real-time mentions | Live updates, WebSocket-driven UI, optimistic updates |
+| CX files | Cross-domain navigation patterns, shared UI state requirements |
+
+### Tier 1 — Self-answer from ideation
+
+- Is SSR required for SEO or first-paint performance, or is this a pure SPA?
+- How complex are the interactive patterns (simple forms vs complex editors vs canvas-based)?
+- Are there real-time UI requirements (live dashboards, collaborative editing)?
+- What is the page count / route complexity implied by the feature inventory?
+- Are there offline-first or PWA requirements that affect framework choice?
+- Does the app need to share code with other surfaces (mobile, desktop)?
+
+### Tier 2 — Ask the user
+
+- Team framework experience or preference?
+- Is there an existing frontend codebase to integrate with?
+- Performance priority: bundle size vs DX vs ecosystem maturity?
+
+---
+
+## Backend Framework / Runtime
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| `meta/constraints.md` → `## Project Surfaces` | Backend surface type (API-only, BFF, monolith) |
+| Every domain `{domain}-index.md` | Feature complexity — CRUD-heavy vs computation-heavy vs orchestration-heavy |
+| Deep dives with AI/ML mentions | AI orchestration, model serving, agent coordination |
+| Deep dives with integration mentions | External API calls, webhook handling, queue processing |
+| CX files | Cross-domain business logic, shared middleware requirements |
+
+### Tier 1 — Self-answer from ideation
+
+- What type of backend logic dominates — simple CRUD, complex business rules, AI orchestration, or data pipelines?
+- Are there features requiring long-running processes (agents, batch jobs, async workflows)?
+- What are the latency requirements (P95 targets from deep dives)?
+- Is there a need for background job processing or event-driven architecture?
+- Does the backend need to serve multiple surfaces with different protocols (REST for web, gRPC for internal)?
+- Are there cold-start sensitivity constraints (serverless viability)?
+
+### Tier 2 — Ask the user
+
+- Team language/framework expertise?
+- Deployment target preference (traditional server, serverless, edge)?
+- Is there an existing backend to extend vs greenfield?
+
+---
+
+## API Layer
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| Every domain `{domain}-index.md` | Query complexity per domain — simple lookups vs complex filtered/nested queries |
+| Deep dives with data fetching mentions | Over-fetching risks, real-time subscription needs, batch query patterns |
+| CX files | Cross-domain data aggregation, BFF patterns, gateway needs |
+| `meta/constraints.md` → `## Project Surfaces` | Number of consuming surfaces (affects API style choice) |
+
+### Tier 1 — Self-answer from ideation
+
+- How varied are the data fetching patterns (uniform CRUD vs highly variable query shapes)?
+- Are there features requiring real-time subscriptions?
+- How many surfaces consume the API (affects REST vs GraphQL vs tRPC calculus)?
+- Is there a need for API-to-API communication (microservice internal APIs)?
+- Are there complex nested data requirements that would benefit from flexible query languages?
+
+### Tier 2 — Ask the user
+
+- Is the API public-facing (needs REST + OpenAPI) or internal-only (tRPC viable)?
+- Team experience with GraphQL vs REST vs tRPC?
+- Is API versioning a concern (breaking change frequency)?
+
+---
+
+## CI/CD
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| `meta/constraints.md` → `## Project Surfaces` | Number of deployable surfaces (affects pipeline complexity) |
+| `meta/constraints.md` → compliance section | Audit requirements, approval gates, compliance-mandated scanning |
+
+### Tier 1 — Self-answer from ideation
+
+- How many independently deployable artifacts exist?
+- Are there compliance requirements mandating specific CI/CD gates (security scanning, approval workflows)?
+- Is the project monorepo or polyrepo (affects CI/CD tooling)?
+
+### Tier 2 — Ask the user
+
+- Is there an existing CI/CD provider?
+- Deployment frequency expectations (continuous vs scheduled)?
+- Are manual approval gates needed for production deploys?
+
+---
+
+## Monitoring / Observability
+
+### Required Reads
+
+| File Pattern | What to Extract |
+|---|---|
+| Deep dives with performance/SLA mentions | Which features have SLA requirements driving alert thresholds |
+| `meta/constraints.md` → compliance section | Audit logging requirements, log retention mandates |
+| Every domain `{domain}-index.md` | Features with error-sensitive flows (payments, auth, data sync) |
+
+### Tier 1 — Self-answer from ideation
+
+- Which features are error-critical (payment flows, auth, data integrity)?
+- Are there SLA or uptime requirements from the ideation?
+- What audit logging is mandated by compliance?
+- Are there features requiring distributed tracing (multi-service request paths)?
+
+### Tier 2 — Ask the user
+
+- Is there an existing monitoring stack?
+- Budget for monitoring services?
+- On-call expectations (who gets alerted)?

package/template/.codex/skills/tech-stack-catalog/references/dev-tooling-decisions.md

@@ -0,0 +1,37 @@
+# Development Tooling Decisions
+
+## Tooling axes
+
+| Tool | Question |
+|------|----------|
+| **Package manager / build system** | pnpm, npm, yarn, bun, cargo, go modules, pip/poetry? |
+| **Test runner** | Vitest, Jest, pytest, cargo test, go test, XCTest? |
+| **Linter** | ESLint, Biome, Ruff, clippy, golangci-lint? |
+| **Type checker** | TypeScript (tsc), mypy, Rust compiler, Go compiler? |
+| **Build command** | What builds the project for production? |
+
+## Bootstrap keys to fire after confirmation
+
+After the user confirms all development tooling, fire bootstrap with `PIPELINE_STAGE=create-prd` and ALL of these keys:
+
+- `PACKAGE_MANAGER` — the confirmed package manager (e.g., `pnpm`)
+- `TEST_RUNNER` — the confirmed test runner (e.g., `vitest`)
+- `LINTER` — the confirmed linter (e.g., `eslint`)
+- `TYPE_CHECKER` — the confirmed type checker (e.g., `tsc`)
+- `TEST_COMMAND` — derived from package manager + test runner (e.g., `pnpm test`)
+- `TEST_WATCH_COMMAND` — derived test watch command (e.g., `pnpm test:watch`)
+- `TEST_COVERAGE_COMMAND` — derived coverage command (e.g., `pnpm test:coverage`)
+- `LINT_COMMAND` — derived lint command (e.g., `pnpm lint`)
+- `LINT_FIX_COMMAND` — derived lint fix command (e.g., `pnpm lint:fix`)
+- `FORMAT_COMMAND` — derived format command (e.g., `pnpm format`)
+- `TYPE_CHECK_COMMAND` — derived type-check command (e.g., `pnpm type-check`)
+- `BUILD_COMMAND` — derived build command (e.g., `pnpm build`)
+- `VALIDATION_COMMAND` — the full validation pipeline (e.g., `pnpm test && pnpm lint && pnpm type-check && pnpm build`)
+
+This fills command placeholders in `commands.md`, `workflow.md`, `implement-slice-tdd.md`, and `validate-phase.md`.
+
+## Validation command derivation
+
+```
+{{BUILD_TOOL}} test && {{BUILD_TOOL}} lint && {{BUILD_TOOL}} type-check && {{BUILD_TOOL}} build
+```

package/template/.codex/skills/tech-stack-catalog/references/surface-decision-tables.md

@@ -0,0 +1,69 @@
+# Surface Decision Tables
+
+## Universal decisions (all project types)
+
+| Axis | Decision Needed |
+|------|----------------|
+| **Primary language(s)** | TypeScript, Rust, Go, Python, Swift, Kotlin, C++, etc. |
+| **Database** | ⚠️ **Handled by Persistence Map Interview** in `create-prd-stack.md` — do NOT process as a single axis. Covers primary, vector, graph, cache, and time-series sub-keys. |
+| **Auth provider** | Firebase vs Auth0 vs Clerk vs custom vs OS-level keychain |
+| **CI/CD** | GitHub Actions vs GitLab CI vs custom |
+| **Monitoring** | Sentry vs Datadog vs custom |
+
+## Web surface decisions
+
+| Axis | Decision Needed |
+|------|----------------|
+| **Frontend framework** | SSR vs SSG vs hybrid, which framework (Next.js, Astro, SvelteKit, etc.) |
+| **Backend runtime** | Edge workers vs traditional server vs serverless |
+| **Hosting** | Cloudflare vs Vercel vs AWS vs self-hosted |
+| **CDN/Assets** | Provider-native vs S3 vs Cloudinary |
+
+## Desktop surface decisions
+
+| Axis | Decision Needed |
+|------|----------------|
+| **UI framework** | Tauri vs Electron vs native (GTK, Qt, SwiftUI, WPF, WinUI) |
+| **Cross-platform strategy** | Single OS, cross-platform with shared UI (Tauri, Electron, Flutter Desktop), or cross-platform with native UI per OS |
+| **Local data storage** | SQLite vs LevelDB vs filesystem vs embedded DB (RocksDB, etc.) |
+| **Distribution** | Installer type (MSI, DMG, AppImage, Flatpak), auto-updater strategy (Sparkle, squirrel, custom) |
+| **OS targets** | Windows, macOS, Linux — which combinations and minimum versions? |
+
+## Mobile surface decisions
+
+| Axis | Decision Needed |
+|------|----------------|
+| **Framework** | Native per-platform (Swift/Kotlin) vs cross-platform (React Native, Flutter, .NET MAUI, Kotlin Multiplatform) |
+| **Cross-platform strategy** | iOS-only, Android-only, or both? Shared codebase or separate? |
+| **Local data storage** | SQLite, Realm, Core Data, Room |
+| **Distribution** | App Store, Play Store, enterprise sideload, TestFlight/Firebase App Distribution |
+| **OS targets** | iOS minimum version, Android minimum API level |
+
+## Desktop + Mobile shared decisions
+
+Some frameworks support building for **both** desktop and mobile from one codebase. If the vision indicates this is desired:
+
+| Axis | Decision Needed |
+|------|----------------|
+| **Shared framework** | Flutter (desktop + mobile + web), Kotlin Multiplatform, .NET MAUI, Compose Multiplatform |
+| **Shared vs platform-specific UI** | Fully shared UI, shared logic with native UI per platform, or hybrid? |
+| **Platform-specific features** | What functionality requires native code per platform? (file system, notifications, hardware access) |
+
+## CLI surface decisions
+
+| Axis | Decision Needed |
+|------|----------------|
+| **Language** | Rust (clap), Go (cobra), Python (click/typer), Node (commander/yargs) |
+| **Distribution** | npm, cargo, homebrew, apt, binary releases (goreleaser, cross) |
+| **Shell integration** | Tab completions, man pages, config file format (TOML, YAML, JSON) |
+
+## Multi-surface connection decisions (2+ connected surfaces)
+
+| Axis | Decision Needed |
+|------|----------------|
+| **Shared API protocol** | REST vs gRPC vs GraphQL vs WebSocket between surfaces |
+| **Sync strategy** | Real-time (WebSocket/SSE), eventual consistency (message queue), batch (cron), offline-first (CRDT/merge) |
+| **Shared contract layer** | How are data shapes shared? Monorepo with shared package? Published npm/crate package? Code generation from OpenAPI/protobuf? |
+| **Auth federation** | Shared auth server with SSO? OAuth2 token exchange? Separate auth per surface? |
+| **Conflict resolution** | Last-write-wins, operational transform, CRDT, manual resolution, server-authoritative |
+| **Offline support** | Which surfaces work offline? What data is cached locally? How are conflicts resolved on reconnect? |

package/template/.codex/skills/technical-writer/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: Technical Writer
+description: Create clear, comprehensive technical documentation for any audience
+---
+
+# Technical Writer
+
+Create clear, comprehensive technical documentation for any audience.
+
+## When to Use This Skill
+- Write user documentation for a feature
+- Create a tutorial for setting up a development environment
+- Document system architecture
+- Write a troubleshooting guide
+- Create onboarding documentation for new developers
+- Write a README for a project
+
+## Instructions
+
+When a user needs technical documentation:
+
+1. **Identify Documentation Type**:
+   - User guide / end-user documentation
+   - Developer documentation / API docs
+   - System architecture documentation
+   - Tutorial / how-to guide
+   - Troubleshooting guide
+   - README file
+   - Release notes / changelog
+   - Onboarding documentation
+   - Knowledge base article
+   - Standard Operating Procedure (SOP)
+
+2. **Determine Audience**:
+   - Technical level (beginner, intermediate, expert)
+   - Role (end user, developer, admin, stakeholder)
+   - Prior knowledge assumptions
+   - Context (internal team, external customers, open source community)
+
+3. **Structure Documentation**:
+
+   **User Guide Format**:
+   ```markdown
+   # [Product/Feature Name]
+
+   ## Overview
+   [What it is, what it does, why use it - 2-3 sentences]
+
+   ## Prerequisites
+   - [Required knowledge]
+   - [Required tools/access]
+   - [System requirements]
+
+   ## Getting Started
+   [Quick start guide with minimal steps to first success]
+
+   ## Key Concepts
+   ### [Concept 1]
+   [Explanation with examples]
+
+   ## Common Tasks
+   ### How to [Task]
+   1. [Step]
+   2. [Step]
+   3. [Expected result]
+
+   ## Advanced Features
+   [Optional advanced functionality]
+
+   ## Troubleshooting
+   ### Problem: [Common issue]
+   **Symptoms**: [What users see]
+   **Solution**: [How to fix]
+
+   ## FAQ
+   **Q: [Question]**
+   A: [Answer]
+
+   ## Additional Resources
+   - [Link to related docs]
+   - [Support channels]
+   ```
+
+   **Tutorial Format**:
+   ```markdown
+   # How to [Accomplish Goal]
+
+   **Time required**: [X minutes]
+   **Difficulty**: [Beginner/Intermediate/Advanced]
+
+   ## What You'll Learn
+   - [Learning objective 1]
+   - [Learning objective 2]
+
+   ## Prerequisites
+   - [Required knowledge]
+   - [Tools needed]
+
+   ## Step-by-Step Instructions
+
+   ### 1. [First Major Step]
+   [Explanation of why this step matters]
+
+   ### 2. [Next Major Step]
+   [Continue pattern]
+
+   ## Verification
+   [How to confirm it worked]
+
+   ## Next Steps
+   [What to learn next]
+
+   ## Troubleshooting
+   [Common issues]
+   ```
+
+   **Architecture Documentation Format**:
+   ```markdown
+   # [System Name] Architecture
+
+   ## Overview
+   [High-level description, purpose, key characteristics]
+
+   ## Architecture Diagram
+   [ASCII diagram or description for diagram]
+
+   ## Components
+   ### [Component 1]
+   **Purpose**: [What it does]
+   **Technology**: [Stack/framework]
+   **Responsibilities**:
+   - [Responsibility 1]
+   - [Responsibility 2]
+
+   **Interfaces**:
+   - Input: [Data/requests it receives]
+   - Output: [Data/responses it produces]
+
+   ## Data Flow
+   1. [Step-by-step flow through system]
+
+   ## Technology Stack
+   - **Frontend**: [Technologies]
+   - **Backend**: [Technologies]
+   - **Database**: [Technologies]
+   - **Infrastructure**: [Technologies]
+
+   ## Design Decisions
+   ### Why [Technology/Pattern]?
+   [Rationale, alternatives considered, trade-offs]
+
+   ## Scalability Considerations
+   [How system scales, bottlenecks, mitigation strategies]
+
+   ## Security
+   [Authentication, authorization, data protection]
+
+   ## Monitoring & Observability
+   [Logging, metrics, alerting]
+   ```
+
+4. **Apply Technical Writing Best Practices**:
+
+   **Clarity**:
+   - Use short sentences (aim for 15-20 words)
+   - Avoid jargon or define it when first used
+   - Use active voice ("Click the button" not "The button should be clicked")
+   - Be specific ("Set timeout to 30 seconds" not "Set a reasonable timeout")
+
+   **Structure**:
+   - Use descriptive headings
+   - Break content into scannable sections
+   - Use numbered lists for sequences
+   - Use bullet points for unordered items
+   - Add table of contents for long docs
+
+   **Visuals**:
+   - Include screenshots with annotations
+   - Add code examples with syntax highlighting
+   - Use diagrams for complex concepts
+   - Show expected outputs
+   - Add tables for comparison or reference
+
+   **Code Examples**:
+   - Include language identifier
+   - Show both good and bad examples
+   - Add comments explaining complex parts
+   - Use realistic, runnable examples
+   - Include error handling
+
+   **User-Focused**:
+   - Start with most common use case
+   - Include "why" not just "how"
+   - Anticipate user questions
+   - Address common pitfalls
+   - Provide troubleshooting
+
+5. **Special Documentation Types**:
+
+   **README.md**:
+   - Project name and description
+   - Installation instructions
+   - Quick start example
+   - Features list
+   - Documentation links
+   - Contributing guidelines
+   - License
+
+   **Release Notes**:
+   - Version number and date
+   - New features
+   - Improvements
+   - Bug fixes
+   - Breaking changes
+   - Migration guide
+   - Deprecation notices
+
+   **Troubleshooting Guide**:
+   - Symptom-based organization
+   - Root cause analysis
+   - Step-by-step resolution
+   - Prevention tips
+   - When to escalate
+
+## Output Quality
+Ensure documentation:
+- Has clear, descriptive title
+- Starts with overview/context
+- Lists prerequisites upfront
+- Uses consistent formatting
+- Includes code examples where appropriate
+- Shows expected outputs
+- Has troubleshooting section
+- Uses appropriate technical level for audience
+- Is structured logically (simple to complex)
+- Includes visual aids (diagrams, screenshots)
+- Has table of contents for long docs
+- Links to related documentation
+- Is easy to scan
+- Uses active voice
+- Avoids ambiguity
+- Includes examples from user perspective