convez.ai
MCP ServerAutomaçãoAvançado
MiaoDX

Intuitive Flow

MiaoDX/intuitive-flow

Modelo operacional para IA escrever código com guia humano mínimo

Ver no GitHub
BomPluginScore · de 0 a 100

Kit 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-flow

1 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

Estrelas
49
Forks
3
Acompanhando
1
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
5

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.

License: MIT Shell Claude Code Codex

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:

SkillUse it for
intuitive-flowDefault build/change entrypoint; routes tiny concrete work directly, cleanup/refactor work to intuitive-refactor, and broad work through plan/review/execution
intuitive-refactorDirectly clean a known module, seam, stale API, compatibility surface, code/package/module layout issue, or architecture target
intuitive-reduce-entropyPeriodically 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-loopBounded autonomous planning loop: scouts run reduce-entropy and grill-batch style critique, while the main session judges scope and returns one review packet
intuitive-squashCompress 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

ScriptPurpose
bun run check:skillsValidate repo-owned skills, manifest coverage, external skill sources, frontmatter, local resource links, and Bun toolchain pin alignment
bun run check:shellRun ShellCheck error-level validation for the updater, Bash helper scripts, and the Git hook entrypoint
bun run setup:hooksConfigure this checkout to use repo-owned Git hooks from .githooks/
scripts/update.shInstall or update agent surfaces, skills, commands, GSD, and gstack
scripts/dev/*.shLocal developer utilities for tmux and workstation sessions
scripts/support/tmp-fix.shIdempotent 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.

Ver o original no GitHub

Bom para

Relacionados