# Multi Phase Session

> Manage multi-phase projects using separate sessions per phase instead of compact, with durable handoff files. Use when work spans multiple sessions, phases, handoffs, or when context degradation becomes a concern.

- **Type:** Skill
- **Install:** `agentstack add skill-avizmarlon-agent-skills-multi-phase-session`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [avizmarlon](https://agentstack.voostack.com/s/avizmarlon)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [avizmarlon](https://github.com/avizmarlon)
- **Source:** https://github.com/avizmarlon/agent-skills/tree/main/skills/multi-phase-session

## Install

```sh
agentstack add skill-avizmarlon-agent-skills-multi-phase-session
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Multi-Phase Session Management

Large software projects, long-term initiatives, or phased work—where each phase is a distinct milestone with clear acceptance criteria—benefit from a session-per-phase model instead of trying to compact context within a single conversation.

## Why separate sessions per phase

AI context quality degrades measurably around 60% of capacity (before auto-compact), and subsequent compacts introduce truncation and lossy summarization. A project split across multiple compact cycles accumulates error.

**Better pattern:** 
- One AI session per phase
- Each phase terminates with a commit, updated handoff, and session closure
- Next phase opens fresh with the handoff file and project docs as context source
- The codebase, specification documents, and handoff file are the canonical context—not the previous chat history

This preserves quality because:
- The next agent (or next session with the same agent) reads living docs, not truncated chat summaries
- Decisions, blocked items, and state are recorded in files meant for future readers, not buried in chat
- Each phase is independently validated before moving forward
- Context isn't split across a "what I remember from chat" and "what the files say"

## Session lifecycle per phase

### Phase completion checklist

Before closing a session:
1. **Code is committed** — all work merged to the appropriate branch or merged to main (per project CI rules)
2. **Acceptance criteria are met** — the phase has a defined "done" state; validate it
3. **Handoff is written/updated** — if the project uses `session-handoff.md` or equivalent, it reflects current state
4. **Next phase is clear** — the handoff names the next objective, expected duration, and any blockers
5. **CHANGELOG or progress log is updated** — significant milestones are recorded for future reference

### Opening a new session for the next phase

1. **Read the handoff first** — open `session-handoff.md` or equivalent in full before proceeding
2. **Check git state** — `git status`, `git branch`, `git log --oneline -5` to understand current state
3. **Verify acceptance criteria from prior phase** — confirm the last phase actually completed and is clean
4. **Read critical docs** — specification, architecture decisions (ADRs), any phase-specific README
5. **Begin with verification** — first steps validate the prior phase is stable before building the next one

### Compact within a phase vs. across phases

- **Compact within a phase** (`/compact`) — acceptable if the work is continuous and there's no natural break. Preserve: current objective, open blockers, active trade-offs, current validation state, and concrete next steps. Drop: resolved discussions, abandoned approaches, large tool outputs.
- **Compact across phases** — anti-pattern. Don't force compact when a phase ends. Open a new session instead; the overhead of reading files is smaller than the risk of losing phase context to lossy summarization.

## Handoff file format and live-doc discipline

A durable handoff file is the primary context for the next agent/session. It must be understandable in isolation.

### Minimum required sections

- **Phase just completed** — name, what was built, what was validated, any trade-offs made
- **Current git state** — branch name, upstream (main/prod/staging), if dirty or clean, current commit hash of relevance
- **Blockers or open decisions** — anything that stopped progress or is waiting for a human choice
- **Architecture / known constraints** — what the next phase must know to avoid breakage
- **Next phase** — expected work, entry point (file/command to start with), and acceptance criteria
- **Gotchas or pitfalls discovered** — anti-patterns found, tools that didn't work, environmental surprises

### Stale-doc defense in depth

When multiple versions of a document exist (e.g., v1, v2, v3 of a design spec, or multiple branches of a financial calculation), protect against a future agent opening the wrong one:

- **Mark every superseded document** with a banner at the top: `[SUPERSEDED — use ]`
  - Apply this to all file types: `.md`, `.csv`, `.json`, data files, not just human-readable docs
  - The banner is a local defense; it doesn't depend on the handoff's index being read first
  
- **Resolve contradictions in your source-of-truth** — if the same matrix says a claim is "proven" in section 1 and "partial" in section 5, a future agent will follow the first occurrence and be misled. Fix the contradiction before closing.

- **Validate the handoff with deterministic checks** — use `grep` to confirm superseded banners are present, or ask a second agent to simulate opening just these docs: "Would a blind agent be misled?"

### Branch naming in handoff

If work lives on a feature branch (not `main`), explicitly name it in the handoff:
```
Current branch: feature/phase-2-auth-overhaul (not merged to main yet)
Next step: open new session in this branch, or merge to main first
```

## Never open Claude in a subdirectory

Always launch the AI agent from **the root of the project repository**, not from a feature directory, subdirectory, or subfolder.

**Why:** Global configuration files (`.claude/`, `.codex/`, `.gemini/`, or language-equivalent), shared rules, and context files live at the repository root. Opening in a subdirectory means:
- The agent doesn't load the root-level instructions or rules
- Multi-session coordination breaks (handoff files won't be found or will be in the wrong place)
- Environment context (project-specific setup, shared libraries, CI configuration) is inaccessible

**When the next session starts:** explicitly tell the next operator or agent the full repository path, e.g.:
```
cd /path/to/my-project-repo
```
Not:
```
cd /path/to/my-project-repo/apps/frontend  ← WRONG
```

Exception: Git worktrees (which share the parent repository's `.git` directory) maintain access to root-level configuration and can function correctly.

## Example: 3-phase refactor

**Phase 1 — Audit & Design**
- Read the current codebase, write spec of changes needed
- Commit: `docs/refactor-spec-v1.md`, `CHANGELOG` entry
- Handoff mentions: "Spec ready, no blockers, Phase 2 begins here: implement core module transformation"

**Phase 2 — Implementation**
- Open new session, read handoff and spec
- Build refactored modules, tests, integration points
- Commit: feature branch `refactor/core-modules`
- Handoff: "Core modules done, integration tests green, Phase 3 is edge-case handling and migration of dependent code"

**Phase 3 — Edge Cases & Cleanup**
- Open new session, check Phase 2 is merged/stable
- Handle remaining dependent code, performance edge cases, documentation
- Commit: merge to `main`
- Handoff: "Refactor complete, all tests passing, code review done. Next work is feature X or maintenance"

Each session is fresh, each phase is independently validated, and context doesn't degrade because the agent reads files, not chat summaries.

## When NOT to use multi-phase

- **Trivial changes** — a typo fix, a single-file edit, or a command-line one-liner does not need a handoff.
- **Exploratory work** — if the outcome is uncertain and there's no phase boundary, a single session is fine. Use compact if needed.
- **Pair-programming** — if the agent and operator are both present and active in the same session, compact is acceptable.

Use multi-phase when work is **clearly phased**, **spans multiple days or sessions**, or when you notice **quality dropping** as context fills.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [avizmarlon](https://github.com/avizmarlon)
- **Source:** [avizmarlon/agent-skills](https://github.com/avizmarlon/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-avizmarlon-agent-skills-multi-phase-session
- Seller: https://agentstack.voostack.com/s/avizmarlon
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.