cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/rules/decision-classification.md

@@ -0,0 +1,113 @@
+---
+description: Product decisions belong to the user, architecture gets options, implementation belongs to the agent
+trigger: always_on
+---
+
+# Decision Classification
+
+> Product decisions belong to the user. Implementation decisions belong to the agent.
+> Architecture decisions get options. Never cross these lines.
+
+## The Problem
+
+AI agents either ask too many questions (overwhelming users with decisions a senior developer
+would just make) or make too many decisions silently (overriding user intent on their own product).
+Neither extreme is acceptable.
+
+## Three Categories
+
+### 1. Product Decisions — User Always Decides
+
+These define *what* gets built and *for whom*. The agent presents options, analysis, and
+trade-offs but **never decides**. It's the user's product — even if the "right" answer
+seems obvious to you.
+
+**Examples:**
+- What problem to solve, who the users are
+- Which features to include or exclude
+- Pricing model, monetization strategy
+- Brand, tone, target market
+- UX philosophy and interaction patterns
+- Feature prioritization (MoSCoW placement)
+- Business rules and domain logic
+- What "success" looks like
+
+**Agent behavior:**
+- Present options with trade-offs when you have insight
+- Share your recommendation with clear reasoning
+- Ask for their decision — don't assume it
+- Accept their choice even if you'd choose differently
+
+### 2. Architecture Decisions — Present Options, User Picks
+
+These define *how* the system is structured at a high level. The agent presents 2-3 options
+with trade-offs and a recommendation. The user chooses.
+
+**Examples:**
+- Database technology (PostgreSQL vs MongoDB vs SurrealDB)
+- Frontend framework (React vs Svelte vs Astro)
+- Hosting provider and deployment model
+- API style (REST vs GraphQL vs tRPC)
+- Auth provider and strategy
+- Caching layer and strategy
+- Real-time communication approach (WebSocket vs SSE vs polling)
+- Monolith vs microservices
+
+**Agent behavior:**
+- Present 2-3 options (not more — decision fatigue is real)
+- Lead with your recommendation and explain why
+- Include trade-offs for each option (cost, complexity, scalability, team fit)
+- Let the user choose — they may have context you don't
+
+### 3. Implementation Decisions — Agent Decides, User Can Override
+
+These are the decisions a senior developer makes without asking. The user shouldn't need
+to think about these — that's what the pipeline is for. Make the call, state what you
+chose and why, and move on. The user overrides if they disagree.
+
+**Examples:**
+- File naming conventions
+- Folder structure within established patterns
+- Variable and function naming
+- Error message formatting
+- Test file organization
+- Linting and formatting config
+- Import ordering
+- Code comment style
+- Git commit message format
+- Internal API response envelope structure
+
+**Agent behavior:**
+- Make the senior-dev call based on established patterns and best practices
+- State briefly what you chose and why (one sentence is fine)
+- Don't ask permission — but don't hide it either
+- If the user expresses a preference, adopt it immediately and apply it consistently
+
+## Escalation Principle
+
+**When uncertain about category, escalate upward:**
+
+- Could be implementation OR architecture? → Treat as architecture (present options)
+- Could be architecture OR product? → Treat as product (ask the user)
+- Any decision that affects the user's brand, revenue, users, or competitive position? → Always product
+
+## During Ideation Specifically
+
+The ideation phase is almost entirely product decisions. The agent should be asking far more
+questions than it answers. The ratio should feel like an interview, not a lecture.
+
+- Every feature choice → product decision → ask
+- Every user experience choice → product decision → ask
+- "How should we implement X?" → defer to `/create-prd` → note it and move on
+- "What technology for X?" → defer to `/create-prd` → note it and move on
+- Don't burden the user with implementation or architecture during ideation unless they bring it up
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Choosing a database without presenting options | ❌ Rejected. Architecture decision — present 2-3 options. |
+| Asking user what to name a variable | ❌ Rejected. Implementation decision — just decide. |
+| Deciding product pricing without asking user | ❌ Rejected. Product decision — user decides. |
+| Unsure if product or architecture? → treating as product | ✅ Correct. Escalate upward. |
+| Making file-naming call, stating choice briefly | ✅ Correct. Implementation decision. |

