intuitive-flow

An opinionated operating model for agent-written software.

intuitive-flow is a portable workflow kit for Claude Code and Codex. It keeps the human surface small, puts reusable workflows in skills, and gives each repo local CLAUDE.md / AGENTS.md guidance instead of a copied process manual.

From Ultrathink to Goal - A Year of AI Coding Engineering The interactive slide deck behind this kit · 中文

Why This Exists

AI agents write all my code, so the repo needs two surfaces.

The human surface should stay tiny: README.md, ARCHITECTURE.md, STATUS.md, and docs/human/**. This is where I decide what the project is, what good means, and what must not break.

Everything else is agent territory: source code, plans, logs, generated evidence, retrospectives, scratch work, and low-level churn. Humans can inspect it when something is risky or broken. They should not have to live there.

intuitive-flow exists to make the counter-pressure explicit. AI coding changes the default shape of a repo: agents are good at adding code, tests, plans, logs, and helper surfaces, but they are less likely to stop and ask whether the repo became easier to understand.

The first job is maintenance through entropy reduction. A repo needs regular passes that remove stale surfaces, merge duplicate guidance, clean known seams, realign docs with code, and make the next human or agent less surprised.

The second job is deliberate feature development. New work should not jump straight from idea to implementation when the scope is fuzzy. It should become a plan, get challenged against the repo's language and boundaries, turn into an execution contract, and only then be implemented and verified.

See BELIEFS.md for the doctrine behind this workflow.

The operating bias is deliberately small:

• Less is more.
• Codex, Claude Code, similar harnesses, and models will keep evolving; refresh skills against them.
• Prefer community best practices when they survive local review.

Choose A Path

Start by choosing the kind of work:

Work	Route
Shape an unsettled product bet	$intuitive-shape, then choose a planning or execution route
Maintain or simplify a repo	$intuitive-reduce-entropy in repo entropy mode, then route selected cleanup to the owning skill and verify it
Clean a known target	$intuitive-refactor for a selected module, seam, stale API, or architecture target
Research a question that needs multiple sources or competing claims reconciled	$research for evidence-led investigation with traceable sources and explicit confidence
Build a feature with unresolved scope or risk	$intuitive-preflight, using plan entropy, planning scouts, or grill-batch only when the contract needs them, then $intuitive-flow
Challenge an existing agent proposal	$cross-review for a bounded second opinion, then stop or route only the accepted recommendation
Align multiple planning perspectives	$agent-planning-loop -> $intuitive-preflight -> $intuitive-flow
Do a tiny bounded task	$intuitive-flow directly, when the change is local and easy to verify
Clean up noisy local history before handoff	$intuitive-squash, after its preflight checks pass