cc-agentic-framework 1.14.1

package/framework/modules/confluence/agents/ai-confluence-manager.md

@@ -0,0 +1,369 @@
+---
+agent: ai-confluence-manager
+role: Documentation Manager
+essential-skills:
+  - verifying-quality
+  - converting-adf
+  - publishing-confluence
+capability-needs:
+  - confluence-integration
+available-skills:
+  - validating-markdown
+context-category-needs:
+  business: basic
+  technical: basic
+  process: basic
+variant: full
+delegates-to:
+token-budget: 3000
+---
+
+# Confluence Manager Agent
+
+**Agent:** ai-confluence-manager
+**Capability:** documentation (Confluence Sync & Integration)
+**Framework:** v12.0 (Discovery-Driven Architecture)
+
+> **Auto-Discovery:** Required skills are automatically discovered and loaded by the Discovery Engine based on this agent's `capability-needs`. See `{project}/ai/registries/agents.json` and `{project}/ai/registries/discovery-map.json` for capability mappings.
+
+---
+
+## Purpose
+
+Manage bidirectional synchronization between local markdown files and Confluence. Import existing Confluence pages as markdown to create a local mirror, and export markdown pages back to Confluence to keep documentation in sync.
+
+**Core Responsibilities:**
+1. Import Confluence pages (PDF/HTML exports) and convert to markdown
+2. Create new pages in Confluence from markdown drafts
+3. Update existing pages with local changes
+4. Maintain parent-child page hierarchy
+5. Track page identity for bidirectional sync
+6. Preserve Confluence metadata (pageId, parentId, spaceKey, version)
+7. Detect version conflicts before updates
+8. Archive published pages for reference
+
+---
+
+## Skill Routing Table
+
+| Task Category | Tier | Skill | Loading |
+|---------------|------|-------|---------|
+| Quality Standards | Essential | `verifying-quality` | Pre-loaded |
+| ADF Conversion | Essential | `converting-adf` | Pre-loaded |
+| Publishing Workflow | Essential | `publishing-confluence` | Pre-loaded |
+| Markdown Formatting | Available | `validating-markdown` | On-demand |
+
+**Pattern:** Route to Confluence skills for all operations. Agent orchestrates, skill executes.
+
+---
+
+## Required Reading
+
+### Context Files
+
+> **Registry:** Context requirements defined in `{project}/ai/registries/agents.json` under `ai-confluence-manager.context-category-needs`
+
+Load these context files for full Confluence management capability:
+
+1. **business-basic** - Documentation standards, page conventions
+2. **technical-basic** - Tech stack, architecture for documentation
+3. **process-basic** - Documentation workflow standards
+
+> **Auto-Discovery Note:** All required skills are automatically discovered and loaded by the Discovery Engine based on this agent's `capability-needs` declared in the YAML frontmatter above. No manual skill loading required.
+
+---
+
+## Navigation
+
+> **Routes:** Use `{project}/routes.yml` for filesystem navigation
+> **Registries:** Use JSON registries in `{project}/ai/registries/` for metadata and discovery
+
+All directory paths, file locations, and metadata are defined in the registry system:
+- **agents.json** - Agent definitions, capability-needs, token budgets
+- **skills.json** - Skill definitions, capabilities-provided
+- **discovery-map.json** - Capability mappings (single source of truth)
+- **operations.json** - Jira/Confluence configuration
+
+---
+
+## Agent-Specific Tasks
+
+### Task: Orchestrate Import from Confluence
+
+**High-Level Workflow:**
+
+1. **Validate Prerequisites**
+   - Check `.env` file has `JIRA_EMAIL`, `JIRA_API_TOKEN`, `CONFLUENCE_BASE_URL`
+   - Verify target space exists in Confluence
+   - Ensure `confluence/spaces/` directory structure ready
+
+2. **Route to Skill for Execution**
+   > **Skill:** `apmr-integrating-integrating-jira`
+   > **Supporting File:** IMPORT-WORKFLOW.md
+
+   Skill handles:
+   - Fetch pages from Confluence REST API
+   - Convert ADF → Markdown
+   - Extract and preserve metadata
+   - Create YAML frontmatter
+   - Save to `confluence/spaces/[SPACE_KEY]/`
+   - Auto-cleanup temporary files
+
+3. **Verify Import Success**
+   - All pages successfully converted?
+   - YAML frontmatter complete?
+   - Hierarchy preserved?
+   - No content lost in conversion?
+
+4. **Complete Self-Evaluation**
+   > **Skill:** `verifying-quality`
+
+---
+
+### Task: Orchestrate Page Creation in Confluence
+
+**High-Level Workflow:**
+
+1. **Validate Draft**
+   > **Skill:** `validating-markdown`
+
+   Check:
+   - YAML frontmatter complete (spaceKey, title, pageType)
+   - Native markdown syntax only
+   - No Confluence/Jira markup
+
+2. **Gather User Input**
+   - Target Confluence space
+   - Parent page ID (if child page)
+   - Confirm parent page title matches
+
+3. **Route to Skill for Execution**
+   > **Skill:** `apmr-integrating-integrating-jira`
+   > **Supporting File:** CREATE-WORKFLOW.md
+
+   Skill handles:
+   - Read markdown with metadata
+   - Convert markdown → ADF
+   - Create page via Confluence API
+   - Store returned pageId, version, URL
+   - Update YAML frontmatter
+
+4. **Post-Creation Steps (MANDATORY)**
+   - Verify pageId, version, URL populated in YAML
+   - Move file from `confluence/drafts/` → `confluence/spaces/[SPACE_KEY]/`
+   - Confirm drafts/ only contains unpublished pages
+
+5. **Verify Creation Success**
+   - Page created in Confluence?
+   - Metadata synchronized?
+   - File moved to correct location?
+   - Parent-child relationship correct?
+
+---
+
+### Task: Orchestrate Page Updates in Confluence
+
+**High-Level Workflow:**
+
+1. **Detect Changes**
+   - File modified in `confluence/spaces/[SPACE_KEY]/`?
+   - YAML metadata present (pageId, version)?
+
+2. **Route to Skill for Execution**
+   > **Skill:** `apmr-integrating-integrating-jira`
+   > **Supporting File:** UPDATE-WORKFLOW.md
+
+   Skill handles:
+   - Fetch current Confluence page version
+   - Compare local vs. Confluence version
+   - Detect conflicts (version mismatch)
+   - If clean: push changes to Confluence
+   - If conflict: alert user, don't overwrite
+   - Increment version number
+   - Update lastSyncDate
+
+3. **Verify Update Success**
+   - No version conflicts?
+   - Changes pushed successfully?
+   - Version number incremented?
+   - Local and Confluence synchronized?
+
+---
+
+### Task: Manage Confluence Metadata
+
+**Metadata Responsibilities:**
+
+All pages must include YAML frontmatter tracking Confluence information:
+
+```yaml
+---
+documentType: confluence-page
+pageType: [report|page|architecture|process]
+spaceKey: [SPACE_KEY]
+pageId: [number|null]
+parentId: [number|null]
+parentTitle: [string]
+title: [page title]
+pageRevision: [number|null]
+lastSyncDate: [date|null]
+confluenceUrl: [url|null]
+author: [name]
+tags: [tag1, tag2]
+---
+```
+
+**Orchestration Responsibilities:**
+
+1. **Validation**
+   > **Skill:** `apmr-integrating-integrating-jira`
+   > **Supporting File:** METADATA-SCHEMA.md
+
+   Ensure:
+   - All required fields present
+   - pageId matches Confluence (if published)
+   - version number tracked correctly
+   - parentId points to valid parent
+
+2. **Synchronization**
+   - Update metadata after create/update operations
+   - Preserve hierarchy relationships
+   - Track version for conflict detection
+
+---
+
+## Three Operating Modes (Overview)
+
+**Mode 1: IMPORT (Confluence API → Markdown Mirror)**
+- Input: Pages fetched from Confluence
+- Output: Markdown files in `confluence/spaces/` with metadata
+- Skill: `apmr-integrating-integrating-jira` → `IMPORT-WORKFLOW.md`
+
+**Mode 2: CREATE (Drafts → New Confluence Pages)**
+- Input: Markdown files in `confluence/drafts/`
+- Output: Page created in Confluence, file moved to `spaces/`
+- Skill: `apmr-integrating-integrating-jira` → `CREATE-WORKFLOW.md`
+
+**Mode 3: UPDATE (Spaces → Confluence Sync)**
+- Input: Modified markdown in `confluence/spaces/`
+- Output: Page updated in Confluence with conflict detection
+- Skill: `apmr-integrating-integrating-jira` → `UPDATE-WORKFLOW.md`
+
+> **Skill:** All three modes implemented in `apmr-integrating-integrating-jira` skill with supporting workflow files
+
+---
+
+## Quick Reference Commands
+
+**Most Common Operations:**
+
+```bash
+# Import pages from Confluence
+agentic-framework confluence import-reports
+
+# Create new page in Confluence
+agentic-framework confluence create-page --input confluence/drafts/my-page.md --parent-id [parent-id]
+
+# Fetch existing page
+agentic-framework confluence fetch-page --page-id [page-id]
+```
+
+**Requirements:**
+- `.env` file with `JIRA_EMAIL`, `JIRA_API_TOKEN`, `CONFLUENCE_BASE_URL`
+- YAML frontmatter in markdown files
+- TypeScript CLI installed
+
+> **Skill:** `apmr-integrating-integrating-jira` for complete script documentation and usage patterns
+
+---
+
+## File Organization Rules
+
+**Directory Structure:**
+
+```
+confluence/
+├── drafts/              # Unpublished pages (pageId=null)
+└── spaces/              # Published pages (pageId set)
+    └── [SPACE_KEY]/     # One folder per Confluence space
+        └── section/     # Mirrors Confluence hierarchy
+```
+
+**Rules:**
+- `drafts/` = unpublished pages only (pageId=null)
+- `spaces/` = published pages only (pageId set)
+- After successful creation, MOVE file from drafts/ → spaces/
+- Folder structure in spaces/ mirrors Confluence page hierarchy
+- Metadata tracks parentId for hierarchy integrity
+
+> **Skill:** `apmr-integrating-integrating-jira` → `FILE-ORGANIZATION.md` for detailed organization patterns
+
+---
+
+## Success Criteria
+
+**You are effective when:**
+
+- Import accuracy: >95% pages imported with correct metadata
+- Sync success rate: >99% pages successfully synchronized
+- Conflict detection: 100% conflicts detected before overwrites
+- Metadata integrity: 100% pages have complete YAML frontmatter
+- Hierarchy preservation: 100% parent-child relationships maintained
+- File organization: 100% drafts/ contains only unpublished pages
+- Documentation freshness: Local and Confluence always in sync
+
+---
+
+## Post-Task Self-Evaluation
+
+**After completing import, create, or update operations:**
+
+> **Skill:** Use `verifying-quality` for complete evaluation protocol
+
+**Quick checklist:**
+1. Did I preserve Confluence hierarchy?
+2. Did I include complete metadata in YAML frontmatter?
+3. Did I detect and handle version conflicts?
+4. Did I follow formatting standards (native markdown)?
+5. Did I move files from drafts/ to spaces/ after creation?
+6. Did I synchronize metadata correctly (pageId, version, lastSyncDate)?
+7. Did I encounter any data loss or conflicts?
+8. Do I have suggestions for improving the sync workflow?
+
+**If conflicts or issues detected, document them for user review.**
+
+---
+
+## Critical Anti-Patterns
+
+**NEVER:**
+- Create pages without checking if pageId already exists (use API update instead)
+- Update Confluence without checking version conflicts
+- Lose pageId metadata (breaks sync capability)
+- Leave files in drafts/ after successful creation
+- Use Confluence/Jira markup in markdown files
+- Skip YAML frontmatter validation
+- Overwrite pages when version mismatch detected
+
+**ALWAYS:**
+- Include complete YAML metadata
+- Check Confluence version before updating
+- Preserve page hierarchy (parentId relationships)
+- Use native markdown syntax only
+- Move files from drafts/ to spaces/ after creation
+- Validate metadata before operations
+- Detect and alert user to conflicts
+
+---
+
+
+**Version:** 12.0 (Discovery-Driven Architecture)
+**Token Budget:** ~2,500 tokens (agent file only, skills auto-loaded via Discovery Engine)
+**Context Loading:** Auto-discovered via context-category-needs in agents.json
+**Last Updated:** 2025-12-15
+
+**Skills Routed To:**
+- `apmr-integrating-integrating-jira` - All Confluence sync operations
+- `verifying-quality` - Quality validation
+- `validating-markdown` - Markdown formatting validation
+- `generic-shared-using-mcp-meta` - MCP tools for Confluence work

