cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/workflow-automation/references/inngest.md

@@ -0,0 +1,88 @@
+# Inngest Workflow Patterns
+
+Ecosystem-specific patterns for the `workflow-automation` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Sequential Steps
+
+```typescript
+const syncUser = inngest.createFunction(
+  { id: "sync-user-data" },
+  { event: "user/signup.completed" },
+  async ({ event, step }) => {
+    const user = await step.run("create-db-record", async () => {
+      return db.users.create({ email: event.data.email });
+    });
+
+    const stripeCustomer = await step.run("create-stripe-customer", async () => {
+      return stripe.customers.create({ email: user.email });
+    });
+
+    await step.run("send-welcome-email", async () => {
+      return email.send({ to: user.email, template: "welcome" });
+    });
+  }
+);
+```
+
+## Fan-Out
+
+```typescript
+// Each function subscribes to the same event — runs independently
+const sendWelcome = inngest.createFunction(
+  { id: "send-welcome-email" },
+  { event: "user/signup.completed" },
+  async ({ event, step }) => {
+    await step.run("send", async () => {
+      await email.send({ to: event.data.email, template: "welcome" });
+    });
+  }
+);
+
+const startTrial = inngest.createFunction(
+  { id: "start-stripe-trial" },
+  { event: "user/signup.completed" },
+  async ({ event, step }) => {
+    await step.run("create-trial", async () => {
+      await stripe.subscriptions.create({
+        customer: event.data.stripeId,
+        trial_period_days: 14,
+      });
+    });
+  }
+);
+```
+
+## Idempotency
+
+```typescript
+const processPayment = inngest.createFunction(
+  {
+    id: "process-payment",
+    idempotency: "event.data.orderId", // Dedup within 24h
+  },
+  { event: "order/payment.requested" },
+  async ({ event, step }) => {
+    await step.run("charge", async () => {
+      return stripe.charges.create({
+        amount: event.data.amount,
+        idempotencyKey: event.data.orderId, // Stripe-level too
+      });
+    });
+  }
+);
+```
+
+## Scheduled/Recurring
+
+```typescript
+const dailyReport = inngest.createFunction(
+  { id: "daily-metrics-report" },
+  { cron: "0 9 * * *" }, // 9am daily
+  async ({ step }) => {
+    const metrics = await step.run("fetch-metrics", fetchDailyMetrics);
+    await step.run("send-report", async () => sendSlackReport(metrics));
+  }
+);
+```

package/template/.codex/skills/workflow-automation/references/temporal.md

@@ -0,0 +1,64 @@
+# Temporal Workflow Patterns
+
+Ecosystem-specific patterns for the `workflow-automation` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Sequential Steps (Activities)
+
+```typescript
+// activities.ts
+export async function createDbRecord(email: string): Promise<User> {
+  return db.users.create({ email });
+}
+
+export async function createStripeCustomer(email: string): Promise<Customer> {
+  return stripe.customers.create({ email });
+}
+
+// workflows.ts
+const { createDbRecord, createStripeCustomer } = proxyActivities<typeof activities>({
+  startToCloseTimeout: "30 seconds",
+  retry: { initialInterval: "1s", maximumAttempts: 3 },
+});
+
+export async function syncUserWorkflow(email: string): Promise<void> {
+  const user = await createDbRecord(email);
+  const customer = await createStripeCustomer(user.email);
+}
+```
+
+## Human-in-the-Loop (Signals)
+
+```typescript
+export const approvalSignal = defineSignal<[boolean]>("approval");
+
+export async function purchaseWorkflow(amount: number): Promise<string> {
+  if (amount > 10000) {
+    let approved: boolean | undefined;
+
+    setHandler(approvalSignal, (isApproved) => {
+      approved = isApproved;
+    });
+
+    // Workflow sleeps until signal or 72h timeout
+    const gotApproval = await condition(() => approved !== undefined, "72 hours");
+
+    if (!gotApproval || !approved) {
+      return "Purchase denied or timed out";
+    }
+  }
+
+  return "Purchase completed";
+}
+```
+
+## Critical Rule: Determinism
+
+Temporal workflows replay from the beginning on recovery. **Workflow code must be deterministic:**
+- ❌ No I/O (database, network, file system)
+- ❌ No `Math.random()` or `Date.now()`
+- ❌ No global mutable state
+- ✅ All I/O goes in activities
+- ✅ Use `workflow.now()` for timestamps
+- ✅ Use `workflow.random()` for randomness

