/letsgo: Project Kickoff Flow

Run this exact sequence every time. Do not skip steps. Steps marked (conditional) only activate when the project context requires them.

Step	Name	Conditional?
1	Personal or Client Project	No
2	Check Project & Gather Context	No
2.5	Playback, Flow, and Summary Confirmation	No
3	Brand Check, Design System, and Assets	No
4	Identify and State the UI Standard	No
5	Platform Detection and Animation Stack	No
6	3-Terminal Setup	No
7	Background Component	No
7.5	Lock Typography, Color, and Icons	No
8	Engagement Design	Conditional — apps with user flows
9	Tech Stack and Database Selection	No
9.5	Scale Readiness & Intelligence Layer	Conditional — high traffic / AI / graph
10	Folder Structure	No
11	Security Standards	No
12	Hand Off to autonomous-engineer	No
12.5	Run Graphify	Conditional — requires ANTHROPIC_API_KEY
13	Design Quality Gate	No
13.5	Flutter Performance & Security Gate	Conditional — Flutter only
14	App Store Prep	Conditional — mobile only
15	End of Build	No

Step 1: Personal or Client Project?

Ask: "Is this a personal project or a client project?"

Use AskUserQuestion with two options: Personal and Client.

If Personal:

Proceed directly to Step 2.

If Client:

Output the full Client Meeting Prep checklist below. Tell the user: "Here are the questions you need answered before the build starts. Use these in your client meeting."

---

CLIENT MEETING PREP: Questions to Ask

The Basics

1. What's the goal? (sell, get leads, get bookings, build community?)
2. Who is this for?
3. What does winning look like in 3 months?
4. Any competitors you admire or hate?
5. What makes you different?

What We're Building

6. What pages or screens do you need?
7. Do you have content ready (text, photos, videos) or do we create it?
8. Do you need to update the site yourself after launch?
9. Do you need people to log in?
10. Do you need to take payments?

Look and Feel

11. Do you have a logo, colors, or fonts already?
12. 3 sites you love: what do you like about them?
13. Anything you definitely don't want?

Tech and Tools

14. Do you have a domain already?
15. Any tools we need to connect? (booking, email, CRM, analytics?)
16. Who looks after the site after launch?

Timeline and Budget

17. When do you want to launch?
18. Any hard deadlines?
19. What's your budget?
20. Do you want ongoing support after launch?

Automation

21. What takes too long or keeps breaking in your process?
22. Any tools you wish talked to each other automatically?
23. What would you want to be notified about instantly? (new leads, orders, messages?)

Legal

24. Do you need a cookie banner or privacy policy?
25. Can you share access to your domain, hosting, and social accounts?

---

After the user confirms they've had the meeting and have answers, ask: "Do you have all the answers? Let's fill them in and then proceed to the build." Then continue to Step 2 with the context gathered from those answers.

Step 2: Check Project & Gather Context

Before asking, always check if the current directory has existing files or an active codebase (e.g., check for package.json, pubspec.yaml, Package.swift, requirements.txt, or run a quick file search).

• If files/codebase exist: Analyze the codebase to auto-detect the tech stack, framework, language, and dependencies. Output a friendly message like: "I've checked the project and detected [detected stack/framework/language]. Based on our current codebase, I think it's good to have these options: [suggest matching UI standard, animation stack, background tools, database, auth, and relevant agent skills]."
  • Note: Only check, reference, or suggest other specialized skills from the wider library of 400+ skills if they are specifically relevant to the detected codebase or project context (e.g., do not check mobile/SwiftUI skills for a web project, and only suggest pixel-art if retro graphics are detected or requested).
• If new project: Ask the user what they are building and who it is for. Use AskUserQuestion. Do not proceed until clear. Minimum needed:
  • Type of app or site (SaaS, portfolio, landing page, dashboard, iOS app, Flutter app, etc.)
  • Who the audience is
  • The primary goal or feeling the project must create

Always document the project details in the root README.md file (either creating it or updating it) with a clear explanation of what is being built, the target audience, the user flow of the app, and the future plans/roadmap for the app. Additionally, for every change or update applied to the codebase, log the changes along with the date in a changelog section of the README.md to keep a clear track of development history.

If the project goal is unclear or the user is still figuring out the concept, invoke design-sprint to run a focused discovery session before proceeding.

If the project needs Claude to connect to an external service (database, API, Slack, GitHub, file system) during development, ask if they want to set up an MCP server. If yes, invoke mcp skill. Also note: once the MCP server is wired, mcp-reconnect (github.com/palios-taey/mcp-reconnect) can auto-drive the /mcp → Reconnect menu after any server restart: worth installing for the dev loop.

If the project requires building a new MCP server (exposing an internal API, custom tool, or third-party integration to Claude), invoke mcp-builder: it covers TypeScript and Python server patterns, tool naming, output schemas, and eval creation.

Step 2.5: Playback, Flow, and Summary Confirmation

Once the user provides their answers or project brief:

1. Playback: State clearly what you understand from the user's answers/inputs (e.g., goals, target audience, stack, features).
2. Flow & Summary: Outline the planned kickoff flow and a concise summary of the project.
3. Change Specific option: Ask the user if they want to proceed or change anything, using AskUserQuestion with options:
   • Proceed to Step 3 (Brand Check)
   • Change specific details (If selected, ask the user what specific details they want to change, update your understanding/summary, and present the confirmation options again).

Step 3: Brand Check, Design System, and Assets

Ask: "Do you have existing brand guidelines (logo, colors, fonts, voice) and project assets (images, icons, vectors, illustrations, videos), or should I create them?"

• Has brand/assets: ask for brand colors, fonts, voice, and asset files. If they have files, ask them to copy them to the project directory or provide the paths. Lock these into the project's design tokens/directories.
• No brand/assets: invoke brand-guidelines skill to define: primary color, type pair, voice (2-3 adjectives), and logo direction. If design assets are needed later, use the generate_image tool or pull from free-design-resources.

After brand is locked, invoke design-system to establish the spacing scale, color tokens, type scale, and component naming conventions that will be used throughout the build.

Step 4: Identify and State the UI Standard

Analyze the project files and context, and suggest the most appropriate UI standard, stating something like: "Hey, I think this project we have is good to have these options: we should use the [recommended standard] standard because..." Based on project context or auto-detection, pick one standard and state it explicitly:

• Hallmark: most expressive, best default for open-ended projects. Invoke hallmark.
• portfolio-design: personal brands, portfolios, agency homepages. Invoke portfolio-design.
• motion-design-school: course platforms, showcases, creative education. Invoke motion-design-school.
• website-ui-v3 / Silencio: agencies, studios, anti-brand bold sites. Invoke website-ui-v2.
• liquid-glass-design: glassmorphism, depth, blur layers, Apple-adjacent premium feel. Invoke liquid-glass-design.
• landonorris-ui / The OFF+BRAND. Method: not a fixed aesthetic. A process for hitting $20k-quality on any project: derive colors/type/motion from the subject, replace every browser default, finish all 5 layers (structure, visual, motion, interaction, polish). The landonorris.com dark + lime design is the reference example, not the output. Use when the project needs to feel premium, alive, and intentional. Source effects from: Codrops, GSAP demos, Flowbase. Invoke landonorris-ui.
• pixel-art: retro games, sprite art, 8-bit/16-bit retro graphics, limited palettes, dithering, subpixel animations, tilesets. Invoke pixel-art.
• canvas-design: posters, print art, static visual design, PDF/PNG deliverables. Design philosophy → museum-quality canvas output. Invoke canvas-design.

