cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/bootstrap-agents/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: bootstrap-agents
+description: "Utility — fill the surface stack map in tech-stack.md and provision skills using intelligent resolution. Called by pipeline commands when tech stack info changes."
+version: 3.0.0
+---
+
+# Bootstrap Agents
+
+**This is a utility command, not an entry point.** It gets called by other pipeline commands (like `/create-prd`, `/write-be-spec`, `/write-fe-spec`, `/implement-slice`) whenever they make tech stack decisions or introduce new dependencies.
+
+Bootstrap does two things:
+1. **Fill the surface stack map** in `.codex/instructions/tech-stack.md` with stack decisions
+2. **Provision skills** from `skill-library/` using the 4-tier resolution chain
+
+**Input**: Surface-keyed stack values + optional global values
+**Output**: Filled map cells + newly installed skills in `.codex/skills/`
+
+---
+
+## 1. Receive values
+
+The calling command provides values in two categories:
+
+### Surface-Keyed Values (fill the Per-Surface Skills table)
+
+Each value is tagged with a surface. Format: `SURFACE=<surface> KEY=<value>`
+
+Example invocation from `/create-prd-stack`:
+```
+SURFACE=shared  LANGUAGES=typescript  BE_FRAMEWORKS=hono  DATABASES=supabase,surrealdb  ORMS=drizzle
+SURFACE=web     LANGUAGES=typescript  FE_FRAMEWORKS=astro  FE_DESIGN=tailwind,vanilla-css  STATE_MGMT=nanostores  DATABASES=supabase,surrealdb  UNIT_TESTS=vitest  E2E_TESTS=playwright
+SURFACE=desktop LANGUAGES=typescript,rust  FE_FRAMEWORKS=—  BE_FRAMEWORKS=tauri  DATABASES=supabase,surrealdb,pglite,surrealdb-embedded  UNIT_TESTS=vitest,cargo-test
+```
+
+Per-surface column keys:
+
+| Column Key | Map Column | Example |
+|-----------|------------|---------|
+| `LANGUAGES` | Languages | typescript, rust |
+| `BE_FRAMEWORKS` | BE Frameworks | hono, tauri |
+| `FE_FRAMEWORKS` | FE Frameworks | astro, react-native |
+| `FE_DESIGN` | FE Design | tailwind, vanilla-css |
+| `ORMS` | ORMs | drizzle |
+| `STATE_MGMT` | State Mgmt | nanostores, zustand |
+| `DATABASES` | Databases | supabase, surrealdb, pglite |
+| `UNIT_TESTS` | Unit Tests | vitest, cargo-test |
+| `E2E_TESTS` | E2E Tests | playwright, detox |
+| `TEST_CMD` | Test Cmd | npm test |
+| `VALIDATION_CMD` | Validation Cmd | npm run validate |
+| `LINT_CMD` | Lint Cmd | npm run lint |
+| `BUILD_CMD` | Build Cmd | npm run build |
+| `DEV_CMD` | Dev Cmd | npm run dev |
+| `PACKAGE_MGR` | Package Mgr | npm |
+
+### Cross-Cutting Values (fill the Cross-Cutting Skills table)
+
+These are project-wide, not per-surface:
+
+| Key | Map Category | Example |
+|-----|-------------|---------|
+| `AUTH` | Auth | clerk, supabase-auth |
+| `CI_CD` | CI/CD | github-actions |
+| `HOSTING` | Hosting | vercel, tauri-updater |
+| `SECURITY` | Security | owasp-web, desktop-sandboxing |
+| `API_DESIGN` | API Design | api-design-principles |
+| `ACCESSIBILITY` | Accessibility | accessibility |
+| `CONTRACT_LIBRARY` | Contract Library | zod |
+
+### Global Values (fill Global Settings in tech-stack.md + root configs)
+
+| Key | Example |
+|-----|---------|
+| `PROJECT_NAME` | RepairYour.Tech |
+| `DESCRIPTION` | One-line description |
+| `TECH_STACK_SUMMARY` | Supabase + SurrealDB + Astro + Tauri |
+| `SURFACES` | web, desktop, mobile |
+| `ARCHITECTURE_DOC` | .memory/wiki/specs/2026-03-13-architecture-design.md |
+
+### Structural Values (fill instruction templates — unchanged from v2)
+
+| Key | Example |
+|-----|---------|
+| `FRAMEWORK_PATTERNS` | Framework-specific patterns block |
+| `PROJECT_STRUCTURE` | Directory layout block |
+| `ARCHITECTURE_TABLE` | Concern/Location/Runtime table rows |
+
+### Infrastructure Values (fill instruction templates — unchanged from v2)
+
+| Key | Example |
+|-----|---------|
+| `SSH_HOST` | my-vps |
+| `DB_PORT` | 19000 |
+| `CREDENTIAL_TOOL` | agent-auth ssh-add |
+| `SECRET_MANAGEMENT` | wrangler secret |
+| `DEPLOY_COMMAND` | wrangler deploy |
+
+If any values are missing, leave those cells empty — they'll be filled on a future invocation.
+
+---
+
+## 2. Fill the surface stack map
+
+Open `.codex/instructions/tech-stack.md` and update:
+
+### 2a. Per-Surface Skills table
+
+For each `SURFACE=<name>` received:
+1. If a row for `<name>` exists → update the cells for the provided column keys only (don't overwrite cells that already have values unless explicitly re-provided)
+2. If no row exists → add a new row with the provided values, `—` for unprovided columns
+
+### 2b. Cross-Cutting Skills table
+
+For each cross-cutting key received, update the corresponding category row. If the value is additive (e.g., adding a second database), **append** to the comma-separated list rather than overwriting. If the value is already present, skip (idempotent).
+
+### 2c. Global Settings
+
+Fill the Global Settings table with any provided global values.
+
+---
+
+## 3. Fill root agent config files
+
+Replace in **both** `AGENTS.md` and `GEMINI.md`:
+- `{{PROJECT_NAME}}`
+- `{{DESCRIPTION}}`
+- `{{TECH_STACK_SUMMARY}}`
+- `{{VALIDATION_COMMAND}}` — use the **primary surface's** validation command from the map (first non-shared row, or shared if only shared exists)
+- `{{ARCHITECTURE_DOC}}`
+- `{{CONTRACT_LIBRARY}}`
+- `{{INSTALLED_SKILLS}}` (if provided; otherwise leave for step 8)
+
+> **Note**: Both files serve as root agent config. Both must be kept in sync — any value filled in one must be filled in the other.
+
+---
+
+## 4. Fill instruction templates
+
+### `.codex/instructions/commands.md`
+Write per-surface command sections. For each surface in the map, create a section with its commands (Test Cmd, Validation Cmd, Lint Cmd, Build Cmd, Dev Cmd, Package Mgr).
+
+### `.codex/instructions/workflow.md`
+Fill `{{VALIDATION_COMMAND}}` with the primary surface's validation command.
+
+### `.codex/instructions/patterns.md`
+Replace `{{FRAMEWORK_PATTERNS}}` if provided.
+
+### `.codex/instructions/structure.md`
+Replace `{{PROJECT_STRUCTURE}}`, `{{ARCHITECTURE_TABLE}}` if provided.
+
+---
+
+## 5. Fill operational skill and rule templates
+
+Scan `.codex/skills/*/SKILL.md` and `.codex/rules/*.md` for `{{PLACEHOLDER}}` values and fill any that match the provided values. Currently applicable:
+
+- `{{VALIDATION_COMMAND}}` — in `fix-bug`, `main-workflow`, `deploy`, `refactor`
+- `{{PACKAGE_MANAGER}}` — in `refactor`, `security-audit`
+- `{{CONTRACT_LIBRARY}}` — in `tdd-contract-first.md`
+- Other command/infra placeholders as documented in v2
+
+---
+
+## 6. Read skill library manifest
+
+Read `skill-library/MANIFEST.md` to load the trigger tables.
+
+If `skill-library/MANIFEST.md` does not exist, skip steps 7-8 and go to step 9.
+
+---
+
+## 7. Provision skills — 4-Tier Resolution Chain
+
+For each skill name referenced in ANY cell of the surface stack map, resolve it using this chain:
+
+### Tier 1: Exact Match
+Check `.codex/skill-library/{name}/` (or `.codex/skills/{name}/` if already installed).
+- **Found in library** AND not yet installed → copy to `.codex/skills/{name}/`, fill any `{{PLACEHOLDER}}`s in the copied SKILL.md
+- **Already installed** → skip (idempotent)
+- **Not found** → proceed to Tier 2
+
+### Tier 2: Partial Match + Adequacy Check
+Search `.codex/skill-library/` and `.codex/skills/` for skills whose name contains the base term. E.g., for `surrealdb-embedded`, check if `surrealdb` exists.
+
+- **Partial match found** → Read its `SKILL.md`. Assess: does it cover the needed variant? Check for keywords related to the specific need (e.g., "embedded", "WASM", "Rust-native" for `surrealdb-embedded`).
+  - **Adequate** — the existing skill covers the variant → use it. Note in the report: `"{name}" resolved by existing "{partial}" skill (covers {variant})`.
+  - **Falls short** — the skill doesn't address the specific variant → proceed to Tier 3
+- **No partial match** → proceed to Tier 3
+
+### Tier 3: External Discovery
+Read `.codex/skills/find-skills/SKILL.md` and invoke its discovery methodology to search for the skill externally.
+
+- **Found** → install → fill map cell with resolved name
+- **Not found** → proceed to Tier 4
+
+### Tier 4: Human Escalation
+Mark the map cell with `⚠️ {name} [not found]`. Include in the report:
+
+> "Skill `{name}` was not found in the skill library, via partial match, or externally. Options:
+> 1. Create it with `/skill-creator`
+> 2. Provide an alternative skill name
+> 3. Mark as not needed (change cell to `—`)"
+
+### Resolution reporting
+After resolving all skills, report:
+- Which skills were installed (Tier 1)
+- Which skills were resolved by adequacy check (Tier 2) — include justification
+- Which skills were discovered externally (Tier 3)
+- Which skills need human attention (Tier 4) — include the `⚠️` cells
+
+---
+
+## 8. Update installed skills list
+
+After provisioning, build a markdown list of all installed skills and update `{{INSTALLED_SKILLS}}` in `tech-stack.md`:
+
+```markdown
+### Default Skills
+- fix-bug — TDD bug fix workflow
+- refactor — Safe refactoring with test verification
+- ...
+
+### Stack Skills (Per-Surface)
+- [skill-name] — [description] (surface: [surface], column: [column])
+- ...
+
+### Stack Skills (Cross-Cutting)
+- [skill-name] — [description] (category: [category])
+- ...
+
+### Surface Skills
+- [skill-name] — [description] (installed for [surface] surface)
+- ...
+```
+
+---
+
+## 9. Report results
+
+Present the results to the calling command (not directly to the user — the calling command handles user communication):
+
+- Which map cells were filled (and their values)
+- Which map cells remain empty
+- Skill resolution report (from step 7)
+- Which skills were already installed and skipped
+- Any `⚠️` cells requiring user attention
+- Any errors (missing files, missing library paths)
+
+---
+
+## Idempotency
+
+Bootstrap is safe to call multiple times:
+
+- **Already-filled map cells**: Cells with values are NOT overwritten unless the calling command explicitly re-provides a value for that surface + column
+- **Already-installed skills**: Skills that already exist in `.codex/skills/` are not re-copied from the library
+- **New surface rows**: New surfaces trigger new row creation without affecting existing rows
+- **Appending values**: Cross-cutting skills and accumulated columns append to existing comma-separated lists without duplicating
+- **Partial invocation**: Bootstrap can be called with just one surface or one key — it only fills what's provided

package/template/.codex/skills/bootstrap-agents-fill/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: bootstrap-agents-fill
+description: Fill surface stack map, instruction templates, and root config placeholders from provided key-value updates
+parameters:
+  - name: values
+    type: object
+    required: true
+    description: Placeholder values and surface/cross-cutting map updates
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Apply per-surface updates in `.codex/instructions/tech-stack.md` without clobbering unrelated filled cells.
+2. Apply cross-cutting and global settings updates.
+3. Fill instruction templates (`commands.md`, `workflow.md`, `patterns.md`, `structure.md`) where values are provided.
+4. Sync root config placeholders in `AGENTS.md` and `GEMINI.md`.
+5. Fill operational skill/rule placeholders where mappings exist.
+6. Emit fill report and hand off to provisioning shard.
+
+## Rule
+
+If no values are provided, report no-op and exit.

package/template/.codex/skills/bootstrap-agents-provision/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: bootstrap-agents-provision
+description: Resolve all map-referenced skills through 4-tier chain and provision installs with idempotent updates
+parameters:
+  - name: strict
+    type: boolean
+    required: false
+    description: If true, fail when unresolved skills remain
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Read stack map and manifest.
+2. Resolve each referenced skill name using: exact → partial+adequacy → external discovery → human escalation.
+3. Install resolved skills idempotently into `.codex/skills/`.
+4. Update installed-skills sections in stack map and root config files.
+5. Compose `FRAMEWORK_PATTERNS` when frontend-capable frameworks are present and route back through fill.
+6. Resolve and fill `CONTRACT_LIBRARY` per language set.
+7. Emit final provisioning report with unresolved items and actions.

package/template/.codex/skills/brainstorming/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: brainstorming
+description: "Use before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements, and design before implementation."
+version: 2.0.0
+source: self
+date_added: "2026-02-27"
+date_rewritten: "2026-03-14"
+---
+
+# Brainstorming Ideas Into Designs
+
+Turn raw ideas into **clear, validated designs** through structured dialogue **before any implementation begins**.
+
+## When to Use
+
+- User describes a new feature, component, or behavior change
+- Task involves creative decisions (not just execution of a clear spec)
+- Requirements are ambiguous or incomplete
+- Work could go in multiple valid directions
+
+## When NOT to Use
+
+- Task has a clear spec with acceptance criteria (just implement it)
+- Fixing a bug with obvious cause (just fix it)
+- During `/plan-phase` or `/implement-slice` (those have their own structure)
+- Trivial changes (rename a variable, fix a typo)
+
+## Operating Mode
+
+You are a **design facilitator**, not a builder. While this skill is active:
+
+- No coding, no file modifications
+- No speculative features — only design what's been discussed
+- No silent assumptions — every assumption gets stated explicitly
+- No skipping ahead — each gate must be passed before proceeding
+
+---
+
+## The Process
+
+### 1. Scan Context (Before Asking Anything)
+
+Read the relevant project state:
+- Existing code in the affected area
+- Related specs, plans, or prior decisions
+- Recent changes that might affect the design
+
+Note what already exists vs. what's proposed. Identify implicit constraints.
+
+**Do not design yet.**
+
+### 2. Understand the Idea
+
+**One question at a time.** Do not dump a list of 10 questions.
+
+Prefer multiple-choice when possible:
+> "Should this component handle errors inline or delegate to a parent error boundary?
+> A) Inline (self-contained)
+> B) Delegate (parent handles)
+> C) Hybrid (catch critical, delegate non-critical)"
+
+Focus on understanding:
+- **Purpose** — what problem does this solve?
+- **Users** — who uses it and how?
+- **Constraints** — performance, security, compatibility limits
+- **Success criteria** — how do we know it's working?
+- **Non-goals** — what is explicitly out of scope?
+
+### 3. Non-Functional Requirements
+
+Before any design, clarify or propose defaults for:
+
+| Requirement | If User Is Unsure |
+|-------------|-------------------|
+| Performance | Propose: "P95 < 200ms for API, <3s for page load" |
+| Scale | Propose: "Support 1K concurrent users initially" |
+| Security | Default: input validation, auth required, no PII in logs |
+| Reliability | Propose: "99.5% uptime, graceful degradation" |
+| Maintenance | "Maintained by your team, or handed off?" |
+
+Mark all proposals as **assumptions** that the user can override.
+
+### 4. Understanding Lock (Hard Gate)
+
+**Before proposing any design**, present:
+
+```markdown
+## Understanding Summary
+- **Building**: [what]
+- **Purpose**: [why]
+- **Users**: [who]
+- **Key constraints**: [limits]
+- **Non-goals**: [explicitly excluded]
+
+## Assumptions
+- [Each assumption stated clearly]
+
+## Open Questions
+- [Any unresolved items]
+```
+
+Then ask: *"Does this accurately reflect your intent? Please confirm or correct before we move to design."*
+
+**Do NOT proceed until confirmed.**
+
+### 5. Explore Design Approaches
+
+Present **2-3 viable approaches**:
+
+1. **Recommended** — lead with this, explain why
+2. **Alternative** — different tradeoff (simpler but less extensible, etc.)
+3. **Alternative** — if genuinely different from #2
+
+For each approach, cover:
+- Complexity estimate (low/medium/high)
+- Extensibility (how easy to evolve later)
+- Risk (what could go wrong)
+- Implementation effort (rough scope)
+
+Apply **YAGNI ruthlessly** — remove unnecessary features from all approaches.
+
+### 6. Present Design (Incrementally)
+
+Break the design into sections of **200-300 words max**. After each section:
+
+> "Does this look right so far?"
+
+Cover as relevant:
+- Architecture / component structure
+- Data flow and state management
+- Error handling and edge cases
+- Testing strategy
+- Integration points
+
+### 7. Decision Log
+
+Maintain a running log:
+
+```markdown
+| Decision | Alternatives | Rationale |
+|----------|-------------|-----------|
+| Use event-driven sync | Polling, webhooks | Lower latency, less server load |
+| SQLite over PostgreSQL | PostgreSQL | Single-user app, simpler deployment |
+```
+
+This log survives into the final design document.
+
+---
+
+## Exit Criteria
+
+You may exit brainstorming **only when ALL are true**:
+
+- [ ] Understanding Lock confirmed by user
+- [ ] At least one design approach explicitly accepted
+- [ ] Assumptions documented and acknowledged
+- [ ] Key risks identified
+- [ ] Decision Log complete
+
+If any criterion is unmet → continue refinement. Do NOT proceed to implementation.
+
+## After Brainstorming
+
+1. Write the design to `.memory/wiki/specs/YYYY-MM-DD-<topic>-design.md`
+2. Include: understanding summary, assumptions, decision log, final design
+3. Ask: "Ready to set up for implementation?"
+4. If yes, hand off to the appropriate pipeline command (`/plan-phase`, `/implement-slice`, etc.)
+
+## Key Principles
+
+1. **One question at a time** — never overwhelm
+2. **Multiple choice preferred** — easier to answer
+3. **Assumptions must be explicit** — never silently assume
+4. **YAGNI ruthlessly** — remove unnecessary features
+5. **Explore alternatives** — always 2-3 approaches
+6. **Incremental validation** — present in sections, validate each
+7. **Clarity over cleverness** — simple > smart

