work-pdca-loop

# Work PDCA Loop Use this skill for repo-local `work/` task folders that must be easy to sort, resume, audit, visualize, and hand off. This is not a static template. It models work as a PDCA loop: 1. `Plan`: frame objective, constraints, acceptance, and decision criteria. 2. `Do`: execute the smallest tracer path that can produce evidence. 3. `Check`: compare evidence against acceptance, risks, and regressions. 4. `Act`: close, continue, or pivot based on recorded decisions. Execution must not be purely linear. Decision points such as `D1` and `D2` determine whether to continue, split, research, pivot, or close. ## Directory Rule Use this folder shape: ```text work/YYYYMMDD-short-slug/ ``` Examples: ```text work/20260706-dyncode-sync-event-listener-goal/ work/20260706-cache-projection-research/ ``` Rules: - `YYYYMMDD` is an eight-digit date. - Prefer the date when the task folder is created. - Preserve historical dates when existing state or docs prove them. - Use lowercase kebab-case for the slug. - Do not create undated `work/<slug>/` folders for new work. ## Required Files Every PDCA goal-loop folder should contain: ```text task.md pdca.md decisions.md prompt.md state.json history/events.jsonl history/state/*.json ``` Meanings: - `task.md`: objective, scope, out-of-scope, acceptance. - `pdca.md`: cycle stage intent and evidence. - `decisions.md`: human-readable decision map. - `prompt.md`: restart instructions. - `state.json`: current machine-readable state. - `history/state/*.json`: archived snapshots before each state change. - `history/events.jsonl`: append-only state change log. ## State Contract `state.json` should include these core fields. Extra task-specific fields are allowed. ```json { "schema_version": "work-pdca-loop.v1", "project_root": "", "work_dir": "", "title": "", "objective": "", "status": "in_progress", "mode": "pdca_goal_loop", "pdca": { "cycle": 1, "stage": "plan", "stages": [] }, "current_phase": "P0", "created_at": "", "updated_at": "", "owner": "codex", "scope": [], "tags": [], "ssot": [], "inputs": [], "outputs": [], "phases": [], "decision_points": [], "validation": { "passed": false, "commands": [], "notes": "" }, "history": { "state_snapshots": "", "events": "" }, "risks": [], "next_action": "", "notes": "" } ``` Recommended `status` values: `planned`, `in_progress`, `completed`, `withdrawn`, `blocked`. Recommended `pdca.stage` values: `plan`, `do`, `check`, `act`. ## Decision Points Decision points are first-class state, not prose only. Example shape: ```json { "id": "D1", "phase": "D1", "question": "Which route should the next implementation take?", "status": "open", "options": [ { "id": "direct", "label": "Direct implementation", "next_phase": "P2", "criteria": "Scope is clear, blast radius is small, and validation path is known." } ], "selected_option_id": null, "rationale": "", "decided_at": null } ``` Do not move past a decision phase without recording: - selected option - rationale - next phase - timestamp ## Generator Prefer the bundled PDCA generator for new folders: ```bash bun ~/.agents/skills/work-pdca-loop/scripts/create-pdca-goal.mjs \ --project-root /path/to/project \ --work-root work \ --slug dyncode-sync-event-listener-goal \ --title "Dyncode Sync Event Listener Goal" \ --objective "Design and implement sync table listener registration." \ --date 20260706 ``` Package script form inside this skill directory: ```bash bun run create -- --project-root /path/to/project --work-root work --slug dyncode-sync-event-listener-goal --title "Dyncode Sync Event Listener Goal" --objective "Design and implement sync table listener registration." ``` The script fails if the target folder already exists. It creates required files, an initial `state.json`, an initial state snapshot, and a creation event. ## State Updates Do not edit `state.json` by blind overwrite when changing status. Use the update script so old state is archived first. ```bash bun ~/.agents/skills/work-pdca-loop/scripts/update-pdca-state.mjs \ --work-dir /path/to/project/work/20260706-dyncode-sync-event-listener-goal \ --status in_progress \ --phase D1 \ --pdca-stage check \ --next-action "Select implementation route after evidence review." \ --event "phase_changed" ``` Select a decision branch: ```bash bun ~/.agents/skills/work-pdca-loop/scripts/update-pdca-state.mjs \ --work-dir /path/to/project/work/20260706-dyncode-sync-event-listener-goal \ --decision-id D1 \ --select-option direct \ --rationale "Scope is clear and validation command is known." \ --pdca-stage check \ --event "decision_selected" ``` Update behavior: 1. Read current `state.json`. 2. Archive it to `history/state/<timestamp>.json`. 3. Apply requested changes. 4. Atomically write new `state.json`. 5. Append event to `history/events.jsonl`. ## Status Web UI (Solid.js) Build the Solid dashboard once, then run the Bun server (serves `webui-solid/dist`): ```bash bun run webui:build bun run webui -- --project-root /path/to/project --work-root work --port 8787 ``` Open `http://127.0.0.1:8787`. Development (API + Vite，推荐一条命令): ```bash bun run webui:dev -- # 或指定项目根：PDCA_PROJECT_ROOT=/path/to/project bun run webui:dev ``` `webui:dev` 会同时启动 Bun API（默认 8787）并把 Vite 5173 的 `/api` 代理过去。**不要**只跑 `cd webui-solid && bun run dev`，否则 `/api/decisions/open` 会 404。 手动双终端： ```bash bun run webui -- --project-root /path/to/project --port 8787 WEBUI_API_PORT=8787 bun run webui:dev:vite-only ``` The console scans `work/*/state.json` and provides: - overview KPIs, PDCA stage board, TanStack task table - decision inbox and cross-task timeline (`history/events.jsonl`) - task workbench: phases, decisions, events, snapshots, markdown files (read-only) - project switching via Settings (`projectRoot` / `workRoot` query + localStorage) - light/dark theme REST: `/api/workspaces` (GET/POST/DELETE), `/api/status`, `/api/decisions/open`, `/api/timeline`, `/api/tasks/{workDir}`, … **多工作区：** CLI（`create` / `update`）与 `webui` 启动时会注册 `projectRoot+workRoot` 到 `~/.config/work-pdca-loop/workspaces.json`；控制台顶栏可切换。环境变量 `WORK_PDCA_REGISTRY` 可改注册表路径。 Project paths may use `~`. Passing `/path/to/project/work` is normalized to project root plus `workRoot=work`. Custom state schemas still work when compatible fields exist (`objective`, `current_phase`, `phases`, `decision_points`, validation). ## Maintenance Checklist - Keep `state.json.status`, `state.json.pdca.stage`, and `state.json.next_action` current. - Use `update-pdca-state.mjs` for state changes so history is preserved. - Record validation commands after they run. - Record decision option and rationale before crossing decision phases. - Update references when a folder is renamed. - When a task is withdrawn, keep `status: "withdrawn"` and explain why. - Do not mark a broad goal complete unless current evidence proves all required work.