Immutable. This exact content is served forever at /api/v1/blob/8aaae5dbf2161216.
# 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 - **Current**: 10.0.0-alpha.77 · **Claude Code**: >= 2.1.251 <!-- x-release-please-version --> See `CHANGELOG.md` for history. See `src/hooks/README.md` for hook architecture.