DevDay

A two-command journal for any git repo. Git captures what changed. You forget why by Friday. DevDay closes that gap.

DevDay is a Claude Code plugin — but the spec is self-contained. The same two commands run as plain shell, in any agent, in any git repository. Git is the only hard requirement.

• /devday-log — append a timestamped checkpoint to today's log while you work
• /devday — synthesise the day into a structured report at end of session

The methodology predates the skill. Hundreds of devlogs accumulated over months across every kind of git work — software, research, writing, infrastructure, talks, client work, side experiments — before this was packaged as a portable convention in May 2026.

Background read: DevDay — a two-command journal for any git project · Project page: smarason.is/en/projects/devday

---

Install — pick one

1. Tell your agent (works in Claude Code, Cursor, any agent that reads READMEs)

Paste this into the chat:

Install DevDay from https://github.com/Magnussmari/devday — read the README,
set up the /devday and /devday-log commands, and confirm when ready.

The agent reads this repo, places the skill and commands under ~/.claude/, and you're done. No flags, no manual paths.

2. Claude Code plugin marketplace

/plugin marketplace add Magnussmari/devday
/plugin install devday@devday

This installs DevDay as a managed Claude Code plugin — updates land via /plugin update.

3. One-line shell install

curl -fsSL https://raw.githubusercontent.com/Magnussmari/devday/main/install.sh | bash

Idempotent. Re-run anytime to update. Uninstall:

curl -fsSL https://raw.githubusercontent.com/Magnussmari/devday/main/install.sh | bash -s -- --uninstall

4. Manual (curl the files yourself)

Expand

# Skill
mkdir -p ~/.claude/skills/DevDay
curl -fsSL https://raw.githubusercontent.com/Magnussmari/devday/main/skills/devday/SKILL.md \
  > ~/.claude/skills/DevDay/SKILL.md

# Slash commands
mkdir -p ~/.claude/commands
curl -fsSL https://raw.githubusercontent.com/Magnussmari/devday/main/commands/devday.md \
  > ~/.claude/commands/devday.md
curl -fsSL https://raw.githubusercontent.com/Magnussmari/devday/main/commands/devday-log.md \
  > ~/.claude/commands/devday-log.md

---

First run

cd <any git repo>
/devday-log    # auto-orients; prints one line confirming project + log dir

From the second invocation onward, the orient step is invisible. If the auto-detected layout is not what you want, edit .devday/config.json once and commit. The skill respects the config from then on.

If you do not use Claude Code, skills/devday/SKILL.md is a self-contained specification — implement the same two commands in any agent or as plain shell scripts. Git is all the runtime you need.

---

Why this works when other journals do not

Three design choices, each from a real failure:

1. The only hard requirement is git. No database. No external app. No login. If you are in a git repository, DevDay works. If you are not, DevDay refuses to run and tells you so in one line. Knowledge-management experiments die on a second source of truth. Git is already the source of truth for code; the journal lives next to it.

2. The skill orients itself on first run. Phase 0 detects the project name from package.json / pyproject.toml / Cargo.toml / go.mod / repo basename — whichever it finds first. It probes a sensible log directory (docs/devlogs/, .devlogs/, falling back to creating one). It detects the default branch. It writes .devday/config.json so it never has to ask again. From the second invocation onward, orient is a one-line cache hit.

3. Append-only checkpoints, idempotent synthesis. /devday-log only ever appends — you cannot accidentally corrupt yesterday's notes. /devday rewrites today's file from scratch each time, preserving the checkpoint log verbatim. Run the synthesiser five times and get the same report.

---

File layout

your-project/
├── .devday/
│   └── config.json                              # orient cache, committed
├── docs/devlogs/                                # default; auto-probed
│   └── 2026/
│       └── 05-may/
│           ├── devday_20260519.md
│           ├── devday_20260520.md
│           └── …
└── (everything else)

fileNamingScheme: "yearMonth" (default, scales for years of history) or "flat" for small projects.

---

Configuration (.devday/config.json)

