Task Plan: Fix CHANGELOG References to Nonexistent Files

Task Plan: Fix CHANGELOG References to Nonexistent Files

Context

The conventional-commits plugin has dead references in CHANGELOG.md (docs/examples.md, placeholder release URL) and in SKILL.md Related Skills (git-commit-helper, semantic-release). All must be removed or fixed.

Source documents:

• Feature Context
• Architecture Spec

Plugin root: plugins/conventional-commits/

Context Manifest

Generated by context-gathering agent on 2026-02-23

How This Currently Works: conventional-commits Plugin Documentation

The conventional-commits plugin is a documentation-only plugin (no Python code, no CLI). It provides a SKILL.md that teaches Conventional Commits v1.0.0 specification, commit types, validation patterns, and integration with tools like commitlint, pre-commit, semantic-release, git-cliff.

Current structure:

• plugins/conventional-commits/CHANGELOG.md — Keep a Changelog format, documents v1.0.0 release
• plugins/conventional-commits/skills/conventional-commits/SKILL.md — Main skill with Related Skills section
• plugins/conventional-commits/.claude-plugin/plugin.json — Plugin manifest (skills, commands)
• No docs/ folder exists in the plugin

Dead references identified:

1. CHANGELOG line 27: "Added docs/examples.md with 15 real-world usage scenarios" — docs/examples.md does not exist
2. CHANGELOG line 31: [1.0.0]: https://github.com/owner/conventional-commits/releases/tag/v1.0.0 — placeholder URL (owner/conventional-commits is not a real repo)
3. SKILL.md Related Skills: git-commit-helper — actual skill is commit-staged (.claude/skills/commit-staged/)
4. SKILL.md Related Skills: semantic-release — no such skill exists in the repo

Existing skills that DO exist:

• plugins/commitlint/skills/commitlint/SKILL.md — commitlint skill
• plugins/python3-development/skills/pre-commit/SKILL.md — pre-commit skill
• .claude/skills/commit-staged/SKILL.md — generates conventional commit messages from diffs

For Implementation: What Needs to Connect

T1 and T2 are independent edits to different files. No code paths or imports connect them. The only dependency is that T3 must run after T1 and T2 complete.

CHANGELOG edit pattern: Use search_replace or direct edit. Replace line 27 text; remove or replace line 31. Preserve YAML/markdown structure.

SKILL.md edit pattern: Locate the "## Related Skills" section (around lines 494-501). Update bullet list: change git-commit-helper → commit-staged; remove semantic-release; verify commitlint and pre-commit use correct activation syntax (e.g., Skill(command: "commitlint:commitlint")).

Technical Reference Details

File Locations

• CHANGELOG: plugins/conventional-commits/CHANGELOG.md
• SKILL: plugins/conventional-commits/skills/conventional-commits/SKILL.md
• Architect decisions: plan/architect-conventional-commits-changelog-refs.md

Skill Activation Syntax (from CLAUDE.md)

Reference skills using activation syntax: Skill(command: "plugin-name:skill-name") or Skill(command: "commit-staged") for root-level skills.

Validation Commands

claude plugin validate plugins/conventional-commits/

Plugin_validator (if used): uv run plugins/plugin-creator/scripts/plugin_validator.py or project-specific invocation.

Task T1: Fix CHANGELOG.md dead references

---
task: T1
title: Fix CHANGELOG.md dead references
status: complete
agent: service-docs-maintainer
dependencies: []
priority: 1
complexity: low
accuracy-risk: low
parallelize-with: [T2]
reason: T1 and T2 touch different files (CHANGELOG vs SKILL)
handoff: Summary of edits; confirm no dead refs remain
---

Context

plugins/conventional-commits/CHANGELOG.md lines 27 and 31 reference non-existent resources.

Objective

Remove or correct all dead references in CHANGELOG.md so every referenced file and URL exists or is removed.

Required Inputs

• plan/architect-conventional-commits-changelog-refs.md — Design decisions for docs/examples.md and release URL
• plugins/conventional-commits/CHANGELOG.md — Current content

Requirements

1. Replace or remove line 27 ("Added docs/examples.md with 15 real-world usage scenarios") per architect decision
2. Remove or replace line 31 placeholder URL [1.0.0]: https://github.com/owner/conventional-commits/releases/tag/v1.0.0
3. Preserve Keep a Changelog format and all other content

Constraints

• Do not invent new documentation; only fix references
• Do not add new sections to CHANGELOG

Expected Outputs

