2481 01 Shared Docs Integration 14e005be

Shared-Docs Integration Guide for Claude Copilot

Purpose: Define how shared-docs should be structured to optimize ingestion by Claude Code and Claude Copilot agents.

Audience: Documentation curators, developers maintaining shared-docs, Claude Code when consuming documentation.

Overview

Claude Copilot consumes documentation through multiple touchpoints:

Key Insight: The problem isn't content quality—it's the absence of navigation layers that would help Claude Code find relevant context efficiently.

Directory Structure

Root Structure (Locked)

shared-docs/
├── 00-best-practices/     # Templates for developer rules, handoffs
├── 01-company/            # Identity, brand, voice, services, methodologies
├── 02-products/           # Product ecosystem and per-product packs
├── 03-ai-enabling/        # Skills, profiles, operations (proprietary)
├── _archive/              # Archived content (excluded from ingestion)
├── .claude/               # Claude Code configuration
├── CLAUDE.md              # Claude Code guidance
├── README.md              # Repository overview
└── STRUCTURE.md           # Structure enforcement

Rule: Root structure is FINAL. Do not create, rename, or remove root-level directories.

Numbering Conventions

Sparse numbering (10, 20, 30) allows inserting files without renumbering (15, 25 can be added).

Navigation Layers

Three-Tier Navigation System

Tier 1: Global Index (00-INDEX.md)
    └── Tier 2: Section Overviews (00-overview.md per directory)
        └── Tier 3: Individual Documents

00-INDEX.md (Create at shared-docs root)

Topic-based navigation for Claude Code to quickly locate relevant content:

# Shared-Docs Navigation Index

## By Topic

### Security
| Document | Location | Tokens | For Agent |
|----------|----------|--------|-----------|
| Security Guidelines | 03-ai-enabling/03-operations/02-security-guidelines.md | ~800 | All |

### Company Voice
| Document | Location | Tokens | For Agent |
|----------|----------|--------|-----------|
| Identity | 01-company/02-voice/01-identity.md | ~600 | @cw, @sd |

### Methodologies
| Document | Location | Tokens | For Agent |
|----------|----------|--------|-----------|
| Forces Framework | 01-company/06-methodologies/10-forces-framework.md | ~1,500 | @sd |

00-overview.md vs 00-index.md

Token Budget Guidelines

By Document Type

Aggregates

Efficiency Patterns

File Splitting Triggers

• Single file exceeds token budget → split by logical section
• Operational guides > 4,000 tokens → create overview + detailed sections
• Product packs > 4,000 tokens total → review for duplication

Frontmatter Schema

Three-Tier Metadata System

Tier 1: Skills (SKILL.md files)

---
skill_name: forces-analysis
skill_category: analysis
description: One-line description for skill search
allowed_tools: [Read, Write, Edit]
token_estimate: 1850
version: 1.2
last_updated: 2025-01-15
owner: Service Design Team
status: active
tags: [forces, organizational-design, leadership]
methodology: 01-company/06-methodologies/10-forces-framework.md
related_skills: [moments-mapping, colab-facilitation]
---

Tier 2: Product Documentation

---
product: Insights Copilot
status: active
last_updated: 2025-01-15
source_of_truth: ../../insights-copilot/docs/04-architecture/system-design.md
owner: Platform Team
token_estimate: 650
doc_type: architecture
ingestion_priority: high
dependencies: [forces-assessment, research-copilot]
summary: Intelligence synthesis platform for pattern detection
key_entities: [Force, Intelligence, Pattern, Stream]
integration_endpoints: [POST /api/forces, GET /api/patterns]
---

Tier 3: Operational Documentation

---
title: Documentation Strategy Guide
doc_type: guide
category: operations
last_updated: 2025-01-15
version: 2.1
status: active
primary_audience: [developers, agents, documentation-curators]
required_reading: false
token_estimate: 2500
replaces: _archive/old-doc-guide.md
related: [05-documentation-guide.md]
---

Agent Dependency Mapping

Create: 03-ai-enabling/02-profiles/AGENT-DEPENDENCIES.md

Maps which documents each agent requires:

# Agent Context Dependencies

## Service Designer (@sd)

### Required Context (always load)
| Document | Reason | Tokens |
|----------|--------|--------|
| 01-company/02-voice/01-identity.md | Company voice | ~600 |
| 01-company/06-methodologies/10-forces-framework.md | Core methodology | ~1,500 |
| 01-company/06-methodologies/20-moments-framework.md | Core methodology | ~1,500 |

**Total minimum**: ~3,600 tokens

### Optional Context (load on demand)
| Document | When Needed | Tokens |
|----------|-------------|--------|
| 01-company/05-patterns/20-tension-patterns.md | Forces analysis | ~1,000 |

## Copywriter (@cw)

