[Feature Request] Built-in Context Persistence Support with Tracking Files

[clay-good]

Note

Moved from issue #846, originally opened by @ql-wade on 2026-03-16. Continuing the conversation here in Discussions — the original issue thread (including any comments) stays available at #846 for the record.

---

Summary

I would like to propose a built-in feature for persistent context management through file-based tracking. This pattern enables AI agents to maintain state across sessions, solving the common problem of context loss.

The Problem

When working with AI coding assistants on complex multi-session tasks:

Problem	Current Behavior
AI doesn't know current state	Re-explain every session
AI forgets previous decisions	Repeat discussions
AI doesn't know next step	Manual user guidance
Error handling chaos	Random retries
Context loss	Lost when session ends

Proposed Solution

Three Principles for AI-Driven Development

1. Attention is All You Need - Skills system controls AI attention scope, loads only necessary context
2. Context is All You Need - Persistent tracking files as agent's "working memory"
3. System Agent Flow is All You Need - Structured agent collaboration with automatic error handling

Tracking Files Pattern

openspec/changes/{change-id}/
├── task_plan.md      # Current phase, goals, task list
├── findings.md       # Technical findings, ADR (Architecture Decision Records)
├── progress.md       # Session progress log
└── delta-log.md      # Delta Specs change records

Schema Configuration

tracking:
  enabled: true
  files:
    task_plan:
      path: "task_plan.md"
      description: "Phase, goals, decisions, error log"
    findings:
      path: "findings.md"
      description: "Technical findings, ADR"
    progress:
      path: "progress.md"
      description: "Session progress log"

  events:
    onArtifactCreate:
      - update: task_plan.md
      - update: progress.md
    onDecisionMade:
      - update: findings.md (ADR)
    onError:
      - update: task_plan.md (error log)

3-Strike Protocol

Automatic error handling with progressive escalation:

Attempt	Action	Log To
1	Diagnose & fix	progress.md
2	Try alternative	findings.md
3	Rethink problem	findings.md
3 failures	Escalate to user	task_plan.md [BLOCKED]

Benefits

1. Session Continuity - Agent always knows: Where? What done? Why? Next?
2. Decision Persistence - Architecture decisions (ADR) are preserved
3. Error Recovery - Structured retry mechanism reduces manual intervention
4. Multi-Agent Support - Enables parallel development with git worktrees
5. Platform Agnostic - Works with Claude Code, OpenCode, and other AI assistants

Reference Implementation

I have implemented this pattern as a CLI tool:

• Repository: https://github.com/ql-wade/sdd-cli
• NPM Package: sdd-ql-workflow
• Quick Start: npx sdd-ql-workflow init

Related Skills

• planning-with-files - File-based planning pattern
• superpowers - Professional development skill set

Proposed Integration

This could be integrated into OpenSpec as:

1. Built-in tracking support in schema.yaml
2. Event hooks for automatic file updates
3. Template files for tracking documents
4. CLI commands for tracking file management

Would you accept a PR?

I have prepared a best practices documentation that could be added to docs/best-practices/context-persistence.md. Would the OpenSpec team be interested in accepting this as:

1. A documentation addition (best practices guide)?
2. A feature enhancement (built-in tracking support)?
3. Both?

Looking forward to your feedback!

---

Related PR (documentation): I've also prepared a fork with the best practices documentation at: https://github.com/ql-wade/OpenSpec/tree/add-trinity-workflow-best-practices