Envoi

Deterministic repo-local orchestration for AI implementation loops: planner -> builder -> checker.

Envoi is for teams that want:

• fast delivery with AI agents,
• strict safety boundaries,
• auditable artifacts per cycle,
• low-friction human control.

Product Narrative

• Product name: Envoi.
• tick is the core mechanic: one bounded execution cycle.
• Human role stays plain: decide, approve, unblock.
• “Taste” appears in microcopy, not in role names.

Human-facing guidance uses:

• Needs you: choose direction.
• Your call: accept, adjust, or undo.
• Taste check: does this feel right? (only when necessary)
• Waiting for you

Core Invariant

envoi tick executes exactly one finite cycle:

1. lock + preflight,
2. one planner decision,
3. one builder execution,
4. one checker pass,
5. one persisted REPORT.json (+ optional REPORT.md).

Use envoi loop only when you intentionally want multiple ticks.

Command Surface (8 Verbs)

• envoi install — scaffold + guided onboarding (global install optional)
• envoi start — guided onboarding (and resume with answers in non-TTY)
• envoi brief — onboarding alias (same flow, no tour prompt)
• envoi tick — one bounded cycle (plan -> edit -> verify -> stop)
• envoi loop — run multiple ticks until boundary
• envoi status — current state + context
• envoi check — environment + constraints health
• envoi undo — rollback tracked files to last recorded base snapshot

Optional bridge:

• envoi app — open desktop app when available, otherwise show benefits + link

Compatibility During Transition

Legacy command aliases are still accepted and automatically mapped to the new command set.

Existing installs can move forward with:

• envoi update --dry-run
• envoi update --yes

Quickstart

One command for Claude Code

npx -y @ttfw/envoi@latest install

This scaffolds your repo and starts guided onboarding immediately. Add --global-install if you also want a global envoi binary in the same run. Guided onboarding (install, start, brief) is currently Claude Code-only.

1) Install

Development-linked install:

cd /path/to/envoi
pnpm build
pnpm link --global

Repo-local install:

cd /path/to/target-repo
pnpm add /path/to/envoi

2) Run guided onboarding

cd /path/to/target-repo
envoi start

envoi start handles onboarding end-to-end:

1. asks Tour vs Setup,
2. captures PRD/context (--prd-file, stdin, discovered file, editor, or inline paste),
3. configures mode (milestone|autonomous|task) and builder (cursor|claude_code),
4. chooses planner provider (claude_code|chatgpt) and assigns planner model automatically,
5. optionally configures builder model when builder is claude_code (sonnet|haiku),
6. configures reviewer (codex|none, default recommended: codex),
7. auto-initializes git (git init) when no repository exists,
8. runs role connectivity checks,
9. writes envoi/ROADMAP.json from the planner snapshot,
10. asks whether to start execution now,
11. if starting immediately in a brand-new repo, auto-commits scaffold files before first tick.

Non-TTY (agent-run) onboarding:

• Envoi emits exactly one next question per run (envoi.onboarding.next_question.v1) and returns exit code 0 by default (to avoid noisy error wrappers in agent CLIs).
• Reply with one answer envelope at a time (envoi.onboarding.answer.v1), then rerun to get the next question.
• After required fields are collected, Envoi asks for explicit review/confirm (confirm, confirm_and_start, or edit:<field>), including full PRD content plus preview/path.
• Output defaults to compact single-line payloads; switch with:
  • --json (single-line payload; explicit for automation)
  • --verbose-onboarding (human + pretty JSON)
  • --onboarding-output compact|json|verbose
• Use --strict-exit to return exit code 20 when onboarding still needs input.
• Use --reconfigure to force a fresh questionnaire after onboarding is already marked complete.
• Resume with either:
  • envoi start --answers-json '<json>'
  • envoi start --answers-file <path>

3) Run manually later (optional)

envoi check
envoi tick
# or
envoi loop --mode milestone

Loop Modes + Follow-up Paths