package/template/.codex/rules/extensibility.md

@@ -0,0 +1,52 @@
+---
+description: A mid-level developer must be able to add a feature by reading READMEs alone
+trigger: always_on
+---
+
+# Extensibility
+
+## The Rule
+
+**A mid-level developer must be able to onboard, understand, and extend any part of the codebase without the AI that generated it.** If they can't add a feature by reading the READMEs in the relevant directories, we've failed.
+
+## File Size Limits
+
+| File Type | Max Lines | Reasoning |
+|-----------|-----------|-----------|
+| Components | 200 | Extract sub-components if larger |
+| Utilities / lib | 300 | Split into focused modules |
+| Schema files | 150 | One domain per schema file |
+| Test files | 400 | Group by feature, split if needed |
+| Config files | 100 | Keep flat and readable |
+
+## Directory Documentation
+
+**Every directory that contains more than 2 files MUST have a `README.md`** explaining:
+
+1. What this directory contains
+2. How to add more of the same (the extension pattern)
+3. What conventions to follow
+4. Links to related directories
+
+## Naming Conventions
+
+Follow the project's established conventions in `.codex/instructions/patterns.md`. When no convention exists yet, use the stack's community standard.
+
+## Anti-Spaghetti Rules
+
+- No `any` types — use `unknown` and narrow with type guards
+- No circular imports — dependency graph must be a DAG
+- No business logic in components — components render, lib/ computes
+- No copy-paste patterns — if you wrote it twice, extract it
+- Same pattern everywhere — if existing code does X one way, new code does X the same way
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Component file over 200 lines | ❌ Rejected. Extract sub-components. |
+| Directory with 3+ files and no README.md | ❌ Rejected. Add one. |
+| Circular import detected | ❌ Rejected. Restructure dependencies. |
+| Copy-pasted logic in two files | ❌ Rejected. Extract to shared module. |
+| New code uses different pattern than existing code for same thing | ❌ Rejected. Match existing conventions. |
+| Clean, focused modules with README documentation | ✅ Correct. |

package/template/.codex/rules/memory-capture.md

