briefs-setup
npx machina-cli add skill naxoc/claude-briefs/briefs-setup --openclawSetup 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. Current phase, tasks, context.
- PLAN.md - The larger project plan, broken into phases with tasks.
- PROGRESS.md - Completed tasks and decision log. Updated after each task.
- NOTES.md - Technical notes and references.
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 briefs-work 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
# Current Task
**Phase:** Exploring
## Context
[Anything needed to pick this back up cold. Ask the user for context about the current task, and save it here.]
## Tasks
[Break down the current phase into actionable tasks]
- [ ] Task
5. Create PLAN.md
# Project Plan
## Goal
[One sentence: what is this project building/solving?]
## Phase 1:
- [ ] Task 1
- [ ] Task 2
## Phase 2:
- [ ] Task 1
- [ ] Task 2
6. Create PROGRESS.md
# Progress
## Completed
[Log completed tasks here with date and time]
## Decisions
[Key decisions and why they were made]
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, where it lives, and suggest running /briefs-work to start a session.
Source
git clone https://github.com/naxoc/claude-briefs/blob/main/briefs-setup/SKILL.mdView on GitHub Overview
This skill automates creating a Claude Briefs management folder in a project. It generates a briefs directory that contains four markdown files—CURRENT.md, PLAN.md, PROGRESS.md, and NOTES.md—to organize focus across sessions for both humans and LLMs.
How This Skill Works
The tool guides you to choose where to place the briefs folder, creates the directory, and stores the absolute path in .claude/briefs-path so future sessions can locate it automatically. It then creates the four template files (CURRENT.md, PLAN.md, PROGRESS.md, NOTES.md) and, if the folder is inside the project, optionally suggests adding it to .gitignore. After setup you can start a session with /briefs-work.
When to Use It
- Starting a new project and want a lightweight, standardized briefing system.
- Migrating ad-hoc notes into a formal Briefs structure for consistency.
- Collaborating with a team that needs a shared focus protocol for sessions.
- Setting up briefs in a repo to support sprint planning and task tracking.
- Storing notes outside the repo (Obsidian or docs folder) and linking via an absolute path.
Quick Start
- Step 1: Decide where to place the briefs folder (project root or absolute path).
- Step 2: Create the directory and save the absolute path to .claude/briefs-path.
- Step 3: Create CURRENT.md, PLAN.md, PROGRESS.md, and NOTES.md from the templates and start a session with /briefs-work.
Best Practices
- Decide the briefs folder location up front and stick with it.
- Keep CURRENT.md updated with the live context after each task.
- Use PLAN.md to outline phases and track progress.
- Log decisions and completed tasks in PROGRESS.md with timestamps.
- If the briefs folder is project-local, add it to .gitignore to avoid accidental commits.
Example Use Cases
- Software project initializes a repo root briefs directory for sprint planning.
- Research project uses CURRENT.md and PLAN.md to coordinate literature review tasks.
- Monorepo teams share a briefs folder across services with a single .claude/briefs-path.
- An individual stores notes outside the repo (Obsidian) and points to it via the path file.
- A new project configures Briefs and runs /briefs-work to begin an ongoing focus session.
