aiops: release agents - Consolidate release and changelog agent guidance

.claude/agents/changelog-agent.md

@@ -5,8 +5,8 @@ description: "Portable changelog management agent with Keep a Changelog 1.1.0 su
 
 # changelog-agent (generated thin definition)
 
-This file is generated from `agents/changelog-agent/changelog.agent.md` — do not edit it by hand.
+This file is generated from `agents/changelog-agent/AGENT.md` — do not edit it by hand.
 Regenerate with `node scripts/agents/generate-agent-defs.cjs`.
 
 Read the canonical specification in full before acting. Start with
-`agents/changelog-agent/changelog.agent.md` (specification and integration guide).
+`agents/changelog-agent/AGENT.md` (specification and integration guide).

.github/agentic-workflows/release.agent.js

@@ -10,7 +10,7 @@
  * Version: 1.0 MVP (Phase 5A)
  *
  * Related Files & Integration:
- * - Changelog Spec Agent: agents/changelog-agent/changelog.agent.md
+ * - Changelog Spec Agent: agents/changelog-agent/AGENT.md
  * - Changelog Portable Agent: agents/changelog-agent/README.md
  * - Changelog Portable Agent: agents/changelog-agent/changelog.agent.js
  * - Changelog Schema: schemas/changelog.schema.json
@@ -128,7 +128,7 @@
         encoding: "utf-8",
       }).trim();
       return branch === "develop";
     } catch (_e) {
       return false;
     }
   }
@@ -139,7 +139,7 @@
         encoding: "utf-8",
       }).trim();
       return status.length > 0;
     } catch (_e) {
       return true;
     }
   }
@@ -314,7 +314,7 @@
       }
 
       // Check 3: Verify valid version sections (pattern: [X.Y.Z] - YYYY-MM-DD)
       const versionPattern = CHANGELOG_VALIDATION.requiresVersionFormat;
 
       // Check 4: Verify [Unreleased] has entries (is not empty)
       const unreleasedRegex = /## \[Unreleased\]\n\n([\s\S]*?)\n## \[/;
@@ -587,7 +587,7 @@
       }).trim();
       const match = remote.match(/github\.com[:/](.+?)(?:\.git)?$/);
       return match ? match[1] : "unknown/unknown";
     } catch (_e) {
       return "unknown/unknown";
     }
   }

.github/agentic-workflows/release.md

@@ -480,7 +480,7 @@ gh agentic release --scope=patch
 
 This release agent integrates with the LightSpeed changelog ecosystem:
 
-- **Changelog Spec Agent:** [`agents/changelog-agent/changelog.agent.md`](../../agents/changelog-agent/changelog.agent.md) — Primary agent specification for changelog management
+- **Changelog Spec Agent:** [`agents/changelog-agent/AGENT.md`](../../agents/changelog-agent/AGENT.md) — Primary agent specification for changelog management
 - **Changelog Portable Agent:** [`agents/changelog-agent/README.md`](../../agents/changelog-agent/README.md) — Multi-file implementation with Keep a Changelog 1.1.0 support
 - **Changelog Schema:** [`schemas/changelog.schema.json`](../../schemas/changelog.schema.json) — JSON schema validation for Keep a Changelog 1.1.0 compliance
 - **Changelog Workflow:** [`.github/workflows/changelog-management.yml`](../../.github/workflows/changelog-management.yml) — GitHub Actions workflow for automated changelog processing

.github/scripts/__tests__/generate-agent-index.test.js

