vectl 0.1.31

Plans with teeth — TODO.md can't say no. vectl can.

vectl — DAG-enforced todo list for AI agents

中文文档 | Read the Introduction

TODO.md can't say no. vectl can.

uvx vectl --help

Why vectl?

Passive Markdown Plans	vectl
❌ Token explosion: Agents re-read the entire plan every call — finished steps included	✅ next returns only actionable steps
❌ State drift: Multiple agents edit the same file — silent overwrites, stale state	✅ CAS-safe atomic writes — conflicts detected, never silent
❌ No ordering: Agents pick what to work on — dependencies skipped, work duplicated	✅ DAG-enforced execution — blocked steps are invisible
❌ No verification: "Done" = a checkbox ticked, no proof	✅ Evidence required on completion
❌ Context pollution: Completed steps stay in context forever, diluting attention	✅ Agents see only what matters now

The Agent Control Plane

vectl turns a passive "todo list" into an active control plane for autonomous agents.

Feature	Problem Solved	Mechanism
Active Gating	Agents skip dependencies or "guess" order.	DAG Enforcement: Blocked steps are invisible. Agents literally cannot claim out-of-order work.
Context Efficiency	Agents re-read 500 lines of "Done" items.	View Filtering: vectl next returns only actionable steps. Zero token waste.
Anti-Hallucination	Agents declare "Done" without checking.	Evidence Protocol: Completion requires proof (logs, screenshots) via evidence_template.
State Consistency	Parallel agents overwrite TODO.md.	CAS Atomic Writes: File-based locking ensures no race conditions.

Quick Start

1. Initialize

uvx vectl init --project my-project

This creates plan.yaml and adds a vectl section to your AGENTS.md (creates one if needed).

2. Connect Your Agent

⚡ Claude Desktop / Cursor

{
  "mcpServers": {
    "vectl": {
      "command": "uvx",
      "args": ["vectl", "mcp"],
      "env": { "VECTL_PLAN_PATH": "/absolute/path/to/plan.yaml" }
    }
  }
}

⚡ OpenCode

Add to your opencode.jsonc:

{
  "mcp": {
    "vectl": {
      "type": "local",
      "command": ["uvx", "vectl", "mcp"],
      "environment": { "VECTL_PLAN_PATH": "/absolute/path/to/plan.yaml" }
    }
  }
}

See OpenCode MCP docs for details.

⌨️ CLI Only (no MCP)

No setup needed — agents call uvx vectl ... directly.

Note: uvx vectl init (Step 1) already creates or updates your AGENTS.md. If you need to update it later (e.g. to enable new guidance features), run:

uvx vectl agents-md

📋 AGENTS.md template (reference)

<!-- VECTL:AGENTS:BEGIN -->
## Plan Tracking (vectl)

vectl tracks this repo's implementation plan as a structured `plan.yaml`:
what to do next, who claimed it, and what counts as done (with verification evidence).

Full guide: `uvx vectl guide`
Quick view: `uvx vectl status`

### Claim-time Guidance
- `uvx vectl claim` may emit a bounded Guidance block delimited by:
  - `--- VECTL:GUIDANCE:BEGIN ---`
  - `--- VECTL:GUIDANCE:END ---`
- For automation/CI: use `uvx vectl claim --no-guidance` to keep stdout clean.

### CLI vs MCP
- Source of truth: `plan.yaml` (channel-agnostic).
- If MCP is available (IDE / Claude host), prefer MCP tools for plan operations.
- Otherwise use CLI (`uvx vectl ...`).
- Evidence requirements are identical across CLI and MCP.

### Rules
- One claimed step at a time.
- Evidence is mandatory when completing (commands run + outputs + gaps).
- Spec uncertainty: leave `# SPEC QUESTION: ...` in code, do not guess.
<!-- VECTL:AGENTS:END -->

3. Migrate (Optional)

If your project already tracks work in a markdown file, issue tracker, or spreadsheet, tell your agent:

Read the migration guide (via `uvx vectl guide --on migration` or `vectl_guide` MCP tool).
Migrate our existing plan to plan.yaml.
Prefer MCP tools (`vectl_mutate`, `vectl_guide`) over CLI if available.

4. The Workflow

# ORIENT: Where are we?
uvx vectl status                    # Plan-wide progress dashboard

# PICK: What's available?
uvx vectl next                      # Show claimable steps

# CLAIM: I'm working on this.
uvx vectl claim <step-id> --agent me  # Lock step, get full spec + guidance

# GUIDANCE (displayed on claim):
# --- VECTL:GUIDANCE:BEGIN ---
# ... (refs, evidence template, project rules) ...
# --- VECTL:GUIDANCE:END ---

# WORK: (you write code, run tests, follow guidance)

# COMPLETE: I proved it works.
uvx vectl complete <step-id> --evidence "..." # Paste filled template here

# REPEAT: What's unlocked now?
uvx vectl next                      # See what the completion unlocked

Every command output ends with hints for the next action:

$ uvx vectl complete auth.user-model -e "commit abc: model + tests"

Completed: auth.user-model

Next available:
  ○ pending  auth.session-token — Session Token  (auth)
  ○ pending  auth.permissions — Permission Model  (auth)

→ vectl claim <id> --agent <name>
→ vectl show <id>

5. Intelligent Guidance (The "Why")

vectl allows Architects to inject guidance directly into the Worker's context at the moment of action.

A. Evidence Templates (--evidence-template)

Prevent "lazy completion" (e.g., "I fixed it"). Force the worker to prove success.

uvx vectl add-step ... --evidence-template "
## Verification
- Command: `pytest tests/auth/`
- Output: [Paste 5 lines of output here]
- [ ] Confirmed 0 failures
"

B. Context Pinning (--refs)

Stop the "needle in a haystack" search. Tell the worker exactly where to look.

uvx vectl add-step ... --refs "src/auth.py,tests/test_auth.py"

When the worker runs uvx vectl claim, they receive:

1. The Task (Step Description)
2. The Context (Pinned Refs)
3. The Standard (Evidence Template)

This creates a "Success Pit": The easiest path for the agent is the correct one.

6. Visualization

See the DAG structure (output is Mermaid flowchart text, paste into GitHub/Obsidian to render):

uvx vectl dag              # High-level phase DAG (default)
uvx vectl dag --phase core # Detailed step DAG within a phase

Output example (renders natively in GitHub):

flowchart TD
  core["✓ Core Logic (5/5)"]
  cli["✓ CLI (4/4)"]
  mcp["▶ MCP Server (1/3)"]
  core --> cli
  cli --> mcp

For all 34 commands (plan mutation, review, admin): uvx vectl --help or uvx vectl guide.

Human Oversight

uvx vectl render                    # Export plan as markdown
uvx vectl diff                      # Changes since last commit
uvx vectl log --last 5              # Recent plan mutations

Data Model (plan.yaml)

version: 1
project: my-project
phases:
  - id: auth
    name: Auth Module
    depends_on: [core]
    steps:
      - id: auth.user-model
        name: User Model
        status: claimed
        claimed_by: engineer-1

Full schema, ID rules, and ordering semantics: docs/DESIGN.md.

Technical Details

Architecture, CAS safety, and test coverage: docs/DESIGN.md.