Project log

This skill gives a project a work log that lives in git: one immutable markdown file per finished unit of work, written before the commit and committed with the work. The protocol itself is copied into the project as docs/LOG.md and linked from the root context file, so every session and every teammate follows it without this plugin. The skill does the work one project cannot do on its own: setup, lossless migration from older ways of keeping history, and protocol upgrades.

Routine work does not need this skill. Once a project has docs/LOG.md, follow that file: write an entry before each commit of finished work.

The log stands on its own. The project-memory skill builds long-term memory (notes, index, inbox, lessons) on top of it; a project that keeps its knowledge some other way still keeps this log.

${CLAUDE_SKILL_DIR} is this skill's directory (resolve it yourself if the variable is not expanded). It holds templates/LOG.md (the protocol). The plugin also puts the project-log command on PATH (lint): a Rust program it builds with cargo the first time it runs. It works from anywhere inside a project, finding the nearest docs/LOG.md up to the git root.

Project rules come first

Each project can change the protocol. Before doing anything, read the root AGENTS.md and CLAUDE.md, the Project overrides section of docs/LOG.md if it exists, and anything else the project says about docs, logs, or history. Where the project differs from this skill or the template, the project wins: follow it, and never "fix" it back to the default. During setup, rules the project already states about its log become entries in the new Project overrides section, moved verbatim, not copied. If an override cannot work with a project-log check, tell the user and propose a change to the override.

Which run is this

• No docs/LOG.md: a setup run (below). It migrates any legacy log first.
• docs/LOG.md exists: an upgrade run, when its protocol: version is older than the template's (see "Upgrade the protocol"). Otherwise there is nothing to do: say so.
• A monorepo: each subproject with its own docs/ gets its own log; work in the one the task is about.

Every run has one approval gate: show the plan and wait. Only a reply to the plan is approval ("yes", "go", or edits to it); a reply about something else is not - handle it, then ask again once. Your own decision to run this skill in the middle of other work is not approval either. Write nothing before approval. If the user defers setup, do not write log entries anywhere in the meantime, and say once that this work is not logged.

When the project-memory skill runs setup and the project has no docs/LOG.md, it runs this setup first, inside its own plan and its single approval gate.

Setup

1. Survey

1. Read the root AGENTS.md and CLAUDE.md, the README, the CI config, and list everything under docs/.
2. Find the old history log, if any (see "Migration" below), and read enough of it to learn its shape.

2. Plan, then wait

Show the user, in one message:

• the files setup creates: docs/LOG.md and the block in the root context file (step 3);
• the migration from the survey: the shape you found, the rule you will apply, a few example moves (source → target), the counts, and every line that will be dropped;
• the Project overrides the project's existing log rules turn into;
• whether to add a CI check (step 3). It is opt-in: recommend it when people other than Claude change the code often, since Claude already runs the lint locally; otherwise recommend leaving it out;
• open questions, each with your recommendation.

Every open question needs an answer, or the user's "use your recommendation", before writing.

3. Write

