# Repo Adoption Project Plan

*A phased plan another repository can follow to adopt the same harness-engineering process this framework teaches. Use this when you need to brief a team, get leadership buy-in, or scope the work in a tracker.*

---

## What "the same process" means

Adopting `harness-copilot` means more than running `npx harness-copilot init`. The CLI scaffolds files; the *process* is what the team does with them — the curation, the specs, the verification loops, and the maintenance discipline.

A complete adoption produces:

1. **A populated Copilot harness.** [`.github/copilot-instructions.md`](../templates/copilot-instructions.md), [`AGENTS.md`](../templates/AGENTS.md), scoped [`.github/instructions/`](../templates/instructions), reusable [`.github/prompts/`](../templates/prompts), custom agents under [`.github/agents/`](../templates/agents), and [`.vscode/mcp.json`](../templates/mcp.json) — all filled with real, project-specific content.
2. **A working verification loop.** A single `verify.sh` (or equivalent) that runs tests, lint, and type-check fast enough that Copilot can self-correct.
3. **An architecture document.** [`ARCHITECTURE.md`](../templates/ARCHITECTURE.md) describing modules, boundaries, data flow, and dependency rules — the matklad pattern.
4. **Specs for non-trivial components.** A `docs/specs/` directory using the SDD template, with at least the highest-risk components specified.
5. **Constraints that fail loudly.** Linters, structural tests, and pre-commit hooks that produce machine-readable, actionable error messages.
6. **CI that blocks on failure.** Tests, lint, type-check, and harness checks gating merges.
7. **Entropy management.** Quality grades, doc-freshness checks, drift detection — set up and scheduled.

Items 1, 2, 6, and 7 are mostly automatable by the framework's skills. **Items 3, 4, and 5 require irreducible human work** — that is the bulk of what this plan schedules.

---

## What the framework automates vs. what the team must do

Be honest about this with stakeholders before you start.

| Activity | Framework handles | Team must do |
|----------|------------------|--------------|
| Scaffolding files | `npx harness-copilot init` creates every file | Decide which to keep |
| Tech-stack detection | `/harness-audit` Phase 1 | Confirm/correct findings |
| Harness scoring | `/harness-audit` Phase 2 (10 components × 10 pts) | Accept or contest the rubric |
| First-pass `copilot-instructions.md` | `/harness-copilot-instructions` drafts content | **Replace placeholders with real values; trim to <150 lines** |
| First-pass `AGENTS.md` | `/harness-agents-md` drafts content | **Same — review every line** |
| Scoped `.instructions.md` files | `/harness-instructions` proposes globs + rules | **Decide which zones need separate rules; author the actual rules** |
| Slash-command prompts | `/harness-prompts` generates from patterns | Decide which workflows deserve a prompt |
| `verify.sh` script | `/harness-verify` writes it | **Make tests/lint/typecheck actually pass** |
| Pre-commit hooks | `/harness-hooks` installs framework | Decide which hooks block vs. warn |
| CI pipeline | `/harness-ci` writes workflow | **Wire to deploy targets, secrets, environments** |
| Custom linters | `/harness-linters` provides starter rules | **Encode architecture-specific rules** (judgment-heavy) |
| `ARCHITECTURE.md` | `/harness-architecture` gives the matklad skeleton | **Write the actual architecture** |
| Specs (`docs/specs/`) | `/harness-sdd` creates templates + workflow | **Write a spec per major component** |
| Tests for existing code | None — must be hand-written or AI-assisted with strong specs | **Write the tests** |
| Quality grades | `/harness-entropy` sets up the rubric | Decide thresholds and what "good" means |
| Ongoing maintenance | `/harness-maintain` re-scans after PRs | Run it; act on findings |

The single largest manual effort is **#3 architecture + #4 specs + tests for legacy code**. Plan accordingly.

---

## Prerequisites

Before starting, confirm with [`checklists/harness-readiness.md`](../checklists/harness-readiness.md). A score below ~20/35 means stabilize the basics first (CI, tests pass, no secrets in repo) before layering harness on top.

You also need:

- A named **harness champion** (one person, ~20% time for the duration of the plan).
- VS Code + GitHub Copilot + Copilot Chat for every developer in scope.
- Branch protection enabled on the default branch (so CI gates can be enforced).

---

## The phased plan

Each phase has: **deliverables**, **automated steps**, **manual work**, **owner**, **exit criteria**. Times are rough effort estimates, not calendar time.

