atlassian-templates

Original source / Raw SKILL.md

---
name: "atlassian-templates"
description: Atlassian Template and Files Creator/Modifier expert for creating, modifying, and managing Jira and Confluence templates, blueprints, custom layouts, reusable components, and standardized content structures. Use when building org-wide templates, custom blueprints, page layouts, and automated content generation.
---

# Atlassian Template & Files Creator Expert

Specialist in creating, modifying, and managing reusable templates and files for Jira and Confluence. Ensures consistency, accelerates content creation, and maintains org-wide standards.

---

## Workflows

### Template Creation Process
1. **Discover**: Interview stakeholders to understand needs
2. **Analyze**: Review existing content patterns
3. **Design**: Create template structure and placeholders
4. **Implement**: Build template with macros and formatting
5. **Test**: Validate with sample data — confirm template renders correctly in preview before publishing
6. **Document**: Create usage instructions
7. **Publish**: Deploy to appropriate space/project via MCP (see MCP Operations below)
8. **Verify**: Confirm deployment success; roll back to previous version if errors occur
9. **Train**: Educate users on template usage
10. **Monitor**: Track adoption and gather feedback
11. **Iterate**: Refine based on usage

### Template Modification Process
1. **Assess**: Review change request and impact
2. **Version**: Create new version, keep old available
3. **Modify**: Update template structure/content
4. **Test**: Validate changes don't break existing usage; preview updated template before publishing
5. **Migrate**: Provide migration path for existing content
6. **Communicate**: Announce changes to users
7. **Support**: Assist users with migration
8. **Archive**: Deprecate old version after transition; confirm deprecated template is unlisted, not deleted

### Blueprint Development
1. Define blueprint scope and purpose
2. Design multi-page structure
3. Create page templates for each section
4. Configure page creation rules
5. Add dynamic content (Jira queries, user data)
6. Test blueprint creation flow end-to-end with a sample space
7. Verify all macro references resolve correctly before deployment
8. **HANDOFF TO**: Atlassian Admin for global deployment

---

## Confluence Templates Library

See **TEMPLATES.md** for full reference tables and copy-paste-ready template structures. The following summarises the standard types this skill creates and maintains.

### Confluence Template Types
| Template | Purpose | Key Macros Used |
|----------|---------|-----------------|
| **Meeting Notes** | Structured meeting records with agenda, decisions, and action items | `{date}`, `{tasks}`, `{panel}`, `{info}`, `{note}` |
| **Project Charter** | Org-level project scope, stakeholder RACI, timeline, and budget | `{panel}`, `{status}`, `{timeline}`, `{info}` |
| **Sprint Retrospective** | Agile ceremony template with What Went Well / Didn't Go Well / Actions | `{panel}`, `{expand}`, `{tasks}`, `{status}` |
| **PRD** | Feature definition with goals, user stories, functional/non-functional requirements, and release plan | `{panel}`, `{status}`, `{jira}`, `{warning}` |
| **Decision Log** | Structured option analysis with decision matrix and implementation tracking | `{panel}`, `{status}`, `{info}`, `{tasks}` |

**Standard Sections** included across all Confluence templates:
- Header panel with metadata (owner, date, status)
- Clearly labelled content sections with inline placeholder instructions
- Action items block using `{tasks}` macro
- Related links and references

### Complete Example: Meeting Notes Template

The following is a copy-paste-ready Meeting Notes template in Confluence storage format (wiki markup):

```
{panel:title=Meeting Metadata|borderColor=#0052CC|titleBGColor=#0052CC|titleColor=#FFFFFF}
*Date:* {date}
*Owner / Facilitator:* @[facilitator name]
*Attendees:* @[name], @[name]
*Status:* {status:colour=Yellow|title=In Progress}
{panel}

h2. Agenda
# [Agenda item 1]
# [Agenda item 2]
# [Agenda item 3]

h2. Discussion & Decisions
{panel:title=Key Decisions|borderColor=#36B37E|titleBGColor=#36B37E|titleColor=#FFFFFF}
* *Decision 1:* [What was decided and why]
* *Decision 2:* [What was decided and why]
{panel}

{info:title=Notes}
[Detailed discussion notes, context, or background here]
{info}

h2. Action Items
{tasks}
* [ ] [Action item] — Owner: @[name] — Due: {date}
* [ ] [Action item] — Owner: @[name] — Due: {date}
{tasks}

h2. Next Steps & Related Links
* Next meeting: {date}
* Related pages: [link]
* Related Jira issues: {jira:key=PROJ-123}
```

> Full examples for all other template types (Project Charter, Sprint Retrospective, PRD, Decision Log) and all Jira templates can be generated on request or found in **TEMPLATES.md**.

---

## Jira Templates Library

### Jira Template Types
| Template | Purpose | Key Sections |
|----------|---------|--------------|
| **User Story** | Feature requests in As a / I want / So that format | Acceptance Criteria (Given/When/Then), Design links, Technical Notes, Definition of Done |
| **Bug Report** | Defect capture with reproduction steps | Environment, Steps to Reproduce, Expected vs Actual Behavior, Severity, Workaround |
| **Epic** | High-level initiative scope | Vision, Goals, Success Metrics, Story Breakdown, Dependencies, Timeline |

