docs: clarify agent command UX

AGENTS.md

@@ -37,6 +37,10 @@ conventions.
 
 ## Command Routing
 
+- `/harness adopt`: use `commands/harness-adopt.md`. Apply prompt-first
+  harness engineering to the target repository. Inspect first, preserve target
+  source-of-truth, avoid blind template copying, and finish with an adoption
+  report.
 - `/harness doctor`: use `commands/harness-doctor.md`. It is diagnostic only:
   inspect and report, do not modify files, and do not remove a target-local
   `./harness-starter-kit` directory.
@@ -78,8 +82,9 @@ decisions, known failures, drift checks, and recommended next work.
 ## Editing This Kit
 
 - Read the relevant workflow doc before changing command behavior:
-  `commands/harness-doctor.md`, `commands/harness-update.md`, or
-  `commands/harness-refresh.md`, or `commands/harness-review.md`.
+  `commands/harness-adopt.md`, `commands/harness-doctor.md`,
+  `commands/harness-update.md`, `commands/harness-refresh.md`, or
+  `commands/harness-review.md`.
 - For adoption behavior, keep `docs/adoption-workflow.md`,
   `docs/prompts/apply-to-target-repo.md`, `docs/templates/adoption-report.md`,
   and examples aligned.

CHANGELOG.md

@@ -4,6 +4,24 @@ Notable project changes should be recorded here before release tags are cut.
 
 ## Unreleased
 
+## v0.1.15 - 2026-06-18
+
+Patch release for clearer Codex and Claude command UX.
+
+### Added
+
+- Canonical `/harness adopt` command workflow for first-time prompt-first
+  adoption.
+- Decision and task-outcome evidence for the stage-based command UX model.
+
+### Changed
+
+- Present harness commands by user stage: First time, Daily work, and
+  Maintenance.
+- Align Codex and Claude Code command examples around the same
+  `doctor → adopt`, `review`, and `update`/`refresh` flow.
+- Bump Agent Skills plugin manifests to `0.1.15` for the command UX release.
+
 ## v0.1.14 - 2026-06-14
 
 Patch release for corrected Claude Code marketplace launch guidance.

README.ja.md

@@ -164,7 +164,7 @@ Codex と Claude Code の runtime-native skills として install できます
 ### Codex
 
 ```bash
-codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.14
+codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.15
 ```
 
 Codex を再起動し、Plugins 画面を開いて `Harnessworks` marketplace から
@@ -180,7 +180,7 @@ $harness-review
 ### Claude Code
 
 ```bash
-claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.14
+claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.15
 claude plugin install harness-agent-skills@harnessworks
 ```
 

README.ko.md

@@ -162,7 +162,7 @@ Claude Code에서 runtime-native skills로 설치할 수도 있습니다.
 ### Codex
 
 ```bash
-codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.14
+codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.15
 ```
 
 Codex를 재시작한 뒤 Plugins 화면을 열고 `Harnessworks` marketplace에서
@@ -178,7 +178,7 @@ $harness-review
 ### Claude Code
 
 ```bash
-claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.14
+claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.15
 claude plugin install harness-agent-skills@harnessworks
 ```
 

README.md

@@ -155,22 +155,34 @@ Every recurring agent failure should be converted into at least one durable
 artifact: a clearer instruction, an automated constraint, a test or CI check, a
 decision or failure record, or a drift check.
 
-## Commands
+## Command Flow
 
 The `/harness ...` names below are prompt conventions by default, not built-in
 editor commands. Type or paste them into your coding agent chat. In editors such
 as Cursor, they will not appear in the command palette unless you separately add
 matching custom slash commands.
 
-| Command | Use when |
-| --- | --- |
-| `/harness doctor` | Score baseline harness evidence without modifying files. |
-| `/harness update` | Refresh the local `./harness-starter-kit` reference after adoption. |
-| `/harness refresh` | Review stale, duplicated, obsolete, or unused target harness guidance. |
-| `/harness review` | Challenge the current change set before finishing. |
-| `/harness review sub-agent` | Explicitly request a read-only reviewer subagent when the runtime permits it. |
+Think about the commands by user stage:
+
+| Stage | Command | Use when |
+| --- | --- | --- |
+| First time | `/harness doctor` | Inspect current harness readiness without modifying files. |
+| First time | `/harness adopt` | Apply the smallest useful harness pieces to this repository. |
+| Daily work | `/harness review` | Challenge the current diff before commit or PR. |
+| Daily work | `/harness review sub-agent` | Explicitly request a read-only reviewer subagent when the runtime permits it. |
+| Maintenance | `/harness update` | Bring in a newer `harness-starter-kit` reference and selectively update this repo. |
+| Maintenance | `/harness refresh` | Clean up stale, duplicated, obsolete, or unused harness guidance already in this repo. |
+
+Quick rule:
+
+- Use `doctor` to inspect.
+- Use `adopt` to start.
+- Use `review` before finishing work.
+- Use `update` when the kit version changes.
+- Use `refresh` when this repo's existing harness guidance gets stale.
 
 See [`commands/`](commands/) for full workflows:
+[`adopt`](commands/harness-adopt.md),
 [`doctor`](commands/harness-doctor.md),
 [`update`](commands/harness-update.md),
 [`refresh`](commands/harness-refresh.md),
@@ -184,33 +196,65 @@ published as runtime-native skills for Codex and Claude Code.
 ### Codex
 
 ```bash
-codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.14
+codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.15
 ```
 
 Restart Codex, open the Plugins screen, select `Harnessworks`, and install
 `harness-agent-skills`.
 
-Use:
+Use the same command model in every runtime:
+
+```text
+Start:      $harness doctor → $harness adopt
+Daily:      $harness review
+Maintain:   $harness update or $harness refresh
+```
+
+Common commands:
 
 ```text
 $harness doctor
-$harness-review
+$harness adopt
+$harness review
+```
+
+Maintenance commands:
+
+```text
+$harness update
+$harness refresh
 ```
 
 ### Claude Code
 
 ```bash
-claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.14
+claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.15
 claude plugin install harness-agent-skills@harnessworks
 ```
 
-Use:
+Use the router command:
+
+```text
+Start:      /harness-agent-skills:harness doctor → /harness-agent-skills:harness adopt
+Daily:      /harness-agent-skills:harness review
+Maintain:   /harness-agent-skills:harness update or /harness-agent-skills:harness refresh
+```
+
+Common commands:
 
 ```text
 /harness-agent-skills:harness doctor
+/harness-agent-skills:harness adopt
 /harness-agent-skills:harness review
 ```
 
+Maintenance commands:
+
+```text
+/harness-agent-skills:harness update
+/harness-agent-skills:harness refresh
+```
+
 The source package lives in [`agent-skills/`](agent-skills/). For direct
 repo-local installs, packaging details, and update behavior, see
 [`docs/agent-skills-package.md`](docs/agent-skills-package.md).

README.zh-CN.md

@@ -161,7 +161,7 @@ Claude Code 的 runtime-native skills 安装。
 ### Codex
 
 ```bash
-codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.14
+codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.15
 ```
 
 重启 Codex，打开 Plugins 页面，在 `Harnessworks` marketplace 中安装
@@ -177,7 +177,7 @@ $harness-review
 ### Claude Code
 
 ```bash
-claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.14
+claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.15
 claude plugin install harness-agent-skills@harnessworks
 ```
 

README.zh-TW.md

@@ -162,7 +162,7 @@ Claude Code 的 runtime-native skills 安裝。
 ### Codex
 
 ```bash
-codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.14
+codex plugin marketplace add harnessworks/harness-agent-skills-marketplace --ref v0.1.15
 ```
 
 重新啟動 Codex，開啟 Plugins 畫面，在 `Harnessworks` marketplace 中安裝
@@ -178,7 +178,7 @@ $harness-review
 ### Claude Code
 
 ```bash
-claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.14
+claude plugin marketplace add harnessworks/harness-agent-skills-marketplace@v0.1.15
 claude plugin install harness-agent-skills@harnessworks
 ```
 

