# Clavue Efficiency Engineering Playbook - 2026-04-30

This document defines how Clavue should upgrade itself toward maximum engineering efficiency. It is written for Clavue developers and for Clavue sessions working on the Clavue codebase.

Reference baseline:

- Local product truth: `PRODUCT.md`, `ARCHITECTURE.md`, `docs/clavue-v8.9-upgrade-plan-2026-04-30.md`.
- Local current worktree: v8.8.108 with uncommitted v8.9 evidence/eval work in progress.
- External upgrade pattern: the current Claude Code changelog emphasizes small high-leverage releases: startup/resume speed, permission-prompt reduction, MCP and plugin resilience, terminal UI polish, shell/cross-platform fixes, provider compatibility, telemetry/debuggability, and memory/file-descriptor stability. Clavue should use the pattern, not copy the product identity.

## Goal

Clavue should be the fastest reliable path from user intent to verified software change.

Efficiency means:

- Fewer user decisions before useful work starts.
- Fewer model/tool turns per correct edit.
- Fewer repeated file reads and stale context tokens.
- Fewer permission prompts for safe local development.
- Faster startup, resume, command discovery, and provider diagnostics.
- More deterministic recovery when routes, tools, MCP servers, plugins, or sessions fail.
- Every release claim backed by an executable gate, not a narrative.

## Best-Practice Upgrade Logic

Use the following release logic for every upgrade slice:

1. Detect one friction source with evidence.
2. Define the lowest-level owner of that friction.
3. Add a regression or metric before broad refactor.
4. Patch the smallest authority boundary.
5. Verify with focused tests, then the relevant release gate.
6. Record evidence in a ledger or report.
7. Only then update public docs.

Do not ship feature expansion when the bottleneck is startup, permissions, provider ambiguity, context bloat, or release evidence.

## Bottom-Up Efficiency Architecture

### Layer 0 - Startup And Package Load

Objective: first visible interaction should happen with minimal module loading.

Rules:

- Keep expensive command implementations lazy-loaded.
- Keep `clavue --version`, `clavue provider <subcommand>`, and `clavue doctor` on fast paths.
- Do not import heavy UI, insights, MCP, plugin, or provider-validation modules at registry initialization.
- Treat command registry changes as startup-risk changes.

Measures:

- Cold `node dist/cli.js --version` time.
- Cold `clavue provider current` time.
- Number of modules loaded before first prompt.
- Heap used before REPL mount.

Near-term tasks:

- Add startup timing to release reports.
- Add a command-registry import budget.
- Keep `/insights`, `/stats`, MCP dialogs, plugin marketplace, and provider wizard as lazy surfaces.

### Layer 1 - Command Surface Authority

Objective: users and models should choose the right command on the first try.

Current state:

- `src/commands.ts` now contains command surface classification.
- `/help` filters public default commands through classification.
- README documents primary/secondary/compatibility behavior.

Remaining risks:

- `/login` is still primary but semantically overlaps with `/provider` and account-auth flows.
- Compatibility aliases can still look canonical if docs or help text drift.
- Experimental and hidden commands can appear in internal builds without enough warning.

Rules:

- Every command must have exactly one classification: primary, secondary, compatibility, internal, experimental, or hidden.
- Primary commands must support direct next actions.
- Compatibility commands must point to the canonical command.
- Hidden/internal commands must not be required by public docs.

Near-term tasks:

- Split `/login` copy into "provider setup" versus "account auth" with explicit canonical handoff.
- Add a command-surface lint that all built-in command names and aliases are classified.
- Add `/help` grouping by primary, secondary, compatibility, and custom.

### Layer 2 - Intent Routing And Workflow Control

Objective: broad user prompts should start the correct workflow without avoidable clarification.

Rules:

- Execute-now prompts should inspect and act when safe.
- Debug/diagnostic prompts should preserve task-board truth without triggering implementation.
- Parallel prompts should launch real workers before claiming parallel execution.
- Planning prompts should not block obvious safe first steps.

