@pilotspace/add 1.6.0 → 1.7.1

package/CHANGELOG.md

@@ -4,6 +4,88 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [1.7.1] — 2026-06-18
+
+Installer depth and method quality release: the onboarding installer gains
+brand-aware prompts, readiness detection, and intent handoff; SOUL.md is now
+seeded on first install and update; scope drafting and build verification gain
+new depth guards. All additive; no breaking changes.
+
+### Added
+- **Brand-aware guided installer (`installer-smarts`)** — `add init` now prompts
+  for the user's brand/project name and detects whether ADD is already present
+  (readiness check); defaults to global scope and captures the user's first
+  intent, handing it off to the first `/add` session via `.add/.intent`.
+- **SOUL.md seeded on install and update (`installer-soul-seed`)** — `add init`
+  and `add update` now seed `.add/SOUL.md` from the bundled voice template if it
+  does not yet exist, so the voice file is present from the first session without
+  waiting for `add.py init`.
+- **Build expectations in VERIFY (`verify-expectations`)** — the §6 VERIFY step
+  gains a Build-expectations block: the AI pre-declares observable outcomes derived
+  from §2 scenarios + §3 contract, and verify confirms them — so a build is checked
+  correct, not merely test-green.
+
+### Changed
+- **Scope drafting quality guard (`scope-drafting-quality`)** — the scope guide now
+  requires the goal to be grounded in current project assets and the milestone map
+  before the goal sentence is drafted; a draft well-formedness gate catches
+  incomplete MILESTONE.md shapes early.
+
+## [1.7.0] — 2026-06-18
+
+The installer & onboarding release: standing up — or repairing — ADD is now one
+guided installer that adapts to the terminal and the agent, and the method's own
+build loop gained recorded delta resolution, guided choices at every human gate,
+and a milestone-close ship review. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **Guided, agent-aware, self-healing installer (`installer-experience`)** — `npx
+  @pilotspace/add` (and `pilotspace-add`) now runs an interactive `@clack/prompts`
+  onramp in a real terminal and degrades to a byte-identical plain-text flow in
+  CI / non-TTY (the pip twin matches, on the stdlib). It **detects the active agent**
+  (Claude Code · Claude app/cowork · Codex · OpenCode · generic) and writes that
+  agent's integration file (`CLAUDE.md` / `AGENTS.md`) as a marker-delimited pointer,
+  then prints that agent's exact next step. `init` **and** `update` now **heal/reconcile**
+  a partial `.add/` — restoring missing managed assets and refreshing stale ones
+  **without touching** `state.json` / `PROJECT.md` / milestones / tasks.
+- **Global install (`--global`)** — install the engine + book + skill once into a
+  shared ADD home (`ADD_HOME` → `XDG_DATA_HOME/add` → `~/.add`) and reuse it across
+  projects; `update --global` refreshes the home and propagates to every registered
+  project. The home mirrors the bundled layer; the registry is a flat, atomically
+  written `registry.json`, and a corrupt registry fails loud (read-before-write,
+  zero-mutation abort).
+- **Global data (`--global-data`)** — opt-in (implies `--global`): a one-way snapshot
+  of a project's **user-data** under `<home>/data/<key>` keyed by project path, so the
+  shared home remembers each opting project. The per-project, git-tracked default is
+  byte-unchanged; without the flag, data stays local.
+- **Claude Code plugin distribution** — ADD is now installable straight from a
+  marketplace, with no npm or pip step: `/plugin marketplace add pilotspace/ADD`
+  then `/plugin install add@add-method`. A repo-root `.claude-plugin/marketplace.json`
+  lists the `add` plugin, which bundles the skill, the engine, and the AIDD book; on
+  first run the skill materializes the engine and book INTO the project
+  (`cli.js init --no-skill`) so every agent and a human at the shell get a
+  self-contained result identical to an npm/pip install. The skill stays in the plugin
+  (no duplicate); boundaries are disclosed in the README and guarded by
+  `tooling/test_plugin_manifest.py`.
+- **Recorded delta resolution (`delta-resolution`)** — both delta types now resolve
+  explicitly: SPEC deltas get a `seed` / `drop` lifecycle and competency deltas
+  consolidate into the foundation via **`add.py fold`** (transcription-only, human-
+  authorized). `add.py check` stays green only when deltas are well-formed.
+- **Guided-choice prompts (`decision-suggestions`)** — every human gate (intake ·
+  bundle approval · verify · milestone close · release) renders a recommended pick
+  plus 1–3 described alternatives. Presentation-only — the engine is untouched.
+- **Milestone-close ship review (`ship-review`)** — closing a milestone now records a
+  cross-task ship review (ship-by-domain · per-task evidence · goal-met map) that the
+  existing engine gate reads, plus AI-defined release-step hints that feed `release.md`.
+
+### Notes
+- The `udd-design-loop` work (the `design.md` UDD loop + the wireframe/HTML-mock
+  recipe, described narratively under [1.5.0]) is attributed to this cut in the
+  `RELEASES.md` ledger — its first explicit ledger accounting.
+- **The engine records; the human ships.** `add.py release` recorded the `RELEASES.md`
+  row and this changelog lineage; it never bumps a version source, tags, or publishes.
+  The human-gated `git tag v1.7.0` triggers the npm / PyPI publish.
+
 ## [1.6.0] — 2026-06-16
 
 The releasing release: shipping a versioned cut is now a first-class **5th ADD

