shift-ax 0.3.0

package/dist/core/topics/bootstrap.js

@@ -0,0 +1,119 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildWorktreePlan } from './worktree.js';
+import { defaultTopicArtifacts } from './topic-artifacts.js';
+function timestampForSlug(date = new Date()) {
+    return date.toISOString().slice(0, 10);
+}
+export function slugifyTopic(input) {
+    const normalized = String(input || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return normalized || 'topic';
+}
+export function summarizeRequest(request) {
+    const compact = String(request || '').trim().replace(/\s+/g, ' ');
+    if (compact.length <= 160)
+        return compact;
+    return `${compact.slice(0, 157)}...`;
+}
+export function buildTopicSlug(request, now = new Date()) {
+    return `${timestampForSlug(now)}-${slugifyTopic(request).slice(0, 48)}`;
+}
+export async function bootstrapTopic({ rootDir, request, summary, now = new Date(), }) {
+    if (!rootDir)
+        throw new Error('rootDir is required');
+    if (!request || String(request).trim() === '') {
+        throw new Error('request is required');
+    }
+    const topicSlug = buildTopicSlug(request, now);
+    const topicDir = join(rootDir, '.ax', 'topics', topicSlug);
+    const artifacts = defaultTopicArtifacts();
+    await mkdir(topicDir, { recursive: true });
+    const requestContent = `${String(request).trim()}\n`;
+    const requestSummary = (summary && String(summary).trim()) || summarizeRequest(request);
+    const requestSummaryContent = `${requestSummary}\n`;
+    const resolvedContextContent = `${JSON.stringify({
+        version: 1,
+        request: String(request).trim(),
+        matches: [],
+        unresolved_paths: [],
+    }, null, 2)}\n`;
+    const brainstormContent = '# Brainstorm\n\n> Shift AX placeholder: planning interview notes must replace this section before review.\n';
+    const specContent = '# Topic Spec\n\n## Goal\n\n> Shift AX placeholder: define the reviewed goal before implementation.\n';
+    const planReviewContent = `${JSON.stringify({ version: 1, status: 'pending' }, null, 2)}\n`;
+    const policyContextSyncContent = `${JSON.stringify({
+        version: 1,
+        status: 'not_needed',
+        required_updates: [],
+        created_at: now.toISOString(),
+        updated_at: now.toISOString(),
+    }, null, 2)}\n`;
+    const implementationPlanContent = '# Implementation Plan\n\n> Shift AX placeholder: write the reviewed implementation steps before execution.\n';
+    const executionHandoffContent = `${JSON.stringify({
+        version: 1,
+        status: 'pending',
+        tasks: [],
+    }, null, 2)}\n`;
+    const executionStateContent = `${JSON.stringify({
+        version: 1,
+        overall_status: 'pending',
+        tasks: [],
+    }, null, 2)}\n`;
+    const workflowStateContent = `${JSON.stringify({
+        version: 1,
+        topic_slug: topicSlug,
+        phase: 'bootstrapped',
+        created_at: now.toISOString(),
+        updated_at: now.toISOString(),
+        plan_review_status: 'pending',
+        escalation: {
+            status: 'clear',
+            triggers: [],
+        },
+    }, null, 2)}\n`;
+    const commitMessageContent = '# Commit Message\n\n> Shift AX placeholder: generate or write the Lore commit message before finalization.\n';
+    const commitStateContent = `${JSON.stringify({ version: 1, status: 'not_committed' }, null, 2)}\n`;
+    const verificationContent = '# Final Verification\n\n> Shift AX placeholder: record verification evidence before finalization.\n';
+    const worktreePlan = buildWorktreePlan({
+        rootDir,
+        topicSlug,
+        request,
+    });
+    const metadata = {
+        version: 1,
+        topic_slug: topicSlug,
+        created_at: now.toISOString(),
+        status: 'bootstrapped',
+        artifacts,
+    };
+    await Promise.all([
+        mkdir(join(topicDir, artifacts.review_dir), { recursive: true }),
+        mkdir(join(topicDir, artifacts.final_dir), { recursive: true }),
+        writeFile(join(topicDir, artifacts.request), requestContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.request_summary), requestSummaryContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.resolved_context), resolvedContextContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.brainstorm), brainstormContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.spec), specContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.plan_review), planReviewContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.policy_context_sync), policyContextSyncContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.implementation_plan), implementationPlanContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.execution_handoff), executionHandoffContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.execution_state), executionStateContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.workflow_state), workflowStateContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.commit_message), commitMessageContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.commit_state), commitStateContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.verification), verificationContent, 'utf8'),
+        writeFile(join(topicDir, artifacts.worktree_plan), `${JSON.stringify(worktreePlan, null, 2)}\n`, 'utf8'),
+        writeFile(join(topicDir, artifacts.worktree_state), `${JSON.stringify({ version: 1, status: 'not_created' }, null, 2)}\n`, 'utf8'),
+        writeFile(join(topicDir, 'topic.json'), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8'),
+    ]);
+    return {
+        topicSlug,
+        topicDir,
+        metadata,
+    };
+}

