DevDay

DevDay — Project-Agnostic Dev Session Journal

A two-command journal that turns a working day in any git repo into a durable, skimmable record. You write the work. Git captures the evidence. DevDay turns both into a journal your future self (and your team) will actually re-read.

The only requirement is that you're inside a git repository. Everything else is auto-detected on first run and cached.

---

The Two Commands

| Command | Purpose | Speed | When to run | |---------|---------|-------|-------------| | /devday-log | Append a timestamped checkpoint | Seconds | After every meaningful chunk of work | | /devday | Synthesize today's full report | ~30s | End of day, or when you wrap a session |

/devday-log is the append-only data feed. /devday is the read-only synthesizer. You can run /devday-log ten times a day and /devday once. The synthesizer reads the checkpoints AND the git log and produces the final artifact.

---

Phase 0 — Orient (runs on first invocation per project)

This phase is mandatory on first run and idempotent thereafter. It establishes how the skill behaves inside this specific repository, then caches the result so future runs skip straight to the work.

Step 0.1 — Verify git

git rev-parse --is-inside-work-tree

If this fails or returns false, abort with a one-line message: DevDay requires a git repository. Run \git init\ first, or change into a project directory. Do not try to operate without git — git is the evidence layer.

Step 0.2 — Locate project root and load cache

PROJECT_ROOT=$(git rev-parse --show-toplevel)
CONFIG_PATH="$PROJECT_ROOT/.devday/config.json"

If $CONFIG_PATH exists, read it and skip to Phase 1 or Phase 2. The config is project-local, committed to git, and shared across the team.

Step 0.3 — Detect project name (in priority order)

Stop at the first match.

1. package.json → name field
2. pyproject.toml → [project] name or [tool.poetry] name
3. Cargo.toml → [package] name
4. go.mod → first module line, last path segment
5. pom.xml → ``
6. Gemfile (Ruby) → directory basename
7. Repository remote URL → last segment minus .git
8. Fallback: basename "$PROJECT_ROOT"

Strip scopes (@org/name → name) and lowercase if needed. This is just a display label; don't agonize.

Step 0.4 — Detect or create the devlog directory

Probe in priority order. Stop at the first directory that exists.

1. docs/devlogs/
2. docs/devlog/
3. devlogs/
4. devlog/
5. .devlogs/
6. .claude/session-reports/

If none exists, create docs/devlogs/ when a docs/ directory is already present, otherwise create .devlogs/. The directory does not need to be in .gitignore — these logs are valuable history.

Step 0.5 — Detect default branch

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

Fallback chain: main → master → trunk → current branch.

Step 0.6 — Optional: read project tagline

Look for a one-line description in this order. Truncate to 80 chars. This shows up in the log headers as ## Project: — .

1. package.json → description
2. pyproject.toml → description
3. Cargo.toml → description
4. README.md → first paragraph after the H1 (best-effort)
5. Empty (skip)

Step 0.7 — Write the config

Create .devday/config.json at project root:

{
  "version": 1,
  "projectName": "BORG",
  "tagline": "Stafrænt þróunarumhverfi",
  "logDir": "docs/devlogs",
  "defaultBranch": "main",
  "fileNamingScheme": "yearMonth",
  "orchestrator": "Magnus Smárason | smarason.is",
  "createdAt": "2026-05-19T13:00:00Z"
}

fileNamingScheme options:

• "yearMonth" — /YYYY/MM-monthname/devday_YYYYMMDD.md (default; scales)
• "flat" — /devday_YYYYMMDD.md (smaller projects)

If a project already has many existing logs under one scheme, respect it — don't silently migrate. Detect by looking for files matching either pattern under logDir/.

orchestrator (optional). Free-text string — a name, an email, a handle, a tag. When set, every log header includes an **Orchestrator:** line beneath the project title (see Step 1.2 and Step 2.3). The skill never auto-fills this field; if the user hasn't asked for it explicitly, leave it absent and omit the header line. The point is enactment — when set, every devlog is signed by the human responsible for the AI-assisted work captured inside it. This is opt-in; many projects won't want it.

