No single truth source
Semantics drift across docs, prompts, and implementation.
Response: converge on one machine-readable truth source first.
Built for Claude Code workflow authors
Running once is easy. Running well over time is the hard part.
Many workflows look impressive for the first few runs. Then the familiar problems appear: target files get overwritten, steps get skipped, failures cannot be replayed, and lessons never feed into the next run.
WorkflowProgram exists to solve those engineering problems directly. It treats a workflow as a product with a truth source, a control plane, a validation layer, and a feedback loop.
One complete run
request
spec
candidate
managed apply
run
verdict
lessons
The four core beliefs
- Use one machine-readable source of truth
- Separate design, execution, judgment, and feedback
- Never write directly into the target project without control
- Every run must leave structured evidence behind
Step 1: See the failure modes
Eight workflow problems WorkflowProgram is designed to solve
Order depends on model memory
One run follows the intended sequence, the next skips or repeats steps.
Response: move critical sequencing into deterministic programs.
Direct writes damage the target project
Conflicts are hard to recover and user-maintained files get overwritten.
Response: generate candidates first, then apply changes in a managed way.
Failures are hard to localize
You know the run failed, but not whether design, execution, or judgment was wrong.
Response: split design, execution, judgment, and evidence capture into different layers.
Evidence is incomplete
There is no state, event, or report trail to replay what happened.
Response: persist a minimum structured evidence bundle for every run.
Validation only checks exit codes
"Finished" is treated as "correct".
Response: separate runtime constraints, test constraints, and final verdict logic.
Lessons never feed back
The same mistakes repeat because they live only in chat history.
Response: separate per-run lessons from long-lived constraints.
Natural-language entry is unstable
Similar requests route to different skills and produce different behavior.
Response: detect intent and route before entering the main flow.
Step 2: Understand the design
A workflow is not one big prompt. It is four layers with different jobs.
Truth Source
Behavior starts from one machine-readable source of truth. Human-facing guides come later.
Control Plane
Programs own transitions, boundaries, and evidence. The model works inside steps, not between them.
Validation Layer
The generator should not be its own judge. Verdicts are produced independently from evidence.
Feedback Loop
Per-run lessons and long-lived rules are different things. Both are needed.
Step 3: Draw the boundaries
Why `PLUGIN_ROOT`, `TARGET_ROOT`, and `RUN_ROOT` must stay separate
`PLUGIN_ROOT`
The source of capabilities: skills, scripts, templates, and plugin payloads.
`TARGET_ROOT`
The user project that receives the final `.claude/` assets.
`RUN_ROOT`
The isolated workspace for one run: context, state, events, reports, and candidates.
Why this matters
Without these boundaries, you cannot tell what was input, what was output, and what was evidence.
Step 4: Split responsibilities
The `S0..S6` model separates route, design, apply, validation, and learning
`S0-S3`
Route the request, clarify requirements, explore context, and settle the machine-readable design.
`S4-S5`
Generate candidate assets, apply them safely, and validate the workflow verdict independently.
`S6`
Turn the run into lessons, constraint candidates, and the next improvement direction.
Step 5: Make sequencing deterministic
The main orchestration chain is a product entry flow, not a loose instruction sheet
Entry layer
Defines the fixed order of checks and execution steps.
Control layer
Advances state, enforces runtime constraints, and persists evidence.
Validation layer
Consumes evidence and gives the workflow-level verdict.
Current mapping
`workflow-entry.py` sequences the chain. `workflow-runner.py` governs execution. `workflowprogram-validate` and `workflow-s5-judge.py` produce the verdict.
Step 6: Route before acting
Entry routing is about choosing the main flow first, then leaving evidence for that choice
The design problem
Similar natural-language requests should not unpredictably land on different flows.
The current implementation
`workflowprogram-orchestrate` plus `route-intent.py` decide the intent and preserve route evidence before execution proceeds.
Step 7: Control target writes
Generated output and target-project writes are different operations
Safer pattern
Generate candidates first, classify changes, then apply them in a managed way.
Current mapping
`RUN_ROOT/outputs/candidate/`, `managed-change-plan.json`, `managed-change-result.json`, and `managed-files.json` preserve ownership and conflict evidence.
Step 8: Separate validation from generation
WorkflowProgram validates in layers
Execution constraints
May the run proceed in this form? Boundaries, enums, minimum evidence, and runtime rules live here.
Verdict
Does this run actually count as passing? This checks flow, artifacts, boundaries, and failure mapping.
Dynamic evidence
Did a real run leave enough evidence to support the verdict?
Step 9: Feed the next run
Lessons and constraints turn one run into future stability
`lessons.md`
Append-only history of failures, conflicts, and candidate constraints.
`constraints.md`
Long-lived ALWAYS/NEVER rules that new sessions can load directly.
`s6-lessons-delta.md`
The per-run delta that turns evidence into reusable guidance.
Step 10: Read the repository with the right map
The repository layout mirrors the product model
`README.md` / `README.en.md`
High-level orientation and quick-start usage.
`docs/`
Design truth sources, plans, and tutorials.
`.claude/scripts/`
Deterministic execution, validation, and control-plane tools.
`tools/`
Build and smoke-test tooling, including runtime harnesses.
`tests/`
Fixtures, expectations, and runtime transcripts.
Step 11: Start using it
Quick start in four commands
git clone https://github.com/Logic70/WorkflowProgram-CN
cd WorkflowProgram-CN
pip install pyyaml
python tools/build_plugin.pycd your-project
claude --plugin-dir /path/to/WorkflowProgram-CN/dist/plugin"Design a code review workflow for this project"
"Audit the workflow structure of this project"
"Validate the workflow assets in this project"Step 12: Go deeper
Read the chapter guide when you want the full explanation
English chapter guide
Read the full tutorial in chapter form, from failure modes to applying the pattern in your own project.
Open English chaptersChinese chapter guide
Switch back to the Chinese version if you want the original tutorial wording and examples.
Open Chinese chapters