Your agent, leveled up

A raw coding agent jumps straight to code. Ask it for a feature and it starts typing — no research, no plan, no cleanup, no review gate. The moment a repository adopts Valinor, that changes: its agents inherit a disciplined, senior-engineer methodology automatically. They research before planning, plan before executing, fan out subagents and workflows, verify before asserting, document for every audience, clean up as they go, and ship through a strict pull-request gate — because the methodology is written into the repo and the repo's agents read it.

This is the part of Valinor you notice first. Valinor isn't only a set of checks bolted onto CI — it's a building methodology installed into every agent in the repo. This page tells that story: what your agent inherits, how it changes the way work gets built, and the bar each change is held to.

Two layers: how to build, and what gets enforced

Valinor governs a repo on two complementary layers, and it's easy to see only the second one.

• The agent doctrine — how to build. A portable methodology that teaches the agent the process of building: the conduct it holds, the lifecycle it moves work through, and the definition of "done" it aims for. This is the layer that levels your agent up, and it's the one this page is about.
• The code gates — what gets enforced. The deterministic gates, the LLM-review rubrics, and the standing audit that prove a change cleared the bar. This layer is covered in depth in the Governance overview.

The two reinforce each other: the doctrine tells the agent how a senior engineer would approach the work, and the gates independently verify the result. An agent that has internalized the doctrine rarely trips a gate, because it was already building to the standard the gate checks.

The conduct your agent inherits

The doctrine opens with a short list of standing conduct — the habits that shape essentially every turn an agent takes in a Valinor repo:

• Use subagents and workflows extensively — and concurrently. The orchestrating agent's attention is precious, so it dispatches single-purpose subagents (or runs a workflow) rather than doing everything inline, and it fans out independent work in parallel instead of serializing it. Research is read-only, so it's always parallelized.
• Be concise. Use the fewest words necessary; conserve attention and tokens.
• Don't leave debt behind. Fix the problem at its root now where you justifiably can; otherwise record the backlog item durably rather than letting it rot.
• DRY — one authoritative home per fact, with everything else pointing at it.
• YAGNI — the smallest solution that actually satisfies the requirement.
• Verify, don't assume.
• Codify your repo's own rules. Each repo declares its own hard-and-fast rules — and backs them with a process gate wherever it can.
• Keep the always-on surface minimal, so the doctrine stays a sharp set of rules rather than a wall of text the agent skims past.
• Enforce with gates — process gates over memory. Where a rule can be checked mechanically, a gate checks it; the agent never relies on memory alone to stay honest.

Read together, these are the instincts of a careful senior engineer, made explicit so every agent in the repo holds them — not just the ones that happen to have been prompted well.

The work lifecycle: a journey, not a leap

The heart of the methodology is the work lifecycle — the path every piece of work travels, from "what should we even do?" to "shipped and cleaned up." A raw agent collapses this whole journey into a single step (write the code). Valinor's agents move through it in order, and each phase lands its output somewhere durable.

1. Research before planning

A well-governed backlog is never truly empty — the next work is generated from signal the repo already carries rather than waited for. Before touching code, the agent explores the repo for relevant context: its code, its prose, its prior thinking-records, and any in-flight work (open pull requests and branches), so it doesn't duplicate, conflict with, or miss something already underway. It checks the research ledger before redoing prior work, and researches externally only for a genuine gap. When it selects a dependency, it resolves the version against the live registry — never from memory — and consciously decides whether to adopt a fresh major. Findings land in a dated research ledger under docs/research/.

2. Plan before executing

Settled research turns directly into an ordered build with verifiable criteria, and the evidence behind each design choice is recorded. The plan is checked against the Definition of DONE before any code is written — so "will this be functional, secure, tested, documented?" is answered up front, not discovered at review time. Plans land in docs/plans/ and carry their own lifecycle (active / completed / superseded).

3. Execute, and document for every audience

The agent builds under the plan — dispatching subagents or running a workflow rather than grinding through everything inline. Crucially, shipping the code is only half of "execute": the change also ships its documentation for every audience — the agents who'll maintain it, the developers who'll read it, the stakeholders who need the what-and-why, and the users who need to know what changed.

4. Verify before asserting

Before claiming anything is done, the agent re-checks the Definition of DONE and verifies checkable claims against reality — it runs the relevant gate rather than asserting from assumption. "It passes" is something proven, not something hoped.

