shift-ax 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 handsupmin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,145 @@
+# Shift AX
+
+> Codex와 Claude Code를 위한 request-to-commit 가드레일.
+
+**English:** [README.md](./README.md)
+
+## 이게 뭐냐
+
+Shift AX는 코딩 에이전트 런타임 위에 얹는 제어 레이어다.
+
+주요 흐름:
+
+1. `~/.shift-ax/`에 재사용 가능한 업무 지식 저장
+2. 계획 전에 문맥 해석
+3. 요청별 topic/worktree 생성
+4. 사람 계획 리뷰에서 중단
+5. 검증, 리뷰, 커밋까지 이어감
+
+즉, 프롬프트 요령이 아니라 **반복 가능한 개발 절차**를 만들기 위한 도구다.
+
+## 설치
+
+```bash
+npm install -g shift-ax
+```
+
+또는:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/handsupmin/shift-ax/main/scripts/install-global.sh | bash
+```
+
+소스 체크아웃에서 직접 쓰려면:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+## 사용법
+
+### 셸 시작
+
+```bash
+shift-ax --codex
+```
+
+또는
+
+```bash
+shift-ax --claude-code
+```
+
+첫 실행에서는:
+
+1. 선호 언어
+2. full-auto 기본 사용 여부
+
+를 물어보고, 아래에 저장한다:
+
+- `~/.shift-ax/settings.json`
+
+full-auto가 켜져 있으면:
+
+- Codex: `--yolo`
+- Claude Code: `--dangerously-skip-permissions`
+
+### 재사용 문맥 온보딩
+
+Shift AX는 재사용 지식을 여기에 저장한다:
+
+- `~/.shift-ax/index.md`
+- `~/.shift-ax/work-types/`
+- `~/.shift-ax/procedures/`
+- `~/.shift-ax/domain-language/`
+
+런타임 안에서:
+
+- **Codex:** `$onboard`
+- **Claude Code:** `/onboard`
+
+### 작업 시작
+
+런타임 안에서:
+
+- **Codex:** `$request <text>`
+- **Claude Code:** `/request <text>`
+
+다른 자주 쓰는 명령:
+
+- Codex: `$doctor`, `$status`, `$topics`, `$resume`, `$review`, `$export-context`
+- Claude Code: `/doctor`, `/status`, `/topics`, `/resume`, `/review`, `/export-context`
+
+### CLI로 직접 실행
+
+셸 없이도 가능:
+
+```bash
+shift-ax onboard-context --discover
+shift-ax run-request --request "Build safer auth refresh flow"
+shift-ax approve-plan --topic .ax/topics/<topic> --reviewer "Alex" --decision approve
+shift-ax run-request --topic .ax/topics/<topic> --resume
+```
+
+## 다른 LLM에게 넘길 프롬프트
+
+다른 LLM이 설치부터 사용까지 대신 하게 하려면 아래를 넘기면 된다:
+
+```text
+You are setting up and using Shift AX in this repository.
+
+Goal:
+- install Shift AX
+- start the correct runtime shell
+- onboard reusable context
+- start the first request safely
+
+Rules:
+- use `shift-ax`, not `ax`, in user-facing commands
+- if Shift AX is not installed, run `npm install -g shift-ax`
+- if working from a source checkout instead of a global install, run:
+  - `npm install`
+  - `npm run build`
+  - `npm link`
+- prefer `shift-ax --codex` unless the user explicitly wants Claude Code
+- on first run, answer the language question using the user's language preference
+- on first run, answer the full-auto question cautiously
+- if `~/.shift-ax/index.md` does not exist, onboard first
+- in Codex use `$onboard` and `$request ...`
+- in Claude Code use `/onboard` and `/request ...`
+- do not start implementation before plan approval
+- if shared policy/context docs must change first, update them before resume
+
+Suggested first commands:
+1. `shift-ax --codex`
+2. run `$onboard`
+3. run `$request <the user's task>`
+```
+
+## 더 보기
+
+- Architecture: [`docs/architecture/shift-ax-architecture.md`](./docs/architecture/shift-ax-architecture.md)
+- LLM setup detail: [`docs/setup/llm-install-and-bootstrap.ko.md`](./docs/setup/llm-install-and-bootstrap.ko.md)
+- Release notes: [`docs/release-notes/`](./docs/release-notes/)

package/README.md

@@ -0,0 +1,143 @@
+# Shift AX
+
+> Request-to-commit guardrails for Codex and Claude Code.
+
+**한국어:** [README.ko.md](./README.ko.md)
+
+## What it is
+
+Shift AX sits on top of coding-agent runtimes and makes them work in a safer delivery loop:
+
+1. capture reusable work knowledge in `~/.shift-ax/`
+2. resolve context before planning
+3. create a request-scoped topic/worktree
+4. pause at human plan review
+5. resume through verification, review, and commit
+
+It is for teams that want a repeatable workflow, not prompt rituals.
+
+## Install
+
+```bash
+npm install -g shift-ax
+```
+
+Or:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/handsupmin/shift-ax/main/scripts/install-global.sh | bash
+```
+
+From a source checkout:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+## How to use it
+
+### Start a shell
+
+```bash
+shift-ax --codex
+```
+
+or
+
+```bash
+shift-ax --claude-code
+```
+
+On first run, Shift AX asks:
+
+1. preferred language
+2. whether full-auto should be enabled by default
+
+Those settings are stored in:
+
+- `~/.shift-ax/settings.json`
+
+If full-auto is enabled:
+
+- Codex gets `--yolo`
+- Claude Code gets `--dangerously-skip-permissions`
+
+### Onboard your reusable context
+
+Shift AX keeps reusable knowledge in:
+
+- `~/.shift-ax/index.md`
+- `~/.shift-ax/work-types/`
+- `~/.shift-ax/procedures/`
+- `~/.shift-ax/domain-language/`
+
+Inside the runtime:
+
+- **Codex:** `$onboard`
+- **Claude Code:** `/onboard`
+
+### Start work
+
+Inside the runtime:
+
+- **Codex:** `$request <text>`
+- **Claude Code:** `/request <text>`
+
+Other common commands:
+
+- Codex: `$doctor`, `$status`, `$topics`, `$resume`, `$review`, `$export-context`
+- Claude Code: `/doctor`, `/status`, `/topics`, `/resume`, `/review`, `/export-context`
+
+### CLI mode
+
+You can also run the workflow directly:
+
+```bash
+shift-ax onboard-context --discover
+shift-ax run-request --request "Build safer auth refresh flow"
+shift-ax approve-plan --topic .ax/topics/<topic> --reviewer "Alex" --decision approve
+shift-ax run-request --topic .ax/topics/<topic> --resume
+```
+
+## Give this prompt to another LLM
+
+If you want another LLM to install and use Shift AX for you, give it this:
+
+```text
+You are setting up and using Shift AX in this repository.
+
+Goal:
+- install Shift AX
+- start the correct runtime shell
+- onboard reusable context
+- start the first request safely
+
+Rules:
+- use `shift-ax`, not `ax`, in user-facing commands
+- if Shift AX is not installed, run `npm install -g shift-ax`
+- if working from a source checkout instead of a global install, run:
+  - `npm install`
+  - `npm run build`
+  - `npm link`
+- prefer `shift-ax --codex` unless the user explicitly wants Claude Code
+- on first run, answer the language question using the user's language preference
+- on first run, answer the full-auto question cautiously
+- if `~/.shift-ax/index.md` does not exist, onboard first
+- in Codex use `$onboard` and `$request ...`
+- in Claude Code use `/onboard` and `/request ...`
+- do not start implementation before plan approval
+- if shared policy/context docs must change first, update them before resume
+
+Suggested first commands:
+1. `shift-ax --codex`
+2. run `$onboard`
+3. run `$request <the user's task>`
+```
+
+## More docs
+
+- Architecture: [`docs/architecture/shift-ax-architecture.md`](./docs/architecture/shift-ax-architecture.md)
+- LLM setup details: [`docs/setup/llm-install-and-bootstrap.md`](./docs/setup/llm-install-and-bootstrap.md)
+- Release notes: [`docs/release-notes/`](./docs/release-notes/)

package/dist/adapters/claude-code/adapter.js

@@ -0,0 +1,90 @@
+import { defaultBaseContextIndex, defaultTopicRoot } from '../contracts.js';
+import { getClaudeCodeExecutionRuntime, launchClaudeCodeExecution, planClaudeCodeExecutionLaunch, } from '../../platform/claude-code/execution.js';
+import { createClaudeCodeTopicWorktree, getClaudeCodeWorktreeRuntime, planClaudeCodeTopicWorktree, removeClaudeCodeTopicWorktree, } from '../../platform/claude-code/worktree.js';
+import { getClaudeCodeWorktreeRoot } from '../../platform/claude-code/upstream/worktree/imported/get-worktree-root.js';
+import { getClaudeCodeTmuxRuntime } from '../../platform/claude-code/tmux.js';
+const CORE_COMMANDS = [
+    'bootstrap-topic',
+    'resolve-context',
+    'review',
+    'worktree-plan',
+    'worktree-create',
+    'worktree-remove',
+    'onboard-context',
+    'doctor',
+    'run-request',
+    'approve-plan',
+    'sync-policy-context',
+    'react-feedback',
+    'finalize-commit',
+    'launch-execution',
+    'topic-status',
+    'topics-status',
+];
+export const claudeCodeAdapter = {
+    platform: 'claude-code',
+    getManifest(rootDir) {
+        const platformRoot = resolvePlatformRoot(rootDir);
+        const worktreeRuntime = getClaudeCodeWorktreeRuntime(platformRoot);
+        const tmuxRuntime = getClaudeCodeTmuxRuntime(platformRoot);
+        const executionRuntime = getClaudeCodeExecutionRuntime();
+        return {
+            platform: 'claude-code',
+            integration_mode: 'hook-bootstrap',
+            natural_language_first: true,
+            worktree_support: worktreeRuntime.support,
+            worktree_runtime: worktreeRuntime,
+            tmux_runtime: tmuxRuntime,
+            execution_runtime: executionRuntime,
+            default_base_context_index: defaultBaseContextIndex(platformRoot),
+            default_topic_root: defaultTopicRoot(platformRoot),
+            core_commands: [...CORE_COMMANDS],
+        };
+    },
+    renderBootstrapInstructions(rootDir) {
+        const platformRoot = resolvePlatformRoot(rootDir);
+        return [
+            'Shift AX Claude Code Build',
+            '',
+            'Bootstrap mode: hook-driven context injection.',
+            'Use SessionStart and related hook surfaces to inject Shift AX startup context and guide the user into the right flow.',
+            `Before planning or implementation, load the base-context index at ${defaultBaseContextIndex(platformRoot)} and route the request through Shift AX core flow.`,
+            'If the base-context index is missing, interview the team and persist it with `shift-ax onboard-context` (interactive) or `shift-ax onboard-context --input <file>` before starting request work.',
+            'Use `shift-ax doctor` for a compact repo/runtime health report when the setup or launcher state is unclear.',
+            'Use `shift-ax run-request` to bootstrap the request-scoped topic/worktree, resolve context, run the planning interview, write `execution-handoff.json`, and pause at the human planning-review gate.',
+            'Use `shift-ax approve-plan` to record the human planning-review decision.',
+            'If the approved plan requires shared domain or policy document updates, complete them first and record that gate with `shift-ax sync-policy-context --topic <dir> --summary "<what changed>" [--path <doc>]... [--entry "Label -> path"]...` before resuming implementation.',
+            'Then resume with `shift-ax run-request --topic <dir> --resume` for automatic review and commit. Add `--no-auto-commit` only when a human explicitly wants a final manual stop.',
+            '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 platform-owned Claude launch commands for subagent or tmux execution from `execution-handoff.json`.',
+            'Use `shift-ax topic-status --topic <dir>` for a compact summary of workflow phase, review gate, execution status, and latest failure reason.',
+            'Use `shift-ax topics-status [--root DIR] [--limit N]` when you need a compact list of recent topics without opening a separate dashboard.',
+            '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 finalize-commit` after `shift-ax review --run` reports commit-ready status.',
+            'Use `shift-ax worktree-plan` to inspect the preferred branch and worktree path for a topic.',
+            'Use `shift-ax worktree-create` before implementation begins, and `shift-ax worktree-remove` when the topic worktree should be torn down.',
+            'Natural language is the primary user surface. Internal AX commands exist for tooling and debugging, but the default user experience should remain conversational.',
+        ].join('\n');
+    },
+    commandFor(command) {
+        return ['shift-ax', command];
+    },
+    async planExecution(input) {
+        return planClaudeCodeExecutionLaunch(input);
+    },
+    async launchExecution(input) {
+        return launchClaudeCodeExecution(input);
+    },
+    async planWorktree(input) {
+        return planClaudeCodeTopicWorktree(input);
+    },
+    async createWorktree(input) {
+        return createClaudeCodeTopicWorktree(input);
+    },
+    async removeWorktree(input) {
+        return removeClaudeCodeTopicWorktree(input);
+    },
+};
+function resolvePlatformRoot(rootDir) {
+    return getClaudeCodeWorktreeRoot(rootDir) || rootDir;
+}