Current risk:

- Intent routing is improving, but generated eval scripts can create "evidence" without executing the real workflow. That is acceptable for offline planning only and must never be called live default-path proof.

Near-term tasks:

- Rename deterministic reports as `offline-contract` evidence when they do not execute the actual CLI path.
- Add a live mode for default-path smoke that creates a temp repo, runs the shipped CLI where possible, and executes real commands.
- Add a regression that generated reports cannot be used as the only release proof.

### Layer 3 - Provider And Model Routing

Objective: route quality should be obvious before a task starts.

Rules:

- Provider capability must flow through one decision: provider/model capabilities -> runtime decision -> workflow/tool behavior.
- A route cannot claim native coding capability without matrix evidence.
- Degraded and chat-only routes must lower workflow promises and produce clear recovery actions.
- Model-slot blanks should inherit safely and visibly.

Current state:

- Provider route policy tests and deterministic matrix work exist.
- `/provider doctor` exposes route diagnostics.

Remaining risks:

- Offline matrix rows are simulated decisions, not live provider probes.
- Users may still blame model quality when the route is degraded or chat-only.

Near-term tasks:

- Add a live provider-matrix mode with redacted credentials and strict timeout budgets.
- Add route-quality tags in status/footer and `/doctor`.
- Add "why this route is degraded" copy with one exact repair action.

### Layer 4 - Tool Execution And Permissions

Objective: safe local work should be low-friction; risky work should be explicit and recoverable.

Rules:

- Permission prompts must say why, exact scope, risk, and smallest safe approval.
- Recent denials must produce a recovery path, not a repeated prompt loop.
- Safe local test/build commands should be recognized deterministically.
- No bypass should be suggested for destructive or outside-workspace actions.

Near-term tasks:

- Add prompt-copy tests for bash, PowerShell, file edits, MCP tools, IDE diff, and fallback tools.
- Add permission prompt latency and prompt-count metrics to eval reports.
- Add a recent-denial recovery helper.

### Layer 5 - Context, Memory, And Token Efficiency

Objective: spend context only on information that changes the next engineering action.

Rules:

- Avoid repeated full-file reads after unchanged content is known.
- Prefer structured state summaries over transcript dumps.
- Keep active task, current diff, recent failures, provider route, and verification commands after compaction.
- Suppress stale memories and active-tool usage docs when they do not help the current turn.

Current strengths:

- There are compaction, continuity, memory, and context tests.
- Context analysis utilities exist.

Near-term tasks:

- Add duplicate-file-read metrics to world-class eval reports.
- Add context-budget warnings for large command output and repeated tool results.
- Add a live long-session smoke with compaction, continuation, resume, and task-board state.

### Layer 6 - UI And Terminal Interaction

Objective: terminal UI should make state obvious without costing speed.

Rules:

- Idle task boards must not imply active execution.
- Help should be progressive, not a flat list of everything.
- Status line should show route quality, permission mode, task state, and recovery hints without noise.
- Ctrl+C, Esc, and cancel behavior must be consistent across modals and embedded inputs.

Near-term tasks:

- Group `/help` by command classification.
- Add task-board rendered UI tests for stale and active in-progress states.
- Add terminal-width snapshot tests for provider, permission, and task screens.

### Layer 7 - MCP, Plugins, Skills, And External Integrations

Objective: external capability should be resilient and never slow down the core loop.

Rules:

- MCP/plugin discovery failures must degrade gracefully.
- OAuth and MCP auth refresh must avoid token leakage and race conditions.
- Plugin marketplace and local plugin scanning must be lazy.
- MCP resources, templates, tools, and commands must be reflected in a unified capability report.

Near-term tasks:

- Add MCP auth refresh locking and no-argv-secret tests.
- Complete local plugin directory scanning in marketplace UI.
- Add MCP/plugin startup budget metrics.
- Expand parsing diagnostics with exact remediation.

