---
name: "AI-Native Coding"
description: "Code patterns optimized for AI agents, not human habits. Explicit over implicit, flat over nested, self-documenting names, co-located context. AI should build complete full-stack systems with tight integration across all docs (CLAUDE.md, MEMORY.md, skills). Pushes beyond human coding patterns that limit AI capability."
version: "2.0.0"
updated: "2026-04-23"
---

# AI-Native Coding

## Principles

### 1. Explicit Over Implicit

```typescript
// BAD: const u = await db.get(id);
// GOOD: const user = await database.getUserById(userId);
```

- Everything needed to understand code is IN the code
- Not in heads, Slack, or meetings

### 2. Flat Over Nested

- Early returns, flat structure
- AI reads linearly
- `if (!user) return notFound();` not nested ifs

### 3. Co-Located Context

```typescript
// BAD: const LIMIT = 10;
// GOOD: /** Max form submissions per IP per 60s (CF KV rate limiter) */ const RATE_LIMIT_MAX_REQUESTS = 10;
```

### 4. Complete Over Incremental

- AI writes 500 lines in one pass
- Every function: all error cases, edge cases, types, validation, docs

### 5. Connected Over Isolated

- **CLAUDE.md** — describes system
- **README** — describes product
- **Code comments** — link related code
- **JSDoc `@see`** — link to API docs
- **Skills** — reference each other

## Full-Stack Integration (one pass per feature)

1. Schema (D1)
2. Validation (Zod shared)
3. API (Hono + JSDoc)
4. UI (component)
5. Test (E2E)
6. SEO (meta + structured data)
7. Analytics (PostHog event)
8. Docs (CLAUDE.md)
9. Deploy (wrangler)

## Documentation as Code

- **CLAUDE.md** — update on every architecture change. Remove stale refs on delete/move.
- **MEMORY.md** — preferences, patterns, corrections, project decisions.
- **Skills** — new capability → update skill. Deprecated → remove + note why.

## File Structure

- Source files: <300 lines (split at 200)
- Test files: <200 lines
- Names for scanability: `api-checkout.ts`, `stripe-service.ts`, `queries-users.ts`
- Imports order:
  1. External packages
  2. Internal modules
  3. Type-only imports

## AI Cost Management

| Use Case | API | Cost |
|----------|-----|------|
| Image gen | GPT Image 1.5 | ~$0.04 |
| Logo | Ideogram v3 | ~$0.03 |
| Video | Sora 2 | ~$0.10 |
| Alt text, translations, meta, keywords, a11y | Workers AI / Claude | $0 |

**Avoid:**

- AI background patterns (use CSS)
- AI icons (use Lucide)
- AI for simple text formatting

## Context Window Management

1. Use `_router.md` FIRST — load only needed skills
2. Reference `CONVENTIONS.md` (breakpoints, CSP, brand tokens, JSON-LD) — never duplicate
3. Prefer `file:line` pointers over pasting code blocks
4. Offload project decisions to `MEMORY.md`
5. **ToolSearch deferred tools** — bulk-load ALL at once (`query:"computer-use", max_results:30`); never one-by-one (each `select:` costs one full round-trip)

### Deduplication (canonical locations)

- Breakpoints, CSP, Hono starter, error envelope, Turnstile, deploy command, JSON-LD templates → `CONVENTIONS.md`
- Form test matrix, SEO audit, visual checklist → skill 07

## Research-Backed Patterns (2026)