package/README.md

@@ -30,7 +30,7 @@ across sessions (context rot). ADD fixes both:
 
 ## Install
 
-Pick your ecosystem — both install the same skill, tooling, and book:
+Pick your ecosystem — all three install the same skill, tooling, and book:
 
 ```bash
 # Node / npm
@@ -43,6 +43,17 @@ pip install pilotspace-add
 pilotspace-add init
 ```
 
+```text
+# Claude Code plugin — no npm or pip needed
+/plugin marketplace add pilotspace/ADD
+/plugin install add@add-method
+```
+
+The plugin carries the engine and the book. On first `/add`, the skill materializes them
+into the project (`node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`) and scaffolds
+`.add/` — a self-contained, portable result identical to the npm/pip flow. The skill stays
+in the plugin, so nothing is duplicated.
+
 No flags needed — the project name is inferred from your folder and the stage
 defaults to `prototype` (pass `--name "My App" --stage mvp` to choose up front).
 
@@ -75,6 +86,28 @@ Project state (`.add/state.json`) and the living-documentation files (`CONVENTIO
 human-owned voice) are *not* created here — the installer drops files only;
 initialisation is the agent's first move when you run `/add`.
 
+## What this plugin does, writes, and runs (boundaries)
+
+ADD is a development methodology, so by design it works *inside your project* — here is
+exactly what that means, so there are no surprises:
+
+- **Runs only when you ask.** Nothing executes on install. The skill acts when you run
+  `/add` (or another agent follows the guideline block). It is user-initiated, every time.
+- **What it runs:** the bundled engine and bootstrapper only — `node bin/cli.js` and
+  `python3 .add/tooling/add.py`. No downloaded or remote code is executed; everything it
+  runs ships in the package.
+- **What it writes:** files under your project's `.add/` (state, milestones, tasks, the
+  book) and the managed guideline block in `CLAUDE.md` / `AGENTS.md`. On a plugin install
+  it also materializes the engine + book into `.add/` on first run. It writes nowhere
+  outside the project working directory; it never touches files above the project root.
+- **Network:** one optional, advisory update check. On `status` / `guide` the engine may
+  make a single HTTPS GET to `https://registry.npmjs.org/@pilotspace/add/latest` to see if
+  a newer version exists — at most once per 24h (cached in `.update-cache.json`), 1.5s
+  timeout, fail-open (offline ⇒ silent no-op). It only writes a one-line note to **stderr**
+  and never changes a command's output or exit code. Disable it entirely with
+  `ADD_NO_UPDATE_CHECK=1`. No other network access, no telemetry, no analytics.
+- **No secrets, no credentials, no privileged access.** Pure local file orchestration.
+
 ## Use it
 
 ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, run