@@ -0,0 +1,84 @@
+---
+description: Patterns, decisions, and blockers written to memory every conversation — empty memory files mean the pipeline never learns
+trigger: always_on
+---
+
+# Memory Capture
+
+> Every conversation that involves a decision, correction, surprise, or blocker MUST record it before the conversation ends. Empty memory files mean the pipeline never learns.
+
+## The Problem
+
+The pipeline needs shared memory that survives across runtimes. The canonical project memory lives in `.memory/`, with `.memory/wiki/patterns.md`, `.memory/wiki/decisions.md`, and `.memory/wiki/blockers.md` as the human-readable compiled files. This rule enforces writing to that shared memory instead of letting learning fragment across runtime-local silos.
+
+## When to Write
+
+| Trigger | What Happened | Target File | Format |
+|---------|---------------|-------------|--------|
+| User corrects me | "No, that's wrong" / "Don't do that" / "I told you to..." | `.memory/wiki/patterns.md` | Anti-pattern (PAT-NNN) |
+| User says "remember this" | Explicit instruction to retain information | `.memory/wiki/decisions.md` | Decision (DEC-NNN) |
+| Non-trivial decision made | Choice with ripple effects (see Protocol 06 triage) | `.memory/wiki/decisions.md` | Decision (DEC-NNN) |
+| Something blocks progress | External dependency, missing spec, tooling failure | `.memory/wiki/blockers.md` | Blocker (BLOCKER-NNN) |
+| Pattern emerges | Something works well or fails repeatedly | `.memory/wiki/patterns.md` | Pattern (PAT-NNN) |
+
+## How to Write
+
+### Patterns (`.memory/wiki/patterns.md`)
+
+```markdown
+### PAT-NNN: [Short description] (YYYY-MM-DD)
+- **Type**: best-practice | anti-pattern
+- **Confidence**: 0.5 (first occurrence) — increment by 0.1 on reuse, max 0.95
+- **Context**: When/where this applies
+- **Pattern**: What to do (or avoid)
+- **Source**: What triggered this entry
+```
+
+### Decisions (`.memory/wiki/decisions.md`)
+
+```markdown
+### DEC-NNN: [Decision summary] (YYYY-MM-DD)
+- **Problem**: What needed deciding
+- **Options considered**: At least 2
+- **Decision**: What was chosen and why
+- **Downstream**: What this affects
+- **Reversibility**: High | Medium | Low
+```
+
+### Blockers (`.memory/wiki/blockers.md`)
+
+```markdown
+### BLOCKER-NNN: [Description] (YYYY-MM-DD)
+- **Status**: active | resolved
+- **Impact**: What this blocks
+- **Resolution**: How it was resolved (if resolved)
+```
+
+## When NOT to Write
+
+- Routine/trivial tasks with nothing new learned — skip
+- Isolated implementation decisions (variable names, file paths) — skip
+- Repeating an existing pattern already logged — update confidence instead
+
+## Native Memory Sync (Codex)
+
+When running in Codex, memory capture is dual-write:
+
+1. Write the CFSA entry to the unified project memory at `.memory/wiki/{patterns|decisions|blockers}.md` (or through the shared memory MCP tools when available)
+2. Evaluate native-memory relevance and sync to Codex native memory store:
+   - User correction/preference → `feedback`
+   - User-specific preference/profile signal → `user`
+   - Project decision/blocker context with downstream impact → `project`
+   - External system pointer/where-to-look info → `reference`
+
+If a trigger requires CFSA logging and native-memory relevance, both writes are required in the same conversation.
+
+## Pre-Completion Check
+
+Before calling `notify_user` to report completion of ANY workflow or substantial task:
+
+1. **Scan this conversation** for triggers in the table above
+2. **If triggers found** → write entries to `.memory/wiki/*` and sync relevant items to native memory
+3. **If no triggers** → explicitly confirm: "No new patterns, decisions, or blockers to log"
+
+This check is **not skippable**. It applies to every pipeline stage, every conversation, every session.

package/template/.codex/rules/question-vs-command.md

@@ -0,0 +1,91 @@
+---
+description: Questions trigger discussion, commands trigger action — never act on a question
+trigger: always_on
+---
+
+# Question vs Command Discrimination
+
+> Questions trigger discussion. Commands trigger action. When in doubt, discuss.
+
+## The Problem
+
+AI agents are too agreeable. When a user asks "is that the right approach?" the agent
+treats it as an instruction to change something. This destroys user trust, derails
+collaborative decision-making, and produces work the user never asked for.
+
+**The rule is simple: never act on a question.**
+
+## Classification
+
+### Questions — Discuss, Don't Act
+
+The user is thinking out loud, seeking your analysis, or testing an idea. Your job is to
+**engage in discussion** — present trade-offs, share your reasoning, offer your recommendation,
+and let the user decide.
+
+**Signal words:** "is this right?", "should we?", "what do you think?", "would it be better?",
+"does it make sense to?", "couldn't we?", "what if we?", "I wonder if", "how about"
+
+**Any message ending with "?"** — even without signal words — defaults to question.
+
+**Agent response:**
+1. Acknowledge the question
+2. Present your analysis with trade-offs
+3. State your recommendation and why
+4. Wait for the user to decide
+
+**Never:** Modify code, change specs, restructure files, or take any action in response to a question.
+
+### Commands — Act, Then Explain
+
+The user is telling you to do something specific. Execute it, then explain what you did.
+
+**Signal words:** "do X", "change this to", "make it", "add a", "remove the", "update",
+"fix", "implement", "create", "delete", "move", "rename"
+
+**Agent response:**
+1. Execute the requested action
+2. Explain what you changed and why (briefly)
+3. Note any side effects or considerations
+
+### Ambiguous — Default to Discussion
+
+The user's intent is unclear. They might be questioning, venting, or requesting.
+
+**Signal words:** "this doesn't look right", "I'm not sure about X", "hmm", "that's
+interesting", hedging language ("maybe", "possibly", "sort of")
+
+**Agent response:** Ask for clarification.
+- "Would you like me to change this, or are you thinking through options?"
+- "I have some thoughts on this — want to discuss, or should I go ahead and make a change?"
+
+## Reinforcement Rules
+
+1. **Rhetorical questions are still questions.** "Shouldn't we use Redis here?" means
+   "let's discuss Redis." It does NOT mean "switch to Redis."
+
+2. **Questioning your work is not a change request.** "Is this the best structure for
+   this component?" means "explain your reasoning." It does NOT mean "restructure the
+   component."
+
+3. **Validate before destructive action.** Even for clear commands, if the action
+   modifies existing work (code, specs, design decisions), confirm before executing:
+   "I'll [specific change]. Want me to go ahead?"
+
+4. **Self-correction questions are especially dangerous.** When a user asks "wait, should
+   this actually be X instead?" — they are exploring, not commanding. Discuss the
+   trade-offs. The worst outcome is an agent that flip-flops between approaches because
+   the user was thinking out loud.
+
+5. **Never mistake frustration for instruction.** "This API is a mess" is not an
+   instruction to refactor the API. It might be — but ask first.
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Editing code because user asked "is this right?" | ❌ Rejected. That's a question — discuss. |
+| Refactoring because user said "this is messy" | ❌ Rejected. Frustration ≠ instruction — ask first. |
+| Switching approach because user asked "what about X?" | ❌ Rejected. They're exploring — discuss trade-offs. |
+| Question → discussion → user commands → action | ✅ Correct. |
+| Ambiguous input → clarification request | ✅ Correct. |