package/dist/core/topics/topic-artifacts.js

@@ -0,0 +1,36 @@
+import { join, resolve, sep } from 'node:path';
+export function defaultTopicArtifacts() {
+    return {
+        request: 'request.md',
+        request_summary: 'request-summary.md',
+        resolved_context: 'resolved-context.json',
+        brainstorm: 'brainstorm.md',
+        spec: 'spec.md',
+        plan_review: 'plan-review.json',
+        policy_context_sync: 'policy-context-sync.json',
+        implementation_plan: 'implementation-plan.md',
+        execution_handoff: 'execution-handoff.json',
+        execution_state: 'execution-state.json',
+        workflow_state: 'workflow-state.json',
+        review_dir: 'review',
+        final_dir: 'final',
+        commit_message: 'final/commit-message.md',
+        commit_state: 'final/commit-state.json',
+        verification: 'final/verification.md',
+        handoff: 'handoff.md',
+        worktree_plan: 'worktree-plan.json',
+        worktree_state: 'worktree-state.json',
+    };
+}
+export function topicArtifactPath(topicDir, key) {
+    return join(topicDir, defaultTopicArtifacts()[key]);
+}
+export function getRootDirFromTopicDir(topicDir) {
+    const resolved = resolve(topicDir);
+    const marker = `${sep}.ax${sep}topics${sep}`;
+    const index = resolved.lastIndexOf(marker);
+    if (index === -1) {
+        throw new Error(`topicDir is not inside .ax/topics: ${topicDir}`);
+    }
+    return resolved.slice(0, index);
+}

package/dist/core/topics/worktree-runtime.js

