Copilot Instructions

# Copilot Instructions — nsalvacao-claude-code-plugins

> Complexity Mode: **complex** | Generated: 2026-03-12

---

## 1. Project Intent

Personal marketplace of Claude Code plugins: autonomous, self-contained components
installable by end users in Claude Code. Each plugin under `plugins/` is an independent
artifact (commands, agents, skills, hooks). `plugin-dev` is BOTH the **internal dev toolkit**
(validation scripts, skill templates, hook authoring) AND a registered marketplace plugin (v1.0.0)
that users can install to develop their own plugins.

Contribution failures that block delivery: broken `marketplace.json` sync, invalid JSON
manifests, missing frontmatter, hook schema violations, markdownlint errors, shellcheck
failures in custom scripts.

---

## 2. Priority & Conflict Handling

1. Explicit session/task instruction (highest priority)
2. Path-scoped instructions (if present under `.github/copilot-instructions/`)
3. This file (repository-wide)
4. Personal/organization defaults (lowest priority)

Follow the most specific applicable rule.
If ambiguity remains, choose the safest minimal change and state assumptions.

### Mandatory Workflow Read (Repository Policy)

Before implementation and before any commit/PR action, agents MUST consult:

1. `AGENTS.md`
2. `docs/PLUGIN_GUIDELINES.md`
3. `.ideas/plugin-dev-roadmap.md` (when roadmap items are involved)
4. `CLAUDE.md`

Mandatory delivery sequence for each logical change (Atomic Loop):

1. Atomic commit (one logical objective only)
2. Push branch
3. Open Pull Request
4. Wait for online GitHub review
5. Do NOT merge as agent (merge is human-approved and human-executed)

Full governance loop with local validation gates: `.ideas/plugin-dev-roadmap.md` § "Governance & Implementation Workflow".

---

## 3. Critical Rules (MUST / NEVER / SHOULD)

### MUST

- Every plugin directory under `plugins/` MUST be listed in `.claude-plugin/marketplace.json`
  under `plugins[].name` — including `plugin-dev` (as of v1.0.0).
- Every plugin MUST have `plugins/<name>/.claude-plugin/plugin.json` (valid JSON, `name` field in kebab-case).
- Every plugin MUST have `plugins/<name>/README.md`.
- Command files (`commands/*.md`) MUST contain YAML frontmatter with a non-empty `description` field.
- Skill files (`skills/*/SKILL.md`) MUST have frontmatter `name` and `description` fields.
- Agent files (`agents/*.md`) MUST have frontmatter: `name`, `description`, `model`, `color`, plus a non-empty body (system prompt) after the closing `---`.
  - `model` valid values: `inherit` (uses parent model), `sonnet`, `opus`, `haiku`
  - `color` valid values: `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`
  - Agent files MUST use LF line endings — CRLF causes `validate-agent.sh` frontmatter detection to fail (see G11).
- `hooks/hooks.json` MUST use the **wrapper format**: `{"hooks": {"PreToolUse": [...], ...}}`.
  The top-level key `hooks` is required — event types at root level will be rejected at runtime.
- Hook `command` field MUST be a plain string scalar (e.g., `"bash ${CLAUDE_PLUGIN_ROOT}/..."`).
- Commits MUST follow Conventional Commits: `feat|fix|docs|refactor|chore|plugin|update`.
- Counter increments in `set -e` bash scripts MUST use `var=$((var + 1))`, NOT `((var++))`.
- Hook scripts MUST use `${CLAUDE_PLUGIN_ROOT}` for portable paths.

### NEVER

- NEVER hardcode API keys, tokens, or passwords in any file.
- NEVER interpolate user-controlled content directly into shell arguments in hook scripts;
  use stdin or a tempfile.
- NEVER use `((var++))` under `set -e` when `var` may start at 0 — it exits with code 1.
- NEVER embed issue counts, sprint status, or transient plans in core plugin files.
- NEVER write `hooks/hooks.json` with event types at root level (direct format is rejected
  by Claude Code runtime; wrapper format `{"hooks":{...}}` is mandatory).

### SHOULD

- Prefer `pnpm` over `npm` for Node.js operations in plugin-studio.
- Keep `SKILL.md` description ≥ 50 chars, third-person, with specific trigger phrases.
- Use HTTPS/WSS for MCP server URLs, not HTTP/WS.

### Emergency Recovery (3 Steps)

1. Re-run minimal local validation: `jq empty .claude-plugin/marketplace.json` +
   `validate-hook-schema.sh` on any changed hooks file.
2. Verify `marketplace.json` sync: every `plugins/<name>/` directory appears as
   `plugins[].name` in `.claude-plugin/marketplace.json` (exact directory name match).
3. If behavior is not locally reproducible, downgrade the affected command status to
   `[UNVERIFIED]` and reference the CI workflow as source of truth.

---

## 4. Repository Map (Where to Change What)