Deepwork: Disciplined Planning & Canonical Execution¶
🇧🇷 Versão em Português disponível: Leia em Português
Pantheon's Deepwork module is the architectural planning and disciplined execution engine for OpenCode. It solves the biggest issue with AI coding agents: the plan as an ephemeral Markdown document that the model reads, forgets, or prematurely concludes without verifiable proof.
1. Non-Negotiable Principles¶
- JSON is Ground Truth, Markdown is a Projection: The canonical state lives in machine-verifiable, structured JSON (
plan.json). - Strictly Zero HTML: No scattered HTML pages or heavy dashboards. All approvals, prompts, and rejections use native OpenCode UI tools (
question). - Human Decisions First: Design trade-offs and open questions (
decisions_needed) are resolved with the developer via interactive choice dialogs before execution. - Dependency DAG, Not a Flat List: Tasks are connected in a Directed Acyclic Graph (Mermaid DAG), making parallel execution (
parallel_safe) and blockers explicit. - Fail-First Acceptance Criteria: Every task defines binary verification checks that currently fail (
fails_now: true) and must pass upon completion.
2. Canonical On-Disk Structure¶
When a Deepwork workflow is initiated via /pantheon-deepwork or @zeus, Pantheon scaffolds a dedicated plan directory:
.pantheon/deepwork/<slug>/
├── plan.json # Machine ground truth (strict JSON schema)
├── journal.ndjson # Append-only audit log of phase and task transitions
└── PLAN.md # Human-readable Markdown projection with Mermaid DAG
The plan.json Format¶
{
"plan_id": "PLAN_001_csv-export",
"created_at": "2026-11-13T10:00:00Z",
"intent": "Add asynchronous CSV metrics report export to the dashboard",
"tier": "lite",
"done_when": [
"npm test tests/metrics-export.test.ts exits 0",
"GET /api/reports/csv responds with Content-Type text/csv"
],
"tasks": [
{
"task_id": "T1",
"title": "Backend streaming CSV route",
"owner": "@hermes",
"depends_on": [],
"parallel_safe": true,
"verification": {
"command": "node --test tests/metrics-api.test.mjs",
"fails_now": true
}
},
{
"task_id": "T2",
"title": "Export button with loading state",
"owner": "@aphrodite",
"depends_on": ["T1"],
"parallel_safe": false,
"verification": {
"command": "npm test",
"fails_now": true
}
}
]
}
3. Interactive Approval Gate with the question Tool¶
Open Questions are never dumped as plain text bullets in chat. Instead, @zeus extracts each decision into the native question tool:
[Interactive Question]
Which buffering approach should be used for CSV generation?
• (Recommended) Native Node.js stream pipeline to prevent memory spikes
• In-memory buffer serialization
Only after all required decisions are answered and the plan is approved does @zeus dispatch execution to specialist agents.
4. Visualizing Dependencies (Mermaid DAG)¶
Every PLAN.md automatically renders a Mermaid dependency graph:
graph TD
T1["T1: Backend Streaming API (@hermes)"] --> T2["T2: Export UI Component (@aphrodite)"]
T2 --> T3["T3: Quality & Security Audit (@themis)"]
classDef done fill:#2ea44f,stroke:#2ea44f,color:#ffffff;
classDef inprogress fill:#0366d6,stroke:#0366d6,color:#ffffff;
classDef pending fill:#6e7681,stroke:#6e7681,color:#ffffff;
5. Reference Implementation¶
Inspect a live Deepwork plan directory in the repository:
- examples/saas-dashboard/.pantheon/deepwork/PLAN_001_metrics-dashboard/