TCA Project Template

A starting scaffold for building software with Type Construction Architecture (TCA). You drive your main agent; it drives a build team that models and writes the code under a hard rule that keeps code generation off the main agent's hands.

How you work here

Use your main agent (Claude Code) exactly as CLAUDE.md instructs. You state product intent and program meaning in plain language; the main agent orchestrates the build team and reviews their work against the construct cards. You do not hand-write the code under src/, and neither does the main agent.

The build team (full loop in CLAUDE.md):

• plan agent (.claude/agents/plan-agent.md) — turns a need into a validated Plan: the list of constructs that carry each meaning, selected from the construct cards, never guessed. You hand it meanings, never construct names.
• build agents (.claude/agents/build-agent.md) — one construct type per agent, per file. Each reads its tca_authorized_construct_* card and writes exactly that one construct in that one file, to the card's required form.
• the main agent — orchestrates: decomposes the Plan into dispatches, reviews every build result against its card (not just the type checker), and escalates only what the doctrine cannot settle. It never writes src/**/*.py and never names a construct; those are the two acts this system exists to keep off its hands.

The construct cards and the planning tool are served over MCP from .claude/scripts/app/ (wired in .mcp.json). A build is done when uv run basedpyright and uv run pytest are both green.

Start

1. Read CLAUDE.md. It is the operating frame for your main agent.
2. Fill in the Project: section of CLAUDE.md with what this repo is (the template ships it as unset, and instructs the agent to settle it with you first).
3. Give your main agent a need, in plain language, and let the loop run.

Method reference (docs/)

• docs/definition.md — what TCA is: the correspondence, the four breaks, the inherited and broken rules.
• docs/programs-are-ontologies.md — why a program built this way is an executable ontology.
• docs/proofs-and-graph.md — designing from proof obligations and reading a construction graph.
• docs/semantic-index-types.md — how a language model reads type names as instructions.