convez.ai
SkillProdutividadeIntermediário
benjsmith

Plan Assist

benjsmith/plan-assist

Documentação resistente a desvios com write-ahead log e heartbeat

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-assist

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
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

FileRoleChanges
charter.mdStable directives: DO/DO NOT, architecture invariants, build-order status table, durable gotchasRarely
work-plan.mdRolling plan: active phase, next, deferred, SESSION HANDOFFEvery session
log.mdAppend-only journal — the canonical source of truthEvery 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

  1. log.md wins. If charter.md disagrees with log.md, the journal is right — charter.md only distills it.
  2. log.md is 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 + the CLAUDE.md orientation block from templates/, 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, update work-plan.md in the same commit as code, commit a log.md entry before risky ops, fold landed phases into log.md and 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.

Ver o original no GitHub

Bom para

Relacionados