@pilotspace/add 1.16.0 → 1.16.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.16.1] — 2026-07-04
+
+Patch: two loose, additive persona-loop improvements found while dogfooding
+ADD in a real consumer project. No engine validation changed; no CLI
+behavior changed; nothing removed or renamed.
+
+### Changed
+- **Persona seed nudge is project-scoped.** The setup/status/check/new-milestone
+  hint to draft a project's missing personas now names the project by scope
+  instead of a generic reminder, so it fires once per genuinely-uncovered
+  project rather than repeating a one-size-fits-all message.
+- **Persona schema template recommends `flow:` + `## Abilities`.** A seeded
+  persona can now state which ADD apply-surface (design/build/advisor) loads
+  it and what it can concretely do, distinct from `## Critical Rules`
+  (always-enforced constraints) and the optional `## Playbook`. Recommended,
+  not engine-checked — existing personas anywhere stay schema-conformant
+  with no forced re-seed.
+
 ## [1.16.0] — 2026-07-03
 
 Closes the **install-update-hardening** milestone: `add.py init`/`update` (both

package/README.md

@@ -39,7 +39,7 @@ pip install pilotspace-add && pilotspace-add init
 
 Then, in your coding agent, say what you want to build:
 
-> `/add` — *"I want to let users transfer money between their own accounts."*
+> `/add` — *"Let users log in with email + password / SSO, and keep them signed in for 30 days unless they explicitly log out."*
 
 The agent sizes it into a milestone (you confirm the shape), drafts the spec →
 scenarios → contract → tests as one bundle (you approve once, at the frozen
@@ -182,7 +182,7 @@ exactly what that means, so there are no surprises:
 ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, run
 **`/add`** and say what you want to build:
 
-> `/add` — *"I want to let users transfer money between their own accounts."*
+> `/add` — *"Let users log in with email + password / SSO, and keep them signed in for 30 days unless they explicitly log out."*
 
 **Works with your agent.** The installer detects which coding agent you're in and
 drops the context file it reads — so ADD drives through the CLI under **Claude Code,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/phases/0-setup.md

@@ -52,7 +52,7 @@ Capture each surfaced decision as an **ADR** in `PROJECT.md` **Key Decisions** a
 ## 3 · Draft to the lock (both paths)
 
 1. **Fill the living documentation**: `.add/PROJECT.md` (Domain · Spec · UI/UX · Key Decisions), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (delete if no UI; `design.md`). Brownfield: from code. Greenfield: from interview, gaps flagged `guessed`.
-   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). **Author one per role** from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches) — citing the teacher in `source:` and carrying its top `## Playbook` are the two optional parts, not the authoring. Covered by the **baseline approval**; `add.py check` validates; never clobber.
+   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). **Author one per role** from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches) — citing the teacher in `source:` and carrying its top `## Playbook` are the two optional parts, not the authoring. Covered by the **baseline approval**; `add.py check` validates; never clobber. Still unseeded later? `status`/`check`/`new-milestone`'s hint means: return here, draft every missing project persona — not just one.
 2. **Propose, then size it.** Float a **kickoff suggestion** for the first milestone: a **goal** (one sentence), a **flow** (task order), **scenarios** (examples of what ships). Not the frozen `MILESTONE.md`. On their reaction, draft `MILESTONE.md` (read `scope.md`).
 3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:
    ```bash

package/tooling/add.py

@@ -100,6 +100,7 @@ from add_engine.io_state import (  # re-exported as module globals: callers use
     _CONFLICT_MARKER_RE,                                            # conflict-marker re
     _load_state_for_json,                                          # --json state loader
     _md5_text, _md5_file,                                          # md5 hashing helpers
+    _personas_unseeded,                                            # persona-seed-nudge predicate
 )
 
 
@@ -1886,6 +1887,11 @@ def cmd_status(args: argparse.Namespace) -> None:
     # Existence-only: no open/parse, so the pointer adds no IO failure path (a non-file is no voice).
     if (root / "SOUL.md").exists():
         print("voice   : .add/SOUL.md  (how I sound & what keeps your trust — read each session)")
+    # persona pointer (persona-seed-nudge v2): project-wide, read every session like context/voice
+    # above — fires until >=1 REAL persona is seeded, self-clears once one lands. Advisory only;
+    # never gates, never touches the --json branch (human-readable orientation surface only).
+    if _personas_unseeded(root):
+        print(f"persona : {PERSONA_HINT}")
     # wave resume hint — a live ledger outranks memory (streams.md "Wave ledger").
     # Existence-only: no open/read/parse, so the hint adds no IO failure path; a
     # non-file at the path is not a ledger. One line PER live ledger — more than
@@ -2930,6 +2936,11 @@ def cmd_check(args: argparse.Namespace) -> None:
                                  "persona_schema_incomplete: missing " + ", ".join(missing)))
             else:
                 infos.append((f"persona '{slug}'", "schema-conformant"))
+    # persona-seed-nudge: surface the SAME "no real persona" gap `new-milestone` nudges on, so
+    # it is also visible on a plain `check`/`status` sweep — an INFO affirmation-of-absence,
+    # never a WARN (measure-not-block; a project with no personas behaves exactly as before).
+    if _personas_unseeded(root):
+        infos.append(("personas", f"unseeded — {PERSONA_HINT}"))
 
     # drift: a done milestone must have no unfinished tasks
     for mslug, m in milestones.items():
@@ -3431,6 +3442,12 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
     else:
         print("active milestone set." + ("" if not await_confirm else
               "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
+        # persona-seed-nudge: a non-blocking hint (never a gate) when this project has no
+        # REAL project-fit persona yet — points at the cross-cutting selection/drafting
+        # service rather than inventing a second mechanism. Fires only on the ACTIVE arm
+        # (a queued milestone isn't yet in flight, so the nudge would be premature there).
+        if _personas_unseeded(root):
+            print(f"note: {PERSONA_HINT}")
     print(_next_footer(root, state))   # converges the old "Decompose it into tasks: …" hint
 
 

package/tooling/add_engine/constants.py

@@ -24,6 +24,7 @@ __all__ = [
     "SETUP_FILES",
     "PERSONA_FRONTMATTER_KEYS",
     "PERSONA_REQUIRED_SECTIONS",
+    "PERSONA_HINT",
     "GUIDELINE_FILES",
     "RULES_FILE_REL",
     "WORKFLOW_HEADINGS",
@@ -99,6 +100,14 @@ SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md
 PERSONA_FRONTMATTER_KEYS = ("name", "vibe")
 PERSONA_REQUIRED_SECTIONS = ("## Identity", "## Critical Rules", "## Default Requirement", "## Success Metrics")
 
+# persona-seed-nudge v2: ONE hint, single-sourced — `new-milestone`/`check`/`status` all print
+# THIS constant (not their own copy) so the wording can never drift across the three surfaces.
+# Project-scoped (not "this milestone's domain") per the confirmed v2 amendment: the AI should
+# catch up ALL of a project's missing personas, not draft a single milestone-fit one.
+PERSONA_HINT = ("no project-fit persona seeded yet under .add/personas/ — spawn the add-persona "
+                "agent (or read docs/18-personas.md) to seed the project's persona(s) from "
+                "PROJECT.md's domain")
+
 # Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts
 # never reach git. Bare-filename patterns match at any depth under .add/ (tasks/,
 # milestones/, archive/). These are working state, not records: scope-snapshot.json

package/tooling/add_engine/io_state.py

@@ -199,3 +199,17 @@ def _md5_file(p: Path) -> str | None:
         return hashlib.md5(p.read_bytes()).hexdigest()
     except OSError:
         return None
+
+
+def _personas_unseeded(root: Path) -> bool:
+    """True when `.add/personas/` has no REAL (non-template) authored persona: the
+    directory is absent, empty, or holds only the seeded `_template.md` scaffold
+    (persona-seed-nudge). Fail-soft: an unreadable directory counts as unseeded
+    rather than raising — this feeds a `note:`/INFO hint, never a gate."""
+    d = root / "personas"
+    if not d.is_dir():
+        return True
+    try:
+        return not any(p.stem != "_template" for p in d.glob("*.md"))
+    except OSError:
+        return True

package/tooling/templates/personas/_template.md.tmpl

@@ -1,6 +1,10 @@
 ---
 name: <persona name — e.g. Frontend Engineer, UX Researcher>
 vibe: <one-line essence — what this persona keeps true>
+flow: <RECOMMENDED — which of the three apply-surfaces this persona is loaded at (see
+ docs/18-personas.md "Apply — three surfaces"): design (the UDD requirements lens) | build
+ (the domain-identity overlay on SOUL.md) | advisor (subagent/streams delegation, incl. the
+ verify refute-read) — comma-separate if more than one, e.g. `build, advisor`>
 source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/personas-teacher/engineering/engineering-software-architect.md` (provenance; omit if hand-authored)>
 ---
 <!-- A PERSONA is a project-fit requirements persona, distilled from the vendored teacher
