omniagent 0.1.2 → 0.1.4

package/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+This document is for contributors and maintainers working on the `omniagent` codebase.
+
+If you are using `omniagent` as an npm package consumer, start with [`README.md`](README.md).
+
+## Local Setup
+
+- Node.js 18+
+- npm
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+## Local Validation
+
+Run the same checks used by CI before opening a PR:
+
+```bash
+npm run check
+npm run typecheck
+npm test
+npm run build
+```
+
+## Docs Changes
+
+When updating docs, keep root `README.md` consumer-focused.
+
+- End-user usage and product behavior belong in `README.md` and `docs/*.md`.
+- Development and contribution workflows belong in `CONTRIBUTING.md`.
+- Update docs assertions in `tests/docs/readme.test.ts` when docs architecture changes.
+
+## CLI Shim E2E (Contributor Workflow)
+
+CLI shim E2E is a contributor-only verification flow and is not required for normal package usage.
+
+Detailed guide:
+
+- [`docs/cli-shim-e2e.md`](docs/cli-shim-e2e.md)
+
+Quick commands:
+
+```bash
+# Build first
+npm run build
+
+# Record baseline outputs from real CLIs
+OA_E2E_RECORD_BASELINE=1 npm test -- tests/e2e/cli-shim/cli-shim.e2e.test.ts
+
+# Compare shim output to recorded baselines
+OA_E2E=1 npm test -- tests/e2e/cli-shim/cli-shim.e2e.test.ts
+```

package/README.md

@@ -1,339 +1,168 @@
 # omniagent
 
-One config, many agents.
+One source of truth for agent config across Claude, Codex, Gemini, and Copilot (and [any other agent](docs/custom-targets.md))
 
-omniagent lets teams stay in sync while everyone uses their tool of choice. Define agent
-content once and sync it to Claude Code, OpenAI Codex, GitHub Copilot CLI, and Gemini CLI.
+Define canonical agent files once in `agents/`, then run `sync` to compile target-specific outputs.
 
-```text
-# Before (manual drift)
-.claude/agents/release-helper.md
-.codex/skills/release-helper/SKILL.md
-.gemini/skills/release-helper/SKILL.md
-.copilot/skills/release-helper/SKILL.md
-
-# After (single source of truth)
-agents/agents/release-helper.md
-npx omniagent@latest sync
-```
+- Teams can keep one shared agent configuration while each teammate uses their preferred CLI.
+- Agent enthusiasts can try out the newest agents, and switch back, without manually porting all their config.
 
-## Quick start
+![Sync hero image](./design/sync-hero-image/output/sv-cast-with-agents.png)
 
-Create a Claude subagent once, then sync everywhere:
+## Quickstart
+
+Author once in `agents/`, sync everywhere.
+
+Subagents example:
+
+```md
+# ./agents/agents/release-helper.md
 
-```bash
-mkdir -p agents/agents
-cat > agents/agents/release-helper.md <<'AGENT'
 ---
+
 name: release-helper
 description: "Help draft release plans and checklists."
+
 ---
-Draft a release plan with milestones and owners.
-AGENT
 
-npx omniagent@latest sync --only claude,codex,gemini,copilot
+Draft a release plan with milestones and owners.
 ```
 
-Outputs:
+Codex does not support subagents. Omniagent
+converts the canonical file into Codex's skill format (and the equivalent format for other
+supported CLIs).
+
+After `sync`, outputs include:
 
 ```text
-.claude/agents/release-helper.md
-.codex/skills/release-helper/SKILL.md
-.gemini/skills/release-helper/SKILL.md
-.copilot/skills/release-helper/SKILL.md
+.claude/
+  agents/
+    release-helper.md
+.codex/
+  skills/
+    release-helper/
+      SKILL.md
 ```
 
-Only Claude supports native subagents. Other targets receive converted skills so they still work.
+## How It Works
 
-## CLI shim (interactive + one-shot)
+1. Author canonical sources in `agents/` (and optional repo `AGENTS.md`).
+2. Run `omniagent sync`.
+3. Omniagent writes target-specific files, converting unsupported surfaces when needed.
 
-`omniagent` without a subcommand acts as a shim to agent CLIs. Select an agent explicitly with
-`--agent` or set a `defaultAgent` in `agents/omniagent.config.*`.
+## Common Commands
 
 ```bash
