cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/utilities/resolve-skill.md

@@ -0,0 +1,195 @@
+---
+name: resolve-skill
+description: Dynamic skill resolution using 4-tier chain (exact match → partial match → external discovery → human escalation)
+parameters:
+  - name: surface
+    type: string
+    required: true
+    description: The surface to resolve skills for (e.g., "web", "api", "mobile")
+  - name: category
+    type: string
+    required: true
+    description: The skill category to resolve (e.g., "Languages", "Databases", "Unit Tests")
+  - name: cross_cutting
+    type: boolean
+    required: false
+    description: If true, resolve from Cross-Cutting Skills table instead of Per-Surface
+---
+
+## Overview
+
+The resolve-skill utility implements CFSA's 4-tier skill resolution chain, ensuring that workflows can dynamically load skills based on the Surface Stack Map while maintaining fallback options for missing or incomplete skill definitions.
+
+## Prerequisites
+
+1. `.codex/instructions/tech-stack.md` must exist and be populated
+2. Surface Stack Map must have at least one row
+3. For Per-Surface resolution: surface must exist in the table
+4. For Cross-Cutting resolution: category must exist in the Cross-Cutting table
+
+## Step-by-Step
+
+### Step 1 — Read Surface Stack Map
+
+1. Open `.codex/instructions/tech-stack.md`
+2. Parse the Per-Surface Skills table OR Cross-Cutting Skills table based on `cross_cutting` parameter
+3. Locate the row for the specified surface (Per-Surface) or category (Cross-Cutting)
+4. Extract the comma-separated skill list from the specified column
+
+**Example extraction:**
+```markdown
+Surface: web
+Category: Databases
+Result: "supabase, surrealdb, pglite"
+```
+
+### Step 2 — 4-Tier Resolution Chain
+
+For each skill in the comma-separated list, attempt resolution through each tier:
+
+#### Tier 1: Exact Match
+
+**Check**: Does `.codex/skills/{skill-name}/SKILL.md` exist?
+
+- **Yes**: Load the skill, add to resolved list, proceed to next skill
+- **No**: Proceed to Tier 2
+
+#### Tier 2: Partial Match + Adequacy Check
+
+**Check**: Does any skill in `.codex/skills/` partially match the name?
+
+**Partial match criteria:**
+- Name contains the skill name as a substring (case-insensitive)
+- OR skill name tags/include the required category in its SKILL.md frontmatter
+
+**Adequacy check:**
+- Read the matched skill's SKILL.md
+- Verify `category` field matches the requested category
+- Verify `surface` field (if present) includes the requested surface
+
+- **Pass**: Load the skill, add to resolved list with warning
+- **Fail**: Proceed to Tier 3
+
+#### Tier 3: External Discovery
+
+**Check**: Can the skill be found in external sources?
+
+**Discovery sources (in order):**
+1. `.codex/skill-library/` — Check if skill template exists in library
+2. Community skills — Search for skill in community repositories (if external search is enabled)
+3. Framework documentation — Check if framework/docs provide skill definitions
+
+**If found in skill-library:**
+- Prompt user: "Found '{skill}' in skill library. Install and provision?"
+- If yes: Call `setup-provision-skills` to install, then proceed to Tier 1
+- If no: Proceed to Tier 4
+
+#### Tier 4: Human Escalation
+
+**All previous tiers failed — escalate to human with options.**
+
+**Present to user:**
+```
+Skill '{skill}' for surface '{surface}', category '{category}' could not be resolved.
+
+Options:
+1. Provide a custom skill path — I'll use your skill file
+2. Skip this skill — I'll proceed without it (may limit functionality)
+3. Create a stub skill — I'll generate a basic skill template for you to customize
+4. Choose an alternative — I'll show you available skills in this category
+
+Which option would you like? (1-4)
+```
+
+**Handle user choice:**
+- **Option 1**: Accept path, verify SKILL.md exists, load skill
+- **Option 2**: Add to `missing` list in output, continue
+- **Option 3**: Generate stub skill at `.codex/skills/{skill}/SKILL.md`, load it
+- **Option 4**: List available skills, let user choose, restart resolution
+
+### Step 3 — Return Resolution Result
+
+After processing all skills in the comma-separated list, return:
+
+```json
+{
+  "resolved": [
+    ".codex/skills/supabase/SKILL.md",
+    ".codex/skills/surrealdb/SKILL.md"
+  ],
+  "missing": ["pglite"],
+  "warnings": [
+    "Partial match found for 'surrealdb' — using 'surrealdb-postgres' instead",
+    "Skill 'pglite' not found, skipped by user request"
+  ],
+  "surface": "web",
+  "category": "Databases"
+}
+```
+
+## Resolution Table
+
+| Tier | Check | Success Action | Failure Action |
+|------|-------|----------------|----------------|
+| 1 | Exact path match exists | Load skill, continue | Proceed to Tier 2 |
+| 2 | Partial match + adequate | Load with warning, continue | Proceed to Tier 3 |
+| 3 | Found in skill-library | Offer to install | Proceed to Tier 4 |
+| 4 | Human escalation | Present options, wait for choice | Block (requires user input) |
+
+## Integration with Workflows
+
+Workflows should call this utility via the Skill tool:
+
+```
+Call skill: `utilities/resolve-skill`
+- Input: {surface: "web", category: "Databases"}
+- Output: Use returned skill paths to load skills for current task
+```
+
+**Example workflow integration:**
+```markdown
+## workflow-write-be-spec.md
+
+### Step 1 — Load Database Skills
+
+Call skill: `utilities/resolve-skill`
+- surface: web (from shard directory path)
+- category: Databases
+
+For each resolved skill:
+1. Read SKILL.md
+2. Extract database schema patterns
+3. Apply to BE spec generation
+```
+
+## Error Handling
+
+| Error Scenario | Handling |
+|----------------|----------|
+| Surface Stack Map missing | Fail with clear error — run setup-cfsa first |
+| Surface not found in table | Fail with clear error — invalid surface |
+| Category column empty | Return empty resolved list (not an error) |
+| All tiers fail | Block on Tier 4 — human must decide |
+| User cancels during Tier 4 | Add to missing list, continue with other skills |
+
+## Completion Checklist
+
+- [ ] Surface Stack Map read successfully
+- [ ] All skills processed through 4-tier chain
+- [ ] Resolution result returned with resolved/missing/warnings
+- [ ] User informed of any warnings or missing skills
+- [ ] Workflow can proceed with resolved skills
+
+## Next Steps
+
+After resolving skills:
+- Load each resolved skill's SKILL.md
+- Extract relevant patterns and commands
+- Apply to current workflow task
+- If critical skills are missing, prompt user to complete setup
+
+## See Also
+
+- `.codex/instructions/tech-stack.md` — Surface Stack Map source
+- `.codex/skills/setup/setup-provision-skills.md` — Skill installation
+- `.codex/skills/setup/setup-cfsa.md` — Initial setup workflow

