tanren

Turn a product idea into enterprise-ready software, with proof at every step.

Tanren is a product-to-proof control plane for agentic software delivery. It is the framework around coding agents that preserves product intent, accepted behaviors, roadmap order, workflow state, execution boundaries, source signals, and behavior proof. Agent runtimes such as Codex, Claude Code, or OpenCode decide how an assigned role reasons and edits. Tanren decides what work exists, why it exists, what may run next, and what proof is required before the work counts as complete.

Enterprise-ready primarily means production-grade engineering discipline: accepted behavior contracts, executable behavior proof, standards, CI, auditability, typed workflow state, isolated execution, and repeatable delivery.

The long-term goal is a continuous chain from product idea to shipped, proven behavior:

product brief
-> accepted behavior catalog
-> roadmap DAG
-> shaped specs
-> orchestrated implementation
-> behavior proof and human walk
-> PR, review, merge, ship
-> feedback, bug triage, and proactive analysis
-> updated product plan

This makes autonomous coding governable. Every increment should be traceable to accepted product behavior, every asserted behavior should have executable behavior proof, and every roadmap milestone should explain what user, operator, client, or runtime-actor outcomes are now complete.

For the accepted product brief, read docs/product/vision.md.

Quick Start

git clone https://github.com/trevorWieland/tanren.git
cd tanren
just bootstrap
just install
just ci

The canonical installed binaries are tanren-cli and tanren-mcp.

scripts/runtime/install-runtime.sh
scripts/runtime/verify-installed-runtime.sh
tanren-cli install --dry-run

Why Tanren Exists

Coding agents can produce changes quickly, but speed without durable product method creates drift. Tanren exists to prevent common failures:

• vague ideas become plausible code without accepted product intent;
• roadmaps become stale prose instead of dependency-aware executable plans;
• specs complete implementation tasks without completing user-visible behavior;
• tests prove implementation details but not accepted product outcomes;
• demos and reviews lack a clear behavior story;
• bugs, audit findings, benchmarks, and feedback become scattered interruptions;
• parallel agent work collides without explicit execution boundaries;
• autonomous loops either stop too often or run without typed events.

Tanren's answer is opinionated: product behavior is the unit of meaning, roadmap nodes must complete behavior, specs are shaped before execution, BDD behavior proof is the proof path, and agents mutate workflow state only through typed tools.

What Tanren Is Not

Tanren is not an agent runtime, model provider, editor, ticket tracker, CI system, or generic task runner. It integrates with those systems through adapters. The core responsibility stays the same across integrations: decide what work happens, preserve why it exists, enforce how it progresses, and keep proof and source references for what was proven.

Tanren is pluggable at the edges but not methodology-neutral. It should not care whether a team uses GitHub or another source-control provider, local subprocesses or remote VMs, one agent harness or another. It should care that work is behavior-backed, roadmap-ordered, spec-shaped, audited, walked, and proven.

What Tanren Empowers

In its complete form, Tanren should let a technical product builder or team answer, from durable state:

• what product is being built and for whom;
• which user problems and success signals justify the current roadmap;
• which behaviors are accepted, implemented, asserted, deprecated, or missing;
• what spec-sized work remains and why that order is correct;
• what is currently in flight, blocked, reviewed, or shipped;
• which behavior proof proves that a behavior exists;
• how bugs, audit findings, benchmarks, post-ship outcomes, and proactive analyses changed the plan;
• where active agent work is running and which harness, credentials, and environment boundaries apply.

That is the difference between "agents can write code" and "agents can help deliver enterprise-ready software whose intended behaviors are planned, implemented, validated, reviewed, shipped, and continuously improved."

Tanren Method

Tanren's method has four product-to-proof layers:

1. Plan product: establish the product brief, motivations, target users, constraints, success signals, and open product decisions.
2. Identify behaviors: turn product intent into a parsable catalog of accepted user, operator, client, and runtime-actor behaviors.
3. Craft roadmap: synthesize a machine-readable DAG of spec-sized nodes that complete accepted behaviors in dependency order. Human-readable roadmap documents are rendered views of that graph.
4. Execute specs: shape one roadmap node into a spec, orchestrate the task loop, run behavior proof, walk the result with a human, review, merge, and update behavior verification state.

Tanren also treats proactive project analysis as a first-class source of planning input. Scheduled standards sweeps, security audits, mutation-testing runs, post-ship health checks, and similar non-interactive analyses should produce findings or proposed planning changes that flow back into behaviors, roadmap nodes, and shaped specs rather than bypassing the product method.

Tanren also treats bug handling as a product-method funnel. A bug report should be triaged as a false alarm, missing behavior, misaligned behavior, insufficient behavior assertion, or regression against asserted behavior before follow-up work is planned.

The spec-orchestration loop is the execution layer, not the whole method. Without product intent there is no meaningful behavior catalog; without accepted behaviors there is no reliable roadmap; without a roadmap DAG there is no principled spec queue; without behavior proof and walks, completed specs do not prove product progress.

This repo currently has the real spec-loop commands installed and temporary project-method bootstrap commands for plan-product, identify-behaviors, architect-system, assess-implementation, and craft-roadmap. The project-method commands write owned planning projections for now; they are not yet native typed Tanren phases.

The first major product milestone is Tanren-in-Tanren: using Tanren to plan, shape, execute, prove, walk, and update Tanren itself, including harness and environment management for Codex, Claude Code, OpenCode, and container or remote execution targets.

How It Works

Tanren's runtime orchestration model has four layers:

1. Intent: a human or coordinator starts a spec, task, dispatch, or lifecycle action through CLI, MCP, API, or TUI.
2. Control plane: application services validate the request, apply policy, call the orchestrator, and persist typed events.
3. Execution: scheduler/runtime crates lease an environment and hand one phase to an agent harness.
4. State and proof: every meaningful state change becomes a typed event, while behavior proof and source references stay linked to the work.

flowchart TD
    U[User or coordinator] --> S[CLI / MCP / API / TUI]
    S --> A[tanren-app-services]
    A --> O[tanren-orchestrator]
    O --> P[tanren-policy]
    O --> G[tanren-planner]
    O --> Q[tanren-scheduler]
    Q --> R[tanren-runtime]
    R --> H[Agent harness]
    H --> T[Typed tool calls]
    T --> A
    A --> E[(Event store)]
    E --> V[Projected views and artifacts]
    V --> O

Loading

The core loop is intentionally narrow: agents write implementation and diagnostic output, while Tanren owns state. Agents do not directly edit orchestrator-owned artifacts such as plan.md, tasks.json, progress.json, or phase-events.jsonl; they call typed tools, and Tanren projects those files from durable events.

Orchestration State Machine

The spec loop starts with interactive shaping, runs autonomous task phases until every task is complete, then validates the whole spec before review and merge.

flowchart TD
    Shape[shape-spec] --> Setup[SETUP]
    Setup --> Pending{Pending task?}
    Pending -->|yes| Do[do-task]
    Do --> Gate[TASK_GATE]
    Gate --> Audit[audit-task]
    Gate --> Adhere[adhere-task]
    Audit --> Guards{All task guards pass?}
    Adhere --> Guards
    Gate --> Guards
    Guards -->|no| Investigate[investigate]
    Investigate --> Pending
    Guards -->|yes| Complete[TaskCompleted]
    Complete --> Pending
    Pending -->|no| SpecGate[SPEC_GATE]
    SpecGate --> Checks[run-demo + audit-spec + adhere-spec]
    Checks -->|pass| Walk[walk-spec]
    Checks -->|fix required| Investigate
    Walk -->|accept| PR[Create PR]
    Walk -->|reject| Pending
    PR --> Feedback[handle-feedback]
    Feedback -->|actionable| Pending
    Feedback -->|resolved| Merge[Merge + CLEANUP]

