# Work PDCA Loop
Repo-local **PDCA goal loops** for coding agents: structured `work/` folders, auditable `state.json` history, decision gates, and a **Solid.js** developer console.
> Not more process — **recoverable working memory** after context loss, handoffs, and branching work.
## Features
| Capability | What you get |
|------------|----------------|
| **CLI** | Create goals, update state with snapshots + `events.jsonl` |
| **Decision points** | D1/D2 branches in machine-readable state, not prose-only |
| **Multi-workspace** | CLI / webui auto-register repos to `~/.config/work-pdca-loop/workspaces.json` |
| **Web console** | Focus queue, task workbench, decisions inbox, timeline, read-only UI |
| **Agent skill** | `SKILL.md` for Pi / Claude Code style agents |
## Requirements
- [Bun](https://bun.sh) 1.1+
## Install
Clone or copy into your agent skills path, e.g.:
```bash
git clone https://github.com/Dwsy/work-pdca-loop.git ~/.agents/skills/work-pdca-loop
cd ~/.agents/skills/work-pdca-loop
bun run webui:build # first time: builds Solid UI
```
Use as an agent skill: point your harness at `SKILL.md` (name: `work-pdca-loop`).
## Quick start
### 1. Create a PDCA goal (in any repo)
```bash
bun ~/.agents/skills/work-pdca-loop/scripts/create-pdca-goal.mjs \
--project-root /path/to/your-repo \
--work-root work \
--slug my-feature \
--title "My Feature" \
--objective "Ship X with evidence."
```
Creates:
```text
work/YYYYMMDD-my-feature/
task.md pdca.md decisions.md prompt.md
state.json
history/events.jsonl
history/state/*.json
```
Also **registers** `projectRoot + workRoot` for the web console.
### 2. Update state (never blind overwrite)
```bash
bun ~/.agents/skills/work-pdca-loop/scripts/update-pdca-state.mjs \
--work-dir /path/to/your-repo/work/YYYYMMDD-my-feature \
--pdca-stage do \
--next-action "Implement tracer path and run tests." \
--event phase_changed
```
Record a decision:
```bash
bun ~/.agents/skills/work-pdca-loop/scripts/update-pdca-state.mjs \
--work-dir .../work/YYYYMMDD-my-feature \
--decision-id D1 \
--select-option direct \
--rationale "Scope clear; validation command known." \
--event decision_selected
```
### 3. Web console
**Production (API + built UI, one port):**
```bash
cd ~/.agents/skills/work-pdca-loop
bun run webui -- --project-root /path/to/your-repo --work-root work --port 8787
# http://127.0.0.1:8787
```
**Development (API + Vite HMR):**
```bash
bun run webui:dev
# API :8787, UI http://localhost:5173 (proxies /api)
```
Optional env:
- `PDCA_PROJECT_ROOT` — default project for dev script
- `WORK_PDCA_REGISTRY` — override workspace registry path
## Work folder contract
`state.json` (schema `work-pdca-loop.v1`) holds status, PDCA stage, phases, `decision_points`, `next_action`, validation, etc.
Updates via `update-pdca-state.mjs` always:
1. Archive previous state → `history/state/<timestamp>.json`
2. Write new `state.json`
3. Append → `history/events.jsonl`
## Web UI routes
| Route | Purpose |
|-------|---------|
| `/` | Command center: focus queue + task list |
| `/decisions` | Open decision gates across workspace |
| `/timeline` | Recent events across tasks |
| `/tasks/*workDir` | Task workbench (phases, docs, audit) |
| `/settings` | Manage / add workspaces |
## HTTP API
| Method | Path |
|--------|------|
| GET | `/api/workspaces` |
| POST | `/api/workspaces` |
| DELETE | `/api/workspaces/:id` |
| GET | `/api/status?projectRoot=&workRoot=` |
| GET | `/api/decisions/open` |
| GET | `/api/timeline` |
| GET | `/api/tasks/{workDir}` |
| GET | `/api/tasks/{workDir}/events` |
| GET | `/api/tasks/{workDir}/snapshots` |
| GET | `/api/tasks/{workDir}/files/{task.md\|pdca.md\|...}` |
| GET | `/healthz` |
UI is **read-only**; writes go through CLI scripts.
## Project layout
```text
work-pdca-loop/
SKILL.md # Agent skill entry
README.md
package.json # bun run create | update | webui | webui:build | webui:dev
packages/shared/ # dashboard + workspace registry
scripts/ # CLI + webui-server + dev-webui
webui-solid/ # Vite + Solid.js console
docs/ # design notes
webui/index.html # legacy fallback if dist not built
```
## npm-style scripts
```bash
bun run create -- --project-root ... --slug ...
bun run update -- --work-dir ...
bun run webui -- --project-root ... --port 8787
bun run webui:build
bun run webui:dev
```
## When to use
**Good fit:** long-running tasks, multi-agent handoff, branching (research / pivot / split), audit trail, local status board.
**Skip:** one-line fixes, throwaway notes, no state tracking needed.
## Design principle
Treat work as **Plan → Do → Check → Act**, with explicit **decision points** before crossing risky branches. Agents resume from `prompt.md` + `state.json` + history; humans scan the console.
## License
MIT — see [LICENSE](LICENSE).
## Author
[Dwsy](https://github.com/Dwsy)