AI-native project scaffold

A starter kit for projects where an AI coding agent (Claude Code, or similar) is a first-class collaborator. Extracted from a working codebase. Stack-agnostic — the patterns are reusable; the specifics are yours to fill in.

What's here

scaffold/
├── CLAUDE.md                          Entry point: rules + doc-loading map for the agent
└── docs/
    ├── tech-constitution.md           WHY: principles, stack rationale
    ├── architecture.md                HOW: layers, request lifecycle, dependency rules
    ├── project-structure.md           WHERE: folder map for the agent
    ├── testing.md                     Quality gates, test tiers, agent-readable outputs
    ├── test-inventory.md              Catalog of tests that exist (populated as you go)
    ├── conventions/
    │   ├── README.md                  Index of context-specific convention files
    │   ├── development-guardrails.md  Coding standards, security posture, observability
    │   ├── component-inventory.md     Catalog of reusable UI components
    │   ├── data-inventory.md          Catalog of tables / collections
    │   └── domain-glossary.md         Precise definitions of domain terms
    └── operations/
        ├── README.md                  Index of operational runbooks
        ├── parallel-development.md    Worktree/container isolation for parallel agents
        ├── debugging-gates.md         How to diagnose quality-gate failures
        └── environment-variables.md   Env var reference (single source of truth)

Placeholders use {{DOUBLE_BRACES}} — search for them and fill in or delete.

The core patterns

1. CLAUDE.md is the entry point. It states the rules the agent must follow and acts as a loader — listing mandatory docs to read first, and conditional docs to load only when working on specific areas.
2. Docs are structured by purpose and audience, not by topic. tech-constitution is for humans making stack decisions. architecture is for anyone modifying code. conventions/* are loaded on demand.
3. Inventories are queryable catalogs. test-inventory, component-inventory, data-inventory answer "what already exists?" — preventing the agent from duplicating things.
4. One command runs all quality gates, and produces a machine-readable summary the agent can consume (test:all:ai → .test-ai-results/summary.md).
5. Parallel development is first-class. Each agent session runs in an isolated worktree with its own infrastructure — no shared state, no port collisions.
6. Doc maintenance is part of the task. Finishing a feature includes updating the relevant docs.

How to use this scaffold

1. Copy the tree into a new repo.
2. Walk the files top-to-bottom and fill in {{PLACEHOLDERS}}.
3. Delete sections that don't apply (e.g., if you don't have a UI, drop component-inventory.md).
4. Wire CLAUDE.md section 8 ("Context-Specific Conventions") to point at the files you kept.
5. Implement test:all (and an AI-readable variant) that runs your actual quality gates.
6. Start building. The agent will load what it needs.

What this scaffold does not include

• A tech stack. Pick your own.
• CI configuration. Covered in docs/operations/ once you have one.
• Plugin configs, hooks, or settings.json — those are per-environment.
• Templates for docs that only make sense once the project has real content (PR templates, ADRs, incident runbooks).