package/template/.codex/skills/validate-phase/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: validate-phase
+description: Orchestrate phase validation across code-quality and production-readiness gates with mandatory reporting and verdicting
+parameters:
+  - name: phase
+    type: string
+    required: false
+    description: Optional explicit phase identifier override
+---
+
+## Overview
+
+Runs validation in two shards: quality → readiness.
+
+
+## Prerequisites
+
+1. Phase slices are complete
+2. Required progress and standards documents exist
+3. Validation environment/tooling is available
+
+## Step-by-Step
+
+### Step 1 — Run quality shard
+
+Call skill: `validate-phase-quality`
+
+Expected outputs:
+- test/lint/type/build validation results
+- CI/CD, staging deploy, deployment strategy, migration checks
+- spec coverage sweep results
+
+### Step 2 — Run readiness shard
+
+Call skill: `validate-phase-readiness`
+
+Expected outputs:
+- gate applicability matrix
+- readiness gate results (API docs/a11y/perf/security/dependencies)
+- consolidated report in `.memory/wiki/specs/audits/phase-N-validation.md`
+- final pass/fail verdict + constrained next step recommendation
+
+## Quality Gate
+
+Do not close workflow unless all pass:
+- quality shard checks complete and passing
+- readiness shard checks complete and passing (or appropriately deferred per policy)
+- validation report written
+- explicit verdict determined
+
+## Completion Checklist
+
+- [ ] quality shard completed
+- [ ] readiness shard completed
+- [ ] validation report produced
+- [ ] verdict (pass/fail) captured
+- [ ] next-step recommendation emitted
+
+## Next Steps
+
+- if pass: `/update-architecture-map`
+- if fail: resolve findings and re-run `/validate-phase`

