the-lifecycle.md

The session lifecycle

Reliable agent work is a loop, not a one-shot. The harness governs every transition; the model fills in the actual code at each step.

   ┌─────────────┐
   │ harness-init │  (once per repo)
   │  stamp files │  AGENTS.md · progress.md · feature_list.json · decisions.md
   │  seed scope  │  session-handoff.md · clean-state-checklist.md · init.ps1/.sh
   │  baseline ✔  │  → cold-start test passes
   └──────┬──────┘
          │
          v
   ┌─────────────┐      next session
   │ session-start│ <───────────────────────────┐
   │  orient from │  pwd · progress · features ·  │
   │  repo files  │  handoff · git log · init/verify
   │  fix baseline│  pick ONE feature, confirm    │
   └──────┬──────┘                                │
          │                                       │
          v                                       │
   ┌─────────────┐                                │
   │    work      │  implement the one feature     │
   │  (WIP = 1)   │  run its verification          │
   │  verify ✔    │  evidence, not confidence      │
   └──────┬──────┘                                │
          │                                       │
          v                                       │
   ┌─────────────┐                                │
   │ session-wrap │  verify · update state ·       │
   │  handoff +   │  write session-handoff.md ·    │
   │  clean state │  clean-state check · commit    │
   └──────┬──────┘                                │
          │                                       │
          └─────────► (reset / new session) ──────┘

The transitions

• init → start: once harness-init has made the repo legible, every future session begins with the session-start ritual instead of re-deriving how the project works.
• start → work: orientation finishes by choosing exactly one feature and confirming the next step. A broken baseline is fixed before this — never build on a failing start.
• work → wrap: a feature is only "done" when its verification ran and produced evidence.
• wrap → reset → start: the wrap writes session-handoff.md. That artifact is what makes a context reset (or a fresh agent, or you tomorrow) able to pick up cleanly. The quality of the handoff is the quality of the next session's start.

How to drive it

• Auto: the session-start and session-wrap skills trigger from natural phrasing ("let's continue", "wrap up").
• Manual: the prompt-commands /resume-work, /wrap-session, /init-harness, /context-low, and /review-gate invoke the same rituals deterministically, which is handy when a skill under-triggers.

See harness-model.md for what each artifact is, and context-management.md for keeping the loop healthy across long projects.