# DevDay

> |

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

## Install

```sh
agentstack add skill-magnussmari-devday-devday
```

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

## About

# 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

```bash
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

```bash
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

```bash
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:

```json
{
  "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

```bash
# 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:

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

**Orchestrator:**    

---

```

### Step 1.3 — Append the checkpoint

**Never overwrite existing content.** Append:

```markdown
## 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:

```bash
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.

```markdown
# 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:

```json
{
  "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:

```bash
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](https://github.com/Magnussmari)
- **Source:** [Magnussmari/devday](https://github.com/Magnussmari/devday)
- **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-magnussmari-devday-devday
- Seller: https://agentstack.voostack.com/s/magnussmari
- 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%.