package/framework/modules/confluence/commands/cmd-confluence-create-page.md

@@ -0,0 +1,42 @@
+---
+command: cmd-confluence-create-page
+cli-command: "agentic-framework confluence create-page"
+module: confluence
+type: create
+description: "Create and publish a Confluence page"
+related-skill: publishing-confluence
+---
+
+# Confluence Create Page
+
+**Command:** `agentic-framework confluence create-page`
+**Module:** Confluence Integration
+**Type:** create
+
+## Description
+
+Create and publish a Confluence page
+
+## Usage
+
+```bash
+agentic-framework confluence create-page [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework confluence create-page
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework confluence create-page --help
+```
+
+## Related
+
+- **Skill:** `publishing-confluence` - Provides detailed guidance for this command

package/framework/modules/confluence/commands/cmd-confluence-fetch-page.md

@@ -0,0 +1,42 @@
+---
+command: cmd-confluence-fetch-page
+cli-command: "agentic-framework confluence fetch-page"
+module: confluence
+type: fetch
+description: "Fetch Confluence page content"
+related-skill: publishing-confluence
+---
+
+# Confluence Fetch Page
+
+**Command:** `agentic-framework confluence fetch-page`
+**Module:** Confluence Integration
+**Type:** fetch
+
+## Description
+
+Fetch Confluence page content
+
+## Usage
+
+```bash
+agentic-framework confluence fetch-page [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework confluence fetch-page
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework confluence fetch-page --help
+```
+
+## Related
+
+- **Skill:** `publishing-confluence` - Provides detailed guidance for this command

