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.

1. 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) |

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:
3. TeamCreate("{project}-work") — assign directory-level file ownership per teammate
4. Lead coordinates via SendMessage — does NOT implement
5. On completion: SendMessage(type: "shutdown_request") then TeamDelete
6. If single task: proceed without team.
7. NEVER spawn ad-hoc background Task agents for implementation.
8. Invoke superpowers:test-driven-development if soul purpose involves code.
9. 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):
3. Small → `--i