cc-agentic-framework 1.14.1

package/framework/modules/core/registries/schemas/template.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agentic-framework.dev/schemas/template.schema.json",
+  "title": "Template Configuration",
+  "description": "Schema for template.config.json files that define template metadata and variables",
+  "type": "object",
+  "required": ["version", "templates"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Template schema version (e.g., 1.0)"
+    },
+    "templates": {
+      "type": "object",
+      "description": "Template definitions keyed by template filename",
+      "additionalProperties": {
+        "$ref": "#/$defs/templateDefinition"
+      },
+      "minProperties": 1
+    },
+    "autoNumbering": {
+      "$ref": "#/$defs/autoNumberingConfig"
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Global defaults applied to all templates in this config",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  },
+  "$defs": {
+    "templateDefinition": {
+      "type": "object",
+      "description": "Configuration for a single template file",
+      "required": ["output", "variables"],
+      "additionalProperties": false,
+      "properties": {
+        "output": {
+          "type": "string",
+          "description": "Output path pattern with {{variable}} placeholders (e.g., '{{name}}.md')",
+          "minLength": 1
+        },
+        "variables": {
+          "type": "object",
+          "description": "Variable configuration for this template",
+          "required": ["required"],
+          "additionalProperties": false,
+          "properties": {
+            "required": {
+              "type": "array",
+              "description": "Variables that must be provided when rendering",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
+              },
+              "uniqueItems": true
+            },
+            "optional": {
+              "type": "array",
+              "description": "Variables that may be provided (defaults applied if missing)",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
+              },
+              "uniqueItems": true,
+              "default": []
+            },
+            "computed": {
+              "type": "array",
+              "description": "Variables computed by the engine (date, number, uuid, user)",
+              "items": {
+                "type": "string",
+                "enum": ["date", "datetime", "year", "number", "uuid", "user"]
+              },
+              "uniqueItems": true,
+              "default": []
+            }
+          }
+        },
+        "defaults": {
+          "type": "object",
+          "description": "Default values for optional variables",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "validation": {
+          "type": "object",
+          "description": "Validation rules for variables",
+          "additionalProperties": {
+            "$ref": "#/$defs/variableValidation"
+          }
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of this template"
+        }
+      }
+    },
+    "variableValidation": {
+      "type": "object",
+      "description": "Validation rules for a single variable",
+      "additionalProperties": false,
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "description": "Regex pattern the value must match"
+        },
+        "minLength": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Minimum string length"
+        },
+        "maxLength": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum string length"
+        },
+        "enum": {
+          "type": "array",
+          "description": "Allowed values",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
+    "autoNumberingConfig": {
+      "type": "object",
+      "description": "Configuration for automatic sequential numbering",
+      "required": ["pattern", "padding"],
+      "additionalProperties": false,
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "description": "Filename pattern with {num} placeholder (e.g., 'STORY-{num}')",
+          "pattern": ".*\\{num\\}.*"
+        },
+        "padding": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 6,
+          "default": 3,
+          "description": "Zero-padding width for numbers (e.g., 3 = 001, 002)"
+        },
+        "startFrom": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 1,
+          "description": "Starting number if no existing files found"
+        }
+      }
+    }
+  }
+}

package/framework/modules/core/registries/skill-triggers.json

