cc-agentic-framework 1.14.1

package/framework/modules/core/skills/building-agents/SKILL.md

@@ -0,0 +1,289 @@
+---
+id: building-agents
+name: designing-agents
+description: Design agents following Pure Agent Pattern. Use when creating new agents or validating existing ones for framework alignment.
+scope: apmr
+applicable-projects: apm-r-ai-agentic-framework
+module: core
+capabilities-provided:
+  - building-agents
+  - agent-design
+---
+
+# Slim Agent Design Skill
+
+**Skill:** building-agents
+**Taxonomy:** meta
+**Scope:** apmr (framework-manager exclusive)
+**Token Budget:** 2,000
+**Version:** 1.0.0
+
+---
+
+## When to Use
+
+Use this skill when:
+- **Creating a new agent** - Design from scratch with agent design principles
+- **Verifying existing agent** - Check alignment with agent standards
+- **Extracting content** - Move duplicated content from agent to skills
+- **Reviewing agent PRs** - Validate agent changes follow agent pattern
+
+This skill is **exclusive to ai-framework-manager** capability-needs.
+
+---
+
+## Core Principles
+
+### 1. Agents are Routing Entry Points
+
+**Purpose:** Orchestration, not content delivery
+
+**Targets:**
+- Lines: < 500
+- Tokens: < 3,000
+- Agent-specific content: > 90%
+
+**Agent responsibility:** Route to skills/context, coordinate workflows, evaluate completion.
+
+**NOT agent responsibility:** Store domain knowledge, provide templates, explain architecture.
+
+---
+
+### 2. Zero Duplication Rule
+
+**If content exists elsewhere, reference it - never duplicate.**
+
+| Content Location | Action |
+|------------------|--------|
+| Exists in a skill | Reference skill via capability-needs |
+| Exists in context | Reference via context-category-needs |
+| Exists in docs | Link to docs (never auto-load) |
+| Doesn't exist | Create skill or context file first |
+
+**Detection:** Search for 50+ consecutive similar lines across agent files.
+
+---
+
+### 3. Content Classification
+
+| Content Type | Belongs In | Example |
+|--------------|------------|---------|
+| Domain knowledge | Context files | Business rules, technical patterns |
+| Reusable workflows | Skills | Git workflows, validation, formatting |
+| Agent orchestration | Agent file | Task routing, evaluation, coordination |
+| Examples/templates | Skill supporting files | Code templates, before/after examples |
+| Reference docs | docs/ folder | Architecture docs, API references |
+
+**Decision tree:** See [CONTENT-ROUTING.md](./CONTENT-ROUTING.md)
+
+---
+
+### 4. Progressive Disclosure via Skills
+
+**Pattern:**
+```
+SKILL.md (~300 lines) ← Always loaded
+├── EXAMPLES.md ← On-demand
+├── PATTERNS.md ← On-demand
+└── WORKFLOW.md ← On-demand
+```
+
+**Rules:**
+- SKILL.md = entry point (< 500 lines)
+- Supporting files = loaded only when needed
+- Agents reference skills, not inline content
+- Total skill budget: 1,500-2,500 tokens
+
+---
+
+### 5. Token Budget Discipline
+
+| Component | Budget | Rationale |
+|-----------|--------|-----------|
+| Agent file | < 3,000 tokens | Pure routing overhead |
+| Individual skill | 1,500-2,500 tokens | Progressive disclosure |
+| Agent + auto-loaded skills | < 15,000 tokens | Runtime context limit |
+| Total framework | < 25,000 tokens | All context + agents + skills |
+
+**Measurement:** Count tokens in markdown files (rough: lines × 5.5)
+
+---
+
+## Quick Decision Tree
+
+```
+Is this content agent-specific orchestration?
+├── YES → Keep in agent
+│   Examples: Task routing, evaluation checklist, mandatory workflow
+│
+└── NO → Where does it belong?
+    ├── Is it domain knowledge? → Context file
+    ├── Is it a reusable workflow? → Skill
+    ├── Is it examples/templates? → Skill supporting file
+    └── Is it reference documentation? → docs/ folder
+```
+
+---
+
+## Slim Agent Template
+
+See [AGENT-TEMPLATE.md](./AGENT-TEMPLATE.md) for complete template with:
+- YAML frontmatter structure
+- Section ordering
+- Token budget allocation per section
+- Required vs optional sections
+
+---
+
+## Validation Checklist (Quick)
+
+Before committing agent changes:
+
+- [ ] **Lines:** < 500 lines total
+- [ ] **Tokens:** < 3,000 tokens estimated
+- [ ] **Duplication:** 0% duplicated content from skills/context
+- [ ] **Agent-specific:** > 90% content is orchestration
+- [ ] **Skill routing:** All task types route to skills
+- [ ] **Discovery:** capability-needs resolve to skills
+- [ ] **Context:** context-category-needs defined correctly
+
+**Full validation:** See [VALIDATION-CHECKLIST.md](./VALIDATION-CHECKLIST.md)
+
+---
+
+## Instructions
+
+### Creating a New Agent
+
+1. **Start with template** from [AGENT-TEMPLATE.md](./AGENT-TEMPLATE.md)
+2. **Define capability-needs** (what skills this agent requires)
+3. **Define context-category-needs** (business/technical/process levels)
+4. **Write orchestration content only** (routing, coordination, evaluation)
+5. **Validate against checklist** before committing
+6. **Update registries** (agents.json, discovery-map.json if new capabilities)
+
+### Verifying Existing Agent
+
+1. **Measure current state** (lines, tokens, duplication %)
+2. **Classify each section** using [CONTENT-ROUTING.md](./CONTENT-ROUTING.md)
+3. **Identify extraction candidates** (> 50 lines duplicated/non-agent-specific)
+4. **Plan extraction** (which skill gets which content)
+5. **Execute extraction** (create skill supporting files first)
+6. **Restructure agent** (remove duplicated sections, add routing)
+7. **Validate result** using [VALIDATION-CHECKLIST.md](./VALIDATION-CHECKLIST.md)
+
+### Extracting Content to Skills
+
+1. **Identify duplicated content** (exists in 2+ agents OR exists in skill)
+2. **Choose target skill** based on content type
+3. **Create supporting file** in skill directory (e.g., WORKFLOW-AGENT-CREATION.md)
+4. **Move content** to supporting file
+5. **Add routing reference** in agent (point to skill + supporting file)
+6. **Remove duplicated content** from agent
+7. **Update skill registry** if token budget changes
+
+---
+
+## Common Patterns
+
+### Pattern 1: Task Routing Table
+
+Replace inline task workflows with routing table:
+
+```markdown
+## Skill Routing Table
+
+| Task | Primary Skill | Supporting File |
+|------|---------------|-----------------|
+| Create Agent | governance skill | AGENT-CREATION-WORKFLOW.md |
+| Create Skill | building-skills skill | SKILL-CREATION-WORKFLOW.md |
+| Update Governance | governance skill | GOVERNANCE-UPDATE-WORKFLOW.md |
+```
+
+### Pattern 2: Capability Reference
+
+Replace inline knowledge with capability reference:
+
+```markdown
+## MCP Operations
+
+> **Skill:** Load `generic-shared-using-mcp-meta` for MCP tool guidance
+> **Supporting:** See FRAMEWORK-MCP-PATTERNS.md for framework-specific patterns
+```
+
+### Pattern 3: Context Reference
+
+Replace inline domain knowledge with context reference:
+
+```markdown
+## Architecture Understanding
+
+> **Context:** Auto-loaded via `context-category-needs.technical: advanced`
+> **Skill:** For deep architecture patterns, load `understanding-framework-architecture` skill
+```
+
+---
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Inline Duplication
+
+**Wrong:**
+```markdown
+## MCP Tools for Framework Work
+[397 lines of MCP documentation that exists in MCP skill]
+```
+
+**Right:**
+```markdown
+## MCP Operations
+> **Skill:** `generic-shared-using-mcp-meta`
+```
+
+### Anti-Pattern 2: Bloated Agent
+
+**Wrong:** 1,950 lines with 67% duplicated content
+
+**Right:** ~420 lines with 100% agent-specific content
+
+### Anti-Pattern 3: Missing Skill Routing
+
+**Wrong:** Agent handles everything inline
+
+**Right:** Agent routes to skills via capability-needs declaration
+
+---
+
+## Supporting Files
+
+| File | Purpose | Load When |
+|------|---------|-----------|
+| [AGENT-TEMPLATE.md](./AGENT-TEMPLATE.md) | Complete agent template | Creating new agent |
+| [CONTENT-ROUTING.md](./CONTENT-ROUTING.md) | Decision matrix for content placement | Classifying content |
+| [VALIDATION-CHECKLIST.md](./VALIDATION-CHECKLIST.md) | Step-by-step validation | Before commit |
+| [EXAMPLES.md](./EXAMPLES.md) | Before/after real examples | Learning patterns |
+
+---
+
+## Related Skills
+
+- `building-framework` - Framework rules and governance
+- `building-skills` - How to build skills
+- `verifying-quality` - Quality validation
+
+---
+
+## Research Foundation
+
+This skill is based on industry best practices:
+
+- **Google Cloud:** "One primary agent maintains context, subagents do actual work"
+- **Anthropic:** "Agent Skills are modular capabilities... load information in stages as needed"
+- **Microsoft Azure:** "Modular design - agents as composable, specialized entities"
+- **UserJot:** "Subagents do one thing well... pure function execution"
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2025-12-15
+**Capabilities Provided:** agent-design, agent-content-routing, agent-validation

