Session Continuity

Cross-session memory and spec-driven implementation tracking. This skill replaces self-improving-agent by combining progress tracking with pattern extraction in a single, workflow-driven system. Progress tracking is shared at .memory/pipeline/progress/; shared cross-runtime memory lives in the project-level .memory/ root.

Overview

Without this skill, agents lose all context between sessions. Work restarts from scratch, implementations drift without spec accountability, and hard-won patterns evaporate. This skill fixes that with five protocols that workflows invoke by name.

What This Skill Does

Capability	What	When
Progress tracking	Checkboxes mirroring spec depth	/plan-phase, /implement-slice
Session resumption	Read state, summarize, pick up where you left off	Any workflow start
Pattern extraction	Record what worked, what didn't, update patterns	Any workflow end
Blocker tracking	Log blockers, track resolution	During implementation
Decision analysis	Philosopher + Devil's Advocate deliberation	During design/architecture decisions
Spec pipeline tracking	Per-shard IA/BE/FE spec completion	/decompose-architecture, write-*-spec
Ambiguity gates	Micro + macro ambiguity checks	End of every spec workflow

Architecture

Workflows  = WHAT to do (ordered steps — invoke protocols by name)
This Skill = HOW to do it (protocols — detailed step-by-step)

Workflows say: "Read .claude/skills/session-continuity/protocols/NN-protocol-name.md and follow the X Protocol." This skill defines each protocol with exact steps, file formats, and rules.

---

Directory Structure

All progress state lives in .memory/pipeline/progress/:

.memory/pipeline/progress/
├── index.md                      # Master checklist — phases + overall %
├── spec-pipeline.md              # Spec completion tracker (IA/BE/FE per shard)
├── phases/
│   ├── phase-01.md               # Per-phase slice checklist
│   └── phase-02.md
├── slices/
│   ├── phase-01-slice-01.md      # Per-slice implementation log
│   └── phase-01-slice-02.md      # (only if slice has ≥3 criteria)
├── sessions/
│   ├── 2026-02-15.md             # What happened this session
│   └── 2026-02-16.md
└── memory/
    ├── patterns.md               # Reusable patterns + confidence
    ├── blockers.md               # Active + resolved blockers
    └── decisions.md              # Key decisions + rationale

Adaptive Granularity Rule

A slice gets its own file only when it has ≥3 acceptance criteria.

• Slice with 1-2 criteria → tracked inline in the phase file
• Slice with 3+ criteria → gets slices/phase-NN-slice-NN.md

This prevents file explosion for simple specs while giving granular tracking for complex ones.

---

Protocol 1: Session Resumption

Invoked by: Any workflow start, or instructions/workflow.md step 1

Purpose: Load cross-session context so the agent knows where to resume.

Steps

1. Check if .memory/pipeline/progress/index.md exists

   • If no: this is a fresh project with no tracked progress. Skip resumption.
   • If yes: continue.

2. Read index.md — get overall status, phase progress percentages.

3. Find in-progress items — scan for [/] markers (in-progress) in phase files.

   • If found: this is the resumption point.
   • If none: find the next unchecked [ ] item.

4. Read the latest session log — sessions/ directory, most recent file.

   • What was accomplished last session?
   • What was deferred and why?
   • What's the recommended starting point?

5. Read .memory/wiki/blockers.md — are there unresolved blockers?

6. Read .memory/wiki/decisions.md — load key decisions for context.

7. Summarize for the current task:

   Status: Phase 2 in progress — 3/7 slices complete (43%)
   Last session: Completed auth middleware slice, deferred rate limiting (blocked on Redis)
   Blockers: 1 active — Redis connection config needed
   Resume at: Phase 2, Slice 4 — Rate limiting middleware
   

---

Protocol 2: Progress Generation

Invoked by: /plan-phase step 7

Purpose: Create progress tracking files from a newly planned phase.

Steps

1. Read the phase plan that was just created (the output of /plan-phase).

