Composable · Evidence-first · Human-guided · Reality-verified
Turn capable coding agents into disciplined engineering collaborators.
Quick start · User guide · Concepts · Case study · Contributing
Modern coding agents can read repositories, edit files, run tools, and generate large amounts of code. The harder problem is not raw capability—it is engineering discipline.
PraxFlow is an opinionated methodology for AI agents, distributed as portable Agent Skills. It helps agents decide:
- what to investigate before acting;
- which claims need evidence;
- what the agent should resolve itself and what needs human judgment;
- how to bound a change before editing;
- how to diagnose failures without locking onto the first plausible explanation;
- what verification is strong enough to support a completion claim;
- what project knowledge is stable enough to preserve.
PraxFlow is not a new agent runtime, a new Skill format, or a generic prompt collection.
The goal is not to make an agent do more. The goal is to make the work it does more reliable.
For most users:
npx skills@latest add hamburger-os/PraxFlowChoose the Workflows, reusable cognitive Skills, optional Domain Packs, and target coding agents you want.
If you already know what you need:
npx skills@latest add hamburger-os/PraxFlow \
--skill develop-feature \
--skill survey \
--skill trace \
--skill grill \
--skill plan-change \
--agent codex \
--yesGitHub CLI also provides Agent Skill installation:
gh skill install hamburger-os/PraxFlowRead Getting Started for package selection, installation options, usage examples, expected behavior, and limitations.
PraxFlow separates methodology from environment execution:
flowchart TD
G[User goal] --> W[Workflow]
W --> S[Reusable cognitive Skills]
P[Protocols] -. constrain .-> W
P -. constrain .-> S
S --> C[Project capabilities]
C --> E[External evidence]
E -->|feedback| W
| Concept | Meaning |
|---|---|
| Workflow | An end-to-end cognitive loop for a class of goals. |
| Skill | A reusable cognitive method used by multiple Workflows. |
| Protocol | Cross-cutting rules for evidence, decisions, change scope, verification, and durable knowledge. |
| Capability | A concrete action supplied by the current project/environment, such as build, test, deploy, flash, browser, serial, or database access. |
The key separation is:
PraxFlow decides when and why an engineering action is needed. The project and agent environment decide how to perform it.
Read the full model in PraxFlow Concepts.
| Workflow | Use it for |
|---|---|
develop-feature |
New or materially changed behavior: understand → clarify/design → bound → implement → review → verify. |
fix-bug |
Incorrect behavior: expected vs observed → diagnose cause → causal repair → regression verification. |
understand-project |
Building only the evidence-backed project model needed for a stated understanding goal. |
review-change |
High-signal review grounded in intent, actual scope, contracts, evidence, and domain risks. |
| Skill | Core question |
|---|---|
survey |
Where should I look first, and how far should I explore? |
trace |
How exactly does this behavior happen across calls, data, state, and lifecycle? |
grill |
What can the agent resolve itself, and what consequential choice genuinely needs the user? |
diagnose |
Which causal explanation best fits the evidence, and how can alternatives be distinguished? |
plan-change |
What is the smallest causal change boundary that addresses the goal? |
plan-change is intentionally provisional in v0.1 and may be removed if evaluation shows that it adds little beyond ordinary agent planning.
evidence— separate observations, sources, inferences, assumptions, unknowns, and conflicts.decisions— investigate before asking; escalate consequential decisions.change-scope— prefer the smallest causal change, not merely the smallest diff.verification— match verification strength and cost to risk and claim strength.knowledge— persist stable reusable knowledge, not transient reasoning history.
praxflow-embedded is the first reference Domain Pack. It adds embedded-specific evidence, review, and verification policy without copying the Core Workflows.
It covers concerns such as authoritative hardware references, ISR/thread boundaries, DMA/cache coherency, alignment, ABI, memory lifetime, timing, error paths, and target-level verification.
See the qualitative reference case: MCP2518FD on RT-Thread.
An Agent Skill is a directory containing at minimum:
skill-name/
└── SKILL.md
The open specification also defines conventional optional resources such as scripts/, references/, and assets/, while permitting additional files.
PraxFlow chooses this canonical repository source layout:
skills/<package-name>/SKILL.md
That flat skills/ catalog is a PraxFlow distribution convention. The Agent Skills specification does not require every repository to use a top-level skills/ directory, and it does not mandate one universal client installation path.
Workflow / Skill / Domain Pack is PraxFlow conceptual metadata (metadata.praxflow-type), not path-depth semantics.
PraxFlow also does not add a human README to every Skill package by default. Human concepts, tutorials, and usage guides live under docs/; package-local references/ exist for material agents need to load during execution.
- Getting Started / 入门与使用 — principles, package selection, installation, usage, expected behavior.
- Concepts / 核心概念 — the full conceptual model and package-format boundaries.
- Roadmap / 路线图 — current scope and evaluation direction.
- Client adapters — installation paths and client compatibility boundaries.
- Evals — methodology evaluation framework.
- Case studies — inspectable engineering evidence.
Maintainer-operational documents such as release procedure, repository settings, and brand guidance are written primarily in Simplified Chinese because the repository currently has one primary maintainer. AI-facing instructions and portable Skill package content remain English-first for agent portability.
python3 scripts/validate.pyCI also runs the pinned Agent Skills reference validator, distribution and installer smoke tests, and Protocol/package synchronization checks.
PraxFlow is pre-1.0. v0.1 is a testable baseline, not a frozen standard.
The current priority is to evaluate the four Core Workflows on real engineering tasks and use observed failures to refine—or remove—abstractions. See Roadmap.
Contributions are welcome, especially when they include evidence from real usage.
CONTRIBUTING.md— contribution, package, and documentation rules.CODE_OF_CONDUCT.md— community expectations.SECURITY.md— vulnerability reporting.CHANGELOG.md— project history.
Before proposing a new Core Skill, ask whether it represents a genuinely reusable cognitive method or merely another verb that a capable agent already knows how to perform.