Atlas Session Lifecycle

Persistent project memory and session lifecycle management for Claude Code.

Featured in: I just delivered on a $30,000 contract thanks to Claude Code (r/ClaudeAI)

Install

curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash

Then run /start in any Claude Code project.

What It Does

Claude Code has no persistent memory between sessions. Every new conversation starts from zero. This creates three compounding problems:

• No persistent memory -- Context, decisions, and progress are lost between sessions. You re-explain the same things every time.
• Project sprawl -- Files accumulate at the project root with no organization. Scripts, docs, configs, and logs pile up across sessions.
• No lifecycle management -- Projects have goals, but no mechanism to track progress, verify completion, or transition to new objectives.

/start solves all three with a structured five-file memory bank, automatic file organization, and a soul purpose lifecycle that tracks your project from inception through completion.

How It Works

/start auto-detects which mode to run based on directory state:

/start
  |
  +-- session-context/ exists? --> Reconcile Mode
  |                                  +-- Validate & repair session files
  |                                  +-- Refresh CLAUDE.md via /init
  |                                  +-- Self-assess soul purpose status
  |                                  +-- Offer: Continue / Close / Redefine
  |                                  +-- Harvest learnings on closure
  |
  +-- No session-context/ -------> Init Mode
                                     +-- Capture soul purpose
                                     +-- Bootstrap 5-file memory bank
                                     +-- Organize root files
                                     +-- Generate CLAUDE.md
                                     +-- Onboard Ralph Loop

Init Mode (first run)

Triggered when session-context/ does not exist.

• Captures your project's soul purpose -- the single objective this project exists to achieve
• Detects environment (git status, existing files, tech stack)
• Bootstraps session-context/ with 5 memory bank files from immutable templates
• Scans root-level files and proposes an organization map (scripts, docs, config, logs)
• Generates or updates CLAUDE.md with project structure and governance sections
• Onboards Ralph Loop (automatic, manual, or skip)

Reconcile Mode (returning)

Triggered when session-context/ already exists.

• Validates and repairs session files from templates if corrupted
• Runs Claude's /init to refresh CLAUDE.md from current codebase state
• Reads soul purpose and active context to understand where you left off
• Self-assesses soul purpose completion (clearly incomplete, probably complete, uncertain)
• Presents lifecycle decision: Continue, Close, or Redefine soul purpose
• Harvests durable knowledge on closure -- promotes decisions, patterns, and troubleshooting entries

Capability Inventory

When /start runs in Reconcile mode (or when you run /sync --full), it generates a comprehensive capability inventory:

• MCP Tools: All available tools with test coverage status
• Security Claims: Security-related features needing verification
• Feature Claims: What the project claims vs what's tested
• Test Gaps: Untested code identified by priority

The inventory lives in session-context/CLAUDE-capability-inventory.md and is used by /research-before-coding to identify what needs validation testing. Results are cached based on git HEAD, so regeneration only happens when your code changes.

Stepback (bundled skill)

Also included: /stepback -- a strategic reassessment protocol for when debugging goes sideways. If you've hit the same error after 2+ fix attempts, /stepback forces you to zoom out:

1. Inventory all fix attempts and their assumptions
2. Find the common thread across failures
3. Research the architecture (mandatory Perplexity queries)
4. Test the broadest hypothesis first
5. Present symptom-level vs architecture-level fix options

Invoked separately via /stepback or /atlas-session-lifecycle:stepback.

Session Memory Bank

Five files in session-context/ give Claude persistent memory across sessions:

All files use a structured entry format with timestamps, 5W1H context, git references, and potential issues.

Soul Purpose Lifecycle

Every project has a soul purpose -- the single objective it exists to achieve.

Define --> Work --> Reconcile --> Assess --> Close or Continue
  |                                |              |
  |                                |              +--> Harvest learnings
  |                                |              +--> Archive purpose
  |                                |              +--> Redefine (optional)
  |                                |
  |                                +--> Self-assess completion
  |                                +--> Optional doubt agent verification
  |                                +--> User decides (never AI)
  |
  +--> Captured during Init Mode

Key invariant: The AI never closes a soul purpose. It assesses and suggests; the user decides.

Installation