2. Create or update index.md:

   # Implementation Progress
   
   **Project**: {{PROJECT_NAME}}
   **Last updated**: {{DATE}}
   **Overall**: 0/{{TOTAL}} slices (0%)
   
   ## Phases
   
   | Phase | Status | Progress | Link |
   |-------|--------|----------|------|
   | Phase 1: {{NAME}} | not-started | 0/{{N}} | [→](phases/phase-01.md) |
   

3. Create phases/phase-NN.md:

   # Phase {{N}}: {{NAME}}
   
   **Status**: not-started
   **Progress**: 0/{{TOTAL}} slices
   
   ## Slices
   
   - [ ] **Slice 1**: {{DESCRIPTION}} ({{S|M|L}})
     - [ ] Contract: {{CONTRACT_LIBRARY}} schema for {{entity}}
     - [ ] `BE` API endpoints for {{entity}}
       - [ ] Subtask 1
       - [ ] Subtask 2
     - [ ] `FE` {{entity}} page and components
       - [ ] Subtask 1
       - [ ] Subtask 2
     - [ ] `QA` Integration tests for {{entity}}
       - [ ] Subtask 1
     → [log](../slices/phase-01-slice-01.md)
   
   - [ ] **Slice 2**: {{DESCRIPTION}} ({{S}})
     - [ ] Criterion 1
   

   Surface tag rules for Progress Generation:

   • Tag tasks (Level 3) with BE, FE, or QA as a backtick-wrapped prefix
   • Untagged tasks are sequential (handled by orchestrator before parallel dispatch)
   • files: blocks are NOT written during generation — only during claim (Protocol 9)
   • Subtasks under tagged tasks inherit the parent's surface ownership

4. Create slices/phase-NN-slice-NN.md for each slice with ≥3 criteria:

   # Phase {{P}} / Slice {{S}}: {{NAME}}
   
   **Status**: not-started
   **Complexity**: {{S|M|L}}
   
   ## Acceptance Criteria
   - [ ] Criterion 1
   - [ ] Criterion 2
   - [ ] Criterion 3
   
   ## Implementation Notes
   <!-- Filled during /implement-slice -->
   
   ## Files Changed
   <!-- List of files created/modified -->
   

