javi-ai

AI development layer — skills, orchestrators, and configs for Claude, OpenCode, Gemini, Qwen, Codex, and Copilot

Quick Start

# Standalone
npx javi-ai install --cli claude

# Or via the workstation installer
npx javi-dots

Supported CLIs

| CLI | Config Path | Skills Path | |-----|-------------|-------------| | Claude Code | ~/.claude/ | ~/.claude/skills/ | | OpenCode | ~/.config/opencode/ | ~/.config/opencode/skill/ | | Gemini CLI | ~/.gemini/ | ~/.gemini/skills/ | | Qwen | ~/.qwen/ | ~/.qwen/skills/ | | Codex CLI | ~/.codex/ | ~/.codex/skills/ | | GitHub Copilot | ~/.copilot/ | ~/.copilot/skills/ |

What's Included

javi-ai ships a layered architecture of AI assets. Each layer has a clear purpose and merge priority:

flowchart TB
    subgraph "Asset Layers (lowest → highest priority)"
        direction TB
        UP["upstream/<br/>37 skills from agent-teams-lite<br/>8 agent groups from PSF"]
        DL["delta/<br/>Orchestrators for Claude + OpenCode<br/>Unified instructions for other CLIs"]
        OW["own/<br/>4 custom skills<br/>3 plugins, 2 hooks"]
        CF["configs/<br/>Per-CLI config files<br/>Claude, OpenCode, Gemini, Qwen, Codex, Copilot"]
    end

    UP --> DL --> OW --> CF

    style UP fill:#334155,color:#e2e8f0
    style DL fill:#475569,color:#e2e8f0
    style OW fill:#f97316,color:#fff
    style CF fill:#ea580c,color:#fff

Layer Details

| Layer | Contents | Source | |-------|----------|--------| | upstream/ | 37 skills + EXTENSION.md overlays, 8 agent groups | agent-teams-lite, PSF | | delta/ | Claude orchestrators, OpenCode agents + domain agents + commands, unified instructions | Modified upstream | | own/ | skill-creator + 3 Obsidian skills, 3 plugins (merge-checks, mermaid, trim-md), 2 Claude hooks | Original creations | | configs/ | CLAUDE.md, opencode.json, QWEN.md, gemini-settings.json, codex-config.toml, copilot-instructions.md | Per-CLI configurations |

Commands

| Command | Description | |---------|-------------| | install | Install AI development layer for selected CLIs (default) | | doctor | Show health report of current installation | | update | Re-install configured CLIs with fresh assets | | uninstall | Remove javi-ai managed files | | sync | Compile .ai-config/ into per-CLI config files |

npx javi-ai install --cli claude,opencode
npx javi-ai doctor
npx javi-ai update
npx javi-ai uninstall
npx javi-ai sync --target claude --mode merge

Install Flags

| Flag | Type | Default | Description | |------|------|---------|-------------| | --dry-run | boolean | false | Preview changes without writing files | | --cli | string | — | Comma-separated CLIs | | --yes / -y | boolean | false | Non-interactive mode |

Sync Flags

| Flag | Type | Default | Description | |------|------|---------|-------------| | --target | string | all | CLI target: claude, opencode, gemini, codex, copilot, all | | --mode | string | overwrite | Sync mode: overwrite or merge | | --project-dir | string | . | Project directory to sync | | --dry-run | boolean | false | Preview without writing |

Extension Model

Some upstream skills ship with an EXTENSION.md alongside the canonical SKILL.md. Extensions are additions that get appended during installation — the upstream SKILL.md is never modified.

upstream/skills/sdd-explore/
├── SKILL.md       ← exact copy from upstream (never edit)
└── EXTENSION.md   ← additions, appended at install time

Each extension carries a tracking comment:

<!-- STATUS: Not yet submitted to upstream -->
<!-- ACTION: If upstream incorporates X, remove this section -->

When upstream adds equivalent functionality, the matching extension block is removed.

Merge Strategies

javi-ai uses different merge strategies depending on file type:

| File Type | Strategy | Behavior | |-----------|----------|----------| | .json | Deep merge | Objects merged recursively, arrays deduplicated | | .md | Marker merge | Content placed between <!-- BEGIN JAVI-AI --> / <!-- END JAVI-AI --> markers | | Other files | Create-if-absent | Only copied if target doesn't exist |

Backups are automatically created in ~/.javi-ai/backups/<timestamp>/ before any merge.

Project-Level Sync

The sync command compiles a project's .ai-config/ directory into per-CLI config files:

npx javi-ai sync --project-dir /path/to/project

It walks .ai-config/agents/ and .ai-config/skills/, reads frontmatter from each markdown file, and generates merged config files like CLAUDE.md, AGENTS.md, GEMINI.md, etc.

A .skillignore file in .ai-config/ can exclude specific skills globally or per-target:

# Exclude from all CLIs
some-skill

# Exclude only from opencode
opencode:another-skill

Requirements

• Node.js >= 18

Ecosystem

| Package | Description | |---------|-------------| | javi-dots | Workstation setup (orchestrates javi-ai) | | javi-ai | AI development layer (this package) | | javi-forge | Project scaffolding (calls javi-ai sync) |

License

MIT