Skip to content

JeiKeiLim/tenet

BranchesTags

Repository files navigation

Tenet

Talk. Establish. Nonstop. Evaluate. Tenet.

Cross-platform AI agent plugin for 12+ hour autonomous development cycles.

tenet — a principle held to be true. Also a palindrome: it reads the same forward and backward, just like the process. Talk through what you want. Establish the spec and plan. Nonstop execution through the DAG. Evaluate every line with independent critics. Each cycle produces a tenet — a verified feature that feeds the next cycle.

You: "Add social features — reactions, badges, user profiles, share cards"
Tenet: interviews you, writes the spec, generates visual mockups,
       decomposes into a dependency graph, implements each job,
       asks workers to commit per job, evaluates with 3 independent critics,
       and loops for 6+ hours until everything passes.

Why Tenet?

AI coding agents are powerful but short-lived. They lose context, drift off-spec, skip tests, and can't sustain multi-hour development sessions. Tenet solves this:

  • Structured phases — Brownfield scan, Interview, Spec, Visuals, Decomposition, Execution, Evaluation, and Agile checkpoints. No required phase is skippable.
  • DAG-based job orchestration — Dependencies are explicit. Parallel jobs run in parallel. Blocked jobs wait.
  • 3-critic evaluation pipeline — Code critic, Test critic, and Playwright e2e eval. All independent, all with fresh context (no author bias). All findings are blocking.
  • Crash recovery — Server-ID-based orphan detection. If the MCP server dies, jobs auto-retry on restart.
  • Agent-agnostic — Works with Claude Code, OpenCode, and Codex. Switch agents mid-project without losing state.
  • Persistent state — Versioned SQLite + WAL mode. Jobs, events, steer messages, and config survive crashes.

Built With Tenet

See Built With Tenet for real projects produced while testing Tenet, including their .tenet/ artifacts, critic feedback, retry trails, and validation notes.

Quick Start

# Install globally
npm install -g @jeikeilim/tenet

# Initialize a project
cd your-project
tenet init

# That's it. Start your coding agent and invoke the tenet skill:
# In Claude Code: /tenet "Add user authentication with OAuth"
# In Codex: use the tenet skill

One-liner (skip interactive prompts)

npx @jeikeilim/tenet init --agent claude-code --skip-playwright-check

How It Works

The 8 Phases

Phase What Happens
0. Brownfield Scan Detects existing code, frameworks, and prior tenet work
1. Interview Agent asks clarifying questions, researches technologies
2. Spec & Harness Writes formal spec with scenarios + quality contract
3. Visuals Generates architecture diagrams, UI mockups, DESIGN.md
4. Decomposition Breaks spec into a dependency graph (DAG) of jobs
5. Execution Loop Implements each job, prompts per-job commits, evaluates, retries on failure
6. Evaluation 3 independent critics: code, tests, and Playwright e2e
7. Agile Checkpoints Handles plan/use checkpoints and redirect loops in agile mode

The Evaluation Pipeline

Every completed job faces three independent critics, each with fresh context and no access to the author's reasoning:

Job Complete
    |
    +---> Code Critic    (spec alignment, security, edge cases)
    +---> Test Critic     (oracle problem detection, behavioral coverage)
    +---> Playwright Eval (scripted tests + agent-driven exploratory e2e)
    |
    ALL must pass --> Next job
    ANY fails     --> Retry with failure context

The Oracle Problem: Research shows AI-written tests have ~6% precision when the same agent writes both code and tests. Tenet's test critic explicitly checks for oracle leakage — tests that verify implementation behavior rather than intended behavior.

Steer Messages

Redirect the agent mid-run without breaking the loop:

You: "Focus on the API first, skip the frontend for now"
Tenet: classifies as directive, adjusts job priority, continues

Three classes: context (informational), directive (priority change), emergency (halt everything).

Architecture

                    +-----------------+
                    |  Coding Agent   |  (Claude Code / OpenCode / Codex)
                    |  + Tenet Skill  |
                    +--------+--------+
                             |
                         MCP Protocol
                             |
                    +--------v--------+
                    |   MCP Server    |  18 tools (start_job, eval, steer, etc.)
                    +--------+--------+
                             |
              +--------------+--------------+
              |              |              |
     +--------v---+  +------v------+  +----v--------+
     | Job Manager|  | State Store |  | Adapters    |
     | (DAG, retry|  | (SQLite+WAL)|  | (subprocess)|
     | heartbeat) |  |             |  |             |
     +------------+  +-------------+  +-------------+
                                       claude --print
                                       opencode run
                                       codex exec --sandbox workspace-write

