cc-agentic-framework 1.14.1

package/framework/modules/core/skills/using-context/EXAMPLES.md

@@ -0,0 +1,257 @@
+# Examples: Agent Context Loading Integration
+
+## Example 1: Architecture Agent (ai-architect)
+
+### Problem
+Agent needs deep knowledge of both business strategy and technical architecture to design system components.
+
+### Solution
+
+```markdown
+## Purpose
+Architect designs system components, technical decisions, and integration patterns.
+Uses business strategy and technical standards to ensure alignment.
+
+## Required Reading
+
+**Critical:** This agent provides **generic architecture principles**.
+The technical-advanced.md provides **YOUR project's specific patterns and tech stack**.
+Always check context files before designing components.
+
+### Context Files
+
+> **📋 Registry:** Loading matrix defined in [ai/registry.yml](../registry.yml)
+> `loading-matrix.ai-architect`
+
+Load these 3 files for architecture design:
+
+1. **[ai/context/business-advanced.md](../context/business-advanced.md)** - Strategy, roadmap, market positioning
+2. **[ai/context/technical-advanced.md](../context/technical-advanced.md)** - Tech stack, patterns, architecture standards
+3. **[ai/context/process-basic.md](../context/process-basic.md)** - Development workflow, documentation standards
+
+### Shared Resources
+
+> **📋 Registry:** Shared resources in [ai/registry.yml](../registry.yml)
+> `shared-resources`
+
+1. **[ai/shared/markdown-formatting-guide.md](../shared/markdown-formatting-guide.md)** - Documentation formatting standards
+2. **[ai/shared/agent-self-evaluation.md](../shared/agent-self-evaluation.md)** - Post-design evaluation framework
+```
+
+### Analysis
+- **Context mix:** 1 advanced business + 1 advanced technical + 1 basic process
+- **Rationale:** Deep knowledge of strategy + tech stack, lightweight workflow knowledge
+- **Token budget:** ~210 tokens (balanced expertise)
+- **Registry reference:** Directly links to registry, no duplication
+
+---
+
+## Example 2: App Developer Agent (ai-app-developer)
+
+### Problem
+Agent implements features but doesn't need deep strategy knowledge. Needs lightweight business understanding with strong technical depth.
+
+### Solution
+
+```markdown
+## Purpose
+App developer implements features, writes code, and maintains components.
+Focuses on technical excellence while understanding business context.
+
+## Required Reading
+
+**Critical:** This agent provides **generic development best practices**.
+The technical-advanced.md provides **YOUR project's specific stack and patterns**.
+Always check context files before starting implementation.
+
+### Context Files
+
+> **📋 Registry:** Loading matrix defined in [ai/registry.yml](../registry.yml)
+> `loading-matrix.ai-app-developer`
+
+Load these 3 files for implementation:
+
+1. **[ai/context/business-basic.md](../context/business-basic.md)** - Product features, core value, users
+2. **[ai/context/technical-advanced.md](../context/technical-advanced.md)** - Tech stack, patterns, codebase structure
+3. **[ai/context/process-basic.md](../context/process-basic.md)** - Development workflow, documentation standards
+
+**Note:** The ai-app-developer uses 1 basic + 1 advanced + 1 basic files.
+This provides lightweight business understanding with deep technical knowledge.
+```
+
+### Analysis
+- **Context mix:** 1 basic business + 1 advanced technical + 1 basic process
+- **Rationale:** Understand features, master technical stack, follow workflow
+- **Token budget:** ~190 tokens (implementation-focused)
+- **Agent-specific note:** Clarifies WHY this unusual mix exists
+
+---
+
+## Example 3: Before & After Comparison
+
+### ❌ BEFORE: Token Inefficient (750+ wasted tokens)
+
+```markdown
+## Architecture Design Process
+
+When designing components, check the technical-advanced.md context to understand
+YOUR project's specific patterns. The technical-advanced.md has detailed information
+about the tech stack you should know.
+
+## Component Design Decisions
+
+For each component, you should check technical-advanced.md to understand how similar
+components are designed in YOUR project. Always reference technical-advanced.md when
+making implementation decisions.
+
+## Integration Patterns
+
+When integrating components, you need to check technical-advanced.md for YOUR project's
+integration patterns. The technical-advanced.md defines standards for how things work together.
+
+## Testing Strategy
+
+Before testing, check technical-advanced.md for YOUR project's testing standards and
+approaches. Reference technical-advanced.md when designing tests.
+```
+
+**Problem:** "Check technical-advanced.md" repeated 4+ times = ~50-80 tokens × 5 = 250-400 tokens wasted
+
+### ✅ AFTER: Token Efficient (~50 tokens saved)
+
+```markdown
+## Required Reading
+
+**Critical:** This agent provides generic architecture principles.
+The technical-advanced.md provides YOUR project's specific patterns and tech stack.
+Always check context files before designing components.
+
+### Context Files
+
+Load these 3 files:
+
+1. **[ai/context/business-advanced.md]** - Strategy, roadmap, market positioning
+2. **[ai/context/technical-advanced.md]** - Tech stack, patterns, architecture standards
+3. **[ai/context/process-basic.md]** - Development workflow, documentation standards
+
+---
+
+## Architecture Design Process
+
+When designing components, consider...
+[No reminders needed - context loaded above]
+
+## Component Design Decisions
+
+For each component, ensure...
+[Context already loaded in Required Reading]
+
+## Integration Patterns
+
+When integrating components, follow...
+[Reference context from Required Reading]
+
+## Testing Strategy
+
+Before testing, design tests that...
+[No need to repeat - context established once]
+```
+
+**Improvement:** Single context statement at top (50 tokens) vs scattered reminders (250+ tokens) = 200 token savings
+
+---
+
+## Example 4: Shared Resources Only (Lightweight Agent)
+
+### Problem
+Agent doesn't need context files, but uses shared tools and templates.
+
+### Solution
+
+```markdown
+## Purpose
+Operations coordinator manages framework-related tasks and documentation.
+
+## Required Reading
+
+**Critical:** This agent uses shared resources for framework operations.
+Check shared resources for templates and procedures.
+
+### Shared Resources
+
+> **📋 Registry:** Shared resources in [ai/registry.yml](../registry.yml)
+> `shared-resources`
+
+1. **[ai/shared/markdown-formatting-guide.md]** - Documentation formatting standards
+2. **[ai/shared/ticket-template.md]** - Ticket structure template
+3. **[ai/shared/validation-checklist.md]** - Quality checklist
+```
+
+### Analysis
+- **No context files:** Agent doesn't need business/technical/process context
+- **Shared resources only:** Uses templates and procedures
+- **Token budget:** ~80 tokens (minimal)
+- **Use case:** Framework maintenance, coordination, administration
+
+---
+
+## Quick Copy-Paste Templates
+
+### Template 1: Full Context + Shared Resources
+
+```markdown
+## Required Reading
+
+**Critical:** This agent provides [domain] principles.
+The [context-file].md provides YOUR project's specific [details].
+
+### Context Files
+
+> **📋 Registry:** [ai/registry.yml](../registry.yml) `loading-matrix.[agent-name]`
+
+Load these N files:
+
+1. **[ai/context/business-[level].md]** - [3-10 word description]
+2. **[ai/context/technical-[level].md]** - [3-10 word description]
+3. **[ai/context/process-[level].md]** - [3-10 word description]
+
+### Shared Resources
+
+> **📋 Registry:** [ai/registry.yml](../registry.yml) `shared-resources`
+
+1. **[ai/shared/resource-name.md]** - [Brief description]
+```
+
+### Template 2: Context Only (No Shared Resources)
+
+```markdown
+## Required Reading
+
+**Critical:** This agent needs [specific] context.
+
+### Context Files
+
+> **📋 Registry:** [ai/registry.yml](../registry.yml) `loading-matrix.[agent-name]`
+
+1. **[ai/context/business-[level].md]** - [3-10 word description]
+2. **[ai/context/technical-[level].md]** - [3-10 word description]
+```
+
+### Template 3: Shared Resources Only (No Context Files)
+
+```markdown
+## Required Reading
+
+**Critical:** This agent uses shared resources for [purpose].
+
+### Shared Resources
+
+> **📋 Registry:** [ai/registry.yml](../registry.yml) `shared-resources`
+
+1. **[ai/shared/resource-name.md]** - [Brief description]
+```
+
+---
+
+**Examples Version:** 1.0
+**Last Updated:** 2025-12-07

