cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/clean-code/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: clean-code
+description: "Applies battle-tested clean code principles to writing, reviewing, and refactoring code. Covers naming, functions, comments, error handling, class design, and the critical difference between clever code and clear code."
+version: 2.0.0
+---
+
+# Clean Code
+
+Code is read 10x more than it's written. Every naming choice, every function boundary, every abstraction layer either helps or hurts the next person who reads it — including future you.
+
+## When to Use
+
+- Writing any new code
+- Reviewing pull requests
+- Refactoring existing code
+- When code "works but feels wrong"
+
+## Stack-Specific References
+
+The principles below are language-agnostic. For idiomatic patterns and syntax, read the reference matching your surface's Languages column:
+
+| Language | Reference |
+|----------|-----------|
+| TypeScript / JavaScript | `references/typescript.md` |
+| Python | `references/python.md` |
+| Go | `references/go.md` |
+| Rust | `references/rust.md` |
+
+## Core Principles
+
+### 1. Names Are Documentation
+
+Names should reveal intent. If a name requires a comment to explain it, the name is wrong.
+
+| Bad | Good | Why |
+|-----|------|-----|
+| `d` | `elapsedDays` | What is `d`? |
+| `list` | `activeUsers` | What kind of list? |
+| `processData()` | `validateAndSaveOrder()` | What processing? |
+| `temp` | `filteredResults` | Temporary what? |
+| `flag` | `isEligibleForDiscount` | What flag? |
+| `doStuff()` | `sendWelcomeEmail()` | What stuff? |
+| `Manager` | `OrderProcessor` | Manager of what? |
+| `Utils` | `StringFormatter` | Util for what? |
+
+**Rules:**
+- Classes/types → nouns (`UserRepository`, `PaymentGateway`)
+- Functions → verbs (`calculateTotal`, `sendNotification`)
+- Booleans → questions (`isActive`, `hasPermission`, `canEdit`)
+- Constants → screaming snake with context (`MAX_RETRY_ATTEMPTS`, not `MAX`)
+- No abbreviations unless universally understood (`id`, `url`, `api` are fine; `usr`, `mgr`, `proc` are not)
+
+### 2. Functions Should Do One Thing
+
+A function that does one thing well is easy to name, test, and reuse. A function that does three things is hard to name, impossible to test independently, and couples three responsibilities.
+
+**The test:** Can you describe the function without using "and"? If not, split it.
+
+```
+❌ processOrder(order)
+   — validates order
+   — calculates total with tax
+   — saves to database
+   — sends confirmation email
+
+✅ validateOrder(order)        → throws if invalid
+   calculateOrderTotal(items) → returns numeric total
+   submitOrder(order)         → orchestrates the above
+```
+
+**Function size limits:**
+- **Ideal**: 5-15 lines
+- **Acceptable**: up to 30 lines
+- **Needs splitting**: 30+ lines
+- **Unacceptable**: 50+ lines (split immediately)
+
+### 3. Parameters
+
+- **0-2 parameters**: ideal
+- **3 parameters**: acceptable with named/destructured args
+- **4+ parameters**: use an options object/struct/dataclass
+- **Boolean parameters**: almost always a code smell — split into two functions
+
+```
+❌ createUser(name, isAdmin)
+✅ createUser(name)  /  createAdmin(name)
+
+❌ sendEmail(to, from, subject, body, cc)
+✅ sendEmail(options)   ← options is a structured type
+```
+
+### 4. Comments: Why, Not What
+
+Good code doesn't need comments to explain WHAT it does. Comments should explain WHY — the non-obvious reasoning, business rules, or constraints.
+
+```
+❌ // Increment counter by one
+   counter += 1
+
+❌ // Check if user is admin
+   if user.role == "admin"
+
+✅ // Stripe requires amount in cents, not dollars
+   amountInCents = round(price * 100)
+
+✅ // FDA regulation 21 CFR Part 11 requires audit trail
+   auditLog.record(changeEvent)
+
+✅ // WARNING: This query locks the orders table — avoid during peak hours
+   db.execute(batchUpdateQuery)
+```
+
+**Delete these comments immediately:**
+- `// TODO: fix this later` — fix it now or create a tracked issue
+- `// This is a hack` — then don't commit the hack
+- `// I don't know why this works` — figure it out before shipping
+- Commented-out code — delete it; version control has your history
+
+### 5. Error Handling
+
+Errors are not edge cases — they're expected behavior. Handle them explicitly.
+
+```
+❌ try { save(order) } catch { log("error") }
+   → What error? What happens to the order?
+
+❌ try { processPayment(order) } catch { throw Error("Something went wrong") }
+   → Useless to the caller
+
+✅ try {
+     processPayment(order)
+   } catch InsufficientFundsError:
+     return { success: false, code: "INSUFFICIENT_FUNDS", retry: false }
+   catch PaymentGatewayError:
+     logger.error("Payment gateway failure", { orderId: order.id })
+     return { success: false, code: "GATEWAY_ERROR", retry: true }
+   catch unknown:
+     rethrow  → Unknown errors bubble up
+```
+
+### 6. Don't Repeat Yourself (DRY) — But Don't Over-Abstract
+
+**DRY violation** — same logic copy-pasted in 3+ places:
+```
+tax1 = price1 * 0.08
+tax2 = price2 * 0.08
+tax3 = price3 * 0.08
+→ Extract: calculateTax(price)
+```
+
+**Over-abstraction** — premature DRY that couples unrelated things:
+```
+❌ handleEntity(type, action, data)  → "universal" handler for everything
+```
+
+**Rule of Three**: Duplicate once is acceptable. Duplicate twice means extract.
+
+### 7. Code Organization
+
+```
+                        High-level policy (business logic)
+                               │
+                               ▼
+                     ┌─────────────────────┐
+                     │   Domain Layer       │  Pure logic, no I/O
+                     │   (models, rules)    │
+                     └─────────────────────┘
+                               │
+                     ┌─────────────────────┐
+                     │   Application Layer  │  Orchestrates domain objects
+                     │   (use cases)        │
+                     └─────────────────────┘
+                               │
+                     ┌─────────────────────┐
+                     │   Infrastructure     │  I/O, databases, APIs
+                     │   (adapters)         │
+                     └─────────────────────┘
+                               │
+                        Low-level detail (frameworks, drivers)
+```
+
+- Dependencies point inward (infrastructure depends on domain, not reverse)
+- Business logic never imports from infrastructure
+- Test domain logic without databases, APIs, or frameworks
+
+## Quick Refactoring Checklist
+
+Before committing code, check:
+
+- [ ] Can I understand every function in <10 seconds?
+- [ ] Are there any functions >30 lines?
+- [ ] Are there any files >200 lines (components) or >300 lines (utilities)?
+- [ ] Do all names reveal intent without needing comments?
+- [ ] Is there any copy-pasted logic (3+ occurrences)?
+- [ ] Are errors handled specifically, not swallowed or genericized?
+- [ ] Would a new team member understand this without asking me?

