vectl 0.1.7

Agentic Implementation Plan Manager

vectl: Agentic Implementation Plan Manager

vectl is a CLI + MCP tool for managing phased implementation plans in agentic workflows. It replaces passive markdown trackers with an active, DAG-enforced, CAS-safe planning system.

uvx vectl --help

Core Philosophy

1. Active Gating: Agents cannot skip phases or ignore dependencies. The tool enforces the DAG.
2. Context Efficiency: Agents only see relevant steps (next actionable items), saving tokens.
3. Atomic State: Updates are CAS-safe file operations. No stale tracker drift.
4. Affordance-Driven Output: Every command output includes hints for what to do next.
5. Minimal Tool Calls: The most common workflow (claim → work → complete) requires the fewest possible interactions.

Installation

cd tools/vectl
uv sync

Quick Start

vectl tracks implementation plans 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

For Your AGENTS.md

Add this to your repo's agent instructions:

## 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`

### 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.

CLI Workflow

uvx vectl init --project myproject        # Create plan.yaml
uvx vectl status                          # Plan-wide progress
uvx vectl next                            # See claimable steps
uvx vectl claim <step-id> --agent me      # Claim a step
uvx vectl complete <step-id> --evidence "commit abc123, pytest passed"

MCP Setup (Claude Desktop / Cursor)

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

Human Oversight

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

Migrating an Existing Plan

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

1. Run uvx vectl init --project <name> to create an empty plan.yaml and configure AGENTS.md.
2. Tell your agent: "Read vectl guide --on migration and migrate our existing plan to plan.yaml."

The guide contains the full workflow.

Data Model (plan.yaml)

version: 1
project: my-project
context: |
  PHILOSOPHY: Clean code, comprehensive tests.
  METHODOLOGY: Models → IO → Logic → CLI → MCP.

phases:
  - id: core
    name: Core Logic
    status: done
    gate: "All tests pass"

  - id: auth
    name: Auth Module
    depends_on: [core]
    status: in_progress
    gate: "Auth tests pass"
    steps:
      - id: auth.user-model
        name: User Model
        status: claimed
        claimed_by: engineer-1
        description: |
          Define User schema.
          - [x] Basic fields
          - [ ] Validation logic
        verification: "uv run pytest tests/test_user.py -v"
        refs: ["docs/specs/auth.md#user-schema"]

ID Scheme

Format	Example	Rule
Phase ID	core, cli-ux	Short, unique across plan
Step ID	core.pydantic-models	{phase_id}.{slug} auto-generated from name

Slug auto-generation: kebab-case from name. Collision resolved by appending -2, -3.

Ordering

• Execution order: Determined by depends_on (DAG). Not by list position.
• Display order: Within DAG constraints, then alphabetical.

Commands

Agent Workflow (every session)

Command	What It Does
status	Plan-wide progress dashboard
next [--detail]	Show claimable steps with summaries
show ID	Inspect any step (contains .) or phase
guide [--context startup|rejection|planning]	Agent onboarding guide
claim STEP --agent NAME	Claim step for work, print full spec
complete STEP --evidence TEXT	Complete step, show next available
defer STEP	Release claimed step back to pending
mine [--agent NAME]	Show steps currently claimed by an agent

Lifecycle

Command	What It Does
skip STEP --reason TEXT	Skip step permanently with reason
cancel STEP	Cancel a step (alias for skip --reason irrelevant)
skip-phase PHASE --reason TEXT	Skip all remaining steps in a phase
reject STEP --reason TEXT [--reviewer NAME]	Reject completed step for rework
check STEP --check KEYWORD	Toggle checklist item (fuzzy match)
check STEP --append TEXT	Add new checklist item

Plan Mutation (architect)

Command	What It Does
add-step --phase ID --name N [--desc D] [--after DEPS] [--verify CMD] [--refs R] [--id ID]	Add step
add-steps --phase ID	Batch add from stdin (YAML list)
add-phase --name N [--after IDS] [--gate TEXT] [--context TEXT] [--id ID]	Add phase
edit-step STEP [--name N] [--desc D] [--verify CMD] [--add-dep ID] [--rm-dep ID]	Edit step
edit-phase PHASE [--name N] [--gate G] [--context C]	Edit phase
remove-step STEP [--force]	Remove step (pending only; --force cleans dep refs)
move-step STEP --to-phase ID	Move step to different phase (clears deps, warns)
unlock PHASE [-e TEXT]	Manually unlock a locked phase

Human Oversight

Command	What It Does
render [--phase ID] [-o FILE]	Export plan as markdown
diff [REF]	Show plan changes since a git ref (default: HEAD)
log [--last N]	Show recent plan mutations from git history
review [--phase ID]	Multi-layer plan health review
gate-check PHASE	Check if a phase is ready to pass its gate

Meta

Command	What It Does
init --project NAME	Create new plan.yaml
validate [--check-refs]	Check plan integrity (DAG, IDs, status consistency)
search PATTERN [--phase ID] [--regex]	Search across phases and steps
mcp	Start the MCP server (stdio mode)
--version / -V	Show version

Affordance Pattern

Every command output ends with hints for the next action:

$ 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>

CAS (Compare-And-Swap) Safety

All write operations use CAS to prevent concurrent modification:

1. Load plan → get file hash
2. Modify in memory
3. Save with expected hash → atomic write (temp file + rename)
4. If hash mismatch → CASConflictError, retry

Architecture

models.py       (~300L)  — Enums, Pydantic models, dataclasses, exceptions
io.py           (~110L)  — YAML IO + CAS
core.py       (~1,570L)  — All business logic (validation, state machine, mutation, render, diff)
cli.py        (~1,670L)  — Typer CLI commands (33 commands)
mcp_server.py   (~660L)  — FastMCP server (8 tools)

Tests

uvx vectl --version               # Verify installation
uv run pytest tests/ -q           # 456 tests

File	Tests	Coverage
test_cli.py	124	All CLI commands end-to-end
test_architect.py	82	Plan mutation, slugs, batch add
test_mcp.py	61	MCP server tools
test_logic.py	55	State machine, auto-unlock, cascade
test_review.py	40	Review layers, gate checks
test_models.py	21	Pydantic validation, enums
test_render.py	19	Markdown export
test_validation.py	17	DAG validation, status consistency
test_diff.py	13	Plan change detection
test_checklist.py	12	Checklist toggle, append
test_io.py	11	YAML IO, CAS
test_properties.py	1	Stateful property-based testing