package/template/.codex/skills/write-architecture-spec/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: write-architecture-spec
+description: Orchestrate IA shard authoring via design and deepen passes, with pipeline-state-driven shard selection and ambiguity gates
+parameters:
+  - name: shard
+    type: string
+    required: false
+    description: Optional shard override; defaults to lowest-numbered IA shard marked not-started
+---
+
+## Overview
+
+Runs IA specification authoring in two shards: design → deepen.
+
+
+## Prerequisites
+
+1. Decomposition outputs exist (`.memory/wiki/specs/ia/` skeletons + indexes)
+2. `.memory/pipeline/progress/spec-pipeline.md` exists and includes IA column states
+3. Stack map is resolved for required categories (Databases, Security, Surfaces)
+
+## Step-by-Step
+
+### Step 0 — Pipeline-state shard selection
+
+1. Read `.memory/pipeline/progress/spec-pipeline.md`.
+2. Select lowest-numbered IA shard with `not-started` status unless override is explicitly requested.
+3. If no IA shard remains: stop and direct next step to `/write-be-spec`.
+
+### Step 1 — Run design shard
+
+Call skill: `write-architecture-spec-design`
+
+Expected outputs:
+- Fully drafted IA sections for selected shard:
+  - interactions
+  - contracts
+  - data models
+  - access control
+  - accessibility
+  - event schemas
+  - edge cases
+
+### Step 2 — Run deepen shard
+
+Call skill: `write-architecture-spec-deepen`
+
+Expected outputs:
+- Iterative deepening passes complete
+- IA shard finalized and verified
+- IA index updated for shard completion
+- spec pipeline IA state updated
+- ambiguity gates executed
+
+## Quality Gate
+
+Do not close workflow unless all pass:
+- complete interaction flows
+- typed contracts with explicit errors
+- complete data model relationships/constraints
+- role coverage across all interactions
+- edge-case coverage for concurrency/deletion/conflicts
+- bidirectional cross-shard dependencies
+
+## Completion Checklist
+
+- [ ] target shard selected from pipeline state
+- [ ] design shard completed and user-reviewed
+- [ ] deepen shard completed and user-reviewed
+- [ ] IA index updated
+- [ ] pipeline tracker updated
+- [ ] ambiguity gates completed
+- [ ] next valid step recommended based on remaining IA shards
+
+## Next Steps
+
+- If IA shards remain: `/write-architecture-spec`
+- If IA is complete and `/audit-ambiguity ia` is clean: `/write-be-spec`