-# Interactive (default)
-omniagent --agent codex
-
-# One-shot prompt
-omniagent -p "Summarize the repo" --agent codex --output json
-
-# Piped stdin
-echo "Summarize the repo" | omniagent --agent codex
-
-# Passthrough to agent CLI
-omniagent --agent codex -- --some-agent-flag --model gpt-5
-```
-
-Shared flags:
-
-- `--approval <prompt|auto-edit|yolo>` (aliases: `--auto-edit`, `--yolo`)
-- `--sandbox <workspace-write|off>` (defaults to `off` when `--yolo` is set and `--sandbox` is
-  not explicit)
-- `--output <text|json|stream-json>` (aliases: `--json`, `--stream-json`)
-- `--model <name>`
-- `--web <on|off|true|false|1|0>` (bare `--web` enables)
-
-Notes:
-
-- `--` passthrough is only valid after `--agent`.
-- Unsupported shared flags emit a warning and are ignored.
-- Agent output is passed through unmodified for all output formats.
-- Some approval values are agent-specific (for example, Claude ignores `--approval auto-edit`
-  and warns).
-- Output formats are only supported in one-shot mode for agents that expose them; interactive runs
-  warn when explicitly set.
-
-### Shared-flag capability matrix
-
-| Agent   | Approval | Sandbox | Output | Model | Web |
-|---------|----------|---------|--------|-------|-----|
-| codex   | ✓        | ✓       | ✓      | ✓     | ✓   |
-| claude  | ✓        | ✗       | ✓      | ✓     | ✗   |
-| gemini  | ✓        | ✓       | ✓      | ✓     | ✓   |
-| copilot | ✓        | ✗       | ✗      | ✓     | ✗   |
+# Sync all supported agent CLIs installed on your system
+npx omniagent@latest sync
 
-## What you can sync
+# Sync specific targets
+npx omniagent@latest sync --only claude,codex
 
-### Subagents (Claude format → converted skills elsewhere)
+# Skip a target for this run
+npx omniagent@latest sync --skip codex
 
-```text
-agents/agents/release-helper.md
----
-name: release-helper
-description: "Help draft release plans and checklists."
----
-Draft a release plan with milestones and owners.
-```
+# Use a non-default agents directory
+npx omniagent@latest sync --agentsDir ./my-custom-agents
 
-### Skills
+# Show local-only overrides and exit
+npx omniagent@latest sync --list-local
 
-```text
-agents/skills/review-helper/SKILL.md
-You are a reviewer. Focus on risks, edge cases, and missing tests.
+# Shim mode (no subcommand)
+omniagent --agent codex
+omniagent -p "Summarize this repo" --agent codex --output json
 ```
 
-### Slash commands
+## Local Overrides (`.local`)
 
-```text
-agents/commands/review.md
----
-description: "Review a diff with a strict checklist."
----
-Summarize issues by severity with file/line references.
-```
-
-### Instruction files
+Use `.local` files for personal variants that should not become team defaults.
 
 ```text
-AGENTS.md
-Global team instructions for all agents.
+agents/
+  AGENTS.local.md    # opinionated personal override
+  commands/
+    deploy.md        # committed to git
+    deploy.local.md  # opinionated personal override
+  skills/
+    ppt/
+      SKILL.md       # committed to git
+      SKILL.local.md # opinionated personal override
 ```
 
-## How it works
-
-1. Author canonical files in `agents/` (and/or repo `AGENTS.md`).
-2. Run `omniagent sync`.
-3. Omniagent writes the right files for each target tool.
-
-## Supported targets
-
-- Claude Code (native subagents + skills + slash commands)
-- OpenAI Codex (skills + global slash-command prompts; subagents converted to skills)
-- GitHub Copilot CLI (skills; slash commands + subagents converted to skills)
-- Gemini CLI (skills require `experimental.skills`; slash commands project/global;
-  subagents converted to skills)
-
-## Repo layout (canonical sources)
+`./agents/.local/` is also supported. This can be used for libraries for your personal tooling, that should not be shared with the team:
 
 ```text
 agents/
