cc-agentic-framework 1.14.1

package/framework/modules/core/commands/cmd-agent-show.md

@@ -0,0 +1,37 @@
+---
+command: cmd-agent-show
+cli-command: "agentic-framework agent show"
+module: core
+type: query
+description: "Show SDK definition for an agent"
+---
+
+# Agent Show
+
+**Command:** `agentic-framework agent show`
+**Module:** Framework Core
+**Type:** query
+
+## Description
+
+Show SDK definition for an agent
+
+## Usage
+
+```bash
+agentic-framework agent show [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework agent show
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework agent show --help
+```

package/framework/modules/core/commands/cmd-bump-version.md

@@ -0,0 +1,42 @@
+---
+command: cmd-bump-version
+cli-command: "agentic-framework bump-version"
+module: core
+type: update
+description: "Bump framework version"
+related-skill: managing-versions
+---
+
+# Bump Version
+
+**Command:** `agentic-framework bump-version`
+**Module:** Framework Core
+**Type:** update
+
+## Description
+
+Bump framework version
+
+## Usage
+
+```bash
+agentic-framework bump-version [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework bump-version
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework bump-version --help
+```
+
+## Related
+
+- **Skill:** `managing-versions` - Provides detailed guidance for this command

package/framework/modules/core/commands/cmd-mcp-check.md

@@ -0,0 +1,59 @@
+---
+description: Check MCP prerequisites status (Docker, Graphiti, Serena)
+cli-command: agentic-framework mcp check
+---
+
+# MCP Check
+
+Checks the status of MCP prerequisites to ensure Graphiti and Serena can be used.
+
+## What Gets Checked
+
+### Docker (for Graphiti)
+- Docker is installed
+- Docker daemon is running
+
+### Graphiti Containers
+- Graphiti/FalkorDB containers exist
+- Containers are running
+
+### Serena
+- uvx is installed (Python tool runner)
+- Serena is cached/available
+
+## Usage
+
+```bash
+# Check all prerequisites
+agentic-framework mcp check
+
+# JSON output (for scripting)
+agentic-framework mcp check --json
+
+# Show installation instructions for missing prerequisites
+agentic-framework mcp check --verbose
+```
+
+## Exit Codes
+
+- **0**: All prerequisites met
+- **1**: Some prerequisites missing
+- **2**: No prerequisites met
+
+## Example Output
+
+```
+MCP Prerequisites Status
+
+  ✓ Docker v24.0.5
+  ✓ Graphiti containers running
+      graphiti, falkordb
+  ✓ uvx v0.1.24
+      Serena will be installed on first use
+
+Summary:
+  Graphiti: Ready
+  Serena:   Ready
+
+✓ All MCP prerequisites are met
+```

package/framework/modules/core/commands/cmd-mcp-seed.md

@@ -0,0 +1,69 @@
+---
+description: Seed MCP knowledge bases (Graphiti and Serena) with project information
+cli-command: agentic-framework mcp seed
+---
+
+# MCP Seed
+
+Seeds knowledge bases with project information for AI memory and code navigation.
+
+## What Gets Seeded
+
+### Graphiti (Knowledge Graph Memory)
+- Project Overview (CLAUDE.md, README.md)
+- Module Catalog (installed modules and their capabilities)
+- Agent Registry (available slash commands)
+- Skill Registry (available skills)
+- Context Summaries (business, technical, process context)
+
+### Serena (Semantic Code Navigation)
+- Project Overview (structure, framework version)
+- Architecture Patterns (module system, discovery engine)
+- CLI Structure (commands, libraries)
+
+## Usage
+
+```bash
+# Seed all configured MCP integrations
+agentic-framework mcp seed
+
+# Seed Graphiti only
+agentic-framework mcp seed --graphiti
+
+# Seed Serena only
+agentic-framework mcp seed --serena
+
+# Preview what would be seeded
+agentic-framework mcp seed --dry-run
+
+# Verbose output
+agentic-framework mcp seed --verbose
+```
+
+## Prerequisites
+
+Before seeding, ensure MCP is configured:
+```bash
+agentic-framework mcp status
+```
+
+If MCP is not configured:
+```bash
+agentic-framework mcp setup
+```
+
+## After Seeding
+
+In your Claude session, use the seeded knowledge:
+
+### Graphiti
+```
+search_memory_facts("project overview", group_ids=["YOUR_GROUP_ID"])
+search_nodes("modules capabilities", group_ids=["YOUR_GROUP_ID"])
+```
+
+### Serena
+```
+activate_project("YOUR_PROJECT_NAME")
+get_symbols_overview("src/")
+```