- **AI-Native Development (InfoQ)** — Producer→Manager (review, don't write), Implementation→Intent (specs in markdown), Delivery→Discovery (multiple variants via worktrees), Content→Knowledge (knowledge bases from incidents)
- **CLAUDE.md Best Practices (HumanLayer)** — <200 lines (60 ideal). WHAT → WHY → HOW. Use `file:line` not snippets. Layer: global > team > personal.
- **Spec-Driven (Addy Osmani)** — Create `spec.md` before coding. Small single-purpose files. Commit after each task.
- **Code Comments for Agents** — Comment WHY not WHAT. Include gold standard reference. Show correct + incorrect examples.
- **Modern CSS (2026)** — `corner-shape: squircle`, Temporal API (replaces Moment.js), CSS scroll-driven animations (zero JS, 60fps)
- **llms.txt** — Add `/llms.txt` to every site with Quick Start + Architecture summary for AI discovery

## Ownership

- **Owns** — AI-native patterns, full-stack integration, docs-as-code, AI-optimized structure, creative AI cost management, context window strategy. See `STYLE_GUIDES.md` for Google TS + Node.js rules.
- **Never owns** — Implementation (→06), testing (→07), deployment (→08), design (→10), SEO (→28)

---
name: "Architecture Thought Loop"
description: "30-point recursive thinking checklist that runs at every architecture decision. Pre-mortem, inversion, constraint-first, state machines, error-first, cost modeling, MECE decomposition, parallel path exploration. Fractalated — each point can spawn sub-analysis."
version: "2.0.0"
updated: "2026-04-23"
---

# Architecture Thought Loop (***EVERY ARCHITECTURE DECISION***)

## Phase 0: Before Thinking About Solutions

### 1. Pre-Mortem

- Imagine launch failed; write 5 reasons why and address each in the design.
- "We launched and nobody signed up because `___`" / "broke because `___`" / "ran out of money because `___`"

### 2. Inversion

- Ask "what would guarantee failure?" — then avoid those things.
- If "no auth" guarantees failure, auth is mandatory.

### 3. Boundary Definition

- Define IN scope and OUT scope explicitly before anything else; write it down.
- Features not on the IN list do not exist this session.

### 4. Constraint Inventory

List ALL constraints before designing:

- **CF Workers** — 10ms CPU, 128MB memory, 25MB bundle
- **D1** — 5M rows free, no JOINs >3 tables efficiently
- **KV** — 100K reads/day free, eventual consistency
- **R2** — 10GB free, S3-compatible
- **Budget** — $0/mo target (free tier only initially)
- **Time** — one session to deploy
- **Users** — zero on day one; design for first 100, not first million

### 5. Competitive Snapshot

- Firecrawl the top 3 competitors before building anything.
- Extract pricing, features, design patterns, tech stack (via Wappalyzer). Beat them on one axis, match on the rest.

## Phase 1: Decomposition

### 6. User Story Decomposition

- Every feature: "As a [user type], I want [action] so that [benefit]."
- Vague benefit ("so that things are better") = feature isn't needed.

### 7. MECE Decomposition

- **Mutually Exclusive, Collectively Exhaustive** — covers all user needs with no overlap.
- Two features doing the same thing → merge. User need with no feature → add one.

### 8. User Journey Mapping

Walk the complete journey before coding any screen:

1. Visit landing → 2. Read value prop → 3. Click CTA → 4. Sign up → 5. Onboard → 6. First value moment → 7. Return trigger → 8. Upgrade → 9. Refer

Every step must exist. Every transition must be designed. Dead ends = churn.

### 9. Data Flow Tracing

For every entity, trace: enter → store → transform → display → export → delete

- Example: User → Clerk webhook → D1 `users` table → API `/me` → UI profile → CSV export → account deletion
- Any unclear step = architecture hole.

### 10. State Machine Modeling

Every entity has states. Map them:

```
User: anonymous → signed_up → onboarded → active → churned → deleted
Subscription: trial → active → past_due → canceled → expired
Invoice: draft → open → paid → void → uncollectible
```

Missing transition = code crash on that edge case.

## Phase 2: Design Decisions

### 11. API-First

- Define the API contract (Zod schemas + routes) BEFORE any UI or database code.
- API is truth; UI is a view; database is storage. No API field needed = no DB column needed.

### 12. Error-First Design

Design error states BEFORE the happy path:

- API down → retry + fallback UI
- Auth expires mid-session → redirect to login
- Invalid data → inline validation
- Payment fails → grace period + retry
- Database full → alert + degrade gracefully

### 13. Parallel Path Exploration

- Design 3 approaches for every major decision; argue each; pick the winner.
- Document the decision AND the rejected alternatives with reasoning.

### 14. Reversibility Check (Bezos One-Way/Two-Way Door)

- **Two-way door (reversible)** — pick in 5 seconds (column name, UI color, copy text).
- **One-way door (irreversible)** — spend 5 minutes (schema, auth provider, payment processor, domain).

### 15. Dependency Audit

For every new package:

- Can I do this without it? Bundle cost? Maintained? CF Workers compatible (no Node.js APIs)?
- **Rule** — >10KB bundle addition + buildable in <1h = build it instead.

## Phase 3: Quality Thinking

### 16. Simplicity Audit

- Remove 30% of features after designing. If core value survives, removed features were premature.
- Ship the simpler version; add features when users ask.

### 17. Performance Budget Allocation

200KB JS budget — divide BEFORE building:

- Framework (Angular) — ~100KB
- UI library (PrimeNG) — ~50KB
- Your code — ~30KB
- Third-party (Clerk, Stripe, PostHog) — ~20KB

Feature busting the budget → lazy load, server-side, or remove.

### 18. Security Threat Model (STRIDE)

For EVERY feature touching user data or money:

- **S**poofing / **T**ampering / **R**epudiation / **I**nformation disclosure / **D**enial of service / **E**levation of privilege

### 19. Accessibility-First Design

- Design for screen readers FIRST, then add visual polish.
- Coherent screen-reader experience forces correct information hierarchy.

### 20. Mobile-First Wireframe

- Sketch 375px layout before desktop. If a feature doesn't fit on mobile, question whether it belongs.

## Phase 4: Content & SEO Thinking

### 21. Content-First Design

- Write the ACTUAL headline, description, and CTA before designing the layout.
- Generic layouts with "Your headline here" produce generic products.

### 22. SEO Keyword Research

- Research the primary keyphrase BEFORE writing any copy (Google Autocomplete, Ahrefs free, Context7).
- Keyphrase determines: page title, H1, meta description, URL slug, alt text.

### 23. Copy Hierarchy

- **H1** — primary value prop (one per page) / **H2** — supporting benefits / **H3** — feature details / **CTA** — clear action verb.
- Can't write H1 in 8 words = don't understand the product.

## Phase 5: Infrastructure Thinking

### 24. Cost Modeling

Estimate monthly CF consumption before building:

- Workers: N requests × 10ms CPU / D1: N rows × N queries/day / KV: N reads/day / R2: N GB + N ops

Use cost-estimator agent. Exceeds free tier at 1000 users → redesign.

### 25. Failure Mode Analysis

| Service | What if down? | Fallback | Recovery |
|---------|--------------|----------|----------|
| Clerk | Auth fails | Cached session + retry | Auto-reconnect |
| Stripe | Payment fails | Queue + retry via Inngest | Webhook reconciliation |
| D1 | DB unavailable | KV cache fallback | Auto-retry |
| R2 | Storage unavailable | Serve cached version | Retry upload |

### 26. Migration Path

Design for today, document the escape hatch:

- **D1 → Neon** — when >3 table JOINs or >500MB
- **KV → Upstash Redis** — when need atomic ops or pub/sub
- **Clerk → self-hosted Authentik** — when >50K MAU or need SSO
- **Stripe → LemonSqueezy** — when need MoR for international tax

### 27. Integration Point Mapping

- List every external system; each is a failure point, a rate limit, and a cost.
- Example: Clerk → Stripe → D1 → R2 → Resend → PostHog → Sentry → CF Workers

## Phase 6: Meta-Thinking

### 28. Five Whys

- Ask "why" five times on every architecture decision until the choice is grounded in facts.

### 29. Second-Order Effects

- For every feature ask: what does it enable? what does it break?
- Second-order effects larger than the feature itself → defer it.

### 30. The "Delete It" Test

- After designing everything, ask "What if I deleted this feature entirely?"
- Product still works + users still get value → delete it. Every unbuilt feature = zero maintenance.

## Execution Pattern

For every architecture decision:

1. Phase 0 (pre-mortem, inversion, constraints) — 2 min
2. Phase 1 (decompose, MECE, journey, data flow) — 5 min
3. Phase 2 (API-first, error-first, 3 paths) — 5 min
4. Phase 3 (simplify, budget, STRIDE, a11y, mobile) — 3 min
5. Phase 4 (content-first, SEO, copy hierarchy) — 2 min
6. Phase 5 (cost, failures, migration, integrations) — 3 min
7. Phase 6 (five whys, second-order, delete test) — 2 min

**Total** — ~22 min of thinking saves 22 hours of rework

## Fractal Property

- Each of the 30 points can spawn sub-analysis.
- Pre-mortem → competitive research. Cost model → CF pricing analysis. STRIDE → security-reviewer agent.
- The thought loop IS the fractal — every facet generates new facets, each terminating at a clear decision.

---
name: "Autonomous Orchestrator"
description: "Master process that drives entire SaaS projects to completion with minimal user input. Spawns parallel child agents for independent work streams. Makes all creative, technical, and architectural decisions autonomously. Continuously improves until the product exceeds competitors."
version: "2.0.0"
updated: "2026-04-23"
---

# Autonomous Orchestrator

## Principles

1. Never present options — pick best, implement, log in commits
2. Complete execution — no stubs, no TODOs, all sub-tasks done
3. Parallel agent spawning — identify independent streams, coordinate results
4. Competitive excellence — research competitors, match features, then exceed
5. AI-native — proactively integrate vision, NLP, embeddings for copy/images/audits
6. Full tool access — use EVERY available MCP, API, Computer Use, and Browser tool; never self-restrict
7. Creative orchestration — chain tools across systems (Figma→code, Airtable→D1, Slack→notify, Computer Use→native app config); the orchestrator decides HOW, not IF

## Tool Inventory (Use Aggressively)

| Category | Tools | When |
|----------|-------|------|
| Desktop | Computer Use (full control) | Native apps, GUI automation, screenshots |
| Browser | Playwright MCP, Chrome MCP | Web scraping, form filling, E2E, visual verify |
| Infrastructure | Cloudflare MCP, Coolify MCP | Deploy, DNS, D1, R2, KV, containers |
| Code | GitHub MCP, Bash | PRs, issues, CI, any shell command |
| Design | Figma MCP | Extract designs, generate diagrams, screenshots |
| Data | Airtable MCP, Notion MCP, Plane MCP | Project tracking, content, task management |
| Communication | Slack MCP, Resend API | Notifications, alerts, team updates |
| Payments | Stripe MCP | Customers, subscriptions, invoices, products |
| Content | WordPress MCP, Firecrawl MCP | CMS, web scraping, content extraction |
| Automation | IFTTT MCP | Cross-service workflows, triggers, applets |
| AI | DeepSeek MCP, Workers AI, OpenAI | Second opinions, embeddings, inference |
| Analytics | PostHog MCP, Sentry MCP, GA4 | Events, errors, dashboards |
| Calendar | Google Calendar MCP | Scheduling, availability |
| Storage | Google Drive MCP | Documents, shared files |

Scan this inventory BEFORE planning. For every task ask: "Which combination of tools gets this done fastest?"

## Master Process Flow

### 1. ANALYZE

- Read context (CLAUDE.md, package.json, code), identify current vs desired state, research competitors, generate task list

### 1.5. ***ARCHITECTURE THOUGHT LOOP***

Run `01/architecture-thought-loop.md` (30-point checklist):

- **Phase 0** — pre-mortem, inversion, boundary, constraints, competitive snapshot
- **Phase 1** — user stories, MECE decomposition, user journey, data flow, state machines
- **Phase 2** — API-first contract, error-first design, 3 parallel paths, reversibility check
- **Phase 3** — simplicity audit (remove 30%), performance budget, STRIDE threat model
- **Phase 4** — content-first copy, SEO keyword research
- **Phase 5** — cost model, failure modes, migration paths, integration mapping
- **Phase 6** — five whys, second-order effects, delete test

~22 min of thinking saves 22 hours of rework. Skip NOTHING.

### 2. PLAN

Group into parallel streams, identify dependencies, create execution order.

### 3. EXECUTE (parallel)

Spawn agents, build completely, make creative decisions inline, deploy continuously.

### 4. VERIFY

E2E tests, Lighthouse, a11y (axe-core), responsive check (6 breakpoints).

### 4.5. ***UI COMPLETENESS SWEEP (MANDATORY — BLOCKS DONE)***

a. **Static scan** — grep `src/` for `Coming soon|TODO|placeholder|lorem|not implemented|stub|mock|fake|dummy|TBD|WIP`

b. **Playwright interactive** — click EVERY button (catch disabled/no-handler), submit EVERY form (valid+invalid), check EVERY link (catch 404s), verify EVERY image (catch broken/placeholder)

c. **Empty state check** — render pages with no data; what does user see?

d. **Loading state check** — throttle network; is there a skeleton or blank?

e. **Error state check** — block APIs; does UI handle gracefully or crash?

f. Playwright a11y tree snapshot ALL pages → axe-core scan → fix a11y/functional issues

g. Screenshot 2 key breakpoints (375 + 1280) → GPT Image 2 vision `detail:low` for aesthetic-only issues → rate 0-10

h. **Below 8/10 = NOT DONE.** Fix all findings. Max 3 rounds, $1 vision budget cap. Homepage/ATF gets vision priority.

i. Re-sweep. Loop until ALL pages ≥8/10 AND zero findings OR budget exhausted.

j. Log sweep results to `~/.claude/audit/sweep-results.jsonl` (Stop hook checks this)

### 5. ITERATE

Compare vs competitors, fix gaps, re-deploy, continue until exceeds.

### 6. DOCUMENT

Update CLAUDE.md, skills, memories. Descriptive commits.

## Agent Types

| Agent | Purpose |
|-------|---------|
| Competitive Researcher | Analyze competitor features |
| Frontend Builder | UI, pages, styles |
| Backend Builder | APIs, DB, auth |
| Test Runner | E2E, unit, integration |
| Visual Auditor | AI vision screenshot analysis |
| Deploy Agent | Build + deploy + cache purge |
| Copy Writer | Marketing, microcopy, SEO |
| Image Generator | Logos, icons, heroes via AI |

## Team Structure

```
Team Lead (claude-opus-4-6) — plans, coordinates
├── Frontend Agent (claude-sonnet-4-6) — UI, design, motion, a11y
├── Backend Agent (claude-sonnet-4-6) — API, DB, auth, webhooks
├── Quality Agent (claude-sonnet-4-6) — tests, security, perf
├── Content Agent (claude-haiku-4-5-20251001) — copy, SEO, media, docs
└── Deploy Agent (claude-haiku-4-5-20251001) — build, deploy, verify
```

- File ownership: frontend owns `src/app/`, backend owns `src/api/`
- Test agents never modify app code | deploy runs AFTER all builds complete

## ToolSearch Bulk-Loading (***CRITICAL***)

- When any computer-use tools are in the deferred list, load ALL in single call — `{ query: "computer-use", max_results: 30 }`
- Never load individual tools one-by-one (wastes one round-trip per tool)
- Same pattern for any deferred tool set — bulk-search by server name prefix, not `select:` for individuals

Custom agents from `~/.agentskills/agents/`: deploy-verifier, security-reviewer, test-writer, seo-auditor, visual-qa, computer-use-operator.

## Completion Criteria

- All features implemented (no stubs/TODOs) | deployed to production | E2E tests pass
- Lighthouse ≥90 | responsive at 375px and 1280px | axe-core 0 violations | CLAUDE.md updated
- `grep "Coming soon"` returns zero | every data array from real API endpoint
- Every button has working handler | GPT Image 2 vision visual verification converged on ALL routes

## Self-Healing Decision Tree

- **TRANSIENT (retry)** — rate limit → backoff; timeout → retry 2s; 503 → check Coolify; cache stale → rebuild
- **CODE BUG (fix)** — type error → fix types; null ref → add guard; logic → trace + fix; import → fix paths
- **ARCHITECTURE (reassess)** — wrong framework → propose alt; schema mismatch → redesign; structure wrong → refactor
- **EXTERNAL (degrade)** — API down → fallback; deprecated → replace; credentials expired → prompt once
- **SKILL MISMATCH (re-route)** — wrong skill → re-evaluate via `_router.md`; conflict → Skill 01 > specific > general

**Recovery** — detect → classify → fix → verify → if 3x same failure escalate one level → check for regressions

## Crons vs Completion

- Crons = monitoring ONLY (health, uptime, deploy status)
- Work completion = single deep session with parallel phases
- If `/loop` or `/schedule` invoked for work (not monitoring), warn user: "This is work completion, not monitoring. Running deep session instead."

## Spawn/Kill Pattern

- Decompose → parallel phases → agents complete + return (ephemeral, not persistent) → master merges → next phase
- Context >60% → `progress.md` → fresh agent
- 3x critical fail → alert brian@megabyte.space via Resend
- DONE when all Hard Gates pass + zero recommendations

**Worktree isolation** — each parallel agent gets isolated git worktree (`git worktree add ../worktree-frontend emdash/feat-xxx`). Agents cannot clobber each other's files. Merge after phase completion.

**SubagentStop hook** — `~/.claude/hooks/on-session-end.sh` fires when agent session ends. Auto-commits + pushes skill/memory changes to `heymegabyte/claude-skills`. Checks `~/.claude/audit/sweep-results.jsonl` — if latest sweep <8/10, blocks "done" and re-queues fixes.

## Anti-Patterns

- Pick best, not ask | no skeletons "for next session" | never sequential when parallel-safe
- No "good enough" | no "Coming soon" | no mock data | no "done" without AI vision proof
- No ignoring admin sections | no crons for work | no recurring tasks for one-run work

## Trigger/Stop Conditions

- **Trigger** — new project, "build this" / "make this better", returning to project with pending improvements
- **Stop** — exceeds all competitors, all quality gates pass, user explicitly says stop

## Ownership

- **Owns** — master orchestration, task decomposition, autonomous decisions, parallel agent coordination, completion criteria, continuous improvement loop, competitive iteration
- **Never owns** — implementation (→06), testing (→07), deployment (→08), design (→10), media (→12), policy (→01)

---
name: "Context Engineering"
version: "1.0.0"
updated: "2026-04-23"
description: "JIT retrieval, structured note-taking, tool result clearing, hybrid architecture, Goldilocks prompts. Anthropic's 5 techniques for managing context in agentic workflows. 3-tier multi-agent model. Compaction strategies."
---

# Context Engineering

Replaced "prompt engineering" as the discipline. **Context > prompting** — what the model sees matters more than how you ask.

## 5 Techniques (Anthropic Engineering)

- **JIT retrieval** — agents hold file paths/identifiers, load data at runtime. Never preload entire codebases. `grep`/`head` for targeted reads, not `cat *`.
- **Structured note-taking** — persistent notes outside context window (`progress.md`, `SPEC.md`) for multi-hour operations. Preserves coherence across compactions. Write before context >60%.
- **Tool result clearing** — safest compaction. Remove tool outputs, keep reasoning chain. Reconstructable data is disposable; decisions are not.
- **Hybrid architecture** — pre-load `CLAUDE.md` + rules (cacheable prefix) + allow autonomous exploration via tools. Static context sets policy; dynamic context discovers facts.
- **Goldilocks prompts** — XML/Markdown-sectioned, specific enough to guide, flexible enough for heuristics. System prompts >3000 tokens degrade reasoning. Rules: pipe-delimited one-liners. Skills: dense fragments. CLAUDE.md <200 lines.

## 3-Tier Multi-Agent Model

- **Tier 1 — In-process** — Claude Code subagents, same terminal, shared filesystem. Fast. Default.
- **Tier 2 — Local orchestrator** — 3-5 agents in isolated worktrees, task state files for coordination, file ownership enforced. Sweet spot for feature work.
- **Tier 3 — Cloud async** — overnight runs, return to a PR. Agent teams, remote triggers, `/ultraplan`.

**Coordination** — shared task list + dependency tracking + peer messaging + file locking. Each agent sees only files it owns (specialization > generalism). Token costs scale linearly with agent count.

## Context Budget

- Subagents — fill with 900K relevant context (skills + code + docs + web research). Return ≤200-word summary to main thread.
- Main thread — orchestrate only, never implement.
- Context >60% → save `progress.md` → spawn fresh.

## Anti-Patterns

- **Context rot** — agent understanding degrades as conversation grows. Compact proactively.
- **Autonomy outrunning verification** — every build step needs a check step.
- **Security blindspot** — 48% of AI-generated code contains security vulnerabilities (Becker study). Never skip review.
- **Idle time** — doubles in agentic mode. Keep agents busy, not developers waiting.

## Caching Strategy

- Deterministic load order: Tools → System → CLAUDE.md → rules (alpha) → skill descriptions → MEMORY.md → conversation
- Static prefix = cacheable (90% savings on repeated reads)
- Min cacheable: Opus 4096 tokens, Sonnet 2048 tokens
- Cache TTL: 5min default, 1hr with frequent access

## Ownership

- **Owns** — context window strategy, compaction triggers, subagent context loading, caching order, note-taking protocol, JIT retrieval patterns, multi-agent coordination
- **Cross-refs** — `autonomous-orchestrator.md` (Ralph Loop), `output-compression.md` (token reduction)

---
name: "one-line-saas"
description: "Execution chain for one-line SaaS prompts. Chains template→scaffold→parallel build→verify→ship."
version: "2.0.0"
updated: "2026-04-23"
---

# One-Line SaaS Execution Chain

When prompt is a one-liner implying a new product (domain name, product idea, or "build X"):

## Phase 0: Research (parallel agents, ~3min)

- **Agent A** — Firecrawl scrape 3-5 competitors → feature list + pricing + positioning
- **Agent B** — Keyphrase research via web search → primary keyphrase + 3 secondaries
- **Agent C** — Infer product type from domain (skill 02) → generate `PROJECT_BRIEF.md` + `SPEC.md` with all ACs
- **Agent D** — If existing website → scrape all pages, extract content + images + brand colors + logo

Research completes BEFORE any code. Builder receives pre-digested context, never calls APIs.

## Phase 1: Scaffold (<5min, sequential, informed by research)

1. `gh repo create <name> --template megabytespace/saas-starter --clone`
2. `cd` into it
3. Run `scripts/scaffold.sh <name> <domain>`
4. Live URL deployed before any feature code

Research data informs scaffold choices (stack, features, pages).

## Phase 2: Content+Media (parallel, ~5min)

- **Agent E** — Generate all copy: hero headline, features, meta desc, JSON-LD, pricing copy. Replace `SITE_NAME`/`HERO_HEADLINE`/etc placeholders in `index.html`.
- **Agent F** — Ideogram logo → favicon set → OG 1200x630 → hero image. Place in `public/`.
- **Agent G** — Generate project `CLAUDE.md` + `.claude/rules/` from brief.
- **Agent H** — Profile all collected images via GPT Image 2 vision → scores, placements, alt text (see skill 12 image-profiling).

## Phase 3: Build (parallel agents in worktrees, ~15min)

- **Agent I (backend)** — Auth webhooks, Stripe checkout/portal/webhooks, domain-specific API routes, Inngest workflows. Sentry + PostHog instrumentation on every route.
- **Agent J (frontend)** — Replace landing page placeholders with real content. Dashboard with real data. Auth pages via Clerk components. Uses pre-profiled images in suggested placements.
- **Agent K (tests)** — Write failing Playwright tests for every SPEC.md AC. Homepage → navigate → interact → verify. Test account flows.

## Phase 4: Verify (parallel, loop max 3)

1. deploy + purge
2. Parallel: deploy-verifier + seo-auditor + visual-qa + test-writer
3. Fix failures
4. Redeploy
5. Re-verify

## Phase 5: Launch

- Update saas-starter template if patterns improved
- Update `~/.agentskills` if new learnings
- Recommendations loop (skill 14) → implement until zero
- DONE

## Parallelization Map

```
Phase 0 [A|B|C|D] ──all complete──→ Phase 1 ──sequential──→
Phase 2 [E|F|G|H] ──all complete──→ Phase 3 [I|J|K] ──all complete──→
Phase 4 [verify loop] ──green──→ Phase 5 [launch]
```

- Main thread orchestrates only. Never implements.
- 11 parallel agents max across phases.
- Research-first: builder receives pre-digested context files, never calls APIs (see skill 06 pre-digested-builds).

---
name: Output Compression
description: Token-efficient output patterns reducing response size 40-65% without losing information density
version: "2.0.0"
updated: "2026-04-23"
---

# Output Compression

## Core Technique: Caveman-Style Output

- Strip articles, prepositions, filler words from technical output
- Example: "The function returns a list of the available configurations" → "fn returns available configs list"
- Reference: 44K-star caveman repo pattern — same info, 40-65% fewer tokens

## Abbreviation Table

- **config** → cfg
- **function** → fn
- **application** → app
- **repository** → repo
- **dependency** → dep
- **environment** → env
- **development** → dev
- **production** → prod
- **authentication** → auth
- **authorization** → authz
- **parameter** → param
- **argument** → arg
- **directory** → dir
- **command** → cmd
- **document** → doc
- **template** → tmpl
- **library** → lib
- **message** → msg
- **request** → req
- **response** → res
- **database** → db
- **middleware** → mw
- **specification** → spec
- **implementation** → impl

## Symbol Grammar

- `→` — leads to / becomes
- `|` — or / separator
- `+` — and / with
- `>` — preferred over
- `<` — less than
- `::` — maps to / defines
- `~` — approximately
- `!=` — not equal / differs from
- `&&` — both required
- `||` — either works
- `**text**` — emphasis
- `` `code` `` — inline reference

## Compression Techniques

### 1. Pipe-Delimited Fragments

```
# BAD (67 tokens):
- The first step is to configure the environment
- Then you need to install the dependencies
- After that, run the test suite
- Finally, deploy to production

# GOOD (23 tokens):
cfg env → install deps → run tests → deploy prod
```

### 2. Tables Over Paragraphs

```
# BAD: "WebP quality should be set to 80 which gives SSIM of 0.98 and is visually lossless.
#       AVIF quality should be 70 for the same perceptual quality but 30-50% smaller."

# GOOD:
| Format | Quality | SSIM | Size |
|--------|---------|------|------|
| WebP   | 80      | 0.98 | baseline |
| AVIF   | 70      | 0.98 | -30-50%  |
```

### 3. Code Over Prose

```typescript
// BAD: "You should create an interface with name, email, and optional phone fields"
// GOOD:
interface User { name: string; email: string; phone?: string; }
```

### 4. Skip Prefixes

Never:

- "Let me..."
- "I'll now..."
- "Here's what I found..."
- "Based on my analysis..."

Just output the result directly.

### 5. Batch Tool Calls

- Parallel independent calls in single response
- 3-5 tool calls/response when no dependencies

### 6. Single-Line Lists

```
# BAD:
# - First item
# - Second item
# - Third item

# GOOD:
first | second | third
```

## When NOT to Compress

- User-facing copy (marketing, UI text, docs) — use full natural language
- Error messages — be specific + helpful
- Explanations to non-technical users — clarity > brevity
- Legal/compliance text — precision required

## Density Targets

- **Rules files** — pipe-delimited one-liners, `→` and `|` separators, no prose wrappers
- **Skill files** — dense paragraphs, abbreviations, match sibling density
- **Chat responses** — 2 sentences, 100-160 chars for descriptions
- **Code comments** — intent not mechanics, JSDoc for public API only

## Ownership

- **Owns** — token efficiency, output formatting, compression patterns, abbreviation standards, density targets
- **Never owns** — content quality (→09), code style (→code-style rule), copy writing (→copy-writing rule)

---
name: "operating-system"
description: "Supreme policy layer governing all Claude Code behavior. Autonomy, one-line prompt interpretation, speed standards, emphasis signal processing, cross-skill coordination, done definitions, conflict resolution. Loaded every prompt."
metadata:
  version: "2.1.0"
  updated: "2026-05-03"
  effort: "high"
  model: "opus"
  internal: true
license: "Rutgers"
compatibility:
  claude-code: ">=2.0.0"
  agentskills: ">=1.0.0"
priority: 1
pack: "core"
stage: stable
triggers: []
paths:
  - "*"
---

# 01 — Operating System

Supreme policy. Loaded every prompt. Overrides all other skills.

## Philosophies (priority order)

1. **Hooks > rules > skills > prompts** — determinism beats hope
2. **Solo + AI builder doctrine** — `rules/solo-builder-doctrine.md`
3. **AI is foundational, not optional** — `rules/ai-permanence` (in `~/.claude/CLAUDE.md`)
4. **Cloudflare-first** — `rules/cloudflare-lock-in-is-leverage.md`
5. **Main-only branch** — `rules/main-only-branch.md`
6. **Pick ONE, never options** — `rules/brian-preferences.md`

## Autonomy default

- Inspect → decide → implement → verify → repair → document → report — WITHOUT asking
- Per `rules/autonomous-engineering.md` 4-tier: `autonomous | review-recommended | approval-required | blocked`
- Approval ONLY for: charging money, dropping tables, bulk customer outreach, secret rotation, billing changes, auth changes, bulk email/SMS, deleting major product area, mass mutation
- Everything else: just do it

## Hard Gates (every project)

1. Deployed + purged
2. Playwright E2E GREEN at 6 breakpoints (per `_kernel/standards.md#breakpoints`)
3. AI vision ≥9/10
4. Yoast GREEN
5. Lighthouse A11y ≥95, Perf ≥90
6. Zero errors / stubs / TODO in user-visible strings
7. Zero Recommendations
8. CSP Level 3 strict-dynamic + nonce
9. Trusted Types
10. All hyperlinks valid
11. INP ≤200ms (target ≤100ms cinematic per `_kernel/standards.md#cwv`)
12. JSON-LD per page (accurate types only — per `_kernel/standards.md#jsonld`)
13. Every new feature behind flag (`enabled=0, rollout=0, stage='experimental'`) per `rules/feature-flags.md`

## One-line prompt interpretation

Phrase → action:

- `make a website for X` / `build a site for Y` / `rebuild Z.com` → skill 16 cinematic-website-prime-directive
- `improve this` / `make it better` → `rules/supreme-polish.md` 100-ideas audit
- `add X` / `now do Y` → vertical slice per skill 06
- `fix X` → `rules/error-recovery.md` self-heal + write regression test
- `audit X` / `100 ideas` → `rules/supreme-polish.md`
- `simplify X` → `rules/proactive-improvements.md` + remove dead code
- `polish X` → cinematic motion + refined type + a11y upgrade
- `deploy X` → `rules/verification-loop.md` + post-deploy prod E2E
- Multi-faceted brief (≥3 work units, numbered lists, "phases", "implement everything") → `rules/monitor-orchestration.md`

## Emphasis signals

- `***TEXT***` triple-asterisk = high-priority directive, propagate to subagents
- `**TEXT**` bold = important, preserve in summaries
- ALL CAPS = build-fail-class directive
- `~~text~~` strikethrough = removed/deprecated

## Speed standards

- TEXT response: 100-160 chars descriptions, 4-8 word headlines, 2 sentences max
- CODE: full files never truncated, no `...` ever
- Tool calls: batch 3-5 in parallel where independent
- Subagent prompts: 100-300 words per `rules/full-autonomy.md`

## Cross-skill coordination

- Skill 02 (goal-and-brief) runs first on new projects
- Skill 05 (architecture) consumed by skills 06, 07, 08, 13, 15
- Skill 09 (brand) drives skills 10, 11, 12
- Skill 13 (observability) wires into every shipped feature
- Skill 16 (cinematic-website-prime-directive) trumps generic 06 for one-line site prompts
- Skill 20 (superpowers) holds PROCESS discipline — brainstorm/plan/worktree/code-review/finish-branch — invoked BEFORE implementation skills; TDD/debug/verify/parallel techniques are folded into `rules/` (see `20-superpowers/NOTICE.md`)

## Done definitions

### Code change

- Local typecheck + build pass = NOT done
- DONE requires: deploy + post-deploy fetch of changed routes + assert new content/headers/JSON-LD/status live
- Per `rules/verification-loop.md`

### Feature

- All 13 Hard Gates green
- E2E coverage in `e2e/FEATURES.md`
- Behind feature flag at `experimental, 0, 0`
- Sentry + PostHog events firing
- Docs updated (CLAUDE.md + README + JSDoc)

### Website (one-line prompt)

- Deployed at real URL
- 100 build-breaking rules satisfied per skill 16
- Self-Verify Statement per route
- Announced to user

## Conflict Resolution

1. This skill > all
2. Project > global
3. Specific > general
4. Brian > defaults
5. `***TEXT***` = high-priority propagate

## Value extraction every prompt

Per `rules/prompt-as-training-signal.md` — every prompt is a gradient:

- Re-prompting same surface = prior turn under-delivered
- Extract lesson BEFORE doing work; write to durable layer SAME TURN
- Cross-link siblings

## Compaction directive

At 60% context, save `progress.md` + spawn fresh agent. Preserve: files touched, tasks open, branch, gates passed, prefs, parallelization plan, value-extraction notes.

## Broadcast

- Side repos (agentskills, saas-starter, plugins, tools) → commit + push to main automatically
- Emdash projects (`~/emdash-projects/*`) → commit freely, never push (Brian pushes from frontend)
- New skills/tools → auto-create GitHub repo + npm/PyPI/Marketplace listing per `rules/full-autonomy.md`

## Self-improvement

After every implementation: "What else?" If anything → do it → ask again → loop until zero.