OpenSkillIndex← back to search
claude-code

Atlas-session-lifecycle start

Session initialization and lifecycle management: bootstraps session context, organizes files, generates CLAUDE.md, manages soul purpose lifecycle with completion protocol and active context harvesting. Use when user says /start, /init, bootstrap session, initialize session, or organize project.

install
source · Clone the upstream repo
git clone https://github.com/anombyte93/atlas-session-lifecycle
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/anombyte93/atlas-session-lifecycle "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/start" ~/.claude/skills/anombyte93-atlas-session-lifecycle-start && rm -rf "$T"
manifest: skills/start/SKILL.md
source content

Session Init & Lifecycle Skill

User runs 

/start
. Questions upfront. Everything else silent. Then seamlessly continue working.

All session operations use 

atlas-session
MCP tools directly (prefixed 
session_*
and 
contract_*
). Use 
ToolSearch
to discover them.

Directive Capture

Capture any text after 

/start
as 
DIRECTIVE
. If empty, the soul purpose is the directive. The skill NEVER finishes with "ready to go" and stops. After setup, immediately begin working.

UX Contract (MANDATORY)

  1. NEVER announce step names — no "Init Step 1", no "Wave 2"
  2. NEVER narrate internal process — no "Detecting environment..."
  3. NEVER explain what you're about to do — just ask questions, then do it silently
  4. User sees ONLY: questions and seamless continuation into work
  5. Batch questions — as few rounds as possible
  6. No "done" message that stops — after setup, immediately begin working

Hard Invariants

  1. User authority is absolute — AI NEVER closes a soul purpose. Only suggests; user decides.
  2. Zero unsolicited behavior — Skill ONLY runs when user types 
    /start
    .
  3. Human-visible memory only — All state lives in files.
  4. Idempotent — Safe to run multiple times.
  5. Templates are immutable — NEVER edit bundled template files.
  6. NEVER auto-invoke doubt agent. Only offer it.
  7. Trust separation — for bounty verify, spawn a separate finality Task agent. Never the same agent that submits.
  8. AtlasCoin is optional — if the service is down, tell the user and continue without bounty tracking.

Service Availability (MANDATORY)

  1. NEVER run 
    claude mcp list
     — assume atlas-session is available, handle errors on first call
  2. NEVER block on external services — log the gap and continue with degraded mode
  3. Fallback hierarchy: try tool → if error/timeout → tell user what's degraded → continue
ServiceIf UnavailableAction
atlas-session MCP
session_start
errors/times out		STOP — required for /start
AtlasCoin
contract_health()
fails		Continue without bounty tracking
PerplexityResearch queries failContext7 + WebSearch fallback
Context7Doc queries failPerplexity results only
BitwardenVault locked/unavailableTell user, skip credential fetch

INIT MODE

Triggered when 

session_start
returns 
preflight.mode == "init"
.

Step 1: Preflight + Assessment (composite)

MCP AVAILABILITY — assume atlas-session is available (do NOT run 

claude mcp list
):

  1. Call 
    session_start(project_dir, DIRECTIVE)
    — returns combined preflight + validate + read_context + git_summary + classify_brainstorm + clutter check in ONE call.
  2. If the call errors or times out, STOP and inform user: 
    atlas-session MCP is not responding. /start requires this MCP to function.

To fix:
1. Check ~/.claude.json or project .mcp.json has atlas-session entry
2. Verify Python module: python3 -c "from atlas_session import server"
3. Restart Claude Code after fixing
    Do NOT proceed with any other steps if session_start fails.
  3. Extract results: 
    preflight = result["preflight"]
    , 
    read_context = result["read_context"]
    , 
    git_summary = result["git_summary"]
    , 
    classify_brainstorm = result["classify_brainstorm"]
    , 
    clutter = result["clutter"]
    .

Step 2: Brainstorm Weight + File Organization

  1. Extract 
    BRAINSTORM_WEIGHT
    from 
    result["classify_brainstorm"]["weight"]
    for Step 4.

File organization (only if 

result["clutter"]
is present and 
status
is "cluttered"):

Present the grouped move map from 

result["clutter"]
:

  • "Your project root has [N] misplaced files. Proposed cleanup: [summary]. Approve?"
  • Options: "Yes, clean up", "Show details first", "Skip"
  • If approved, execute moves via 
    git mv
    (if 
    is_git
    ) or file operations.

Step 3: Silent Bootstrap + CI/CD Detection

  1. Call 
    session_init(project_dir, DIRECTIVE_OR_PENDING)
  2. Call 
    session_ensure_governance(project_dir)
  3. Call 
    session_cache_governance(project_dir)
  4. Run 
    /init
    (Claude Code built-in — refreshes CLAUDE.md. Must run in main thread.)
  5. Call 
    session_restore_governance(project_dir)