After the standard is chosen, invoke design-principles to reinforce the foundational rules (contrast, hierarchy, alignment, proximity, repetition) that apply regardless of style. Then invoke getdesign as a component and pattern reference alongside 21st-dev.

Also invoke design-inspiration to pull at least 3 locked references before any UI code is written. Output the full Inspiration Brief (feeling, references, typography, color, icons, background, motion, components) before proceeding to Step 5. The skill covers every source in the toolkit: Mobbin, Godly, Awwwards, Lapa Ninja, Dark Mode Design, Pageflows, Screenlane, Land-book, VibeUI, Aceternity, Origin UI, Magic UI, Motion Primitives, 21st.dev, Fancy Components, hover.dev, buildui.com, UIverse, Emil Kowalski, Grainient, Mesher, CSS Pattern, SVG Backgrounds, Lummi, Fontjoy, Typewolf, Fonts in Use, Variable Fonts, Realtime Colors, oklch.com, Radix Colors, Happy Hues, Lucide, Phosphor, Tabler, Iconoir, SVG Repo, 60fps.design, Codrops, transition.style, cubic-bezier.com, Impeccable, Taste, oh-my-claude-sisyphus.

CodePen (codepen.io): use for sourcing micro-interactions, canvas effects, CSS animations, and GSAP demos that can be adapted into components. Search by technique (e.g. "gsap splittext", "scroll reveal", "liquid button") and port the relevant logic into the project stack.

Also reference free-design-resources for any icons, illustrations, vectors, or fonts needed: always pull from free sources first before suggesting paid assets.

Step 5: Platform Detection and Animation Stack

Detect the platform and lock the animation + component approach:

Platform	Animation Skills	Component Source
Web / Next.js / React	framer-motion + motion-dev + gsap (heavy scroll/timeline) + css-animations + ui-animation + gstac + lenis (smooth scroll) + matter.js (2D physics/rigid-body simulations)	shadcn-ui, origin-ui, magic-ui, motion-primitives, skiper-ui, 21st-dev, getdesign, reactbits, aceternity, hover.dev, buildui.com, fancy-components, uiverse

GSAP setup for Next.js/React: install: npm install gsap @gsap/react. Only import the plugins you actually use. Minimal landing page setup:

import { gsap } from "gsap";
import { useGSAP } from "@gsap/react";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { SplitText } from "gsap/SplitText";
gsap.registerPlugin(useGSAP, ScrollTrigger, SplitText);

Full plugin import reference is in project memory reference_gsap.md. Always use useGSAP hook (not useEffect): it handles cleanup automatically. Mark component 'use client' in Next.js App Router.
| Responsive / Multi-screen | mobile-responsiveness + responsive-web-design + mobile-first-design + frontend-design | apply alongside web stack |
| iOS / macOS / SwiftUI | apple-standards + apple-animations + ios-hig + apple-design + swiftui-patterns | HIG, Dynamic Type, SF Symbols, Swift Concurrency, SwiftData, App Store rules |
| Flutter | flutter-google + flutter-evals + dart-flutter-patterns + flutter-animations + flutter-dart-code-review | Flutter Material / custom — always run the Flutter Performance & Security Gate (Step 13.5). flutter-google covers debugging, pub.dev evaluation, and best practices. flutter-evals covers golden tests, integration tests, and test quality scoring. |
| Video generation | remotion + hyperframes (HTML-native, agent-first, Apache 2.0) | React components (Remotion) / HTML + GSAP (HyperFrames) |
| Document output | docx, pdf, pptx, xlsx (Anthropic document skills) | Word, PDF, PowerPoint, Excel files |
| Generative art | algorithmic-art (p5.js + seeded randomness) | Interactive p5.js HTML artifacts |
| Web artifacts | web-artifacts-builder (React + Tailwind + shadcn bundled to HTML) | Complex claude.ai artifacts |
| Animated GIFs | slack-gif-creator (PIL + GIFBuilder, Slack-optimized) | Slack emoji GIFs, message GIFs |
| AI application | context-engineering + (claude-api or azure-ai) | Invoke recsys-pipeline-architect for recommendation engines. For RAG (semantic search, knowledge base, document Q&A) or Knowledge Graph (fraud, social, supply chain) — configure in Step 9.5 |

For any web project targeting more than one screen size, invoke mobile-responsiveness, responsive-web-design, mobile-first-design, and frontend-design to lock breakpoints, fluid grids, and tablet/mobile layout rules before building.

Also invoke animation-designer to define the motion language: easing curves, durations, entrance/exit patterns, and stagger rules that will be consistent across the entire build.

State the platform and animation stack explicitly before moving on.

Step 6: Output the 3-Terminal Setup

Output the three terminal prompts filled in with project name, goal, stack, UI standard, and animation approach:

• Terminal 1: Orchestrator (Supervisor): plans architecture, delegates tasks, wakes on structured outcomes from workers. Does not poll or interrupt mid-loop
• Terminal 2: Developer (Worker): builds components, runs local loop to completion, then delivers a structured outcome to the Orchestrator
• Terminal 3: QA (Worker): reviews every component for regressions, runs local loop to completion, then delivers a structured outcome to the Orchestrator

Supervisor-Worker Protocol

No permission-asking. Every session: Orchestrator, Developer, and QA: has full authorization for all actions within the approved scope. Do not ask "can I?", "should I?", or "is it okay to?" for anything already inside the plan. Execute. Surface blockers only when genuinely stuck on something outside the approved scope, never for routine task execution.

Workers do not interrupt mid-loop. When a worker finishes its local loop, it delivers a structured outcome:

{
  "status": "done | blocked | needs_review",
  "artifacts": ["list of files changed or created"],
  "decisions": ["choices made and why"],
  "blockers": ["anything that needs supervisor resolution"],
  "next_steps": ["recommended actions for the supervisor to delegate next"]
}

The Orchestrator reads structured outcomes and decides what to delegate next. No pane-checking. No mid-loop status pings.

Iteration cap. Each worker gets a maximum of 4 attempts on the same task. If a worker reaches 4 attempts without resolving the blocker, it stops, sets "status": "blocked" in its outcome, describes what was tried and why it failed, and surfaces to the Orchestrator. The Orchestrator re-scopes, reassigns, or escalates: it does not send the same worker back into a fifth loop. Infinite retry loops are a bug, not persistence.

Model Tiering

Use the right model tier for the right work. Default to mid-tier (Sonnet) and escalate to the big model (Opus) only when the task genuinely requires it.

Task type	Model
Orchestration, delegation, task routing	Sonnet
Boilerplate generation, known patterns, file edits	Sonnet
Running established skills against clear inputs	Sonnet
Judgment calls with ambiguous or conflicting requirements	Opus
Architectural decisions with real trade-offs	Opus
Security review on sensitive or novel code	Opus
Debugging where the root cause is genuinely unclear	Opus
Any task where Sonnet has already failed twice	Opus