**Standard Sections** included across all Jira templates:
- Clear summary line
- Acceptance or success criteria as checkboxes
- Related issues and dependencies block
- Definition of Done (for stories)

---

## Macro Usage Guidelines

**Dynamic Content**: Use macros for auto-updating content (dates, user mentions, Jira queries)
**Visual Hierarchy**: Use `{panel}`, `{info}`, and `{note}` to create visual distinction
**Interactivity**: Use `{expand}` for collapsible sections in long templates
**Integration**: Embed Jira charts and tables via `{jira}` macro for live data

---

## Atlassian MCP Integration

**Primary Tools**: Confluence MCP, Jira MCP

### Template Operations via MCP

All MCP calls below use the exact parameter names expected by the Atlassian MCP server. Replace angle-bracket placeholders with real values before executing.

**Create a Confluence page template:**
```json
{
  "tool": "confluence_create_page",
  "parameters": {
    "space_key": "PROJ",
    "title": "Template: Meeting Notes",
    "body": "<storage-format template content>",
    "labels": ["template", "meeting-notes"],
    "parent_id": "<optional parent page id>"
  }
}
```

**Update an existing template:**
```json
{
  "tool": "confluence_update_page",
  "parameters": {
    "page_id": "<existing page id>",
    "version": "<current_version + 1>",
    "title": "Template: Meeting Notes",
    "body": "<updated storage-format content>",
    "version_comment": "v2 — added status macro to header"
  }
}
```

**Create a Jira issue description template (via field configuration):**
```json
{
  "tool": "jira_update_field_configuration",
  "parameters": {
    "project_key": "PROJ",
    "field_id": "description",
    "default_value": "<template markdown or Atlassian Document Format JSON>"
  }
}
```

**Deploy template to multiple spaces (batch):**
```json
// Repeat for each target space key
{
  "tool": "confluence_create_page",
  "parameters": {
    "space_key": "<SPACE_KEY>",
    "title": "Template: Meeting Notes",
    "body": "<storage-format template content>",
    "labels": ["template"]
  }
}
// After each create, verify:
{
  "tool": "confluence_get_page",
  "parameters": {
    "space_key": "<SPACE_KEY>",
    "title": "Template: Meeting Notes"
  }
}
// Assert response status == 200 and page body is non-empty before proceeding to next space
```

**Validation checkpoint after deployment:**
- Retrieve the created/updated page and assert it renders without macro errors
- Check that `{jira}` embeds resolve against the target Jira project
- Confirm `{tasks}` blocks are interactive in the published view
- If any check fails: revert using `confluence_update_page` with `version: <current + 1>` and the previous version body

---

## Best Practices & Governance

**Org-Specific Standards:**
- Track template versions with version notes in the page header
- Mark outdated templates with a `{warning}` banner before archiving; archive (do not delete)
- Maintain usage guides linked from each template
- Gather feedback on a quarterly review cycle; incorporate usage metrics before deprecating

**Quality Gates (apply before every deployment):**
- Example content provided for each section
- Tested with sample data in preview
- Version comment added to change log
- Feedback mechanism in place (comments enabled or linked survey)

**Governance Process**:
1. Request and justification
2. Design and review
3. Testing with pilot users
4. Documentation
5. Approval
6. Deployment (via MCP or manual)
7. Training
8. Monitoring

---

## Handoff Protocols

See **HANDOFFS.md** for the full handoff matrix. Summary:

| Partner | Receives FROM | Sends TO |
|---------|--------------|---------|
| **Senior PM** | Template requirements, reporting templates, executive formats | Completed templates, usage analytics, optimization suggestions |
| **Scrum Master** | Sprint ceremony needs, team-specific requests, retro format preferences | Sprint-ready templates, agile ceremony structures, velocity tracking templates |
| **Jira Expert** | Issue template requirements, custom field display needs | Issue description templates, field config templates, JQL query templates |
| **Confluence Expert** | Space-specific needs, global template requests, blueprint requirements | Configured page templates, blueprint structures, deployment plans |
| **Atlassian Admin** | Org-wide standards, global deployment requirements, compliance templates | Global templates for approval, usage reports, compliance status |


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### references/governance-framework.md

