# Initialize Harness Project

> Scaffold a new harness-compliant project, migrate an existing project to the next adoption level, or bootstrap an existing project that just got the harness marketplace plugin installed (no `harness setup`). Assess current state, scaffold or migrate, configure, validate, instrument (baselines / telemetry / Tier-0 integrations), and finalize.

## When to Use

- Starting a brand new project that should be harness-managed from day one
- Migrating an existing project to harness for the first time
- Upgrading an existing harness project from one adoption level to the next (basic to intermediate, intermediate to advanced)
- **Bootstrapping a project for plugin-only users:** the marketplace plugin is installed but `harness setup` was never run, so `harness.config.json`, baselines, telemetry identity, and Tier-0 MCP integrations are missing
- Refreshing instrumentation on an existing harness project (re-baselining after large changes, migrating legacy layouts, picking up new Tier-0 integrations)
- When `on_project_init` triggers fire
- NOT when the project is already at the desired adoption level AND fully instrumented (use harness-onboarding to orient instead)
- NOT when adding a single component to an existing harness project (use add-harness-component)
- NOT when the project has no clear owner or maintainer — harness setup requires someone to own the constraints

## Plugin-only callout

If the user installed only the `harness-claude` (or sibling `harness-cursor`/`harness-gemini`/`harness-codex`) marketplace plugin, no `harness` shell binary is in their PATH. Prefix every CLI invocation in this skill with `npx @harness-engineering/cli`:

```bash
# instead of: harness validate
npx @harness-engineering/cli validate
# instead of: harness check-arch --update-baseline
npx @harness-engineering/cli check-arch --update-baseline
```

Detect plugin-only state by checking whether `harness` resolves on PATH (`command -v harness`). If not, use the `npx` form. First call is slow; subsequent calls within ~24h hit the npx cache.

## Process

### Phase 1: ASSESS — Determine Current State

1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.config.json`, and any skill definitions. Their presence determines whether this is a new project or a migration.

2. **For new projects:** Gather project context — language, framework, test runner, build tool. Ask the human if any of these are undecided. Do not assume defaults.

2b. **For existing projects with detectable frameworks:** Run `harness init` without flags first. The command auto-detects frameworks (FastAPI, Django, Gin, Axum, Spring Boot, Next.js, React+Vite, Vue, Express, NestJS) by scanning project files. Present the detection result to the human and ask for confirmation before proceeding. If detection fails, ask the human to specify `--framework` manually.

3. **For existing projects:** Run `harness validate` to see what is already configured and what is missing. Read `AGENTS.md` if it exists. Identify the current adoption level:
   - **Basic:** Has `AGENTS.md` and `harness.config.json` with project metadata. No layers, no skills, no dependency constraints.
   - **Intermediate:** Has layers defined, dependency constraints between layers, at least one custom skill. `harness check-deps` runs and passes.
   - **Advanced:** Has full persona configuration, custom skills for the team's workflows, state management, learnings capture, and CI integration for `harness validate`.

4. **Recommend the target adoption level.** For new projects, start with basic unless the team has harness experience. For existing projects, recommend one level up from current. Present the recommendation and wait for confirmation.

5. **Classify the project shape — product/service or test-suite?** Check these signals; if any match, the project is a test suite and the rest of this skill's flow changes:
   - Repo or package name matches `*test*`, `*-e2e*`, `*-qa*`, `*-automation*`
   - `package.json` has `@playwright/test`, `cypress`, `webdriverio`, `mocha`, or `testcafe` as a direct dep
   - Top-level `tests/`, `e2e/`, `specs/`, or `playwright/` directories are the primary source tree
   - Config files like `playwright.config.*`, `cypress.config.*`, `wdio.conf.*`
   - No production runtime — build output consumed only by other test repos (shared library)

   **If a test suite:** complete Phase 2 (scaffolding) here, then dispatch to `initialize-test-suite-project` for Phase 3 configuration and Phase 4 verification, then return here for Phase 4 step 4+ (knowledge graph, roadmap question, final commit). The test-suite skill owns archetype selection, layer variants, tags, reporters, and the custom report.

   **If a product/service:** continue with the rest of this skill as written.

### Phase 2: SCAFFOLD — Generate Project Structure

1. **Run `harness init` with the appropriate flags:**
   - New basic JS/TS project: `harness init --level basic`
   - With framework: `harness init --level basic --framework <framework>`
   - Non-JS language: `harness init --language <python|go|rust|java>`
   - Non-JS with framework: `harness init --framework <fastapi|django|gin|axum|spring-boot>`
   - Existing project (auto-detect): `harness init` (no flags -- auto-detection runs)
   - Migration to intermediate: `harness init --level intermediate --migrate`
   - Migration to advanced: `harness init --level advanced --migrate`

   **Supported frameworks:** nextjs, react-vite, vue, express, nestjs, fastapi, django, gin, axum, spring-boot
   **Supported languages:** typescript, python, go, rust, java

2. **Review generated files.** `harness init` creates:
   - `harness.config.json` — Project configuration (name, stack, adoption level)
   - `.harness/` directory — State and learnings storage
   - `AGENTS.md` — Agent instructions (template, needs customization)
   - Layer definitions (intermediate and above)
   - Dependency constraints (intermediate and above)

3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.config.json`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.

