Intuitive Flow
MiaoDX/intuitive-flow
Modelo operacional para IA escrever código com guia humano mínimo
Ver no GitHubKit de workflow portátil para Claude Code e Codex que organiza repositórios em torno de um modelo operacional opinado para software escrito por agentes. Define superfícies claras para humanos (documentação pequena e focada) e agentes (código, planos, logs), com skills reutilizáveis para redução de entropia, refatoração e planejamento.
Instalação
npx convez-ai MiaoDX/intuitive-flow1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Organizar repositórios para desenvolvimento dirigido por agentes de IA
- Reduzir entropia técnica e identificar candidates para manutenção
- Padronizar fluxos de refatoração, build e planejamento entre projetos
- Manter superfície humana pequena enquanto agentes trabalham autonomamente
Veredito

Solução madura e opinada para times que usam agentes IA na escrita de código. Exige alinhamento filosófico com o modelo proposto, mas oferece estrutura sólida para escalar desenvolvimento assistido por IA com governança clara.
README
A tradução para o português deste README ainda está na fila.
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.
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.
The workflow keeps the user-facing choices small: use $intuitive-flow for
default shaping/build/change routing, $intuitive-refactor to clean a known
target, $intuitive-reduce-entropy to surface repo maintenance candidates,
$intuitive-planning-loop to let scouts refine contested plans before one
review packet, and $intuitive-squash before branch handoff.
See BELIEFS.md for the supporting doctrine behind the workflow;
current project truth stays in the small human surface above.
Start In A Repo
In the target repo, give your AI agent the maintenance entrypoint and ask it to find the ranked batch of high-value entropy reduction candidates:
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 ranked candidate batch before applying changes.
Optional Tool Install (For Humans)
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.sh
Primary Skills
Keep the public choice small:
| Skill | Use it for |
|---|---|
| intuitive-flow | Default build/change entrypoint; routes tiny concrete work directly, cleanup/refactor work to intuitive-refactor, and broad work through plan/review/execution |
| 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 produce a ranked batch of high-value maintenance candidates; routes accepted docs, agent guidance, tests, architecture discovery, and known code cleanup to the right specialist |
| intuitive-planning-loop | Bounded autonomous planning loop: scouts run reduce-entropy and grill-batch style critique, while the main session judges scope and returns one review packet |
| intuitive-squash | Compress noisy local agent history into a clean reviewable commit story |
Common routed specialists include $intuitive-preflight, $intuitive-doc,
$intuitive-init, and $intuitive-tests; direct-use utilities such as
$intuitive-port-worktree, $multica-goal-tracker, $skill-runner, and
$simplify are installed too. The full repo-owned install list lives in
scripts/local-skill-manifest.txt, with the human-facing role audit in
docs/human/skill-self-improvement-audit.md. Architecture discovery may route
through improve-codebase-architecture when that external skill is installed.
Human Docs
- 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.
Scripts
| Script | Purpose |
|---|---|
bun run check:skills | Validate repo-owned skills, manifest coverage, external skill sources, frontmatter, local resource links, and Bun toolchain pin alignment |
bun run check:shell | Run ShellCheck error-level validation for the updater, Bash helper scripts, and the Git hook entrypoint |
bun run setup:hooks | Configure this checkout to use repo-owned Git hooks from .githooks/ |
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 |
scripts/update.sh uses the direct npm registry by default. Pass
--npm-mirror to force mirror registry access for every npm/npx task.
For script development:
bun install
bun run setup:hooks
bun run verify
How It Works
Human docs define repo truth, AGENTS.md and CLAUDE.md stay project-local,
skills/ is the canonical repo-owned skill surface, and scripts/update.sh
syncs Claude Code, Codex, GSD, gstack, manifest-listed external skill sources, and
repo-owned skills into user-level tooling. See ARCHITECTURE.md
for subsystem contracts and proof boundaries.
Contributing
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.
License
MIT - see LICENSE.