# Plan: Integration Phase 5 -- Self-Integration ("Eat Your Own Cooking")

**Date:** 2026-04-27 | **Spec:** docs/changes/integration-phase/proposal.md (Phase 5) | **Tasks:** 5 | **Time:** ~18 min

## Goal

Write two ADRs documenting the tiered integration rigor approach and the shift-left integration design decision, regenerate slash commands so `/harness:integration` is available, update AGENTS.md with the integration phase description, verify skill discovery, and enrich the knowledge graph with integration-phase decision nodes.

## Observable Truths (Acceptance Criteria)

1. `docs/knowledge/decisions/0001-tiered-integration-rigor.md` exists with valid YAML frontmatter (number: 0001, title: "Tiered integration rigor", date: 2026-04-27, status: accepted, tier: large, source: docs/changes/integration-phase/proposal.md) and Context/Decision/Consequences sections documenting decision D3 from the spec.
2. `docs/knowledge/decisions/0002-shift-left-integration-into-brainstorming.md` exists with valid YAML frontmatter (number: 0002, title: "Shift-left integration design into brainstorming and planning", date: 2026-04-27, status: accepted, tier: large, source: docs/changes/integration-phase/proposal.md) and Context/Decision/Consequences sections documenting decision D2 from the spec.
3. Running `pnpm harness generate-slash-commands --yes` produces `agents/commands/claude-code/harness/integration.md` and `agents/commands/gemini-cli/harness/integration.toml`.
4. AGENTS.md contains a section titled "Integration Phase" describing the phase's position in the workflow (between Verification and Code Review), the three sub-phases (WIRE, MATERIALIZE, UPDATE), and the tiering model (small/medium/large).
5. Running `pnpm harness skill list` shows `harness-integration` as a tier 1 skill.
6. After running `ingest_source` with `source: "knowledge"`, ADR files are ingested as decision graph nodes via the DecisionIngestor pipeline.
7. `harness validate` passes after all changes.

## Uncertainties

- [ASSUMPTION] `docs/knowledge/decisions/` directory exists (created in Phase 4). No ADR files exist yet (only README.md), so numbering starts at 0001.
- [ASSUMPTION] Knowledge graph enrichment via `ingest_source` with `source: "knowledge"` will invoke the `DecisionIngestor` created in Phase 4 to parse the new ADR files. If the build has not been re-run since Phase 4, a `pnpm build --filter @harness-engineering/graph` may be needed first.
- [DEFERRABLE] The spec mentions "run the integration skill against itself as a final smoke test" as optional. Task 5 includes a verification-only skill discovery check but not a full skill invocation.

## File Map

```
CREATE  docs/knowledge/decisions/0001-tiered-integration-rigor.md
CREATE  docs/knowledge/decisions/0002-shift-left-integration-into-brainstorming.md
MODIFY  AGENTS.md (add Integration Phase section after Skill Tier System)
```

Generated by commands (not hand-written):

```
CREATE  agents/commands/claude-code/harness/integration.md
CREATE  agents/commands/gemini-cli/harness/integration.toml
```

## Tasks

### Task 1: Write ADR 0001 -- Tiered Integration Rigor

**Depends on:** none | **Files:** `docs/knowledge/decisions/0001-tiered-integration-rigor.md`

1. Create `docs/knowledge/decisions/0001-tiered-integration-rigor.md` with this exact content:

```markdown
---
number: 0001
title: Tiered integration rigor
date: 2026-04-27
status: accepted
tier: large
source: docs/changes/integration-phase/proposal.md
---

## Context

The harness workflow produces verified code through brainstorming, planning, execution, and verification phases. However, integration -- ensuring features are properly wired into the system, documented, and discoverable -- was not systematically verified. A single integration rigor level for all changes would be disproportionate: a typo fix does not warrant an ADR, while a new package absolutely should have one.

The question was whether to apply a uniform integration gate to all changes or to scale integration requirements proportionally to change size.

## Decision

Integration rigor is tiered into three levels -- small, medium, and large -- estimated at plan time and confirmed from execution results, with the higher tier winning any conflict.

- **Small** (bug fix, config change, fewer than 3 files, no new exports): Wiring checks only. Barrel export verification and `harness validate` always run.
- **Medium** (new feature within existing package, new exports, 3-15 files): Wiring checks plus project updates (roadmap sync, changelog verification, knowledge graph enrichment).
- **Large** (new package, new skill, new public API surface, architectural change): Wiring checks plus project updates plus knowledge materialization (ADR authoring, documentation updates, full graph enrichment).

The tier is set by the planner during plan creation and re-derived after execution from actual git diff signals (new packages, new public exports, files changed). The effective tier is `max(planned, derived)` to prevent under-classification when scope creeps during execution.

## Consequences

**Positive:**

- Proportional effort matches how real projects work. Small changes pass integration quickly with only default wiring checks.
- Large changes are forced to produce durable knowledge artifacts (ADRs, documentation, graph nodes) that benefit future development.
- Dual-estimate classification catches scope creep -- if execution produces more changes than planned, the tier escalates automatically.

**Negative:**

- Planner must estimate the tier during planning, adding a small cognitive overhead to plan creation.
- Tier escalation during execution may surprise the developer with additional integration requirements.

**Neutral:**

- The WIRE sub-phase always runs its default checks regardless of tier, providing a consistent baseline.
- Existing small changes (bug fixes) experience no additional overhead beyond the always-on barrel export and validate checks.
```

2. Run: `harness validate`
3. Commit: `docs(adr): add ADR 0001 for tiered integration rigor approach`

---

### Task 2: Write ADR 0002 -- Shift-Left Integration Design

**Depends on:** none (parallelizable with Task 1) | **Files:** `docs/knowledge/decisions/0002-shift-left-integration-into-brainstorming.md`

1. Create `docs/knowledge/decisions/0002-shift-left-integration-into-brainstorming.md` with this exact content:

```markdown
---
number: 0002
title: Shift-left integration design into brainstorming and planning
date: 2026-04-27
status: accepted
tier: large
source: docs/changes/integration-phase/proposal.md
---

## Context

Integration work -- barrel exports, skill registration, documentation updates, ADR authoring -- was historically discovered at the end of the workflow, after code was already written and verified. This late discovery made integration feel like bureaucracy rather than intentional design, and problems caught at the end were more expensive to fix.

The question was whether to add a post-execution discovery phase that identifies integration gaps, or to shift integration thinking earlier into brainstorming and planning so the integration phase becomes a verification gate rather than a discovery phase.

## Decision

Integration design is shifted left into brainstorming and planning. The integration phase (INTEGRATE) is a verification gate, not a discovery phase.

- **Brainstorming** produces an "Integration Points" section in every spec, defining: entry points affected, registrations needed, documentation updates, architectural decisions warranting ADRs, and knowledge impact.
- **Planning** derives integration tasks from the spec's Integration Points section. These tasks are tagged `category: "integration"` and appear alongside implementation tasks in the plan.
- **INTEGRATE phase** (between VERIFY and REVIEW) mechanically verifies that planned integration tasks completed. It does not discover new integration work -- it confirms what was planned.

This follows decision D2 from the integration phase proposal.

## Consequences

**Positive:**

- Integration is intentional and plannable rather than an afterthought discovered during late-stage checking.
- Problems are caught at spec review time (brainstorming) rather than after implementation, when fixes are cheaper.
- The INTEGRATE phase is fast and mechanical because it only verifies planned outcomes rather than exploring for gaps.
- Specs become more complete by requiring authors to think about system connectivity upfront.

**Negative:**

- Brainstorming specs require an additional section (Integration Points), adding work to the spec-writing process.
- Planning must derive integration tasks from the spec, adding complexity to the planning skill.
- If the spec's Integration Points section is incomplete, the INTEGRATE phase will pass but real integration gaps will remain undetected.

**Neutral:**

- The WIRE sub-phase still runs default checks (barrel exports, validate) regardless of what was planned, providing a safety net for the most common wiring issues.
- Existing specs without an Integration Points section are not retroactively affected -- the requirement applies to new specs going forward.
```

2. Run: `harness validate`
3. Commit: `docs(adr): add ADR 0002 for shift-left integration design`

---

