hub-launch 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-07-28
+
+### Added
+
+- Verify reports now auto-post to the PR by default; use `--no-post` to restore the old confirm-before-posting behavior.
+- Added a `hula-help` Agent Skill for interactive onboarding and reference guidance.
+- Moved `hula-verify`'s tmp writes from OS `/tmp` to a repo-local, gitignored `.hublaunch/tmp/` directory (#325).
+
+## [1.17.0] - 2026-07-23
+
+### Added
+
+- `hula launch` now supports per-pipeline-step model and iteration-cap overrides via a `steps` block in `.hublaunch/hublaunch.config.js` (hula-server PR #442), plus a `--skip-regression` flag to force-skip regression tests for a single launch. Conflicting `bugfix.model`/`mergeConflict.model` values, or `regression.skip` combined with the legacy `--regression` flag, are rejected locally before any network call.
+
 ## [1.16.0] - 2026-07-17
 
 ### Fixed

package/README.md

@@ -40,6 +40,7 @@ That's the whole fundamental workflow.
 - 🖥️ **Client Agnostic** — based on skills that can be adapted to most agent harnesses
 - 🔔 **Notifications** - you can configure an endpoint for notifications about progress. For instance, a slack channel.
 - 📋 **Logging** - run `hula-info` for progress in the container. Also pushes several documents within each PR showing logging.
+- 🧭 **Guided Help** — run `/hula-help` anytime for an interactive walkthrough of setup, the workflow, and any command or skill
 - 🖥️ **Dashboard** — track all your active plans at [https://www.hublaunch.site/dashboard](https://www.hublaunch.site/dashboard)
 - 🔒 **Safe** - tokens are maintained by you locally in your config file, and on our server securely protected and removed when no longer needed.
 
@@ -82,8 +83,9 @@ After upgrading the CLI:
 npm install -g hub-launch@latest   # or: pnpm add -g hub-launch
 ```
 
-re-run `hula init` inside each project to refresh the bundled Agent Skills,
-instruction templates, and config scaffolding:
+re-run `hula init` inside each project to refresh the bundled Agent Skills and
+config scaffolding (workflow scripts and instruction docs now ship with the
+package, so they update automatically with the CLI):
 
 ```bash
 cd <your-project>
@@ -149,9 +151,41 @@ Top-level commands:
 | `hula merge`   | —     | Merge PR and clean up                                            |
 | `hula launch`  | —     | Trigger AI coding session on hula-project server                 |
 | `hula schedule` | —     | Trigger or schedule an execute-action (e.g. `--built-in harden`) |
+| `hula script <name>` | — | Run a bundled cross-platform workflow script (used by the Agent Skills) |
+| `hula instructions <name>` | — | Print a bundled instruction doc (`planning`, `proceed`, `skill-creation`) |
+| `hula session-hook` | — | Claude Code PreToolUse hook that captures launch-session provenance |
 
 Run `hula <command> --help` for details, or see the full [Commands Reference](./docs/commands.md).
 
+### Cross-platform, low-footprint tooling
+
+The workflow scripts and instruction documents that power the Agent Skills ship
+**inside the `hula` package** as cross-platform Node — they are no longer copied
+into your repo, and they need **no `bash` and no `jq`**, so they run identically
+on macOS, Linux, and Windows. `hula init` therefore does not write
+`.github/scripts/*.sh` or `.hublaunch/*-instructions.md`.
+
+Skills invoke them via the global bin:
+
+```bash
+# Run a bundled workflow script (cross-platform, no bash/jq)
+hula script merge-local -- 42 ".hula-worktrees/issue-42" "fix(#42): message"
+
+# Print a bundled instruction document
+hula instructions planning
+```
+
+**Migration:** upgrading from an older version? Existing
+`.github/scripts/hula-*.sh` and `.hublaunch/*-instructions.md` keep working, but
+are now obsolete and safe to delete — `hula init` prints a reminder listing them
+(it never deletes anything).
+
+**Claude Code commands:** the `/hula-*` commands are available as a Claude Code
+plugin so they load globally, so `hula init` no longer writes `.claude/commands/*`
+symlinks by default. Prefer repo-local command files instead? Run
+`hula init --with-claude-commands`. The committed `.agents/skills/` directory
+(read by GitHub Copilot, Cursor, Codex, and 30+ tools) is unchanged.
+
 ## `hula launch` and Resume
 
 `hula launch` submits a job to the hula-project server, which runs an AI coding agent (Claude Code) through a fixed 9-step pipeline:
@@ -281,6 +315,72 @@ variables, and includes them in the request to the server. Notes:
 - Only forward variables your tests actually need; treat anything you list as
   leaving your machine.
 
+### Configuring per-step model & iteration overrides
+
+`hula launch` runs your plan through a fixed 9-step server-side pipeline. By
+default every step uses the server's built-in model, loop-iteration cap, and
+skip behavior. To override those per step for your project, add a `steps` block
+to `.hublaunch/hublaunch.config.js` (config-file only — this is a persistent
+project setting, not a per-launch flag):
+
+```js
+export const config = {
+  // ...
+  steps: {
+    implementation: { model: "opus" },
+    lintfix: { model: "haiku", maxIterations: 2 },
+    regression: { skip: true },
+  },
+};
+```
+
+Each of the 9 keys maps to a pipeline step. All fields are optional; omit a step
+(or the whole `steps` block) to keep the server default:
+
+| Step key         | `model` | `maxIterations` | `skip` | Other |
+| ---------------- | :-----: | :-------------: | :----: | ----- |
+| `implementation` |   ✅    |                 |        |       |
+| `findBugs`       |   ✅    |   ✅ (1–20)     |        | `diffMaxLines` (≥1), `excludeRegex` (string) |
+| `bugfix`         |   ✅    |                 |        |       |
+| `lintfix`        |   ✅    |   ✅ (1–20)     |        |       |
+| `build`          |   ✅    |   ✅ (1–20)     |        |       |
+| `regression`     |         |                 |   ✅   |       |
+| `mergeConflict`  |   ✅    |                 |        |       |
+| `summary`        |   ✅    |   ✅ (1–20)     |        |       |
+| `verify`         |   ✅    |   ✅ (1–20)     |   ✅   |       |
+
+`model` values are free-form strings passed straight through to the server
+(`claude --model <value>`); no allowlist is enforced. Values are validated at
+config-load time — an out-of-range `maxIterations`, a non-boolean `skip`, or an
+empty `model` string fails immediately with a clear error.
+
+#### `--skip-regression`
+
+As a per-launch counterpart to the config `steps.regression.skip`, `hula launch`
+accepts a `--skip-regression` flag that force-skips the regression-tests step for
+that one invocation (it wins over whatever `steps.regression.skip` is set to in
+config):
+
+```bash
+# Skip regression tests for a single launch
+hula launch feature-auth .hublaunch/plans/my-plan.md --skip-regression
+```
+
+#### Conflict rules (validated locally before any network call)
+
+Two combinations are rejected client-side — `hula launch` exits `1` immediately
+with the same message the server would return, so misconfigurations fail fast:
+
+- **`bugfix.model` ≠ `mergeConflict.model`** — both map to the same
+  `RALPH_BUGFIX_MODEL` env var on the server, so they cannot be set to different
+  values:
+  `bugfix.model and mergeConflict.model both map to RALPH_BUGFIX_MODEL and cannot conflict`
+- **`regression.skip: true` combined with the legacy `--regression` flag** — one
+  forces the step off, the other forces it on. This also covers passing both
+  `--skip-regression` and `--regression`, and a config `steps.regression.skip:
+  true` combined with a one-off `--regression`:
+  `regression.skip and the legacy regression flag are contradictory`
+
 ## `hula schedule`
 
 `hula schedule` triggers a built-in or custom execute-action (e.g. the `harden` security audit) on the hula-project server, which provisions a sandbox to run it and opens a PR / plan / feedback as the outcome.

package/dist/commands/init.d.ts

@@ -1,5 +1,11 @@
 import type { Command } from 'commander';
 import type { Config } from '../types/index.js';
+/**
+ * Idempotently append a `.gitignore` entry with its own comment header, if
+ * `marker` isn't already present in `content`. Pure/sync so the append logic is
+ * unit-testable without touching the filesystem.
+ */
+export declare function appendGitignoreEntry(content: string, marker: string, comment: string, entry: string): string;
 /**
  * Keys whose **actual runtime value** is written by the config template below.
  * A key belongs here if and only if emitting it a second time would duplicate
@@ -40,7 +46,62 @@ export declare function initCommand(program: Command, _config: Config): void;
  * Generate hook templates based on authentication provider
  */
 export declare function generateHookTemplates(projectRoot: string, authProvider: string): Promise<void>;
+/**
+ * Ensure the `.hublaunch/skills/` action-file directory exists.
+ *
+ * The planning/proceed/skill-creation instruction documents are no longer
+ * copied into the consumer repo — they ship inside the `hula` package and are
+ * read at runtime via `hula instructions <planning|proceed|skill-creation>`.
+ * This keeps the project footprint to genuinely project-specific files.
+ *
+ * Only the `.hublaunch/skills/` directory (user-authored /hula-schedule action
+ * files) is created here; files committed there persist (it is not gitignored).
+ */
+export declare function initializeSkillsActionDir(projectRoot: string): Promise<void>;
+/**
+ * Initialize Agent Skills for AI-assisted hula workflows.
+ *
+ * Single source of truth: .agents/skills/<name>/SKILL.md (Agent Skills spec).
+ *
+ * Each harness gets a reference to that canonical file:
+ *   - GitHub Copilot, Cursor, Codex, and other Agent Skills-compatible tools
+ *     read directly from .agents/skills/<name>/SKILL.md.
+ *   - Claude Code reads from .claude/commands/<name>.md, which is created as
+ *     a symlink pointing into .agents/skills/ (relative path so it works after
+ *     cloning on any machine). No content is duplicated.
+ *
+ * Because the symlinks are named <name>.md (not SKILL.md) and live under
+ * .claude/commands/ (not .agents/skills/), GitHub Copilot's Agent Skills
+ * scanner does not pick them up, so no duplicate commands appear.
+ *
+ * Any existing .claude/skills/ directory is removed on init to clean up
+ * legacy installations that previously wrote full files there.
+ *
+ * Agent Skills standard: https://agentskills.io/specification
+ */
+export declare function initializeAgentSkills(projectRoot: string, withClaudeCommands: boolean): Promise<void>;
+/**
+ * Detect tool-owned files from earlier hula versions that are now obsolete and
+ * print a non-destructive notice. `hula init` no longer generates
+ * `.github/scripts/hula-*.sh` or `.hublaunch/*-instructions.md` — those scripts
+ * and instruction docs ship inside the `hula` package now (run via
+ * `hula script <name>` / `hula instructions <name>`). Pre-existing copies are
+ * left untouched (they still work) but can be safely deleted.
+ */
+export declare function noticeObsoleteFiles(projectRoot: string): Promise<void>;
+/**
+ * Register the hula session hook in the consumer repo's .claude/settings.json.
+ *
+ * Adds a PreToolUse/Bash hook entry that captures the Claude Code session id
+ * of the chat session running /hula-launch (clientSessionId provenance —
+ * hula-server PR #419). Unlike initVsCodeAutoApproval's single-key overwrite,
+ * hooks live in a NESTED ARRAY (`hooks.PreToolUse[]`) that users may already
+ * populate, so this merges: it preserves every existing hook and appends ours
+ * only when absent (idempotent by the command string).
+ */
+export declare function initClaudeSessionHook(projectRoot: string): Promise<void>;
 export declare function executeInit(options?: {
     force?: boolean;
+    withClaudeCommands?: boolean;
 }): Promise<void>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAczC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAahD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,aAkBhC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAe9E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAmBnE;AA0bD;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CA+Bf;AA4bD,wBAAsB,WAAW,CAAC,OAAO,CAAC,EAAE;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2gBhB"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAczC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAahD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,MAAM,CAIR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,aAmBhC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAe9E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAuBnE;AA0bD;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAyED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQlF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,OAAO,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmEf;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmC5E;AAwED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkD9E;AAsCD,wBAAsB,WAAW,CAAC,OAAO,CAAC,EAAE;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CA4iBhB"}

package/dist/commands/init.js

@@ -1,4 +1,4 @@
-import { writeFile, readFile, mkdir, copyFile, chmod, rm, symlink, } from 'fs/promises';
+import { writeFile, readFile, readdir, mkdir, copyFile, rm, symlink, } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join, relative, isAbsolute } from 'path';
 import { logger } from '../utils/logger.js';
