npm - omniagent - Versions diffs - 0.1.3 → 0.1.5 - Mend

omniagent 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CLAUDE.md CHANGED Viewed

@@ -1,10 +1,32 @@
 # omniagent Development Guidelines
-Auto-generated from all feature plans. Last updated: 2026-02-08
+Auto-generated from all feature plans. Last updated: 2026-01-10
 ## Active Technologies
+- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js fs/promises + path (004-sync-agent-config)
+- Filesystem (repo-local directories) (004-sync-agent-config)
+- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js fs/promises + path, Vitest, Vite, Biome (005-sync-slash-commands)
+- Filesystem (repo `agents/commands/`, project target dirs, user home dirs) (005-sync-slash-commands)
+- Filesystem (repo-local config + target directories) (006-add-custom-subagents)
+- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises`, `path`, Vitest, Vite, Biome (007-agent-templating)
+- Filesystem (repo-local config + target directories + user home config) (007-agent-templating)
+- Filesystem (repo-local agents/ directories and user home state under `~/.omniagent/state/`) (009-local-config-sync)
+- Filesystem (repo-local sources/outputs + user home state under `~/.omniagent/state/`) (010-instruction-file-sync)
+- Filesystem (repo-local `agents/` directory or user-supplied agents directory) (012-agents-dir-override)
+- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, @typescript/native-preview (tsgo), Vitest, Vite, Biome (013-fix-typecheck-ci)
+- Filesystem (repo-local config and user home state) (013-fix-typecheck-ci)
+- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path`, Vite, Vitest, Biome (014-add-custom-targets)
+- Filesystem (repo-local directories and user home state under `~/.omniagent/state/`) (014-add-custom-targets)
+- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path`, `jiti`, Vite, Vitest, Biome, @typescript/native-preview (tsgo) (015-cli-shim-flags)
+- Filesystem (repo-local agents directory and user home state under `~/.omniagent/state/`) (015-cli-shim-flags)
+- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path`, Vitest, Vite, Biome (016-sync-default-agents)
+- Filesystem (repo-local outputs and user home state under `~/.omniagent/state/`) (016-sync-default-agents)
-- TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path` + `child_process`, Vitest, Vite, Biome (017-dynamic-template-scripts)
+- TypeScript 5.x, ES2022 target + yargs (CLI parsing), Vitest (testing), Vite (build), Biome (formatting/linting) (003-biome-integration)
+- TypeScript 5.x, ES2022 target + yargs (CLI parsing), Vitest (testing) (002-vitest-cli-testing)
+- TypeScript 5.x, Node.js 18+ + yargs (CLI parsing only) (001-cli-foundation)
 ## Project Structure
@@ -15,15 +37,31 @@ tests/
 ## Commands
-npm test && npm run lint
+npm run check && npm test
 ## Code Style
-TypeScript 5.9 (ES2022) on Node.js 18+: Follow standard conventions
+TypeScript 5.x, Node.js 18+: Enforced by Biome (formatting and linting)
+- Line width: 100 characters
+- Indentation: Tabs (2-space width)
+- Quotes: Double quotes
+- Semicolons: Always
+- Run `npm run format` before committing
 ## Recent Changes
+- 016-sync-default-agents: Added TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path`, Vitest, Vite, Biome
+- 015-cli-shim-flags: Added TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path`, `jiti`, Vite, Vitest, Biome, @typescript/native-preview (tsgo)
+- 014-add-custom-targets: Added TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path`, Vite, Vitest, Biome
-- 017-dynamic-template-scripts: Added TypeScript 5.9 (ES2022) on Node.js 18+ + yargs, Node.js `fs/promises` + `path` + `child_process`, Vitest, Vite, Biome
 <!-- MANUAL ADDITIONS START -->
+- Dynamic template scripts (`<nodejs>` and `<shell>`) are a shared sync runtime feature and apply across all
+  syncable template surfaces (skills, subagents, slash commands, and instruction templates).
+- Any future syncable surface must integrate with the shared template-script runtime instead of
+  introducing surface-specific script execution behavior.
+- Keep ignore and publish rules aligned with tool-specific directories so package publishes stay
+  clean.
+- CLI shim E2E docs: `docs/cli-shim-e2e.md`.
 <!-- MANUAL ADDITIONS END -->

package/CONTRIBUTING.md ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,339 +1,209 @@
 # 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