The Orchestrator uses Sonnet for routing and delegation. Workers use Sonnet by default. Either escalates to Opus when they hit a judgment call, an ambiguous spec, or a second failed attempt. This keeps cost predictable without sacrificing quality on the decisions that matter.

Invoke model-route to apply this tiering automatically across the agent pipeline.

For fully unattended runs, launch each terminal with:

claude --dangerously-skip-permissions

Or pre-approve the tools workers use most in ~/.claude/settings.json:

{
  "allowedTools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
}

This eliminates the approval prompts for routine file and shell operations without opening the full skip-permissions flag.

Session Resilience (for unattended runs)

When workers run overnight, in loops, or across long autonomous tasks, two tools keep them alive:

1. API Watchdog: detects when a transient API error (529 overloaded, 429, 500, ECONNRESET) stalls a session at the prompt and auto-injects Continue with exponential backoff. Distinguishes transient errors from real usage limits (leaves those alone):

# Install (single file, no dependencies)
curl -O https://raw.githubusercontent.com/palios-taey/claude-code-api-watchdog/main/watchdog.py

# Dry-run first: logs every keystroke it WOULD send without sending any
python3 watchdog.py --sessions orchestrator,developer,qa --dry-run

# Live: escalate-only by default (never auto-restarts unless you pass --resume-cmd)
python3 watchdog.py --sessions orchestrator,developer,qa

Point --sessions at the exact tmux session names used in the 3-terminal setup above. Repo: github.com/palios-taey/claude-code-api-watchdog

2. MCP Reconnect: drives the /mcp → Reconnect menu sequence automatically after an MCP server restarts or drops. Eliminates the manual context-switch during the edit-restart-reconnect loop:

# Install
git clone https://github.com/palios-taey/mcp-reconnect && cd mcp-reconnect && sudo make install

# Reconnect all Claude Code sessions
mcp-reconnect

# Target specific sessions
mcp-reconnect orchestrator developer qa

# When calling FROM WITHIN a Claude Code session (e.g. a deploy script), always detach with a delay
nohup mcp-reconnect --delay 10 &>/dev/null & disown

Use --path LABEL to navigate submenus (e.g. mcp-reconnect --path taeys-hands --path Reconnect). Repo: github.com/palios-taey/mcp-reconnect

---

Step 7: Ask About Background Component

Always ask, never skip. Use AskUserQuestion. Options: Spline, Vanta.js, Haikei, Framer marketplace, Grainient, Mesher, CSS Pattern, SVG Backgrounds, CSS-only (mesh gradient, animated gradient, noise texture), endlesstools.io, none.

Invoke the matching skill based on the user's choice:

• Spline: invoke spline: 3D scene setup, lazy loading, mobile fallback pattern
• Vanta.js: if mobile target, automatically apply vanta-mobile-fix
• Haikei: invoke haikei: SVG export, section divider patterns
• Framer marketplace: invoke framer-marketplace: free component browsing and code extraction
• Grainient: use grainient.supply: grain + gradient generator, export as WebP/SVG
• Mesher: use mesher.io: mesh gradient with precise color placement, exports SVG or CSS
• CSS Pattern: use css-pattern.com: pure CSS repeating patterns, zero HTTP cost
• SVG Backgrounds: use svgbackgrounds.com: scalable SVG backgrounds, free
• endlesstools.io: invoke endlesstools
• CSS-only: use css-animations for mesh gradient or animated gradient background

Step 7.5: Lock Typography, Color, and Icons

After the Inspiration Brief is output and the background is chosen, lock these three before any UI code is written:

Typography

• Use Fontjoy (fontjoy.com) to generate the heading + body pairing
• Validate each font in context on Typewolf (typewolf.com) before committing
• For variable fonts or editorial direction, check Variable Fonts (v-fonts.com)
• Apply impeccable-style tracking, line-height, and measure rules to the chosen pair

Color