Four layers:

  1. Core — Job orchestration with DAG execution, heartbeat stall detection, configurable retry logic, and server-ID crash recovery
  2. Adapters — Pluggable agent adapters that spawn CLI subprocesses. 120-minute default timeout, configurable.
  3. MCP Server — 18 tools via @modelcontextprotocol/server. Zod-validated inputs.
  4. CLI — init, serve, status, config commands. Scaffolds .tenet/, copies skills to agent-specific locations, and runs explicit DB upgrades.

CLI Reference

# Initialize project (interactive agent selection + optional Playwright MCP install)
tenet init [path]
tenet init --agent claude-code --skip-playwright-check
tenet init --upgrade  # Update DB, skills/configs, preserve your docs

# Start MCP server
tenet serve
tenet serve --background

# Check project status
tenet status
tenet status --all  # Include completed/failed jobs

# Configure
tenet config                          # View current config
tenet config --agent claude-code      # Set default agent
tenet config --max-retries unlimited  # Default: no fixed retry cap
tenet config --max-retries 5          # Optional finite retry limit
tenet config --timeout 120            # Set job timeout (minutes)

MCP Tools

Tool Purpose
tenet_init Initialize a project from MCP
tenet_compile_context Gather spec, harness, status, and knowledge into a single context
tenet_validate_clarity Score the interview transcript before spec generation
tenet_validate_readiness Score implementation readiness before decomposition
tenet_register_jobs Load a job DAG with dependencies
tenet_start_job Execute a single job via agent adapter
tenet_continue Get the next actionable job from the DAG
tenet_job_wait Check or long-poll job status
tenet_job_result Retrieve job output and status
tenet_retry_job Reset a failed/completed job to pending
tenet_cancel_job Cancel a running or pending job
tenet_start_eval Dispatch code critic + test critic + playwright eval
tenet_report_blocking_finding Let report-only jobs pause and spawn a linked follow-up job
tenet_update_knowledge Write knowledge/journal entries
tenet_add_steer Submit a steer message (context/directive/emergency)
tenet_process_steer Acknowledge and act on steer messages
tenet_health_check Verify system consistency
tenet_get_status Get current job counts and progress

Project Structure

After tenet init, your project gets:

your-project/
  .tenet/
    interview/      # Interview transcripts (dated per feature)
    spec/           # Formal specifications
    harness/        # Quality contracts (linting, testing, architecture rules)
    status/         # Auto-generated status files
    knowledge/      # Reusable technical knowledge
    journal/        # Dev activity logs
    steer/          # Steer message inbox/processed
    visuals/        # Architecture diagrams, UI mockups
    bootstrap/      # Compiler/build configuration
    .state/
      tenet.db      # Versioned SQLite state (jobs, events, steer, config)
      config.json   # Project configuration
  .mcp.json         # Claude Code MCP server configuration (auto-generated)
  .codex/config.toml # Codex MCP server configuration and project trust
  opencode.json     # OpenCode MCP server configuration and permissions
  .claude/skills/tenet/  # Generated skill files for Claude Code, with Tenet version metadata
  .agents/skills/tenet/  # Generated skill files for Codex, with Tenet version metadata

Execution Modes

Mode Phases Use Case
Full (default) All 8 phases New features, major refactors
Standard Skip interview (use existing spec) Spec already written
Quick Skip interview + spec + decomposition Bug fixes, small changes

Crash Recovery

Tenet is designed for long autonomous runs where crashes are expected:

  • Server restart: Stale "running" jobs are reset to "pending" only after their heartbeat exceeds the timeout
  • Adapter timeout: 120-minute default (configurable), prevents zombie subprocesses
  • Heartbeat monitoring: Detects truly stuck jobs within a session
  • MCP disconnect: Skill instructs agents to attempt server restart, halt if unrecoverable
  • Update checks: Health/status can surface newer npm versions with manual upgrade guidance; Tenet does not auto-update during an active run
  • DB upgrades: Normal startup refuses old/newer DB schemas with guidance. Close the agent, run tenet init --upgrade, then restart; upgrade backs up .tenet/.state/tenet.db first.