@@ -0,0 +1,196 @@
+{
+  "version": "1.0.0",
+  "description": "Skill trigger patterns for contextual skill reminders. Maps available skills to keywords and patterns that indicate when the skill would be helpful.",
+  "skill-triggers": {
+    "using-mcp": {
+      "description": "MCP tools and web search capabilities",
+      "triggers": [
+        "mcp",
+        "model context protocol",
+        "web search",
+        "search the web",
+        "external api",
+        "third-party tool",
+        "duckduckgo",
+        "fetch url",
+        "external service"
+      ],
+      "prompt-patterns": [
+        "search.*web",
+        "find.*mcp",
+        "discover.*tool",
+        "fetch.*url",
+        "look up.*online"
+      ]
+    },
+    "validating-markdown": {
+      "description": "Markdown formatting and YAML frontmatter validation",
+      "triggers": [
+        "markdown",
+        "frontmatter",
+        "yaml syntax",
+        ".md file",
+        "documentation format",
+        "readme",
+        "changelog"
+      ],
+      "prompt-patterns": [
+        "create.*doc",
+        "write.*readme",
+        "format.*markdown",
+        "validate.*yaml",
+        "check.*frontmatter"
+      ]
+    },
+    "using-framework": {
+      "description": "Framework architecture and discovery engine understanding",
+      "triggers": [
+        "framework architecture",
+        "routes.yml",
+        "discovery engine",
+        "registry system",
+        "module system",
+        "skill loading",
+        "context loading"
+      ],
+      "prompt-patterns": [
+        "how.*framework",
+        "understand.*architecture",
+        "navigate.*codebase",
+        "discovery.*engine"
+      ]
+    },
+    "validating-links": {
+      "description": "Link validation in markdown documentation",
+      "triggers": [
+        "broken link",
+        "validate link",
+        "check reference",
+        "link syntax",
+        "dead link",
+        "missing reference"
+      ],
+      "prompt-patterns": [
+        "validate.*link",
+        "check.*reference",
+        "find.*broken",
+        "verify.*url"
+      ]
+    },
+    "building-context": {
+      "description": "Context file authoring and validation",
+      "triggers": [
+        "context file",
+        "business context",
+        "technical context",
+        "process context",
+        "context-category-needs"
+      ],
+      "prompt-patterns": [
+        "create.*context",
+        "update.*context",
+        "write.*context"
+      ]
+    },
+    "building-skills": {
+      "description": "Skill creation and framework integration",
+      "triggers": [
+        "create skill",
+        "new skill",
+        "skill file",
+        "skill template"
+      ],
+      "prompt-patterns": [
+        "create.*skill",
+        "build.*skill",
+        "add.*skill"
+      ]
+    },
+    "building-agents": {
+      "description": "Agent design patterns",
+      "triggers": [
+        "create agent",
+        "new agent",
+        "agent design",
+        "agent variant",
+        "agent design"
+      ],
+      "prompt-patterns": [
+        "create.*agent",
+        "build.*agent",
+        "design.*agent"
+      ]
+    },
+    "integrating-jira": {
+      "description": "Jira integration and ticket sync",
+      "triggers": [
+        "jira",
+        "jira ticket",
+        "jira sync",
+        "jira export",
+        "jira import"
+      ],
+      "prompt-patterns": [
+        "sync.*jira",
+        "export.*jira",
+        "import.*jira"
+      ]
+    },
+    "publishing-confluence": {
+      "description": "Confluence page publishing and ADF conversion",
+      "triggers": [
+        "confluence",
+        "confluence page",
+        "adf",
+        "atlassian document format"
+      ],
+      "prompt-patterns": [
+        "publish.*confluence",
+        "create.*confluence",
+        "convert.*adf"
+      ]
+    },
+    "building-reports": {
+      "description": "Report generation and metrics collection",
+      "triggers": [
+        "report",
+        "metrics",
+        "status report",
+        "executive summary"
+      ],
+      "prompt-patterns": [
+        "generate.*report",
+        "create.*report",
+        "build.*metrics"
+      ]
+    },
+    "organizing-backlog": {
+      "description": "Backlog organization and ticket lifecycle",
+      "triggers": [
+        "backlog",
+        "sprint planning",
+        "milestone",
+        "epic breakdown"
+      ],
+      "prompt-patterns": [
+        "organize.*backlog",
+        "plan.*sprint",
+        "break.*epic"
+      ]
+    },
+    "building-worlds": {
+      "description": "World design and magic system creation",
+      "triggers": [
+        "world building",
+        "magic system",
+        "fantasy world",
+        "culture design"
+      ],
+      "prompt-patterns": [
+        "create.*world",
+        "design.*magic",
+        "build.*culture"
+      ]
+    }
+  }
+}