package/template/.codex/rules/security-first.md

@@ -0,0 +1,54 @@
+---
+description: Security-first — PII isolation, input validation, secret handling, no secrets in client
+trigger: always_on
+---
+
+# Security First
+
+## The Rule
+
+**Security is not a feature — it is the foundation.** Every line of code is written with the assumption that it will be attacked. PII must never leak. Secrets must never reach the client. Inputs must always be validated.
+
+## PII Isolation
+
+| Rule | Implementation |
+|------|---------------|
+| **No PII in AI payloads** | User data (email, name, DOB, payment info) is NEVER included in AI model requests |
+| **PII fields tagged in schemas** | {{CONTRACT_LIBRARY}} schemas mark sensitive fields for automated auditing |
+| **No PII in logs** | Structured logging with automatic PII redaction |
+| **No PII in error messages** | Error responses never include user data — use IDs and codes only |
+| **Encrypted at rest** | All PII fields encrypted in database |
+
+## Input Validation
+
+- **Every** API endpoint validates input with {{CONTRACT_LIBRARY}} — no exceptions
+- **Every** form validates client-side with {{CONTRACT_LIBRARY}} AND server-side with the same schema
+- **No** raw user input reaches a database query — always parameterized
+- **No** user input is rendered as HTML — always escaped
+- **Rate limiting** — Every public-facing endpoint must have rate limiting configured. No exceptions. Use the project's configured rate limiting utility (see `patterns.md` for the approach). Unauthenticated endpoints must have stricter limits than authenticated ones.
+
+## Secrets Management
+
+- **NEVER** hardcode secrets in source code
+- **NEVER** expose API keys in client-side bundles
+- All secrets via environment variables, accessed only in server-side code
+- API keys stored encrypted, decrypted only at request time
+
+## CSP & Headers
+
+Every response includes:
+- `Content-Security-Policy` — strict, no inline scripts
+- `X-Content-Type-Options: nosniff`
+- `X-Frame-Options: DENY`
+- `Strict-Transport-Security` — HSTS with long max-age
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| PII field in AI model request payload | ❌ Rejected. Strip before sending. |
+| API key hardcoded in source file | ❌ Rejected. Use environment variable. |
+| User input rendered as raw HTML | ❌ Rejected. Always escape. |
+| Public endpoint without rate limiting | ❌ Rejected. Add rate limiter. |
+| API endpoint without input validation | ❌ Rejected. Add {{CONTRACT_LIBRARY}} schema. |
+| Encrypted PII, parameterized queries, server-side secrets | ✅ Correct. |