{
  "version": 1,
  "projectName": "smarason.is",
  "tagline": "Portfolio website for Magnús Smári Smárason — Next.js 16 + Sanity",
  "logDir": "docs/devlogs",
  "defaultBranch": "main",
  "fileNamingScheme": "yearMonth",
  "orchestrator": "Magnus Smárason | smarason.is",
  "createdAt": "2026-05-20T08:36:00Z"
}

Field	Required	Notes
version	✓	Schema version (currently 1).
projectName	✓	Display label only. Auto-detected from manifest files; edit freely.
tagline		Short subtitle for the log header. Optional.
logDir	✓	Where daily logs live. Default docs/devlogs.
defaultBranch	✓	Used for git-log queries when no branch is specified.
fileNamingScheme	✓	"yearMonth" or "flat".
orchestrator		Optional. Free-text — name, email, handle, internal ID. When set, every log header is signed. See "Responsibility" below.
createdAt	✓	ISO-8601 timestamp, set on orient.

A full example lives at docs/examples/config.json.

---

The orchestrator field — responsibility as enactment

DevDay has one optional config field worth dwelling on: orchestrator. If set, the skill writes a signature line into every log header — the value is whatever string you choose: a name, an email, a handle, an internal ID, a team tag.

**Orchestrator:** Magnus Smárason | smarason.is

The point is not provenance metadata. The point is enactment. AI-assisted work is real work, and the human who set the prompt, accepted the suggestion, merged the PR remains responsible for what got built. The devlog is where that responsibility shows up in writing, day after day, in the orchestrator's own name. It is a small ritual — three words, a pipe, a domain. It is also a quiet contract with the future reader of the file: I did this. Push back on me, not the agent.

The field is off by default. Use it where authorship matters; skip it where it does not.

---

Example entry

A real entry from smarason.is is included at docs/examples/devday_20260519.md. Below is the structure (trimmed):

# Dev Day Log: 2026-05-19 (Monday)
## Project: smarason.is — Portfolio website for Magnús Smári Smárason

**Orchestrator:** Magnus Smárason | smarason.is

### Summary
<2-4 sentences. Specific numbers. Real PR hashes. No marketing.>

---

## 📊 Commits Today
| Hash       | Message                                        | Time  |
| ---------- | ---------------------------------------------- | ----- |
| `559e18ac` | fix(blog): filter null categories in renderer  | 10:14 |
| `d6ccd572` | feat: Scite — Webinar page + release BORG (#23)| 14:30 |
| …          |                                                |       |

## 🧠 Decisions Made
1. **Decision:** <what was chosen>
   **Why:** <what we tried first, what broke, what shipped>
   **Impact:** <follow-up consequences>

## 🎯 Session Quality
**Flow:** high — five distinct phases, no drift between them
**Blockers:** significant but resolved — three pre-existing Sanity null-reference crashes…
**Overall:** <one paragraph honest assessment>

The Decisions Made section is where the long-term value lives. A commit message says Merge #691. A decision entry says why we chose tar+npm-ci over docker exec and what we tried first that broke. Six months from now, that decision is the difference between three minutes and three hours.

---

What I actually use it for

• As a debugger for my own week. I scan the last seven daily logs on a Monday morning. Anything in Next Steps carried forward three days in a row gets done, dropped, or escalated. The journal makes drift visible.
• As a handoff document. When a teammate jumps into a branch I have been on, I send them today's log. Five minutes of reading instead of fifteen of explanation.
• As input to higher-order analyses. The day-files are ingestible by an AI — feed a week of them to Claude and you get a surprisingly accurate "what did Magnús actually work on this week" summary, with the why preserved. Not possible from git alone.

---

Repo layout

devday/
├── .claude-plugin/
│   ├── plugin.json                # Claude Code plugin manifest
│   └── marketplace.json           # makes this repo a single-plugin marketplace
├── skills/devday/SKILL.md         # canonical spec
├── commands/
│   ├── devday.md                  # /devday slash command
│   └── devday-log.md              # /devday-log slash command
├── install.sh                     # one-line shell installer
├── docs/examples/                 # config + example log entry
└── README.md

---

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Bug reports and feature ideas have templates under .github/ISSUE_TEMPLATE/.

---

License

MIT — © 2026 Magnús Smári Smárason. If you try it, I want to hear what stuck and what did not. The skill is opinionated; those opinions came from real failures and they are open to revision.