package/framework/modules/core/skills/using-context/SKILL.md

@@ -0,0 +1,238 @@
+---
+id: using-context
+module: core
+name: loading-context-pattern
+description: Load context files in layered fashion with registry integration. Use when building agents, updating context loading patterns, or understanding how agents consume business/technical/process knowledge.
+scope: generic
+applicable-projects: any
+capabilities-provided:
+  - context-loading-knowledge
+# Claude Code v2.1 features - read-only knowledge skill
+tools:
+  - Read
+  - Glob
+  - Grep
+---
+
+# Loading Context Pattern
+
+## When to Use This Skill
+
+You need to understand **how agents load context** and should:
+- Build agents with proper context loading (Required Reading sections)
+- Structure agent "Required Reading" sections for clarity and token efficiency
+- Reference context files from registry (single source of truth)
+- Avoid redundant context reminders throughout agent instructions
+- Design frameworks with separated concerns (context vs implementation)
+- Review historical context loading patterns
+
+**Example Invocations:**
+- "Use loading-context-pattern to add a Required Reading section to my agent"
+- "Help me structure context loading for an agent - how do I organize files?"
+- "Show me how agents should reference registry in Required Reading sections"
+- "I want to improve token efficiency - how do context reminders work?"
+
+---
+
+## Quick Reference
+
+### The Pattern
+
+**Problem:** Agents need context to operate, but repeating "check context files" throughout agent instructions wastes 750-3,000 tokens
+
+**Solution:** Load context once in Required Reading section with:
+
+| Component | Purpose | Size |
+|-----------|---------|------|
+| **Context Files** | Business/technical/process knowledge | 50-120 tokens |
+| **Shared Resources** | Tools, templates, utilities | 40-60 tokens |
+| **Registry Reference** | Single source of truth | 20-30 tokens |
+| **Total** | Complete context load | 150-250 tokens per agent |
+
+### Standard Structure
+
+Every agent follows this pattern immediately after Purpose:
+
+```markdown
+## Required Reading
+
+**Critical:** This agent provides [domain] principles.
+The [context-file].md provides YOUR project's specific details.
+
+### Context Files
+
+> **📋 Registry:** Loading matrix in [ai/registry.yml](../registry.yml)
+
+Load these [N] files for [agent-purpose]:
+
+1. **[ai/context/business-[level].md]** - [Brief description]
+2. **[ai/context/technical-[level].md]** - [Brief description]
+3. **[ai/context/process-[level].md]** - [Brief description]
+
+### Shared Resources
+
+> **📋 Registry:** Shared resources in [ai/registry.yml](../registry.yml)
+
+1. **[ai/shared/resource-name.md]** - [Brief description]
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Business + Technical Context (Domain Experts)
+
+**Use When:** Agent needs project knowledge to provide specialized expertise
+
+**Structure:**
+```markdown
+### Context Files
+
+Load these 2 files for [agent-purpose]:
+
+1. **[ai/context/business-advanced.md]** - Product strategy, user personas, market
+2. **[ai/context/technical-advanced.md]** - Tech stack, patterns, architecture
+```
+
+**Token Budget:** 120-180 tokens (dense knowledge)
+
+### Pattern 2: Lightweight + Intensive (Balanced Learning)
+
+**Use When:** Agent needs some business context but deep technical knowledge
+
+**Structure:**
+```markdown
+### Context Files
+
+Load these 2 files for [agent-purpose]:
+
+1. **[ai/context/business-basic.md]** - Product overview, core features
+2. **[ai/context/technical-advanced.md]** - Architecture, patterns, standards
+```
+
+**Token Budget:** 100-160 tokens (balanced)
+
+### Pattern 3: Process-Focused Loading
+
+**Use When:** Agent executes standardized workflows
+
+**Structure:**
+```markdown
+### Context Files
+
+Load these 2 files for [agent-purpose]:
+
+1. **[ai/context/process-basic.md]** - Development workflow, standards
+2. **[ai/context/technical-basic.md]** - Stack overview, conventions
+```
+
+**Token Budget:** 80-140 tokens (implementation-focused)
+
+---
+
+## Registry Integration
+
+All context loading references registry.yml as single source of truth:
+
+**Registry Structure:**
+```yaml
+workflow:
+  loading-matrix:
+    ai-architect:
+      - business-advanced
+      - technical-advanced
+      - process-basic
+    ai-app-developer:
+      - business-basic
+      - technical-advanced
+      - process-basic
+
+shared-resources:
+  markdown-formatting: ai/shared/markdown-formatting-guide.md
+  agent-evaluation: ai/shared/agent-self-evaluation.md
+```
+
+**Why registry-first:**
+1. Single source of truth - update once, applies everywhere
+2. Enables context dependency tracking
+3. Simplifies agent design (just reference registry)
+4. Token budgets tracked centrally
+
+**In Agents:** Always link to registry, never duplicate metadata:
+```markdown
+> **📋 Registry:** Loading matrix defined in [ai/registry.yml](../registry.yml)
+> `loading-matrix.ai-architect`
+```
+
+---
+
+## Token Efficiency Guidelines
+
+### ✅ DO: One clear statement in Required Reading
+
+```markdown
+## Required Reading
+
+**Critical:** This agent provides **generic architecture principles**.
+The technical-advanced.md provides **YOUR project's specific patterns**.
+Always check context files before designing.
+```
+
+**Token cost:** 50-80 tokens (one statement)
+
+### ❌ DON'T: Repeat throughout agent
+
+```markdown
+## Section 1
+→ Check technical-advanced.md for YOUR project's patterns
+
+## Section 2
+→ Check technical-advanced.md for YOUR project's patterns
+
+## Section 3
+→ Check technical-advanced.md for YOUR project's patterns
+```
+
+**Token cost:** 50-80 tokens × 15-20 reminders = 750-1,600 wasted tokens
+
+### Key Rules
+
+1. **Keep descriptions short:** 3-10 words per file
+2. **State once, reference many:** One Required Reading section, reference throughout
+3. **Use registry references:** Point to registry rather than duplicating paths
+4. **Minimal file lists:** Only include files agent actually needs
+
+**Token Budget Targets:**
+- Required Reading section: 150-250 tokens per agent
+- Context Files subsection: 80-120 tokens
+- Shared Resources subsection: 40-60 tokens
+- Agent-specific notes: 30-50 tokens (optional)
+
+---
+
+## See Also
+
+### Deep Dives (Supporting Files)
+
+- **[STANDARDS.md](STANDARDS.md)** - How to structure Required Reading sections in agents, file descriptions, registry integration
+- **[EXAMPLES.md](EXAMPLES.md)** - Real-world agent integration examples, before/after comparisons
+
+### Related Skills
+
+- **[using-framework](../using-framework/SKILL.md)** - Framework design patterns with routes/registry separation
+- **[building-skills](../building-skills/SKILL.md)** - How to build skills with good structure
+- **[building-framework](../building-framework/SKILL.md)** - Framework governance rules
+
+### Reference Files
+
+- **ai/registry.yml** - Single source of truth for loading matrices and context definitions
+- **ai/context/** - All context files (organized by type: business, technical, process)
+- **ai/shared/** - Shared resources available to all agents
+- **ai/framework/framework-governance.md** - Pure Agent Pattern rules
+
+---
+
+**Type:** knowledge (static reference)
+**Scope:** generic (reusable across projects with context files)
+**Applicable Projects:** any project with framework structure
+**Last Updated:** 2025-12-07