Let an agent change your backend

Tenchi's development workflow gives people and agents deterministic inspection, previewable generation, structured checks, and historical verification. An MCP-aware agent can access those operations directly through the Tenchi MCP server; an agent with filesystem and shell access can use the equivalent CLI workflow.

You remain in control because contracts, use cases, ports, and composition stay in ordinary Python files. The agent inspects evidence, edits those files directly, and runs the same checks you use locally and in CI.

Give an agent a Tenchi task

Generated applications include an AGENTS.md, so most agents will discover the local rules automatically. For an explicit first instruction, adapt this prompt:

Read AGENTS.md before editing. Run `uv run tenchi map` for the affected feature
and inspect its diagnostics and unresolved references. Explain the intended
files and relationships before changing them. Preview any generated structure
with the applicable command:
`uv run tenchi make feature <name> --dry-run --json`
`uv run tenchi make use-case <feature> <name> --dry-run --json`
Implement the change without hiding explicit wiring, then run
`uv run tenchi check`.
If a contract changed, run the OpenAPI compatibility diff before updating its
snapshot. If a durable job changed, run the job compatibility diff before
updating `jobs.json`. If an application tool changed, run the tool
compatibility diff before updating `tools.json`. If an evaluation policy
changed, run the evaluation compatibility diff before updating
`evaluations.json`.
When generated structure needs its own completion evidence, create a change
plan with `--plan` and retain its reported `plan_id`. Finish with
`uv run tenchi verify --base-ref <historical-ref> --json`, adding
`--change-plan <path>` if a plan was created. Use that plan's baseline commit
when present, and report the receipt with the files changed. Review behavior
and test assertions against the requirement. Do not weaken `tenchi.toml` to
make a failing requirement disappear.

If you already know the feature, include its name in the task so the agent can start with uv run tenchi map --feature <name> --json instead of loading the complete application graph.

What Tenchi provides

A passing receipt establishes the evidence it reports; it does not establish business correctness or the quality of assertions.

Tenchi's documentation is also published as /llms.txt for compact navigation and /llms-full.txt for the complete guide.

Use the recommended working loop

1. Read the local rules

Start with the generated AGENTS.md. It describes the application's file layout, allowed dependency direction, explicit composition points, error and authorization conventions, and the commands that define done.

Tell the agent to follow those repository instructions ahead of generic framework advice; your application may add stricter local conventions.

2. Map before reading broadly

uv run tenchi map --json
uv run tenchi map --feature notes --json
uv run tenchi map --feature notes \
  --kind contract,route,use-case,policy,port,adapter --json

The complete map combines source declarations with composed API routes, operational tasks, background jobs, application tools, and evaluations. A feature projection retains directly connected shared and cross-feature nodes, giving an agent a bounded starting context without hiding dependencies that cross the feature directory.

Inspect these fields before editing:

• nodes identify concepts and their source declarations. Runtime-bound kinds such as contracts, routes, jobs, tasks, tools, evaluations, use cases, and adapters become registered when composition reaches them; source-only declarations remain declared.
• edges explain ownership, route bindings, dependencies, authorization, implementations, and feature tests. Evidence points to the source that supports each relationship.
• confidence is exact when the relationship is directly proven and inferred when it follows a documented naming convention.
• diagnostics embeds the current doctor findings.
• unresolved records relationships the analyzer could not prove. Treat these as missing context, not as permission to assume the dependency is absent.

Node IDs, result keys, and diagnostic codes are stable within the declared schema_version. If your tooling parses the JSON directly, check that version before relying on the rest of the result. Additive fields may appear within the same version. When you encounter an unsupported version, update the integration before interpreting its results. See upgrade guidance for the versioned public surfaces.

3. Preview generated structure

uv run tenchi make feature notes --dry-run --json
uv run tenchi make use-case notes create_note --dry-run --json
uv run tenchi make use-case notes create_note \
  --from-contract app.features.notes.contracts:create_note_contract \
  --dry-run --json

Dry runs perform the same naming and conflict validation as a real generation without writing files. The result lists every planned path and the explicit wiring steps that remain app-owned.

Select optional modules per feature, for example tenchi make feature invoices --with jobs --with tools --dry-run --json. Existing server modules do not opt a new feature into those capabilities. To add application tools, preview tenchi make capability tools --dry-run --json. After generation, complete its feature bindings, server composition, manifest review, and verification-policy steps. Existing files are never overwritten.

