Skip to content
Back to search

atlas-session-lifecycle

Session lifecycle management for Claude Code — persistent memory, soul purpose, reconcile, harvest, archive

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/anombyte93--atlas-session-lifecycle/badge.svg)](/listings/anombyte93--atlas-session-lifecycle)

HTML

<a href="/listings/anombyte93--atlas-session-lifecycle"><img src="/api/listings/anombyte93--atlas-session-lifecycle/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

Then run `/start` in any Claude Code project.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 305 lines · 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Atlas Session Lifecycle
  2. [![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)
  3. Persistent project memory and session lifecycle management for Claude Code.
  4. > **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)
  5. ---
  6. ## Install
  7. ```bash
  8. curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 14 on GitHub
  9. ```
  10. Then run `/start` in any Claude Code project.
  11. ---
  12. ## What It Does
  13. Claude Code has no persistent memory between sessions. Every new conversation starts from zero. This creates three compounding problems:
  14. - **No persistent memory** -- Context, decisions, and progress are lost between sessions. You re-explain the same things every time.
  15. - **Project sprawl** -- Files accumulate at the project root with no organization. Scripts, docs, configs, and logs pile up across sessions.
  16. - **No lifecycle management** -- Projects have goals, but no mechanism to track progress, verify completion, or transition to new objectives.
  17. `/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.
  18. ---
  19. ## How It Works
  20. `/start` auto-detects which mode to run based on directory state:
  21. ```
  22. /start
  23. |
  24. +-- session-context/ exists? --> Reconcile Mode
  25. | +-- Validate & repair session files
  26. | +-- Refresh CLAUDE.md via /init
  27. | +-- Self-assess soul purpose status
  28. | +-- Offer: Continue / Close / Redefine
  29. | +-- Harvest learnings on closure
  30. |
  31. +-- No session-context/ -------> Init Mode
  32. +-- Capture soul purpose
  33. +-- Bootstrap 5-file memory bank
  34. +-- Organize root files
  35. +-- Generate CLAUDE.md
  36. +-- Onboard Ralph Loop
  37. ```
  38. ### Init Mode (first run)
  39. Triggered when `session-context/` does not exist.
  40. - Captures your project's **soul purpose** -- the single objective this project exists to achieve
  41. - Detects environment (git status, existing files, tech stack)
  42. - Bootstraps `session-context/` with 5 memory bank files from immutable templates
  43. - Scans root-level files and proposes an organization map (scripts, docs, config, logs)
  44. - Generates or updates `CLAUDE.md` with project structure and governance sections
  45. - Onboards Ralph Loop (automatic, manual, or skip)
  46. ### Reconcile Mode (returning)
  47. Triggered when `session-context/` already exists.
  48. - Validates and repairs session files from templates if corrupted
  49. - Runs Claude's `/init` to refresh `CLAUDE.md` from current codebase state
  50. - Reads soul purpose and active context to understand where you left off
  51. - Self-assesses soul purpose completion (clearly incomplete, probably complete, uncertain)
  52. - Presents lifecycle decision: **Continue**, **Close**, or **Redefine** soul purpose
  53. - Harvests durable knowledge on closure -- promotes decisions, patterns, and troubleshooting entries
  54. ### Capability Inventory
  55. When `/start` runs in Reconcile mode (or when you run `/sync --full`), it generates a comprehensive capability inventory:
  56. - **MCP Tools**: All available tools with test coverage status
  57. - **Security Claims**: Security-related features needing verification
  58. - **Feature Claims**: What the project claims vs what's tested
  59. - **Test Gaps**: Untested code identified by priority
  60. 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.
  61. ### Stepback (bundled skill)
  62. 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:
  63. 1. Inventory all fix attempts and their assumptions
  64. 2. Find the common thread across failures
  65. 3. Research the architecture (mandatory Perplexity queries)
  66. 4. Test the broadest hypothesis first
  67. 5. Present symptom-level vs architecture-level fix options
  68. Invoked separately via `/stepback` or `/atlas-session-lifecycle:stepback`.
  69. ---
  70. ## Session Memory Bank
  71. Five files in `session-context/` give Claude persistent memory across sessions:
  72. | File | Purpose |
  73. |------|---------|
  74. | `CLAUDE-activeContext.md` | Current session state, goals, and progress |
  75. | `CLAUDE-decisions.md` | Architecture decisions and rationale |
  76. | `CLAUDE-patterns.md` | Established code patterns and conventions |
  77. | `CLAUDE-troubleshooting.md` | Common issues and proven solutions |
  78. | `CLAUDE-soul-purpose.md` | Soul purpose definition and completion criteria |
  79. All files use a structured entry format with timestamps, 5W1H context, git references, and potential issues.
  80. ---
  81. ## Soul Purpose Lifecycle
  82. Every project has a soul purpose -- the single objective it exists to achieve.
  83. ```
  84. Define --> Work --> Reconcile --> Assess --> Close or Continue
  85. | | |
  86. | | +--> Harvest learnings
  87. | | +--> Archive purpose
  88. | | +--> Redefine (optional)
  89. | |
  90. | +--> Self-assess completion
  91. | +--> Optional doubt agent verification
  92. | +--> User decides (never AI)
  93. |
  94. +--> Captured during Init Mode
  95. ```
  96. **Key invariant**: The AI never closes a soul purpose. It assesses and suggests; the user decides.
  97. ---
  98. ## Installation
  99. ### One-liner (skill mode, default)
  100. ```bash
  101. curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 145 on GitHub
  102. ```
  103. Installs to `~/.claude/skills/start/`. The SKILL.md orchestrator and `session-init.py` script are placed together.
  104. ### Plugin mode
  105. ```bash
  106. curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash -s -- --plugin
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 153 on GitHub
  107. ```
  108. Installs to `~/.claude/plugins/atlas-session-lifecycle/` with full plugin structure including `plugin.json`.
  109. ### Manual install
  110. ```bash
  111. git clone https://github.com/anombyte93/atlas-session-lifecycle.git
  112. cd atlas-session-lifecycle
  113. ./install.sh
  114. ```
  115. Or copy files directly:
  116. ```bash
  117. mkdir -p ~/.claude/skills/start
  118. cp skills/start/SKILL.md ~/.claude/skills/start/SKILL.md
  119. cp scripts/session-init.py ~/.claude/skills/start/session-init.py
  120. chmod +x ~/.claude/skills/start/session-init.py
  121. mkdir -p ~/claude-session-init-templates
  122. cp templates/* ~/claude-session-init-templates/
  123. ```
  124. ### Version toggle
  125. ```bash
  126. # Install v1 (monolithic SKILL.md, no script)
  127. ./install.sh --version v1
  128. # Revert from v2 back to v1 (backs up v2 files first)
  129. ./install.sh --revert
  130. # Pull latest version and reinstall
  131. ./install.sh --update
  132. ```
  133. ### Auto-update
  134. 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.
  135. ---
  136. ## Configuration
  137. ### custom.md
  138. 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.
  139. Three headings control when your instructions apply:
  140. ```markdown
  141. ## During Init
  142. - After brainstorming, always suggest a git branching strategy
  143. - Skip file organization for monorepo projects
  144. - Always ask about deployment target (local, cloud, edge)
  145. ## During Reconcile
  146. - Check for uncommitted changes before assessing soul purpose
  147. - If soul purpose mentions "API", verify endpoints are documented
  148. - Always show a progress percentage estimate
  149. ## Always
  150. - Keep tone direct and concise. No fluff.
  151. - When creating session context entries, include the git branch name
  152. - Never suggest closing a soul purpose unless all tests pass
  153. ```
  154. **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.
  155. **Examples of what you can customize**:
  156. - Tone and verbosity of responses
  157. - Extra questions to ask during brainstorm
  158. - Conditions for when to suggest soul purpose closure
  159. - Project-specific checks during reconcile
  160. - Integration with other tools or workflows
  161. ### Ralph Loop
  162. During Init, the skill asks how Ralph Loop should operate:
  163. - **Automatic** -- starts Ralph Loop after setup with configurable intensity (small, medium, long)
  164. - **Manual** -- user triggers each iteration explicitly
  165. - **Skip** -- no Ralph Loop
  166. The preference is stored in `CLAUDE.md` and respected on subsequent Reconcile runs.
  167. ---
  168. ## Upgrading from v1
  169. v2 is a backward-compatible evolution. Your existing `session-context/` files, templates, and project structure are unchanged.
  170. 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.
  171. To revert at any time:
  172. ```bash
  173. ./install.sh --revert
  174. ```
  175. ---
  176. ## Plugin Structure
  177. ```
  178. atlas-session-lifecycle/
  179. .claude-plugin/
  180. plugin.json # Plugin metadata (name, version, keywords)
  181. skills/
  182. start/
  183. SKILL.md # Session lifecycle orchestrator
  184. stepback/
  185. SKILL.md # Strategic reassessment for stuck debugging
  186. scripts/
  187. session-init.py # Deterministic ops (9 JSON-outputting subcommands)
  188. custom.md # User customization hook (plain English)
  189. templates/
  190. CLAUDE-activeContext.md
  191. CLAUDE-decisions.md
  192. CLAUDE-mdReference.md
  193. CLAUDE-patterns.md
  194. CLAUDE-soul-purpose.md
  195. CLAUDE-troubleshooting.md
  196. v1/
  197. SKILL.md # v1 monolithic skill (867 lines)
  198. install.sh # Installer with version toggle and auto-update
  199. README.md
  200. LICENSE
  201. CONTRIBUTING.md
  202. CODE_OF_CONDUCT.md
  203. SECURITY.md
  204. ```
  205. ---
  206. ## Requirements
  207. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
  208. - Python 3.8+
  209. - Git (optional -- enables `git mv` for tracked files during organization)
  210. ---
  211. ## Contributing
  212. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  213. ---
  214. ## License
  215. [MIT](LICENSE)
install.sh · Bundled script · 515 lines · 6 findings marked
  1. #!/usr/bin/env bash
  2. # ============================================================================
  3. # Atlas Session Lifecycle — Installer
  4. # ============================================================================
  5. # Usage:
  6. # curl -fsSL https://raw.githubusercontent.com/anombyte93/atlas-session-lifecycle/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 6 on GitHub
  7. # curl -fsSL ... | bash -s -- --plugin # install as Claude Code plugin
  8. # bash install.sh # skill mode (default)
  9. # bash install.sh --plugin # plugin mode
  10. # bash install.sh --version v1 # install v1 (legacy)
  11. # bash install.sh --revert # revert to v1
  12. # bash install.sh --update # pull latest and reinstall
  13. # bash install.sh --check-update # check for newer version
  14. # bash install.sh --no-extras # skip bundled extra skills
  15. # bash install.sh --all # install all extras without prompting
  16. # ============================================================================
  17. set -euo pipefail
  18. REPO_OWNER="anombyte93"
  19. REPO_NAME="atlas-session-lifecycle"
  20. SKILL_NAME="start"
  21. VERSION="4.1.0"
  22. # SECURITY: Pin to specific commit hash for integrity
  23. # Update this when releasing new versions
  24. PINNED_COMMIT="8c4cbc5"
  25. SKILL_DIR="${SKILL_DIR:-${HOME}/.claude/skills/${SKILL_NAME}}"
  26. PLUGIN_DIR="${HOME}/.claude/plugins/${REPO_NAME}"
  27. TEMPLATE_DIR="${HOME}/claude-session-init-templates"
  28. UPDATES_DIR="${HOME}/.config/claude-skills"
  29. UPDATES_FILE="${UPDATES_DIR}/updates.json"
  30. UPDATE_INTERVAL_SECONDS=86400
  31. GITHUB_API="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest"
  32. CLONE_URL="https://github.com/${REPO_OWNER}/${REPO_NAME}.git"
  33. if [[ -t 1 ]] && [[ -z "${CI:-}" ]] && [[ -z "${NO_COLOR:-}" ]]; then
  34. RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[0;33m'
  35. CYAN='\033[0;36m'; BOLD='\033[1m'; RESET='\033[0m'
  36. else
  37. RED='' GREEN='' YELLOW='' CYAN='' BOLD='' RESET=''
  38. fi
  39. info() { printf "${CYAN}[info]${RESET} %s\n" "$*"; }
  40. ok() { printf "${GREEN}[ok]${RESET} %s\n" "$*"; }
  41. warn() { printf "${YELLOW}[warn]${RESET} %s\n" "$*"; }
  42. err() { printf "${RED}[error]${RESET} %s\n" "$*" >&2; }
  43. die() { err "$@"; exit 1; }
  44. cleanup() {
  45. if [[ -n "${TMPDIR_SKILL:-}" ]] && [[ -d "${TMPDIR_SKILL}" ]]; then
  46. rm -rf "${TMPDIR_SKILL}"
  47. fi
  48. }
  49. trap cleanup EXIT
  50. require_cmd() {
  51. command -v "$1" >/dev/null 2>&1 || die "Required command not found: $1"
  52. }
  53. check_update() {
  54. if [[ -n "${CI:-}" ]] || [[ -n "${NO_UPDATE_CHECK:-}" ]]; then return 0; fi
  55. require_cmd curl; require_cmd date; mkdir -p "${UPDATES_DIR}"
  56. if [[ -f "${UPDATES_FILE}" ]]; then
  57. local last_check; last_check=$(python3 -c "
  58. import json
  59. try:
  60. d = json.load(open('${UPDATES_FILE}'))
  61. print(d.get('skills', {}).get('${SKILL_NAME}', {}).get('last_check', 0))
  62. except: print(0)
  63. " 2>/dev/null || echo 0)
  64. local now; now=$(date +%s); local elapsed=$(( now - last_check ))
  65. if [[ ${elapsed} -lt ${UPDATE_INTERVAL_SECONDS} ]]; then
  66. local cached_latest; cached_latest=$(python3 -c "
  67. import json
  68. try:
  69. d = json.load(open('${UPDATES_FILE}'))
  70. print(d.get('skills', {}).get('${SKILL_NAME}', {}).get('latest', ''))
  71. except: print('')
  72. " 2>/dev/null || echo "")
  73. if [[ -n "${cached_latest}" ]] && [[ "${cached_latest}" != "${VERSION}" ]]; then
  74. warn "Update available: ${VERSION} -> ${cached_latest}"
  75. info "Run: curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 83 on GitHub
  76. fi; return 0
  77. fi
  78. fi
  79. local api_response; api_response=$(curl -fsSL --max-time 5 -H "Accept: application/vnd.github+json" "${GITHUB_API}" 2>/dev/null) || return 0
  80. local latest_version; latest_version=$(printf '%s' "${api_response}" | python3 -c "
  81. import json, sys, re
  82. try:
  83. data = json.load(sys.stdin)
  84. tag = data.get('tag_name', '')
  85. # SECURITY: Validate semver format to prevent code injection
  86. if re.match(r'^v?\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$', tag):
  87. print(tag.lstrip('v'))
  88. else:
  89. print('')
  90. except: print('')
  91. " 2>/dev/null || echo "")
  92. if [[ -z "${latest_version}" ]]; then return 0; fi
  93. # SECURITY: Validate version format before use
  94. if [[ ! "${latest_version}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then return 0; fi
  95. local now; now=$(date +%s)
  96. # SECURITY: Use shlex.quote equivalent via printf escaping
  97. python3 -c "
  98. import json, shlex
  99. path = shlex.quote('${UPDATES_FILE}')
  100. skill_name = shlex.quote('${SKILL_NAME}')
  101. now = ${now}
  102. latest = shlex.quote('${latest_version}')
  103. current = shlex.quote('${VERSION}')
  104. try: data = json.load(open(path))
  105. except: data = {}
  106. data.setdefault('skills', {})
  107. data['skills'][skill_name] = {'last_check': now, 'latest': latest, 'current': current}
  108. with open(path, 'w') as f: json.dump(data, f, indent=2)
  109. " 2>/dev/null || true
  110. if [[ "${latest_version}" != "${VERSION}" ]]; then
  111. warn "Update available: ${VERSION} -> ${latest_version}"
  112. info "Run: curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 120 on GitHub
  113. else ok "You are on the latest version (${VERSION})"; fi
  114. }
  115. revert_to_v1() {
  116. info "Reverting to v1 (monolithic SKILL.md, no script)"
  117. if [[ ! -d "${SKILL_DIR}" ]]; then
  118. die "No installation found at ${SKILL_DIR}. Nothing to revert."
  119. fi
  120. TMPDIR_SKILL=$(mktemp -d "${TMPDIR:-/tmp}/claude-skill-XXXXXX")
  121. info "Cloning ${REPO_OWNER}/${REPO_NAME} at ${PINNED_COMMIT}..."
  122. git clone --quiet "${CLONE_URL}" "${TMPDIR_SKILL}/repo" 2>/dev/null \
  123. || die "Failed to clone repository."
  124. git -C "${TMPDIR_SKILL}/repo" checkout --quiet "${PINNED_COMMIT}" 2>/dev/null \
  125. || die "Failed to checkout pinned commit."
  126. local src_dir="${TMPDIR_SKILL}/repo"
  127. if [[ ! -f "${src_dir}/v1/SKILL.md" ]]; then
  128. die "v1/SKILL.md not found in repository. Cannot revert."
  129. fi
  130. # Back up current v2 files
  131. if [[ -f "${SKILL_DIR}/SKILL.md" ]]; then
  132. cp "${SKILL_DIR}/SKILL.md" "${SKILL_DIR}/SKILL.md.v2-backup"
  133. ok "Backed up v2 SKILL.md -> SKILL.md.v2-backup"
  134. fi
  135. if [[ -f "${SKILL_DIR}/session-init.py" ]]; then
  136. cp "${SKILL_DIR}/session-init.py" "${SKILL_DIR}/session-init.py.v2-backup"
  137. ok "Backed up session-init.py -> session-init.py.v2-backup"
  138. fi
  139. # Install v1 SKILL.md
  140. cp "${src_dir}/v1/SKILL.md" "${SKILL_DIR}/SKILL.md"
  141. ok "Installed v1 SKILL.md (monolithic)"
  142. # Remove session-init.py (v1 doesn't use it)
  143. if [[ -f "${SKILL_DIR}/session-init.py" ]]; then
  144. rm "${SKILL_DIR}/session-init.py"
  145. ok "Removed session-init.py (not used by v1)"
  146. fi
  147. local timestamp; timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
  148. cat > "${SKILL_DIR}/.version" <<VEOF
  149. ${VERSION}-v1
  150. installed: ${timestamp}
  151. mode: revert
  152. repo: ${REPO_OWNER}/${REPO_NAME}
  153. skill_version: v1
  154. VEOF
  155. ok "Wrote .version (${VERSION}-v1, ${timestamp})"
  156. printf "\n"
  157. printf "${GREEN}${BOLD}Successfully reverted to v1${RESET}\n"
  158. printf " Location: %s\n" "${SKILL_DIR}"
  159. printf " Note: v2 files backed up with .v2-backup extension\n"
  160. printf "\n"
  161. }
  162. install_plugin() {
  163. local mode="install"
  164. info "Atlas Session Lifecycle — Plugin Installer"
  165. info "Version: ${BOLD}v${VERSION}${RESET}"
  166. printf "\n"; require_cmd git
  167. if [[ -d "${PLUGIN_DIR}" ]]; then
  168. mode="upgrade"
  169. info "Existing plugin installation detected"
  170. info "Mode: upgrade (pulling latest)"
  171. cd "${PLUGIN_DIR}"
  172. git fetch --quiet origin main 2>/dev/null || true
  173. git reset --hard origin/main --quiet 2>/dev/null || {
  174. warn "Git pull failed, doing fresh clone"
  175. cd "${HOME}"
  176. rm -rf "${PLUGIN_DIR}"
  177. mode="install"
  178. }
  179. if [[ "${mode}" == "upgrade" ]]; then
  180. local timestamp; timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
  181. ok "Updated plugin to latest (${timestamp})"
  182. printf "\n"
  183. printf "${GREEN}${BOLD}Successfully upgraded atlas-session-lifecycle plugin${RESET}\n"
  184. printf " Location: %s\n" "${PLUGIN_DIR}"
  185. printf "\n"
  186. info "To use: ${CYAN}/start${RESET}"
  187. printf "\n"
  188. return 0
  189. fi
  190. fi
  191. if [[ "${mode}" == "install" ]]; then
  192. info "Mode: fresh install"
  193. mkdir -p "$(dirname "${PLUGIN_DIR}")"
  194. git clone --quiet "${CLONE_URL}" "${PLUGIN_DIR}" 2>/dev/null \
  195. || die "Failed to clone repository."
  196. ok "Cloned plugin to ${PLUGIN_DIR}"
  197. fi
  198. # Also install templates to home dir fallback
  199. if [[ -d "${PLUGIN_DIR}/templates" ]]; then
  200. mkdir -p "${TEMPLATE_DIR}"
  201. cp "${PLUGIN_DIR}/templates/"* "${TEMPLATE_DIR}/" 2>/dev/null || true
  202. ok "Installed templates to ${TEMPLATE_DIR}/ (fallback)"
  203. fi
  204. printf "\n"
  205. printf "${GREEN}${BOLD}Successfully installed atlas-session-lifecycle plugin${RESET}\n"
  206. printf " Location: %s\n" "${PLUGIN_DIR}"
  207. printf " Templates: %s\n" "${TEMPLATE_DIR}"
  208. printf "\n"
  209. info "To use: ${CYAN}/start${RESET}"
  210. printf "\n"
  211. }
  212. install_extra_skills() {
  213. # Discover and install bundled skills beyond /start
  214. # $1 = src_dir (cloned repo), $2 = "all"|"ask"|"none"
  215. local src_dir="$1"
  216. local extras_mode="${2:-ask}"
  217. local skills_base="${HOME}/.claude/skills"
  218. if [[ "${extras_mode}" == "none" ]]; then return 0; fi
  219. # Discover extra skills (everything in skills/ except start/)
  220. local extras=()
  221. local descriptions=()
  222. if [[ -d "${src_dir}/skills" ]]; then
  223. for skill_dir in "${src_dir}/skills"/*/; do
  224. local skill_name; skill_name=$(basename "${skill_dir}")
  225. if [[ "${skill_name}" == "start" ]]; then continue; fi
  226. if [[ -f "${skill_dir}/SKILL.md" ]]; then
  227. extras+=("${skill_name}")
  228. # Extract description from YAML frontmatter
  229. local desc; desc=$(sed -n 's/^description: *"\{0,1\}\(.*\)"\{0,1\}$/\1/p' "${skill_dir}/SKILL.md" | head -1)
  230. descriptions+=("${desc:-No description}")
  231. fi
  232. done
  233. fi
  234. if [[ ${#extras[@]} -eq 0 ]]; then return 0; fi
  235. printf "\n"
  236. info "Bundled extra skills available:"
  237. printf "\n"
  238. for i in "${!extras[@]}"; do
  239. printf " ${BOLD}%d)${RESET} ${CYAN}/%s${RESET}\n" "$((i+1))" "${extras[$i]}"
  240. printf " %s\n" "${descriptions[$i]:0:100}"
  241. done
  242. printf "\n"
  243. local install_extras=()
  244. if [[ "${extras_mode}" == "all" ]]; then
  245. install_extras=("${extras[@]}")
  246. info "Installing all extra skills (--all)"
  247. elif [[ -t 0 ]] && [[ -t 1 ]]; then
  248. # Interactive — ask the user
  249. printf "Install extra skills? [${BOLD}a${RESET}]ll / [${BOLD}n${RESET}]one / [${BOLD}s${RESET}]elect: "
  250. local choice; read -r choice
  251. case "${choice}" in
  252. a|A|all|ALL|"")
  253. install_extras=("${extras[@]}") ;;
  254. n|N|none|NONE)
  255. info "Skipping extra skills"
  256. return 0 ;;
  257. s|S|select|SELECT)
  258. for i in "${!extras[@]}"; do
  259. printf " Install ${CYAN}/%s${RESET}? [Y/n]: " "${extras[$i]}"
  260. local yn; read -r yn
  261. case "${yn}" in
  262. n|N|no|NO) ;;
  263. *) install_extras+=("${extras[$i]}") ;;
  264. esac
  265. done ;;
  266. *)
  267. info "Skipping extra skills"
  268. return 0 ;;
  269. esac
  270. else
  271. # Non-interactive (piped via curl) — install all by default
  272. install_extras=("${extras[@]}")
  273. info "Installing all extra skills (non-interactive)"
  274. fi
  275. # Install selected extras
  276. for skill_name in "${install_extras[@]}"; do
  277. local target="${skills_base}/${skill_name}"
  278. mkdir -p "${target}"
  279. cp "${src_dir}/skills/${skill_name}/SKILL.md" "${target}/SKILL.md"
  280. ok "Installed /${skill_name} to ${target}/"
  281. done
  282. if [[ ${#install_extras[@]} -gt 0 ]]; then
  283. printf "\n"
  284. ok "Installed ${#install_extras[@]} extra skill(s)"
  285. fi
  286. }
  287. install_skill() {
  288. local target_version="${1:-v2}"
  289. local extras_mode="${2:-ask}"
  290. local mode="install"
  291. info "Atlas Session Lifecycle — Skill Installer"
  292. info "Skill: ${BOLD}${SKILL_NAME}${RESET} v${VERSION} (${target_version})"
  293. printf "\n"; require_cmd git
  294. if [[ -d "${SKILL_DIR}" ]]; then
  295. mode="upgrade"
  296. local existing_version="unknown"
  297. if [[ -f "${SKILL_DIR}/.version" ]]; then
  298. existing_version=$(head -1 "${SKILL_DIR}/.version" 2>/dev/null || echo "unknown")
  299. fi
  300. info "Existing installation detected (${existing_version})"
  301. info "Mode: upgrade"
  302. if [[ -f "${SKILL_DIR}/SKILL.md" ]]; then
  303. cp "${SKILL_DIR}/SKILL.md" "${SKILL_DIR}/SKILL.md.bak"
  304. ok "Backed up SKILL.md -> SKILL.md.bak"
  305. fi
  306. else info "Mode: fresh install"; fi
  307. TMPDIR_SKILL=$(mktemp -d "${TMPDIR:-/tmp}/claude-skill-XXXXXX")
  308. info "Cloning ${REPO_OWNER}/${REPO_NAME} at ${PINNED_COMMIT}..."
  309. git clone --quiet "${CLONE_URL}" "${TMPDIR_SKILL}/repo" 2>/dev/null \
  310. || die "Failed to clone repository."
  311. git -C "${TMPDIR_SKILL}/repo" checkout --quiet "${PINNED_COMMIT}" 2>/dev/null \
  312. || die "Failed to checkout pinned commit."
  313. local src_dir="${TMPDIR_SKILL}/repo"
  314. mkdir -p "${SKILL_DIR}"
  315. if [[ "${target_version}" == "v1" ]]; then
  316. # v1 install: monolithic SKILL.md, no script
  317. if [[ -f "${src_dir}/v1/SKILL.md" ]]; then
  318. cp "${src_dir}/v1/SKILL.md" "${SKILL_DIR}/SKILL.md"
  319. ok "Installed v1 SKILL.md (monolithic)"
  320. else
  321. die "v1/SKILL.md not found in repository."
  322. fi
  323. if [[ -f "${SKILL_DIR}/session-init.py" ]]; then
  324. rm "${SKILL_DIR}/session-init.py"
  325. ok "Removed session-init.py (not used by v1)"
  326. fi
  327. else
  328. # v2 install: skill from skills/start/, script from scripts/
  329. if [[ -f "${src_dir}/skills/start/SKILL.md" ]]; then
  330. cp "${src_dir}/skills/start/SKILL.md" "${SKILL_DIR}/SKILL.md"
  331. ok "Installed SKILL.md (orchestrator)"
  332. else
  333. die "skills/start/SKILL.md not found in repository."
  334. fi
  335. if [[ -f "${src_dir}/scripts/session-init.py" ]]; then
  336. cp "${src_dir}/scripts/session-init.py" "${SKILL_DIR}/session-init.py"
  337. chmod +x "${SKILL_DIR}/session-init.py"
  338. ok "Installed session-init.py (backend)"
  339. else
  340. die "scripts/session-init.py not found in repository."
  341. fi
  342. # Deploy MCP server source (atlas-session MCP package)
  343. if [[ -d "${src_dir}/src/atlas_session" ]]; then
  344. mkdir -p "${SKILL_DIR}/src"
  345. rm -rf "${SKILL_DIR}/src/atlas_session"
  346. cp -r "${src_dir}/src/atlas_session" "${SKILL_DIR}/src/atlas_session"
  347. if [[ -f "${src_dir}/src/pyproject.toml" ]]; then
  348. cp "${src_dir}/src/pyproject.toml" "${SKILL_DIR}/src/pyproject.toml"
  349. fi
  350. ok "Installed MCP server (src/atlas_session/)"
  351. else
  352. warn "src/atlas_session/ not found — MCP server not installed"
  353. fi
  354. fi
  355. # Install templates
  356. if [[ -d "${src_dir}/templates" ]]; then
  357. mkdir -p "${TEMPLATE_DIR}"
  358. cp "${src_dir}/templates/"* "${TEMPLATE_DIR}/" 2>/dev/null || true
  359. ok "Installed templates to ${TEMPLATE_DIR}/"
  360. fi
  361. if [[ -f "${src_dir}/install.sh" ]]; then
  362. cp "${src_dir}/install.sh" "${SKILL_DIR}/install.sh"
  363. chmod +x "${SKILL_DIR}/install.sh"
  364. fi
  365. # Offer extra bundled skills (v2 only)
  366. if [[ "${target_version}" == "v2" ]]; then
  367. install_extra_skills "${src_dir}" "${extras_mode}"
  368. fi
  369. local timestamp; timestamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
  370. cat > "${SKILL_DIR}/.version" <<VEOF
  371. ${VERSION}
  372. installed: ${timestamp}
  373. mode: ${mode}
  374. repo: ${REPO_OWNER}/${REPO_NAME}
  375. skill_version: ${target_version}
  376. VEOF
  377. ok "Wrote .version (${VERSION}, ${timestamp})"
  378. # Clean up old flat file if it exists
  379. if [[ -f "${HOME}/.claude/skills/start.md" ]]; then
  380. rm "${HOME}/.claude/skills/start.md"
  381. ok "Removed old flat file start.md"
  382. fi
  383. printf "\n"
  384. printf "${GREEN}${BOLD}Successfully %s ${SKILL_NAME} v${VERSION} (${target_version})${RESET}\n" \
  385. "$([ "${mode}" = "upgrade" ] && echo "upgraded" || echo "installed")"
  386. printf " Location: %s\n" "${SKILL_DIR}"
  387. printf " Templates: %s\n" "${TEMPLATE_DIR}"
  388. if [[ "${target_version}" == "v2" ]]; then
  389. printf " Script: %s/session-init.py\n" "${SKILL_DIR}"
  390. fi
  391. printf "\n"
  392. info "To use: ${CYAN}/start${RESET}"
  393. printf "\n"
  394. }
  395. main() {
  396. local target_version="v2"
  397. local install_mode="skill"
  398. local extras_mode="ask"
  399. # Parse modifier flags first
  400. local args=()
  401. for arg in "$@"; do
  402. case "${arg}" in
  403. --plugin) install_mode="plugin" ;;
  404. --no-extras) extras_mode="none" ;;
  405. --all) extras_mode="all" ;;
  406. *) args+=("${arg}") ;;
  407. esac
  408. done
  409. case "${args[0]:-}" in
  410. --check-update|-u) check_update ;;
  411. -v) echo "atlas-session-lifecycle v${VERSION}" ;;
  412. --revert) revert_to_v1 ;;
  413. --update)
  414. info "Updating atlas-session-lifecycle..."
  415. if [[ "${install_mode}" == "plugin" ]]; then
  416. install_plugin
  417. else
  418. install_skill "v2" "${extras_mode}"
  419. fi
  420. ;;
  421. --help|-h)
  422. printf "Usage: %s [OPTIONS]\n" "${0##*/}"
  423. printf "\n${BOLD}Atlas Session Lifecycle${RESET} — Session lifecycle management for Claude Code\n"
  424. printf "\nInstall modes:\n"
  425. printf " (no args) Install as skill to ~/.claude/skills/start/\n"
  426. printf " --plugin Install as plugin to ~/.claude/plugins/\n"
  427. printf "\nOptions:\n"
  428. printf " --version v1|v2 Install specific version (skill mode only)\n"
  429. printf " --revert Revert from v2 to v1 (skill mode only)\n"
  430. printf " --update Pull latest and reinstall\n"
  431. printf " --check-update Check for newer release\n"
  432. printf " --all Install all bundled skills without prompting\n"
  433. printf " --no-extras Skip bundled extra skills (only install /start)\n"
  434. printf " -v Print version\n"
  435. printf " --help Show help\n"
  436. printf "\nExamples:\n"
  437. printf " # One-liner install (skill mode)\n"
  438. printf " curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash\n"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 491 on GitHub
  439. printf "\n # One-liner install (plugin mode)\n"
  440. printf " curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash -s -- --plugin\n"
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 493 on GitHub
  441. printf "\n # Update existing installation\n"
  442. printf " curl -fsSL https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/install.sh | bash -s -- --update\n" ;;
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 495 on GitHub
  443. "")
  444. if [[ "${install_mode}" == "plugin" ]]; then
  445. install_plugin
  446. else
  447. install_skill "v2" "${extras_mode}"
  448. fi
  449. check_update ;;
  450. --version)
  451. target_version="${args[1]:-v2}"
  452. if [[ "${target_version}" != "v1" ]] && [[ "${target_version}" != "v2" ]]; then
  453. die "Invalid version: ${target_version}. Use v1 or v2."
  454. fi
  455. install_skill "${target_version}" "${extras_mode}"
  456. check_update ;;
  457. *)
  458. die "Unknown argument: ${args[0]} (try --help)" ;;
  459. esac
  460. }
  461. main "$@"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.