### Phase 3: CONFIGURE — Customize for the Project

1. **Configure personas.** Run `harness persona generate` to create persona definitions based on the project's stack and team structure. Personas define how agents should behave in this project — coding style, communication preferences, constraint strictness.

2. **Customize AGENTS.md.** The generated template needs project-specific content:
   - Project description and purpose
   - Architecture overview (components, layers, data flow)
   - Key conventions the team follows
   - Known constraints and forbidden patterns
   - Links to relevant documentation

3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.config.json` and ensure they match the actual codebase structure.

4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.

5. **Configure i18n (all levels).** Ask: "Will this project support multiple languages?" Based on the answer:
   - **Yes:** Invoke `harness-i18n-workflow` configure phase to set up i18n config in `harness.config.json` (source locale, target locales, framework, strictness). Then invoke `harness-i18n-workflow` scaffold phase to create translation file structure and extraction config. Set `i18n.enabled: true`.
   - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
   - **Not sure yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.

5b. **Configure design system (non-test-suite projects).** Ask: "Will this project have a UI requiring a design system?" Mirror the i18n step's three-way response shape. Use `emit_interaction`:

    ```json
    emit_interaction({
      type: "question",
      question: {
        text: "Will this project have a UI requiring a design system?",
        options: [
          {
            label: "Yes — capture design intent now",
            pros: ["Records platforms in harness.config.json", "harness-design-system fires automatically on first design-touching feature"],
            cons: ["One extra follow-up question (which platforms)"],
            risk: "low",
            effort: "low"
          },
          {
            label: "No — this project has no UI",
            pros: ["No future design nudges", "Permanent decline recorded"],
            cons: ["Re-running init is required if a UI is added later"],
            risk: "low",
            effort: "low"
          },
          {
            label: "Not sure yet",
            pros: ["Decision deferred without commitment", "Can run harness-design-system later"],
            cons: ["No design.enabled flag set; on_new_feature will prompt later"],
            risk: "low",
            effort: "low"
          }
        ],
        recommendation: { optionIndex: 0, reason: "Most product/service projects benefit from a centralized design system", confidence: "medium" }
      }
    })
    ```

    Based on the answer:
    - **Yes:** Ask a follow-up: "Which platforms? `web`, `mobile`, or both?" Write `design.enabled: true` and `design.platforms: [...]` (a non-empty array of `web` and/or `mobile`) to `harness.config.json`. Inform the user: "Design tokens will be generated when you start your first design-touching feature — `harness-design-system` fires automatically via `on_new_feature`."
    - **No:** Write `design.enabled: false` to `harness.config.json`. Do not write `design.platforms`. The `on_new_feature` trigger respects this flag and will not fire `harness-design-system`.
    - **Not sure yet:** Do not write `design.enabled` or `design.platforms`. The project can enable design later by running `harness-design-system` directly; `on_new_feature` will prompt gently when a feature touches user-facing UI.

    **Skip this step entirely if Phase 1 step 5 classified the project as a test suite.** Test-suite projects will be dispatched at step 6 below to `initialize-test-suite-project` and have no UI to govern.

6. **Test-suite projects only — dispatch to `initialize-test-suite-project`.** If Phase 1 step 5 classified this as a test suite, invoke `initialize-test-suite-project` now and let it own archetype selection, shared-library decision, layer variants (A self-contained vs B consumer), ESLint flat-config fix, tag taxonomy, reporter stack, custom report, and the "prove the guards fire" verification. Return here for Phase 4 step 4+ (knowledge graph, roadmap, commit). Product and service projects skip this step entirely.

### Phase 4: VALIDATE — Confirm Everything Works

1. **Run `harness validate`** to verify the full configuration. This checks:
   - `harness.config.json` schema validity
   - `AGENTS.md` presence and required sections
   - Layer definitions (if intermediate+)
   - Dependency constraints (if intermediate+)
   - Persona configuration (if configured)

2. **Fix any validation errors before finishing.** Do not leave the project in a half-configured state.

3. **Run `harness check-deps`** (intermediate and above) to verify dependency constraints match the actual codebase. If there are violations, decide with the human: update the constraints or fix the code.

### Phase 5: INSTRUMENT — Capture Baselines and Wire Integrations

This phase closes the parity gap that the marketplace plugin install does not cover: knowledge graph, architecture/perf baselines, telemetry identity, legacy-layout migrations, and Tier-0 MCP integrations. For npm + `harness setup` users most of this was already wired during setup; the steps are still safe to re-run idempotently.

1. **Build the initial knowledge graph.** Required for graph-based MCP tools (`get_impact`, `find_context_for`, `compute_blast_radius`, `detect_anomalies`):

   ```bash
   harness scan
   ```

   Populates `.harness/graph/` with dependency and relationship data. Skip only if the project explicitly disables graph use in `harness.config.json`.

2. **Capture the architecture baseline.** Records the current layer-violation, circular-dep, and complexity counts so future runs of `harness check-arch` can detect regressions:

   ```bash
   harness check-arch --update-baseline
   ```

   Writes `.harness/arch/baselines.json`. Re-run after large refactors. CI (`refresh-baselines` job in `.github/workflows/ci.yml` on this repo) auto-refreshes on `main` for harness-developing projects; downstream projects do this manually here.

3. **Capture the performance baseline** (intermediate and above, or any project that wants regression detection on coupling and size budgets):

   ```bash
   harness check-perf
   ```

   First invocation captures the baseline; subsequent runs compare against it. Updates can be applied via the `update_perf_baselines` MCP tool when the human confirms a regression is intentional.

4. **Configure telemetry identity** (optional but recommended for teams). Anonymous telemetry is default-enabled by the standard hook profile; identity tagging adds project/team/alias to events for filtering. Ask the human:
   - "Tag telemetry events with project + team identity? (recommended for shared installs, optional for personal use)"
   - If yes, run:

     ```bash
     harness telemetry identify --project <project-name> --team <team-name>
     ```

     Writes `.harness/telemetry.json`.

   - If they want to disable telemetry entirely, write `{ "telemetry": { "enabled": false }, "adoption": { "enabled": false } }` to `harness.config.json`. Or recommend the `DO_NOT_TRACK=1` env var.

5. **Surface legacy layout warnings.** If the project predates the current harness layout (`docs/plans/`, `.harness/architecture/`, etc.), the migrate command surfaces and optionally fixes them:

   ```bash
   harness migrate --dry-run
   ```

   If migrations are needed, ask the human before running `harness migrate` (without `--dry-run`). Skip silently when the dry-run reports nothing.

6. **Wire Tier-0 MCP integrations.** Tier-0 is zero-config (no API keys): `context7` (live library docs), `sequential-thinking` (structured reasoning), `playwright` (browser automation). On npm + `harness setup` they're auto-wired during step 4 of setup; on plugin-only installs they are NOT, since the plugin can't mutate the user's project `.mcp.json`.

   List current state, then offer to wire:

   ```bash
   harness integrations list
   # then for each missing Tier-0 integration:
   harness integrations add context7
   harness integrations add sequential-thinking
   harness integrations add playwright
   ```

   For Tier-1 integrations (Linear, Slack, Perplexity, etc.), surface availability with `harness integrations list` and let the human decide — they require API keys and are out of scope for an automated bootstrap.

### Phase 6: FINALIZE — Roadmap and Commit

1. **Set up project roadmap.** Ask: "Set up a project roadmap now? `docs/roadmap.md` tracks features, milestones, and status across your specs and plans." Use `emit_interaction`:

   ```json
   emit_interaction({
     type: "question",
     question: {
       text: "Set up a project roadmap now?",
       options: [
         {
           label: "Yes — create docs/roadmap.md now",
           pros: ["Roadmap visible from day one", "Future specs auto-discovered on next sync"],
           cons: ["Adds one file to the initial commit"],
           risk: "low",
           effort: "low"
         },
         {
           label: "No — skip for now",
           pros: ["Smaller initial footprint"],
           cons: ["Run `/harness:roadmap --create` later when ready"],
           risk: "low",
           effort: "low"
         }
       ],
       recommendation: { optionIndex: 0, reason: "Validation has just passed — a tangible 'project works' signal is the right moment to introduce planning artifacts", confidence: "medium" }
     }
   })
   ```

   Based on the answer:
   - **Yes:** Invoke `harness-roadmap` (skill) or run `/harness:roadmap --create` to create `docs/roadmap.md`. Verify the file exists. The `manage_roadmap` MCP tool is for managing entries in an existing roadmap, not for creating one.
     - **If `design.enabled === true` in `harness.config.json`** (set by Phase 3 step 5b), call `manage_roadmap` with `action: add`, `feature: "Set up design system"`, `status: "planned"`, `milestone: "Current Work"`, `summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens. Deferred from project init — fires on first design-touching feature via on_new_feature."`. Skip silently if `manage_roadmap show` reports a duplicate `(feature, milestone)` pair. This closes the loop between deferred design intent and visible planning work.
   - **No:** Skip silently. The user can still run `/harness:roadmap --create` later — that informational fallback remains valid.