5. Initialize memory files (only if they don't already exist):

   • .memory/wiki/patterns.md — empty with header
   • .memory/wiki/blockers.md — empty with header
   • .memory/wiki/decisions.md — empty with header

---

Protocol 3: Progress Update

Invoked by: /implement-slice step 7

Purpose: Mark completed work, release claims, and propagate status changes upward.

Steps

1. Mark acceptance criteria [x] in the slice's tracking location:

   • If slice has its own file: update slices/phase-NN-slice-NN.md
   • If inline: update phases/phase-NN.md

2. Release any claimed tasks — if the completed task had [!]:

   • Change status from [/] to [x]
   • Remove the [!] flag from the task line
   • Remove the files: block under the task (lock released)

   # Before (during parallel work)
   - [/] `BE` API endpoints for user profile [!]
     - files: src/api/users/[id].ts, src/db/queries/user.ts
     - [x] GET endpoint
     - [x] PUT endpoint
   
   # After (task complete)
   - [x] `BE` API endpoints for user profile
     - [x] GET endpoint
     - [x] PUT endpoint
   

3. Mark the slice itself [x] in the phase file (only when ALL tasks are [x]):

   - [x] **Slice 3**: Auth middleware (M) ✅ 2026-02-15
   

4. Update phase progress in the phase file header:

   **Status**: in-progress
   **Progress**: 4/7 slices
   

5. Update index.md — recalculate overall progress:

   **Overall**: 12/20 slices (60%)
   

   Update the phase row's status and progress count.

6. Log implementation notes (if slice file exists):

   • What approach was taken
   • Key files changed
   • Any deviations from the plan

7. Log blockers encountered during implementation to .memory/wiki/blockers.md:

   ## Active Blockers
   
   ### BLK-003: Redis config missing (2026-02-15)
   - **Slice**: Phase 2, Slice 4 — Rate limiting
   - **Impact**: Cannot implement rate limiter without Redis connection
   - **Needs**: VPS Redis setup or config from user
   
   ## Resolved Blockers
   
   ### BLK-002: Firebase admin SDK version conflict (2026-02-14)
   - **Resolution**: Pinned to v12.0.0, added to package.json overrides
   - **Resolved**: 2026-02-14
   

---

Protocol 4: Pattern Extraction

Invoked by: End of any workflow (replaces self-improving-agent step)

Purpose: Extract reusable patterns from what just happened.

Steps

1. Reflect on the task:

   • What happened? (summary)
   • What worked well? (repeat this)
   • What didn't work? (avoid this)
   • Was there a surprise or insight?

2. Classify the pattern:

   Classification	Criteria	Action
   Best practice	Worked well, likely reusable	Add to patterns.md
   Anti-pattern	Caused problems, should avoid	Add to patterns.md as "avoid"
   Context-specific	Only applies to this situation	Log in session but don't generalize
   Not significant	Routine, nothing new learned	Skip

3. Write to .memory/wiki/patterns.md (only for best-practice or anti-pattern):

   ### PAT-007: Schema coercion for URL params (2026-02-15)
   - **Type**: best-practice
   - **Confidence**: 0.7 (applied 1 time)
   - **Context**: Astro API routes receive all params as strings
   - **Pattern**: Use `z.coerce.number()` instead of `z.number()` for URL params
   - **Source**: Phase 2, Slice 3 implementation
   

4. Update confidence on existing patterns if reapplied:

   • Increment applied count
   • Increase confidence: new_confidence = min(0.95, old + 0.1)

5. Post-decision pushback — for each decision made during this workflow (logged via Protocol 6 or made implicitly), challenge it with hindsight:

   • Did it hold up? — Did implementation confirm or undermine the reasoning?
   • Surprises? — Did anything unexpected happen because of this choice?
   • Would you choose differently now? — With what you learned during impl, same call?
   • Scope creep? — Did the decision force unplanned work or workarounds?

   If the answer to "would you choose differently" is yes, log it as a revision candidate in .memory/wiki/decisions.md with the original decision ID:

   ### DEC-004-REVIEW: Middleware decision revisited (2026-02-16)
   - **Original**: DEC-004 — middleware over per-route auth
   - **What changed**: Discovered 3 public routes need explicit exclusions, increasing complexity
   - **Verdict**: Still correct, but add route-level override capability
   - **Action**: Create follow-up slice for route exclusion config
   

   If no significant decisions were made during this workflow, skip this step.

---

Protocol 5: Session Close

Invoked by: End of session (agent should do this before signing off)

Purpose: Write a session log so the next session can resume cleanly.

Steps

1. Create sessions/YYYY-MM-DD.md:

   # Session: 2026-02-15
   
   ## Context
   - Resumed from: Phase 2, Slice 3
   - Goal for session: Implement auth middleware + rate limiting
   
   ## Accomplished
   - [x] Phase 2, Slice 3 — Auth middleware (complete)
   - [x] Phase 2, Slice 3a — Token refresh logic (complete)
   
   ## Deferred
   - [ ] Phase 2, Slice 4 — Rate limiting (blocked on Redis config)
   
   ## Patterns Learned
   - PAT-007: Schema coercion for URL params
   
   ## Next Session
   - Resolve BLK-003 (Redis config)
   - Start Phase 2, Slice 4 if unblocked
   - Otherwise skip to Phase 2, Slice 5
   

2. If a session log for today already exists, append to it (don't overwrite).

---

Protocol 6: Decision Effect Analysis

Invoked by: Any moment a non-trivial decision needs to be made

Purpose: Two-pass deliberation — the Philosopher explores, the Analyst stress-tests. Same questions, different lenses. They loop until they agree. No code is written until convergence.

Triage: Should This Protocol Be Invoked?

Does this decision have upstream or downstream effects?

• Isolated (UI element shape, variable name, test structure) → Skip. Just decide.
• Has ripple effects (touches other components, changes contracts, affects data flow, sets precedent) → Invoke.

Rule of thumb: if changing this later requires editing more than the current file, it has ripple effects.

Pass 1: The Philosopher

1. What are the project's established guidelines and protocols for this? Read the relevant rules, instructions, specs, and existing patterns.

2. What are the different ways to accomplish this within those guidelines? List at least 3 viable approaches (forcing function against first-idea bias).

3. What are the pros and cons of each? Be specific — name concrete trade-offs, not vague qualities.

4. Which one is the clear winner and why? State the recommendation with reasoning.

Pass 2: The Devil's Advocate

Take the Philosopher's recommendation and try to find flaws in it:

1. What are the project's established guidelines and protocols for this? Did the Philosopher miss any? Misinterpret any?

2. What are the different ways to accomplish this within those guidelines? Review the options the Philosopher considered. Did they overlook any?

3. What are the pros and cons of each? Did the Philosopher underweight a con or overweight a pro? Are there hidden costs they didn't surface?

4. Do I agree with the Philosopher's recommendation, or is there a better way?

   • If agree → proceed to Record step
   • If disagree → state what's better and why, then push findings back to the Philosopher for another pass

Convergence Loop

If the Devil's Advocate disagrees, the Philosopher reviews those findings and re-evaluates. The Devil's Advocate then scrutinizes again. Repeat until both agree.

They are twins with different jobs — the Philosopher explores and proposes, the Devil's Advocate stress-tests and finds flaws. Together they catch blind spots.

Record

Once converged, write to .memory/wiki/decisions.md:

### DEC-004: Use middleware over per-route auth (2026-02-15)
- **Problem**: 12+ routes need identical auth enforcement
- **Guidelines checked**: security-first rule, extensibility rule, DRY principle
- **Options considered**: Per-route checks, middleware, decorator pattern
- **Decision**: Middleware — single enforcement point
- **Philosopher reasoning**: DRY, single place to enforce and audit
- **Devil's Advocate concurrence**: Agreed — per-route is a security risk (forgotten routes)
- **Upstream**: Depends on Firebase Admin SDK token verification
- **Downstream**: All future routes auto-protected; public routes need opt-out
- **Reversibility**: Medium — mechanical but touches every route file

Proceed

The decision is justified, stress-tested, and recorded. Implement it.

---

Protocol 7: Spec Pipeline Generation

Invoked by: /decompose-architecture (after creating indexes)

Purpose: Create a spec pipeline tracker so you always know which shards have IA specs, BE specs, and FE specs completed.

Steps

1. Read the IA index — .memory/wiki/specs/ia/index.md — to get the list of shards.

2. Create .memory/pipeline/progress/spec-pipeline.md:

   # Spec Pipeline Progress
   
   **Project**: {{PROJECT_NAME}}
   **Last updated**: {{DATE}}
   **Overall**: 0/{{N×3}} specs (0%)
   
   ## Shard Spec Status
   
   | # | Shard | IA Spec | BE Spec | FE Spec |
   |---|-------|---------|---------|---------|
   | 00 | {{shard-name}} | ❌ | ❌ | ❌ |
   | 01 | {{shard-name}} | ❌ | ❌ | ❌ |
   | ... | ... | ... | ... | ... |
   
   ## Spec Completion Tracking
   
   Shards with all three specs complete (tracking only — /plan-phase requires ALL shards to be complete, not just individual ones):
   - (none yet)
   

3. Initialize memory files if they don't exist (same as Protocol 2, step 5).

---

Protocol 8: Spec Pipeline Update

Invoked by: /write-architecture-spec, /write-be-spec, /write-fe-spec (after updating the layer index)

Purpose: Mark a spec column done and report pipeline progress.

Steps

1. Identify the shard and layer — which shard just got its spec completed, and which layer (IA, BE, or FE)?

2. Update spec-pipeline.md — change the relevant ❌ to ✅:

   | 03 | user-profiles | ✅ | ✅ | ❌ |
   

3. Recalculate overall progress:

   **Overall**: 8/45 specs (18%)
   

4. Update "Spec Completion Tracking" — if a shard now has all three specs complete (IA ✅ + BE ✅ + FE ✅), add it to the completion tracking list. Note: /plan-phase requires ALL shards to be complete, not just this one.

   ## Spec Completion Tracking
   
   Shards with all three specs complete (tracking only — /plan-phase requires ALL shards to be complete, not just individual ones):
   - ✅ Shard 00: API conventions
   - ✅ Shard 01: Authentication
   

5. Report status — log what was completed and what's next.

---

Ambiguity Gates (Micro + Macro)

Invoked by: Every write-*-spec workflow, before "Request review"

Purpose: Ensure no guesses pass downstream. Two levels:

Micro Ambiguity Check

Walk each individual element in the spec and ask:

"Would an implementer need to guess about this?"

Workflow	What to check
/write-architecture-spec	Each feature, interaction, data model field, access rule, edge case
/write-be-spec	Each endpoint, request/response field, error code, schema constraint, middleware rule
/write-fe-spec	Each component, prop, interaction, state transition, responsive breakpoint, a11y rule

For every element where the answer is "yes" → fix it now. Add the missing detail, type, behavior, or constraint. Don't flag it — resolve it.

Macro Ambiguity Check

Step back and ask about the entire spec:

"Does the next downstream phase have everything it needs?"

Workflow	Downstream question
/write-architecture-spec	Would the BE spec writer need to guess anything from this IA shard?
/write-be-spec	Would the FE spec writer need to guess anything from this BE spec?
/write-fe-spec	Would an implementer running /implement-slice need to guess anything?

If the answer is "yes" → fix it now. The spec is not complete until the downstream phase can work from it without assumptions.

Relationship to /audit-ambiguity

The ambiguity gates are inline, lightweight, fix-it-now checks. The /audit-ambiguity workflow is a standalone, scored, report-generating audit you run across multiple documents at once. They complement each other:

• Gates: prevent ambiguity from entering (at write time)
• Audit: detect ambiguity that slipped through (after the fact)

---

Protocol 9: Parallel Claim

Invoked by: /implement-slice step 1.5 (parallel dispatch)

Purpose: Coordinate parallel agent ownership of tasks using claim markers and file-level locks. Prevents two agents from modifying the same files.

Concepts

Concept	Description
Surface tag	BE, FE, or QA prefix on a task, determines which agent type handles it
Claim flag [!]	Appended to a task line — means an agent owns this task and all subtasks
files: block	Listed directly under a claimed task — hard lock on those files
Frozen files	Files no parallel agent may touch — see Frozen Files list below

Frozen Files

Files no parallel agent may touch:

• package.json (or equivalent dependency manifest for the project's package manager)
• {{PACKAGE_MANAGER}} lock file (e.g., pnpm-lock.yaml, yarn.lock, package-lock.json)
• {{FRONTEND_FRAMEWORK}} config file (e.g., astro.config.mjs, next.config.js, vite.config.ts)
• {{CONTRACTS_DIR}} (e.g., src/contracts/*)
• Language config file (e.g., tsconfig.json for TypeScript, pyproject.toml for Python)
• .env

Claiming a Task

When an agent is dispatched to a surface-tagged task:

1. Change status from [ ] to [/]
2. Append [!] to the end of the task line
3. Write files: block directly under the task line, listing every file the agent will modify:

   - [/] `BE` API endpoints for user profile [!]
     - files: src/api/users/[id].ts, src/db/queries/user.ts
     - [ ] GET /api/users/:id
     - [ ] PUT /api/users/:id
   

4. Subtasks inherit the claim — the agent owns all nested items under the claimed task

Collision Check

Before dispatching agents, the orchestrator must verify no file overlap:

1. Collect files: lists from all tasks about to be claimed
2. Check intersection — if any file appears in more than one list:
   • Same tag → merge tasks (shouldn't happen if planned well)
   • Different tags → cannot parallelize. Run sequentially, assign to whichever tag owns the majority of files
3. Check frozen files — if any agent's files: list includes a frozen file, reject the claim and require a // BOUNDARY: stub approach instead
4. Empty intersection → ✅ safe to dispatch in parallel

Releasing a Task

When an agent completes all subtasks under a claimed task:

1. Change status from [/] to [x]
2. Remove [!] from the task line
3. Remove the files: block (lock released)
4. All subtasks should be [x]

See Protocol 3 (Progress Update) step 2 for the exact format.

Dependency Rules (TDD Order)

Tests are the rock. Code is malleable. If tests fail, the code changes — never the tests. Shallow or simplified tests that force passing results are the single greatest failure mode. Comprehensive tests are non-negotiable.

The dependency chain follows strict TDD: Red → Green → Verify.

Phase	Tag	What Happens	Depends On
1. Contract	(untagged)	Orchestrator writes {{CONTRACT_LIBRARY}} schemas	Nothing
2. QA-RED	QA	Write comprehensive failing tests from acceptance criteria	Contract [x]
3. BE + FE	BE, FE	Implement in parallel to make tests pass	QA-RED [x]
4. QA-GREEN	QA	Second pass — verify all tests pass, check for cheating, add integration/E2E	BE [x] + FE [x]

Iterative Correction Loop

If QA-GREEN finds failures:

1. Never weaken or simplify tests — tests encode the acceptance criteria
2. Report failures to orchestrator with specific test names and error output
3. Orchestrator re-dispatches BE and/or FE agents to fix failing code
4. QA-GREEN runs again — repeat until all tests pass
5. Only the orchestrator may terminate the loop — agents cannot declare "good enough"

Contract → QA-RED → BE+FE (parallel) → QA-GREEN
                                           ↓
                                     Tests pass? ──Yes──→ Slice complete
                                           ↓ No
                                     Re-dispatch BE/FE → QA-GREEN (repeat)

Stale Lock Recovery

If an agent crashes mid-task (leaving [!] without completing):

1. Manual cleanup: User or orchestrator resets the task from [/] to [ ], removes [!] and files: block
2. Subtask state preserved: Any subtasks already marked [x] remain — the new agent picks up from the first [ ] subtask
3. Prevention: Agents should update subtask status incrementally, not batch at the end

Level Hierarchy Reference

Level 1: Phase       [ ] [/] [x]         — no tags, no [!]
Level 2: Slice       [ ] [/] [x]         — no tags, no [!]
Level 3: Task        [ ] [/] [x] + [!]   — has BE/FE/QA tag, claimable
Level 4+: Subtask    [ ] [/] [x]         — no [!], owned by parent task's agent

---

Integration Points

Workflows reference this skill's protocols, not its internals:

Workflow	Step	Protocol
instructions/workflow.md	Step 1 (context)	Session Resumption
instructions/workflow.md	Step 5 (learn)	Pattern Extraction + Session Close
rules/completion-checklist.md	Definition of Done #5	Pattern Extraction
rules/completion-checklist.md	Definition of Done #6	Session Close
/create-prd-stack	Per-axis tech decisions	Decision Effect Analysis
/create-prd-architecture	After system architecture approval	Decision Effect Analysis
/decompose-architecture	After creating indexes	Spec Pipeline Generation
/write-architecture-spec	During data model + access control design	Decision Effect Analysis
/write-architecture-spec	After updating IA index	Spec Pipeline Update
/write-architecture-spec	Before request review	Ambiguity Gates (micro + macro)
/write-be-spec	After updating BE index	Spec Pipeline Update
/write-be-spec	Before request review	Ambiguity Gates (micro + macro)
/write-fe-spec	After updating FE index	Spec Pipeline Update
/write-fe-spec	Before request review	Ambiguity Gates (micro + macro)
/plan-phase	Step 7	Progress Generation
/implement-slice	Step 0	Session Resumption
/implement-slice	Step 1.5	Parallel Claim
/implement-slice	Step 4 (during impl)	Decision Effect Analysis
/implement-slice	Step 6	Parallel Synthesis
/implement-slice	Step 7	Progress Update (incl. claim release)

DO / DON'T

DO

• ✅ Create progress files that mirror spec depth exactly
• ✅ Mark items immediately when complete (never defer check-offs)
• ✅ Log blockers the moment they're encountered
• ✅ Write session close log before ending any session
• ✅ Only add patterns with genuine reuse value

DON'T

• ❌ Over-generalize from a single experience (set confidence low)
• ❌ Create slice files for trivial slices (< 3 criteria)
• ❌ Skip session resumption at workflow start
• ❌ Let progress files drift from actual state
• ❌ Log every minor observation as a "pattern"