CI/CD Scaffold Detection (smart, zero-friction):

Use 

project_signals
from 
result["preflight"]
(already available from Step 1).

Determine CI/CD action based on these rules:

ConditionAction
has_ci == true
Skip — already has CI/CD
has_code_files == false
OR 
is_empty_project == true
Skip — no code to test
Simple script only (1-2 
.py
/
.sh
files, no package manifest)		Skip — toy project
Has package manifest (
package.json
, 
pyproject.toml
, 
Cargo.toml
, 
go.mod
)		Prompt user (see below)
3+ code files but no package manifestPrompt user (see below)

Prompt when needed:

"This project has code files but no CI/CD. Atlas-Copilot can scaffold GitHub Actions workflows (CI tests + Claude review). Enable?"

Options:

  • "Yes, full CI" — scaffold both CI and review workflows
  • "CI only" — scaffold CI workflow only
  • "Skip" — don't scaffold, don't ask again this session

Scaffold logic (if user accepts):

Detect language/stack from 

project_signals
:

  • has_package_json
    → Node.js
  • has_pyproject
    → Python
  • has_go_mod
    → Go
  • has_cargo_toml
    → Rust
  • Default → Python if 
    .py
    files exist, else generic

Create 

.github/workflows/
directory, then:

  1. CI workflow (
    ci.yml
    ): calls 
    anombyte93/atlas-copilot/.github/workflows/reusable-ci.yml@v1
    with appropriate inputs
  2. Review workflow (
    claude-review.yml
    ): calls 
    anombyte93/atlas-copilot/.github/workflows/reusable-claude-review.yml@v1

Use language-specific defaults:

Stacktest-commandbuild-commandinstall-command
Node.js
npm test -- --coverage --ci
npm run build
npm ci
Python
pytest tests/ -x --tb=short
(empty)
pip install -e ".[dev]"
Go
go test ./... -v -race
(empty)
go mod download
Rust
cargo test --verbose
cargo build --verbose
(empty)
  1. Read 
    custom.md
    if it exists, follow instructions under "During Init".

Step 4: Quick Clarify + Activate + Continuation

Quick Clarify runs first (always):

Invoke 

skill: "quick-clarify"
with the DIRECTIVE. This asks 3 questions: deliverable type, done criteria, and size. For Medium/Large tasks, it also runs research.

After brainstorm completes:

  1. Call 
    session_activate(project_dir, DERIVED_SOUL_PURPOSE, DIRECTIVE_OR_PENDING)
    — sets soul purpose, enables stop hook, and returns feature claims in ONE call.
  2. Extract feature claims from the result for tracking.

Bounty creation (optional):

Call 

contract_health()
. If healthy, call 
contract_create(project_dir, DERIVED_SOUL_PURPOSE, escrow, criteria)
using 
contract_draft_criteria
for suggestions.

Default escrow: 100. Increase for complex soul purposes at AI's discretion.

If AtlasCoin is down, tell user and continue without bounty.

Before Starting Work (MANDATORY)

  1. Count independent tasks in the soul purpose.
  2. If 2+ independent tasks: 
    • TeamCreate("{project}-work")
      — assign directory-level file ownership per teammate
    • Lead coordinates via SendMessage — does NOT implement
    • On completion: 
      SendMessage(type: "shutdown_request")
      then 
      TeamDelete
  3. If single task: proceed without team.
  4. NEVER spawn ad-hoc background Task agents for implementation.
  5. Invoke 
    superpowers:test-driven-development
    if soul purpose involves code.
  6. Invoke 
    superpowers:writing-plans
    if soul purpose has 3+ steps.

Auto-Invocation of Soul Loop (MANDATORY for code tasks)

Detect if Soul Loop should be enabled:

  1. Check if soul purpose involves code — Look for keywords: "implement", "build", "fix", "add", "create", "refactor", "update", "write"

  2. Determine intensity from task size (from quick-clarify):

    • Small → 
      --intensity small
    • Medium → 
      --intensity medium
    • Large → 
      --intensity long

  3. Configure gates from project structure:

    GATES="research,deterministic"

# Add E2E gate if tests/e2e/ exists
if [[ -d "$PROJECT_DIR/tests/e2e" ]]; then
  GATES="$GATES,e2e"
fi

# Add Acceptance gate if config/trello-testing.json exists
if [[ -f "$PROJECT_DIR/config/trello-testing.json" ]]; then
  GATES="$GATES,acceptance"
