@antoneeo/agentic-sdlc-skill 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.14.0] - 2026-07-08 (M6: Vision Actors — a characterized cast in the Vision)
+### Changed
+- **Vision defines Actors.** The Vision templates replace the flat `## Target Users` / `## Users or Stakeholders` with a first-class `## Actors` element: one light line per actor — **Role** — primary goal; good UX = what a good experience means to them. An Actor is defined ONCE in the Vision (project or feature) and REFERENCED by each use-case / `D-UC` (actor = who they are, use-case = what they do) — anti-DRY, and enough to design the intended UX for concrete roles instead of an implicit "user". A feature may declare its own feature-local cast for internal-tooling work.
+- **`elicitation.md`**: the L3 elicitation round gains an explicit **Actors** question (role, primary goal, UX expectation); "for whom" is folded into it.
+- **`SKILL.md`**: the "Protect the Vision" value now names the actors + the UX they expect; the §3 Request-Analysis trace includes the actor each part serves.
+- **`review.md`**: the conformance set gains one rule — a use-case with no defined Actor, or an unmet Actor UX expectation, is a finding.
+- **README** Key Features refreshed to cover the delivered M1–M6 capabilities (execution disciplines, operative guides + agent-KB, opt-in subagent execution, self-activation, and Actors).
+
+### Process note
+Governed Hybrid (devPNT re-pointed at this project): M-VISION `milestone_vision_vision_actors` v1.0 → milestone M6 → ADR `adr_2026-07-08_vision_actors` (Light record; the reviewed `ANALYSIS_vision_actors.md` is the design detail). The devPNT M-VISION doctrine mirror (`mcp_system_prompt.md` §4.2 — the M-VISION gains an Actors element, added to the Vision-Alignment re-read + the amendment hard-stop) is a devPNT-source edit pending `setup_mcp.bat` redeploy. Independent fresh-context reviews PASS (ANALYSIS diff: 2 WARN fixed, incl. the change satisfying its own new rule; ADR light: 0 BLOCK). Doc-only: `check --hybrid` CLEAN, eval battery 51/51. No new shipped support files (allowlist unchanged).
+
 ## [1.13.0] - 2026-07-05 (M2 amendment: review reads AND proves Vision + Use-Cases + Threat Model)
 ### Changed
 - **Review discipline hardened (M2.A7).** `review.md` now, for an impact/solution-analysis / design review: (a) §Requesting takes the **Vision + use-cases/user-needs + threat model** as explicit inputs the reviewer checks the artifact *against* (Hybrid: M-VISION/D-UC/P-TM; Standalone: the ANALYSIS Vision-Alignment / Use-Cases / Threat-Model sections); (b) §Reviewing requires the reviewer OUTPUT to carry a **conformance/traceability statement** — each Vision benefit / use-case / threat mapped to where the artifact satisfies it, or a finding — and a PASS is **not valid on "found nothing"**. Scoped to analysis/design reviews (plain code reviews stay findings-only → honors the "no enforcement theater" Non-Goal); it is the reviewer-side twin of the existing §Receiving anti-silent-drop rule.

package/README.md

@@ -5,10 +5,14 @@
 ## Key Features
 
 - **Risk-proportional workflow**: L1/L2/L3/Spike triage avoids heavyweight process for trivial work.
-- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star.
+- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. The Vision names its **Actors** — the cast a feature serves, one light line each — so UX is designed for concrete roles, not an implicit "user".
+- **Execution disciplines**: explicit TDD (RED/GREEN/REFACTOR), systematic debugging, an L3 spec-elicitation round, and a single code-review definition wired into the workflow phases.
+- **Operative guides + agent-global KB**: distil user-provided indications into source-faithful `ai_docs/reference/GUIDE_*.md` — consulted before operative work, proposed after reusable work — shared cross-project via `~/.agentic-sdlc`.
+- **Opt-in subagent execution**: an approved design projects into a validated executable plan an orchestrator can drive through subagents.
+- **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
-- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer.
-- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `guides.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`; an agent-global KB at `~/.agentic-sdlc` shares the same engine cross-project.
+- **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer, with independent fresh-context reviews of technical artifacts and diffs.
+- **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `guides.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `ENFORCEMENT.md`, and `scripts/sdlc_check.py`.
 - **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates.
 
 ## Installation

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/skills/agentic-sdlc-skill/SKILL.md

@@ -25,7 +25,7 @@ Read these files only when needed. `SKILL.md` is the operating contract; the sup
 - **Preserve quality:** every change must maintain or improve stability, testability and maintainability.
 - **Verify technically:** close implementation work with tests, lint, smoke checks or an explicit reason.
 - **Keep useful memory:** document relevant decisions and operational state, not filler text.
-- **Protect the Vision:** every decision must stay aligned with expected benefits, users, non-goals and success signals.
+- **Protect the Vision:** every decision must stay aligned with expected benefits, the actors it serves (and the UX they expect), non-goals and success signals.
 
 If a patch looks easy but you do not understand why the current code is shaped the way it is, investigate first.
 
@@ -183,7 +183,7 @@ Standalone L3:
 - Before creating a new `ANALYSIS_[feature].md`, search `ai_docs/solutions/` with glob/grep for an existing analysis on the same topic: if there is one, update it instead of duplicating it.
 - Create or update `ai_docs/solutions/ANALYSIS_[feature].md`.
 - Minimum sections: Objective, Feature Vision (or Vision Alignment), Impact, Security and Threat Model, Action Plan, Test Strategy, Diary/Current State.
-- Build the Impact/solution **on** the Vision, the use-cases/user-needs and the Security & Threat Model — read and trace to them first, and state the trace (which use-case / threat / benefit each part serves) so the closure review (`review.md`) can verify conformance. Do not draft the Impact in isolation.
+- Build the Impact/solution **on** the Vision, the use-cases/user-needs and the Security & Threat Model — read and trace to them first, and state the trace (which actor / use-case / threat / benefit each part serves) so the closure review (`review.md`) can verify conformance. Do not draft the Impact in isolation.
 - For features spanning multiple milestones or multiple analyses, also create `ai_docs/vision/features/VISION_[feature].md`.
 
 Hybrid L3:

package/skills/agentic-sdlc-skill/elicitation.md

@@ -14,13 +14,17 @@ Ask ONE structured set of questions, not a drip of follow-ups. Keep each
 question short and numbered; offer concrete options where a real choice
 exists (this narrows the reply and speeds up the round). Cover:
 
-1. **Goal / benefit** — what problem this closes, for whom, and why now.
-2. **Scope boundaries** — what is explicitly included in this unit of work.
-3. **Non-goals** — what is explicitly excluded, so scope does not silently
+1. **Goal / benefit** — what problem this closes and why now.
+2. **Actors** — who interacts with this: their role, primary goal, and what
+   "good UX" means to them. These become the Vision's `## Actors`; each
+   use-case below attaches to one (actor = who they are, use-case = what
+   they do). Skip only when an approved Vision already names them.
+3. **Scope boundaries** — what is explicitly included in this unit of work.
+4. **Non-goals** — what is explicitly excluded, so scope does not silently
    creep in later.
-4. **Constraints** — technical, compatibility, and security constraints that
+5. **Constraints** — technical, compatibility, and security constraints that
    bound the solution space.
-5. **Acceptance signals** — how you and the user will both recognize the
+6. **Acceptance signals** — how you and the user will both recognize the
    work is done and correct.
 
 ## Reflect

package/skills/agentic-sdlc-skill/review.md

@@ -15,8 +15,9 @@ When you hand work to a reviewer (human or agent), give them:
   the change was built against — not a paraphrase of it.
 - **The actual diff**: the real changed files, not a description of them.
 - **For an impact/solution-analysis review, the constraints it derives from**:
-  the **Vision** (Hybrid: the `M-VISION`; Standalone: `project_vision.md`/`roadmap.md`
-  + the ANALYSIS Vision-Alignment), the **use-cases / user-needs** (Hybrid: `D-UC`;
+  the **Vision**, including its `## Actors` (Hybrid: the `M-VISION`; Standalone:
+  `project_vision.md`/`roadmap.md` + the ANALYSIS Vision-Alignment), the
+  **use-cases / user-needs** (Hybrid: `D-UC`;
   Standalone: the ANALYSIS `## Use Cases / User Needs`), and the **threat model**
   (Hybrid: `P-TM`; Standalone: the ANALYSIS `## Security and Threat Model`). Hand these
   *in addition to* the design artifact — the reviewer checks the artifact **against**
@@ -55,9 +56,10 @@ When you are the reviewer:
 - **Conformance statement (impact/solution-analysis & design reviews only — not a
   plain code-diff review).** When the artifact under review carries Vision / use-case
   / threat-model constraints, your output MUST map each constraint to its evidence: for
-  every use-case/user-need, every threat, and every applicable Vision benefit/Non-Goal,
-  state WHERE the artifact satisfies it (section or `file:line`) or raise it as a
-  finding. A PASS/approve is **not valid on "found nothing"** — the conformance
+  every use-case/user-need (and the Actor it serves — a use-case with no defined Actor,
+  or an Actor UX expectation the solution does not meet, is a finding), every threat, and
+  every applicable Vision benefit/Non-Goal, state WHERE the artifact satisfies it (section
+  or `file:line`) or raise it as a finding. A PASS/approve is **not valid on "found nothing"** — the conformance
   statement is the proof the check ran; an unfalsifiable "I checked" is the review
   theater this discipline exists to prevent (the reviewer-side twin of §Receiving's
   silent-drop rule). Plain code reviews stay findings-only.

package/skills/agentic-sdlc-skill/templates.md

@@ -87,7 +87,12 @@ Status: DRAFT
      or APPROVED (by <who>, <date>) — only after the user's explicit confirmation -->
 
 ## North Star
-## Target Users
+## Actors
+<!-- the cast this product serves. One light line per actor:
+     **Role** — primary goal; good UX = what a good experience means to them.
+     Define each actor ONCE here; use-cases (Standalone) / D-UC (Hybrid) reference
+     them by role and never re-describe who they are (anti-DRY). Actors characterize
+     the intended UX; keep it proportional — a role list, not persona research. -->
 ## Core Problem
 ## Goals
 ## Non-Goals
@@ -122,7 +127,11 @@ Only for features spanning multiple ANALYSIS documents or multiple milestones: o
 
 ## Problem
 ## Expected Benefit
-## Users or Stakeholders
+## Actors
+<!-- the cast this feature serves — usually a subset/refinement of the project
+     Actors, or a distinct feature-local cast for internal-tooling work. One light
+     line each: **Role** — primary goal; good UX = what good feels like.
+     Referenced by the use-cases, not re-described in them. -->
 ## Success Signals
 ## Non-Goals / Out of Scope
 ## Related Constraints and Principles
@@ -149,15 +158,18 @@ end_date:
 ## Feature Vision
 <!-- expected benefit and problem solved; alignment with the project vision
      (cite the document and its DRAFT/APPROVED state); non-goals/out-of-scope
-     for this feature; success signals; stakeholders only if not obvious.
+     for this feature; success signals; the Actors this feature serves (name them,
+     or point to the project Vision's ## Actors — do not re-describe them here).
      This is the single home of the feature vision: the separate file
      VISION_[feature].md is created only if the feature spans multiple
      ANALYSIS documents or multiple milestones. -->
 
 ## Use Cases / User Needs
 <!-- who needs this and why: the concrete use-cases / user-needs the change serves
-     (the Standalone home for what Hybrid keeps in D-UC). Derived from the elicitation
-     round; the Impact below must cover each, and the closure review checks coverage. -->
+     (the Standalone home for what Hybrid keeps in D-UC). Each use-case NAMES the
+     Actor it serves (defined in the Vision's ## Actors) — actor = who they are,
+     use-case = what they do. Derived from the elicitation round; the Impact below
+     must cover each, and the closure review checks coverage + actor UX fit. -->
 
 ## Impact
 <!-- existing files touched, APIs/contracts, performance, new dependencies -->