workflow

A skill for AI-assisted multi-session projects. Keeps state, events, and tasks separated so any agent (Claude Code, Cursor, Aider, …) can pick up where the last one left off.

---

Features

Event / state dual-track

• Events (append-only) live in JOURNAL.md — one entry per decision, failure, or verified result, with 現象 / 原因 / 處理 / 驗證 + quantified acceptance + PPT bullet + output files + tags.
• State is projected from events into CHECKPOINT.md (now), TASKS.md (next), PROJECT_STATE.md (overview), experiments/INDEX.md (tag/file reverse index).
• snapshot_state.py is a reducer — state can always be rebuilt from events.

Phase-based archival

• Continuous event numbering across the whole project (#1 … #N, never reset).
• When a phase ends, the active JOURNAL.md is renamed to experiments/phaseN_<name>.md and a fresh journal is opened.
• Nothing is overwritten; full history stays greppable.

Bundled ppt-master skill

• harvest_to_ppt.py greps every event's PPT bullet + output files and builds a deck scaffold.
• The ppt-master skill under skills/ppt-master/ is vendored from hugohe3/ppt-master — credit to the original author.

Dynamic model switching

• Two-axis policy: phase × criticality.
• 🔴 contract / core algorithm / schema → Opus
• 🟡 glue / CRUD / iteration → Sonnet
• 🟢 rename / lint / move files → Haiku
• CHECKPOINT.md:next_model_suggested persists the decision across sessions.

Workspace isolation

• Default --isolated mode: all workflow artifacts live under <project>_workflow/, existing files untouched.
• Also supports --flat (everything at root) and --partial (only experiments/ + _ppt_workspace/ isolated).

Mid-project adoption

• init_project.py --adopt scans existing notes.md / todo.md / 實驗記錄.md / CLAUDE.md.
• Suggests: archive legacy logs to experiments/phase1_legacy_*.md, convert todos to TASKS.md, inject # @workflow marker at top of existing CLAUDE.md.
• Every action is opt-in, per-item; nothing is overwritten without confirmation.

Change detection

• detect_changes.py maintains .workflow_snapshot.json (hash + mtime per file).
• Next time the agent starts, it reports files modified outside of an event — so the agent can ask "want to log an event for this?" instead of drifting.

Reverse index (RAG-ish)

experiments/INDEX.md is auto-maintained by log_experiment.py:

• Tags → events — "how did we handle #aws last time?"
• Files → events — "what changed clean_202603.py and why?"

Agent-agnostic

• Pure Python + pure Markdown + YAML frontmatter as the cross-agent contract.
• Claude Code, Cursor, Aider, Roo, Codex CLI, Gemini CLI, plain chat — all work. See AGENT_COMPAT.md.

---

Install

git clone https://github.com/377LAI/workflow.git D:/p/workflow

No pip install needed — everything is stdlib Python.

Usage

New project:

python D:/p/workflow/scripts/init_project.py <path> --type data_analysis

Existing project (mid-project adoption):

python D:/p/workflow/scripts/init_project.py <path> --adopt --isolated

Log an event:

python D:/p/workflow/scripts/log_experiment.py . \
  --title "Lambda IP blocked" \
  --phenomenon "..." --cause "..." --action "..." --verify "..." \
  --tags "#aws,#network-block" --artifacts "cloud/smoke_test.py"

See QUICKSTART.md for the full 80-line walkthrough.

Docs

• SKILL.md — skill metadata + activation protocol
• QUICKSTART.md — five-minute hands-on
• AGENT_COMPAT.md — non-Claude agent support
• workflows/ — six-stage playbooks (bootstrap → explore → build → harvest → present → handoff)
• references/ — deep dives: checkpoint discipline, adoption guide, model policy, experiment log discipline, token saving, plan mode, skill composition, claude.md recipes

When not to use

• One-off edits (typo, one-line fix) — overhead isn't worth it.
• Exploratory spikes — finish the spike, then adopt.
• Very large projects (> 10 sub-modules with hierarchy) — v0.2 is still single-level; hierarchical workflows land in v1.0.

Changelog

v0.3.0

• Model guardian — log_experiment.py now requires --model <id>; auto-writes model_in_use to CHECKPOINT on every event. checkpoint.py compare / status --strict detect drift and return exit 10. model_guard.py prints a drift banner on startup; wired into PostToolUse hook so every Edit/Write also checks. Activation Protocol step 4 is now MANDATORY.
• brief.py — one-shot boot context: CHECKPOINT status + current tasks + last 3 events + drift flag in < 1 KB. Replaces reading three files on startup. Activation Protocol step 1 updated.
• token_stats.py — quantified token accounting for all workflow state files. Auto-detects _workflow/ and _internal_experiments/ layouts. Configurable threshold (default 3000); exits 11 with TOKEN BLOAT warning when exceeded.
• token_saving_playbook.md — principles 1 and 8 marked ✅ v0.3 landed; v0.4 candidates listed; new "量化追蹤" section documents token_stats.py usage.

v0.2.0

• Event/state dual-track system (state = fold(events))
• detect_changes.py + .workflow_snapshot.json for out-of-band change detection
• adopt_existing.py for mid-project adoption (merge-not-overwrite)
• Phase-based archival; experiments/INDEX.md reverse index
• AGENT_COMPAT.md for non-Claude agent support

v0.1.0

• init_project.py scaffold generation (isolated / flat / partial modes)
• log_experiment.py append-only event log with 現象/原因/處理/驗證 + PPT bullets + tags
• snapshot_state.py state rebuilder
• harvest_to_ppt.py + bundled ppt-master skill

---

Credits

• ppt-master by hugohe3 — vendored into skills/ppt-master/.
• Extracted from the TDCS traffic-analysis final-presentation project dogfood (2026-04).

License

MIT