Plan Assist
benjsmith/plan-assist
Documentação resistente a desvios com write-ahead log e heartbeat
Ver no GitHubSkill do Claude Code que implementa um sistema de documentação de projeto em três camadas (charter + plano + diário) para manter a intenção do projeto consistente entre sessões. Usa um write-ahead log e verificações periódicas para detectar desvios cedo e evitar reconciliações dolorosas.
Instalação
npx convez-ai benjsmith/plan-assist1 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
- Manter coerência de intenção do projeto entre múltiplas sessões
- Recuperação de projeto em caso de perda de estado
- Handoff estruturado entre sessões de desenvolvimento
- Detecção precoce de desvios arquiteturais
Veredito

Skill sólida para times que precisam de rastreabilidade e continuidade em projetos complexos. A abordagem de write-ahead log + heartbeat é pragmática e reduz o risco de perda de contexto, especialmente em projetos de longa duração.
README
A tradução para o português deste README ainda está na fila.
plan-assist
A Claude Code skill that sets up and maintains a three-tier project-documentation system which keeps a project's intent from drifting across sessions. The journal is treated as a write-ahead log for intent, and a cheap periodic heartbeat catches drift early — so you get small continuous corrections instead of one painful reconciliation later.
The three documents
| File | Role | Changes |
|---|---|---|
charter.md | Stable directives: DO/DO NOT, architecture invariants, build-order status table, durable gotchas | Rarely |
work-plan.md | Rolling plan: active phase, next, deferred, SESSION HANDOFF | Every session |
log.md | Append-only journal — the canonical source of truth | Every session + before risky ops |
Plus an orientation block added to the project's CLAUDE.md so future sessions
read the docs in the right order.
Two invariants
log.mdwins. Ifcharter.mddisagrees withlog.md, the journal is right —charter.mdonly distills it.log.mdis append-only. Never edit or delete past entries; newest at the bottom; absolute dates only.
Why the ceremony
log.md is a write-ahead log for the project's intent: a session once lost its
working tree on a mv, and the journal was the only recovery path. So you append
and commit a journal entry before a risky operation, not after.
Install
Easiest — with the skills installer:
npx skills add benjsmith/plan-assist
Or clone manually into a project's skills directory (per-project) or your user skills directory (global):
# per-project
git clone https://github.com/benjsmith/plan-assist .claude/skills/plan-assist
# or global (all projects)
git clone https://github.com/benjsmith/plan-assist ~/.claude/skills/plan-assist
Claude Code discovers the skill on next launch via its SKILL.md frontmatter.
Use
The skill auto-surfaces on phrases like "set up project docs", "plan docs", "session handoff", "wrap up this session", "before I move/reset the repo", "project heartbeat" — or invoke it explicitly.
- Bootstrap (
Mode A): scaffolds the three docs + theCLAUDE.mdorientation block fromtemplates/, seeds a Session 1 entry, and (opt-in) offers a heartbeat hook and a read-only command allowlist. It never clobbers existing files — it offers to merge. - Maintain (
Mode B): a session contract the agent follows — read order at start, updatework-plan.mdin the same commit as code, commit alog.mdentry before risky ops, fold landed phases intolog.mdand prune, write a SESSION HANDOFF when stopping mid-task, and run the heartbeat on each commit and at session boundaries.
Heartbeat
A cheap recurring check (usually a one-line no-op) that flags drift: stale
build-order markers, journal debt, an over-budget work-plan.md, unaddressed
open questions. Ships in three forms — skill-baked (default, zero config),
hook-enforced (settings.json), or scheduled (cron / loop). See
hooks/heartbeat.md.
Layout
SKILL.md # frontmatter + the session contract
templates/
charter.md # stable directives skeleton
work-plan.md # rolling plan skeleton
log.md # append-only journal skeleton
CLAUDE-orientation.md # block inserted into a project's CLAUDE.md
hooks/
heartbeat.md # checklist + optional settings.json snippets
License
MIT — see LICENSE.