2. **Commit the initialization.** All generated, configured, and instrumentation files in a single commit. Include `harness.config.json`, `AGENTS.md`, `.harness/arch/baselines.json`, `.harness/telemetry.json` (if created), updates to project `.mcp.json` (if Tier-0 integrations were wired), and any roadmap files.

## Harness Integration

- **`harness init --level <level> [--framework <framework>] [--language <language>]`** — Scaffold a new project. `--framework` infers language automatically. `--language` without `--framework` gives a bare language scaffold. Running without flags on an existing project directory triggers auto-detection.
- **`harness init --level <level> --migrate`** — Migrate an existing project to the next adoption level, preserving existing configuration.
- **`harness persona generate`** — Generate persona definitions based on project stack and team structure.
- **`harness validate`** — Verify the full project configuration is valid and complete.
- **`harness check-deps`** — Verify dependency constraints match the actual codebase (intermediate and above).
- **`harness scan`** — Phase 5 step 1. Builds the initial knowledge graph at `.harness/graph/`.
- **`harness check-arch --update-baseline`** — Phase 5 step 2. Captures the architecture baseline at `.harness/arch/baselines.json` so future runs can detect regressions.
- **`harness check-perf`** — Phase 5 step 3. Runs structural complexity, coupling, and size budget checks; first invocation captures the baseline.
- **`harness telemetry identify --project <name> --team <name>`** — Phase 5 step 4. Tags telemetry events with identity for filtering. Writes `.harness/telemetry.json`.
- **`harness migrate --dry-run` / `harness migrate`** — Phase 5 step 5. Surfaces and optionally fixes legacy layouts (`docs/plans/`, `.harness/architecture/`).
- **`harness integrations list` / `harness integrations add <name>`** — Phase 5 step 6. Lists Tier-0 (zero-config) and Tier-1 (API-key) MCP integrations and adds them to project `.mcp.json`.
- **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
- **`harness-design-system` (deferred via `on_new_feature`)** — Phase 3 step 5b records `design.enabled` + `design.platforms` in `harness.config.json` but does NOT run the full design-system skill. Token generation defers to the first design-touching feature, where `harness-design-system` fires via `on_new_feature` and reads `design.enabled` to decide whether to proceed.
- **`initialize-test-suite-project`** — Sub-skill. Invoked during Phase 3 step 6 when Phase 1 step 5 classified the project as a test suite. Owns archetype selection, shared-library vs in-repo decision, layer variants, tag taxonomy, reporter stack, custom report, and "prove the guards fire" verification.
- **`harness-roadmap` skill** — Phase 6 step 1 invokes this skill (or `/harness:roadmap --create`) when the user opts in to creating `docs/roadmap.md`. The `manage_roadmap` MCP tool does not create roadmaps; it manages entries in an existing one.
- **`manage_roadmap` MCP tool** — Phase 6 step 1, when `design.enabled === true`, calls `manage_roadmap` with `action: add` to insert a `planned` "Set up design system" item under milestone `Current Work` with a summary describing the deferred work.

