cfsa-antigravity 1.0.0

package/template/.agent/skills/parallel-debugging/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: parallel-debugging
+description: Leverage concurrent terminal background processes to debug multiple independent failures simultaneously using ACH methodology. Use when you have 2+ failures across different subsystems.
+---
+
+# Parallel Debugging via Concurrent Streams
+
+## Overview
+
+When a test suite or system has multiple independent failures, investigating them sequentially in a single terminal is slow. This skill teaches you to spawn multiple concurrent workstreams (e.g. background bash processes) per failure domain, investigating them simultaneously.
+
+**Core principle:** This is a concurrency layer on top of `systematic-debugging`, not a replacement. You must still follow the full four-phase debugging process for each stream.
+
+## When to Use
+
+- 2+ test failures across **different files or subsystems**
+- Multiple error types in logs from **independent components**
+- Post-refactor breakage across **unrelated modules**
+- Production incidents affecting **separate services**
+
+## When NOT to Use
+
+- **Related failures** — fixing one might fix others (investigate together first)
+- **Shared state** — concurrent terminal commands might interfere (e.g. mutating the same database table)
+- **Unknown scope** — you don't know what's broken yet (explore first, then go concurrent)
+- **Single root cause suspected** — one investigation is faster
+
+**Decision test:** If fixing Bug A could possibly affect Bug B, they are NOT independent. Investigate sequentially to avoid tool tool conflict.
+
+## The Protocol
+
+### Phase 1: Hypothesis Generation (ACH)
+
+Before dispatching agents, generate competing hypotheses:
+
+1. **List all failures** with their error messages, stack traces, and last-known-good state
+2. **Group by domain** — which failures share files, state, or call paths?
+3. **Independence test** — for each group, ask: "Could fixing group A change group B's behavior?"
+   - **Yes** → merge into one investigation
+   - **No** → independent, can parallelize
+
+```markdown
+## Failure Analysis
+
+| # | Failure | Domain | Files | Independent? |
+|---|---------|--------|-------|-------------|
+| 1 | `auth.test.ts` — token expired | Auth | `src/auth/*` | ✅ |
+| 2 | `api.test.ts` — 500 on /users | API handler | `src/api/users.ts` | ✅ |
+| 3 | `api.test.ts` — 500 on /users/me | API handler | `src/api/users.ts` | ❌ shares files with #2 |
+| 4 | `db.test.ts` — connection refused | Database | `src/db/*` | ✅ |
+
+→ Dispatch: 3 agents (merge #2 + #3)
+```
+
+### Phase 2: Concurrent Investigation
+
+For each independent failure domain, start a concurrent investigation stream:
+
+1. **Background Terminals**: Use your `WaitMsBeforeAsync` flag to run `npm run test -- path/to/failing.test.ts` in the background. Do this simultaneously for each independent domain.
+2. **Concurrent Analysis**: Check the status of all background commands concurrently. Read the logs side-by-side.
+
+**Constraint per stream:**
+- Mentally partition your execution space: Workstream 1 only looks at Files A and B. Workstream 2 only looks at Files C and D.
+- Do NOT try to `replace_file_content` without strict certainty that the files don't overlap.
+- Every stream still requires the full `systematic-debugging` methodology: gather evidence, find patterns, form hypothesis, test minimally.
+
+### Phase 3: Result Synthesis
+
+After all agents complete:
+
+```markdown
+## Debug Synthesis
+
+### Results
+| Agent | Domain | Root Cause | Fix | Confidence | Cross-Domain? |
+|-------|--------|-----------|-----|------------|---------------|
+| 1 | Auth | Expired token TTL config | Updated config | HIGH | No |
+| 2+3 | API | Missing null check on user.email | Added guard | HIGH | No |
+| 4 | Database | Connection pool exhausted | Increased pool size | MEDIUM | Possible |
+
+### Cross-Domain Discoveries
+[Agent 4 noted: connection pool exhaustion could cause API timeouts under load.
+This may be related to #2+3 under different conditions. Monitor after fix.]
+
+### Integration Verification
+- [ ] All agent fixes applied
+- [ ] No file conflicts between agents
+- [ ] Full test suite passes (not just fixed tests)
+- [ ] Cross-domain discoveries documented as issues
+```
+
+**Synthesis rules:**
+1. **HIGH confidence + no cross-stream overlap** → apply fixes concurrently using batched `replace_file_content` calls.
+2. **MEDIUM confidence** → apply sequentially and test between each.
+3. **Cross-stream discovery** → stop concurrent execution, investigate sequentially.
+
+### Phase 4: Integration Verification
+
+**Non-negotiable after merging all fixes:**
+
+1. Run full test suite (not just the tests each agent fixed)
+2. Check for new failures introduced by fixes
+3. Verify no files were modified by multiple agents
+4. Document cross-domain discoveries as issues for future investigation
+
+## Example: Real Session
+
+**Scenario:** 6 failures across 3 files after refactoring
+
+| File | Failures | Domain |
+|------|----------|--------|
+| `agent-tool-abort.test.ts` | 3 (timing issues) | Abort logic |
+| `batch-completion.test.ts` | 2 (tools not executing) | Batch processing |
+| `race-conditions.test.ts` | 1 (execution count = 0) | Race condition handling |
+
+**Independence test:** Abort logic, batch processing, and race conditions are separate subsystems. ✅
+
+**Dispatch:** Start 3 concurrent `run_command` tests in the background using `WaitMsBeforeAsync`, each tracing their subsystem. Check `command_status` concurrently for all 3.
+
+**Results:**
+- Stream 1: Replaced arbitrary timeouts with event-based waiting
+- Stream 2: Fixed event structure bug (`threadId` in wrong place)
+- Stream 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, applied via batched `multi_replace_file_content` calls, full suite tested and green.
+
+## Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Parallelizing related failures | One fix breaks another stream's assumptions | Independence test FIRST |
+| Mismatched file edits | `replace_file_content` fails with hash mismatched | Ensure file scopes are 100% independent |
+| Skipping systematic-debugging phases | Guessing instead of investigating | Run the actual tests concurrently |
+| Running tests on shared DB | State leaks between background tests | Mock DB or run sequentially |
+| Skipping integration verification | Silent regressions from fix interactions | Full suite after merge |

package/template/.agent/skills/parallel-feature-development/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: parallel-feature-development
+description: Prevent tool call conflicts when making concurrent edits across a codebase. Establishes strict file ownership, interface contracts, and merge strategies. Use with parallel-agents when executing concurrent `replace_file_content` calls.
+---
+
+# Concurrent Feature Development
+
+## Overview
+
+When making concurrent code edits (e.g. implementing the frontend and backend of a slice simultaneously), the #1 risk is **file hash conflicts** — trying to execute multiple `replace_file_content` calls on the same file, which causes the operation to fail. This skill prevents that with strict file ownership, typed interface contracts, and batched execution.
+
+**Core principle:** One concurrent stream per file, always. No exceptions. If two streams need the same file, they're not independent — restructure the decomposition.
+
+## When to Use
+
+- Implementing multiple surfaces (e.g. `BE` and `FE`) in the same turn
+- A phase plan has slices that can be implemented concurrently
+- Multiple features touching different subsystems simultaneously
+- Any time `parallel-agents` is used for implementation (not analysis)
+
+## When NOT to Use
+
+- Single agent doing sequential work
+- Agents only analyzing/reviewing (no code changes)
+- All changes are in the same file or module
+
+## The Cardinal Rule
+
+```
+ONE OWNER PER FILE. NO EXCEPTIONS.
+```
+
+If Stream A owns `src/auth/login.ts`, no other stream may modify that file — not even to add an import.
+
+## The Protocol
+
+### 1. Ownership Declaration
+
+Before writing code concurrently, create an explicit mental or written ownership manifest:
+
+```markdown
+## File Ownership Manifest
+
+| Stream | Owned Files | Interface Files |
+|--------|-------------|-----------------|
+| Stream 1 (Auth) | `src/auth/*`, `src/middleware/auth.ts` | `src/types/auth.ts` |
+| Stream 2 (API) | `src/api/*`, `src/middleware/api.ts` | `src/types/api.ts` |
+| Stream 3 (UI) | `src/components/*`, `src/pages/*` | `src/types/ui.ts` |
+
+### Shared Files (Frozen)
+- `src/types/shared.ts` — modify only in synthesis step
+- `src/config.ts` — frozen during parallel work
+- `package.json` — frozen during parallel work
+```
+
+**Rules:**
+- Every source file to be edited appears in exactly ONE workstream
+- Shared files are **frozen** — do not mutate them concurrently
+- If a stream needs a change to a shared file, document it as a `// BOUNDARY:` stub
+- Interface files define the contract between streams
+
+### 2. Interface Contracts
+
+Before generating concurrent edits, define the typed interfaces they'll communicate through:
+
+```typescript
+// src/types/auth.ts — Stream 1 PRODUCES this, Stream 2 CONSUMES it
+export interface AuthResult {
+  userId: string;
+  roles: string[];
+  token: string;
+}
+
+// src/types/api.ts — Stream 2 PRODUCES this, Stream 3 CONSUMES it
+export interface UserResponse {
+  id: string;
+  name: string;
+  email: string;
+}
+```
+
+**Contract rules:**
+- Interfaces are strictly defined BEFORE generating logic
+- Do NOT change interface files during the concurrent implementation phase
+- Each interface has exactly one PRODUCER and one or more CONSUMERS
+- Develop against the interface, not assumptions
+
+### 3. Batched Tool Execution
+
+When generating concurrent tool calls in the same turn:
+
+```markdown
+## Stream: [Role]
+
+### Your Owned Files
+[Explicit list — you may ONLY create/modify these files]
+
+### Frozen Files (DO NOT MODIFY)
+[List of shared files — read but never write]
+
+### Interface Contract
+[The interfaces you produce and consume]
+
+### Boundary Protocol
+If you need something from another stream's domain:
+1. Import the interface type (read-only)
+2. Code against the interface, not the implementation
+3. Add a `// BOUNDARY:` comment if you need a shared file change
+```
+
+### 4. Merge Protocol
+
+Always execute edits that don't overlap in a single batched `multi_replace_file_content` call, but conceptually process dependencies:
+
+```
+1. Interface files (already defined, verify no changes)
+2. Stream with fewest dependencies first
+3. Stream with most dependencies last
+4. Shared file modifications (from BOUNDARY stubs)
+```
+
+**Execution checklist:**
+- [ ] No file appears in multiple streams' edits
+- [ ] All interface contracts satisfied (types compile)
+- [ ] Shared file BOUNDARY stubs resolved in a sequential commit
+- [ ] Full test suite passes after the batched edit
+
+### 5. Conflict Resolution
+
+If despite everything, a conflict is detected:
+
+| Conflict Type | Resolution |
+|---------------|-----------|
+| **Same file modified** | `replace_file_content` block. Separate edits into sequential tool calls. |
+| **Interface mismatch** | Producer's implementation doesn't match contract → fix producer |
+| **Missing dependency** | Assumed something exists that doesn't → add BOUNDARY stub |
+| **Mutual dependency** | A needs B's output AND B needs A's output → can't go concurrent, code sequentially |
+
+## Integration with Kit
+
+- **With `session-continuity` Protocol 9 (Parallel Claim):** When tasks in progress files have surface tags (`BE`, `FE`, `QA`) and claim markers (`[!]`), the `files:` blocks under claimed tasks serve as your live ownership manifest. By analyzing these blocks, you can safely batch `replace_file_content` calls for both `FE` and `BE` tasks simultaneously.
+- **With `boundary-not-placeholder`:** Use `// BOUNDARY:` stubs for cross-stream dependencies you can't resolve concurrently. Resolve them sequentially afterward.
+- **With `implement-slice`:** When a slice enters parallel mode (step 1.5), claim all tags concurrently. The synthesis step (6.5) resolves BOUNDARY stubs on frozen files.
+
+## Example: Concurrent Vertical Slice
+
+**Slice:** "User can view their profile"
+
+| Stream | Surface | Owned Files | Produces | Consumes |
+|--------|---------|-------------|----------|----------|
+| DB Stream | Schema | `migrations/003-profile.sql`, `src/db/profile.ts` | `ProfileRecord` type | — |
+| API Stream | Endpoint | `src/api/profile.ts`, `src/api/profile.test.ts` | `GET /api/profile` | `ProfileRecord` |
+| UI Stream | Component | `src/components/Profile.tsx`, `src/pages/profile.astro` | Rendered page | `GET /api/profile` |
+
+**Merge order:** DB → API → UI (dependency chain)
+
+**Frozen files:** `src/types/shared.ts`, `astro.config.mjs`, `package.json`
+
+## Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Two sub-tasks mutate the same file | Tool call conflict, lost edits | ONE STREAM PER FILE. NO EXCEPTIONS. |
+| No interface contracts | Mismatched assumptions | Define types BEFORE editing |
+| Skipping integration tests | Interfaces match but behavior doesn't | Full suite after batch edits |
+| Parallelizing tightly coupled code | Constant blocking, BOUNDARY stubs everywhere | Code sequentially |

package/template/.agent/skills/performance-budgeting/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: performance-budgeting
+description: "Axis-by-axis interview methodology for establishing engineering performance budgets during architecture PRD compilation. Use when conducting the Step 10.5 performance budget interview in /create-prd-compile."
+category: product
+risk: none
+source: self
+date_added: "2026-03-03"
+---
+
+# Performance Budgeting
+
+## Purpose
+
+This skill owns the interview methodology for establishing concrete, enforceable performance thresholds across all applicable surfaces.
+
+## When to Use This Skill
+
+- During `/create-prd-compile` Step 10.5 — the performance budget interview
+- Any time engineering performance standards need to be established from scratch
+- When updating `ENGINEERING-STANDARDS.md` for an existing project
+
+## Write-As-You-Go Rule
+
+Performance budgets are written **as you go** — each axis is discussed, decided, and immediately written to the corresponding subsection of `docs/plans/ENGINEERING-STANDARDS.md`. Do not batch them.
+
+## Surface Conditioning
+
+> **Surface conditioning**: Only present axes that apply to the confirmed tech stack surfaces. A CLI-only project skips Web Vitals and bundle-size axes. A web-only project skips Desktop and CLI axes. Always present API and DB axes.
+
+## Interview Protocol
+
+### Axis 0 — Target device tier and network baseline
+
+Before any threshold is chosen, anchor all budgets to an explicit operating context. Require named choices — no vague defaults.
+
+| Decision | Options (examples) |
+|----------|---------------------|
+| Target device tier | Low-end Android (Moto G Power), Mid-range (Pixel 7a), High-end (iPhone 15) |
+| Target network condition | Slow 3G (400 Kbps, 400 ms RTT), Fast 3G (1.6 Mbps, 150 ms RTT), 4G (9 Mbps, 50 ms RTT), Wi-Fi |
+
+Ask: "What is the lowest-spec device and slowest network your users will realistically use? All budgets will be validated against this baseline."
+
+**Write immediately** → `docs/plans/ENGINEERING-STANDARDS.md` § `## Performance Budgets` baseline note — fill in the `[device tier]` and `[network condition]` placeholders.
+
+### Axis 1 — Web Vitals per page type (web/desktop surfaces only)
+
+Define LCP, INP, and CLS targets **per page type** (e.g., landing, dashboard, detail). Different page types have different acceptable thresholds.
+
+| Page Type | LCP | INP | CLS | Notes |
+|-----------|-----|-----|-----|-------|
+| Landing / marketing | ≤ 2.0 s | ≤ 150 ms | ≤ 0.05 | First-impression page; tightest targets |
+| Dashboard / data-heavy | ≤ 2.5 s | ≤ 200 ms | ≤ 0.1 | Streaming data acceptable |
+| Detail / form | ≤ 2.0 s | ≤ 100 ms | ≤ 0.05 | Interaction-heavy; INP matters most |
+
+Ask: "Which page types does your app have, and do these starting points fit?"
+
+**Write immediately** → `docs/plans/ENGINEERING-STANDARDS.md` § `### Web Vitals per page type`
+
+### Axis 2 — JS bundle size per page type (web/desktop surfaces only)
+
+Define initial and total JS budgets **per page type**, gzipped.
+
+| Page Type | Initial JS (gzipped) | Total JS (gzipped) | Notes |
+|-----------|---------------------|--------------------|-------|
+| Landing / marketing | ≤ 80 KB | ≤ 150 KB | Must load fast on first visit |
+| Dashboard / data-heavy | ≤ 150 KB | ≤ 300 KB | Lazy-load heavy components |
+
+Ask: "Are there pages that pull in large libraries (maps, charts, editors)? Those need their own row."
+
+**Write immediately** → `docs/plans/ENGINEERING-STANDARDS.md` § `### JS Bundle Size per page type`
+
+### Axis 3 — API response time per tier
+
+Define p50, p95, and p99 targets **per tier**, not a single number for the whole API.
+
+| Tier | Description | p50 | p95 | p99 |
+|------|-------------|-----|-----|-----|
+| Tier 1 — Cached read | Response served from cache (Redis, CDN, in-memory) | ≤ 10 ms | ≤ 30 ms | ≤ 50 ms |
+| Tier 2 — Uncached read | Single-entity DB fetch or simple join | ≤ 30 ms | ≤ 80 ms | ≤ 150 ms |
+| Tier 3 — Write | Create, update, delete with validation | ≤ 80 ms | ≤ 200 ms | ≤ 400 ms |
+| Tier 4 — Background | Async jobs, batch processing, external calls | Best-effort | ≤ 1000 ms | ≤ 3000 ms |
+
+Ask: "Do any endpoints call external services? Those belong in Tier 4. Are there any endpoints that don't fit these four tiers?"
+
+**Write immediately** → `docs/plans/ENGINEERING-STANDARDS.md` § `### API Response Time per tier`
+
+### Axis 4 — DB query time per tier
+
+Define p50 and p95 targets **per query tier**.
+
+| Tier | Description | p50 | p95 |
+|------|-------------|-----|-----|
+| Tier 1 — Indexed point lookup | Primary-key or unique-index fetch | ≤ 5 ms | ≤ 15 ms |
+| Tier 2 — Indexed range scan | Range or list query on indexed column | ≤ 15 ms | ≤ 50 ms |
+| Tier 3 — Aggregation | COUNT, SUM, GROUP BY, window functions | ≤ 50 ms | ≤ 150 ms |
+| Tier 4 — Full-text / vector / analytical | Search, similarity, or reporting queries | ≤ 100 ms | ≤ 300 ms |
+
+Ask: "Are there any known heavy queries (reports, analytics)? Those belong in Tier 4. Any queries that don't fit these four tiers?"
+
+**Write immediately** → `docs/plans/ENGINEERING-STANDARDS.md` § `### DB Query Time per tier`
+
+### Axis 5 — Desktop / mobile surface budgets (if applicable)
+
+Define surface-specific budgets using the reference table:
+
+**Desktop**:
+| Metric | Starting point |
+|--------|---------------|
+| Cold start | ≤ 2 s |
+| Memory (idle / active) | ≤ 200 MB / ≤ 500 MB |
+| Installer size | ≤ 100 MB |
+| Window resize repaint | ≤ 16 ms (60 fps) |
+
+**Mobile**:
+| Metric | Starting point |
+|--------|---------------|
+| Cold launch | ≤ 1.5 s |
+| Warm launch | ≤ 0.5 s |
+| Battery drain (active) | ≤ 5 %/hr |
+| Download size | ≤ 50 MB |
+
+Ask: "Do these match your target devices and user expectations?"
+
+**Write immediately** → `docs/plans/ENGINEERING-STANDARDS.md` § `### Desktop surfaces` and/or `### Mobile surfaces`
+
+### Axis 6 — CI enforcement mapping
+
+For **every budget defined in axes 0–5**, name the enforcement tool and fail condition.
+
+| Budget Category | Enforcement Tool | Fail Condition | Fail vs. Warn |
+|----------------|-----------------|----------------|---------------|
+| Web Vitals | Lighthouse CI | Score below threshold | Fail |
+| Bundle size | size-limit | Exceeds per-page-type cap | Fail |
+| API response time | k6 / autocannon | p95 exceeds tier target | Warn (fail after baseline) |
+| DB query time | pgbench / query timer | p95 exceeds tier target | Warn (fail after baseline) |
+| Desktop/mobile | Platform profiler | Any metric exceeds threshold | Warn |
+
+Ask: "For API and DB budgets, should CI fail immediately or warn-then-fail after a baseline run?"
+
+**Write immediately** → `docs/plans/ENGINEERING-STANDARDS.md` § `### CI Enforcement`
+
+## Closing Summary
+
+Summarise all confirmed performance budgets. Ask: "Any axis you want to tighten, loosen, or add?"

package/template/.agent/skills/pipeline-rubrics/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: pipeline-rubrics
+description: "Scoring rubrics for all 5 pipeline layers (Vision, Architecture, IA, BE, FE). Use when auditing specs, running self-checks, or remediating ambiguity gaps."
+category: quality
+risk: none
+source: self
+date_added: "2026-02-28"
+---
+
+# Pipeline Rubrics
+
+Standardized scoring rubrics for every pipeline layer. Used by audit workflows, self-checks in compilation workflows, and remediation workflows.
+
+## When to Use This Skill
+
+- During `/audit-ambiguity` — load the rubric for the layer being audited
+- During document compilation self-checks — load the relevant rubric to validate before presenting
+- During `/remediate-pipeline` — load rubrics for adversarial scoring
+- Any time a two-implementer test is needed on a pipeline document
+
+## How to Use
+
+1. Identify the pipeline layer being scored
+2. Load the matching reference file from `references/`
+3. Score each dimension using the ✅ / ⚠️ / ❌ criteria
+4. Apply the scoring formula from `references/scoring.md`
+
+## Reference Files
+
+| Layer | File | Dimensions |
+|-------|------|------------|
+| Vision | `references/vision-rubric.md` | 7 |
+| Architecture | `references/architecture-rubric.md` | 15 |
+| IA | `references/ia-rubric.md` | 8 |
+| BE | `references/be-rubric.md` | 10 |
+| FE | `references/fe-rubric.md` | 10 |
+| Scoring | `references/scoring.md` | Formula + cross-layer checks |
+
+## Two-Implementer Test
+
+For every dimension: *"Would two different developers, reading only this spec with no other context, make the same decision?"*
+
+- If YES with a specific citation → ✅
+- If MAYBE or requires inference → ⚠️
+- If NO or content is absent → ❌
+
+## Related Skills
+
+- `resolve-ambiguity` — resolve gaps found by rubric scoring
+- `technical-writer` — rewrite sections that score ⚠️ or ❌
+- `code-review-pro` — adversarial review methodology

package/template/.agent/skills/pipeline-rubrics/references/architecture-rubric.md

@@ -0,0 +1,19 @@
+# Architecture Rubric (15 dimensions)
+
+| # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
+|---|---|---|---|---|
+| 1 | Tech Stack Decisiveness | Every applicable axis has a named technology + rationale + what alternatives were rejected and why. No axis uses "TBD" or "standard". | Some axes decided, some TBD or rationale missing | Major axes undecided |
+| 2 | System Architecture | Every component is named. Every communication path has a protocol. Every component has a defined failure mode and fallback. Data flow is traced end-to-end with every hop named. Observability documented: logging library named, log format specified, PII scrubbing fields named, tracing boundaries named, alerting thresholds are numbers. | Some components or flows missing, or failure modes absent, or observability present but logging/tracing/alerting any one of these is missing or undocumented | Diagram only, no flows or failure modes; or no observability section at all |
+| 3 | Data Strategy | Every entity has a named canonical store. Every hot query path is identified. Migration strategy names the tool and approach. PII fields are enumerated by name. | Some entities without canonical store, or PII not enumerated | Sketched only |
+| 4 | Security Model | Auth flow is step-by-step. Every role has an explicit permission list. Rate limits are numbers (not "standard"). Input validation names the library and where it runs. | Some flows vague or rate limits unspecified | Not addressed |
+| 5 | Compliance Depth | Every regulated domain (minors, payments, health) has its own section with: account type hierarchy, consent flows, content filtering rules, audit requirements. No compliance domain is a sub-bullet. | Mentioned but in a sub-bullet without full depth | Not addressed |
+| 6 | API Design | Versioning strategy is named. Error format is defined (fields, types). Pagination strategy is named with parameters. Rate limit headers are specified. | Some conventions missing | Not addressed |
+| 7 | Integration Robustness | Every external service has: what it provides + failure mode + fallback strategy + cost model. No external is listed without a fallback. | Some externals missing fallback or cost model | Externals unnamed |
+| 8 | Phasing Clarity | Every phase has: entry criteria + exit criteria + dependency list. No phase uses "when ready" as a criterion. | Phases listed without entry/exit criteria | No phasing |
+| 9 | Engineering Standards | Every threshold is a concrete number (coverage %, response time ms, bundle size KB). No threshold uses "good", "acceptable", or "TBD". Every threshold row names its enforcement tool (CI action, load test, profiler) — a threshold without a named enforcement tool is treated as incomplete. Performance budgets are per-page-type for web/desktop and per-tier for API and DB. | Some thresholds concrete but enforcement tool missing for one or more rows, or budgets use a single number for the whole app rather than per-page-type or per-tier | Thresholds missing entirely, or majority lack enforcement mechanisms |
+| 10 | Persistence Architecture | Persistence map complete — all query types (find, store, relate, rank/search) mapped to a named store with rationale. Every entity spanning multiple stores has a documented cross-store consistency contract covering: canonical ID, creation sequence (with failure recovery), deletion cascade, and read join strategy. No store is chosen without a traced feature requirement. | Persistence map present but one or more cross-store entities missing their full consistency contract | No persistence map; single DATABASE decision with no query-type analysis |
+| 11 | Error Architecture | Global error envelope defined with all four fields typed and a locked example JSON produced. Error propagation chain documents every layer (DB, service, API handler, transport, client) with explicit catch/log/expose rules. Unhandled exception strategy names the process-level mechanism, log fields, client response, and alerting timeline. Client fallback contract covers every surface with offline decision, UI behaviour, retry strategy, and timeout. Error boundary strategy names placement and fallback rendering for all applicable surfaces. | Envelope defined but propagation chain incomplete, or client fallback missing for one surface | No global error envelope; error handling left to individual spec writers |
+| 12 | Attack Surface Coverage | Secret management plan documented (storage, access policy, rotation). Dependency audit cadence named with CI gate behaviour. Web surface: all OWASP Top 10 categories addressed with named mechanisms (not "handled by framework"). API surface: BOLA/IDOR addressed with per-endpoint ownership check strategy. Security headers documented with configured values (not just "enabled"). Observability: logging strategy documented (library, format, PII fields named), tracing documented (boundaries, sampling rate), alerting thresholds named with numbers. | Some surface checks present but one or more OWASP categories use vague mechanisms, or security headers missing configured values, or observability partially documented | No attack surface review present; secret management not documented |
+| 13 | Observability & Operability Strategy | Runbook locations are named and linked. On-call escalation path defined with owner, contact method, and escalation timeline. At least one dashboard per service named with its hosting location. SLO defined per critical endpoint with a numeric target (e.g., "p99 < 300ms"). Mean-time-to-detection strategy named (what triggers the alert, which tool, which threshold number). Alert fatigue strategy addressed (severity tiers defined, silencing rules documented). | Some items present but runbooks missing, or SLOs not numeric, or escalation path absent, or dashboard named without hosting location | No operability strategy; observability only mentioned as sub-bullets in other dimensions with no dedicated analysis |
+| 14 | Cost Architecture | Baseline cost documented (cost at 0 users / idle infrastructure). Scaling curve documented for at least two load points (e.g., 1k and 10k users) showing which component drives cost growth. Highest-cost operation per user action identified by name. Cost observability mechanism named (specific tool or method for seeing cost per feature or endpoint). Budget ceiling defined with a number and currency. | Cost mentioned but scaling curve absent, or budget ceiling missing, or no per-operation analysis, or cost observability mechanism unnamed | No cost analysis present; cost considerations absent from the architecture document |
+| 15 | Testability Architecture | Test suite can run without live external network calls — dependency injection or service mocking strategy is named explicitly. Service boundaries are injectable for mocking (confirmed, not assumed). Local-dev environment topology mirrors production (or deviations are explicitly documented with rationale). Architecture avoids global shared mutable state that would create test-order dependencies — or an isolation strategy is named. Integration test data strategy documented (seed data approach, factory pattern, or test containers named). | Some criteria met but mocking strategy missing or undocumented, or local-dev parity undocumented, or test data strategy absent | No testability architecture consideration; testability left entirely to the implementation phase with no architectural decisions to support it |

package/template/.agent/skills/pipeline-rubrics/references/be-rubric.md

@@ -0,0 +1,21 @@
+# BE Rubric (11 dimensions)
+
+| # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
+|---|---|---|---|---|
+| 1 | Upstream Traceability | (a) Every endpoint cites its IA source shard + section. (b) Every schema field traces to an IA data model field. No endpoint is "inferred" from context. (c) Every sub-feature listed in the IA shard's `## Features` is represented by at least one endpoint in the BE spec — a sub-feature with zero endpoints and no explicit `[Deferred to Phase N]` note is a gap. | Some endpoints or fields missing IA citations, or ≤20% of sub-features lack endpoint representation | Orphan endpoints with no IA source, or >20% of sub-features have no endpoint and no deferral note |
+| 2 | Contract Completeness | Every endpoint has: Zod request schema (all fields typed) + Zod response schema (all fields typed) + error schema. No field uses `any`, `unknown`, or untyped `string` where a more specific type exists. | Some schemas present but fields untyped or missing | Major schemas absent |
+| 3 | Error Exhaustiveness | Every endpoint has: HTTP status code + application error code (not just HTTP) + error message format + retry guidance. No endpoint uses "standard error handling" without defining it. | Some endpoints missing error codes or retry guidance | Generic 500s or no error section |
+| 4 | Schema Completeness | Every database table has: all fields with types + constraints (nullable, unique, indexed) + relationships with foreign keys + indexes for every query pattern. No field uses "standard" constraints without defining them. | Constraints or indexes missing | Sketched only |
+| 5 | Middleware Explicitness | Every endpoint has an explicit middleware matrix: auth required (yes/no) + rate limit (number/window) + input validation (where it runs) + CORS policy. No endpoint inherits "default middleware" without defining it. | Some endpoints missing middleware entries | No matrix |
+| 6 | State Transitions | Every stateful entity has a state machine: all states named + all valid transitions + what triggers each transition + what's blocked in each state. | Lifecycle mentioned but transitions or triggers missing | No lifecycle |
+| 7 | Concurrency | Every write operation has an explicit concurrency strategy: optimistic locking, pessimistic locking, idempotency key, or "single writer" with justification. No operation uses "handle concurrency" without a named strategy. | Mentioned but strategy not named | Not addressed |
+| 8 | Pagination & Limits | Every list endpoint has: pagination strategy (cursor/offset) + page size (default + max) + sort options + filter options. No endpoint uses "standard pagination" without defining it. | Some list endpoints missing pagination or limits | No strategy |
+| 9 | Integration Seams | Every external service call has: request format + response format + timeout (ms) + retry policy (count + backoff) + circuit breaker behavior. No integration uses "standard retry" without defining it. | Some integrations missing timeout or retry policy | Unnamed externals |
+| 10 | Security Rules | Every endpoint has explicit: authentication requirement + authorization check (which roles) + input sanitization + output filtering (what's excluded from response). No endpoint uses "standard security" without defining it. | Some endpoints missing auth or authz specification | Not mentioned |
+| 11 | Global Error Envelope Conformance | Every endpoint's error section explicitly cites the global error envelope from `architecture-design.md` `## Error Architecture` (e.g., `[error-architecture]` reference or direct quote of the envelope shape). No endpoint defines its own error shape that differs from the global envelope. The `code` field in every error response uses the application-specific enum, not a raw HTTP status string. | Envelope referenced on most endpoints but one or more endpoints define a local error shape without justification | No reference to the global error envelope anywhere in the spec; each endpoint invents its own error shape |
+
+> **Dimension 1 audit procedure**:
+> 1. Read the IA shard's `## Features` section and list every Level-1 sub-feature.
+> 2. For each sub-feature, search the BE spec for at least one endpoint that implements it. An endpoint "implements" a sub-feature if it directly creates, reads, updates, or deletes data for that capability.
+> 3. If a sub-feature has no endpoint, check for an explicit `[Deferred to Phase N — reason]` note in the endpoint completeness reconciliation table. If neither an endpoint nor a deferral note exists, score it as a gap.
+> 4. Score: ✅ if all sub-features are represented. ⚠️ if ≤20% of sub-features lack representation. ❌ if >20% of sub-features have no endpoint and no deferral note.

package/template/.agent/skills/pipeline-rubrics/references/fe-rubric.md

@@ -0,0 +1,20 @@
+# FE Rubric (11 dimensions)
+
+| # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
+|---|---|---|---|---|
+| 1 | Upstream Traceability | Every component cites its BE source spec + field. Every page cites its IA user flow. No component is "inferred" from context. | Some components or pages missing source citations | No mapping |
+| 2 | Component Inventory | (a) Every component has: name + props interface (all props typed) + children + variants. No component uses "standard props" or "typical interface". (b) Every IA user flow maps to at least one component or page entry in the FE spec — no user flow is unrepresented. (c) Every role-based rendering variant from the conditional rendering matrix (produced during `/write-fe-spec-classify` Step 4c.5) appears as a named component variant. | Some components missing props or variants, or some IA user flows not mapped to any component, or some conditional rendering variants missing | Vague component list, or IA user flows largely unrepresented, or no conditional rendering variants defined |
+| 3 | State Management | Every piece of state is classified: server state (which query) + client state (which store) + URL state (which param). Loading, error, and empty states are defined for every async operation. | Some state unclassified or async states missing | Unspecified |
+| 4 | Interactions | Every interactive element has: trigger + action + feedback (visual + timing). Every form has: validation rules + error display + submission behavior + success behavior. | Some interactions implicit or missing feedback | Unspecified |
+| 5 | Routing | Every route has: URL pattern + auth guard (yes/no + redirect target) + page component + meta (title, description). No route uses "standard guard" without defining it. | Some routes missing guards or meta | Vague |
+| 6 | Responsive | Every component has behavior defined at: mobile (≤768px) + tablet (769–1024px) + desktop (≥1025px). No component uses "responsive" without defining the behavior at each breakpoint. | Mobile mentioned but tablet/desktop missing | Not addressed |
+| 7 | Accessibility | Every interactive element has: ARIA role + keyboard navigation + screen reader label. Every image has alt text policy. WCAG level is named. | Partial — some elements missing ARIA or keyboard nav | Not addressed |
+| 8 | Error/Loading States | Every data-fetching view has: loading skeleton/spinner + error message + retry action + empty state. No state uses "standard loading" without defining it. | Some states missing or using generic messages | None |
+| 9 | Performance | Every page has: bundle size budget + lazy loading strategy for heavy components + image optimization policy. No page uses "optimized" without a number. | Some pages missing budgets or lazy loading strategy | Not addressed |
+| 10 | Security Rules | Every form has: CSRF protection + input sanitization + output encoding. Every auth-gated view has: token validation + expiry handling + redirect on failure. | Some forms or views missing security rules | Not mentioned |
+| 11 | Design System Consistency | Every page component names its page archetype from design-system.md. Every loading/error/empty state uses the confirmed design language (skeleton vs. spinner, toast vs. inline error — no invention). Every navigation element is drawn from the global component inventory (not re-implemented). Motion durations and easing match the confirmed motion language. | Some components naming archetype but others missing; or some states using non-standard patterns | No reference to design-system.md; components invent their own layout conventions |
+
+> **Dimension 2 audit procedure**:
+> 1. Read the IA shard's `## User Interactions` section and list every user flow (each trigger → action → response sequence counts as one flow).
+> 2. For each user flow, search the FE spec's `## Component Inventory` and `## Page/Route Definitions` for at least one component or page entry that implements it. A flow is "implemented" if a component or page handles the trigger and renders the expected response. Score ⚠️ if some flows are unmapped. Score ❌ if IA user flows are largely unrepresented.
+> 3. Read the conditional rendering matrix from `/write-fe-spec-classify` Step 4c.5. For each non-trivial cell (any value other than `full` for the majority role), verify the FE spec's component inventory includes a named variant for that role × feature combination. Score ⚠️ if some variants are missing. Score ❌ if no conditional rendering variants are defined.

package/template/.agent/skills/pipeline-rubrics/references/ia-rubric.md

@@ -0,0 +1,19 @@
+# IA Rubric (8 dimensions)
+
+| # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
+|---|---|---|---|---|
+| 1 | Feature Enumeration | (a) Every feature from the vision's Must Have list appears in at least one shard. (b) Every feature has a clear scope boundary (what's in, what's out). (c) Every shard's `## Features` section contains Level-1 sub-features from `ideation.md` — not architecture headlines — and every sub-feature is represented in at least one section body (User Interactions, Data Model, Access Control, or Edge Cases). | Some features vague, scope unclear, or sub-features listed in `## Features` but not represented in any section body | Major Must Have features missing, or `## Features` contains only architecture headlines with no sub-feature detail |
+| 2 | Access Model | Every role has: a named role + an exhaustive list of what it CAN do + an exhaustive list of what it CANNOT do + escalation path. No role uses "standard access" without defining it. | Some roles defined but missing permission or restriction lists | No access model |
+| 3 | Data Model | Every entity has: named fields + field types + constraints + relationships with cardinality. No field uses "standard" or "typical" without defining it. | Structure present but field types or constraints missing | Absent |
+| 4 | User Flows | Every user flow has: trigger + step-by-step actions + system responses + error paths. No flow ends at "success" without defining what success looks like. | Happy path only, or flows missing error paths | None |
+| 5 | Cross-Shard Contracts | Every cross-shard reference is bidirectional and cites the specific section in the referenced shard. No reference uses "see shard N" without a section name. | One-way references or missing section citations | None |
+| 6 | Edge Cases | Every feature has ≥3 edge cases covering: concurrent access, invalid input, and deletion/cascade. No edge case uses "handle gracefully" without defining the handling. | Some edge cases listed but fewer than 3 per feature, or vague handling | None |
+| 7 | Deep Dive Coverage | Every referenced deep dive file exists and contains exhaustive subsystem detail (technology choice + rationale + phasing + failure modes + integration contracts). No deep dive is a skeleton. | Some deep dives exist but are partial or skeleton | Referenced deep dives missing or empty |
+| 8 | Testability | Every feature has ≥1 acceptance criterion in Given/When/Then format. No criterion uses "should work" or "should be fast" without a measurable threshold. | Some criteria present but not in Given/When/Then or missing thresholds | Mostly subjective |
+
+> **Deep Dive audit note**: When auditing dimension 7, read each deep dive file directly — do not infer its completeness from the parent shard's reference to it. A parent shard that links to a deep dive scores ⚠️ (not ✅) if the deep dive file itself is still a skeleton. Score ✅ only when the deep dive file contains exhaustive subsystem detail that an implementer could work from without asking questions.
+
+> **Dimension 1 audit procedure**:
+> 1. Read `docs/plans/vision.md` (and `ideation.md` appendix if present) to extract the authoritative list of Level-1 sub-features per domain.
+> 2. For each shard, open `docs/plans/ia/[NN-domain-name].md` and confirm every sub-feature from step 1 appears in the `## Features` section. Score ❌ if Must Have sub-features are missing entirely.
+> 3. For each sub-feature listed in `## Features`, verify it is represented in at least one section body (User Interactions, Data Model, Access Control, or Edge Cases). A sub-feature that appears only as a headline in `## Features` but has no corresponding detail in any section body scores ⚠️ — headline only = warning, not pass.

package/template/.agent/skills/pipeline-rubrics/references/scoring.md

@@ -0,0 +1,28 @@
+# Scoring Formula
+
+- ✅ = 0 points, ⚠️ = 0.5 points, ❌ = 1 point
+- `ambiguity% = (points / applicable_checkpoints) × 100`
+- Gaps found during Implementer Simulation are added directly to the punch list as ❌ items and also count toward the ambiguity score.
+
+## Cross-Layer Consistency Checks
+
+Run after all per-document scoring is complete, whenever the current layer is BE, FE, or the scope is `all`.
+
+| Check | How to Verify |
+|-------|---------------|
+| IA → BE coverage | For each user flow in each IA shard, verify a BE endpoint exists that handles it. Orphan endpoints or uncovered flows are ❌. |
+| BE → FE field mapping | For each BE response field, verify at least one FE component prop consumes it. Unmapped fields or props are ❌. |
+| IA → FE access control | For each access control rule in each IA shard, verify the FE spec has corresponding conditional rendering. Missing conditional rendering is ❌. |
+| Error code coverage | For each BE error code, verify the FE spec has a corresponding error state. Missing error states are ❌. |
+
+Write all cross-layer findings to a `## Cross-Layer Consistency` section in the layer's ambiguity report.
+
+## Document-to-Layer Mapping
+
+| Layer | Documents to load |
+|-------|-------------------|
+| Vision | `docs/plans/vision.md` |
+| Architecture | `docs/plans/*-architecture-design.md`, `docs/plans/ENGINEERING-STANDARDS.md` |
+| IA | `docs/plans/ia/index.md` + each shard listed + `docs/plans/ia/deep-dives/*.md` (list directory; include all files present) |
+| BE | `docs/plans/be/index.md` + each spec listed |
+| FE | `docs/plans/fe/index.md` + each spec listed |

package/template/.agent/skills/pipeline-rubrics/references/vision-rubric.md

@@ -0,0 +1,11 @@
+# Vision Rubric (7 dimensions)
+
+| # | Dimension | ✅ (must meet ALL criteria) | ⚠️ | ❌ |
+|---|---|---|---|---|
+| 1 | Problem Clarity | Single sentence. Names a specific user. Names a specific pain. Is falsifiable. | Vague, multi-problem, or untestable | Missing |
+| 2 | Persona Specificity | Each persona has: name + role + specific pain point + current workaround + success criteria + switching trigger. No persona uses "users" or "customers" without a role. | Named but missing ≥1 required field | Missing or generic "users" |
+| 3 | Feature Completeness | Every Must Have has ≥2 levels of sub-features. Every sub-feature has at least one edge case. MoSCoW categories are mutually exclusive. | Some Must Haves at Level 1 only, or missing edge cases | Missing MoSCoW or major features absent |
+| 4 | Constraint Explicitness | Every axis (budget, timeline, team size, compliance, performance) has a specific value or explicit "not applicable". No axis uses "standard" or "TBD". | Some axes addressed, some missing or vague | Missing |
+| 5 | Success Measurability | Every metric is a number with a unit and a timeframe (e.g., "p95 < 500ms at launch"). No metric uses "fast", "good", or "acceptable". | Directional only | Missing |
+| 6 | Competitive Positioning | ≥3 named competitors. Differentiation is a specific capability gap. Moat is a defensible mechanism. | Vague positioning or <3 competitors | Not addressed |
+| 7 | Open Question Resolution | Every open question has: owner + deadline + what decision it blocks. No question is listed without an owner. | Questions listed, no owners or deadlines | No questions section |