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

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.

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):

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

# Backlog

## Goal
[One sentence: what is this project building/solving?]

---

## Up next
[Max 3 items — what's actually happening now]
- [ ] Task

## Blocked
[Items waiting on external input — include reason and date blocked]

## Backlog
[Everything else that needs doing, in rough priority order]
- [ ] Task

# Done
[Flat list of completed items — no detail, that lives in PROGRESS.md]

6. Create PROGRESS.md

# Progress

[Completed tasks, newest first. Written by /briefs-done — one foldable entry
per task: `### Task name (YYYY-MM-DD)`, commit SHA, what/why, scope, key
decisions.]

7. Create NOTES.md

# 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).