package/template/.codex/skills/clean-code/references/typescript.md

@@ -0,0 +1,126 @@
+# TypeScript Clean Code Patterns
+
+Language-specific patterns for the `clean-code` skill. Read `SKILL.md` first for universal principles.
+
+---
+
+## Single Responsibility
+
+```typescript
+// ❌ Does three things
+function processOrder(order: Order): void {
+  if (!order.items.length) throw new Error("Empty order");
+  if (!order.customer) throw new Error("No customer");
+
+  let total = 0;
+  for (const item of order.items) {
+    total += item.price * item.quantity;
+    if (item.taxable) total += item.price * 0.08;
+  }
+
+  db.orders.insert({ ...order, total, status: "pending" });
+  emailService.send(order.customer.email, "Order confirmed");
+}
+
+// ✅ Each function does one thing
+function validateOrder(order: Order): void {
+  if (!order.items.length) throw new InvalidOrderError("Empty order");
+  if (!order.customer) throw new InvalidOrderError("No customer");
+}
+
+function calculateOrderTotal(items: OrderItem[]): number {
+  return items.reduce((total, item) => {
+    const subtotal = item.price * item.quantity;
+    const tax = item.taxable ? item.price * TAX_RATE : 0;
+    return total + subtotal + tax;
+  }, 0);
+}
+
+function submitOrder(order: Order): OrderConfirmation {
+  validateOrder(order);
+  const total = calculateOrderTotal(order.items);
+  const saved = db.orders.insert({ ...order, total, status: "pending" });
+  emailService.send(order.customer.email, "Order confirmed");
+  return { orderId: saved.id, total };
+}
+```
+
+## Options Objects Over Positional Args
+
+```typescript
+// ❌ Boolean flag parameter
+function createUser(name: string, isAdmin: boolean): User { ... }
+
+// ✅ Two clear functions
+function createUser(name: string): User { ... }
+function createAdmin(name: string): User { ... }
+
+// ❌ Too many positional args
+function sendEmail(to: string, from: string, subject: string, body: string, cc?: string): void { ... }
+
+// ✅ Options object
+interface SendEmailOptions {
+  to: string;
+  from: string;
+  subject: string;
+  body: string;
+  cc?: string;
+}
+function sendEmail(options: SendEmailOptions): void { ... }
+```
+
+## Error Handling
+
+```typescript
+// ❌ Swallowing errors
+try {
+  await saveOrder(order);
+} catch (e) {
+  console.log("error");
+}
+
+// ❌ Generic catch-all
+try {
+  await processPayment(order);
+} catch (e) {
+  throw new Error("Something went wrong");
+}
+
+// ✅ Specific, actionable error handling
+try {
+  await processPayment(order);
+} catch (error) {
+  if (error instanceof InsufficientFundsError) {
+    return { success: false, code: "INSUFFICIENT_FUNDS", retry: false };
+  }
+  if (error instanceof PaymentGatewayError) {
+    logger.error("Payment gateway failure", { orderId: order.id, error });
+    return { success: false, code: "GATEWAY_ERROR", retry: true };
+  }
+  throw error; // Unknown errors bubble up
+}
+```
+
+## Comments
+
+```typescript
+// ❌ Redundant
+// Increment counter by one
+counter += 1;
+
+// ❌ Obvious
+// Check if user is admin
+if (user.role === "admin") { ... }
+
+// ✅ Explains WHY
+// Stripe requires amount in cents, not dollars
+const amountInCents = Math.round(price * 100);
+
+// ✅ Business rule
+// FDA regulation 21 CFR Part 11 requires audit trail for all changes
+await auditLog.record(changeEvent);
+
+// ✅ Non-obvious consequence
+// WARNING: This query locks the orders table — avoid running during peak hours
+await db.execute(batchUpdateQuery);
+```