package/framework/modules/core/commands/cmd-mcp-setup.md

@@ -0,0 +1,61 @@
+---
+description: Configure MCP integrations (Graphiti, Serena) for a project
+cli-command: agentic-framework mcp setup
+---
+
+# MCP Setup
+
+Configures MCP (Model Context Protocol) integrations for AI memory and code navigation.
+
+## What Gets Configured
+
+### Graphiti (Knowledge Graph Memory)
+- Group ID for project isolation
+- Permissions in settings.local.json
+- Session end hook for save reminders
+
+### Serena (Semantic Code Navigation)
+- .serena/project.yml configuration
+- Memory directory setup
+- Permissions in settings.local.json
+- Session start hook for activation reminder
+
+## Usage
+
+### Interactive Mode (Recommended)
+```bash
+agentic-framework mcp setup
+```
+
+### Non-Interactive Mode
+```bash
+# Enable both Graphiti and Serena
+agentic-framework mcp setup --graphiti --serena
+
+# Custom configuration
+agentic-framework mcp setup \
+  --graphiti --graphiti-group-id my-project \
+  --serena --serena-project my-project --serena-language typescript
+
+# Skip prompts
+agentic-framework mcp setup --no-interactive --graphiti --serena
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--graphiti` | Enable Graphiti only |
+| `--serena` | Enable Serena only |
+| `--graphiti-group-id <id>` | Custom group ID (default: project name) |
+| `--serena-project <name>` | Custom project name (default: project name) |
+| `--serena-language <lang>` | Primary language (default: typescript) |
+| `--no-interactive` | Skip interactive prompts |
+
+## After Setup
+
+1. Ensure prerequisites are met: `agentic-framework mcp check`
+2. Seed knowledge bases: `agentic-framework mcp seed`
+3. In Claude session:
+   - Activate Serena: `activate_project("YOUR_PROJECT")`
+   - Search Graphiti: `search_memory_facts("context", group_ids=["YOUR_GROUP"])`

package/framework/modules/core/commands/cmd-mcp-status.md

@@ -0,0 +1,70 @@
+---
+description: Show MCP integration status for a project
+cli-command: agentic-framework mcp status
+---
+
+# MCP Status
+
+Shows the current MCP integration status for a project, including configuration, files, and prerequisites.
+
+## What Gets Shown
+
+### Configuration
+- Whether MCP is enabled
+- Graphiti group ID
+- Serena project name and language
+
+### Files
+- .serena/project.yml existence
+- Session start hook
+- Session end hook
+
+### Prerequisites
+- Docker and Graphiti container status
+- uvx and Serena availability
+
+### Ready Status
+- Whether Graphiti is ready to use
+- Whether Serena is ready to use
+
+## Usage
+
+```bash
+# Show status
+agentic-framework mcp status
+
+# JSON output (for scripting)
+agentic-framework mcp status --json
+
+# For a different project
+agentic-framework mcp status --path /path/to/project
+```
+
+## Example Output
+
+```
+MCP Integration Status
+
+Configuration:
+  ✓ MCP enabled
+  ✓ Graphiti: my-project
+  ✓ Serena: my-project (typescript)
+
+Files:
+  ✓ .serena/project.yml
+  ✓ .claude/hooks/session-start-mcp.sh
+  ✓ .claude/hooks/session-end-graphiti.sh
+
+MCP Prerequisites Status
+
+  ✓ Docker v24.0.5
+  ✓ Graphiti containers running
+  ✓ uvx v0.1.24
+
+Ready to Use:
+  Graphiti: Yes
+  Serena:   Yes
+
+Seed knowledge bases:
+  agentic-framework mcp seed
+```

