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 · 中文
AI agents write all my code, so the repo needs two surfaces.
The human surface should stay tiny: README.md, ARCHITECTURE.md,
STATUS.md, docs/human/**, the layout, and the tests. 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.
The workflow makes big questions expensive and small questions cheap: use
office-hours or grill-me for what to build, $intuitive-flow for normal
development, and $intuitive-refactor to clean a system without drifting
forever. See BELIEFS.md for the full doctrine.
In the target repo, give your AI agent the skill file and ask it to initialize local guidance:
Read this skill:
https://github.com/MiaoDX/intuitive-flow/blob/main/skills/intuitive-init/SKILL.md
Then run:
Use $intuitive-init to initialize this repo's AGENTS.md and CLAUDE.md.
Run /init-style discovery if available.
Preserve project-specific instructions.
Propose a diff before applying.
Clone Intuitive Flow when you want the update scripts and local skill sync:
git clone --depth=1 https://github.com/MiaoDX/intuitive-flow.git ~/intuitive-flow
~/intuitive-flow/scripts/update.shintuitive-flow is both the project and the default development skill: this
repo defines the operating model, and $intuitive-flow runs it inside a target
repo.
| Skill | Use it for |
|---|---|
| intuitive-init | Merge /init suggestions, Intuitive Flow defaults, and repo evidence into local AGENTS.md / CLAUDE.md |
| intuitive-doc | Keep human-facing docs small, current, and separated from agent evidence/history |
| intuitive-layout | Improve repo/folder organization before deeper architecture work |
| intuitive-tests | Organize, prune, mark, and refactor tests around behavior |
| intuitive-flow | Move a fuzzy idea through plan review, GSD handoff, execution, cleanup, and verification |
| intuitive-refactor | Bound broad refactors with accepted severities, evidence, and a stop condition |
| intuitive-squash | Compress noisy local agent history into a clean reviewable commit story |
- README.md: orientation, install commands, and public project map
- ARCHITECTURE.md: subsystem contracts, extension points, and proof boundaries
- STATUS.md: current state, supported commands, and next maintenance focus
- docs/human/: human-facing detail that should not bloat root docs
Generated diagrams, release-note analysis, vendored tools, planning scratchpads, and implementation evidence are context, not current truth unless a human doc promotes them.
| Script | Purpose |
|---|---|
scripts/update.sh |
Install or update agent surfaces, skills, commands, GSD, and gstack |
scripts/dev/*.sh |
Local developer utilities for tmux and workstation sessions |
scripts/support/tmp-fix.sh |
Idempotent updater patch hook used by scripts/update.sh --tmp-fix |
For script development:
bun install
bun run verify
Human docs define repo truth, AGENTS.md and CLAUDE.md stay project-local,
skills carry reusable workflows, and scripts/update.sh syncs Claude Code,
Codex, GSD, gstack, external community skill sources, and repo-owned skills
into user-level tooling. See ARCHITECTURE.md for subsystem
contracts and proof boundaries.
PRs are welcome from humans and AI agents. The most useful contributions are sharper shared rules and fixes to workflows that drift as the underlying CLIs evolve.
Less is more.
MIT - see LICENSE.