fi

  4. Invoke Soul Loop:

    /soul-loop "$DERIVED_SOUL_PURPOSE" --intensity $INTENSITY --gates "$GATES"

This is automatic — do not ask the user. Soul Loop provides the backpressure guardrails for iterative development.

Ralph Loop Invocation (optional, for iterative work)

If iterative development is appropriate for the soul purpose, use 

/ralph-loop
:

/ralph-loop "DERIVED_SOUL_PURPOSE" --max-iterations N --completion-promise "TEXT"

The user controls iterations and completion promises.

CRITICAL: you must call the 

Skill
tool — not just mention it in text.

Soul Loop Invocation (backpressure-enforced iteration)

Soul Loop enforces hierarchical backpressure gates on each iteration. Use for iterative development that needs quality guardrails.

IntensityInvocation
Small
/soul-loop "SOUL_PURPOSE" --intensity small
Medium
/soul-loop "SOUL_PURPOSE" --intensity medium
LongFirst 
skill: "prd-taskmaster"
, then 
/soul-loop "SOUL_PURPOSE" --intensity long

Gate Hierarchy:

  • Critical (hard block): Max iterations, state corruption, 10+ failures
  • Quality (soft warning): Test failures, feature proof failures
  • Progressive (friction): 5+ failures warns, 10+ hard stops
  • Agentic (allow exit): Completion promise matched via 
    <promise>
    tag

To complete: Output 

<promise>YOUR_COMPLETION_PROMISE</promise>
when done.

CRITICAL: Soul loop enforces backpressure. Test failures allow continued iteration with warnings. After 10 failures, hard block.

RECONCILE MODE

Triggered when 

session_start
returns 
preflight.mode == "reconcile"
.

UX: Everything in Steps 1-2 is invisible to the user. First visible interaction is a question (Step 3) or seamless work continuation (Step 4).

Step 0: Sync Previous State

Before any assessment, save the current session state so context files reflect reality:

  1. Invoke 
    /sync
    — updates all session-context files and MEMORY.md with current progress.
  2. This is silent — no output shown to user.

Step 1: Silent Assessment + Context Reality Check (composite)