-  agents/        # subagents (Claude format)
-  skills/        # skills (one folder per skill)
-  commands/      # slash commands
-  .local/        # personal overrides (ignored in outputs)
-AGENTS.md        # repo-wide instructions (optional)
+  .local/
+    commands/my-personal-command.md
+    skills/my-personal-skill/SKILL.md
 ```
 
-Default agents directory is `agents/`. Override it with `--agentsDir` (relative to the project
-root, or an absolute path).
-
-## Use cases
-
-- **Keep a team-wide review assistant consistent** while each person uses their preferred tool.
-- **Ship one release-helper subagent** that works everywhere.
-- **Avoid tool wars** by supporting Claude, Codex, Gemini, and Copilot from one source of truth.
-- **Layer personal tweaks** without polluting the repo using `.local` overrides.
-
-## Requirements
-
-- Node.js 18+
-
-## Local validation
-
-Run the same steps as CI:
-
-1. `npm ci`
-2. `npm run check`
-3. `npm run typecheck`
-4. `npm test`
-5. `npm run build`
+If a `.local` item matches a shared item name, the local item wins for your sync run. Generated
+outputs do not keep the `.local` suffix.
 
-## Advanced
+Use `--list-local` to see active local items, or `--exclude-local` to ignore them for a run.
 
-### Targeting via frontmatter
+Example `.gitignore` entries:
 
-```yaml
----
-name: release-helper
-targets: [claude, gemini]
----
+```gitignore
+agents/.local/
+agents/**/*.local*
 ```
 
-- `targets` / `targetAgents`: `claude`, `gemini`, `codex`, `copilot`.
-- `name`: overrides filename when supported.
-- `description`: optional metadata.
-
-### Custom targets (omniagent.config.*)
-
-Define custom targets in the agents directory. The CLI auto-discovers the first match in:
-`omniagent.config.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`.
-
-```ts
-const config = {
-	targets: [
-		{
-			id: "acme",
-			displayName: "Acme Agent",
-			outputs: {
-				skills: "{repoRoot}/.acme/skills/{itemName}",
-				subagents: "{repoRoot}/.acme/agents/{itemName}.md",
-				commands: {
-					projectPath: "{repoRoot}/.acme/commands/{itemName}.md",
-					userPath: "{homeDir}/.acme/commands/{itemName}.md",
-				},
-				instructions: "AGENTS.md",
-			},
-		},
-	],
-	disableTargets: ["copilot"],
-};
-
-export default config;
-```
+## Basic Templating
 
-- Built-in IDs require `override: true` or `inherits: "claude"` to avoid collisions.
-- `disableTargets` removes built-ins from the active target set.
-- Placeholders: `{repoRoot}`, `{homeDir}`, `{agentsDir}`, `{targetId}`, `{itemName}`,
-  `{commandLocation}`.
-- When multiple targets resolve to the same output file, default writers handle
-  skills/subagents/instructions. Command collisions are errors.
+Use `<agents ...>` blocks when some text should render only for specific targets.
 
