claude-code-arcane 1.0.0

package/skills/confluence-expert/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: confluence-expert
+description: "Atlassian Confluence expert for creating and managing spaces, knowledge bases, documentation, page hierarchies, templates, macros, and content governance."
+argument-hint: ""
+category: "agile"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Atlassian Confluence Expert
+
+Master-level expertise in Confluence space management, documentation architecture, content creation, macros, templates, and collaborative knowledge management.
+
+## Atlassian MCP Integration
+
+**Primary Tool**: Confluence MCP Server
+
+**Key Operations**:
+```
+create_space({ key: "TEAM", name: "Engineering Team", description: "Engineering team knowledge base" })
+create_page({ spaceKey: "TEAM", title: "Sprint 42 Notes", parentId: "123456", body: "<p>...</p>" })
+update_page({ pageId: "789012", version: 4, body: "<p>Updated content</p>" })
+delete_page({ pageId: "789012" })
+search({ cql: 'space = "TEAM" AND label = "meeting-notes" ORDER BY lastModified DESC' })
+```
+
+## Workflows
+
+### Space Creation
+1. Determine space type (Team, Project, Knowledge Base, Personal)
+2. Create space with clear name and description
+3. Set space homepage with overview
+4. Configure space permissions (View, Edit, Create, Delete, Admin)
+5. Create initial page tree structure
+6. Add space shortcuts for navigation
+7. **Verify**: Navigate to the space URL and confirm homepage loads; check non-admin permissions
+8. **HANDOFF TO**: Teams for content population
+
+### Page Architecture
+**Best Practices**: Use page hierarchy (parent-child), maximum 3 levels deep, consistent naming, date-stamp meeting notes.
+
+**Recommended Structure**:
+```
+Space Home
+├── Overview & Getting Started
+├── Team Information
+├── Projects
+│   ├── Project A (Overview, Requirements, Meeting Notes)
+│   └── Project B
+├── Processes & Workflows
+├── Meeting Notes (Archive)
+└── Resources & References
+```
+
+### Template Creation
+1. Identify repeatable content pattern
+2. Create page with structure and placeholders
+3. Format with appropriate macros
+4. Save as template, share with space or make global
+5. **Verify**: Create test page from template and confirm all placeholders render correctly
+
+### Documentation Strategy
+1. **Assess** current documentation state
+2. **Define** goals and audience
+3. **Organize** content taxonomy and structure
+4. **Create** templates and guidelines
+5. **Migrate** existing documentation
+6. **Monitor** usage and adoption
+7. **REPORT TO**: Senior PM on documentation health
+
+## Essential Macros
+
+> See references/macro-cheat-sheet.md for full macro reference with all parameters.
+
+**Content**: `{info}`, `{note}`, `{warning}`, `{tip}`, `{expand}`, `{toc:maxLevel=3}`, `{excerpt}`, `{excerpt-include:Page Name}`
+
+**Dynamic**: `{jira:JQL=...}`, `{jirachart:type=pie|jql=...}`, `{recently-updated}`, `{contentbylabel}`
+
+**Collaboration**: `{status:colour=Green|title=Approved}`, `{tasks}`, `@username`, `{date}`
+
+**Layout**: `{section}{column:width=50%}...{column}{section}`, `{panel:title=...}`, `{code:javascript}`
+
+## Templates Library
+
+> See references/templates.md for complete template library with full markup.
+
+| Template | Purpose | Key Sections |
+|----------|---------|--------------|
+| **Meeting Notes** | Sprint/team meetings | Agenda, Discussion, Decisions, Action Items |
+| **Project Overview** | Project kickoff & status | Quick Facts, Objectives, Stakeholders, Milestones, Risks |
+| **Decision Log** | Architectural/strategic decisions | Context, Options, Decision, Consequences, Next Steps |
+| **Sprint Retrospective** | Agile ceremony docs | What Went Well, What Didn't, Action Items, Metrics |
+
+## Space Permissions
+
+> See references/space-architecture-patterns.md for permission scheme details and architecture patterns.
+
+- **Public Space**: All users View, team members Edit/Create, space admins Admin
+- **Team Space**: Team members View/Edit/Create, team leads Admin, others no access
+- **Project Space**: Stakeholders View, project team Edit/Create, PM Admin
+
+## Content Governance
+
+**Review Cycles**: Critical docs monthly, standard quarterly, archive annually.
+**Archiving**: Move to Archive space, label with "archived" + date, maintain 2 years then delete.
+
+**Quality Checklist**: Clear title, owner identified, last updated date visible, appropriate labels, links functional, formatting consistent, no sensitive data exposed.
+
+## Decision Framework
+
+- **Escalate to Atlassian Admin**: Org-wide templates, cross-space permissions, blueprint config, global automation
+- **Collaborate with Jira Expert**: Embed Jira queries/charts, link pages to issues, Jira-based reports
+- **Support Scrum Master**: Sprint docs, retrospective pages, team working agreements, process docs
+- **Support Senior PM**: Executive reports, portfolio docs, stakeholder communication, strategic planning
+
+## Handoff Protocols
+
+**FROM Senior PM**: Documentation requirements, space structure needs, knowledge management strategy
+**TO Senior PM**: Documentation coverage reports, content usage analytics, knowledge gaps, template adoption
+
+**FROM Scrum Master**: Sprint ceremony templates, team documentation needs, meeting notes structure
+**TO Scrum Master**: Configured templates, space for team docs, training on best practices
+
+**WITH Jira Expert**: Jira-Confluence linking, embedded reports, issue-to-page connections
+
+## Analytics & Metrics
+
+- **Usage**: Page views per space, most visited pages, search queries, contributor activity, orphaned pages
+- **Health**: Pages without recent updates, pages without owners, duplicate content, broken links, empty spaces

package/skills/confluence-expert/references/macro-cheat-sheet.md

@@ -0,0 +1,144 @@
+# Confluence Macro Cheat Sheet
+
+## Overview
+
+Quick reference for the most commonly used Confluence macros. Each entry includes the macro name, storage format syntax, primary use case, and practical tips.
+
+## Navigation & Structure Macros
+
+### Table of Contents
+- **Purpose:** Auto-generate a linked table of contents from page headings
+- **Syntax:** `<ac:structured-macro ac:name="toc" />`
+- **Parameters:** `maxLevel` (1-6), `minLevel` (1-6), `style` (disc, circle, square, none), `type` (list, flat)
+- **Use case:** Long documentation pages, meeting notes, specifications
+- **Tip:** Set `maxLevel="3"` to avoid overly deep TOC entries
+
+### Children Display
+- **Purpose:** List child pages of the current page
+- **Syntax:** `<ac:structured-macro ac:name="children" />`
+- **Parameters:** `depth` (1-999), `sort` (title, creation, modified), `style` (h2-h6), `all` (true/false)
+- **Use case:** Parent hub pages, project homepages, documentation indexes
+- **Tip:** Use `depth="1"` for clean navigation, `all="true"` for deep hierarchies
+
+### Include Page
+- **Purpose:** Embed content from another page inline
+- **Syntax:** `<ac:structured-macro ac:name="include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Page Name" /></ac:link></ac:parameter></ac:structured-macro>`
+- **Use case:** Reusable content blocks (headers, footers, disclaimers)
+- **Tip:** Changes to the source page are reflected everywhere it is included
+
+### Page Properties
+- **Purpose:** Define structured metadata on a page (key-value pairs)
+- **Syntax:** `<ac:structured-macro ac:name="details">` with table inside
+- **Use case:** Project metadata, status tracking, structured page data
+- **Tip:** Combine with Page Properties Report macro to create dashboards
+
+### Page Properties Report
+- **Purpose:** Display a table of Page Properties from child pages
+- **Syntax:** `<ac:structured-macro ac:name="detailssummary" />`
+- **Parameters:** `cql` (CQL filter), `labels` (filter by label)
+- **Use case:** Project dashboards, status rollups, portfolio views
+- **Tip:** Use labels to scope the report to relevant pages only
+
+## Visual & Formatting Macros
+
+### Info Panel
+- **Purpose:** Blue information callout box
+- **Syntax:** `<ac:structured-macro ac:name="info"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
+- **Use case:** Helpful notes, additional context, best practices
+
+### Warning Panel
+- **Purpose:** Yellow warning callout box
+- **Syntax:** `<ac:structured-macro ac:name="warning"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
+- **Use case:** Important caveats, deprecation notices, breaking changes
+
+### Note Panel
+- **Purpose:** Yellow note callout box
+- **Syntax:** `<ac:structured-macro ac:name="note"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
+- **Use case:** Reminders, action items, things to watch
+
+### Tip Panel
+- **Purpose:** Green tip callout box
+- **Syntax:** `<ac:structured-macro ac:name="tip"><ac:rich-text-body>Content</ac:rich-text-body></ac:structured-macro>`
+- **Use case:** Pro tips, shortcuts, recommended approaches
+
+### Expand
+- **Purpose:** Collapsible content section (click to expand)
+- **Syntax:** `<ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">Click to expand</ac:parameter><ac:rich-text-body>Hidden content</ac:rich-text-body></ac:structured-macro>`
+- **Use case:** Long sections, FAQs, detailed explanations, optional reading
+- **Tip:** Use for content that not all readers need
+
+### Status
+- **Purpose:** Colored status lozenge (inline label)
+- **Syntax:** `<ac:structured-macro ac:name="status"><ac:parameter ac:name="colour">Green</ac:parameter><ac:parameter ac:name="title">DONE</ac:parameter></ac:structured-macro>`
+- **Colors:** Grey, Red, Yellow, Green, Blue
+- **Use case:** Task status, review state, approval status
+- **Tip:** Standardize status values across your team (e.g., TODO, IN PROGRESS, DONE)
+
+## Integration Macros
+
+### Jira Issues
+- **Purpose:** Display Jira issues or JQL query results
+- **Syntax:** `<ac:structured-macro ac:name="jira"><ac:parameter ac:name="jqlQuery">project = PROJ AND status = Open</ac:parameter></ac:structured-macro>`
+- **Parameters:** `jqlQuery`, `columns` (key, summary, status, assignee, etc.), `count` (true/false), `serverId`
+- **Use case:** Sprint boards in documentation, requirement traceability, release notes
+- **Tip:** Use `columns` parameter to show only relevant fields
+
+### Roadmap Planner
+- **Purpose:** Visual timeline/Gantt view of items
+- **Syntax:** Available via macro browser (Roadmap Planner)
+- **Use case:** Project timelines, release planning, milestone tracking
+- **Tip:** Link roadmap items to Jira epics for automatic status updates
+
+### Chart Macro
+- **Purpose:** Create charts from table data on the page
+- **Syntax:** `<ac:structured-macro ac:name="chart"><ac:parameter ac:name="type">pie</ac:parameter><ac:rich-text-body>Table data</ac:rich-text-body></ac:structured-macro>`
+- **Types:** pie, bar, line, area, scatter, timeSeries
+- **Use case:** Status distribution, metrics dashboards, trend visualization
+- **Tip:** Place a Confluence table inside the macro body as data source
+
+## Content Reuse Macros
+
+### Excerpt
+- **Purpose:** Mark a section of content for reuse via Excerpt Include
+- **Syntax:** `<ac:structured-macro ac:name="excerpt"><ac:rich-text-body>Reusable content</ac:rich-text-body></ac:structured-macro>`
+- **Use case:** Define canonical content blocks (product descriptions, team info)
+
+### Excerpt Include
+- **Purpose:** Display an Excerpt from another page
+- **Syntax:** `<ac:structured-macro ac:name="excerpt-include"><ac:parameter ac:name=""><ac:link><ri:page ri:content-title="Source Page" /></ac:link></ac:parameter></ac:structured-macro>`
+- **Use case:** Embed product descriptions, standard disclaimers, shared definitions
+
+## Advanced Macros
+
+### Code Block
+- **Purpose:** Display formatted code with syntax highlighting
+- **Syntax:** `<ac:structured-macro ac:name="code"><ac:parameter ac:name="language">python</ac:parameter><ac:plain-text-body>code here</ac:plain-text-body></ac:structured-macro>`
+- **Languages:** java, python, javascript, sql, bash, xml, json, and many more
+- **Use case:** API documentation, configuration examples, code snippets
+
+### Anchor
+- **Purpose:** Create a named anchor point for deep linking
+- **Syntax:** `<ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">anchor-name</ac:parameter></ac:structured-macro>`
+- **Use case:** Link directly to specific sections within long pages
+- **Tip:** Use with TOC macro for custom navigation
+
+### Recently Updated
+- **Purpose:** Show recently modified pages in a space
+- **Syntax:** `<ac:structured-macro ac:name="recently-updated" />`
+- **Parameters:** `spaces`, `labels`, `types`, `max`
+- **Use case:** Team dashboards, space homepages, activity feeds
+
+## Macro Selection Guide
+
+| Need | Recommended Macro |
+|------|------------------|
+| Page navigation | Table of Contents |
+| List child pages | Children Display |
+| Reuse content | Include Page or Excerpt Include |
+| Status tracking | Status + Page Properties |
+| Project dashboard | Page Properties Report |
+| Hide optional content | Expand |
+| Show Jira data | Jira Issues |
+| Visualize data | Chart |
+| Code documentation | Code Block |
+| Important callouts | Info/Warning/Note/Tip panels |