@@ -0,0 +1,141 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve, sep, join } from 'node:path';
+import { buildWorktreePlan } from './worktree.js';
+function runGit(cwd, args) {
+    return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+}
+function getRootDirFromTopicDir(topicDir) {
+    const resolved = resolve(topicDir);
+    const marker = `${sep}.ax${sep}topics${sep}`;
+    const index = resolved.lastIndexOf(marker);
+    if (index === -1) {
+        throw new Error(`topicDir is not inside .ax/topics: ${topicDir}`);
+    }
+    return resolved.slice(0, index);
+}
+async function readTopicMetadata(topicDir) {
+    const raw = await readFile(join(topicDir, 'topic.json'), 'utf8');
+    return JSON.parse(raw);
+}
+async function readTopicRequest(topicDir) {
+    return (await readFile(join(topicDir, 'request.md'), 'utf8')).trim();
+}
+async function writeWorktreeState(topicDir, payload) {
+    await writeFile(join(topicDir, 'worktree-state.json'), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+function isGitRepository(rootDir) {
+    try {
+        runGit(rootDir, ['rev-parse', '--show-toplevel']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readWorktreePlan(topicDir) {
+    const raw = await readFile(join(topicDir, 'worktree-plan.json'), 'utf8');
+    return JSON.parse(raw);
+}
+export async function planTopicWorktree({ topicDir, }) {
+    const rootDir = getRootDirFromTopicDir(topicDir);
+    const metadata = await readTopicMetadata(topicDir);
+    const request = await readTopicRequest(topicDir);
+    const plan = buildWorktreePlan({
+        rootDir,
+        topicSlug: metadata.topic_slug,
+        request,
+    });
+    await writeFile(join(topicDir, 'worktree-plan.json'), `${JSON.stringify(plan, null, 2)}\n`, 'utf8');
+    return plan;
+}
+export async function resolveTopicWorktreeTarget({ topicDir, baseBranch = 'main', }) {
+    const rootDir = getRootDirFromTopicDir(topicDir);
+    const metadata = await readTopicMetadata(topicDir);
+    const plan = existsSync(join(topicDir, 'worktree-plan.json'))
+        ? await readWorktreePlan(topicDir)
+        : await planTopicWorktree({ topicDir });
+    return {
+        topicDir,
+        rootDir,
+        topicSlug: metadata.topic_slug,
+        branchName: plan.preferred_branch_name,
+        worktreePath: plan.preferred_worktree_path,
+        baseBranch,
+    };
+}
+export async function recordTopicWorktreeCreate(target, state) {
+    const result = {
+        version: 1,
+        topic_slug: target.topicSlug,
+        branch_name: target.branchName,
+        worktree_path: target.worktreePath,
+        base_branch: target.baseBranch,
+        created: state.created,
+        reused: state.reused,
+    };
+    await writeWorktreeState(target.topicDir, {
+        ...result,
+        status: state.reused ? 'reused' : state.created ? 'created' : 'not_created',
+    });
+    return result;
+}
+export async function recordTopicWorktreeRemove(target, removed) {
+    const result = {
+        version: 1,
+        topic_slug: target.topicSlug,
+        branch_name: target.branchName,
+        worktree_path: target.worktreePath,
+        removed,
+    };
+    await writeWorktreeState(target.topicDir, {
+        ...result,
+        status: removed ? 'removed' : 'remove_failed',
+    });
+    return result;
+}
+export async function createTopicWorktree({ topicDir, baseBranch = 'main', }) {
+    const target = await resolveTopicWorktreeTarget({
+        topicDir,
+        baseBranch,
+    });
+    if (!isGitRepository(target.rootDir)) {
+        throw new Error(`rootDir is not a git repository: ${target.rootDir}`);
+    }
+    if (existsSync(target.worktreePath)) {
+        return recordTopicWorktreeCreate(target, {
+            created: false,
+            reused: true,
+        });
+    }
+    runGit(target.rootDir, [
+        'worktree',
+        'add',
+        '-b',
+        target.branchName,
+        target.worktreePath,
+        target.baseBranch,
+    ]);
+    return recordTopicWorktreeCreate(target, {
+        created: true,
+        reused: false,
+    });
+}
+export async function removeTopicWorktree({ topicDir, }) {
+    const target = await resolveTopicWorktreeTarget({ topicDir });
+    if (existsSync(target.worktreePath)) {
+        runGit(target.rootDir, ['worktree', 'remove', '--force', target.worktreePath]);
+    }
+    try {
+        runGit(target.rootDir, ['branch', '-D', target.branchName]);
+    }
+    catch {
+        // Branch may already be absent.
+    }
+    return recordTopicWorktreeRemove(target, !existsSync(target.worktreePath));
+}

package/dist/core/topics/worktree.js

@@ -0,0 +1,8 @@
+export function buildWorktreePlan({ rootDir, topicSlug, }) {
+    return {
+        version: 1,
+        topic_slug: topicSlug,
+        preferred_branch_name: `ax/${topicSlug}`,
+        preferred_worktree_path: `${rootDir}/.ax/worktrees/${topicSlug}`,
+    };
+}

package/dist/platform/claude-code/bootstrap.js

@@ -0,0 +1,66 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { buildProductShellAssets, SHIFT_AX_PRODUCT_SHELL_COMMANDS } from '../product-shell-commands.js';
+import { getGlobalContextHome } from '../../core/settings/global-context-home.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_FILES = [
+    'platform/claude-code/scaffold/CLAUDE.template.md',
+    'platform/claude-code/scaffold/hooks/shift-ax-session-start.template.md',
+    ...SHIFT_AX_PRODUCT_SHELL_COMMANDS.map((name) => `platform/claude-code/scaffold/commands/${name}.template.md`),
+];
+function templatePath(relativePath) {
+    return join(HERE, 'scaffold', relativePath.split('/').slice(3).join('/'));
+}
+function localePrelude(locale) {
+    return locale === 'ko'
+        ? '선호 사용자 언어: 한국어. 사용자가 명시적으로 바꾸라고 하지 않으면 한국어로 응답하세요.'
+        : 'Preferred user language: English. Respond in English unless the user explicitly asks to switch.';
+}
+function injectLocalePrelude(raw, locale) {
+    const prelude = localePrelude(locale);
+    if (raw.startsWith('---\n')) {
+        const closing = raw.indexOf('\n---\n', 4);
+        if (closing !== -1) {
+            const frontmatter = raw.slice(0, closing + 5);
+            const rest = raw.slice(closing + 5);
+            return `${frontmatter}\n${prelude}\n\n${rest}`;
+        }
+    }
+    return `${prelude}\n\n${raw}`;
+}
+function renderTemplate(relativePath, rootDir, locale) {
+    const raw = readFileSync(templatePath(relativePath), 'utf8');
+    return injectLocalePrelude(raw
+        .replaceAll('{{BASE_CONTEXT_INDEX}}', `${rootDir}/docs/base-context/index.md`)
+        .replaceAll('{{GLOBAL_CONTEXT_INDEX}}', getGlobalContextHome().indexPath), locale);
+}
+export function claudeCodeScaffoldTemplateFiles() {
+    return [...TEMPLATE_FILES];
+}
+export function renderClaudeCodeSessionStartContext(rootDir, locale = 'en') {
+    return renderTemplate('platform/claude-code/scaffold/hooks/shift-ax-session-start.template.md', rootDir, locale);
+}
+export function renderClaudeCodeBootstrap(rootDir, locale = 'en') {
+    return renderTemplate('platform/claude-code/scaffold/CLAUDE.template.md', rootDir, locale);
+}
+export function getClaudeCodeBootstrapAssets(rootDir, locale = 'en') {
+    const commandAssets = buildProductShellAssets({
+        platform: 'claude-code',
+        commandBasePath: '.claude/commands',
+        renderTemplate: (name) => renderTemplate(`platform/claude-code/scaffold/commands/${name}.template.md`, rootDir, locale),
+    });
+    return [
+        {
+            path: 'CLAUDE.md',
+            description: 'Top-level CLAUDE bootstrap for Claude Code builds.',
+            content: renderClaudeCodeBootstrap(rootDir, locale),
+        },
+        {
+            path: '.claude/hooks/shift-ax-session-start.md',
+            description: 'SessionStart hook payload guidance for Claude Code builds.',
+            content: renderClaudeCodeSessionStartContext(rootDir, locale),
+        },
+        ...commandAssets,
+    ];
+}

package/dist/platform/claude-code/execution.js

@@ -0,0 +1,157 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { materializeExecutionPrompts } from '../../core/planning/execution-launch.js';
+import { buildClaudeWorkerSessionName } from './upstream/tmux/imported/session-name.js';
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function buildClaudeExecShellCommand(plan) {
+    return `cd ${shellQuote(plan.working_directory)} && claude -p --output-format text --permission-mode bypassPermissions --no-session-persistence \"$(cat ${shellQuote(plan.prompt_path)})\" > ${shellQuote(plan.output_path)}`;
+}
+function formatProcessError(error) {
+    const failure = error;
+    const stdout = typeof failure.stdout === 'string'
+        ? failure.stdout
+        : failure.stdout instanceof Buffer
+            ? failure.stdout.toString('utf8')
+            : '';
+    const stderr = typeof failure.stderr === 'string'
+        ? failure.stderr
+        : failure.stderr instanceof Buffer
+            ? failure.stderr.toString('utf8')
+            : '';
+    return [failure.message ?? 'process failed', stdout.trim(), stderr.trim()]
+        .filter(Boolean)
+        .join('\n');
+}
+function claudeExecutionTimeoutMs() {
+    const parsed = Number(process.env.SHIFT_AX_CLAUDE_EXEC_TIMEOUT_MS || '45000');
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 45_000;
+}
+function clearExistingTmuxSession(sessionName) {
+    try {
+        execFileSync('tmux', ['has-session', '-t', sessionName], {
+            stdio: 'pipe',
+        });
+        execFileSync('tmux', ['kill-session', '-t', sessionName], {
+            stdio: 'pipe',
+        });
+    }
+    catch {
+        // no existing session to clear
+    }
+}
+export function getClaudeCodeExecutionRuntime() {
+    return {
+        support: 'available',
+        entrypoint_style: 'cli',
+        execution_handoff_artifact: 'execution-handoff.json',
+        operations: {
+            launch: {
+                command: ['shift-ax', 'launch-execution'],
+                topic_flag: '--topic',
+                additional_flags: ['--platform', '--task-id', '--dry-run'],
+            },
+        },
+        hosts: {
+            subagent_cli: 'claude',
+            tmux_cli: 'tmux',
+        },
+    };
+}
+export async function planClaudeCodeExecutionLaunch({ topicDir, taskId, }) {
+    const artifacts = await materializeExecutionPrompts(topicDir, taskId);
+    const tasks = artifacts.map((artifact) => {
+        const basePlan = {
+            task_id: artifact.task.id,
+            source_text: artifact.task.source_text,
+            execution_mode: artifact.task.execution_mode,
+            working_directory: artifact.worktreePath,
+            prompt_path: artifact.promptPath,
+            output_path: artifact.outputPath,
+        };
+        if (artifact.task.execution_mode === 'tmux') {
+            const sessionName = buildClaudeWorkerSessionName(topicDir.split('/').pop() || 'topic', artifact.task.id);
+            const shellCommand = buildClaudeExecShellCommand({
+                ...basePlan,
+                command: [],
+                shell_command: '',
+            });
+            return {
+                ...basePlan,
+                command: [
+                    'tmux',
+                    'new-session',
+                    '-d',
+                    '-s',
+                    sessionName,
+                    '-c',
+                    artifact.worktreePath,
+                    shellCommand,
+                ],
+                shell_command: shellCommand,
+                session_name: sessionName,
+            };
+        }
+        const shellCommand = buildClaudeExecShellCommand({
+            ...basePlan,
+            command: [],
+            shell_command: '',
+        });
+        return {
+            ...basePlan,
+            command: [
+                '/bin/sh',
+                '-lc',
+                shellCommand,
+            ],
+            shell_command: shellCommand,
+        };
+    });
+    return {
+        platform: 'claude-code',
+        launched: false,
+        topic_dir: topicDir,
+        tasks,
+    };
+}
+export async function launchClaudeCodeExecution({ topicDir, taskId, }) {
+    const plan = await planClaudeCodeExecutionLaunch({ topicDir, taskId });
+    for (const task of plan.tasks) {
+        if (task.execution_mode === 'tmux') {
+            if (task.session_name) {
+                clearExistingTmuxSession(task.session_name);
+            }
+            execFileSync(task.command[0], task.command.slice(1), {
+                stdio: 'pipe',
+            });
+            continue;
+        }
+        try {
+            const output = execFileSync('claude', [
+                '-p',
+                '--output-format',
+                'text',
+                '--permission-mode',
+                'bypassPermissions',
+                '--no-session-persistence',
+                readFileSync(task.prompt_path, 'utf8'),
+            ], {
+                cwd: task.working_directory,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+                timeout: claudeExecutionTimeoutMs(),
+            });
+            mkdirSync(dirname(task.output_path), { recursive: true });
+            writeFileSync(task.output_path, output, 'utf8');
+        }
+        catch (error) {
+            throw new Error(`Claude Code execution failed for ${task.task_id}: ${formatProcessError(error)}`);
+        }
+    }
+    return {
+        ...plan,
+        launched: true,
+    };
+}

package/dist/platform/claude-code/scaffold/CLAUDE.template.md

@@ -0,0 +1,40 @@
+# Shift AX Claude Code SessionStart Bootstrap
+
+This build is expected to use SessionStart hook-driven context injection.
+
+## Hook Intent
+
+- SessionStart should inject Shift AX bootstrap context.
+- Before planning or implementation, resolve context from {{GLOBAL_CONTEXT_INDEX}}.
+- If the global index is missing, recommend `/onboard` before `/request`. Do not pretend the missing context does not matter.
+- Use `shift-ax doctor` when setup, launcher availability, or topic state looks unhealthy.
+- Use `shift-ax resolve-context` before answering when relevant documents may exist.
+- Use `shift-ax run-request` to create the request-scoped topic/worktree, run the planning interview, write brainstorming/spec/plan artifacts plus `execution-handoff.json`, and pause at the human planning-review gate.
+- Use `shift-ax approve-plan` after the human reviewer signs off.
+- If the reviewed plan requires shared policy or base-context doc changes, record them first with `shift-ax sync-policy-context --topic <dir> --summary "<what changed>" [--path <doc>]... [--entry "Label -> path"]...`.
+- Then resume with `shift-ax run-request --topic <dir> --resume` for automatic review and commit. Use `--no-auto-commit` only when a human explicitly wants the final commit step held back.
+- If downstream review or CI fails after the topic looked ready, use `shift-ax react-feedback --topic <dir> --kind <review-changes-requested|ci-failed> --summary "<text>"` to reopen implementation with a file-backed reaction trail.
+- Use `shift-ax launch-execution --platform claude-code --topic <dir> [--task-id <id>] [--dry-run]` when you need the concrete Claude or tmux launch commands from `execution-handoff.json`.
+- Use `shift-ax topic-status --topic <dir>` when you need a compact summary of phase, review gate, execution state, and last failure.
+- Use `shift-ax topics-status [--root DIR] [--limit N]` when you need a compact multi-topic view without leaving the CLI.
+- If a reviewed request hits a mandatory escalation trigger, persist that stop with `shift-ax run-request --topic <dir> --resume --escalation <kind>:<summary>` and resume only after human review with `--clear-escalations`.
+- Use `shift-ax worktree-plan` to inspect the preferred branch/worktree path for the topic.
+- Use `shift-ax worktree-create` before implementation begins and `shift-ax worktree-remove` when the topic worktree should be torn down.
+- Worktree runtime provenance is tracked in `platform/claude-code/upstream/worktree/provenance.md`.
+- Active imported worktree helpers currently include `getWorktreeRoot`, `createClaudeManagedWorktree`, and `removeClaudeManagedWorktree`.
+- Use `shift-ax review --run` before finalization and `shift-ax finalize-commit` only after the review gate allows commit.
+- Natural language is the primary user surface. Internal AX commands exist to support the flow, not replace the conversation.
+- In Shift AX Claude Code sessions, use `/onboard`, `/request <text>`, `/export-context`, `/doctor`, `/status`, `/topics`, `/resume <topic>`, `/review <topic>`, `/help` as the primary visible commands. `$...` aliases may mirror them when useful.
+- Native product-shell command files are installed under `.claude/commands/` for: `onboard`, `request`, `export-context`, `doctor`, `status`, `topics`, `resume`, and `review`.
+
+## Product-shell aliases
+
+Treat these as explicit Shift AX commands inside the session:
+
+- `$onboard` -> onboarding flow
+- `$doctor` -> repo/topic health
+- `$request <text>` -> new request-to-commit flow
+- `$status` -> current topic or repo status
+- `$topics` -> recent topics list
+- `$resume <topic>` -> resume a topic
+- `$review <topic>` -> run structured review

package/dist/platform/claude-code/scaffold/commands/doctor.template.md

@@ -0,0 +1,11 @@
+---
+description: Run Shift AX health checks for the current repository.
+argument-hint: "[--topic <dir>]"
+---
+
+Run Shift AX doctor for the current repository.
+
+- If arguments specify a topic, use `shift-ax doctor --topic <dir>`.
+- Otherwise use `shift-ax doctor`.
+
+Summarize the repo health, base-context health, and any launcher warnings.

package/dist/platform/claude-code/scaffold/commands/export-context.template.md

@@ -0,0 +1,20 @@
+---
+description: Explain how to share the user's Shift AX global knowledge base.
+argument-hint: ""
+---
+
+Do not build an archive.
+
+Explain that the user should share:
+
+- `~/.shift-ax/`
+
+And tell the recipient to place the shared files at the same location on their machine:
+
+- `~/.shift-ax/`
+
+Mention that the most important file is:
+
+- `~/.shift-ax/index.md`
+
+If useful, remind them that `/onboard` can refresh the profile before sharing.

package/dist/platform/claude-code/scaffold/commands/onboard.template.md

@@ -0,0 +1,43 @@
+---
+description: Capture or refresh the user's global Shift AX knowledge base.
+argument-hint: "[optional note]"
+---
+
+This command is the most important setup step.
+
+Start by saying:
+
+> This step matters most. Please invest 10 minutes so Shift AX can understand how you work.
+
+Then run a conversational interview that captures:
+
+1. primary role summary
+2. work types
+3. related repositories for each work type
+4. per-repository working methods
+5. company/domain language
+
+For each work type and repository:
+
+- ask which directories matter
+- inspect the repository when a path is available
+- infer likely workflow details from real files
+- present your inferred workflow back to the user
+- ask them to correct anything wrong or missing
+
+When you have enough information:
+
+1. write `.ax/onboarding-input.json`
+2. if `{{GLOBAL_CONTEXT_INDEX}}` or other global knowledge files already exist, ask whether to overwrite them first
+3. persist with:
+   - `shift-ax onboard-context --root "$PWD" --input .ax/onboarding-input.json`
+   - add `--overwrite` only if the user explicitly agreed
+
+Keep the top-level knowledge base in `~/.shift-ax/` with:
+
+- `index.md` listing only titles and linked pages
+- linked work type pages
+- linked repository/procedure pages
+- linked domain-language pages
+
+After completion, remind the user to share `~/.shift-ax/` with teammates who do similar work.