## Success Criteria

- `harness.config.json` exists and passes schema validation
- `AGENTS.md` exists with project-specific content (not just the template)
- `.harness/` directory exists with appropriate state files
- `harness validate` passes with zero errors
- `harness check-deps` passes (intermediate and above)
- Personas are configured if the project uses them
- The adoption level matches what was agreed upon with the human
- All generated files are committed in a single atomic commit
- i18n configuration is set if the human chose to enable it during init
- For non-test-suite projects, the design-system question was asked and `harness.config.json` reflects the answer: `design.enabled: true` (with `design.platforms` populated) for yes, `design.enabled: false` for no, or absent for not-sure.
- **Phase 5 (INSTRUMENT) outputs:** `.harness/graph/` is populated; `.harness/arch/baselines.json` exists; `harness check-perf` ran without errors (intermediate and above); `.harness/telemetry.json` exists if the human opted into identity tagging; legacy layout warnings were surfaced via `harness migrate --dry-run` and either resolved or explicitly deferred; Tier-0 MCP integrations (context7, sequential-thinking, playwright) are present in the project's `.mcp.json` (or the human declined and that decision is recorded).
- The roadmap question was asked. If the user answered yes, `docs/roadmap.md` exists and was created via `harness-roadmap` (or the documented `/harness:roadmap --create` fallback).
- When `design.enabled === true` AND the user answered yes to the roadmap question, `docs/roadmap.md` contains a `planned` entry titled "Set up design system" under milestone `Current Work` with a summary describing the deferred work. The entry is absent in all other answer combinations.
- For test suites: `initialize-test-suite-project` ran to completion and its Success Criteria are also met
- For plugin-only invocations: every CLI invocation in this skill ran successfully via `npx @harness-engineering/cli <cmd>` without requiring a global install. If any invocation failed because the npx download failed, the human was prompted to retry or `npm install -g @harness-engineering/cli` instead.

