Agent Legibility

AGENTS.md

• Give Agents concise maps, not encyclopedias
• Keep [AGENTS.md] short (< 100 lines) and progressively disclose through references.

# CLAUDE.md

<2-line overview>

## Scripts
npm run dev          # Start dev server
npm run lint         # Check for linting issues
npm run typecheck    # Verify type safety

Always run `npm lint && npm typecheck` after code changes.

See `package.json` for the full list of NPM tasks.

## Structure
- `app/`  - Application
- `docs/` - Markdown files
- `db/`   - DB migration
- `config.ts` - Global configuration

## Further Reading

**IMPORTANT:** From the docs below, read the ones required by the current task

- `docs/ssr-gotchas.md`
- `docs/testing-strategy.md`
- `docs/analytics.md`

Treat docs as source code

docs/
├── decisions/          # Strategic decisions (ADRs)
│   ├── db-sharding.md
│   └── i18n.md      
├── user-flows/         # Sequence diagrams, flow diagrams
│   ├── checkout-flow.md
│   └── signin-flow.md
├── plans/
│   └── active/
│		└── featureA    # Ralph Wiggum / ralph-tui ready
│			├── prd.md
│			├── prompt_plan.md
│			├── prompt_impl.md			
│			├── plan.md
│			├── specs/
│				├── topicA.md
│				├── topicB.md
│				└── ...
│   └── completed/
├── references/         # Slowly changing material referenced by other parts
│   ├── compliance.md
│   ├── accessibility.md
│   ├── performance.md
│   └── ...
├── AGENTS.md
└── ARCHITECTURE.md

Provide observability skills

• Screenshot skills
• Chrome Devtools Protocol
• Local observability stack (Logs, OTel)

Design <> Code

• Use Design tokens: primitive/semantic/component + alias
• Connect Figma components to code Prefer Code Connect CLI and make it part of your CI pipeline.

Agent distribution

• Team-level rules, skills and connectors on Claude, Codex and Cursor
• Packmind
• Git submodule with an install.sh script. Use symlinks for cross-agent compatibility similar to skills
• Run your own Plugin Marketplace for Claude Code. Plugin = Skills + Agents + Hooks + MCP servers

Agent autonomy

• Bootable Git worktrees so that agents can branch out, build and verify in parallel.
• Bootable Cloud Agents
• Ralph Wiggum / Taskmaster AI

Local Sandboxes

• Container-based: Dev Containers, standard Docker
• Process-isolation: bubblewrap (Linux), sandbox-exec (Mac)

Agent Harness

Upstream steering

• AGENTS.md
• Subagents
  • Per layer: data, domain, HTTP
  • Per module: core, bookings, payments
  • Experts: Webpack Bundler Investigator, Route Analyzer, i18n Auditor
• Skills
  • Write tests
  • Performance
  • Analytics
  • Refactor / Simplify
  • Review
• Rules
  • Copywriting
  • Security
  • Testing
  • UI Design
• MCP (task tracker, API docs, Figma)

Backpressure

• Linting
• Type checking
• Build validation
• Tests
• Visual snapshots

LLM as Judges

• For subjective criteria: Tone, UX, code quality, etc.
• For acceptance criteria: Code meets requirements in PRDs and spec files.
• Provide binary PASS/FAIL answers (e.g. through PR status checks)