How a Spec Becomes Lasting Project Context

Spec-driven development creates context while the work happens. A spec records intent, a plan records the approach, tasks track progress, and an outcome records what actually changed. Together, they give the next session a trail from the request to the code.

Frame keeps this feature history alongside project-wide rules, the module map and decision notes. The two levels complement each other: shared files explain the project; specs explain how individual changes took shape.

A worked example: email reminders

This is an illustrative workflow for a task-management app, not a report of a shipped Frame feature. Suppose the request is: “Send a reminder before a task is due, but let people turn reminders off.”

1. Capture intent in spec.md

The spec names the problem, the expected behavior and the boundaries. It is the place to resolve ambiguity before changing code.

Feature: task email reminders
Goal: help people notice approaching deadlines.
Acceptance criteria:
- A person can enable or disable reminders.
- Completed tasks do not generate reminders.
- Retrying a job does not send the same reminder twice.
Out of scope: SMS and push notifications.

These boundaries become useful context later. A new session can see that push notifications were excluded deliberately, rather than assume someone forgot them.

2. Record the approach in plan.md

The plan connects the desired behavior to the existing code. It identifies the modules involved, the intended changes and how they will be checked. Frame’s spec workflow also records a footprint: the files the work is expected to touch.

Approach:
- Reuse the existing email delivery adapter.
- Store reminder preference with the user settings.
- Identify each delivery by task and due-date revision.
Validation:
- Check opt-out, completed tasks and retried jobs.

A future session now has a reason for using the existing email adapter. It can evaluate a proposed change against that decision instead of rediscovering it.

3. Break down the work in tasks.md

Tasks turn the plan into discrete work. In Frame, spec tasks can be imported into .frame/tasks.json and linked back to their spec. Project-wide task tracking and feature-specific intent stay connected.

• Add the preference and its control.
• Implement reminder selection and delivery.
• Verify opt-out behavior and retry handling.

The task list shows what remains. The spec and plan explain what completion means and why the tasks exist.

4. Record reality in outcome.md

Implementation can reveal something the plan missed. The outcome records what shipped, deviations from the plan, validation and follow-up work while those details are still available.

Outcome:
- Reminder preference and delivery flow implemented.
- Delivery identity includes the due-date revision because
  rescheduling a task must allow a new reminder.
- Opt-out, completed-task and retry checks passed.
Follow-up:
- Decide how reminders should behave after timezone changes.

The outcome prevents the original plan from being mistaken for a complete description of reality. The timezone question remains visible instead of disappearing with the conversation.

What the next session reads

Project instructions direct the agent to the relevant module map, tasks, notes and spec history. It can compare the reminder outcome with the current code, understand the delivery identity decision, and pick up the timezone question without reconstructing the whole conversation.

A decision that affects other features also belongs in .frame/PROJECT_NOTES.md. The module map belongs in .frame/STRUCTURE.json. The feature’s detailed history stays in its spec files under .frame/specs/.

Keep the record useful

Context remains useful when it is specific and current. Record meaningful deviations, link related decisions, and check the history against the code. A saved plan is not proof that every step shipped; a task marked complete is not a substitute for validation.

The same files serve two purposes: they guide the work now and explain it later. That is the connection between spec-driven development and context management in Frame.

Continue with project-wide context preservation or sharing that context across Claude Code and Codex CLI.