package/framework/modules/core/skills/building-agents/AGENT-TEMPLATE.md

@@ -0,0 +1,289 @@
+# Slim Agent Template
+
+This template defines the structure for agents that follow routing/orchestration patterns.
+
+---
+
+## YAML Frontmatter (Required)
+
+```yaml
+---
+agent: ai-{agent-name}
+role: {Role Title}
+capability-needs:
+  - {capability-1}
+  - {capability-2}
+context-category-needs:
+  business: none|basic|advanced|expert
+  technical: none|basic|advanced|expert
+  process: none|basic|advanced|expert
+token-budget: {2000-3000}
+---
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `agent` | Yes | Agent identifier (ai-{name} pattern) |
+| `role` | Yes | Human-readable role title |
+| `framework-version` | Yes | Current framework version |
+| `capability-needs` | Yes | Array of capabilities this agent requires |
+| `context-category-needs` | Yes | Business/Technical/Process levels |
+| `token-budget` | Yes | Target token budget (< 3000) |
+
+---
+
+## Section Structure
+
+### Recommended Order and Budget
+
+| Section | Lines | Tokens | Required |
+|---------|-------|--------|----------|
+| Title + Purpose | 20-30 | ~150 | Yes |
+| Auto-Discovery Note | 5-10 | ~50 | Yes |
+| Core Responsibilities | 15-25 | ~120 | Yes |
+| Skill Routing Table | 20-30 | ~150 | Yes |
+| Required Reading | 15-25 | ~120 | Optional |
+| Agent-Specific Tasks | 100-200 | ~1000 | Yes |
+| Success Criteria | 10-20 | ~80 | Yes |
+| Self-Evaluation | 10-20 | ~80 | Yes |
+| Footer/Metadata | 15-25 | ~100 | Yes |
+| **TOTAL** | **~350-420** | **~1850-2350** | — |
+
+---
+
+## Complete Template
+
+```markdown
+# {Agent Name} Agent
+
+**Agent:** ai-{agent-name}
+**Capability:** {primary-capability}
+**Framework:** v12.0 (Discovery-Driven Architecture)
+**Version:** 12.0
+
+> **Auto-Discovery:** Required skills are automatically discovered and loaded
+> by the Discovery Engine based on this agent's `capability-needs`.
+> See [ai/registries/agents.json]({project}/ai/registries/agents.json) and
+> [ai/registries/discovery-map.json]({project}/ai/registries/discovery-map.json)
+> for capability mappings.
+
+---
+
+## Purpose
+
+{1-2 sentence description of agent purpose}
+
+**Core Responsibilities:**
+1. {Responsibility 1}
+2. {Responsibility 2}
+3. {Responsibility 3}
+4. {Responsibility 4}
+5. {Responsibility 5}
+
+---
+
+## Skill Routing Table
+
+| Task Category | Primary Skill | Supporting File |
+|--------------|---------------|-----------------|
+| {Task 1} | `{skill-id}` | {SUPPORTING-FILE.md} |
+| {Task 2} | `{skill-id}` | {SUPPORTING-FILE.md} |
+| {Task 3} | `{skill-id}` | {SUPPORTING-FILE.md} |
+
+> **Note:** For tasks not listed, check agent's `capability-needs` in
+> agents.json - Discovery Engine will auto-load appropriate skills.
+
+---
+
+## Required Reading
+
+> **Context:** Auto-loaded via `context-category-needs` declared in frontmatter
+
+For deep context understanding, these files are auto-loaded by Discovery Engine:
+- Business context at {level} level
+- Technical context at {level} level
+- Process context at {level} level
+
+---
+
+## Agent-Specific Tasks
+
+### Task: {Task Name 1}
+
+**When:** {When to use this task}
+
+**Workflow:**
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+**Validation:**
+- [ ] {Validation check 1}
+- [ ] {Validation check 2}
+
+---
+
+### Task: {Task Name 2}
+
+**When:** {When to use this task}
+
+**Workflow:**
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+---
+
+## Success Criteria
+
+You are effective when:
+- {Criterion 1}
+- {Criterion 2}
+- {Criterion 3}
+- {Criterion 4}
+
+---
+
+## Self-Evaluation
+
+After completing tasks:
+
+1. Did I follow the skill routing table?
+2. Did I leverage auto-discovery instead of inline knowledge?
+3. Did I validate against success criteria?
+4. Did I document any issues or assumptions?
+
+> **Skill:** Use `verifying-quality`
+> for complete evaluation protocol
+
+---
+
+**Version:** 12.0
+**Token Budget:** {budget} tokens
+**Last Updated:** {date}
+```
+
+---
+
+## Token Budget Guidelines
+
+### Slim Agent (< 3,000 tokens)
+
+**Characteristics:**
+- Pure routing/orchestration
+- Skill routing table for all task types
+- Minimal inline workflows
+- Context auto-loaded via Discovery Engine
+
+**Example agents:** ai-confluence-manager, ai-app-developer
+
+### Standard Agent (3,000-4,000 tokens)
+
+**Characteristics:**
+- Some agent-specific workflows
+- Skill routing for reusable tasks
+- Domain-specific coordination logic
+
+**Example agents:** ai-jira-manager, ai-framework-developer
+
+### Heavy Agent (4,000-5,000 tokens) - Avoid
+
+**When acceptable:**
+- Agent has unique, non-extractable workflows
+- Agent coordinates multiple complex systems
+- No skill covers the agent's specialty
+
+**Requires justification:** Document why content can't be extracted to skills.
+
+---
+
+## Section Templates
+
+### Purpose Section Template
+
+```markdown
+## Purpose
+
+{Agent name} provides {primary capability} by {how it achieves it}.
+
+**Core Responsibilities:**
+1. {Action verb} {what} for {whom/what}
+2. {Action verb} {what} for {whom/what}
+3. {Action verb} {what} for {whom/what}
+```
+
+### Skill Routing Table Template
+
+```markdown
+## Skill Routing Table
+
+| Task Category | Primary Skill | When to Load |
+|--------------|---------------|--------------|
+| {Category} | `{skill-id}` | {Trigger condition} |
+
+> **Auto-Discovery:** All skills in `capability-needs` are auto-loaded.
+> This table shows which skill handles which task type for clarity.
+```
+
+### Agent-Specific Task Template
+
+```markdown
+### Task: {Task Name}
+
+**When:** {Specific trigger conditions}
+
+**Prerequisites:**
+- {Prerequisite 1}
+- {Prerequisite 2}
+
+**Workflow:**
+1. {Step with clear action}
+2. {Step with clear action}
+3. {Step with clear action}
+
+**Validation:**
+- [ ] {Measurable validation criterion}
+- [ ] {Measurable validation criterion}
+
+> **Skill:** For {related capability}, load `{skill-id}`
+```
+
+---
+
+## What NOT to Include
+
+### Never include in agent:
+
+1. **Domain knowledge** - Belongs in context files
+2. **Reusable workflows** - Belongs in skills
+3. **Architecture documentation** - Belongs in skills or docs
+4. **Code examples** - Belongs in skill supporting files
+5. **Reference documentation** - Belongs in docs folder
+6. **Duplicated content** - Reference source instead
+
+### Red flags (content to extract):
+
+- Section > 100 lines → Consider extraction
+- Content exists in another agent → Extract to skill
+- Content is not agent-specific → Move to context/skill
+- Examples and templates → Move to skill supporting file
+
+---
+
+## Validation Before Commit
+
+Before committing a new or modified agent:
+
+1. **Line count:** `wc -l ai/agents/ai-{name}.md` → Must be < 500
+2. **Token estimate:** Lines × 5.5 → Must be < 3,000
+3. **Duplication check:** Search for similar content in other agents
+4. **Routing check:** All task types have skill routing
+5. **Discovery check:** `agentic-framework validate --verbose`
+6. **Link check:** `agentic-framework validate --links`
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2025-12-15