Harness Initialize Project

# 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`). Ground the project in a strategic anchor (`STRATEGY.md`) first, then 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 load-bearing-minimum, load-bearing-minimum 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

**Prompt the human in plain text** — every framework confirmation, migration check, and telemetry-identity question in this skill is plain text only. Do not elevate to `AskUserQuestion`: the framework list (~10 options) exceeds its 4-option cap and natural headers like "Confirm framework" exceed its 12-char cap, rendering the call as ERR.

### Phase 0: GROUND — Capture the Strategic Anchor

Run this before anything else — it is the first thing init does and the first question it asks the human.
Offer to capture `STRATEGY.md`, the durable upstream product anchor read by `harness-brainstorming`,
`harness-ideate`, and `harness-roadmap-pilot`. _Think first (strategy), build second (scaffold)._

Ask in plain text in your reply, same as the design-system step (Phase 3 step 5b) — never via `emit_interaction`, `AskUserQuestion`, or any tool (the human won't see a tool-routed prompt; only plain text reaches them across Claude Code, Cursor, Codex, and Gemini CLI). State your recommendation, then STOP and wait for the human's reply:

```markdown
### Capture strategic anchor (STRATEGY.md) now?

|            | A) Yes — run the strategy interview                                                                                        | B) No — this project does not need a strategy doc                           | C) Not sure yet                                                       |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Pros**   | Grounds brainstorm/ideate/roadmap-pilot in product-level context; durable across milestones and phases (peer of README.md) | Permanent decline recorded; init does not re-ask on rerun                   | Decision deferred without commitment; can run /harness:strategy later |
| **Cons**   | Adds an interview (10-20 minutes) to init                                                                                  | Re-running init will not re-offer; user must run /harness:strategy manually | No decline flag set; init may re-offer on rerun                       |
| **Risk**   | Low                                                                                                                        | Low                                                                         | Low                                                                   |
| **Effort** | Medium                                                                                                                     | Low                                                                         | Low                                                                   |

**Recommendation:** A) Yes — run the strategy interview (confidence: medium) — strategy grounds brainstorm/ideate/roadmap-pilot; value compounds as the project grows.
```

Before prompting, check whether `STRATEGY.md` already exists at repo root. Three cases:

- **Absent (most common on init).** Present the prompt above. Apply the answer:
  - **Yes:** delegate to `harness-strategy` (which routes via its own Phase 0 to the first-run interview). It writes a valid `STRATEGY.md` at repo root, doc-validated via the `write_strategy` / `validate_strategy` MCP tools. Do **not** run a project-level `harness validate` here — `harness.config.json` does not exist until SCAFFOLD. When `harness-strategy` completes, proceed to Phase 1.
  - **No:** record the decline in working memory. `Phase 3: CONFIGURE` step 0 persists `init.strategy.declined: true` to `.harness/state.json` after SCAFFOLD creates it. Do **not** touch `.harness/` here — it does not exist yet.
  - **Not sure:** record nothing. `/harness:strategy` remains available standalone, and a future re-run of init will re-offer.

- **Present and valid.** Skip the prompt silently. Surface a one-line note: `STRATEGY.md detected — downstream skills will pick it up as grounding`. No decline is recorded.

- **Present but invalid.** Surface the validation error via the `validate_strategy` MCP tool (the MCP server already has `@harness-engineering/core` loaded, so this resolves even for plugin-only adopters with no `node_modules`). Offer three paths (mirror `harness-strategy` Phase 0):
  - **a) Fix now via `/harness:strategy` update** → delegate to `harness-strategy` with the broken section pre-selected.
  - **b) Move file to `STRATEGY.md.bak.<YYYY-MM-DD-HHmm>` and run a fresh interview** → rename, then delegate to `harness-strategy` Phase 1.
  - **c) Ignore for this init and proceed** → record the decline (persisted in `Phase 3: CONFIGURE` step 0) and continue. Init does NOT block on a present-but-invalid `STRATEGY.md`.

**Guards:**

- Phase 0 runs for **all** project shapes, including test suites — strategy is offered before the Phase 1
  step 5 test-suite classification and the step-6 dispatch, identical in reach to the legacy step.
