/start

name: start
description: "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."
user-invocable: true

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 `a