One-liner (skill mode, default)

curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash

Installs to ~/.claude/skills/start/. The SKILL.md orchestrator and session-init.py script are placed together.

Plugin mode

curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash -s -- --plugin

Installs to ~/.claude/plugins/atlas-session-lifecycle/ with full plugin structure including plugin.json.

Manual install

git clone https://github.com/anombyte93/atlas-session-lifecycle.git
cd atlas-session-lifecycle
./install.sh

Or copy files directly:

mkdir -p ~/.claude/skills/start
cp skills/start/SKILL.md ~/.claude/skills/start/SKILL.md
cp scripts/session-init.py ~/.claude/skills/start/session-init.py
chmod +x ~/.claude/skills/start/session-init.py
mkdir -p ~/claude-session-init-templates
cp templates/* ~/claude-session-init-templates/

Version toggle

# Install v1 (monolithic SKILL.md, no script)
./install.sh --version v1

# Revert from v2 back to v1 (backs up v2 files first)
./install.sh --revert

# Pull latest version and reinstall
./install.sh --update

Auto-update

The installer records a last-checked timestamp. On each run, if more than 24 hours have passed since the last check, it queries GitHub for newer releases and prompts you to update.

Configuration

custom.md

Edit custom.md in the plugin root (or ~/.claude/skills/start/custom.md for skill installs) to modify /start behavior. Write plain English instructions — no code needed. The AI reads these at each lifecycle phase and follows them.

Three headings control when your instructions apply:

## During Init
- After brainstorming, always suggest a git branching strategy
- Skip file organization for monorepo projects
- Always ask about deployment target (local, cloud, edge)

## During Reconcile
- Check for uncommitted changes before assessing soul purpose
- If soul purpose mentions "API", verify endpoints are documented
- Always show a progress percentage estimate

## Always
- Keep tone direct and concise. No fluff.
- When creating session context entries, include the git branch name
- Never suggest closing a soul purpose unless all tests pass

How it works: The skill reads custom.md at specific points — during init (after session-context is bootstrapped), during reconcile (after reading context, before assessment), and always (both modes). Your instructions augment the default behavior; they don't replace the skill logic.

Examples of what you can customize:

• Tone and verbosity of responses
• Extra questions to ask during brainstorm
• Conditions for when to suggest soul purpose closure
• Project-specific checks during reconcile
• Integration with other tools or workflows

Ralph Loop

During Init, the skill asks how Ralph Loop should operate:

• Automatic -- starts Ralph Loop after setup with configurable intensity (small, medium, long)
• Manual -- user triggers each iteration explicitly
• Skip -- no Ralph Loop

The preference is stored in CLAUDE.md and respected on subsequent Reconcile runs.

Upgrading from v1

v2 is a backward-compatible evolution. Your existing session-context/ files, templates, and project structure are unchanged.

The main difference: v1 was a single 867-line SKILL.md where Claude interpreted all operations from prose. v2 extracts deterministic operations into session-init.py (9 JSON-outputting subcommands), reducing SKILL.md to a slim orchestrator. The user experience is identical.

To revert at any time:

./install.sh --revert

Plugin Structure

atlas-session-lifecycle/
  .claude-plugin/
    plugin.json               # Plugin metadata (name, version, keywords)
  skills/
    start/
      SKILL.md                # Session lifecycle orchestrator
    stepback/
      SKILL.md                # Strategic reassessment for stuck debugging
  scripts/
    session-init.py           # Deterministic ops (9 JSON-outputting subcommands)
  custom.md                   # User customization hook (plain English)
  templates/
    CLAUDE-activeContext.md
    CLAUDE-decisions.md
    CLAUDE-mdReference.md
    CLAUDE-patterns.md
    CLAUDE-soul-purpose.md
    CLAUDE-troubleshooting.md
  v1/
    SKILL.md                  # v1 monolithic skill (867 lines)
  install.sh                  # Installer with version toggle and auto-update
  README.md
  LICENSE
  CONTRIBUTING.md
  CODE_OF_CONDUCT.md
  SECURITY.md

Requirements

• Claude Code CLI
• Python 3.8+
• Git (optional -- enables git mv for tracked files during organization)

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT