vt-c-phase-checkpoint

Manages .claude-checkpoint.md files for workflow phase handoffs. Enables clean conversation clearing between phases while preserving continuity. Each phase writes a checkpoint on completion; the next phase reads it to resume seamlessly. - Read - Write - Edit - Bash - Grep - Glob

Plugin: core-standards
Category: Other
Command: /vt-c-phase-checkpoint

---

Phase Checkpoint Protocol

Purpose: Enable conversation clearing between workflow phases without losing continuity. Each completed phase writes a checkpoint file; the next phase reads it to resume context.

Why Clear Between Phases

Long conversations accumulate context that: 1. Saturates the context window — build-phase debugging fills memory, causing compaction that loses planning context 2. Creates stale context — old reasoning biases later phases (e.g., review shouldn't carry the author's justifications) 3. Contaminates independent phases — a reviewer in the same conversation reviews its own work with its own rationale still in memory

Clearing the conversation between phases gives each phase a fresh, unbiased context window while the checkpoint file provides the minimal necessary continuity.

---

Checkpoint File: .claude-checkpoint.md

Location: project root (next to CLAUDE.md)

Format

---
completed_phase: [phase-number]-[phase-name]
completed_at: [ISO 8601 timestamp]
next_phase: [phase-number]-[phase-name]
next_command: /[phase-number]-[phase-name]
branch: [current git branch]
active_spec: [SPEC-NNN or null]  # derived from branch name or .active-spec file
review_status: [PASS | FAIL | NOT_RUN]  # post-build/post-execute checkpoints only
plan_status: [LOADED | BYPASSED | NOT_APPLICABLE]  # post-build/post-execute checkpoints only
step_progress: "[N/M completed, Step K in_progress]"  # only if steps exist in specs/[N]-feature/state.yaml
clear_recommended: [true/false]
clear_reason: [why clearing is recommended, or "low context — continuing is fine"]
---

# Phase Checkpoint

## Completed: Phase [N] ([Name])
[1-3 sentence summary of what was accomplished]

## Key Outcomes
- [Bullet list of concrete deliverables or decisions]

## Step Progress
[Only if `steps:` exists in `specs/[N]-feature/state.yaml` for the active SPEC]
Steps completed: 1-3. Step 4 in progress. Remaining: Steps 5-6.
Resume from: Step 4 — [description]

## Context for Next Phase
[Anything the next phase specifically needs to know.
Not a rehash of everything — just the delta that helps the next phase start efficiently.]

## Open Items
- [ ] [Item deferred or unresolved, with reason]

## Next Step
Run `[/next-command]` to start [next phase name].
[1-2 sentences explaining what the next phase will do.]

review_status (post-build/post-execute checkpoints only)

When completed_phase is 3-build or kw-2-execute:

1. Check if .review-gate.md exists in the project root
2. If it exists, read branch and status from its frontmatter
3. Determine value:
4. PASS: .review-gate.md exists, branch matches current git branch, status is PASS
5. FAIL: .review-gate.md exists, branch matches, status is FAIL
6. NOT_RUN: .review-gate.md is missing, or branch does not match current git branch

For all other completed_phase values, omit the review_status field.

When review_status is NOT_RUN, add the following warning to the checkpoint body (in the "Context for Next Phase" section):

> ⚠ Review has not been run for this branch.
> Run /vt-c-4-review (or /vt-c-kw-3-review) before creating a PR.
> Security review is mandatory per Constitution Principle I.

plan_status (post-build/post-execute checkpoints only)

When completed_phase is 3-build or kw-2-execute:

1. Derive active spec from branch (.active-spec file or feature/spec-NNN-* branch name), then look up specs_dir from .design-state.yaml
2. Check if specs/[N]-feature/plan.md or specs/[N]-feature/tasks.md exists
3. Determine value:
4. LOADED: plan.md or tasks.md exists in the active spec's directory
5. BYPASSED: Plan artifacts missing but build/execute proceeded (developer acknowledged the plan-required warning)
6. NOT_APPLICABLE: No active spec, no SpecKit setup, or no specs_dir configured

For all other completed_phase values, omit the plan_status field.

When plan_status is BYPASSED, add the following warning to the checkpoint body (in the "Context for Next Phase" section):

> ⚠ Build proceeded without a plan from /vt-c-2-plan.
> Consider running /vt-c-2-plan retroactively and documenting architecture decisions.
> Plan before build is required per Constitution Principle II.

Beads Ready Work (if .beads/ exists)

When .beads/issues.jsonl exists, include a "Ready Work" section in the checkpoint:

## Ready Work (Beads)
[Output of `bd ready --json | bd list --format summary` — unblocked issues for the next session]

