Confluence Space Manager

Confluence Space Manager

Role

You are responsible for the shape and discoverability of a solution's Confluence space. You do not author the content of architecture, specs, or sprint plans — those come from the architect, spec-author, and sprint-planner skills. You guarantee that:

• Every solution has a predictable top-level layout so collaborators know where

things live.

• New spaces start with the right scaffolding and the JIRA project-linker so

ticket integration is immediate.

• Mature spaces don't drift indefinitely — they are periodically audited

against the canon and re-aligned with explicit user approval.

You are platform-agnostic with respect to Solution / Pipeline / Agent / UI scope — the canonical structure flexes with optional sections per scope.

---

Operating Modes

The mode is named explicitly by the caller. Default to Audit if ambiguous — auditing is read-only and never destructive.

---

Inputs

• Cloud ID: c62e56c2-b224-4d4e-a859-afa7de01241e (Ontoledgy default —

override only for other tenants).

• Space key (e.g., TBMLI, SAA, SAKE/ACE). For Create mode, may be

TBD if a fresh space is being provisioned.

• JIRA project key (e.g., TI, TBMLI) — used for the project-linker

macro on the Overview page.

• Repo root — used to discover steering docs, releases, and specs that

should be reflected in the space scaffold.

• Solution scope (optional, one of: solution, pipeline, agent, ui,

bie, research-bid) — toggles optional sections (e.g., a research-bid space also gets a Proposal section, like ACE).

---

Outputs

---

Canonical Structure

The full canonical structure — including which sections are mandatory, which are scope-conditional, and the ownership of each section — lives in references/canonical-space-structure.md. Always read it before any mode runs. A summary is reproduced here so you can sanity-check at a glance:

{Space Homepage}                         ← project-linker, recently-updated, contributors
├── 01 Overview                          ← what the system does (narrative + diagram)
├── 02 Steering                          ← mirror of .claude/steering/ (product, tech, structure)
├── 03 Releases                          ← mirror of .claude/releases/ — one child per release
├── 04 Architecture                      ← Solution Architecture, Domain Ontology, per-component designs
├── 05 Specs                             ← mirror of .claude/specs/ — one child per feature
├── 06 Sprints                           ← sprint kick-offs and retrospectives
├── 07 Reviews                           ← Code Reviews and Architecture Reviews (date-stamped)
├── 08 Ontology                          ← first-class domain ontology pages (BORO + BIE)
├── 09 References                        ← external docs, related work, glossary, audit reports
├── 99 WIP                               ← scratch / drafts (not for canonical content)
└── (scope-conditional)
    ├── Proposal                         ← only when scope = research-bid
    └── Templates                        ← Confluence's auto-templates (Project plan, Decision, Meeting notes)

Section numbering keeps the order stable in the Confluence sidebar. Numbers are part of the canonical title and must be preserved by Audit/Align.

---

Workflow — Create Mode

Step 1 — Detect Existing State

• Confirm or fetch the space (mcp__atlassian__getConfluenceSpaces filtered by

keys). If the space does not exist, ask the user to provision it via the Confluence UI (the MCP cannot create spaces). Provide a one-line instruction and the recommended template (Project space).

• Read the homepage. If it already contains content, skip the homepage

rewrite and only add missing canonical sections. Never silently overwrite existing user content.

• Read repo .claude/steering/, .claude/releases/, .claude/specs/ if they

exist — used to seed sections 02, 03, 05.

Step 2 — Confirm Plan with User

Show a preview tree of what will be created (sections + first-level children seeded from repo metadata). Ask for approval. The user may opt out of any section. Gate: do not create anything until the plan is approved.

Step 3 — Create Sections

In order (01 → 99), use mcp__atlassian__createConfluencePage for each canonical section that is missing. For each:

• Title exactly as in the canonical structure (with the numeric prefix).
• Parent: the homepage (top-level sections) or the appropriate section page.
• Body: load from references/page-templates.md (one template per section

type). Templates contain placeholders that are filled from steering / release / spec metadata where available.

Step 4 — Wire JIRA Integration

If the homepage is freshly created, ensure it contains the com.atlassian.confluence.project-linker extension pointing at the JIRA project key. If the homepage pre-exists and lacks the linker, append a "Project Tracker" section with the linker rather than overwriting the page.

Step 5 — Persist Mapping

Write/update .claude/workflow-config.md with:

• confluence.cloudId
• confluence.spaceKey
• confluence.homepageId
• confluence.sections.{01-overview, 02-steering, ...} page IDs

This mapping is what product-vision-steering, release-planner, feature-spec-author, and software-architect use as the parent for their Confluence publications. Without it they fall back to asking the user.

Step 6 — Return

Report to caller: space URL, list of created sections (with IDs), warnings about pre-existing content not modified, and the path to the updated workflow-config.md.

---

Workflow — Audit Mode

Step 1 — Walk the Space

• Fetch the homepage and walk descendants 2 levels deep

(mcp__atlassian__getConfluencePageDescendants with depth=2).

• Build a tree of (title, id, parentId, position).

Step 2 — Compare Against Canon

Run the audit checklist in references/audit-checklist.md. For each canonical section, classify:

For each row, produce a recommended action: rename, move, create, archive, or accept (extra pages can be intentionally bespoke — never auto-archive).

Step 3 — Score

Compute a simple coverage score: present / (present + missing + misnamed + misplaced). This is informative only — used in the report header to track drift over time, not as a pass/fail gate.

Step 4 — Publish the Report

Write the report to .claude/confluence/{space-key}-audit-{YYYY-MM-DD}.md and also create/update a child page under 09 References titled Space Audit — {YYYY-MM-DD}. Ask the user to review and select which recommended actions to apply. Recommendations are presented as a checklist the user can edit.