package/dist/adapters/codex/adapter.js

@@ -0,0 +1,94 @@
+import { defaultBaseContextIndex, defaultTopicRoot } from '../contracts.js';
+import { getCodexExecutionRuntime, launchCodexExecution, planCodexExecutionLaunch, } from '../../platform/codex/execution.js';
+import { createCodexTopicWorktree, getCodexWorktreeRuntime, planCodexTopicWorktree, removeCodexTopicWorktree, } from '../../platform/codex/worktree.js';
+import { resolveCodexRepoRoot } from '../../platform/codex/upstream/worktree/imported/resolve-repo-root.js';
+import { getCodexTmuxRuntime as getCodexTmuxRuntimeMetadata } from '../../platform/codex/tmux.js';
+const CORE_COMMANDS = [
+    'bootstrap-topic',
+    'resolve-context',
+    'review',
+    'worktree-plan',
+    'worktree-create',
+    'worktree-remove',
+    'onboard-context',
+    'doctor',
+    'run-request',
+    'approve-plan',
+    'sync-policy-context',
+    'react-feedback',
+    'finalize-commit',
+    'launch-execution',
+    'topic-status',
+    'topics-status',
+];
+export const codexAdapter = {
+    platform: 'codex',
+    getManifest(rootDir) {
+        const platformRoot = resolvePlatformRoot(rootDir);
+        const worktreeRuntime = getCodexWorktreeRuntime(platformRoot);
+        const tmuxRuntime = getCodexTmuxRuntimeMetadata(platformRoot);
+        const executionRuntime = getCodexExecutionRuntime();
+        return {
+            platform: 'codex',
+            integration_mode: 'agents-md-bootstrap',
+            natural_language_first: true,
+            worktree_support: worktreeRuntime.support,
+            worktree_runtime: worktreeRuntime,
+            tmux_runtime: tmuxRuntime,
+            execution_runtime: executionRuntime,
+            default_base_context_index: defaultBaseContextIndex(platformRoot),
+            default_topic_root: defaultTopicRoot(platformRoot),
+            core_commands: [...CORE_COMMANDS],
+        };
+    },
+    renderBootstrapInstructions(rootDir) {
+        const platformRoot = resolvePlatformRoot(rootDir);
+        return [
+            'Shift AX Codex Build',
+            '',
+            'Bootstrap mode: AGENTS.md-driven startup.',
+            `Before planning or implementation, load the base-context index at ${defaultBaseContextIndex(platformRoot)} and route the request through Shift AX core flow.`,
+            'If the base-context index is missing, interview the team and persist it with `shift-ax onboard-context` (interactive) or `shift-ax onboard-context --input <file>` before starting request work.',
+            'Use `shift-ax doctor` for a compact repo/runtime health report when the setup or launcher state is unclear.',
+            'Use `shift-ax run-request` to bootstrap the request-scoped topic/worktree, resolve context, run the planning interview, write `execution-handoff.json`, and pause at the human planning-review gate.',
+            'Use `shift-ax approve-plan` to record the human planning-review decision.',
+            'If the approved plan requires shared domain or policy document updates, complete them first and record that gate with `shift-ax sync-policy-context --topic <dir> --summary "<what changed>" [--path <doc>]... [--entry "Label -> path"]...` before resuming implementation.',
+            'Then resume with `shift-ax run-request --topic <dir> --resume` for automatic review and commit. Add `--no-auto-commit` only when a human explicitly wants a final manual stop.',
+            '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 codex --topic <dir> [--task-id <id>] [--dry-run]` when you need the platform-owned Codex launch commands for subagent or tmux execution from `execution-handoff.json`.',
+            'Use `shift-ax topic-status --topic <dir>` for a compact summary of workflow phase, review gate, execution status, and latest failure reason.',
+            'Use `shift-ax topics-status [--root DIR] [--limit N]` when you need a compact list of recent topics without opening a separate dashboard.',
+            '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 finalize-commit` after `shift-ax review --run` reports commit-ready status.',
+            'Use `shift-ax worktree-plan` to inspect the preferred branch and worktree path for a topic.',
+            'Use `shift-ax worktree-create` before implementation begins, and `shift-ax worktree-remove` when the topic worktree should be torn down.',
+            'Natural language is the primary user surface. Internal AX commands exist for tooling and debugging, but the default user experience should remain conversational.',
+        ].join('\n');
+    },
+    commandFor(command) {
+        return ['shift-ax', command];
+    },
+    async planExecution(input) {
+        return planCodexExecutionLaunch(input);
+    },
+    async launchExecution(input) {
+        return launchCodexExecution(input);
+    },
+    async planWorktree(input) {
+        return planCodexTopicWorktree(input);
+    },
+    async createWorktree(input) {
+        return createCodexTopicWorktree(input);
+    },
+    async removeWorktree(input) {
+        return removeCodexTopicWorktree(input);
+    },
+};
+function resolvePlatformRoot(rootDir) {
+    try {
+        return resolveCodexRepoRoot(rootDir);
+    }
+    catch {
+        return rootDir;
+    }
+}

package/dist/adapters/contracts.js

@@ -0,0 +1,7 @@
+import { join } from 'node:path';
+export function defaultBaseContextIndex(rootDir) {
+    return join(rootDir, 'docs', 'base-context', 'index.md');
+}
+export function defaultTopicRoot(rootDir) {
+    return join(rootDir, '.ax', 'topics');
+}

package/dist/adapters/index.js

@@ -0,0 +1,12 @@
+import { claudeCodeAdapter } from './claude-code/adapter.js';
+import { codexAdapter } from './codex/adapter.js';
+const ADAPTERS = {
+    codex: codexAdapter,
+    'claude-code': claudeCodeAdapter,
+};
+export function listPlatformAdapters() {
+    return Object.values(ADAPTERS);
+}
+export function getPlatformAdapter(platform) {
+    return ADAPTERS[platform];
+}