## Rationalizations to Reject

| Rationalization                                                          | Why It Is Wrong                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "The generated AGENTS.md template looks fine -- no need to customize it" | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.                                                                                                                                               |
| "We should start at the advanced level since we want full coverage"      | The skill recommends basic for new projects. Each level builds on the previous. Jumping to advanced creates misconfigured rules.                                                                                                                                                |
| "I will skip the i18n question to keep setup fast"                       | Phase 3 requires asking about i18n and recording the decision. Skipping creates ambiguity about whether the omission was intentional.                                                                                                                                           |
| "I will skip the design-system question to keep setup fast"              | Phase 3 step 5b requires asking about design and recording the answer in `design.enabled`. Skipping creates ambiguity about whether the omission was intentional and bypasses the linkage between init and the deferred `harness-design-system` invocation on `on_new_feature`. |
| "Validation passed, so the project is ready"                             | Phase 5 captures baselines, configures telemetry identity, surfaces legacy warnings, and wires Tier-0 integrations. Validation alone is not sufficient.                                                                                                                         |
| "Plugin install means setup is done"                                     | The marketplace plugin ships skills, slash commands, subagents, hooks, and MCP — but it cannot mutate the user's project state. `harness.config.json`, baselines, telemetry identity, and Tier-0 integrations require running this skill once per project.                      |
| "Skip Phase 5 if we already ran `harness setup`"                         | Phase 5 is idempotent. It safely no-ops where setup already wired things and fills gaps where it didn't (common case: setup ran once, then a new Tier-0 integration was added or a layout was migrated). Re-running is the right behavior.                                      |
| "This is a test suite, we'll configure layers in this skill"             | Phase 3 step 6 dispatches to `initialize-test-suite-project` for archetype selection, layer variants, and the rest. Do not inline test-suite-specific configuration here — the sub-skill owns it and carries the gotchas.                                                       |