@@ -316,7 +316,7 @@ const { buildImplementationLink } = await import(
 );
 const movedSpec = {
   name: "Changelog Agent",
-  path: "agents/changelog-agent/changelog.agent.md",
+  path: "agents/changelog-agent/AGENT.md",
   implementation: "agents/changelog-agent/",
 };
 assertEqual(

.github/scripts/generate-agent-index.js

@@ -100,14 +100,21 @@ function collectAgentSpecs() {
 
     try {
       const files = fs.readdirSync(dir);
+      // A consolidated agent folder keeps its spec in AGENT.md alone (GIT-2623).
+      // Index AGENT.md only when no *.agent.md sits beside it, so folders that
+      // still carry both files are not listed twice.
+      const hasAgentSpec = files.some((name) => name.endsWith(".agent.md"));
 
       for (const file of files) {
         const filePath = path.join(dir, file);
         const stat = fs.statSync(filePath);
 
         if (stat.isDirectory()) {
           walkDir(filePath);
-        } else if (file.endsWith(".agent.md")) {
+        } else if (
+          file.endsWith(".agent.md") ||
+          (file === "AGENT.md" && !hasAgentSpec)
+        ) {
           const spec = parseAgentSpec(filePath, REPO_ROOT);
           if (spec) {
             specs.push(spec);

CHANGELOG.md

@@ -68,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **Release and changelog agents consolidated** — Each agent now has a single definition file, the release agent states that it relies on the changelog agent, and the agent index and Claude Code agent list are generated from that single file. (#3880)
 - **Label inventory token** — The organisation label inventory now needs its own dedicated token, refuses the GitHub Actions token and fails when private repositories are missing. (#3734)
 - **Private Repositories Stay Out Of Public Reports** — The label inventory and the weekly drift report now count private repositories without naming them or listing their labels. Detail goes to a private repository when one is set. (#3734)
 - **Dependabot Merge Queue Fixed** — Dependabot pull requests no longer fail the Mergify queue check, because the queue now tests each pull request in place. ([PR #3817](https://github.com/lightspeedwp/.github/pull/3817))
@@ -102,6 +103,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+- **Duplicate release and changelog agent specs** — Removed the second copy of the release and changelog agent definitions, so each agent has one definition file to maintain. (#3880)
 - **Unused Workflow Stubs** — Removed 7 placeholder workflows that ran echo-only steps on every event, plus a dead reusable trigger and stale directory readme. (#3381)
 - **Orphaned Footer Utility Removed** — Deleted an unused duplicate footer-generation script and its test, and corrected the stale documentation that pointed at it. (#3462)
 - **Inert Workflow Test Harness** — Deleted two files that declared workflow triggers but sat outside `.github/workflows/`, the only directory GitHub registers, so neither had ever run. (#3570)

agents/README.md

@@ -64,7 +64,7 @@ Agents with both specification files and complete implementations (28 total).
 - **[Website Content Strategist](./website-content-strategist-agent/)** – [`website-content-strategist.agent.md`](./website-content-strategist.agent.md)
   - Content strategy planning, audits, and SEO optimization
 
-- **[Changelog](./changelog-agent/)** – [`changelog.agent.md`](./changelog-agent/changelog.agent.md)
+- **[Changelog](./changelog-agent/)** – [`AGENT.md`](./changelog-agent/AGENT.md)
   - Automated changelog generation from commit history
 
 ### Project Management & Planning
@@ -148,7 +148,7 @@ Agents with both specification files and complete implementations (28 total).
 - **[Prompt Engineer](./prompt-engineer/)** – [`prompt-engineer.agent.md`](./prompt-engineer.agent.md)
   - Prompt optimization and engineering
 
-- **[Release Agent](./release/)** – [`release.agent.md`](./release.agent.md)
+- **[Release Agent](./release-agent/)** – [`AGENT.md`](./release-agent/AGENT.md)
   - Release management and versioning
 
 - **[Task Researcher Agent](./task-researcher-agent/)** – [`task-researcher.agent.md`](./task-researcher.agent.md)

agents/agent.md

@@ -60,7 +60,7 @@ The following instruction files provide detailed standards for agent development
 | [metrics.instructions.md](../instructions/metrics.instructions.md) | Metrics collection, aggregation, and reporting standards | metrics.agent.md |
 | [planner.instructions.md](../instructions/planner.instructions.md) | PR planning, checklist generation, and merge readiness validation | planner.agent.md (to be created) |
 | [project-meta-sync.instructions.md](../instructions/project-meta-sync.instructions.md) | GitHub Project board field synchronisation from labels | project-meta-sync.agent.md |
-| [release.instructions.md](../instructions/release.instructions.md) | Release management, semantic versioning, and changelog compliance | release.agent.md |
+| [release.instructions.md](../instructions/release.instructions.md) | Release management, semantic versioning, and changelog compliance | release-agent/AGENT.md |
 | [workflows.instructions.md](../instructions/workflows.instructions.md) | GitHub Actions workflow standards and patterns | All workflow files |
 | [reporting.instructions.md](../instructions/reporting.instructions.md) | Report generation, storage, and formatting standards | All agents that generate reports |
 

agents/changelog-agent/AGENT.md

@@ -1,5 +1,6 @@
 ---
 name: "Changelog Agent"
+title: "Changelog Agent"
 description: "Portable changelog management agent with Keep a Changelog 1.1.0 support, entry validation, and automated formatting."
 file_type: "agent"
 category: "release-management"
@@ -59,13 +60,10 @@ Provide enterprise-grade, portable changelog management using Keep a Changelog 1
 **Release Processing** - Convert [Unreleased] to version releases
 **Formatting** - Enforce changelog formatting standards
 
-## Qodo PR-Agent integration
+## Used by
 
-[Qodo PR-Agent](../../docs/QODO_PR_AGENT.md) is an optional input to this asset. It is the third-party tool, not the internal `agents/pr-agent/`. The full map of integrations is in the [responsibility matrix](../../.github/specs/019-qodo-pr-agent-integration/contracts/responsibility-matrix.md).
-
-- **Invocation**: pr-comment only, which is the proposal a maintainer requests with the `/update_changelog` comment command. The shared [`skills/qodo-pr-agent`](../../skills/qodo-pr-agent/SKILL.md) skill is **not** a source for this proposal, because `update_changelog` stores no result at PR-Agent v0.46.0 and the skill cannot return it. The comment command is the only working path (publishing is always off).
-- **On output**: Validate the proposal against the changelog rules: at most 250 characters, user-facing, no implementation detail, linked to a PR or issue, and in a Keep a Changelog category. Reject it and name the failing rule if it fails. Qodo PR-Agent never commits the entry.
-- **Fallback**: The existing changelog flow applies unchanged. When the skill returns `skipped` or `error`, say `Qodo PR-Agent input skipped: <reason>` in this asset's own output.
+- [Release Manager](../release-agent/AGENT.md) — calls this agent for changelog validation and the
+  `[Unreleased]` → version roll during release preparation and execution.
 
 ## Implementation Reference
 

agents/changelog-agent/README.md

@@ -407,7 +407,7 @@ Parse and manipulate Keep a Changelog format.
 
 ### Specification & Control Plane
 
-- **Spec Agent:** [`agents/changelog-agent/changelog.agent.md`](./changelog.agent.md) — Full agent specification with architecture and integration details
+- **Spec Agent:** [`agents/changelog-agent/AGENT.md`](./AGENT.md) — Full agent specification with architecture and integration details
 - **Workflow:** [`.github/workflows/changelog-management.yml`](../../.github/workflows/changelog-management.yml) — GitHub Actions workflow for PR validation and release processing
 - **Release Agent:** [`.github/agentic-workflows/release.agent.js`](../../.github/agentic-workflows/release.agent.js) — Release automation with changelog integration
 
@@ -422,21 +422,23 @@ Parse and manipulate Keep a Changelog format.
 The Changelog Agent is split into two tiers:
 
 1. **Portable Agent (this folder)** — `agents/changelog-agent/changelog.agent.js` — ESM implementation with complete functionality
-2. **Spec Agent** — `agents/changelog-agent/changelog.agent.md` — Specification and integration guide
+2. **Spec Agent** — `agents/changelog-agent/AGENT.md` — Specification and integration guide
 
 All three pieces (spec, portable agent, workflow) reference each other to ensure consistency and traceability.
 
 ### Definition file roles
 
-- `AGENT.md` — the agent definition file required by the repo's agent-folder convention.
-- `changelog.agent.md` — the portable, reusable spec (validated as a subagent definition).
-- The two files carry the same functional content by design; `changelog.agent.md` is the file every live reference points at.
+- `AGENT.md` — the single canonical agent definition and specification. Every live
+  reference points at it. The former duplicate `changelog.agent.md` was merged into it
+  and removed (GIT-2623).
+- The [Release Manager](../release-agent/AGENT.md) depends on this agent for changelog
+  validation and the version roll.
 
 ### Claude Code discovery
 
 Claude Code discovers project subagents under `.claude/agents/`. The thin
 definition `.claude/agents/changelog-agent.md` is generated from
-`changelog.agent.md` — do not edit it by hand. Regenerate with
+`AGENT.md` — do not edit it by hand. Regenerate with
 `node scripts/agents/generate-agent-defs.cjs`; the drift test
 (`scripts/agents/__tests__/generate-agent-defs.test.js`) fails if the
 checked-in file disagrees with the canonical spec. The Copilot location
@@ -577,7 +579,7 @@ entry: {
 
 ## See Also
 
-- **Changelog Spec Agent** — [`agents/changelog-agent/changelog.agent.md`](./changelog.agent.md)
+- **Changelog Spec Agent** — [`agents/changelog-agent/AGENT.md`](./AGENT.md)
 - **Release Agent README** — `agents/release/README.md`
 - **Release Process Guide** — `docs/RELEASE_PROCESS.md`
 - **Keep a Changelog Standard** — <https://keepachangelog.com/en/1.1.0/>

agents/release-agent/AGENT.md

@@ -73,7 +73,7 @@ permissions:
   - shell
 metadata:
   guardrails: Never publish incomplete or broken releases. Abort and notify if any validation fails. Always lint and test before release. Support dry-run mode. Log all actions for audit trails. Default to read-only analysis unless user explicitly requests changes.
-implementation: release
+implementation: "agents/release-agent/"
 language: en
 created_date: '2026-08-29'
 ---
@@ -145,6 +145,13 @@ You are the **Release Manager Agent** for `lightspeedwp/.github`. Automate relea
 - **Notes compilation**: use changelog sections + merged PRs to build highlights, breaking changes, contributors, and compare links.
 - **Label hygiene**: prefer single `release:*` label per PR to align human intent with scope selection.
 
+## Dependency: Changelog Agent
+
+The release flow depends on the [Changelog Agent](../changelog-agent/AGENT.md). Changelog
+validation, `[Unreleased]` checks and the roll to `[X.Y.Z] - YYYY-MM-DD` follow its Keep a
+Changelog 1.1.0 rules. Run or defer to it for every changelog step above. Do not
+reimplement changelog parsing here.
+
 # Constraints
 
 - Must not publish incomplete or broken releases.