External Causal Workspace

Disk-backed causal workspace for complex agent decisions.

External Causal Workspace makes complex agent work inspectable, falsifiable, and evidence-bound by forcing the agent to externalize the structure of the task before answering, planning, debugging, refactoring, or modifying files.

It is designed for terminal agents and Agent Skills-compatible clients that can read and write files in a local project workspace.

What this skill does

When a task is complex or high-impact, the skill makes the agent create a temporary, task-local workspace under the target project:

.agent/current/owner.md
.agent/current/task.md
.agent/current/world.md
.agent/current/hypotheses.md
.agent/current/claims.md
.agent/current/verification.md
.agent/current/decision.md

The workspace belongs to the target project, not to the skill package.

The goal is not to expose private chain-of-thought. The goal is to make the agent's operational reasoning auditable through structured artifacts:

• task boundary;
• local world model;
• constraints and invariants;
• competing hypotheses;
• materially important claims;
• evidence and verification limits;
• retained decision;
• remaining uncertainty.

Core value

A normal model can produce a fluent answer while silently mixing observed facts, inferences, assumptions, risks, preferences, and decisions.

This skill forces separation between:

fact ≠ inference ≠ hypothesis ≠ constraint ≠ invariant ≠ risk ≠ value ≠ decision

The most important protection is claims.md: materially important assertions must be typed, sourced, statused, and assigned an impact level.

The second major protection is verification.md: the agent must not claim that something was inspected, tested, confirmed, validated, passed, or failed unless the claim has an evidence anchor.

The third protection, added in 0.2.1, is the final workspace integrity gate: before the final answer, the agent must re-check the required workspace files, finalize decision.md, update owner.md, and ensure the workspace is no longer left as active.

Use when

Use this skill when a task is:

• complex or ambiguous;
• architectural;
• debugging-oriented;
• root-cause oriented;
• refactoring-heavy;
• strategic or high-impact;
• performance-sensitive;
• security-sensitive;
• multi-file;
• likely to create technical debt if misunderstood;
• dependent on repository-specific facts;
• dependent on verification, traceability, or falsification.

Avoid using it heavily for:

• trivial edits;
• simple formatting;
• small isolated renames;
• direct factual questions that do not depend on local project reality;
• any task where a full workspace adds more noise than value.

Package structure

external-causal-workspace/
  SKILL.md
  README.md
  LICENSE
  SECURITY.md
  CHANGELOG.md
  MANIFEST.json
  metadata.json
  .gitignore
  references/
    claims-ledger-protocol.md
    final-response-contract.md
    state-and-memory-protocol.md
    structural-reasoning-protocol.md
    tool-verification-protocol.md
    world-model-workspace.md
  examples/
    architecture-review/
      prompt.md
      expected-output.md
    debugging-cache-ttl/
      prompt.md
      expected-output.md
    strategic-decision/
      prompt.md
      expected-output.md
  evals/
    evals.json

Installation

OpenCode, project-local

mkdir -p .opencode/skills/external-causal-workspace
cp -R external-causal-workspace/* .opencode/skills/external-causal-workspace/

OpenCode, global

mkdir -p ~/.config/opencode/skills/external-causal-workspace
cp -R external-causal-workspace/* ~/.config/opencode/skills/external-causal-workspace/

Codex / Agent Skills-compatible clients, project-local

mkdir -p .agents/skills/external-causal-workspace
cp -R external-causal-workspace/* .agents/skills/external-causal-workspace/

Codex / Agent Skills-compatible clients, global

mkdir -p ~/.agents/skills/external-causal-workspace
cp -R external-causal-workspace/* ~/.agents/skills/external-causal-workspace/

Typical workflow

For a complex task, the agent should:

1. decide whether the skill is required;
2. inspect only the necessary workspace context;
3. reset or create .agent/current/;
4. write owner.md, task.md, world.md, hypotheses.md, claims.md, verification.md, and decision.md;
5. model the objects, relations, constraints, causalities, and invariants;
6. generate competing hypotheses or solution paths;
7. test them logically and, where possible, with tools;
8. update claim statuses and verification evidence;
9. finalize the retained decision;
10. run the final workspace integrity gate;
11. answer from the stabilized structure.

Example activation prompt

Analyze this stale-cache issue. Use external-causal-workspace because the task is ambiguous, architecture-sensitive, and depends on verification.

The skill is also designed for implicit activation through its description field. The description intentionally starts with Use when so compatible agents can recognize the trigger conditions.

Security model

This is an instruction-first skill. It does not bundle executable scripts by default.

By design, task reasoning is written under the target project's .agent/current/ directory. You should not commit temporary task state unless you intentionally want to preserve it.

Recommended .gitignore entries are included in this package.

What this skill is not

This skill is not:

• a replacement for tests;
• a proof of formal correctness;
• a hidden reasoning dump;
• a universal workflow for every task;
• a durable audit log by itself;
• a complete observability or governance platform.

It is one focused component: a task-local causal workspace for high-impact agent reasoning and decision-grade traceability.

Release status

Current release: 0.2.1.

This version is intended as the first public release candidate after validation on self-contained architecture, debugging, and strategic-decision examples.