Phasekeeper

Phasekeeper is a Codex plugin for long-running software projects. It gives Codex a board-first workflow so each session starts from explicit project state instead of chat memory.

Use it when a project needs:

• a clear active phase and next step
• approved specs before implementation
• issue tracking that survives session handoff
• verification logs tied to the work that changed
• predictable closeout with commits, progress notes, and next-session context

The core rule is simple: every implementation session starts from the active phase board.

Quick Start

Install the marketplace from GitHub:

codex plugin marketplace add coderdeep11/phasekeeper

For local development, clone the repository and add the checkout as a local marketplace:

git clone https://github.com/coderdeep11/phasekeeper.git
cd phasekeeper
codex plugin marketplace add "$(pwd)"

Then install or enable phasekeeper from Codex's plugin UI.

If the UI is unavailable, enable it in Codex config:

[plugins."phasekeeper@phasekeeper-marketplace"]
enabled = true

Set up a target repository:

Use Phasekeeper to set up this repo.

Future sessions should start with:

Start this session with Phasekeeper.

And end with:

Close this session with Phasekeeper.

What It Installs

Phasekeeper scaffolds workflow files into the target repository.

File	Purpose
AGENTS.md	Agent operating rules for session start, scoped work, and closeout.
WORKFLOW.md	Human-readable process manual for specs, boards, implementation, issues, and handoff.
PROGRESS.md	Concise historical archive of accepted phases and session handoffs.
docs/boards/README.md	Active phase pointer and phase index.
docs/boards/phase-board.template.md	Template for active phase boards.
docs/specs/phase-spec.template.md	Template for phase specs that must be explicitly approved before implementation.

The initializer creates missing files and refuses to overwrite existing files unless --force is provided.

Direct script fallback:

python3 /path/to/phasekeeper/plugins/phasekeeper/scripts/init_phasekeeper.py /path/to/target-repo

Overwrite existing workflow files intentionally:

python3 /path/to/phasekeeper/plugins/phasekeeper/scripts/init_phasekeeper.py /path/to/target-repo --force

Daily Workflow

At session start, Codex reads:

1. AGENTS.md
2. docs/boards/README.md
3. the active board, if one exists
4. the active spec, if one exists
5. WORKFLOW.md
6. open issues on the active board

Then it reports:

Phase NN, Step K of N. Open issues: N. Next up: <description>. Ready?

No implementation starts until the operator confirms.

During work, Codex follows one board step at a time, updates references and tests, logs issues when found, and keeps changes scoped to the active phase.

At session close, Codex updates:

• active board status
• references for changed files
• verification commands and results
• work log
• PROGRESS.md
• git status and recent commit context

Completed board steps should have a matching commit unless the operator explicitly asks for an uncommitted handoff.

Workflow Guarantees

Phasekeeper is intentionally conservative:

• Specs start as DRAFT and are not approved until the operator explicitly approves them.
• Boards are created from approved specs, not inferred from chat.
• OPEN issues live on the active board so future sessions can find them.
• Test and verification results are recorded with exact commands.
• Unrelated refactors and cleanup stay out of phase steps.
• Existing local changes are preserved unless the operator asks otherwise.

Repository Layout

This repository is a Codex marketplace root:

.agents/plugins/marketplace.json
plugins/phasekeeper/

The plugin package lives in plugins/phasekeeper/:

plugins/phasekeeper/
├── .codex-plugin/plugin.json
├── assets/templates/
├── scripts/init_phasekeeper.py
└── skills/phasekeeper/

Update Or Remove

For a local path marketplace, edits in the checkout are already the source. Start a new Codex session after changing plugin metadata or skills.

For a Git-backed marketplace, refresh Codex's local copy:

codex plugin marketplace upgrade phasekeeper-marketplace

Remove the marketplace:

codex plugin marketplace remove phasekeeper-marketplace

Development

Run tests:

python3 -m pytest -q

Validate package metadata:

python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
python3 -m json.tool plugins/phasekeeper/.codex-plugin/plugin.json >/dev/null

Validate the skill:

python3 /path/to/skill-creator/scripts/quick_validate.py plugins/phasekeeper/skills/phasekeeper

Smoke-test the initializer:

python3 plugins/phasekeeper/scripts/init_phasekeeper.py /tmp/phasekeeper-demo-repo
python3 plugins/phasekeeper/scripts/init_phasekeeper.py /tmp/phasekeeper-demo-repo
python3 plugins/phasekeeper/scripts/init_phasekeeper.py /tmp/phasekeeper-demo-repo --force

Publishing Checklist

Before promoting a release:

• Keep machine-local filesystem paths out of committed docs.
• Run tests, JSON validation, and skill validation.
• Confirm install examples point at the published GitHub repository.
• Verify a throwaway repo can be initialized through Codex and through the direct script fallback.

License

MIT