MCP AVAILABILITY — assume atlas-session is available (do NOT run 

claude mcp list
):

  1. Call 
    session_start(project_dir, DIRECTIVE)
    — returns combined assessment in one call.
  2. If the call errors or times out, STOP and inform user (same message as Init Mode). Do NOT proceed.
  3. Extract: 
    preflight
    , 
    validate
    , 
    read_context
    , 
    git_summary
    , 
    classify_brainstorm
    , 
    clutter
    from the result.
  4. Call 
    session_cache_governance(project_dir)
  5. Run 
    /init
    in main thread.
  6. Call 
    session_restore_governance(project_dir)
  7. Compare 
    read_context
    against 
    git_summary
    : if context is stale (commits exist that aren't reflected in active context), update 
    session-context/CLAUDE-activeContext.md
    with real progress.
  8. Check capability inventory: call 
    session_capability_inventory(project_dir)
    and check response.
    • If 
      cache_hit == True
      and 
      git_changed == False
      : inventory is current, skip extraction.
    • If 
      needs_generation == True
      : inventory requires generation. The MCP tool returns 
      inventory_path
      when ready.
  9. Read 
    CLAUDE-capability-inventory.md
    if it exists. Extract untested code, security claims, and feature claims with gaps.
  10. Check bounty: if 
    session-context/BOUNTY_ID.txt
    exists, call 
    contract_get_status(project_dir)
    .
  11. Read 
    custom.md
    if it exists, follow instructions under "During Reconcile".

Root Cleanup

If 

result["clutter"]
is present and 
status
is "cluttered", present move map to user (same flow as Init Step 2).

Step 2: Directive + Features + Self-Assessment

If DIRECTIVE is non-empty (3+ words) AND 

status_hint
is 
no_purpose
:

  • Call 
    session_archive(project_dir, "(pending)", DIRECTIVE)
    to set soul purpose
  • Skip Step 3, go to Step 4 with lightweight brainstorm

If DIRECTIVE is non-empty (3+ words) AND soul purpose exists:

  • Skip Step 3, go to Step 4 — work on directive (overrides for this session)

Otherwise (no directive):

  1. Call 
    session_features_read(project_dir)
    — check feature claim status.
  2. Using 
    read_context
    + 
    features_read
    + 
    git_summary
    , classify: 
    • clearly_incomplete
      : open tasks non-empty, active blockers, criteria not met
    • probably_complete
      : no open tasks, artifacts exist, criteria met
    • uncertain
      : mixed signals

Step 3: User Interaction (conditional)

If 

clearly_incomplete
: No questions. Skip to Step 4.

If 

probably_complete
or 
uncertain
: Ask ONE question: "Soul purpose: '[text]'. [1-2 sentence assessment]. [Bounty: active/none]. What would you like to do?"

  • Options: "Continue", "Verify first", "Close", "Redefine"
  • "Verify first": Invoke 
    superpowers:verification-before-completion
    , fold findings into re-presented question.
  • "Close": Run Settlement Flow below.
  • "Redefine": Ask for new purpose, then run Settlement Flow with new purpose.

Step 4: Continuation

Transition directly into work. No "session reconciled" message.

  • DIRECTIVE provided: Begin working on directive.
  • Soul purpose redefined: Begin working on new purpose.
  • clearly_incomplete
    : Pick up where last session left off using active context.
  • No active soul purpose: Ask user what to work on, set as new soul purpose via 
    session_archive
    .

Before Starting Work (MANDATORY)

  1. Count independent tasks in the soul purpose.
  2. If 2+ independent tasks: 
    • TeamCreate("{project}-work")
      — assign directory-level file ownership per teammate
    • Lead coordinates via SendMessage — does NOT implement
    • On completion: 
      SendMessage(type: "shutdown_request")
      then 
      TeamDelete
  3. If single task: proceed without team.
  4. NEVER spawn ad-hoc background Task agents for implementation.
  5. Invoke 
    superpowers:test-driven-development
    if soul purpose involves code.
  6. Invoke 
    superpowers:writing-plans
    if soul purpose has 3+ steps.

Ralph Loop Check (Reconcile)

Check if a Ralph Loop is already active:

test -f ~/.claude/ralph-loop.local.md && echo "active" || echo "inactive"

Note: Ralph Loop is no longer auto-invoked. User can manually start it with 

/ralph-loop
if needed for iterative work.

SETTLEMENT FLOW

Triggered when user chooses "Close" in Reconcile Step 3.

Read 

custom.md
if it exists, follow instructions under "During Settlement".

Step 1: Harvest + Promote + Feature Verification (composite)

  1. Call 
    session_close(project_dir)
    — returns combined harvest + features_read + hook_deactivate in ONE call.
  2. Extract 
    harvest = result["harvest"]
    , 
    features = result["features"]
    , 
    hook = result["hook"]
    .
  3. If promotable content exists in 
    harvest
    , assess what to promote (decisions need rationale, patterns must be reusable, troubleshooting must have verified solutions). Present to user for approval.
  4. After approval, append promoted content to target files via Edit tool.
  5. If pending features exist in 
    features
    , run their proofs (shell commands, file checks).
  6. Update feature status in 
    CLAUDE-features.md
    .

Step 2: Code Review Gate

  1. Invoke 
    superpowers:verification-before-completion
    — run doubt review on recent changes.
  2. If critical issues found, present to user: "Fix issues first" / "Close anyway" / "Continue working".
  3. Invoke 
    superpowers:requesting-code-review
    before PR creation.

Step 3: PR Creation

  1. Push current branch: 
    git push -u origin HEAD
  2. Create PR: 
    gh pr create --title "..." --body "..."
    with review summary.
  3. Return PR URL to user.

Step 4: Bounty Settlement (if bounty exists)

  1. Call 
    contract_run_tests(project_dir)
    — execute all criteria.
  2. If tests pass, call 
    contract_submit(project_dir)
    .
  3. Spawn a single finality Task agent: 
    Task(subagent_type: "general-purpose", prompt: "You are finality-agent. Verify bounty [ID] independently. Call contract_verify. Report pass/fail.")
  4. Wait for finality result.
  5. If verified: call 
    contract_settle(project_dir)
    . Tell user tokens earned.
  6. If failed: present to user — "Fix and re-verify" / "Close anyway (forfeit)" / "Continue working".

Step 5: Archive + Cleanup

  1. Call 
    session_archive(project_dir, OLD_PURPOSE, NEW_PURPOSE)
    — archive soul purpose, reset active context.
  2. Remove Ralph Loop indicator: 
    rm -f ~/.claude/ralph-loop.local.md
  3. Tell user: "Session closed. Soul purpose '[text]' archived." (Include token info if bounty settled.)

Customizations

Create or edit 

custom.md
in the plugin root directory.

The AI reads 

custom.md
at each lifecycle phase:

  • During Init: After session-context is bootstrapped (Step 3)
  • During Reconcile: After read-context, before assessment (Step 1)
  • During Settlement: Before harvest + archive (Settlement Step 1)
  • Always: Applied in all modes