Agentic Team Project Template

A framework for AI agents and humans to collaborate on principal-level engineering decisions. Technology and agent agnostic. Works with any coding agent that can read Markdown and run shell commands (Claude, Codex, Copilot, etc.). Reduces decision fatigue through evidence-driven discovery, structured semantic state, and composable workflows that adapt to your skill level and project complexity.

Problem: When an agent acts alone, humans lose visibility into trade-offs and assumptions. When humans micro-direct agents, decisions become slow. When guardrails are opaque, teams cannot learn or adapt them.

Solution: Make the operating rules explicit and learnable (AGENTS.md), keep semantic state visible and structured, use composable skills that agents can invoke in any topology, and stay human-in-the-loop at irreversible or high-stakes choices.

• Principal-level decisions, not code generation. Architecture boundaries, right-sizing (conscious, recorded, bought-in), quality gates, role attribution, tech choices - decisions that are hard to reverse.
• Adapts to your experience. The workflow calibrates to the user's skill level and project complexity. A domain expert can partner with an agent on design; a junior engineer gets more coaching and structure.
• Opinionated but learnable. The rules are in readable Markdown, not hidden in prompt engineering. You can change them, disagree with them, or understand why they exist.
• No magic. Commands are explicit shell scripts under .agentic-template/bin/. Hooks and commands are in CLAUDE.md (symlink to AGENTS.md). Knowledge is stored locally in .agents/knowledge/ with durable schemas.
• Works with any agent. No proprietary integrations. Agents start with .agentic-template/bin/project startup, read AGENTS.md from disk and see the startup sequence and options before executing shell commands. That is it.

"I already have a CLAUDE.md and some skill files — why this?" Because these rules fail. project check runs nine deterministic gates, so an agent that skips a required handoff section, invents a knowledge edge, or leaves a credential in a committable file is caught — not trusted to have read the prose. See Why this, not just a skill file.

1. You provide project intent - briefs, constraints, user stories, artifacts.
2. The agent inspects the repo - existing code, manifests, configs - and asks the smallest useful question set to resolve unknowns.
3. The agent proposes a minimal architecture - smallest sufficient design, recorded and bought into.
4. You decide at hard choices - architecture boundaries, trade-offs, what NOT to build.
5. Development follows a loop - calibrate, ideate, structured spec, ATDD, review, archive + wiki.

Human provides:                    Agent discovers:              Human decides at:
- Project intent                   - Runtime, framework          - Hard choices
- Briefs, artifacts                - Persistence, messaging      - Architecture boundaries
- User stories                     - Test strategy               - Right-sizing (what NOT to build)
- Constraints                      - Container, infra            - Trade-offs between personas

                           |
                           v

                    /specialise -> evidence-driven bootstrap
                                    calibrate audience, build project profile

                           |
                           v

                     Development lifecycle:
                     calibrate -> ideate -> structured spec -> ATDD -> review -> archive + wiki

On GitHub, use Use this template. Locally, copy the repo and point origin at your new repository.

Update CUSTOMIZE_THIS_PROJECT.toon:

• project: name, purpose, primary users
• domain: core capabilities, hard constraints
• narrative: (optional) a free-text project brief; agents will interrogate and expand it

Add any artifacts: sketches, API drafts, package files, links.

In Claude, Codex or another coding agent, make the first prompt explicit:

Run .agentic-template/bin/project startup first. Confirm that AGENTS.md was
read from disk, review the startup sequence and options, then continue.

Help me initialise this project from the template.
Run .agentic-template/bin/project init, inspect the result, and guide me
through the smallest useful next setup steps. If my project intent is unclear,
interview me and help convert my answers, briefs and artifacts into project state.

The agent will:

• Inspect repository evidence (existing code, manifests, config)
• Ask the smallest useful question set to resolve unknowns
• Recommend the smallest sufficient architecture
• Populate PROJECT_PROFILE.toon with facts, inferences, decisions and unknowns
• Specialise runtime, testing, static analysis, build, deployment, observability and CI from your evidence
• Rewrite the README and operating contract for your project
• Hand off to HANDOFF.toon so the next work continues from here

If you already have a project and want the portable context router without adopting the full template:

1. Clone this template somewhere outside your project.

2. Run the scaffold (dry-run first, then apply):

   /path/to/template/.agentic-template/bin/project context scaffold \
     --into /your/project --apply

   This copies the router library, the context command, the portable tests, the qualification fixture, and the router configuration (ROUTER.toon, RECOVERY.toon, runtimes.toon, overrides.toon) into your project. It also writes starter files (TOPICS.toon, risk-rules.toon) only if they don't already exist, and never touches project-owned files (overrides.local.toon, observations/).

3. Wire up the project facade. If your project doesn't already have .agentic-template/bin/project, create a minimal one that dispatches context:

   #!/usr/bin/env python3
   import subprocess, sys
   from pathlib import Path
   BIN = Path(__file__).resolve().parent
   if len(sys.argv) > 1 and sys.argv[1] == "context":
       sys.exit(subprocess.run([str(BIN / "context")] + sys.argv[2:]).returncode)
   print("project: only 'context' is available")
   sys.exit(1)

