♻️ Simplify structured output types to use markdown-based content

Replace complex structured JSON schemas (GeneratedPullRequest,
ChangelogResponse,
ReleaseNotesResponse) with simpler Markdown* types that wrap a single content
field.
This lets the LLM drive output structure while capability TOMLs provide
guidelines.

Changes:
- Add MarkdownChangelog, MarkdownPullRequest, MarkdownReleaseNotes types
- Update capability TOML prompts to request free-form markdown in content
field
- Refactor iris.rs to dispatch on new type names and use raw_content()/
format()
- Add list_directory() helper to file_read.rs for graceful directory handling
- Update tests to work with markdown-based assertions instead of structured
fields
- Clean up unused imports and remove format_pull_request() helper

The Markdown* types use render_markdown_for_terminal() for styled CLI output
while raw_content() provides clean markdown for file output or web UIs.

Author: hyperb1iss

CLAUDE.md

@@ -30,10 +30,10 @@ src/
 │       └── parallel_analyze.rs # Concurrent subagent processing
 ├── types/                  # Response type definitions
 │   ├── commit.rs          # GeneratedMessage
-│   ├── pr.rs              # GeneratedPullRequest
-│   ├── review.rs          # GeneratedReview, CodeIssue
-│   ├── changelog.rs       # ChangelogResponse, ChangeEntry
-│   └── release_notes.rs   # ReleaseNotesResponse
+│   ├── pr.rs              # MarkdownPullRequest
+│   ├── review.rs          # MarkdownReview
+│   ├── changelog.rs       # MarkdownChangelog
+│   └── release_notes.rs   # MarkdownReleaseNotes
 ├── services/               # Pure operations (no LLM)
 │   └── git_commit.rs      # GitCommitService for git operations
 ├── cli.rs                 # CLI entry point
@@ -88,11 +88,14 @@ Capabilities define:
 
 Iris produces structured JSON matching these schemas (all in `src/types/`):
 
-- `GeneratedMessage` - Commit message (emoji, title, body)
-- `GeneratedPullRequest` - PR description with sections
-- `GeneratedReview` - Code review with dimension analysis
-- `ChangelogResponse` - Changelog sections (Added, Changed, Fixed, etc.)
-- `ReleaseNotesResponse` - Release notes with highlights
+- `GeneratedMessage` - Commit message (emoji, title, body) - structured JSON
+- `MarkdownPullRequest` - PR description as free-form markdown
+- `MarkdownReview` - Code review as LLM-driven markdown
+- `MarkdownChangelog` - Changelog in Keep a Changelog format as markdown
+- `MarkdownReleaseNotes` - Release notes as free-form markdown
+
+The `Markdown*` types use a simple `{ content: String }` structure, letting the LLM drive
+the format while capability TOMLs provide guidelines. This produces more natural, flexible output.
 
 ## Adding a New Capability
 

src/agents/capabilities/changelog.toml

@@ -1,9 +1,9 @@
 name = "changelog"
 description = "Generate changelogs from Git commits and changes"
