Maintain Project Continuity

Evidence-backed project context for fresh AI coding conversations.

Maintain Project Continuity: verified state flows from repository documents through a checkpoint to fresh AI coding sessions

Test License: MIT Agent Skill

简体中文

Long chats are a poor project database. This Agent Skill keeps the current objective, verified progress, environment facts, and optional external knowledge sources in small repository files so Codex, Claude Code, or another agent can continue without re-reading a giant transcript.

Why this is different

  • Evidence before completion — a completed item needs a commit, passing test, artifact, reproducible check, or explicit manual acceptance.
  • Snapshot, not diary — PROJECT_STATUS.md is rewritten in full; stale claims do not accumulate at the bottom.
  • Tool-neutral — AGENTS.md and CLAUDE.md route different agents to the same canonical workflow.
  • Knowledge-aware — the agent asks for an Obsidian Vault, notes directory, or other knowledge source when its location is unknown.
  • Context-bounded — it reads only relevant notes and small Git/log snapshots, never an entire Vault by default.
  • Environment-aware — durable machine and validation facts live separately from transient task status.

What it installs into a project

AGENTS.md
CLAUDE.md
docs/
├── AI_WORKFLOW.md
├── PROJECT_STATUS.md
├── ENVIRONMENT.md
└── KNOWLEDGE_SOURCES.md
scripts/
└── project_context.py

Existing files are preserved. The initializer creates only missing files.

Install the Skill

Codex

git clone https://github.com/chuyanchu/maintain-project-continuity.git
mkdir -p ~/.codex/skills
cp -R maintain-project-continuity/skills/maintain-project-continuity ~/.codex/skills/

Claude Code

git clone https://github.com/chuyanchu/maintain-project-continuity.git
mkdir -p ~/.claude/skills
cp -R maintain-project-continuity/skills/maintain-project-continuity ~/.claude/skills/

Restart or reload the agent after installation.

Use it

Ask naturally:

Initialize durable project context for this repository.

Resume this project from verified repository state.

Prepare an evidence-backed handoff before I start a new conversation.

Or invoke it explicitly where supported:

Use $maintain-project-continuity to audit and hand off this project.

The agent will ask where your Obsidian Vault or other long-term knowledge source lives. Reply none if the project does not have one.

The everyday loop

Start a focused milestone
        ↓
Resume from verified files + relevant notes
        ↓
Implement and test without treating chat as storage
        ↓
Rewrite the current status snapshot and validate it
        ↓
Open a fresh conversation for the next milestone

Operations

Operation Purpose
init Add missing workflow files without overwriting existing instructions
start Show a bounded Git/context snapshot and validate the stored state
validate Check required sections, completion evidence fields, branch consistency, placeholders, and common secret patterns
audit Run validation plus context-size and entrypoint checks

After initialization, the project receives a portable copy of the validator:

python3 scripts/project_context.py validate .

Windows users can run the same script with py -3.

Design principles

  1. Code, Git, tests, artifacts, and explicit manual acceptance outrank prose.
  2. Changed code remains in progress until it is verified.
  3. Current status is a replace-in-place snapshot, not a growing session log.
  4. Full logs stay outside the status file.
  5. External knowledge is loaded progressively, never wholesale.
  6. Memory and compaction help a session last longer but do not replace a verified handoff.

The validator deliberately cannot prove that prose evidence is true. A cited test, commit, artifact, or acceptance result still has to be inspected or executed by the agent.

Compatibility

  • Codex Agent Skills
  • Claude Code Agent Skills
  • Other assistants that can read a SKILL.md workflow
  • Git and non-Git projects
  • macOS, Linux, and Windows with Python 3

Contributing

Real-world feedback is especially useful. Open an issue with the agent, operating system, trigger phrase, expected behavior, actual behavior, and a sanitized excerpt of the generated status file. Never include credentials or private project material.

Pull requests should keep the Skill concise, preserve existing user files, and include or update tests when validator behavior changes.

License

MIT