package/template/.codex/rules/single-question.md

@@ -0,0 +1,59 @@
+---
+description: One question at a time with options, pros and cons, and a recommendation — never batch questions
+trigger: always_on
+---
+
+# Single-Question Flow
+
+> Never batch questions. One question at a time. Options, pros and cons, recommendation.
+
+## The Rule
+
+**Every question — to the user OR to yourself — follows the same structure:**
+
+1. **One question only.** Never ask multiple questions in a single message. If you have 5 things to ask, ask the first one. Wait for the answer. Then ask the second.
+
+2. **Present options.** List 2–4 concrete options (not open-ended "what do you want?").
+
+3. **Pros and cons.** Each option gets specific trade-offs — not vague qualities.
+
+4. **Recommend one.** State which option you'd choose and why. The user can override.
+
+## Applies to EVERYTHING
+
+This is not just for user-facing questions. It applies to:
+
+| Scenario | What This Means |
+|----------|----------------|
+| Asking the user a product decision | One decision at a time, options + recommendation |
+| Asking the user a preference | One preference at a time, options + recommendation |
+| Internal reasoning ("how should I structure this?") | Enumerate options, weigh trade-offs, pick one |
+| Ideation interviews | One domain/feature question at a time |
+| PRD stack decisions | One technology choice at a time |
+| Ambiguity resolution | One gap at a time |
+
+## Format
+
+```
+**[Question in plain language]**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A      | ...  | ...  |
+| B      | ...  | ...  |
+| C      | ...  | ...  |
+
+**Recommendation:** Option B — [specific reason why].
+```
+
+For internal reasoning, use the same structure but don't present it to the user — just apply the discipline internally and state your decision with brief reasoning.
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| "Here are 5 questions for you:" | ❌ Rejected. Ask one. |
+| "What do you think?" (open-ended, no options) | ❌ Rejected. Provide options. |
+| "Should we use X?" (no alternatives shown) | ❌ Rejected. Show at least 2 options with trade-offs. |
+| One question + 3 options + pros/cons + recommendation | ✅ Correct. |
+| "I chose X because [reason]" (internal, stated briefly) | ✅ Correct. |

package/template/.codex/rules/skill-mcp-first.md

@@ -0,0 +1,45 @@
+---
+description: Check skills and MCPs before reasoning on your own — leverage existing knowledge first
+trigger: always_on
+---
+
+# Skill and MCP First
+
+> Before doing anything yourself, check if a skill or MCP already knows how to do it.
+
+## The Rule
+
+**When you receive any task, BEFORE reasoning about how to do it:**
+
+1. **Scan skills.** Read through the skill names and descriptions already loaded in your context. If a skill matches the task or a sub-task, read its `SKILL.md` and follow it.
+
+2. **Scan MCPs.** Check if any connected MCP server provides tools relevant to the task. If so, use the MCP tool instead of inventing your own approach.
+
+3. **Only then think.** If no skill or MCP covers the task, proceed with your own reasoning.
+
+## Why
+
+| Without this rule | With this rule |
+|---|---|
+| You reinvent patterns already documented in skills | You leverage tested, refined procedures |
+| You ignore MCP tools and use workarounds | You use the right tool for the job |
+| Every session starts from scratch | Skills accumulate institutional knowledge |
+| Quality varies by conversation | Skills enforce consistent quality |
+
+## What Counts as a Match
+
+- **Exact match**: Skill name/description directly describes the task → read and follow it
+- **Partial match**: Skill covers a sub-task or related concern → read it for relevant sections
+- **MCP match**: An MCP server has tools that handle part of the task → use them
+- **No match**: No skill or MCP is relevant → proceed with your own reasoning and note it
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| Writing a test strategy without checking `Testing Strategist` skill | ❌ Rejected. |
+| Debugging without checking `systematic-debugging` skill | ❌ Rejected. |
+| Designing an API without checking `api-design-principles` skill | ❌ Rejected. |
+| Reading skill → following its methodology → executing | ✅ Correct. |
+| No relevant skill found → proceeding with own reasoning | ✅ Correct. |
+| Using MCP tool instead of manual workaround | ✅ Correct. |