package/template/.codex/skills/write-architecture-spec-deepen/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: write-architecture-spec-deepen
+description: Run iterative IA deepening, finalize shard, update indexes/tracker, and enforce ambiguity gates before handoff
+parameters:
+  - name: shard
+    type: string
+    required: false
+    description: Optional explicit IA shard filename
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. Target IA shard exists with all design sections filled (no unresolved skeleton markers)
+2. Design shard has completed and received explicit approval
+
+## Step-by-Step
+
+### Step 1 — Skeleton and readiness guard
+
+1. Verify target shard has no unresolved placeholder/TODO skeleton markers in required authored sections.
+2. If unresolved markers remain, stop and return to design shard.
+
+### Step 2 — Iterative deepening passes
+
+Run passes until no meaningful additions remain (with pass-loop guard):
+1. cross-section consistency
+2. what-if scenario expansion
+3. adversarial/abuse-path pass
+4. additional convergence passes when new material appears
+
+Ensure event-consumer cross-references are valid and bidirectional.
+
+### Step 3 — Finalize shard and run complexity gate
+
+1. Write full integrated shard content to `.memory/wiki/specs/ia/[shard-name].md`.
+2. Re-read and verify required sections are non-empty and consistent.
+3. Apply complexity thresholds:
+   - <=400 lines pass
+   - 401-500 lines warn
+   - >500 lines stop and trigger split path
+
+### Step 4 — Update indexes and tracker
+
+1. Mark shard complete in `.memory/wiki/specs/ia/index.md`.
+2. Update `.memory/pipeline/progress/spec-pipeline.md` IA column via protocol.
+3. Run conditional bootstrap if shard is the architecture-design stack-lock shard.
+
+### Step 5 — Ambiguity gates and last-shard branch
+
+1. Run micro + macro ambiguity gates and two-implementer/devil's-advocate checks.
+2. If this is the last IA shard, run `/audit-ambiguity ia` before any BE spec recommendation.
+3. If IA shards remain, recommend next pending IA shard.
+
+### Step 6 — Graph refresh, review request, and constrained next-step recommendation
+
+1. Run Protocol 8 fully, including mandatory `memory_compile` graph refresh after tracker verification.
+2. Present completion with:
+- shard link
+- cross-reference verification status
+- ambiguity gate confirmation
+- spec graph refresh confirmation
+- pipeline state and next allowed command
+
+## Completion Checklist
+
+- [ ] deepening passes completed with convergence
+- [ ] cross-references validated bidirectionally
+- [ ] complexity gate handled
+- [ ] IA index updated
+- [ ] spec pipeline tracker updated
+- [ ] ambiguity gates passed
+- [ ] last-shard audit branch handled correctly
+- [ ] spec graph refreshed via `memory_compile`
+- [ ] review request sent and workflow paused
+
+## Next Steps
+
+- if IA shards remain: `/write-architecture-spec`
+- if IA complete and ambiguity audit passes: `/write-be-spec`

package/template/.codex/skills/write-architecture-spec-design/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: write-architecture-spec-design
+description: Draft IA shard sections from reconciled ideation and architecture sources, with write-as-you-go section locking
+parameters:
+  - name: shard
+    type: string
+    required: false
+    description: Optional explicit IA shard filename
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. Target IA shard skeleton exists under `.memory/wiki/specs/ia/`
+2. Pipeline tracker is available to determine current shard when not overridden
+
+## Step-by-Step
+
+### Step 0 — Pipeline and map guards
+
+1. Read `.memory/pipeline/progress/spec-pipeline.md` and select target shard.
+2. Verify required stack map values exist in `.codex/instructions/tech-stack.md`:
+   - Databases
+   - Security
+   - Surfaces
+3. If guards fail: stop and route to prerequisite workflow.
+
+### Step 1 — Re-run check for partially filled shard
+
+1. Inspect target IA shard for existing authored sections.
+2. If partial content exists, ask whether to continue (skip completed sections) or redo selected sections.
+
+### Step 2 — Requirements reconciliation and scope lock
+
+1. Reconcile authoritative sources (ideation domain tree + shard features + MoSCoW summary).
+2. Run sub-feature reconciliation protocol.
+3. Present adds/removals/re-scope outcomes and lock scope.
+4. If sub-feature count exceeds split threshold, stop and route through decomposition remediation.
+
+### Step 3 — Draft and lock required sections (write-as-you-go)
+
+For each section below:
+1. present proposed content + review questions
+2. confirm decisions
+3. write section immediately to shard file
+
+Sections:
+- `## Interactions`
+- `## Contracts`
+- `## Data Models`
+- `## Access Control`
+- `## Accessibility`
+- `## Event Schemas` (explicit N/A allowed)
+- `## Edge Cases`
+
+### Step 4 — Deep dive file writes (conditional)
+
+1. Detect deep-dive references in shard.
+2. For referenced deep-dive skeletons, author exhaustive subsystem details when still placeholders.
+
+### Step 5 — Completeness gate and review request
+
+1. Verify all required sections exist and are non-empty.
+2. Verify no unresolved skeleton markers remain for required sections.
+3. Request explicit approval before deepen shard begins.
+
+## Completion Checklist
+
+- [ ] pipeline + map guards passed
+- [ ] scope reconciliation completed and confirmed
+- [ ] all required sections written progressively
+- [ ] conditional deep-dive files authored where referenced
+- [ ] section completeness gate passed
+- [ ] explicit approval requested
+
+## Next Steps
+
+- Run `write-architecture-spec-deepen`

