convez.ai
AgenteDevOps & InfraestruturaIntermediário
suntay44

Plannable

suntay44/plannable

Planejamento spec-driven para agentes de IA com rastreamento de evidências

Ver no GitHub
InicialPluginScore · de 0 a 100

CLI de planejamento orientado por specs para agentes de IA que codificam. Gera um MASTER_PLAN.md legível para humanos e arquivos de sub-planos comprimidos para agentes (Codex, Claude Code, Cursor) trabalharem progressivamente com validação e evidência de conclusão.

Instalação

$npx convez-ai suntay44/plannable

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
28
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v1.0.0
Issues abertas
2
Contribuidores
1

Casos de uso

  • Estruturar desenvolvimento de software em etapas verificáveis para agentes de IA
  • Manter plano único como fonte de verdade enquanto agentes trabalham em partes isoladas
  • Registrar evidência de conclusão e validar progresso antes de marcar como pronto

Veredito

Ferramenta pragmática para quem usa agentes de IA em workflows de desenvolvimento. Resolve um problema real — como manter planos coerentes enquanto múltiplos agentes trabalham em paralelo — com abordagem clara e verificável. Exige adoção de disciplina (evidências obrigatórias), mas garante rastreabilidade.

README

A tradução para o português deste README ainda está na fila.

Plannable

Command-driven planning for AI coding agents.

Plannable turns a product idea into a short, human-readable MASTER_PLAN.md plus compressed, agent-readable part files (PlannablePlan .ai.md format). Agents load one part at a time — each part carries enough context about the whole masterplan to work alone — and nothing gets checked off without recorded evidence.

Think spec-kit, but the plan is split into compressed parts where each part knows its place in the masterplan.

Install

# From npm (when published)
npm install -g plannable

# From source
git clone https://github.com/plannable/plannable.git
cd plannable && npm install && npm run build && npm link

See docs/INSTALL.md for local development setup.

Get Started

plannable create "CRM"     # generate MASTER_PLAN.md + compressed part files
plannable run-next         # print the next pending part (load only this)
# ...implement the part...
plannable evidence PART-001 "Contact creation works" --artifact "npm test"
plannable complete PART-001
plannable verify           # structural + evidence checks for the whole plan

create accepts any product idea ("SaaS billing dashboard", "mobile habit tracker", "backend API", ...). Common domains get sharper first drafts via scenario hints; everything else gets a generic draft that verify will warn you to enrich with product-specific detail before implementing.

Generated Files

MASTER_PLAN.md          short, scenario-driven plan for humans (source of truth)
PLAN_EVIDENCE.md        evidence log — proof a part is actually done (source of truth)
PLAN_STATE.md           progress view, generated from the two files above
plans/PART*_PLAN.ai.md  compressed parts for agents, loaded one at a time

Each part file carries a CTX: block — the product goal, what prior parts delivered, and what comes next — so one part file is all the context an agent needs:

@PlannablePlan v0.1

ID=PART-002
PH=CORE
SCN=SCN-002
OUT=Deal pipeline works

CTX:
- product: CRM — managing contacts, companies, deals, tasks, and follow-ups
- phase: Core CRM Foundation (part 2/3)
- prior: PART-001 delivered "Contact management works"
- next: PART-003 covers "Follow-up tasks work"

T:
1 create:deal.entity(fields=title,company,value,stage)
2 build:pipeline.stages

AC:
- a deal can move through pipeline stages

V:
- npm test?

DONE:
- update MASTER_PLAN.md Part 2=[x]
- append PLAN_EVIDENCE.md#PART-002 with files+checks+notes

S:
- if database stack unclear, stop and ask

Full format reference: docs/PLANNABLE_PLAN_SPEC.md.

Commands

CommandWhat it does
plannable create "CRM"Generate a scenario-driven plan for any product idea
plannable run-nextPrint the next pending part (the only file an agent should load)
plannable statusShow progress, grouped by masterplan phase
plannable evidence PART-001 "summary" --artifact "npm test"Record proof of completed work
plannable complete PART-001Check off a part — refuses without evidence
plannable verifyValidate files, structure, evidence; warn on generic draft wording
plannable doctorStatus + verification in one report
plannable repairRegenerate PLAN_STATE.md and fix drift after manual edits
plannable compress plan.mdConvert a Markdown plan into plan.ai.md, reporting token savings
plannable expand plans/PART1_PLAN.ai.mdExpand a compressed part back into readable Markdown

Add --json to run-next, status, verify, doctor, or repair for machine-readable output. Details: docs/COMMANDS.md.

Using Plannable from an AI Agent

Plannable ships skill instructions for three platforms — copy or reference the matching folder:

PlatformSkill locationInvocation
Claude Code.claude/skills/plannable//plannable create a CRM
Codex.agents/skills/plannable/$plannable create a CRM
Cursor.cursor/skills/plannable/ (+ .cursor/commands/, .cursor/rules/)/plannable create a CRM

The workflow is the same everywhere: create → enrich the draft with product-specific detail → run-next → implement → evidence → complete → verify.

Rules That Keep Plans Honest

  • One part at a time. Agents load only the next pending .ai.md file; its CTX: block supplies the masterplan arc.
  • Evidence before checkoff. complete fails unless evidence is recorded in PLAN_EVIDENCE.md.
  • No state drift. MASTER_PLAN.md + PLAN_EVIDENCE.md are the source of truth; PLAN_STATE.md is generated from them — never hand-edit it, just run plannable repair.
  • Drafts must be enriched. verify warns while the plan still contains generic scaffold wording.

More

MIT licensed.

Ver o original no GitHub

Bom para

Relacionados