cc-agentic-framework 1.14.1

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

@@ -0,0 +1,209 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agentic-framework.dev/schemas/agents.schema.json",
+  "title": "Agentic Framework Agents Registry",
+  "description": "Schema for agents.json registry that defines all available agents with their capabilities, context needs, and SDK configuration",
+  "type": "object",
+  "required": ["version", "agents"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Registry version (semantic version)"
+    },
+    "agents": {
+      "type": "array",
+      "description": "List of all agent definitions",
+      "items": {
+        "$ref": "#/definitions/AgentDefinition"
+      }
+    }
+  },
+  "definitions": {
+    "AgentDefinition": {
+      "type": "object",
+      "required": ["id", "module", "file", "capability-needs", "context-category-needs", "token-budget"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^ai-[a-z][a-z0-9-]*$",
+          "description": "Unique agent identifier (e.g., ai-framework-manager, ai-app-developer)"
+        },
+        "module": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Module ID that provides this agent"
+        },
+        "file": {
+          "type": "string",
+          "pattern": "^(\\.claude/commands/|ai/agents/|framework/modules/[a-z-]+/agents/).+\\.md$",
+          "description": "Path to agent markdown file relative to project root"
+        },
+        "essential-skills": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "description": "Skills that are always loaded for this agent (Tier 1: cannot be omitted, critical for agent function)"
+        },
+        "capability-needs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "description": "Capabilities this agent requires (Tier 2: matched to skills via discovery-map, role-based enhancements)"
+        },
+        "available-skills": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "description": "Skills available for on-demand invocation (Tier 3: referenced but not loaded, invoke via Skill tool)"
+        },
+        "context-category-needs": {
+          "type": "object",
+          "description": "Context loading requirements by category and level",
+          "additionalProperties": false,
+          "properties": {
+            "business": {
+              "$ref": "#/definitions/ContextLevel"
+            },
+            "technical": {
+              "$ref": "#/definitions/ContextLevel"
+            },
+            "process": {
+              "$ref": "#/definitions/ContextLevel"
+            }
+          }
+        },
+        "context-files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]+-[a-z]+\\.md$"
+          },
+          "description": "Computed list of context files to load (derived from context-category-needs)"
+        },
+        "token-budget": {
+          "type": "integer",
+          "minimum": 500,
+          "maximum": 10000,
+          "description": "Token budget for agent prompt"
+        },
+        "sdk": {
+          "$ref": "#/definitions/SDKConfiguration",
+          "description": "Claude Agent SDK configuration for programmatic execution"
+        }
+      }
+    },
+    "ContextLevel": {
+      "type": "string",
+      "enum": ["basic", "advanced", "expert"],
+      "description": "Context loading level (cumulative: basic < advanced < expert)"
+    },
+    "SDKConfiguration": {
+      "type": "object",
+      "description": "Claude Agent SDK configuration for programmatic agent execution",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this agent is SDK-enabled for programmatic execution"
+        },
+        "model": {
+          "type": "string",
+          "enum": ["opus", "sonnet", "haiku"],
+          "default": "sonnet",
+          "description": "Default model for this agent (can be overridden at runtime)"
+        },
+        "allowed-tools": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SDKTool"
+          },
+          "description": "Whitelist of tools this agent can use (empty = all tools)"
+        },
+        "sub-agents": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SubAgentType"
+          },
+          "description": "Phase-specialized sub-agents this agent can invoke"
+        },
+        "execution-mode": {
+          "type": "string",
+          "enum": ["interactive", "autonomous"],
+          "default": "interactive",
+          "description": "Execution mode: interactive (user prompts) or autonomous (batch)"
+        },
+        "max-tokens": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 200000,
+          "description": "Maximum output tokens for generated responses"
+        },
+        "permissions": {
+          "$ref": "#/definitions/SDKPermissions",
+          "description": "Permission settings for tool usage"
+        },
+        "custom-agent-file": {
+          "type": "string",
+          "pattern": "^\\.claude/agents/ai-[a-z][a-z0-9-]*\\.json$",
+          "description": "Path to generated custom agent JSON file (enables Task tool invocation with subagent_type)"
+        }
+      }
+    },
+    "SDKTool": {
+      "type": "string",
+      "enum": [
+        "Read",
+        "Write",
+        "Edit",
+        "Glob",
+        "Grep",
+        "Bash",
+        "WebSearch",
+        "WebFetch",
+        "Task",
+        "TodoWrite",
+        "AskUserQuestion",
+        "NotebookEdit"
+      ],
+      "description": "Claude Agent SDK built-in tool names"
+    },
+    "SubAgentType": {
+      "type": "string",
+      "enum": ["explore", "architect", "reviewer", "implementer"],
+      "description": "Phase-specialized sub-agent types: explore (discovery), architect (design), reviewer (validation), implementer (execution)"
+    },
+    "SDKPermissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["default", "bypassPermissions", "acceptEdits"],
+          "default": "default",
+          "description": "Permission mode for tool usage"
+        },
+        "allowed-bash-commands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Whitelist of allowed bash command patterns (regex)"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agentic-framework.dev/schemas/command.schema.json",
+  "title": "Agentic Framework Command Wrapper",
+  "description": "Schema for command wrapper markdown files that expose CLI commands as Claude slash commands",
+  "type": "object",
+  "required": ["command", "cli-command", "module", "type", "description"],
+  "additionalProperties": true,
+  "properties": {
+    "command": {
+      "type": "string",
+      "pattern": "^cmd-[a-z][a-z0-9-]*$",
+      "description": "Unique command identifier (e.g., cmd-backlog-create-ticket)"
+    },
+    "cli-command": {
+      "type": "string",
+      "pattern": "^agentic-framework .+$",
+      "description": "Full CLI invocation (e.g., agentic-framework backlog create-ticket)"
+    },
+    "module": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Module ID that provides this command"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["create", "validate", "sync", "transform", "export", "import", "migrate", "update", "fetch", "query", "execute"],
+      "description": "Command type category"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "Brief description of what the command does"
+    },
+    "related-skill": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Related skill that provides detailed guidance (optional)"
+    },
+    "options": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/CommandOption"
+      },
+      "description": "Command-line options"
+    },
+    "examples": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/CommandExample"
+      },
+      "description": "Usage examples"
+    }
+  },
+  "definitions": {
+    "CommandOption": {
+      "type": "object",
+      "required": ["name", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^--?[a-z][a-z0-9-]*( <[a-z]+>)?$",
+          "description": "Option name with optional value placeholder (e.g., --type <type>)"
+        },
+        "description": {
+          "type": "string",
+          "description": "What this option does"
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this option is required"
+        },
+        "default": {
+          "type": "string",
+          "description": "Default value if not specified"
+        }
+      }
+    },
+    "CommandExample": {
+      "type": "object",
+      "required": ["command", "description"],
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Example command invocation"
+        },
+        "description": {
+          "type": "string",
+          "description": "What this example demonstrates"
+        }
+      }
+    }
+  }
+}

package/framework/modules/core/registries/schemas/custom-agent.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agentic-framework.dev/schemas/custom-agent.schema.json",
+  "title": "Claude Code Custom Agent Definition",
+  "description": "Schema for .claude/agents/*.json files that define custom agents for Claude Code invocation via Task tool",
+  "type": "object",
+  "required": ["name", "description", "model", "instructions", "tools"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^ai-[a-z][a-z0-9-]*$",
+      "description": "Custom agent identifier (must match subagent_type in Task tool invocation)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 200,
+      "description": "Brief description shown in /agents listing"
+    },
+    "model": {
+      "type": "string",
+      "enum": ["opus", "sonnet", "haiku"],
+      "default": "sonnet",
+      "description": "Default model for this agent (can be overridden at invocation)"
+    },
+    "instructions": {
+      "type": "string",
+      "minLength": 100,
+      "description": "System prompt instructions for the agent (condensed from markdown source)"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Tool"
+      },
+      "minItems": 1,
+      "description": "Tools available to this agent"
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "description": "Skills this agent can invoke via Skill tool"
+    },
+    "context": {
+      "$ref": "#/definitions/ContextNeeds",
+      "description": "Context loading requirements"
+    },
+    "sourceAgent": {
+      "type": "string",
+      "pattern": "^ai-[a-z][a-z0-9-]*$",
+      "description": "Source agent ID from agents.json (for traceability)"
+    },
+    "generated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp when this definition was generated"
+    }
+  },
+  "definitions": {
+    "Tool": {
+      "type": "string",
+      "enum": [
+        "Read",
+        "Write",
+        "Edit",
+        "Glob",
+        "Grep",
+        "Bash",
+        "WebSearch",
+        "WebFetch",
+        "Task",
+        "TodoWrite",
+        "AskUserQuestion",
+        "NotebookEdit",
+        "Skill"
+      ],
+      "description": "Claude Code tool name"
+    },
+    "ContextNeeds": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "business": {
+          "$ref": "#/definitions/ContextLevel"
+        },
+        "technical": {
+          "$ref": "#/definitions/ContextLevel"
+        },
+        "process": {
+          "$ref": "#/definitions/ContextLevel"
+        }
+      }
+    },
+    "ContextLevel": {
+      "type": "string",
+      "enum": ["basic", "advanced", "expert"],
+      "description": "Context loading level"
+    }
+  }
+}

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