```markdown
# Template Governance Framework

## Overview

Operational framework for managing template lifecycle — creation, updates, deprecation, and quality enforcement with concrete thresholds and decision criteria.

## Ownership Model

### Roles

**Template Owner** (1 per template):
- Reviews usage dashboard on the 1st of each quarter
- Archives templates with <5 uses in the past 90 days
- Responds to change requests within 14 calendar days
- Runs quarterly accuracy check: open 3 random pages created from the template, verify content matches current process
- Escalates to committee if change affects >50 users

**Template Steward** (1 per team/domain):
- Runs monthly usage pull: `CQL: type = page AND label = "template-{name}" AND created >= "now-30d"`
- Flags templates where >30% of users delete or heavily modify a section (indicates friction)
- Collects and triages feedback — tags Jira tickets with `template-change` and links to template page

**Template Committee** (3-5 people, for orgs with 20+ templates):
- Meets quarterly (45 min max): reviews new proposals, resolves conflicts, flags duplicates
- Decision rule: approve if template serves >1 team and doesn't duplicate existing template by >60% content overlap
- Publishes quarterly "Template Health" Confluence page with adoption rates and actions taken

### Assignment Matrix

| Template Category | Owner Role | Steward Role |
|------------------|-----------|-------------|
| Engineering templates | Engineering Manager | Senior Engineer |
| Product templates | Head of Product | Senior PM |
| Meeting templates | Operations Lead | EA/Admin |
| Project templates | PMO Lead | Senior PM |
| HR/People templates | HR Director | HR Coordinator |
| Company-wide templates | Operations Lead | Template Committee |

## Approval Workflow

### New Template Proposal

1. **Request** - Submitter creates proposal with:
   - Template name and purpose
   - Target audience
   - Justification (why existing templates are insufficient)
   - Draft content
   - Proposed owner

2. **Review** - Template owner/committee evaluates:
   - Does this duplicate an existing template?
   - Is the scope appropriate (not too broad or narrow)?
   - Does it follow design standards?
   - Is it needed by more than one team?

3. **Pilot** - If approved:
   - Deploy to a small group for 2-4 weeks
   - Collect feedback on usability and completeness
   - Iterate based on feedback

4. **Launch** - After successful pilot:
   - Publish to template library
   - Announce to relevant teams
   - Add to Template Index page
   - Train users if needed

5. **Monitor** - Post-launch:
   - Track adoption rate (first 30 days)
   - Collect initial feedback
   - Make quick adjustments if needed

### Template Update Process

1. **Change Request** - Anyone can suggest changes via:
   - Comment on the template page
   - Jira ticket tagged `template-change`
   - Direct message to template owner

2. **Assessment** - Owner evaluates:
   - Impact on existing documents using this template
   - Alignment with organizational standards
   - Effort required for update

3. **Implementation** - Owner or steward:
   - Makes changes in a draft version
   - Reviews with 1-2 frequent users
   - Updates version number and changelog
   - Publishes updated template

4. **Communication** - Notify users:
   - Post update in relevant Slack/Teams channel
   - Update Template Index page
   - Send email for major changes

## Change Management

### Impact Categories

**Low Impact (Owner decides):**
- Typo fixes and formatting improvements
- Clarifying existing instructions
- Adding optional sections

**Medium Impact (Owner + 1 reviewer):**
- Adding new required sections
- Changing variable names or structure
- Updating macro usage

**High Impact (Committee review):**
- Removing sections from widely-used templates
- Merging or splitting templates
- Changing organizational template standards

### Communication Plan

| Change Type | Communication | Timeline |
|------------|---------------|----------|
| Low impact | Changelog update | Same day |
| Medium impact | Team channel announcement | 1 week notice |
| High impact | Email + meeting + migration guide | 2-4 weeks notice |

## Deprecation Process

### When to Deprecate
- Template replaced by a better alternative
- Process the template supports has been retired
- Template has zero usage in the past 6 months
- Template is redundant with another active template

### Deprecation Steps

1. **Decision** - Owner proposes deprecation with justification
2. **Announcement** - Notify users 30 days before deprecation:
   - Mark template with "DEPRECATED" status
   - Add deprecation notice at top of template
   - Point to replacement template (if applicable)
3. **Transition Period** - 30 days:
   - Template still available but marked deprecated
   - New documents should use replacement
   - Existing documents do not need to change
4. **Archive** - After transition:
   - Move template to Archive section
   - Remove from active template list
   - Keep accessible for historical reference
5. **Review** - 90 days after archive:
   - Confirm no active usage
   - Add to annual cleanup list if truly unused

## Usage Tracking

### Metrics & Thresholds

| Metric | Healthy | Flagged | Deprecate |
|--------|---------|---------|-----------|
| Pages created/month | >10 | 3-10 | <3 for 2 consecutive quarters |
| Unique users/month | >5 | 2-5 | 0-1 for 90 days |
| Section deletion rate | <10% | 10-30% | >30% (users removing sections = template mismatch) |
| Time to first use (new templates) | <7 days | 7-30 days | >30 days (failed launch, re-announce or rethink) |

### Tracking via CQL

```
-- Monthly usage for a specific template
type = page AND label = "template-sprint-retro" AND created >= "now-30d"

-- Stale templates (no usage in 90 days)
type = page AND label IN ("template-sprint-retro", "template-decision-log") AND created < "now-90d" AND created >= "now-91d"