package/framework/modules/core/commands/cmd-validate-links.md

@@ -0,0 +1,42 @@
+---
+command: cmd-validate-links
+cli-command: "agentic-framework validate --links"
+module: core
+type: validate
+description: "Validate markdown links in documentation"
+related-skill: validating-links
+---
+
+# Validate Links
+
+**Command:** `agentic-framework validate --links`
+**Module:** Framework Core
+**Type:** validate
+
+## Description
+
+Validate markdown links in documentation
+
+## Usage
+
+```bash
+agentic-framework validate --links [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework validate --links
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework validate --links --help
+```
+
+## Related
+
+- **Skill:** `validating-links` - Provides detailed guidance for this command

package/framework/modules/core/commands/cmd-validate-versions.md

@@ -0,0 +1,42 @@
+---
+command: cmd-validate-versions
+cli-command: "agentic-framework validate --versions"
+module: core
+type: validate
+description: "Validate version consistency across modules"
+related-skill: managing-versions
+---
+
+# Validate Versions
+
+**Command:** `agentic-framework validate --versions`
+**Module:** Framework Core
+**Type:** validate
+
+## Description
+
+Validate version consistency across modules
+
+## Usage
+
+```bash
+agentic-framework validate --versions [options]
+```
+
+## Execution
+
+When invoked, run the CLI command:
+
+```bash
+agentic-framework validate --versions
+```
+
+Use `--help` to see all available options:
+
+```bash
+agentic-framework validate --versions --help
+```
+
+## Related
+
+- **Skill:** `managing-versions` - Provides detailed guidance for this command

package/framework/modules/core/hooks/_lib/notify-helper.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Shared notification helper
+# Auto-detects terminal (iTerm2/Warp/macOS) and sends appropriate notification.
+# Source this file from other hook scripts: source "$(dirname "$0")/_lib/notify-helper.sh"
+
+send_notification() {
+  local title="${1:-Claude Code}"
+  local message="${2:-Attention needed}"
+
+  # macOS native notification (always available)
+  if command -v osascript &>/dev/null; then
+    osascript -e "display notification \"$message\" with title \"$title\"" 2>/dev/null &
+  fi
+
+  # iTerm2 notification via escape sequence
+  if [[ "$TERM_PROGRAM" == "iTerm.app" ]]; then
+    printf "\033]9;%s\007" "$message" 2>/dev/null
+  fi
+
+  # Warp terminal notification
+  if [[ "$TERM_PROGRAM" == "WarpTerminal" ]]; then
+    printf "\033]777;notify;%s;%s\007" "$title" "$message" 2>/dev/null
+  fi
+
+  # Generic terminal bell as fallback
+  printf "\a" 2>/dev/null
+}

package/framework/modules/core/hooks/block-main-commit.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Block direct commits to main/master branch (but allow merges)
+# Handles: git -C /path commit, cd /path && git commit, and plain git commit
+
+INPUT=$(cat)
+
+# Only block commits, not merges (merges are intentional after review)
+if echo "$INPUT" | grep -qE '"command".*git commit' && ! echo "$INPUT" | grep -qE '"command".*git merge'; then
+  # Extract the command from JSON
+  CMD=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | sed 's/"command"\s*:\s*"//' | sed 's/"$//')
+
+  # Try to extract directory from git -C flag
+  GIT_DIR=$(echo "$CMD" | grep -oE 'git -C [^ ]+' | sed 's/git -C //')
+
+  # Try to extract directory from cd command (handles "cd /path && git commit")
+  if [ -z "$GIT_DIR" ]; then
+    GIT_DIR=$(echo "$CMD" | grep -oE '^\(cd [^)&]+' | sed 's/^(cd //' | sed 's/ *$//')
+  fi
+  if [ -z "$GIT_DIR" ]; then
+    GIT_DIR=$(echo "$CMD" | grep -oE '^cd [^;&]+' | sed 's/^cd //' | sed 's/ *$//')
+  fi
+
+  # Get branch from the appropriate directory
+  if [ -n "$GIT_DIR" ] && [ -d "$GIT_DIR" ]; then
+    BRANCH=$(git -C "$GIT_DIR" branch --show-current 2>/dev/null)
+  else
+    BRANCH=$(git branch --show-current 2>/dev/null)
+  fi
+
+  if echo "$BRANCH" | grep -qE '^(main|master)$'; then
+    echo "BLOCKED: Do not commit directly to $BRANCH. Use a feature branch or worktree." >&2
+    exit 2
+  fi
+fi
+exit 0

