orchestkit

# CLAUDE.md

Essential context for Claude Code when working on OrchestKit.

## Language

Always respond in English. Never Hebrew. No exceptions.

## Tone

No sugarcoat. Failed = failed; blocked = blocked. Rule: `src/shared/rules/anti-sycophancy.md`.

## Visuals

ASCII art + 12 semantic emojis for any structured chat answer: status, comparisons, plans, ad-hoc "explain/show me X". Whole session, not just reply 1. Sub-agents do NOT inherit this; restate it in their prompt. Rule: `src/rules/visual-style.md`. CI lints PR titles+bodies; `visual-style-override` bypasses.

## Project Overview

**OrchestKit** — Claude Code plugin for AI-assisted development with built-in best practices, security patterns, and quality gates.

For live component counts (skills / agents / hooks / per-session token cost) run `claude plugin details ork`.

## Directory Structure

```
src/                    ← SOURCE (edit here!)
├── skills/<name>/SKILL.md    # 107 skills (YAML frontmatter + Markdown)
├── agents/<name>.md          # 36 agents (CC 2.1.78 format)
├── settings/<plugin>.settings.json  # Plugin settings (permissions only; CC ignores most keys)
└── hooks/                    # TypeScript hooks (hooks.json + src/ + dist/)
manifests/                    # Plugin definitions (JSON)
plugins/                      # GENERATED by npm run build
scripts/build-plugins.sh      # Assembles plugins/ from src/
```

Edit `src/` and `manifests/`. `plugins/` is regenerated by `npm run build`, so edits there are overwritten. Stage the regenerated `plugins/` diff with your `src/` changes, except `hooks/dist/` (release-owned, #3578: never commit it); an empty `plugins/` means the build was interrupted, so run it again.

## Commands

```bash
npm run build              # Build plugins from source (required after editing src/)
npm test                   # Run all tests (lint + unit + security + integration + e2e)
npm test --quick           # Fast: skip integration/e2e/performance
npm run test:skills        # Skill structure validation
npm run test:agents        # Agent frontmatter validation
npm run test:security      # Security tests (gates push)
npm run test:manifests     # Manifest consistency (counts, deps, ordering)
npm run typecheck          # TypeScript type checking for hooks
cd src/hooks && npm run build    # Compile TypeScript hooks
```

## Adding Components

**Skill**: See `src/skills/CONTRIBUTING-SKILLS.md` for full authoring standards. Create `src/skills/my-skill/SKILL.md` with YAML frontmatter (`name`, `description`, `tags`, `user-invocable`, `complexity`). SKILL.md body must stay under 500 lines. Add to `manifests/ork.json`, run `npm run build`.

**Agent**: Create `src/agents/my-agent.md` with frontmatter (`name`, `description`, `model`, `tools`, `skills`). Add `background: true` for agents that never need interactive results. Add to manifest, rebuild.

**Hook**: Create `src/hooks/src/<category>/my-hook.ts`, register 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, the #959 class), rebuild with `cd src/hooks && npm run build`. Then run `bash bin/validate-counts.sh` and fix what it reports, and add a Registry changelog entry in `src/hooks/README.md`.

## Before Committing

Work on a feature branch; `main` and `dev` are protected. Run `npm test`, and `npm run typecheck` if you touched hooks.

`bin/git-hooks/pre-push:324` runs `tests/security/run-security-tests.sh` and `.github/workflows/ci.yml:162` runs gitleaks, so `--no-verify` relocates a security or secret failure to CI instead of avoiding it.

Use TaskCreate for 3+ step work. Enforcement is layered: `task-existence-gate` runs live inside `sync-task-dispatcher` (advisory nudge for un-tasked agent spawns, never blocking); `multi-step-task-nudge` covers 3+ step prompts. Non-agent work stays your judgement call.

## Session Resilience

Commit after each logical unit of work — never batch all commits to end of session. Rate limits can kill a session at any time. If build/test fails mid-session, commit the passing work first, then fix the failure separately.

## GitHub CLI

- Use `gh api` for milestone assignment — the `--milestone` flag is unreliable with milestone numbers.
- Issues close on merge from `Closes #N` in the PR body; closing by hand loses that PR link.
- Use `gh issue comment` for progress updates, not close/reopen.

## Plugin Architecture

Single plugin `ork`. User-invocable skills surface as `/ork:<skillname>`. Counts + per-session token cost: `claude plugin details ork`.

## Version

- **Current**: 10.0.0-beta.122 · **Claude Code**: >= 2.1.277 <!-- x-release-please-version -->

See `CHANGELOG.md` for history. See `src/hooks/README.md` for hook architecture.