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, 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.
The workflow keeps the user-facing choices small: use office-hours or
grill-me for what to build, $intuitive-flow to build it,
$intuitive-refactor to clean a known target, and
$intuitive-reduce-entropy to find what repo maintenance would pay off most.
See BELIEFS.md for the full doctrine.
In the target repo, give your AI agent the maintenance entrypoint and ask it to find the highest-value entropy reduction slice:
Read this skill:
https://github.com/MiaoDX/intuitive-flow/blob/main/skills/intuitive-reduce-entropy/SKILL.md
Then run:
Use $intuitive-reduce-entropy to make this repo easier for humans and AI agents
to work in. If agent guidance is the first entropy source, route to
$intuitive-init. Start with a candidate list before applying changes.
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.shKeep the public choice small:
| Skill | Use it for |
|---|---|
| intuitive-flow | Move a fuzzy idea through plan review, GSD handoff, execution, cleanup, and verification |
| intuitive-refactor | Directly clean a known module, seam, stale API, compatibility surface, code/package/module layout issue, or architecture target |
| intuitive-reduce-entropy | Periodically inspect repo mess and recommend the highest-value maintenance slice; routes to $intuitive-doc for human docs, $intuitive-init for agent guidance, and $intuitive-tests for tests |
| intuitive-squash | Compress noisy local agent history into a clean reviewable commit story |
Specialist skills still exist for direct or routed use: $intuitive-doc,
$intuitive-init, and $intuitive-tests.
- 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
- Agent harness references: official and field-practice sources that guide agent guidance, skills, hooks, and MCP setup
- Reduce repo entropy: copy/paste prompt for periodic repo maintenance
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 |
|---|---|
bun run build:skills |
Regenerate flattened skills/intuitive-* outputs from skills-src/ |
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-src/ authors generated intuitive skills, skills/ carries flattened
installable 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.