@technomoron/agent-run 0.99.5 → 0.99.7

package/CHANGES

@@ -4,6 +4,16 @@ CHANGES
 Unreleased (2026-04-24)
 -----------------------
 
+Version 0.99.7 (2026-04-26)
+---------------------------
+* Add a checked-in basic starter config under `examples/basic-config` that exercises manifests, templates, snippets, skills, overrides, guardrails, checks, and generated runtime paths.
+* Add `agent-run --init [config-root]` to copy the packaged starter config skeleton to a destination, defaulting to `~/.agent-config`.
+* Replace the placeholder test command with an integration test suite covering the starter config, rendering, checking, stale-file detection, guard shims, local AI-file detection, and flexible command parsing.
+
+Version 0.99.6 (2026-04-26)
+---------------------------
+* Allow `agent-run` to find the target command after wrapper arguments, so invocations like `agent-run --sandboxed --network codex` work the same as `agent-run codex --sandboxed --network`.
+
 Version 0.99.5 (2026-04-25)
 ---------------------------
 * Bootstrap missing default global templates, manifests, local templates, and overrides before `agent-run codex`, `agent-run claude`, or `agent-run update` render a profile.

package/README.md

@@ -165,6 +165,35 @@ Per-profile override templates can be placed in:
 - `overrides/codex-config.toml.njk`
 - `overrides/claude-settings.json.njk`
 
