A configuration framework for Claude Code CLI that adds 21 specialized agents, a real peer-review enforcement gate, an anti-drift consistency system, and intelligent task routing.
This is NOT a standalone tool — it requires Claude Code CLI as the underlying platform.
This framework extends Claude Code CLI with:
- 21 Specialized Agents covering the full development lifecycle
- Real Enforcement Hooks — a blocking peer-review Stop gate and a model-tier guard on sub-agent calls, plus session-context and delegation-hint hooks, registered via the plugin's
hooks/hooks.jsonand covered by tests - Anti-Drift Consistency System — dynamic validator, doc generator, and CI gate that keep the registry, docs, and filesystem in lockstep
- MCP Integration — 6 MCP servers ship with the plugin, covering code intelligence, file operations, documentation lookup, structured reasoning, web fetching, and a persistent code-review knowledge graph
| Requirement | Purpose |
|---|---|
| Claude Code CLI | Agent execution platform (required) |
| Git | Version control |
PowerShell 7+ (pwsh) |
Windows: runs hooks and installer scripts (7.0+ for hooks, 7.3+ for installer); Linux/macOS: optional (hooks run as POSIX shell; pwsh needed only for the optional .ps1 test suites) |
| bash + jq | Validation and doc-generation tooling (Git Bash works on Windows). On Linux/macOS, sh + jq + git are the complete hook runtime — nothing else needed. If jq is missing on POSIX hosts, enforcement is disarmed — hooks fire without enforcing anything, including the peer-review Stop gate |
| gh + yq | Command-line executor agents (bash-expert / powershell-expert): GitHub CLI queries and YAML processing; run gh auth login once. yq is mikefarah v4 |
| Node.js/npm | Required: the plugin starts the filesystem, context7 and sequential-thinking MCP servers via npx |
uv (uvx) |
Required: the plugin starts the serena, fetch and code-review-graph MCP servers via uvx |
| shellcheck | Shell-script linting (optional, used by CI) |
# macOS
brew install --cask claude-code
# Linux / WSL
curl -fsSL https://anthropic.com/install-claude.sh | sh
# Windows / Powershell
irm https://claude.ai/install.ps1 | iex
# Verify
claude --versionSix MCP servers are included in the plugin. They connect automatically at session start once the plugin is enabled, with no approval prompt, and register as plugin:agentic-framework:<server>. Run claude mcp list to see them. To switch one off, use the /mcp panel, or add its scoped name — plugin:agentic-framework:code-review-graph, for example — under the project's entry in ~/.claude.json, in that project's disabledMcpServers list (see About code-review-graph below for the exact shape; the list is per project, and the bare server name does not match).
Both runtime environment variables below are optional; /agentic-framework:setup configures them for you. Set them globally via shell profile or system settings, or copy .env.example for placeholders:
| Env Var | Purpose |
|---|---|
CONTEXT7_API_KEY |
API key for the context7 MCP server (optional) |
MCP_FS_ROOT |
Root directory for the filesystem MCP server (defaults to the current project directory) |
Servers included in the plugin:
| MCP Server | Purpose | Runtime |
|---|---|---|
| filesystem | Enhanced file operations for large files and atomic updates | Node.js (npx) |
| context7 | External documentation and best practices lookup | Node.js (npx) |
| serena | Semantic code intelligence and symbol operations | Python (uvx) |
| sequential-thinking | Structured step-by-step reasoning for complex problem decomposition | Node.js (npx) |
| fetch | Web content fetching and conversion for efficient page consumption | Python (uvx) |
| code-review-graph | Persistent incremental code knowledge graph for reviews: change impact, dead code, execution flows, semantic search (after an initial graph build — see the note below) | Python (uvx) |
The six launchers are unpinned: the manifest fixes no version, so new upstream code arrives without a plugin update. Measured 2026-09-18 on a warm cache: npx revalidates the package against the npm registry at every launch (filesystem, context7, sequential-thinking); uvx re-resolves the requirement at every launch and reuses its downloads when they are still the newest (fetch, code-review-graph); serena is different again — its source is a git URL with no ref, so each launch asks GitHub for the commit at the repository's default branch and runs that, an unreviewed push rather than a release. Whatever resolves is downloaded and executed with your user privileges before anyone has reviewed it, and a launch that cannot reach the registry or GitHub may fail. The controls this plugin documents that act before that code runs are not connecting the server (per-project disabledMcpServers, or the /mcp panel for later sessions) and a same-named server in your own user or project scope, which outranks the plugin's entry and is the supported way to run a version you pinned yourself; CRG_TOOLS and the ask rule for apply_refactor_tool (Installation step 3) narrow what a running server may do, not what it runs at launch. Cost note: serena is the bundle's session-start heavyweight (it boots language servers for the project) and code-review-graph is its per-request heavyweight (30 tools and about 37 KB of tool schema at 2.3.8, advertised to every session); if you don't use one of them, switch it off in the /mcp panel, or add its scoped name (plugin:agentic-framework:<server>) to that project's disabledMcpServers list in ~/.claude.json — see About code-review-graph below for the exact shape. Do not edit the plugin cache's .mcp.json — claude plugin update overwrites it.
serena is launched with --project-from-cwd, so it activates the repository Claude Code was started in and registers it in serena's global config (~/.serena/serena_config.yml) on first run, creating a .serena/project.yml file in the repo. Started outside a git repository, it logs a warning and starts with no project activated. Three consequences to know before you open a repository you did not write. First, activation is now automatic: serena reads the repository's own .serena/project.yml at server launch, before the first model turn and with no tool call in the transcript, and boots language servers for the project's languages (some language servers evaluate project build configuration). Second, that file may carry an activation_command, which serena executes with your privileges in the project root when — and only when — the project path matches trusted_project_path_patterns in ~/.serena/serena_config.yml. Upstream ships that list empty, which makes a committed activation_command inert; keep it empty or narrow it to directories you own, and never set it to ** on a machine where you clone other people's code. Third, serena's generated .serena/.gitignore covers only /cache and /project.local.yml, so .serena/project.yml and .serena/memories/ show up as untracked files in your repository: commit them deliberately (they are meant to be shared) or ignore .serena/ yourself. Inside a repository serena now runs in single-project mode: it does not expose activate_project or get_current_config (measured: 21 tools instead of 23), so an agent cannot switch to a different project root mid-session — a sibling worktree or a monorepo sub-project needs its own session. Outside a repository both tools are present. To opt out of automatic activation, define your own serena server in user or project scope without --project-from-cwd; it outranks the plugin's entry.
About code-review-graph — read this before your first session. Installing the framework connects this server automatically, with no approval prompt, and it ships with its full tool set, which is not read-only. apply_refactor_tool writes source files into whatever directory the model passes as repo_root — every tool that targets a single repository accepts that parameter (28 of the 30), an explicit value overrides the --repo launch flag, and the package's only guard on that root is that the target contains a .git, .svn, or .code-review-graph directory, so any checkout on your machine is reachable. cross_repo_search_tool / list_repos_tool read any other repositories registered with the tool. It is also a solo-maintained community package (MIT, no PyPI attestations as of 2.3.8). The tool counts and the root guard above were measured against 2.3.8; the manifest is unpinned, so verify them against the version you resolve. If that is not acceptable on your machine, switch it off before first use. Edit ~/.claude.json before you start a session and disable the server under the entry for the project you are about to open:
{
"projects": {
"C:/path/to/your/project": {
"disabledMcpServers": ["plugin:agentic-framework:code-review-graph"]
}
}
}Two things follow from that shape. The list is recorded per project, so you have to set it for every directory you will open; there is no machine-wide off switch for a plugin-shipped server short of disabling the whole plugin. And the scoped spelling is required — a bare code-review-graph does not match a plugin-shipped server. The /mcp panel writes the same per-project list, but it is only reachable from inside a session, by which point the server has already connected, so editing the file is the true before-first-use switch.
To keep the server but drop its write reach, set CRG_TOOLS in your environment to a comma-separated list of the tools you want — unlisted tools are removed. Being an OS environment variable, it narrows the tool set for every project at once; the server still connects, and its package is still downloaded and executed at session start. Those two knobs are the durable ones; editing the plugin cache's .mcp.json does not survive claude plugin update. The recommended settings template also adds an ask rule for apply_refactor_tool (see Installation step 3), so that one tool prompts before it writes — in the default permission mode; bypassPermissions and auto never consult the rule, so on those modes narrow with CRG_TOOLS or disable the server instead.
Its tools return nothing until a graph exists — call build_or_update_graph_tool once, or run uvx code-review-graph build in the repo (the CLI and the server should run the same package version so they agree on the database schema; after an upgrade, run uvx --refresh code-review-graph build to realign them). The graph is written to <repo>/.code-review-graph/ in every repository you point it at (the package gitignores that directory); CRG_DATA_DIR relocates it.
The framework is distributed as a single Claude Code plugin via the marketplace (no local cloning).
Installing it does more than add agents. The plugin ships six MCP servers, and they connect automatically at session start with no approval prompt — including code-review-graph, whose apply_refactor_tool can write source files (read About code-review-graph above before you install). The six launchers and their dependency closures download from npm, PyPI and GitHub on the first run after a fresh install, a cleared npm/uv cache, or a new upstream release (for serena, a new commit on its default branch), and execute with your user privileges. You can switch any server off in the /mcp panel, or before the first session by adding its scoped name to that project's disabledMcpServers list in ~/.claude.json (the About code-review-graph section above shows the exact shape).
Using the Claude Code GUI:
/plugin marketplace add tomas-rampas/agentic-framework
/plugin install agentic-framework@agentic-framework
Or via the CLI:
claude plugin marketplace add tomas-rampas/agentic-framework
claude plugin install agentic-framework@agentic-frameworkThe six MCP servers are already installed. Neither environment variable is required — the servers start without them. Inside a Claude Code session, run:
/agentic-framework:setup
It writes the two optional variables (see .env.example for placeholders):
CONTEXT7_API_KEY— optional, for the context7 MCP server; it runs keyless by default and a key only raises its rate limitsMCP_FS_ROOT— optional, filesystem server root (defaults to the current project directory)
The plugin ships settings.template.json with recommended permissions and alwaysThinkingEnabled. Merge these into your ~/.claude/settings.json:
# Inspect the template (use the versioned cache path)
cat ~/.claude/plugins/cache/agentic-framework/agentic-framework/*/settings.template.json
# (or open the plugin folder via /plugin)
# Copy permissions and alwaysThinkingEnabled into your ~/.claude/settings.json
# (do not overwrite hooks — they are registered via hooks/hooks.json in the plugin)The template's permissions.ask list includes mcp__plugin_agentic-framework_code-review-graph__apply_refactor_tool and mcp__code-review-graph__apply_refactor_tool — both name forms of the one graph tool that writes source files. ask outranks allow, so even if you later allow the whole server, that tool still prompts before it edits anything — in the default permission mode. bypassPermissions and auto do not consult permission rules at all; on those modes, narrow the server with CRG_TOOLS or disable it instead.
Hooks load and the six MCP servers connect at session start:
# Restart any running Claude Code session
claude/agentic-framework:validate-hooks
/agentic-framework:analyze-frameworkIf you have this framework cloned into ~/.claude, migrate to the plugin distribution:
# Dry-run (the default — reports what would change, makes no changes)
/agentic-framework:migrate-legacy
# Perform the migration (backs up settings.json + .claude.json, de-registers the
# framework hooks, deletes the 4 copied hook scripts, and cleans a legacy ~/.claude
# clone; add -RemoveMcp to also remove framework-shaped MCP servers)
/agentic-framework:migrate-legacy -ApplyNote: Do not run the migration on dirty working trees or unpushed commits — it will refuse to proceed. Exit codes: 0 = migration complete (or dry-run), 2 = checkout cleanup aborted (genuine uncommitted changes or unpushed commits); hook/MCP removals from the earlier steps have already been applied by then.
Upgrading from 4.3.0 or earlier: the six MCP servers used to live in a second, optional plugin. They are now part of agentic-framework itself, and the separate plugin is retired. If you installed it, uninstall it:
/plugin uninstall agentic-framework-mcp@agentic-framework
The same command works from the CLI, prefixed with claude instead of /. Leaving the retired plugin installed runs the same six servers twice, under two names.
Check your own MCP configuration too. Scope precedence is local > project > user > plugin: when the same server name is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source. This cuts both ways.
- A user-scope server in
~/.claude.jsonwith a name likeserenaorcontext7shadows the plugin's copy. Delete those entries to get the servers the plugin ships, or keep them deliberately: a same-named entry in your own user or project scope shadows the plugin's unpinned launcher, which is the supported way to run a version you pinned yourself. - A cloned repository's project
.mcp.jsonoutranks the plugin, so a familiar name likeserenain a project file can be an arbitrary command. Read a project's.mcp.jsonbefore approving it. This repository's own tracked root.mcp.jsonis exactly such a project-scope config inside a clone.
Upgrading from a pre-rename install: the marketplace name changed from claude-agentic-framework to agentic-framework. If you have an older registration, remove it first, then re-add and re-install:
In Claude Code:
/plugin marketplace remove claude-agentic-framework
/plugin marketplace add tomas-rampas/agentic-framework
/plugin install agentic-framework@agentic-framework
/reload-plugins
Restarting Claude Code has the same effect as /reload-plugins.
To check for updates (whether or not you migrated):
claude plugin marketplace update agentic-framework
claude plugin update agentic-framework@agentic-framework/plugin uninstall agentic-framework@agentic-framework
/plugin marketplace remove agentic-framework
# Clean up environment variables (optional)
# Windows PowerShell:
[Environment]::SetEnvironmentVariable('CONTEXT7_API_KEY', $null, 'User')
[Environment]::SetEnvironmentVariable('MCP_FS_ROOT', $null, 'User')
# macOS/Linux: remove the export lines from ~/.zshrc, ~/.bashrc, or ~/.bash_profile
# (see the setup command's "To undo" section for the exact lines to remove)Plugin marketplace add fails: ensure you use the exact owner/repo form (tomas-rampas/agentic-framework), a git clone URL, or a local checkout path. Note that adding the marketplace directly via a URL to marketplace.json itself is unsupported (its relative plugin source ./ cannot resolve without repo context).
MCP servers not available: restart Claude Code; the servers connect at session start. Run claude mcp list to verify they are registered, and /plugin list to verify agentic-framework is installed. A server you disabled in /mcp stays disabled for that project until you re-enable it there.
Hooks not firing after restart: verify the agentic-framework plugin is installed: /plugin list. If missing, re-run /plugin install agentic-framework@agentic-framework.
# Start Claude Code CLI
claude
# Or start with a specific task
claude "Create a REST API in Rust with JWT authentication"Tasks are automatically routed to the appropriate agent. Examples:
"Create user stories for authentication feature" → product-owner
"Design microservices architecture" → system-architect
"Implement JWT authentication in Rust" → rust-expert
"Create ASP.NET Core REST API with Entity Framework" → csharp-expert
"Build gRPC microservice in Go" → go-expert
"Build a Fisher Transform indicator for MetaTrader 5" → mql-trading-dev
"Review pull request for code quality" → code-review-gatekeeper
"Set up Kubernetes deployment with Helm" → devops-orchestrator
"Write API documentation for REST endpoints" → technical-docs-writer
"Analyze codebase security vulnerabilities" → comprehensive-analyst
How the commands, self-scoring loop, review chain, and Stop gate fit together:
| Agent | Focus |
|---|---|
| product-owner | User stories, backlog management, acceptance criteria |
| Agent | Focus |
|---|---|
| system-architect | System design, technology selection, SOLID principles |
| comprehensive-analyst | Security audits, performance profiling, investigation |
| code-review-gatekeeper | Code review, quality gates, standards compliance |
| peer-review-critic | Final independent peer review — diff-scoped gatekeeper (branch vs base) |
| spec-compliance-reviewer | Requirement-by-requirement spec conformance review (specs/.md) |
| Agent | Focus |
|---|---|
| rust-expert | Systems programming, memory safety, async/await |
| csharp-expert | ASP.NET Core, Entity Framework, Azure |
| go-expert | Microservices, gRPC, Kubernetes operators |
| java-expert | Spring Boot, Maven/Gradle, enterprise apps |
| python-expert | Django/Flask, data science, automation |
| typescript-expert | React/Next.js, Node.js, frontend/backend |
| mql-trading-dev | MQL4/MQL5, C/C++ DLLs, MetaTrader trading systems |
| Agent | Focus |
|---|---|
| bash-expert | Command-line executor; shell scripting, Linux/CI automation |
| powershell-expert | Windows command-line executor; PowerShell automation |
| Agent | Focus |
|---|---|
| database-specialist | Schema design, query optimization, SQL/NoSQL |
| frontend-specialist | React/Vue/Angular, responsive design, accessibility |
| security-specialist | Vulnerability assessment, compliance, auth |
| uiux-specialist | User flows, design systems, wireframing |
| Agent | Focus |
|---|---|
| devops-orchestrator | CI/CD, containers, cloud deployment, monitoring |
| technical-docs-writer | API docs, user guides, architecture docs |
The most capable model orchestrates; the cheapest model that can do the job does the job. Every agent carries a default tier in its frontmatter (model:), mirrored in claude.json and in the Default tier column of the agent table in CLAUDE.md: review gates, security and architecture run on opus; language experts, domain specialists, analysis and planning on sonnet; executors, docs and UI/UX on haiku. The orchestrating session chooses the model on every delegation through the Agent tool's model parameter — one tier down for mechanical work, one tier up (with the reason stated) for concurrency, auth/crypto, large refactors or after two failed review rounds — and never runs a sub-agent on its own top tier. Built-in agents (Explore, Plan, general-purpose, claude) have no default tier and would inherit the parent's model, so they always get an explicit one: the orchestrator passes it, and when it does not, the pretooluse-model-guard hook fills it in automatically (haiku for Explore, sonnet for the others) with nothing to configure (on POSIX hosts the hook needs jq, like every hook here; without it the hook enforces nothing). The same hook denies the top tier and every fork. Setting CLAUDE_CODE_SUBAGENT_MODEL=sonnet in your settings env is optional: it additionally covers agents the hook cannot recognise (your own, or another plugin's, when their definition has no model:). Rationale and measurements: docs/design/model-tiering.md.
The framework distributes as one plugin:
<plugin root>* # ~/.claude/plugins/cache/agentic-framework/agentic-framework/<version>/
├── CLAUDE.md # Agent execution rules and task routing
├── claude.json # Agent registry (single source of truth for the tooling)
├── settings.template.json # Recommended permissions + alwaysThinkingEnabled
├── .mcp.json # MCP server definitions (filesystem, context7, serena, sequential-thinking, fetch, code-review-graph)
├── agents/ # 21 agent definitions (.md with YAML frontmatter)
├── commands/ # 12 namespaced commands (delegate, spec, build, review-spec, log-triage, etc.)
│ └── setup.md # Configures the two MCP environment variables (both optional)
├── hooks/ # Real hook scripts + hooks/hooks.json registration (peer-review Stop gate, recorder, session context, delegation hint)
├── skills/ # Operational skills
├── scripts/ # Validation, anti-drift consistency, and doc-generation scripts
├── tests/ # Consistency + hook test harnesses
├── docs/design/ # Design rationale for the hook architecture
├── .github/workflows/ # CI (anti-drift consistency gate)
└── security-check.sh # Security validation
* is the plugin cache path: ~/.claude/plugins/cache/agentic-framework/agentic-framework/<version>/
Note: Commands are namespaced as /agentic-framework:<name>. For example, /agentic-framework:spec instead of /spec.
| Command | Purpose |
|---|---|
/agentic-framework:delegate |
End-to-end orchestration: auto-runs the spec interview when no source of truth exists, then hands off to build (single feature) or per-todo orchestration (multi-domain) |
/agentic-framework:analyze-framework |
Framework health checking and validation |
/agentic-framework:list-agents |
Agent catalog with filtering and multiple output formats |
/agentic-framework:validate-hooks |
Hook coverage and consistency verification |
/agentic-framework:agent-status |
Agent configuration status and health assessment |
/agentic-framework:quality-report |
Quality metrics, trend analysis, and reporting |
/agentic-framework:setup |
Configure the two MCP environment variables, CONTEXT7_API_KEY and MCP_FS_ROOT (both optional) |
| Command | Purpose |
|---|---|
/agentic-framework:log-triage |
Local, deterministic log triage: streams large log files (text, JSON/NDJSON, CSV, XML, syslog, access logs, container/cloud exports), groups recurring issues by stable fingerprint, assesses severity with observed/inferred/unknown labels, attributes issues to Git repositories, and exports JSON, SARIF 2.1.0, HTML, Markdown, CSV and NDJSON reports — see docs/log-triage/README.md |
The self-correcting spec → build → review loop: the system, not the user, catches the gaps.
| Command | Purpose |
|---|---|
/agentic-framework:spec |
Interview the user one question at a time, then write specs/<name>.md with checkable acceptance criteria and a definition of done |
/agentic-framework:build |
Build exactly what the spec says, then loop build ⇆ spec-compliance-reviewer until VERDICT: APPROVED (max 3 iterations) |
/agentic-framework:review-spec |
Manual conformance check: per-requirement PASS/FAIL of the current build against the spec, without entering the loop |
For legacy clones being migrated to plugins, there is also:
| /agentic-framework:migrate-legacy | Migrate a local ~/.claude clone to the plugin distribution |
The framework ships operational skills in skills/<name>/SKILL.md (the layout Claude Code loads):
| Skill | Purpose |
|---|---|
| agent-debugger | Diagnose agent routing, loading, and configuration issues |
| agent-routing-advisor | Recommend the right specialist agent for a task |
| code-scaffolder | Generate idiomatic project scaffolding for supported languages |
| code-scoring-loop | Rubric-based score → rewrite → rescore loop for code diffs, scored by the specialist agents before the review gates |
| dependency-checker | Verify the toolchain the framework needs (git, jq, pwsh 7, node, uv) |
| git-workflow-assistant | Guide branching, commit conventions, and PR workflows (incl. the peer-review gate) |
| hook-config-generator | Guide for adding a new real hook (script + registration + tests) |
| refactoring-advisor | Identify refactoring opportunities and improvement patterns |
| self-scoring-loop | Rubric-based score → rewrite → rescore loop for non-code deliverables |
The framework ships real Claude Code hooks via the agentic-framework plugin in hooks/hooks.json. Each hook is registered as a shell-form fallback chain: sh "${CLAUDE_PLUGIN_ROOT}/hooks/dispatch.sh" <name> || pwsh -NoProfile -File "${CLAUDE_PLUGIN_ROOT}/hooks/<name>.ps1". On Linux/macOS, the dispatcher runs the POSIX shell script; on Windows, it runs the PowerShell script. Each hook exists as both a .ps1 (PowerShell 7) and .sh (POSIX shell) pair.
| Hook | Event | Behavior |
|---|---|---|
stop-peer-review-gate (.ps1/.sh pair) |
Stop |
Blocking. Refuses to end a session while a feature branch has committed work ahead of its base and the latest peer-review-critic run did not record VERDICT: APPROVED — one block if no review ran, up to 3 while the verdict is CHANGES_REQUIRED. Loop-safe, fail-open (legacy no-verdict markers unlock). Accepts bare and plugin-scoped reviewer names. |
record-subagent-run (.ps1/.sh pair) |
PostToolUse + SubagentStop |
Records each peer-review-critic run as a per-session marker, parsing the report's machine-readable VERDICT: line into it (the verdict the Stop gate enforces). |
session-start-context (.ps1/.sh pair) |
SessionStart |
Injects branch/review status into the session context at startup. |
pretooluse-delegation-hint (.ps1/.sh pair) |
PreToolUse |
Advisory: suggests the matching specialist subagent when a technology-specific file is written (once per session per agent). |
pretooluse-model-guard (.ps1/.sh pair) |
PreToolUse (Task|Agent) |
Blocking and rewriting. The model-tier ceiling, automatic with nothing to configure (POSIX hosts need jq, or the hook enforces nothing): denies a sub-agent call whose model names the top tier (fable, in any spelling or as a full model id), denies every fork (a fork always runs on its parent's model), and rewrites a built-in agent call (Explore, Plan, general-purpose, claude, or no type) that carries no model — it sets haiku for Explore and sonnet for the rest, echoes every other field back unchanged, and lets the call proceed without touching your permission rules (when CLAUDE_CODE_SUBAGENT_MODEL is set to a usable tier the hook stays out of the way and the variable decides). It is not a general ceiling: an agent type the hook does not know (your own, or another plugin's) is neither denied nor rewritten, because its frontmatter is invisible to the hook; if that definition has no model: it inherits the caller's tier, and CLAUDE_CODE_SUBAGENT_MODEL is the cover. Fail-open on any payload it cannot parse; AF_MODEL_GUARD=off disables it. |
Design rationale (including why the legacy TDD hard block was retired) lives in docs/design/. The hook scripts are tested by tests/hooks.test.ps1 (PowerShell) and tests/hooks.test.sh (POSIX), and /agentic-framework:validate-hooks asserts pair parity: every registered hook has both .ps1 and .sh implementations, every registered script exists and is paired, all event names are valid. An equivalence test tests/hooks-equivalence.test.sh verifies the two implementations produce identical output on systems where both interpreters are present (primarily CI).
Claude Code CLI not found:
which claude # If missing, reinstall per the Prerequisites sectionMCP servers not available:
claude mcp list # What Claude Code sees
# If empty: restart Claude Code, or run /plugin list to verify agentic-framework is installed
# A server you disabled in /mcp stays disabled per project until re-enabled thereAgents not found or not loading:
/agentic-framework:list-agents # Verify agents are available
/agentic-framework:analyze-framework # Framework health checkHooks not firing or Stop gate misbehaving:
/agentic-framework:validate-hooks # Hook pair parity and dispatch check
# If hooks are not firing after setup, restart Claude Code (hooks load at session start)Hooks fire but nothing is enforced (peer-review gate not blocking):
On Linux/macOS, if jq is missing from PATH, the hook scripts load and fire (visible in the transcript), but enforcement is disarmed — nothing gets enforced, including the peer-review Stop gate. Cause: the POSIX hook implementations depend on jq to validate the hook JSON payload; without it, hooks skip enforcement. Fix: install jq with your system package manager (apt-get install jq on Debian/Ubuntu; brew install jq on macOS), then restart Claude Code. When jq is absent, the SessionStart hook prints a [session-context] warning line at session start — this confirms the symptom is active.
Harmless "sh: not found" stderr on Windows without Git Bash:
When Git Bash is not installed, the hook chain's sh command fails with a "not found" error line in the transcript. This is harmless — the || arm runs the PowerShell .ps1 script directly. (Installing Git Bash removes the noise and speeds hooks up: sh then exists and dispatch.sh detects MINGW*/MSYS*/CYGWIN*, running the POSIX .sh implementation directly when jq is on PATH — which skips a pwsh cold start of roughly 1–2 seconds on every hook fire — and routing to the same PowerShell script otherwise.)
Hooks feel slow, or fire twice:
Two known causes. First, on Windows without jq in Git Bash, every hook fire pays a pwsh cold start — install jq (winget install jqlang.jq) so the dispatcher can take the POSIX fast path described above. Second, if you migrated from a pre-v4 (pre-plugin) install, the legacy hook entries may still sit in ~/.claude/settings.json alongside the plugin's hooks/hooks.json registration, making every hook fire twice. Run /agentic-framework:validate-hooks — it warns on exactly this — and remove the legacy entries (/agentic-framework:migrate-legacy automates the cleanup).
Plugin installation failed:
See Upgrading from a pre-rename install under Updating the Plugin if you have a pre-rename registration — you must remove the old registration first.
/plugin list # Check installed plugins
/plugin marketplace add tomas-rampas/agentic-framework # Re-add to marketplace
/plugin install agentic-framework@agentic-framework # Re-installMarketplace name suffix vs. GitHub path:
When installing a plugin, use the full <name>@<marketplace> form where <marketplace> is the marketplace's registered name (the "name" field in .claude-plugin/marketplace.json) — here, agentic-framework. The repo segment of the GitHub path now matches that name, but the two remain distinct values: /plugin marketplace add takes the owner/repo path, while the @ suffix — and marketplace update and marketplace remove — take the registered marketplace name.
/plugin install agentic-framework@agentic-framework
Alternatively, once the marketplace is added, the bare plugin name also works: /plugin install agentic-framework. The CLI reference documents <plugin> as "plugin name or plugin-name@marketplace-name", so the bare form is supported — but prefer the qualified form: it's unambiguous if another registered marketplace ever ships a plugin with the same name.
Windows MAX_PATH limit during marketplace clone: On deeply nested Windows paths, marketplace clone fails with "Filename too long" at the 260-character limit. Remediation: enable Windows 10+ long paths in two steps (both required). First, run this PowerShell command as Administrator:
Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' LongPathsEnabled 1 -Type DWordThen configure Git for long paths:
git config --global core.longpaths trueRestart Claude Code, then re-run the marketplace add and install from Plugin installation failed above. Without both steps, the "Filename too long" error will recur.
Running the shell test suites or validators manually on Windows:
If you are running the test suites manually on Windows, use the Git Bash bash.exe directly (not WSL's bash, which may be on PATH by default): C:\Program Files\Git\bin\bash.exe -c 'bash tests/hooks.test.sh'. Bare bash without a full path may resolve to WSL bash, which will fail or behave incorrectly.
Migrating from a legacy local clone:
/agentic-framework:migrate-legacy # Dry-run (default; no changes)
/agentic-framework:migrate-legacy -Apply # Perform migration
/agentic-framework:analyze-framework # Verify successTo add or modify agents, manage framework consistency, or understand the anti-drift validation system, see CONTRIBUTING.md.
This project is licensed under the Apache License 2.0.
Built for Claude Code CLI • 21 Specialized Agents • 5 Hook Scripts • 9 Skills • 12 Commands • v4.5.1