package/framework/modules/core/skills/building-agents/VALIDATION-CHECKLIST.md

@@ -0,0 +1,304 @@
+# Agent Validation Checklist
+
+Complete validation process for ensuring agents meet design standards.
+
+---
+
+## Pre-Validation: Gather Metrics
+
+Before validation, collect these metrics:
+
+```bash
+# Line count
+wc -l ai/agents/ai-{name}.md
+
+# Token estimate (rough: lines × 5.5)
+echo "Estimated tokens: $(( $(wc -l < ai/agents/ai-{name}.md) * 55 / 10 ))"
+
+# File size
+ls -la ai/agents/ai-{name}.md
+```
+
+**Record:**
+- [ ] Total lines: ____
+- [ ] Estimated tokens: ____
+- [ ] File size: ____ bytes
+
+---
+
+## Stage 1: Size Validation
+
+### 1.1 Line Count Check
+
+| Status | Criteria |
+|--------|----------|
+| PASS | < 500 lines |
+| WARNING | 500-700 lines |
+| FAIL | > 700 lines |
+
+**Current:** ____ lines → Status: ____
+
+### 1.2 Token Budget Check
+
+| Status | Criteria |
+|--------|----------|
+| PASS | < 3,000 tokens |
+| WARNING | 3,000-4,000 tokens |
+| FAIL | > 4,000 tokens |
+
+**Current:** ____ tokens → Status: ____
+
+### 1.3 Budget Alignment
+
+Compare against declared `token-budget` in YAML frontmatter:
+
+- [ ] Actual tokens ≤ declared budget
+- [ ] Declared budget ≤ 3,000 (standard)
+
+---
+
+## Stage 2: Duplication Detection
+
+### 2.1 Cross-Agent Duplication
+
+Search for content that exists in other agents:
+
+```bash
+# Find similar content patterns
+for agent in ai/agents/ai-*.md; do
+  echo "=== $agent ==="
+  grep -c "## MCP\|## Discovery\|## Registry\|## Version" "$agent"
+done
+```
+
+**Check each section > 50 lines:**
+- [ ] Section 1: ____ - Exists in other agent? Y/N
+- [ ] Section 2: ____ - Exists in other agent? Y/N
+- [ ] Section 3: ____ - Exists in other agent? Y/N
+
+### 2.2 Skill Duplication
+
+Search for content that exists in skills:
+
+```bash
+# Check if content exists in skills
+grep -r "## MCP Tools" ai/skills/
+grep -r "## Discovery" ai/skills/
+```
+
+**Check each major section:**
+- [ ] MCP content: Duplicated from skill? Y/N
+- [ ] Architecture content: Duplicated from skill? Y/N
+- [ ] Workflow content: Duplicated from skill? Y/N
+
+### 2.3 Duplication Percentage
+
+Calculate: `(duplicated lines / total lines) × 100`
+
+| Status | Criteria |
+|--------|----------|
+| PASS | 0% duplicated |
+| WARNING | 1-10% duplicated |
+| FAIL | > 10% duplicated |
+
+**Current:** ____% → Status: ____
+
+---
+
+## Stage 3: Content Classification
+
+### 3.1 Section Audit
+
+For each major section (> 20 lines), classify:
+
+| Section | Lines | Type | Correct Location? |
+|---------|-------|------|-------------------|
+| Purpose | | Agent orchestration | YES |
+| Skill Routing | | Agent orchestration | YES |
+| {Section 3} | | ? | ? |
+| {Section 4} | | ? | ? |
+| {Section 5} | | ? | ? |
+
+**Content types:**
+- **Agent orchestration** → Should be in agent
+- **Domain knowledge** → Should be in context
+- **Reusable workflow** → Should be in skill
+- **Examples/templates** → Should be in skill supporting file
+
+### 3.2 Agent-Specific Percentage
+
+Calculate: `(agent-specific lines / total lines) × 100`
+
+| Status | Criteria |
+|--------|----------|
+| PASS | > 90% agent-specific |
+| WARNING | 70-90% agent-specific |
+| FAIL | < 70% agent-specific |
+
+**Current:** ____% → Status: ____
+
+---
+
+## Stage 4: Structure Validation
+
+### 4.1 Required Sections
+
+- [ ] YAML frontmatter with all required fields
+- [ ] Purpose section with core responsibilities
+- [ ] Skill routing table (or equivalent)
+- [ ] Success criteria section
+- [ ] Self-evaluation section
+- [ ] Footer with version/metadata
+
+### 4.2 YAML Frontmatter Fields
+
+- [ ] `agent:` - Valid agent ID
+- [ ] `role:` - Human-readable role
+- [ ] `capability-needs:` - Array of capabilities
+- [ ] `context-category-needs:` - Business/Technical/Process levels
+- [ ] `token-budget:` - Within limits (< 3000)
+
+### 4.3 Section Ordering
+
+Recommended order:
+1. [ ] Title and purpose
+2. [ ] Auto-discovery note
+3. [ ] Skill routing table
+4. [ ] Required reading (optional)
+5. [ ] Agent-specific tasks
+6. [ ] Success criteria
+7. [ ] Self-evaluation
+8. [ ] Footer/metadata
+
+---
+
+## Stage 5: Discovery Integration
+
+### 5.1 Capability-Needs Resolution
+
+Run discovery test:
+
+```bash
+agentic-framework validate --verbose
+```
+
+**Check:**
+- [ ] All capability-needs resolve to skills
+- [ ] No "missing capability" errors
+- [ ] Discovered skills match expected
+
+### 5.2 Context-Category-Needs Resolution
+
+**Verify levels are appropriate:**
+- [ ] `business:` level matches agent's domain knowledge needs
+- [ ] `technical:` level matches agent's technical depth needs
+- [ ] `process:` level matches agent's process knowledge needs
+
+### 5.3 Registry Alignment
+
+**Check agents.json:**
+- [ ] Agent entry exists
+- [ ] `capability-needs` matches YAML frontmatter
+- [ ] `context-category-needs` matches YAML frontmatter
+- [ ] `token-budget` matches YAML frontmatter
+
+---
+
+## Stage 6: Link Validation
+
+Run link validator:
+
+```bash
+agentic-framework validate --links
+```
+
+**Check:**
+- [ ] All internal links resolve
+- [ ] All skill references valid
+- [ ] All context references valid
+- [ ] No broken anchors
+
+---
+
+## Stage 7: Functional Testing
+
+### 7.1 Task Coverage
+
+For each task type the agent handles:
+- [ ] Task 1: Can route to correct skill? Y/N
+- [ ] Task 2: Can route to correct skill? Y/N
+- [ ] Task 3: Can route to correct skill? Y/N
+
+### 7.2 Real Scenario Test
+
+Test with actual use case:
+
+1. Invoke agent with realistic task
+2. Verify skill auto-discovery works
+3. Verify context auto-loading works
+4. Verify task completion
+
+**Result:** ____
+
+---
+
+## Validation Summary
+
+### Pass/Fail Criteria
+
+| Stage | Status | Notes |
+|-------|--------|-------|
+| Size | ____ | Lines: ____, Tokens: ____ |
+| Duplication | ____ | ____% duplicated |
+| Classification | ____ | ____% agent-specific |
+| Structure | ____ | Missing: ____ |
+| Discovery | ____ | Issues: ____ |
+| Links | ____ | Broken: ____ |
+| Functional | ____ | Issues: ____ |
+
+### Overall Result
+
+- [ ] **PASS** - All stages pass
+- [ ] **PASS WITH WARNINGS** - Minor issues, can proceed
+- [ ] **FAIL** - Must address issues before commit
+
+### Action Items
+
+If not passing, list required fixes:
+
+1. ____
+2. ____
+3. ____
+
+---
+
+## Quick Validation (Abbreviated)
+
+For quick checks, use this abbreviated version:
+
+```bash
+# 1. Size check
+wc -l ai/agents/ai-{name}.md  # Must be < 500
+
+# 2. Discovery check
+agentic-framework validate --verbose
+
+# 3. Link check
+agentic-framework validate --links
+
+# 4. Visual inspection
+# - Has skill routing table?
+# - Has success criteria?
+# - Has self-evaluation?
+```
+
+**Quick pass criteria:**
+- [ ] < 500 lines
+- [ ] Discovery passes
+- [ ] Links valid
+- [ ] Required sections present
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2025-12-15