# Orchestrator Guidelines

> Guidance when working on orchestrator infrastructure (agents, skills, guidelines, setup wizard) Use when this capability is needed.

- Skill: `tomevault-io/orchestrator-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/orchestrator-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/orchestrator-guidelines/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/orchestrator-guidelines

---


You are working on the **orchestrator repository** - the shared infrastructure provider for your organization's Claude Code resources.

## When This Activates

- Editing agents, skills, hooks, commands, or guidelines
- Modifying setup wizard or templates
- Updating CLAUDE.md, README.md, or SETUP_CONFIG.json

## Critical Principles

### 1. Changes Affect All Repos
Your updates propagate via symlinks to all repositories. **Test thoroughly before committing.**

### 2. Keep Generic
Avoid hardcoding organization-specific details. Use placeholders and `SETUP_CONFIG.json` for customization.

### 3. Maintain Backward Compatibility
Breaking changes require coordinated updates across all dependent repositories.

### 4. Documentation Must Stay Current
- Update CLAUDE.md when adding/removing resources
- Use cross-repo-doc-sync agent to keep docs synchronized
- Update Resource Discovery Map after changes

## Key Guidelines

**Reference these when working on orchestrator:**
- `guidelines/global/documentation-standards.md` - Keep docs concise and purposeful
- `guidelines/orchestrator/architectural-principles.md` - Orchestrator architecture and design principles

## Testing Checklist

Before committing changes:
- [ ] Test in orchestrator
- [ ] Test in at least one application repo via symlinks
- [ ] Verify hooks execute correctly
- [ ] Check skills trigger as expected
- [ ] Run validation: `./setup/scripts/validate-setup.sh`

## Common Tasks

**Adding a new agent:**
1. Create `shared/agents/global/new-agent.md` (or `shared/agents/{repo-name}/` for repo-specific) with frontmatter
2. Update `shared/agents/README.md`
3. Update CLAUDE.md Resource Discovery Map
4. Test invocation via Task tool

**Adding a new skill:**
1. Create skill directory in `shared/skills/`
2. Add trigger rules to `shared/skills/skill-rules.json`
3. Update CLAUDE.md Resource Discovery Map
4. Test by editing matching files

**Updating guidelines:**
1. Edit guideline file
2. Check which agents/skills reference it
3. Update cross-references if needed
4. Invoke cross-repo-doc-sync if major changes

**Remember:** You're maintaining infrastructure used by multiple teams. Quality and consistency matter.

---
> Source: [BoardKit/orchestrator](https://github.com/BoardKit/orchestrator) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-25 -->