4. Verify: run .agentic-template/bin/project context check — it should print CONTEXT ROUTER OK.

5. Catalogue your skills in .agents/skills/CATALOG.toon and layer them following the taxonomy conventions (see the method glossary).

See the portable context router page for why context depth is routed rather than fixed.

Start from the route that matches your intent:

For a full command-line map, run .agentic-template/bin/project docs.

The context store is the repository, not an external memory service. It is the versioned set of artifacts that let humans and agents recover intent, behavior, lineage and conformance:

Generated projects should encode the top 1-3 architecture risks as cheap fitness functions where practical. Non-trivial handoffs should include the spec reference or no-spec rationale, fitness-function delta or no-change rationale, validation run and knowledge update. See docs/context-store.md.

Work flows through a small, connected loop. Agents drive it; humans steer at decision points.

/specialise --> calibrate audience + app shape (plain language)
                  right-size: smallest sufficient architecture, recorded buy-in
       |
       v
/ideate ------> short-cycle multi-persona loop -> structured change artifact
     (idea or     Intent -> Boundary -> Delivery -> Quality gate
     narrative)   At hard choices: show persona stances (discourages/accepts/encourages)
       |
       v
project lint --> static analysis gate (shift-left): lint, type-check,
                 security, complexity — before tests
       |
       v
outside-in -> acceptance test per WHEN/THEN scenario, fidelity by risk
    ATDD        (acceptance / component-integration / subcutaneous)
                 acceptance tests are orthogonal to the testing trophy
       |
       v
/review ------> boy-scout cleanup: code, language and architectural smells, coupling
       |
       v
archive -------> specs/capabilities/ + wiki keeps docs and knowledge graph current

Key principles:

• Shift left from the get-go. Static analysis (project lint) runs before tests in CI. Reproducible builds (project build) are Nix-first. Deployment pipeline and observability decisions are recorded at /specialise, even when deferred. Budget appetite (constrained / moderate / comfortable / generous) influences right-sizing.
• Specs are structured and agent-first. TOON is the template default; generated projects may choose TOON or S-expressions by purpose during setup.
• Quality is standing, not a phase. Boy-scout rule, reuse over duplication, pay in-path debt, docs land in the change, no silent TODOs.
• Right-sizing is conscious. The smallest sufficient architecture is chosen, explicitly. What is excluded and why are recorded. Revisit conditions are named.
• Use the right framework. Don't build from first principles when a mature, well-supported framework solves the problem. Hand-rolling what a framework provides is a smell.
• Knowledge is a typed, checked graph. .agents/knowledge/ is closer to a small git-native knowledge base than a folder of notes. Nodes are typed and addressable (DOM-, SYS-, CON-, ARCH-, ADR-, PAT-, RISK-, Q-, LRN-) and connect through declared edges (depends_on, consumes, produces, decisions, risks, supersedes). Edges are validated: a dangling reference fails check-knowledge, and a spec citing a non-existent node fails check-changes. That makes "which risks touch this capability, and which decision accepted them?" a traversal rather than a grep — answerable without the session that produced it. Specs, ADRs and wiki pages join the same graph via TAXONOMY.md.
• Context is repo-native. Structure, lineage, behavior and conformance live in versioned files and checks, with external memory added only when evidence justifies it.
• Format policy is explicit. TOON fits state/contracts; S-expressions fit rules/compute. See docs/structured-data.md.

This template works with any agent that can:

• Read Markdown files
• Execute shell commands
• Interpret simple structured text (TOON by default)
• Follow a text-based operating contract

No proprietary APIs. No agent-specific prompting tricks. The contract is learnable.

The template does not force choices. It:

• Inspects repository evidence first (existing code, manifests, config)
• Recommends the smallest sufficient option
• Asks only high-impact questions
• Records unknowns, not secret assumptions

Example: if you have a package.json, Node is inferred. If you have both Python and Java, the agent asks which is primary. If you have neither, the agent asks what you are building.

This is not a scaffolding tool. It is for:

• Making architecture boundary decisions
• Choosing what NOT to build (right-sizing)
• Reconciling trade-offs between personas
• Keeping technical debt visible and paid
• Keeping quality standing, not deferred
• Recording durable decisions (ADRs)

Code generation happens inside the lifecycle, not as the whole point.

At every hard choice, agents surface the trade-off:

choice: add a message broker now
  architect     discourages (no async evidence yet)
  tech-lead     accepts     (isolated, reversible)
  product-owner encourages  (unblocks the next capability)
  -> [human decides]

No consensus required. The lead decides, informed by who cares what.

Enter the Nix development shell:

nix develop

Or use the documented one-shot ladder (pinned container -> npx fallback).

Run the canonical commands:

.agentic-template/bin/project help
.agentic-template/bin/project startup    # Welcome, options and AGENTS.md from disk
.agentic-template/bin/project init       # Bootstrap a new project
.agentic-template/bin/project check      # Run all repo checks
.agentic-template/bin/project ready      # Is this project ready to ship?
.agentic-template/bin/project doctor     # Diagnostic summary

This template is built on composable skills - reusable workflows for ideation, discovery, planning, testing, refactoring, review and delivery. Skills are lazy-loaded via .agents/skills/CATALOG.toon and do not require all of them at once.

• Claude (Anthropic) - reads CLAUDE.md, .claude/README.md and .claude/skills/agentic-template/SKILL.md
• Copilot (GitHub) - reads AGENTS.md + .github/copilot-instructions.md
• Codex (OpenAI) - reads AGENTS.md + .codex/README.md
• Cursor - reads AGENTS.md + .cursor/rules/agentic-startup-and-skills.mdc
• Any agent that can read Markdown and execute shell commands

The template defines persistent team roles that agents can adopt via /sudo:

• Product Owner: scope, intent, acceptance criteria
• Architect: boundaries, trade-offs, reversibility
• Tech Lead: thin slices, test strategy, delivery
• Domain Expert: domain rules, validation paths
• Knowledge Curator: durable knowledge, graph consistency

1. Single lead + fallback checklist - one agent, explicit review gates (cheapest)
2. Sequential role passes - lead switches personas via /sudo (scalable)
3. Independent subagents - separate agents per role (most rigorous)
4. Persistent team - dedicated roles with long-term memory (highest fidelity)

Pick the topology that matches your risk and budget.

Every project makes an explicit container decision. Deployable services and web applications default to a tested application image unless evidence supports a documented exception.

.agentic-template/bin/project image
.agentic-template/bin/project image-test
docker run -it $(docker build -q .)

See README_TEMPLATE.md (generated README) for runtime instructions.

Default to test-first for meaningful behaviour.

Testing posture:

• Outside-in, boundary-in ATDD. Start from acceptance test, drive inward.
• Fidelity by risk. Acceptance, component-integration, or subcutaneous - choose per scenario.
• Real dependencies where they matter. Use Testcontainers for lifecycle-managed integration tests.
• Testing trophy: strong unit feedback + strong integration confidence + a few E2E paths.

.agentic-template/bin/project test
.agentic-template/bin/project integration-test
.agentic-template/bin/project e2e-test

Project configuration is declared in:

• AGENTS.md - operating rules and canonical commands
• docs/context-store.md - repo-native structure, lineage, behavior and conformance map
• PROJECT_PROFILE.toon - project facts, inferences, decisions, unknowns
• HANDOFF.toon - active work state, completed work, next actions
• PROJECT_PROFILE.toon.structured_data - TOON/S-expression policy by purpose
• .agents/knowledge/ - durable decisions (ADRs), patterns, risks, questions, learnings

Environment variables are documented in the generated README.md.

Default setup uses TOON for state/contracts and S-expressions for rules/compute. TOON is readable and diff-friendly; S-expressions are compact for predicates and transformations. See docs/structured-data.md.

Every project records:

• Local topology: Nix devshell, containers, Compose
• Deployment target: cloud provider, serverless, self-hosted, deferred
• IaC status: required, deferred, not applicable

See PROJECT_PROFILE.toon.infrastructure and the generated README.

This is not:

• An internal developer platform (IDP). No defaults for databases, brokers, Kubernetes, or runtimes.
• A code-generation service. It is for decision-making.
• Black-box magic. All rules are readable; all state is structured text.
• Coupled to a single agent or platform.
• A replacement for human architecture review. It is a tool to make review more structured.

• Architecture: see docs/architecture/ (ADRs)
• Decisions: see docs/decisions/ (ADR index)
• Docs map: see docs/README.md
• Wiki: see docs/wiki/index.md (method pages inherited from the template, product pages written by the project)
• Context store: see docs/context-store.md
• Validation: see docs/validation.md
• Runbooks: see docs/runbooks/ for optional repeatable operations
• Knowledge: see .agents/knowledge/ (taxonomy, domains, systems, risks, questions)
• Durable rules: see AGENTS.md (operating contract)
• Development lifecycle: see docs/wiki/method/development.md

This template was designed with AI agents as first-class collaborators. The structure, workflows and rules reflect a philosophy: agents reduce decision fatigue when operating under an explicit, learnable contract that keeps humans in the loop at irreversible choices.

The /specialise bootstrap, the development lifecycle, the persona topology, the knowledge graph, and the CI contract were all developed with agent assistance. They have been shaped by what makes agent-human collaboration effective, not just what makes sense to humans alone.

If you use this template, you are opting into:

• Composable skills that agents can invoke
• Semantic state (structured text) that agents can parse and update
• Readable operating rules (this contract) that agents and humans share
• Persistent topologies (personas, subagents) that preserve context across sessions
• Hard choice attribution (persona stance) so you know who favours what trade-off

The goal is not to replace you. It is to make it faster and clearer for you and an agent to collaborate on decisions that matter.