package/template/.codex/skills/write-be-spec/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: write-be-spec
+description: Orchestrate backend spec production from completed IA shards through classify and write passes with mandatory ambiguity gates
+parameters:
+  - name: shard
+    type: string
+    required: false
+    description: Optional IA shard override; defaults to lowest-numbered BE not-started shard with IA complete
+---
+
+## Overview
+
+Runs BE specification authoring in two shards: classify → write.
+
+
+## Prerequisites
+
+1. IA shard(s) are complete and marked ✅ in `.memory/wiki/specs/ia/index.md`
+2. `.memory/pipeline/progress/spec-pipeline.md` exists
+3. BE conventions/index files exist under `.memory/wiki/specs/be/`
+
+## Step-by-Step
+
+### Step 0 — Pipeline-state shard selection
+
+1. Read `.memory/pipeline/progress/spec-pipeline.md`.
+2. Find shards where IA is `complete` and BE is `not-started`.
+3. Select lowest-numbered eligible shard unless user explicitly overrides.
+4. If none remain, stop and recommend `/write-fe-spec`.
+
+### Step 1 — Run classify shard
+
+Call skill: `write-be-spec-classify`
+
+Expected outputs:
+- Classification type + rationale
+- Expected BE spec count
+- Referenced Material Inventory
+- Created BE spec stub(s) after approval
+
+### Step 2 — Run write shard
+
+Call skill: `write-be-spec-write`
+
+Expected outputs:
+- Full BE spec file(s) in `.memory/wiki/specs/be/`
+- Updated `.memory/wiki/specs/be/index.md`
+- Updated `.memory/pipeline/progress/spec-pipeline.md` BE status
+- Ambiguity gate results + next allowed command
+
+## Quality Gate
+
+Do not close workflow unless all pass:
+- request/response schema coverage per endpoint
+- database schema/index/permission completeness
+- middleware/security constraints reflected from IA
+- specific error code definitions
+- rate-limit specs per endpoint
+- deep-dive and cross-reference coverage
+- complete IA Source Map traceability
+
+## Completion Checklist
+
+- [ ] target shard selected from pipeline state
+- [ ] classify shard completed and approved
+- [ ] write shard completed and approved
+- [ ] BE index updated
+- [ ] BE pipeline tracker updated
+- [ ] ambiguity gate completed
+- [ ] next valid command recommendation emitted
+
+## Next Steps
+
+- if BE specs remain: `/write-be-spec`
+- if BE complete and `/audit-ambiguity be` is clean: `/write-fe-spec`

package/template/.codex/skills/write-be-spec-classify/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: write-be-spec-classify
+description: Classify target IA shard for BE extraction, load stack skills, and produce a complete referenced-material inventory
+parameters:
+  - name: shard
+    type: string
+    required: false
+    description: Optional explicit IA shard filename
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. Target IA shard is complete
+2. `.memory/wiki/specs/ia/index.md` and `.memory/pipeline/progress/spec-pipeline.md` are present
+
+## Step-by-Step
+
+### Step 0 — Pipeline and IA readiness gates
+
+1. Read pipeline tracker and select BE target shard.
+2. Verify IA completion state for selected shard.
+3. If IA incomplete, stop and route to IA workflow.
+
+### Step 1 — Classification
+
+1. Apply BE classification guidance (feature domain / multi-domain split / cross-cutting / structural reference / composite).
+2. Provide classification rationale, expected BE spec count, and split boundaries.
+3. Require explicit user approval before proceeding.
+
+### Step 2 — Surface stack map validation
+
+1. Resolve shard surface context.
+2. Verify required stack map values:
+   - Languages
+   - Databases
+   - BE Frameworks
+   - ORMs
+   - Unit Tests
+   - Auth (cross-cutting)
+3. If missing values, stop and route to PRD stage completion.
+
+### Step 3 — Skill loading bundle
+
+1. Load required backend design skills and conditional async/workflow-automation skills when needed.
+2. Load ambiguity skill when unresolved requirements appear.
+
+### Step 4 — Source ingestion and inventory
+
+Read in order:
+1. BE and master indexes + data-placement strategy
+2. primary IA shard
+3. cross-shard references with section-level capture
+4. referenced deep dives (must be complete)
+5. testability/acceptance sections (when present)
+6. completed cross-cutting BE specs (`00-*`)
+
+Build Referenced Material Inventory with file/section/line source records.
+
+### Step 5 — Approval and spec stub creation
+
+1. Present classification + inventory and request explicit approval.
+2. After approval, create BE spec stub(s) from BE template.
+3. If structural reference (0 specs), emit no-write branch and recommend next shard.
+
+## Completion Checklist
+
+- [ ] target shard selected and IA-complete
+- [ ] classification approved
+- [ ] stack map validation passed
+- [ ] skill bundle loaded
+- [ ] referenced material inventory complete
+- [ ] deep-dive completeness validated
+- [ ] BE stub(s) created after approval
+
+## Next Steps
+
+- Run `write-be-spec-write`

