# AGENTS.md

<!-- Universal agent instructions for this repository. Read by GitHub Copilot Coding Agent
     and most coding agents. Keep concise (~120 lines). Point to deeper docs. -->

## What This Repo Is

`harness-copilot` is a Harness Engineering framework for GitHub Copilot. It ships 16 pluggable skills (`.github/prompts/harness-*.prompt.md`) that audit, generate, and maintain Copilot customizations (`.github/copilot-instructions.md`, `.github/instructions/`, `.github/prompts/`, `.github/agents/`, `AGENTS.md`, `.vscode/mcp.json`) in any target repository.

The framework itself is Copilot-only. The skills it generates target Copilot. Do not reintroduce Claude Code, Cursor, or Codex support without an explicit issue and discussion.

## Build & Run

```bash
npm install                      # No runtime deps; installs dev tools only
npm test                         # Run all tests (skills + cli + setup)
npm run test:skills              # Skills lint + structure tests
npm run test:cli                 # CLI behavior tests
npm run test:setup               # Bash setup script tests
npm run lint                     # Lint all SKILL.md files
node bin/cli.js --help           # CLI help
node bin/cli.js list             # List skills
./setup --tool copilot           # Install into a target project
```

The CLI has zero runtime dependencies (Node ≥ 18 built-ins only).

## Project Structure

```
harness-copilot/
  bin/cli.js              # CLI entry point (npx harness-copilot)
  setup                   # Bundled bash installer
  skills/harness-*/       # 16 skills, each with SKILL.md + optional templates/
  templates/              # Canonical Copilot template files
  docs/                   # Concepts (Copilot surfaces, principles, anti-patterns)
  guides/                 # Step-by-step walkthroughs
  checklists/             # Audit checklists
  agent/                  # Reference playbooks and specs
  tests/                  # Node test suite + standalone lint script
  project/                # Roadmap, decisions, progress
```

See [ARCHITECTURE.md](docs/architecture.md) if/when added.

## Architecture Overview

- **Skills** are the unit of distribution. Each lives at `skills/harness-<name>/SKILL.md` with optional bundled `templates/`. The SKILL.md body is the prompt that will be installed as `.github/prompts/harness-<name>.prompt.md` in the target repo.
- **CLI (`bin/cli.js`)** discovers skills, scaffolds the `.github/` and `.vscode/` Copilot customization tree into a target directory, and reports what changed.
- **`setup`** is a thin bash wrapper around the CLI for users who prefer not to run `npx`.
- **`tests/`** validates the skill set (count, names, frontmatter, line limits, template bundles), the CLI surface, and the setup script.

Dependencies flow one way: `bin/` and `setup` consume `skills/` and `templates/`; nothing in `skills/` or `templates/` should depend on the CLI.

## Code Style

- Node target is **18+**. Use ESM (`import`/`export`). No CommonJS.
- No runtime dependencies. Use only Node built-ins (`node:fs`, `node:path`, `node:readline`, etc.).
- Path joins use `node:path`. Never concatenate paths with `/`.
- ANSI color helpers live at the top of `bin/cli.js`; reuse them rather than inlining escape codes.
- Shell scripts: `#!/usr/bin/env bash` + `set -euo pipefail`. POSIX-compatible where possible.

File naming: kebab-case for files and directories. Skills are `harness-<noun>` (e.g., `harness-audit`, `harness-prompts`).

## Testing

- Tests use Node's built-in `node:test` runner with `node:assert/strict`.
- Run `npm test` before opening a PR. All tests must pass.
- New skills require: a `skills/harness-<name>/SKILL.md` with valid frontmatter, a corresponding entry in `EXPECTED_SKILLS` in `tests/skills.test.js`, and an entry in the README skill table.
- Frontmatter requirements (enforced by lint): `name`, `description`, `user-invocable`.

Test pattern:

```js
describe('thing', () => {
  it('does X when Y', () => {
    // Arrange -> Act -> Assert
  });
});
```

## Common Patterns

### Adding a Skill

1. Create `skills/harness-<name>/SKILL.md` with YAML frontmatter and body under 300 lines.
2. If the skill ships templates, put them under `skills/harness-<name>/templates/`.
3. Add `harness-<name>` to `EXPECTED_SKILLS` in `tests/skills.test.js` and (if it ships templates) to `EXPECTED_TEMPLATES`.
4. Add the slash command to the README skill table.
5. Run `npm run lint` and `npm test`.

### Editing a Skill

- Edit `SKILL.md` only. Never edit installed copies inside a target project's `.github/prompts/` directory.
- Keep SKILL.md under 300 lines (lint will fail otherwise).
- Do not include `[PLACEHOLDER]` brackets — use parametrizable language and reference templates instead.

## Key Docs

- [docs/copilot-customization.md](docs/copilot-customization.md) — How each Copilot customization file works.
- [docs/principles.md](docs/principles.md) — Core harness engineering principles.
- [docs/anti-patterns.md](docs/anti-patterns.md) — What not to do.
- [docs/getting-started.md](docs/getting-started.md) — First-time setup walkthrough.
- [project/ROADMAP.md](project/ROADMAP.md) — Upcoming work.

## Verification

Before submitting, ensure:

1. `npm run lint` — no SKILL.md violations
2. `npm test` — all tests pass
3. `node bin/cli.js list` — your new/edited skill appears
4. New code has tests
5. No secrets in committed code
6. No reintroduction of Claude/Cursor/Codex-specific surfaces

## Agent-Specific Notes

- This repo's customization layer lives at [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Read it before making changes — it contains the rules above plus repo-specific Copilot guidance.
- When generating Copilot customization files, always include valid YAML frontmatter. Invalid frontmatter silently breaks Copilot's customization loading.
- When proposing changes to the skill set, update the README skill table and `tests/skills.test.js` in the same change. Never let them drift.
- This is a content-heavy repository. Most edits are markdown. Run the lint script frequently.