67f3922e4f
Phase 1 — Agent & Command Foundation: - Rewrite cs-project-manager agent (55→515 lines, 4 workflows, 6 skill integrations) - Expand cs-product-manager agent (408→684 lines, orchestrates all 8 product skills) - Add 7 slash commands: /rice, /okr, /persona, /user-story, /sprint-health, /project-health, /retro Phase 2 — Script Gap Closure (2,779 lines): - jira-expert: jql_query_builder.py (22 patterns), workflow_validator.py - confluence-expert: space_structure_generator.py, content_audit_analyzer.py - atlassian-admin: permission_audit_tool.py - atlassian-templates: template_scaffolder.py (Confluence XHTML generation) Phase 3 — Reference & Asset Enrichment: - 9 product references (competitive-teardown, landing-page-generator, saas-scaffolder) - 6 PM references (confluence-expert, atlassian-admin, atlassian-templates) - 7 product assets (templates for PRD, RICE, sprint, stories, OKR, research, design system) - 1 PM asset (permission_scheme_template.json) Phase 4 — New Agents: - cs-agile-product-owner, cs-product-strategist, cs-ux-researcher Phase 5 — Integration & Polish: - Related Skills cross-references in 8 SKILL.md files - Updated product-team/CLAUDE.md (5→8 skills, 6→9 tools, 4 agents, 5 commands) - Updated project-management/CLAUDE.md (0→12 scripts, 3 commands) - Regenerated docs site (177 pages), updated homepage and getting-started Quality audit: 31 files reviewed, 29 PASS, 2 fixed (copy-frameworks.md, governance-framework.md) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
247 lines
7.5 KiB
Markdown
247 lines
7.5 KiB
Markdown
# 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
|