cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skills/prd-templates/references/write-verification-protocol.md

@@ -0,0 +1,57 @@
+# Write Verification Protocol
+
+**Purpose**: Every file write MUST be verified by reading the file back. This protocol eliminates the ~18 instances of "write the completed section" without verification.
+
+---
+
+## Procedure
+
+### 1. Write
+
+Write the content to the target file at the specified section.
+
+### 2. Read Back
+
+Immediately after writing, read the target file. Locate the section header that was just written.
+
+### 3. Verify
+
+Check ALL of these conditions:
+
+- [ ] The section header exists in the file
+- [ ] The section content is non-empty (not just a header with no body)
+- [ ] The content matches what was intended (key fields present, no truncation)
+
+### 4. Handle Failure
+
+**If ANY check fails:**
+
+1. Log: "Write verification failed for `[file]` section `[section]`."
+2. Retry the write once.
+3. Read back again and re-verify.
+4. If second attempt fails → **STOP**: "Unable to write `[section]` to `[file]` after 2 attempts. Investigate before proceeding."
+
+### 5. Confirm
+
+After successful verification, log: `Write verified: [file] § [section]`
+
+---
+
+## When to Use
+
+Any workflow step that says:
+- "Write the completed [section]"
+- "Write [content] to [file]"
+- "Update [file] with [content]"
+- "Append [content] to [file]"
+
+MUST follow this protocol. There are no exceptions. A write instruction without read-back verification is an enforcement failure.
+
+---
+
+## Scope
+
+This protocol applies to **spec and instruction file writes** — the documents that drive downstream pipeline behavior. It does NOT apply to:
+- Progress tracking file writes (those have their own verification in the completion checklist)
+- Temporary/scratch files
+- Audit report writes (those are progressive and self-verifying)