Step 0.8 — Confirm orientation in one line

After Phase 0, print exactly one line to the user, then proceed to whatever they actually asked for:

DevDay oriented:  @ / (branch: ). Config cached at .devday/config.json.

If config already existed, skip this line entirely — orient is silent on subsequent runs.

---

Phase 1 — /devday-log (Append a Checkpoint)

Goal: capture what's happening right now in a few seconds. No synthesis. No git log walking. Just a timestamped snapshot of context.

Step 1.1 — Run config-load + git context in parallel

# All in one parallel batch:
git log --oneline -8 --format="%h %s (%ar)"
git diff --stat HEAD~3 HEAD 2>/dev/null
git branch --show-current
date "+%H:%M"

Step 1.2 — Resolve today's log file

/YYYY/MM-monthname/devday_YYYYMMDD.md

Where MM-monthname is e.g. 05-may, 12-december. Lowercase English month names.

Examples:

• docs/devlogs/2026/05-may/devday_20260519.md
• .devlogs/2026/01-january/devday_20260108.md

If fileNamingScheme is "flat", just /devday_YYYYMMDD.md.

Create parent directories if missing. If the file doesn't exist, write this header first:

# Dev Day Log: YYYY-MM-DD
## Project:  — 

**Orchestrator:**    

---

Step 1.3 — Append the checkpoint

Never overwrite existing content. Append:

## HH:MM — 

**Branch:** ``
**Recent commits:**
- `` 
- `` 

**What's happening:**

**Files in focus:**
- `` — 
- `` — 

---

If the user passed a note as argument (/devday-log "just finished the migration"), use it as the summary line and the headline of "What's happening". Still pull the rest from git.

Step 1.4 — Confirm

One-line response:

Logged @  → .  entries today. Run /devday at end-of-day for the full report.

---

Phase 2 — /devday (Synthesize the Day)

Goal: produce a single, polished markdown report that captures today's work in a form worth re-reading next week, next quarter, or by a stranger.

Step 2.1 — Load context (parallel)

Run these simultaneously:

git log --all --since="6am" --pretty=format:"%h|%an|%ai|%s|%D" --no-merges
git log --all --since="6am" --until="now" --shortstat --no-merges
git diff --stat HEAD~10 HEAD 2>/dev/null
git status --short
git branch --show-current

Read today's existing log file (if any) — its ## HH:MM — checkpoint entries are the narrative backbone.

Step 2.2 — Decide path

If today's log exists: read it. Extract all ## HH:MM — checkpoints. The synthesis enriches the file — preserves checkpoints verbatim, adds the structured sections around them.

If no log file: generate from scratch using git history alone.

Step 2.3 — Synthesize

Write the report using this template. Treat checkpoints as authoritative narrative; git is evidence.

# Dev Day Log:  ()
## Project:  — 

**Orchestrator:**    

### Summary

---

## Checkpoint Log

---

## 📊 Commits Today

| Hash | Message | Time |
|------|---------|------|
| `abc1234` | feat: ... | 14:32 |

**By type:**
- **feat:** X  — **fix:** X  — **docs:** X  — **chore:** X — **other:** X

---

## ✅ Key Accomplishments

- 
- 
- 

---

## 🧠 Decisions Made

1. **Decision:** 
   **Why:** 
   **Impact:** 

---

## 🔄 Next Steps

- [ ] 
- [ ] 
- [ ] 

---

## 🎯 Session Quality

**Flow:** high / medium / low
**Blockers:** none / minor / significant
**Overall:** 

---

## Session Summary

**Total Commits:** X
**Estimated Duration:** X hours (first commit → last commit)
**Files Modified:** X
**Lines:** +X / -X

**Final Verification:**
- ✅ 
- ✅ 
- ✅ 

**Status:** 

---

*Generated by DevDay v2 — *

Step 2.4 — Categorize commits

Use conventional-commit prefixes (feat:, fix:, docs:, refactor:, test:, chore:, perf:, ci:, build:, style:, revert:). Commits without a recognized prefix go in Other. Don't moralize about non-conventional commits — just bucket them.

