jeikeilim/tenet/tenet

Tenet Skill

Execute Tenet as a checkpoint-driven autonomous development loop. This file is the router and invariant layer. Phase files contain the detailed procedures.

Index Contract

This SKILL.md is an index, not the full procedure. Before doing work for any phase, you MUST:

1. Read the exact phase file named in the Phase Map.
2. Follow that file's procedure, paths, formats, and gates.
3. Keep the phase file open as the source of truth while executing the phase.

Do not execute a phase from memory or from this file's summary. Do not write phase artifacts until the corresponding phase file has been read in the current session. If the phase file cannot be read, stop and report which file is missing.

Authority Order

When instructions conflict, prefer them in this order:

1. MCP tool schema and tool return values.
2. The phase file for the phase being executed.
3. This top-level skill file.

Do not invent tool calls or runtime state. If a named Tenet MCP tool is missing, stop and report the MCP configuration problem.

Core Invariants

1. Every implementation job runs through Tenet MCP: tenet_continue -> tenet_compile_context -> tenet_start_job -> tenet_job_wait -> tenet_job_result.
2. Context is compiled per job with tenet_compile_context for the orchestrator's working context; do not substitute raw file dumps. This context is not forwarded to workers — the dispatch path builds each worker's own run context (spec/decomposition/harness inlined) automatically.
3. Generation and validation are separate contexts.
4. Eval is a hard blocking gate. A failed eval must be retried, remediated, or blocked before dependent work proceeds.
5. Harness enforcement applies in all modes.
6. Human-readable project memory lives under .tenet/; live runtime state lives in MCP SQLite under .tenet/.state/.
7. Status files are generated from MCP state. Do not manually edit .tenet/status/status.md or .tenet/status/job-queue.md to advance runtime.
8. Use server-side continuation; do not reconstruct job IDs or dependency state manually.
9. Wrong turns and failed attempts must remain visible to the active retry context.
10. Purpose alignment outranks narrow checkbox compliance.
11. Knowledge writes need confidence tags.
12. Never assume yolo mode. It only activates when the user explicitly says "yolo", "skip questions", "decide everything", "don't ask me questions", or equivalent.
13. Never commit live .tenet/.state/tenet.db, .tenet/.state/tenet.db-wal, or .tenet/.state/tenet.db-shm. If portable Tenet state should be tracked, run tenet db snapshot and commit .tenet/state-snapshot/tenet.db instead.
14. Durable project doctrine lives in .tenet/project/**; normal implementation jobs must not edit it.
15. New feature/run artifacts live under .tenet/runs/<run-slug>/. Legacy top-level artifact directories are compatibility lanes only.

Boot Sequence

Run this before mode selection or execution:

1. Call tenet_continue().
2. If no active Tenet state exists, call tenet_init(project_path=".").
3. Call tenet_health_check().
4. If health fails because the MCP server is unreachable, tell the user: "Tenet MCP server is not running. Run npx tenet init in the project root, then restart your agent." Do not self-start the server; host config manages MCP lifecycle.
5. Call tenet_get_status().
6. If either call returns update_available, tell the user the current version, latest version, and update_command. Do not auto-update during an active run; instruct the user to close the agent, install the update, run tenet init --upgrade, then restart.
7. Run the context bootstrap gate before mode selection:

• Required docs: .tenet/project/overview.md, .tenet/project/architecture.md, .tenet/project/product.md, .tenet/project/testing.md, .tenet/project/design.md.
• Pass when all required docs exist and are real (not empty placeholders or obvious templates). Do not judge "thin", "stale", or "needs improvement"; the gate is pass/fail only.
• If any required doc is a placeholder, classify the project:
• Brownfield (real implementation exists in the repo — non-trivial source outside .tenet/, agent config, and scaffolding): the gate fails. Read and execute phases/00-context-bootstrap.md to live-scan and synthesize doctrine. Stop normal work until the gate passes.
• Greenfield (no real implementation to scan yet): defer. Do NOT run the bootstrap synthesis and do NOT write status-style "greenfield/TBD" doctrine into project/. Leave the placeholders in place — initial project doctrine is authored from the interview output in phases/01-interview.md once the interview is done.

1. In the greenfield deferred state, proceed to mode selection and the interview. The bootstrap gate is satisfied post-interview once phases/01-interview.md § 11 has written real project/** doctrine from interview decisions.
2. Detect whether .git/ exists. Git behavior is defined in phases/05-execution-loop.md.
3. Probe Playwright MCP availability if possible. If unavailable, warn once. This is only non-blocking when the run-local harness/spec marks browser exploration optional, skipped with reason, or not applicable; required browser/visual Layer 2 cannot pass without it.
4. Mode-selection checkpoint. Once boot is otherwise complete, run the mode checkpoint (see Mode Selection below): recommend Full/Standard/Quick with a one-line rationale, have the user confirm or override, and record the selected mode + basis. This checkpoint opens the interview phase — it creates the run/transcript scaffold (phases/01-interview.md § 1) and records the decision in the transcript's ## Mode Selection block — so read phases/01-interview.md before running it. This is the gate between boot and phase work: until the mode is selected and recorded, do not begin phase work (no task diagnosis, no spec/decomposition, no questions beyond the mode checkpoint itself). The context-bootstrap code scan in step 7 is the only sanctioned source reading during boot.

Do not enter execution while health is bad.

Mode Selection

Mode selection (Full / Standard / Quick) is a required, user-facing checkpoint that runs once the boot sequence passes (including the context bootstrap gate). Do not infer the mode silently from the task's surface form, and never assert a mode retroactively to justify skipping ceremony — surface your recommendation and let the user confirm or override it.

Recommend a mode with a one-line rationale, then ask the user to confirm or change it (prefer an interactive prompt, per phases/01-interview.md § 6). Record the selected mode and a selection basis in the transcript's ## Mode Selection block before any phase work. Re-evaluate only at major scope changes.

• Full: new feature, greenfield work, unclear edges, major refactor, broad multi-module change. Full crystallization: full interview → spec/harness/readiness → decomposition.
• Standard: medium complexity, known architecture, moderate unknowns. Compact interview (3–5 questions), then spec/harness/readiness → decomposition.
• Quick: small isolated bug/config/content tweak with low ambiguity. A minimum interview — confirm scope and acceptance criteria; never zero questions (see phases/01-interview.md § 9 anti-skip) — then a compact spec/harness update or a trivial single-job DAG.

Every mode, Quick included, still: completes the boot sequence first, reads the phase file before entering any phase, writes the interview transcript, and runs the clarity + readiness gates. Quick is a shallower interview, not a license to skip the phase structure, the phase-file read, or the gates. If a task looks obvious enough to "just fix," that is exactly when the procedure must still govern — apparent clarity is not a skip signal.

In YOLO mode (phases/01-interview.md § 7), the agent selects and records the mode autonomously with Selection basis: yolo_agent_decision and no interactive prompt; it still records the ## Mode Selection block.

At the end of the interview, two mode-like decisions are captured (see phases/01-interview.md § 3 for the full procedure):

• delivery_mode (autonomous | agile) — Full mode only. Copied to spec front matter.
• model_tier (frontier | local) — all modes (Full, Standard, Quick). Advisory; stays in the transcript, consumed once by decomposition. Default frontier.

Phase Map

Read the relevant phase file before executing that phase. The phrase "read" means opening the file contents in the current session, not assuming prior knowledge.

1. Context bootstrap: phases/00-context-bootstrap.md
2. Interview and clarity gate: phases/01-interview.md
3. Pre-spec research, spec, harness, readiness gate: phases/02-spec-and-harness.md
4. Visual artifacts and prototypes: phases/03-visuals.md
5. DAG decomposition and job registration: phases/04-decomposition.md
6. Autonomous execution loop, run-completion doctrine drift review, report-only blocking findings, finding dispatch, and git behavior: phases/05-execution-loop.md
7. Evaluation pipeline and failure handling: phases/06-evaluation.md
8. Agile checkpoints and redirects: phases/07-agile-checkpoints.md

Autonomous Full mode normally follows interview -> visuals -> scenarios -> research/spec/harness/readiness -> decomposition -> execution.

Agile Full mode follows interview -> research/spec/harness -> visuals -> initial plan-checkpoint -> readiness -> per-slice decomposition/execution/use-checkpoint. phases/07-agile-checkpoints.md owns checkpoint and redirect behavior.

Phase Entry Rule

At every phase boundary:

1. Identify the next phase by name.
2. Read its phase file from the Phase Map.
3. Execute only that phase's documented steps.
4. When moving to a new phase, read the new phase file first.

Examples:

• Before asking interview questions, read phases/01-interview.md.
• Before writing spec, harness, or scenarios, read phases/02-spec-and-harness.md.
• Before generating visuals, read phases/03-visuals.md.
• Before registering jobs, read phases/04-decomposition.md.
• Before dispatching jobs, read phases/05-execution-loop.md.
• Before acting on eval results, read phases/06-evaluation.md.
• Before agile plan/use checkpoints or redirects, read phases/07-agile-checkpoints.md.

Gates

• Clarity gate: after interview, call tenet_validate_clarity() and wait for the validation job result. Do not self-score.
• Readiness gate: after spec/harness/scenarios and required visuals, call tenet_validate_readiness with exact artifact_paths and resolve blockers before decomposition.
• Plan/use checkpoints: in agile mode, block until the user responds with approve, redirect: ..., cancel, or done as defined in phases/07-agile-checkpoints.md.
• Pre-execution gate: before dispatching a DAG or slice DAG, summarize mode, job count, key spec decisions, and harness constraints. Ask for confirmation unless the user explicitly asked to start without oversight.
• Eval gate: after every completed job, call tenet_start_eval(...) and wait according to the returned execution_mode. The critic set comes from .tenet/critics.json (3 built-in by default; the project may disable any and add custom critics — global at .tenet/critics/*.md and run-scoped at .tenet/runs/<run-slug>/critics/*.md from the Critic Tailoring step). All returned eval jobs must pass.
• To add a repo-specific critic (security, a11y, API contract, etc.) by hand, follow critics.md (the critic designer) — it produces the roster entry + prompt file so you don't hand-write prompts. To tailor critics to a feature's risks automatically during a run, the spec phase runs Critic Tailoring (phases/02-spec-and-harness.md § 4.5); the run-end lifecycle prunes or promotes them (same section, Run-end critic lifecycle).

Execution Rules