agent-skills/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-agent-skills",
   "displayName": "Harness Agent Skills",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Portable Harness Starter Kit workflows for Claude Code.",
   "author": {
     "name": "Harnessworks",

agent-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-agent-skills",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Universal Agent Skills package for applying Harness Starter Kit workflows in coding-agent repositories.",
   "author": {
     "name": "Harnessworks",

agent-skills/references/package-contract.md

@@ -9,7 +9,8 @@ for target-repository judgment.
    docs, package manager, CI, naming, and conventions.
 2. If the target has a local Harness Starter Kit clone, prefer its canonical
    workflow docs:
-   - adoption: `harness-starter-kit/docs/adoption-workflow.md`
+   - adoption: `harness-starter-kit/commands/harness-adopt.md`
+   - adoption background: `harness-starter-kit/docs/adoption-workflow.md`
    - doctor: `harness-starter-kit/commands/harness-doctor.md`
    - update: `harness-starter-kit/commands/harness-update.md`
    - refresh: `harness-starter-kit/commands/harness-refresh.md`

commands/harness-adopt.md

@@ -0,0 +1,115 @@
+# /harness adopt
+
+Apply Harness Starter Kit to the current target repository with the prompt-first
+adoption workflow.
+
+Harness Adopt may modify target repository files, but it must stay conservative:
+inspect first, preserve the target repository as the source of truth, and add
+only the smallest useful harness pieces.
+
+## Goal
+
+Turn the target repository's real conventions, checks, repeated mistakes, and
+review expectations into durable harness artifacts: agent instructions,
+constraints, feedback loops, memory, evaluation, and governance.
+
+This command is for first-time adoption. It is not a blind installer and not a
+request to copy every starter-kit template.
+
+## Procedure
+
+1. Treat the current working directory as the target repository root.
+2. Inspect the target repository before editing:
+   - `git status --short --branch`
+   - existing `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, or
+     `.github/copilot-instructions.md`
+   - `README.md`, `CONTRIBUTING.md`, package manifests, CI configs, and local
+     verification commands
+   - existing docs under `docs/`, especially decisions, failures, conventions,
+     domain notes, and evaluation records
+3. If `./harness-starter-kit` exists, treat it as read-only reference material.
+   If it does not exist and the user asked you to use this kit from GitHub, clone
+   `https://github.com/harnessworks/harness-starter-kit` into that path for
+   reference.
+4. Read the canonical adoption workflow from the local kit reference when
+   available:
+   - `./harness-starter-kit/docs/adoption-workflow.md`
+   - `./harness-starter-kit/docs/prompts/apply-to-target-repo.md`
+   - relevant profile snippets under
+     `./harness-starter-kit/templates/profiles/<profile>/`
+5. Select the smallest useful adoption set for this target. Prefer updating
+   existing docs/configs over adding parallel files.
+6. Add or update only artifacts that fit the target's existing architecture,
+   tools, package manager, docs, commands, and conventions. Common candidates:
+   - agent instructions
+   - lightweight drift checks
+   - decision or failure memory templates
+   - convention or domain notes
+   - an adoption report with verification and measurement plan
+7. Do not add CI, pre-commit hooks, dependencies, package scripts, or broad
+   architecture rules unless they match the target's existing workflow and the
+   maintainer asked for that level of enforcement.
+8. Run relevant local checks using the target repository's existing tools, plus
+   any adopted harness checks.
+9. Finish with the required report format and state whether the nested
+   `./harness-starter-kit` reference should be removed, ignored, or kept before
+   commit.
+
+## Required Report Format
+
+```text
+Harness Adoption Report
+
+Target State:
+- Branch/status: <summary>
+- Existing tools and verification commands: <summary>
+- Existing agent/harness files reviewed: <files or none>
+
+Applied:
+- <target-specific harness artifact added or updated>
+
+Skipped:
+- <starter-kit template/profile/check skipped and why>
+
+Checks Run:
+- <command>: <result>
+
+Assumptions:
+- <assumption made while adapting the kit, or none>
+
+Manual Steps:
+- <maintainer action needed, or none>
+
+Failure Memory:
+- Recorded: <docs/failures/... or none>
+- Detection/prevention check: <test, fixture, smoke check, lint rule, drift check,
+  CI gate, manual review point, or reason none is practical>
+- Skipped: <reason if no failure note was added>
+
+Effectiveness Measurement Plan:
+- Baseline available: <yes/no/unknown>
+- Tasks to track: <next comparable tasks>
+- Primary metric: <wrong-file edits, first-pass verification, repeated mistakes,
+  drift detections, human rework, or other>
+- Review window: <for example, next 5 agent PRs>
+- Recording location: <where future outcomes should be stored>
+
+Gate Placement:
+- Normal completion gate: <commands agents should run before finishing>
+- Focused/manual checks: <checks excluded from normal gate and why>
+
+Reference Clone:
+- `./harness-starter-kit`: <remove, ignore, keep intentionally, or not present>
+```
+
+## Safety Rules
+
+- Do not blindly copy templates.
+- Do not overwrite existing target files wholesale.
+- Do not delete, move, re-clone, or clean up target files without explicit user
+  approval.
+- Treat profile snippets as reference material, not mandatory transformations.
+- Preserve the target repository's existing architecture, tools, docs, package
+  manager, commands, and conventions.
+- If no safe useful adoption is available, report that clearly instead of making
+  cosmetic harness changes.