git:20260905.1fc12be to git:20260905.3174df9

# 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 # 106 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

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