-### Instruction templates (per-target outputs)
+```md
+Shared guidance for all targets.
 
-```text
-/agents/guide.AGENTS.md
----
-outPutPath: docs/
----
-<agents include="claude,gemini">
-# Team Instructions
+<agents claude,codex>
+Extra instructions only for Claude and Codex.
 </agents>
 ```
 
-- Templates live under `/agents/**` and can target specific outputs.
-- `outPutPath` is treated as a directory; filename is ignored if supplied.
-
-### Local overrides (personal, never synced)
-
-```text
-agents/commands/deploy.local.md
-agents/skills/review-helper.local/SKILL.md
-```
-
-Local items override shared items with the same name. Outputs never include `.local`.
-
-### Agent-scoped templating
-
-```text
-Shared content.
-
-<agents claude,codex>
-Only Claude and Codex see this.
-</agents>
+For advanced templating and dynamic scripts (`<nodejs>`, `<shell>`), see
+[`docs/templating.md`](docs/templating.md).
 
-<agents not:claude,gemini>
-Everyone except Claude and Gemini see this.
-</agents>
-```
+## Agent CLI Shim
 
-### Dynamic template scripts (`<nodejs>` and `<shell>`)
+Omniagent provides a CLI shim (`omniagent` without a subcommand) for working with agent CLIs via a unified interface.
 
-`sync` can execute inline script blocks in canonical templates before agent templating/rendering.
+This can be useful for CI/CD and shell scripts, while maintaining full portability between agents:
 
-Node.js blocks evaluate JavaScript and inject the returned value:
+```bash
+# code-review.sh
+#!/usr/bin/env bash
+set -euo pipefail
+agent="${1:-claude}"
 
-```md
-Current docs:
-<nodejs>
-const fs = require("node:fs");
-const path = require("node:path");
-
-const docsDir = path.join(process.cwd(), "docs");
-const pages = fs
-  .readdirSync(docsDir)
-  .filter((name) => name.endsWith(".md"))
-  .sort();
-
-return pages.map((name) => `- ${name}`).join("\n");
-</nodejs>
+omniagent -p "Perform comprehensive code review for this branch against main" --agent "$agent"
 ```
 
-Shell blocks execute in the user's shell and inject stdout:
+Example usage:
 
-```md
-Current docs:
-<shell>
-for file in docs/*.md; do
-  [ -f "$file" ] || continue
-  printf -- "- %s\n" "$(basename "$file")"
-done | sort
-</shell>
+```bash
+./code-review.sh
+./code-review.sh codex
 ```
 
-Behavior:
+## Documentation
 
-- Scripts run once per template per sync run and cached results are reused across targets.
-- Each script block runs in an isolated process (Node subprocess for `<nodejs>`, shell process for `<shell>`).
-- `<nodejs>` blocks can use `require`, `__dirname`, and `__filename`.
-- `<shell>` blocks run with the user's shell (`$SHELL` on Unix, `cmd.exe` on Windows fallback).
-- `<nodejs>` return values are normalized as: string unchanged, object/array JSON text, other values via
-  `String(value)`, `null`/`undefined` as empty output.
-- `<shell>` blocks render raw stdout.
-- Static template text around script blocks is preserved.
-- Script failures stop sync before managed writes are applied.
-- Long-running scripts emit periodic `still running` warnings every 30 seconds.
-- Routine per-script telemetry is quiet by default and shown only with `sync --verbose`.
+- Docs index: [`docs/README.md`](docs/README.md)
+- Getting started: [`docs/getting-started.md`](docs/getting-started.md)
+- Sync basics: [`docs/sync-basics.md`](docs/sync-basics.md)
+- CLI shim details: [`docs/cli-shim.md`](docs/cli-shim.md)
+- Custom targets (custom agents): [`docs/custom-targets.md`](docs/custom-targets.md)
+- Local overrides: [`docs/local-overrides.md`](docs/local-overrides.md)
+- Templating and dynamic scripts: [`docs/templating.md`](docs/templating.md)
+- Command reference: [`docs/reference.md`](docs/reference.md)
+- Troubleshooting: [`docs/troubleshooting.md`](docs/troubleshooting.md)
 
-## CLI reference
+## Requirements
 
-```bash
-npx omniagent@latest sync
-npx omniagent@latest sync --only claude
-npx omniagent@latest sync --skip codex
-npx omniagent@latest sync --exclude-local
-npx omniagent@latest sync --exclude-local=skills,commands
-npx omniagent@latest sync --agentsDir ./my-custom-agents
-npx omniagent@latest sync --list-local
-npx omniagent@latest sync --yes
-npx omniagent@latest sync --verbose
-npx omniagent@latest sync --json
-```
+- Node.js 18+
 
-Run-level overrides:
+## Contributing
 
-- `--only` replaces per-file frontmatter defaults for this run.
-- `--skip` filters the active target set (frontmatter defaults or all targets).
-- `--exclude-local` omits local sources entirely (or only for the listed categories).
-- `--list-local` prints detected local items and exits.
-- `--agentsDir` points to the agents directory (default `agents/`, resolved from the repo root).
-- If both are provided, `--only` applies first, then `--skip`.
+Development and test workflows are documented in [`CONTRIBUTING.md`](CONTRIBUTING.md).

package/dist/cli.js

@@ -826,7 +826,7 @@ const codexTarget = {
       fallback: { mode: "convert", targetType: "skills" }
     },
     commands: {
-      userPath: "{homeDir}/.codex/prompts/{itemName}.md"
+      fallback: { mode: "convert", targetType: "skills" }
     },
     instructions: {
       filename: "AGENTS.md",
@@ -4653,12 +4653,18 @@ async function syncSlashCommands(request) {
   const managedManifest = await readManagedOutputs(request.repoRoot, homeDir) ?? { entries: [] };
   const nextManaged = /* @__PURE__ */ new Map();
   const activeOutputPaths = /* @__PURE__ */ new Set();
