Hybrid 3-File Architecture (v1.5.3)

The Hybrid 3-File Model solves the “Token Waste vs. Amnesia” problem for AI agents managing tasks. Instead of forcing the agent to read a massive backlog file every session, work is distributed across three specialized files.

🌉 A Bridge Between Two Thinking Worlds

This model acts as a bridge between:

• Short-term Thinking (AI Agent): Requires extreme focus and minimal input data to avoid noise and token waste.
• Long-term Thinking (Human): Requires full history, macro planning, and completion evidence for project governance.

📦 The Three Core Components

The system operates around 3 files located in the artifacts/tasks/ directory:

artifacts/tasks/
├── backlog.md          # 📌 Operational Authority — single source of truth
├── sprint-current.md   # 🔥 Hot Lane — agent-writable buffer for ad-hoc quick tasks
└── done.md             # ✅ Historical Archive — plan-grouped, append-only log

1. backlog.md (Operational Authority)

• Role: The single source of truth storing the entire task lifecycle (Bugs, Features, ICE Scores).
• Problem Solved: Keeps the Macro View intact for humans without forcing the AI to re-read thousands of lines of old plans constantly.
• Rule: Updated exclusively via the /backlog command.

2. sprint-current.md (🔥 Hot Lane)

• Role: An agent-writable buffer for ad-hoc quick tasks that arise during a coding session.
• Problem Solved: Eliminates ceremony — the agent writes quick tasks directly here instead of going through /backlog update for every small item.
• Rule: Agent writes directly during sessions. Flushed to done.md by /end.

[!NOTE] In v1.5.3, sprint-current.md is no longer a system-generated mirror of the backlog. It is the Hot Lane — a lightweight buffer where the agent captures quick tasks as they arise during work, with zero overhead.

3. done.md (Historical Archive)

• Role: An append-only archive of every completed task, grouped by plan with origin tags (#backlog or #session).
• Problem Solved: Battles “AI Amnesia” during long chat sessions. Provides quantitative evidence for /retro to calculate Project Velocity.

🗜️ Backlog Compression (/backlog clean)

Done items are compressed, not deleted. The clean action moves Done items from active tables into the ✅ Completed (Archived) section (1 line per plan + IDs list).

Lookup chain:

backlog.md (✅ Completed: plan name + IDs)
    ↓ link
done.md (per-task detail, grouped by plan heading)
    ↓ link
plans/done/*.md (full plan: phases, architecture, DoD)

This preserves backlog.md as the single source of truth for all tasks while keeping it token-efficient.

🔄 Operation Flow

Two Parallel Streams

• Strategic stream: /plan → /backlog sync → work → /end → done.md (origin: #backlog)
• Quick task stream: session request → Hot Lane → /end → done.md (origin: #session) or promote → backlog.md

Key Workflow Integration

[!IMPORTANT] Critical Requirement: The 3-file mechanism only becomes operational after you execute the /backlog sync command following your planning phase (/plan). Without this synchronization, tasks exist only as “blueprints” in plan.md and will never receive the IDs required to trigger the Agent’s high-speed operational flow.

📊 Token Budget

One of the key design goals is keeping the /open context ultra-light:

Compare this to the traditional approach where a single backlog read could consume ~3,000+ tokens.

📜 Version History

The architecture has evolved significantly across recent versions:

📚 References

• Rule: Hybrid 3-File Integrity — C1 (Hot Lane), C2 (plan-grouped done.md), C3 (compress-not-delete), C5 (/end sync)
• Workflow: /backlog, /end, /plan, /retro
• Learn: Defense-in-Depth — File Guard Headers (Layer 4)

→ Explore Workflow /open with Hybrid 3-File → Explore Workflow /backlog → Explore Workflow /end — The Sole Sync Point