# Clavue 8.10 Capabilities — Source of Truth for README / Website / Release Notes

> Status: this document captures the capabilities landed on
> `v89-p0-development` (27 commits, 969/969 tests green). It is the
> single source of truth that README, the marketing site, the
> npm package description, and any release notes should pull from
> when the branch is merged and published as v8.10.
>
> Until this branch is merged + tagged, **do not ship** the
> messaging here. Use it for editorial work only.

## TL;DR

clavue is the first CLI coding agent where **plan steps are
executable, verification is automatic, and the model cannot claim
"done" without actually proving it**. Everything else flows from
that.

## Capabilities — concrete, demoable

### Verification-driven plan loop (new)

| What | How | Why it matters |
|------|-----|----------------|
| Plans are verifiable markdown | `## Step N` + `**Verify**: <command>` + optional `**Expect**: <substring>` | Authors specify "done" as a runnable check, not a vibe |
| `VerifyPlan` tool runs them | Per-step `onlyStep` or whole plan | Model can verify its own work between turns |
| Auto-mark `**Verified**: <iso>` | Passing steps written back to plan file | Subsequent runs skip re-verifying passed steps |
| ALL_VERIFIED / VERIFICATION_FAILED signal | Trailer on every VerifyPlan tool result | Recency bias — clear "you may finalize" or "do not finalize" verdict |
| Verify-gap reminder | Auto-injected after 5 turns with no VerifyPlan call | Stops drift toward declaring done without checking |
| Finish-line reminder | Fires when plan fully verified but no summary written | Cuts the "kept polishing instead of shipping" loop |
| Per-failureReason guidance | Every failure type gets directly-actionable next step | Model spends turns on the fix, not on debug-the-debugger |
| Plan-file structural lint | 8 error codes (Expect-without-Verify, Verified-without-Verify, etc.) | Catches malformed plans before VerifyPlan even runs |
| `/verify-plan [stepIndex]` slash command | Local execution, no model tokens | Fast "is it green?" check for the user |
| `/verify-stats [N]` slash command | Per-step pass rate + recent failure reason from disk log | Spot flaky verify commands across sessions |
| `/verify-reset [stepIndex...]` slash command | Clear stale Verified markers after editing | Honest re-verification when code changed |
| JSONL verify log | `<projectDir>/verify-log.jsonl` | Persistence, observability, audit trail |

### Long-conversation continuity (upgraded)

| What | How | Why it matters |
|------|-----|----------------|
| 12-section compact summary | Resolved Questions + Pending User Asks + Critical Context added on top of the existing 9 fields | Resumed turn doesn't re-answer already-answered questions |
| REFERENCE-ONLY preamble | Hermes-style framing on the resume message | Model treats summary as background, not active instructions |
| `/compact --focus "topic"` | Focus-topic injection biases ~60-70% of summary budget | Long debug sessions can preserve the relevant slice |
| Same-language summary | Forced via `CONTINUATION_PRIORITY_NOTE` | No silent English translation of Chinese / Japanese / etc. user threads |
| `post_compact_tasks` attachment | Snapshots todos / tasks across compaction | Model doesn't forget in-flight task list after `/compact` |
| Plan-progress addendum to summarizer | Verified vs pending step indices forced into the summary | Resumed turn never re-verifies finished steps |
| `plan_progress` field in V1 hook schema | Optional, snake-case, additive | External CI / dashboards can read plan state from PostCompact hook |

### Model picker (fixed)

| What | How | Why it matters |
|------|-----|----------------|
| Selection ✔ on the right row | `dedupeModelOptions` + `findOptionValueIgnoreCase` | Two option sources can no longer ghost the marker onto the wrong row |
| Default-row wording | "Resolves to X" instead of "currently X" | No more "I thought I picked Opus but it says I'm using gpt-5.4" confusion |
| Effort hint shows friendly name | `focusedDisplayName` | "Effort not supported for Sonnet (1M context)" instead of "claude-sonnet-4-6[1m]" |

## What stayed and was already strong

These aren't new but should still be in the marketing copy because
they're competitive moat against Claude Code / Codex / Cursor /
similar:

- Native repo tools (Read / Edit / Write / Glob / Grep / Bash / LSP)
- Provider-as-route control surface (`/provider`)
- Worktrees as first-class (`EnterWorktree` / `ExitWorktree`)
- Skill system (bundled + dynamic + MCP)
- Subagent isolation (AgentTool returns last-message text only)
- 5-stage compaction pipeline (snip / micro / collapse / auto / reactive)
- File-backed long-term memory (`memdir/`)
- SDK + remote modes
- Custom API URL / key / token + CCR-compatible gateway support

## Competitive comparison (one-line)

| Capability | Claude Code | Codex CLI | Cursor | Cline | Hermes | clavue v8.10 |
|---|---|---|---|---|---|---|
| Plans-as-verifiable-markdown | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| `VerifyPlan` tool with auto-mark | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| ALL_VERIFIED objective signal | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Verify-gap / finish-line reminder | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Plan lint (8 codes) | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 12-section compact summary | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Focused compaction (`--focus`) | partial | ❌ | ❌ | ❌ | ✅ | ✅ |
| Cross-compact tasks snapshot | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Provider-as-route | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
| Worktrees built-in | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |

## Headline sentences (for hero / OG / npm)

Pick one, depending on audience:

- "The CLI coding agent that proves its work."
- "Plans you can run. Verification you can trust. Coding you can ship."
- "clavue makes 'done' a check, not a claim."
- "An execution-first AI coding CLI where every step verifies itself."

## Subhead options

- "Author plans in markdown. Add a `**Verify**` line per step. clavue runs it, marks it Verified, and won't let the model say 'done' until every check actually passes."
- "Built for long sessions: structured compaction keeps your context alive across runs, verify-log keeps your tests honest across days."

## Three-line elevator pitch for "Why clavue"

1. **Plans are runnable.** Each step carries a verify command. clavue executes it, marks it Verified on success, and surfaces precise per-failureReason guidance otherwise.

2. **The agent can't fake "done".** ALL_VERIFIED only fires when every verify command actually exits clean. The model is told — at the tool-result level, the prompt level, AND the reminder level — that self-claims of completion are not enough.

3. **Long sessions stay sharp.** 12-section compact summaries with REFERENCE-ONLY framing, focused compaction, cross-compact task snapshots, and a JSONL audit trail of every verification keep multi-day projects coherent instead of drifting.

## Demo script (for landing page video / GIF)

```bash
# 1. Start a feature in plan mode
$ clavue
> /enter-plan-mode

# 2. clavue returns a starter template — author fills it in
## Step 1: Add JWT validation
**Verify**: `pnpm test --run auth.test.ts`
**Expect**: ✓ login with JWT

## Step 2: Wire the route
**Verify**: `curl -s localhost:3000/login -d '{}' | jq .ok`
**Expect**: true

# 3. /exit-plan-mode → implement step 1 → verify it
> Implement step 1.
> /verify-plan 1
1/1 passed
  ✓ step 1: Add JWT validation
Plan file rewritten with **Verified**: 2026-05-09T...

# 4. After both steps, run the whole plan
> /verify-plan
2/2 passed
All verify-bearing steps are now verified.

# 5. clavue tells the model: ALL_VERIFIED. You may now finalize.
```

This is what to film.