package/template/.codex/skills/code-review-pro/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: Code Review Pro
+description: Deep code analysis covering security, performance, maintainability, and best practices
+---
+
+# Code Review Pro
+
+Deep code analysis covering security, performance, maintainability, and best practices.
+
+## When to Use This Skill
+Activate when the user:
+- Asks for a code review
+- Wants security vulnerability scanning
+- Needs performance analysis
+- Asks to "review this code" or "audit this code"
+- Mentions finding bugs or improvements
+- Wants refactoring suggestions
+- Requests best practice validation
+
+## Instructions
+1. **Security Analysis (Critical Priority)**
+   - SQL injection vulnerabilities
+   - XSS (cross-site scripting) risks
+   - Authentication/authorization issues
+   - Secrets or credentials in code
+   - Unsafe deserialization
+   - Path traversal vulnerabilities
+   - CSRF protection
+   - Input validation gaps
+   - Insecure cryptography
+   - Dependency vulnerabilities
+
+2. **Performance Analysis**
+   - N+1 query problems
+   - Inefficient algorithms (check Big O complexity)
+   - Memory leaks
+   - Unnecessary re-renders (React/Vue)
+   - Missing indexes (database queries)
+   - Blocking operations
+   - Resource cleanup (file handles, connections)
+   - Caching opportunities
+   - Excessive network calls
+   - Large bundle sizes
+
+3. **Code Quality & Maintainability**
+   - Code duplication (DRY violations)
+   - Function/method length (should be <50 lines)
+   - Cyclomatic complexity
+   - Unclear naming
+   - Missing error handling
+   - Inconsistent style
+   - Missing documentation
+   - Hard-coded values that should be constants
+   - God classes/functions
+   - Tight coupling
+
+4. **Best Practices**
+   - Language-specific idioms
+   - Framework conventions
+   - SOLID principles
+   - Design patterns usage
+   - Testing approach
+   - Logging and monitoring
+   - Accessibility (for UI code)
+   - Type safety
+   - Null/undefined handling
+
+5. **Bugs and Edge Cases**
+   - Logic errors
+   - Off-by-one errors
+   - Race conditions
+   - Null pointer exceptions
+   - Unhandled edge cases
+   - Timezone issues
+   - Encoding problems
+   - Floating point precision
+
+6. **Provide Actionable Fixes**
+   - Show specific code changes
+   - Explain why change is needed
+   - Include before/after examples
+   - Prioritize by severity
+
+## Output Format
+```markdown
+# Code Review Report
+
+## 🚨 Critical Issues (Fix Immediately)
+### 1. [Issue Title] (line X)
+**Severity**: Critical
+**Issue**: [Description]
+**Impact**: [What could happen]
+
+**Current Code:**
+```
+[problematic code]
+```
+
+**Fixed Code:**
+```
+[corrected code]
+```
+
+**Explanation**: [Why this matters]
+
+## ⚠️ High Priority Issues
+### 2. [Issue] (line Y)
+[Details...]
+
+## 💡 Medium Priority Issues
+### 3. [Issue] (line Z)
+[Details...]
+
+## ✅ Low Priority / Nice to Have
+### 4. [Issue]
+[Details...]
+
+## 📊 Summary
+- **Total Issues**: N
+  - Critical: X
+  - High: Y
+  - Medium: Z
+  - Low: W
+
+## 🎯 Quick Wins
+Changes with high impact and low effort:
+1. [Fix 1]
+2. [Fix 2]
+
+## 🏆 Strengths
+- [Positive observation 1]
+- [Positive observation 2]
+
+## 🔄 Refactoring Opportunities
+1. **Extract Method**: Lines X-Y could be extracted into `functionName()`
+2. **Remove Duplication**: [specific code blocks]
+```
+
+## Best Practices
+- Always prioritize security issues first
+- Provide specific line numbers for issues
+- Include before/after code examples
+- Explain *why* something is a problem
+- Consider the language/framework context
+- Don't just criticize—acknowledge good code too
+- Suggest gradual improvements for large refactors
+- Link to documentation for recommendations
+- Consider project constraints (legacy code, deadlines)
+- Balance perfectionism with pragmatism
+- Focus on impactful changes
+- Group similar issues together
+- Make recommendations actionable