## Examples

### Example: New TypeScript Project (Basic Level)

**ASSESS:**

```
Human: "I'm starting a new TypeScript API project using Express and Vitest."
Check for .harness/ — not found. This is a new project.
Recommend: basic level (new project, start simple).
Human confirms: "Basic is fine for now."
```

**SCAFFOLD:**

```bash
harness init --level basic --framework express
# Creates: harness.config.json, .harness/, AGENTS.md (template)
```

**CONFIGURE:**

```
Edit AGENTS.md:
  - Add project description: "REST API for widget management"
  - Add stack: TypeScript, Express, Vitest, PostgreSQL
  - Add conventions: "Use zod for validation, repository pattern for data access"
  - Add constraints: "No direct SQL queries outside repository layer"
  - Ask: "Will this project support multiple languages?"
  - Human: "Yes, Spanish and French."
  - Run harness-i18n-workflow configure (source: en, targets: es, fr)
  - Run harness-i18n-workflow scaffold (creates locales/ directory structure)
```

**VALIDATE:**

```bash
harness validate  # Pass — basic level checks satisfied
git add harness.config.json .harness/ AGENTS.md
git commit -m "feat: initialize harness project at basic level"
```

### Example: New TypeScript Web App with Design and Roadmap

**ASSESS:**

```
Human: "I'm starting a new Next.js web app. Single-language, but it definitely needs a design system."
Check for .harness/ — not found. Recommend: basic level.
Phase 1 step 5 classification: not a test suite (Next.js app with src/, no playwright/cypress).
```

**SCAFFOLD:**

```bash
harness init --level basic --framework nextjs
```

**CONFIGURE (Phase 3):**

```
Step 5 (i18n): "Will this project support multiple languages?"
  Human: "No, English only."
  Result: i18n.enabled = false in harness.config.json.

Step 5b (design): "Will this project have a UI requiring a design system?"
  Human: "Yes."
  Follow-up: "Which platforms? web, mobile, or both?"
  Human: "Web."
  Result: design.enabled = true, design.platforms = ["web"] in harness.config.json.
  Inform: "Design tokens will be generated when you start your first design-touching
  feature — harness-design-system fires automatically via on_new_feature."

Step 6 (test-suite dispatch): skipped (not a test suite).
```

**VALIDATE (Phase 4):**

```
Step 1: harness validate — pass.
Step 3: harness check-deps — pass (basic level, no constraints yet).
Build initial knowledge graph: harness scan — graph populated.

Step 4 (roadmap): "Set up a project roadmap now?"
  Human: "Yes."
  Invoke harness-roadmap (or /harness:roadmap --create) — docs/roadmap.md created.
  design.enabled === true detected → manage_roadmap action: add
    feature: "Set up design system"
    status: planned
    milestone: Current Work
    summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens..."
  Result: docs/roadmap.md contains the planned design item.

Step 5: commit.
```

```bash
git add harness.config.json .harness/ AGENTS.md docs/roadmap.md
git commit -m "feat: initialize harness project with design and roadmap"
```

**Final state:** `harness.config.json` has `design.enabled: true` + `design.platforms: ["web"]`; `docs/roadmap.md` lists "Set up design system" as a `planned` item under `Current Work`; on the first feature touching UI, `on_new_feature` fires `harness-design-system` which reads `design.enabled` and runs the full discover/define/generate/validate flow.

### Example: Migrating Existing Project from Basic to Intermediate

**ASSESS:**

```
Read harness.config.json — level: basic
Read AGENTS.md — exists, has project-specific content
Run: harness validate — passes at basic level
Recommend: intermediate (add layers and dependency constraints)
Human confirms: "Yes, we're ready for layers."
```

**SCAFFOLD:**