package/template/.codex/skills/write-be-spec-write/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: write-be-spec-write
+description: Author and validate BE spec files, update indexes/tracker, run deepening and ambiguity gates, and enforce allowed next-step transitions
+parameters:
+  - name: spec_file
+    type: string
+    required: false
+    description: Optional explicit BE spec filename
+---
+
+## Overview
+
+
+## Prerequisites
+
+1. BE spec stub exists and includes `## Classification`
+2. Referenced Material Inventory exists from classify shard
+
+## Step-by-Step
+
+### Step 1 — Re-run and endpoint reconciliation gate
+
+1. Detect existing authored content and decide continue vs targeted redo.
+2. Build endpoint completeness reconciliation table before drafting sections.
+3. Require each unspecced endpoint to be either authored now or explicitly deferred with reason.
+
+### Step 2 — Write BE spec content
+
+Use BE template/conventions and write full sections, including split-group metadata when applicable.
+
+Core expectations:
+- endpoint contracts
+- schema rules
+- middleware/security controls
+- error strategy
+- testing strategy hooks
+- IA source mapping
+
+### Step 3 — Complexity gate
+
+Apply line-count thresholds:
+- <=600 pass
+- 601-800 warn
+- >800 hard stop and split recommendation
+
+### Step 4 — Index and tracker updates
+
+1. Update `.memory/wiki/specs/be/index.md`.
+2. Update BE completion state in `.memory/pipeline/progress/spec-pipeline.md`.
+3. Handle structural-reference no-spec rows when classification indicates 0 specs.
+
+### Step 5 — Iterative deepening passes
+
+Run multi-pass refinement:
+1. cross-endpoint consistency
+2. sequencing/concurrency scenarios
+3. failure cascade analysis
+4. optional convergence passes up to loop guard threshold
+
+### Step 6 — Cross-reference + ambiguity gates
+
+1. Verify back-links to IA source and related BE specs.
+2. Verify deep-dive and cross-shard source citations.
+3. Run micro/macro ambiguity checks, two-implementer test, devil's-advocate pass.
+4. If last BE spec, run `/audit-ambiguity be` before allowing FE recommendation.
+
+### Step 7 — Dependency/bootstrap and ledger updates
+
+1. Detect newly introduced dependencies and trigger bootstrap + verification as needed.
+2. Update feature ledger BE coverage when ledger exists.
+
+### Step 8 — Graph refresh, review request, and constrained next-step recommendation
+
+1. Run Protocol 8 fully, including mandatory `memory_compile` graph refresh after tracker verification.
+2. Present:
+- spec link(s)
+- cross-reference verification status
+- ambiguity gate status
+- spec graph refresh confirmation
+- pipeline state and only allowed next command (`/write-be-spec` or `/write-fe-spec`)
+
+## Completion Checklist
+
+- [ ] endpoint reconciliation table completed
+- [ ] BE spec content fully authored
+- [ ] complexity gate handled
+- [ ] BE index updated
+- [ ] pipeline tracker updated
+- [ ] deepening passes completed
+- [ ] ambiguity gate completed
+- [ ] dependency bootstrap checks handled
+- [ ] feature ledger BE coverage updated (if present)
+- [ ] spec graph refreshed via `memory_compile`
+- [ ] review requested with constrained next-step options
+
+## Next Steps
+
+- if BE specs remain: `/write-be-spec`
+- if BE complete and ambiguity audit passes: `/write-fe-spec`