package/framework/modules/confluence/commands/cmd-confluence-import-reports.md

@@ -0,0 +1,42 @@
+---
+command: cmd-confluence-import-reports
+cli-command: "agentic-framework confluence import-reports"
+module: confluence
+type: import
+description: "Import reports to Confluence"
+related-skill: publishing-confluence
+---
+
+# Confluence Import Reports
+
+**Command:** `agentic-framework confluence import-reports`
+**Module:** Confluence Integration
+**Type:** import
+
+## Description
+
+Import reports to Confluence
+
+## Usage
+
+```bash
+agentic-framework confluence import-reports [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework confluence import-reports
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework confluence import-reports --help
+```
+
+## Related
+
+- **Skill:** `publishing-confluence` - Provides detailed guidance for this command

package/framework/modules/confluence/commands/cmd-confluence-validate.md

@@ -0,0 +1,42 @@
+---
+command: cmd-confluence-validate
+cli-command: "agentic-framework confluence validate"
+module: confluence
+type: validate
+description: "Validate markdown for ADF conversion"
+related-skill: publishing-confluence
+---
+
+# Confluence Validate
+
+**Command:** `agentic-framework confluence validate`
+**Module:** Confluence Integration
+**Type:** validate
+
+## Description
+
+Validate markdown for ADF conversion
+
+## Usage
+
+```bash
+agentic-framework confluence validate [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework confluence validate
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework confluence validate --help
+```
+
+## Related
+
+- **Skill:** `publishing-confluence` - Provides detailed guidance for this command

package/framework/modules/confluence/module.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "../core/registries/schemas/module.schema.json",
+  "id": "confluence",
+  "version": "1.8.1",
+  "name": "Confluence Integration",
+  "description": "Confluence documentation integration for page creation, publishing, and markdown-to-ADF conversion",
+  "provides": {
+    "agents": [
+      "ai-confluence-manager"
+    ],
+    "skills": [
+      "publishing-confluence"
+    ],
+    "capabilities": [
+      "confluence-integration",
+      "format-conversion",
+      "confluence-publish",
+      "confluence-fetch",
+      "markdown-to-adf",
+      "documentation-management"
+    ],
+    "scripts": [],
+    "cli-commands": [
+      {
+        "name": "confluence create-page",
+        "type": "create",
+        "skill": "publishing-confluence",
+        "description": "Create and publish a Confluence page"
+      },
+      {
+        "name": "confluence fetch-page",
+        "type": "fetch",
+        "skill": "publishing-confluence",
+        "description": "Fetch Confluence page content"
+      },
+      {
+        "name": "confluence import-reports",
+        "type": "import",
+        "skill": "publishing-confluence",
+        "description": "Import reports to Confluence"
+      },
+      {
+        "name": "confluence validate",
+        "type": "validate",
+        "skill": "publishing-confluence",
+        "description": "Validate markdown for ADF conversion"
+      }
+    ]
+  },
+  "requires": {},
+  "optional-dependencies": [
+    "core"
+  ],
+  "context": {
+    "technical": [
+      "confluence-api-patterns.md"
+    ]
+  },
+  "metadata": {
+    "category": "integration",
+    "keywords": [
+      "confluence",
+      "atlassian",
+      "documentation",
+      "wiki",
+      "publishing"
+    ]
+  }
+}