Step 5 — Hand Off

Audit mode never modifies the space. End by asking the user whether to enter Align mode with the approved actions.

---

Workflow — Align Mode

Step 1 — Load Approved Actions

Read the audit report. Extract the approved action rows (those the user checked or otherwise confirmed).

Step 2 — Apply in Safe Order

Execute approved actions in this order to minimise transient broken links: 1. Create missing canonical sections (so child pages have a target to move into). 2. Rename misnamed pages (updateConfluencePage with new title — body unchanged). 3. Move misplaced pages (updateConfluencePage with new parentId). 4. Archive explicitly approved removals (set status, do not hard delete — audit trail matters).

After each operation, update the audit report's "Changelog" section with the operation, the page ID, and a timestamp.

Step 3 — Re-Audit

Re-run Audit Mode silently and confirm the coverage score improved. If any approved action failed, surface the failure to the user with the API error.

Step 4 — Return

Report to caller: changes applied (count by type), new coverage score, and audit report URL.

---

Boundaries — What This Skill Does NOT Do

• Does not author content for steering / specs / architecture pages —

those skills publish their own content under the canonical sections this skill provisions.

• Does not create JIRA epics, stories, or subtasks — that is

release-planner (epics) and backlog-manager (stories/subtasks).

• Does not provision new Confluence spaces — the Atlassian MCP cannot

create spaces. This skill scaffolds within a space the user has already created.

• Does not delete content — archive is the strongest action available, and

only when explicitly approved per page.

• Does not enforce content quality inside individual pages — that is the

responsibility of the publishing skill (software-architect, feature-spec-author, etc.). This skill enforces structure, not prose.

• Does not fork or template a new space from scratch — bootstrapping a

brand-new space is a follow-up skill (see Future Work).

---

Future Work — Space Template Skill

Once the canonical structure is stable across 3+ spaces, this skill's references/page-templates.md should be promoted to a standalone confluence-space-template artifact (a JSON or YAML manifest) that:

• Can be used by an external script to provision a new Confluence space