@@ -0,0 +1,233 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agentic-framework.dev/schemas/module.schema.json",
+  "title": "Agentic Framework Module",
+  "description": "Schema for module.json manifest files that define framework modules",
+  "type": "object",
+  "required": ["id", "version", "name", "description", "provides"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 2,
+      "maxLength": 30,
+      "description": "Unique module identifier (kebab-case)"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (e.g., 1.0.0)"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 50,
+      "description": "Human-readable module name"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "Brief description of module purpose"
+    },
+    "provides": {
+      "type": "object",
+      "description": "What this module provides to the framework",
+      "additionalProperties": false,
+      "properties": {
+        "agents": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^ai-[a-z][a-z0-9-]*$"
+          },
+          "description": "Agent IDs provided by this module"
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "description": "Skill IDs provided by this module"
+        },
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "description": "Capability IDs this module makes available"
+        },
+        "scripts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "DEPRECATED: Python scripts (use cli-commands instead)"
+        },
+        "guards": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "DEPRECATED: Pre-commit guard scripts (use entry-points.hooks instead)"
+        },
+        "cli-commands": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "Simple command name (legacy format)"
+              },
+              {
+                "type": "object",
+                "required": ["name", "type"],
+                "additionalProperties": false,
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "Full command name (e.g., 'planning create-plan')"
+                  },
+                  "type": {
+                    "type": "string",
+                    "enum": ["create", "validate", "sync", "transform", "export", "import", "migrate", "update", "fetch", "query", "execute"],
+                    "description": "Command type category"
+                  },
+                  "skill": {
+                    "type": "string",
+                    "description": "Skill ID that implements this command (optional for query/execute types)"
+                  },
+                  "template": {
+                    "type": "string",
+                    "description": "Template file used by create commands"
+                  },
+                  "schema": {
+                    "type": "string",
+                    "description": "JSON Schema file used by validate commands"
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Human-readable command description"
+                  }
+                },
+                "description": "Structured command definition linking to implementing skill"
+              }
+            ]
+          },
+          "description": "CLI commands provided by this module via agentic-framework CLI"
+        }
+      }
+    },
+    "requires": {
+      "type": "object",
+      "description": "Required module dependencies with version constraints",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^(>=|>|=|<|<=)?\\d+\\.\\d+\\.\\d+$"
+      }
+    },
+    "optional-dependencies": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "description": "Optional modules that enhance functionality if present"
+    },
+    "context": {
+      "type": "object",
+      "description": "Context files provided by this module",
+      "additionalProperties": false,
+      "properties": {
+        "business": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "technical": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "process": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "entry-points": {
+      "type": "object",
+      "description": "CLI entry points and scripts",
+      "additionalProperties": false,
+      "properties": {
+        "cli": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "script"],
+            "properties": {
+              "name": { "type": "string" },
+              "script": { "type": "string" },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "hooks": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "pre-commit": { "type": "array", "items": { "type": "string" } },
+            "post-commit": { "type": "array", "items": { "type": "string" } },
+            "pre-push": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "claude-hooks": {
+          "type": "object",
+          "description": "Claude Code hook configurations by event type",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["matcher", "scripts"],
+              "additionalProperties": false,
+              "properties": {
+                "matcher": {
+                  "type": "string",
+                  "description": "Regex pattern to match against hook event context"
+                },
+                "scripts": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Shell script filenames in the module's hooks/ directory"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional module metadata",
+      "properties": {
+        "author": { "type": "string" },
+        "license": { "type": "string" },
+        "repository": { "type": "string", "format": "uri" },
+        "homepage": { "type": "string", "format": "uri" },
+        "keywords": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "category": {
+          "type": "string",
+          "enum": ["core", "integration", "workflow", "development", "documentation", "reporting"]
+        }
+      }
+    }
+  }
+}