Diagnostics

When things go wrong, use the tenet:diagnose skill:

# Or manually inspect:
sqlite3 .tenet/.state/tenet.db "SELECT type, status, COUNT(*) FROM jobs GROUP BY type, status"
sqlite3 .tenet/.state/tenet.db "SELECT * FROM jobs WHERE status='failed'"

The diagnose skill provides 10 diagnostic sections with ready-to-run queries for job status, event logs, config, git-DB desync detection, and more.

Agent Compatibility

Agent Status Notes
Claude Code Fully supported Primary development target
OpenCode Supported Skill and MCP discovery via opencode.json
Codex Supported --sandbox workspace-write by default, .codex/config.toml for MCP

Requirements

  • Node.js >= 20
  • At least one AI coding agent CLI installed (claude, opencode, or codex)
  • Optional: Playwright MCP for browser/visual e2e testing (tenet init offers to install it and writes each supported agent config)

Development

git clone https://github.com/JeiKeiLim/tenet
cd tenet
pnpm install
pnpm run build
pnpm run test
pnpm run lint

Doc/Code Consistency Review

This repository includes a maintainer-only AI review script that checks current Markdown docs against code-derived facts such as MCP tool names, CLI options, adapter defaults, and runtime defaults. It is not shipped in the npm package and it does not apply fixes. When multiple reviewers are used, their raw findings are preserved and a final synthesizer groups duplicate or overlapping findings into merged issues.

Run the normal review with Claude:

make docs-review

Pass custom review arguments through DOCS_REVIEW_ARGS:

# Use a different reviewer
DOCS_REVIEW_ARGS="--agents codex" make docs-review
DOCS_REVIEW_ARGS="--agents opencode" make docs-review

# Use combinations
DOCS_REVIEW_ARGS="--agents claude,codex" make docs-review
DOCS_REVIEW_ARGS="--agents claude,codex,opencode" make docs-review

# Control the final merge/synthesis pass
DOCS_REVIEW_ARGS="--agents claude,codex --synthesizer claude" make docs-review
DOCS_REVIEW_ARGS="--agents claude,codex --synthesizer none" make docs-review

# Save cognition-alignment JSON and keep printing Markdown
DOCS_REVIEW_ARGS="--json-out /tmp/tenet-doc-review.json" make docs-review

# Save both outputs
DOCS_REVIEW_ARGS="--json-out /tmp/tenet-doc-review.json --markdown-out /tmp/tenet-doc-review.md" make docs-review

# Save Markdown without printing it
DOCS_REVIEW_ARGS="--markdown-out /tmp/tenet-doc-review.md --no-print" make docs-review

Run the real-agent E2E smoke test with Claude + Codex by default:

make docs-review-e2e

Customize E2E reviewers and the final synthesizer:

DOCS_REVIEW_E2E_AGENTS=codex make docs-review-e2e
DOCS_REVIEW_E2E_AGENTS=opencode make docs-review-e2e
DOCS_REVIEW_E2E_AGENTS=claude,opencode make docs-review-e2e
DOCS_REVIEW_E2E_AGENTS=claude,codex,opencode make docs-review-e2e
DOCS_REVIEW_E2E_SYNTHESIZER=codex make docs-review-e2e
DOCS_REVIEW_E2E_SYNTHESIZER=none make docs-review-e2e

The E2E always runs with --fail-on never and only verifies real subprocess plumbing, JSON shape, Markdown output, reviewer metadata, merged issue metadata, and that repo-tracked files did not change. It writes reports to a temp directory by default. To choose an output directory, use a path outside the repository:

DOCS_REVIEW_E2E_OUTPUT_DIR=/tmp/tenet-doc-review-e2e make docs-review-e2e
DOCS_REVIEW_E2E_PRINT_MARKDOWN=1 make docs-review-e2e

License

MIT

About

Cross-platform AI agent harness for 12+ hour autonomous development cycles. Spec-driven, DAG-orchestrated, with a 3-critic evaluation pipeline. Works with Claude Code, OpenCode, and Codex.

Topics

opencode harness codex claude ai-agent ai-driven-development spec-driven-development harness-engineering

Resources

Readme
Activity

Stars

40 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 9

v26.5.6 Latest
May 19, 2026
+ 8 releases

Packages

 
 
 

Contributors

Languages