@r3dlex/ai-catapult 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andre Burgstahler (r3dlex)
+
+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.md

@@ -0,0 +1,139 @@
+# ai-catapult
+
+Scaffold [init-ai-repo v3 AI-SDLC governance](https://github.com/r3dlex/init-ai-repo) into any repository — no LLM required, no config needed, one command.
+
+## What it does
+
+`ai-catapult` is a deterministic CLI that writes a complete v3 `.ai/` governance skeleton into your repo: directory structure, matrix, system prompts, rules, workflows, traceability wiring, and agent contracts. It also ships as a **Claude Code plugin** and a **Codex plugin** so the scaffold runs from inside your AI coding agent without leaving your editor.
+
+It repackages the `init-ai-repo`/`ai-catapult-init` skill as a standalone tool — same output, zero dependency on a running LLM session.
+
+## Quick start
+
+```sh
+# Scaffold governance skeleton into the current directory
+npx ai-catapult init
+
+# Then install the plugin into detected harnesses (Claude Code and/or Codex)
+npx ai-catapult install
+```
+
+Or install globally:
+
+```sh
+npm install -g ai-catapult
+ai-catapult init
+ai-catapult install
+```
+
+## Commands
+
+### `ai-catapult init [target]`
+
+Scaffold the mechanical v3 `.ai/` governance skeleton into `<target>` (default: current directory).
+
+```
+Options:
+  --repo-id <id>         Repository identifier          (default: basename of target)
+  --date <YYYY-MM-DD>    Scaffold date token             (default: today)
+  --upstream-url <url>   Upstream git URL for matrix.json
+  --upstream-ref <ref>   Upstream git ref                (default: main)
+  --force                Overwrite existing files without error
+  -h, --help             Show help
+```
+
+### `ai-catapult install`
+
+Install the ai-catapult plugin into detected AI coding harnesses.
+
+Harnesses detected automatically:
+- **Claude Code** — `~/.claude/` present
+- **Codex** — `${CODEX_HOME:-~/.codex}/` present
+
+```
+Options:
+  --harness <claude|codex|all>   Select harness(es) (default: auto-detect)
+  --dry-run                      Print what would happen without writing
+  --force                        Overwrite even if dir contains a foreign plugin
+  -h, --help                     Show help
+```
+
+After install, reload Claude Code and run `/ai-catapult-init` to complete the in-harness judgment-laden phases.
+
+## Claude Code plugin
+
+`ai-catapult` ships as a Claude Code plugin bundling the `ai-catapult-init` skill.
+
+### Install path
+
+Running `npx ai-catapult install` copies the plugin payload to:
+```
+~/.claude/plugins/ai-catapult/
+```
+
+Then follow the printed two-step registration inside Claude Code:
+```
+/plugin marketplace add ~/.claude/plugins/ai-catapult
+/plugin install ai-catapult@ai-catapult-local
+```
+
+The installer does **not** write `installed_plugins.json` — that is a Claude Code internal file. Use the `/plugin` commands above to register the plugin.
+
+### Build the plugin locally
+
+```sh
+bash setup.sh                  # vendor the pinned skill source
+npm run build:plugin:claude    # assemble into dist/claude-plugin/
+```
+
+## Codex plugin
+
+`ai-catapult` ships as a Codex plugin bundling the `ai-catapult-init` skill.
+
+### Install path
+
+Running `npx ai-catapult install` copies the plugin payload to:
+```
+${CODEX_HOME:-~/.codex}/plugins/cache/ai-catapult-local/ai-catapult/local/
+```
+
+Then add the printed TOML block to your `${CODEX_HOME:-~/.codex}/config.toml`:
+```toml
+[marketplaces.ai-catapult-local]
+source_type = "local"
+source = "<printed payload path>"
+
+[plugins."ai-catapult@ai-catapult-local"]
+enabled = true
+```
+
+The installer does **not** auto-mutate `config.toml` — you add the block manually. See [docs/codex-install.md](docs/codex-install.md) for details.
+
+### Build the plugin locally
+
+```sh
+bash setup.sh                  # vendor the pinned skill source
+npm run build:plugin:codex     # assemble into dist/codex-plugin/
+```
+
+## Publishing
+
+Both `ai-catapult` (unscoped) and `@r3dlex/ai-catapult` (scoped mirror) are published to npm.
+
+### Dry-run (safe, default)
+
+```sh
+bash scripts/publish-both.sh
+```
+
+### Real publish (double-gated)
+
+```sh
+AI_CATAPULT_PUBLISH=1 bash scripts/publish-both.sh --yes
+```
+
+Semver-tagged releases are automated via `.github/workflows/release.yml` (requires `NPM_TOKEN` in repo secrets).
+
+## License
+
+MIT © Andre Burgstahler (r3dlex)

package/bin/ai-catapult.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve, basename } from 'node:path';
+import { scaffold } from '../src/scaffold.js';
+import { runInstall } from '../src/install.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const VENDOR_TEMPLATES = join(__dirname, '..', 'vendor/skills/ai-catapult-init/templates');
+
+const HELP = `Usage: ai-catapult <command> [options]
+
+Commands:
+  init [target]  Scaffold v3 .ai/ governance skeleton into <target> (default: cwd)
+  install        Install Claude Code and Codex plugins into detected harnesses
+
+Options:
+  -v, --version  Print version
+  -h, --help     Show this help`;
+
+const INIT_HELP = `Usage: ai-catapult init [target] [options]
+
+Scaffold the mechanical v3 .ai/ governance skeleton into <target>.
+No LLM required. Judgment-laden content is deferred to the in-harness plugin.
+
+Arguments:
+  target               Directory to scaffold into (default: current directory)
+
+Options:
+  --repo-id <id>         Repository identifier, e.g. "my-repo"     (default: basename of target)
+  --date <YYYY-MM-DD>    Scaffold date token                        (default: today)
+  --upstream-url <url>   Upstream git URL for matrix.json           (default: "")
+  --upstream-ref <ref>   Upstream git ref for matrix.json           (default: "main")
+  --force                Overwrite existing files without error
+  -h, --help             Show this help`;
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse flags from an argv array (already sliced past [node, script]).
+ * Returns { positionals: string[], flags: Map<string, string|boolean>, firstPositionalIdx: number }
+ * --foo bar   → flags.get('foo') === 'bar'
+ * --foo       → flags.get('foo') === true
+ * -h          → flags.get('h') === true
+ */
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = new Map();
+  // Track the raw index of the first positional in argv (for subcommand slicing)
+  let firstPositionalIdx = -1;
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--') {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        flags.set(key, next);
+        i += 2;
+      } else {
+        flags.set(key, true);
+        i += 1;
+      }
+    } else if (arg.startsWith('-') && arg.length === 2) {
+      flags.set(arg.slice(1), true);
+      i += 1;
+    } else {
+      if (firstPositionalIdx === -1) firstPositionalIdx = i;
+      positionals.push(arg);
+      i += 1;
+    }
+  }
+  return { positionals, flags, firstPositionalIdx };
+}
+
+// ---------------------------------------------------------------------------
+// Finish prompt builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the structured next-steps block shown to the user after a successful
+ * scaffold. Content is deterministic given same inputs.
+ *
+ * @param {object} opts
+ * @param {string}   opts.targetDir           - resolved absolute target path (used in "scaffolded into" line)
+ * @param {string}   opts.pathDisplay         - base used for anchor path bullet lines (e.g. targetDir for
+ *                                              stdout, '.' for the file so it stays machine-independent)
+ * @param {string[]} opts.emittedPaths         - relative paths actually written
+ * @param {string[]} opts.judgmentLadenPaths   - from boundary-manifest.json
+ * @returns {string}
+ */
+function buildFinishPrompt({ targetDir, pathDisplay, emittedPaths, judgmentLadenPaths }) {
+  // Pick two anchor paths that are always mechanical (existence already verified
+  // by scaffold — if they are missing scaffold would have failed earlier).
+  const matrixPath = emittedPaths.includes('.ai/matrix.json') ? '.ai/matrix.json' : emittedPaths[0] ?? null;
+  const agentsPath = emittedPaths.includes('AGENTS.md') ? 'AGENTS.md' : null;
+
+  const anchorLines = [];
+  if (matrixPath) anchorLines.push(`  • ${pathDisplay}/${matrixPath}`);
+  if (agentsPath) anchorLines.push(`  • ${pathDisplay}/${agentsPath}`);
+
+  const jlLines = judgmentLadenPaths.map((p) => `  • ${p}`).join('\n');
+
+  return [
+    '╔══════════════════════════════════════════════════════════════╗',
+    '║          ai-catapult — scaffold complete                     ║',
+    '╚══════════════════════════════════════════════════════════════╝',
+    '',
+    'Mechanical v3 skeleton scaffolded into:',
+    `  ${pathDisplay}`,
+    '',
+    'Key emitted paths (verified on disk):',
+    ...anchorLines,
+    '',
+    'Judgment-laden phases NOT yet written (require in-harness plugin):',
+    jlLines,
+    '',
+    '── Next step: complete in-harness ─────────────────────────────',
+    '',
+    '1. Install the ai-catapult plugin:',
+    '     npx ai-catapult install',
+    '',
+    '2. Open the scaffolded repo in Claude Code or Codex, then run:',
+    '     Claude Code:  /ai-catapult-init',
+    '     Codex:        invoke the ai-catapult-init skill',
+    '',
+    'The ai-catapult-init skill will guide you through topology decisions,',
+    'ADRs, cascade configuration, and traceability — the judgment-laden',
+    'phases that require knowledge of your specific repository.',
+    '────────────────────────────────────────────────────────────────',
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand: init
+// ---------------------------------------------------------------------------
+
+function runInit(argv) {
+  const { positionals, flags } = parseArgs(argv);
+
+  if (flags.has('help') || flags.has('h')) {
+    console.log(INIT_HELP);
+    process.exit(0);
+  }
+
+  const targetDir = positionals[0] ? resolve(positionals[0]) : process.cwd();
+  const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+
+  const repoId = String(flags.get('repo-id') || basename(targetDir));
+  const date = String(flags.get('date') || today);
+  const upstreamUrl = String(flags.get('upstream-url') || '');
+  const upstreamRef = String(flags.get('upstream-ref') || 'main');
+  const force = flags.has('force');
+
+  const { emittedPaths, judgmentLadenPaths } = scaffold({
+    targetDir, templatesDir: VENDOR_TEMPLATES, repoId, date, upstreamUrl, upstreamRef, force,
+  });
+
+  // Build finish prompt for stdout — uses absolute targetDir so the user sees
+  // real paths they can open directly.
+  const finishPromptStdout = buildFinishPrompt({ targetDir, pathDisplay: targetDir, emittedPaths, judgmentLadenPaths });
+
+  // Emit to stdout.
+  process.stdout.write(finishPromptStdout + '\n');
+
+  // Build finish prompt for the file — uses '.' as the path base so the file
+  // contains only relative paths and is byte-identical across machines/CI runs.
+  const finishPromptFile = buildFinishPrompt({ targetDir, pathDisplay: '.', emittedPaths, judgmentLadenPaths });
+
+  // Write to <target>/.ai/handoff/NEXT-STEPS.md.
+  // Safe to write unconditionally: scaffold's collision guard has already run
+  // and would have exited 1 on mechanical collisions before reaching this line.
+  const nextStepsPath = join(targetDir, '.ai/handoff/NEXT-STEPS.md');
+  mkdirSync(dirname(nextStepsPath), { recursive: true });
+  writeFileSync(nextStepsPath, finishPromptFile, 'utf8');
+}
+
+// runInstall is imported from src/install.js
+
+// ---------------------------------------------------------------------------
+// Main dispatch
+// ---------------------------------------------------------------------------
+
+const rawArgv = process.argv.slice(2);
+const { positionals: topPositionals, flags: topFlags, firstPositionalIdx } = parseArgs(rawArgv);
+
+if (topFlags.has('version') || topFlags.has('v')) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const verb = topPositionals[0];
+
+// Global --help/-h only when no verb is given; with a verb the subcommand
+// handles its own --help flag.
+if (!verb && (topFlags.has('help') || topFlags.has('h') || rawArgv.length === 0)) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+// No verb and no global flag already handled above; bare invocation → help.
+if (!verb) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (verb === 'init') {
+  // Fix #2: use firstPositionalIdx (the index of 'init' in rawArgv) rather than
+  // rawArgv.indexOf('init'), which would match the first literal 'init' anywhere
+  // — e.g. `ai-catapult --date init init <target>` would mis-dispatch to ./init.
+  runInit(rawArgv.slice(firstPositionalIdx + 1));
+  process.exit(0);
+}
+
+if (verb === 'install') {
+  runInstall(rawArgv.slice(firstPositionalIdx + 1));
+  process.exit(0);
+}
+
+process.stderr.write(`Unknown argument: ${verb}. Run ai-catapult --help for usage.\n`);
+process.exit(1);

package/dist/claude-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "ai-catapult",
+  "description": "Scaffold init-ai-repo v3 AI-SDLC governance — deterministic, no LLM required",
+  "owner": {
+    "name": "r3dlex"
+  },
+  "plugins": [
+    {
+      "name": "ai-catapult",
+      "description": "Scaffold init-ai-repo v3 AI-SDLC governance into any repository. One command, zero config, no LLM required. Provides the ai-catapult-init skill for Claude Code.",
+      "version": "0.1.0",
+      "author": {
+        "name": "r3dlex"
+      },
+      "source": "./",
+      "category": "productivity",
+      "homepage": "https://github.com/r3dlex/ai-catapult",
+      "tags": [
+        "ai-sdlc",
+        "governance",
+        "scaffold",
+        "init-ai-repo"
+      ]
+    }
+  ],
+  "version": "0.1.0"
+}

package/dist/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "ai-catapult",
+  "version": "0.1.0",
+  "description": "Scaffold init-ai-repo v3 AI-SDLC governance into any repository — no LLM required, one command. Ships as a Claude Code skill.",
+  "author": {
+    "name": "r3dlex"
+  },
+  "repository": "https://github.com/r3dlex/ai-catapult",
+  "homepage": "https://github.com/r3dlex/ai-catapult",
+  "license": "MIT",
+  "keywords": [
+    "ai-sdlc",
+    "governance",
+    "scaffold",
+    "init-ai-repo",
+    "claude-code"
+  ],
+  "skills": [
+    "./skills/ai-catapult-init/"
+  ]
+}