- A present-valid (skip) or present-invalid (offer fix) `STRATEGY.md` is the migration path for an existing
  strategy doc — distinct from the `.harness/`-based adoption-level classification in `Phase 1: ASSESS`,
  which Phase 0 must not pre-empt.
- **No / Not-sure proceeds immediately into `Phase 1: ASSESS`. Phase 0 never blocks init.**

This mirrors the ask-once-record-the-answer pattern also used by the i18n and design-system prompts in Phase 3.

### 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, recommend `load-bearing-minimum` — the minimum tier that keeps its guarantees when the senior reviewer disappears for two weeks (ESLint + layer enforcement, complexity cap 15, module-size cap, multi-persona review, and the outcome-eval ship gate wired into a scaffolded CI workflow), without the full advanced-tier surface area. Offer `basic` as an explicit opt-down for teams that want the lightest possible touch or are brand new to harness. For existing projects, suggest one level up from current. Present the guidance 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 JS/TS project (recommended default `load-bearing-minimum`): `harness init` or `harness init --level load-bearing-minimum`
   - Lightest-touch new JS/TS project: `harness init --level basic`
   - With framework: `harness init --framework <framework>` (uses `load-bearing-minimum` unless a `--level` is given; add `--level basic` for the lightest touch)
   - 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 load-bearing-minimum: `harness init --level load-bearing-minimum --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

0. **Persist the Phase 0 grounding decision.** SCAFFOLD has now created `.harness/`. If the user **declined**
   the strategic anchor in `Phase 0: GROUND` (answered "No", or chose "ignore" on a present-but-invalid
   `STRATEGY.md`), write `init.strategy.declined: true` to `.harness/state.json` (merge into existing JSON;
   do not clobber). If the user answered "Yes" or "Not sure" in Phase 0, write nothing. This is the deferred
   half of the Phase 0 offer: Phase 0 captures the answer, this step records the decline once `.harness/`
   exists — so the relocation never fabricates `.harness/` early and never misclassifies a new project as a
   migration in `Phase 1: ASSESS`.

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:** 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).** Mirror the i18n step's three-way response shape.

    **Ask directly in your reply. Do NOT route this question through `emit_interaction`, `AskUserQuestion`, or any tool.** `emit_interaction` records the prompt but does not display it to the human — the client collapses the call to "Called harness" and the rendered text only returns to the model, so the human sees nothing. `AskUserQuestion` is Claude-Code-only and caps headers at 12 chars / 4 options. Plain text in your own message is the only channel that reliably reaches the human across every tool (Claude Code, Cursor, Codex, Gemini CLI). State your recommendation, then STOP and wait for the human's reply:

    ```markdown
    ### Will this project have a UI requiring a design system?

    | | A) Yes — capture design intent now | B) No — this project has no UI | C) Not sure yet |
    |---|---|---|---|
    | **Pros** | Records platforms in harness.config.json; harness-design-system fires automatically on first design-touching feature | No future design nudges; permanent decline recorded | Decision deferred without commitment; can run harness-design-system later |
    | **Cons** | One extra follow-up question (which platforms) | Re-running init is required if a UI is added later | No design.enabled flag set; on_new_feature will prompt later |
    | **Risk** | Low | Low | Low |
    | **Effort** | Low | Low | Low |

    **Recommendation:** A) Yes — capture design intent now (confidence: medium) — most product/service projects benefit from a centralized design system.
    ```

    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:** 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.** `docs/roadmap.md` tracks features, milestones, and status across your specs and plans.

   **Ask in plain text in your reply, same as Phase 0: GROUND and Phase 3 step 5b — never via `emit_interaction`, `AskUserQuestion`, or any tool (the human won't see a tool-routed prompt; only plain text reaches them across Claude Code, Cursor, Codex, and Gemini CLI).** State your recommendation, then STOP and wait for the human's reply:

   ```markdown
   ### Set up a project roadmap now?

   |            | A) Yes — create docs/roadmap.md now                                     | B) No — skip for now                             |
   | ---------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
   | **Pros**   | Roadmap visible from day one; future specs auto-discovered on next sync | Smaller initial footprint                        |
   | **Cons**   | Adds one file to the initial commit                                     | Run `/harness:roadmap --create` later when ready |
   | **Risk**   | Low                                                                     | Low                                              |
   | **Effort** | Low                                                                     | Low                                              |

   **Recommendation:** A) Yes — create docs/roadmap.md now (confidence: medium) — validation has just passed; a tangible "project works" signal is the right moment to introduce planning artifacts.
   ```

   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: "Intake"`, `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.
- **`harness-strategy`** — Phase 0: GROUND delegates to this skill on "Yes". The skill conducts a first-run interview (pushback rules with a 2-round cap per section) and writes a valid `STRATEGY.md` at repo root via `writeStrategyDoc`. On "No" the decline is recorded in working memory and persisted as `init.strategy.declined: true` to `.harness/state.json` by Phase 3: CONFIGURE step 0 (after SCAFFOLD). On "not sure" no state is written; the user can run `/harness:strategy` standalone. When `STRATEGY.md` already exists and is valid the prompt is skipped; when present-but-invalid the user gets the three-path repair offer.
- **`validate_strategy` / `write_strategy` MCP tools** — used by Phase 0: GROUND to doc-validate `STRATEGY.md` and to detect a present-but-invalid one. Routed through the MCP server (which already has `@harness-engineering/core` loaded) so init does not require local `node_modules` or a `node -e` one-liner.
- **`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 `Intake` 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.
- The strategy question (Phase 0: GROUND) was asked unless `STRATEGY.md` already existed and was valid (in which case the prompt was skipped silently with a one-line detection note). The answer was recorded according to the documented semantics: Yes → `STRATEGY.md` exists, doc-validated via `validate_strategy` against `StrategyDocSchema` (no project-level `harness validate` is run in Phase 0); No → `.harness/state.json` contains `init.strategy.declined: true`; Not sure → no `STRATEGY.md` and no `init.strategy.declined` flag.
- **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 `Intake` 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 `load-bearing-minimum` for new projects — enough to hold when the senior reviewer is away, without the full advanced surface area. Each level builds on the previous; jumping straight 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`.                                                                                   |
| "I will skip the strategy question — it's just paperwork"                    | Phase 0: GROUND is the only point in the workflow where init asks the user to capture the strategic anchor. Skipping bypasses the grounding signal that brainstorming, ideate, and roadmap-pilot read; downstream skill output degrades silently. Even a "no" or "not sure" answer is better than no answer because it locks in the decision (or absence of one). |
| "STRATEGY.md exists already, so I should re-run the interview to refresh it" | When `STRATEGY.md` is present and valid, Phase 0: GROUND skips the prompt silently. Refreshing strategy mid-init is out of scope — that is what the standalone `/harness:strategy` update flow is for. Surface a one-line detection note and continue.                                                                                                            |
| "STRATEGY.md is present but invalid, so I should block init"                 | Phase 0: GROUND explicitly does NOT block. It surfaces the validation error, offers three repair paths (fix now / move-to-bak / ignore), and continues based on the user's choice. Init is the wrong place to gate on strategy correctness.                                                                                                                       |
| "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: load-bearing-minimum (the default — holds when the senior reviewer is away).
Human opts down: "Keep it light for now — basic is fine."
```