### Task 3: Update AGENTS.md with Integration Phase Description

**Depends on:** none (parallelizable with Tasks 1-2) | **Files:** `AGENTS.md`

1. Open `AGENTS.md` and locate the "### Skill Tier System" section (around line 432).

2. Insert the following new section **immediately before** the "### Skill Tier System" heading:

```markdown
### Integration Phase

The integration phase (INTEGRATE) is a verification gate between Verification and Code Review in the standard workflow. It confirms that planned integration tasks -- wiring, knowledge materialization, and documentation updates -- actually completed after execution.

**Position in workflow:** `VERIFY -> INTEGRATE -> REVIEW`

**Three sub-phases:**

- **WIRE** (all tiers): Verifies barrel exports are current (`pnpm run generate:barrels:check`), `harness validate` passes, and entry points are reachable. Always runs, even for small changes.
- **MATERIALIZE** (medium + large tiers): Verifies ADRs are written for architectural decisions, knowledge graph is enriched with decision nodes, and documentation tasks are complete.
- **UPDATE** (medium + large tiers): Verifies roadmap sync, changelog entries, and spec cross-references.

**Tiered rigor model:**

| Tier       | Signal                                            | Integration Requirements                                               |
| ---------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
| **small**  | Bug fix, config change, < 3 files, no new exports | WIRE only (default checks always run)                                  |
| **medium** | New feature, new exports, 3-15 files              | WIRE + project updates (roadmap, changelog, graph enrichment)          |
| **large**  | New package, new skill, architectural change      | WIRE + project updates + knowledge materialization (ADRs, doc updates) |

The tier is estimated during planning and confirmed from execution results. The effective tier is `max(planned, derived)` -- the higher tier always wins.

**Skill:** `harness-integration` (Tier 1 workflow skill). Invoked via `/harness:integration` or dispatched by autopilot at the INTEGRATE state.

**ADRs:** Architectural decisions are recorded as markdown files in `docs/knowledge/decisions/` using sequential 4-digit numbering (e.g., `0001-decision-name.md`). ADRs are ingested by the knowledge pipeline as queryable `decision` graph nodes.
```

3. Update the "Last Updated" line at the bottom of AGENTS.md from `2026-04-24` to `2026-04-27`.

4. Run: `harness validate`
5. Commit: `docs: add integration phase section to AGENTS.md`

---

### Task 4: Regenerate Slash Commands

**Depends on:** none | **Files:** `agents/commands/claude-code/harness/`, `agents/commands/gemini-cli/harness/`

1. Run slash command generation:

   ```bash
   pnpm harness generate-slash-commands --yes
   ```

2. Verify `integration.md` exists in the claude-code output:

   ```bash
   ls agents/commands/claude-code/harness/integration.md
   ```

3. Verify `integration.toml` exists in the gemini-cli output:

   ```bash
   ls agents/commands/gemini-cli/harness/integration.toml
   ```

4. Run: `harness validate`
5. Commit: `chore: regenerate slash commands to include /harness:integration`

---

### Task 5: Verify Skill Discovery, Enrich Knowledge Graph, Final Validation

**Depends on:** Tasks 1-4 | **Files:** none (verification only)

[checkpoint:human-verify] -- Confirm skill discovery and graph enrichment results.

1. **Verify skill discovery.** Run:

   ```bash
   pnpm harness skill list | grep harness-integration
   ```

   Expected: `harness-integration` appears in the output as a tier 1 skill with type `rigid`.

2. **Build graph package** (if needed for DecisionIngestor availability):

   ```bash
   pnpm build --filter @harness-engineering/graph
   ```

3. **Enrich knowledge graph.** The knowledge graph enrichment with integration-phase concepts is done by invoking `ingest_source` MCP tool with `{ path: ".", source: "knowledge" }`. This triggers the `DecisionIngestor` (created in Phase 4) to parse the two new ADR files into `decision` graph nodes.

   If `ingest_source` is not available as a CLI command, note this for manual invocation via MCP when the tool is next available. The ADR files are already in the correct format for pipeline ingestion.

4. **Final validation:**

   ```bash
   harness validate
   ```

5. No commit for this task (verification only).
