feat: point to the release-please process from README's Learn more

[aagnone3]

Summary

Small, real README addition (root README's "Learn more" section now points to the release process), used as an intentional end-to-end smoke test of the release-please pipeline adopted in #156/#158.

Everything so far only exercised the "nothing to release" path. This feat:-titled PR should cause release-please's standing release PR to propose a genuine MINOR bump for agentic-engineering (plugin.json + its .claude-plugin/marketplace.json, .cursor-plugin/plugin.json, .codex-plugin/plugin.json mirrors) — merging that generated release PR afterward is what actually validates the full tag + GitHub Release cut, not just config correctness.

Test plan

• bun test — 487 pass.
• bun run docs:check — up to date.
• After merge: confirm release-pr.yml opens a release PR proposing 4.0.0 → 4.1.0 for agentic-engineering, touching all 4 tracked files correctly — then merge it and confirm the tag/GitHub Release land.

🤖 Generated with Claude Code

[github-actions]

📚 Documentation-health audit (propose-only)

Ran the documentation-health skill's judgment pass over the repo (merge-preview checkout). Findings are grouped by severity with file:line + concrete fix. Nothing here is applied — this review is the confirmation step.

Environment caveat (transparency): In this CI run the deterministic Python scanner could not be executed — every Bash call was aborted by a misconfigured PreToolUse hook (python3 ${PLUGIN_ROOT}/scripts/*.py, with PLUGIN_ROOT unset → /scripts/...), and Glob/Grep/find and the GitHub read APIs were unavailable. The repo's own plugin.json hooks correctly use ${CLAUDE_PLUGIN_ROOT}, so this is a CI harness/wiring issue, not a repo defect — but it does mean the scanner's Tier-1 gate is currently non-functional in this environment and should be fixed so the gate actually runs. I reproduced the deterministic checks by reading files directly. Not verified: lychee link-checking beyond manual spot-checks, doctoc/markdownlint, and repo-wide leak/secret grep.

---

WARN — fix soon

1. CLAUDE.md ↔ AGENTS.md are forked and unbridged
AGENTS.md:3 declares itself the "lean, tool-agnostic companion" to CLAUDE.md, but the two are fully independent files: root CLAUDE.md contains no @AGENTS.md import and is not a symlink to it. Claude Code does not read AGENTS.md natively, so several rules that live only in AGENTS.md are invisible to the primary tool:

• the "Adding a New Target Provider" checklist (AGENTS.md:13-48)
• ASCII-first rule (AGENTS.md:11)
• OpenCode output-path invariants (AGENTS.md:10)
• the docs/plans/ convention (AGENTS.md:52)

No contradiction between the files (the non-contradiction contract holds), but content is stranded from each file's audience. Fix: bridge them — add @AGENTS.md to CLAUDE.md (or symlink) and canonicalize shared rules in AGENTS.md; or, keeping CLAUDE.md canonical, fold AGENTS.md's unique rules into it so Claude Code actually sees them.

2. docs/upstream-sources.md:2 — report_repo points at a pre-fork personal repo
report_repo: aagnone3/agentic-engineering. Per docs/upstream-sources.md:9-12, /upstream-scan files its result issues (label upstream-scan) onto report_repo. The canonical repo is Life-With-Data/agentic-engineering (plugin.json:10 repository, all README badges/install URLs), and README.md:12 calls this "an independent project ... built as our own." As written, scheduled scans would create issues on a third-party/author-fork repo rather than here. Fix: set report_repo: Life-With-Data/agentic-engineering (or confirm the cross-repo target is intentional and document why).

3. LICENSE:3 — copyright holder mismatch
Copyright (c) 2025 Every — but the author is Anthony Agnone (plugin.json:5-8) and the project ships under the Life-With-Data org. "Every" matches neither. The MIT copyright line is legally load-bearing. Fix: set the holder to the actual rights holder (the author or the org).

---

INFO — advisory

4. Root README.md has no License section
LICENSE (MIT) exists and the nested plugins/agentic-engineering/README.md:350-352 has a License section, but the root README does not. Fix: add a one-line ## License — MIT for the newcomer.

5. Provenance metadata is inconsistent across files
package.json:2 (@aagnone3/agentic-plugin), LICENSE:3 (Every), docs/upstream-sources.md:2 (aagnone3/...) vs. plugin.json / README (Life-With-Data + author aagnone3). Reconcile so provenance reads consistently (ties into #2/#3).

---

Scanner signals I checked and am not flagging (false positives / healthy)

• "No Usage/Quickstart section" (root README): heading-name miss only — Install + "The loop" + command tables give the fastest path to value.
• Hardcoded counts "31 agents / 62 skills" in both READMEs: this is the good SSOT pattern — tests/plugin-consistency.test.ts enforces them against the filesystem (CLAUDE.md:27,35). Not drift.
• "15 agents" in CLAUDE.md:119: a dated Key-Learnings anecdote, not a live count.
• Community-health files: all present — README, LICENSE, and CONTRIBUTING/CODE_OF_CONDUCT/SECURITY/SUPPORT under .github/.
• Root CLAUDE.md: 121 lines (well under the ~200 ceiling), no broken @imports, explicit SSOT handling of counts/versions — healthy.
• Internal links resolve: FLOWS.md, docs/multi-platform-native-plugins.md, scripts/HOOKS.md, docs/dependency-policy.md, docs/upstream-sources.md, docs/solutions/*, skills/lifecycle/*, operating-principles snippet, gh-recipes.md — all present.
• Commands are current: bun test, bun run docs:build, bun run docs:check, bun run typecheck all exist in package.json scripts.

---

Propose-only — no files edited, committed, or pushed.

[github-actions]

📚 Documentation Health Audit (propose-only)

Repository-wide documentation-health pass across the six layers (root & nested CLAUDE.md, cross-tool agent context, root & nested READMEs, community-health, docs/). No files changed.

⚠️ Run note — deterministic scanner could not execute. Every Bash/Write/Edit call in this CI run was rejected by the plugin's own PreToolUse hooks (hooks/hooks.json), which invoke python3 ${PLUGIN_ROOT}/scripts/block-*.py. In this runner ${PLUGIN_ROOT} expanded to empty, resolving to a nonexistent /scripts/..., so the hooks fail closed and block all shell/edit tools; Grep/Glob were also unavailable. Findings below come from the judgment pass over files read directly. Treat "clean" categories (placeholder rot, secrets) as clean in inspected files, not verified repo-wide. (The hook failure is an environment/runner issue, not a repo documentation defect.)

🔴 ERROR — fix now

1. Nested plugins/agentic-engineering/CLAUDE.md contradicts the authoritative root CLAUDE.md on versioning/changelog — it will steer an agent into forbidden actions.

• Root CLAUDE.md:39 — "Do not hand-bump the version. release-please computes the bump…"
• Root CLAUDE.md:41 — "Don't hand-write CHANGELOG.md entries. release-please generates them…"
• Nested plugins/agentic-engineering/CLAUDE.md:5-9 — "Every change to this plugin MUST include… Bump version using semver… CHANGELOG.md — Document changes"
• Nested plugins/agentic-engineering/CLAUDE.md:11-15 — manual "Version Bumping Rules" (MAJOR/MINOR/PATCH by hand)
• Nested plugins/agentic-engineering/CLAUDE.md:21-22 — pre-commit checklist "[ ] Version bumped in .claude-plugin/plugin.json" / "[ ] CHANGELOG.md updated with changes"

This nested file still documents the pre-release-please manual process. An agent scoped to plugins/agentic-engineering/ loads it and will hand-bump plugin.json and hand-edit CHANGELOG — exactly what the root file and docs/solutions/adopt-release-please.md forbid, and what release-please owns (its generated CHANGELOG region gets overwritten; a manual bump collides with the standing release PR). It also violates the repo's own invariant at AGENTS.md:3 ("must not contradict [CLAUDE.md]").
Fix: Rewrite the Versioning Requirements / Version Bumping Rules / Pre-Commit Checklist sections to defer to release-please — delete the manual bump + changelog steps and replace with a one-line pointer to root CLAUDE.md §"Updating the plugin"/§"Release process" and docs/solutions/plugin-versioning-requirements.md. Keep the genuinely plugin-scoped content (Skill Naming Convention, Skill Compliance Checklist).

🟡 WARN — fix soon

2. LICENSE:3 — stale copyright holder. Copyright (c) 2025 Every. The project de-branded to Life-With-Data (every .github/ community-health file uses lifewithdata.org); the LICENSE is the only doc still attributing to "Every".
Fix: Update the holder (e.g. Copyright (c) 2025-2026 Life With Data — confirm the correct legal entity/year).

3. docs/upstream-sources.md:2 — report_repo: aagnone3/agentic-engineering points at a non-canonical personal fork. The changelog (3.21.3) repointed README/docs/manifests from aagnone3 to the canonical Life-With-Data. If this is live config, /upstream-scan will file its report issues on the wrong repo.
Fix: Confirm intent; unless it's a deliberate fixture, set report_repo: Life-With-Data/agentic-engineering.

4. Root AGENTS.md is unbridged from CLAUDE.md. Both exist at root; neither imports the other (AGENTS.md:3 cross-links in prose only). Claude Code does not read AGENTS.md natively, so its content (CLI/provider-adding guidance) never loads for Claude. The content is complementary, not a forked duplicate — so this is drift-prone, not broken.
Fix: Add a one-line @AGENTS.md import to root CLAUDE.md (or a symlink) so the tool-agnostic guidance loads natively. Worth doing since this repo dogfoods the documentation-health skill.

🔵 INFO / hygiene

5. Hardcoded component counts — scanner would WARN, but this is a false positive (no action needed). README.md:8, README.md:149-151, plugins/agentic-engineering/README.md:9-11, and per-category counts at plugins/agentic-engineering/README.md:19,41,51,59,69 are hand-written, but tests/plugin-consistency.test.ts (bun test, CI-gated) enforces they match the filesystem. The value is guarded by a test → not a genuine drift risk. (Optional ideal: generate them between <!-- GENERATED --> markers, as the docs site already does.)

6. Minor onboarding duplication. The local-install snippet at README.md:52-55 is repeated at CLAUDE.md:83-85 ("Try the plugin locally"). Low risk; could keep human onboarding in the README and reference it from CLAUDE.md.

7. CODEOWNERS absent. Advisory only.

✅ Healthy (for the record)

Root CLAUDE.md (121 lines, under the ~200 ceiling) is exemplary SSOT discipline — it refuses to hardcode counts (CLAUDE.md:27) and names tests/plugin-consistency.test.ts as the source of truth (CLAUDE.md:35). README sizes are within thresholds (root 165, plugin 353). Community-health coverage is complete (CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / SUPPORT in .github/, root MIT LICENSE). No secrets or broken @imports in inspected files.

---

Propose-only: no files were edited, committed, or pushed. Priority fix = #1 (the nested-CLAUDE.md versioning contradiction).

[github-actions]

📚 Documentation Health Audit (propose-only)

Coverage caveat — read this first. The deterministic scanner could not run in this CI environment: every Bash call is rejected by the plugin's own Bash PreToolUse hooks, which resolve ${PLUGIN_ROOT} to empty and try to exec python3 /scripts/block-*.py (missing → exit 2 → blocked). Glob/Grep aren't exposed and the GitHub read tools were permission-denied, so no repo-wide **/*.md enumeration or link-crawl was possible. This audit is therefore a judgment pass over the primary documentation surfaces read directly (root + nested CLAUDE.md, AGENTS.md, root + plugin README.md, HOOKS.md, docs/*, LICENSE, the three manifests, tests/plugin-consistency.test.ts). Treat coverage as partial; the deterministic gate should be re-run once Bash works.

Bottom line: no ERROR-class documentation breakage in the surfaces audited. Every internal link checked resolves, LICENSE is present, community-health files are complete (.github/CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|SUPPORT.md), no secrets appeared in docs read, and root CLAUDE.md is lean (121 lines) and exemplary on single-source-of-truth — it deliberately refuses to hardcode counts (CLAUDE.md:27) and defers to the enforcing test. Findings below are all WARN/INFO.

---

Layer: Root README — WARN

1. Missing a ## License section. README.md (ends at line 165) has Install/Configure/Usage but no License heading, and never references the LICENSE file (MIT, present at repo root). Standard-Readme expects it.

• Fix: add, in Standard-Readme order, ## License → Released under the [MIT License](LICENSE).

Layer: Internal docs — WARN

2. docs/upstream-sources.md:2 — report_repo: aagnone3/agentic-engineering targets a non-canonical owner. The canonical repo is Life-With-Data/agentic-engineering (README badges/install commands + plugin.json:10 "repository"). /upstream-scan files its result issues onto report_repo, so scan output would land on aagnone3/…. CLAUDE.md:118 documents a fork-disconnect force-push off that exact lineage, which makes stale drift plausible.

• Fix: confirm intent. If scan issues should land on the canonical repo, change to report_repo: Life-With-Data/agentic-engineering. (If aagnone3/agentic-engineering is deliberately the scan sink, leave it.)

Layer: Cross-tool agent context (AGENTS.md ↔ CLAUDE.md) — WARN (downgraded)

3. AGENTS.md (53 lines) is not bridged into CLAUDE.md. There is no @AGENTS.md import or symlink, and Claude Code doesn't read AGENTS.md natively — so a Claude agent never sees AGENTS.md-only content such as the "Adding a New Target Provider" checklist (AGENTS.md:13-48). I am downgrading this from the usual "unbridged twin" WARN: the two files are not duplicates and do not contradict — AGENTS.md:3 explicitly defers to CLAUDE.md ("must not contradict it") and they cover distinct scopes (CLAUDE.md = marketplace/versioning/release; AGENTS.md = CLI/converter working agreement). So the drift risk is low; this is a deliberate-decision check, not a defect.

• Fix (choose one): if that CLI/provider guidance should also reach Claude, add @AGENTS.md to CLAUDE.md; if AGENTS.md is intentionally for non-Claude tools only, no action needed.

INFO / advisory

4. LICENSE:3 copyright holder is "Every" while the project org is Life-With-Data and the plugin author is Anthony Agnone (plugin.json:5-7). Confirm the attribution is intended.

5. README.md:87 pinned-release example npx github:Life-With-Data/agentic-engineering#v3.0.0. Release tags follow the <package>-v<version> scheme (CLAUDE.md:107) and the plugin is currently v4.0.0, so a bare v3.0.0 git tag may not resolve. Verify the tag exists; update the example to a real tag/ref. (Low confidence — could not check tags in this environment.)

6. No root CODEOWNERS and no docs/adr/ (the repo uses docs/solutions/ as its decision log, which is fine). Advisory only.

---

Scanner false-positives I explicitly dismissed (NOT findings)

• Hardcoded counts "31 agents / 62 skills / 1 MCP server" appear in README.md:8,149-151, the plugin README.md:9-11, and all three manifests. A naive scan flags every hardcoded count as a drift landmine — here it is noise. These are enforced against the filesystem by tests/plugin-consistency.test.ts (bun test in CI, per CLAUDE.md:35,40), the counts are internally consistent across all five surfaces, and CLAUDE.md itself models the SSOT ideal by omitting them. Acceptable, well-guarded pattern.

Out-of-scope operational note (not a docs finding)

The scanner-blocking behavior above is not a documentation defect — HOOKS.md:29 correctly documents that hooks/hooks.json uses ${PLUGIN_ROOT} for Codex (which sets that var), while Claude Code's wiring is the inline hooks in plugin.json using ${CLAUDE_PLUGIN_ROOT} (plugin.json:39+). This run's breakage looks like the CI harness loading the Codex hooks/hooks.json with PLUGIN_ROOT unset. Worth a maintainer glance only because that file's name matches Claude Code's hook auto-discovery convention (unlike the Cursor file, which is named hooks-cursor.json) — confirm Claude Code doesn't auto-load it and clobber Bash on real installs.

---

Propose-only: no files were edited, committed, or pushed. This is the single review for this run.