**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

**GROUND (Phase 0 — asked first, before ASSESS/SCAFFOLD):**

```
Phase 0 (strategy): "Capture strategic anchor (STRATEGY.md) now?"
  Human: "Yes."
  Delegate to harness-strategy → first-run interview → STRATEGY.md written.
  Result: STRATEGY.md exists at repo root, doc-validated via validate_strategy (StrategyDocSchema);
  no project-level harness validate runs in Phase 0.
```

**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. Suggested tier: load-bearing-minimum (the standard starting point). Human opts down to basic for the first pass.
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 0 (persist grounding): user answered "Yes" in Phase 0 → STRATEGY.md already written; nothing to persist.

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: Intake
    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 `Intake`; 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`.

**GROUND (Phase 0 — asked first, before ASSESS/SCAFFOLD):**

```
Phase 0 (strategy): "Capture strategic anchor (STRATEGY.md) now?"
  Human: "Not sure."
  Result: no STRATEGY.md written, no init.strategy.declined flag; /harness:strategy stays available later.
```

**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.
Suggested tier: load-bearing-minimum (the standard starting point). Human opts down: "Basic is fine for this first pass."
```

**SCAFFOLD:**

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

**CONFIGURE:**

```
Phase 3 step 0 (persist grounding): user was "Not sure" in Phase 0 → nothing to persist.
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