When a contract exists, prefer --from-contract. The preview derives the boundary parameters and return type from the loaded declaration, so an agent does not have to transcribe the contract into a second signature. It also rejects declarations that cannot be bound as routes or represented in OpenAPI. After generation, # tenchi: incomplete markers and the generated failing test keep check red until the agent implements and tests the behavior. Remove the markers only when their placeholders have been replaced.

After accepting the preview, run the command without --dry-run. Generators create files but do not rewrite route or infrastructure modules. The agent must make those composition changes in the application files, where you can review them.

When the requested structure itself should be verified, create the files and plan together:

uv run tenchi make use-case notes create_note \
  --from-contract app.features.notes.contracts:create_note_contract \
  --plan .tenchi/changes/create-note.json \
  --base-ref origin/main --json

Retain the returned plan_id outside the edited worktree, such as in the task or orchestrator state. The final receipt reports the ID it verified. See verify a generated change for the exact completion conditions and the limits of this proof.

4. Edit through the application boundaries

Follow the application architecture rather than placing code where it is merely convenient:

• Contracts own the HTTP boundary.
• Plain async use cases own behavior.
• Pure policies own authorization decisions.
• Feature-owned protocols define infrastructure needs.
• Adapters implement those ports under app/infra/.
• Server modules explicitly compose routes, contexts, hooks, and concrete adapters.

If the graph and the task disagree, inspect the source evidence and unresolved references before expanding the edit. tenchi map is an orientation tool, not a substitute for reading the definitions that will change.

5. Validate once, completely

uv run tenchi check --json

Check runs every step even after one fails, so you receive a complete repair list in one pass. Each step reports its command, exit code, duration, bounded standard output and error output, and whether either stream was truncated.

Treat ok: false as unfinished work. Do not stop after fixing only the first failed step, and do not silently weaken Ruff, Pyright, pytest, doctor, or the OpenAPI, job-message, application-tool, or evaluation-policy snapshots to make the aggregate pass.

6. Compare boundary changes historically

For a contract change, compare before replacing the snapshot:

uv run tenchi openapi --diff openapi.json

uv run tenchi openapi --diff-ref origin/main --snapshot openapi.json

Breaking and unknown changes fail closed. A baseline from the merge base, previous push, or previous release remains meaningful even when the branch also updates its committed snapshot. See OpenAPI and compatibility for the complete workflow.

For an application-tool change, use the parallel workflow:

uv run tenchi tools --diff tools.json
uv run tenchi tools \
  --diff-ref origin/main \
  --snapshot tools.json

This catches removed tools, narrower inputs, wider outputs, newly possible application errors, and less-safe annotations before an agent replaces the snapshot. See Application tools for the complete compatibility rules.

For an evaluation-policy change, compare the manifest too; it contains no case inputs:

uv run tenchi eval snapshot --diff evaluations.json
uv run tenchi eval snapshot \
  --diff-ref origin/main \
  --snapshot evaluations.json

This catches removed cases or metrics, lower thresholds, larger budgets or timeouts, reordered cases, and deterministic-to-model changes without running providers or exposing case inputs. A missing historical snapshot is an error; only a human-authorized first adoption should add --allow-missing-baseline, and the result must record an evaluation manifest baseline metadata change. See AI evaluations for the complete workflow.

For durable background messages, compare the job manifest before accepting its snapshot:

uv run tenchi jobs --diff jobs.json
uv run tenchi jobs --diff-ref origin/main --snapshot jobs.json
uv run tenchi jobs --write jobs.json

Removing a job or narrowing the payloads its consumer accepts is breaking even if the current producer no longer emits the old shape; stored messages may still use it.

7. Produce the completion receipt

After reviewing and accepting any snapshot updates, verify the finished tree against the same historical point. When using a change plan, first set PLAN_BASE_SHA to its recorded baseline.commit; the original ref may have moved. Choose the corresponding command:

uv run tenchi verify --base-ref origin/main --json
uv run tenchi verify --base-ref "$PLAN_BASE_SHA" \
  --change-plan .tenchi/changes/create-note.json --json

See verifying a generated change for the complete plan workflow.

