briefs-work
npx machina-cli add skill naxoc/claude-briefs/briefs-work --openclawBriefs: Start Work Session
Keeps sessions focused. One task at a time, always know the next step.
Starting a Session
Step 1: Find the briefs folder. Check these in order:
- Read
.claude/briefs-pathfor a saved path - Check if
.briefs/exists in the project root - If neither works, ask the user for the path
Step 2: Read CURRENT.md. If there's an active task, summarize it and ask: "Pick up where we left off, or start something new?"
Step 3: Get to work. Match your behavior to what the task actually involves:
- Investigating → You're researching, reading, exploring, or trying to understand something. Report what you find, ask clarifying questions. Don't jump to solutions until the problem is understood.
- Planning → You're figuring out the approach - whether that's a project plan, a document outline, a migration strategy, bugfixing, coding something, or a technical design. Ask one question at a time, propose 2-3 short options, get approval before doing the work.
- Doing → You're producing the actual work - writing code, drafting content, building spreadsheets, creating documents, whatever the deliverable is. Describe what you'll do before doing it. Break large work into chunks and check in after each piece.
- Reviewing → You're checking, auditing, proofreading, or evaluating something. List what you find in bullets. Don't fix or change things unless asked.
File Updates
Update the briefs files at these moments:
- CURRENT.md - After completing a step, hitting a blocker, or changing direction. Always keep it reflecting the actual state.
- PROGRESS.md - After completing a task. Keep entries concise.
- PLAN.md - When tasks are added, completed, or reprioritized.
- NOTES.md - When you learn something worth remembering across sessions.
Rules
- One task at a time. The PLAN can be huge but we always know the next step because it's in CURRENT.md.
- Don't use numbered lists unless absolutely necessary. They make reordering painful.
- Keep all output concise. If you're writing more than a screenful, stop and ask if the user wants the rest.
Overview
briefs-work helps you begin every work session by loading the saved state from a briefs path and CURRENT.md. It summarizes any active task, applies constraints to stay focused, and guides you through Investigating, Planning, Doing, and Reviewing to deliver one task at a time.
How This Skill Works
It locates a briefs path by checking .claude/briefs-path, then .briefs/ in the project root, or prompts for a path. It reads CURRENT.md to summarize the active task and asks whether to pick up where you left off or start something new, then you work in one of four modes—Investigating, Planning, Doing, or Reviewing—with explicit behavior and progress checks. After steps, you update CURRENT.md, PROGRESS.md, PLAN.md, and NOTES.md as appropriate.
When to Use It
- Starting a session: locate the briefs path and load CURRENT.md to decide whether to resume or start fresh.
- Resuming work: summarize the active task and confirm the next step to take.
- Investigating: research, read, and clarify the problem before proposing a solution.
- Planning: define the approach, present 2-3 short options, and get approval before acting.
- Doing or Reviewing: execute work in chunks, describe planned actions, and audit results.
Quick Start
- Step 1: Locate the briefs path (.claude/briefs-path) or .briefs/ in the project root, then read CURRENT.md.
- Step 2: If an active task exists, summarize it and decide to pick up or start something new.
- Step 3: Enter a mode (Investigating, Planning, Doing, or Reviewing) and work in chunks, updating CURRENT.md and PROGRESS.md as you go.
Best Practices
- Always locate the briefs path before starting.
- Read CURRENT.md and summarize any active task; decide to resume or start new.
- Keep one task at a time and progress in small chunks.
- In Planning, propose 2-3 short options and seek approval before acting.
- Update CURRENT.md, PROGRESS.md, PLAN.md, and NOTES.md as you go.
Example Use Cases
- Open a repo, locate the briefs path, read CURRENT.md, and find an active task; summarize and decide to resume.
- Investigating: research an API contract, list findings and clarify questions.
- Planning: outline the approach, present 2-3 options, and obtain confirmation.
- Doing: implement a feature in chunks and report progress after each piece.
- Blocker occurs: update CURRENT.md to reflect changes and re-plan.