```bash
harness init --level intermediate --migrate
# Preserves existing harness.config.json and AGENTS.md
# Adds: layer definitions template, dependency constraints template
```

**CONFIGURE:**

```
Define layers in harness.config.json:
  - presentation: src/routes/, src/middleware/
  - business: src/services/, src/models/
  - data: src/repositories/, src/db/

Define constraints:
  - presentation → business (allowed)
  - business → data (allowed)
  - data → presentation (forbidden)
  - presentation → data (forbidden — must go through business)

Update AGENTS.md with layer documentation.
```

**VALIDATE:**

```bash
harness validate      # Pass — intermediate level checks satisfied
harness check-deps    # Pass — no constraint violations in existing code
git add -A
git commit -m "feat: migrate harness project to intermediate level with layers"
```

### Example: Plugin-only Bootstrap (Existing Project, No Prior Harness Setup)

The user installed `harness-claude` from the marketplace. They have an existing TypeScript repo with no `.harness/` directory. Goal: get them to a working harness install without asking them to `npm install -g`.

**ASSESS:**

```
Check for .harness/ — not found.
Check `command -v harness` — not on PATH. Plugin-only install confirmed.
All CLI invocations below will be prefixed with `npx @harness-engineering/cli`.

Detect framework: package.json has "express" — auto-detection will pick this up.
Recommend: basic level (no prior harness adoption signal).
Human confirms: "Basic is fine."
```

**SCAFFOLD:**

```bash
npx @harness-engineering/cli init  # auto-detects framework
# Creates: harness.config.json, .harness/, AGENTS.md (template)
```

**CONFIGURE:**

```
Customize AGENTS.md with project-specific content.
Phase 3 step 5 (i18n): "No, English only." → i18n.enabled = false.
Phase 3 step 5b (design): "No, this is a backend service." → design.enabled = false.
Phase 3 step 6 (test-suite dispatch): not a test suite, skipped.
```

**VALIDATE:**

```bash
npx @harness-engineering/cli validate    # Pass
npx @harness-engineering/cli check-deps  # Pass (basic level, no constraints yet)
```

**INSTRUMENT (Phase 5 — the work that `harness setup` would have done):**

```bash
# 1. Knowledge graph
npx @harness-engineering/cli scan
# 2. Architecture baseline
npx @harness-engineering/cli check-arch --update-baseline
# 3. Performance baseline (basic level: structural only)
npx @harness-engineering/cli check-perf --structural
# 4. Telemetry identity — ask the human
#    Human: "Yes, project=acme-api, team=platform"
npx @harness-engineering/cli telemetry identify --project acme-api --team platform
# 5. Legacy layouts — dry-run reports nothing for a fresh repo
npx @harness-engineering/cli migrate --dry-run
# 6. Tier-0 MCP integrations
npx @harness-engineering/cli integrations list
npx @harness-engineering/cli integrations add context7
npx @harness-engineering/cli integrations add sequential-thinking
npx @harness-engineering/cli integrations add playwright
```

**FINALIZE:**

```
Phase 6 step 1 (roadmap): "Yes, create docs/roadmap.md."
Invoke harness-roadmap or run `npx @harness-engineering/cli` equivalent — docs/roadmap.md created.

Phase 6 step 2 (commit):
```

```bash
git add harness.config.json AGENTS.md .harness/ .mcp.json docs/roadmap.md
git commit -m "feat: bootstrap harness on existing project (plugin install)"
```

**Final state:** plugin user now has the same starting state as if they'd run `npm install -g @harness-engineering/cli && harness setup`. Subsequent slash commands, subagents, hooks, and MCP tools all have the project state they need.

### Example: Adoption Level Progression

**Basic (start here):**

- `AGENTS.md` with project context
- `harness.config.json` with metadata
- `harness validate` runs in development

**Intermediate (add structure):**

- Layer definitions and boundaries
- Dependency constraints enforced by `harness check-deps`
- At least one custom skill for team workflows

**Advanced (full integration):**

- Persona configuration for consistent agent behavior
- State management across sessions
- `.harness/learnings.md` capturing institutional knowledge
- `harness validate` runs in CI pipeline
- Custom skills for all common team workflows
