auriga-cli 1.7.0 → 1.9.2

package/README.md

@@ -11,13 +11,38 @@ This repo itself is a fully configured harness project. You can clone it to see
 | Module | Description |
 |---|---|
 | **Workflow** | `CLAUDE.md` auriga workflow: requirement clarification -> TDD -> Review, Harness principles, Subagent usage guide |
-| **Skills** | Development process skills — brainstorming, systematic-debugging, TDD, verification, planning, playwright |
-| **Recommended Skills** | Optional utility skills (e.g. `ui-ux-pro-max`) you can add on top of the workflow skills |
-| **Plugins** | Recommended Claude Code plugins — skill-creator, claude-md-management, codex |
-| **Hooks** | Claude Code hooks: `notify` (macOS notification, focus-aware sound-only when terminal is frontmost), `pr-create-guard` (PostToolUse body snapshot after `gh pr create`), `pr-ready-guard` (PreToolUse block on stray planning docs / active specs in `docs/specs/` / unpushed commits before `gh pr ready`) |
+| **Skills** | Development process + orchestration skills — brainstorming, systematic-debugging, TDD, verification, planning, playwright, deep-review, test-designer, parallel-implementation, ui-ux-pro-max |
+| **Recommended Skills** | Optional utility skills (e.g. `codex-agent`, `claude-code-agent`) you can add on top of the workflow skills |
+| **Plugins** | Recommended Claude Code plugins — skill-creator, claude-md-management, codex, auriga-go |
+| **Hooks** | Claude Code hooks: `notify` (macOS notification, focus-aware sound-only when terminal is frontmost — **opt-in**: not installed by `install --all`, requires `install hooks --hook notify`), `pr-create-guard` (PostToolUse body snapshot after `gh pr create`), `pr-ready-guard` (PreToolUse block on stray planning docs / active specs in `docs/specs/` / unpushed commits before `gh pr ready`) |
 
 ## Quick Start
 
+### Agent Bootstrap (non-TTY)
+
+Running inside `claude -p`, `claude -p --worktree`, or any non-interactive Agent session? Start here:
+
+```bash
+npx -y auriga-cli guide
+```
+
+This prints a 5-step SOP (prerequisite check → `install --all` → optional recommended skills → session reload → verify). Follow it top-to-bottom and the Agent can install the full harness without any human prompt.
+
+The leading `-y` belongs to `npx` (it auto-confirms package installation), **not** to `auriga-cli`.
+
+Non-interactive install commands:
+
+```bash
+npx -y auriga-cli install --all              # workflow + skills + plugins + hooks (atomic)
+npx -y auriga-cli install recommended        # opt-in utility skills (not in --all)
+npx -y auriga-cli install <type> [--flags]   # one of: workflow | skills | recommended | plugins | hooks
+npx -y auriga-cli --help                     # full catalog + flags
+```
+
+Exit codes: `0` success, `1` fatal (precheck / parse / fetch), `2` partial success — `stderr` lists per-category `[OK]/[FAIL]` and a `Retry:` hint. After install, reload the Claude Code session so the new `CLAUDE.md` / skills / plugins / hook registrations are picked up.
+
+### Interactive menu
+
 ```bash
 npx auriga-cli
 ```
@@ -60,7 +85,6 @@ Installs selected skills via `npx skills add`, targeting both Claude Code and Co
 | deep-review | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | Multi-dimensional PR review orchestrator (required + conditional reviewers + punch list) |
 | test-designer | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | Independent-Evaluation test designer for TDD red phase |
 | parallel-implementation | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | Slice planner for parallel multi-subagent code writing |