package/template/.codex/skills/prompt-engineer/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: prompt-engineer
+description: "Transforms user prompts into optimized prompts using established frameworks (RTF, RISEN, Chain of Thought, RODES). Analyzes intent, selects framework, and produces structured, ready-to-use prompts."
+version: 2.0.0
+source: self
+date_added: "2026-02-27"
+date_rewritten: "2026-03-14"
+---
+
+# Prompt Engineering
+
+Transform vague or unstructured prompts into highly effective, framework-backed prompts that maximize AI output quality.
+
+## When to Use
+
+- User provides a vague or generic prompt ("help me code Python")
+- User has a complex idea but struggles to articulate it clearly
+- User asks "create a prompt for..." or "how do I ask AI to..."
+- Task requires step-by-step reasoning (debugging, analysis, design)
+- User wants to improve an existing prompt's effectiveness
+
+## When NOT to Use
+
+- User's prompt is already clear and specific
+- Simple factual questions ("what is X?")
+- During pipeline workflows that have their own prompting structure
+
+## Operating Mode
+
+Work silently — no framework jargon in the output. The user gets a polished prompt, not a lecture on prompt engineering theory.
+
+---
+
+## Workflow
+
+### 1. Analyze Intent
+
+Read the raw prompt and detect:
+
+| Dimension | Options |
+|-----------|---------|
+| **Type** | Coding, writing, analysis, design, learning, planning, creative |
+| **Complexity** | Simple (one-step), moderate (multi-step), complex (reasoning needed) |
+| **Clarity** | Clear intent vs. ambiguous/vague |
+| **Domain** | Technical, business, creative, academic |
+
+Identify implicit requirements:
+- Does the user need examples?
+- Is the output format specified?
+- Are there constraints (time, scope, resources)?
+- Is this exploratory or execution-focused?
+
+### 2. Clarify If Needed
+
+- **0 questions** if intent is clear (most cases)
+- **1-2 questions max** if critical information is ambiguous
+- **Never ask** about framework selection — that's your job
+
+### 3. Select Framework
+
+| Task Type | Framework | Why |
+|-----------|-----------|-----|
+| Role-based tasks (act as expert) | **RTF** (Role-Task-Format) | Clear role + task + output format |
+| Step-by-step reasoning (debugging, analysis) | **Chain of Thought** | Forces explicit reasoning steps |
+| Multi-phase projects (systems, deliverables) | **RISEN** (Role, Instructions, Steps, End goal, Narrowing) | Comprehensive structure |
+| Complex design/architecture | **RODES** (Role, Objective, Details, Examples, Sense check) | Balances detail with validation |
+| Summarization/synthesis | **Chain of Density** | Iterative compression to essentials |
+| Communication (reports, presentations) | **RACE** (Role, Audience, Context, Expectation) | Audience-aware messaging |
+| Goal-setting (OKRs, planning) | **CLEAR** (Collaborative, Limited, Emotional, Appreciable, Refinable) | Actionable goals |
+
+**Blending**: Combine 2 frameworks when a task spans types. Example: architecture design → RODES + Chain of Thought.
+
+**Selection happens silently** — never explain framework choice to the user.
+
+### 4. Generate Prompt
+
+Build the optimized prompt using the selected framework(s):
+
+**Structure rules:**
+- Start with a clear role definition
+- State the objective in one sentence
+- Break complex tasks into numbered steps
+- Include output format specification
+- Add a validation/sense-check instruction for complex tasks
+- Keep the prompt self-contained (no external context needed)
+
+**Quality checks before presenting:**
+- [ ] Prompt is self-contained
+- [ ] Task is specific and measurable
+- [ ] Output format is clear
+- [ ] No ambiguous language
+- [ ] Appropriate detail for task complexity
+- [ ] Language matches user's language
+
+### 5. Present
+
+Present the optimized prompt in a clean markdown code block. No meta-commentary, no framework explanation.
+
+---
+
+## Examples
+
+### Vague Input → RTF
+
+**User**: "help me write better code"
+
+**Output**:
+```
+Role: You are a senior software engineer conducting a code review.
+
+Task: Review the code I provide and identify issues across these dimensions:
+1. Readability — naming, structure, comments
+2. Correctness — logic errors, edge cases, off-by-one errors
+3. Performance — unnecessary allocations, O(n²) where O(n) exists
+4. Security — injection risks, data exposure, input validation
+5. Maintainability — coupling, cohesion, testability
+
+Format: For each issue found, provide:
+- Location (file/line if applicable)
+- Category (readability/correctness/performance/security/maintainability)
+- Current code
+- Suggested improvement with explanation
+- Severity (critical/warning/suggestion)
+```
+
+### Complex Input → RODES + Chain of Thought
+
+**User**: "I need to build a recommendation system using purchase history and user preferences"
+
+**Output**:
+```
+Role: You are a senior ML engineer specializing in recommendation systems.
+
+Objective: Design a product recommendation system combining user purchase history, stated preferences, and behavioral signals.
+
+Details:
+- Input sources: transaction logs, preference surveys, browsing behavior
+- Algorithm tradeoffs: collaborative filtering vs. content-based vs. hybrid
+- Performance targets: recommendations served in <200ms, updated hourly
+- Scale: handle 100K+ users with sparse interaction matrices
+
+Approach this step-by-step:
+1. Analyze data sources and their signal quality
+2. Propose 2-3 algorithm approaches with tradeoff analysis
+3. Design the data pipeline (ingestion → processing → serving)
+4. Define evaluation metrics (precision, recall, diversity, novelty)
+5. Outline a phased implementation roadmap
+
+Examples: Include pseudocode for the core recommendation logic, a data flow diagram, and sample API response structure.
+
+Sense check: Verify the solution balances personalization with discovery, handles cold-start problems for new users, and scales to production load.
+
+Output: Technical design document with architecture diagrams, algorithm justification, and implementation roadmap.
+```
+
+### Debugging → Chain of Thought
+
+**User**: "my code isn't working, needs debugging"
+
+**Output**:
+```
+You are an expert debugger.
+
+Task: Debug the code I provide using systematic analysis.
+
+Step-by-step approach:
+1. Read the code and identify its intended purpose
+2. Identify the error or unexpected behavior
+3. Trace variable states through execution
+4. Locate the root cause
+5. Propose a fix with explanation
+6. Suggest preventive measures
+
+For each step, show your reasoning:
+- What you're checking
+- What you found
+- Why it matters
+
+Output format:
+- **Issue**: [Describe the bug]
+- **Root cause**: [Why it's happening]
+- **Fix**: [Corrected code with inline comments]
+- **Prevention**: [How to avoid this in the future]
+
+Include a minimal working example to verify the fix.
+```
+
+---
+
+## Rules
+
+**NEVER:**
+- Explain which framework was selected or why
+- Generate generic, one-size-fits-all prompts
+- Ask more than 2 clarifying questions
+- Include meta-commentary ("This prompt uses...", "Note that...")
+
+**ALWAYS:**
+- Analyze intent before generating
+- Select framework based on task type and complexity
+- Include output format specification
+- Present in a clean code block
+- Match the user's language (English → English, etc.)