The receipt contains the resolved commit, current and historical tenchi.toml requirements, complete check result, application summary, diagnostics, unresolved relationships, and evidence for OpenAPI, jobs, tools, and evaluations. It distinguishes passed, failed, skipped, not configured, and not verifiable stages. It passes only when the policy was not weakened, every enforced requirement passes, and the map has no diagnostics or unresolved relationships. Required compatibility stages reject breaking and unknown changes; optional boundaries can be not configured or explicitly skipped according to the current and historical policy.

The source field identifies the exact application tree with its current HEAD, SHA-256 digest, and clean-or-dirty state. Tenchi includes tracked and nonignored untracked paths below the application root, then rechecks the identity after each application-owned stage. If an agent, test, import, or concurrent process leaves that tree changed at a verification checkpoint, the receipt fails and must be rerun after the edits stop. Git environment variables cannot redirect capture to another checkout. Ignored runtime artifacts stay outside the identity.

When a change plan is supplied, the receipt additionally requires the planned files, removed incomplete markers, exact registered contract and use case, the accepted contract-derived signature, exact route bindings, and a direct dependency from the exact generated test function. Keep that function's name when replacing its failing body, retain its direct imported use-case binding, and avoid decorators that replace the function. The plan also requires the callable pytest collects to match that source definition, then requires at least one invocation whose setup, call, and teardown all pass; skipped, xfailed, xpassed, deselected, failed, errored, uncollected, or ambiguous results fail the receipt. It also requires the plan's baseline commit to match the verification baseline.

If an agent disables or removes a required stage in tenchi.toml, Tenchi retains the historical requirement for that run and reports the policy change as incompatible. The agent therefore cannot make a difficult check disappear in the same change that weakens the policy. Without a policy file, Tenchi's built-in policy requires check, architecture, and OpenAPI plus each optional boundary whose composition module exists; generated applications commit the policy so the repository owns its definition of done.

verify complements the diff-before-write review by comparing the configured boundaries of the finished tree, including accepted snapshot updates, with historical contracts. Use the pull request base, previous push, or previous release instead of the branch's current commit.

Choose JSON or human output

Use --json with map, routes, doctor, make, check, and verify. Compatibility comparisons use --diff-format json, including OpenAPI, jobs, tools, and evaluation snapshots:

uv run tenchi map --json
uv run tenchi openapi --diff openapi.json --diff-format json
uv run tenchi jobs --diff jobs.json --diff-format json
uv run tenchi tools --diff tools.json --diff-format json
uv run tenchi eval snapshot --diff evaluations.json --diff-format json
uv run tenchi verify --base-ref origin/main --json

These modes write one versioned object to stdout, including on expected failures. Parse the command's result schema; failures before a normal result exists use operation_error with a stable code. Human and JSON modes describe the same operation: use JSON when another tool will make a decision and human output when a person is reviewing in a terminal. The CLI reference describes the commands and their results.

Failed check steps include bounded output from the project's validation commands, and verification includes the same output. Review it before sharing reports: Tenchi does not remove sensitive values printed by tests or scripts.

Know when to inspect the source yourself

The application map is source-backed and conservative. Python permits dynamic imports, factories, decorators, and runtime mutation that static analysis may not be able to prove. Tenchi reports unresolved relationships rather than inventing certainty, and inferred edges remain visibly different from exact ones.

The map also does not prove business correctness. An agent still needs to read the relevant contract, use case, policy, port, and tests, then rely on the full validation loop.

A change plan narrows that limitation but does not remove it. It proves that the requested generated structure was completed and connected, and reports planned-test execution from the project pytest process. Because project-owned plugins and test code share that process, the result is not independent of the repository's own code. It also cannot prove that the implementation satisfies the product requirement or that its test assertions are meaningful. Use externally owned hidden acceptance tests when the code producer itself is outside the trust boundary.

Model evaluation execution is intentionally outside check and verify. Those commands still check and compare the declared policy. Let an agent inspect suites with eval list and evaluation_diff, but authorize eval run separately because it may send application-owned case data to external providers and incur cost. The agent MCP server follows the same rule: evaluation_list is available by default, while evaluation_run requires --allow-evaluation-runs.

Continue with the agent MCP guide to connect a client, the CLI reference for every command option, or stability and releases for the compatibility guarantees around these result schemas.