npm - @alexandrealvaro/agentic - Versions diffs - 0.14.0-beta.1 → 0.15.1-beta.1 - Mend

@alexandrealvaro/agentic 0.14.0-beta.1 → 0.15.1-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/README.md CHANGED Viewed

@@ -4,13 +4,13 @@ A starter kit for engineering production code with LLMs. Lean templates and init
 **The framing.** An LLM is the super-soldier serum; the engineer is Steve Rogers. The serum amplifies what the engineer already brings — solid bases, investigation, care for quality, architecture, clean code, observability, maintainability. The kit encodes those bases as skills, ADRs, and gates so the amplification compounds in the right direction. See [WORKFLOW.md](WORKFLOW.md) for the principles.
-The CLI installs nine universal skills (`agentic-bootstrap`, `agentic-philosophy`, `agentic-architecture`, `agentic-adr`, `agentic-spec`, `agentic-task`, `agentic-audit`, `agentic-review`, `agentic-ground`) plus three conditional ones (`agentic-design` for frontend, `agentic-subagent` for Claude Code, `agentic-skill` opt-in) into the agent's native location. Each skill produces its artifact or runs its operation via the agent's native conversational UI; `agentic update` keeps installed skills in sync with upstream kit changes via a state-aware three-way diff. Report rough edges via [GitHub Issues](https://github.com/alexandremendoncaalvaro/agentic-development/issues); current releases live under [GitHub Releases](https://github.com/alexandremendoncaalvaro/agentic-development/releases).
+The CLI installs nineteen universal skills at the default `team` profile (`ad-bootstrap`, `ad-philosophy`, `ad-architecture`, `ad-adr`, `ad-spec`, `ad-task`, `ad-audit`, `ad-review`, `ad-ground`, `ad-next`, `ad-spike`, `ad-tdg`, `ad-domain`, `ad-grill`, `ad-deepen`, `ad-diagnose`, `ad-commit`, `ad-pr`, `ad-merge`) plus four conditional ones (`ad-design` for frontend, `ad-subagent` for Claude Code, `ad-skill` opt-in, `ad-hooks` opt-in / recommended at `mature`) into the agent's native location. Lower profiles install fewer (`poc` = 9 universals, `solo` = 16, `team` / `mature` = 19; `ad-deepen` is excluded from `poc` / `solo` per [ADR-0020](doc/adr/0020-deep-modules-vocabulary.md) §4; `ad-commit` / `ad-pr` / `ad-merge` are excluded from `poc` per [ADR-0023](doc/adr/0023-agentic-commit-skill.md) / [ADR-0024](doc/adr/0024-agentic-pr-skill.md) / [ADR-0025](doc/adr/0025-agentic-merge-skill.md)). Each skill produces its artifact or runs its operation via the agent's native conversational UI; `agentic update` keeps installed skills in sync with upstream kit changes via a state-aware three-way diff. Report rough edges via [GitHub Issues](https://github.com/alexandremendoncaalvaro/agentic-development/issues); current releases live under [GitHub Releases](https://github.com/alexandremendoncaalvaro/agentic-development/releases).
 ## Prerequisites
 An agentic coding tool that reads markdown files. Examples here use **Claude Code** and **Codex CLI** (primary tools the author uses); the kit also works with [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), Cursor, Continue, Aider, and any other tool that follows the [agents.md](https://agents.md) open standard.
-For the CLI path: Node.js 18+. The CLI is the recommended path. Paste-into-agent prompts (see [Manual prompts](#manual-prompts) below) remain as an alternative for users who don't want to run an installer — same artifacts, same patterns.
+For the CLI path: Node.js 20+ (Node 18 is past EOL and `@clack/prompts` 1.x requires `node:util` `styleText`, which only ships in Node 20+). The CLI is the recommended path. Paste-into-agent prompts (see [Manual prompts](#manual-prompts) below) remain as an alternative for users who don't want to run an installer — same artifacts, same patterns.
 For the philosophy and full reasoning behind the kit, see [WORKFLOW.md](WORKFLOW.md).
@@ -30,37 +30,44 @@ Two categories ([ADR-0007](doc/adr/0007-workflow-operational-skills.md)) and two
 | Skill | Category | Installs | What it does | Invoke |
 | --- | --- | --- | --- | --- |
-| `agentic-bootstrap` | spec-driven | universal | Scans the repo, writes `AGENTS.md` ≤150 lines | `/agentic-bootstrap` |
-| `agentic-architecture` | spec-driven | universal | Scans the code, writes `ARCHITECTURE.md` | `/agentic-architecture` |
-| `agentic-adr` | spec-driven | universal | Drafts `doc/adr/NNNN-<slug>.md` from the conversation | `/agentic-adr` |
-| `agentic-spec` | spec-driven | universal | Drafts `doc/specs/NNNN-<slug>.md` — feature-level spec (User Scenarios, Requirements, Success Criteria) layer 3 of the five-layer stack | `/agentic-spec` |
-| `agentic-task` | spec-driven | universal | Drafts `doc/tasks/NNNN-<slug>.md` (checkbox + Notes format; carries `Spec ref` to link the implementing spec) | `/agentic-task` |
-| `agentic-audit` | spec-driven | universal | Read-only drift report (AGENTS.md / ARCHITECTURE.md / ADRs) | `/agentic-audit` |
-| `agentic-philosophy` | workflow-operational | universal | Universal agent guardrails — auto-loads on non-trivial work | implicit |
-| `agentic-review` | workflow-operational | universal | Fresh-context code review per WORKFLOW §10; structured findings, no "approve" | `/agentic-review <range>` |
-| `agentic-ground` | workflow-operational | universal | Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate per WORKFLOW §4 + §5 | `/agentic-ground` |
-| `agentic-next` | workflow-operational | universal | State-aware navigation aid (`flutter doctor` pattern) — surveys the five-layer artifact stack and recommends prioritized next actions; complements `agentic-audit` (drift) | `/agentic-next` |
-| `agentic-spike` | workflow-operational | universal | Staged spike with golden fixtures per WORKFLOW §14, for cases where the *technique* is uncertain across multiple plausible approaches; produces `spikes/NNNN-<slug>/` with discovery + fixture + pipeline-with-gates + two-layer evaluation | `/agentic-spike` |
-| `agentic-tdg` | workflow-operational | universal | Outcome-based prompting per WORKFLOW §9 — ground truth pair + Test Dependency Map + three approaches + single-criterion selection, for cases where the technique is known but the implementation strategy is uncertain | `/agentic-tdg` |
-| `agentic-design` | spec-driven | auto if frontend detected | Bootstrap `DESIGN.md` from existing tokens (Figma, tailwind.config, tokens.json, CSS custom props) | `/agentic-design` |
-| `agentic-subagent` | spec-driven | auto if installing for Claude Code | Drafts `.claude/agents/<name>.md` (Claude Code only — Codex has no subagent primitive) | `/agentic-subagent` |
-| `agentic-skill` | spec-driven | opt-in only | Drafts a new Claude Code or Codex skill at the appropriate path | `/agentic-skill` |
-| `agentic-hooks` | workflow-operational | opt-in only | Scaffolds deterministic quality gates per WORKFLOW §11 (pre-commit + pre-push); detects stack and recommends a runner (Husky / lefthook / pre-commit / native) | `/agentic-hooks` |
-A short TUI shows the detected mode, agent, and feature signals (frontend / `.claude/` / `.agents/` presence) and lets you toggle the conditional skills. Non-interactive flags: `--agent claude-code | codex | both`, `--yes` to skip confirmations — auto-checked conditionals (e.g., `agentic-design` if the project has React) install; `agentic-skill` stays opt-in. Re-running on an installed project is idempotent — unchanged files report `·`, divergent ones prompt to replace.
+| `ad-bootstrap` | spec-driven | universal | Scans the repo, writes `AGENTS.md` ≤150 lines | `/ad-bootstrap` |
+| `ad-architecture` | spec-driven | universal | Scans the code, writes `ARCHITECTURE.md` | `/ad-architecture` |
+| `ad-adr` | spec-driven | universal | Drafts `doc/adr/NNNN-<slug>.md` from the conversation | `/ad-adr` |
+| `ad-spec` | spec-driven | universal | Drafts `doc/specs/NNNN-<slug>.md` — feature-level spec (User Scenarios, Requirements, Success Criteria) layer 3 of the five-layer stack | `/ad-spec` |
+| `ad-task` | spec-driven | universal | Drafts `doc/tasks/NNNN-<slug>.md` (checkbox + Notes format; carries `Spec ref` to link the implementing spec) | `/ad-task` |
+| `ad-audit` | spec-driven | universal | Read-only drift report (AGENTS.md / ARCHITECTURE.md / ADRs) | `/ad-audit` |
+| `ad-philosophy` | workflow-operational | universal | Universal agent guardrails — auto-loads on non-trivial work | implicit |
+| `ad-review` | workflow-operational | universal | Fresh-context code review per WORKFLOW §10; structured findings, no "approve" | `/ad-review <range>` |
+| `ad-ground` | workflow-operational | universal | Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate per WORKFLOW §4 + §5 | `/ad-ground` |
+| `ad-next` | workflow-operational | universal | State-aware navigation aid (`flutter doctor` pattern) — surveys the five-layer artifact stack and recommends prioritized next actions; complements `ad-audit` (drift) | `/ad-next` |
+| `ad-spike` | workflow-operational | universal | Staged spike with golden fixtures per WORKFLOW §14, for cases where the *technique* is uncertain across multiple plausible approaches; produces `spikes/NNNN-<slug>/` with discovery + fixture + pipeline-with-gates + two-layer evaluation | `/ad-spike` |
+| `ad-tdg` | workflow-operational | universal | Outcome-based prompting per WORKFLOW §9 — ground truth pair + Test Dependency Map + three approaches + single-criterion selection, for cases where the technique is known but the implementation strategy is uncertain | `/ad-tdg` |
+| `ad-domain` | spec-driven | universal | Lazy lifecycle owner of `CONTEXT.md` (Layer 2 — ubiquitous language per Evans 2003); single-context or `CONTEXT-MAP.md` multi-context | `/ad-domain` |
+| `ad-grill` | workflow-operational | universal | Interview-before-research grilling — one question at a time with recommendation, codebase-first, sharpens vocabulary against `CONTEXT.md`, captures terms via `ad-domain` and decisions via `ad-adr` (three-criteria rule); upstream of `ad-ground` | `/ad-grill` |
+| `ad-deepen` | workflow-operational | universal in `team` + `mature` only | Surface deepening opportunities using WORKFLOW §8 vocabulary (Module / Interface / Depth / Seam / Adapter / Leverage / Locality); three phases — explore, present numbered candidates with deletion-test framing, grill the chosen one; pairs with `ad-audit` | `/ad-deepen` |
+| `ad-diagnose` | workflow-operational | universal | Disciplined diagnosis loop for hard bugs and performance regressions per WORKFLOW §15; five phases — build a feedback loop (the skill itself), reproduce, hypothesise (3-5 ranked falsifiable), instrument (one variable at a time), fix + regression-test | `/ad-diagnose` |
+| `ad-commit` | workflow-operational | universal in `solo` / `team` / `mature` | Atomic Conventional Commits with DCO `Signed-off-by` sign-off per ADR-0023; four phases — scope intake, stage-split when concerns mix, draft message, sign + write. Identity from `git config`. No `Co-Authored-By`. Helper, not blocker | `/ad-commit` |
+| `ad-pr` | workflow-operational | universal in `solo` / `team` / `mature` | Open a GitHub PR with a uniform body shape (Summary / Test plan / Links) per ADR-0024; four phases — preflight (`gh` auth + branch pushed), scope assembly, draft body, open + report URL. Title format = Conventional Commits | `/ad-pr` |
+| `ad-merge` | workflow-operational | universal in `solo` / `team` / `mature` | Evaluate (CI / fresh-context review / linked task / unresolved comments / mergeability) and merge a GitHub PR per ADR-0025; CI green = hard gate (yields to explicit user override); others = warnings. Merge mode auto-detected from `gh repo view`; `--delete-branch` by default | `/ad-merge` |
+| `ad-design` | spec-driven | auto if frontend detected | Bootstrap `DESIGN.md` from existing tokens (Figma, tailwind.config, tokens.json, CSS custom props) | `/ad-design` |
+| `ad-subagent` | spec-driven | auto if installing for Claude Code | Drafts `.claude/agents/<name>.md` (Claude Code only — Codex has no subagent primitive) | `/ad-subagent` |
+| `ad-skill` | spec-driven | opt-in only | Drafts a new Claude Code or Codex skill at the appropriate path | `/ad-skill` |
+| `ad-hooks` | workflow-operational | opt-in only | Scaffolds deterministic quality gates per WORKFLOW §11 (pre-commit + pre-push); detects stack and recommends a runner (Husky / lefthook / pre-commit / native) | `/ad-hooks` |
+A short TUI shows the detected mode, agent, and feature signals (frontend / `.claude/` / `.agents/` presence) and lets you toggle the conditional skills. Non-interactive flags: `--agent claude-code | codex | both`, `--yes` to skip confirmations — auto-checked conditionals (e.g., `ad-design` if the project has React) install; `ad-skill` stays opt-in. Re-running on an installed project is idempotent — unchanged files report `·`, divergent ones prompt to replace.
 If your project already has an `AGENTS.md` (or `CLAUDE.md`), the installer appends a managed `Skills installed by agentic` section bracketed by `<!-- agentic-managed-skills:start -->` / `:end -->` markers. User content outside those markers is byte-preserved; re-runs update only the managed block.
-### Planned skills
+### v0.15 bundle
-Skills accepted by ADR but not yet implemented; tracked under [task-0020](doc/tasks/0020-mattpocock-absorptions.md). Each ships in its own minor release.
+The four skills accepted by ADR-0019 / 0020 / 0021 / 0022 (the mattpocock-absorption Phase-2 set) shipped together in v0.15.0-beta.1. Closes [task-0020](doc/tasks/0020-mattpocock-absorptions.md) Phase 2 in a single release rather than the originally-planned per-minor stack (v0.15 → v0.18). Rationale: 3 of 4 skills are direct mirrors of mature mattpocock prior art; bundling kept the WORKFLOW §15 / §8 / Layer-2 deltas coherent in one ship.
-| Skill | Target | Operationalizes | ADR |
-| --- | --- | --- | --- |
-| `agentic-domain` | v0.15.x | Lazy-creates / updates `CONTEXT.md` (Layer 2 — ubiquitous language per Evans 2003) | [ADR-0019](doc/adr/0019-domain-language-layer.md) |
-| `agentic-grill` | v0.16.x | Interview-before-research session, upstream of `agentic-ground` | (forthcoming) |
-| `agentic-deepen` | v0.17.x | Surfaces deepening opportunities using the Ousterhout/Feathers vocabulary | [ADR-0020](doc/adr/0020-deep-modules-vocabulary.md) |
-| `agentic-diagnose` | v0.18.x | Five-phase debugging discipline per WORKFLOW §15 | [ADR-0021](doc/adr/0021-diagnose-discipline.md) |
+| Skill | ADR | Operationalizes |
+| --- | --- | --- |
+| `ad-domain` | [ADR-0019](doc/adr/0019-domain-language-layer.md) | Layer 2 (ubiquitous language) — lazy `CONTEXT.md` lifecycle |
+| `ad-grill` | [ADR-0022](doc/adr/0022-agentic-grill-skill.md) | Interview-before-research, upstream of `ad-ground` |
+| `ad-deepen` | [ADR-0020](doc/adr/0020-deep-modules-vocabulary.md) | WORKFLOW §8 vocabulary applied to refactor proposals (team + mature only) |
+| `ad-diagnose` | [ADR-0021](doc/adr/0021-diagnose-discipline.md) | WORKFLOW §15 five-phase debugging |
 ## Project maturity profiles
@@ -68,10 +75,10 @@ The kit ships four profiles that select which skills auto-install. Same WORKFLOW
 | Profile | Universal install set | Conditional posture | Recommended for |
 | --- | --- | --- | --- |
-| `poc` | philosophy, ground, audit | all blocked | spike, hackathon, exploration |
-| `solo` | + bootstrap, spec, task, review | architecture / adr / hooks opt-in; design auto if frontend; subagent auto for Claude Code | solo developer shipping a real product |
-| `team` (default) | + architecture, adr | hooks opt-in; design / subagent / skill follow autoIf | team product, shared discipline |
-| `mature` | same as team | hooks **recommended**; future evals + spike skills land here | regulated / public-facing production |
+| `poc` | 9 — philosophy, ground, audit, next, spike, tdg, domain, grill, diagnose | all blocked | spike, hackathon, exploration |
+| `solo` | 16 — + bootstrap, spec, task, review, commit, pr, merge | architecture / adr / hooks opt-in; design auto if frontend; subagent auto for Claude Code | solo developer shipping a real product |
+| `team` (default) | 19 — + architecture, adr, deepen | hooks opt-in; design / subagent / skill follow autoIf | team product, shared discipline |
+| `mature` | 19 — same as team | hooks **recommended**; deepening surfaced via `ad-deepen` | regulated / public-facing production |
 Select at init time:
@@ -125,7 +132,7 @@ Useful flags:
 If the project was installed with a kit version older than v0.3 (no state file present), the first `update` falls back to today's byte-compare behavior, then writes the state file so subsequent runs use the three-way diff.
-The `agentic-review` skill writes the assembled WORKFLOW §10 handoff to `.agentic/reviews/<ISO-timestamp>-<scope>.md` before delegating to the fresh-context reviewer (Claude Code) or before instructing you to `/clear` and paste (Codex). These files are ephemeral audit artifacts — add `.agentic/reviews/` to your `.gitignore`.
+The `ad-review` skill writes the assembled WORKFLOW §10 handoff to `.agentic/reviews/<ISO-timestamp>-<scope>.md` before delegating to the fresh-context reviewer (Claude Code) or before instructing you to `/clear` and paste (Codex). These files are ephemeral audit artifacts — add `.agentic/reviews/` to your `.gitignore`.
 For persistent install:
@@ -136,41 +143,48 @@ agentic init
 ## Recommended daily sequence
-The kit ships nine universal skills plus three conditional ones — twelve discrete capabilities. The sequence below is a happy path through them for the three flows that cover most daily work. Skip steps that don't apply; the kit never enforces order.
+The kit ships nineteen universal skills in the full `team` / `mature` install set; `ad-deepen` is excluded from `poc` and `solo` per [ADR-0020](doc/adr/0020-deep-modules-vocabulary.md) §4, and `ad-commit` / `ad-pr` / `ad-merge` are excluded from `poc` per [ADR-0023](doc/adr/0023-agentic-commit-skill.md) / [ADR-0024](doc/adr/0024-agentic-pr-skill.md) / [ADR-0025](doc/adr/0025-agentic-merge-skill.md) (concrete counts: `poc` = 9 universals, `solo` = 16, `team` / `mature` = 19). Plus four conditional skills (`ad-design`, `ad-subagent`, `ad-skill`, `ad-hooks`). The sequence below is a happy path through them for the three flows that cover most daily work. Skip steps that don't apply; the kit never enforces order.
 **Greenfield project, first non-trivial feature:**
 1. `agentic init` — install skills.
-2. `/agentic-bootstrap` — produce `AGENTS.md` (operational guide).
-3. `/agentic-architecture` — produce `ARCHITECTURE.md` once load-bearing patterns emerge.
-4. `/agentic-spec` — feature-level spec at `doc/specs/NNNN-<slug>.md` (User Scenarios, Requirements, Success Criteria).
-5. `/agentic-adr` — only when the feature forces a binding architectural decision worth recording for posterity.
-6. `/agentic-task` — work-unit decomposition; reference the spec via `Spec ref`.
-7. `/agentic-ground` — four-source research before code (`agentic-philosophy` auto-loads in parallel).
-8. Implement.
-9. `/agentic-review main..HEAD` — fresh-context §10 review before merge.
-10. `/agentic-audit` — periodic drift check across operational docs and specs.
+2. `/ad-bootstrap` — produce `AGENTS.md` (operational guide).
+3. `/ad-architecture` — produce `ARCHITECTURE.md` once load-bearing patterns emerge.
+4. `/ad-grill` — interview-before-research when the ask is fuzzy; resolves vocabulary into `CONTEXT.md` via `/ad-domain` as terms surface.
+5. `/ad-spec` — feature-level spec at `doc/specs/NNNN-<slug>.md` (User Scenarios, Requirements, Success Criteria).
+6. `/ad-adr` — only when the feature forces a binding architectural decision worth recording for posterity (three-criteria rule: hard to reverse, surprising without context, real trade-off).
+7. `/ad-task` — work-unit decomposition; reference the spec via `Spec ref`.
+8. `/ad-ground` — four-source research before code (`ad-philosophy` auto-loads in parallel).
+9. Implement.
+10. `/ad-review main..HEAD` — fresh-context §10 review before merge.
+11. `/ad-audit` — periodic drift check across operational docs, specs, and the `CONTEXT.md` glossary.
 **Brownfield project, quick fix:**
 1. `agentic update` (only if you want upstream kit changes).
-2. Fix. `agentic-philosophy` auto-loads if the change is non-trivial.
-3. `/agentic-review` only if the fix is non-trivial. Trivial diffs skip the review.
+2. Fix. `ad-philosophy` auto-loads if the change is non-trivial.
+3. `/ad-review` only if the fix is non-trivial. Trivial diffs skip the review.
 4. Commit.
 **Brownfield project, research-only ("what's the best way to add X?"):**
-1. `/agentic-ground` — runs the four-source research pass and surfaces the happy path with citations.
-2. Decide whether the answer becomes a spec (`/agentic-spec`) or a one-off task (`/agentic-task`).
+1. `/ad-ground` — runs the four-source research pass and surfaces the happy path with citations.
+2. Decide whether the answer becomes a spec (`/ad-spec`) or a one-off task (`/ad-task`).
 3. Continue from step 6 of the greenfield flow.
-The kit's discipline scales with the project's maturity. A solo PoC may legitimately skip `/agentic-spec` and `/agentic-adr` (the WORKFLOW §1 prune principle applies — don't add an artifact that wouldn't change agent behavior). A team product running on this kit is expected to use the full sequence and additionally invoke `/agentic-hooks` once to scaffold the deterministic gates per WORKFLOW §11 (pre-commit lint / format / secret-scan; pre-push build / unit / integration). Project maturity profiles that automate the recommendation by stack are deferred — see the next planned release.
+The kit's discipline scales with the project's maturity. A solo PoC may legitimately skip `/ad-spec` and `/ad-adr` (the WORKFLOW §1 prune principle applies — don't add an artifact that wouldn't change agent behavior). A team product running on this kit is expected to use the full sequence and additionally invoke `/ad-hooks` once to scaffold the deterministic gates per WORKFLOW §11 (pre-commit lint / format / secret-scan; pre-push build / unit / integration). Project maturity profiles that automate the recommendation by stack are deferred — see the next planned release.
+**Lost mid-flow?** Invoke `/ad-next` at any time to survey the project's state across the five-layer artifact stack (Constitution → Domain → Spec → Plan/Decisions → Code) and get prioritized next-action recommendations. Read-only; complements `/ad-audit` (drift detection — different question).
+**Technique uncertain across multiple plausible approaches?** Invoke `/ad-spike` (per WORKFLOW §14) when the spec is clear but the *how* is unknown — library choice, multi-stage transformation, novel domain. The skill scaffolds a staged spike with golden fixtures + per-stage debug artifacts + two-layer evaluation under `spikes/NNNN-<slug>/`. The directory is throwaway by design; conclude with `/ad-adr` and delete.
+**Technique known but implementation strategy uncertain?** Invoke `/ad-tdg` (per WORKFLOW §9) when multiple algorithms could produce the expected output with different trade-offs along readability / performance / testability. The skill forces a ground-truth pair, lists the tests covering the file (Test Dependency Map), generates three implementation candidates, and commits to one by a single named criterion — refusing the "optimize for all three at once" failure mode. No file written; the verified implementation is the artifact, with the candidate set + criterion landing in the commit message body.
-**Lost mid-flow?** Invoke `/agentic-next` at any time to survey the project's state across the five-layer artifact stack (Constitution → Domain → Spec → Plan/Decisions → Code) and get prioritized next-action recommendations. Read-only; complements `/agentic-audit` (drift detection — different question).
+**Question is fuzzy?** Invoke `/ad-grill` (per [ADR-0022](doc/adr/0022-agentic-grill-skill.md)) before research. One question at a time with a recommended answer; codebase-first when the answer is in code; sharpens vocabulary against `CONTEXT.md`. Routes to `/ad-ground` (research-ready), `/ad-tdg` (implement-ready), `/ad-spike` (technique-uncertain), or `/ad-diagnose` (it turned out to be a bug) when the question is sharp.
-**Technique uncertain across multiple plausible approaches?** Invoke `/agentic-spike` (per WORKFLOW §14) when the spec is clear but the *how* is unknown — library choice, multi-stage transformation, novel domain. The skill scaffolds a staged spike with golden fixtures + per-stage debug artifacts + two-layer evaluation under `spikes/NNNN-<slug>/`. The directory is throwaway by design; conclude with `/agentic-adr` and delete.
+**Bug or performance regression?** Invoke `/ad-diagnose` (per WORKFLOW §15). Five phases — build a feedback loop (the skill itself), reproduce, hypothesise (3-5 ranked falsifiable), instrument (one variable at a time), fix + regression-test. The loop is the skill; everything else is mechanical.
-**Technique known but implementation strategy uncertain?** Invoke `/agentic-tdg` (per WORKFLOW §9) when multiple algorithms could produce the expected output with different trade-offs along readability / performance / testability. The skill forces a ground-truth pair, lists the tests covering the file (Test Dependency Map), generates three implementation candidates, and commits to one by a single named criterion — refusing the "optimize for all three at once" failure mode. No file written; the verified implementation is the artifact, with the candidate set + criterion landing in the commit message body.
+**Stable codebase friction?** Invoke `/ad-deepen` (per WORKFLOW §8, [ADR-0020](doc/adr/0020-deep-modules-vocabulary.md)) on `team` / `mature` profiles. Surfaces deepening opportunities using the Module / Interface / Depth / Seam / Adapter / Leverage / Locality vocabulary and the deletion test. Premature on `poc` / `solo` — auto-install excludes them.
 ## Manual prompts
@@ -197,19 +211,19 @@ Prompts reference templates by relative path. Two ways to give your agent access
 ## Workflows by scenario
-**New project (greenfield).** Initialize git and project structure, then run `agentic init` to install the universal skill set plus any auto-detected conditional skills. From inside Claude Code or Codex: `/agentic-bootstrap` produces `AGENTS.md`, `/agentic-architecture` produces `ARCHITECTURE.md`, `/agentic-adr` records each binding decision, `/agentic-task` opens trackable work items, `/agentic-audit` flags drift, `/agentic-review <range>` runs a fresh-context review of a diff, `/agentic-design` bootstraps `DESIGN.md` from your tokens (frontend projects), `/agentic-subagent` and `/agentic-skill` scaffold custom subagents and skills. `agentic-philosophy` auto-loads on non-trivial work.
+**New project (greenfield).** Initialize git and project structure, then run `agentic init` to install the universal skill set plus any auto-detected conditional skills. From inside Claude Code or Codex: `/ad-bootstrap` produces `AGENTS.md`, `/ad-architecture` produces `ARCHITECTURE.md`, `/ad-adr` records each binding decision, `/ad-task` opens trackable work items, `/ad-audit` flags drift, `/ad-review <range>` runs a fresh-context review of a diff, `/ad-design` bootstraps `DESIGN.md` from your tokens (frontend projects), `/ad-subagent` and `/ad-skill` scaffold custom subagents and skills. `ad-philosophy` auto-loads on non-trivial work.
-**Existing project (brownfield).** Same flow. The project-wide skills (`/agentic-bootstrap`, `/agentic-architecture`) follow a **scan-first pattern**: the agent reads the codebase first, pre-fills every placeholder it can verify, then asks you only about the genuine gaps and conflicts — no philosophical questions, no interview-by-section. The per-artifact skills (`/agentic-adr`, `/agentic-task`, `/agentic-design`, `/agentic-skill`, `/agentic-subagent`) work on a single decision or asset and don't need codebase-wide verification. Backfill ADRs only for decisions that matter going forward.
+**Existing project (brownfield).** Same flow. The project-wide skills (`/ad-bootstrap`, `/ad-architecture`) follow a **scan-first pattern**: the agent reads the codebase first, pre-fills every placeholder it can verify, then asks you only about the genuine gaps and conflicts — no philosophical questions, no interview-by-section. The per-artifact skills (`/ad-adr`, `/ad-task`, `/ad-design`, `/ad-skill`, `/ad-subagent`) work on a single decision or asset and don't need codebase-wide verification. Backfill ADRs only for decisions that matter going forward.
-**Revisiting / auditing existing specs.** Run `/agentic-audit` from inside Claude Code or Codex. The skill reads `AGENTS.md`, `ARCHITECTURE.md`, and `doc/adr/` and produces a drift list — one finding per line, format `[file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.` Read-only — never rewrites specs. Apply judgment manually before changing anything.
+**Revisiting / auditing existing specs.** Run `/ad-audit` from inside Claude Code or Codex. The skill reads `AGENTS.md`, `ARCHITECTURE.md`, and `doc/adr/` and produces a drift list — one finding per line, format `[file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.` Read-only — never rewrites specs. Apply judgment manually before changing anything.
-**Reviewing your own diff.** Run `/agentic-review <range>` (e.g. `/agentic-review main..HEAD` or `/agentic-review PR#42`). The skill assembles the diff, the relevant spec slice (`AGENTS.md`, applicable ADRs, the task's Acceptance Criteria), and delegates to a fresh-context reviewer subagent — no inherited bias from the session that wrote the code (WORKFLOW §10). Returns structured findings grouped Blocker / Concern / Note. Codex variant uses `/clear` + paste handoff since Codex has no subagent primitive.
+**Reviewing your own diff.** Run `/ad-review <range>` (e.g. `/ad-review main..HEAD` or `/ad-review PR#42`). The skill assembles the diff, the relevant spec slice (`AGENTS.md`, applicable ADRs, the task's Acceptance Criteria), and delegates to a fresh-context reviewer subagent — no inherited bias from the session that wrote the code (WORKFLOW §10). Returns structured findings grouped Blocker / Concern / Note. Codex variant uses `/clear` + paste handoff since Codex has no subagent primitive.
-**Researching before implementation.** Run `/agentic-ground` (or let it auto-trigger on non-trivial work). The skill runs a four-source research pass — official docs, validated open-source examples, in-repo patterns, and git history — synthesizes a happy path with citations from each source, and gates any deviation behind an irrefutable justification before code is written (WORKFLOW §4 + §5). Output is the input to whatever produces the implementation plan; the skill does not write code.
+**Researching before implementation.** Run `/ad-ground` (or let it auto-trigger on non-trivial work). The skill runs a four-source research pass — official docs, validated open-source examples, in-repo patterns, and git history — synthesizes a happy path with citations from each source, and gates any deviation behind an irrefutable justification before code is written (WORKFLOW §4 + §5). Output is the input to whatever produces the implementation plan; the skill does not write code.
-**Specifying a feature.** Run `/agentic-spec` (or `/agentic-spec` with a feature name). The skill scaffolds `doc/specs/NNNN-<slug>.md` with industry-aligned mandatory sections (User Scenarios, Functional / Non-functional Requirements, Success Criteria, Edge Cases, Out of Scope, Open Questions, Related). Specs are layer 3 of the five-layer artifact stack — Constitution → Domain → Spec → Plan/Decisions → Code. One spec per feature; multiple tasks (`/agentic-task`) implement one spec; the task template carries a `Spec ref` field linking back to the spec.
+**Specifying a feature.** Run `/ad-spec` (or `/ad-spec` with a feature name). The skill scaffolds `doc/specs/NNNN-<slug>.md` with industry-aligned mandatory sections (User Scenarios, Functional / Non-functional Requirements, Success Criteria, Edge Cases, Out of Scope, Open Questions, Related). Specs are layer 3 of the five-layer artifact stack — Constitution → Domain → Spec → Plan/Decisions → Code. One spec per feature; multiple tasks (`/ad-task`) implement one spec; the task template carries a `Spec ref` field linking back to the spec.
-**Project already built with agents.** Treat missing artifacts as brownfield (run the relevant skill) and existing artifacts as audit (`/agentic-audit`).
+**Project already built with agents.** Treat missing artifacts as brownfield (run the relevant skill) and existing artifacts as audit (`/ad-audit`).
 ## What ends up in your target project
@@ -230,11 +244,11 @@ your-project/
 │   └── reviews/                (gitignored — ephemeral §10 review handoffs)
 ├── .claude/                    (Claude Code targets)
 │   ├── agentic-state.json      (kit install state — committed)
-│   ├── skills/agentic-*/SKILL.md
+│   ├── skills/ad-*/SKILL.md
 │   └── agents/fresh-context-reviewer.md
 └── .agents/                    (Codex targets, cc-sdd convention)
     ├── agentic-state.json      (kit install state — committed)
-    └── skills/agentic-*/{SKILL.md, agents/openai.yaml}
+    └── skills/ad-*/{SKILL.md, agents/openai.yaml}
 ```
 The pattern matches how [GitHub's spec-kit](https://github.com/github/spec-kit) and [cookiecutter](https://cookiecutter.readthedocs.io/) handle distribution — templates in one place, outputs in another, never mixed.

package/WORKFLOW.md CHANGED Viewed

@@ -72,7 +72,7 @@ Comments are exceptions. They justify *why* a non-obvious choice was made — ne
 ### Documentation Discipline
-The agent's authoritative copy of the eight-rule documentation discipline lives in the `agentic-philosophy` skill (`Documentation Discipline` section). The rules are summarized below for reference; the skill carries the full text agents read at session time. ADR-0008 records the canonical decision and the reconciliations against ADR-0004 (file-based task tracking) and ADR-0005 (universal agent behavior as a skill).
+The agent's authoritative copy of the eight-rule documentation discipline lives in the `ad-philosophy` skill (`Documentation Discipline` section). The rules are summarized below for reference; the skill carries the full text agents read at session time. ADR-0008 records the canonical decision and the reconciliations against ADR-0004 (file-based task tracking) and ADR-0005 (universal agent behavior as a skill).
 1. **Definitions and decisions only.** No speculation, history, or unfounded plans.
 2. **No dates, version stamps, `DRAFT` markers, or changelogs in narrative documents.** Decision-record artifacts under `doc/adr/`, `doc/tasks/`, `doc/specs/` are exempt — their lifecycle fields are the auditability primitive.
@@ -83,7 +83,7 @@ The agent's authoritative copy of the eight-rule documentation discipline lives
 7. **No commented-out code; no orphan `TODO` / `FIXME` in source.** Every deferred item references a GitHub Issue or a `doc/tasks/NNNN-*.md` task.
 8. **Tests are living documentation of behavior.**
-The skill body explains the rationale per rule, lists the failure modes the rules counter (bloated `AGENTS.md`, README pages drifting into changelogs, decision artifacts diluted by speculation), and walks through the reconciliations. Generator skills (`agentic-bootstrap`, `agentic-architecture`, `agentic-spec`, `agentic-task`, `agentic-adr`, `agentic-design`) reject violations of these rules at write time; `agentic-audit` flags drift across narrative docs and decision-record artifacts on demand.
+The skill body explains the rationale per rule, lists the failure modes the rules counter (bloated `AGENTS.md`, README pages drifting into changelogs, decision artifacts diluted by speculation), and walks through the reconciliations. Generator skills (`ad-bootstrap`, `ad-architecture`, `ad-spec`, `ad-task`, `ad-adr`, `ad-design`) reject violations of these rules at write time; `ad-audit` flags drift across narrative docs and decision-record artifacts on demand.
 ## 3. Format by Evidence
@@ -102,7 +102,7 @@ No format is universally best. **An observation from my practice, not benchmarke
 ## 4–5. Research Before Implementation
-Combines Find the Happy Path (canonical / idiomatic baseline) and Ground in Real Patterns (anchoring in project-specific examples). The kit treats both as one indivisible flow via `agentic-ground`; two prose sections would frame one operation as two separate practices.
+Combines Find the Happy Path (canonical / idiomatic baseline) and Ground in Real Patterns (anchoring in project-specific examples). The kit treats both as one indivisible flow via `ad-ground`; two prose sections would frame one operation as two separate practices.
 Two sub-practices, joined into one indivisible pass.
@@ -110,7 +110,7 @@ Two sub-practices, joined into one indivisible pass.
 **Ground in real patterns.** Don't dump the codebase into context. Anchor the model in a specific, project-relevant example: *"Find an existing example of [similar feature]; use that exact structure."* Cite specific files, not "the codebase." Use just-in-time retrieval — pass paths or IDs and let the agent fetch via tools.
-The kit ships `agentic-ground` as the workflow-operational implementation of both. It runs a four-source research pass — official docs, validated open-source examples, in-repo patterns, git history — joined by AND not OR, synthesizes the happy path with citations from each source, and gates any deviation behind an irrefutable justification before code is written. Splitting the two sub-practices into separate skills would force two invocations with overlapping research outputs and fragment the synthesis context (ADR-0010).
+The kit ships `ad-ground` as the workflow-operational implementation of both. It runs a four-source research pass — official docs, validated open-source examples, in-repo patterns, git history — joined by AND not OR, synthesizes the happy path with citations from each source, and gates any deviation behind an irrefutable justification before code is written. Splitting the two sub-practices into separate skills would force two invocations with overlapping research outputs and fragment the synthesis context (ADR-0010).
 ## 6. Explore → Plan → Implement → Commit
@@ -159,7 +159,7 @@ Three principles fall out of those terms:
 - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
 - **One adapter is a hypothetical seam; two adapters make it real.** Don't introduce a seam unless something actually varies across it.
-Skills that touch architecture (`agentic-architecture`, `agentic-adr`, the planned `agentic-deepen`) use these terms verbatim, so suggestions and reviews land in a single language.
+Skills that touch architecture (`ad-architecture`, `ad-adr`, the planned `ad-deepen`) use these terms verbatim, so suggestions and reviews land in a single language.
 ## 9. Outcome-Based Prompting (TDG)
@@ -230,7 +230,7 @@ This is a combination of established practices, not new terminology: spike (XP),
 ## 15. Diagnose With Discipline
-For hard bugs and performance regressions, the failure mode is jumping to hypotheses before there is a way to check them. The discipline below is the counter; it owes its shape to standard debugging practice (Kernighan & Pike, *The Practice of Programming*, 1999) and the kit ships `agentic-diagnose` as the operational implementation (ADR-0021).
+For hard bugs and performance regressions, the failure mode is jumping to hypotheses before there is a way to check them. The discipline below is the counter; it owes its shape to standard debugging practice (Kernighan & Pike, *The Practice of Programming*, 1999) and the kit ships `ad-diagnose` as the operational implementation (ADR-0021).
 ### Phase 1 — Build a feedback loop

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.14.0-beta.1",
+  "version": "0.15.1-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "start": "node bin/agentic.js",

package/src/commands/init.js CHANGED Viewed

@@ -67,28 +67,28 @@ export const REQUIRED_SKILLS = requiredSkillsForProfile('team');
  */
 export const CONDITIONAL_SKILLS = [
   {
-    name: 'agentic-design',
+    name: 'ad-design',
     autoIf: (f) => f.frontend,
     agents: ['claude-code', 'codex'],
     hintWhenAuto: 'detected: frontend',
     hintWhenManual: 'frontend / DESIGN.md',
   },
   {
-    name: 'agentic-subagent',
+    name: 'ad-subagent',
     autoIf: () => true,
     agents: ['claude-code'],
     hintWhenAuto: 'Claude Code only',
     hintWhenManual: 'Claude Code only',
   },
   {
-    name: 'agentic-skill',
+    name: 'ad-skill',
     autoIf: () => false,
     agents: ['claude-code', 'codex'],
     hintWhenAuto: 'opt-in',
     hintWhenManual: 'opt-in (rarely needed)',
   },
   {
-    name: 'agentic-hooks',
+    name: 'ad-hooks',
     autoIf: () => false,
     agents: ['claude-code', 'codex'],
     hintWhenAuto: 'opt-in',
@@ -103,14 +103,14 @@ export const CONDITIONAL_SKILLS = [
   // The autoIf rule here is the universal-default; per-profile overrides
   // come from `availableConditionalsForProfile`'s rule field.
   {
-    name: 'agentic-architecture',
+    name: 'ad-architecture',
     autoIf: () => true,
     agents: ['claude-code', 'codex'],
     hintWhenAuto: 'system patterns + boundaries',
     hintWhenManual: 'opt-in (recommended once load-bearing patterns emerge)',
   },
   {
-    name: 'agentic-adr',
+    name: 'ad-adr',
     autoIf: () => true,
     agents: ['claude-code', 'codex'],
     hintWhenAuto: 'binding architectural decisions (Nygard pattern)',
@@ -325,7 +325,7 @@ export async function initCommand(opts) {
     saveState(cwd, agent, nextStates[agent]);
   }
-  // Dedup: agentic-architecture and agentic-adr are universal at team /
+  // Dedup: ad-architecture and ad-adr are universal at team /
   // mature (in REQUIRED_SKILLS) AND conditional at solo (in
   // CONDITIONAL_SKILLS) per review B1 (v0.11.3). Without the Set, the
   // managed-skills section would list those rows twice.
@@ -361,38 +361,49 @@ export async function initCommand(opts) {
   if (interactive) {
     p.note(lines.join('\n'), 'Result');
     const slashLine = [
-      '/agentic-bootstrap (AGENTS.md)',
-      '/agentic-architecture (ARCHITECTURE.md)',
-      '/agentic-adr',
-      '/agentic-spec (doc/specs/)',
-      '/agentic-task',
-      '/agentic-audit',
-      '/agentic-review (WORKFLOW §10)',
-      '/agentic-ground (WORKFLOW §4 + §5)',
-      '/agentic-next (state survey + recommendations)',
-      '/agentic-spike (WORKFLOW §14 — staged spike with golden fixtures)',
-      '/agentic-tdg (WORKFLOW §9 — outcome-based prompting + TDM)',
-      ...(optedSkills.includes('agentic-design') ? ['/agentic-design (DESIGN.md)'] : []),
-      ...(optedSkills.includes('agentic-subagent') && agents.includes('claude-code')
-        ? ['/agentic-subagent']
+      '/ad-bootstrap (AGENTS.md)',
+      '/ad-architecture (ARCHITECTURE.md)',
+      '/ad-adr',
+      '/ad-spec (doc/specs/)',
+      '/ad-task',
+      '/ad-audit',
+      '/ad-review (WORKFLOW §10)',
+      '/ad-ground (WORKFLOW §4 + §5)',
+      '/ad-next (state survey + recommendations)',
+      '/ad-spike (WORKFLOW §14 — staged spike with golden fixtures)',
+      '/ad-tdg (WORKFLOW §9 — outcome-based prompting + TDM)',
+      '/ad-domain (CONTEXT.md — Layer 2 ubiquitous language)',
+      '/ad-grill (interview-before-research)',
+      '/ad-deepen (WORKFLOW §8 — deepening opportunities)',
+      '/ad-diagnose (WORKFLOW §15 — five-phase diagnosis)',
+      '/ad-commit (Conventional Commits + DCO sign-off)',
+      '/ad-pr (open PR with uniform body)',
+      '/ad-merge (evaluate + merge PR)',
+      ...(optedSkills.includes('ad-design') ? ['/ad-design (DESIGN.md)'] : []),
+      ...(optedSkills.includes('ad-subagent') && agents.includes('claude-code')
+        ? ['/ad-subagent']
         : []),
-      ...(optedSkills.includes('agentic-skill') ? ['/agentic-skill'] : []),
-      ...(optedSkills.includes('agentic-hooks') ? ['/agentic-hooks (WORKFLOW §11)'] : []),
+      ...(optedSkills.includes('ad-skill') ? ['/ad-skill'] : []),
+      ...(optedSkills.includes('ad-hooks') ? ['/ad-hooks (WORKFLOW §11)'] : []),
     ]
       .filter((line) => {
         // Filter the universal-set entries to only those actually installed
         // for this profile.
         const universalNames = requiredSkillsForProfile(profileName);
         const universalLabels = {
-          'agentic-bootstrap': '/agentic-bootstrap (AGENTS.md)',
-          'agentic-architecture': '/agentic-architecture (ARCHITECTURE.md)',
-          'agentic-adr': '/agentic-adr',
-          'agentic-spec': '/agentic-spec (doc/specs/)',
-          'agentic-task': '/agentic-task',
-          'agentic-audit': '/agentic-audit',
-          'agentic-review': '/agentic-review (WORKFLOW §10)',
-          'agentic-ground': '/agentic-ground (WORKFLOW §4 + §5)',
-          // 'agentic-philosophy' is implicit and not listed.
+          'ad-bootstrap': '/ad-bootstrap (AGENTS.md)',
+          'ad-architecture': '/ad-architecture (ARCHITECTURE.md)',
+          'ad-adr': '/ad-adr',
+          'ad-spec': '/ad-spec (doc/specs/)',
+          'ad-task': '/ad-task',
+          'ad-audit': '/ad-audit',
+          'ad-review': '/ad-review (WORKFLOW §10)',
+          'ad-ground': '/ad-ground (WORKFLOW §4 + §5)',
+          'ad-deepen': '/ad-deepen (WORKFLOW §8 — deepening opportunities)',
+          'ad-commit': '/ad-commit (Conventional Commits + DCO sign-off)',
+          'ad-pr': '/ad-pr (open PR with uniform body)',
+          'ad-merge': '/ad-merge (evaluate + merge PR)',
+          // 'ad-philosophy' is implicit and not listed.
         };
         for (const [skill, label] of Object.entries(universalLabels)) {
           if (line === label) return universalNames.includes(skill);
@@ -403,7 +414,7 @@ export async function initCommand(opts) {
     p.outro(
       `Done (profile: ${profileName}). In ${agents
         .map((a) => AGENT_LABEL[a])
-        .join(' or ')}: ${slashLine}. agentic-philosophy auto-loads on non-trivial work.`
+        .join(' or ')}: ${slashLine}. ad-philosophy auto-loads on non-trivial work.`
     );
   } else {
     for (const line of lines) {

package/src/commands/update.js CHANGED Viewed

@@ -297,7 +297,7 @@ export async function updateCommand(opts) {
     }
   }
-  // Dedup: agentic-architecture and agentic-adr are universal at team /
+  // Dedup: ad-architecture and ad-adr are universal at team /
   // mature (in REQUIRED_SKILLS) AND conditional at solo (in
   // CONDITIONAL_SKILLS) per review B1 (v0.11.3). Without the Set, the
   // managed-skills section would list those rows twice.