package/template/.codex/skills/brand-guidelines/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: brand-guidelines
+description: "Apply the confirmed design direction to all visual surfaces. If `{{DESIGN_DIRECTION}}` still appears as a literal placeholder, the design direction has not been confirmed — run `/create-prd` first."
+---
+
+# {{PROJECT_NAME}} Brand Guidelines
+
+> **Status**: {{#if DESIGN_DIRECTION}}Active{{else}}⚠️ UNFILLED — Run /create-prd to confirm design direction before using this skill{{/if}}
+
+## Design Direction
+
+- **Confirmed direction**: {{DESIGN_DIRECTION}}
+- **Rationale**: {{DESIGN_DIRECTION_RATIONALE}}
+- **Primary audience**: {{DESIGN_AUDIENCE}}
+
+## Color Palette
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Primary | {{PRIMARY_COLOR}} | Main brand color — buttons, links, key UI elements |
+| Secondary | {{SECONDARY_COLOR}} | Supporting color — secondary actions, accents |
+| Accent | {{ACCENT_COLOR}} | Highlight color — notifications, badges, emphasis |
+| Background | {{BACKGROUND_COLOR}} | Page/app background |
+| Text | {{TEXT_COLOR}} | Primary text color |
+
+## Typography
+
+| Role | Font | Usage |
+|------|------|-------|
+| Heading | {{HEADING_FONT}} | Page titles, section headers, display text |
+| Body | {{BODY_FONT}} | Paragraphs, descriptions, UI labels |
+| Mono | {{MONO_FONT}} | Code blocks, terminal output, technical values |
+
+## Motion Philosophy
+
+{{MOTION_PHILOSOPHY}}
+
+## Existing Brand Assets
+
+{{EXISTING_BRAND_ASSETS}}
+
+## What to Avoid
+
+{{DESIGN_AVOID}}