### Phase 0 — Readiness & alignment (≈ 0.5 day)

**Deliverables**
- Completed [harness-readiness.md](../checklists/harness-readiness.md) score recorded in an issue.
- One-page brief: why we're doing this, what success looks like, who owns it.
- Named champion + named reviewer for harness PRs.

**Automated** — none.

**Manual**
- 30-min team alignment meeting (agenda: top 3 agent mistakes per person → starter rule list). See [`guides/small-team.md`](small-team.md#the-alignment-meeting-30-minutes) for the format.
- Pick scope: one repo, or a pilot subset of a monorepo.

**Exit criteria** — readiness score ≥ 20/35; champion identified; scope written down.

---

### Phase 1 — Install + baseline audit (≈ 0.5 day)

**Deliverables**
- Scaffolded `.github/`, `AGENTS.md`, `.vscode/mcp.json` committed on a branch.
- `/harness-audit --report-only` output saved as `project/harness-baseline.md`.
- A prioritized backlog issue (or epic) with the top 5 gaps.

**Automated**
```
cd <target-repo>
npx harness-copilot init --yes
# Open Copilot Chat, then:
/harness-audit --report-only
```

**Manual**
- Review the audit's tech-stack detection — correct anything wrong.
- Triage the gap report into "must fix", "should fix", "nice to have".

**Exit criteria** — baseline audit committed; backlog created; team agrees on the gap priority.

---

### Phase 2 — Foundation curation (≈ 2–4 days)

This is the *first* manual lift. The CLI seeded templates with placeholders; replace them with truth.

**Deliverables**
- `.github/copilot-instructions.md` populated, **under 150 lines**, real commands, real conventions, real "never do this" rules. No `[PLACEHOLDER]` brackets remain.
- `AGENTS.md` populated. Mirrors `copilot-instructions.md` but written for the Copilot Coding Agent and other agents.
- One scoped `.github/instructions/*.instructions.md` per zone with materially different rules (e.g., `tests`, `migrations`, `generated`, `frontend`, `backend`).
- 2–3 custom agents pruned and personalized (planner, reviewer — drop the rest if not used).

**Automated**
```
/harness-copilot-instructions
/harness-agents-md
/harness-instructions
/harness-agents
```

**Manual** — the irreducible work
- Capture **conventions** from team experience: naming, file layout, dependency rules, error-handling style. These come from people, not detection.
- Capture the **"never do X" rules** from the alignment meeting in Phase 0.
- Add the **glossary**: 5–20 domain terms with one-line definitions.
- Write a **commands** section: install, build, test, single-test, lint, type-check, run — exact commands, copy-pasteable.
- Strip every line that is generic LLM filler. If it could apply to any project, delete it.

**Exit criteria** — a new hire could read `AGENTS.md` and run the project; every section has project-specific (not template) content.

---

### Phase 3 — Verification loop (≈ 1–3 days)

This unlocks Copilot's ability to self-correct. Skipping it is the most common adoption failure.

**Deliverables**
- `verify.sh` (or `make verify`, `pnpm verify`, etc.) that runs tests + lint + type-check in one command.
- `verify.sh` runs in **under 5 minutes** locally on a clean checkout.
- Exit code 0 = green; nonzero = red. No "passed with warnings" ambiguity.
- Documented in `AGENTS.md` and `.github/copilot-instructions.md`.

**Automated**
```
/harness-verify
```

**Manual**
- **Make existing tests actually pass.** If tests are currently red or flaky, fix or quarantine before proceeding. A red `verify.sh` poisons every Copilot session.
- Tighten lint and type configs (`<Nullable>enable</Nullable>` + `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` in every `*.csproj`, `tsconfig` strict, PSScriptAnalyzer with default rules + your custom rule pack). Ratchet up; do not start permissive.
- Decide what counts as a fast feedback loop for your stack and trim slow tests out of `verify.sh` (move to CI-only).

**Exit criteria** — `./verify.sh` green from a clean checkout; documented; runtime acceptable.

---

### Phase 4 — Architecture document (≈ 1–2 days)

**Deliverables**
- `ARCHITECTURE.md` at repo root following the [matklad pattern](../templates/ARCHITECTURE.md): module map, data flow, boundaries, glossary, dependency rules, "where to find things".

**Automated**
```
/harness-architecture
```
Copilot will scan and propose a draft — treat it as a starting point, not the answer.

**Manual** — this is the second irreducible lift
- Write the **module map**: each top-level directory, one paragraph on what it owns.
- Draw or describe the **data flow** for the 1–2 most important user actions (e.g., "how a request becomes a response", "how a job runs end to end").
- State **dependency rules** explicitly: which modules can import which. (e.g., "domain layer must not import from api layer".) These become the first custom-linter rules in Phase 6.
- Capture the **glossary** of 5–20 domain terms shared across the codebase.
- List **"where to find X"** — the navigation hints that save agents (and humans) discovery time.

**Exit criteria** — a new contributor can answer "where does feature X live?" by reading `ARCHITECTURE.md` alone.

---

### Phase 5 — Specs for major components (ongoing; first batch ≈ 1 week)

This is where the team moves from "Copilot helps with code" to **Specification-Driven Development**. See [`docs/specification-driven-development.md`](../docs/specification-driven-development.md) and the [`harness-sdd`](../skills/harness-sdd/SKILL.md) skill for the workflow.

**Deliverables**
- `docs/specs/` directory with `_template.md` and `_plan-template.md` installed.
- A spec written for the **3–5 highest-risk or most-changed components** (use git history to identify them — `git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head`).
- A short "how we do SDD here" note appended to `AGENTS.md`.

**Automated**
```
/harness-sdd
```
Sets up directory, templates, and workflow conventions.

**Manual** — third irreducible lift
- For each chosen component, run a **planning session** (Copilot Chat, no code written) and produce a spec covering: Purpose, Interface, Behavior (happy path, edge cases, errors), Dependencies, Constraints, Verification.
- For each Behavior bullet, ensure a corresponding **Verification** bullet (a test, lint rule, or structural check). If you can't verify it, the spec is too vague.
- For new work going forward: tasks > 2 hours get a spec; tasks < 30 min do not. In between is judgment.
- **Backfilling tests**: if the component has no tests, author them against the spec (Copilot can write them in execution-mode sessions; humans review against the spec, not against vibes).

**Exit criteria** — at least three specs in `docs/specs/`, each with verification mapped to actual tests, each Status field set correctly.

---

### Phase 6 — Constraints that fail loudly (≈ 2–4 days)

Make the architectural rules from Phase 4 **enforced by machines**, not by code review attention.

**Deliverables**
- Pre-commit hooks: format, lint, type-check, secret-scan, large-file detection.
- CI workflow that runs `verify.sh` and blocks merges on failure.
- Custom linters / structural tests that encode at least 2–3 architecture rules (dependency boundaries, naming, banned imports). Each violation produces a **machine-readable, actionable** error message.

**Automated**
```
/harness-hooks
/harness-ci
/harness-linters
```

**Manual**
- Decide which checks **block** vs. **warn**. Bias toward blocking — warnings get ignored.
- Author the custom rules. The framework gives starters; you encode the architecture.
- Wire CI to your secrets/environment/deploy targets (these vary per org).
- Add branch protection requiring the harness checks job to pass.

**Exit criteria** — a PR that violates an architectural rule fails CI with a clear, fix-yourself message; pre-commit catches the obvious problems before push.

---

### Phase 7 — Entropy management (≈ 1–2 days setup, recurring after)

AI-generated code drifts faster than hand-written code. Schedule the cleanup.

**Deliverables**
- Quality grades documented (what is "A" vs "C" code in this repo).
- Doc freshness check (CI fails if `ARCHITECTURE.md` or `.github/copilot-instructions.md` is older than N days *and* the code under it changed).
- Dead-code sweep on a recurring schedule (monthly).
- A `/harness-maintain` cadence (after every non-trivial PR, or weekly).

**Automated**
```
/harness-entropy
/harness-maintain          # use after PRs to refresh docs
```

**Manual**
- Pick the freshness threshold — start lenient (90 days) and ratchet down.
- Decide who triages the entropy report (the harness champion at first, eventually rotated).

**Exit criteria** — first entropy report generated, owner assigned for triage.

---

### Phase 8 — Team rollout & ongoing care (continuous)

**Deliverables**
- A 30-min onboarding doc / walkthrough for new developers explaining: install Copilot, what's in `.github/`, how to invoke slash commands, the SDD workflow.
- A monthly cadence for re-running `/harness-audit` and updating the maturity score.
- Harness changes go through PR review like any other code.

**Manual**
- Champion socializes the workflow; pair with skeptics.
- Capture new "agent gotchas" in scoped `.instructions.md` as they're discovered.
- Maintain the [`checklists/`](../checklists/) cadence.

**Exit criteria** — every PR author runs `verify.sh` before pushing; new joiners can self-onboard from the docs.

---

## Effort summary

| Phase | Effort | Calendar guidance |
|-------|--------|------------------|
| 0. Readiness & alignment | 0.5 day | Day 1 |
| 1. Install + baseline audit | 0.5 day | Day 1 |
| 2. Foundation curation | 2–4 days | Week 1 |
| 3. Verification loop | 1–3 days | Week 1–2 |
| 4. Architecture document | 1–2 days | Week 2 |
| 5. Specs (first batch of 3–5) | ~1 week | Weeks 2–3 |
| 6. Constraints | 2–4 days | Weeks 3–4 |
| 7. Entropy management | 1–2 days setup | Week 4 |
| 8. Rollout & ongoing | continuous | from Week 4 |

**Realistic full adoption: 4–6 weeks** for a single repo with one champion at ~50% time, plus episodic input from the team. A scrappy minimum-viable harness (Phases 0–3 only) lands in **about a week**.

---

## Risks and how to manage them

| Risk | Mitigation |
|------|------------|
| Templates adopted verbatim, never edited | Phase 2 has explicit "no `[PLACEHOLDER]` brackets" exit criterion; reviewer rejects PRs that ship template text |
| Verification loop stays red, agents poisoned | Phase 3 blocks Phase 4+; tests must be green before moving on |
| Architecture doc written once, never updated | Doc-freshness check in Phase 7; `/harness-maintain` after PRs |
| Specs written for trivial things, skipped for complex things | Use the > 2 hour heuristic; require spec link in PR description for long-running work |
| Champion leaves; harness rots | Rotate champion every 6 months; treat harness PRs like product PRs |
| Custom linter rules block legit work | All new rules ship as warnings for one week, then promoted to errors |

---

## Tracker-friendly issue checklist

Copy this into your tracker as the parent epic body. Each bullet is one issue.

```
Phase 0
- [ ] Run harness-readiness checklist; record score
- [ ] Hold 30-min alignment meeting; capture top mistakes
- [ ] Name harness champion + harness PR reviewer

Phase 1
- [ ] Run npx harness-copilot init on branch
- [ ] Run /harness-audit --report-only; commit baseline
- [ ] Triage gap report into must / should / nice

Phase 2
- [ ] Populate .github/copilot-instructions.md (no placeholders, < 150 lines)
- [ ] Populate AGENTS.md
- [ ] Add scoped .github/instructions/ files for each distinct zone
- [ ] Prune custom agents to those actually used

Phase 3
- [ ] Make existing tests green
- [ ] Author/verify verify.sh runs tests + lint + typecheck
- [ ] Confirm verify.sh < 5 min on clean checkout
- [ ] Document verify.sh in agent config

Phase 4
- [ ] Draft ARCHITECTURE.md via /harness-architecture
- [ ] Replace draft with real module map, data flow, dependency rules, glossary

Phase 5
- [ ] Run /harness-sdd; install templates
- [ ] Identify 3-5 highest-risk components from git history
- [ ] Write spec for each (planning session per spec)
- [ ] Backfill tests where missing, mapped to spec verification

Phase 6
- [ ] /harness-hooks; configure pre-commit
- [ ] /harness-ci; wire workflow + branch protection
- [ ] /harness-linters; encode 2-3 architecture rules
- [ ] Confirm a violating PR fails CI with actionable message

Phase 7
- [ ] /harness-entropy; pick freshness thresholds
- [ ] Schedule monthly /harness-maintain run
- [ ] Assign entropy-report triage owner

Phase 8
- [ ] Write 30-min onboarding for new joiners
- [ ] Schedule monthly re-audit; track maturity score over time
```

---

## Related reading

- [docs/getting-started.md](../docs/getting-started.md) — first-time setup walkthrough.
- [docs/principles.md](../docs/principles.md) — the why behind the work.
- [docs/specification-driven-development.md](../docs/specification-driven-development.md) — Phase 5 in depth.
- [guides/individual-developer.md](individual-developer.md) — solo adoption (subset of this plan).
- [guides/small-team.md](small-team.md) — team adoption (overlaps with Phase 8).
- [guides/enterprise.md](enterprise.md) — multi-repo, org-wide rollout (this plan × N repos).
- [checklists/harness-readiness.md](../checklists/harness-readiness.md) — Phase 0 input.
- [checklists/post-implementation.md](../checklists/post-implementation.md) — Phase 8 cadence.