{"id":45679644,"url":"https://github.com/anombyte93/atlas-session-lifecycle","last_synced_at":"2026-04-10T11:34:19.968Z","repository":{"id":337538996,"uuid":"1154060369","full_name":"anombyte93/atlas-session-lifecycle","owner":"anombyte93","description":"Session lifecycle management for Claude Code — persistent memory, soul purpose, reconcile, harvest, archive","archived":false,"fork":false,"pushed_at":"2026-02-26T07:21:56.000Z","size":391,"stargazers_count":84,"open_issues_count":79,"forks_count":8,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T23:34:14.999Z","etag":null,"topics":["ai-workflow","claude-code","claude-code-plugin","developer-tools","lifecycle-management","persistent-memory","productivity","project-initialization","session-management","soul-purpose"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anombyte93.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T01:06:14.000Z","updated_at":"2026-02-24T07:38:32.000Z","dependencies_parsed_at":"2026-03-09T20:04:51.499Z","dependency_job_id":null,"html_url":"https://github.com/anombyte93/atlas-session-lifecycle","commit_stats":null,"previous_names":["anombyte93/claude-session-init","anombyte93/atlas-session-lifecycle"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/anombyte93/atlas-session-lifecycle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anombyte93%2Fatlas-session-lifecycle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anombyte93%2Fatlas-session-lifecycle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anombyte93%2Fatlas-session-lifecycle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anombyte93%2Fatlas-session-lifecycle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anombyte93","download_url":"https://codeload.github.com/anombyte93/atlas-session-lifecycle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anombyte93%2Fatlas-session-lifecycle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31641310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-workflow","claude-code","claude-code-plugin","developer-tools","lifecycle-management","persistent-memory","productivity","project-initialization","session-management","soul-purpose"],"created_at":"2026-02-24T14:00:36.904Z","updated_at":"2026-04-10T11:34:19.939Z","avatar_url":"https://github.com/anombyte93.png","language":"Python","readme":"# Atlas Session Lifecycle\n\n[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/anombyte93/atlas-session-lifecycle/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![GitHub stars](https://img.shields.io/github/stars/anombyte93/atlas-session-lifecycle)](https://github.com/anombyte93/atlas-session-lifecycle/stargazers) [![Last Commit](https://img.shields.io/github/last-commit/anombyte93/atlas-session-lifecycle)](https://github.com/anombyte93/atlas-session-lifecycle/commits/main) [![GitHub Issues](https://img.shields.io/github/issues/anombyte93/atlas-session-lifecycle)](https://github.com/anombyte93/atlas-session-lifecycle/issues)\n\nPersistent project memory and session lifecycle management for Claude Code.\n\n\u003e **Featured in**: [I just delivered on a $30,000 contract thanks to Claude Code](https://www.reddit.com/r/ClaudeAI/comments/1r0n1qz/i_just_delivered_on_a_30000_contract_thanks_to/) (r/ClaudeAI)\n\n---\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash\n```\n\nThen run `/start` in any Claude Code project.\n\n---\n\n## What It Does\n\nClaude Code has no persistent memory between sessions. Every new conversation starts from zero. This creates three compounding problems:\n\n- **No persistent memory** -- Context, decisions, and progress are lost between sessions. You re-explain the same things every time.\n- **Project sprawl** -- Files accumulate at the project root with no organization. Scripts, docs, configs, and logs pile up across sessions.\n- **No lifecycle management** -- Projects have goals, but no mechanism to track progress, verify completion, or transition to new objectives.\n\n`/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.\n\n---\n\n## How It Works\n\n`/start` auto-detects which mode to run based on directory state:\n\n```\n/start\n  |\n  +-- session-context/ exists? --\u003e Reconcile Mode\n  |                                  +-- Validate \u0026 repair session files\n  |                                  +-- Refresh CLAUDE.md via /init\n  |                                  +-- Self-assess soul purpose status\n  |                                  +-- Offer: Continue / Close / Redefine\n  |                                  +-- Harvest learnings on closure\n  |\n  +-- No session-context/ -------\u003e Init Mode\n                                     +-- Capture soul purpose\n                                     +-- Bootstrap 5-file memory bank\n                                     +-- Organize root files\n                                     +-- Generate CLAUDE.md\n                                     +-- Onboard Ralph Loop\n```\n\n### Init Mode (first run)\n\nTriggered when `session-context/` does not exist.\n\n- Captures your project's **soul purpose** -- the single objective this project exists to achieve\n- Detects environment (git status, existing files, tech stack)\n- Bootstraps `session-context/` with 5 memory bank files from immutable templates\n- Scans root-level files and proposes an organization map (scripts, docs, config, logs)\n- Generates or updates `CLAUDE.md` with project structure and governance sections\n- Onboards Ralph Loop (automatic, manual, or skip)\n\n### Reconcile Mode (returning)\n\nTriggered when `session-context/` already exists.\n\n- Validates and repairs session files from templates if corrupted\n- Runs Claude's `/init` to refresh `CLAUDE.md` from current codebase state\n- Reads soul purpose and active context to understand where you left off\n- Self-assesses soul purpose completion (clearly incomplete, probably complete, uncertain)\n- Presents lifecycle decision: **Continue**, **Close**, or **Redefine** soul purpose\n- Harvests durable knowledge on closure -- promotes decisions, patterns, and troubleshooting entries\n\n### Capability Inventory\n\nWhen `/start` runs in Reconcile mode (or when you run `/sync --full`), it generates a comprehensive capability inventory:\n\n- **MCP Tools**: All available tools with test coverage status\n- **Security Claims**: Security-related features needing verification\n- **Feature Claims**: What the project claims vs what's tested\n- **Test Gaps**: Untested code identified by priority\n\nThe 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.\n\n### Stepback (bundled skill)\n\nAlso 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:\n\n1. Inventory all fix attempts and their assumptions\n2. Find the common thread across failures\n3. Research the architecture (mandatory Perplexity queries)\n4. Test the broadest hypothesis first\n5. Present symptom-level vs architecture-level fix options\n\nInvoked separately via `/stepback` or `/atlas-session-lifecycle:stepback`.\n\n---\n\n## Session Memory Bank\n\nFive files in `session-context/` give Claude persistent memory across sessions:\n\n| File | Purpose |\n|------|---------|\n| `CLAUDE-activeContext.md` | Current session state, goals, and progress |\n| `CLAUDE-decisions.md` | Architecture decisions and rationale |\n| `CLAUDE-patterns.md` | Established code patterns and conventions |\n| `CLAUDE-troubleshooting.md` | Common issues and proven solutions |\n| `CLAUDE-soul-purpose.md` | Soul purpose definition and completion criteria |\n\nAll files use a structured entry format with timestamps, 5W1H context, git references, and potential issues.\n\n---\n\n## Soul Purpose Lifecycle\n\nEvery project has a soul purpose -- the single objective it exists to achieve.\n\n```\nDefine --\u003e Work --\u003e Reconcile --\u003e Assess --\u003e Close or Continue\n  |                                |              |\n  |                                |              +--\u003e Harvest learnings\n  |                                |              +--\u003e Archive purpose\n  |                                |              +--\u003e Redefine (optional)\n  |                                |\n  |                                +--\u003e Self-assess completion\n  |                                +--\u003e Optional doubt agent verification\n  |                                +--\u003e User decides (never AI)\n  |\n  +--\u003e Captured during Init Mode\n```\n\n**Key invariant**: The AI never closes a soul purpose. It assesses and suggests; the user decides.\n\n---\n\n## Installation\n\n### One-liner (skill mode, default)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash\n```\n\nInstalls to `~/.claude/skills/start/`. The SKILL.md orchestrator and `session-init.py` script are placed together.\n\n### Plugin mode\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash -s -- --plugin\n```\n\nInstalls to `~/.claude/plugins/atlas-session-lifecycle/` with full plugin structure including `plugin.json`.\n\n### Manual install\n\n```bash\ngit clone https://github.com/anombyte93/atlas-session-lifecycle.git\ncd atlas-session-lifecycle\n./install.sh\n```\n\nOr copy files directly:\n\n```bash\nmkdir -p ~/.claude/skills/start\ncp skills/start/SKILL.md ~/.claude/skills/start/SKILL.md\ncp scripts/session-init.py ~/.claude/skills/start/session-init.py\nchmod +x ~/.claude/skills/start/session-init.py\nmkdir -p ~/claude-session-init-templates\ncp templates/* ~/claude-session-init-templates/\n```\n\n### Version toggle\n\n```bash\n# Install v1 (monolithic SKILL.md, no script)\n./install.sh --version v1\n\n# Revert from v2 back to v1 (backs up v2 files first)\n./install.sh --revert\n\n# Pull latest version and reinstall\n./install.sh --update\n```\n\n### Auto-update\n\nThe 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.\n\n---\n\n## Configuration\n\n### custom.md\n\nEdit `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.\n\nThree headings control when your instructions apply:\n\n```markdown\n## During Init\n- After brainstorming, always suggest a git branching strategy\n- Skip file organization for monorepo projects\n- Always ask about deployment target (local, cloud, edge)\n\n## During Reconcile\n- Check for uncommitted changes before assessing soul purpose\n- If soul purpose mentions \"API\", verify endpoints are documented\n- Always show a progress percentage estimate\n\n## Always\n- Keep tone direct and concise. No fluff.\n- When creating session context entries, include the git branch name\n- Never suggest closing a soul purpose unless all tests pass\n```\n\n**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.\n\n**Examples of what you can customize**:\n- Tone and verbosity of responses\n- Extra questions to ask during brainstorm\n- Conditions for when to suggest soul purpose closure\n- Project-specific checks during reconcile\n- Integration with other tools or workflows\n\n### Ralph Loop\n\nDuring Init, the skill asks how Ralph Loop should operate:\n\n- **Automatic** -- starts Ralph Loop after setup with configurable intensity (small, medium, long)\n- **Manual** -- user triggers each iteration explicitly\n- **Skip** -- no Ralph Loop\n\nThe preference is stored in `CLAUDE.md` and respected on subsequent Reconcile runs.\n\n---\n\n## Upgrading from v1\n\nv2 is a backward-compatible evolution. Your existing `session-context/` files, templates, and project structure are unchanged.\n\nThe 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.\n\nTo revert at any time:\n\n```bash\n./install.sh --revert\n```\n\n---\n\n## Plugin Structure\n\n```\natlas-session-lifecycle/\n  .claude-plugin/\n    plugin.json               # Plugin metadata (name, version, keywords)\n  skills/\n    start/\n      SKILL.md                # Session lifecycle orchestrator\n    stepback/\n      SKILL.md                # Strategic reassessment for stuck debugging\n  scripts/\n    session-init.py           # Deterministic ops (9 JSON-outputting subcommands)\n  custom.md                   # User customization hook (plain English)\n  templates/\n    CLAUDE-activeContext.md\n    CLAUDE-decisions.md\n    CLAUDE-mdReference.md\n    CLAUDE-patterns.md\n    CLAUDE-soul-purpose.md\n    CLAUDE-troubleshooting.md\n  v1/\n    SKILL.md                  # v1 monolithic skill (867 lines)\n  install.sh                  # Installer with version toggle and auto-update\n  README.md\n  LICENSE\n  CONTRIBUTING.md\n  CODE_OF_CONDUCT.md\n  SECURITY.md\n```\n\n---\n\n## Requirements\n\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI\n- Python 3.8+\n- Git (optional -- enables `git mv` for tracked files during organization)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanombyte93%2Fatlas-session-lifecycle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanombyte93%2Fatlas-session-lifecycle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanombyte93%2Fatlas-session-lifecycle/lists"}