### Required Context
| Document | Reason | Tokens |
|----------|--------|--------|
| 01-company/02-voice/* | All voice files | ~4,500 total |

## Tech Architect (@ta)

### Required Context
| Document | Reason | Tokens |
|----------|--------|--------|
| 03-ai-enabling/03-operations/01-development-standards.md | Code standards | ~1,200 |
| Product architecture docs | Integration context | ~1,200 |

Cross-Referencing Strategy

Current Pattern

> **Full details:** [Page Title](relative/path/to/detailed/doc.md)

Enhanced Pattern: Typed Cross-References

## Cross-References

**Source of Truth:**
→ [Architecture Deep Dive](../../product-repo/docs/04-architecture/system-design.md)

**Prerequisites:**
→ [Getting Started](./00-overview.md)
→ [Authentication Setup](./60-security.md#authentication)

**Related Concepts:**
→ [Shared Glossary: Force](../03-operations/12-shared-glossary.md#force)

**Implementation:**
→ [Task Breakdown](./80-integration-prompt.md)

Link Registry Pattern (Per Product Directory)

Create 00-links.md per product pack:

---
# Link Registry: 02-products/06-insights-copilot
---

## Source of Truth Links
- architecture: ../../insights-copilot/docs/04-architecture/
- api: ../../insights-copilot/docs/05-api/

## Internal Links
- ecosystem: ../00-ecosystem-overview.md
- shared-glossary: ../../03-ai-enabling/03-operations/12-shared-glossary.md

## External Links
- production: https://insights.ineedacopilot.com
- repo: https://github.com/org/insights-copilot

Product Pack Structure

Standard Product Pack Template

02-products/06-insights-copilot/
├── 00-overview.md          # Entry point (800 tokens max)
├── 10-architecture.md      # System context (1,200 tokens max)
├── 20-deployment.md        # Environments (400 tokens max)
├── 30-operations.md        # Monitoring (400 tokens max)
├── 40-integrations.md      # How to connect (650 tokens max)
├── 50-api.md               # Endpoints (700 tokens max)
├── 60-security.md          # Auth/data (400 tokens max)
├── 70-decisions.md         # ADRs/gaps (400 tokens max)
└── 80-integration-prompt.md # LLM integration guide (600 tokens max)

Total target: < 4,000 tokens per product pack

Each File Must Include

1. Frontmatter (product metadata)
2. Summary (2-3 sentences max)
3. Core content (tables preferred)
4. Cross-reference to detailed docs in product repo

Content Optimization for AI

Structural Patterns

Semantic Markers (Optional)

<!-- AI_CONTEXT: Authentication required for all endpoints -->
| Method | Path | Auth | Purpose |
|--------|------|------|---------|

<!-- AI_CONSTRAINT: Rate limit 100 req/min per token -->

Payload Examples with Type Annotations

{
  "event": "assessment.completed",        // string, required
  "assessment_id": "uuid",                 // UUID v4, required
  "forces": [                              // array, 1-20 items
    {
      "name": "string",                    // max 255 chars
      "intensity": 5                       // int, 1-10
    }
  ],
  "timestamp": "2025-01-15T10:30:00Z"     // ISO-8601, UTC
}

Context Loading Strategy

On Session Start

1. Load Tier 1: 00-INDEX.md (~400 tokens)
2. If agent invoked, load agent manifest (~200 tokens)
3. Defer Tier 2 until needed

When Agent Invoked

1. Load required context from AGENT-DEPENDENCIES.md
2. Surface optional context (don't auto-load)
3. Load dependencies on demand

When User Asks Specific Question

1. Use 00-INDEX.md to find topic docs
2. Load doc + stated dependencies
3. Suggest related docs

Token Budget by Scenario

Files to Create

Priority 1: Navigation (Immediate)

Priority 2: Catalogs (This Week)

Priority 3: Per-Directory (Ongoing)

Validation Skills

Claude Copilot provides three validation skills for maintaining shared-docs quality. These are invoked by Claude during sessions rather than run as external scripts.

Available Skills

Usage

Ask Claude to invoke a skill:

Check the token budgets for all files in docs/

Validate links in the shared-docs directory

Check frontmatter in 02-products/ and fix any issues

Claude will load the skill via skill_get and execute the validation, providing a report and optionally fixing issues.

Skill Capabilities

Success Metrics

Anti-Patterns to Avoid

Implementation Roadmap

Phase 1: Navigation (Week 1)

• Create 00-INDEX.md at shared-docs root
• Create AGENT-DEPENDENCIES.md
• Add token estimates to all frontmatter

Phase 2: Catalogs (Week 2)

• Generate skills catalog
• Generate profiles catalog
• Consolidate voice layer files (optional)

Phase 3: Product Packs (Week 3-4)

• Add 00-overview.md to each product directory
• Add frontmatter to all product docs
• Create link registries per product

Phase 4: Automation (Month 2)

• Token budget CI check
• Link validation in pre-commit
• Automated index generation

References

• Extension Specification: EXTENSION-SPEC.md
• Documentation Guide: documentation-guide.md
• Working Protocol: working-protocol.md