+## Starter Config
+
+A complete starter lives in `examples/basic-config`. It includes a minimal
+project, `.agent-run.env`, a config root with global templates and snippets,
+profile-local templates, skill templates, profile skill overrides, tool config
+overrides, guardrails, checks, and generated runtime paths.
+
+To copy the packaged starter config root into your default config location:
+
+```sh
+agent-run --init
+```
+
+Or choose a destination:
+
+```sh
+agent-run --init ~/.agent-config
+```
+
+The copy skips files that already exist, so local edits are preserved.
+
+Try it from a checkout:
+
+```sh
+pnpm build
+node dist/agent-run.js update examples/basic-config/project
+node dist/agent-run.js check examples/basic-config/project
+```
+
 Check the current repo:
 
 ```sh

package/dist/agent-run.js

@@ -69,6 +69,10 @@ function main(invokedTool, argv) {
         runInit(parsed);
         return;
     }
+    if (parsed.command === 'init-config') {
+        runInitConfig(parsed);
+        return;
+    }
     if (parsed.command === 'edit') {
         runEdit(parsed);
         return;
@@ -93,18 +97,33 @@ function parseInvocation(invokedTool, argv) {
     if (extracted.configRootOverride !== null) {
         process.env[CONFIG_ROOT_OVERRIDE_ENV] = extracted.configRootOverride;
     }
+    if (extracted.initConfig) {
+        if (inputArgs.length > 0) {
+            fail('--init cannot be combined with a command');
+        }
+        return {
+            command: 'init-config',
+            targetPath: path.resolve(extracted.initConfigTargetPath ?? defaultConfigRoot())
+        };
+    }
     if (command === null) {
         if (inputArgs.length === 0) {
             fail('usage: agent-run <codex|claude|check|init|edit|update> [options] (run with --help for details)');
         }
-        const firstArg = inputArgs.shift();
+        const firstArg = inputArgs[0];
         if (isHelpFlag(firstArg)) {
             printHelp('general');
         }
-        command = normalizeCommandName(firstArg ?? '');
-        if (command === null) {
+        const commandIndex = findCommandArgIndex(inputArgs);
+        if (commandIndex === -1) {
             fail(`unknown command: ${firstArg ?? ''} (run with --help for usage)`);
         }
+        const parsedCommand = normalizeCommandName(inputArgs[commandIndex] ?? '');
+        if (parsedCommand === null) {
+            fail(`unknown command: ${firstArg ?? ''} (run with --help for usage)`);
+        }
+        command = parsedCommand;
+        inputArgs.splice(commandIndex, 1);
     }
     if (command === 'check') {
         return parseCheckCommand(inputArgs);
@@ -123,9 +142,23 @@ function parseInvocation(invokedTool, argv) {
     }
     return parseRunCommand(command, inputArgs);
 }
+function findCommandArgIndex(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--') {
+            return -1;
+        }
+        if (normalizeCommandName(arg ?? '') !== null) {
+            return index;
+        }
+    }
+    return -1;
+}
 function extractGlobalOptions(argv) {
     const args = [];
     let configRootOverride = null;
+    let initConfig = false;
+    let initConfigTargetPath = null;
     let verbose = false;
     let passthrough = false;
     for (let index = 0; index < argv.length; index += 1) {
@@ -145,6 +178,15 @@ function extractGlobalOptions(argv) {
             verbose = true;
             continue;
         }
+        if (arg === '--init') {
+            initConfig = true;
+            const nextArg = argv[index + 1];
+            if (nextArg !== undefined && !nextArg.startsWith('-')) {
+                initConfigTargetPath = nextArg;
+                index += 1;
+            }
+            continue;
+        }
         if (arg === '--config-root') {
             const nextArg = argv[index + 1];
             if (nextArg === undefined) {
@@ -164,7 +206,7 @@ function extractGlobalOptions(argv) {
         }
         args.push(arg);
     }
-    return { args, configRootOverride, verbose };
+    return { args, configRootOverride, initConfig, initConfigTargetPath, verbose };
 }
 function parseRunCommand(command, inputArgs) {
     const wrapperArgs = {
@@ -354,6 +396,7 @@ function renderHelp(topic) {
             return [
                 'Usage:',
                 '  agent-run <codex|claude|check|init|edit|update> [options]',
+                '  agent-run --init [config-root]',
                 '',
                 'Commands:',
                 '  codex [--none] [--create] [--danger|--sandboxed] [--network] [args...]',
@@ -369,6 +412,7 @@ function renderHelp(topic) {
                 '  -h, --help         Show this help text',
                 '  -v, --verbose      Print path resolution and wrapper actions',
                 '  --config-root DIR  Override the agent-config root',
+                '  --init [DIR]       Copy the packaged starter config root to DIR (default ~/.agent-config)',
                 '',
                 'Codex wrapper options:',
                 '  --danger           Run Codex with no sandbox: -a never -s danger-full-access (default)',
@@ -464,6 +508,15 @@ function runInit(parsed) {
     const rendered = syncAgentProfile(projectRoot, agentDir);
     printUpdateSummary(rendered);
 }
+function runInitConfig(parsed) {
+    const targetPath = path.resolve(parsed.targetPath);
+    const sourcePath = starterConfigRootPath();
+    if (!fs.existsSync(sourcePath)) {
+        fail(`starter config skeleton not found: ${sourcePath}`);
+    }
+    copySkeletonTree(sourcePath, targetPath);
+    process.stdout.write(`OK copied starter config to ${targetPath}\n`);
+}
 function ensureRunnableProfile(configRoot, agentDir, profile) {
     ensureConfigRootLayout(configRoot);
     ensureConfigRootGitignore(configRoot);
@@ -974,6 +1027,30 @@ function writeGeneratedFile(filePath, content, executable = false) {
     }
     verbose(`write ${filePath}`);
 }
+function starterConfigRootPath() {
+    return path.resolve(__dirname, '..', 'examples', 'basic-config', 'agent-config');
+}
+function copySkeletonTree(sourceDir, targetDir) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const targetName = entry.name === 'gitignore' ? '.gitignore' : entry.name;
+        const targetPath = path.join(targetDir, targetName);
+        if (entry.isDirectory()) {
+            copySkeletonTree(sourcePath, targetPath);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (fs.existsSync(targetPath)) {
+            continue;
+        }
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.copyFileSync(sourcePath, targetPath);
+    }
+}
 function renderProfile(projectRoot, agentDir, checkOnly = false) {
     const configRoot = defaultConfigRoot(projectRoot);
     const profile = resolveProfile(projectRoot);

package/examples/basic-config/README.md

@@ -0,0 +1,22 @@
+# agent-run Basic Config
+
+This directory is a small, copyable starter for a repo that wants to keep
+agent-run files outside the source tree.
+
+It contains two pieces:
+
+- `project/`: a minimal project with `.agent-run.env` pointing at the bundled
+  config root.
+- `agent-config/`: a complete config root with global templates, snippets,
+  skill templates, a profile manifest, profile-local instructions, and profile
+  overrides.
+
+Try it from this repository after building:
+
+```sh
+pnpm build
+node dist/agent-run.js update examples/basic-config/project
+node dist/agent-run.js check examples/basic-config/project
+```
+
+Generated files are written under `examples/basic-config/agent-config/starter/basic-project/`.

package/examples/basic-config/agent-config/gitignore

@@ -0,0 +1,21 @@
+# Generated agent-run files
+**/AGENTS.md
+**/CLAUDE.md
+**/GEMINI.md
+**/config.toml
+
+# Generated native agent homes
+**/.agents/
+**/.claude/
+**/.codex/
+
+# Generated runtime files
+**/bin/
+**/reviews/
+**/memories/
+
+# Generated review reports
+**/REVIEW-*.md
+
+# Optional generated caches
+**/.agent-run-cache/

package/examples/basic-config/agent-config/global/agents/code.md.njk

@@ -0,0 +1,9 @@
+# Starter Code Agent
+
+Project kind: `{{ kind }}`.
+
+{% include "global/snippets/git-rules.md.njk" %}
+
+{% include "global/snippets/no-ai-files.md.njk" %}
+
+{% include "global/snippets/verification.md.njk" %}

package/examples/basic-config/agent-config/global/agents/writing.md.njk

@@ -0,0 +1,5 @@
+# Starter Writing Agent
+
+Write clear project documentation and preserve existing facts.
+
+{% include "global/snippets/no-ai-files.md.njk" %}

package/examples/basic-config/agent-config/global/skills/code-review/SKILL.md.njk

@@ -0,0 +1,12 @@
+---
+name: code-review
+description: Use for reviewing code changes in {{ profile }}.
+---
+
+# Code Review
+
+Write review notes to:
+
+```text
+{{ paths.reviewFile }}
+```

package/examples/basic-config/agent-config/global/skills/commit-workflow/SKILL.md.njk

@@ -0,0 +1,12 @@
+---
+name: commit-workflow
+description: Use when preparing commits for {{ profile }}.
+---
+
+# Commit Workflow
+
+Review changed files before committing. Run:
+
+{% for check in checks %}
+- `{{ check }}`
+{% endfor %}

package/examples/basic-config/agent-config/global/skills/github-release/SKILL.md.njk

@@ -0,0 +1,8 @@
+---
+name: github-release
+description: Use when preparing a release for {{ profile }}.
+---
+
+# GitHub Release
+
+Use `{{ paths.changesFile }}` for release notes. Do not publish without user approval.

package/examples/basic-config/agent-config/global/skills/triage/SKILL.md.njk

@@ -0,0 +1,8 @@
+---
+name: triage
+description: Use for sorting incoming work for {{ profile }}.
+---
+
+# Triage
+
+Classify requests, identify blockers, and name the configured checks that apply.

package/examples/basic-config/agent-config/global/snippets/git-rules.md.njk

@@ -0,0 +1,9 @@
+## Git Rules
+
+Do not commit, tag, or push unless the user explicitly asks for that action.
+
+Guardrails:
+
+- blockGitWrite: `{{ guardrails.blockGitWrite }}`
+- blockPublish: `{{ guardrails.blockPublish }}`
+- blockGithubRelease: `{{ guardrails.blockGithubRelease }}`

package/examples/basic-config/agent-config/global/snippets/no-ai-files.md.njk

@@ -0,0 +1,9 @@
+## Agent File Storage
+
+Keep generated agent files out of the project repository.
+
+Agent directory:
+
+```text
+{{ agentDir }}
+```

package/examples/basic-config/agent-config/global/snippets/verification.md.njk

@@ -0,0 +1,7 @@
+## Verification
+
+Run the configured checks before reporting completion:
+
+{% for check in checks %}
+- `{{ check }}`
+{% endfor %}

package/examples/basic-config/agent-config/global/tool-templates/AGENTS.md.njk

@@ -0,0 +1,20 @@
+# Starter AGENTS for {{ profile }}
+
+Do not edit this generated file. Edit `agent-run.jsonc` and `local.md.njk`.
+
+{% for section in renderedAgentSections %}
+{{ section }}
+
+{% endfor %}
+## Paths
+
+- projectRoot: `{{ projectRoot }}`
+- agentDir: `{{ agentDir }}`
+- reviewFile: `{{ paths.reviewFile }}`
+- memoriesDir: `{{ paths.memoriesDir }}`
+
+## Skills
+
+{% for skill in skills %}
+- `{{ skill.name }}`: {{ skill.description }}
+{% endfor %}

package/examples/basic-config/agent-config/global/tool-templates/CLAUDE.md.njk

@@ -0,0 +1,7 @@
+# Starter CLAUDE for {{ profile }}
+
+{% for section in renderedAgentSections %}
+{{ section }}
+
+{% endfor %}
+Claude reads this file from the private agent directory.

package/examples/basic-config/agent-config/global/tool-templates/claude-settings.json.njk

@@ -0,0 +1,7 @@
+{
+  "env": {
+    "AGENT_DIR": "{{ agentDir }}",
+    "AGENT_RUN_PROJECT_ROOT": "{{ projectRoot }}",
+    "STARTER_PROFILE": "{{ profile }}"
+  }
+}

package/examples/basic-config/agent-config/global/tool-templates/codex-config.toml.njk

@@ -0,0 +1,11 @@
+# Starter global Codex config
+project_doc_max_bytes = 32768
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+writable_roots = [
+  "{{ projectRoot }}",
+  "{{ agentDir }}",
+  "{{ paths.memoriesDir }}"
+]
+network_access = false

package/examples/basic-config/agent-config/starter/basic-project/agent-run.jsonc

@@ -0,0 +1,43 @@
+{
+  "profile": "starter/basic-project",
+  "kind": "code",
+  "agent": {
+    "base": "global/agents/code.md.njk",
+    "includes": [
+      "{{ profile }}/local.md.njk",
+      "{{ profile }}/project-rules.md.njk"
+    ]
+  },
+  "skills": {
+    "install": [
+      "commit-workflow",
+      "github-release",
+      "code-review",
+      "triage"
+    ],
+    "overrides": {
+      "triage": "{{ profile }}/overrides/triage.SKILL.md.njk"
+    }
+  },
+  "tools": {
+    "codex": true,
+    "claude": true
+  },
+  "checks": [
+    "agent-run check .",
+    "pnpm run cleanbuild",
+    "pnpm test"
+  ],
+  "guardrails": {
+    "blockGitWrite": true,
+    "blockPublish": true,
+    "blockGithubRelease": true,
+    "forbidRepoAiFiles": true
+  },
+  "paths": {
+    "changesFile": "{{ projectRoot }}/CHANGES",
+    "reviewDir": "{{ agentDir }}/reviews",
+    "reviewFile": "{{ agentDir }}/reviews/REVIEW-{{ date }}.md",
+    "memoriesDir": "{{ agentDir }}/memories"
+  }
+}

package/examples/basic-config/agent-config/starter/basic-project/local.md.njk

@@ -0,0 +1,5 @@
+## Local Project Instructions
+
+This starter profile belongs to `{{ profile }}`.
+
+Use the project root at `{{ projectRoot }}` and keep generated files in `{{ agentDir }}`.

package/examples/basic-config/agent-config/starter/basic-project/overrides/claude-settings.json.njk

@@ -0,0 +1,8 @@
+{
+  "env": {
+    "AGENT_DIR": "{{ agentDir }}",
+    "AGENT_RUN_PROJECT_ROOT": "{{ projectRoot }}",
+    "STARTER_PROFILE": "{{ profile }}",
+    "STARTER_OVERRIDE": "true"
+  }
+}

package/examples/basic-config/agent-config/starter/basic-project/overrides/codex-config.toml.njk

@@ -0,0 +1,11 @@
+# Starter profile Codex override
+project_doc_max_bytes = 65536
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+writable_roots = [
+  "{{ projectRoot }}",
+  "{{ agentDir }}",
+  "{{ paths.memoriesDir }}"
+]
+network_access = false

package/examples/basic-config/agent-config/starter/basic-project/overrides/triage.SKILL.md.njk

@@ -0,0 +1,12 @@
+---
+name: triage
+description: Use this profile-specific triage workflow for {{ profile }}.
+---
+
+# Starter Triage
+
+Use the project checks from this profile before closing out:
+
+{% for check in checks %}
+- `{{ check }}`
+{% endfor %}

package/examples/basic-config/agent-config/starter/basic-project/project-rules.md.njk

@@ -0,0 +1,5 @@
+## Project Rules
+
+- Prefer small, reviewed changes.
+- Keep release notes in `{{ paths.changesFile }}`.
+- Store durable notes in `{{ paths.memoriesDir }}`.

package/examples/basic-config/project/.agent-run.env

@@ -0,0 +1,2 @@
+AGENT_CONFIG_DIR=../agent-config
+AGENT_RUN_PROFILE=starter/basic-project

package/examples/basic-config/project/CHANGES

@@ -0,0 +1,7 @@
+CHANGES
+=======
+
+Unreleased
+----------
+
+* Starter project.

package/examples/basic-config/project/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@starter/basic-project",
+  "private": true,
+  "scripts": {
+    "cleanbuild": "echo cleanbuild",
+    "test": "echo test"
+  }
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@technomoron/agent-run",
-  "version": "0.99.5",
+  "version": "0.99.7",
   "packageManager": "pnpm@10.28.1",
   "bin": {
     "agent-run": "dist/agent-run.js"
   },
   "files": [
     "dist/",
+    "examples/",
     "README.md",
     "LICENSE",
     "CHANGES"
@@ -21,7 +22,8 @@
     "clean:dist": "rimraf ./dist/",
     "cleanbuild": "run-s clean:dist build",
     "prepack": "run-s build",
-    "test": "echo 'No tests for agent-run'",
+    "test": "run-s build test:integration",
+    "test:integration": "bash ./scripts/test.sh",
     "release": "bash ./scripts/release.sh",
     "release:check": "bash ./scripts/release-check.sh",
     "release:preflight": "pnpm cleanbuild && pnpm test && pnpm release:check -- --local",