package/framework/modules/core/hooks/notify.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Notification Hook (Notification:permission_prompt|idle_prompt)
+# Sends macOS notification and terminal escape when Claude needs attention.
+# Advisory — never blocks.
+
+# Read stdin JSON from Claude Code
+INPUT=$(cat)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared notification helper
+if [[ -f "$SCRIPT_DIR/_lib/notify-helper.sh" ]]; then
+  source "$SCRIPT_DIR/_lib/notify-helper.sh"
+else
+  # Inline fallback if helper not found
+  send_notification() {
+    local title="${1:-Claude Code}"
+    local message="${2:-Attention needed}"
+    if command -v osascript &>/dev/null; then
+      osascript -e "display notification \"$message\" with title \"$title\"" 2>/dev/null &
+    fi
+    printf "\a" 2>/dev/null
+  }
+fi
+
+# Determine notification type from hook matcher context
+# Claude Code passes the event type in the hook context
+EVENT_TYPE=$(echo "$INPUT" | jq -r '.hook_event_name // "notification"' 2>/dev/null)
+MATCHER=$(echo "$INPUT" | jq -r '.hook_matcher // empty' 2>/dev/null)
+
+case "$MATCHER" in
+  permission_prompt)
+    send_notification "Claude Code" "Permission needed — please approve or deny"
+    ;;
+  idle_prompt)
+    send_notification "Claude Code" "Waiting for your input"
+    ;;
+  *)
+    send_notification "Claude Code" "Attention needed"
+    ;;
+esac
+
+exit 0

package/framework/modules/core/hooks/post-write-format.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Post-Write Format Hook (PostToolUse:Write|Edit)
+# Auto-formats files with prettier/eslint if config exists.
+# Advisory, runs async — never blocks.
+
+# Read stdin JSON from Claude Code
+INPUT=$(cat)
+
+# Extract the file path from tool input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty' 2>/dev/null)
+
+if [[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+cd "$PROJECT_ROOT" || exit 0
+
+# Only format files within the project
+case "$FILE_PATH" in
+  "$PROJECT_ROOT"*) ;;
+  *) exit 0 ;;
+esac
+
+# Get file extension
+EXT="${FILE_PATH##*.}"
+
+# Check for prettier and format supported file types
+if [[ -f "$PROJECT_ROOT/.prettierrc" || -f "$PROJECT_ROOT/.prettierrc.json" || -f "$PROJECT_ROOT/.prettierrc.yml" || -f "$PROJECT_ROOT/prettier.config.js" || -f "$PROJECT_ROOT/prettier.config.mjs" ]]; then
+  case "$EXT" in
+    ts|tsx|js|jsx|json|css|scss|md|yaml|yml|html)
+      if command -v npx &>/dev/null; then
+        npx prettier --write "$FILE_PATH" 2>/dev/null &
+      fi
+      ;;
+  esac
+fi
+
+# Check for eslint and fix supported file types
+if [[ -f "$PROJECT_ROOT/.eslintrc" || -f "$PROJECT_ROOT/.eslintrc.json" || -f "$PROJECT_ROOT/.eslintrc.js" || -f "$PROJECT_ROOT/eslint.config.js" || -f "$PROJECT_ROOT/eslint.config.mjs" ]]; then
+  case "$EXT" in
+    ts|tsx|js|jsx)
+      if command -v npx &>/dev/null; then
+        npx eslint --fix "$FILE_PATH" 2>/dev/null &
+      fi
+      ;;
+  esac
+fi
+
+exit 0