package/template/.codex/rules/source-before-ask.md

@@ -0,0 +1,93 @@
+---
+description: Before any question or decision, reason about what source documents are relevant, read them, then speak — never ask from summaries alone
+trigger: always_on
+---
+
+# Source Before Ask
+
+> Never present a question, decision, or recommendation to the user without first reading the source documents that inform it. Feature names are not features. Summaries are not specs.
+
+## The Rule
+
+**Before presenting ANY question, decision, option table, or recommendation to the user:**
+
+1. **Reason about relevance.** Ask yourself: "What domains, features, deep dives, CX files, or specs contain detail that affects THIS specific decision?" Think about second-order connections — a database decision doesn't just touch the "data" domain; it touches every domain that has complex query patterns, real-time sync, or graph relationships.
+
+2. **Read those documents.** Not the summary. Not the index line. The actual source files that contain the architectural detail. If a domain has deep dives (`[DEEP]` or `[EXHAUSTED]` status), read the deep dive files — they contain the information that changes the answer.
+
+3. **Cite what you found.** When presenting the question or decision, reference what you learned: "Based on the diagnostics deep dive, your multi-agent repair flow requires X, which means option A fits better than B because..."
+
+4. **Only then ask.** Now you're asking an informed question that the user can answer without doing your research for you.
+
+## The Per-Decision Research Loop
+
+This loop fires for EVERY decision point, not once per workflow:
+
+```
+For each question/decision/recommendation:
+  1. STOP — do not type anything to the user yet
+  2. THINK — what ideation/spec/CX content is relevant to THIS decision?
+     - Which domains does this decision affect?
+     - Which features have architectural constraints that change the answer?
+     - Which cross-cuts create dependencies?
+     - Which deep dives contain the detail I need?
+  3. READ — open and read those specific files now
+  4. SYNTHESIZE — what did I learn that affects this decision?
+  5. PRESENT — now ask the question, citing what you found
+```
+
+## Common Relevance Patterns
+
+| Decision Type | What to Read Before Asking |
+|--------------|---------------------------|
+| Frontend framework | Every domain with UI complexity, responsive requirements, offline-first features, real-time updates |
+| Database / persistence | Every domain with complex data relationships, sync requirements, search patterns, graph traversals |
+| AI/ML framework | Every domain that mentions AI, ML, diagnostics, recommendations, automation, agents |
+| Auth / security | Every domain's role matrix, CX files for cross-domain permission boundaries |
+| API design | Every domain's CX files for cross-domain data flow, every deep dive with integration points |
+| Deployment / hosting | Constraints file, every surface's performance requirements, offline capabilities |
+| State management | Every domain with real-time features, collaborative editing, optimistic updates |
+| Caching strategy | Every domain's query patterns, hot paths, data freshness requirements |
+
+## Why
+
+| Without this rule | With this rule |
+|---|---|
+| Agent asks "which database?" based on a MoSCoW bullet | Agent reads the graph traversal deep dive and knows you need a graph-capable store |
+| User has to say "go read the docs" 15 times per session | Agent arrives at each question already informed |
+| Decisions feel generic — could apply to any project | Decisions are grounded in YOUR project's specific architecture |
+| Context evaporates after Step 0.5's bulk loading | Context is refreshed per-decision, exactly when it matters |
+| Agent asks questions the ideation already answered | Agent knows what's been decided and asks only what's open |
+
+## Applies To
+
+**Every pipeline stage.** This is not limited to `/create-prd`:
+
+| Stage | What This Means |
+|-------|----------------|
+| `/create-prd-stack` | Before each axis question, read the domains that axis touches |
+| `/create-prd-architecture` | Before each component design, read the domains that component serves |
+| `/create-prd-security` | Before each security item, read the role matrices and CX trust boundaries |
+| `/write-architecture-spec` | Before each interaction design, read the relevant domain deep dives |
+| `/write-be-spec` | Before each endpoint design, read the IA shard interactions that endpoint serves |
+| `/write-fe-spec` | Before each component spec, read the BE endpoints and IA interactions it consumes |
+| `/implement-slice` | Before each implementation decision, read the relevant specs |
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| "Which database do you prefer?" without reading any domain files | ❌ Rejected. Read the domains first — the answer might be obvious. |
+| Presenting 3 framework options with generic pros/cons | ❌ Rejected. Pros/cons must reference THIS project's specific needs. |
+| Asking a question the ideation deep dives already answered | ❌ Rejected. Read before asking. |
+| "Based on your diagnostics domain's multi-agent flow, you need X" | ✅ Correct. Informed by source material. |
+| Citing specific CX dependencies when recommending architecture | ✅ Correct. Research before recommendation. |
+| Re-reading a deep dive mid-workflow because THIS question needs it | ✅ Correct. Per-decision freshness. |
+
+## The Litmus Test
+
+Before sending any question to the user, ask yourself:
+
+> **"Could a user reasonably respond: 'Did you even read my ideation docs?'"**
+
+If the answer is yes — you didn't do this rule. Stop. Read. Then ask.