Step 2.5 — Estimate duration

First-commit-of-day timestamp → last-commit-of-day timestamp. Round to nearest 15 min.

If only one commit, report ` 90 min) with no checkpoints, call it out as "split sessions" in Session Quality.

Step 2.6 — Extract decisions

Look for decision indicators in commit messages and checkpoint entries:

• "chose X over Y", "decided to...", "switched from X to Y"
• "migrated to...", "replaced X with Y", "opted for..."
• Anything in a **Decision:** line inside a checkpoint

Promote these to the 🧠 Decisions Made section with rationale and impact filled from context.

Step 2.7 — Vibe / Session Quality heuristics

| Signal | Flow | Blockers | |--------|------|----------| | Many short-interval commits, focused branch | High | — | | Steady progress, some gaps | Medium | — | | Long gaps, few commits, context switching | Low | — | | Revert/fix loops visible in git log | — | Minor or Significant | | Multi-attempt commits on same area | — | Minor | | Clean linear history, green CI | — | None |

Be honest. A medium-flow day with significant blockers is more useful than a fake "high-flow productive!" assessment.

Step 2.8 — Write the file

Overwrite today's log file with the enriched report. The checkpoints from Phase 1 are preserved verbatim under ## Checkpoint Log. Everything else is fresh synthesis.

Step 2.9 — Confirm

Print to user:

DevDay report → 
  ·  commits ·  checkpoints ·  files changed
  · 
  · Next: 

---

Optional Integrations

DiaryLog / life-logging

After Phase 2, optionally offer to log the session:

{
  "time": "HH:MM",
  "what": "Dev session: ",
  "mood": "",
  "tags": ["work", "development"],
  "note": ""
}

Don't force this — only offer if a DiaryLog skill is detected in the environment.

Auto-commit the log

If the user has explicitly opted in (via .devday/config.json field "autoCommit": true), stage and commit the log:

git add 
git commit -m "docs(devday): YYYY-MM-DD session report"

Default is false. Many users prefer to commit logs as part of a batch.

Weekly review

A future /devweek could aggregate Mon–Sun logs into a weekly view. Out of scope here, but the file layout (YYYY/MM-monthname/devday_YYYYMMDD.md) is designed to support it.

---

Why These Defaults

• Git is the only hard requirement. Anything else (docs/, monorepo, single-package,

Python, Rust, Node) is auto-detected.

• Config is committed. The team shares the convention. If you don't want the config

in git, add .devday/ to .gitignore — Phase 0 will rerun and rebuild it.

• Checkpoints over end-of-day-only. Your future self forgets why by 18:00. Capture

the why at 11:30 when it's fresh.

• Markdown, not HTML. Re-readable in GitHub, in your editor, in cat, on paper.
• Append-only checkpoint log. No risk of /devday-log corrupting an existing entry.
• Synthesizer is idempotent. Running /devday twice produces the same report.

---

Anti-patterns to avoid

• Don't run /devday-log to record trivia. "Started thinking about X" is noise.

Record finished thoughts, finished work, finished decisions.

• Don't synthesize without checkpoints if the day was non-trivial. A 6-commit day

with no checkpoints will produce a thin report — git messages alone miss the why.

• Don't put credentials in checkpoints. They land in git log once committed. Treat

the log as you treat any committed source file.

---

Reference: file paths the skill writes

| File | When | Notes | |------|------|-------| | .devday/config.json | First run per project (Phase 0) | Commit it | | /YYYY/MM-monthname/devday_YYYYMMDD.md | Every /devday-log and /devday | Append-only via /devday-log; rewritten by /devday |

---

Versioning

• v1.x — BORG-specific, Magnús's personal workflow at smarason.is / unak.is
• v2.0 — Generalized, project-agnostic. First-run Phase 0 Orient. Works in any git repo.

Issues, PRs, and ports welcome.

---

Created 2026-02-14 · Generalized 2026-05-19 · Magnús Smári Smárason · MIT

Source & license

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

• Author: Magnussmari
• Source: Magnussmari/devday
• License: MIT

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