Project Canvas OS
Purpose
Operate projects with two complementary layers:
Agent knowledge layer: README.md + current project docs
Human cognition layer: Project.canvas
Truth layer: Git/CI/tests/artifacts/evidence
Mutation/audit layer: scripts/project_canvas_os.py
The important correction: Canvas does not replace documentation.
- Project documents remain the best way for agents to understand the system deeply: architecture, domain model, API contracts, runbooks, testing strategy, ADRs, protocols, setup notes.
Project.canvas is primarily for humans: it lowers understanding cost by showing goals, modules, current work, risks, decisions, and evidence relationships spatially.
- README is the project contract and index: it should point to the important docs and the Canvas.
- The CLI validates Canvas and audits documentation hygiene so docs stay current, discoverable, and non-redundant.
Required Companion Skills
Load as needed:
json-canvas — required before direct .canvas JSON work.
obsidian-markdown — required before writing Obsidian-facing Markdown.
obsidian-cli — optional; only when interacting with a running Obsidian vault.
software-delivery-workflows or task-pr-flow — when the Canvas/docs update is tied to code delivery, branches, PRs, or validation gates.
Default: use the bundled CLI first for Canvas/status/evidence operations. Direct JSON edits are allowed only when the CLI cannot express the operation.
Hard Rules
- Do not discard useful project documentation. Keep relevant docs current when code, architecture, run/validation, API contracts, or operational procedures change.
- Do not create redundant or ephemeral status-document sprawl. Temporary progress/status/handoff docs are allowed only when explicitly canonical for that project or requested by the user.
- README must be a contract and doc index, not a long progress log.
Project.canvas is the human-facing cognition map, not the sole source of project knowledge.
- Every completion claim needs concrete evidence: command output, CI link, commit, screenshot, trace, benchmark, or manual observation.
- Agent may transition tasks to
Verify; agent may not transition to Done without a concrete Evidence Card and explicit gate text from a human or named verification script.
- Prefer CLI operations over hand-editing Canvas JSON:
python3 <skill>/scripts/project_canvas_os.py status <repo>
python3 <skill>/scripts/project_canvas_os.py docs <repo>
python3 <skill>/scripts/project_canvas_os.py add-task <repo> --title "..."
python3 <skill>/scripts/project_canvas_os.py add-evidence <repo> --task "..." --test "..." --set-task-verify
python3 <skill>/scripts/project_canvas_os.py transition <repo> --task "..." --state Done --gate "human confirmed"
- Canvas and relevant docs should be committed with code when the code changes project understanding.
Documentation Layer
Docs are allowed and expected when they help agents understand or operate the project.
Good docs:
README.md
AGENTS.md / CLAUDE.md / .agents/*.md
docs/architecture.md
docs/domain.md
docs/api.md
docs/testing.md
docs/runbook.md
docs/adr/*.md
docs/protocols/*.md
Bad docs:
duplicate summaries
stale implementation notes
unowned progress logs
status files that contradict Project.canvas
handoffs with no durable facts
Rule: if a document describes durable project knowledge, keep it current. If it only describes transient state, prefer Project.canvas + Evidence.
Best-Practice Operating Loop
Start of work
- Read
README.md as the contract/index.
- Read the relevant docs linked from README or discovered by:
python3 <skill>/scripts/project_canvas_os.py docs <repo>
- Inspect the human map:
python3 <skill>/scripts/project_canvas_os.py status <repo>
python3 <skill>/scripts/project_canvas_os.py validate <repo> --strict
- Pick a task from
Active, or propose a small Proposed task.
- Check dependencies, docs, risk, and evidence edges before coding.
End of work
- Run the real validation for the code/workflow.
- Update relevant docs if the change affects architecture, domain terms, public API, setup, validation, runbooks, or agent rules.
- Add/update an Evidence Card with exact result text:
python3 <skill>/scripts/project_canvas_os.py add-evidence <repo> \
--title "<short evidence>" \
--task "<task title/id>" \
--test "<command + result>" \
--artifact "<path/url or none>" \
--set-task-verify
- Add Risk Card if anything is unverified, flaky, blocked, undocumented, or assumed.
- Update Module/Decision cards for human comprehension when durable relationships changed.
- Audit docs and Canvas:
python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --docs-strict
- Report changed code, docs, Canvas state, validation output, and remaining uncertainty.
Canvas Role
Canvas is for fast human orientation. Keep it spatial, short, and connected.
Use five stable regions:
| Region |
Purpose |
| Goal |
intent and success condition |
| System Structure |
module/data/agent relationships; link key docs as file nodes when useful |
| Current Work |
Proposed/Active/Verify/Blocked/Done tasks |
| Evidence |
concrete proof handles |
| Risks & Decisions |
open uncertainty and durable choices |
Do not put long explanations in Canvas. Put durable explanations in docs and link them from README/Canvas.
Card Types
Use only these six text-card types unless the user explicitly extends the protocol:
| Card |
Purpose |
| Goal |
objective and success condition |
| Module |
system module, data flow, agent flow, major interface |
| Task |
executable work item |
| Evidence |
hard proof for task/module/decision |
| Risk |
uncertainty, blocker, missing proof, missing docs, operational risk |
| Decision |
durable choice with rationale and impact |
Use Canvas file nodes for important docs when a visual link improves human comprehension; do not invent a separate Document Card type unless the project explicitly needs it.
State Model
| State |
Meaning |
Agent can set? |
Color |
| Proposed |
suggested, not approved |
yes |
"6" |
| Active |
approved/current work |
yes, if instructed or already active |
"5" |
| Verify |
implementation claims complete, evidence attached |
yes |
"3" |
| Done |
accepted by human or named verification gate |
only with explicit gate |
"4" |
| Blocked |
dependency, evidence, or required-doc update missing |
yes |
"1" |
Done requires both:
concrete Evidence Card
Gate: <human/script confirmation>
CLI First
Primary script:
scripts/project_canvas_os.py
Useful commands:
python3 <skill>/scripts/project_canvas_os.py init <repo> --name "<Project>" --goal "<Goal>"
python3 <skill>/scripts/project_canvas_os.py docs <repo>
python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --docs-strict --list-docs
python3 <skill>/scripts/project_canvas_os.py validate <repo> --strict
python3 <skill>/scripts/project_canvas_os.py status <repo>
Compatibility validator:
scripts/validate_project_canvas.py
Use references/cli-reference.md for full commands.
Initialization
For a repo without this system:
python3 <skill>/scripts/project_canvas_os.py init <repo> --name "<Project>" --goal "<Goal>"
python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --list-docs
This creates:
README.md
Project.canvas
.agents/canvas-protocol.md
Then keep or create only docs that are useful to agents and link key docs from README.
Scaling Rules
Escalate only when the file-level system is insufficient:
- Native Markdown docs + Canvas + CLI — default.
- Sub-canvas/file nodes — when one canvas exceeds roughly 50 cards or one module needs its own map.
- Obsidian Advanced Canvas — when folding/focus/navigation becomes the bottleneck.
- Bases — only for hidden indexes like all
Verify tasks, open risks, or docs inventory; not the daily entrypoint.
- MCP/REST — only when multiple independent agents need concurrent vault access with policy enforcement.
Validation Gate
Before final response after any Canvas/docs change:
python3 <skill>/scripts/project_canvas_os.py validate <repo> --strict
python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --docs-strict
python3 -m json.tool <repo>/Project.canvas >/dev/null
git -C <repo> diff --check
python3 <skill>/scripts/test_project_canvas_os.py -v # when editing the skill itself
For codebase sessions with an external coding gate, also run the cheapest relevant repository script that can see the checkout, usually lint/typecheck/test.
Checks include:
- JSON parses.
- Node/edge IDs unique.
- Edges reference real nodes.
- Task states are valid.
Verify/Done tasks have concrete evidence.
Done has explicit gate text when transitioned through CLI.
- Markdown docs are inventoried and classified as contract/knowledge/other/state.
- Stale/deprecated doc markers are reported;
--docs-strict fails on them.
- Key knowledge docs not referenced by README or Canvas are reported as discoverability warnings.
Linked Files
scripts/project_canvas_os.py — primary zero-dependency CLI.
scripts/validate_project_canvas.py — validation compatibility wrapper.
scripts/test_project_canvas_os.py — skill self-tests.
templates/README.md — minimal project contract and docs index template.
templates/Project.canvas — five-region starter canvas.
references/canvas-protocol.md — repo-local agent protocol for .agents/canvas-protocol.md.
references/operating-model.md — full operating model and escalation rules.
references/cli-reference.md — command reference and examples.
references/adoption-checklist.md — checklist for converting an existing repo.
references/documentation-hygiene.md — rules for current, non-redundant Agent knowledge docs.
When Not To Use
Do not use this skill for:
- Replacing GitHub/Linear lifecycle systems.
- Long-form research notes unrelated to a project.
- General wiki design with no project execution loop.
- Projects where the user explicitly wants conventional documentation only.
- Obsidian plugin development itself; use Obsidian-specific skills directly.
1---2name: project-canvas-os3description: "Use when operating a best-practice Project Canvas OS: project documents as the Agent knowledge layer, README.md as project contract, Obsidian Project.canvas as the human cognition map, Evidence cards as truth handles, and a zero-dependency CLI as the safe mutation/audit layer. Trigger on Project Canvas OS, Project.canvas, Obsidian Canvas project map, documentation hygiene, Heptabase-style project map, evidence-driven project state, or requests to reduce human understanding cost without losing project docs."4version: 2.1.05author: Hermes Agent6license: MIT7platforms: [linux, macos, windows]8metadata:9 source: https://skillmd.com/skills/peterfile/project-canvas-os10 hermes:11 tags: [project-management, documentation, obsidian, canvas, json-canvas, evidence, software-delivery, cli]12 related_skills: [json-canvas, obsidian-markdown, obsidian-cli, software-delivery-workflows, task-pr-flow]13---1415# Project Canvas OS1617## Purpose1819Operate projects with two complementary layers:2021```text22Agent knowledge layer: README.md + current project docs23Human cognition layer: Project.canvas24Truth layer: Git/CI/tests/artifacts/evidence25Mutation/audit layer: scripts/project_canvas_os.py26```2728The important correction: **Canvas does not replace documentation**.2930- Project documents remain the best way for agents to understand the system deeply: architecture, domain model, API contracts, runbooks, testing strategy, ADRs, protocols, setup notes.31- `Project.canvas` is primarily for humans: it lowers understanding cost by showing goals, modules, current work, risks, decisions, and evidence relationships spatially.32- README is the project contract and index: it should point to the important docs and the Canvas.33- The CLI validates Canvas and audits documentation hygiene so docs stay current, discoverable, and non-redundant.3435## Required Companion Skills3637Load as needed:38391. `json-canvas` — required before direct `.canvas` JSON work.402. `obsidian-markdown` — required before writing Obsidian-facing Markdown.413. `obsidian-cli` — optional; only when interacting with a running Obsidian vault.424. `software-delivery-workflows` or `task-pr-flow` — when the Canvas/docs update is tied to code delivery, branches, PRs, or validation gates.4344Default: use the bundled CLI first for Canvas/status/evidence operations. Direct JSON edits are allowed only when the CLI cannot express the operation.4546## Hard Rules47481. Do not discard useful project documentation. Keep relevant docs current when code, architecture, run/validation, API contracts, or operational procedures change.492. Do not create redundant or ephemeral status-document sprawl. Temporary progress/status/handoff docs are allowed only when explicitly canonical for that project or requested by the user.503. README must be a contract and doc index, not a long progress log.514. `Project.canvas` is the human-facing cognition map, not the sole source of project knowledge.525. Every completion claim needs concrete evidence: command output, CI link, commit, screenshot, trace, benchmark, or manual observation.536. Agent may transition tasks to `Verify`; agent may not transition to `Done` without a concrete Evidence Card and explicit gate text from a human or named verification script.547. Prefer CLI operations over hand-editing Canvas JSON:55 ```bash56 python3 <skill>/scripts/project_canvas_os.py status <repo>57 python3 <skill>/scripts/project_canvas_os.py docs <repo>58 python3 <skill>/scripts/project_canvas_os.py add-task <repo> --title "..."59 python3 <skill>/scripts/project_canvas_os.py add-evidence <repo> --task "..." --test "..." --set-task-verify60 python3 <skill>/scripts/project_canvas_os.py transition <repo> --task "..." --state Done --gate "human confirmed"61 ```628. Canvas and relevant docs should be committed with code when the code changes project understanding.6364## Documentation Layer6566Docs are allowed and expected when they help agents understand or operate the project.6768Good docs:6970```text71README.md72AGENTS.md / CLAUDE.md / .agents/*.md73docs/architecture.md74docs/domain.md75docs/api.md76docs/testing.md77docs/runbook.md78docs/adr/*.md79docs/protocols/*.md80```8182Bad docs:8384```text85duplicate summaries86stale implementation notes87unowned progress logs88status files that contradict Project.canvas89handoffs with no durable facts90```9192Rule: if a document describes durable project knowledge, keep it current. If it only describes transient state, prefer `Project.canvas` + Evidence.9394## Best-Practice Operating Loop9596### Start of work97981. Read `README.md` as the contract/index.992. Read the relevant docs linked from README or discovered by:100 ```bash101 python3 <skill>/scripts/project_canvas_os.py docs <repo>102 ```1033. Inspect the human map:104 ```bash105 python3 <skill>/scripts/project_canvas_os.py status <repo>106 python3 <skill>/scripts/project_canvas_os.py validate <repo> --strict107 ```1084. Pick a task from `Active`, or propose a small `Proposed` task.1095. Check dependencies, docs, risk, and evidence edges before coding.110111### End of work1121131. Run the real validation for the code/workflow.1142. Update relevant docs if the change affects architecture, domain terms, public API, setup, validation, runbooks, or agent rules.1153. Add/update an Evidence Card with exact result text:116 ```bash117 python3 <skill>/scripts/project_canvas_os.py add-evidence <repo> \118 --title "<short evidence>" \119 --task "<task title/id>" \120 --test "<command + result>" \121 --artifact "<path/url or none>" \122 --set-task-verify123 ```1244. Add Risk Card if anything is unverified, flaky, blocked, undocumented, or assumed.1255. Update Module/Decision cards for human comprehension when durable relationships changed.1266. Audit docs and Canvas:127 ```bash128 python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --docs-strict129 ```1307. Report changed code, docs, Canvas state, validation output, and remaining uncertainty.131132## Canvas Role133134Canvas is for fast human orientation. Keep it spatial, short, and connected.135136Use five stable regions:137138| Region | Purpose |139|---|---|140| Goal | intent and success condition |141| System Structure | module/data/agent relationships; link key docs as file nodes when useful |142| Current Work | Proposed/Active/Verify/Blocked/Done tasks |143| Evidence | concrete proof handles |144| Risks & Decisions | open uncertainty and durable choices |145146Do not put long explanations in Canvas. Put durable explanations in docs and link them from README/Canvas.147148## Card Types149150Use only these six text-card types unless the user explicitly extends the protocol:151152| Card | Purpose |153|---|---|154| Goal | objective and success condition |155| Module | system module, data flow, agent flow, major interface |156| Task | executable work item |157| Evidence | hard proof for task/module/decision |158| Risk | uncertainty, blocker, missing proof, missing docs, operational risk |159| Decision | durable choice with rationale and impact |160161Use Canvas `file` nodes for important docs when a visual link improves human comprehension; do not invent a separate Document Card type unless the project explicitly needs it.162163## State Model164165| State | Meaning | Agent can set? | Color |166|---|---|---:|---|167| Proposed | suggested, not approved | yes | `"6"` |168| Active | approved/current work | yes, if instructed or already active | `"5"` |169| Verify | implementation claims complete, evidence attached | yes | `"3"` |170| Done | accepted by human or named verification gate | only with explicit gate | `"4"` |171| Blocked | dependency, evidence, or required-doc update missing | yes | `"1"` |172173`Done` requires both:174175```text176concrete Evidence Card177Gate: <human/script confirmation>178```179180## CLI First181182Primary script:183184```text185scripts/project_canvas_os.py186```187188Useful commands:189190```bash191python3 <skill>/scripts/project_canvas_os.py init <repo> --name "<Project>" --goal "<Goal>"192python3 <skill>/scripts/project_canvas_os.py docs <repo>193python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --docs-strict --list-docs194python3 <skill>/scripts/project_canvas_os.py validate <repo> --strict195python3 <skill>/scripts/project_canvas_os.py status <repo>196```197198Compatibility validator:199200```text201scripts/validate_project_canvas.py202```203204Use `references/cli-reference.md` for full commands.205206## Initialization207208For a repo without this system:209210```bash211python3 <skill>/scripts/project_canvas_os.py init <repo> --name "<Project>" --goal "<Goal>"212python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --list-docs213```214215This creates:216217```text218README.md219Project.canvas220.agents/canvas-protocol.md221```222223Then keep or create only docs that are useful to agents and link key docs from README.224225## Scaling Rules226227Escalate only when the file-level system is insufficient:2282291. Native Markdown docs + Canvas + CLI — default.2302. Sub-canvas/file nodes — when one canvas exceeds roughly 50 cards or one module needs its own map.2313. Obsidian Advanced Canvas — when folding/focus/navigation becomes the bottleneck.2324. Bases — only for hidden indexes like all `Verify` tasks, open risks, or docs inventory; not the daily entrypoint.2335. MCP/REST — only when multiple independent agents need concurrent vault access with policy enforcement.234235## Validation Gate236237Before final response after any Canvas/docs change:238239```bash240python3 <skill>/scripts/project_canvas_os.py validate <repo> --strict241python3 <skill>/scripts/project_canvas_os.py audit <repo> --strict --docs-strict242python3 -m json.tool <repo>/Project.canvas >/dev/null243git -C <repo> diff --check244python3 <skill>/scripts/test_project_canvas_os.py -v # when editing the skill itself245```246247For codebase sessions with an external coding gate, also run the cheapest relevant repository script that can see the checkout, usually lint/typecheck/test.248249Checks include:250251- JSON parses.252- Node/edge IDs unique.253- Edges reference real nodes.254- Task states are valid.255- `Verify`/`Done` tasks have concrete evidence.256- `Done` has explicit gate text when transitioned through CLI.257- Markdown docs are inventoried and classified as contract/knowledge/other/state.258- Stale/deprecated doc markers are reported; `--docs-strict` fails on them.259- Key knowledge docs not referenced by README or Canvas are reported as discoverability warnings.260261## Linked Files262263- `scripts/project_canvas_os.py` — primary zero-dependency CLI.264- `scripts/validate_project_canvas.py` — validation compatibility wrapper.265- `scripts/test_project_canvas_os.py` — skill self-tests.266- `templates/README.md` — minimal project contract and docs index template.267- `templates/Project.canvas` — five-region starter canvas.268- `references/canvas-protocol.md` — repo-local agent protocol for `.agents/canvas-protocol.md`.269- `references/operating-model.md` — full operating model and escalation rules.270- `references/cli-reference.md` — command reference and examples.271- `references/adoption-checklist.md` — checklist for converting an existing repo.272- `references/documentation-hygiene.md` — rules for current, non-redundant Agent knowledge docs.273274## When Not To Use275276Do not use this skill for:277278- Replacing GitHub/Linear lifecycle systems.279- Long-form research notes unrelated to a project.280- General wiki design with no project execution loop.281- Projects where the user explicitly wants conventional documentation only.282- Obsidian plugin development itself; use Obsidian-specific skills directly.