• task: stops at task completion boundary
• milestone: stops at milestone boundary/completion
• autonomous: continues across milestones until blocked/limit/signal

Boundary outputs are explicit:

• task/milestone => STANDBY with next command
• autonomous => continues unless safety boundary triggers

PM-Style Idea Intake (No Technical Burden on User)

Capture new ideas between boundaries:

envoi idea "Preview changes before publish"
envoi idea "Need staging validation faster" --testability soon --target-by 2026-03-01

Ideas are persisted in state (idea_inbox) and fed into planner decisions. Planner should choose sequencing, scope, and timing; user should not be forced into low-level technical choices. Planner snapshots are written to envoi/ROADMAP.json and refreshed by onboarding when needed.

If Envoi stops with an orchestrator product question, answer it directly and continue:

envoi answer "Use plain HTML/CSS/JS with no persistence."
envoi tick

Optional Reviewer Gate

When configured, reviewer can:

• allow proceed,
• force stop before build (STOP_REVIEWER_FORCED_PATCH),
• ask product question (STOP_REVIEWER_ASK_QUESTION).

This reduces rework on touchy tasks while keeping human control clear.

Verdict Labels (Display Layer)

Canonical machine values remain unchanged (success|stop|blocked, STOP_*, BLOCKED_*). Display labels in CLI/report copy map to:

• CLEARED
• STANDBY
• BLOCKED
• OUT_OF_BOUNDS
• LIMIT_HIT
• ROLLED_BACK

Token Strategy + Telemetry

Envoi minimizes context waste by:

• compacting oversized prompt sections,
• bounding idea/question payloads,
• truncating oversized warning payloads,
• using compact machine contracts for builder dispatch.

Token feedback is surfaced at:

• ORCHESTRATE,
• BUILD,
• per tick total,
• cumulative loop totals.

If provider usage metadata is missing, n/a is shown.

Update Strategy

envoi update --dry-run
envoi update --yes

Options:

• --mode auto|linked|registry
• --manager pnpm|npm|yarn|bun
• --dry-run
• --yes

Linked-install behavior:

• envoi tick and envoi loop refresh stale linked builds before execution.
• if linked source refreshes between loop ticks, loop stops at safe boundary (self_update) so next launch uses fresh code.

Config + Workspace Migration

New defaults:

• envoi.config.json
• envoi/ workspace directory

Legacy layout support:

• Envoi auto-detects prior config/workspace layouts.
• on load, Envoi migrates prior defaults to new paths and writes envoi.config.json.
• prior config names remain compatible and continue to load.

Safety vs Speed

envoi autonomy --set strict
envoi autonomy --set balanced
envoi autonomy --set fast

• strict: more friction, highest safety bias
• balanced: recommended default
• fast: fewer prompts, still constrained by guardrails

Repeated proceed prompts usually come from host CLI safety boundaries (filesystem/network/command risk), not only Envoi itself.

CLI Reference

Global option:

• envoi -c <path> / envoi --config <path>

Commands:

• envoi install
• envoi start
• envoi brief
• envoi tick
• envoi loop --mode task|milestone|autonomous --max-ticks <n>
• envoi status
• envoi check
• envoi undo
• envoi app
• envoi mode --set <mode>
• envoi builder --set <builder>
• envoi autonomy --set strict|balanced|fast
• envoi idea "<text>" [--target-by <date>] [--testability soon|later|unknown]
• envoi update
• envoi pr-note

Help:

• envoi --help
• envoi <command> --help

Runtime Artifacts

Default runtime files live under envoi/:

• STATE.json
• TASK.json
• REPORT.json
• REPORT.md (optional)
• BLOCKED.json
• ROADMAP.json
• history/<run_id>/...

PR Attribution

envoi pr-note
envoi pr-note --format text

Development

pnpm build
pnpm test
pnpm typecheck

Additional Docs

• docs/DOGFOOD.md
• docs/NEW-PLAN.md
• pilot/ (legacy workflow docs)