-- All template-created pages for audit
type = page AND label = "template-*" ORDER BY created DESC
```

### Reporting
- **Monthly:** Top 10 templates by usage → auto-generated Confluence table
- **Quarterly:** Flag templates below thresholds → owner action required within 14 days
- **Annually:** Full catalog review — archive anything with 0 uses in 6 months

## Quality Standards

### Content Checklist (pass/fail per template)
- [ ] Every section has placeholder text showing expected content (not just a heading)
- [ ] No section references a process, tool, or team that no longer exists
- [ ] All Jira macro JQL filters return results (test quarterly)
- [ ] Links to other Confluence pages resolve (no 404s)
- [ ] Template renders correctly in both desktop and mobile preview

**FAIL examples:** Template says "Update the JIRA board" but team uses Linear. Template has a "QA Sign-Off" section but team has no QA role. Placeholder text says "TODO: add content here" with no guidance on what content.

### Structural Checklist
- [ ] Metadata header: owner name, version (semver), status (`active`/`deprecated`/`draft`), last-reviewed date
- [ ] Table of Contents macro if template has 4+ sections
- [ ] Change History table at bottom (date, author, change description)
- [ ] Placeholder text uses `{placeholder}` syntax or ac:placeholder macro — visually distinct from real content

### Maintenance Triggers
- Template not reviewed in 90+ days → owner gets Jira ticket auto-created via automation
- 3+ unresolved feedback items → escalate to committee
- Broken macro detected → owner notified same day via Slack/email automation

## Review Cadence

### Quarterly Review (Template Owner)
- Review usage metrics
- Address pending feedback
- Update content for accuracy
- Verify all links and macros work
- Update version number if changed

### Semi-Annual Review (Template Committee)
- Review full template catalog
- Identify gaps (missing templates)
- Identify overlaps (duplicate templates)
- Evaluate template standards compliance
- Plan improvements for next half

### Annual Review (Leadership — 60 min meeting)

**Agenda:**
1. (10 min) Catalog stats: total templates, usage trend YoY, templates added/deprecated
2. (15 min) Top 5 templates by adoption — what makes them work
3. (15 min) Bottom 5 templates — deprecate, rework, or retrain?
4. (10 min) Gaps identified by teams — templates requested but not yet built
5. (10 min) Governance process retro — is the framework itself working? Adjust thresholds, roles, or cadence as needed

**Deliverable:** Updated Template Health page published within 1 week of meeting

## Getting Started

### For New Organizations
1. Start with 5-10 essential templates (meeting notes, decision record, project plan)
2. Assign owners for each template
3. Establish basic quality standards
4. Review after 90 days and expand
5. Formalize governance as template count grows beyond 20

```

### references/template-design-patterns.md

```markdown
# Template Design Patterns

## Overview

Well-designed Confluence and Jira templates accelerate team productivity by providing consistent starting points for common documents and workflows. This guide covers design patterns, variable handling, and best practices for creating reusable templates.

## Variable Placeholders

### Confluence Template Variables

**Syntax:** `<at:var at:name="variableName">default value</at:var>`

**Common Variables:**
| Variable | Purpose | Example Default |
|----------|---------|----------------|
| `projectName` | Project identifier | "Project Name" |
| `author` | Document author | "@mention author" |
| `date` | Creation or target date | "YYYY-MM-DD" |
| `status` | Current document status | "Draft" |
| `version` | Document version | "1.0" |
| `owner` | Responsible person | "@mention owner" |
| `reviewers` | Review participants | "@mention reviewers" |

**Best Practices:**
- Use descriptive variable names (camelCase)
- Always provide meaningful default values
- Group related variables together
- Include instruction text that users should replace
- Use Status macro for status variables (visual clarity)

### Jira Template Fields

**Custom Fields for Templates:**
- Text fields for structured input
- Select lists for controlled vocabularies
- Date fields for milestones
- User pickers for assignments
- Labels for categorization

## Conditional Sections

### Pattern: Role-Based Sections

Include or exclude content based on the document's audience:

```
## For Engineering (delete if not applicable)
- Technical requirements
- Architecture decisions
- Performance criteria

## For Design (delete if not applicable)
- User flows
- Wireframes
- Accessibility requirements

## For Business (delete if not applicable)
- ROI analysis
- Market context
- Success metrics
```

### Pattern: Complexity-Based Sections

Scale content depth based on project size:

```
## Required for All Projects
- Problem statement
- Solution overview
- Success metrics

## Required for Medium+ Projects (>2 weeks)
- Detailed requirements
- Technical design
- Test plan

## Required for Large Projects (>1 month)
- Architecture review
- Security review
- Rollback plan
- Communication plan
```

### Pattern: Optional Deep Dives

Use Expand macros for optional detail:

```
[Expand: Detailed Requirements]
  Content that power users may need but casual readers can skip