@@ -10,6 +10,17 @@ import { DEFAULT_CONFIG } from '../types/config.schema.js';
 import { checkGhVersion } from '../utils/github-cli.js';
 import { parseExistingConfig, mergeConfigs, CONFIG_PARSE_FAILED_PREFIX, } from '../utils/config-parser.js';
 import { getCliVersion } from '../utils/version.js';
+/**
+ * Idempotently append a `.gitignore` entry with its own comment header, if
+ * `marker` isn't already present in `content`. Pure/sync so the append logic is
+ * unit-testable without touching the filesystem.
+ */
+export function appendGitignoreEntry(content, marker, comment, entry) {
+    if (content.includes(marker))
+        return content;
+    const prefix = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    return `${content}${prefix}\n${comment}\n${entry}\n`;
+}
 /**
  * Keys whose **actual runtime value** is written by the config template below.
  * A key belongs here if and only if emitting it a second time would duplicate
@@ -45,6 +56,7 @@ export const TEMPLATE_EMITTED_KEYS = new Set([
     'hooks',
     'worktreeBasePath',
     'envVars',
+    'steps',
 ]);
 /**
  * Build the `// Preserved custom settings` block for any keys present in the
@@ -75,6 +87,7 @@ export function initCommand(program, _config) {
         .command('init')
         .description('Initialize HubLaunch configuration (interactive)')
         .option('--force', 'Overwrite existing configuration')
+        .option('--with-claude-commands', 'Also write repo-local .claude/commands/* symlinks (default: use the global hula Claude Code plugin instead)')
         .action(async (options) => {
         try {
             await executeInit(options);
@@ -605,43 +618,20 @@ const AGENT_SKILLS = [
     { templateDir: 'hula-schedule', skillName: 'hula-schedule' },
     { templateDir: 'hula-upload', skillName: 'hula-upload' },
     { templateDir: 'hula-info', skillName: 'hula-info' },
+    { templateDir: 'hula-help', skillName: 'hula-help' },
 ];
 /**
- * Copy planning instruction templates to .hublaunch/.
- * These are used by the hula-plan and hula-confirm skills at runtime.
+ * Ensure the `.hublaunch/skills/` action-file directory exists.
+ *
+ * The planning/proceed/skill-creation instruction documents are no longer
+ * copied into the consumer repo — they ship inside the `hula` package and are
+ * read at runtime via `hula instructions <planning|proceed|skill-creation>`.
+ * This keeps the project footprint to genuinely project-specific files.
+ *
+ * Only the `.hublaunch/skills/` directory (user-authored /hula-schedule action
+ * files) is created here; files committed there persist (it is not gitignored).
  */