package/template/.codex/skills/validate-phase-quality/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: validate-phase-quality
+description: Execute code-quality gates for a completed phase including tests, coverage, lint, types, build, CI/CD, staging, migrations, and spec coverage
+parameters:
+  - name: phase
+    type: string
+    required: false
+    description: Optional explicit phase identifier override
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. All slices in target phase are marked complete
+
+## Step-by-Step
+
+### Step 0 — Validation skill loading and optional parallelism
+
+1. Load testing-strategist, code-review-pro, deployment-procedures skills.
+2. Optionally parallelize independent-slice validation checks where safe.
+
+### Step 1 — Test suite gate
+
+1. Run test command.
+2. If tests fail, stop with failing-slice report.
+
+### Step 2 — Coverage and mutation gates
+
+1. Run coverage command and enforce thresholds from engineering standards (or defaults).
+2. Run mutation testing for critical paths when supported.
+3. Enforce blocking/non-blocking outcomes per policy.
+
+### Step 3 — Static quality gates
+
+1. Run lint command (zero errors requirement).
+2. Run type-check command (zero errors requirement).
+3. Run build command (must succeed).
+
+### Step 4 — Delivery and deployment gates
+
+1. Verify CI/CD pipeline is green for latest phase commit.
+2. Deploy to staging and run smoke checks.
+3. Verify deployment strategy alignment with architecture doc when documented.
+4. Verify migrations are clean and rollback scripts exist.
+
+### Step 5 — Spec coverage sweep
+
+1. Run full spec coverage sweep across IA/BE/FE layers.
+2. Apply hard-stop behavior for uncovered mandatory scope.
+
+## Completion Checklist
+
+- [ ] tests pass
+- [ ] coverage thresholds pass
+- [ ] lint/type/build pass
+- [ ] CI/CD green
+- [ ] staging deployment + smoke checks pass
+- [ ] deployment strategy verification complete
+- [ ] migration verification complete
+- [ ] spec coverage sweep complete
+
+## Next Steps
+
+- Run `validate-phase-readiness`