package/template/.codex/skills/propagate-decision/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: propagate-decision
+description: Scan downstream specs for contradictions with locked decisions and apply approved fixes with consistency checks
+parameters:
+  - name: decision_type
+    type: string
+    required: false
+    description: Optional direct type override (skips selection menu)
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Run `propagate-decision-scan`.
+2. Run `propagate-decision-apply` after user confirmation.
+3. Return completion summary and next-step guidance.

package/template/.codex/skills/propagate-decision-apply/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: propagate-decision-apply
+description: Present and apply contradiction fixes one-by-one, flag assumptions, run consistency checks, and write propagation record
+parameters:
+  - name: scan_report
+    type: string
+    required: false
+    description: Optional explicit propagation scan report path
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Load propagation scan report.
+2. Walk explicit contradictions one at a time (apply/skip/edit/stop-and-save).
+3. Walk implicit assumptions and flag for ambiguity handling where accepted.
+4. Run consistency check on changed documents.
+5. Write `.memory/wiki/specs/audits/propagation-[type]-[date].md`.
+6. Call `memory_compile` to refresh the spec graph from the corrected spec set.
+7. Present completion summary with graph refresh confirmation and next steps.

package/template/.codex/skills/propagate-decision-scan/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: propagate-decision-scan
+description: Pre-scan decision types, collect downstream references, classify contradictions, and write propagation scan report
+parameters:
+  - name: decision_type
+    type: string
+    required: false
+    description: Optional direct decision type to scan
+---
+
+## Overview
+
+
+## Step-by-Step
+
+1. Pre-scan all supported decision types and count downstream references.
+2. Present selection menu (or honor direct argument).
+3. Run full scan on selected types; classify references as explicit contradiction / implicit assumption / consistent.
+4. Write `.memory/wiki/specs/audits/propagation-scan-[date].md`.
+5. Stop for user confirmation before apply shard.