-| auriga-go | [Ben2pc/auriga-cli](https://github.com/Ben2pc/auriga-cli) | Workflow autopilot for the auriga workflow; reminder-based navigation across the 12 steps with an Experimental hook-backed `ship` mode |
 
 Supports both project and global installation scopes.
 
@@ -73,6 +97,7 @@ Installs selected plugins via `claude plugins install`, automatically adding req
 | skill-creator | Create and manage custom skills |
 | claude-md-management | Audit and improve CLAUDE.md |
 | codex | Codex cross-model collaboration |
+| auriga-go | Workflow autopilot for the auriga workflow. Reminder-based navigation across the 12 `CLAUDE.md` phases with an Experimental hook-backed `ship` mode. Bundles a skill (description-based NL trigger + `/auriga-go`) plus a plugin-level Stop hook for ship mode. |
 
 ### Hooks
 
@@ -80,8 +105,8 @@ Installs Claude Code hooks into a chosen scope. Each hook is self-contained unde
 
 | Hook | Description |
 |---|---|
-| notify | Native macOS notification when Claude needs your attention. Shows the brand mark in the small app-icon position; click brings the originating terminal back to focus. **Focus-aware**: when the launching terminal is already frontmost, drops the banner and plays the sound only (toggle via `soundOnlyWhenFocused` in `config.json`). **Per-project group ID**: new notifications cleanly replace older ones in Notification Center, no process accumulation, no cross-project interference. Auto-installs `alerter` via Homebrew (`vjeantet/tap/alerter`). Customize sound and icon by editing `.claude/hooks/notify/config.json` and `.claude/hooks/notify/icon.png`. macOS-only at runtime; silent no-op on other platforms. |
-| pr-create-guard | PostToolUse hook for `gh pr create`. Queries the newly-created PR via `gh pr view` and injects a body snapshot (headings found + TODO-checkbox counts) as `additionalContext` for the Agent to self-verify against the step-10 scope / acceptance / risks / TODO contract. Never blocks — PostToolUse runs after the fact. Graceful degradation when gh is unavailable. |
+| notify *(opt-in)* | Native macOS notification when Claude needs your attention. Shows the brand mark in the small app-icon position; click brings the originating terminal back to focus. **Focus-aware**: when the launching terminal is already frontmost, drops the banner and plays the sound only (toggle via `soundOnlyWhenFocused` in `config.json`). **Per-project group ID**: new notifications cleanly replace older ones in Notification Center, no process accumulation, no cross-project interference. Auto-installs `alerter` via Homebrew (`vjeantet/tap/alerter`). Customize sound and icon by editing `.claude/hooks/notify/config.json` and `.claude/hooks/notify/icon.png`. macOS-only at runtime; silent no-op on other platforms. |
+| pr-create-guard | PostToolUse hook for `gh pr create`. Queries the newly-created PR via `gh pr view` and injects a body snapshot (headings found + TODO-checkbox counts) as `additionalContext` for the Agent to self-verify against the PR-readiness scope / acceptance / risks / TODO contract. Never blocks — PostToolUse runs after the fact. Graceful degradation when gh is unavailable. |
 | pr-ready-guard | PreToolUse hook for `gh pr ready`. Blocks on structural signals only: (1) stray planning docs at `findings.md` / `progress.md` / `task_plan.md` / `docs/superpowers/specs/*.md` — must be archived to `docs/worklog/worklog-<date>-<branch>/` (or deleted) per CLAUDE.md `Document Conventions`; (2) unfinalized active specs at `docs/specs/*.md` — must be promoted to `docs/architecture/`, archived, or deleted; (3) unpushed commits on the current branch. No text regex of PR content is ever used as a block signal. On pass, injects a PR body snapshot as `additionalContext`. |
 
 Scope choices:
@@ -98,6 +123,12 @@ Re-running the installer preserves your customized `config.json` and `icon.png`,
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (required for Plugins and Hooks modules)
 - [Homebrew](https://brew.sh) (recommended for the `notify` hook to install `alerter`)
 
+## Development
+
+- `npm test` — unit/integration tests (sub-second)
+- `bash tests/ship-loop.test.sh` — ship-loop Stop hook tests (bash)
+- `npm run test:e2e` — full tarball install e2e suite (~90-120s). Packs the actual npm tarball, installs it into a scratch project, and runs `auriga-cli install` against GitHub content pinned to the current HEAD SHA. The preflight uses `git branch -r --contains HEAD` — purely local, no network — so **HEAD must be reachable from a local remote ref** (a successful `git push` updates local remote refs synchronously; if someone else pushed, run `git fetch` first). The `plugins` and `--all` scenarios additionally require the `claude` CLI on PATH; they skip gracefully otherwise.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -11,13 +11,38 @@
 | 模块 | 说明 |
 |---|---|
 | **Workflow** | `CLAUDE.md` 里的 auriga 工作流：需求澄清 → TDD → Review，Harness 原则，Subagent 使用指南 |
-| **Skills** | 开发流程 skills —— brainstorming、systematic-debugging、TDD、verification、planning、playwright |
-| **Recommended Skills** | 可选的工具类 skills（如 `ui-ux-pro-max`），在 workflow skills 之外按需追加 |
-| **Plugins** | 推荐的 Claude Code 插件 —— skill-creator、claude-md-management、codex |
-| **Hooks** | Claude Code hooks：`notify`（macOS 通知，终端在焦点时仅放声不弹横幅）、`pr-create-guard`（`gh pr create` 后注入 PR body 快照的 PostToolUse）、`pr-ready-guard`（`gh pr ready` 前按游离 planning 文档 / `docs/specs/` 内未清理的 spec / 未 push commits 拦截的 PreToolUse） |
+| **Skills** | 开发流程 + 编排类 skills —— brainstorming、systematic-debugging、TDD、verification、planning、playwright、deep-review、test-designer、parallel-implementation、ui-ux-pro-max |
+| **Recommended Skills** | 可选的工具类 skills（如 `codex-agent`、`claude-code-agent`），在 workflow skills 之外按需追加 |
+| **Plugins** | 推荐的 Claude Code 插件 —— skill-creator、claude-md-management、codex、auriga-go |
+| **Hooks** | Claude Code hooks：`notify`（macOS 通知，终端在焦点时仅放声不弹横幅 —— **opt-in**：`install --all` 不装，需要 `install hooks --hook notify`）、`pr-create-guard`（`gh pr create` 后注入 PR body 快照的 PostToolUse）、`pr-ready-guard`（`gh pr ready` 前按游离 planning 文档 / `docs/specs/` 内未清理的 spec / 未 push commits 拦截的 PreToolUse） |
 
 ## 快速开始
 
+### Agent Bootstrap（非交互）
+
+在 `claude -p`、`claude -p --worktree` 或任何非交互 Agent 会话里想装整套 harness？从这里开始：
+
+```bash
+npx -y auriga-cli guide
+```
+
+会打印一份 5 步 SOP（前置检查 → `install --all` → 可选 recommended skills → 重启 session → 验证）。Agent 照着顺序往下跑就能装完整套 harness，全程不需要人按键。
+
+开头的 `-y` 是 **npx 自己的 flag**（用来跳过"是否要装这个包"的确认），**不是** auriga-cli 的参数。
+
+非交互安装命令：
+
+```bash
+npx -y auriga-cli install --all              # workflow + skills + plugins + hooks（原子）
+npx -y auriga-cli install recommended        # 可选工具 skills（不在 --all 内）
+npx -y auriga-cli install <type> [--flags]   # 单类：workflow | skills | recommended | plugins | hooks
+npx -y auriga-cli --help                     # 完整 catalog + flag 说明
+```
+
+退出码：`0` 成功；`1` 致命错误（前置检查 / 解析 / 拉取失败）；`2` 部分成功——`stderr` 会列出逐类 `[OK]/[FAIL]` 和 `Retry:` 提示。装完后请重启 Claude Code session，让新的 `CLAUDE.md` / skills / plugins / hook 注册 生效。
+
+### 交互式菜单
+
 ```bash
 npx auriga-cli
 ```
@@ -46,7 +71,7 @@ npx auriga-cli
 
 ### Skills
 
-通过 `npx skills add` 逐个安装选中的 skills，同时安装到 Claude Code 和 Codex。
+通过 `npx skills add` 安装选中的 skills，同时安装到 Claude Code 和 Codex。
 
 | Skill | 来源 | 说明 |
 |---|---|---|
@@ -60,7 +85,6 @@ npx auriga-cli
 | deep-review | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | 多维度 PR review 编排器（必选 + 条件 + punch list 汇总） |
 | test-designer | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | TDD 红灯阶段的 Independent Evaluation 测试设计器 |
 | parallel-implementation | [Ben2pc/g-claude-code-plugins](https://github.com/Ben2pc/g-claude-code-plugins) | 多 subagent 并行写代码时的切片计划器 |
-| auriga-go | [Ben2pc/auriga-cli](https://github.com/Ben2pc/auriga-cli) | auriga 工作流的自动驾驶：在 12 步内做 reminder-based 导航；包含 Experimental 的 hook-backed `ship` 模式 |
 
 支持 project 和 global 两种安装范围。
 
@@ -73,6 +97,7 @@ npx auriga-cli
 | skill-creator | 创建和管理自定义 skills |
 | claude-md-management | 审计和改进 CLAUDE.md |
 | codex | Codex 跨模型协作 |
+| auriga-go | auriga 工作流的自动驾驶：在 12 步内做 reminder-based 导航；包含 Experimental 的 hook-backed `ship` 模式。内置一个 skill（按 description 的自然语言触发 + `/auriga-go` slash command）和一个 plugin 层面的 Stop hook。 |
 
 ### Hooks
 
@@ -80,8 +105,8 @@ npx auriga-cli
 
 | Hook | 说明 |
 |---|---|
-| notify | 当 Claude 需要你关注时弹一条原生 macOS 通知。在通知小图标位显示品牌图，点击通知可把发起 Claude 的终端拉回前台。**焦点感知**：发起 Claude 的终端正处于前台时，仅放提示音不弹横幅（通过 `config.json` 的 `soundOnlyWhenFocused` 切换）。**按项目分组**：新通知会干净地替换通知中心里的旧条目，不会进程堆积，也不会跨项目互相覆盖。会自动通过 Homebrew 安装 `alerter`（`vjeantet/tap/alerter`）。改 `.claude/hooks/notify/config.json` 即可换提示音、替换 `.claude/hooks/notify/icon.png` 即可换图标。仅 macOS 运行时生效，其它平台静默 no-op。 |
-| pr-create-guard | `gh pr create` 的 PostToolUse hook。创建成功后通过 `gh pr view` 拉真实 PR body，扫 `^##` / `^###` headings 并统计 `- [ ]` / `- [x]`，通过 `additionalContext` 注入快照让 Agent 对照 step 10 的"范围 / 验收标准 / 风险 / 剩余 TODO"四要素。不 block——PostToolUse 发生在动作之后。gh 不可用时静默降级。 |
+| notify *(opt-in)* | 当 Claude 需要你关注时弹一条原生 macOS 通知。在通知小图标位显示品牌图，点击通知可把发起 Claude 的终端拉回前台。**焦点感知**：发起 Claude 的终端正处于前台时，仅放提示音不弹横幅（通过 `config.json` 的 `soundOnlyWhenFocused` 切换）。**按项目分组**：新通知会干净地替换通知中心里的旧条目，不会进程堆积，也不会跨项目互相覆盖。会自动通过 Homebrew 安装 `alerter`（`vjeantet/tap/alerter`）。改 `.claude/hooks/notify/config.json` 即可换提示音、替换 `.claude/hooks/notify/icon.png` 即可换图标。仅 macOS 运行时生效，其它平台静默 no-op。 |
+| pr-create-guard | `gh pr create` 的 PostToolUse hook。创建成功后通过 `gh pr view` 拉真实 PR body，扫 `^##` / `^###` headings 并统计 `- [ ]` / `- [x]`，通过 `additionalContext` 注入快照让 Agent 对照 PR-readiness 阶段的"范围 / 验收标准 / 风险 / 剩余 TODO"四要素。不 block——PostToolUse 发生在动作之后。gh 不可用时静默降级。 |
 | pr-ready-guard | `gh pr ready` 的 PreToolUse hook。**只按结构信号**拦截：(1) 仓库根存在游离 planning 文档（`findings.md` / `progress.md` / `task_plan.md`）或 `docs/superpowers/specs/*.md` 未归档——按 CLAUDE.md 的"文档规范"迁到 `docs/worklog/worklog-<date>-<branch>/` 或删除；(2) `docs/specs/*.md` 内有未结案的活跃 spec——晋升到 `docs/architecture/`、归档或删除；(3) 本地有未 push commits。**不做 PR 正文文本 regex 匹配**。放行时注入 PR body 快照。 |
 
 作用域选择：
@@ -98,6 +123,12 @@ npx auriga-cli
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)（Plugins 和 Hooks 模块需要）
 - [Homebrew](https://brew.sh)（`notify` hook 用来安装 `alerter`，可选）
 
+## 开发
+
+- `npm test` —— 单元/集成测试（亚秒）
+- `bash tests/ship-loop.test.sh` —— ship-loop Stop hook 测试（bash）
+- `npm run test:e2e` —— 完整的 tarball 安装 e2e 套件（~90-120s）。`npm pack` 打出真实 tarball，装到临时项目，对着 GitHub 上当前 HEAD SHA 对应的 content 跑 `auriga-cli install`。预检用 `git branch -r --contains HEAD`，纯本地、不发网络请求，因此 **HEAD 必须能被任何本地 remote ref 追溯到**（`git push` 成功时会同步更新本地 remote ref；如果是别人推的，先 `git fetch`）。`plugins` 和 `--all` 场景还要求 `claude` CLI 已在 PATH，否则这两条会优雅跳过。
+
 ## License
 
 MIT

package/dist/catalog.d.ts

@@ -0,0 +1,12 @@
+export interface CatalogEntry {
+    name: string;
+    description: string;
+}
+export interface Catalog {
+    generatedAt: string;
+    workflowSkills: CatalogEntry[];
+    recommendedSkills: CatalogEntry[];
+    plugins: CatalogEntry[];
+    hooks: CatalogEntry[];
+}
+export declare function loadCatalog(packageRoot: string): Catalog;

package/dist/catalog.js

@@ -0,0 +1,9 @@
+import fs from "node:fs";
+import path from "node:path";
+export function loadCatalog(packageRoot) {
+    const catalogPath = path.join(packageRoot, "dist", "catalog.json");
+    if (!fs.existsSync(catalogPath)) {
+        throw new Error(`catalog missing at ${catalogPath}. Run 'npm run build' or reinstall the package.`);
+    }
+    return JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+}

package/dist/catalog.json

@@ -0,0 +1,87 @@
+{
+  "generatedAt": "2026-04-22T05:16:53.660Z",
+  "workflowSkills": [
+    {
+      "name": "brainstorming",
+      "description": "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+    },
+    {
+      "name": "deep-review",
+      "description": "Run a formal, multi-dimensional code review of a pull request. Reads the PR diff, classifies change types, dispatches parallel reviewers by dimension (correctness, consistency, docs-sync, plus conditional security/edge-cases/UX/performance/structure/maintainability), and synthesizes findings into an actionable punch list. Use when the user asks to review a PR, run /deep-review, mark a PR as ready for review, or requests a formal/thorough code review."
+    },
+    {
+      "name": "parallel-implementation",
+      "description": "Plan how to slice a non-trivial coding task across parallel subagents. Returns a dispatch plan (file assignments, dependencies, output-format contracts) — the main Agent then executes it with the Agent tool + `isolation: \"worktree\"`. Invoke only when work justifies multi-agent overhead: (a) greenfield 0→1 across multiple independent modules, (b) change touches ≥3 modules, or (c) ≥5 files each with >50 lines of diff. Small changes write inline."
+    },
+    {
+      "name": "planning-with-files",
+      "description": "Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring >5 tool calls. Supports automatic session recovery after /clear."
+    },
+    {
+      "name": "playwright-cli",
+      "description": "Automate browser interactions, test web pages and work with Playwright tests."
+    },
+    {
+      "name": "systematic-debugging",
+      "description": "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes"
+    },
+    {
+      "name": "test-designer",
+      "description": "Design failing tests for complex features using Independent Evaluation — dispatches a context-free agent that sees only the requirement spec and code paths (not the implementation approach), then returns executable failing tests. Use when starting TDD for a non-trivial feature, when the requirement is ambiguous enough that biased tests are a risk, or when the user asks for independent test design."
+    },
+    {
+      "name": "test-driven-development",
+      "description": "Use when implementing any feature or bugfix, before writing implementation code"
+    },
+    {
+      "name": "ui-ux-pro-max",
+      "description": "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
+    },
+    {
+      "name": "verification-before-completion",
+      "description": "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always"
+    }
+  ],
+  "recommendedSkills": [
+    {
+      "name": "claude-code-agent",
+      "description": "Delegate coding, review, diagnosis, planning, and structured-output tasks to an independent Claude Code session via `claude -p` (Agent SDK)."
+    },
+    {
+      "name": "codex-agent",
+      "description": "Delegate coding, review, diagnosis, planning, and browser tasks to an independent Codex session via `codex exec` / resume / review."
+    }
+  ],
+  "plugins": [
+    {
+      "name": "skill-creator",
+      "description": "Create and manage custom skills"
+    },
+    {
+      "name": "claude-md-management",
+      "description": "Audit and improve CLAUDE.md files"
+    },
+    {
+      "name": "codex",
+      "description": "Cross-model collaboration with Codex"
+    },
+    {
+      "name": "auriga-go",
+      "description": "Workflow autopilot for the auriga workflow (reminder-based navigation + Experimental ship mode)"
+    }
+  ],
+  "hooks": [
+    {
+      "name": "notify",
+      "description": "(opt-in) Native macOS notification when Claude needs your attention (auto-installs alerter via Homebrew)"
+    },
+    {
+      "name": "pr-create-guard",
+      "description": "Workflow guard: after `gh pr create`, query the new PR and inject a body snapshot (headings + TODO counts) so the Agent can verify scope / acceptance / risks / TODO"
+    },
+    {
+      "name": "pr-ready-guard",
+      "description": "Workflow guard: block `gh pr ready` on unpushed commits, stray planning docs, or unfinalized active specs in docs/specs/; filter-inject PR body snapshot otherwise"
+    }
+  ]
+}

package/dist/cli.d.ts

@@ -1,2 +1,24 @@
 #!/usr/bin/env node
-export {};
+import { type CategoryName } from "./types.js";
+export type { CategoryName } from "./types.js";
+export interface InstallParsed {
+    all: boolean;
+    type?: CategoryName;
+    filter?: string[];
+    lang?: string;
+    cwd?: string;
+    scope?: "project" | "user";
+}
+export type ParsedArgs = {
+    command: "help";
+    helpType?: CategoryName;
+} | {
+    command: "version";
+} | {
+    command: "guide";
+} | {
+    command: "install";
+    install: InstallParsed;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function main(argv: string[]): Promise<number>;