[/Expand]
```

## Reusable Components

### Header Block
Every template should start with a consistent header:

```
| Field | Value |
|-------|-------|
| Author | @mention |
| Status | [Status Macro: Draft] |
| Created | [Date] |
| Last Updated | [Date] |
| Reviewers | @mention |
| Approver | @mention |
```

### Decision Log Component
Reusable across templates that involve decisions:

```
## Decision Log
| # | Decision | Date | Decided By | Rationale |
|---|----------|------|-----------|-----------|
| 1 | [Decision] | [Date] | [Name] | [Why] |
```

### Change History Component
Track document evolution:

```
## Change History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | [Date] | [Name] | Initial version |
```

### Action Items Component
Standard task tracking:

```
## Action Items
- [ ] [Task description] - @assignee - Due: [date]
- [ ] [Task description] - @assignee - Due: [date]
```

## Macro Integration

### Recommended Macros per Template Type

**Meeting Notes Template:**
- Table of Contents (for long meetings)
- Action Items (task list macro)
- Jira Issues (link to discussed tickets)
- Expand (for detailed discussion notes)

**Decision Record Template:**
- Status macro (decision status)
- Page Properties (structured metadata)
- Info/Warning panels (context and caveats)
- Jira Issues (related tickets)

**Project Plan Template:**
- Roadmap Planner (timeline view)
- Jira Issues (JQL for project epics)
- Children Display (sub-pages for phases)
- Chart macro (status distribution)

**Runbook Template:**
- Code Block (commands and scripts)
- Warning panels (danger zones)
- Expand (detailed troubleshooting)
- Anchor links (quick navigation)

## Responsive Layouts

### Two-Column Layout
Use Confluence Section and Column macros:

```
[Section]
  [Column: 60%]
    Main content, description, details
  [/Column]
  [Column: 40%]
    Sidebar: metadata, quick links, status
  [/Column]
[/Section]
```

### Card Layout
For overview pages with multiple items:

```
[Section]
  [Column: 33%]
    [Panel: Card 1]
      Title, summary, link
    [/Panel]
  [/Column]
  [Column: 33%]
    [Panel: Card 2]
  [/Column]
  [Column: 33%]
    [Panel: Card 3]
  [/Column]
[/Section]
```

## Brand Consistency

### Visual Standards
- Use consistent heading levels (H1 for title, H2 for sections, H3 for subsections)
- Apply Info/Warning/Note panels consistently (same meaning across templates)
- Use Status macro colors consistently (Green=done, Yellow=in progress, Red=blocked)
- Maintain consistent table formatting (header row, alignment)

### Content Standards
- Use the same voice and tone across templates
- Standardize date format (YYYY-MM-DD or your organization's preference)
- Use consistent terminology (define terms in a glossary)
- Include the same footer/metadata block in all templates

## Versioning Strategy

### Template Version Control
- Include version number in template metadata
- Maintain a changelog for template updates
- Communicate template changes to users
- Keep previous versions accessible during transition periods

### Version Numbering
- **Major (2.0):** Structural changes, section additions/removals
- **Minor (1.1):** Content updates, improved instructions
- **Patch (1.0.1):** Typo fixes, formatting corrections

### Migration Path
When updating templates:
1. Create new version alongside old version
2. Announce change with migration guide
3. New documents use new template automatically
4. Existing documents do not need to be migrated (optional)
5. Deprecate old template after 90 days
6. Archive old template (do not delete)

## Template Catalog Organization

### Categorization
Organize templates by:
- **Document type:** Meeting notes, decisions, plans, runbooks
- **Team:** Engineering, product, marketing, HR
- **Lifecycle:** Planning, execution, review, retrospective
- **Frequency:** One-time, recurring, as-needed

### Discovery
- Maintain a "Template Index" page with descriptions and links
- Tag templates with consistent labels
- Include a "When to Use" section in each template
- Provide examples of completed documents using the template

```

### scripts/template_scaffolder.py

