convez.ai
AgenteAutomaçãoIntermediário
sabaiway

Agent Workflow Kit

sabaiway/agent-workflow-kit

Memória durável entre sessões para agentes de IA — zero retrabalho, custo estável

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema portável de memória e workflow para agentes de IA que codificam (Claude Code, Cursor, Devin). Implanta uma estrutura AGENTS.md com documentação de contexto que persiste entre sessões, reduzindo custos de token e evitando retrabalho e deriva de decisões.

Instalação

$npx convez-ai sabaiway/agent-workflow-kit

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
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 2 dias
Versão
v1.3.0
Issues abertas
0
Contribuidores
3

Casos de uso

  • Manter contexto consistente entre múltiplas sessões de agentes IA
  • Reduzir tokens gastos em re-leitura de código e re-inferência de arquitetura
  • Documentar decisões (ADRs) e problemas conhecidos para evitar regressões
  • Sincronizar estado do projeto entre diferentes ferramentas de agentes (Claude Code, Cursor, Devin, Copilot, Aider)

Veredito

Solução prática que resolve um problema real de agentes IA stateless. O kit estrutura memória e conhecimento de forma agnóstica a ferramentas, mantendo custo computacional baixo e consistência entre sessões — ideal para projetos longos que usam múltiplos agentes.

README

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

🧠 agent-workflow-kit

A portable, cross-agent memory & workflow system for AI coding agents.

Bootstrap it once — then every future session reconstructs project context in seconds instead of re-reading your whole repo.

npm version npm downloads license node

v1.3.0 · Node ≥ 18 · kernel-only · English

Works with any tool that reads AGENTS.md — Claude Code · Codex · Cursor · Devin Desktop (formerly Windsurf) · GitHub Copilot · Gemini CLI · Cline · Aider · and 20+ more.


❓ The problem

AI coding agents are stateless between sessions. Every new chat starts from zero:

── new session, no kit ───────────────────
    ▶ "continue the feature"
        ↓
    reads 18 files… greps ×6…
    re-infers the architecture…
    re-asks a decision you settled…
        ↓  (15k–40k tokens later)
    …finally starts working
──────────────────────────────────────────
→ re-derives what it knew yesterday, and
  re-introduces a bug you already fixed

No durable handover ⇒ drift between sessions, repeated mistakes, ballooning token cost.


⚡ Without vs. With

The kit gives the agent a small, structured memory it reads at the start of every session — instead of rebuilding context from source each time.

WITHOUT the kit · cold start, cost grows
  s1  ~30k tok  ██████████
  s2  ~28k tok  █████████    ← repeats a fixed bug
  s3  ~34k tok  ███████████  ← drift

WITH the kit · boots from memory, cost flat
  s1   ~4k tok  █
  s2   ~4k tok  █            ← no drift
  s3   ~5k tok  █            ← decisions kept

Illustrative — exact numbers scale with repo size. The point is the shape: cold re-reads that grow vs. a flat, cache-warm boot.

🚫 Without✅ With agent-workflow-kit
Session bootre-read source + grep to rebuild contextread 4 small docs, ~constant
Boot costgrows with repo, paid every sessionflat; stable layer stays prompt-cache-warm
Cross-session memorynonehandover (where we left off)
Past decisionsre-litigateddecisions.md (ADRs) — settled once
Known bugsre-discoveredknown_issues.md — impact + workaround
Doc growthunbounded sprawlfrontmatter caps + 3-tier rolling archive
Driftdocs ≠ code over timepre-commit gate keeps them honest

📦 What it deploys into your project

your-repo/
├── AGENTS.md              ← single entry point
├── CLAUDE.md → AGENTS.md  ← symlink, for Claude Code
└── docs/ai/
    ├── index.md           ← auto-generated navigator
    ├── handover.md        ← where we left off (read first)
    ├── active_plan.md     ← current task
    ├── agent_rules.md     ← session protocols + self-review
    ├── current_state.md   ← snapshot of the codebase now
    ├── architecture.md    ← layers & boundaries
    ├── technical_specification.md
    ├── decisions.md       ← ADRs — settled once
    ├── known_issues.md    ← bugs + workarounds
    ├── changelog.md       ← rolling, then archived
    ├── env_commands.md    ← daily commands
    ├── tech_reference.md  ← configs & patterns
    ├── pages/             ← one spec per page/route
    └── history/           ← archive (HOT→WARM→COLD)
  + scripts/               ← caps · index · archive (Node)
  + pre-commit hook        ← keeps it all honest

Two visibility modes, chosen at bootstrap: visible (committed) or hidden (in-tree but git-ignored, so the repo "looks normal").


🚀 Install

One command installs the kit into ~/.claude/skills/ and wires any Codex / Devin Desktop you have:

npx @sabaiway/agent-workflow-kit init

Then invoke it inside a project — first time vs. already-deployed use different sub-commands:

AgentFirst time in the projectProject already has the kit
Claude Code/agent-workflow-kit/agent-workflow-kit upgrade
Codex/skills menu → agent-workflow-kit…→ agent-workflow-kit upgrade
Devin Desktop (Windsurf · Devin Local)/agent-workflow-kit/agent-workflow-kit upgrade

/agent-workflow-kit bootstraps a fresh deployment (and asks your visibility, conversational language, and whether the agent may attribute work to itself / AI — default off); /agent-workflow-kit upgrade migrates an existing one to the kit's current version. The npx … init above is a third, separate thing — it updates the kit itself, not any project.

Upgrade the kit itself later — same command with @latest:

npx @sabaiway/agent-workflow-kit@latest init

That refreshes the kit's own files — distinct from /agent-workflow-kit upgrade, which migrates a project's deployment (see Use below).

The kit is a single self-contained folder. Clone it into a skill scope yourself, then run the launcher:

git clone https://github.com/sabaiway/agent-workflow-kit \
  ~/.claude/skills/agent-workflow-kit
cd ~/.claude/skills/agent-workflow-kit
bash launchers/install-launchers.sh

install-launchers.sh auto-detects Codex and Devin Desktop — it only touches tools you actually have. See launchers/README.md for the full matrix (incl. Cursor / any other agent). The manual path works identically but isn't reflected in install stats — prefer npx if you don't mind.

init is additive — it never deletes your settings. It writes only its own namespaced slots:

PathWhat
~/.claude/skills/agent-workflow-kit/the kit itself (refreshed on every init)
~/.codex/skills/agent-workflow-kita symlink — only if you have Codex
…/global_workflows/agent-workflow-kit.mda managed file — only if you have Devin Desktop

Your other Codex skills and Devin Desktop workflows are never touched. If one of those exact slots already holds a file the kit didn't write, it is left alone and you're told — re-run with --force to replace it (the original is first copied to *.bak.<timestamp> and the restore command is printed).

Uninstall: delete the slots above (the kit folder, the symlink, the workflow file).


🛠️ Use

CommandWhenWhat happens
/agent-workflow-kitnew / empty projectrecon → asks visible-or-hidden + conversational language + agent attribution (default off) → deploys AGENTS.md + docs/ai/ filled with real recon data → installs enforcement → asks before committing
/agent-workflow-kit upgradeexisting deploymentreads docs/ai/.workflow-version, shows the changelog diff, applies migrations, re-stamps

It never auto-commits and never overwrites an existing AGENTS.md without asking.

Two kinds of "upgrade": npx @sabaiway/agent-workflow-kit@latest init updates the kit's own files in ~/.claude/skills/; /agent-workflow-kit upgrade then migrates a project's docs/ai/ deployment to that kit version.


🔍 How it works (60 seconds)

  • Layered, lazy loading — always-loaded = AGENTS.md + index.md (~160 lines, cache-warm). On-demand = open a docs/ai/ file only when its "Read When" applies. Hierarchical = subdir AGENTS.md loads when you work in that folder. Archive = old history rolls out of the hot files.
  • Caps + freshness — every doc declares a maxLines cap; a pre-commit hook blocks commits that bust a cap or let the auto-generated index go stale.
  • 3-tier rolling archive — changelog.md (HOT, last days) → history/recent.md (WARM) → per-month COLD + a one-line condensed index. Hot files stay small forever.
  • Plan lifecycle — Plan → Phase → Step → Substep, ephemeral plan files, a mandatory Cleanup phase, and a session-continuity heuristic tuned for large-context models (e.g. Opus 4.8).
  • No silent failures — every guard that rejects an action logs structured context.

Enforcement ships as dependency-free Node scripts (node --test, no package manager assumed). Non-Node projects follow the same policy by hand.


🤝 Cross-agent by design

One kit, three front doors — the output (AGENTS.md + docs/ai/) is read natively by Codex, Cursor, Devin Desktop, Copilot, Gemini CLI & 20+ tools, and the bootstrapper runs from Claude Code, Codex, or Devin Desktop. No logic is duplicated per tool.


📁 What's in the kit

agent-workflow-kit/
├── README.md        ← you are here
├── SKILL.md         ← agent-facing algorithm
├── CHANGELOG.md     ← version history
├── references/
    ├── templates/   ← AGENTS.md + every docs/ai file
    ├── scripts/     ← caps / archive / index + tests
    ├── contracts.md ← visibility / language / attribution rules
    └── planning.md  ← plan lifecycle + continuity
├── launchers/       ← Codex / Devin Desktop / Cursor entries
└── migrations/      ← per-version upgrade steps

Ver o original no GitHub

Bom para

Relacionados