shiplog

The captain's log for your codebase. Every decision, discovery, and trade-off — captured in GitHub as you ship.

Quick Install

npx skills add devallibus/shiplog --skill shiplog

Works with Claude Code, Codex, and Cursor. Only requires gh CLI.

---

Your AI assistant forgets everything between sessions

You brainstormed a design with Claude yesterday. Today, a new session starts from scratch. The reasoning behind that auth middleware? Gone. The three alternatives you rejected? Nowhere to be found. Last week's architectural decision? Buried in a chat log you can't search.

shiplog makes your git history remember everything. Not just what changed — but why it changed, what you considered, and what you discovered along the way.

Brainstorm → Issue → Branch → Commits → PR
    ↑                           ↑
    |         Discoveries → New Issues / Stacked PRs
    |
    └── Search it all later: issues, PRs, commits, memory

What you get

Every brainstorm becomes a GitHub Issue. Design decisions, alternatives considered, and a task list — all searchable forever.

Every commit carries context. Not just "add JWT validation" — but why JWT over sessions, what you tried first, and what to watch out for.

Every PR tells the full story. A timeline of the entire journey: what was planned, what was discovered mid-work, what changed and why.

Nothing falls through the cracks. Find a sub-problem while coding? shiplog routes it — fix inline, stack a prerequisite PR, or spin off a new issue. Your discovery is never lost.

Any model can pick up where another left off. Every artifact is signed with who wrote it (which AI model, which tool). Context handoffs between models are first-class — not copy-paste.

---

How it works

You say "let's brainstorm auth middleware" and shiplog captures the result as a GitHub issue. When you say "work on #42", it creates an isolated branch in a git worktree. As you commit, it logs the reasoning. When you open the PR, it writes a timeline of the whole journey.

Your existing workflow, with a knowledge trail that persists across sessions, models, and tools.

Step	What happens
Brainstorm	Design discussion becomes a GitHub Issue with tasks
Branch	Isolated worktree created, timeline started, plan loaded
Discover	Sub-problems routed: inline fix, stacked PR, or new issue
Commit	Conventional commits with context comments on significant changes
Ship	PR with full journey timeline, decisions, and lessons learned
Search	Find any past decision across issues, PRs, and commits

Two modes

Full Mode (default) — Knowledge goes directly into issues and PRs. Perfect for personal projects and open source.

Quiet Mode — Your team sees clean PRs. The full reasoning lives in a separate --log branch, one click away.

main
  └── feature/auth-middleware            ← Clean PR (team sees this)
        └── feature/auth-middleware--log  ← Knowledge trail (one click away)

---

Features

Cross-model review

No PR merges without review from a different AI model or a human. A single model authoring, reviewing, and merging its own work is the anti-pattern shiplog prevents. Reviews carry signed Reviewed-by: lines, support four dispositions (approve, approve-with-follow-ups, request-changes, comment), and generate self-contained review contracts when spawning a reviewer isn't possible.

Agent identity signing

Every artifact carries a provenance signature — Authored-by: claude/opus-4.6 (claude-code). The signing system auto-detects the current model from the platform and makes everything searchable:

gh issue list --search "Authored-by: claude/"   # all Claude artifacts
gh pr list --search "Reviewed-by:"              # all reviews

Model-tier routing

Use your best model for brainstorming, a fast one for implementation. shiplog prompts you to switch at phase transitions and writes context handoffs so the receiving model can execute without guessing.

Tier	Best for	Example models
tier-1 (reasoning)	Architecture, trade-offs, PR synthesis	Claude Opus, o3
tier-2 (capable)	Context loading, structured docs	Claude Sonnet
tier-3 (fast)	Implementation, routine commits	Claude Haiku, GPT-4o-mini

Delegation contracts

When a reasoning model hands work to a faster model, the handoff is structured: allowed files, forbidden changes, stop conditions, verification requirements, and decision budget. If a tier-3 model reading the handoff would need to make a judgment call, the handoff is not specific enough.

Runtime-aware orchestration

shiplog distinguishes orchestration from isolation. A task might stay inside one orchestrator with local parallel tool calls, fan out to bounded sub-agents, or move to an external session such as a tmux-backed background worker. The important part is that the dispatch contract and collection summary are durable, and that shiplog does not pretend a helper lane is an independent reviewer when it is not.

Discovery protocol

Find a bug while building a feature? shiplog classifies it and routes it:

Discovery made during work
  ├── Small fix (< 30 min)?         → Fix inline, add timeline comment
  ├── Prerequisite for current work? → Stack a new branch/PR
  ├── Independent but important?     → Create new issue, continue
  └── Refactoring opportunity?       → Create issue tagged "refactor"

Stacked prerequisites get their own issue and branch with cross-references on the parent. Nothing gets lost.

Task-level delivery

Ship incrementally. Commits reference tasks (feat(#42/T1): add JWT validation), partial-delivery PRs use Addresses #42 (completes T1, T2), and the issue stays open for remaining work. No premature closures, no lost tr