AGENTS.md — [Project Name]

Purpose: Provides a copy-paste template for the AGENTS.md file that every child project needs, covering project overview, commands, structure, code style, and boundaries.

Instructions for AI coding agents working on this project.

Project overview

[Brief description of what this project does]

Tech Stack: [e.g., TypeScript, React, Node.js, PostgreSQL]

Commands

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Run tests
pnpm test

# Lint code
pnpm lint

# Build for production
pnpm build

Testing

• Framework — [e.g., Vitest, Playwright]
• Run all tests — pnpm test
• Run specific test — pnpm test -- <filename>
• Coverage — pnpm test:coverage

Every feature requires tests. No PR without passing tests.

Project structure

app/
  (public)/      # Public routes
  (admin)/       # Admin routes
  api/           # API routes
components/      # React components
hooks/           # Custom hooks
lib/             # Utilities and shared logic
types/           # TypeScript types
docs/
  specs/         # Spec artifacts from agent workflow

Code style

• TypeScript strict mode — Always enabled
• Functional components — Prefer with hooks
• Named exports — Not default exports
• Small functions — Keep focused and single-purpose
• JSDoc comments — For public APIs

Git workflow

• Branch naming — feature/PROJ-42-description, fix/PROJ-51-description, chore/PROJ-60-description
• Commit messages — Imperative mood ("Add feature" not "Added feature")
• PRs — Require passing CI and review
• Merge strategy — Squash merge to main

Pre-flight gates

For agents with prerequisites that must be confirmed before execution (e.g., scaffold state, passing builds, available credentials), use the pre-flight gate pattern documented in .claude/skills/skill-creator/SKILL.md § "Writing Patterns".

Boundaries — do NOT

• Modify files outside your issue scope
• Skip tests — Not even to "save time"
• Commit secrets or credentials
• Remove existing tests — Not without approval
• Make breaking API changes — Not without documentation

Framework standards

This project follows Framework SDLC principles:

1. Issue-first documentation — Design artifacts (briefs, tech specs, decisions) default to Linear issue comments. Spec files (docs/specs/) only for artifacts exceeding ~200 lines, shared across issues, or containing complex diagrams.
2. No silent failures — If requirements are unclear, STOP and ask.
3. Verify before done — Every issue has acceptance criteria and test requirements.
4. Quality over speed — Consistency enables improvement. Ship working code.

When implementing issues:

• Check Linear issue comments first — Look for briefs and tech specs
• Read linked specs for large features — docs/specs/[issue-id]-brief.md, -prototype.md (UI only), -tech.md
• Follow acceptance criteria exactly
• Run verification before marking done
• Update specs if you discover gaps

Project-specific patterns

[Anything unique to this project — or "None, follows Framework standards exactly"]