package/template/.codex/skills/validate-phase-readiness/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: validate-phase-readiness
+description: Execute production-readiness gates with applicability control, consolidate validation report, and issue final readiness verdict
+parameters:
+  - name: phase
+    type: string
+    required: false
+    description: Optional explicit phase identifier override
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. Quality shard has completed successfully
+2. Quality-shard report section (`## Spec Coverage`) exists in phase validation audit file
+
+## Step-by-Step
+
+### Step 0 — Gate applicability matrix (mandatory first)
+
+1. Classify phase content against gate applicability rules.
+2. Build gate applicability table with always-on/content-triggered/deferred statuses.
+3. Apply single-deferral/deadline constraints.
+
+### Step 1 — API documentation sync gate (conditional)
+
+1. Run when applicability matrix marks as required.
+2. Verify OpenAPI/docs synchronization with implemented contracts and errors.
+
+### Step 2 — Accessibility gate (conditional)
+
+1. Run accessibility audit for changed UI components when applicable.
+
+### Step 3 — Performance gates
+
+1. Run budget verification against engineering standards when budgets exist.
+2. Enforce fail/warn behavior by classification.
+3. Run optional deep performance audit when tooling/skill is available.
+
+### Step 4 — Security and dependency gates
+
+1. Run adversarial and security-hardening reviews.
+2. Run DAST when configured/applicable.
+3. Run package manager vulnerability audit and enforce high/critical blocking rule.
+4. Run supplemental dependency-audit protocol when installed.
+
+### Step 5 — Feature ledger and boundary stub audits
+
+1. Verify must-have features assigned to phase are implemented.
+2. Audit active `BOUNDARY:` stubs for tracking/test/spec-status validity.
+
+### Step 6 — Report append and completion gating
+
+1. Verify quality shard already wrote spec coverage section.
+2. Append readiness sections to existing phase validation report.
+3. Update progress/memory/session artifacts.
+4. Present report with pass/fail verdict and constrained next steps.
+
+## Completion Checklist
+
+- [ ] applicability matrix completed
+- [ ] conditional gates executed or validly deferred
+- [ ] security/dependency gates passed
+- [ ] feature-ledger reconciliation passed
+- [ ] boundary stub audit passed
+- [ ] readiness sections appended to report
+- [ ] verdict presented with next-step guidance
+
+## Next Steps
+
+- if pass: `/update-architecture-map`
+- if fail: resolve findings and re-run `/validate-phase`

package/template/.codex/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: verification-before-completion
+description: "Use when about to claim work is complete, fixed, or passing — requires running verification commands and confirming output before making any success claims. Evidence before claims, always."
+version: 2.0.0
+source: self
+date_added: "2026-02-27"
+date_rewritten: "2026-03-14"
+---
+
+# Verification Before Completion
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this response, you cannot claim it passes. Period.
+
+## When to Apply
+
+**Before ANY of these:**
+- Claiming tests pass, build succeeds, or linter is clean
+- Expressing satisfaction ("Great!", "Done!", "All good!")
+- Committing, pushing, or creating a PR
+- Moving to the next task or slice
+- Reporting completion to the user
+
+## The Gate
+
+```
+1. IDENTIFY → What command proves this claim?
+2. RUN     → Execute it. Fresh. Complete. Not a cached result.
+3. READ    → Full output. Check exit code. Count failures.
+4. VERIFY  → Does the output support the claim?
+5. CLAIM   → Only now may you state the result.
+```
+
+Skip any step = the claim is unverified.
+
+## Evidence Standards
+
+| Claim | Required Evidence | Not Sufficient |
+|-------|-------------------|----------------|
+| "Tests pass" | Full test output showing 0 failures | Previous run, "should pass", partial suite |
+| "Build succeeds" | Build command output, exit code 0 | Linter passing (linter ≠ compiler) |
+| "Lint clean" | Linter output showing 0 errors/warnings | Build passing (build ≠ lint) |
+| "Bug fixed" | Reproduce original symptom → now passes | "I changed the code" |
+| "Regression test works" | Red-green cycle: fail → fix → pass | Test passes once without verifying it can fail |
+| "Requirements met" | Line-by-line checklist against acceptance criteria | "Tests pass" (tests may not cover requirements) |
+| "Migration works" | Run migration up AND down successfully | "Schema looks correct" |
+
+## Red-Green Verification (TDD)
+
+When claiming a regression test is valid:
+
+```
+1. Write test
+2. Run test → MUST FAIL (Red)
+3. Implement fix
+4. Run test → MUST PASS (Green)
+5. Revert fix temporarily
+6. Run test → MUST FAIL AGAIN (proves test is meaningful)
+7. Restore fix
+8. Run test → Passes (final confirmation)
+```
+
+If the test never fails, it proves nothing.
+
+## Red Flags — Stop and Verify
+
+Catch yourself if you're about to say:
+
+| Phrase | What to Do Instead |
+|--------|-------------------|
+| "Should work now" | Run the command |
+| "I'm confident this is correct" | Confidence ≠ evidence |
+| "Looks like it should pass" | Looks ≠ verified |
+| "Just this once I'll skip" | No exceptions |
+| "The linter passed so the build should too" | They check different things |
+| "I changed the right file" | Run the test |
+| "The agent said it succeeded" | Verify independently |
+
+## Integration with Pipeline
+
+This skill reinforces the pipeline's `completion-checklist` rule:
+
+1. **Code** — implementation meets the contract ← verified by tests
+2. **Tests** — all pass ← verified by running them RIGHT NOW
+3. **Tracking** — progress files updated ← verified by reading them
+4. **Locks** — claims removed ← verified by checking
+
+## The Bottom Line
+
+**Run the command. Read the output. Count the failures. THEN make the claim.**
+
+This is non-negotiable. The cost of verification is 30 seconds. The cost of a false claim is broken trust, shipped bugs, and wasted debugging time downstream.

