diff --git a/AGENTS.md b/AGENTS.md index 2906cee..3f4b059 100644 --- a/AGENTS.md +++ b/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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 091ac33..23b1729 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.ja.md b/README.ja.md index 99856cf..e84e8f1 100644 --- a/README.ja.md +++ b/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 ``` diff --git a/README.ko.md b/README.ko.md index b1ac7e0..a917ded 100644 --- a/README.ko.md +++ b/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 ``` diff --git a/README.md b/README.md index 78ba380..d30a8a2 100644 --- a/README.md +++ b/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). diff --git a/README.zh-CN.md b/README.zh-CN.md index bb1cb0f..ccc629b 100644 --- a/README.zh-CN.md +++ b/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 ``` diff --git a/README.zh-TW.md b/README.zh-TW.md index c16a3dc..5ac80b0 100644 --- a/README.zh-TW.md +++ b/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 ``` diff --git a/agent-skills/.claude-plugin/plugin.json b/agent-skills/.claude-plugin/plugin.json index faf80b7..cb26bef 100644 --- a/agent-skills/.claude-plugin/plugin.json +++ b/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", diff --git a/agent-skills/.codex-plugin/plugin.json b/agent-skills/.codex-plugin/plugin.json index 74daa34..378ad15 100644 --- a/agent-skills/.codex-plugin/plugin.json +++ b/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", diff --git a/agent-skills/references/package-contract.md b/agent-skills/references/package-contract.md index 643ae1a..1cb6310 100644 --- a/agent-skills/references/package-contract.md +++ b/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` diff --git a/commands/harness-adopt.md b/commands/harness-adopt.md new file mode 100644 index 0000000..e6916ed --- /dev/null +++ b/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//` +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: +- Existing tools and verification commands: +- Existing agent/harness files reviewed: + +Applied: +- + +Skipped: +- + +Checks Run: +- : + +Assumptions: +- + +Manual Steps: +- + +Failure Memory: +- Recorded: +- Detection/prevention check: +- Skipped: + +Effectiveness Measurement Plan: +- Baseline available: +- Tasks to track: +- Primary metric: +- Review window: +- Recording location: + +Gate Placement: +- Normal completion gate: +- Focused/manual checks: + +Reference Clone: +- `./harness-starter-kit`: +``` + +## 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. diff --git a/docs/agent-skills-package.md b/docs/agent-skills-package.md index 38360dd..599c526 100644 --- a/docs/agent-skills-package.md +++ b/docs/agent-skills-package.md @@ -89,9 +89,18 @@ codex plugin marketplace add "$MARKETPLACE_ROOT" ``` After registering the marketplace, restart Codex and install -`harness-agent-skills` from the plugin directory. When iterating locally, copy -the updated `agent-skills/` directory into the marketplace plugin path again and -restart Codex so the updated package is discovered. +`harness-agent-skills` from the plugin directory. Use the same stage model as +other runtimes: + +```text +Start: $harness doctor → $harness adopt +Daily: $harness review +Maintain: $harness update or $harness refresh +``` + +When iterating locally, copy the updated `agent-skills/` directory into the +marketplace plugin path again and restart Codex so the updated package is +discovered. ## Claude Code Usage @@ -131,11 +140,13 @@ To test the package locally without installing from a remote marketplace: claude --plugin-dir ./agent-skills ``` -Inside Claude Code, plugin skills are namespaced by plugin name. Invoke the -router as: +Inside Claude Code, plugin skills are namespaced by plugin name. Use the router +with the same stage model as other runtimes: ```text -/harness-agent-skills:harness doctor +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 ``` To test through a local Claude marketplace, copy the plugin into a temporary diff --git a/docs/component-map.md b/docs/component-map.md index 6f0c3d1..abfc38d 100644 --- a/docs/component-map.md +++ b/docs/component-map.md @@ -17,6 +17,7 @@ This map connects harness engineering concepts to files in a target repository. | Failure-memory check | `scripts/check_failure_memory.py` | `templates/generic/scripts/check_failure_memory.py` | | Decision-memory diff warning | `scripts/check_decision_memory.py`, `.harness/decision-memory-rules.json` | `templates/generic/scripts/check_decision_memory.py`, `templates/generic/.harness/decision-memory-rules.json` | | Harness readiness diagnostic | six-element `/harness doctor` report with coupling findings | `commands/harness-doctor.md`, `docs/scoring/harness-score-rubric.md` | +| Harness adoption workflow | `/harness adopt` report | `commands/harness-adopt.md`, `docs/adoption-workflow.md`, `docs/templates/adoption-report.md` | | Harness source tracking | `.harness/source.json` | documented in `commands/harness-update.md` | | Harness update workflow | `/harness update` report | `commands/harness-update.md` | | Harness refresh workflow | `/harness refresh` report | `commands/harness-refresh.md` | @@ -56,6 +57,11 @@ Then grow the harness as the project and agent usage mature. Use the optional GitHub Actions workflow skeleton with `--with-ci` only after confirming the target repository uses GitHub Actions. +Use `/harness adopt` when the maintainer wants first-time prompt-first harness +adoption. The command inspects the target, applies only the smallest useful +harness pieces, and finishes with an adoption report and effectiveness +measurement plan. + Use `/harness doctor` when the maintainer wants a diagnostic score before or after adoption. The command reports readiness; it does not install harness files. diff --git a/docs/decisions/0010-stage-command-ux-for-agent-runtimes.md b/docs/decisions/0010-stage-command-ux-for-agent-runtimes.md new file mode 100644 index 0000000..1863e5d --- /dev/null +++ b/docs/decisions/0010-stage-command-ux-for-agent-runtimes.md @@ -0,0 +1,67 @@ +# 0010. Stage Command UX For Agent Runtimes + +## Status + +Accepted + +## Context + +Harness Starter Kit exposes prompt-first workflows through README prompts, +`/harness ...` prompt conventions, Codex skills, and Claude Code plugin skills. +The workflow set had the right primitives, but the user-facing presentation made +new users compare individual commands before understanding when to use them. + +The most confusing areas were: + +- first-time adoption was documented as a large Quick Start prompt, while the + runtime skills already supported `/harness adopt` +- `doctor`, `review`, `update`, and `refresh` were listed as peers even though + they belong to different stages of use +- Codex and Claude Code examples showed different small command subsets, making + the runtime-native UX look inconsistent +- `update` and `refresh` are both maintenance actions, but they operate on + different sources: the kit reference versus the target repository's existing + harness guidance + +## Decision + +Present command UX by user stage across README and Agent Skills docs: + +- First time: `doctor` to inspect, then `adopt` to apply the smallest useful + harness pieces +- Daily work: `review` before commit or PR +- Maintenance: `update` for newer kit-source adoption, `refresh` for stale local + target harness guidance + +Add `commands/harness-adopt.md` as the canonical command workflow for first-time +adoption while keeping `docs/adoption-workflow.md` as the deeper background +workflow. Keep Codex and Claude Code examples aligned to the same stage model, +even though Claude plugin invocation is namespaced. + +## Rationale + +- Stage-based commands are easier for new users than a flat command list. +- Keeping `adopt` explicit closes the gap between the first-prompt README flow + and the runtime-native `harness-adopt` skill. +- Grouping `update` and `refresh` under Maintenance reduces naming confusion + without breaking existing command names. +- The target repository remains the source of truth because `adopt` is still a + prompt-first workflow, not a blind installer. + +## Alternatives Considered + +- Add a new `/harness maintain` command. Rejected for now because it would add a + new command surface before the simpler documentation and routing cleanup is + proven useful. +- Rename `update` and `refresh`. Rejected because existing docs, skills, and + user habits already use those names; stage grouping is lower risk. +- Keep adoption only as a Quick Start prompt. Rejected because Codex and Claude + users need the same mental model as prompt-only users. + +## Agent Guidance + +When explaining commands, use the stage model first: First time, Daily work, +Maintenance. Do not present `update` and `refresh` as generic synonyms. Say that +`update` brings in a newer kit reference and `refresh` cleans up existing target +harness guidance. Treat `/harness adopt` as first-time prompt-first adoption, not +an automatic template installer. diff --git a/docs/examples/task-outcomes/020-command-ux-stage-flow.yaml b/docs/examples/task-outcomes/020-command-ux-stage-flow.yaml new file mode 100644 index 0000000..d28c112 --- /dev/null +++ b/docs/examples/task-outcomes/020-command-ux-stage-flow.yaml @@ -0,0 +1,95 @@ +schema_version: 1 + +target: + repository: harnessworks/harness-starter-kit + repository_ref: main at 3aae5aa before local edits + stack_or_framework: Markdown command docs, Python unittest, Agent Skills packaging + date: 2026-06-18 + agent_or_model: Hermes Agent + reviewer: primary agent with local validation + +task: + id: command-ux-stage-flow + run_id: harness-starter-kit-020 + prompt_summary: Clarify Codex and Claude command UX by organizing harness commands into first-time, daily-work, and maintenance stages. + prompt_ref: current Hermes thread request "ux 정리를 진행하자" + prompt_hash: not recorded + comparable_task_group: harness-maintenance + condition: harnessed-only + expected_boundary: + - README.md + - README.ko.md + - README.ja.md + - README.zh-CN.md + - README.zh-TW.md + - CHANGELOG.md + - AGENTS.md + - agent-skills/.codex-plugin/plugin.json + - agent-skills/.claude-plugin/plugin.json + - commands/harness-adopt.md + - docs/agent-skills-package.md + - docs/component-map.md + - agent-skills/references/package-contract.md + - scripts/check_agent_skills_package.py + - tests/test_readme_prompt_drift.py + - tests/test_agent_skills_package.py + - docs/decisions/0010-stage-command-ux-for-agent-runtimes.md + - docs/examples/task-outcomes/020-command-ux-stage-flow.yaml + known_failure_mode: Command UX can become runtime-specific, omit the first-time adopt path, or make update and refresh look like interchangeable maintenance commands. + +harness_context: + harness_doctor_score: 100/100 after implementation; this record is harness-maintenance evidence, not effectiveness proof + harness_source: + kit_url: https://github.com/harnessworks/harness-starter-kit + kit_commit: 3aae5aa + source_tracking_ref: none; this repository is the kit source + relevant_instructions: + - AGENTS.md + - README.md + - docs/agent-skills-package.md + relevant_constraints: + - python3 -m unittest tests.test_readme_prompt_drift tests.test_agent_skills_package tests.test_repository_hygiene + - python3 scripts/check_agent_skills_package.py + - python3 scripts/check_docs_drift.py + - python3 scripts/check_structure.py + - python3 scripts/check_decision_memory.py + relevant_memory_records: + - docs/decisions/0008-universal-agent-skills-package.md + - docs/decisions/0009-claude-code-plugin-marketplace.md + - docs/decisions/0010-stage-command-ux-for-agent-runtimes.md + +outcome: + files_changed: + - README.md + - README.ko.md + - README.ja.md + - README.zh-CN.md + - README.zh-TW.md + - CHANGELOG.md + - AGENTS.md + - agent-skills/.codex-plugin/plugin.json + - agent-skills/.claude-plugin/plugin.json + - commands/harness-adopt.md + - docs/agent-skills-package.md + - docs/component-map.md + - agent-skills/references/package-contract.md + - scripts/check_agent_skills_package.py + - tests/test_readme_prompt_drift.py + - tests/test_agent_skills_package.py + - docs/decisions/0010-stage-command-ux-for-agent-runtimes.md + - docs/examples/task-outcomes/020-command-ux-stage-flow.yaml + wrong_file_edits: 0 + repeated_known_mistake: false + verification_command: python3 -m unittest discover -s tests && python3 -m py_compile scripts/apply_harness.py scripts/check_agent_skills_package.py scripts/check_docs_drift.py scripts/check_structure.py scripts/check_encoding_hygiene.py scripts/check_effectiveness_plan.py scripts/check_failure_memory.py scripts/check_decision_memory.py scripts/harness_doctor.py && python3 scripts/check_agent_skills_package.py && python3 scripts/check_docs_drift.py && python3 scripts/check_structure.py && python3 scripts/check_encoding_hygiene.py && python3 scripts/check_effectiveness_plan.py && python3 scripts/check_failure_memory.py && python3 scripts/check_decision_memory.py && python3 scripts/harness_doctor.py --target . && git diff --check + first_pass_verification: + result: passed after adding the decision record required by decision-memory review; unittest, py_compile, package check, docs drift, structure, encoding, effectiveness, failure memory, decision memory, Harness Doctor, and diff whitespace checks completed successfully + drift_violations_detected: [] + human_rework_minutes: 0 + reverted_files: [] + notes: Added failing regression tests first for README command-stage UX and Codex/Claude adopt command visibility, then updated docs and package contract to pass them. + +follow_up: + harness_change_needed: false + decision_or_failure_record: Decision record added in docs/decisions/0010-stage-command-ux-for-agent-runtimes.md; no failure record because this was a UX clarification rather than a recurring runtime failure fix. + include_in_effectiveness_report: false + include_in_comparable_product_task_count: false diff --git a/scripts/check_agent_skills_package.py b/scripts/check_agent_skills_package.py index bb0f4b9..12bb754 100644 --- a/scripts/check_agent_skills_package.py +++ b/scripts/check_agent_skills_package.py @@ -17,7 +17,7 @@ REFERENCES_ROOT = PACKAGE_ROOT / "references" CODEX_PLUGIN_MANIFEST = PACKAGE_ROOT / ".codex-plugin" / "plugin.json" CLAUDE_PLUGIN_MANIFEST = PACKAGE_ROOT / ".claude-plugin" / "plugin.json" -PACKAGE_VERSION = "0.1.14" +PACKAGE_VERSION = "0.1.15" WORKFLOW_SKILLS = { "harness": None, @@ -210,6 +210,7 @@ def validate_references(errors: list[str]) -> None: if contract.exists(): text = contract.read_text(encoding="utf-8") for canonical in ( + "commands/harness-adopt.md", "commands/harness-doctor.md", "commands/harness-update.md", "commands/harness-refresh.md", diff --git a/tests/test_agent_skills_package.py b/tests/test_agent_skills_package.py index 0903f20..c34e310 100644 --- a/tests/test_agent_skills_package.py +++ b/tests/test_agent_skills_package.py @@ -28,7 +28,7 @@ def test_codex_plugin_manifest_points_to_packaged_skills(self) -> None: ) self.assertEqual("harness-agent-skills", manifest["name"]) - self.assertEqual("0.1.14", manifest["version"]) + self.assertEqual("0.1.15", manifest["version"]) self.assertEqual("./skills/", manifest["skills"]) self.assertEqual("MIT", manifest["license"]) self.assertIn("$harness", " ".join(manifest["interface"]["defaultPrompt"])) @@ -42,7 +42,7 @@ def test_claude_plugin_manifest_points_to_packaged_skills(self) -> None: self.assertEqual("harness-agent-skills", manifest["name"]) self.assertEqual("Harness Agent Skills", manifest["displayName"]) - self.assertEqual("0.1.14", manifest["version"]) + self.assertEqual("0.1.15", manifest["version"]) self.assertEqual("MIT", manifest["license"]) self.assertEqual( "https://github.com/harnessworks/harness-starter-kit", @@ -50,6 +50,17 @@ def test_claude_plugin_manifest_points_to_packaged_skills(self) -> None: ) self.assertIn("claude-code", manifest["keywords"]) + def test_agent_skills_docs_show_codex_and_claude_adopt_commands(self) -> None: + readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8") + package_doc = (REPO_ROOT / "docs" / "agent-skills-package.md").read_text( + encoding="utf-8" + ) + + self.assertIn("$harness adopt", readme) + self.assertIn("/harness-agent-skills:harness adopt", readme) + self.assertIn("$harness adopt", package_doc) + self.assertIn("/harness-agent-skills:harness adopt", package_doc) + def test_claude_plugin_validate_passes_when_claude_is_available(self) -> None: if shutil.which("claude") is None: self.skipTest("Claude Code CLI is not installed") diff --git a/tests/test_readme_prompt_drift.py b/tests/test_readme_prompt_drift.py index 6df899e..eb7eb5f 100644 --- a/tests/test_readme_prompt_drift.py +++ b/tests/test_readme_prompt_drift.py @@ -80,6 +80,22 @@ def language_switcher_entries( class ReadmePromptDriftTests(unittest.TestCase): + def test_readme_explains_command_flow_by_user_stage(self) -> None: + text = (REPO_ROOT / "README.md").read_text(encoding="utf-8") + + self.assertIn("## Command Flow", text) + self.assertIn("First time", text) + self.assertIn("Daily work", text) + self.assertIn("Maintenance", text) + self.assertIn("/harness adopt", text) + self.assertIn("commands/harness-adopt.md", text) + + first_time = text.index("First time") + daily_work = text.index("Daily work") + maintenance = text.index("Maintenance") + self.assertLess(first_time, daily_work) + self.assertLess(daily_work, maintenance) + def test_localized_readmes_are_valid_utf8(self) -> None: for path in localized_readmes(): with self.subTest(readme=path.name):