Loading

Each task advances through a guarded lifecycle:

stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress: TaskStarted
    InProgress --> Implemented: TaskImplemented
    Implemented --> Implemented: TaskGateChecked
    Implemented --> Implemented: TaskAudited
    Implemented --> Implemented: TaskAdherent
    Implemented --> Complete: all required guards
    Pending --> Abandoned: typed disposition
    InProgress --> Abandoned: typed disposition
    Implemented --> Abandoned: typed disposition
    Complete --> [*]

Loading

The full state-machine specification, including cross-spec flows and escalation rules, lives in docs/architecture/subsystems/orchestration.md.

Architecture

graph TD
    WEB[tanren-web] --> API[tanren-api]
    CLI[tanren-cli] --> API
    TUI[tanren-tui] --> API
    EXT[External clients] --> API
    AGENT[Agent clients] --> MCP[tanren-mcp]

    API --> APP[tanren-app-services]
    MCP --> APP
    APP --> DOMAIN[tanren-domain]
    APP --> CONTRACT[tanren-contract]
    APP --> STORE[tanren-store]
    STORE --> PG[(Postgres event log and projections)]

    DAEMON[tanren-daemon] --> APP
    PROJ[tanren-projection-worker] --> STORE
    PROVIDER[tanren-provider-worker] --> APP
    WEBHOOK[tanren-webhook-worker] --> APP
    NOTIFY[tanren-notification-worker] --> APP
    RUNTIME[tanren-runtime-worker] --> TARGET[Container or remote execution target]
    TARGET --> HARNESS[Codex / Claude Code / OpenCode adapters]
    PROVIDER --> SCM[Source control / CI / issue / VM providers]

Loading

Core crates:

• tanren-domain: typed IDs, commands, events, views, policy-neutral state
• tanren-contract: interface schemas and request/response contracts
• tanren-store: database migrations, event store, projections, and queues
• tanren-app-services: application workflows over domain/store/contract
• tanren-orchestrator: state transition and dispatch orchestration
• tanren-planner: task graph planning and replanning data model
• tanren-scheduler: dependency, lane, and capability-aware scheduling
• tanren-runtime*: execution contracts and environment substrates
• tanren-harness-*: agent-runtime adapters
• bin/*: CLI, MCP, API, daemon, and TUI entrypoints

The linking rule is deliberate: transport binaries call application services; application services call the orchestrator; the orchestrator coordinates policy, store, planner, scheduler, and runtime boundaries. This keeps direct store mutation out of CLI/API/MCP handlers and makes state transitions auditable.

Repository Structure

tanren/
├── bin/             # Rust binaries
├── crates/          # Rust libraries
├── xtask/           # repo automation and proof-support commands
├── commands/        # source command markdown rendered by the installer
├── profiles/        # standards profiles
├── protocol/        # protocol overview
├── docs/            # Tanren-owned product, behavior, architecture, implementation, roadmap projections
├── tests/bdd/       # behavior feature files
└── scripts/         # shell entrypoints

Development

• Setup: just bootstrap
• Static gate: just check
• Behavior proof: just tests
• Full PR gate: just ci
• Auto-fix: just fix

Rust CI runs just ci. Protected development branches are governed by the just ci status check.

Documentation

• docs/README.md - documentation index
• docs/product/vision.md - accepted product brief
• docs/behaviors/index.md - product behavior catalog
• tests/bdd/README.md - executable behavior proof rules
• docs/architecture/delivery.md - stack installation and delivery contract
• docs/architecture/system.md - architecture overview
• docs/architecture/subsystems/quality-controls.md - gates, audit, adherence, and quality controls

The roadmap (docs/roadmap/) and implementation readiness (docs/implementation/) docs were cleared as part of the architecture rewrite. They will be regenerated by commands/project/craft-roadmap.md against the pruned behavior catalog.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.