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

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.