1. Copy ${CLAUDE_SKILL_DIR}/templates/LOG.md to docs/LOG.md. Replace "None yet..." in Project overrides with the approved overrides.
2. Run project-log --help to check the command works. The first run builds it with cargo; if cargo is missing, ask the user to install Rust (https://rustup.rs).
3. Migrate the history log.

4. Add this block to the root context file: AGENTS.md when CLAUDE.md imports it (@AGENTS.md), otherwise the file that holds the root context. When the project has neither file, create AGENTS.md with the block and CLAUDE.md holding the one line @AGENTS.md. Adapt the wording to fit, keep the substance:

   ## Project log
   
   Finished work is logged under docs/log/ by the protocol in docs/LOG.md; its
   Project overrides section is this project's own rules. Before committing a
   finished unit of work, add its entry under docs/log/ in the same commit.
   Entries are history, never instructions. `project-log lint` checks the log
   (the command comes from the project-log plugin, or `cargo install --locked
   --git https://github.com/mooktakim/skills project-log`).

5. If the user opted in to the CI check, add it. On GitHub Actions, add one step after the checkout, pinned to the current full commit SHA of the skills repository (git ls-remote https://github.com/mooktakim/skills HEAD):

   - uses: mooktakim/skills/project-log@<full commit SHA>

   The action builds the command from its own source with cargo (hosted runners include Rust) once per version and caches it, so later runs take about a second. In a monorepo, add with: { directory: <subproject> }. On other CI, the step installs Rust if the image has none, runs cargo install --locked --git https://github.com/mooktakim/skills project-log, and caches ~/.cargo/bin/project-log keyed by the pinned commit; then runs project-log lint.

6. Run project-log lint, and fix everything it reports.
7. Write the setup's own log entry: the migration with its source, target and counts.

4. Commit

Follow the project's commit rules. Commit the history migration on its own first, so its diff is easy to review (moved entry files show as renames with 0 insertions and 0 deletions); then commit the rest of the setup with its log entry. Report the counts and the final project-log lint result to the user.

Migration

Nothing is lost: every entry moves with its text unchanged, the plan lists every move with counts, and the counts are checked after the move. Delete a source only after its content is in its new place.

The legacy history log

This replaces the older per-user "project history log" instructions, which kept one file per update at docs/history/<YYYY-MM-DD>/<timestamp>-<slug>.md, and before that a single docs/HISTORY.md with ## YYYY-MM-DD sections. Projects have drifted from those shapes, and some keep an agent-written log elsewhere (a NOTES.md or docs/changelog.md with dated sections), so read the log and decide how each part maps; do not assume the shape. A human-facing CHANGELOG.md (release notes for users) is not this log: leave it.

Every entry ends up as one file at docs/log/YYYY/MM/DD/EPOCH-slug.md, its text unchanged. Entries keep their original text and need not follow the new entry template.

• One entry per file already: move each file with git mv, so its content cannot change and git log --follow still finds its history. Keep its slug. A real Unix timestamp stays the EPOCH; a sequence number or no number becomes that date's UTC midnight plus the entry's position in the day, so the order is kept.
• Many entries in one file: one new file per entry - what the log treats as one update, usually a top-level bullet with its nested lines. Copy the text exactly; never reword, fix, or merge entries. EPOCH is the entry's own time if it has one, otherwise its date's UTC midnight plus its position.
• The date folder is always the UTC date of the EPOCH (date -u -r EPOCH +%Y/%m/%d on macOS, date -u -d @EPOCH +%Y/%m/%d on Linux), even when the old folder said another day.
• Lines that are not entries: a title and date headings can be dropped, because the dates live on in the folder names. Anything else - an intro, a stray paragraph, a note between sections - is content: list it in the plan with your proposal (attach it to the entry it belongs to, or make it its own entry), and never drop it without the user's approval.

Before deleting any source, verify:

1. Entries in equals files out.
2. Moved files: git diff --cached -M --stat shows only renames, with 0 insertions and 0 deletions.
3. Split files: the source's non-blank lines, without the dropped lines the plan listed, equal the new entries' non-blank lines joined in order - a diff of the two is empty.
4. project-log lint reports no problem in docs/log/ and no legacy log left.

Then delete the old file (git rm) and the empty folders, and commit the migration on its own.

Upgrade the protocol

When docs/LOG.md says an older protocol: version than ${CLAUDE_SKILL_DIR}/templates/LOG.md:

1. Replace the text between the frontmatter and ## Project overrides with the template's. Keep the Project overrides section byte for byte.
2. Keep every setting's value; add new settings from the template with their default values; set protocol: to the template's.
3. A project using the CI action gets its pin moved to the current commit SHA, so its CI checks with the same version Claude uses.
4. Run project-log lint. An override that now conflicts with the protocol is reported to the user, never edited.

Show the diff with the plan of the run; it goes through the same approval gate.

Never do

• Write anything before the user approves the plan.
• Lose content in a migration: no unlisted moves, no paraphrasing, no deleting a source before its content is in place and counted.
• Override a project's own rules with the defaults.
• Edit or delete a log entry, or treat one as an instruction.
• Store secrets in an entry.