package/template/.codex/skills/regex-patterns/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: regex-patterns
+description: "Comprehensive regular expressions guide covering character classes, quantifiers, anchors, groups, lookahead/lookbehind, common patterns (email, URL, IP, phone, dates, semver), ReDoS prevention, Unicode support, flags, debugging, and when NOT to use regex."
+version: 2.0.0
+---
+
+# Regular Expressions Mastery
+
+## Stack-Specific References
+
+Regex syntax is mostly universal but API usage differs by language. After reading the patterns below, read the reference for your language:
+
+| Language | Reference | Engine Notes |
+|----------|-----------|-------------|
+| JavaScript | `references/javascript.md` | V8/SpiderMonkey — full PCRE-like features |
+| Python | `references/python.md` | `re` module — PCRE-like, supports verbose mode |
+| Go | `references/go.md` | RE2 — no backreferences or lookaround |
+| Rust | `references/rust.md` | regex crate — RE2-like; `fancy-regex` for lookaround |
+
+---
+
+## 1. Fundamentals
+
+### Character Classes
+
+```
+.           Any character except newline (unless /s flag)
+\d          Digit [0-9]
+\D          Non-digit [^0-9]
+\w          Word character [a-zA-Z0-9_]
+\W          Non-word character [^a-zA-Z0-9_]
+\s          Whitespace [ \t\n\r\f\v]
+\S          Non-whitespace
+[abc]       Any of a, b, or c
+[^abc]      Not a, b, or c
+[a-z]       Range: a through z
+[a-zA-Z]    Any letter
+[0-9a-fA-F] Hexadecimal digit
+```
+
+### Quantifiers
+
+```
+*           Zero or more (greedy)
++           One or more (greedy)
+?           Zero or one (optional)
+{3}         Exactly 3
+{2,5}       Between 2 and 5
+{3,}        3 or more
+
+*?          Zero or more (lazy)
++?          One or more (lazy)
+{2,5}?      Between 2 and 5 (lazy)
+
+*+          Zero or more (possessive — not in all engines)
+++          One or more (possessive)
+```
+
+### Greedy vs Lazy
+
+```
+Input:   <b>bold</b> and <b>more bold</b>
+
+<b>.*</b>      Greedy:  matches entire string (one match)
+<b>.*?</b>     Lazy:    matches "<b>bold</b>" and "<b>more bold</b>" (two matches)
+```
+
+---
+
+## 2. Anchors and Boundaries
+
+```
+^           Start of string (or line with multiline flag)
+$           End of string (or line with multiline flag)
+\b          Word boundary (between \w and \W)
+\B          Non-word boundary
+\A          Start of string (never affected by multiline — Python, Ruby)
+\z          End of string (absolute — Python, Ruby)
+```
+
+### Word Boundary Examples
+
+```
+\bcat\b     Matches "cat" in "The cat sat" — not in "concatenate"
+\bpre\w+    Matches "prefix", "preview" — not "compress"
+```
+
+---
+
+## 3. Groups
+
+### Capturing Groups
+
+```
+(abc)           Capture group — stores match for backreference
+(\d{4})         Capture the year
+(\w+)@(\w+)    Two capture groups: username and domain
+
+# Backreferences
+(.)\1           Matches repeated character: "aa", "bb"
+(\w+)\s+\1     Matches repeated word: "the the"
+```
+
+### Named Groups
+
+Named group syntax varies by language:
+- JavaScript: `(?<name>pattern)`
+- Python: `(?P<name>pattern)`
+- Go: `(?P<name>pattern)` (RE2 syntax)
+
+### Non-Capturing Groups
+
+```
+(?:abc)         Groups but does NOT capture (no backreference)
+(?:com|org|net) Matches without storing
+```
+
+### Alternation
+
+```
+cat|dog         Matches "cat" or "dog"
+(cat|dog)s      Matches "cats" or "dogs"
+(?:Mr|Mrs|Ms)   Matches title without capturing
+```
+
+---
+
+## 4. Lookahead and Lookbehind
+
+### Lookahead
+
+```
+(?=pattern)     Positive: followed by pattern
+(?!pattern)     Negative: NOT followed by pattern
+
+# Password: at least one digit, one uppercase, one lowercase
+^(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}$
+
+# Match "foo" only if followed by "bar"
+foo(?=bar)      Matches "foo" in "foobar", not in "foobaz"
+
+# Match number NOT followed by percent
+\d+(?!%)        Matches "42" in "42 items", not in "42%"
+```
+
+### Lookbehind
+
+```
+(?<=pattern)    Positive: preceded by pattern
+(?<!pattern)    Negative: NOT preceded by pattern
+
+(?<=\$)\d+      Matches "50" in "$50", not in "50 items"
+(?<!un)happy    Matches "happy" but not "unhappy"
+
+# Note: lookbehinds must be fixed-width in most engines
+# Go RE2 does NOT support lookaround at all
+```
+
+---
+
+## 5. Common Patterns
+
+### Email (Simplified)
+```
+^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$
+# WARNING: For production, use a library. RFC 5322 regex is 6,300+ chars.
+```
+
+### URL
+```
+https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b(?:[-a-zA-Z0-9()@:%_+.~#?&/=]*)
+# For strict validation, use the URL parser in your language instead.
+```
+
+### IPv4
+```
+\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b
+```
+
+### Phone (US)
+```
+^(?:\+1[-.\s]?)?(?:\(?\d{3}\)?[-.\s]?)?\d{3}[-.\s]?\d{4}$
+```
+
+### Date (YYYY-MM-DD)
+```
+^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$
+# Validates format, NOT calendar correctness.
+```
+
+### Semantic Versioning
+```
+^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|\d*[a-zA-Z\-][\da-zA-Z\-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z\-][\da-zA-Z\-]*))*))?(?:\+[\da-zA-Z\-]+(?:\.[\da-zA-Z\-]+)*)?$
+```
+
+### Hex Color
+```
+^#(?:[0-9a-fA-F]{3}){1,2}$
+```
+
+### Slug
+```
+^[a-z0-9]+(?:-[a-z0-9]+)*$
+```
+
+---
+
+## 6. ReDoS Prevention
+
+### Dangerous Patterns — O(2^n)
+
+```
+(a+)+$                  Nested quantifiers
+(a|a)+$                 Overlapping alternation
+(\w+\s*)+$             Repeated group with optional separator
+```
+
+### Prevention Rules
+
+1. NEVER nest quantifiers: `(a+)+` → flatten to `a+`
+2. NEVER use overlapping alternation with quantifiers
+3. NEVER use `.*` inside a repeated group — use `([^,]*,)+` instead
+4. Use atomic groups or possessive quantifiers when available
+5. Use negated character classes `[^"]*` over lazy `.*?`
+6. Set regex timeouts in production
+7. Consider RE2 (linear-time, no backtracking) for user inputs
+
+---
+
+## 7. Unicode Support
+
+### Unicode Categories (\p{})
+
+```
+\p{L}    Letter (any script)
+\p{Lu}   Uppercase letter
+\p{Ll}   Lowercase letter
+\p{N}    Number
+\p{Nd}   Decimal digit
+\p{P}    Punctuation
+\p{S}    Symbol
+\p{Z}    Separator (spaces)
+\p{M}    Mark (combining characters)
+
+# Script-specific
+\p{Script=Greek}
+\p{Script=Han}
+\p{Script=Arabic}
+```
+
+> **Note:** Unicode property support varies by engine. JavaScript requires `/u` flag. Go RE2 supports `\p{L}` etc. Python `re` does NOT support `\p{}`—use the `regex` package.
+
+---
+
+## 8. Flags
+
+```
+g       Global: find all matches
+i       Case-insensitive
+m       Multiline: ^ and $ match line boundaries
+s       DotAll: . matches newline characters
+u       Unicode: enables \p{}, correct surrogate pair handling
+x       Extended/Verbose: ignore whitespace, allow comments (Python, Ruby, PCRE)
+y       Sticky: match at exact position (JavaScript)
+```
+
+---
+
+## 9. Debugging
+
+1. Use [regex101.com](https://regex101.com) — supports multiple engines
+2. Break complex patterns into named pieces and compose them
+3. Test incrementally — start simple, add one element at a time
+4. Test edge cases: empty string, very long string, Unicode, newlines
+5. Log intermediate results (capture groups)
+
+### Common Mistakes
+
+```
+/file.txt/           # Dot matches anything — matches "file_txt"
+/file\.txt/          # Correct: escaped dot
+
+/\d{3}/              # Matches "123" inside "abc12345def"
+/^\d{3}$/            # Correct: anchored to exact 3 digits
+
+/<.*>/               # Greedy: matches entire "<a>text</a>"
+/<[^>]*>/            # Correct: negated class
+```
+
+---
+
+## 10. When NOT to Use Regex
+
+### Use a Parser Instead
+- HTML/XML — use DOM parser (cheerio, BeautifulSoup, lxml)
+- JSON, YAML, TOML — use a parser
+- Nested structures — regex cannot handle arbitrary depth
+- Programming language syntax — use tree-sitter, ANTLR
+
+### Use String Methods Instead
+```
+# Prefer:
+startsWith('prefix')    over    /^prefix/.test(str)
+endsWith('suffix')      over    /suffix$/.test(str)
+includes('text')        over    /text/.test(str)
+split(',')              over    split(/,/)
+```
+
+### When Regex IS Right
+- Pattern matching in text (log parsing, data extraction)
+- Input validation (format checks)
+- Search and replace with pattern awareness
+- Tokenizing simple grammars (CSV, log lines)
+- Text cleanup (normalize whitespace, strip control characters)
+
+---
+
+## 11. Critical Reminders
+
+### ALWAYS
+- Anchor with `^` and `$` when validating entire strings
+- Use non-capturing groups `(?:...)` when you don't need the value
+- Prefer negated character classes `[^"]*` over lazy `.*?`
+- Test with adversarial inputs for ReDoS
+- Escape user input before inserting into regex
+- Use Unicode flag for international content
+
+### NEVER
+- Parse HTML/XML/JSON with regex
+- Use nested quantifiers without understanding backtracking
+- Trust regex for email validation beyond basic format
+- Use `.` when you mean a specific character class
+- Build regex from untrusted input without escaping

package/template/.codex/skills/regex-patterns/references/go.md

@@ -0,0 +1,44 @@
+# Go Regex Patterns
+
+Language-specific API for the `regex-patterns` skill. Read `SKILL.md` first for universal syntax.
+
+---
+
+## Core API
+
+```go
+package main
+
+import (
+    "fmt"
+    "regexp"
+)
+
+func main() {
+    // Compile (returns error)
+    re, err := regexp.Compile(`^hello\s+(\w+)$`)
+    if err != nil {
+        panic(err)
+    }
+
+    // MustCompile panics on invalid pattern (for constants)
+    re = regexp.MustCompile(`\d+`)
+
+    // Methods
+    matched := re.MatchString("hello world")           // bool
+    result := re.FindString("abc 123 def")              // "123"
+    allResults := re.FindAllString("a1 b2 c3", -1)     // ["1", "2", "3"]
+    submatch := re.FindStringSubmatch("hello world")    // ["hello world", "world"]
+    replaced := re.ReplaceAllString("foo 123", "NUM")   // "foo NUM"
+
+    fmt.Println(matched, result, allResults, submatch, replaced)
+}
+```
+
+## Important: RE2 Engine
+
+Go uses the **RE2 engine** which guarantees linear-time execution (no ReDoS). Trade-off:
+- ✅ No backtracking — immune to ReDoS
+- ❌ No backreferences (`\1`)
+- ❌ No lookahead/lookbehind
+- ✅ Supports `\p{L}` Unicode properties