ai: Instructions file for Claude Code

AGENTS.md

This file provides guidance to coding agents (Claude Code, Codex) working with code in this repository. CLAUDE.md is a symlink to this file — edit here.

Install / Update

node scripts/install.js

Copies config/CLAUDE.md → ~/CLAUDE.md and config/AGENTS.md → ~/.codex/AGENTS.md, installs upstream skill packs via npx skills@latest, symlinks the local IsaiaScope/ai skills directly into both supported agents' skills dirs (Claude-side → ~/.claude/skills/, Codex-side → ~/.codex/skills/), and owns the tracker's two hooks in ~/.claude/settings.json (see scripts/agent-hooks.js). No build step. The one package.json is dev tooling only — Biome and Ultracite, pinned, for linting the JavaScript; no script here requires from node_modules. Python and shell lint stay zero-install (uvx ruff, shellcheck). Rules, and why each exemption exists, are in ruff.toml, biome.jsonc and .shellcheckrc. The whole suite is one command, and it lives in docs/iso/config.json under test.command — that is the command /iso-review's phase gate runs, so running anything else locally checks less than CI does. It covers node --test scripts/*.test.js, every *.test.sh under scripts/ and skills/*/scripts/{,lib/,adapters/}, and every skills/*/scripts/test_*.py.

Architecture

config/
  AGENTS.md   — global agent instructions (copied to ~/.codex/AGENTS.md on install)
  CLAUDE.md   — symlink to AGENTS.md (copied to ~/CLAUDE.md on install)
skills/                            — prefix routes each skill to a marketplace plugin (iso-* → eng)
  iso-config/SKILL.md              — the Iso config every iso-* skill reads
  iso-config/scripts/lib/branch.sh — shared branch vocabulary: protected test, name derivation, the gate
  iso-config/scripts/lib/track.sh  — the one seam to the tracker: iso_track, iso_track_path; never fatal
  iso-issue-tracking/SKILL.md      — work tracker, reached through a swappable adapter
  iso-ai-init/SKILL.md             — initialize a repo with IsaiaScope AI defaults
  iso-init-repo/SKILL.md           — initialize repo governance (branches, CI, hooks)
  iso-plan/SKILL.md                — planning pipeline orchestrator
  iso-write/SKILL.md               — TDD plan executor on a feature branch, no commits
  iso-review/SKILL.md              — three phases over the branch: architecture, simplify, review
  iso-spawn/SKILL.md               — spawn a codex/claude agent in a herdr tab
  iso-readme/SKILL.md              — write/refine READMEs in house style, commit + push
scripts/
  install.js                        — deploys config files + installs skill packs globally
  agent-hooks.js                    — writes the tracker hooks into ~/.claude/settings.json (list: skills/iso-issue-tracking/scripts/hooks.json)
  skills-manifest.js                — filesystem → skill catalog: discovery, prefix routing (PLUGINS), manifest projection
  dispatch-integrity.test.sh        — every verb a script dispatches must resolve to a defined function
  portability.test.sh               — no skill may carry the machine it was written on (paths, package manager, agent config dir)
  skill-refs.test.sh                — every skill name referenced in live prose has a directory (survives a rename's blind spots)
.claude-plugin/
  marketplace.json                  — Claude marketplace catalog (2 plugins → ./plugins/<name>)
.agents/plugins/
  marketplace.json                  — Codex marketplace catalog (2 plugins → ./plugins/<name>)
plugins/                            — one subdir per marketplace plugin (routed by skill prefix)
  isaiascope-eng/                   — engineering plugin (iso-* skills)
    .claude-plugin/plugin.json      — Claude manifest (skills array, regenerated on install)
    .codex-plugin/plugin.json       — Codex manifest (skills: "./skills/", whole-dir)
    skills → ../../../skills/iso-*  — per-skill symlinks, regenerated on install