# Devlog

> Maintain a structured development changelog (DEVLOG.md) that captures architectural decisions, progress milestones, key conversation takeaways, and strategic/business decisions for any project. Use this skill whenever the user says "log this", "devlog", "update the devlog", "push devlog", or references logging a decision, milestone, or takeaway. Also trigger proactively at the end of conversation…

- **Type:** Skill
- **Install:** `agentstack add skill-code-katz-claude-devlog-skill-devlog`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [code-katz](https://agentstack.voostack.com/s/code-katz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [code-katz](https://github.com/code-katz)
- **Source:** https://github.com/code-katz/claude-devlog-skill/tree/main/skills/devlog

## Install

```sh
agentstack add skill-code-katz-claude-devlog-skill-devlog
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Development Changelog (Devlog) Skill

This skill maintains a living development log (`DEVLOG.md`) in the root of a project's Git repository. It captures the important decisions, progress, and insights from development conversations so that future sessions have full context on what was done and why.

This skill is **project-agnostic** — it works with any repository. On first use in a session, it identifies the active project and adapts accordingly.

## Why This Matters

Development conversations contain critical context — the *reasoning* behind decisions, alternatives that were considered and rejected, and strategic pivots that shaped the project. Without a structured log, this context evaporates between sessions. The devlog serves as institutional memory for the project, making every future conversation more informed.

## Project Context (First Use Per Session)

The first time this skill triggers in a session, establish the project context by checking for clues in this order:

1. **Memory/conversation context** — Does Claude already know what project the user is working on? If so, confirm: "I'll log this to the devlog for [Project Name] — correct?"
2. **Project knowledge** — Are there project files or documents that identify the project name and repo?
3. **Ask the user** — If neither source provides clarity, ask: "Which project should I log this to? I'll need the project name and Git repo URL."

Capture and remember for the session:
- **Project name** — Used in the DEVLOG.md header and commit messages (e.g., "The Chronicle", "My Portfolio Site")
- **Git repo URL** — Where to push (e.g., `https://github.com/user/repo.git` or `https://gitlab.com/user/repo.git`)
- **Authentication** — If git is configured with a credential helper (e.g., macOS Keychain), no token is needed — git handles it transparently. Only ask for a Personal Access Token if a push fails with an auth error.
- **Default branch** — Usually `main`, but confirm if unsure

### Lint Check

When establishing project context for the first time in a session, verify that the project has a linter configured. Check for stack-appropriate lint configuration files:

- **Python**: `ruff.toml`, `pyproject.toml` with `[tool.ruff]`, `.flake8`
- **JavaScript/TypeScript**: `.eslintrc*`, `eslint.config.*`, `biome.json`, or a `lint` script in `package.json`
- **Swift/iOS**: `.swiftlint.yml`
- **Go**: `.golangci.yml`
- **Rust**: `clippy` configuration in `Cargo.toml`
- **General**: `.pre-commit-config.yaml`

If no linter is configured, flag it to the user before proceeding. Recommend: Ruff for Python, ESLint or Biome for JS/TS, SwiftLint for Swift, golangci-lint for Go, clippy for Rust. Frame it as a prerequisite, not an afterthought.

## Entry Format

Each entry follows this structure:

```markdown
## [YYYY-MM-DD] Brief descriptive title

**Category:** `feature` | `bugfix` | `refactor` | `infrastructure` | `security` | `milestone` | `strategy`
**Tags:** `relevant`, `topic`, `tags`
**Risk Level:** `low` | `med` | `high`
**Breaking Change:** `yes` | `no`

### Summary
A 1-2 sentence overview of what happened or was decided.

### Detail
Full context including:
- What was decided or accomplished
- Why this approach was chosen
- Dependencies or implications for future work
- Any open questions or follow-ups

### Decisions Made
Explicit trade-off decisions recorded here — what options were evaluated, what was chosen, and why alternatives were rejected.

### Related
- Links to related entries, documents, or resources when applicable
```

## Categories Explained

Choose the category that best fits each entry:

- **`feature`** — New capability or user-facing functionality added to the project.

- **`bugfix`** — A defect was identified and resolved.

- **`refactor`** — Internal restructuring with no behavior change (code quality, naming, structure). Use this for what was previously called `architecture`.

- **`infrastructure`** — Build system, CI/CD, deployment, tooling, or dependency changes.

- **`security`** — Security hardening, vulnerability fixes, auth changes, secrets management, access control.

- **`milestone`** — Completed phase, release, or significant deliverable. The "what we shipped" entries.

- **`strategy`** — Business decisions, market positioning, pricing changes, go-to-market pivots, competitive analysis conclusions. The "why we're doing it this way" entries. Use for purely non-technical context.

## Fields Explained

### Risk Level
Describes the blast radius and reversibility of the change:
- `low` — Isolated change, easy to revert, no shared state affected
- `med` — Touches shared code, multiple files, or has integration dependencies
- `high` — Affects shared infrastructure, auth, data models, or production systems

### Breaking Change
Whether this update changes a public contract, API, CLI behavior, or file format:
- `yes` — Existing consumers must update to remain compatible
- `no` — Backwards compatible, no consumer changes required

### Decisions Made
A dedicated section for recording explicit trade-off decisions: what options were evaluated, what was chosen, and why alternatives were rejected. Acts as a lightweight ADR (Architecture Decision Record) inline with the log entry. Populate this whenever an alternative approach was considered — even briefly — to prevent re-litigating settled decisions in future sessions.

## Entry Deprecation

As a project evolves, earlier devlog entries may contain decisions that were later reversed, superseded, or implemented differently. Without an explicit signal, Claude (and humans) may act on stale decisions buried deep in a growing DEVLOG.md. The deprecation mechanism solves this by marking outdated entries in-place.

### Supersession Marker

When an entry's decisions are no longer current, add a blockquote marker immediately after the entry heading, before the `**Category:**` line:

```markdown
## [2026-03-22] Original decision title
> **SUPERSEDED [2026-03-26]:** Replaced by [2026-03-26] d20Mob ruleset adopted. Reason: custom ruleset replaces SRD 5e as mechanical foundation.

**Category:** `strategy`
...
```

### Marker Rules

- **Format:** `> **SUPERSEDED [YYYY-MM-DD]:** Replaced by [date] replacement-entry-title. Reason: one-phrase explanation.`
- **Placement:** Immediately after the `## [date] title` heading, before `**Category:**`.
- **One marker per entry.** If an entry is superseded multiple times, update the existing marker to point to the latest replacement.
- **Partial supersession:** When only some decisions in an entry are stale, use: `> **PARTIALLY SUPERSEDED [YYYY-MM-DD]:** [which decisions are stale and why]. [which decisions remain current].`
- **Preserve the entry body.** The marker annotates; it does not rewrite history. The full original entry remains below the marker for historical reference.
- **User approval required.** Never add a SUPERSEDED marker without showing it to the user first. Supersession is a judgment call, not an automation.

### When Deprecation Happens

Deprecation review is part of the entry-creation workflow (see Step 2 below). Every time a new entry is written, Claude scans existing entries for conflicts and proposes SUPERSEDED markers alongside the new entry. This is not a separate manual step.

## When to Create Entries

### Proactive Suggestions (Claude-initiated)
At natural pause points or the end of substantive conversations, review what was discussed and suggest devlog entries for any of the following:

- A technical architecture decision was made or changed
- A meaningful piece of work was completed
- A strategic or business direction was established or shifted
- An important insight emerged that should persist across sessions
- A design trade-off was evaluated and a direction was chosen

Frame the suggestion naturally: "This feels like something worth capturing in the devlog — we decided X because of Y. Want me to log it?"

Do NOT suggest entries for:
- Routine Q&A or simple lookups
- Work that's still in-progress with no decision point
- Minor clarifications that don't change direction

### Ad-hoc Entries (User-initiated)
The user may say things like:
- "Log this"
- "Add this to the devlog"
- "This should go in the changelog"
- "Devlog: [description]"

When this happens, capture what the user is referring to — which may be the immediately preceding discussion, a specific decision, or something they describe explicitly.

## Workflow: Creating and Pushing an Entry

### Step 1: Draft the Entry
Write the entry following the format above. Include rich detail — the goal is that someone reading this months from now (including a future Claude session) can fully understand what happened and why.

### Step 2: Review for Superseded Entries
After drafting the new entry, scan the existing DEVLOG.md for decisions that the new entry conflicts with or replaces. This review is lightweight:

1. Scan entry **headings** (`## [date] title`), **Summary** sections, and **Decisions Made** sections only. Skip Detail bodies unless a heading or summary suggests a conflict.
2. For each conflict found, draft a SUPERSEDED or PARTIALLY SUPERSEDED marker (see Entry Deprecation above).
3. If no conflicts are found, proceed to Step 3 with no deprecations.

This scan is proportional to the number of entries, not the total line count. For a 15-entry DEVLOG, scanning headings + summaries + decisions is approximately 30-40 lines of reading.

### Step 3: Show the User
Present the drafted entry in the conversation. If Step 2 identified superseded entries, also present the proposed SUPERSEDED markers:

> "New entry ready. I also noticed that [2026-03-22] Original decision is superseded by this new entry — I'd like to add a SUPERSEDED marker to it. Here's the new entry and the proposed deprecation:"

Ask for confirmation or edits before committing. Never push without the user seeing the entry and any proposed deprecations first.

### Step 4: Update DEVLOG.md
**IMPORTANT: DEVLOG.md always lives inside the project repo root — never in a parent directory.**

Determine the correct path:
- **Local Claude Code session** (most common): The primary working directory IS the repo root. Use `{cwd}/DEVLOG.md` directly — e.g., if cwd is `/Users/alice/projects/my-app`, write to `/Users/alice/projects/my-app/DEVLOG.md`.
- **Remote/cloned session**: Use the cloned repo's root path in that environment.

Read the existing DEVLOG.md from that path (or create it if it doesn't exist). Insert the new entry at the top of the file, below the header. Entries are reverse-chronological (newest first). If the user approved any SUPERSEDED markers in Step 3, insert those markers into the affected entries as well.

If creating DEVLOG.md for the first time, use this header:

```markdown
# [Project Name] — Development Log

A living record of architectural decisions, milestones, key insights, and strategic direction.
Auto-maintained via [claude-devlog-skill](https://github.com/code-katz/claude-devlog-skill). Entries are reverse-chronological.

---
```

Replace `[Project Name]` with the actual project name established during session setup (e.g., "The Chronicle", "My API Service").

### Step 5: Archive if Needed
After updating DEVLOG.md, check whether archiving is warranted. Archiving moves superseded entries to a separate file to keep the active DEVLOG focused and within a manageable context window. See the **Archiving** section below for trigger conditions, file format, and rules.

### Step 6: Commit and Push
After the user approves, commit on the CURRENT branch. Never run `git checkout` or `git switch`: in parallel-session workflows the checkout you are in IS the session's branch, and the devlog entry should ride with the work it documents.

```bash
cd /path/to/repo
branch=$(git rev-parse --abbrev-ref HEAD)
git add DEVLOG.md
# If archiving occurred, also add DEVLOG-ARCHIVE.md
git add DEVLOG-ARCHIVE.md 2>/dev/null
git commit -m "devlog: [brief title from entry]"
git push origin "$branch"
```

Branch rules:
- On a feature or session branch, the entry reaches the default branch through the project's normal merge/PR flow, together with the work it documents.
- If a pre-commit hook rejects a commit on main/master (claude-team's branch guard does this by design), do not bypass it; move to a registered branch instead.
- If there is no remote or the push is rejected, keep the local commit and tell the user.

Use a commit message prefixed with `devlog:` followed by a short version of the entry title. If archiving occurred in Step 5, use: `devlog: [brief title] + archive N superseded entries`.

### Error Handling
- **Git not configured:** Prompt the user to provide their repo URL and set up authentication. Walk them through creating a Personal Access Token if needed.
- **Push fails:** Show the error, suggest common fixes (auth issues, branch protection, network). Offer to save the entry locally so it's not lost.
- **DEVLOG.md has merge conflicts:** Show the conflict, help resolve it, then retry.
- **No repo cloned locally:** Clone the repo first, then proceed.

## Archiving

As a project matures, superseded entries accumulate in DEVLOG.md. Archiving moves them to a separate file so the active devlog stays focused on current decisions and fits comfortably within Claude's context window.

### When to Archive

Archiving triggers during Step 5 of the workflow when **both** conditions are true:

1. DEVLOG.md exceeds approximately **50 entries** or **1,500 lines** (whichever comes first)
2. There are entries with **SUPERSEDED** markers available to archive

If either condition is not met, skip archiving. Small devlogs and devlogs with no superseded entries are never archived.

### What Gets Archived

Only entries with a `SUPERSEDED` or `PARTIALLY SUPERSEDED` marker. Current entries are **never** archived regardless of age. A 3-month-old architectural decision that is still in effect is more valuable in the active devlog than a 1-week-old decision that was reversed.

For `PARTIALLY SUPERSEDED` entries: do **not** archive. These entries still contain current decisions alongside stale ones. They remain in DEVLOG.md with their partial marker intact.

### Archive File Format

The archive file is `DEVLOG-ARCHIVE.md` in the same repo root as DEVLOG.md.

```markdown
# [Project Name] — Development Log Archive

Superseded entries moved from DEVLOG.md. Each entry's SUPERSEDED marker points to its replacement in the active devlog.
Auto-maintained via [claude-devlog-skill](https://github.com/code-katz/claude-devlog-skill). Entries are reverse-chronological.

---

## [2026-03-22] Original decision title
> **SUPERSEDED [2026-03-26]:** Replaced by [2026-03-26] d20Mob ruleset adopted. Reason: custom ruleset replaces SRD 5e.

**Category:** `strategy`
...full original entry preserved...

---
```

### No Tombstones

When an entry is moved to the archive, it is **removed entirely** from DEVLOG.md. No stub or placeholder is left behind. The superseding entry already exists in DEVLOG.md and provides the current context. If someone needs the historical record, `DEVLOG-ARCHIVE.md` is in the same directory.

### Archive Commit

If archiving occurs, stage both files and use the commit message format: `devlog: archive N superseded entries`.

## Git Setup (First-Time Per Session)

### Local Claude Code Session (Most Common)
If Claude Code's primary working directory is already inside the project repo, no setup is needed — the repo is already available locally. Verify with:

```bash
git -C /path/to/cwd rev-parse --show-toplevel
```

The output is the repo root. DEVLOG.md belongs there.

### Remote/Sandboxed Session
If the repo isn't available locally, clone it using the environment's own authentication: `gh auth`, a configured credential helper, or the platform's built-in git access. Never embed tokens in remote URLs; they persist in plaintext in `.git/config` and in shell history.

If commit identity isn't configured, set it for this repo only. Never modify the user'

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [code-katz](https://github.com/code-katz)
- **Source:** [code-katz/claude-devlog-skill](https://github.com/code-katz/claude-devlog-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-code-katz-claude-devlog-skill-devlog
- Seller: https://agentstack.voostack.com/s/code-katz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.