---
description: Project conventions synced from HARNESS.md
globs: **/*
alwaysApply: true
---

<!-- These conventions are synced from HARNESS.md. Do not edit this file
     directly — run /convention-sync to regenerate. -->

# Conventions

## Stack

- **Primary languages**: Markdown (skills, agents, commands, templates),
  Bash (hook scripts, utility scripts), JSON (plugin config, hooks
  config), YAML (CI workflows)
- **Build system**: None — this is a Claude Code plugin, not a compiled
  application
- **Test framework**: None — content is validated by markdownlint (CI)
  and bash syntax checks
- **Container strategy**: None

## Naming

Skills use `SKILL.md` inside a named directory
(`skills/<name>/SKILL.md`). Agents use `<name>.agent.md`. Commands
use `<name>.md`. Hook scripts use `<name>.sh` (kebab-case). All
names are lowercase kebab-case except `SKILL.md`.

## File Structure

One component per file, organised by type — agents in `agents/`,
skills in `skills/<name>/SKILL.md`, commands in `commands/`, hook
scripts in `hooks/scripts/`, templates in `templates/`, utility
scripts in `scripts/`.

## Error Handling

All hook scripts use `set -euo pipefail`. Guard clauses exit silently
(`exit 0`) when not applicable. Hook scripts are advisory only — they
never block. Output uses JSON `systemMessage` format.

## Documentation

Every skill, agent, and command file must have YAML frontmatter with
`name` and `description` fields. Skills must include an Overview
section. README.md documents the full plugin. Bash scripts must have
a header comment block explaining purpose and behaviour.