harnessed 4.5.1 → 4.7.0

package/README.md

@@ -2,8 +2,9 @@
 
 **English** | [简体中文](./README-cn.md) | [繁體中文](./README-tw.md) | [日本語](./README-ja.md) | [한국어](./README-ko.md) | [Português (Brasil)](./README-pt-BR.md) | [Türkçe](./README-tr.md) | [Русский](./README-ru.md) | [Tiếng Việt](./README-vi.md) | [ไทย](./README-th.md)
 
-> AI coding harness package manager + composition orchestrator
-> Machine-executes the three-layer-stack collaboration methodology (gstack governance + GSD project manager + superpowers senior engineer + karpathy principles + mattpocock moves) as a runnable engine
+> **Turn raw Claude Code into a disciplined senior engineering team.** One install wires governance, planning, TDD, and review into a single Discuss→Ship workflow where progress and evidence persist on disk, not in chat.
+
+> _AI coding harness package manager + composition orchestrator_ — machine-executes the three-layer-stack collaboration methodology (gstack governance + GSD project manager + superpowers senior engineer + karpathy principles + mattpocock moves) as a runnable engine
 
 [![npm](https://img.shields.io/npm/v/harnessed?label=npm&color=blue)](https://npmjs.com/package/harnessed)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
@@ -17,7 +18,7 @@
 
 ## ✨ TL;DR
 
-**Best-practice orchestration for Harness Engineering on Claude Code** — assembles the best open-source Claude Code ecosystem components, weaving them into a unified workflow via opinionated composition skills; does not vendor upstream code — manifests describe install/check, and composition skills orchestrate multi-upstream collaboration.
+**How it works**: harnessed **assembles** the best open-source Claude Code agents (gstack, GSD, superpowers, planning-with-files) and **orchestrates** them into one workflow via opinionated composition skills. It does **not** vendor upstream code — manifests describe install/check, and composition skills conduct the multi-upstream collaboration (so an upstream upgrade is just a re-install, never a manual code sync).
 
 ### 🔁 The operating loop
 
@@ -76,6 +77,38 @@ The AI will auto-fetch the doc + run the install, handling OS / permissions / PA
 
 ---
 
+## ⏱️ First 5 Minutes
+
+The shortest path from zero to a running workflow:
+
+```bash
+# 1. Install (one line)
+npm install -g harnessed && harnessed setup
+```
+
+```
+# 2. Inside Claude Code — kick off your first workflow
+/auto "your first requirement"        # newcomer default: runs all stages end-to-end
+```
+
+```bash
+# 3. Lost? Run harnessed with no arguments — it tells you where you are + what's next
+harnessed
+#   → you-are-here dashboard (active phase + per-step status) + a NEXT: auto|manual|done line
+#   no need to remember status / next / resume — one command (comet `/comet` analog, read-only)
+#   add --json for machine-readable output
+```
+
+```bash
+# 4. Resume any time after an interruption
+harnessed            # same you-are-here view
+harnessed resume     # continue from the latest checkpoint
+```
+
+> Want finer control over which stage runs and when? See the 3 modes below.
+
+---
+
 ## 🚀 Quick Start — 3 Options
 
 In order of increasing user intervention:
@@ -405,6 +438,7 @@ planning-with-files /plan (cross-cutting tool) → write artifacts to .planning/
 | `harnessed gates <master>` | Evaluate which sub-workflows fire for a master stage (JSON: fire/skip/parallelism). Used by slash commands to orchestrate native spawns. |
 | `harnessed prompt <sub>` | Output a spawn-ready prompt (role + checklist + disciplines + completion/clarification protocols) for a sub-workflow. |
 | `harnessed checkpoint <action> <sub>` | Record sub-workflow start/complete/fail to `~/.claude/harnessed/checkpoints/`. |
+| `harnessed` (no args) | Zero-arg you-are-here: active-workflow dashboard + `NEXT: auto\|manual\|done` + run hint; `--json` machine-readable; no active workflow → onboarding hint (comet `/comet` analog, read-only). |
 | `harnessed next` | Deterministic next-step contract (`NEXT: auto\|manual\|done`) for the active workflow. |
 | `harnessed reject <sub>` | Mark a sub as user-rejected (terminal, distinct from `failed`). |
 | `harnessed compact [--tokens <n>]` | Summarize+evict resolved ledger entries (G6-safe: `fail_count>0` never evicted); auto-triggers on `checkpoint complete --tokens`. |
@@ -416,6 +450,7 @@ planning-with-files /plan (cross-cutting tool) → write artifacts to .planning/
 | `harnessed doctor` | 14-check health check (Node / MCP / jq / Win bash / routing / token budget / mattpocock / CodeGraph / update-available, etc.) |
 | `harnessed update [--check\|--upstreams\|--migration-report]` | Self-update (`npm i -g harnessed@latest`); `--check` reports the latest version; `--upstreams` re-runs the base manifests; `--migration-report` is a read-only stale-state inventory |
 | `harnessed release-preflight` | Read-only release-readiness gate (CHANGELOG `[Unreleased]` / version / git-clean / tag-absent); exits 1 if not ready. The Ship-stage gate. |
+| `harnessed retro --done` | Reset the retro-reminder phase counter after running `/retro` (clears the per-turn RETRO-DUE nudge). |
 | `harnessed install <name>` | Install an upstream manifest |
 | `harnessed uninstall [name]` | Reverse uninstall |
 | `harnessed backup` | Snapshot backup management |

package/bin/harnessed-inject-state.mjs

@@ -65,6 +65,17 @@ function workflowStateBlock(wf) {
         `BREAK-LOOP: sub '${e.sub}' failed ${e.fail_count}x — stop retrying, run break-loop skill`,
       )
   }
+  // Phase 22 — smart-reminder lines from envelope flags (parity with injectState.ts).
+  if (wf.ship_ready) {
+    lines.push(
+      `SHIP-READY: ${wf.ship_commits ?? 0} commit(s) since the last release tag — consider shipping (harnessed release-preflight, then /ship)`,
+    )
+  }
+  if (wf.retro_due) {
+    lines.push(
+      'RETRO-DUE: enough phases completed since the last retro — run /retro, then `harnessed retro --done`',
+    )
+  }
   lines.push('</workflow-state>')
   return lines.join('\n')
 }