DOCSEARCHbyAlgolia
Submit Docs

dotcontext

repository·main·Indexed 20 days ago

https://github.com/vinilana/dotcontext

A contextual harness providing a durable, shared layer of project knowledge, workflow structure, and execution policies for AI coding tools. It features the PREVC (Planning, Review, Execution, Validation, Confirmation) execution model, a Model Context Protocol (MCP) server for AI agent integration, and a CLI (@dotcontext/cli) for synchronization and administration. Dotcontext manages project state via a .context/ directory, utilizing sensors for quality checks and plan-driven contracts to ensure verifiable agent execution.

Tokens
67.3K
Snippets
176
Records
310
Agent score
66%

What's inside dotcontext

  1. Overview of dotcontext configuration files

    main

    dotcontext distinguishes between authored configuration (which should be committed to git) and generated runtime state (which should be gitignored).

    Configuration files are located under .context/ and include:

    • .context/config.json: Configuration for repeatable context scaffolding.
    • .context/config/policy.json: Declarative rules for workflow actions and approvals.
    • .context/config/sensors.json: A catalog of executable quality checks (sensors).

    All files under .context/config/ and .context/config.json must be version-controlled to ensure all team members and agents operate under the same rules and quality gates.

  3. What is dotcontext?

    main

    dotcontext is a contextual layer designed to act as a 'harness for your harness.' It provides a unified system to maintain project continuity regardless of which AI tool or agent you are using. It focuses on making agent execution legible, constrained, reusable, and auditable through several key features:

    • Shared Context: Uses a .context/ directory to store durable project knowledge (docs, agents, skills, plans) and generated runtime state.
    • PREVC Workflow: A structured execution cycle: Plan → Review → Execute → Verify → Confirm.
    • Sensors & Policies: Enforces quality checks and approval rules via the runtime rather than relying solely on prompts.
    • Replay & Audit: Provides durable sessions, traces, task contracts, and failure datasets for inspection and replay.

    The system is organized around a single runtime accessible via CLI, MCP (Model Context Protocol), and various host integrations.

  4. Understand the @dotcontext/harness package role

    main

    The @dotcontext/harness package provides a reusable harness runtime for dotcontext. It serves as the orchestration layer for the system, managing the core logic without being tied to specific user interfaces or protocols.

    Key responsibilities include:

    • Harness Domain Services: Core logic and services.
    • Workflow Runtime: Execution of defined workflows.
    • Orchestration: Managing the interaction between plans, agents, context, and skills.
    • Transport-Agnostic APIs: Providing APIs that can be consumed by various adapters, such as the Model Context Protocol (MCP).

    Note that @dotcontext/harness does not manage CLI user experience (UX) or protocol-specific startup logic; those concerns are handled by other packages like @dotcontext/cli.

  5. Core features of dotcontext

    main

    dotcontext provides a durable, version-controlled context for your repository located in the .context/ directory. Key features include:

    • Versioned Knowledge Base: Project docs, agent playbooks, and reusable skills are stored in .context/ and committed to git.
    • PREVC Workflow: A structured execution workflow consisting of Plan, Review, Execute, Validate, and Confirm phases to guide AI agents through real work.
    • Sensors: Executable quality checks (e.g., build, tests, typecheck, lint) that emit pass/fail results during execution.
    • Enforcement and Audit: Uses Policies to declare allow/deny/approve rules, and provides sessions, traces, artifacts, and checkpoints for a durable audit trail of AI actions.
    • Tool Portability: A single configuration that can be exported to various AI tools or accessed live via an MCP server.

  6. Use @dotcontext/integrations for AI coding host adapters

    main

    The @dotcontext/integrations package provides host hook integrations for dotcontext. It exposes adapters and event mappers specifically designed for supported AI coding hosts, allowing them to interface with the dotcontext harness runtime.

    Supported hosts include:

    • Claude Code hooks
    • Codex CLI hooks
    • Pi extension (pi-dev)

    Note: Integrations are designed to call the harness runtime directly and do not import CLI or MCP surfaces.

  7. What is a task contract and how does it work?

    main

    A task contract is a machine-enforceable JSON record that defines the requirements for a task's completion. Unlike loose prompts, a contract specifies exactly what must be produced and which gates must be passed. The harness (not the LLM) decides if a task is complete by evaluating the contract against the current session state.

    Task contracts are typically derived from a linked plan. When a plan is linked to a workflow, the harness materializes the plan's phases into task contracts stored in .context/runtime/contracts/tasks/. The active workflow state (.context/runtime/workflows/prevc.json) uses the binding.activeTaskId field to point to the contract currently being enforced.

    // Example of a task contract structure
{
  "id": "task-123",
  "title": "Implement Auth",
  "status": "in_progress",
  "requiredSensors": ["tests-passing"],
  "requiredArtifacts": ["auth-module.ts"]
}

  8. How sensors and policies work in the harness

    main

    Sensors

    Sensors are executable quality checks. When run, they emit a structured result (e.g., event: "sensor.run") with a status of passed, failed, skipped, or blocked. Task contracts can require specific sensors by their id to be passed before completion.

    Policies

    Policies are evaluated at runtime when a workflow action occurs. The harness returns a verdict containing allowed, blocked, requiresApproval, and the reasons for the decision. If a rule has the require_approval effect, the workflow pauses until the specified approvalRole provides sign-off.

  9. Use hidden aliases for admin commands

    main

    Each admin command is registered twice: once under the visible admin group and once as a hidden top-level command. The top-level form acts as a convenience alias for scripting.

    Example equivalent commands:

    dotcontext admin workflow status
dotcontext workflow status

    Use the admin <subcommand> form for documented, discoverable usage (e.g., when running dotcontext admin --help).

  10. What are Sensors and how do they provide backpressure?

    main

    In dotcontext, Sensors are executable quality checks (typically shell commands) that provide deterministic evidence for the runtime. Unlike an agent's verbal claims, sensors produce structured results (passed, failed, skipped, or blocked) that are recorded as traces in the session.

    Backpressure occurs when a sensor marked as blocking: true fails. The runtime uses this failure as a hard gate, preventing the workflow from advancing to the next phase or completing a task until the sensor passes. This ensures that quality is enforced by the harness rather than just asserted by an agent.

  11. Understand the .context directory convention

    main

    The .context/ directory at your repository root is the central hub for all dotcontext data. It follows a strict split between Authored state (files you write and commit) and Generated state (runtime artifacts produced by the harness).

    Authored vs. Generated

    TypePurposeExamplesGit Strategy
    AuthoredSource of truth and project knowledgeDocs, agent playbooks, skills, policy rules, sensor catalogsCommit to Git
    GeneratedReproducible runtime stateSessions, traces, contracts, replays, cacheGitignore

    Scaffolding the directory

    Instead of creating the directory manually, use the MCP server to scaffold the structure:

    context({ action: "init", autoFill: true })

  12. How the Dotcontext Harness Runtime works

    main

    The harness acts as the central engine for execution, managing state, constraints, and feedback. It is responsible for several key runtime functions:

    • Runtime State: Persists durable execution data (sessions, traces, artifacts, checkpoints, contracts, replays, datasets) under .context/runtime and configuration (policy, sensors) under .context/config.
    • Guides: Constrains agent behavior using workflow structures, task contracts, handoff contracts, and policy rules.
    • Sensors: The feedback layer that runs checks, persists evidence, and produces findings that feed backpressure into task and workflow completion.
    • Replay and Dataset: Converts runtime history into inspectable artifacts. Session replay reconstructs execution timelines, while failure datasets cluster repeated breakdowns for evaluation.