### Layer 8 - Parallel, Team, Companion, And Mao Workflows

Objective: orchestration should reduce wall-clock time, not add coordination overhead.

Rules:

- Parallel work must show worker count, budget, isolation mode, cancellation, and final aggregation.
- Team creation needs a direct or guided command path.
- Companion workflows must either execute through `/mao` or clearly label themselves as planning-only.
- `/mao` should reuse active provider profile and never require a second global setup path.

Near-term tasks:

- Add `/team create` or guided creation from `/team` empty state.
- Wire `/boy fix` and `/bigdaddy review` to `/mao` through a tested bridge.
- Add parallel result aggregation and partial failure UX.
- Add no-recursion tests across parallel, companion, and Mao handoffs.

### Layer 9 - Observability And Debuggability

Objective: developers should identify the failing layer in one command.

Rules:

- Every default-path failure should map to one layer: startup, command routing, provider, permission, tool execution, context, UI, MCP/plugin, orchestration, release.
- Debug output must redact secrets.
- Reports should distinguish simulated/offline evidence from live execution evidence.

Near-term tasks:

- Add `clavue doctor --json` or equivalent report for machine-readable diagnostics.
- Add route-decision, permission-count, command-latency, and context-token sections to eval reports.
- Add release report aggregation over eval, matrix, default path, build, package, and online checks.

### Layer 10 - Build, Release, And Self-Verification

Objective: releases should be independently reproducible.

Rules:

- `src/` is authored runtime source; `dist/` is release artifact.
- Unexpected missing-module stubs should fail.
- Generated reports should not silently enter release artifacts unless intentionally included.
- Trusted publishing must be primary; local publish is emergency fallback.

Current risk:

- `docs/evals/world-class/*.json` reports are generated under `docs/`, and `package.json` publishes `docs/**` except `docs/superpowers/**`. These reports may enter npm packages unless intentionally excluded or relocated.

Near-term tasks:

- Decide whether eval JSON reports are release artifacts. If not, move them outside publishable `docs/**` or exclude them.
- Add a publish-surface assertion for generated eval reports.
- Add live tarball extraction smoke to the release report.

## Functional Conflict Audit

### Conflict 1 - `/provider`, `/login`, And Auth Semantics

Problem:

Provider setup, official login, custom API profile management, and account auth are close enough to confuse users.

Decision:

- `/provider` is canonical for provider profiles and route repair.
- `/login` may remain a primary setup convenience only if it clearly routes users to provider setup versus account auth.
- Account-token commands must not be described as custom provider setup.

### Conflict 2 - Offline Evidence Versus Live Proof

Problem:

Current deterministic scripts can emit pass reports without executing the actual user path.

Decision:

- Offline evidence is useful for contracts and planning.
- Live proof must execute the shipped CLI or real runtime path.
- Release reports must label evidence mode: `offline-contract`, `local-live`, or `online-live`.

### Conflict 3 - Command Breadth Versus Product Clarity

Problem:

Many commands increase power but reduce discoverability.

Decision:

- Primary commands are the product map.
- Secondary commands are available but not first-run defaults.
- Compatibility aliases stay only when they reduce migration friction.
- Internal/hidden/experimental commands must not appear as public promises.

### Conflict 4 - Provider Flexibility Versus Coding Quality

Problem:

More routes do not automatically improve coding outcomes.

Decision:

- Route capability tier controls workflow behavior.
- Chat-only and degraded routes must not receive native workflow promises.
- Provider doctor and status must show exact route tier and repair action.

### Conflict 5 - Parallelism Versus Safety

Problem:

High-concurrency work can accelerate delivery or multiply mistakes.

Decision:

- Parallel launch must be bounded.
- Each worker needs ownership, budget, isolation mode, and stop criteria.
- Aggregation must verify results before claiming completion.

## Clavue-On-Clavue Development Workflow

When using Clavue to develop Clavue, follow this loop:

1. Read `PRODUCT.md`, `ARCHITECTURE.md`, and this playbook.
2. Run or inspect `git status --short` and identify unrelated worktree changes.
3. Classify the requested work by layer.
4. Find the smallest authority boundary that owns the behavior.
5. Add or update focused tests first when behavior changes.
6. Patch source only, unless the task is explicitly release packaging.
7. Run the smallest focused test.
8. Rebuild `dist` only when the changed surface is shipped through tracked dist.
9. Run relevant gates.
10. Record evidence in the correct ledger or report.

Layer-to-test map:

- Startup/package load: `node dist/cli.js --version`, release-pipeline tests, source-build tests.
- Command surface: `node --test tests/slash-command-surfaces.test.mjs`.
- Intent/workflow: `node --test tests/user-turn-intent.test.mjs tests/session-workflow-continuity.test.mjs`.
- Provider routing: `npm run test:route-policy`, provider CLI/runtime tests, provider matrix.
- Permissions: `node --test tests/permission-authorization-flow.test.mjs tests/safe-local-bash-command.test.mjs`.
- Context/memory: compact, memory, and context tests.
- MCP/plugin/skills: runtime skill support, MCP config, plugin tests.
- Parallel/team/companion/Mao: focused tests for each workflow plus no-recursion tests.
- Release: `npm run check`, `npm run build`, `npm run package:release`, release report.

## Efficiency Metrics To Track

Add these metrics to eval reports over time:

- `cold_version_ms`
- `cold_provider_current_ms`
- `repl_ready_ms`
- `command_registry_module_count`
- `provider_doctor_ms`
- `permission_prompt_count_per_task`
- `duplicate_file_read_count`
- `tool_error_recovery_rate`
- `context_tokens_to_first_edit`
- `turns_to_first_verified_change`
- `parallel_wall_clock_saved_ms`
- `resume_success_rate`
- `live_default_path_pass_rate`
- `release_evidence_completeness`

## Next Development PRs

### PR-EFF-01 - Evidence Mode Separation

Goal: prevent simulated/offline reports from being mistaken for live product proof.

Tasks:

- Add `evidenceMode` to default-path, provider-matrix, and world-class reports.
- Rename deterministic default-path smoke output to offline contract evidence unless it executes the CLI.
- Add tests that release reports distinguish offline-contract from local-live and online-live.

### PR-EFF-02 - Live Default Path

Goal: execute a real temp-repo path.

Tasks:

- Create temp project.
- Run `node dist/cli.js --version`.
- Run non-interactive provider/profile diagnostics where possible.
- Run `/init` path or direct init helper.
- Make a real edit and run `node --test`.
- Record actual command status and duration.

### PR-EFF-03 - Command Surface Lint

Goal: every built-in command and alias is classified.

Tasks:

- Compare `COMMANDS()` and aliases against `BUILTIN_COMMAND_SURFACE_CLASSIFICATIONS`.
- Fail if unclassified built-ins appear.
- Group `/help` by classification.

### PR-EFF-04 - Provider Live Matrix

Goal: add optional live route probes with safe timeouts and redaction.

Tasks:

- Support `--mode offline|live`.
- Redact URL credentials and tokens.
- Record timeout, auth failure, route failure, and degraded states distinctly.

### PR-EFF-05 - Publish Surface Hygiene

Goal: prevent accidental publication of transient eval artifacts.

Tasks:

- Decide publish policy for `docs/evals/**/*.json`.
- Add `package.json` file exclusion or move reports if needed.
- Add release validation for generated report policy.

## Release Rule

A Clavue release can claim "high-efficiency engineering maturity" only when:

- Live default path passes.
- Provider matrix has both offline-contract and at least one live route evidence mode.
- Permission prompt count is measured.
- Startup and provider diagnostics have timing metrics.
- Command surface lint passes.
- Generated report publish policy is enforced.
- Release report contains mode-labeled evidence from every critical layer.
