incorrect view of what comes next in the task list when starting a new session

[lqueryvg]

Problem

• when i start a new claude session it has an incorrect view of what comes next in the task list

Cause

• openspec reads MEMORY.md instead of directly looking at tasks.md when starting a new session
• MEMORY.md is not updated with current progress when working through tasks.md so it becomes stale (and therefore useless)

Proposal

• Also update MEMORY.md when checking off tasks in tasks.md

---

Environment

openspec version 1.1.1
2.1.39 (Claude Code)

[1code-async]

Task completed.

I've posted a detailed analysis comment on issue #699. Here's a summary of the key findings:

Core insight: The MEMORY.md referenced in the issue is Claude Code's own memory file (CLAUDE.md), not an openspec artifact. OpenSpec already reads tasks.md directly during the apply phase (src/commands/workflow/instructions.ts:217-237), but between sessions Claude relies on its stale memory file instead.

The comment covers:

• How task progress tracking currently works in the codebase
• 4 related issues (Bug: Supported models fail to update OpenSpec tasks, causing incorrect 'openspec view' progress #374, tasks.md not respected #254, Feature request: automatically update project.md during archive #331, How to return to the Review phase after Implement Tasks? #355) that share the same "artifacts drifting out of sync" theme
• 4 potential implementation approaches ranging from post-apply hooks to workflow workarounds
• A scope consideration about whether openspec should manage the host AI tool's memory file

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Understanding the Problem

The MEMORY.md file referenced here is not an openspec artifact — it's a Claude Code feature (CLAUDE.md), which Claude reads at the start of each session to understand project context. When you progress through tasks in tasks.md, Claude Code's memory file is not updated to reflect the new task state, so the next session starts with a stale view of progress.

How Task Progress Works Today

OpenSpec's apply phase already reads tasks.md directly to determine progress:

• src/commands/workflow/instructions.ts:217-237 — parseTasksFile() parses checkbox items (- [ ] / - [x]) from tasks.md
• src/commands/workflow/instructions.ts:307-399 — generateApplyInstructions() calculates total, complete, remaining counts and determines state (blocked, ready, all_done)
• schemas/spec-driven/schema.yaml:148-153 — The apply phase config specifies tracks: tasks.md

So when you invoke the openspec apply skill (e.g., /opsx:apply), it reads tasks.md directly and gives the agent accurate progress information. The issue is that between sessions, Claude reads its own CLAUDE.md / MEMORY.md instead.

Related Issues

This falls into a broader pattern of artifacts drifting out of sync during the task lifecycle:

• Bug: Supported models fail to update OpenSpec tasks, causing incorrect 'openspec view' progress #374 — Models fail to write task state back correctly, causing incorrect openspec view progress
• tasks.md not respected #254 — tasks.md not respected; tasks marked done without performing work
• Feature request: automatically update project.md during archive #331 — project.md not updated during archive (same class of sync problem)
• How to return to the Review phase after Implement Tasks? #355 — No automatic feedback loop between implementation and specs/tasks

Potential Approaches

1. Post-apply hook that updates CLAUDE.md — After tasks are checked off during an apply session, automatically append/update a section in CLAUDE.md summarizing current task progress. This would require openspec to write to a file it doesn't currently own.

2. Skill instruction enhancement — Modify the apply skill instructions (generated in src/commands/workflow/instructions.ts:384-386) to explicitly tell the agent to update CLAUDE.md after checking off tasks. This is the simplest approach but relies on the agent following the instruction.

3. Agent-tool-specific memory hooks — Since different AI tools have different memory mechanisms (CLAUDE.md for Claude Code, .github/copilot-instructions.md for Copilot, etc.), openspec could provide a post-apply callback in the schema that updates the relevant memory file. The adapter system in src/core/command-generation/adapters/ already knows about tool-specific paths (src/core/config.ts:24).

4. Instruct users to use the apply skill at session start — The apply skill (/opsx:apply) already reads tasks.md directly and provides accurate progress. If sessions always start with the apply skill, the stale MEMORY.md problem is bypassed. This is a workflow workaround, not a code fix.

Scope Consideration

This touches on a broader question: should openspec manage the AI tool's memory/context file? Currently, openspec generates skill/command files (e.g., .claude/commands/opsx/*.md) but does not touch CLAUDE.md itself. Writing to CLAUDE.md would expand openspec's responsibility into managing the host tool's persistent memory, which has implications for multi-tool support and potential conflicts with user-maintained content in those files.

[lqueryvg]

FYI, my workaround is to add the following to ~/.claude/CLAUDE.md

When working in an OpenSpec project (i.e. an openspec/ directory exists),
update MEMORY.md with current progress every time you update tasks.md (checking off tasks).