• Build the palette live on Realtime Colors (realtimecolors.com): validate in a real UI, not swatches
• Pick individual values using oklch.com (matches the project's CSS token standard)
• Use Radix Colors (radix-ui.com/colors) for semantic token scales with light + dark mode
• For quick full-palette direction, reference Happy Hues (happyhues.co)

Icons

Choose one icon set and commit. Do not mix sets:

• Lucide (lucide.dev): default for shadcn projects. npm install lucide-react
• Phosphor (phosphoricons.com): when weight is a design variable (thin luxury → bold energy)
• Tabler (tabler-icons.io): when comprehensive coverage is needed (5000+)
• Iconoir (iconoir.com): when a slightly more geometric, distinctive style fits
• SVG Repo (svgrepo.com): for brand logos, one-off illustrations, anything outside a standard set

State the locked typography pair, color palette, and icon set explicitly before moving on.

Quick Theme Option

If the project output is a slide deck, document, or HTML artifact (not a full web app), offer theme-factory as a shortcut: 10 pre-set color/font themes the user can browse and apply in one step instead of building tokens from scratch. Show the theme showcase, let the user pick, then apply. Can also generate a custom theme from a mood or brief.

Push to Figma

After tokens are locked, invoke figma-design-system to automatically create a new Figma file for the project. The skill will:

• Create a file named [Project Name]: Design System
• Populate color styles, text styles, spacing tokens, border radius scale
• Build a Brand Foundation page with swatches and type specimen
• Create named component starter frames
• Return the direct Figma link

This runs via the figma-developer-mcp (already configured in ~/.claude/settings.json). If the MCP is unavailable, output the tokens as a structured list for manual Tokens Studio import instead.

Step 8: Engagement Design (for apps with user flows)

If the project has user flows, onboarding, or retention goals, apply:

• hooked-ux: identify the internal trigger and variable reward
• psychology-principles: apply Fitts, Hick, social proof, peak-end rule to key screens
• ui-ux-pro-max: layer advanced UX patterns on top: micro-interactions, empty states, error states, loading patterns, progressive disclosure

State the engagement design decisions before building.

Step 9: Tech Stack and Database Selection

If an existing project was detected in Step 2, inspect the codebase and suggest the database, ORM, and auth options that best integrate with the current codebase (e.g., "Hey, since this is a Next.js project, I think it's good to have Supabase for our database and Clerk for auth"). Present these as active suggestions to the user.

If starting a new project, use AskUserQuestion for BOTH questions. Always present options: never assume or skip. The user must actively choose.

Tech Stack

Ask which framework/language to use. Present relevant options based on platform detected in Step 4:

Web options: Next.js (App Router), Remix, Astro, plain React + Vite, Vue/Nuxt, SvelteKit
Mobile options: SwiftUI, UIKit, Flutter, React Native, Expo
Backend options (if needed): Next.js API routes, Express, Fastify, NestJS, Django, FastAPI, Go
Note: If building API endpoints or backend routers, always invoke the api-design and rest-api-design skills to ensure clean resource modeling, REST standards, versioning, and OpenAPI/Swagger documentation.

When designing REST APIs, enforce these 8 rules automatically:

1. Domain Model Driven — Model routes after your domain entities and relationships, not UI screens. Example: GET /orders/{id}/items reflects the Order → OrderItem relationship directly.

2. HTTP Methods

Method	Use
GET	Read list or detail
POST	Create
PUT	Update (full replace)
DELETE	Delete
PATCH	Avoid — can be confused with partial-update semantics

3. Idempotence

• GET: naturally idempotent
• PUT, DELETE: design to be idempotent
• POST: implement idempotence only when business requirements demand it (e.g. deduplication key)

4. HTTP Status Codes — use precisely:

Code	Meaning	Code	Meaning
200	Request Successful	401	User Not Authenticated
201	Created Successfully	403	Permission Check Failed
400	Data Validation Failed	404	Resource Not Found
405	Method Not Supported	409	Business Rule Conflict
415	Unsupported Data Request Format	500	Internal Server Error

5. Versioning — prefer path versioning: GET /v1/users. Query param (?v1) and header (Version: v1) are alternatives; pick one and be consistent.

6. Semantic Paths — use resource nouns, not verbs. Use plural nouns for collections:

• POST /v1/users/login → POST /v1/authorizes
• GET /v1/order/{id}/{item} → GET /v1/orders/{id}/items

7. Batch Processing — expose both patterns:

• Single: POST /v1/users / GET /v1/users/1
• Batch: POST /v1/users/batch / GET /v1/users?ID=1,2,3

8. Query Language — support these three on collection endpoints:

• Pagination: GET /v1/users?page=1&size=20
• Sorting: GET /v1/users?sort=name:asc,age:desc
• Filter: GET /v1/users?age=gt:20,lt:50&name=match:lisa&gender=eq:male

AI app: Add Claude API or Azure AI to whichever framework is chosen. For RAG, semantic search, or knowledge graph features, see Step 9.5.

Database

Ask which database to use. Present these options with their use cases:

Database	Best for
PostgreSQL (via Supabase or Railway)	Default choice: relational data, full SQL, scales well
MySQL	Existing MySQL infra, WordPress-adjacent, simpler queries
SQLite	Local-first apps, small scale, no server needed
MongoDB	Flexible schema, document data, rapid iteration
Supabase	Postgres + auth + realtime + storage in one, great DX
PlanetScale	MySQL-compatible, serverless, branching workflow
Turso (libSQL)	Edge/SQLite, low latency, great for global apps
Redis	Cache, sessions, queues, pub/sub
Firestore	Firebase ecosystem, realtime sync, mobile-first
Neon	Serverless Postgres, great with Vercel
None	No database needed (static site, API-only consumer)

Once the user chooses:

• Lock the ORM and invoke the matching skill:
  • JS/TS default: invoke prisma
  • Edge/serverless/lightweight: invoke drizzle
  • Supabase chosen: invoke supabase (covers DB + auth + storage in one)
  • SQLAlchemy (Python), GORM (Go): no skill, use docs
• If PostgreSQL or Supabase is selected, invoke the supabase-postgres-best-practices skill to guarantee optimal database query performance, indexing, schema design, Row-Level Security (RLS) configuration, and connection scalability.
• Note connection pooling if serverless: PgBouncer or Supabase's built-in pooler

Auth Selection

Ask which auth library to use and invoke the matching skill:

• Clerk: invoke clerk: best for Next.js, pre-built UI, orgs, MFA, passkeys
• NextAuth: invoke nextauth: open-source, free, OAuth + credentials, full control
• Supabase Auth: already covered if supabase is the database choice
• None: public-only app, no auth needed

Caching Selection

If a database (e.g. Postgres, MySQL, MongoDB) was chosen, ask: "Do you want to add Redis Cache to our stack so the database/server doesn't get overloaded under traffic?"

• Yes: Add Redis to the stack and invoke the redis-patterns skill. If high concurrency or millions of users are expected, also invoke the redis-connections (for connection pooling, pipelining, and client-side caching) and redis-clustering (for slot tagging and read replicas) skills.
• No: Proceed without cache.

Pipeline Selection

Ask: "Do you want to configure an automated CI/CD pipeline (GitHub Actions) for testing, security gates, and deployments?"

• Yes: Add GitHub Actions to the stack and invoke the github-actions-docs and deployment-pipeline-design skills to implement multi-stage build, test, scan, and deploy pipelines.
• No: Proceed with manual deployments.

Observability Selection

Ask: "Do you want to implement structured logging and observability (Stripe-style canonical log lines)?"

• Yes: Add structured logging to the stack and invoke the logging-best-practices skill to implement context-rich wide events per request with middleware.
• No: Proceed with standard console logging.

Infrastructure Layer Selection

Ask: "Does your project need any infrastructure layer in front of your services?"

Use AskUserQuestion to present the options. Then analyze the project context and recommend one (or a combination) with a short reason before the user confirms.

Option	When to recommend
Reverse Proxy (Nginx, Caddy, Traefik)	Single backend, need TLS termination, caching, or to hide internal infrastructure
Load Balancer (AWS ALB, GCP LB, HAProxy)	Multiple instances of the same service, need traffic distribution, health checks, or horizontal scaling
API Gateway (Kong, AWS API GW, Traefik, tyk)	Multiple services or microservices exposed as APIs, need auth, rate limiting, request transformation, or versioning
API Gateway + Load Balancer	Multiple services behind a governed API layer, each service scaled independently — common in cloud-native / microservices
Reverse Proxy + API Gateway	Monolith or BFF pattern where a proxy handles TLS/caching and a gateway governs API access downstream
None	Serverless/edge deployment (Vercel, Netlify, Cloudflare Workers) where the platform handles routing, TLS, and scaling automatically

Recommendation logic:

• Static site / JAMstack / Vercel / Netlify → recommend None (platform handles it)
• Single Next.js or monolith server → recommend Reverse Proxy (Caddy or Nginx for TLS + caching)
• Microservices or multiple backend services → recommend API Gateway + Load Balancer
• Backend with public API, rate limiting needed → recommend API Gateway
• High-traffic monolith needing horizontal scale → recommend Load Balancer

State the recommendation and reasoning explicitly. The user confirms or overrides.

Add the chosen infrastructure layer to the locked stack output below.

Step 9.5 — Scale Readiness & Intelligence Layer

Ask: "Do you expect high traffic (100k+ users, viral potential, or enterprise scale)? Does your project need AI search, recommendations, or knowledge graph features?"

Use AskUserQuestion with options: High-traffic scale, AI / RAG / semantic search, Knowledge graph, Multiple, Not now.

Activate the relevant sections below based on the answer.

---

A. High-Traffic Scale (100k+ users / millions of users)

Database Read Replicas
At scale, 80%+ of queries are reads. Route them to replicas to protect the primary:

• Postgres: use Supabase read replicas, Neon branching, or RDS read replicas
• Pattern: write via ORM primary connection, read via replica connection string
• Never run analytics or reporting queries against the primary

Connection Pooling (mandatory at scale)
Serverless functions can exhaust Postgres connections instantly. PgBouncer is not optional at scale:

• Supabase: use the ?pgbouncer=true connection string in transaction mode
• Self-hosted: deploy PgBouncer as a sidecar or use pgcat for multi-tenant pooling
• Rule: max DB connections = (2 × CPU cores) + effective_spindle_count — never exceed it

Database Sharding
When a single Postgres instance hits its write ceiling (typically ~10k writes/sec):

• Horizontal sharding by tenant ID, user ID, or region
• Options: Citus (Postgres extension), CockroachDB (distributed SQL), PlanetScale (MySQL sharding)
• Shard key selection is irreversible — choose based on the dominant query pattern

CDN Strategy
Not just background images — cache at the edge for all static and semi-static content:

• Static assets: Cloudflare CDN, AWS CloudFront, or Vercel Edge Network
• API responses: cache GET responses at the CDN layer with Cache-Control: public, s-maxage=60
• Use stale-while-revalidate for near-real-time data that can tolerate brief staleness
• Purge strategy: tag-based purge (Cloudflare) or surrogate keys (Fastly) — never purge everything

Message Queues / Async Job Processing
Every operation that doesn't need to complete before the HTTP response belongs in a queue:

• Emails, webhooks, image processing, report generation, ML inference, third-party API calls
• Options by scale:

  Queue	Best for
  BullMQ (Redis-backed)	Single-region, Node.js, simple job retry
  AWS SQS	Serverless, managed, infinite scale
  Kafka / Confluent	High-throughput event streaming, event sourcing
  Google Pub/Sub	GCP-native, push/pull, guaranteed delivery

• Pattern: HTTP handler enqueues job → returns 202 Accepted → worker processes async

Auto-Scaling Policy
A load balancer with no scaling policy is just a router:

• Kubernetes: HorizontalPodAutoscaler on CPU (70%) + custom metrics (queue depth, RPS)
• AWS ECS: target tracking scaling on ALB RequestCountPerTarget
• Vercel / Cloudflare Workers: scales automatically — focus on cold start optimization instead
• Define scale-in cooldown (300s minimum) to prevent flapping

Circuit Breakers + Bulkheads
Prevent one slow dependency from cascading into a full outage:

• Circuit breaker: after N failures, open the circuit and return a fallback immediately
• Bulkhead: isolate thread pools / connection pools per downstream service
• Libraries: cockatiel (Node.js), resilience4j (Java), polly (C#), tenacity (Python)
• Every external API call (payment provider, email, third-party service) needs a circuit breaker

Graceful Degradation + Fallback Patterns
Design for partial failure, not just full uptime:

• Redis down → fall back to DB query (slower but functional)
• Search service down → fall back to basic DB LIKE query
• Recommendation engine down → show popular items
• Payment provider timeout → queue the retry, show "processing" to user
• Never return a 500 when a degraded response is possible

Distributed Tracing (beyond structured logs)
At scale, a single request touches 5+ services. Logs alone can't reconstruct it:

• Instrument with OpenTelemetry (vendor-neutral, works with Datadog, Jaeger, Honeycomb, Grafana Tempo)
• Trace every DB query, external API call, queue publish/consume
• Correlate logs + traces via trace_id propagated in headers (traceparent)
• Set sampling rate: 100% in staging, 1-10% in production (tail-based sampling for errors: 100%)

Global Deployment / Multi-Region
Latency is a product problem — 100ms extra = 1% conversion drop:

• Database: Neon (serverless, multi-region), CockroachDB (geo-distributed), PlanetScale
• Compute: Cloudflare Workers (edge), Vercel Edge Functions, AWS Lambda@Edge
• Rule: co-locate compute with data — an edge function that hits a single-region DB gains nothing
• Active-active multi-region requires conflict-free data models (CRDTs or event sourcing)

Cost Guardrails
At millions of users, one missing index or an unbounded query destroys the budget:

• Set DB query timeout (5s max for user-facing, 30s for background)
• Enforce pagination on all collection endpoints — never allow unbounded SELECT *
• Set Redis memory limits with eviction policy (allkeys-lru for cache, noeviction for queues)
• Alert on: p99 query time > 500ms, cache hit rate < 80%, error rate > 0.1%
• Budget alerts on cloud spend — set at 80% of expected monthly cost

Scale Readiness Checklist:

• Read replicas configured — analytics / reports never hit primary
• PgBouncer or Supabase pooler in transaction mode
• All background work offloaded to a queue (BullMQ / SQS / Kafka)
• Auto-scaling policy defined with scale-in cooldown
• Circuit breakers on every external API call
• Graceful degradation fallbacks for Redis, search, and third-party services
• OpenTelemetry instrumentation with trace_id propagated across services
• CDN caching for static assets + cacheable API responses
• Query timeouts and pagination enforced on all endpoints
• Cloud cost alerts configured at 80% of monthly budget

---

B. RAG (Retrieval-Augmented Generation)

Use RAG when the project needs AI answers grounded in your own data: docs, support knowledge base, product catalog, legal corpus, internal wikis, user-generated content.

RAG Architecture

Ingest Pipeline:
  Raw Documents → Chunking → Embedding → Vector Store

Query Pipeline:
  User Query → Embed Query → Vector Search (top-k) → Rerank → LLM with context → Response

Chunking Strategy — the most impactful variable in RAG quality:

Strategy	When to use
Fixed-size (512 tokens, 10% overlap)	General purpose, fastest to implement
Semantic chunking (split on meaning boundaries)	Long documents with clear sections
Hierarchical (parent + child chunks)	Retrieve child for precision, parent for context
Sentence-window (store sentence, retrieve surrounding window)	Dense prose, Q&A over narratives

Embedding Models:

Model	Best for
text-embedding-3-large (OpenAI)	Highest quality English retrieval
text-embedding-3-small (OpenAI)	Cost-efficient, 5x cheaper
nomic-embed-text (open source)	Self-hosted, no per-token cost
voyage-3 (Anthropic partner)	Best for Claude integration

Vector Stores:

Store	Best for
pgvector (Postgres extension)	Already on Postgres — zero new infra, scales to 10M+ vectors
Pinecone	Managed, serverless, production-ready out of the box
Weaviate	Hybrid search (vector + keyword) built in
Qdrant	High-performance, self-hosted or cloud
Chroma	Local dev and prototyping

Recommendation: start with pgvector if already on Postgres — avoids a new service and handles most production workloads. Graduate to Pinecone or Qdrant if query latency exceeds 200ms at scale.

Retrieval Quality:

• Use hybrid search: vector similarity + BM25 keyword search, fused with RRF (Reciprocal Rank Fusion)
• Add a reranker (Cohere Rerank, BGE-Reranker) after top-k retrieval — improves precision by 20-40%
• Metadata filtering: filter by document type, date, user permissions before vector search — reduces noise and enforces access control
• Evaluate retrieval quality with: hit rate, MRR (Mean Reciprocal Rank), NDCG

Generation:

• Use Claude API with prompt caching for repeated system prompts (cuts cost 90% on repeated context)
• System prompt structure: role → retrieval context → task → output format
• Always cite sources: return chunk IDs with the response so the UI can link back to the source document
• Hallucination guard: if no retrieved chunk scores above threshold, respond "I don't have enough information" rather than generating from weights

RAG Stack Recommendation:

Ingest:     LangChain / LlamaIndex document loaders + chunkers
Embeddings: text-embedding-3-small (dev) → text-embedding-3-large (prod)
Store:      pgvector (Postgres) → Pinecone at scale
Rerank:     Cohere Rerank v3
LLM:        Claude Sonnet 4.6 (coding/reasoning) | Claude Haiku 4.5 (high-volume, cost-sensitive)
Caching:    Redis for repeated query results + Claude prompt caching for system context
Eval:       Ragas (retrieval + generation quality metrics)

RAG Checklist:

• Chunking strategy chosen and tested against real queries
• Embedding model locked — never mix models in the same index
• Hybrid search (vector + keyword) implemented
• Reranker in the retrieval pipeline
• Metadata filtering for access control and relevance
• Source citations returned with every response
• Prompt caching enabled on Claude API for static system context
• Ragas or equivalent eval running on a golden question set
• Fallback response when no chunk exceeds similarity threshold

---

C. Knowledge Graph

Use a knowledge graph when data has rich, complex relationships that relational tables make painful: recommendation engines, fraud detection, identity resolution, semantic search over connected entities, supply chain, social networks.

When to choose a graph DB over Postgres:

• Queries require traversing 3+ relationship hops
• The schema is highly dynamic (entities gain new relationship types over time)
• You need pathfinding, centrality, or community detection algorithms
• Example: "find all users who bought the same product as users who also bought X, and who share a city with a high-value customer" — trivial in Cypher, painful in SQL

Graph Database Options:

DB	Best for
Neo4j	Most mature, Cypher query language, AuraDB managed cloud
Amazon Neptune	AWS-native, supports Gremlin + SPARQL + openCypher
Memgraph	High-performance, Cypher-compatible, streaming graph analytics
FalkorDB	Redis-based graph, ultra-low latency, good for real-time
Weaviate	Combined vector + graph — use when RAG + graph are both needed

Core Graph Patterns:

// Create nodes and relationships (Neo4j Cypher)
CREATE (u:User {id: '1', name: 'Alice'})
CREATE (p:Product {id: '42', name: 'Widget'})
CREATE (u)-[:PURCHASED {at: datetime()}]->(p)

// Traverse: find products bought by users similar to Alice (2 hops)
MATCH (me:User {id: '1'})-[:PURCHASED]->(p:Product)<-[:PURCHASED]-(similar:User)
      -[:PURCHASED]->(rec:Product)
WHERE NOT (me)-[:PURCHASED]->(rec)
RETURN rec.name, count(*) AS score ORDER BY score DESC LIMIT 10

Graph + RAG (GraphRAG)
The most powerful pattern for knowledge-intensive AI apps:

• Store entities and relationships in the graph (Neo4j / Weaviate)
• Store document chunks and embeddings in the vector store (pgvector / Pinecone)
• At query time: vector search retrieves relevant chunks → graph traversal enriches with connected entities → combined context sent to LLM
• Example: user asks about a product → vector search finds relevant docs → graph traversal adds: related products, supplier chain, customer reviews, known issues
• Microsoft GraphRAG framework (microsoft/graphrag) automates entity extraction + community summarization from documents

Graph + Vector Hybrid (for AI apps):

User Query
    ↓
Vector Search (semantic similarity) → top-k chunks
    ↓
Graph Traversal (entity expansion) → connected nodes
    ↓
Rerank combined results
    ↓
LLM with enriched context
    ↓
Cited, grounded response

Graph Checklist:

• Graph DB chosen based on query patterns and existing infra
• Node and relationship schema designed before ingestion (hard to change later)
• Indexes on high-cardinality node properties (user ID, product ID)
• Query depth bounded — unbounded traversals will kill performance (use LIMIT and depth constraints)
• If combining with RAG: entity extraction pipeline defined (spaCy, Claude extraction, or dedicated NER model)
• Read replicas for analytics queries — never run graph algorithms on the write primary

---

Confirm Full Stack

Output the complete locked stack before proceeding:

Framework:       [chosen framework]
Language:        [TypeScript / Swift / Dart / Python / etc.]
Base UI:         shadcn-ui (web) | native (Apple) | Material (Flutter)
Primary UI:      skiper-ui (web) | platform native
Supplementary:   21st-dev, getdesign, reactbits, free-design-resources
Background:      [chosen in Step 7]
UI Standard:     [chosen in Step 4]
Animation:       [chosen in Step 5] + lenis (smooth scroll, web only)
Brand:           [colors, fonts locked in Step 3]
Database:        [chosen database]
ORM:             [prisma / drizzle / SQLAlchemy / etc.]
Auth:            [clerk / nextauth / supabase-auth / none]
Caching:         [redis (via redis-patterns, redis-connections, redis-clustering) / none]
API Design:      [api-design, rest-api-design / none]
DB Optimization: [supabase-postgres-best-practices / none]
Pipeline:        [github-actions (via github-actions-docs, deployment-pipeline-design) / none]
Observability:   [logging-best-practices / none]
Infra Layer:     [Reverse Proxy / Load Balancer / API Gateway / combination / none]
Scale:           [read replicas / connection pooling / queue / circuit breakers / CDN / multi-region / none]
RAG:             [pgvector / Pinecone / Weaviate / Qdrant + reranker + hybrid search / none]
Graph:           [Neo4j / Neptune / Memgraph / FalkorDB / GraphRAG / none]
Validation:      zod (all API routes + env vars)
Hosting:         [Netlify / Vercel / Railway / Fly.io / App Store / etc.: ask if not obvious]
MCP:             [list any MCP servers being connected, or none]

Step 10: Output Folder Structure

Read references/project-structure.md and output the full folder structure. Rules always apply:

• Clean architecture: frontend, backend, api, shared: always separate
• constants/ in every top-level dir: no exceptions
• Env vars never accessed directly: always through config/env.ts
• Shared types in shared/types/

Add these directories when selected in Step 9.5:

• Message queue / workers (if queue was chosen): src/workers/, src/queues/, src/jobs/
• RAG (if RAG was chosen): src/rag/ with subdirs chunking/, embeddings/, retrieval/, eval/
• Knowledge graph (if graph was chosen): src/graph/ with subdirs schema/, queries/, ingestion/
• Multi-region / edge (if multi-region was chosen): src/edge/ for edge function handlers separate from origin handlers

Step 11: Enforce Security Standards

Run /security-scan (ECC: 1,282 security tests across CLAUDE.md, MCP configs, hooks, and skills). Then confirm before handoff:

• .env created, .env.example committed, .env in .gitignore
• Env vars never accessed raw — always through a validated config module:
  • Web/Node: config/env.ts with zod — invoke zod skill, no raw process.env anywhere
  • Flutter: --dart-define or flutter_dotenv, access via String.fromEnvironment()
  • Python: pydantic-settings with a Settings model
  • Go: viper or os.Getenv wrapped in a typed config struct
• Auth library confirmed — never custom auth:
  • Web: clerk, nextauth, or supabase auth
  • Flutter: supabase auth, firebase_auth, or clerk Flutter SDK
  • Backend: JWT verified via library, never manually decoded
• Input validation at all API boundaries:
  • Web/Node: zod validators in api/validators/
  • Python: pydantic models on all request bodies
  • Go: validator struct tags or manual boundary validation
• Security headers configured for the framework:
  • Next.js: next.config.ts headers block
  • Express/Fastify: helmet middleware
  • Django: SECURE_* settings + django-csp
  • Go: custom middleware or gorilla/handlers
  • Flutter: certificate pinning via dio interceptor
• ORM or query builder confirmed — no raw SQL string concatenation anywhere
• Dependency audit runs as part of scaffold: npm audit / pip-audit / go mod verify / flutter pub audit
• Rate limiting on all public API routes — invoke api-rate-limiting skill to implement token bucket, fixed window, or sliding window algorithms (using Redis if distributed)
• If RAG was chosen: embedding API keys scoped to least privilege, vector store access controlled by metadata filters matching auth claims
• If graph DB was chosen: graph queries parameterized — no string-interpolated Cypher/Gremlin, same injection risk as SQL

Step 12: Hand Off to autonomous-engineer

Invoke autonomous-engineer. Pass the full locked context:

• Goal, audience, platform, UI standard, animation approach, background, brand tokens
• Complete stack from the Confirm Full Stack output (Step 9)
• Scale decisions from Step 9.5: queue provider, circuit breaker library, CDN strategy, tracing setup, multi-region plan
• RAG configuration from Step 9.5: vector store, embedding model, chunking strategy, reranker, hybrid search setup
• Graph configuration from Step 9.5: graph DB, schema design, query depth limits, entity extraction pipeline
• Folder structure with workers/rag/graph directories (Step 10)
• Security requirements including framework-specific env handling, auth library, rate limiting, injection prevention (Step 11)

architect_planner (supervisor)
  ↓ delegates with locked plan
developer_engineer (worker) → structured outcome
  ↓
qa_evaluator (worker) → structured outcome
  ↓
test_engineer (worker) → structured outcome
  ↓
tdd_auto_fixer (worker) → structured outcome
  ↓
architect_planner reviews all outcomes, decides next delegation

Workers run their local loops to completion before surfacing. Each delivers a structured outcome (status, artifacts, decisions, blockers, next steps) to architect_planner. The supervisor wakes on outcomes, not on check-in intervals.

Step 12.5: Run Graphify (optional, requires API key)

If ANTHROPIC_API_KEY is set in the environment, run graphify to map the codebase and auto-open the knowledge graph:

gfy

(gfy is the alias for graphify . && open graphify-out/graph.html)

If no API key is set, skip this step silently. When available, it generates:

• graphify-out/graph.html: interactive knowledge graph (auto-opens)
• graphify-out/GRAPH_REPORT.md: key insights and suggested questions
• graphify-out/graph.json: queryable graph data

Step 13: Design Quality Gate

Before marking the build complete, run a final pass using:

• refactoring-ui: hierarchy, spacing, color: fix violations
• ux-heuristics: check all 10 heuristics, flag severity 3+ issues
• taste: does it look like only this product, or like every other app?
• impeccable-style: typography tracking, widow fix, spacing scale, hover/focus/active states
• webapp-testing: Playwright-based functional testing of the live app: invoke when the project has interactive UI flows that need verification beyond visual QA

Do not call the build done until this gate passes.

Step 13.5 — Flutter Performance & Security Gate (Flutter projects only)

Skip for non-Flutter projects. Mandatory before App Store Prep. Run in this order: profile → audit → fix → verify.

---

1. Profile First (always in profile mode, never debug)

flutter run --profile

Debug mode is JIT-compiled and has extra assertions — it is NOT representative of real performance. Always profile with --profile. Connect Flutter DevTools and open the Performance tab.

Performance Overlay — enable in-app to get a real-time UI + Raster thread graph:

MaterialApp(
  showPerformanceOverlay: true, // remove before release
  ...
)

Timeline tracing — wrap suspected slow code:

import 'dart:developer';
Timeline.startSync('expensive-operation');
// your code
Timeline.finishSync();

View results in DevTools → Performance → Timeline Events.

Frame Analysis tab (DevTools 2.17+) — shows Build / Layout / Paint / Raster breakdown per frame. Flag any frame > 16ms (60 FPS) or > 8ms (120 FPS ProMotion).

---

2. Rendering Audit

RepaintBoundary — Flutter may repaint a much larger area than necessary when one widget changes. Isolate expensive, frequently-updating widgets:

// Correct: only the chart layer repaints on data update
Column(
  children: [
    Header(),                            // never repaints
    RepaintBoundary(child: LiveChart()), // isolated repaint
    TransactionList(),                   // never repaints
  ],
)

Use DevTools → Inspector → Highlight Repaints to see repaint boundaries live. Every boundary has memory overhead — only wrap widgets that update independently from their siblings. Never wrap Text, Icon, or static widgets.

Best candidates for RepaintBoundary: charts, graphs, video players, maps, camera previews, looping animations, live dashboards.

const constructors — the single highest-leverage widget optimization. Flutter short-circuits the entire rebuild for const widgets:

// Every static widget should be const
const Text('Hello')
const SizedBox(height: 16)
const Icon(Icons.star)

Enable flutter_lints — it warns when const is missing.

Localize setState — calling setState rebuilds all descendents. Move state as close to the consuming widget as possible. Use Riverpod, Bloc, or Provider to scope rebuilds to only what changed.

Lazy lists — ListView builds all children eagerly. Use builder variants for any list:

ListView.builder(itemBuilder: (_, i) => ItemWidget(items[i]))  // lazy
SliverList(delegate: SliverChildBuilderDelegate(...))           // lazy + sliver

Avoid opacity animations via Opacity widget — use FadeTransition instead. Opacity triggers a paint layer; FadeTransition is compositor-only.

---

3. Memory Leak Detection

Run in profile mode, open DevTools → Memory tab:

1. Trigger a manual GC snapshot at app start (baseline)
2. Navigate through every screen, trigger all major interactions
3. Navigate back to root, trigger GC again
4. Compare snapshots — memory should return to near baseline
5. Any retained delta after GC = leak candidate. Inspect the retaining path.

Mandatory dispose pattern — every StatefulWidget that owns a resource must dispose it:

@override
void dispose() {
  _animationController.dispose();   // AnimationController
  _scrollController.dispose();      // ScrollController
  _textController.dispose();        // TextEditingController
  _focusNode.dispose();             // FocusNode
  _subscription.cancel();           // StreamSubscription
  _timer?.cancel();                 // Timer / PeriodicTimer
  super.dispose(); // always last
}

Async BuildContext safety — after any await, the widget may have unmounted:

Future<void> _load() async {
  final data = await fetchData();
  if (!mounted) return; // guard before using context
  setState(() => _data = data);
}

Common leak sources to audit:

• AnimationController without vsync cleanup
• StreamSubscription from listen() never cancelled
• ChangeNotifier listeners added but never removed
• Closures holding BuildContext references across async gaps
• Singleton services holding widget references

---

4. Shader Compilation Jank

First run on a new device can stutter due to shader compilation. Fix with shader warm-up:

# Record shader trace
flutter run --profile --cache-sksl --purge-persistent-cache

# Bundle shaders into the release build
flutter build apk --bundle-sksl-path flutter_01.sksl.json
flutter build ipa --bundle-sksl-path flutter_01.sksl.json

Alternatively, use Impeller (default on iOS, opt-in on Android) which pre-compiles shaders at build time and eliminates runtime jank entirely.

---

5. Image Optimization

• Use cached_network_image for all remote images — never Image.network directly
• Always set explicit width and height — prevents CLS-equivalent layout shifts
• Use .webp format — ~30% smaller than PNG/JPEG at same quality
• For large local assets, use ResizeImage to decode at display size, not source size:

  Image(image: ResizeImage(AssetImage('img.png'), width: 200, height: 200))

• Decode images in an Isolate for assets > 500KB to avoid UI thread stalls

---

6. Build Size Audit

flutter build apk --analyze-size
flutter build ipa --analyze-size

Opens an interactive size breakdown. Flag any single package > 5 MB. Actions:

• Remove unused packages from pubspec.yaml
• Use deferred loading for large optional features: import 'package:x/x.dart' deferred as x
• Tree-shaking is automatic in release mode — confirm no dart:mirrors usage (disables it)
• Use --split-per-abi for Android APKs to avoid shipping all ABIs in one bundle

---

7. Security

• No API keys or tokens hardcoded in Dart source — use --dart-define or flutter_dotenv
• Sensitive local data (tokens, credentials) stored in flutter_secure_storage, never SharedPreferences
• All release builds obfuscated:

  flutter build apk --obfuscate --split-debug-info=build/debug-info/android
  flutter build ipa --obfuscate --split-debug-info=build/debug-info/ios

  Store the split-debug-info output — required for symbolicating crash reports
• Certificate pinning on all production API calls (via dio interceptor or http_certificate_pinning)
• Screenshot/screen recording prevention on sensitive screens (payments, health data):

  // Android only — add to sensitive screen's initState
  FlutterWindowManager.addFlags(FlutterWindowManager.FLAG_SECURE);
  // Lift in dispose()
  FlutterWindowManager.clearFlags(FlutterWindowManager.FLAG_SECURE);

• Root/jailbreak detection for financial or health apps (flutter_jailbreak_detection)
• No debug logs in release builds — gate behind kDebugMode:

  if (kDebugMode) print('debug only');

API Security

• All API base URLs and keys in --dart-define or .env — never in source:

  flutter run --dart-define=API_BASE_URL=https://api.example.com --dart-define=API_KEY=xxx

  Access in Dart: const String.fromEnvironment('API_KEY')
• HTTPS enforced on all endpoints — no HTTP allowed in production
• Auth tokens sent only via Authorization header, never in query params
• Token refresh logic implemented — short-lived access tokens (15 min), long-lived refresh tokens stored in flutter_secure_storage
• All API responses validated with typed models (freezed + json_serializable) — never trust raw dynamic
• API errors never surfaced raw to users — map to user-friendly messages
• Rate limiting aware — implement exponential backoff on 429 responses
• Network requests only via a single HTTP client instance (e.g. Dio singleton) with interceptors for auth headers, logging (debug only), and error handling

.gitignore — must include before first commit:

# Environment & secrets
.env
.env.*
*.env
dart_defines/
secrets/

# Flutter
.dart_tool/
.flutter-plugins
.flutter-plugins-dependencies
build/
*.g.dart       # generated — committed only if your workflow requires it
coverage/

# Debug info (obfuscation symbols — never commit, archive separately)
build/debug-info/

# IDE
.idea/
.vscode/
*.iml

# macOS
.DS_Store

Run git status before every first commit to verify no .env, dart_defines/, or build/debug-info/ files are staged.

---

8. Static Analysis & Tests

flutter analyze          # must pass with zero errors
dart fix --apply         # auto-fix lint warnings
flutter test --coverage  # must reach 80%+ coverage

Enable strict lints in analysis_options.yaml:

include: package:flutter_lints/flutter.yaml
linter:
  rules:
    - prefer_const_constructors
    - prefer_const_literals_to_create_immutables
    - avoid_unnecessary_containers
    - sized_box_for_whitespace
    - use_key_in_widget_constructors

---

Flutter Gate Checklist

• Profiled with flutter run --profile (not debug)
• No frames > 16ms in DevTools Timeline
• RepaintBoundary on all expensive/animated widgets
• const on all static widgets, flutter_lints passing
• Memory baseline stable after full navigation loop
• All controllers / subscriptions / timers disposed
• Async BuildContext guarded with mounted checks
• Shader warm-up or Impeller enabled
• cached_network_image for all remote images
• App size reviewed — no single package bloat
• No hardcoded secrets — all keys via --dart-define or .env
• .gitignore includes .env, dart_defines/, build/debug-info/, build/
• HTTPS enforced on all API endpoints
• Auth tokens in Authorization header only, stored in flutter_secure_storage
• All API responses typed — no raw dynamic
• Release build obfuscated + split-debug-info archived separately
• flutter analyze zero errors, flutter_lints configured
• Test coverage 80%+

Do not proceed to App Store Prep until this checklist passes.

Step 14: App Store Prep (mobile apps only)

If the project targets iOS, Android, or both, run appstore-guidelines checklist:

• App icon at correct sizes (1024x1024 for iOS, 512x512 for Android)
• Screenshots at required device sizes
• Privacy labels accurate
• Demo account + setup steps written for App Review Notes
• In-App Purchase via Apple IAP if selling digital content

Step 15: End of Build

Two things always happen at the end:

n8n offer: If any part of the project involved repeating triggers, API calls, or multi-service workflows, use AskUserQuestion to ask: "Want to automate any part of this with n8n?" with options:

• Yes, automate it: invoke n8n skill: ask follow-up questions (what to trigger, what to connect, what the output should be) using AskUserQuestion, then output a ready-to-paste n8n AI prompt and setup instructions
• Not right now: skip and move to next steps
• Tell me what could be automated: list 3-5 specific automation opportunities based on what was just built, then ask again

Test before push: Open all changed/new files in the browser using open and tell the user: "Test it locally: let me know when everything looks good and I'll push." Do NOT run git commit or git push until the user explicitly confirms (e.g. "good", "looks good", "push it").

What's next: Present a list of 4-5 contextual next steps based on what was just built. Include relevant offers from:

• doc-coauthoring — if the project needs a PRD, spec, proposal, or decision doc written with the 3-stage (context → refinement → reader testing) workflow
• internal-comms — if the project involved a team workflow and needs 3P updates, a launch newsletter, FAQ, or incident write-up
• skill-creator — if what was just built follows a repeatable pattern the user will want to invoke again, offer to turn it into a reusable skill with evals
• Scale monitoring — if scale readiness (Step 9.5A) was configured, offer to set up dashboards: p99 latency alert, cache hit rate alert, queue depth alert, error rate alert, cloud cost budget alert
• RAG eval — if RAG (Step 9.5B) was configured, offer to run a Ragas evaluation pass on the golden question set and iterate on chunking or reranker configuration based on results
• Graph query tuning — if a graph DB (Step 9.5C) was configured, offer to profile the top 5 traversal queries, add indexes on hot node properties, and set depth + LIMIT guards on all production queries
• production-audit — run a full production readiness audit covering uptime, error tracking, alerting, runbooks, and on-call setup before going live with real users

---

Additional Resources

• references/ui-standards.md: design standards, component stack, background tools, 3-terminal template
• references/project-structure.md: clean architecture folder layout, constants rules, env var handling
• references/security.md: full OWASP checklist, auth rules, input validation, env var handling, security headers