-output_type = "ChangelogResponse"
+output_type = "MarkdownChangelog"
 
 task_prompt = """
-You are Iris, an expert release engineer producing a structured changelog for the specified Git range. Match the legacy CLI exactly so downstream tooling parses the JSON without post-processing.
+You are Iris, an expert release engineer producing a changelog entry for the specified Git range in Keep a Changelog format.
 
 ## Mandatory Data Collection
 1. `git_log(from, to)` — understand commit scope/themes.
@@ -22,91 +22,100 @@ You are Iris, an expert release engineer producing a structured changelog for th
 6. For Small/Medium changesets: You may request `detail="standard"` if needed.
 7. Call additional tools (code search, workspace notes) whenever you need context before summarizing.
 
-## Required JSON Schema (`ChangelogResponse`)
+## Output Format: Free-Form Markdown
+
+Return a JSON object with a single `content` field containing the changelog entry as markdown.
+Follow the Keep a Changelog format (https://keepachangelog.com/).
+
+### Required Structure
+
+```markdown
+## [VERSION] - DATE
+
+SUMMARY (1-3 sentences capturing the release theme)
+
+### Added
+- New feature descriptions
+
+### Changed
+- Modification descriptions
+
+### Fixed
+- Bug fix descriptions
+
+### Security
+- Security-related changes (if any)
+
+### Deprecated
+- Deprecated features (if any)
+
+### Removed
+- Removed features (if any)
+
+### Breaking Changes
+- Breaking change descriptions with upgrade notes (if any)
+
+### Metrics
+- Total Commits: N
+- Files Changed: N
+- Insertions: +N
+- Deletions: -N
 ```
-{
-  "version": "string or null",
-  "release_date": "string or null",
-  "summary": "1-3 sentence overview of the release highlights (what's the big picture?)",
-  "sections": {
-    "Added": [ChangeEntry],
-    "Changed": [ChangeEntry],
-    "Deprecated": [ChangeEntry],
-    "Removed": [ChangeEntry],
-    "Fixed": [ChangeEntry],
-    "Security": [ChangeEntry]
-  },
-  "breaking_changes": [BreakingChange],
-  "metrics": {
-    "total_commits": number,
-    "files_changed": number,
-    "insertions": number,
-    "deletions": number,
-    "total_lines_changed": number
-  }
-}
 
-ChangeEntry = {
-  "description": "impact-focused sentence",
-  "commit_hashes": ["short or full hashes"],
-  "associated_issues": ["issue refs like #123"],
-  "pull_request": "PR #id or null"
-}
+### Guidelines
+
+**Section Organization:**
+- Include only sections that have entries (skip empty sections)
+- Order: Added → Changed → Fixed → Security → Deprecated → Removed → Breaking Changes → Metrics
+- Use the exact section names shown above (no "Features" or "Bug Fixes")
+
+**Entry Format:**
+- Use `backticks` for files, modules, functions, commands, flags
+- Use **bold** for key concepts or emphasis
+- Include commit hash references in parentheses when helpful: `(abc1234)`
+- Reference issues/PRs when available: `#123`, `PR #456`
+
+**Writing Style:**
+- Present tense, imperative mood: "Add" not "Added"
+- Start with capital letter, no ending period
+- Be concise but descriptive
+- Avoid cliché words: "enhance", "streamline", "leverage", "optimize"
+- Focus on impact—omit trivial changes
+- Group related changes; list most impactful first
+
+**Version & Date:**
+- Use `[Unreleased]` if no version tag provided
+- Use ISO date format: YYYY-MM-DD
 
-BreakingChange = {
-  "description": "what changed and required action",
-  "commit_hash": "hash"
+**Metrics:**
+- Compute from actual git data—do not guess
+- Include: commits, files changed, insertions, deletions
+
+## Example Output
+
+```json
+{
+  "content": "## [1.2.0] - 2024-01-15\n\nThis release introduces **parallel analysis** for large changesets and improves agent reliability.\n\n### Added\n\n- Add `parallel_analyze` tool for concurrent subagent processing (abc1234)\n- Add `workspace` tool for agent notes and task management (def5678)\n\n### Changed\n\n- Rename `changes/` module to `changelog.rs` for cleaner structure\n- Update token limits from 8K to 16K for complex outputs\n\n### Fixed\n\n- Fix memory leak in `cache_handler` when processing large diffs (ghi9012)\n- Fix JSON parsing for responses with trailing commas\n\n### Breaking Changes\n\n- **Remove MCP server** (`git-iris serve` command and all MCP tooling)\n  - Users should migrate to direct CLI usage\n\n### Metrics\n\n- Total Commits: 12\n- Files Changed: 23\n- Insertions: +1,245\n- Deletions: -387"
 }
 ```
 
-- **You must emit all six section keys exactly as shown, even if some arrays are empty.** Do not rename them (no "Features" or "Bug Fixes").
-- Descriptions must cite concrete artifacts (files, modules, commands) and the motivation/impact.
-- Use associated_issues/pull_request whenever data is available; otherwise leave arrays empty / null.
-
 ## Tone & Emoji Policy
 - Keep language precise and high-signal. NO YAPPING.
-- When gitmoji mode is enabled: Start each description with an emoji matching the change type (✨ Added, 🔄 Changed, 🐛 Fixed, 🔒 Security, ⚠️ Deprecated, 🔥 Removed). Never modify JSON keys or section names; enum strings must stay plain text.
-- When gitmoji mode is disabled (or conventional preset): Do not emit emojis in descriptions.
+- When gitmoji mode is enabled: Start each entry with an emoji matching the change type (✨ Added, 🔄 Changed, 🐛 Fixed, 🔒 Security, ⚠️ Deprecated, 🔥 Removed).
+- When gitmoji mode is disabled: No emojis in descriptions.
 
 ## Detail Level Adaptation
-Adapt your output based on the detail level specified in the user prompt:
-- **Minimal**: 1-2 entries per section, brief descriptions, no associated issues/PRs
+Adapt your output based on the detail level specified:
+- **Minimal**: 1-2 entries per section, brief descriptions
 - **Standard** (default): 2-4 entries per section, balanced descriptions with commit refs
-- **Detailed**: 3-5+ entries per section, full descriptions with all metadata (issues, PRs, impact)
-
-## Writing Guidelines
-- Use present tense and imperative mood ("Add X" not "Added X")
-- Start each entry with capital letter, no ending period
-- Be concise but descriptive with good grammar
-- Avoid cliché words: "enhance", "streamline", "leverage", "optimize"
-- Focus on impact and significance—omit trivial changes below relevance threshold
-- Group related changes; list most impactful first within each section
-- Mention dependency/build changes under appropriate category
-- DO NOT speculate about purpose—only state what's evident from context
-
-## Markdown Formatting (IMPORTANT)
-Use rich markdown in descriptions to make entries scannable and expressive:
-- Use `backticks` for file names, modules, functions, commands, flags (e.g., "`src/types/`", "`--debug`", "`git_diff()`")
-- Use **bold** for key concepts or emphasis (e.g., "**breaking change**", "**unified architecture**")
-- For the summary field, use bold and inline code to highlight the release theme
-
-Example descriptions (with gitmoji enabled):
-- "✨ Add `parallel_analyze` tool for concurrent subagent processing"
-- "🔄 Rename `changes/` module to `changelog.rs` for cleaner structure"
-- "🔥 **Remove MCP server** (`git-iris serve` command and all MCP tooling)"
-- "🐛 Fix memory leak in `cache_handler` when processing large diffs"
-
-Example descriptions (without gitmoji):
-- "Add `parallel_analyze` tool for concurrent subagent processing"
-- "Rename `changes/` module to `changelog.rs` for cleaner structure"
-- "**Remove MCP server** (`git-iris serve` command and all MCP tooling)"
+- **Detailed**: 3-5+ entries per section, full descriptions with all metadata
 
 ## Generation Steps
-1. Gather context via the mandatory tool calls; if you skipped a tool, explain why in your reasoning and call it before drafting.
-2. **Write a summary** (1-3 sentences) capturing the release's key theme or highlights. Focus on the most significant change or overall direction.
-3. Bucket each change into the canonical section that best matches (Added, Changed, Deprecated, Removed, Fixed, Security).
-4. Provide entries per section based on detail level. Each entry should describe the change, its purpose, and where it lives in the codebase.
-5. Document every breaking change (if any) with concrete upgrade steps in `breaking_changes`.
-6. Compute metrics from actual git data — do not guess.
-7. Output only the JSON object defined above; do not wrap in Markdown or prose.
+1. Gather context via the mandatory tool calls
+2. Determine version from git tag or use [Unreleased]
+3. Write a summary capturing the release's key theme
+4. Categorize changes into the canonical sections
+5. Document breaking changes with upgrade notes
+6. Compute metrics from git data
+7. Return JSON with the `content` field containing the full markdown
 """