-async function initializePlanningInstructions(projectRoot, overridePlanningInstructions, overrideProceedInstructions) {
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    const templatesSourceDir = join(__dirname, '..', 'templates');
-    const instructionsTemplatePath = join(templatesSourceDir, 'planning-instructions.md');
-    const instructionsDestPath = join(projectRoot, '.hublaunch', 'planning-instructions.md');
-    if (!existsSync(instructionsDestPath) || overridePlanningInstructions) {
-        await copyFile(instructionsTemplatePath, instructionsDestPath);
-        logger.success('Updated: .hublaunch/planning-instructions.md');
-    }
-    else {
-        logger.info('Keeping existing planning instructions');
-    }
-    const proceedInstructionsTemplatePath = join(templatesSourceDir, 'proceed-instructions.md');
-    const proceedInstructionsDestPath = join(projectRoot, '.hublaunch', 'proceed-instructions.md');
-    if (!existsSync(proceedInstructionsDestPath) || overrideProceedInstructions) {
-        await copyFile(proceedInstructionsTemplatePath, proceedInstructionsDestPath);
-        logger.success('Updated: .hublaunch/proceed-instructions.md');
-    }
-    else {
-        logger.info('Keeping existing proceed instructions');
-    }
-    // Skill-creation instructions are read by the /hula-schedule skill at runtime
-    // (parallel to how /hula-plan reads planning-instructions.md). They are
-    // deterministic tooling, so always refresh them with the latest template.
-    const skillCreationTemplatePath = join(templatesSourceDir, 'skill-creation-instructions.md');
-    const skillCreationDestPath = join(projectRoot, '.hublaunch', 'skill-creation-instructions.md');
-    await copyFile(skillCreationTemplatePath, skillCreationDestPath);
-    logger.success('Updated: .hublaunch/skill-creation-instructions.md');
-    // Ensure the action-file directory used by the /hula-schedule skill exists.
-    // Files committed here persist (it is not gitignored). Seed a .gitkeep so the
-    // empty directory survives in git until the first action file is created.
+export async function initializeSkillsActionDir(projectRoot) {
     const skillsDir = join(projectRoot, '.hublaunch', 'skills');
     await mkdir(skillsDir, { recursive: true });
     const gitkeepPath = join(skillsDir, '.gitkeep');
@@ -671,16 +661,20 @@ async function initializePlanningInstructions(projectRoot, overridePlanningInstr
  *
  * Agent Skills standard: https://agentskills.io/specification
  */
-async function initializeAgentSkills(projectRoot) {
+export async function initializeAgentSkills(projectRoot, withClaudeCommands) {
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
     const skillsSourceDir = join(__dirname, '..', 'templates', 'skills');
     // Canonical location — single source of truth.
     const agentsSkillsDir = join(projectRoot, '.agents', 'skills');
     await mkdir(agentsSkillsDir, { recursive: true });
-    // Claude Code reads from .claude/commands/.
+    // Claude Code reads from .claude/commands/ — only when the opt-in flag asks
+    // for repo-local commands. By default the /hula-* commands come from the hula
+    // Claude Code plugin (installed globally), so no symlinks are written.
     const claudeCommandsDir = join(projectRoot, '.claude', 'commands');
-    await mkdir(claudeCommandsDir, { recursive: true });
+    if (withClaudeCommands) {
+        await mkdir(claudeCommandsDir, { recursive: true });
+    }
     // Remove .claude/skills/ if it exists — legacy path that caused duplicates.
     const claudeSkillsDir = join(projectRoot, '.claude', 'skills');
     try {
@@ -695,63 +689,66 @@ async function initializeAgentSkills(projectRoot) {
         const agentsDestDir = join(agentsSkillsDir, skillName);
         await mkdir(agentsDestDir, { recursive: true });
         await copyFile(srcSkillMd, join(agentsDestDir, 'SKILL.md'));
-        // Create a symlink in .claude/commands/ pointing back to the canonical file.
-        // Relative path so the symlink works after cloning on any machine.
-        const symlinkPath = join(claudeCommandsDir, `${skillName}.md`);
-        const symlinkTarget = join('..', '..', '.agents', 'skills', skillName, 'SKILL.md');
-        // Remove any existing file/symlink before (re-)creating.
-        await rm(symlinkPath, { force: true });
-        await symlink(symlinkTarget, symlinkPath);
+        // Optionally create a symlink in .claude/commands/ pointing back to the
+        // canonical file. Relative path so it works after cloning on any machine.
+        if (withClaudeCommands) {
+            const symlinkPath = join(claudeCommandsDir, `${skillName}.md`);
+            const symlinkTarget = join('..', '..', '.agents', 'skills', skillName, 'SKILL.md');
+            // Remove any existing file/symlink before (re-)creating.
+            await rm(symlinkPath, { force: true });
+            await symlink(symlinkTarget, symlinkPath);
+        }
         logger.success(`Updated skill: ${skillName}`);
     }
     logger.blank();
     logger.info('🎉 Agent Skills installed — works with Claude Code, GitHub Copilot, Codex, and 30+ AI tools');
     logger.info('💡 Invoke with /hula-plan, /hula-fix, /hula-create, etc. (note: hyphens, not dots)');
+    if (withClaudeCommands) {
+        logger.info('🔗 Repo-local Claude Code commands written to .claude/commands/ (--with-claude-commands).');
+    }
+    else {
+        logger.info('📦 For Claude Code, /hula-* commands are installed globally to ~/.claude/commands/ when hula is installed/built — no per-project files needed.');
+        logger.info('   If they are missing, reinstall hula (or run its postinstall), or use `hula init --with-claude-commands` for repo-local command files.');
+    }
 }
 /**
- * List of bundled shell scripts that support the chat participant workflows.
- * These scripts are copied from src/templates/scripts/ to .github/scripts/
- * during `hula init` to reduce terminal approval clicks in VS Code.
- */
-const BUNDLED_SCRIPTS = [
-    'hula-read-config.sh',
-    'hula-fix-setup.sh',
-    'hula-fix-commit.sh',
-    'hula-verify-gather.sh',
-    'hula-verify-post.sh',
-    'hula-merge-local.sh',
-    'hula-merge-remote.sh',
-    'hula-launch-run.sh',
-    // No new auto-approve rule needed: the VSCODE_AUTO_APPROVE_SETTINGS pattern
-    // `^bash \.github/scripts/hula-` already matches hula-schedule-run.sh and
-    // hula-schedule-manage.sh.
-    'hula-schedule-run.sh',
-    'hula-schedule-manage.sh',
-    // Claude Code PreToolUse hook that captures the launching chat session id
-    // (clientSessionId provenance — hula-server PR #419). Registered in the
-    // consumer's .claude/settings.json by initClaudeSessionHook().
-    'hula-session-hook.sh',
-];
-/**
- * Initialize bundled shell scripts for chat participant workflows.
- * Copies scripts from src/templates/scripts/ to .github/scripts/ in the target project.
- * These scripts bundle multiple terminal commands into single invocations,
- * reducing VS Code terminal approval popups from ~28 to ~7 per workflow cycle.
+ * Detect tool-owned files from earlier hula versions that are now obsolete and
+ * print a non-destructive notice. `hula init` no longer generates
+ * `.github/scripts/hula-*.sh` or `.hublaunch/*-instructions.md` — those scripts
+ * and instruction docs ship inside the `hula` package now (run via
+ * `hula script <name>` / `hula instructions <name>`). Pre-existing copies are
+ * left untouched (they still work) but can be safely deleted.
  */
-async function initializeScriptFiles(projectRoot) {
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    const scriptsSourceDir = join(__dirname, '..', 'templates', 'scripts');
-    const scriptsDestDir = join(projectRoot, '.github', 'scripts');
-    // Create .github/scripts directory
-    await mkdir(scriptsDestDir, { recursive: true });
-    for (const scriptName of BUNDLED_SCRIPTS) {
-        const srcPath = join(scriptsSourceDir, scriptName);
-        const destPath = join(scriptsDestDir, scriptName);
-        // Always overwrite scripts with latest version (they are deterministic tooling, not user-customized)
-        await copyFile(srcPath, destPath);
-        await chmod(destPath, 0o755);
-        logger.success(`Updated script: .github/scripts/${scriptName}`);
+export async function noticeObsoleteFiles(projectRoot) {
+    const obsolete = [];
+    const scriptsDir = join(projectRoot, '.github', 'scripts');
+    if (existsSync(scriptsDir)) {
+        try {
+            const entries = await readdir(scriptsDir);
+            if (entries.some((f) => f.startsWith('hula-') && f.endsWith('.sh'))) {
+                obsolete.push('.github/scripts/hula-*.sh');
+            }
+        }
+        catch {
+            // Unreadable dir — skip the notice rather than fail init.
+        }
+    }
+    for (const name of [
+        'planning-instructions.md',
+        'proceed-instructions.md',
+        'skill-creation-instructions.md',
+    ]) {
+        if (existsSync(join(projectRoot, '.hublaunch', name))) {
+            obsolete.push(`.hublaunch/${name}`);
+            break;
+        }
+    }
+    if (obsolete.length > 0) {
+        logger.blank();
+        logger.info('ℹ️  These hula files are now obsolete and safe to delete (scripts & instructions ship with the hula package):');
+        for (const f of obsolete) {
+            logger.listItem(f, 1);
+        }
     }
 }
 /**
@@ -770,8 +767,6 @@ const VSCODE_AUTO_APPROVE_SETTINGS = {
     '/^gh (issue view|pr list|pr view|pr diff|repo view)\\b/': true,
     // GitHub CLI write commands used by hula workflows
     '/^gh pr (comment|merge)\\b/': true,
-    // Hula bash scripts deployed to .github/scripts/
-    '/^bash \\.github\\/scripts\\/hula-/': true,
     // Common safe commands
     '/^(ls|cat|head|tail|wc|echo|mkdir|rm -f|cd|pwd)\\b/': true,
 };
@@ -807,10 +802,10 @@ async function initVsCodeAutoApproval(projectRoot) {
     await writeFile(settingsPath, content, 'utf-8');
     logger.success('VS Code auto-approval configured: .vscode/settings.json');
 }
-/** The hook command registered in .claude/settings.json (relative path —
- * Claude Code runs hook commands from the project root, so this is
- * machine-independent and safe to commit in the consumer repo). */
-const CLAUDE_SESSION_HOOK_COMMAND = 'bash .github/scripts/hula-session-hook.sh';
+/** The hook command registered in .claude/settings.json. Runs the global
+ * `hula` bin (cross-platform, no bash/jq) instead of a project-local shell
+ * script, so no file is written into the consumer repo. */
+const CLAUDE_SESSION_HOOK_COMMAND = 'hula session-hook';
 /**
  * Register the hula session hook in the consumer repo's .claude/settings.json.
  *
@@ -821,7 +816,7 @@ const CLAUDE_SESSION_HOOK_COMMAND = 'bash .github/scripts/hula-session-hook.sh';
  * populate, so this merges: it preserves every existing hook and appends ours
  * only when absent (idempotent by the command string).
  */
-async function initClaudeSessionHook(projectRoot) {
+export async function initClaudeSessionHook(projectRoot) {
     const claudeDir = join(projectRoot, '.claude');
     const settingsPath = join(claudeDir, 'settings.json');
     await mkdir(claudeDir, { recursive: true });
@@ -1118,6 +1113,12 @@ export async function executeInit(options) {
         envVarsLine =
             '\n  // envVars: ["TEST_USER_EMAIL", "API_KEY"],  // Environment variables to forward to container (read from .env)';
     }
+    // Per-pipeline-step model/iteration overrides (hula-server PR #442). Rendered
+    // as a real value when preserved across re-init, otherwise a commented example.
+    const stepsDocsUrl = 'https://github.com/NoStackApp/hub-launch#configuring-per-step-model--iteration-overrides';
+    const stepsLine = finalConfig.steps
+        ? `\n  steps: ${JSON.stringify(finalConfig.steps)},  // Per-pipeline-step model/iteration overrides. Keys/fields/ranges: ${stepsDocsUrl}`
+        : `\n  // steps: { implementation: { model: "opus" }, regression: { skip: true } },  // Per-pipeline-step model/iteration overrides. Keys/fields/ranges: ${stepsDocsUrl}`;
     const configContent = `export const config = {${versionLine}
   // API Configuration${apiKeyLine}${anthropicKeyLine}${daytonaKeyLine}${daytonaTierLine}${containerResourcesLine}${updateNotificationUrlLine}${updateNotificationNameTagLine}${usageTierLine}
 
@@ -1132,7 +1133,7 @@ export async function executeInit(options) {
 
   // Worktree base path (used by /hula-fix, /hula-merge, /hula-upload)
   worktreeBasePath: "${(finalConfig.worktreeBasePath || '.hula-worktrees').replace(/\\/g, '\\\\').replace(/"/g, '\\"')}",
-${envVarsLine}${buildPreservedSection(finalConfig)}
+${envVarsLine}${stepsLine}${buildPreservedSection(finalConfig)}
 };
 `;
     // Create directory if it doesn't exist
@@ -1168,22 +1169,30 @@ ${envVarsLine}${buildPreservedSection(finalConfig)}
         if (existsSync(gitignorePath)) {
             gitignoreContent = await import('fs/promises').then((fs) => fs.readFile(gitignorePath, 'utf-8'));
         }
+        const originalGitignoreContent = gitignoreContent;
         // Check if hublaunch.config.js is already in .gitignore
-        if (!gitignoreContent.includes('hublaunch.config.js')) {
-            // Add entry with comment
-            const newEntry = gitignoreContent.endsWith('\n')
-                ? '# HubLaunch configuration\nhublaunch.config.js\n'
-                : '\n# HubLaunch configuration\nhublaunch.config.js\n';
-            gitignoreContent += newEntry;
-            await import('fs/promises').then((fs) => fs.writeFile(gitignorePath, gitignoreContent, 'utf-8'));
+        const beforeConfig = gitignoreContent;
+        gitignoreContent = appendGitignoreEntry(gitignoreContent, 'hublaunch.config.js', '# HubLaunch configuration', 'hublaunch.config.js');
+        if (gitignoreContent !== beforeConfig) {
             logger.success('✨ Added hublaunch.config.js to .gitignore');
         }
         // Check if worktree base path is already in .gitignore (skip absolute paths — they're outside the repo)
-        if (!isAbsolute(worktreeBasePath) &&
-            !gitignoreContent.includes(worktreeBasePath)) {
-            gitignoreContent += `\n# HubLaunch worktrees\n${worktreeBasePath}/\n`;
+        if (!isAbsolute(worktreeBasePath)) {
+            const beforeWorktree = gitignoreContent;
+            gitignoreContent = appendGitignoreEntry(gitignoreContent, worktreeBasePath, '# HubLaunch worktrees', `${worktreeBasePath}/`);
+            if (gitignoreContent !== beforeWorktree) {
+                logger.success(`✨ Added ${worktreeBasePath}/ to .gitignore`);
+            }
+        }
+        // Ignore the repo-local scratch dir hula-verify writes its report/diff/
+        // comment files into.
+        const beforeTmp = gitignoreContent;
+        gitignoreContent = appendGitignoreEntry(gitignoreContent, '.hublaunch/tmp', '# HubLaunch verify report/diff scratch files', '.hublaunch/tmp/');
+        if (gitignoreContent !== beforeTmp) {
+            logger.success('✨ Added .hublaunch/tmp/ to .gitignore');
+        }
+        if (gitignoreContent !== originalGitignoreContent) {
             await import('fs/promises').then((fs) => fs.writeFile(gitignorePath, gitignoreContent, 'utf-8'));
-            logger.success(`✨ Added ${worktreeBasePath}/ to .gitignore`);
         }
         // Warn if .agents/skills is in .gitignore — it must be committed so all
         // team members get GitHub Copilot and Claude Code support.
@@ -1232,18 +1241,16 @@ ${envVarsLine}${buildPreservedSection(finalConfig)}
     logger.blank();
     logger.info('Generating templates directory structure...');
     await generateTemplatesStructure(repoRoot);
-    // Copy planning instruction templates to .hublaunch/ for skills to reference at runtime
+    // Ensure the .hublaunch/skills/ action-file directory exists. Instruction
+    // documents are no longer copied here — skills read them from the package via
+    // `hula instructions <name>`.
     logger.blank();
-    logger.info('Updating planning instruction templates...');
-    await initializePlanningInstructions(repoRoot, true, true);
+    logger.info('Ensuring .hublaunch/skills/ action directory...');
+    await initializeSkillsActionDir(repoRoot);
     // Initialize Agent Skills for AI-assisted planning (works with Copilot, Claude Code, and others)
     logger.blank();
     logger.info('Setting up Agent Skills for AI-assisted planning...');
-    await initializeAgentSkills(repoRoot);
-    // Initialize bundled shell scripts for chat participant workflows
-    logger.blank();
-    logger.info('Setting up bundled shell scripts for chat workflows...');
-    await initializeScriptFiles(repoRoot);
+    await initializeAgentSkills(repoRoot, options?.withClaudeCommands ?? false);
     // Register the Claude Code session hook (clientSessionId provenance)
     logger.blank();
     logger.info('Registering Claude Code session hook...');
@@ -1254,6 +1261,8 @@ ${envVarsLine}${buildPreservedSection(finalConfig)}
         logger.info('Configuring VS Code auto-approval for hula agent commands...');
         await initVsCodeAutoApproval(repoRoot);
     }
+    // Non-destructive migration notice for repos initialized by an older hula.
+    await noticeObsoleteFiles(repoRoot);
     logger.blank();
     logger.blank();
     logger.info('Next steps:');
@@ -1263,6 +1272,7 @@ ${envVarsLine}${buildPreservedSection(finalConfig)}
     logger.listItem('📝 Edit .hublaunch/hublaunch.config.js to customize (each field is documented inline):', 1);
     logger.listItem('daytonaTier, containerResources — sandbox sizing', 2);
     logger.listItem('teamMembers, envVars — project specifics', 2);
+    logger.listItem('steps — per-pipeline-step model & iteration overrides', 2);
     logger.listItem('updateNotificationUrl, updateNotificationNameTag — Slack notifications', 2);
     // Show credential setup instructions based on selected services
     if (authProvider !== 'none') {
@@ -1278,6 +1288,7 @@ ${envVarsLine}${buildPreservedSection(finalConfig)}
     logger.listItem("Run 'hublaunch create' to create your first issue", 1);
     logger.blank();
     logger.info('💡 Or use the Agent Skills slash commands in any AI chat:');
+    logger.info('   - /hula-help [topic] - Interactive guide: getting started, workflow, commands, config');
     logger.info('   - /hula-plan <description> - Generate implementation plan');
     logger.info('   - /hula-confirm - Validate and refine the plan');
     logger.info('   - /hula-upload - Upload plan to origin/main');