# Getting Started

This guide walks you through installing `harness-copilot` in a project and running your first harness audit.

## Prerequisites

- **VS Code** with **GitHub Copilot** and **Copilot Chat** extensions.
- **Node 18+** (only for the `npx` installer; not a runtime dependency).
- A git repository you want to harness.

## Step 1: Install the harness into your repo

```bash
cd /path/to/your/project
npx harness-copilot init
```

This scaffolds the GitHub Copilot customization tree:

```
your-project/
├── .github/
│   ├── copilot-instructions.md       # Loaded on every Copilot Chat request
│   ├── instructions/                 # Scoped rules with applyTo globs
│   │   ├── typescript.instructions.md
│   │   └── tests.instructions.md
│   ├── prompts/                      # Slash-command prompts
│   │   ├── harness-audit.prompt.md
│   │   ├── harness-verify.prompt.md
│   │   └── … (16 total)
│   └── agents/                       # Custom Copilot agent profiles
│       ├── planner.md
│       └── reviewer.md
├── AGENTS.md                         # Universal agent config
└── .vscode/
    └── mcp.json                      # Optional MCP server wiring
```

The CLI **never overwrites** an existing `.github/copilot-instructions.md`, `AGENTS.md`, or `.vscode/mcp.json` unless you pass `--force`. Prompts always refresh.

## Step 2: Open Copilot Chat and run `/harness-help`

In VS Code, open the Copilot Chat panel (`⌘⇧I` / `Ctrl+Shift+I`) and type:

```
/harness-help
```

Copilot will scan your project, list the 16 available skills, and recommend which one to run next based on what's missing.

## Step 3: Run your first audit

```
/harness-audit
```

This runs a **5-phase workflow**:

1. **Discovery** — detect language, framework, package manager, build system, existing harness files.
2. **Assessment** — score 10 harness components on a 0-10 scale (verification loops, agent config, CI, hooks, custom linters, entropy management, etc.).
3. **Gap report** — structured report with priority order, anti-pattern check, and maturity score.
4. **Plan** — present prioritized actions across three tiers (Quick Wins / Short-term / Medium-term).
5. **Execution** — apply approved actions, invoking sub-skills for each gap.

Stop at any phase with `--report-only` if you just want the diagnosis.

## Step 4: Fill in the seeded files

The CLI seeds `.github/copilot-instructions.md`, `AGENTS.md`, and (if you allow it) `.vscode/mcp.json` from canonical templates. These are scaffolds, not finished products. You should:

1. Open `.github/copilot-instructions.md` and replace template placeholders with real values (tech stack, build commands, architecture summary, conventions).
2. Open `AGENTS.md` and do the same — it's the universal version Copilot Coding Agent reads.
3. Open each `.github/instructions/*.instructions.md` and adjust the `applyTo` glob plus the rules to match your project.
4. Decide which `.github/agents/*.md` custom agent profiles to keep, and which slash-command prompts under `.github/prompts/` you want.

> **Human curation required.** Auto-generated config adopted verbatim drifts from reality and becomes harmful. The user must review, edit, and own the final version.

## Step 5: Add scoped rules

If your project has zones with different conventions (tests vs source, migrations, generated code), generate scoped instructions:

```
/harness-instructions
```

This creates `.github/instructions/<name>.instructions.md` files with `applyTo` globs.

## Step 6: Add reusable prompts

For repeated workflows (code review, PR description, security review), generate prompts:

```
/harness-prompts
```

This creates `.github/prompts/<name>.prompt.md` files that you trigger as `/<name>` in Copilot Chat.

## Step 7: Build the verification loop

Run `/harness-verify` to install or document test, lint, and type-check commands. Copilot is most useful when it can self-correct — and it can only self-correct when verification is fast, fail-loud, and one command away.

## Step 8: Add CI and pre-commit hooks

```
/harness-ci
/harness-hooks
```

These set up GitHub Actions workflows and pre-commit hooks that catch problems before Copilot's suggestions land in main.

## Step 9: Fight entropy

```
/harness-entropy
```

This sets up quality grades, dead-code detection, doc freshness checks, and instruction-rot detection. AI-generated code accumulates drift faster than hand-written code — entropy management is non-negotiable.

## What's Next

- Read [docs/copilot-customization.md](copilot-customization.md) to understand each Copilot surface in depth.
- Read [docs/principles.md](principles.md) for the core harness engineering principles.
- Read [docs/anti-patterns.md](anti-patterns.md) for the patterns to avoid.
- Run `/harness-maintain` after any non-trivial PR to keep `.github/copilot-instructions.md` and `AGENTS.md` in sync with the code.

## Troubleshooting

**Copilot isn't picking up `.github/copilot-instructions.md`.**
Verify the file is committed (Copilot Chat reads the workspace, not the working tree in all cases). Reload the VS Code window. Confirm Copilot Chat is enabled in your VS Code settings.

**`/harness-foo` doesn't appear in the slash menu.**
The prompt files must live under `.github/prompts/` and end in `.prompt.md`. Filename (without the suffix) becomes the slash command. If the file is missing or named incorrectly, the command won't surface. Reload the window after adding new prompts.

**A scoped `.instructions.md` isn't loading.**
Check the `applyTo` glob — Copilot loads the file only when at least one matching file is in chat context. Test by opening a matching file in the editor before invoking Copilot.

**`npm test` fails after I edit a skill.**
Skill files must stay under 300 lines and have valid YAML frontmatter with `name`, `description`, and `user-invocable`. Run `npm run lint` to see specific failures.