# Contributing to OrchestKit Plugin

Welcome to the OrchestKit plugin for Claude Code! We're excited that you're interested in contributing. This plugin extends Claude Code with specialized skills, agents, and hooks for AI-native development workflows.

## How to Contribute

### Getting Started

1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/orchestkit.git
   cd orchestkit
   ```
3. **Create a feature branch**:
   ```bash
   git checkout -b feature/your-feature-name
   # or for issues:
   git checkout -b issue/123-description
   ```
4. **Make your changes** following the guidelines below
5. **Test your changes** thoroughly
6. **Submit a Pull Request** to the `main` branch

### Branch Naming Convention

- `feature/` - New features or enhancements
- `fix/` - Bug fixes
- `docs/` - Documentation updates

### Issue close-out (`Closes #N`)

If your PR ships work for a tracked issue, include `Closes #NNN` in the
PR body so GitHub auto-closes the issue on merge. **We never run
`gh issue close` manually** — issues should only close when the work
that resolves them lands on `main` via CI. The `.github/PULL_REQUEST_TEMPLATE.md`
includes a placeholder; replace `Closes #` with the issue number(s) when
opening the PR.

If the work spans multiple issues, list each on its own `Closes #` line
or use `Closes #1, #2, #3` on a single line — both forms are recognized.

This convention prevents the "open issues that are silently done" drift
class documented in #1554.

## Project Structure

OrchestKit uses a **build system** to assemble modular plugins from source files.

### Source Files (Edit These)

```
src/
├── skills/               # <!--ork:skills-->111<!--/ork--> skills (flat SKILL.md structure, CC 2.1.59+)
│   └── <skill-name>/
│       ├── SKILL.md           # Required: Patterns and best practices
│       ├── references/        # Optional: Specific implementations
│       ├── scripts/           # Optional: Executable code and generators
│       ├── assets/            # Optional: Templates and copyable files
│       └── checklists/        # Optional: Implementation checklists
├── agents/               # <!--ork:agents-->37<!--/ork--> specialized AI personas
└── hooks/                # <!--ork:hooks-->202<!--/ork--> TypeScript hooks in 12 split bundles

manifests/                # Plugin definition
└── ork.json              # Single plugin (<!--ork:skills-->111<!--/ork--> skills, <!--ork:agents-->37<!--/ork--> agents, <!--ork:hooks-->202<!--/ork--> hooks)
```

### Generated Files (Do Not Edit)

```
plugins/                  # Generated by build script
└── ork/                  # Single plugin

.claude-plugin/
└── marketplace.json      # Generated marketplace manifest
```

### Build System

When you modify source files in `src/` or `manifests/`, **you MUST run the build script** to regenerate `plugins/`:

```bash
npm run build
# OR
bash scripts/build-plugins.sh
```

**What the build script does:**
1. Reads plugin definitions from `manifests/*.json`
2. Copies skills, agents, hooks from `src/` to `plugins/<plugin-name>/`
3. Creates `.claude-plugin/plugin.json` for each plugin
4. Generates `.claude-plugin/marketplace.json` with all plugins

**Critical Rules:**
- **ALWAYS edit files in `src/` or `manifests/`**, NEVER in `plugins/`
- **ALWAYS run `bash scripts/build-plugins.sh`** after making changes
- The `plugins/` directory is **generated** and **not tracked in git**
- CI automatically runs the build script on merge to main

**Development Workflow:**
1. Edit source: `src/skills/`, `src/agents/`, or `manifests/`
2. Build: `npm run build`
3. Test: `/plugin marketplace add file://$(pwd)` then `/plugin install ork`
4. Verify: `/ork:doctor`
5. Commit: Only commit changes to `src/` and `manifests/` (not `plugins/`)

## Adding New Skills

Skills use the native flat SKILL.md structure (introduced in CC 2.1.59, current minimum CC 2.1.108).

**Important:** Create skills in `src/skills/`, not `skills/` (which is a symlink).

### 1. Create Skill Directory

```bash
mkdir -p src/skills/your-skill-name/references
```

### 2. Create SKILL.md (Required)

Create `src/skills/your-skill-name/SKILL.md`:

```markdown
---
name: your-skill-name
description: Brief description for skill discovery
tags: [keyword1, keyword2, keyword3]
---

# Your Skill Name

Brief description of what this skill provides.

## When to Use

- Use case 1
- Use case 2

## Key Patterns

### Pattern 1
Explanation and code example.

### Pattern 2
Explanation and code example.

## Best Practices

- Practice 1
- Practice 2

## Anti-Patterns

- What NOT to do
```

### 3. Add References (Optional)

Create specific implementation guides in `references/`:
- `src/skills/your-skill-name/references/implementation-guide.md`
- `src/skills/your-skill-name/references/advanced-patterns.md`

### 4. Add Templates (Optional)

Create code templates in `assets/`:
- `src/skills/your-skill-name/assets/component-template.py`
- `src/skills/your-skill-name/assets/test-template.py`

### 5. Add to Plugin Manifest

Add your skill to the manifest (`manifests/ork.json`) — the build script uses `"skills": "all"`:

```bash
vim manifests/ork.json
```

### 6. Build and Validate

```bash
# Build plugins to include your new skill
npm run build

# Validate structure
npm run test:skills

# Test locally
/plugin marketplace add file://$(pwd)
/plugin install ork
/ork:doctor
```

## Adding New Agents

Agents are specialized AI personas defined in markdown.

**Important:** Create agents in `src/agents/`, not `agents/` (which is a symlink).

### 1. Create Agent File

Create `src/agents/your-agent.md`:

```markdown
# Your Agent Name

## Role
Brief description of the agent's specialized role.

## Capabilities
- Capability 1
- Capability 2

## Tools Available
- Tool 1
- Tool 2

## Workflow
How the agent approaches tasks.

## Success Criteria
What constitutes successful completion.

## Model Preference
haiku | sonnet | opus
```

### 2. Task Management Section (Required for agents with task tools)

Agents that include `TaskCreate`, `TaskUpdate`, or `TaskList` in their `tools:` array must have a Task Management section:

```markdown
## Task Management
For multi-step work (3+ distinct steps), use CC 2.1.16 task tracking:
1. `TaskCreate` for each major step with descriptive `activeForm`
2. `TaskGet` to verify `blockedBy` is empty before starting
3. Set status to `in_progress` when starting a step
4. Use `addBlockedBy` for dependencies between steps
5. Mark `completed` only when step is fully verified
6. Check `TaskList` before starting to see pending work
```

### 3. Add to Plugin Manifest

Both plugins use `"agents": "all"`, so new agents are automatically included. No manifest edit needed.

### 4. Build and Test

```bash
# Build plugins to include your new agent
npm run build

# Validate agents
npm run test:agents

# Test locally
/plugin marketplace add file://$(pwd)
/plugin install ork

# Test agent spawning (in Claude Code)
# Use Task tool with subagent_type: "your-agent"
```

### Agent Taxonomy Fields (for docs generation)

All agents require these frontmatter fields for the auto-generated `agents-data.ts`:

| Field | Type | Description |
|-------|------|-------------|
| `taskTypes` | string[] | What the agent does: `build`, `review`, `debug`, `test`, `deploy`, `design`, `research`, `document`, `optimize`, `secure`, `plan` |
| `keywords` | string[] | Search terms for the agent selector (3-8 keywords) |
| `examplePrompts` | string[] | Exactly 2 example prompts showing typical usage |

These fields are validated by `tests/agents/test-agent-frontmatter.sh`.

## Vendor Upstream Skills (Option E)

OrchestKit references Vercel Labs skills as upstream API documentation, deposited as `references/upstream-*.md` inside our own skill directories.

### How it works

```
vendor/vercel-skills/mapping.json  → defines 37 refs across 4 Vercel repos
scripts/sync-vercel-skills.sh      → fetches + deposits into src/skills/*/references/
vendor/vercel-skills/manifest.json → tracks content hashes for dedup
```

### Adding a new upstream reference

1. Add entry to `vendor/vercel-skills/mapping.json`:
   ```json
   { "repo": "vercel-labs/json-render", "skill_path": "skills/new-skill", "target_skill": "json-render-catalog", "ref_filename": "upstream-new.md" }
   ```
2. Run `bash scripts/sync-vercel-skills.sh`
3. Verify: `bash scripts/sync-vercel-skills.sh --check`
4. Commit the mapping, manifest, and new reference file together

### Modes

- `--check` — verify all refs exist on disk (used in CI)
- `--dry-run` — show what would change without writing
- No flag — fetch and sync (requires network)

## Adding New Hooks

Hooks provide lifecycle automation for Claude Code.

### Hook Requirements

1. **Shebang and strict mode**:
   ```bash
   #!/usr/bin/env bash
   set -euo pipefail
   ```

2. **JSON output** (for pretool hooks):
   ```bash
   echo '{"continue": true, "suppressOutput": true}'
   exit 0
   ```

3. **Source common utilities** (if needed):
   ```bash
   source "$(dirname "$0")/../_lib/common.sh"
   ```

### Hook Categories

| Directory | Purpose |
|-----------|---------|
| `pretool/` | Validate before tool execution |
| `posttool/` | Act after tool execution |
| `permission/` | Auto-approve safe operations |
| `lifecycle/` | Session start/end |
| `stop/` | Conversation end handlers |

### Register Hook

Add to `.claude/settings.json` under appropriate matcher.

### Test Hook

```bash
# Syntax check
bash -n hooks/your-hook.sh

# Full test suite
./tests/unit/test-shell-syntax.sh
```

## Security Guidelines

### Required Practices

- Always use `set -euo pipefail`
- Quote all variables: `"${var}"`
- Validate file paths before operations
- Use `jq --arg` for JSON variable interpolation

### Prohibited Patterns

- **No `eval`** - Never use dynamic execution
- **No network calls** in hooks
- **No secrets** in skill files
- **No `--no-verify`** on git commands

## Versioning

