project-continuity skill

A lightweight Codex skill for preserving project state across sessions.

project-continuity is a Codex skill for keeping lightweight project state across windows, sessions, and context resets.

It maintains a small Markdown snapshot at codex-continuity/PROJECT_STATE.md so a future Codex session can answer one practical question:

Where did this project stop, and what should happen next?

This skill does not replace your project documentation. It is intentionally narrow: it records the current task, recent progress, key decisions, blockers, next steps, and relevant files.

Why this exists

Long-running AI-assisted projects often lose continuity:

• A new window does not know what the previous session completed.
• Important context gets compressed or dropped.
• Open tasks, decisions, and blockers live only in chat history.
• README.md is for stable project documentation, not fast-changing work state.
• AGENTS.md is for collaboration rules, not project progress.

project-continuity gives Codex a stable place to write and recover the current project state without turning your repository into a chat log.

When to use it

Use this skill when:

• A project needs an initial continuity file.
• You ask Codex to record progress, summarize a work phase, or update project state.
• You open a new session and ask Codex to continue the previous task.
• A task creates decisions, blockers, or next steps that future sessions must know.

Avoid using it for:

• One-off Q&A.
• Short tasks that do not need cross-session recovery.
• Permanent team rules or coding preferences.
• Secrets, tokens, API keys, private accounts, or unsanitized logs.

Installation

Copy the project-continuity/ folder from this repository into your Codex skills directory.

macOS / Linux:

~/.codex/skills/project-continuity

Windows:

C:\Users\<username>\.codex\skills\project-continuity

After installation, Codex reads project-continuity/SKILL.md and uses its frontmatter description to decide when to trigger the skill.

Default state file

The preferred state file path is:

codex-continuity/PROJECT_STATE.md

The skill also supports the legacy path:

.codex/PROJECT_STATE.md

Path rules:

• If both paths exist, codex-continuity/PROJECT_STATE.md wins.
• The legacy path is read-only compatibility.
• If only the legacy path exists, the next update should migrate state to the new path.

State file template

New state files use this structure:

# Project State

## Summary

## Current Task

## Recent Progress

## Key Decisions

## Open Issues / Blockers

## Next Steps

## Relevant Files

Section intent:

• Summary: short description of the current project state.
• Current Task: the task currently in progress.
• Recent Progress: recent progress that still matters for recovery.
• Key Decisions: decisions that future sessions should preserve.
• Open Issues / Blockers: unresolved problems or questions.
• Next Steps: concrete actions a future session can execute.
• Relevant Files: files worth reading before continuing.

Workflow

Initialize project continuity

When a project does not have codex-continuity/PROJECT_STATE.md and the environment allows file writes, Codex should:

1. Create the codex-continuity/ directory.
2. Create a minimal PROJECT_STATE.md template.
3. Record only information confirmed from the current request, current directory, and known context.
4. Avoid scanning the whole repository or guessing project background.

Initialization creates a continuity container. It should not attempt to write a full project dossier.

Record progress

When a work phase produces information that future sessions need, Codex should update PROJECT_STATE.md.

Good reasons to update:

• A clear task was completed.
• Project files changed in a way that affects future work.
• A decision was made that future sessions must follow.
• The task goal, scope, or next step changed.
• A blocker, risk, or open question was found.

Update rules:

• Read the existing state file before updating it.
• Preserve still-valid information.
• Remove or rewrite stale information.
• Record phase summaries, not full chat transcripts.
• Keep Next Steps concrete and executable.
• If the state file conflicts with real project files, trust the project files.

Resume previous work

When the user asks to continue previous work, Codex should:

1. Read codex-continuity/PROJECT_STATE.md.
2. If the new path does not exist, read .codex/PROJECT_STATE.md.
3. Summarize the recovered state.
4. Confirm the next step from Next Steps and relevant files.
5. Read only the files needed to continue.

Example prompts:

Continue the previous task.
Pick up where we left off.
Resume from the project state.
Use project-continuity to continue.

Equivalent prompts in other languages also work when your project or agent instructions use those languages.

Size control

PROJECT_STATE.md is a current-state snapshot, not a historical log. It should not grow forever.

Recommended limits:

• Do not append full conversations.
• Do not maintain a long date-by-date activity log.
• Before each update, read the existing file and remove, merge, or compress stale content.
• Keep at most 5 still-useful Recent Progress items.
• Keep at most 10 still-valid Key Decisions.
• Keep only unresolved Open Issues / Blockers.
• Keep at most 3-5 concrete Next Steps.
• Keep only currently useful Relevant Files.
• If the file exceeds roughly 120 lines, compress old content before writing new content.

Retention rule:

Still valid: keep it.
Expired: delete it.
Historically useful but too detailed: compress it into one sentence.

Example

See the sanitized example state file:

examples/PROJECT_STATE.example.md

Repository layout

project-continuity-skill/
├── README.md
├── LICENSE
├── project-continuity/
│   ├── SKILL.md
│   └── agents/
│       └── openai.yaml
└── examples/
    └── PROJECT_STATE.example.md

Notes:

• README.md is for humans.
• project-continuity/ is the installable Codex skill.
• examples/PROJECT_STATE.example.md shows a safe example state file.

Relationship to other project files

File	Purpose	Managed by this skill
AGENTS.md	Long-term collaboration rules, language preferences, coding style, debugging principles	No
README.md	Stable project overview, installation, and usage	No
codex-continuity/PROJECT_STATE.md	Current progress, decisions, blockers, and next steps	Yes
SKILL.md	Skill trigger and execution instructions	Yes
agents/openai.yaml	Codex UI metadata for this skill	Yes

License

MIT License. See LICENSE.