Team Configuration

When you run moot init, it puts three things on disk: a CLAUDE.md file, a set of workflow skills in .claude/skills/, and a .devcontainer/ configuration. The CLAUDE.md is the most important of the three. It is not boilerplate — it is the team’s configuration: where the agents look to understand what kind of team they are, what they care about, and how they work together.

This page explains what is in it and how it is structured so you can use it well.

The direction layer

The top of a well-configured CLAUDE.md states three things: a mission, a vision, and a set of values. These are not decorative. They are load-bearing.

Mission is the project’s north star: one sentence that says what the work is for. It doesn’t describe what you’re building; it says why it matters. Missions don’t change unless the project’s fundamental purpose does.

Vision is the medium-term destination: a more concrete picture of what success looks like over the next few months. It can change as the project matures.

Values are trade-off guides. They say what to prize when two reasonable options are in tension — correctness over cleverness, accessibility over virtuosity, honest scope over optimistic claims. Each value pre-resolves a recurring trade-off so agents make consistent calls without re-litigating the same decision each session.

Why does an agent team need all three? Human teams carry these things implicitly — in shared context, in culture, in years of working together. An agent starts fresh each session. Without an articulated direction, it falls back on the training defaults it arrived with, which may be reasonable defaults for generic software work but are not your project’s standards. Direction is what makes agent behavior consistent across sessions and across team members.

If a layer is missing, the symptoms are recognizable. A team with no mission produces work that drifts — agents can’t consistently prioritize what matters when options diverge. A team with no vision over-invests in foundational work or makes local decisions that don’t accumulate toward anything. A team with no values gets inconsistent quality judgments: one agent calls a verbose implementation a clarity win; another calls it bloat.

The operational layers

Below the direction layer, CLAUDE.md contains several operational layers. Each serves a different function and has a different character.

Policies are if-then rules that translate direction into concrete guardrails. They are scoped: they say what to do in a specific situation, not how to think in general. A policy like “confirm before irreversible actions” follows directly from valuing reversibility. Policies can be updated as you learn your project’s risk profile.

The constitution holds invariants — commitments that don’t change run-to-run. Which role is responsible for which resource. Which role makes which class of decision. What counts as a process error versus a judgment call. The constitution is load-bearing: violating it is not recoverable by good intentions.

Topology names who talks to whom. The default team has a specific communication structure: work flows in one direction through a pipeline; certain roles escalate through specific channels; resource ownership determines which role acts on a given class of request. Topology is the most load-bearing layer to change — modifying the pipeline shape has effects that propagate through every agent’s operating assumptions.

Operational practice is how agents do the work: commit discipline, handoff format, when to delegate versus handle locally. Unlike the constitution, these can improve. Retrospectives are designed to surface refinements to operational practice; the retro cycle is how the team gets better over time.

Why are these separate? Different layers have different cadences. Direction is set once and revised when the project’s fundamentals shift. Policies are tuned as you learn the project’s risk surface. Operational practice improves every few features. The constitution and topology are nearly fixed — they only change when the team’s structure intentionally changes.

Keeping them separate means a retro observation can land in the right layer without accidentally destabilizing a higher one. A process improvement goes into operational practice. A hard-won invariant goes into the constitution. A new resource-ownership rule goes into policies. The layers give each kind of learning a home.

How changes propagate

Changes to CLAUDE.md take effect the next time an agent starts a session — no restart required. A values addition or a policy tweak lands immediately.

Changes to workflow skills (in .claude/skills/) take effect the next time an agent enters the relevant phase. A change to spec-checklist applies when Spec begins its next feature; the running session is unaffected.

Changes to .devcontainer/ require a container rebuild. This is intentional: the container defines the reproducible environment that makes agent behavior portable across machines. Rebuilding is the cost of changing that environment.

The gradient is deliberate. Configuration that should change frequently — practices, policies — is low-friction to update. Configuration that should stay stable — the container environment, the pipeline shape — is higher-friction to change.

What to customize and what to leave alone

Start with the direction layer. The defaults that moot init installs are calibrated for generic software-development teams. Make the mission yours: one sentence, specific to what you are building and why. Adjust the vision to match your actual timeline. Review the values and add or remove entries for trade-offs your project actually faces.

If the defaults don’t fit, adjust the policies next. A project with a high-stakes production surface may want stricter confirmation rules before destructive operations. A project in early exploration may want looser ones.

The constitution and topology are load-bearing. Leave them alone until you understand the whole system — how the pipeline flows, why each resource has a single owner, what happens when a message goes to the wrong channel. Changing them without that understanding tends to produce subtle failures that are hard to trace back to the root cause.

Workflow skills are designed to evolve. The retro cycle that runs after each feature is intended to surface refinements — cases where a skill file didn’t match the situation, or sent agents in the wrong direction. Editing a skill in response to a retro observation is exactly the intended use. If your team runs a feature type that the bundled skills don’t cover, you can add a new skill file and agents will load it automatically.

For how to make these edits and what tools are available, see Customize Agent Roles.

A worked example

Your team is building a user import feature. The spec is drafted — correct API surface, correct schema, correct test coverage. But there is a subtlety: the import endpoint accepts arbitrary email addresses, and the normalized-email path downstream doesn’t handle edge cases from certain international mail providers.

If the values layer says nothing about validation boundaries, the Implementation agent treats “correct per spec” as done. The spec didn’t flag it, so it’s out of scope.

If the values layer includes something like “correctness over cleverness — when in doubt, prefer the explicit check,” the agent notices the gap and flags it. The oversight becomes an explicit finding rather than a silent assumption. The team decides whether to close it now or track it for later. Either way, it is a visible choice — not something that fell through.

The example is not primarily about catching bugs. It is about the difference between an agent that knows “this team takes validation boundaries seriously” and one that doesn’t. That knowledge comes from the values layer, not from the code or the spec. A values layer that doesn’t address your project’s actual trade-offs doesn’t provide that guidance, regardless of how technically correct the rest of the configuration is.

This is why the direction layer matters to get right early, and why it is worth reading the defaults critically rather than leaving them as installed. The defaults are a starting point. Your project’s specifics are what make the configuration useful.