**Do not manually run `./bin/bump-version.sh` on branches prefixed with `feat/`, `fix/`, `perf/`, `refactor/`, `docs/`, `chore/`, `ci/`, `style/`, or `test/`.** Release-please (`"release-type": "simple"`) owns version decisions on these branches — it computes the next version from conventional-commit types since the last tag and opens a `chore(main): release X.Y.Z` PR automatically.

Manual bumps on these branches create **ghost versions** (see #1457): you bump to 7.62.0, release-please picks 7.63.0, v7.62.0 never gets tagged.

Hotfix branches with bare names (e.g. `hotfix-auth-bug`) still trigger the pre-push version check — those are for legitimate manual version control, typically cherry-picks or out-of-band releases.

If you need to override release-please's computed next version, use release-please's own [release-as footer](https://github.com/googleapis/release-please?tab=readme-ov-file#how-do-i-change-the-version-number) in the commit message.

### Release Cadence

Release PRs are driven by two triggers:

1. **On every push to `main`** — release-please analyzes new conventional-commit types since the last tag. A `feat:` or `fix:` opens / updates the `chore(main): release X.Y.Z` PR.
2. **Weekly cron (Mondays 09:00 UTC)** — forces a release-please run even if no push has landed since the last tag. Prevents "release drought" when feat commits sit on `main` without triggering an update.

Release-please skips creating a PR when there's nothing to release, so the cron never produces empty or noisy release PRs. The cron is a *floor*, not a ceiling — bursty feat cadence (multiple releases per day) is still supported and expected.

## Testing

### Run All Tests

```bash
npm test
# OR
./tests/run-all-tests.sh
```

### Individual Test Suites

```bash
# Security tests (MUST pass)
npm run test:security
# OR
./tests/security/run-security-tests.sh

# Skill structure validation
npm run test:skills
# OR
./tests/skills/structure/test-skill-md.sh

# Agent validation
npm run test:agents
# OR
./tests/agents/test-agent-frontmatter.sh

# Other tests
./tests/unit/test-shell-syntax.sh       # Shell syntax
./tests/schemas/validate-all.sh         # Schema validation
./bin/validate-counts.sh                # Component counts
```

### Before Submitting

- [ ] New skills have `SKILL.md` with valid frontmatter
- [ ] All tests pass locally
- [ ] Hook scripts output valid JSON
- [ ] No security violations
- [ ] CHANGELOG.md updated

## CC Version Bump Audit Checklist

**Philosophy**: "Every time there's a new model release, we delete a bunch of code." (Anthropic). OrchestKit accumulates workarounds, prompt engineering fixes, and compatibility shims that may become unnecessary as Claude Code improves. Treat each CC version bump as a code deletion opportunity.

When bumping the minimum CC version (the `>= X.Y.Z` in CLAUDE.md), run this audit **before** tagging the release:

### 1. Review CC CHANGELOG for new capabilities

```bash
# Check what's new in the target CC version
# Compare current minCCVersion to target
grep -r 'Claude Code.*>=' CLAUDE.md
```

For each new CC capability, ask: "Does OrchestKit have a workaround for this that can now be removed?"

### 2. Grep for version-gated code

```bash
# Find version checks, compatibility shims, and CC-specific workarounds
grep -rn 'minCCVersion\|CC 2\.1\.\|Claude Code 2\.' src/
grep -rn 'compatibility\|workaround\|shim\|polyfill\|fallback' src/skills/ src/hooks/
```

Remove any code gated behind versions older than the new minimum.

### 3. Audit prompt engineering

Review skills for prompt patterns that compensate for fixed model weaknesses:
- Overly explicit instructions that the model now handles natively
- Multi-step decomposition of tasks the model can now do in one shot
- Defensive repetition ("IMPORTANT:", "CRITICAL:", "NEVER forget to...")
- Redundant examples where the model now understands from description alone

### 4. Simplify multi-phase skills

Check if complex multi-phase workflows can be collapsed:
- Can a 3-phase skill become 2 phases?
- Are there intermediate validation steps that the model now handles reliably?
- Can `complexity: max` skills be downgraded to `high`?

### 5. Audit hook necessity

```bash
# List all hooks and their descriptions
jq '.hooks[] | {event: .matcher.tool_name // .matcher.event, type: .type}' src/hooks/hooks.json
```

For each hook, ask: "Is this working around a CC bug that's now fixed?"

### 6. Measure before/after

| Metric | Before | After |
|--------|--------|-------|
| Total lines in `src/skills/` | `find src/skills -name '*.md' \| xargs wc -l` | |
| Total lines in `src/hooks/` | `find src/hooks/src -name '*.ts' \| xargs wc -l` | |
| Hook count | Check `hooks.json` | |
| Skill count | Check `manifests/ork.json` | |
| Average skill token count | `npm run test:skills` output | |

### 7. Track deletion as a health metric

Include in the release PR description:
- Lines deleted vs. lines added (target: net negative or neutral)
- Skills simplified or removed
- Hooks removed
- Workarounds eliminated (with CC changelog reference)

A CC version bump PR that only bumps the version number without auditing for deletable code is incomplete.

## Questions?

1. Check existing issues and discussions
2. Open a new discussion for general questions
3. Open an issue for bug reports or feature requests

Thank you for contributing to OrchestKit!