OrchestKit — Source-vs-Generated Invariants

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

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/ /my-hook.ts, register in BOTH src/hooks/hooks.json and the entries map src/hooks/src/entries/ .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.