@anthropologies/claudestory 0.1.41 → 0.1.43

package/dist/mcp.js

@@ -4096,7 +4096,7 @@ var init_session = __esm({
 // src/mcp/index.ts
 init_esm_shims();
 import { realpathSync as realpathSync2, existsSync as existsSync11 } from "fs";
-import { resolve as resolve8, join as join18, isAbsolute } from "path";
+import { resolve as resolve8, join as join19, isAbsolute } from "path";
 import { z as z11 } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -4149,7 +4149,7 @@ init_errors();
 init_helpers();
 init_types();
 import { z as z10 } from "zod";
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 
 // src/cli/commands/status.ts
 init_esm_shims();
@@ -5443,8 +5443,8 @@ init_handover();
 init_esm_shims();
 init_session_types();
 init_session();
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync3, readdirSync as readdirSync4 } from "fs";
-import { join as join13 } from "path";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync3, readdirSync as readdirSync4 } from "fs";
+import { join as join14 } from "path";
 
 // src/autonomous/state-machine.ts
 init_esm_shims();
@@ -7783,6 +7783,43 @@ init_project_loader();
 init_snapshot();
 init_snapshot();
 init_queries();
+
+// src/autonomous/version-check.ts
+init_esm_shims();
+import { readFileSync as readFileSync6 } from "fs";
+import { join as join13, dirname as dirname4 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+function checkVersionMismatch(runningVersion, installedVersion) {
+  if (!installedVersion) return null;
+  if (runningVersion === "0.0.0-dev") return null;
+  if (runningVersion === installedVersion) return null;
+  return `claudestory MCP server is running v${runningVersion} but v${installedVersion} is installed. Restart Claude Code to load the updated version.`;
+}
+function getInstalledVersion() {
+  try {
+    const thisFile = fileURLToPath3(import.meta.url);
+    const candidates = [
+      join13(dirname4(thisFile), "..", "..", "package.json"),
+      join13(dirname4(thisFile), "..", "package.json")
+    ];
+    for (const candidate of candidates) {
+      try {
+        const raw = readFileSync6(candidate, "utf-8");
+        const pkg = JSON.parse(raw);
+        if (pkg.version) return pkg.version;
+      } catch {
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getRunningVersion() {
+  return "0.1.43";
+}
+
+// src/autonomous/guide.ts
 init_handover();
 var RECOVERY_MAPPING = {
   PICK_TICKET: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
@@ -7804,18 +7841,18 @@ var RECOVERY_MAPPING = {
 function buildGuideRecommendOptions(root) {
   const opts = {};
   try {
-    const handoversDir = join13(root, ".story", "handovers");
+    const handoversDir = join14(root, ".story", "handovers");
     const files = readdirSync4(handoversDir, "utf-8").filter((f) => f.endsWith(".md")).sort();
     if (files.length > 0) {
-      opts.latestHandoverContent = readFileSync6(join13(handoversDir, files[files.length - 1]), "utf-8");
+      opts.latestHandoverContent = readFileSync7(join14(handoversDir, files[files.length - 1]), "utf-8");
     }
   } catch {
   }
   try {
-    const snapshotsDir = join13(root, ".story", "snapshots");
+    const snapshotsDir = join14(root, ".story", "snapshots");
     const snapFiles = readdirSync4(snapshotsDir, "utf-8").filter((f) => f.endsWith(".json")).sort();
     if (snapFiles.length > 0) {
-      const raw = readFileSync6(join13(snapshotsDir, snapFiles[snapFiles.length - 1]), "utf-8");
+      const raw = readFileSync7(join14(snapshotsDir, snapFiles[snapFiles.length - 1]), "utf-8");
       const snap = JSON.parse(raw);
       if (snap.issues) {
         opts.previousOpenIssueCount = snap.issues.filter((i) => i.status !== "resolved").length;
@@ -8008,6 +8045,7 @@ async function handleStart(root, args) {
   for (const stale of staleSessions) {
     writeSessionSync(stale.dir, { ...stale.state, status: "superseded" });
   }
+  const versionWarning = checkVersionMismatch(getRunningVersion(), getInstalledVersion());
   const wsId = deriveWorkspaceId(root);
   const mode = args.mode ?? "auto";
   if (mode !== "auto" && !args.ticketId) {
@@ -8202,7 +8240,7 @@ Staged: ${stagedResult.data.join(", ")}`
       }
     }
     const { state: projectState, warnings } = await loadProject(root);
-    const handoversDir = join13(root, ".story", "handovers");
+    const handoversDir = join14(root, ".story", "handovers");
     const ctx = { state: projectState, warnings, root, handoversDir, format: "md" };
     let handoverText = "";
     try {
@@ -8219,7 +8257,7 @@ Staged: ${stagedResult.data.join(", ")}`
       }
     } catch {
     }
-    const rulesText = readFileSafe2(join13(root, "RULES.md"));
+    const rulesText = readFileSafe2(join14(root, "RULES.md"));
     const lessonDigest = buildLessonDigest(projectState.lessons);
     const digestParts = [
       handoverText ? `## Recent Handovers
@@ -8235,7 +8273,7 @@ ${rulesText}` : "",
     ].filter(Boolean);
     const digest = digestParts.join("\n\n---\n\n");
     try {
-      writeFileSync3(join13(dir, "context-digest.md"), digest, "utf-8");
+      writeFileSync3(join14(dir, "context-digest.md"), digest, "utf-8");
     } catch {
     }
     if (mode !== "auto" && args.ticketId) {
@@ -8427,7 +8465,8 @@ ${ticket.description}` : "",
         "Do NOT use Claude Code's plan mode \u2014 write plans as markdown files.",
         "Do NOT ask the user for confirmation or approval.",
         "Do NOT stop or summarize between tickets \u2014 call autonomous_guide IMMEDIATELY.",
-        "You are in autonomous mode \u2014 continue working until done."
+        "You are in autonomous mode \u2014 continue working until done.",
+        ...versionWarning ? [`**Warning:** ${versionWarning}`] : []
       ],
       transitionedFrom: "INIT"
     });
@@ -8954,7 +8993,7 @@ function guideError(err) {
 }
 function readFileSafe2(path2) {
   try {
-    return readFileSync6(path2, "utf-8");
+    return readFileSync7(path2, "utf-8");
   } catch {
     return "";
   }
@@ -8964,8 +9003,8 @@ function readFileSafe2(path2) {
 init_esm_shims();
 init_session();
 init_session_types();
-import { readFileSync as readFileSync7, existsSync as existsSync10 } from "fs";
-import { join as join14 } from "path";
+import { readFileSync as readFileSync8, existsSync as existsSync10 } from "fs";
+import { join as join15 } from "path";
 
 // src/core/session-report-formatter.ts
 init_esm_shims();
@@ -9179,7 +9218,7 @@ async function handleSessionReport(sessionId, root, format = "md") {
       isError: true
     };
   }
-  const statePath2 = join14(dir, "state.json");
+  const statePath2 = join15(dir, "state.json");
   if (!existsSync10(statePath2)) {
     return {
       output: `Error: Session ${sessionId} corrupt \u2014 state.json missing.`,
@@ -9189,7 +9228,7 @@ async function handleSessionReport(sessionId, root, format = "md") {
     };
   }
   try {
-    const rawJson = JSON.parse(readFileSync7(statePath2, "utf-8"));
+    const rawJson = JSON.parse(readFileSync8(statePath2, "utf-8"));
     if (rawJson && typeof rawJson === "object" && "schemaVersion" in rawJson && rawJson.schemaVersion !== CURRENT_SESSION_SCHEMA_VERSION) {
       return {
         output: `Error: Session ${sessionId} \u2014 unsupported session schema version ${rawJson.schemaVersion}.`,
@@ -9218,7 +9257,7 @@ async function handleSessionReport(sessionId, root, format = "md") {
   const events = readEvents(dir);
   let planContent = null;
   try {
-    planContent = readFileSync7(join14(dir, "plan.md"), "utf-8");
+    planContent = readFileSync8(join15(dir, "plan.md"), "utf-8");
   } catch {
   }
   let gitLog = null;
@@ -9243,7 +9282,7 @@ init_issue();
 init_roadmap();
 init_output_formatter();
 init_helpers();
-import { join as join15, resolve as resolve6 } from "path";
+import { join as join16, resolve as resolve6 } from "path";
 var PHASE_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 var PHASE_ID_MAX_LENGTH = 40;
 function validatePhaseId(id) {
@@ -9352,7 +9391,7 @@ function formatMcpError(code, message) {
 async function runMcpReadTool(pinnedRoot, handler) {
   try {
     const { state, warnings } = await loadProject(pinnedRoot);
-    const handoversDir = join16(pinnedRoot, ".story", "handovers");
+    const handoversDir = join17(pinnedRoot, ".story", "handovers");
     const ctx = { state, warnings, root: pinnedRoot, handoversDir, format: "md" };
     const result = await handler(ctx);
     if (result.errorCode && INFRASTRUCTURE_ERROR_CODES.includes(result.errorCode)) {
@@ -9910,10 +9949,10 @@ init_esm_shims();
 init_project_loader();
 init_errors();
 import { mkdir as mkdir4, stat as stat2, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
-import { join as join17, resolve as resolve7 } from "path";
+import { join as join18, resolve as resolve7 } from "path";
 async function initProject(root, options) {
   const absRoot = resolve7(root);
-  const wrapDir = join17(absRoot, ".story");
+  const wrapDir = join18(absRoot, ".story");
   let exists = false;
   try {
     const s = await stat2(wrapDir);
@@ -9933,11 +9972,11 @@ async function initProject(root, options) {
       ".story/ already exists. Use --force to overwrite config and roadmap."
     );
   }
-  await mkdir4(join17(wrapDir, "tickets"), { recursive: true });
-  await mkdir4(join17(wrapDir, "issues"), { recursive: true });
-  await mkdir4(join17(wrapDir, "handovers"), { recursive: true });
-  await mkdir4(join17(wrapDir, "notes"), { recursive: true });
-  await mkdir4(join17(wrapDir, "lessons"), { recursive: true });
+  await mkdir4(join18(wrapDir, "tickets"), { recursive: true });
+  await mkdir4(join18(wrapDir, "issues"), { recursive: true });
+  await mkdir4(join18(wrapDir, "handovers"), { recursive: true });
+  await mkdir4(join18(wrapDir, "notes"), { recursive: true });
+  await mkdir4(join18(wrapDir, "lessons"), { recursive: true });
   const created = [
     ".story/config.json",
     ".story/roadmap.json",
@@ -9977,7 +10016,7 @@ async function initProject(root, options) {
   };
   await writeConfig(config, absRoot);
   await writeRoadmap(roadmap, absRoot);
-  const gitignorePath = join17(wrapDir, ".gitignore");
+  const gitignorePath = join18(wrapDir, ".gitignore");
   await ensureGitignoreEntries(gitignorePath, STORY_GITIGNORE_ENTRIES);
   const warnings = [];
   if (options.force && exists) {
@@ -10016,7 +10055,7 @@ async function ensureGitignoreEntries(gitignorePath, entries) {
 // src/mcp/index.ts
 var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "0.1.41";
+var version = "0.1.43";
 function tryDiscoverRoot() {
   const envRoot = process.env[ENV_VAR2];
   if (envRoot) {
@@ -10028,7 +10067,7 @@ function tryDiscoverRoot() {
     const resolved = resolve8(envRoot);
     try {
       const canonical = realpathSync2(resolved);
-      if (existsSync11(join18(canonical, CONFIG_PATH2))) {
+      if (existsSync11(join19(canonical, CONFIG_PATH2))) {
         return canonical;
       }
       process.stderr.write(`Warning: No .story/config.json at ${canonical}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropologies/claudestory",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "license": "UNLICENSED",
   "description": "Cross-session context persistence for AI coding projects. Tracks tickets, issues, roadmap, and handovers so every session builds on the last.",
   "keywords": [

package/src/skill/SKILL.md

@@ -3,7 +3,7 @@ name: story
 description: Cross-session context persistence for AI coding projects. Load project context, manage sessions, guide setup.
 ---
 
-# /story — Project Context & Session Management
+# /story -- Project Context & Session Management
 
 claudestory tracks tickets, issues, roadmap, and handovers in a `.story/` directory so every AI coding session builds on the last instead of starting from zero.
 
@@ -11,16 +11,16 @@ claudestory tracks tickets, issues, roadmap, and handovers in a `.story/` direct
 
 `/story` is one smart command. Parse the user's intent from context:
 
-- `/story` → full context load (default, see Step 2 below)
-- `/story auto` → start autonomous mode (see Autonomous Mode below)
-- `/story review T-XXX` → start review mode for a ticket (see Tiered Access below)
-- `/story plan T-XXX` → start plan mode for a ticket (see Tiered Access below)
-- `/story guided T-XXX` → start guided mode for a ticket (see Tiered Access below)
-- `/story handover` → draft a session handover. Summarize the session's work, then call `claudestory_handover_create` with the drafted content and a descriptive slug
-- `/story snapshot` → save project state (call `claudestory_snapshot` MCP tool)
-- `/story export` → export project for sharing. Ask the user whether to export the current phase or the full project, then call `claudestory_export` with either `phase` or `all` set
-- `/story status` → quick status check (call `claudestory_status` MCP tool)
-- `/story help` → show all capabilities (read `~/.claude/skills/story/reference.md`)
+- `/story` -> full context load (default, see Step 2 below)
+- `/story auto` -> start autonomous mode (read `autonomous-mode.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
+- `/story review T-XXX` -> start review mode for a ticket (read `autonomous-mode.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
+- `/story plan T-XXX` -> start plan mode for a ticket (read `autonomous-mode.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
+- `/story guided T-XXX` -> start guided mode for a ticket (read `autonomous-mode.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
+- `/story handover` -> draft a session handover. Summarize the session's work, then call `claudestory_handover_create` with the drafted content and a descriptive slug
+- `/story snapshot` -> save project state (call `claudestory_snapshot` MCP tool)
+- `/story export` -> export project for sharing. Ask the user whether to export the current phase or the full project, then call `claudestory_export` with either `phase` or `all` set
+- `/story status` -> quick status check (call `claudestory_status` MCP tool)
+- `/story help` -> show all capabilities (read `reference.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
 
 If the user's intent doesn't match any of these, use the full context load.
 
@@ -28,13 +28,13 @@ If the user's intent doesn't match any of these, use the full context load.
 
 Check if the claudestory MCP tools are available by looking for `claudestory_status` in your available tools.
 
-**If MCP tools ARE available** → proceed to Step 1.
+**If MCP tools ARE available** -> proceed to Step 1.
 
 **If MCP tools are NOT available:**
 
 1. Check if the `claudestory` CLI is installed: run `claudestory --version` via Bash
 2. If NOT installed:
-   - Check `node --version` and `npm --version` — both must be available
+   - Check `node --version` and `npm --version` -- both must be available
    - If Node.js is missing, tell the user to install Node.js 20+ first
    - Otherwise, with user permission, run: `npm install -g @anthropologies/claudestory`
    - Then run: `claude mcp add claudestory -s user -- claudestory --mcp`
@@ -56,156 +56,28 @@ Check if the claudestory MCP tools are available by looking for `claudestory_sta
 
 ## Step 1: Check Project
 
-- If `.story/` exists in the current working directory (or a parent) → proceed to Step 2
-- If no `.story/` but project indicators exist (code, manifest, .git) → run the **AI-Assisted Setup Flow** below
-- If no `.story/` and no project indicators → explain what claudestory is and suggest navigating to a project
-
-### AI-Assisted Setup Flow
-
-This flow creates a meaningful `.story/` project instead of empty scaffolding. Claude analyzes the project, proposes structure, and creates everything via MCP tools.
-
-#### 1a. Detect Project Type
-
-Check for project indicators to determine if this is an **existing project** or a **new/empty project**:
-
-- `package.json` → npm/node (read `name`, `description`, check for `typescript` dep)
-- `Cargo.toml` → Rust
-- `go.mod` → Go
-- `pyproject.toml` / `requirements.txt` → Python
-- `*.xcodeproj` / `Package.swift` → Swift/macOS
-- `*.sln` / `*.csproj` → C#/.NET
-- `Gemfile` → Ruby
-- `build.gradle.kts` / `build.gradle` → Android/Kotlin/Java (or Spring Boot)
-- `pubspec.yaml` → Flutter/Dart
-- `angular.json` → Angular
-- `svelte.config.js` → SvelteKit
-- `.git/` → has version history
-
-If none found (empty or near-empty directory) → skip to **1c. New Project Interview**.
-
-#### 1b. Existing Project — Analyze
-
-Before diving into analysis, briefly introduce claudestory to the user:
-
-"Claude Story tracks your project's roadmap, tickets, issues, and session handovers in a `.story/` directory. Every Claude Code session starts by reading this context, so you never re-explain your project from scratch. Sessions build on each other: decisions, blockers, and lessons carry forward automatically. I'll analyze your project and propose a structure. You can adjust everything before I create anything."
-
-Keep it to 3-4 sentences. Not a sales pitch, just enough that the user knows what they're opting into and that they're in control.
-
-Read these files to understand the project (skip any that don't exist, skip files > 50KB):
-
-1. **README.md** — project description, goals, feature list, roadmap/TODO sections
-2. **Package manifest** — project name, dependencies, scripts
-3. **CLAUDE.md** — existing project spec (if any)
-4. **Top-level directory listing** — identify major components (src/, test/, docs/, etc.)
-5. **Git summary** — `git log --oneline -20` for recent work patterns
-6. **GitHub issues (ask user first)** — `gh issue list --limit 30 --state open --json number,title,labels,body,createdAt`. If gh fails (auth, rate limit, no remote), skip cleanly and note "GitHub import skipped: [reason]"
-
-**Framework-specific deep scan** — after detecting the project type in 1a, scan deeper into framework conventions to understand architecture:
-
-- **Next.js / Nuxt:** Check `app/` vs `pages/` routing, scan `app/api/` or `pages/api/` for API routes, read `next.config.*` / `nuxt.config.*`, check for middleware.
-- **Express / Fastify / Koa:** Scan for route files (`routes/`, `src/routes/`), look for `router.get/post` patterns, identify service/controller layers.
-- **NestJS:** Read `nest-cli.json`, scan `src/` for `*.module.ts`, check for controllers and services.
-- **React (CRA / Vite) / Vue / Svelte:** Check `src/components/` structure, look for state management imports (redux, zustand, pinia), identify routing setup.
-- **Angular:** Read `angular.json`, scan `src/app/` for modules and components, check for services and guards.
-- **Django / FastAPI / Flask:** Check for `manage.py`, scan for app directories or router files, look at models and migrations.
-- **Spring Boot:** Check `pom.xml` or `build.gradle` for Spring deps, scan `src/main/java` for controller/service/repository layers.
-- **Rust:** Check `Cargo.toml` for workspace members, scan for `mod.rs` / `lib.rs` structure, identify crate types.
-- **Swift / Xcode:** Check `.xcodeproj` or `Package.swift`, identify SwiftUI vs UIKit, scan for targets.
-- **Android (Kotlin/Java):** Check `build.gradle.kts`, scan `app/src/main/` for activity/fragment/composable structure, check `AndroidManifest.xml`, identify Compose vs XML layouts.
-- **Flutter / Dart:** Check `pubspec.yaml`, scan `lib/` for feature folders (models/, screens/, widgets/, services/), check for state management imports (provider, riverpod, bloc).
-- **Go:** Check `go.mod`, scan for `cmd/` and `internal/`/`pkg/`, check for `Makefile`.
-- **Monorepo:** If `packages/`, `apps/`, or workspace config detected, list each package with its purpose before proposing phases.
-- **Other:** Scan `src/` two levels deep and identify dominant patterns (MVC, service layers, feature folders).
-
-**Derive project metadata:**
-- **name**: from package manifest `name` field, or directory name
-- **type**: from package manager (npm, cargo, pip, etc.)
-- **language**: from file extensions and manifest
-
-**Assess project stage** from the data — don't use fixed thresholds. A project with 3 commits and a half-written README is greenfield. A project with 500+ commits, test suites, and release tags is mature. A project with 200 commits and active PRs is active development. Use your judgment.
-
-**Propose 3-7 phases** reflecting the project's actual development trajectory. Examples:
-- Library: setup → core-api → documentation → testing → publishing
-- App: mvp → auth → data-layer → ui-polish → deployment
-- Mid-development project: capture completed work as early phases, then plan forward
-
-**Propose initial tickets** per active phase (2-5 each), based on:
-- README TODOs or roadmap sections (treat as hints, not ground truth)
-- GitHub issues if imported — infer from label semantics: bug/defect labels → issues, enhancement/feature labels → tickets
-- Obvious gaps (missing tests, no CI, no docs, etc.)
-- If more than 30 GitHub issues exist, note "Showing 30 of N. Additional issues can be imported later."
-
-**Important:** Only mark phases complete if explicitly confirmed by user or docs — do NOT infer completion from git history alone.
-
-#### 1c. New Project — Interview
-
-Ask the user:
-1. "What are you building?" — project name and purpose
-2. "What's the tech stack?" — language, framework, project type
-3. "What are the major milestones?" — helps define phases
-4. "What's the first thing to build?" — seeds the first ticket
-
-Propose phases and initial tickets from the answers.
-
-#### 1d. Present Proposal
-
-Show the user a structured proposal (table format, not raw JSON):
-- **Project:** name, type, language
-- **Phases** (table: id, name, description)
-- **Tickets per phase** (title, type, status)
-- **Issues** (if GitHub import was used)
-
-Before asking for approval, briefly explain what they're looking at:
-
-"**How this works:** Phases are milestones in your project's development. They track progress from setup to shipping. Tickets are specific work items within each phase. After setup, typing `/story` at the start of any Claude Code session loads this context automatically. Claude will know your project's state, what was done last session, and what to work on next."
-
-Then ask for approval with clear interaction guidance:
-
-"Does this look right? You can:
-- Adjust any phase (rename, reorder, add, remove)
-- Change tickets (add, remove, rephrase, move between phases)
-- Mark phases as complete or in-progress
-- Split or merge phases
-
-I'll iterate until you're happy, then create everything."
-
-#### 1e. Execute on Approval
-
-1. Call `claudestory_init` with name, type, language — after this, all MCP tools become available dynamically
-2. Call `claudestory_phase_create` for each phase — first phase with `atStart: true`, subsequent with `after: <previous-phase-id>`
-3. Call `claudestory_ticket_create` for each ticket
-4. Call `claudestory_issue_create` for each imported GitHub issue
-5. Call `claudestory_ticket_update` to mark already-complete tickets as `complete`
-6. Call `claudestory_snapshot` to save initial baseline
-
-#### 1f. Post-Setup
-
-After creation completes:
-- Confirm what was created (e.g., "Created 5 phases, 12 tickets, and 3 issues")
-- Check if `.gitignore` includes `.story/snapshots/` (warn if missing — snapshots should not be committed)
-- Suggest creating `CLAUDE.md` if it doesn't exist (project spec for AI sessions)
-- Suggest creating `RULES.md` if it doesn't exist (development constraints)
-- Write an initial handover documenting the setup decisions
-- Proceed to Step 2 (Load Context) to show the new project state
+- If `.story/` exists in the current working directory (or a parent) -> proceed to Step 2
+- If no `.story/` but project indicators exist (code, manifest, .git) -> read `setup-flow.md` in the same directory as this skill file and follow the AI-Assisted Setup Flow (if not found, tell user to run `claudestory setup-skill`)
+- If no `.story/` and no project indicators -> explain what claudestory is and suggest navigating to a project
 
 ## Step 2: Load Context (Default /story Behavior)
 
 Call these in order:
 
-1. **Project status** — call `claudestory_status` MCP tool
-2. **Session recap** — call `claudestory_recap` MCP tool (shows changes since last snapshot)
-3. **Recent handovers** — call `claudestory_handover_latest` MCP tool with `count: 3` (last 3 sessions' context — ensures reasoning behind recent decisions is preserved, not just the latest session's state)
-4. **Development rules** — read `RULES.md` if it exists in the project root
-5. **Lessons learned** — call `claudestory_lesson_digest` MCP tool
-6. **Recent commits** — run `git log --oneline -10`
+1. **Project status** -- call `claudestory_status` MCP tool
+2. **Session recap** -- call `claudestory_recap` MCP tool (shows changes since last snapshot)
+3. **Recent handovers** -- call `claudestory_handover_latest` MCP tool with `count: 3` (last 3 sessions' context -- ensures reasoning behind recent decisions is preserved, not just the latest session's state)
+4. **Development rules** -- read `RULES.md` if it exists in the project root
+5. **Lessons learned** -- call `claudestory_lesson_digest` MCP tool
+6. **Recent commits** -- run `git log --oneline -10`
 
 ## Step 2b: Empty Scaffold Check
 
 After `claudestory_status` returns, check in order:
 
-1. **Integrity guard** — if the response starts with "Warning:" and contains "item(s) skipped due to data integrity issues", this is NOT an empty scaffold. Tell the user to run `claudestory validate`. Continue Step 2/3 normally.
-2. **Scaffold detection** — check BOTH: output contains "## Getting Started" AND shows `Tickets: 0/0 complete` + `Handovers: 0`. If met AND the project has code indicators (git history, package manifest, source files), route to the AI-Assisted Setup Flow (section 1b above) instead of Step 3. Skip remaining Step 2 calls and Step 3.
-3. **Empty without code** — if scaffold detected but no code indicators (truly empty directory), continue to Step 3 which will show: "Your project is set up but has no tickets yet. Would you like me to help you create your first phase and tickets?"
+1. **Integrity guard** -- if the response starts with "Warning:" and contains "item(s) skipped due to data integrity issues", this is NOT an empty scaffold. Tell the user to run `claudestory validate`. Continue Step 2/3 normally.
+2. **Scaffold detection** -- check BOTH: output contains "## Getting Started" AND shows `Tickets: 0/0 complete` + `Handovers: 0`. If met AND the project has code indicators (git history, package manifest, source files), read `setup-flow.md` in the same directory as this skill file and follow the AI-Assisted Setup Flow (section 1b). After setup completes, restart Step 2 from the top (the project now has data to load).
+3. **Empty without code** -- if scaffold detected but no code indicators (truly empty directory), continue to Step 3 which will show: "Your project is set up but has no tickets yet. Would you like me to help you create your first phase and tickets?"
 
 ## Step 3: Present Summary
 
@@ -226,9 +98,9 @@ Then ask: **"What would you like to work on?"**
 
 - **Snapshots** save project state for diffing. They may be auto-taken before context compaction.
 - **Handovers** are session continuity documents. Create one at the end of significant sessions.
-- **Recaps** show what changed since the last snapshot — useful for understanding drift.
+- **Recaps** show what changed since the last snapshot -- useful for understanding drift.
 
-**Never modify or overwrite existing handover files.** Handovers are append-only historical records. Always create new handover files — never edit, replace, or write to an existing one. If you need to correct something from a previous session, create a new handover that references the correction. This prevents accidental data loss during sessions.
+**Never modify or overwrite existing handover files.** Handovers are append-only historical records. Always create new handover files -- never edit, replace, or write to an existing one. If you need to correct something from a previous session, create a new handover that references the correction. This prevents accidental data loss during sessions.
 
 Before writing a handover at the end of a session, run `claudestory snapshot` first. This ensures the next session's recap can show what changed. If `setup-skill` has been run, a PreCompact hook auto-takes snapshots before context compaction.
 
@@ -238,20 +110,20 @@ Before writing a handover at the end of a session, run `claudestory snapshot` fi
 - Tool/framework quirks discovered during implementation
 - Process improvements (review workflows, testing strategies)
 
-Don't duplicate what's already in the handover — lessons are structured, tagged, and ranked. Handovers are narrative. Use `claudestory_lesson_digest` to check existing lessons before creating duplicates. Use `claudestory_lesson_reinforce` when an existing lesson proves true again.
+Don't duplicate what's already in the handover -- lessons are structured, tagged, and ranked. Handovers are narrative. Use `claudestory_lesson_digest` to check existing lessons before creating duplicates. Use `claudestory_lesson_reinforce` when an existing lesson proves true again.
 
 ## Ticket and Issue Discipline
 
-**Tickets** are planned work — features, tasks, refactors. They represent intentional, scoped commitments.
+**Tickets** are planned work -- features, tasks, refactors. They represent intentional, scoped commitments.
 
 **Ticket types:**
-- `task` — Implementation work: building features, writing code, fixing bugs, refactoring.
-- `feature` — A user-facing capability or significant new functionality. Larger scope than a task.
-- `chore` — Maintenance, publishing, documentation, cleanup. No functional change to the product.
+- `task` -- Implementation work: building features, writing code, fixing bugs, refactoring.
+- `feature` -- A user-facing capability or significant new functionality. Larger scope than a task.
+- `chore` -- Maintenance, publishing, documentation, cleanup. No functional change to the product.
 
-**Issues** are discovered problems — bugs, inconsistencies, gaps, risks found during work. If you're not sure whether something is a ticket or an issue, make it an issue. It can be promoted to a ticket later.
+**Issues** are discovered problems -- bugs, inconsistencies, gaps, risks found during work. If you're not sure whether something is a ticket or an issue, make it an issue. It can be promoted to a ticket later.
 
-When working on a task and you encounter a bug, inconsistency, or improvement opportunity that is out of scope for the current ticket, create an issue using `claudestory issue create` (CLI) with a clear title, severity, and impact description. Don't fix it in the current task, don't ignore it — log it. This keeps the issue tracker growing organically and ensures nothing discovered during work is lost.
+When working on a task and you encounter a bug, inconsistency, or improvement opportunity that is out of scope for the current ticket, create an issue using `claudestory issue create` (CLI) with a clear title, severity, and impact description. Don't fix it in the current task, don't ignore it -- log it. This keeps the issue tracker growing organically and ensures nothing discovered during work is lost.
 
 When starting work on a ticket, update its status to `inprogress`. When done, update to `complete` in the same commit as the code change.
 
@@ -274,7 +146,7 @@ Read operations (list, get, next, blocked) are available via both CLI and MCP.
 
 ## Notes
 
-**Notes** are unstructured brainstorming artifacts — ideas, design thinking, "what if" explorations. Use notes when the content doesn't fit tickets (planned work) or issues (discovered problems).
+**Notes** are unstructured brainstorming artifacts -- ideas, design thinking, "what if" explorations. Use notes when the content doesn't fit tickets (planned work) or issues (discovered problems).
 
 Create notes via CLI: `claudestory note create --content "..." --tags idea`
 
@@ -282,68 +154,10 @@ Create notes via MCP: `claudestory_note_create` with `content`, optional `title`
 
 List, get, and update notes via MCP: `claudestory_note_list`, `claudestory_note_get`, `claudestory_note_update`. Delete remains CLI-only: `claudestory note delete <id>`.
 
-## Autonomous Mode
-
-`/story auto` starts an autonomous coding session. The guide picks tickets, plans, reviews, implements, and commits — looping until all tickets are done or the session limit is reached.
-
-**How it works:**
-
-1. Call `claudestory_autonomous_guide` with `{ "sessionId": null, "action": "start" }`
-2. The guide returns an instruction with ticket candidates and exact JSON for the next call
-3. Follow every instruction exactly. Call the guide back after each step.
-4. The guide advances through: PICK_TICKET → PLAN → PLAN_REVIEW → IMPLEMENT → CODE_REVIEW → FINALIZE → COMPLETE → loop
-5. Continue until the guide returns SESSION_END
-
-**Critical rules for autonomous mode:**
-- Do NOT use Claude Code's plan mode — write plans as markdown files
-- Do NOT ask the user for confirmation or approval
-- Do NOT stop or summarize between tickets — call the guide IMMEDIATELY
-- Follow the guide's instructions exactly — it specifies which tools to call, what parameters to use
-- After each step completes, call `claudestory_autonomous_guide` with `action: "report"` and the results
-
-**If the guide says to compact:** Call `claudestory_autonomous_guide` with `action: "pre_compact"`, then run `/compact`, then call with `action: "resume"`.
-
-**If something goes wrong:** Call `claudestory_autonomous_guide` with `action: "cancel"` to cleanly end the session.
-
-## Tiered Access — Review, Plan, Guided Modes
-
-The autonomous guide supports four execution tiers. Same guide, same handlers, different entry/exit points.
-
-### `/story review T-XXX`
-
-"I wrote code for T-XXX, review it." Enters at CODE_REVIEW, loops review rounds, exits on approval.
-
-1. Call `claudestory_autonomous_guide` with `{ "sessionId": null, "action": "start", "mode": "review", "ticketId": "T-XXX" }`
-2. The guide enters CODE_REVIEW — follow its diff capture and review instructions
-3. On approve: session ends automatically. On revise/reject: fix code, re-review
-4. After approval, you can proceed to commit — the guide does NOT auto-commit in review mode
-
-**Note:** Review mode relaxes git constraints — dirty working tree is allowed since the user has code ready for review.
-
-### `/story plan T-XXX`
-
-"Help me plan T-XXX." Enters at PLAN, runs PLAN_REVIEW rounds, exits on approval.
-
-1. Call `claudestory_autonomous_guide` with `{ "sessionId": null, "action": "start", "mode": "plan", "ticketId": "T-XXX" }`
-2. The guide enters PLAN — write the implementation plan as a markdown file
-3. On plan review approve: session ends automatically. On revise/reject: revise plan, re-review
-4. The approved plan is saved in `.story/sessions/<id>/plan.md`
-
-### `/story guided T-XXX`
-
-"Do T-XXX end to end with review." Full pipeline for a single ticket: PLAN → PLAN_REVIEW → IMPLEMENT → CODE_REVIEW → FINALIZE → COMPLETE → HANDOVER → SESSION_END.
-
-1. Call `claudestory_autonomous_guide` with `{ "sessionId": null, "action": "start", "mode": "guided", "ticketId": "T-XXX" }`
-2. Follow every instruction exactly, calling the guide back after each step
-3. Session ends automatically after the single ticket is complete
-
-**Guided vs Auto:** Guided mode forces `maxTicketsPerSession: 1` and exits after the ticket. Auto mode loops until all tickets are done or the session limit is reached.
-
-### All tiered modes:
-- Require a `ticketId` — no ad-hoc review without a ticket in V1
-- Use the same review process as auto mode (same backends, same adaptive depth)
-- Can be cancelled with `action: "cancel"` at any point
+## Support Files
 
-## Command & Tool Reference
+Additional skill documentation, loaded on demand:
 
-For the full list of CLI commands and MCP tools, read `reference.md` in the same directory as this skill file.
+- **`setup-flow.md`** -- Project detection and AI-Assisted Setup Flow (new project initialization)
+- **`autonomous-mode.md`** -- Autonomous mode, review, plan, and guided execution tiers
+- **`reference.md`** -- Full CLI command and MCP tool reference