a-organvm/session-lifecycle-patterns

Session Lifecycle Patterns

Structure AI agent sessions for predictable outcomes, context preservation, and clean handoffs.

The Phase Model

FRAME → SHAPE → BUILD → PROVE → DONE
  ↑       ↑       ↑       ↑
  └───────┴───────┴───────┘
     (back-transitions allowed)

Phase Definitions

| Phase | Purpose | Activities | Gate | |-------|---------|-----------|------| | FRAME | Understand context | Explore code, read docs, ask questions | Can articulate the problem | | SHAPE | Design approach | Create plan, identify files, consider tradeoffs | Plan reviewed and approved | | BUILD | Implement | Write code, create files, apply changes | Implementation complete | | PROVE | Verify | Run tests, validate output, check quality | All checks pass | | DONE | Close | Summarize, commit, document decisions | Session artifacts preserved |

Phase Transitions

VALID_TRANSITIONS = {
    "FRAME": ["SHAPE"],
    "SHAPE": ["FRAME", "BUILD"],       # Can go back to reframe
    "BUILD": ["SHAPE", "PROVE"],       # Can go back to reshape
    "PROVE": ["BUILD", "DONE"],        # Can go back to fix
    "DONE": [],                        # Terminal
}

def can_transition(current: str, target: str) -> bool:
    return target in VALID_TRANSITIONS.get(current, [])

Phase Anti-Patterns

• Skipping FRAME — Jumping to code without understanding the problem
• SHAPE → BUILD without approval — Building before alignment on approach
• Staying in BUILD forever — Not proving that the work is correct
• PROVE → DONE without evidence — Claiming completion without verification

Session Metadata

Session Record Structure

session:
  id: "sess_2026-03-20_a1b2c3"
  started: "2026-03-20T10:58:00Z"
  ended: "2026-03-20T12:30:00Z"
  phase_history:
    - phase: FRAME
      entered: "2026-03-20T10:58:00Z"
      duration_minutes: 15
    - phase: SHAPE
      entered: "2026-03-20T11:13:00Z"
      duration_minutes: 20
    - phase: BUILD
      entered: "2026-03-20T11:33:00Z"
      duration_minutes: 45
    - phase: PROVE
      entered: "2026-03-20T12:18:00Z"
      duration_minutes: 12
  scope:
    organ: IV
    repo: a-i--skills
    task: "Create python-packaging-patterns skill"
  artifacts:
    files_created: [skills/development/python-packaging-patterns/SKILL.md]
    files_modified: []
    commits: ["abc123"]
  decisions:
    - "Chose hatchling as recommended build backend"
    - "Included namespace package pattern for multi-repo use"

Context Preservation

Intra-Session Context

Maintain context as the session progresses through phases:

class SessionContext:
    def __init__(self):
        self.discoveries: list[str] = []   # FRAME findings
        self.plan: dict = {}               # SHAPE output
        self.changes: list[str] = []       # BUILD artifacts
        self.evidence: list[str] = []      # PROVE results

    def frame_discovery(self, finding: str):
        self.discoveries.append(finding)

    def shape_decision(self, key: str, value: str, rationale: str):
        self.plan[key] = {"value": value, "rationale": rationale}

Inter-Session Context

For multi-session work, preserve essential context at session end:

## Session Close Summary

### What was accomplished
- Created 6 Wave 0 skills (python-packaging-patterns through vector-search-patterns)

### What remains
- 18 more Wave 0 skills in Batches 2-4
- Waves 1-4 pending

### Key decisions
- Using governance_norm_group: repo-hygiene for packaging/config skills
- Using organ_affinity: [all] for cross-cutting infrastructure skills

### Blockers
- None

### Next session should start by
- Reading this summary
- Continuing with Wave 0 Batch 2

Session Types

Exploration Session

FRAME (80%) → SHAPE (20%) → DONE

Heavy on reading, light on planning, no implementation. Produces understanding and a plan for a future BUILD session.

Implementation Session

FRAME (10%) → SHAPE (15%) → BUILD (55%) → PROVE (20%) → DONE

Quick reorientation, then focused building and verification.

Debug Session

FRAME (40%) → BUILD (30%) → PROVE (30%) → DONE

Heavy investigation, targeted fix, thorough verification.

Review Session

FRAME (30%) → PROVE (70%) → DONE

Mostly reading and validating existing work.

Multi-Session Continuity

Session Chains

When work spans multiple sessions, each session references the chain:

chain:
  id: "skill-fortification-campaign"
  session_index: 3
  total_sessions_estimated: 15
  previous_session: "sess_2026-03-20_wave0-batch1"
  completed_items: ["A1", "A2", "A3", "A4", "A5", "A6"]
  remaining_items: ["A7", "A8", "A13", "A14", "B1", "B2", ...]

Handoff Protocol

At session end, produce a handoff document:

1. State snapshot — What exists now (files, branches, test status)
2. Decision log — Why choices were made (so next session doesn't re-litigate)
3. Next actions — Exactly what to do next, with no ambiguity
4. Risk flags — Anything the next session should watch for

Session Quality Signals

| Signal | Healthy | Unhealthy | |--------|---------|-----------| | Phase transitions | Sequential with occasional back-steps | Skipping phases, staying in one phase | | FRAME duration | 10-30% of session | <5% or >50% | | PROVE evidence | Concrete test/validation output | "I think this works" | | Context preserved | Summary written at DONE | Session ends abruptly | | Scope creep | Stays within stated scope | Expanding mid-BUILD |

Anti-Patterns

• Infinite FRAME — Analysis paralysis; at some point, start shaping
• Skipping PROVE — Every BUILD must be proved before DONE
• No session close — Always write a summary, even if brief
• Context loss between sessions — Handoff documents are mandatory for multi-session work
• Phase theater — Going through motions without substance in each phase