package/template/.codex/skills/concise-planning/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: concise-planning
+description: "Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist."
+version: 2.0.0
+source: self
+date_added: "2026-02-27"
+date_rewritten: "2026-03-14"
+---
+
+# Concise Planning
+
+Generate focused, actionable implementation plans that eliminate ambiguity and prevent scope creep.
+
+## When to Use
+
+- User asks "how should I approach this?" or "can you make a plan for X?"
+- Task involves multiple files or components
+- Work spans more than ~3 logical steps
+- You need to communicate a proposed sequence before executing
+
+## When NOT to Use
+
+- Task is a single-step operation (just do it)
+- User gave an explicit command with clear intent (just execute)
+- During `/plan-phase` or `/implement-slice` (those have their own planning structure)
+
+## Workflow
+
+### 1. Scan Context (30 seconds, not 5 minutes)
+
+Read only what's necessary:
+- **Project structure** — `ls` the relevant directories
+- **Existing patterns** — check one similar file for conventions
+- **Constraints** — look for test frameworks, linters, type systems in use
+
+Do NOT read every file in the project. Do NOT generate a 500-line analysis. Scan, not study.
+
+### 2. Ask or Assume
+
+- **0 questions** if the task is clear and you have enough context
+- **1 question max** if there's a genuinely blocking ambiguity
+- **Never more than 2** — if you need more, you don't understand the codebase well enough. Go read more code instead of asking.
+
+For non-blocking unknowns, state your assumption:
+> "Assuming we want this as a new utility in `lib/` rather than inline — will adjust if you prefer otherwise."
+
+### 3. Generate Plan
+
+Use this exact structure:
+
+```markdown
+## Approach
+
+[1-3 sentences: what you'll do and why this approach over alternatives]
+
+## Scope
+
+**In:**
+- [Specific deliverable 1]
+- [Specific deliverable 2]
+
+**Out:**
+- [Explicitly excluded item — prevents scope creep]
+
+## Steps
+
+1. [Verb] [specific target] — [why, if non-obvious]
+2. [Verb] [specific target]
+3. [Verb] [specific target]
+4. [Verb] [specific target]
+5. Validate: [specific validation command or check]
+
+## Assumptions
+
+- [Assumption 1 — what you decided without asking]
+```
+
+### Plan Quality Rules
+
+| Rule | Why |
+|------|-----|
+| **6-10 steps** | Fewer = too vague. More = over-planned. |
+| **Verb-first steps** | "Add", "Create", "Refactor", "Test" — not "The component should..." |
+| **Name files and functions** | "Add `validateEmail()` to `lib/validators.ts`" not "add validation" |
+| **One validation step minimum** | Every plan ends with proof it works |
+| **Explicit "Out" scope** | Prevents the plan from growing mid-execution |
+| **No nested sub-plans** | If a step needs sub-steps, it's too big — split it |
+
+### Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| "Research best practices for X" | Just apply the best practice directly in a step |
+| "Consider whether to use A or B" | Pick one, state why, move on |
+| "Set up the project structure" | "Create `src/validators/` with `index.ts` and `email.ts`" |
+| "Write tests" | "Add tests for `validateEmail`: valid input, empty string, missing @, >254 chars" |
+| 20-step plan | 8-step plan with clear scope boundaries |
+| Plan that describes what might happen | Plan that describes what WILL happen |
+
+## Output Format
+
+Always present the plan in a markdown code block or as structured markdown. Never as prose paragraphs.
+
+After presenting the plan, ask one question:
+> "Ready to execute, or want to adjust anything?"
+
+Then execute on confirmation — don't re-plan.