• plugins/conventional-commits/CHANGELOG.md — Updated with no dead references

Acceptance Criteria

1. No reference to docs/examples.md or any non-existent file path
2. No placeholder URL (owner/conventional-commits); either valid URL or link line removed
3. CHANGELOG remains valid markdown and Keep a Changelog compliant

Verification Steps

1. Read(plugins/conventional-commits/CHANGELOG.md) — Confirm no docs/examples.md reference
2. Grep(pattern="docs/|owner/conventional-commits", path=plugins/conventional-commits/CHANGELOG.md) — Returns no matches
3. Read(plugins/conventional-commits/CHANGELOG.md) — Confirm release link is valid or absent

Task T2: Fix SKILL.md Related Skills section

---
task: T2
title: Fix SKILL.md Related Skills section
status: complete
agent: service-docs-maintainer
dependencies: []
priority: 1
complexity: low
accuracy-risk: low
parallelize-with: [T1]
reason: T1 and T2 touch different files
handoff: Summary of edits; list skills now referenced
---

Context

plugins/conventional-commits/skills/conventional-commits/SKILL.md Related Skills section (lines 494-501) references git-commit-helper and semantic-release. git-commit-helper maps to commit-staged; semantic-release skill does not exist.

Objective

Update Related Skills to reference only existing skills with correct activation syntax.

Required Inputs

• plan/architect-conventional-commits-changelog-refs.md — Design decisions for Related Skills
• plugins/conventional-commits/skills/conventional-commits/SKILL.md — Current content
• Verification: plugins/commitlint/, plugins/python3-development/skills/pre-commit/, .claude/skills/commit-staged/ exist

Requirements

1. Replace git-commit-helper with commit-staged (or equivalent activation syntax)
2. Remove semantic-release reference (no skill exists)
3. Keep commitlint and pre-commit; ensure activation syntax is correct (e.g., Skill(command: "commitlint:commitlint"), Skill(command: "python3-development:pre-commit"))

Constraints

• Do not create new skills
• Preserve skill activation syntax conventions from CLAUDE.md

Expected Outputs

• plugins/conventional-commits/skills/conventional-commits/SKILL.md — Updated Related Skills section

Acceptance Criteria

1. All referenced skills exist in the repository (commitlint, pre-commit, commit-staged)
2. No reference to semantic-release or git-commit-helper
3. Activation syntax follows project conventions (Skill command format)

Verification Steps

1. Grep(pattern="commitlint|pre-commit|commit-staged|semantic-release|git-commit-helper", path=plugins/conventional-commits/skills/conventional-commits/SKILL.md) — Only commitlint, pre-commit, commit-staged present
2. Glob(plugins/commitlint/**/SKILL.md) and Glob(plugins/python3-development/skills/pre-commit/**) and Read(.claude/skills/commit-staged/SKILL.md) — Confirm all exist
3. Read Related Skills section — Verify activation syntax matches other skills in repo

Task T3: Validate plugin and run plugin_validator

---
task: T3
title: Validate plugin and run plugin_validator
status: complete
agent: general-purpose
dependencies: [T1, T2]
priority: 2
complexity: low
accuracy-risk: low
parallelize-with: []
reason: Must run after T1 and T2 complete
handoff: Validation output; BLOCKED if any failures
---

Context

After T1 and T2, the plugin must pass validation to confirm no reference-related issues remain.

Objective

Run plugin validation and plugin_validator (if available) to confirm the conventional-commits plugin passes all checks.

Required Inputs

• T1 and T2 outputs (updated CHANGELOG.md and SKILL.md)
• claude plugin validate command availability
• plugins/plugin-creator/scripts/plugin_validator.py or equivalent

Requirements

1. Run claude plugin validate plugins/conventional-commits/ — must pass
2. Run plugin_validator if available (e.g., uv run plugins/plugin-creator/scripts/plugin_validator.py or project-specific command)
3. Report any failures; do not proceed if BLOCKED

Constraints

• T3 depends on T1 and T2; do not run before they complete

Expected Outputs

• Validation output (success or failure report)
• Confirmation that no dead reference errors remain

Acceptance Criteria

1. claude plugin validate plugins/conventional-commits/ exits 0
2. plugin_validator (if run) reports no new errors related to references
3. No dead reference warnings in validation output

Verification Steps

1. Execute claude plugin validate plugins/conventional-commits/ — capture exit code and output
2. Execute plugin_validator per project docs — capture output
3. Grep validation output for "reference", "missing", "not found" — confirm no such errors