package/framework/modules/core/hooks/post-write-validate.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Post-Write Validation Hook
+# Validates files after they are written (advisory mode)
+#
+# This wrapper script invokes the compiled TypeScript hook.
+# Deploy to: .claude/hooks/post-write-validate.sh
+
+# Find the framework CLI
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+# Try to find the CLI in different locations
+if [ -f "$PROJECT_ROOT/framework/cli/dist/hooks/post-write-validate.js" ]; then
+  CLI_HOOKS="$PROJECT_ROOT/framework/cli/dist/hooks"
+elif [ -f "$PROJECT_ROOT/node_modules/agentic-framework/dist/hooks/post-write-validate.js" ]; then
+  CLI_HOOKS="$PROJECT_ROOT/node_modules/agentic-framework/dist/hooks"
+else
+  # Hook not available, pass through
+  cat
+  exit 0
+fi
+
+# Run the TypeScript hook
+node "$CLI_HOOKS/post-write-validate.js"

package/framework/modules/core/hooks/pre-bash-safety.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Pre-Bash Safety Hook (PreToolUse:Bash)
+# Blocks destructive commands like rm -rf /, force push to main.
+# BLOCKING — exits with code 2 to prevent execution.
+
+# Read stdin JSON from Claude Code
+INPUT=$(cat)
+
+# Extract the command from the tool input JSON
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# Destructive filesystem patterns
+if echo "$COMMAND" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|--recursive\s+--force|-[a-zA-Z]*f[a-zA-Z]*r)\s+/\s*$'; then
+  echo "BLOCKED: 'rm -rf /' detected. This would destroy the entire filesystem."
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|--recursive\s+--force|-[a-zA-Z]*f[a-zA-Z]*r)\s+/\*'; then
+  echo "BLOCKED: 'rm -rf /*' detected. This would destroy the entire filesystem."
+  exit 2
+fi
+
+# Force push to main/master
+if echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force.*\s+(origin\s+)?(main|master)\b'; then
+  echo "BLOCKED: Force push to main/master detected. This rewrites shared history."
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+push\s+.*-f\s+.*\s+(origin\s+)?(main|master)\b'; then
+  echo "BLOCKED: Force push to main/master detected. This rewrites shared history."
+  exit 2
+fi
+
+# Drop all tables
+if echo "$COMMAND" | grep -qiE 'DROP\s+(DATABASE|TABLE)\s+.*\*|DROP\s+SCHEMA\s+public\s+CASCADE'; then
+  echo "BLOCKED: Destructive database operation detected."
+  exit 2
+fi
+
+exit 0

package/framework/modules/core/hooks/pre-commit-skill-reminder.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Pre-Commit Skill Reminder Hook
+# Reminds agents to use committing-code skill before git commits (advisory mode)
+#
+# This wrapper script invokes the compiled TypeScript hook.
+# Deploy to: .claude/hooks/pre-commit-skill-reminder.sh
+
+# Find the framework CLI
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+# Try to find the CLI in different locations
+if [ -f "$PROJECT_ROOT/framework/cli/dist/hooks/pre-commit-skill-reminder.js" ]; then
+  CLI_HOOKS="$PROJECT_ROOT/framework/cli/dist/hooks"
+elif [ -f "$PROJECT_ROOT/node_modules/agentic-framework/dist/hooks/pre-commit-skill-reminder.js" ]; then
+  CLI_HOOKS="$PROJECT_ROOT/node_modules/agentic-framework/dist/hooks"
+else
+  # Hook not available, pass through
+  cat
+  exit 0
+fi
+
+# Run the TypeScript hook
+node "$CLI_HOOKS/pre-commit-skill-reminder.js"