Auto

Auto

Auto is the front door when the user wants the repository to keep choosing and executing the next safe owner without repeated prompting.

Core Take

Auto is a supervisor, not a larger implementation skill. It compiles the run, records durable state, selects the next checkpoint from evidence, invokes the real owner, verifies the result, and continues until the auditable stop condition is true.

Before the first file mutation, capture a walkthrough diff baseline when UI or rendered output may change. Use .agents/skills/walkthrough/scripts/diff-baseline.mjs and record its path.

The loop is:

request -> run profile -> vision/source intake -> readiness
-> candidate owner -> execute -> proof -> state update -> next candidate
-> review -> repository gate -> GitHub delivery -> final audit

Do not score the entire run up front. Score only when more than one valid next checkpoint exists.

Modes

A bare feature plus full may use an existing local PRD when useful. If no PRD is required to make coherent decisions, Auto writes the decisions and packets in its goal plan instead of creating planning ceremony.

Front-Door Routing

Use orchestrator only when the user explicitly requests parallel child thread/branch work. Auto never invents parallel delegation or worktrees.

Run Profile Compiler

Before work, compile and record this profile in the goal plan:

Reject impossible combinations instead of silently weakening one. full cannot become planning-only because a PRD was created. clean cannot expand into a new feature. A timed run cannot spend its closeout reserve on new scope.

Goal Plan Contract

Use autogoal before durable Auto work. Create or resume a plan from the auto template with the agent-native pack and any relevant browser, design, docs, package-api, release, or to-prd pack.

The plan must contain:

• run profile and source inventory;
• completion threshold and explicit exclusions;
• state capsule;
• decision, assumption, claim, error-attempt, and packet ledgers;
• readiness and proof matrices;
• source/generated owner map;
• review, repository-check, and delivery gates;
• phase states and completion audit.

Checkpoints are receipts. Update the plan after meaningful execution, not only at the end.

Before full closeout, run both plan validators:

node .agents/rules/auto/scripts/check-plan-placeholders.mjs <plan-path>
node .agents/skills/autogoal/scripts/check-complete.mjs <plan-path>

The placeholder audit fails unresolved TODO/TBD text, bare pending cells, and unchecked items. The autogoal checker proves the resolved goal-plan structure.

State Capsule

Keep this compact capsule current so work can resume without rereading the world:

mode:
target:
active source:
active packet:
current owner:
last proven fact:
latest changed files:
next proof:
open blocker:
decision debt:
time remaining / reserve:

Update after source changes, failed proof, owner changes, and packet closeout. Never claim a state that is only planned.

Source Intake

Read only what can change the next decision:

1. VISION.md, docs/README.md, and the named local source.
2. The active plan/PRD/milestone and unresolved decisions.
3. Exact public exports, runtime entries, package manifests, and call sites.
4. Tests/fixtures/scenarios that define the current behavior.
5. CLI/template/generated owners when scaffold output is involved.
6. Matching docs and packages/kitcn/skills/kitcn/** when user guidance moves.
7. Local OSS clones for unfamiliar or parity-sensitive API design.

Build a source-backed case matrix rather than reading broad directories without a question.

Full Mode Contract

auto full is terminal only when every applicable lane is proven:

1. Resolve the named source or the latest relevant unfinished local PRD.
2. Repair bounded contradictions, placeholders, missing owner decisions, and weak proof contracts in that source.
3. If the source is fundamentally missing, route once to to-prd; then return to the same full run.
4. Decompose directly into local task packets in the PRD or active Auto plan.
5. Execute each packet with task, major-task, architecture-cleanup, hard-cut, design, or tdd as its true owner.
6. Run package build, changeset, fixture, scenario, docs/package-skill, browser, and generated-output gates required by the changed surface.
7. Run final cleanup and reviews.
8. Run bun lint:fix and bun check.
9. Commit, push, and open/update the GitHub PR when the run includes verified code-changing delivery.
10. Audit the complete goal plan and close the durable goal.

Local PRDs and task packets own decomposition; the GitHub PR owns delivery and review.

Task Packet Ledger

Every implementation packet gets one row:

Mode is one of:

• blocking: must close before dependent packets;
• parallel-join: may overlap only when explicit parallel work is authorized, but joins before its claim is consumed;
• detached: useful but cannot change the requested completion claim.

Consolidate test-only, docs-only, guard-only, and refactor-only fragments into the behavior packet they support unless ownership and acceptance are truly independent.

Claim Receipts

Any important final claim must have a receipt:

Allowed evidence includes source lines, test output, generated diffs, runtime observations, Browser proof, benchmark results, package exports, build artifacts, and authoritative external docs. A plan checkbox or command exit code without relevant assertions is not enough.

For evidence-backed claims:

• high: direct fresh evidence covers the exact claim and boundary;
• medium: direct evidence plus a bounded inference;
• low: unverified inference, stale evidence, or incomplete boundary.

Completion claims require high confidence. Rewrite, narrow, or keep working when confidence is lower.

Hard Confidence Thresholds

These block progress regardless of candidate score:

Decision Debt Cap

Decision debt is an unresolved choice that can change public behavior, owner boundaries, security, data lifecycle, or proof. Keep at most three active items and none on the critical path to the active packet.

If the cap is exceeded, stop implementation and resolve the highest-impact decision. Cosmetic preferences do not count.

Assumption Ledger

Validate high-impact assumptions before code. Low-impact reversible assumptions may proceed if they are explicit and tested before closeout.

Readiness Ownership

One owner signs each readiness lane:

Do not let multiple scorecards create fake rigor. Use readiness ownership to answer who must act next.

Scenario And Proof Matrix

Create a row for every source-listed behavior and failure class:

Include, when applicable:

• happy path and empty/missing input;
• auth/session/permission denial;
• validation and typed error behavior;
• retry/idempotency/concurrency;
• live subscription and non-live cache behavior;
• package export and consumer type flow;
• CLI interactive, --yes, and --json behavior;
• scaffold regeneration and fixture diff;
• Convex bundle/import boundary;
• UI loading, error, permission, responsive, and keyboard behavior;
• deletion/absence of superseded APIs for a hard cut.

Every row is pass, blocked with evidence, or N/A with reason.

Harness Selection

Choose the smallest harness that can disprove the claim:

Record command, cwd, prerequisites, expected signal, actual result, and artifact.

Error-Attempt Ledger And Self-Repair

For any repeated failure record:

After two attempts with the same signature, stop repeating the command. Change the diagnostic layer: reduce the repro, inspect ownership, refresh dependencies once when the failure shape indicates environment rot, switch harness, or route to diagnosing-bugs.

Trigger workflow self-repair when:

• the run repeatedly chooses the wrong skill;
• a required receipt cannot be represented in the plan;
• generated sources drift after the documented command;
• a stop rule permits false completion;
• an error recurs because the workflow gives no next-different move.

Repair the smallest source-owned rule/template/helper, add a smoke or eval case, regenerate mirrors, and run agent-native-reviewer plus autoreview. Do not rewrite the workflow merely because one task was awkward.

Skill Evaluation

For every changed skill keep at least one evaluation row:

Evaluate routing, placeholder failure, completion pass, source/generated ownership, and omitted workflows. A description that reads well is not proof that the skill routes correctly.

Candidate Scoring

When more than one safe next checkpoint exists, score 0-5:

• user/developer leverage;
• vision fit;
• unblock value;
• evidence strength;
• proof availability;
• reversibility;
• deletion/complexity reduction;
• conflict risk (reverse scored).

Record the top candidates, selected owner, and rejected high-scoring candidate with reason. If one owner is obvious, write no score needed.

Self-Grilling

Before an irreversible design or before full closeout, ask:

• Does this preserve kitcn's familiar mental models?
• Is the type path end to end or locally simulated?
• Is the Convex function bundle as narrow as the operation?
• Is the public surface smaller and clearer than the alternatives?
• Are CLI and generated ownership deterministic for agents?
• Does auth fail closed at the real owner?
• Are docs written for the current state?
• Can every acceptance claim be disproved by the selected harness?
• What attractive extra scope should be cut?

Record answers and changed decisions, not rhetorical questions.

Timed Loops

For timed <duration>:

1. Reserve at least 20% of the timebox for proof, review, and handoff.
2. Select packets small enough to finish before that reserve.
3. At each checkpoint update time remaining, active packet, and safe stop.
4. When reserve begins, stop opening scope and enter autoclosure.
5. A timebox ending is not completion; report proven work and the exact next packet or blocker.

Waits are work only when an external process is expected to change. While a safe independent packet exists, do it rather than polling.

Review-Until

Each review round must be fresh and independent:

1. Snapshot the intended delta and proof.
2. Run the selected reviewer without priming it with the prior verdict.
3. Classify findings: accept, reject with source evidence, or duplicate.
4. Fix accepted findings and rerun targeted proof.
5. Continue until the named threshold is met or the capped rounds expose a hard unresolved risk.

Never weaken full because the requested review threshold is lower. Final autoreview is still mandatory.

All-Lane Closeout

Before completion score each applicable lane 0-100 with evidence:

No applicable lane below 95 may be called complete. Use N/A only with a specific boundary reason. The score points to the next owner; it never replaces the receipt.

Command Discipline

• Use repository scripts and exact working directories.
• Prefer focused proof before broad gates.
• Do not run committed fixtures in place; prepare scenarios under tmp.
• Run bun install once when the task or dependency state requires it.
• Keep package behavior source-first; build for artifacts/exports or packages that intentionally require it.
• Edit .agents and package skill sources, never generated mirrors.
• Manage installed skills only through npx skills add/update/remove.
• Run bun install after source/lock changes to regenerate agent output.
• For authorized GitHub delivery, follow repository branch/check/whole-checkout rules exactly.

Stop Rules

Stop only when:

• the measurable target and all applicable lanes are proven;
• a missing user/external authority action blocks the next safe move;
• an irreversible decision outside the source contract requires direction;
• repeated different diagnostics prove an environment blocker;
• the timed closeout boundary is reached with a truthful partial handoff.

Do not stop because a plan, PRD, packet list, code diff, test pass, reviewer verdict, commit, or PR exists. None alone proves the full run.

Final Handoff

Report outcome first, then:

• source and packets completed;
• key behavior/public API decisions;
• proof and repository gates;
• annotated walkthrough images when UI or rendered output changed;
• generated/docs/package-skill sync;
• review findings resolved or rejected with evidence;
• GitHub PR/check state;
• residual risks, waivers, or exact blocker;
• final goal-plan audit and durable goal status.