ai-shared

Shared AI skills and sync tooling for Stella repositories.

Layout

modules/
  <module-name>.md      # reusable AGENTS.md fragments
skills/
  <skill-name>/
    SKILL.md            # shared Codex skill source of truth
scripts/sync-ai-skills.sh
scripts/link-codex-skills.sh
.coderabbit.yaml          # shared CodeRabbit configuration

Recommended shared planning conventions for consumer repos:

.agents/ARCHITECTURE.md
.agents/GOALS.md
.agents/STATUS.md
.agents/plans/

Consumer repositories are expected to use:

.ai/shared/              # submodule pointing here
.ai/manifest.json        # selected modules and local AGENTS fragment
.ai/local/agents.md      # repo-specific AGENTS.md fragment
.ai/generated-agent-files.txt # generated prompt-file registry
.ai/local-skills/        # repo-local Codex-style skills
AGENTS.md                # generated and committed
CLAUDE.md                # generated shim importing AGENTS.md
GEMINI.md                # generated shim importing AGENTS.md
.claude/commands/        # generated flat command files
.agents/skills/          # generated Codex-style skills
.coderabbit.yaml         # generated shared CodeRabbit config

Sync behavior

The sync script assembles AGENTS.md from:

1. .ai/shared/modules/<name>.md, in .ai/manifest.json order
2. .ai/local/agents.md

Repositories can add directory-specific instructions with agents.scopes. Each scope generates its own AGENTS.md, CLAUDE.md, and GEMINI.md; agents combine those instructions with the root guidance when working in that subtree:

{
  "agents": {
    "title": "Project Guidelines",
    "modules": ["engineering", "typescript"],
    "local": ".ai/local/agents.md",
    "scopes": [
      {
        "path": "packages/core",
        "title": "Core Guidelines",
        "modules": ["testing"],
        "local": ".ai/local/core-agents.md"
      }
    ]
  }
}

Scope paths must name existing repository directories. Modules and local fragments are additive to the root instructions, so keep general rules at the root and scope only assumptions that apply to one subtree.

Frontend guidance is deliberately layered:

• frontend contains framework-neutral UI, accessibility, state-subscription, and payload rules.
• react contains React component and type conventions.
• tanstack-react contains TanStack Router and Query conventions.
• stella-web contains Stella's coss, Eden, Zustand, and debounce conventions.

The generated .ai/generated-agent-files.txt registry lets sync remove a scoped prompt after its manifest entry is removed without touching unrelated hand-written files. Commit the registry with the generated prompt files.

The script also generates CLAUDE.md and GEMINI.md adapters so committed instructions are immediately usable by multiple coding agents. When .ai/manifest.json contains an agents object, these root prompt files are generated even if the module list is empty and the local fragment is absent, so --check still catches stale committed instructions.

The same script overlays skills from:

1. .ai/shared/skills/
2. .ai/local-skills/

onto both generated targets:

• .claude/commands/<skill>.md
• .agents/skills/<skill>/SKILL.md

If the same skill name exists in both sources, the local skill wins.

The generated directories keep only a .gitignore placeholder when no skills are present. .gitkeep files from source directories are ignored and are not copied into generated outputs.

The same sync also copies shared root-level automation files, always .coderabbit.yaml, from .ai/shared/ into the consumer repository root.

Consumer repos can opt into additional shared root files (for example the shared Rust lint policy rustfmt.toml, clippy.toml, and deny.toml) by listing them in .ai/manifest.json:

{
  "sharedRootFiles": ["rustfmt.toml", "clippy.toml", "deny.toml"]
}

Listed files are copied verbatim from .ai/shared/ into the repo root and verified by --check, exactly like .coderabbit.yaml. Opt-in keeps repos with stricter local configs (e.g. a repo that bans wall-clock/RNG access in clippy.toml) from being overwritten. Entries must be repo-relative paths without .., and every listed source must exist in .ai/shared.

CodeRabbit path filters and guideline files can be extended per repo from .ai/manifest.json:

{
  "coderabbit": {
    "pathFilters": ["!apps/web/src/routeTree.gen.ts"],
    "codeGuidelineFilePatterns": ["**/.cursorrules"]
  }
}

Use --check in CI to fail when committed generated files are stale:

bash .ai/shared/scripts/sync-ai-skills.sh --check .

The sync script's validation regressions can be run in this repository with:

bash scripts/test-sync-ai-skills.sh

Usage from a consumer repo

bash .ai/shared/scripts/sync-ai-skills.sh .

Package scripts and workflows should invoke the canonical submodule script directly. Do not keep a wrapper copy in the consumer repository:

{
  "scripts": {
    "sync-ai": "bash .ai/shared/scripts/sync-ai-skills.sh .",
    "sync-ai:check": "bash .ai/shared/scripts/sync-ai-skills.sh --check ."
  }
}

Keep .ai/shared pinned to a reviewed commit. A scheduled consumer workflow can call stella/.github/.github/workflows/ai-shared-update.yml to propose fast-forward submodule and generated-file updates in a pull request; never fetch a floating shared revision during normal CI.

To link generated agent skills into Codex's global skill directory:

bash .ai/shared/scripts/link-codex-skills.sh .

By default this installs namespaced links like stella-open-pr into ${CODEX_HOME:-$HOME/.codex}/skills to avoid cross-repo collisions. Set CODEX_SKILL_PREFIX="" if you explicitly want unprefixed global names.

Current Shared Commands

• rabbit-round — handle bot PR reviews systematically
• open-pr — open a clean, verified pull request from the current branch
• plan — create implementation plans using the shared .agents/plans/ convention
• regression-hunt — reproduce, isolate, fix, and lock down a regression
• security-audit — generic security review with repo-specific overlays
• product-think — shape a feature/problem before implementation
• update-deps — review and update third-party dependencies