via the Atlassian REST API (the MCP doesn't currently support space creation).

• Powers a --bootstrap flag on this skill that wires the new space directly

to a freshly initialised repo.

This is explicitly out of scope for the first cut — the page-tree templates captured in references/page-templates.md are the precursor.

---

References

• references/canonical-space-structure.md — the canonical page tree, section

ownership, mandatory vs. scope-conditional sections, and naming rules.

• references/page-templates.md — body templates for each canonical section

(Overview, Steering, Releases, Architecture, Specs, Sprints, Reviews, Ontology, References, WIP).

• references/naming-conventions.md — title formats for design, review,

spec, and dated artefacts; numeric prefix rules; the per-host date-stamping convention observed in TBMLI and ACE.

• references/audit-checklist.md — the row-by-row checklist used in Audit

mode, plus the coverage score formula and severity ladder.

• references/reference-spaces.md — annotated tour of ACE (SAKE), TBMLI,

and SAA showing how each maps onto the canonical structure (gaps and all).

• Atlassian MCP tools: getConfluenceSpaces, getConfluencePage,

getConfluencePageDescendants, createConfluencePage, updateConfluencePage, searchConfluenceUsingCql.

• Companion skills: product-vision-steering (Phase 0),

release-planner (Phase 0.5), feature-spec-author (Phase 1), backlog-manager (Phase 2), software-architect (architecture pages).

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the `skill-feedback` skill to report it?" If the user declines, continue without feedback capture.

Audit Checklist

The row-by-row checklist used in Audit Mode. Each row evaluates one canonical aspect of the space and produces a finding with a severity and a recommended action.

---

Severity Ladder

Audit mode is non-blocking — it never refuses to publish. It produces a report; Align mode applies user-approved actions.

---

Coverage Score

coverage = present / (present + missing + misnamed + misplaced)

Calculated over the mandatory sections only (those marked ✅ Always in canonical-space-structure.md). Range: 0.0 – 1.0. Reported in the audit header as a percentage.

The score is informative — used to track drift over time across multiple audits of the same space, not as a gate.

---

Checklist Rows

Each row is structured as:

• What — the canonical thing being checked
• How — the API/MCP call or comparison performed
• Severity if absent or broken
• Recommended action when violated

Row A — Homepage Exists and Has JIRA Linker

• What: the space's homepage exists and contains a

com.atlassian.confluence.project-linker extension.

• How: getConfluencePage(homepageId); scan body.content for the

extension node.

• Severity if missing: critical (if a JIRA project is configured) or

medium (if no JIRA project — recommend setting one up).

• Recommended action: append a "Project Tracker" section with the

project-linker macro.

Row B — Homepage Has Activity Macros

• What: homepage contains recently-updated and contributors macros.
• How: scan body.content.
• Severity if missing: low.
• Recommended action: append the macros to the homepage.

Row C — Mandatory Sections Present

For each section marked ✅ Always in canonical-space-structure.md:

• What: a top-level child of the homepage exists with the canonical

title or an accepted variant.

• How: getConfluencePageDescendants(homepageId, depth=1); compare

titles.

• Severity if missing: critical for 01 Overview, 02 Steering,

04 Architecture, 09 References. high for 07 Reviews. medium otherwise.

• Recommended action: create the section using the appropriate

template from page-templates.md.

Row D — Section Titles Match Canonical Form

• What: each present section uses the canonical title (numeric prefix

+ Title Case).

• How: string compare against canonical title; if it matches an accepted

variant, classify as misnamed (low).

• Severity if violated: low.
• Recommended action: rename to canonical form.

Row E — Conditional Sections Match Scope

• What: if scope = research-bid, Proposal exists; if scope ≠

research-bid, Proposal is absent or moved to 99 WIP.

• How: scan top-level children for Proposal; check repo for scope

flag in .claude/workflow-config.md.

• Severity if mismatched: info (intentional choice possible).
• Recommended action: flag for user review; do not auto-act.

Row F — Steering Mirror Complete

• What: 02 Steering has three children: Product Vision,

Technology Stack, Project Structure (or accepted variants product.md / tech.md / structure.md titles).

• How: getConfluencePageDescendants(steeringPageId, depth=1).
• Severity if missing: medium if .claude/steering/ exists in repo;

info otherwise.

• Recommended action: create placeholders and route the user to

product-vision-steering to populate.

Row G — Releases Mirror Reflects Repo

• What: for each .claude/releases/{name}/ in the repo, a child page

named {name} exists under 03 Releases.

• How: read repo + getConfluencePageDescendants(releasesPageId).
• Severity if mismatched: medium (known release missing on

Confluence) or info (page exists with no repo backing — could be retired).

• Recommended action: create for missing; flag for review for

unbacked.

Row H — Specs Mirror Reflects Repo

• What: for each .claude/specs/{feature}/ in the repo, a child page

exists under 05 Specs with three grandchildren.

• How: read repo + descendants.
• Severity: medium if repo spec is missing on Confluence; info if

Confluence-only spec.

• Recommended action: create for missing.

Row I — Reviews Are Date-Stamped

• What: every page under 07 Reviews / Code Reviews follows the

date-stamped naming convention.

• How: descendants + regex ^.*\sReview\s-\s\d{4}-\d{2}-\d{2}.*$ or

similar.

• Severity if violated: low.
• Recommended action: rename (with user approval; some review pages

may legitimately summarise multiple dates).

Row J — No Mixed Em-dash/Hyphen in Titles

• What: titles use either em-dash or hyphen consistently within a

single title.

• How: regex on each title.
• Severity if violated: medium.
• Recommended action: rename to use the canonical separator

(— for Component — Aspect, - for Ontology - Domain).

Row K — Forbidden Patterns Absent

• What: no titles contain trailing whitespace, double spaces,

non-ISO dates, or all-caps section names.

• How: regex sweep across all titles.
• Severity if violated: medium.
• Recommended action: rename.

Row L — Numeric Prefix Adoption

• What: top-level sections use the NN prefix.
• How: regex ^\d{2}\s on top-level child titles.
• Severity if absent: low.
• Recommended action: batch rename proposal — present all top-level

sections together so the user can approve in one pass.

Row M — Extra Top-Level Pages

• What: any top-level page that does not match a canonical section or

an accepted variant.

• How: subtract canonical from descendants(depth=1).
• Severity: info.
• Recommended action: flag for review with three options:
• accept — page is intentional (default for research-bid spaces).
• move — relocate under a canonical section.
• archive — explicit removal (requires user confirmation).

Row N — Sprint Pages Under 06 Sprints

• What: sprint kick-off pages live under 06 Sprints, not under

Planning or Architecture.

• How: search for Sprint Planning / Sprint Kickoff titles

anywhere in the space; check parent.

• Severity if misplaced: medium.
• Recommended action: move to 06 Sprints.

Row O — Per-Component Architecture Pages Have Designs or Stubs

• What: each child of 04 Architecture / Components has either a

Design v{N} child or is explicitly marked as a stub.

• How: descendants(depth=2); check for child page matching design

pattern.

• Severity if missing: low (a component listed without a design is

an open task, not a structural error).

• Recommended action: create design placeholder; route user to the

appropriate architect skill.

Row P — Audit Reports Archived in 09 References

• What: prior audit reports exist under

09 References / Space Audits and are listed reverse-chronologically.

• How: descendants + title match.
• Severity if missing: info (first audit ever — expected).
• Recommended action: create the Space Audits parent and publish

the current report there.

---

Output — Audit Report Schema

The report is written to .claude/confluence/{space-key}-audit-{YYYY-MM-DD}.md and mirrored to Confluence under 09 References / Space Audits / {YYYY-MM-DD}.

Schema:

# Confluence Space Audit — {space-key} — {YYYY-MM-DD}

**Coverage:** {coverage}% ({present} of {total} mandatory sections present)
**Audited by:** confluence-space-manager
**Cloud ID:** {cloudId}
**Space ID / Key:** {spaceId} / {spaceKey}

## Summary

{N} critical, {N} high, {N} medium, {N} low, {N} info findings.

## Findings

| # | Row | What | Status | Severity | Recommended Action | Approve? |
|---|-----|------|--------|----------|-------------------|----------|
| 1 | A | Homepage JIRA linker | ❌ missing | critical | append project-linker macro | [ ] |
| 2 | C | `01 Overview` section | ❌ missing | critical | create with Overview template | [ ] |
| 3 | C | `02 Steering` section | ✅ present | — | — | n/a |
| 4 | D | `Architecture` (no prefix) | ⚠ misnamed | low | rename to `04 Architecture` | [ ] |
| ... |

## Changelog

(populated by Align mode)

| Timestamp | Action | Page | Result |
|-----------|--------|------|--------|

## Open Questions

- (Audit may surface ambiguities for human decision — list here.)

The Approve? column is the user's input — they tick the box ([x]) for each action they want Align mode to apply, then call Align mode against this file.

---

Notes on False Positives

Some real-world cases the checklist may flag but are intentional:

• ACE (`SAKE`) `Proposal` and `Scope - Requirement` — research-bid

scope; legitimate top-level pages. Audit should be invoked with scope: research-bid to suppress these as extra.

• TBMLI `Ontology - Addressess` — typo, but the page has accumulated

links. Rename only with explicit user approval; consider creating a redirect note on the renamed page.

• Reviews under `Architecture / Code Reviews` (SAA) — reviews nested

inside architecture is a valid alternative layout. The canonical form is 07 Reviews at top level; recommend move but accept keep if the user prefers the alternative.

Canonical Confluence Space Structure

This is the reference layout that every solution-specific Confluence space at Ontoledgy should converge on. It is derived from the most mature space (SAKE/ACE — Agentic Chemical Engineer), the JIRA-integrated mid-mature space (TBMLI), and the newest space (SAA — Solution - Agentic Accountant). See reference-spaces.md for an annotated tour of each.

The structure is opinionated but flexes per solution scope. Mandatory sections must be present in every space. Conditional sections are present only when the scope flag matches.

---

Top-Level Tree

{Space Homepage}
│  ├─ Description (one-paragraph product purpose)
│  ├─ Project Tracker (com.atlassian.confluence.project-linker macro)
│  ├─ Recently Updated (recently-updated macro)
│  └─ Contributors (contributors macro)
│
├── 01 Overview                          [mandatory]
├── 02 Steering                          [mandatory]
│   ├── Product Vision                   [mirror of .claude/steering/product.md]
│   ├── Technology Stack                 [mirror of .claude/steering/tech.md]
│   └── Project Structure                [mirror of .claude/steering/structure.md]
│
├── 03 Releases                          [mandatory once a release exists]
│   └── {release-name}                   [one per release; e.g., "MVP", "v1.0"]
│       ├── Release Plan                 [mirror of .claude/releases/{name}/features.md]
│       ├── Roadmap                      [scope tiers + dependency diagram]
│       └── Linked Epics                 [JIRA epic links + status]
│
├── 04 Architecture                      [mandatory]
│   ├── Solution Architecture            [high-level across the system]
│   ├── Architecture Principles          [optional but recommended]
│   ├── Domain Ontology                  [BORO-grounded; or link to 08]
│   ├── Components / Services            [one child page per component]
│   │   └── {Component Name}
│   │       ├── {Component} — Architecture Design v{N}
│   │       ├── {Component} — Architecture Review v{N}  [optional]
│   │       └── Implementation Path — {Component}        [optional]
│   ├── APIs, Interfaces and Deployment Model   [optional]
│   └── Tools, Compute and Environments         [optional]
│
├── 05 Specs                             [mandatory once specs exist]
│   └── {feature-name}                   [one per feature; mirror of .claude/specs/{feature}/]
│       ├── Requirements
│       ├── Design
│       └── Tasks                        [with linked JIRA tickets]
│
├── 06 Sprints                           [mandatory once a sprint exists]
│   └── Sprint {N} — {dates}             [kickoff + retro]
│
├── 07 Reviews                           [mandatory]
│   ├── Code Reviews                     [grouped by area: Pipelines, Frontend, General]
│   │   └── {Area or Component} — Review — {YYYY-MM-DD} {hostname}
│   └── Architecture Reviews             [optional sub-grouping; same date-stamp pattern]
│
├── 08 Ontology                          [mandatory if domain modelling is in scope]
│   └── {Domain} — {Aspect}              [e.g., "Ontology - Legal Entities"]
│
├── 09 References                        [mandatory]
│   ├── External References              [links to standards, papers, vendor docs]
│   ├── Glossary                         [optional]
│   └── Space Audits                     [audit reports created by this skill]
│
├── 99 WIP                               [optional but expected]
│   └── (free-form scratch / drafts)
│
├── Proposal                             [conditional — scope = research-bid]
│   ├── Public Description
│   ├── Scope
│   ├── Question 09–15 (or as defined by the funder)
│   └── Question 10 — Technical Approach
│
└── Templates                            [conditional — auto-created by Confluence]
    ├── Template - Project plan
    ├── Template - Decision documentation
    └── Template - Meeting notes

---

Section Ownership

Every canonical section has an owner skill — the skill responsible for publishing or updating its content. The Confluence Space Manager owns the shape (parent IDs, titles, ordering), not the content.

---

Mandatory vs. Conditional Sections

A space passes the audit's minimum viable structure check if all sections marked ✅ Always are present.

---

Numeric Prefix Convention

Top-level section titles begin with a two-digit numeric prefix (e.g., 01 Overview) so they render in the Confluence sidebar in a stable order. This is observed informally in some spaces and is now the canonical rule.

• Numbers are zero-padded to two digits (01–99).
• Numbers are spaced from the title with a single space.
• The number is part of the canonical title — Audit mode treats

Overview (no prefix) as misnamed, not missing.

• Existing spaces (ACE, TBMLI, SAA) use unprefixed titles. Audit mode

flags this as misnamed with severity low — adoption is gradual and user-approved.

---

Section-Title Variants — Acceptance Rules

Audit mode treats these variants as the same canonical section. Renaming is recommended (severity low) but not blocking.

Anything that doesn't match the canonical title or any accepted variant is classified as extra — flagged for human review, never auto-archived.

---

Examples — How Real Spaces Map

A short summary; full annotated tour in reference-spaces.md.

ACE (SAKE) — research-bid scope

TBMLI — solution scope, JIRA-integrated

SAA — solution scope, sparse

---

Why This Structure

1. Predictability. A new contributor to any space knows where to find architecture, releases, and reviews without orientation. 2. Tool alignment. The mirror sections (02 Steering, 03 Releases, 05 Specs, 06 Sprints) match the .claude/ repo layout so publishing skills know exactly where their output lands. 3. JIRA integration is first-class. The homepage's project-linker macro means tickets surface immediately rather than being buried. 4. Reviews are durable. Date-stamped review pages are append-only, preserving history rather than churning a single "Review" page. 5. Audit-ability. Numeric prefixes + acceptance rules make the audit deterministic and the gap report actionable.

---

Open Questions

• Should 08 Ontology be a child of 04 Architecture instead of a top-level

section? Pro: closer to where it is consumed. Con: ontologies are reused across architecture/specs/components and benefit from a dedicated home. Current decision: top-level, with a "see also" link from `04`.

• Should Proposal (research-bid) get a numeric prefix? **Current decision:

no — it sits outside the canonical numeric series because it is conditional and bespoke per funder.**

Naming Conventions

These rules cover both section titles (the canonical top-level pages) and artifact titles (designs, reviews, specs, sprints) — everything the Confluence Space Manager creates or audits.

---

Section Titles (Top-Level Pages)

Numeric-prefix format: {NN} {Section Name}.

• NN is a two-digit zero-padded integer (01–99).
• One space between NN and the section name.
• Section name uses Title Case.
• The numeric prefix is part of the title — Audit mode treats it as

significant.

Reserved numbers:

Numbers 10–98 are open for project-specific top-level sections (e.g., 50 Compliance for a regulated product). Audit mode flags unknown numbered sections as extra with severity info.

Conditional sections (no numeric prefix):

---

Artifact Titles

Architecture Designs

Format: {Component Name} — Architecture Design v{N}

• Em-dash (—, U+2014), surrounded by single spaces.
• Component Name in Title Case, no acronyms expanded unless ambiguous.
• v{N} is a sequential integer starting at 1. Increment on substantive

redesign, not minor edits.

Examples:

• Address Verification Services — Architecture Design v1
• Agent Harness — Design v2 (legacy variant — accepted, severity low)

Architecture Reviews

Two valid formats:

1. Versioned: {Component Name} — Architecture Review v{N} 2. Dated: {Component Name} — Architecture Review — {YYYY-MM-DD}

Dated form is preferred when the review is informal or AI-assisted (matches the Code Review pattern). Versioned form is preferred when the review formally accompanies a design version.

Examples:

• Agent Harness - Architecture Review (agent-architect) — accepted, low
• Trades Pipeline — Architecture Review 2026-04-04 — accepted (dated)

Code Reviews

Format: {Area or Component} — Review — {YYYY-MM-DD} {hostname-or-codename}

• The trailing host-or-codename token captures which agent / machine

produced the review (e.g., MAUDLIN, roy.corp.ontoledgy.io, poledouris, Boulez). It is observed informally in TBMLI and ACE and is now canonical.

• The host token is optional but recommended — it disambiguates

same-day reviews from different agents.

Examples:

• File System Snapshot Service - Review - 2026-03-24-2216 MAUDLIN
• Document Control Identity Service - Review - 2026-03-11-0813 roy.corp.ontoledgy.io
• Code Review - Services - 2026-04-03 (no host — accepted, info)

Implementation Plans

Format: Implementation Path — {Component Name} or: {Component Name} — Implementation Plan

Both are accepted. The first is observed in TBMLI, the second in earlier spaces. Audit mode does not flag either.

Feature Specs

Top-level child of 05 Specs: {feature-name} (kebab-case, no spaces).

Grandchildren (canonical):

• Requirements
• Design
• Tasks

These are mirrored from .claude/specs/{feature-name}/{requirements,design,tasks}.md.

Release Pages

Top-level child of 03 Releases: {Release Name} (free text — typically MVP, v1.0, Q2-2026).

Grandchildren:

• Release Plan
• Roadmap
• Linked Epics

Sprint Pages

Format: Sprint {N} — {start-date} → {end-date}

Example: Sprint 1 — 2026-04-14 → 2026-05-31

Optionally augment with the sprint theme: Sprint {N} — {dates} — {theme}.

Domain Ontology Pages

Under 08 Ontology: Ontology - {Domain} (note hyphen-with-spaces, not em-dash).

Examples:

• Ontology - Legal Entities
• Ontology - Trades
• Ontology - Addressess (sic — typo in TBMLI; flag in audit, severity low)

The hyphen-form is preserved for backwards compatibility with TBMLI; new spaces may use the em-dash form Ontology — {Domain} if preferred.

---

Casing & Punctuation Rules

---

Forbidden Patterns

These will be flagged by Audit mode at severity medium:

• Trailing whitespace in titles.
• Double spaces inside titles (e.g., Code Review - 2026-04-03).
• Mixed em-dash and hyphen in the same title (Component — Review - v1).
• Date in non-ISO format (24/03/2026, March 24 2026).
• All-caps section titles (ARCHITECTURE).

These will be flagged at severity low (correctable but not blocking):

• Missing numeric prefix on a top-level section.
• Hyphen used where em-dash is canonical (Component - Design v1).
• Inconsistent version capitalisation (V1 vs v1).
• Component name in lowercase (agent harness — design v1).

---

Migration Rules

When Audit mode flags a misnamed page:

1. Generate the canonical title. 2. Diff: present before/after. 3. Recommend rename action (severity low/medium). 4. Wait for user approval — never auto-rename. 5. On approval, updateConfluencePage with the new title (body unchanged).

Renames preserve the page ID and URL slug — the slug typically updates automatically but old URLs continue to resolve via Confluence's redirect.

Page Body Templates

Body templates for each canonical section. Each template lists:

• Purpose — what the page is for
• Variables — {{...}} placeholders filled from steering/release/spec metadata
• Body — Markdown body to publish (Atlassian MCP createConfluencePage

accepts Markdown for top-level body content; macros use ADF extension blocks documented inline)

When creating pages via mcp__atlassian__createConfluencePage, the API accepts plain Markdown for most content. For Confluence-specific macros (project linker, recently updated, contributors, table of contents), include them as embedded ADF extension blocks within the request body when the API surface supports it; otherwise, ask the user to add the macro manually after page creation. Always confirm placement of macros in the post-creation review.

---

Homepage Template

Purpose: the front door of the space — describes the product in one paragraph, surfaces the JIRA project, and shows recent activity.

Variables:

• {{project-name}} — full product name (from product.md)
• {{description}} — one-sentence purpose (from product.md)
• {{jira-project-key}} — e.g., TBMLI

Body:

## Description

{{description}}

## Project Tracker

> Macro: `com.atlassian.confluence.project-linker` — bound to JIRA project
> `{{jira-project-key}}`. If the macro is not pre-rendered by the API, ask
> the user to insert "Project linker" via the Confluence editor and select
> the project.

## Recently Updated

> Macro: `recently-updated` — types: page, whiteboard, database, blog;
> max=10; theme=concise; hideHeading=true.

## Contributors

> Macro: `contributors` — scope=descendants; limit=10.

---

## Quick Links

- [Steering](./02 Steering)
- [Releases](./03 Releases)
- [Architecture](./04 Architecture)
- [Specs](./05 Specs)
- [Reviews](./07 Reviews)

---

01 Overview Template

Purpose: narrative description of what the system does, who uses it, and the high-level architecture diagram. Stable — changes rarely.

Variables:

• {{product-name}}
• {{description}}
• {{primary-users}} — bullet list from product.md
• {{key-features}} — bullet list (top 3–5)
• {{system-diagram}} — ASCII or mermaid diagram

Body:

## What the System Does

{{description}}

The {{product-name}} automates and augments the work traditionally
performed by {{primary-users}} by:

{{key-features}}

## System Structure (At a Glance)

\`\`\`
{{system-diagram}}
\`\`\`

## What is Novel

(populated by the architect during high-level design — link to
`04 Architecture / Architecture Principles`)

## Documentation Structure

This space is organised as follows:

1. **[01 Overview](./01 Overview)** — this page
2. **[02 Steering](./02 Steering)** — product vision, tech stack, project structure
3. **[03 Releases](./03 Releases)** — release plans and roadmap
4. **[04 Architecture](./04 Architecture)** — system architecture and component designs
5. **[05 Specs](./05 Specs)** — feature specifications
6. **[06 Sprints](./06 Sprints)** — sprint kick-offs and retros
7. **[07 Reviews](./07 Reviews)** — code and architecture reviews
8. **[08 Ontology](./08 Ontology)** — domain models
9. **[09 References](./09 References)** — external references and glossary

---

02 Steering Template (parent page)

Purpose: holder for the three steering documents.

Body:

## Project Steering Documents

These three pages are mirrored from the repo's `.claude/steering/` directory.
They are the project's long-lived "constitution" — they change rarely and
intentionally.

| Document | Purpose | Last Updated |
|----------|---------|--------------|
| [Product Vision](./Product Vision) | Vision, users, key features, objectives | (auto) |
| [Technology Stack](./Technology Stack) | Stack, frameworks, libraries, tooling | (auto) |
| [Project Structure](./Project Structure) | Directory layout, naming conventions | (auto) |

The content of each child page is owned by `product-vision-steering`. To
refresh, run that skill against the repo.

The three child pages (Product Vision, Technology Stack, Project Structure) are populated by product-vision-steering — this skill only creates them as empty placeholders if they do not exist.

---

03 Releases Template (parent page)

Purpose: index of all releases, current and historic.

Body:

## Releases

| Release | Status | Target Date | Plan | Roadmap |
|---------|--------|-------------|------|---------|
| {{release-name}} | {{status}} | {{date}} | [Plan](./{{release-name}}/Release Plan) | [Roadmap](./{{release-name}}/Roadmap) |

> Each release child page is owned by `release-planner`. Adding a new
> release requires running that skill — it creates the child page tree and
> the JIRA epic skeletons.

---

04 Architecture Template (parent page)

Purpose: index of architecture pages, with the canonical sub-pages seeded.

Body:

## Architecture

This section captures the system's architecture at three levels:

1. **Solution Architecture** — high-level component view, integration
   topology, deployment model.
2. **Architecture Principles** — non-functional decisions, constraints, and
   trade-offs that shape every component.
3. **Component / Service Designs** — one child page per component, each with
   its own `Architecture Design v{N}` and (optionally) `Architecture Review v{N}`.

| Page | Owner | Purpose |
|------|-------|---------|
| [Solution Architecture](./Solution Architecture) | `software-architect` | System-wide view |
| [Architecture Principles](./Architecture Principles) | `software-architect` | NFRs, constraints |
| [Domain Ontology](../08 Ontology) | `ob-ontologist` | Cross-link to ontology section |
| [Components](#components) | per-component architect skill | One child per component |

## Components

(One child page per service / pipeline / agent / UI component.)

---

05 Specs Template (parent page)

Purpose: index of feature specs, mirroring .claude/specs/.

Body:

## Feature Specifications

| Feature | Status | Requirements | Design | Tasks | Tickets |
|---------|--------|--------------|--------|-------|---------|
| {{feature-name}} | {{status}} | [Reqs](./{{feature-name}}/Requirements) | [Design](./{{feature-name}}/Design) | [Tasks](./{{feature-name}}/Tasks) | [JIRA epic](#) |

> Each feature child page is owned by `feature-spec-author`. The three
> grandchildren (Requirements, Design, Tasks) are written from the
> approved spec files in `.claude/specs/{{feature-name}}/`.

---

06 Sprints Template (parent page)

Purpose: index of sprint kick-off and retro pages.

Body:

## Sprints

| Sprint | Dates | Kick-off | Retro |
|--------|-------|----------|-------|
| {{N}} | {{start}} → {{end}} | [Kick-off](./Sprint {{N}} — {{dates}}) | (after sprint) |

> Sprint pages are owned by `sprint-planner` (kickoff) and `sprint-executor`
> (retro append).

---

07 Reviews Template (parent page)

Purpose: index of all reviews, grouped by area.

Body:

## Reviews

Reviews are date-stamped, append-only pages. Never overwrite — create a new
page for each review pass.

### Code Reviews

Grouped by area. Naming convention: `{Area} — Review — {YYYY-MM-DD} {hostname}`.

- [Pipelines](./Code Reviews/Pipelines)
- [Frontend](./Code Reviews/Frontend)
- [General](./Code Reviews/General)

### Architecture Reviews

Naming convention: `{Component} — Architecture Review v{N}` (versioned)
or `{Component} — Architecture Review — {YYYY-MM-DD}` (dated).

> See `references/naming-conventions.md` in the
> `confluence-space-manager` skill for the full naming rules.

---

08 Ontology Template (parent page)

Purpose: index of domain ontology pages.

Body:

## Domain Ontologies

| Domain | Page | Owner |
|--------|------|-------|
| {{domain}} | [Ontology - {{domain}}](./Ontology - {{domain}}) | `ob-ontologist` |

> Ontology pages are first-class artifacts — they are referenced by both
> architecture pages (`04 Architecture`) and feature specs (`05 Specs`).
> Each domain has its own page named `Ontology - {Domain}` (e.g.,
> `Ontology - Legal Entities`).

---

09 References Template (parent page)

Purpose: index of cross-cutting references and audit reports.

Body:

## References

### External References

| Topic | Link | Notes |
|-------|------|-------|
| (add as you go) | | |

### Glossary

(Optional — link to a glossary page if it exists.)

### Space Audits

Reports produced by the `confluence-space-manager` skill. Latest first.

- (audits will appear here after the first run)

---

99 WIP Template (parent page)

Purpose: scratch / drafts area. No template content — intentionally blank.

Body:

## Work in Progress

Scratch and drafts area. Pages here are exempt from naming conventions
and audit checks. Promote to a canonical section when a page is ready.

---

Per-Component Architecture Design Template

Purpose: the body shape for {Component} — Architecture Design v{N} pages. The software-architect (or scope-specific architect) skill is the content owner — this template is what confluence-space-manager seeds when it creates the page placeholder.

Variables:

• {{component-name}}
• {{version}}

Body:

# {{component-name}} — Architecture Design v{{version}}

> Owner: `software-architect` (or scope-specific architect skill).
> This is a placeholder created by `confluence-space-manager`. Run the
> appropriate architect skill to populate the five canonical deliverables:
>
> 1. Solution Overview
> 2. Component Model
> 3. Technology Mapping
> 4. Integration Design
> 5. Open Questions and Risks

---

Per-Feature Spec Template

Purpose: the body shape for 05 Specs / {feature-name} / {Requirements, Design, Tasks} pages. Owner is feature-spec-author. Placeholders only.

Body for each grandchild (Requirements / Design / Tasks):

# {{section}} — {{feature-name}}

> Owner: `feature-spec-author`. This is a placeholder created by
> `confluence-space-manager`. Run `feature-spec-author` against
> `.claude/specs/{{feature-name}}/{{section-lowercase}}.md` to populate.

---

Notes on Macro Embedding

The Atlassian MCP createConfluencePage tool accepts Markdown for body content via the bodyRepresentation: "markdown" parameter (subject to API surface — confirm at use time). For Confluence-specific macros, the Markdown body cannot embed them directly. Two patterns:

1. Post-creation update — create the page with the Markdown body, then call updateConfluencePage with an ADF body that includes the macros as extension nodes. The ADF nodes for the macros used in the homepage template are documented in TBMLI's homepage (page ID 6487081701) and SAA's homepage (page ID 6508381002) as reference implementations.

2. Manual macro insertion — create the page with placeholders (> Macro: ...) in the body. After creation, prompt the user to insert the macros via the Confluence editor. Acceptable for first-pass scaffold — the Audit mode flags missing macros as low severity.

Pattern 1 is preferred when the API supports it. Pattern 2 is the fallback.

---

Reference ADF — Macro Snippets

Copy these extension node shapes into ADF bodies as needed.

project-linker

{
  "type": "extension",
  "attrs": {
    "layout": "default",
    "extensionType": "com.atlassian.confluence.project-linker",
    "extensionKey": "project-linker",
    "localId": "<uuid>"
  }
}

recently-updated

{
  "type": "extension",
  "attrs": {
    "layout": "default",
    "extensionType": "com.atlassian.confluence.macro.core",
    "extensionKey": "recently-updated",
    "parameters": {
      "macroParams": {
        "types": {"value": "page,whiteboard,database,blog"},
        "max": {"value": "10"},
        "theme": {"value": "concise"},
        "hideHeading": {"value": "true"}
      },
      "macroMetadata": {
        "macroId": {"value": "<uuid>"},
        "schemaVersion": {"value": "1"},
        "title": "Recent updates"
      }
    },
    "localId": "<uuid>"
  }
}

contributors

{
  "type": "extension",
  "attrs": {
    "layout": "default",
    "extensionType": "com.atlassian.confluence.macro.core",
    "extensionKey": "contributors",
    "parameters": {
      "macroParams": {
        "scope": {"value": "descendants"},
        "limit": {"value": "10"}
      },
      "macroMetadata": {
        "macroId": {"value": "<uuid>"},
        "schemaVersion": {"value": "1"},
        "title": "Contributors"
      }
    },
    "localId": "<uuid>"
  }
}

Reference Spaces — Annotated Tour

Three real Ontoledgy spaces that informed the canonical structure. Each is mapped to the canonical sections so you can see the convention in action (and where it bends).

Cloud ID for all: c62e56c2-b224-4d4e-a859-afa7de01241e.

---

ACE — SAKE (Solution - Agentic Chemical Engineering)

Most mature space. Spans multiple repos (knowledge extraction service, file system snapshot service, identification services, document control identity service, BIE infrastructure, bclearer PDK). Originally a research-bid space (Innovate UK / DSIT / HVMC application), evolved into a multi-component product space.

• URL: https://ontoledgy.atlassian.net/wiki/spaces/ACE/overview
• Space key: ACE (CQL queries) — backing space ID is SAKE due to

rename history. getConfluenceSpaces({keys: ["ACE"]}) may return empty; use CQL space = ACE instead.

• Homepage ID: 6487081701's analogue — actual homepage ID:

6380716198 (parent of Background, Proposal, WIP - Tasks, Current Assets/Infrastructure, Scope - Requirement, System Architecture and Agent Roles, WIP, References, Plans).

• Homepage style: legacy — does not use the project-linker macro.

Audit Row A would flag this as medium (no JIRA project bound).

• Notable scope flag: research-bid.

Mapping to canonical structure

What ACE teaches

• References as a first-class section is right. ACE's References

subtree (Agent Engineering / Skills / Coding Agents / Chemical Engineering / external bodies) is a strong pattern.

• Date-stamped review pages with hostname suffix are real. Examples:

File System Snapshot Service - Review - 2026-03-24-2216 MAUDLIN, Document Control Identity Service - Review - 2026-03-11-0813 roy.corp.ontoledgy.io.

• Per-component depth is real. `Current Assets/Infrastructure /

bCLEARer PDK and Architecture Framework is a deep sub-tree that maps cleanly to the per-component design pattern under 04 Architecture`.

• Research-bid scope needs its own conditional section. The Proposal

+ Scope - Requirement pages are essential to ACE but pollute the canonical structure if forced into it. Hence the Proposal conditional.

• Numeric prefixes were never adopted. Migration to 01..99 will be

the largest cosmetic change.

---

TBMLI (Trade Based Money Laundering Investigator)

Mid-mature, JIRA-integrated, sprint-driven product space. Single solution, multiple services (Knowledge Extraction Services, Entity Verification Services, Sanctions Screening, Address Verification Services, Agent Harness). Created using the modern Confluence project-space template.

• URL: https://ontoledgy.atlassian.net/wiki/spaces/TBMLI/overview
• Space ID: 6487080964
• Homepage ID: 6487081701 — uses the modern template:
• Description placeholder
• Project Tracker macro (com.atlassian.confluence.project-linker)
• Recently Updated macro
• Contributors macro
• JIRA project key: TBMLI.

Mapping to canonical structure

What TBMLI teaches

• The modern Confluence space template is the baseline. Project

Tracker + Recently Updated + Contributors on the homepage. We adopt these in the canonical Homepage Template.

• JIRA integration is first-class via project-linker. New spaces must

have this macro on the homepage; older spaces (ACE) lack it and the audit should flag it as critical once a JIRA project is attached.

• **Per-component sub-trees with Design v{N} and Architecture Review

pages work well.** Examples:

• Architecture / Address Verification Services / Address Verification Services — Architecture Design v1 / Implementation Path — Address Verification Services
• Architecture / Agent Harness / Agent Harness - Design v2 / Agent Harness - Architecture Review (agent-architect)
• **Pipelines and Frontend are valid grouping subsections under

07 Reviews.** The audit checklist accepts these as code-review sub-areas, alongside General.

---

SAA (Solution - Agentic Accountant)

Newest space, sparse, more architecturally-organised. Demonstrates a cleaner per-tier layout (Backend / Pipeline / UI under Solution Architecture).

• URL: https://ontoledgy.atlassian.net/wiki/spaces/SAA/overview
• Space ID: 6508380165
• Homepage ID: 6508381002 — same modern template as TBMLI

(Description, Project Tracker, Recently Updated, Contributors).

Mapping to canonical structure

What SAA teaches

• **Tier-based layout (Backend / Pipeline / UI) is a valid component

grouping.** Adopted under 04 Architecture / Components.

• **Confluence's auto-templates are tolerable as a conditional

Templates section** — they don't need to be moved or renamed.

• Greenfield spaces start almost empty. The Create mode of this

skill should be designed so an empty space gets the full canonical scaffold in one pass.

---

Convergence Analysis

What's consistent across all three spaces:

• Architecture is always a top-level section (in some form).
• Per-component depth (Service → Design vN) is universal.
• Reviews are date-stamped, append-only.
• Domain ontology is a first-class concept (separate from architecture).
• The newer two adopt the JIRA project-linker; the oldest does not.

What's inconsistent (and resolved by the canonical structure):

• Section naming (Background vs Overview, Plans vs Releases, etc.).
• Whether reviews are nested under architecture or top-level (canonical

says top-level).

• Whether ontology is under architecture or top-level (canonical says

top-level).

• Whether sprint planning lives under "Planning" or its own section

(canonical says 06 Sprints).

---

Quick Lookup — Page IDs for Reference Macro Implementations

If you need to study the exact ADF for the homepage macros (project-linker, recently-updated, contributors), fetch:

• TBMLI homepage: 6487081701
• SAA homepage: 6508381002

Both contain the same three macro stack and serve as reference implementations for the Homepage template in page-templates.md.