package/template/.codex/skills/create-prd/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: create-prd
+description: Orchestrate architecture design generation from ideation through stack, design-system, architecture, security, and compile shards
+parameters:
+  - name: ideation_index
+    type: string
+    required: false
+    description: Optional override path to ideation-index.md
+---
+
+## Overview
+
+Runs the create-prd stage in five shards and compiles final architecture outputs.
+
+
+## Prerequisites
+
+1. `.memory/wiki/specs/ideation/ideation-index.md` exists and is complete
+2. Ideation approval already obtained
+3. `.codex/instructions/tech-stack.md` exists and has resolved values for required map cells
+
+## Step-by-Step
+
+### Step 0 — Ideation readiness gate
+
+1. Read ideation index and validate required sections:
+   - `## Structural Classification`
+   - `## Engagement Tier`
+   - `## MoSCoW Summary` (with at least one Must Have)
+2. If missing required sections: stop and direct user to complete ideation.
+3. For large ideation sets, run deep ideation loading protocol and write digest to architecture draft.
+
+### Step 1 — Run stack shard
+
+Call skill: `create-prd-stack`
+
+Expected outputs:
+- `.memory/wiki/specs/architecture/prd-working/ideation-relevance-index.md`
+- `.memory/wiki/specs/architecture/prd-working/stack-synthesis.md`
+- Stack decisions appended to `.memory/wiki/specs/architecture-draft.md`
+
+### Step 2 — Run design-system shard
+
+Call skill: `create-prd-design-system`
+
+Expected outputs:
+- `.memory/wiki/specs/design-system.md`
+- `.memory/wiki/specs/architecture/prd-working/design-system-synthesis.md`
+
+### Step 3 — Run architecture shard
+
+Call skill: `create-prd-architecture`
+
+Expected outputs:
+- `## System Architecture` in `.memory/wiki/specs/architecture-draft.md`
+- `## Error Architecture` in `.memory/wiki/specs/architecture-draft.md`
+- `## Data Strategy` in `.memory/wiki/specs/architecture-draft.md`
+- `.memory/wiki/specs/data-placement-strategy.md`
+
+### Step 4 — Run security shard
+
+Call skill: `create-prd-security`
+
+Expected outputs:
+- `## Security Model` in `.memory/wiki/specs/architecture-draft.md`
+- `## Security — Attack Surface` in `.memory/wiki/specs/architecture-draft.md`
+- `## Integration Points` in `.memory/wiki/specs/architecture-draft.md`
+- `## Observability Architecture` in `.memory/wiki/specs/architecture-draft.md`
+
+### Step 5 — Run compile shard
+
+Call skill: `create-prd-compile`
+
+Expected outputs:
+- `.memory/wiki/specs/YYYY-MM-DD-architecture-design.md`
+- `.memory/wiki/specs/ENGINEERING-STANDARDS.md`
+- Checkpoint cleanup in `.memory/wiki/specs/architecture/prd-working/`
+
+## Completion Checklist
+
+- [ ] Ideation readiness and size-aware loading handled
+- [ ] Stack shard complete
+- [ ] Design-system shard complete
+- [ ] Architecture shard complete
+- [ ] Security shard complete
+- [ ] Compile shard complete
+- [ ] Architecture rubric self-check complete
+- [ ] User review requested with both final documents
+- [ ] Next command recommendation emitted
+
+## Next Steps
+
+After explicit user approval of compiled architecture outputs, the only valid next command is:
+- `/audit-ambiguity architecture`