orchestkit: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working in the OrchestKit repository. This is the vendor-neutral companion to CLAUDE.md; where both exist, they say the same thing.

OrchestKit is a plugin for Claude Code (Anthropic's agentic CLI). It packages reusable skills, specialist agents, and lifecycle hooks. It is source-built: you edit src/ and a build step assembles the installable plugins/ tree. It is not a hosted service and has no runtime backend.

The one rule that prevents most broken PRs

Edit src/ and manifests/. Never edit plugins/ by hand — it is generated.

src/                         ← EDIT HERE
  skills/<name>/SKILL.md      # skills (YAML frontmatter + Markdown body, <500 lines)
  agents/<name>.md            # agents (frontmatter: name, description, model, tools, skills)
  hooks/src/<category>/*.ts   # TypeScript lifecycle hooks
manifests/                   ← EDIT HERE (plugin definitions)
plugins/                     ← GENERATED by `npm run build` — do not hand-edit

After any src/ change, run npm run build, then stage the resulting plugins/ diff together with your src/ change in the same commit. A plugins/ diff after a build is expected, not noise. If plugins/ comes out empty, the build was interrupted — run it again.

Build and verify

npm run build            # assemble plugins/ from src/ — required after editing src/
npm test                 # full suite (lint + unit + security + integration + e2e)
npm test --quick         # skip integration/e2e/performance
npm run test:skills      # skill structure validation
npm run test:agents      # agent frontmatter validation
npm run test:security    # security tests — MUST pass, gates push
npm run typecheck        # TypeScript check (run if hooks changed)

Before opening a PR: npm test and npm run test:security must pass, and git diff should show real changes (not no-ops left over from a previous session).

Adding a component

• Skill — create src/skills/<name>/SKILL.md with frontmatter (name, description, tags, user-invocable, complexity); body stays under 500 lines. Add it to manifests/ork.json, then npm run build. See src/skills/CONTRIBUTING-SKILLS.md.
• Agent — create src/agents/<name>.md with the required frontmatter, add to the manifest, rebuild.
• Hook — create src/hooks/src/<category>/<name>.ts and register it in both src/hooks/hooks.json and the entries map src/hooks/src/entries/<event>.ts. One without the other is a silently-dead hook. Rebuild with cd src/hooks && npm run build.