Models matter. Context matters more.
POCDD builds a complex feature by first owning it in one self-contained file
under .pocs/ — the prompt, the spec, and the handoff in a single artifact.
An agent shapes that file by closing gaps until nothing blocks the goal, then
the proven result is implemented into the product.
The full methodology and philosophy live in spec/POCDD.md. The
operational contract every sub-skill relies on lives in
shared/conventions.md. Read both before acting.
The model in one breath
/poc SOURCE → [ /poc work : close gaps in a loop ] → /poc implement → /poc archive | /poc remove
A POC file has exactly three sections — Goal, Implementation,
Remaining gaps — and a phase: header. It is done when Remaining gaps is
empty. Decisions the agent can't make become [user] gaps and never stop
execution.
Routing — the /poc command surface
Map the developer's intent (or an explicit /poc … invocation) to one sub-skill:
| Intent / invocation | Sub-skill | Folder |
|---|---|---|
"start a POC for X", /poc <SOURCE> |
pocdd-create | create/ |
"work the POC", "close the gaps", /poc work <name> |
pocdd-work | work/ |
"what's the status of ", /poc status <name> |
pocdd-status | status/ |
"list pocs", /poc list |
pocdd-list | list/ |
"implement ", /poc implement <name> |
pocdd-implement | implement/ |
"archive ", /poc archive <name> |
pocdd-archive | archive/ |
"remove ", /poc remove <name> |
pocdd-remove | remove/ |
"clear pocs", /poc clear |
pocdd-clear | clear/ |
"validate ", /poc verify <name> |
pocdd-verify | verify/ |
Parsing rule (resolve ambiguity)
The reserved subcommands — create, work, status, list, implement,
archive, remove, clear, verify — always take precedence. Anything else
after /poc is treated as a SOURCE for creation:
/poc list→ list./poc work calendar→ work thecalendarPOC./poc "add holidays sync"→ create a new POC from that source./poc https://provider.dev/docs→ create from that URL.
(Bare /poc create <SOURCE> is also accepted and routes to pocdd-create.)
Where POCs live
All POC files live under .pocs/ at the repo root — gitignored in its
entirety. Resolve the directory with shared/context.sh
(POCS_DIR overrides the default). Never write POC files anywhere else, and never
commit .pocs/.