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. 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. 2. Focus — Keep the agent anchored to the current task. Prevents drifting between topics or losing track after session compactions.

1. 3. 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:

Trigger	Action	Example
userrequest	User says "start new project"	Write new FOCUS.md with Focus Point and TODOs
taskcomplete

User says "task done" | Edit TODO line: ☐ → ✅ |
| priority_shift | User changes priorities | Edit Focus Point line |
| new_project | Starting new focused project | Write new FOCUS.md, archive old if exists |
| heartbeat | Heartbeat check reveals blockers | Edit Status line, add Blockers section |

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

File	Purpose	When to Update
FOCUS.md	Current work state — What we're doing NOW	Every task change, status change, or context shift
FOCUS-LOG.md

Completed work history — Archive of finished focuses | Only when archiving a completed/blocked focus |
| MEMORY.md | Long-term curated memory — Important insights, lessons, preferences | Periodically distill from daily notes |

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:

CODEBLOCK0

Tree View

Hierarchical structure showing nesting levels:

CODEBLOCK1

Field Reference

Field	Prefix	Required	Description
Focus Point	INLINECODE4	✅ Yes	Root task name
TODOs

☐/⏳/✅ | ✅ Yes | Task checklist | | Context | 📖 | ✅ Yes | Active state + blockers | | Decisions | 📌 | ❌ No | Key decisions made | | Constraints | ⚠️ | ❌ No | Limitations/requirements | | Sub-Agents | 🤖 | ❌ No | Spawned agents status | | Started | - | ❌ No | Start date | | Status | - | ❌ No | active/paused/blocked |

Usage

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

Option 1: CLI Script (recommended)

CODEBLOCK2

Option 2: Direct File Operations

CODEBLOCK3

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:

Section	Prefix	Example	Placement
Decisions	INLINECODE12	INLINECODE13	Optional section after TODOs
TODOs

☐/⏳/✅ | ☐ Implement feature | Required section |
| Constraints | ⚠️ | ⚠️ Must use TypeScript | Optional section after TODOs |
| Blockers | 🚧 | 🚧 Waiting for API key | Inside 📖 Context section |
| Context | 📖 | 📖 Current status... | Required section (last) |
| Sub-Agents | 🤖 | 🤖 label — task — status | Optional section before Context |

Display Format

• - TODOs Level 1: Icon prefix

- ✅ = completed - ⏳ = in progress - ☐ = pending

• - TODOs Level 2: Plain list, no icon prefix
• Decisions: prefix INLINECODE27
• Constraints: prefix INLINECODE28
• Context: prefix INLINECODE29

FOCUS-LOG.md Format

Append-only log of completed focuses:

CODEBLOCK4

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 INLINECODE33
• Update Status line if needed

HEARTBEAT.md format:
CODEBLOCK5