| name | dot-ai-changelog-fragment |
| description | Create changelog fragment for release notes. Invoke during /prd-done workflow during the first push to the PR. |
| user-invocable | true |
Create Changelog Fragment
Create a towncrier changelog fragment for release notes when completing PRD work. This should be included in the PR so the fragment is reviewed along with the code changes.
Workflow
Step 1: Identify the PRD
If not already known from context, ask: "Which PRD should I create release notes for?"
Look for:
- PRD mentioned in recent conversation
- PRD referenced in current branch name (e.g.,
feature/prd-320-*)
- PRD file path provided by user
Step 2: Read the PRD Thoroughly
Read the entire PRD file to extract:
- Problem Statement: What user pain point was solved, why it mattered
- Solution Overview: What the feature does, how it works
- User Impact: Specific benefits, what users can now do
- Key Capabilities: Individual features, options, or modes added
- Technical Details: Configuration options, environment variables, commands
- Documentation Updates: Which docs were added or updated (check Milestones section)
Step 3: Determine Fragment Type
Read pyproject.toml to see the available fragment types. Each [[tool.towncrier.type]] section has:
- A comment above it describing when to use that type
- A
directory field (the type identifier used in the filename, e.g., feature for .feature.md)
Choose the type that best matches the PRD based on those descriptions.
Step 4: Write the Fragment
Create file: changelog.d/[issue-id].[type].md
IMPORTANT: Use flat structure, NOT subdirectories!
- ✅ Correct:
changelog.d/329.feature.md
- ❌ Wrong:
changelog.d/feature/329.md
Naming convention:
issue-id: GitHub issue number from PRD (e.g., 320)type: Type identifier from step 3 (e.g., feature, bugfix, misc)
Content format:
## [Feature Title]
[Opening sentence: What this feature is and the problem it solves]
[Key capabilities paragraph: Specific things users can now do, with concrete examples]
[Configuration/usage paragraph if applicable: How to enable or use the feature]
[Documentation link if docs were updated]
Documentation links:
If the PRD includes documentation updates, link to the relevant page on devopstoolkit.ai. The URL pattern is:
https://devopstoolkit.ai/docs/{project}/{path}- Where
{project} is: mcp (dot-ai), controller (dot-ai-controller), ui (dot-ai-ui), or stack (dot-ai-stack)
- And
{path} maps from the docs folder (e.g., docs/guides/mcp-recommendation-guide.md → guides/mcp-recommendation-guide)
Example: changelog.d/142.feature.md
## Multi-Cluster Management
Manage multiple Kubernetes clusters from a single dot-ai instance. Previously, each cluster required its own dot-ai deployment, making it difficult to compare configurations or apply consistent patterns across environments.
The `query` tool now accepts a `--cluster` flag to target specific clusters, and results indicate which cluster each resource belongs to. The `recommend` tool can generate manifests targeting different clusters with environment-specific customizations. Cross-cluster searches let you find resources across all connected clusters simultaneously—useful for tracking down where a particular workload is deployed. Cluster health aggregation shows a unified view of all clusters in the `version` output.
Configure additional clusters by adding kubeconfig contexts to `ADDITIONAL_KUBECONFIGS` (comma-separated paths). Each context becomes available as a cluster target. The default cluster remains the current kubeconfig context when no `--cluster` flag is specified.
See the [Multi-Cluster Setup Guide](https://devopstoolkit.ai/docs/mcp/setup/multi-cluster-setup) for configuration details and examples.
Step 5: Confirm Creation
Show the user:
- The fragment file path created
- The content written
- Reminder to commit and push with the PR
Guidelines
- User-focused: Describe what users gain, not implementation details
- Specific: Include concrete examples of what each capability does
- Complete: Cover all major features added, not just the headline
- Present tense: "Tools now return..." not "Added support for..."
- No diary style: "Multi-Cluster Management" not "Added multi-cluster support"
- Include configuration: Mention environment variables, commands, or setup steps
- Link to docs: If PRD updated documentation, link to the specific page on devopstoolkit.ai