5. Clean up as you go

Each process artifact is pruned once its successor lands — the research once the plan captures it, the plan once the work ships — with no escape valve, because each deliverable is written to fully obviate its predecessor. A pivotal why-this-architecture decision graduates to an architecture decision record. The product documentation is never pruned; the scaffolding of half-finished thinking is.

6. Ship through a strict PR gate

main is pull-request-only — the agent never pushes to it directly. It branches, pushes, opens a pull request, waits for CI to go green, and only then marks it ready for review. An independent LLM review is the backstop, and the merge bar is strict. The discipline that a human team enforces with branch protection, Valinor's agents hold by default.

The action surfaces: skills your agent reads and follows

The lifecycle isn't just prose for the agent to absorb — Valinor ships action skills, orchestrator-level procedures your agent reads and applies at the right phase. They're bundled inside the installed package and version-locked to your Valinor, and your agent discovers them rather than memorizing them.

• valinor-roadmapping — what to do next. The front of the lifecycle: when the explicit backlog is thin but the work plainly isn't done, this procedure generates the next-highest-value work from the repo's own structured signal (the research and plan ledgers, the honest "no gate yet" lines in the doctrine, governance owed to consumers, gaps in coverage), value-ranks the candidates, and feeds the result into research.
• valinor-planning — turn research into a build. The procedure for the Plan phase: ground a plan in research the repo already holds, trace every design choice to its evidence, author an ordered task list with checkable test-first completion criteria, and walk the Definition of DONE as a forward checklist.
• valinor-execution — run the plan. The toolkit for the Execute phase: for each phase, run it inline, dispatch a single-purpose subagent, or instantiate a named workflow pattern (fan-out-and-synthesize, adversarial-verification, and others) when a phase genuinely needs more compute.
• valinor-onboard — turn on the right capabilities. The agent-first counterpart to the human valinor onboard wizard: right after valinor init, this walks the opt-in capabilities (scaffolded at non-blocking defaults) and helps the agent decide, per the repo's context, which to enforce.

Your agent reaches these through self-describing catalogs rather than a memorized inventory — it discovers the available procedures and reads the one it needs (the CLI reference has the exact commands). And for capabilities beyond the lifecycle — a security review, an accessibility pass, a performance check — the doctrine sends the agent to find-skills to discover the right skill for the job, rather than naming a fixed chain that would go stale.

The Definition of DONE: the bar a change is held to

Underneath the conduct and the lifecycle sits the Definition of DONE — the through-line that defines what "finished" actually means. It's a multi-criterion bar the agent checks at three points: at Plan time ("will the change be all of these?"), at Verify time ("is it?"), and at the gates ("prove it"). It asks whether a change is, among other things:

• Functional and tested, built test-first against concrete criteria;
• Backwards-compatible or otherwise safe to deploy;
• Secure (the OWASP top-10) and dependency-healthy;
• Accessible (WCAG 2.1 AA) on every user-facing surface;
• Logged and measured where it matters, with privacy-preserving logging;
• Durably documented for every audience — agents, developers, stakeholders, and users;
• The smallest solution that satisfies the requirement (YAGNI), leaving no debt or rot behind.

Each criterion names not just the goal but how it's enforced — and where there's no automated gate yet, the doctrine says so honestly rather than implying coverage that doesn't exist. This is what makes the "leveled up" framing more than a slogan: the agent isn't just told to be careful, it's held to a written, checkable bar, and the code gates independently verify the result.

Why this matters

A raw agent is fast but undisciplined — it produces code without the surrounding rigor a senior engineer brings: the research that catches a duplicate effort, the plan that surfaces a design flaw early, the verification that turns "should work" into "does work," the cleanup that keeps the repo from rotting, and the review gate that catches what slipped through. Valinor installs that rigor into every agent in the repo, the moment it's adopted. Your agent doesn't become a senior engineer overnight — but it starts building the way one would, on every change, automatically.

Where to go next

• See exactly how each layer is enforced in the Governance overview.
• Adopt the doctrine and scaffold the gates in Installation.
• Reach the lifecycle procedures from your agent via the CLI reference.

For the full, canonical doctrine — the conduct, the lifecycle, and every Definition-of-DONE criterion — contributors can read AGENTS.md ≡ CLAUDE.md in the Valinor repository.