package/template/.codex/skills/verify-infrastructure/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: verify-infrastructure
+description: Run operational infrastructure verification gates for workspace/infrastructure/auth checkpoints and emit pass/fail audit report
+parameters:
+  - name: trigger
+    type: string
+    required: false
+    description: Optional trigger override (workspace|infrastructure|auth)
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Run placeholder/map completeness audit.
+2. Determine trigger and initialize report filename.
+3. Verify CI/CD config and latest pipeline green status.
+4. Run environment/secrets audit.
+5. Verify migrations and rollback readiness.
+6. Verify staging deployment + health checks.
+7. Run conditional auth smoke test.
+8. Run logging and error-tracking gates.
+9. Run spec-pipeline integrity check.
+10. Finalize report with verdict and next-step guidance.

package/template/.codex/skills/workflow-automation/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: workflow-automation
+description: "Architect durable, event-driven workflows using step functions, retry strategies, idempotency, fan-out patterns, and the critical differences between orchestration approaches."
+version: 2.0.0
+---
+
+# Workflow Automation
+
+You are a workflow architect who understands the fundamental tradeoff: **simplicity vs. correctness**. Every workflow platform sits somewhere on that spectrum. Your job is to pick the right point for the user's situation and implement it correctly.
+
+## When to Use
+
+- Background jobs that must complete even if the server restarts
+- Multi-step processes where partial completion is worse than failure (payments, onboarding)
+- Event-driven architectures where one event triggers multiple independent reactions
+- Scheduled/recurring tasks that need observability and retry guarantees
+- Any process where "it probably ran" is not acceptable
+
+## When NOT to Use
+
+- Simple fire-and-forget tasks (use a queue or a delay)
+- Synchronous request-response flows
+- Tasks under 100ms that don't involve external services
+
+## Ecosystem-Specific References
+
+After reading the methodology below, read the reference matching your orchestration platform:
+
+| Platform | Reference | Best For |
+|----------|-----------|----------|
+| Inngest | `references/inngest.md` | Serverless, event-driven, fast shipping |
+| Temporal | `references/temporal.md` | Complex orchestration, human-in-the-loop |
+| BullMQ | `references/bullmq.md` | Simple job queues, rate limiting, Redis stack |
+
+---
+
+## Core Concept: Durable Execution
+
+**Wrap each unit of work in a step, so the system can retry, resume, and checkpoint independently.**
+
+```
+Without durable execution:
+  fetch data → process → save → send email
+           ↑ server crashes here
+           ↓ entire pipeline reruns from scratch
+           ↓ customer gets duplicate email
+
+With durable execution:
+  step("fetch")   ✓ saved
+  step("process") ✓ saved
+  step("save")    ← server crashes here
+  step("save")    ← retries ONLY this step
+  step("email")   ✓ runs once
+```
+
+---
+
+## Platform Decision Matrix
+
+| Factor | Inngest | Temporal | BullMQ |
+|--------|---------|----------|--------|
+| **Complexity** | Low (serverless functions) | High (workers + server) | Medium (Redis-backed) |
+| **Durability** | Steps checkpointed | Full workflow replay | Job-level retry |
+| **Infrastructure** | Managed or self-hosted | Requires Temporal Server | Requires Redis |
+| **Best for** | Serverless, event-driven | Complex orchestration | Simple job queues |
+| **Learning curve** | 1-2 days | 1-2 weeks | 1-2 days |
+| **Language support** | TS, Python, Go | TS, Go, Java, Python, .NET | TS/JS only |
+
+### Decision Rules
+
+1. **Serverless + event-driven?** → Inngest
+2. **Complex orchestration, human-in-the-loop, multi-day?** → Temporal
+3. **Simple job queue, Redis already in stack?** → BullMQ
+4. **Team of 1-3, shipping fast?** → Inngest
+5. **Enterprise, compliance-heavy, Java/.NET stack?** → Temporal
+
+---
+
+## Pattern 1: Sequential Steps
+
+Each step depends on the previous result. Steps checkpoint independently.
+
+```
+step("create-db-record")       → returns user
+step("create-stripe-customer") → uses user.email
+step("send-welcome-email")     → uses user.email
+```
+
+If step 2 fails, only step 2 retries. Steps 1 and 3 are not re-executed.
+
+---
+
+## Pattern 2: Fan-Out (Parallel Execution)
+
+One event triggers multiple independent workflows. Each runs and retries independently.
+
+```
+Event: user/signup.completed
+  → Workflow A: send-welcome-email   (independent)
+  → Workflow B: create-stripe-trial  (independent)
+  → Workflow C: provision-workspace  (independent)
+```
+
+If Workflow B fails, Workflows A and C are unaffected.
+
+---
+
+## Pattern 3: Idempotency
+
+Prevent duplicate execution when the same event fires twice.
+
+**Rule:** Idempotency at the workflow level AND the external call level. Belt and suspenders.
+
+- **Workflow level:** Deduplicate by event ID or business key (e.g., order ID)
+- **External call level:** Use idempotency keys on payment APIs, email sends, etc.
+
+---
+
+## Pattern 4: Scheduled/Recurring
+
+Cron-triggered workflows with observability:
+- Scheduled trigger (e.g., daily at 9am)
+- Steps checkpoint independently
+- Failed runs are visible, retriable, and alertable
+
+---
+
+## Pattern 5: Human-in-the-Loop
+
+Workflows that pause and wait for external input — approval flows, multi-day processes.
+
+```
+workflow: purchaseWorkflow(amount)
+  if amount > threshold:
+    pause and wait for approval signal (up to 72h)
+    if no approval → deny
+  continue with purchase
+```
+
+---
+
+## Sharp Edges
+
+| Issue | Severity | Rule |
+|-------|----------|------|
+| No idempotency keys on external calls | Critical | ALWAYS use idempotency keys for payments, emails, mutations |
+| Side effects in workflow code (Temporal) | Critical | Workflows must be deterministic — no I/O, no random, no clock |
+| Giant payloads in step results | High | Steps serialize data — keep under 256KB |
+| No timeouts on activities | High | ALWAYS set timeouts — default infinite hangs forever |
+| Linear retry without backoff | Medium | ALWAYS use exponential backoff |
+| Missing dead letter handling | High | Failed-after-all-retries jobs need a destination |
+| Monolithic workflows | Medium | Break workflows >10 steps into child workflows |
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| `setTimeout(fn, 3600000)` for delays | Platform sleep — survives restarts |
+| Global variables for workflow state | Step results and explicit state passing |
+| Retry loops in application code | Platform-level retry policies |
+| Polling in a loop for completion | Event-driven triggers or workflow signals |
+| One giant function with all logic | Decompose into steps/activities |
+
+## Related Skills
+
+Works with: `error-handling-patterns`, `deployment-procedures`