package/skills/confluence-expert/references/space-architecture-patterns.md

@@ -0,0 +1,246 @@
+# Confluence Space Architecture Patterns
+
+## Overview
+
+Well-organized Confluence spaces dramatically improve information discoverability and team productivity. This guide covers proven space organization patterns, page hierarchy best practices, and governance strategies.
+
+## Space Organization Patterns
+
+### Pattern 1: By Team
+
+Each team or department gets its own space.
+
+**Structure:**
+```
+Engineering Space (ENG)
+Product Space (PROD)
+Marketing Space (MKT)
+Design Space (DES)
+Support Space (SUP)
+```
+
+**Pros:**
+- Clear ownership and permissions
+- Teams control their own content
+- Natural permission boundaries
+- Easy to find team-specific content
+
+**Cons:**
+- Cross-team content duplication
+- Silos between departments
+- Hard to find project-spanning information
+- Inconsistent practices across spaces
+
+**Best for:** Organizations with stable teams and clear departmental boundaries
+
+### Pattern 2: By Project
+
+Each major project or product gets its own space.
+
+**Structure:**
+```
+Project Alpha Space (ALPHA)
+Project Beta Space (BETA)
+Platform Infrastructure Space (PLAT)
+Internal Tools Space (TOOLS)
+```
+
+**Pros:**
+- All project context in one place
+- Easy onboarding for project members
+- Clean archival when project completes
+- Natural lifecycle management
+
+**Cons:**
+- Team knowledge scattered across spaces
+- Permission management per project
+- Space proliferation over time
+- Ongoing vs project work separation unclear
+
+**Best for:** Project-based organizations, agencies, consulting firms
+
+### Pattern 3: By Domain (Hybrid)
+
+Combine functional spaces with cross-cutting project spaces.
+
+**Structure:**
+```
+Company Wiki (WIKI) - Shared knowledge
+Engineering Standards (ENG) - Team practices
+Product Specs (PROD) - Requirements and roadmap
+Project Alpha (ALPHA) - Cross-team project
+Project Beta (BETA) - Cross-team project
+Archive (ARCH) - Completed projects
+```
+
+**Pros:**
+- Balances team and project needs
+- Shared knowledge has a home
+- Clear archival path
+- Scales with organization growth
+
+**Cons:**
+- More complex to set up initially
+- Requires governance to maintain
+- Some ambiguity about where content belongs
+
+**Best for:** Growing organizations, 50-500 people, multiple concurrent projects
+
+## Page Hierarchy Best Practices
+
+### Recommended Depth
+- **Maximum 4 levels deep** - Deeper hierarchies become hard to navigate
+- **3 levels ideal** for most content types
+- Use flat structures with labels for categorization beyond 4 levels
+
+### Standard Page Hierarchy
+
+```
+Space Home (overview, quick links, recent updates)
+├── Getting Started
+│   ├── Onboarding Guide
+│   ├── Tool Setup
+│   └── Key Contacts
+├── Projects
+│   ├── Project Alpha
+│   │   ├── Requirements
+│   │   ├── Design
+│   │   └── Meeting Notes
+│   └── Project Beta
+├── Processes
+│   ├── Development Workflow
+│   ├── Release Process
+│   └── On-Call Runbook
+├── References
+│   ├── Architecture Decisions
+│   ├── API Documentation
+│   └── Glossary
+└── Archive
+    ├── 2025 Projects
+    └── Deprecated Processes
+```
+
+### Page Naming Conventions
+- Use clear, descriptive titles (not abbreviations)
+- Include date for time-sensitive content: "2025-Q1 Planning"
+- Prefix meeting notes with date: "2025-03-15 Sprint Review"
+- Use consistent casing (Title Case or Sentence case, not both)
+- Avoid special characters that break URLs
+
+### Space Homepage Design
+Every space homepage should include:
+1. **Space purpose** - One paragraph describing what this space is for
+2. **Quick links** - 5-7 most accessed pages
+3. **Recent updates** - Recently Updated macro filtered to this space
+4. **Getting started** - Link to onboarding content for new members
+5. **Contact info** - Space owner, key contributors
+
+## Labeling Taxonomy
+
+### Label Categories
+- **Content type:** `meeting-notes`, `decision`, `specification`, `runbook`, `retrospective`
+- **Status:** `draft`, `in-review`, `approved`, `deprecated`, `archived`
+- **Team:** `team-engineering`, `team-product`, `team-design`
+- **Project:** `project-alpha`, `project-beta`
+- **Priority:** `high-priority`, `p1`, `critical`
+
+### Labeling Best Practices
+- Use lowercase, hyphenated labels (no spaces or camelCase)
+- Define a standard label vocabulary and document it
+- Use labels for cross-space categorization
+- Combine labels with CQL for powerful search and reporting
+- Audit labels quarterly to remove unused or inconsistent labels
+- Limit to 3-5 labels per page (over-labeling reduces value)
+
+### CQL Examples for Label-Based Queries
+```
+# All meeting notes in a space
+type = page AND space = "ENG" AND label = "meeting-notes"
+
+# All approved specifications
+type = page AND label = "specification" AND label = "approved"
+
+# Recent decisions across all spaces
+type = page AND label = "decision" AND lastModified > now("-30d")
+```
+
+## Cross-Space Linking
+
+### When to Link vs Duplicate
+- **Link** when content has a single source of truth
+- **Duplicate** (Include Page macro) when content must appear in multiple contexts
+- **Excerpt Include** when only a portion of a page is needed elsewhere
+
+### Linking Best Practices
+- Use full page titles in links for clarity
+- Add context around links ("See the [Architecture Decision Record] for rationale")
+- Avoid orphan pages - every page should be reachable from space navigation
+- Use the Recently Updated macro on hub pages for activity visibility
+- Create "Related Pages" sections at the bottom of content pages
+
+## Archive Strategy
+
+### When to Archive
+- Project completed more than 90 days ago
+- Process or document officially deprecated
+- Content not updated in 12+ months
+- Replaced by newer content
+
+### Archive Process
+1. Add `archived` label to the page
+2. Move to Archive section within the space (or dedicated Archive space)
+3. Add a note at the top: "This page is archived as of [date]. See [replacement] for current information."
+4. Update any incoming links to point to current content
+5. Do NOT delete - archived content has historical value
+
+### Archive Space Pattern
+- Create a dedicated `Archive` space for completed projects
+- Move entire project page trees to Archive space on completion
+- Set Archive space to read-only permissions
+- Review Archive space annually for content that can be deleted
+
+## Permission Inheritance Patterns
+
+### Pattern 1: Open by Default
+- All spaces readable by all employees
+- Edit restricted to space members
+- Admin restricted to space owners
+- **Best for:** Transparency-focused organizations
+
+### Pattern 2: Restricted by Default
+- Spaces accessible only to specific groups
+- Request access via space admin
+- **Best for:** Regulated industries, confidential projects
+
+### Pattern 3: Tiered Access
+- Public tier: Company wiki, shared processes
+- Team tier: Team-specific spaces with team access
+- Restricted tier: HR, finance, legal with limited access
+- **Best for:** Most organizations (balanced approach)
+
+### Permission Tips
+- Use Confluence groups, not individual users, for permissions
+- Align groups with LDAP/SSO groups where possible
+- Audit permissions quarterly
+- Document permission model on the space homepage
+- Use page-level restrictions sparingly (breaks inheritance, hard to audit)
+
+## Scaling Considerations
+
+### < 50 People
+- 3-5 spaces total
+- Simple by-team pattern
+- Light governance
+
+### 50-200 People
+- 10-20 spaces
+- Hybrid pattern (team + project)
+- Formal labeling taxonomy
+- Quarterly content reviews
+
+### 200+ People
+- 20-50+ spaces
+- Full domain pattern with governance
+- Space owners and content stewards
+- Automated archival policies
+- Regular information architecture reviews