package/template/.codex/rules/specificity-standards.md

@@ -0,0 +1,64 @@
+---
+description: Every spec item must have testable acceptance criteria — no ambiguity, no adjectives, only numbers and types
+trigger: always_on
+---
+
+# Specificity & Depth Standards
+
+> No ambiguity downstream. No surface-level specs. Every element must be testable.
+
+## No Ambiguity: Testable Acceptance Criteria
+
+Every spec item, feature description, and requirement MUST have **testable acceptance criteria**.
+
+### Ambiguous vs. Concrete
+
+| ❌ Ambiguous | ✅ Concrete |
+|-------------|------------|
+| "Fast response times" | "P95 latency < 200ms for API responses" |
+| "Secure authentication" | "JWT with RS256, 15-min access token, 7-day refresh, httpOnly cookie" |
+| "User-friendly interface" | "Form validates on blur, shows inline errors, submits on Enter" |
+| "Handle errors gracefully" | "4xx returns `{ error: string, code: string }`, 5xx logs to Sentry" |
+
+### When Writing Specs
+
+- Numbers, not adjectives ("3 retries", not "retry several times")
+- Specific types ("string[]", not "a list")
+- Exact error behavior ("returns 409 with existing email", not "handles duplicates")
+- Concrete state transitions ("pending → processing → complete | failed")
+
+### When Writing Code
+
+- Explicit return types, not inferred
+- Named constants, not magic numbers
+- Error messages that identify the problem and suggest the fix
+
+## Depth Standards: Exhaustive Specifications
+
+Specs must go **deep enough** that an implementer needs zero clarification.
+
+### Architecture Spec Depth
+
+1. Every entity has all fields typed with constraints
+2. Every relationship has cardinality and cascade behavior
+3. Every endpoint has request/response schema, error codes, auth rules
+4. Every state machine has all transitions and guard conditions
+5. Every integration has retry policy, timeout, fallback behavior
+
+### Feature Spec Depth
+
+1. Every UI component has props typed, states enumerated, events listed
+2. Every form has validation rules per field with error messages
+3. Every API call has loading, success, and error UI states
+4. Every responsive breakpoint has layout behavior specified
+5. Every interaction has keyboard, mouse, and touch behavior defined
+
+## What Gets Flagged
+
+| Pattern | Verdict |
+|---------|---------|
+| "Fast response times" in a spec | ❌ Rejected. Specify P95 latency threshold. |
+| "Handle errors gracefully" | ❌ Rejected. Specify error codes and response shapes. |
+| Endpoint without typed request/response schema | ❌ Rejected. Add full schema. |
+| Form spec without per-field validation rules | ❌ Rejected. Specify each field. |
+| "P95 < 200ms", "returns 409 with `{error, code}`" | ✅ Correct. Testable and specific. |