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:

work/YYYYMMDD-short-slug/

Examples:

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:

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.

{
  "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:

{
  "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:

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:

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.

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:

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):

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，推荐一条命令):

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。

手动双终端：

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.