+  const activeSourcesWithOutputs = /* @__PURE__ */ new Map();
   const countsByTarget = /* @__PURE__ */ new Map();
   const getCounts = (targetId) => {
     const existing = countsByTarget.get(targetId) ?? emptyResultCounts();
     countsByTarget.set(targetId, existing);
     return existing;
   };
+  const recordSourceOutput = (targetId, sourceId) => {
+    const sources = activeSourcesWithOutputs.get(targetId) ?? /* @__PURE__ */ new Set();
+    sources.add(sourceId);
+    activeSourcesWithOutputs.set(targetId, sources);
+  };
   const converterRegistry = /* @__PURE__ */ new Map();
   const writerRegistry = /* @__PURE__ */ new Map();
   const validAgents = request.validAgents ?? buildSupportedAgentNames(request.targets);
@@ -4812,6 +4818,7 @@ async function syncSlashCommands(request) {
       const managedKey = buildManagedOutputKey(entry2);
       nextManaged.set(managedKey, entry2);
       activeOutputPaths.add(normalizeManagedOutputPath(entry2.outputPath));
+      recordSourceOutput(entry2.targetId, entry2.sourceId);
     };
     const counts = getCounts(target.id);
     let converterActive = false;
@@ -4997,16 +5004,18 @@ async function syncSlashCommands(request) {
       if (nextManaged.has(key)) {
         continue;
       }
+      const outputKey = normalizeManagedOutputPath(entry2.outputPath);
+      if (activeOutputPaths.has(outputKey)) {
+        continue;
+      }
       const activeSources = activeSourcesByTarget.get(entry2.targetId);
       const sourceStillActive = activeSources?.has(entry2.sourceId) ?? false;
-      if (!removeMissing || sourceStillActive) {
+      const currentSources = activeSourcesWithOutputs.get(entry2.targetId);
+      const sourceHasCurrentOutput = currentSources?.has(entry2.sourceId) ?? false;
+      if (!removeMissing || sourceStillActive && !sourceHasCurrentOutput) {
         updatedEntries.push(entry2);
         continue;
       }
-      const outputKey = normalizeManagedOutputPath(entry2.outputPath);
-      if (activeOutputPaths.has(outputKey)) {
-        continue;
-      }
       const existingHash = await hashOutputPath(entry2.outputPath);
       if (!existingHash) {
         continue;
@@ -6425,7 +6434,8 @@ function validateCommandOutputDefinition(output, label, errors) {
     errors.push(`${label} must be a string or an object.`);
     return;
   }
-  if (!output.projectPath && !output.userPath) {
+  const fallbackConvertsToSkills = output.fallback?.mode === "convert" && output.fallback.targetType === "skills";
+  if (!output.projectPath && !output.userPath && !fallbackConvertsToSkills) {
     errors.push(`${label} must include projectPath or userPath.`);
   }
   if (output.projectPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omniagent",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Unified agent configuration CLI that compiles canonical agent configs to multiple runtimes.",
   "type": "module",
   "bin": {

package/tasks.md

@@ -0,0 +1,25 @@
+# README Docs Refactor Tasks
+
+- [x] Create concise onboarding-first `README.md` for the 90% sync workflow.
+- [x] Add advanced docs pages and move complex README content into `/docs`.
+- [x] Move custom targets/custom agent declaration guidance to `docs/custom-targets.md`.
+- [x] Move templating and dynamic script guidance to `docs/templating.md`.
+- [x] Add a docs index and link advanced docs from `README.md`.
+- [x] Update docs tests to match the new README/docs structure.
+- [x] Run validation (`npm run check` and `npm test`).
+
+# Contributor/Consumer Split Follow-up
+
+- [x] Remove development-only validation details from root `README.md`.
+- [x] Add `CONTRIBUTING.md` with local development and validation guidance.
+- [x] Move CLI shim E2E guidance under contributing docs flow.
+- [x] Remove contributor-only links from end-user docs indexes.
+- [x] Update docs tests for the new contributing boundary.
+- [x] Run validation (`npm run check` and `npm test`).
+
+# README Basics Follow-up
+
+- [x] Add simple `.local` override explanation to root `README.md`.
+- [x] Add simple basic templating explanation to root `README.md`.
+- [x] Update docs tests to assert these root README basics.
+- [x] Run validation (`npm run check` and `npm test`).