This enables the next phase to immediately see actionable work items without running bd prime separately. Keep this section concise (top 5 ready items max).

If .beads/ does not exist, omit this section.

Rules

1. Concise — The file must be small enough to be fully consumed in one Read. Target: under 60 lines.
2. Forward-looking — Focus on what the next phase needs, not a full history of what happened.
3. No duplication — Don't repeat what's already in journal entries, specs, or ADRs. Reference them instead.
4. Overwritten each time — Each phase overwrites the checkpoint. There is only one active checkpoint.
5. Git-ignored — Add .claude-checkpoint.md to .gitignore. This is ephemeral workflow state, not project documentation.

---

Clear Recommendation Heuristic

Each phase sets clear_recommended based on:

Transition	Clear?	Reason
0-start → 1-bootstrap	false	Small context, bootstrap benefits from start context
1-bootstrap → 2-plan	false	Bootstrap is brief, plan benefits from bootstrap context
2-plan → 3-build	true	Planning explores alternatives and research — build should start fresh with just the plan
3-build → 4-review	true	Critical. Review must be independent of build conversation to avoid self-confirmation bias
4-review (pass) → 5-finalize	true	Deploy checks are independent; review findings are captured in the report
4-review (fail) → fix → 4-review	false	Fixes need the review findings in context
5-finalize → 6-operate	false	Operate is reactive — no accumulated context to clear
Long build session	true	Context window filling up from implementation details

Long Session Detection

If a build phase has been running for many turns (heuristic: user has sent >30 messages in current conversation), the checkpoint should set:

clear_recommended: true
clear_reason: "Long build session — context window is filling up. Clear and resume with /vt-c-3-build to continue with fresh context."

In this case next_command stays /vt-c-3-build (resume, not advance).

---

Protocol: Writing a Checkpoint (Phase Exit)

Every workflow skill's final step should include:

1. Consolidate pending journal entries

If docs/vt-c-journal/ has entries from this session, run the consolidation logic (or remind user to run /vt-c-consolidate).

2. Write .claude-checkpoint.md

# Gather context
BRANCH=$(git branch --show-current 2>/dev/null || echo "not a git repo")
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Derive active spec from branch name
BRANCH=$(git branch --show-current 2>/dev/null || echo "")
if [ -f ".active-spec" ]; then
  ACTIVE_SPEC=$(cat .active-spec)
elif echo "$BRANCH" | grep -qE '^feature/spec-[0-9]+-'; then
  ACTIVE_SPEC="SPEC-$(echo "$BRANCH" | sed 's/feature\/spec-\([0-9]*\)-.*/\1/' | sed 's/^0*//' | awk '{printf "%03d", $1}')"
else
  ACTIVE_SPEC="null"
fi

# Gather step progress if available
# Read the steps: block for the active SPEC from specs/[N]-feature/state.yaml
# Summarize as "N/M completed, Step K in_progress" (or omit if no steps exist)

Write the file using the format above, filling in: - completed_phase: this skill's phase - next_phase: the next sequential phase - next_command: the slash command for the next phase - branch: from git - active_spec: derived from branch name or .active-spec file (null if not on a spec branch) - clear_recommended and clear_reason: per the heuristic table above - Summary, outcomes, context, open items from session knowledge

3. Display the clear recommendation

When clear_recommended: true:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase [N] complete. Checkpoint saved.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommended: Clear the conversation to give the next phase
a fresh context window.

  /clear

Then start the next phase:

  [/next-command]

Why: [clear_reason]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When clear_recommended: false:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase [N] complete. Checkpoint saved.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Next step: [/next-command]

(Context is small enough to continue in this conversation,
 or you can /clear and resume — checkpoint is saved either way.)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Protocol: Reading a Checkpoint (Phase Entry)

Every workflow skill's first step (before any other work) should include:

1. Check for .claude-checkpoint.md

if [ -f ".claude-checkpoint.md" ]; then
  # Checkpoint exists — read and display resume context
fi

2. If checkpoint exists

Read the file and:

a) Validate phase sequence: - Extract next_phase from frontmatter - Compare with this skill's phase - If they match: display "Resuming from checkpoint" (normal flow) - If they don't match: check if this is a mandatory gate transition

Mandatory gate transitions (hard-block):

If next_phase is 4-review and the user is running /vt-c-5-finalize or /vt-c-6-operate:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BLOCKED: Code review required before deployment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The checkpoint indicates /vt-c-4-review has not been completed.
Code review is mandatory before deployment.

Run /vt-c-4-review first.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STOP. Do not proceed.

If next_phase is 5-finalize and the user is running /vt-c-5-finalize, but .review-gate.md has status: FAIL:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BLOCKED: Review gate did not pass
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The last /vt-c-4-review resulted in FAIL status.
Fix the issues and re-run /vt-c-4-review.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STOP. Do not proceed.

