visionlog.md

MCP server for long-term project governance. Records vision, goals, guardrails, SOPs, and architectural decisions (ADRs) — the contracts that all execution must honor.

Part of the trilogy: research.md → visionlog.md → ike.md

  • research.md earns decisions with evidence
  • visionlog.md records them as binding contracts
  • ike.md executes within those contracts

What it enforces

  • Guardrails are active or deprecated — never deleted
  • ADRs are permanent once accepted — a new ADR supersedes, never overwrites
  • Goals form a DAG — dependencies must be resolved before a goal is available
  • Vision is sticky — it does not drift session to session

Trilogy conventions

visionlog.md follows shared conventions with ike.md and research.md. See CONVENTIONS.md for the full standard.

  • Config lives at .visionlog/config.yaml (committed to git)
  • Tools: project_init (new project) and project_set (register existing for session)

Install

Not yet published to npm. Install from local path.

npm install
npm run build

Add to .mcp.json:

{
  "mcpServers": {
    "visionlog": {
      "command": "/absolute/path/to/visionlog.md/dist/visionlog",
      "args": ["mcp", "start"]
    }
  }
}

Session protocol

project_set { path: "/path/to/project" }   <- returns project_id
visionlog_boot { project_id: "..." }        <- active guardrails + goal state
visionlog_guide { project_id: "..." }       <- vision + decisions + goal map

Read both visionlog_boot and visionlog_guide at the start of every session before touching any task or code.

Project structure

my-project/
  .visionlog/
    config.yaml          <- project GUID + metadata (commit this)
    vision.md            <- north star, anti-goals, success criteria
    goals/               <- GOAL-NNNN.md — DAG of milestones
    adr/                 <- ADR-NNNN.md — architectural decisions
    guardrails/          <- GUARD-NNNN.md — active constraints
    sops/                <- SOP-NNNN.md — coordination protocols

Tools

Session

Tool Description
project_init Initialize visionlog in a new project
project_set Register existing project for session, returns project_id

Orientation (call at session start)

Tool Description
visionlog_boot Active guardrails + current goal state + backlog check
visionlog_guide Vision + key decisions + full goal map
visionlog_status Counts: goals, decisions, guardrails, SOPs

Vision

Tool Description
vision_view Read the project vision
vision_set Set or update the vision document

Goals

Tool Description
goal_create Add a goal to the DAG
goal_list List all goals with status
goal_view Read a goal
goal_update Update goal status or body
goal_unlockable List goals whose dependencies are met

Decisions (ADRs)

Tool Description
decision_create Record an architectural decision
decision_list List all ADRs
decision_view Read an ADR
decision_update Update status or body

Guardrails

Tool Description
guardrail_create Add a guardrail
guardrail_list List all guardrails
guardrail_view Read a guardrail
guardrail_update Update status or body
guardrail_inject Inject guardrails into an existing prompt

SOPs

Tool Description
sop_create Add a standard operating procedure
sop_list List all SOPs
sop_view Read a SOP
sop_update Update status or body

Project links

Data verified by PyPI on Mar 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dshanklin from gravatar.com dshanklin

Credits

Author: Daniel Shanklin

GitHub Statistics

Data verified by PyPI on Mar 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

agent-tools governance guardrails mcp vision

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

visionlog_md-0.2.0.tar.gz (93.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

visionlog_md-0.2.0-py3-none-any.whl (19.5 kB view details)

Uploaded Python 3

File details

Details for the file visionlog_md-0.2.0.tar.gz.

File metadata

  • Download URL: visionlog_md-0.2.0.tar.gz
  • Upload date:
  • Size: 93.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for visionlog_md-0.2.0.tar.gz
Algorithm Hash digest
SHA256 65f263e2836e626462eae3b2f336fb823e2df8c190840b010cbcf3367e5b196d
MD5 ed3e5cf1a13416cb12dd30472eb260db
BLAKE2b-256 50621ed5ec4765d28b30bc306c824299e0ce9489448cf99ecce35fe74f4a9888

See more details on using hashes here.

Provenance

The following attestation bundles were made for visionlog_md-0.2.0.tar.gz:

Publisher: publish.yml on eidos-agi/visionlog.md

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file visionlog_md-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: visionlog_md-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 19.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for visionlog_md-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b72fa7f76f1ed0c934e2b38fccce79be462e488d0f81ea36884e782b4cac242f
MD5 63ada25b91fd01d50fce11d2809694dd
BLAKE2b-256 ec59445c366c28b5cdb7fd96c11309abece01baf0c62c4afee4393b886fe5259

See more details on using hashes here.

Provenance

The following attestation bundles were made for visionlog_md-0.2.0-py3-none-any.whl:

Publisher: publish.yml on eidos-agi/visionlog.md

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page