+# Sync all supported agent CLIs installed on your system
+npx omniagent@latest sync
-| Agent   | Approval | Sandbox | Output | Model | Web |
-|---------|----------|---------|--------|-------|-----|
-| codex   | ✓        | ✓       | ✓      | ✓     | ✓   |
-| claude  | ✓        | ✗       | ✓      | ✓     | ✗   |
-| gemini  | ✓        | ✓       | ✓      | ✓     | ✓   |
-| copilot | ✓        | ✗       | ✗      | ✓     | ✗   |
+# Sync specific targets
+npx omniagent@latest sync --only claude,codex
-## What you can sync
+# Skip a target for this run
+npx omniagent@latest sync --skip codex
-### Subagents (Claude format → converted skills elsewhere)
+# Use a non-default agents directory
+npx omniagent@latest sync --agentsDir ./my-custom-agents
-```text
-agents/agents/release-helper.md
----
-name: release-helper
-description: "Help draft release plans and checklists."
----
-Draft a release plan with milestones and owners.
-```
+# Show local-only overrides and exit
+npx omniagent@latest sync --list-local
-### Skills
+# Apply a sync profile (see docs/profiles.md)
+npx omniagent@latest sync --profile code-reviewer
-```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
+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.
-Run the same steps as CI:
+Use `--list-local` to see active local items, or `--exclude-local` to ignore them for a run.
-1. `npm ci`
-2. `npm run check`
-3. `npm run typecheck`
-4. `npm test`
-5. `npm run build`
+Example `.gitignore` entries:
-## Advanced
-### Targeting via frontmatter
-```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;
-```
+## Sync Profiles
-- 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.
+Profiles let each dev pick a named, checked-in filter that `sync` applies to
+the shared `agents/` directory — so a ten-person team can share one source of
+truth while each member opts in to exactly the skills, subagents, commands,
+and targets they want.
-### Instruction templates (per-target outputs)
-```text
-/agents/guide.AGENTS.md
----
-outPutPath: docs/
----
-<agents include="claude,gemini">
-# Team Instructions
-</agents>
+```jsonc
+// agents/profiles/code-reviewer.json
+{
+  "description": "Focused setup for PR reviews",
+  "extends": "base",
+  "targets": { "claude": { "enabled": true }, "codex": { "enabled": true } },
+  "enable": {
+    "skills":    ["code-review", "security-review"],
+    "subagents": ["reviewer"],
+    "commands":  ["review", "diff-summary"]
+  },
+  "variables": { "REVIEW_STYLE": "terse" }
+}
 ```
-- Templates live under `/agents/**` and can target specific outputs.
-- `outPutPath` is treated as a directory; filename is ignored if supplied.
+```bash
+omniagent sync                                   # uses agents/profiles/default.json when present
+omniagent sync --profile code-reviewer
+omniagent sync --profile base,code-reviewer     # merge multiple (later wins)
+omniagent sync --var REVIEW_STYLE=thorough      # override a variable from the CLI
+```
-### Local overrides (personal, never synced)
+Profiles support `extends` chains, `.local` overrides (personal, gitignored),
+glob-based `enable`/`disable` lists, per-target toggles, and template
+variables. Discover and validate profiles with `omniagent profiles`,
+`omniagent profiles show <name>`, and `omniagent profiles validate`.
-```text
-agents/commands/deploy.local.md
-agents/skills/review-helper.local/SKILL.md
-```
+See [`docs/profiles.md`](docs/profiles.md) for the full schema, resolution
+order, and examples.
-Local items override shared items with the same name. Outputs never include `.local`.
+## Basic Templating
-### Agent-scoped templating
+Use `<agents ...>` blocks when some text should render only for specific targets.
-```text
-Shared content.
+```md
+Shared guidance for all targets.
 <agents claude,codex>
-Only Claude and Codex see this.
-</agents>
-<agents not:claude,gemini>
-Everyone except Claude and Gemini see this.
+Extra instructions only for Claude and Codex.
 </agents>
 ```
-### Dynamic template scripts (`<nodejs>` and `<shell>`)
+For advanced templating and dynamic scripts (`<nodejs>`, `<shell>`), see
+[`docs/templating.md`](docs/templating.md).
-`sync` can execute inline script blocks in canonical templates before agent templating/rendering.
+## Agent CLI Shim
-Node.js blocks evaluate JavaScript and inject the returned value:
+Omniagent provides a CLI shim (`omniagent` without a subcommand) for working with agent CLIs via a unified interface.
-```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>
+This can be useful for CI/CD and shell scripts, while maintaining full portability between agents:
+```bash
+# code-review.sh
+#!/usr/bin/env bash
+set -euo pipefail
+agent="${1:-claude}"
+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)
+- Sync profiles: [`docs/profiles.md`](docs/profiles.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).