Advisory transitions (warn but allow override):

For all other out-of-sequence transitions:

⚠ Checkpoint suggests /[expected-phase], but you're running /[this-phase].

Options:
1. Continue with /[this-phase] anyway
2. Run /[expected-phase] instead

b) Display resume context:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Resuming from checkpoint
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━���━━━━━━━━━━━━━━━━━━━━━━━
Last phase: [completed_phase] ([completed_at])
Branch: [branch]
Active Spec: [active_spec or "none"] (from branch)

[Context for Next Phase section from checkpoint]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

c) Load referenced context: - If active_spec is set: Read the active spec's specs/[N]-feature/spec.md (look up specs_dir in .design-state.yaml) - Read recent journal entries from docs/vt-c-journal/ - Check git branch matches checkpoint's branch

3. If no checkpoint exists

Proceed normally — this is a fresh start or the user skipped the checkpoint mechanism.

---

Integration with .gitignore

The bootstrap skill (and repo-init) should add:

# Workflow state (ephemeral, not project documentation)
.claude-checkpoint.md
.review-gate.md
.test-gate.md

---

Integration with /vt-c-0-start

When /vt-c-0-start runs, it should check for a checkpoint and display the recommendation:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Checkpoint detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Last completed: Phase [N] ([name]) at [timestamp]
Suggested next: /[next-command]

Would you like to continue with /[next-command]?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Integration with /vt-c-activate

When /vt-c-complete marks a specs as done: 1. It already updates .design-state.yaml 2. Additionally: write a checkpoint with next_command: /vt-c-activate (to pick up the next specs) 3. Set clear_recommended: true with reason "specs completed — fresh context for next feature"

---

Example Checkpoint: After /vt-c-3-build

---
completed_phase: 3-build
completed_at: 2026-02-13T14:30:00Z
next_phase: 4-review
next_command: /vt-c-4-review
branch: feature/data-import
active_spec: SPEC-003
review_status: NOT_RUN
plan_status: LOADED
step_progress: "5/6 completed, Step 6 in_progress"
clear_recommended: true
clear_reason: "Review should run with fresh context to avoid self-confirmation bias from the build conversation."
---

# Phase Checkpoint

## Completed: Phase 3 (Build)
Implemented Data Import feature (SPEC-003) with CSV/Excel parsing,
chunked upload for large files, and server-side validation.

## Key Outcomes
- CSV parsing via papaparse with streaming for large files
- Chunked upload (10MB threshold) with progress tracking
- Server-side validation with preview mode for client
- 47 tests passing (unit + integration)

## Step Progress
Steps completed: 1-5. Step 6 in progress. Remaining: Step 6.
Resume from: Step 6 — Integration Tests

## Context for Next Phase
Review should focus on:
- File upload security (size limits, type validation, path traversal)
- Memory usage during large file parsing
- Error handling for malformed CSV/Excel data
- See journal entry 2026-02/entries/2026-02-13-1400-decision.md for parsing approach rationale

## Open Items
- [ ] UTF-16 encoded files deferred to SPEC-007 (edge case, <1% of uploads)

## Next Step
Run `/vt-c-4-review` to start code review.
The review will run 6 parallel reviewers against specs/3-data-import/spec.md (SPEC-003).

---

Example Checkpoint: Mid-Build Resume

---
completed_phase: 3-build-partial
completed_at: 2026-02-13T16:00:00Z
next_phase: 3-build
next_command: /vt-c-3-build
branch: feature/data-import
active_spec: SPEC-003
step_progress: "3/6 completed, Step 4 in_progress"
clear_recommended: true
clear_reason: "Long build session — context window filling up. Resume with fresh context."
---

# Phase Checkpoint

## Completed: Phase 3 (Build) — Partial
Implemented CSV parsing and upload API. Still need: Excel support,
validation UI, and integration tests.

## Key Outcomes
- src/api/import.ts — upload endpoint with chunked support
- src/utils/csv-parser.ts — streaming CSV parser
- 23 tests passing

## Step Progress
Steps completed: 1-3. Step 4 in progress. Remaining: Steps 4-6.
Resume from: Step 4 — Excel Support

## Context for Next Phase
Continuing build. Remaining work:
1. Add Excel parsing (xlsx library already in package.json)
2. Build validation preview UI component
3. Write integration tests for upload → parse → validate flow
See plan in docs/solutions/data-import-plan.md

## Open Items
- [ ] Excel parsing (in progress)
- [ ] Validation UI component
- [ ] Integration tests

## Next Step
Run `/vt-c-3-build` to continue implementation.
Pick up from Excel parsing — CSV side is complete and tested.