Agent-First Project Scaffolding

Distilled from analyzing agent instruction files across 8 major open source projects totaling 400k+ stars.

Projects Analyzed

Project	Stars	Key Innovation
OpenClaw	181k	Multi-agent safety, 3-step PR pipeline, skills system
Excalidraw	116k	Minimal but effective CLAUDE.md
Cal.com	40k	Three-tier boundaries (Always/Ask/Never), modular rules, knowledge base
PostHog	31k	Per-language cursor rules, security rules (SQL/HogQL injection), interaction style
Vercel AI SDK	21k	Task completion guidelines, clean architecture docs
CodexBar	5.4k	Swift-specific agent patterns
Peekaboo	2k	Submodule coordination
mcporter	1.7k	Shared guardrails pointer pattern

Also incorporates Peter Steinberger's blog post on shipping at inference speed.

Next.js Reference (NEW)

The projects/nextjs/ directory contains a comprehensive Next.js-specific reference for Claude Opus 4.6 and OpenAI Codex 5.3, including:

• AGENTS.md — Production-ready Next.js agent instructions (App Router, Server Components, Server Actions)
• templates/ — 3 ready-to-use templates (minimal, full-stack, SaaS)
• skills/ — React performance (57 Vercel rules) + web design guidelines (100+ rules)
• commands/ — Slash commands for page creation, Server Actions, performance optimization
• RESEARCH.md — Full investigation across 18+ sources with eval data
• NEXT-STEPS.md — Setup guide with ecosystem map

Key finding: Vercel's evals show AGENTS.md with compressed doc index achieves 100% pass rate vs 53% baseline on Next.js 16 APIs.

FastAPI / Python Backend Reference (NEW)

The projects/fastapi/ directory contains a comprehensive Python/FastAPI-specific reference for Claude Opus 4.6 and OpenAI Codex 5.3, including:

• AGENTS.md — Production-ready FastAPI agent instructions (async patterns, Pydantic v2, SQLAlchemy, Alembic)
• templates/ — 3 ready-to-use templates (minimal, full-stack, microservices)
• skills/ — FastAPI patterns & anti-patterns (12 categories) + Python tooling config (uv, Ruff, mypy, pytest, Docker)
• commands/ — Slash commands for endpoint creation, migrations, verification pipeline
• RESEARCH.md — Full investigation across 25+ sources with tiered references
• NEXT-STEPS.md — Setup guide with ecosystem map

Key finding: Every high-star Python project with AGENTS.md uses the same stack: uv + Ruff + mypy + pytest. The tooling consensus is settled.

Supabase + PostgreSQL Reference (NEW)

The projects/supabase/ directory contains a comprehensive Supabase + PostgreSQL-specific reference for Claude Opus 4.6 and OpenAI Codex 5.3, including:

• AGENTS.md — Production-ready Supabase agent instructions (RLS, migrations, Edge Functions, Auth, Realtime, Storage)
• templates/ — 3 ready-to-use templates (minimal, full-stack, multi-tenant SaaS)
• skills/ — Supabase patterns & anti-patterns (8 categories) + PostgreSQL performance & security (8 categories from official agent-skills)
• commands/ — Slash commands for migration creation, RLS policy generation, verification pipeline
• RESEARCH.md — Full investigation across 20+ sources including Supabase's official agent-skills
• NEXT-STEPS.md — Setup guide with ecosystem map

Key finding: Supabase is the first major platform with official agent skills (supabase/agent-skills, 1.3k stars) — 31 Postgres rules across 8 categories. RLS optimization alone can improve query performance by 100x-15,000x.

Key Findings (see ANALYSIS.md for full breakdown)

1. Commands are king - Every project puts build/test/lint commands front and center
2. Boundaries define autonomy - Cal.com's Always/Ask/Never tiers are the gold standard
3. Do/Don't > prose - Scannable lists outperform paragraphs for agent consumption
4. Security is underinvested - Only PostHog has deep security guidance
5. Task completion checklists prevent incomplete work - Define what "done" means
6. Multi-agent safety is emerging - OpenClaw leads with explicit coordination rules
7. Domain knowledge needs its own file - Cal.com's knowledge-base.md pattern works
8. One file to rule them all - AGENTS.md is becoming the universal standard (symlink CLAUDE.md to it)

Universal Template

The AGENTS_TEMPLATE.md at root is the copy-paste starting point. Sections in priority order:

1. Project Overview - One line
2. Commands - Table of build/test/lint/dev commands
3. Project Structure - Directory map
4. Boundaries - Always do / Ask first / Never do
5. Code Style - Do/Don't with examples
6. Git & Commits - Conventional commits, safety rules
7. Security - Input validation, secrets, dependencies
8. Testing - Regression tests, task completion checklists
9. Multi-Agent Safety - Concurrent agent coordination
10. Docs - Front-matter hints, update-on-change
11. Tools - committer, gh, slash commands
12. Critical Thinking - Root cause, verify, ask when stuck

Directory Structure

