start

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

Service	If Unavailable	Action
atlas-session MCP	session_start errors/times out	STOP — required for /start
AtlasCoin	contract_health() fails	Continue without bounty tracking
Perplexity	Research queries fail	Context7 + WebSearch fallback
Context7	Doc queries fail	Perplexity results only
Bitwarden	Vault locked/unavailable	Tell 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:

Condition	Action
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 manifest	Prompt 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:

Stack	test-command	build-command	install-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)

6. 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.

Intensity	Invocation
Small	/soul-loop "SOUL_PURPOSE" --intensity small
Medium	/soul-loop "SOUL_PURPOSE" --intensity medium
Long	First 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