Focus Tree

Session content focus tree with checklist tracking. Extracts decisions, TODOs, constraints, and context into a single-root hierarchical structure for better conversation alignment and task management.

Core Principles

1. Alignment — Maintain synchronized understanding between agent and user. The FOCUS.md serves as a shared source of truth that both parties can reference.

1. Focus — Keep the agent anchored to the current task. Prevents drifting between topics or losing track after session compactions.

1. Planning — Enable structured, step-by-step task execution. Break down complex work into manageable hierarchical sub-tasks with clear progress tracking.

When to Read FOCUS.md

• Every session start (before responding to first message)
• After every compaction (if context feels thin, read it)
• When the user asks about current work ("what are we doing?", "where were we?")

When to Write/Update FOCUS.md

Agents update FOCUS.md directly using file tools when:

Additional actions:

• When work is DONE — append to FOCUS-LOG.md and clear/write new FOCUS.md
• Before compaction memory flushes — ensure FOCUS.md reflects current state

Rules

1. One focus at a time. If the user pivots, archive the old focus first.
2. Keep it short. FOCUS.md should be <50 lines. It's a resume point, not a journal.
3. 📖 Context is sacred. Always update it before stopping work. Future-you reads this first.
4. Don't duplicate memory files. FOCUS.md tracks what we're doing now. Daily memory files track what happened. Different jobs.
5. Archive when done. Append completed focuses to FOCUS-LOG.md with completion date and outcome, then clear FOCUS.md.
6. Read it, don't ask. If FOCUS.md exists, read it and resume. Don't ask "what were we working on?" when the answer is in the file.

File Roles

Focus Tree uses three distinct files for different purposes:

Key principle: FOCUS.md tracks what we're doing now. Daily memory files track what happened. FOCUS-LOG tracks what we finished. Different jobs.

FOCUS.md Structure

Focus Tree uses a hierarchical tree structure. Here's the complete format:

# FOCUS.md - Current Focus

🎯 **Focus Point**: [Task Name]

**Started:** [Date]
**Status:** [active/paused/blocked]

📝 TODOs
☐ [Task 1]
☐ [Task 2]

📖 Context
[Current context/notes]
🚧 [Blocker if any]

Tree View

Hierarchical structure showing nesting levels:

🎯 Focus Point (Root)
├── 📌 Decisions
├── 📝 TODOs (max 2 levels)
│   ├── ✅ Level 1 task
│   │   ├── Level 2 sub-task (no icon)
│   │   └── Level 2 sub-task
│   └── ⏳ Level 1 task
├── ⚠️ Constraints
├── 🤖 Sub-Agents
└── 📖 Context
    └── 🚧 Blockers

Field Reference

Usage

Focus Tree operates on FOCUS.md and FOCUS-LOG.md directly.

Option 1: CLI Script (recommended)

node scripts/focus.mjs init "Project Name"    # Initialize
node scripts/focus.mjs add-todo "Task"        # Add task
node scripts/focus.mjs done 1                 # Mark done
node scripts/focus.mjs status active          # Update status
node scripts/focus.mjs archive "Outcome"      # Archive

Option 2: Direct File Operations

read /path/to/workspace/FOCUS.md
edit /path/to/workspace/FOCUS.md
  old: "☐ Incomplete task"
  new: "✅ Completed task"

Context Section Details

The 📖 Context section serves as the "Active State" — it's the resume point after compaction.

What to include:

• What was the last thing done
• What's the next action
• Any blockers or waiting

Always update Context before stopping work. Future-you will read this first.

Content Parsing

When editing FOCUS.md, agents should use these section prefixes:

Display Format

• TODOs Level 1: Icon prefix
• ✅ = completed
• ⏳ = in progress
• ☐ = pending
• TODOs Level 2: Plain list, no icon prefix
• Decisions: prefix 📌
• Constraints: prefix ⚠️
• Context: prefix 📖

FOCUS-LOG.md Format

Append-only log of completed focuses:

# Focus Log

## [Project Name] — COMPLETED YYYY-MM-DD
**Duration:** X hours/days
**Outcome:** One-line result

## [Project Name] — ARCHIVED YYYY-MM-DD
**Duration:** X hours/days
**Outcome:** Partial completion note
**Status:** incomplete

Integration with AGENTS.md

Add to your session-start routine, after reading SOUL.md and USER.md:

• Read FOCUS.md if it exists → resume work or acknowledge status
• If no FOCUS.md exists → check MEMORY.md for recent context
• Proceed with current focus or start new

Integration with HEARTBEAT.md

Focus Tree provides dedicated heartbeat integration:

Heartbeat triggers:

• Check current FOCUS.md status
• Detect blockers → edit 📖 Context section, add 🚧 [blocker description]
• Update Status line if needed

HEARTBEAT.md format:

# HEARTBEAT.md

Focus Tree Trigger-based Updates

## Trigger Conditions
1. **User request** — User explicitly says "start new task"
2. **Heartbeat check** — Check FOCUS.md status, update Blockers

## Execution Flow
1. Read FOCUS.md
2. Detect task status (if blocked, edit FOCUS.md to add Blockers)
3. Write/Edit FOCUS.md as needed

## No Auto-extraction
- Do not auto-extract tasks from conversation
- Only update on explicit trigger conditions