AGENTS.md                              # This repo's own agent instructions
CLAUDE.md                              # Symlink -> AGENTS.md
AGENTS_TEMPLATE.md                     # Universal template (copy into new projects)
ANALYSIS.md                            # Deep analysis of all 8 projects
README.md                              # This file
docs/
  subagent.md                          # Multi-agent coordination guide
  slash-commands/
    README.md                          # Command index
    handoff.md                         # /handoff - session continuity
    pickup.md                          # /pickup - context rehydration
    fixissue.md                        # /fixissue - issue resolution
scripts/
  committer                            # Safe commit helper (executable)
skills/
  create-cli/SKILL.md                  # Example skill definition
projects/                              # Raw agent docs by project
  openclaw/                            # 181k stars
    AGENTS.md                          # Full repo guidelines
    CLAUDE.md                          # Codebase patterns
    CONTRIBUTING.md                    # AI PRs welcome policy
    skills/                            # PR_WORKFLOW, review-pr, prepare-pr, merge-pr
    prompts/                           # reviewpr, landpr, fixissue, changelog
  calcom/                              # 40k stars
    AGENTS.md                          # Do/Don't format, boundaries
    agents/
      README.md                        # Rules index
      knowledge-base.md                # Domain knowledge
      rules/                           # Modular rules with YAML frontmatter
  posthog/                             # 31k stars
    AGENTS.md                          # Security-heavy, multi-language
    cursorrules.md                     # Interaction style
    cursor-rules/                      # Per-language: django, react, rust
  vercel-ai/                           # 21k stars
    AGENTS.md                          # Task completion guidelines
  excalidraw/                          # 116k stars
    CLAUDE.md                          # Minimal effective template
  agent-scripts/                       # steipete's shared config
    AGENTS.md                          # Canonical shared rules
  codexbar/AGENTS.md                   # Swift menu bar app
  peekaboo/AGENTS.md                   # macOS screenshot CLI
  mcporter/AGENTS.md                   # MCP launcher
  nextjs/                              # Next.js reference (Opus 4.6 + Codex 5.3)
    AGENTS.md                          # Production Next.js agent instructions
    CLAUDE.md                          # Symlink note (-> AGENTS.md)
    RESEARCH.md                        # Full investigation findings
    NEXT-STEPS.md                      # Setup guide + ecosystem map
    templates/
      minimal.md                       # ~40 line template for small projects
      full-stack.md                    # ~120 line template with DB + auth
      saas.md                          # ~150 line multi-tenant template
    skills/
      react-performance.md            # 57 Vercel rules distilled
      web-design-guidelines.md        # 100+ UI/UX rules distilled
    commands/
      create-page.md                  # /create-page slash command
      create-server-action.md         # /create-server-action slash command
      optimize-performance.md         # /optimize-performance slash command
  fastapi/                            # FastAPI/Python reference (Opus 4.6 + Codex 5.3)
    AGENTS.md                         # Production FastAPI agent instructions
    CLAUDE.md                         # Symlink note (-> AGENTS.md)
    RESEARCH.md                       # Full investigation findings (25+ sources)
    NEXT-STEPS.md                     # Setup guide + ecosystem map
    templates/
      minimal.md                      # ~50 line template for small APIs
      full-stack.md                   # ~150 line template with DB + auth
      microservices.md                # ~170 line distributed services template
    skills/
      fastapi-patterns.md             # 12 categories of patterns & anti-patterns
      python-tooling.md               # uv, Ruff, mypy, pytest, Alembic, Docker configs
    commands/
      create-endpoint.md              # /create-endpoint slash command
      create-migration.md             # /create-migration slash command
      run-checks.md                   # /run-checks slash command
  supabase/                          # Supabase + PostgreSQL reference (Opus 4.6 + Codex 5.3)
    AGENTS.md                        # Production Supabase agent instructions
    CLAUDE.md                        # Symlink note (-> AGENTS.md)
    RESEARCH.md                      # Full investigation findings (20+ sources)
    NEXT-STEPS.md                    # Setup guide + ecosystem map
    templates/
      minimal.md                     # ~60 line template for small Supabase apps
      full-stack.md                  # ~200 line Next.js + Supabase template
      saas.md                        # ~220 line multi-tenant SaaS template
    skills/
      supabase-patterns.md           # RLS, Auth, Realtime, Storage, Edge Functions patterns
      postgres-performance.md        # 8 categories from official agent-skills
    commands/
      create-migration.md            # /create-migration slash command
      create-rls-policy.md           # /create-rls-policy slash command
      run-checks.md                  # /run-checks slash command

How to Use

1. New project: Copy AGENTS_TEMPLATE.md to your repo as AGENTS.md. Run ln -s AGENTS.md CLAUDE.md.
2. Customize: Replace the placeholder sections with your actual commands, structure, and stack.
3. Add boundaries: Define your Always/Ask/Never rules.
4. Add domain knowledge: Create agents/knowledge-base.md for product-specific context.
5. Add rules (optional): Use Cal.com's agents/rules/_template.md pattern for modular rules.
6. Add slash commands (optional): Copy docs/slash-commands/ for session continuity.