vectl 0.1.1

Agentic Implementation Plan Manager

vectl: Agentic Implementation Plan Manager

⚠️ EXPERIMENTAL / DOGFOOD ONLY — vectl is used to manage its own development plan. It is NOT integrated with Eidos and should NOT be used by Eidos agents.

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

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

# From tools/vectl/ directory:
uv run vectl init --project myproject     # Create plan.yaml
uv run vectl add-phase --name "Phase 1"   # Add a phase
uv run vectl add-step --phase phase-1 --name "Do thing" --desc "Description"
uv run vectl next                         # See claimable steps
uv run vectl claim <step-id> --agent me   # Claim a step
uv run vectl complete <step-id> --evidence "commit abc123"  # Complete it

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
next [--detail]	Show claimable steps with summaries
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

Inspection

Command	What It Does
status	Plan-wide progress dashboard
show ID	Inspect any step (contains .) or phase
help-agent [--context startup|rejection|planning]	Agent onboarding guide

Lifecycle

Command	What It Does
skip STEP --reason TEXT	Skip step permanently with reason
reject STEP --reason TEXT [--reviewer NAME]	Reject completed step for rework
update-checklist STEP --check KEYWORD	Toggle checklist item (fuzzy match)
update-checklist 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
remove-step STEP	Remove step (pending only, no dependents)
move-step STEP --to-phase ID	Move step to different phase (clears deps, warns)
unlock PHASE [-e TEXT]	Manually unlock a locked phase

Meta

Command	What It Does
init --project NAME	Create new plan.yaml
validate [--check-refs]	Check plan integrity (DAG, IDs, status consistency)
--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  (~170L)  — Enums, Pydantic models, exceptions
io.py      (~110L)  — YAML IO + CAS
core.py    (~860L)  — All business logic (validation, state machine, mutation)
cli.py     (~900L)  — Typer CLI commands
mcp_server.py       — Stub (not yet implemented)

Tests

uv run pytest tests/ -v          # 241 tests

File	Tests	Coverage
test_models.py	21	Pydantic validation, enums
test_io.py	11	YAML IO, CAS
test_validation.py	17	DAG validation, status consistency
test_logic.py	31	State machine, auto-unlock, cascade
test_cli.py	80	All CLI commands end-to-end
test_checklist.py	12	Checklist toggle, append
test_architect.py	69	Plan mutation, slugs