# Briefs Setup

> Briefs Setup

- Skill: `naxoc/briefs-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add naxoc/briefs-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/naxoc/briefs-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: naxoc (https://skillmd.com/u/naxoc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/naxoc/briefs-setup

---


# Setup Claude Briefs

Creates the Briefs project management structure in the current project. Briefs
is a lightweight system for managing focus across sessions - for both humans
and LLMs.

## What This Creates

A briefs directory with four files:
- **CURRENT.md** - The heart of the system. One active task: context, planned approach, task list, session log.
- **BACKLOG.md** - The larger project plan: up next, blocked, backlog, done.
- **PROGRESS.md** - The long-term memory. Completed tasks with backstory and decisions. Written only by `/briefs-done`.
- **NOTES.md** - Technical notes, gotchas, and references that outlive any single task.

The lifecycle that maintains them: `/briefs-plan` (settle the approach) →
`/briefs-work` (execute, repeatable sessions) → user reviews and commits →
`/briefs-done` (review against plan, archive, reset). `/briefs-health` audits
when things feel muddled.

## Steps

**1. Ask where to put the briefs folder**

Ask: "Where should I create the briefs folder?"

Present two options:
- **With this project** - creates `.briefs/` in the project root. Suggest adding `.briefs/` to `.gitignore` (these are working notes, not source code).
- **Somewhere else** - user provides an absolute path. Good for people who keep notes in Obsidian, a shared docs folder, or anywhere outside the repo.

**2. Create the directory**
```bash
mkdir -p <chosen-path>
```

**3. Save the path**

Create `.claude/briefs-path` containing the absolute path to the briefs folder. This lets the other briefs skills find it automatically in future sessions.

```bash
mkdir -p .claude
echo "<absolute-path-to-briefs-folder>" > .claude/briefs-path
```

If `.briefs/` was chosen inside the project, store the absolute path anyway for consistency.

**4. Create CURRENT.md**

The skeleton every skill in the family expects (`/briefs-plan` fills it,
`/briefs-work` maintains it, `/briefs-done` archives and resets it):

```markdown
Working on: **<nothing — pick a task with /briefs-plan>**
Branch: 

# Context

# Approach

# Task list

# Log

# Review notes
```

If the user already has an active task, offer to fill in `Working on:` and
`# Context` from their description now — and point them at `/briefs-plan` for
the Approach.

**5. Create BACKLOG.md**
```markdown
# Goal
[One sentence: what is this project building/solving?]

---

# Blocked
[Waiting on someone outside the project. Each says who, and since when.]

# Backlog
[Everything that needs doing, roughly ordered — the top few are what matters
next, the rest is a holding pen.]

## One item, as a heading
*tag · optional metadata*

Prose, measurements, links, sub-bullets — whatever the item needs.

# Done
Completed work lives in **PROGRESS.md** — what was built, why, and the commit.
This file is for what is still outstanding.
```

**No `# Backlog` title at the top.** The filename says it, and a `# Backlog`
containing a `## Backlog` reads as though one nests inside the other. Sections are
`#`, items are `##`.

**Items are `##` headings, not checkboxes.** A backlog item grows: measurements,
a settled decision, a correction, the reason something was deferred. Checkbox
list items fight that — continuation lines need a hanging indent, and the whole
thing renders as one bullet no matter how long it gets. Headings fold in Obsidian,
appear in the outline panel, and can be linked to as
`[[BACKLOG#One item, as a heading]]`.

The checkbox instinct is right for CURRENT.md's `# Task list`, where an item
really is a thing you tick within one session. It is wrong here, where an item is
a small document that may sit for weeks.

**Completed items are deleted, not listed.** PROGRESS.md already records what was
built, when, and with which commit; a `# Done` list in the backlog is a second
copy that drifts. Keep the `# Done` heading as a one-line pointer so a reader
knows where the history went.

**Older briefs use `- [ ]` checkbox items** with indented continuation lines. Both
shapes are readable; the other briefs skills handle either. Don't convert an
existing file just because you are passing through — but do write new items as
headings, and keep one file to one style.

**6. Create PROGRESS.md**
```markdown
[Completed tasks, newest first. Written by /briefs-done — one foldable entry
per task: `## Task name (YYYY-MM-DD HH:MM)`, commit SHA, what/why, scope, key
decisions, and the fixtures and commands it was tested with.]
```

**No `# Progress` title**, for the same reason BACKLOG.md has none: the filename
says it, and a title wrapping every entry makes the entries `###` for no gain.
Entries are `##`, so they are top-level siblings and fold cleanly.

**7. Create NOTES.md**
```markdown
# Notes

[Key learnings, gotchas, and reference material]
```

**8. If project-local, offer to gitignore**

If the briefs folder is inside the project, check if `.gitignore` exists and offer to add the folder to it.

**9. Confirm completion**
Show what was created and where it lives. Suggest `/briefs-plan` to plan the first task (or `/briefs-work` if there's already a plan to execute).