@@ -9,8 +13,11 @@ source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/pe
      the teacher; the engine only seeds + validates this schema (presence-based). This
      `_template.md` is the schema reference — copy it to `<slug>.md` and fill it.
 
-     REQUIRED: `name` + `vibe` frontmatter and the Identity / Critical Rules /
+     REQUIRED (engine-checked): `name` + `vibe` frontmatter and the Identity / Critical Rules /
      Default Requirement / Success Metrics sections.
+     RECOMMENDED (not engine-checked, but expected on every persona for consistency): `flow:`
+     frontmatter and the `## Abilities` section — a persona with no stated flow or abilities is
+     hard for the design/build/advisor surfaces to actually pick up and use.
      OPTIONAL (recommended for a faithful distillation): `source:` frontmatter, and the
      `## Anti-patterns` + `## Playbook` sections. The engine never requires the optional
      parts; absence is conformant.
@@ -23,12 +30,25 @@ source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/pe
      3. TAG provenance honestly. In `## Playbook`, mark each item teacher-derived vs
         ADD-native. Never credit home-grown project scaffolding to the teacher.
      4. METRICS are rules, not snapshots. Prefer an invariant ("suite matches the last
-        green run") over a volatile literal ("2491/0") that rots as the project grows. -->
+        green run") over a volatile literal ("2491/0") that rots as the project grows.
+     5. NAME the flow. State which apply-surface(s) actually load this persona — a persona
+        that fits none of design/build/advisor is dead weight nobody will ever pick up.
+     6. ABILITIES are checkable skills, not aspirations. Anchor each to a real file, tool, or
+        command this project already has — the same anchoring discipline as Critical Rules
+        and Success Metrics, applied to "what this persona can concretely do." -->
 
 ## Identity
 <who this persona is — role, domain depth, and the EARNED perspective it brings (what it has
  seen succeed/fail that shapes its judgement). One short paragraph.>
 
+## Abilities
+<concrete, checkable things this persona can actually DO — a capability list, distinct from
+ Critical Rules (always-enforced constraints) and Playbook (optional step-by-step scaffolding).
+ State each as something the agent can perform right now, anchored to a real file/tool/command
+ where possible — not an aspiration.>
+- <a concrete capability — e.g. "can diff two response fixtures byte-for-byte to prove passthrough">
+- <another concrete capability>
+
 ## Critical Rules
 <non-negotiables this persona ALWAYS enforces. Lead with 1–2 carried from the teacher (its
  signature stance), then add project-specific ones.>