```python
#!/usr/bin/env python3
"""
Template Scaffolder

Generates Confluence page template markup in storage-format XHTML. Supports
built-in template types and custom section definitions with optional macros.

Usage:
    python template_scaffolder.py meeting-notes
    python template_scaffolder.py decision-log --format json
    python template_scaffolder.py custom --sections "Overview,Goals,Action Items" --macros toc,status
    python template_scaffolder.py --list
"""

import argparse
import json
import sys
from datetime import datetime
from typing import Any, Dict, List, Optional


# ---------------------------------------------------------------------------
# Macro Generators
# ---------------------------------------------------------------------------

def macro_toc() -> str:
    """Generate table of contents macro."""
    return '<ac:structured-macro ac:name="toc"><ac:parameter ac:name="printable">true</ac:parameter><ac:parameter ac:name="style">disc</ac:parameter><ac:parameter ac:name="maxLevel">3</ac:parameter></ac:structured-macro>'


def macro_status(text: str = "IN PROGRESS", color: str = "Yellow") -> str:
    """Generate status macro."""
    return f'<ac:structured-macro ac:name="status"><ac:parameter ac:name="colour">{color}</ac:parameter><ac:parameter ac:name="title">{text}</ac:parameter></ac:structured-macro>'


def macro_info_panel(content: str) -> str:
    """Generate info panel macro."""
    return f'<ac:structured-macro ac:name="info"><ac:rich-text-body><p>{content}</p></ac:rich-text-body></ac:structured-macro>'


def macro_warning_panel(content: str) -> str:
    """Generate warning panel macro."""
    return f'<ac:structured-macro ac:name="warning"><ac:rich-text-body><p>{content}</p></ac:rich-text-body></ac:structured-macro>'


def macro_note_panel(content: str) -> str:
    """Generate note panel macro."""
    return f'<ac:structured-macro ac:name="note"><ac:rich-text-body><p>{content}</p></ac:rich-text-body></ac:structured-macro>'


def macro_expand(title: str, content: str) -> str:
    """Generate expand/collapse macro."""
    return f'<ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">{title}</ac:parameter><ac:rich-text-body>{content}</ac:rich-text-body></ac:structured-macro>'


def macro_jira_issues(jql: str) -> str:
    """Generate Jira issues macro."""
    return f'<ac:structured-macro ac:name="jira"><ac:parameter ac:name="jqlQuery">{jql}</ac:parameter><ac:parameter ac:name="columns">key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution</ac:parameter></ac:structured-macro>'


MACRO_MAP = {
    "toc": macro_toc,
    "status": macro_status,
    "info": macro_info_panel,
    "warning": macro_warning_panel,
    "note": macro_note_panel,
    "expand": macro_expand,
    "jira-issues": macro_jira_issues,
}


# ---------------------------------------------------------------------------
# Built-in Templates
# ---------------------------------------------------------------------------

def _section(title: str, content: str) -> str:
    """Generate a section with heading and content."""
    return f'<h2>{title}</h2>\n{content}\n'


def _table(headers: List[str], rows: List[List[str]]) -> str:
    """Generate an XHTML table."""
    parts = ['<table><colgroup>']
    for _ in headers:
        parts.append('<col />')
    parts.append('</colgroup><thead><tr>')
    for h in headers:
        parts.append(f'<th><p>{h}</p></th>')
    parts.append('</tr></thead><tbody>')
    for row in rows:
        parts.append('<tr>')
        for cell in row:
            parts.append(f'<td><p>{cell}</p></td>')
        parts.append('</tr>')
    parts.append('</tbody></table>')
    return ''.join(parts)


def template_meeting_notes() -> Dict[str, Any]:
    """Generate meeting notes template."""
    today = datetime.now().strftime("%Y-%m-%d")
    body = macro_toc() + '\n'
    body += macro_info_panel("Replace placeholder text with your meeting details.") + '\n'
    body += _section("Meeting Details", _table(
        ["Field", "Value"],
        [["Date", today], ["Time", ""], ["Location", ""], ["Facilitator", ""], ["Note Taker", ""]],
    ))
    body += _section("Attendees", '<ul><li><p>Name 1</p></li><li><p>Name 2</p></li></ul>')
    body += _section("Agenda", '<ol><li><p>Item 1</p></li><li><p>Item 2</p></li><li><p>Item 3</p></li></ol>')
    body += _section("Discussion Notes", '<p>Summary of discussion points...</p>')
    body += _section("Decisions Made", _table(
        ["Decision", "Owner", "Date"],
        [["", "", today]],
    ))
    body += _section("Action Items", _table(
        ["Action", "Owner", "Due Date", "Status"],
        [["", "", "", macro_status("TODO", "Grey")]],
    ))
    body += _section("Next Meeting", '<p>Date: TBD</p><p>Agenda items for next time:</p><ul><li><p></p></li></ul>')

    return {"name": "Meeting Notes", "body": body, "labels": ["meeting-notes", "template"]}


def template_decision_log() -> Dict[str, Any]:
    """Generate decision log template."""
    today = datetime.now().strftime("%Y-%m-%d")
    body = macro_toc() + '\n'
    body += _section("Decision Log", macro_info_panel("Track key decisions, context, and outcomes."))
    body += _table(
        ["ID", "Date", "Decision", "Context", "Alternatives Considered", "Outcome", "Owner", "Status"],
        [
            ["D-001", today, "", "", "", "", "", macro_status("DECIDED", "Green")],
            ["D-002", "", "", "", "", "", "", macro_status("PENDING", "Yellow")],
        ],
    )
    body += '\n'
    body += _section("Decision Template", macro_expand("Decision Details Template",
        '<h3>Context</h3><p>What is the issue or situation requiring a decision?</p>'
        '<h3>Options</h3><ol><li><p>Option A - pros/cons</p></li><li><p>Option B - pros/cons</p></li></ol>'
        '<h3>Decision</h3><p>What was decided and why?</p>'
        '<h3>Consequences</h3><p>What are the expected outcomes?</p>'
    ))

    return {"name": "Decision Log", "body": body, "labels": ["decision-log", "template"]}


def template_runbook() -> Dict[str, Any]:
    """Generate runbook template."""
    body = macro_toc() + '\n'
    body += macro_warning_panel("This runbook should be tested and reviewed quarterly.") + '\n'
    body += _section("Overview", '<p>Brief description of what this runbook covers.</p>'
        + _table(["Field", "Value"], [
            ["Service/System", ""], ["Owner", ""], ["Last Tested", ""],
            ["Severity", ""], ["Estimated Duration", ""],
        ]))
    body += _section("Prerequisites", '<ul><li><p>Access to system X</p></li><li><p>VPN connected</p></li><li><p>Required tools installed</p></li></ul>')
    body += _section("Steps", '<ol><li><p><strong>Step 1:</strong> Description</p><ac:structured-macro ac:name="code"><ac:parameter ac:name="language">bash</ac:parameter><ac:plain-text-body><![CDATA[# command here]]></ac:plain-text-body></ac:structured-macro></li>'
        '<li><p><strong>Step 2:</strong> Description</p></li>'
        '<li><p><strong>Step 3:</strong> Description</p></li></ol>')
    body += _section("Verification", '<p>How to verify the issue is resolved:</p><ul><li><p>Check 1</p></li><li><p>Check 2</p></li></ul>')
    body += _section("Rollback", macro_note_panel("If the above steps do not resolve the issue, follow these rollback steps.") +
        '<ol><li><p>Rollback step 1</p></li><li><p>Rollback step 2</p></li></ol>')
    body += _section("Escalation", _table(
        ["Level", "Contact", "When to Escalate"],
        [["L1", "", ""], ["L2", "", ""], ["L3", "", ""]],
    ))

    return {"name": "Runbook", "body": body, "labels": ["runbook", "operations", "template"]}


def template_project_kickoff() -> Dict[str, Any]:
    """Generate project kickoff template."""
    today = datetime.now().strftime("%Y-%m-%d")
    body = macro_toc() + '\n'
    body += _section("Project Overview", _table(
        ["Field", "Value"],
        [["Project Name", ""], ["Start Date", today], ["Target End Date", ""],
         ["Project Lead", ""], ["Sponsor", ""], ["Status", macro_status("KICKOFF", "Blue")]],
    ))
    body += _section("Vision & Goals", '<h3>Vision</h3><p>What does success look like?</p>'
        '<h3>Goals</h3><ol><li><p>Goal 1</p></li><li><p>Goal 2</p></li><li><p>Goal 3</p></li></ol>')
    body += _section("Scope", '<h3>In Scope</h3><ul><li><p></p></li></ul><h3>Out of Scope</h3><ul><li><p></p></li></ul>')
    body += _section("Stakeholders", _table(
        ["Name", "Role", "Responsibility", "Communication Preference"],
        [["", "", "", ""]],
    ))
    body += _section("Timeline & Milestones", _table(
        ["Milestone", "Target Date", "Status"],
        [["Phase 1", "", macro_status("NOT STARTED", "Grey")],
         ["Phase 2", "", macro_status("NOT STARTED", "Grey")]],
    ))
    body += _section("Risks", _table(
        ["Risk", "Likelihood", "Impact", "Mitigation"],
        [["", "High/Medium/Low", "High/Medium/Low", ""]],
    ))
    body += _section("Next Steps", '<ul><li><p></p></li></ul>')

    return {"name": "Project Kickoff", "body": body, "labels": ["project-kickoff", "template"]}


def template_sprint_retro() -> Dict[str, Any]:
    """Generate sprint retrospective template."""
    body = macro_toc() + '\n'
    body += _section("Sprint Info", _table(
        ["Field", "Value"],
        [["Sprint", ""], ["Date Range", ""], ["Facilitator", ""],
         ["Velocity", ""], ["Commitment", ""], ["Completion Rate", ""]],
    ))
    body += _section("What Went Well", '<ul><li><p></p></li></ul>')
    body += _section("What Could Be Improved", '<ul><li><p></p></li></ul>')
    body += _section("Action Items from Last Retro", _table(
        ["Action", "Owner", "Status"],
        [["", "", macro_status("DONE", "Green")], ["", "", macro_status("IN PROGRESS", "Yellow")]],
    ))
    body += _section("New Action Items", _table(
        ["Action", "Owner", "Due Date", "Priority"],
        [["", "", "", "High/Medium/Low"]],
    ))
    body += _section("Team Health Check", macro_info_panel("Rate each area 1-5 (1=needs work, 5=great)") + _table(
        ["Area", "Rating", "Trend", "Notes"],
        [["Teamwork", "", "", ""], ["Delivery", "", "", ""],
         ["Fun", "", "", ""], ["Learning", "", "", ""]],
    ))

    return {"name": "Sprint Retrospective", "body": body, "labels": ["sprint-retro", "agile", "template"]}


def template_how_to_guide() -> Dict[str, Any]:
    """Generate how-to guide template."""
    body = macro_toc() + '\n'
    body += macro_info_panel("This guide explains how to accomplish a specific task.") + '\n'
    body += _section("Overview", '<p>Brief description of what this guide covers and who it is for.</p>')
    body += _section("Prerequisites", '<ul><li><p>Prerequisite 1</p></li><li><p>Prerequisite 2</p></li></ul>')
    body += _section("Step-by-Step Instructions",
        '<h3>Step 1: Title</h3><p>Description of what to do.</p>'
        '<h3>Step 2: Title</h3><p>Description of what to do.</p>'
        '<h3>Step 3: Title</h3><p>Description of what to do.</p>')
    body += _section("Troubleshooting", macro_expand("Common Issues",
        '<h3>Issue 1</h3><p>Solution...</p>'
        '<h3>Issue 2</h3><p>Solution...</p>'))
    body += _section("Related Resources", '<ul><li><p>Link 1</p></li><li><p>Link 2</p></li></ul>')

    return {"name": "How-To Guide", "body": body, "labels": ["how-to", "guide", "template"]}


TEMPLATE_REGISTRY = {
    "meeting-notes": template_meeting_notes,
    "decision-log": template_decision_log,
    "runbook": template_runbook,
    "project-kickoff": template_project_kickoff,
    "sprint-retro": template_sprint_retro,
    "how-to-guide": template_how_to_guide,
}


# ---------------------------------------------------------------------------
# Custom Template Builder
# ---------------------------------------------------------------------------

def build_custom_template(
    sections: List[str],
    macros: List[str],
) -> Dict[str, Any]:
    """Build a custom template from sections and macros."""
    body = ""

    # Add requested macros at the top
    if "toc" in macros:
        body += macro_toc() + '\n'
    if "status" in macros:
        body += '<p>Status: ' + macro_status() + '</p>\n'

    for section in sections:
        section = section.strip()
        if not section:
            continue
        body += _section(section, '<p></p>')

    # Add panels if requested
    if "info" in macros:
        body = macro_info_panel("Add instructions or context here.") + '\n' + body
    if "warning" in macros:
        body += macro_warning_panel("Add warnings here.") + '\n'
    if "note" in macros:
        body += macro_note_panel("Add notes here.") + '\n'

    return {"name": "Custom Template", "body": body, "labels": ["custom", "template"]}


# ---------------------------------------------------------------------------
# Output Formatting
# ---------------------------------------------------------------------------

def format_text_output(result: Dict[str, Any]) -> str:
    """Format results as readable text report."""
    lines = []
    lines.append("=" * 60)
    lines.append(f"TEMPLATE: {result['name']}")
    lines.append("=" * 60)
    lines.append("")
    lines.append(f"Labels: {', '.join(result.get('labels', []))}")
    lines.append("")
    lines.append("CONFLUENCE STORAGE FORMAT MARKUP")
    lines.append("-" * 30)
    lines.append(result["body"])

    return "\n".join(lines)


def format_json_output(result: Dict[str, Any]) -> Dict[str, Any]:
    """Format results as JSON."""
    return result


def format_list_output(output_format: str) -> str:
    """Format available templates list."""
    if output_format == "json":
        templates = {}
        for name, func in TEMPLATE_REGISTRY.items():
            result = func()
            templates[name] = {
                "name": result["name"],
                "labels": result["labels"],
            }
        return json.dumps(templates, indent=2)

    lines = []
    lines.append("=" * 60)
    lines.append("AVAILABLE TEMPLATES")
    lines.append("=" * 60)
    lines.append("")
    for name, func in TEMPLATE_REGISTRY.items():
        result = func()
        lines.append(f"  {name}")
        lines.append(f"    Name: {result['name']}")
        lines.append(f"    Labels: {', '.join(result['labels'])}")
        lines.append("")
    lines.append(f"Total templates: {len(TEMPLATE_REGISTRY)}")
    lines.append("")
    lines.append("Usage:")
    lines.append("  python template_scaffolder.py <template-name>")
    lines.append('  python template_scaffolder.py custom --sections "Section1,Section2" --macros toc,status')
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# CLI Interface
# ---------------------------------------------------------------------------

def main() -> int:
    """Main CLI entry point."""
    parser = argparse.ArgumentParser(
        description="Generate Confluence page template markup"
    )
    parser.add_argument(
        "template",
        nargs="?",
        help="Template name or 'custom' for custom template",
    )
    parser.add_argument(
        "--format",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)",
    )
    parser.add_argument(
        "--list",
        action="store_true",
        help="List all available template types",
    )
    parser.add_argument(
        "--sections",
        help='Comma-separated section names for custom template (e.g., "Overview,Goals,Action Items")',
    )
    parser.add_argument(
        "--macros",
        help='Comma-separated macro names to include (e.g., "toc,status,info")',
    )

    args = parser.parse_args()

    try:
        if args.list:
            print(format_list_output(args.format))
            return 0

        if not args.template:
            parser.error("template name is required unless --list is used")

        template_name = args.template.lower()

        if template_name == "custom":
            if not args.sections:
                parser.error("--sections is required for custom templates")
            sections = [s.strip() for s in args.sections.split(",")]
            macros = [m.strip() for m in args.macros.split(",")] if args.macros else []
            result = build_custom_template(sections, macros)
        elif template_name in TEMPLATE_REGISTRY:
            result = TEMPLATE_REGISTRY[template_name]()
        else:
            available = ", ".join(sorted(TEMPLATE_REGISTRY.keys()))
            print(f"Error: Unknown template '{template_name}'. Available: {available}", file=sys.stderr)
            return 1

        if args.format == "json":
            print(json.dumps(format_json_output(result), indent=2))
        else:
            print(format_text_output(result))

        return 0

    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())

```