Skip to content

TheSemicolon/agent-framework

BranchesTags

Repository files navigation

Agent Framework

Personal AI coding assistant configuration — skills, agents, rules, and settings — managed as a git repo and symlinked into ~/.claude/ and ~/.copilot/ for use across all projects and machines. Supports both Claude Code and GitHub Copilot (CLI and VS Code).

Contents

Purpose

This repo is the single source of truth for user-level AI assistant customization. It exists so that every new Claude Code or Copilot CLI instance — on any machine, in any project — inherits the same skills, behavioral rules, custom agents, and settings.

The architecture is skills-first: domain expertise lives in shared SKILL.md files (agentskills.io format) that both Claude Code and Copilot discover natively. Thin platform-specific agent wrappers add tool restrictions, model choices, and platform-specific behavior. Setup symlinks the repo into ~/.claude/ (Claude Code) and ~/.copilot/ (Copilot CLI).

Security Advisory — Expertise Pipeline Removal

This framework previously included an automated expertise pipeline that injected externally-stored knowledge into the AI assistant's system context on every prompt submission. That pipeline has been removed.

What was removed

  • The UserPromptSubmit hook (hooks/expertise-preflight.sh) that called an external API on every prompt and emitted the response as systemMessage
  • The expertise-curator skill and agent (the API write gateway)
  • The shared expertise-surfacing skill and the multi-hop write path that auto-routed expertise-candidate blocks from subagents into the store
  • The expertise-lookup skill and agent (the API read-only query interface)
  • The repo-local .expertise/ offline queue, the offline-flush script, the benchmark harness, and all paired Copilot configs and rule/instruction pairs

Why

The hook injected content from ${EXPERTISE_API_URL}/expertise/search into the harness system role with no signing, provenance, or user review. Both Claude Code and VS Code Copilot treat systemMessage from a UserPromptSubmit hook as harness-level instruction — equivalent privilege to CLAUDE.md and loaded rules. A compromised endpoint could dictate session behavior with the full blast radius of the session's tool allowlist. This is structurally identical to the MCP-server threat the project rejects in rules/no-mcp-servers.md (OWASP ASI04, citing CVE-2025-59536 and CVE-2026-21852).

A multi-hop write path (subagent → expertise-candidate block → curator → store → next session preflight) closed a self-poisoning loop with no human review at any stage. The default URL was hardcoded in both settings.json and the script, making the threat live by default for any user who ran setup.sh.

ADR-046 records the full threat model and supersedes the prior expertise-pipeline ADRs (009, 010, 019, 024, 043, 044). The no-mcp-servers policy has been extended to explicitly cover network-sourced systemMessage injection from any runtime mechanism, not just MCP as a protocol.

What's next

A future, safer mechanism for sharing lessons-learned across sessions is being designed separately. Candidate approaches under consideration include signed local snapshots, signature verification with allowlisted public keys, and tool-call retrieval where the agent makes the request as a visible tool invocation rather than a silent hook. The previously-stored expertise data has been backed up; once the new design lands, that data can be reviewed and re-fed into it.

Repository Structure

.agent-framework/
├── README.md              # You are here
├── AGENTS.md              # Cross-platform source of truth for conventions
├── CLAUDE.md              # Claude Code-specific configuration (thin, points to AGENTS.md)
├── CONTRIBUTING.md        # Agent authoring guidelines and three-file pattern
├── .gitignore             # Prevents secrets from being committed
├── setup.sh               # Automated setup — symlinks into ~/.claude/ and ~/.copilot/
├── validate.sh            # Pre-push consistency checker (enforces three-file pattern)
├── settings.json          # Claude Code user-level settings
├── standards/             # Team-wide technology and tooling standards
│   ├── documentation.md   # Markdown formatting, README, and CLAUDE.md conventions
│   └── tooling.md         # Primary languages, frameworks, platforms, and tools
├── adrs/                  # Architecture Decision Records (MADR format)
├── scripts/               # Utility scripts
│   ├── scaffold.sh        # Scaffolds new skill or rule from templates
│   └── setup-repo.sh      # Repo initialization helper
├── templates/             # Scaffolding templates
│   ├── skill/             # SKILL.md, agent.md, copilot-agent.agent.md
│   └── rule/              # rule.md, instruction.instructions.md
├── skills/                # Shared expertise (agentskills.io SKILL.md format)
│   ├── ai-crossplatform-expert/
│   │   └── SKILL.md       # Cross-platform format translation knowledge
│   ├── ansible-expert/
│   │   └── SKILL.md       # Ansible playbook authoring and CI/CD patterns
│   ├── azure-devops-expert/
│   │   └── SKILL.md       # Azure DevOps pipelines, repos, and boards
│   ├── code-review-expert/
│   │   └── SKILL.md       # Semantic code review dimensions and strategy
│   ├── checkmarx-expert/
│   │   └── SKILL.md       # Checkmarx One CLI scanning and CI/CD integration
│   ├── docs-expert/
│   │   └── SKILL.md       # Documentation best practices and Mermaid diagrams
│   ├── docker-expert/
│   │   └── SKILL.md       # Docker, BuildKit, multi-stage builds, Compose v2
│   ├── dotnet-expert/
│   │   └── SKILL.md       # .NET 10 LTS SDK, ASP.NET Core, EF Core
│   ├── gh-cli-expert/
│   │   └── SKILL.md       # GitHub CLI command reference and patterns
│   ├── gitflow-expert/
│   │   └── SKILL.md       # Git workflow guidance and best practices
│   ├── helm-expert/
│   │   └── SKILL.md       # Helm 3 chart authoring and release management
│   ├── kitty-agent/
│   │   └── SKILL.md       # Kitty terminal config format, kittens, sessions
│   ├── linter/
│   │   └── SKILL.md       # Multi-tool linting patterns and auto-fix
│   └── shell-expert/
│       └── SKILL.md       # Shell scripting compatibility, idioms, and security
├── agents/                # Claude Code user-level agent wrappers (thin)
│   ├── ai-crossplatform-expert.md
│   ├── ansible-expert.md
│   ├── azure-devops-expert.md
│   ├── checkmarx-expert.md
│   ├── code-review-expert.md
│   ├── docs-expert.md
│   ├── docker-expert.md
│   ├── dotnet-expert.md
│   ├── gh-cli-expert.md
│   ├── gitflow-expert.md
│   ├── helm-expert.md
│   ├── kitty-agent.md
│   ├── linter.md
│   └── shell-expert.md
├── copilot/               # GitHub Copilot configuration
│   ├── agents/            # Copilot CLI agent wrappers (self-contained)
│   │   ├── ai-crossplatform-expert.agent.md
│   │   ├── ansible-expert.agent.md
│   │   ├── azure-devops-expert.agent.md
│   │   ├── checkmarx-expert.agent.md
│   │   ├── code-review-expert.agent.md
│   │   ├── docs-expert.agent.md
│   │   ├── docker-expert.agent.md
│   │   ├── dotnet-expert.agent.md
│   │   ├── gh-cli-expert.agent.md
│   │   ├── gitflow-expert.agent.md
│   │   ├── helm-expert.agent.md
│   │   ├── kitty-agent.agent.md
│   │   ├── linter.agent.md
│   │   └── shell-expert.agent.md
│   └── instructions/      # Copilot instruction files (mirrors rules/)
│       ├── adr-required.instructions.md
│       ├── agent-first-selection.instructions.md
│       ├── conventional-commits.instructions.md
│       ├── debian-baseline.instructions.md
│       ├── github-flow.instructions.md
│       ├── no-mcp-servers.instructions.md
│       ├── orchestrator-protocol.instructions.md
│       ├── plan-before-code.instructions.md
│       ├── post-implementation-review.instructions.md
│       ├── pr-template-standard.instructions.md
│       ├── research-parallelism.instructions.md
│       ├── script-output-conventions.instructions.md
│       ├── semver-tagging.instructions.md
│       └── structured-review-format.instructions.md
├── hooks/                 # Shell scripts for Claude Code, Copilot, and git hooks
│   ├── bash-destructive-guard.sh
│   ├── secrets-guard.sh
│   ├── stop-preflight-check.sh
│   ├── worktree-create.sh
│   └── worktree-remove.sh
└── rules/                 # Claude Code user-level behavioral rules
    ├── adr-required.md
    ├── agent-first-selection.md
    ├── conventional-commits.md
    ├── debian-baseline.md
    ├── github-flow.md
    ├── no-mcp-servers.md
    ├── orchestrator-protocol.md
    ├── plan-before-code.md
    ├── post-implementation-review.md
    ├── pr-template-standard.md
    ├── research-parallelism.md
    ├── script-output-conventions.md
    ├── semver-tagging.md
    └── structured-review-format.md

Quick Start

# 1. Clone the repo
git clone git@github.com:TheSemicolon/agent-framework.git ~/.agent-framework

# 2. Run setup (creates symlinks, backs up any existing files)
~/.agent-framework/setup.sh

That's it. The setup script handles everything — see Installation for details.

How It Works

Settings

Claude Code (settings.json): Symlinked to ~/.claude/settings.json. Controls model defaults, performance tuning, hooks, and permissions across all projects.

Current configuration:

{
  "effortLevel": "high",
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet",
    "MAX_THINKING_TOKENS": "32000",
    "BASH_DEFAULT_TIMEOUT_MS": "120000",
    "BASH_MAX_TIMEOUT_MS": "600000"
  }
}
Setting Value Purpose
effortLevel high Deep thinking on every task
CLAUDE_CODE_SUBAGENT_MODEL sonnet Subagents use Sonnet — balances speed and quality for parallel research
MAX_THINKING_TOKENS 32000 Extended thinking budget for deeper reasoning
BASH_DEFAULT_TIMEOUT_MS 120000 (2 min) Default timeout for bash commands
BASH_MAX_TIMEOUT_MS 600000 (10 min) Max timeout for long-running commands (builds, tests)

Other available settings:

Setting Type Purpose
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE env var Trigger context compaction earlier (default ~95%, lower = more aggressive)
CLAUDE_CODE_MAX_OUTPUT_TOKENS env var Cap output tokens per request
MCP_TIMEOUT env var MCP server startup timeout (ms)
MCP_TOOL_TIMEOUT env var MCP tool execution timeout (ms)
BASH_MAX_OUTPUT_LENGTH env var Max chars in bash output before truncation

GitHub Copilot: Copilot does not use settings.json. Copilot configuration lives in:

  • VS Code: settings.json under chat.* keys (e.g., chat.agentSkillsLocations, chat.agentFilesLocations) — object maps of paths to booleans, additive to defaults. The github.copilot.chat.* namespace is not honored.
  • Copilot CLI: Environment variables and ~/.config/github-copilot/ configuration
  • Project-level: .github/copilot-instructions.md for always-on instructions

Copilot has no equivalent of Claude Code's effortLevel or MAX_THINKING_TOKENS. Both VS Code Copilot and Copilot CLI support hooks (8 events each, command type only), but with limited actionability compared to Claude Code — see Hooks for details. Behavioral tuning on Copilot is done through instruction file content, not runtime settings.

Rules and Instructions

Rules and instructions govern AI assistant behavior across both platforms. Each behavioral convention has two files:

  • rules/<name>.md — Claude Code rule (loaded automatically at session start)
  • copilot/instructions/<name>.instructions.md — Copilot instruction (condensed mirror)

Claude Code rules use YAML frontmatter:

---
description: 'Short description used to decide when the rule is relevant'
paths: "*.py"              # Optional — scope the rule to specific file patterns
---

Rule content here.
  • Rules without a paths field apply universally.
  • Rules with a paths field only activate when working with matching files.
  • Project-level rules (.claude/rules/) take precedence over user-level rules on conflict.

Copilot instructions use YAML frontmatter with applyTo for scoping:

---
description: 'Short description for relevance matching'
applyTo: '**'             # Glob pattern — ** for global, *.py for Python, etc.
---

Condensed instruction content here.
  • Instructions with applyTo: '**' apply to all interactions.
  • Copilot instructions are typically condensed versions of the full Claude rules, noting platform-specific caveats (e.g., sequential agent invocation instead of parallel).
  • Project-level instructions live in .github/instructions/ and are additive with user-level instructions.

Agents

Each agent has two wrappers — one per platform — following the three-file pattern:

  • agents/<name>.md — Claude Code wrapper (thin, delegates to SKILL.md via skills:)
  • copilot/agents/<name>.agent.md — Copilot wrapper (self-sufficient, inlines key knowledge)

Claude Code agents use YAML frontmatter:

---
name: agent-name
description: What this agent does
model: opus                # Optional — default model for this agent
tools: Read, Grep, Glob    # Optional — restrict available tools
skills:
  - skill-name             # Injects SKILL.md content at startup
---

Agent system prompt here.

Claude agents can be invoked via the --agent flag, the Agent tool, or @name in sessions.

Copilot agents use a different frontmatter set:

---
description: What this agent does
name: agent-name
tools:
  - read
  - search
  - web
---

Self-sufficient agent body with all domain knowledge inlined.

Copilot agents are invoked via @name in chat. Key differences from Claude agents:

  • No skills: injection — all knowledge must be in the wrapper body
  • Limited hooks — VS Code Copilot and Copilot CLI each support 8 hook events (command type only), but CLI's actionable output is limited to preToolUse deny — behavioral guards in body instructions provide additional CLI coverage
  • Sequential-only invocation — no parallel agent fan-out
  • Tool names differ: execute (Copilot) vs Bash (Claude), search vs Grep/Glob

Naming convention (both platforms):

Suffix Role Can write/edit? Example
*-expert Read-only advisory — researches, explains, recommends No shell-expert
*-agent Executor — writes files, runs tools, delegates Yes kitty-agent

Claude-specific frontmatter fields (not available on Copilot):

Key Description Values
model Model override opus, sonnet, haiku, full model ID
maxTurns Max agentic turns integer
isolation Git worktree isolation worktree
effort Effort level override low, medium, high
background Always run as background task true
skills SKILL.md content injection list of skill names

Skills (skills/)

Skills are the shared expertise layer — cross-platform knowledge packages in agentskills.io format. Both Claude Code and Copilot discover SKILL.md files natively.

Each skill is a directory containing a SKILL.md file:

skills/
└── ai-crossplatform-expert/
    └── SKILL.md

SKILL.md uses YAML frontmatter with only the agentskills.io safe intersection fields:

---
name: skill-name              # Required — lowercase-hyphens, max 64 chars, matches dir name
description: 'What it does'   # Required — max 1024 chars, always quoted (never block scalar)
---

Claude agent wrappers reference skills via the skills: frontmatter field, which injects the SKILL.md content at subagent startup. Copilot has no equivalent — Copilot wrappers inline key knowledge in their body.

Copilot (copilot/)

This directory holds GitHub Copilot configuration — agent wrappers and instruction files.

copilot/
├── agents/
│   ├── ai-crossplatform-expert.agent.md
│   ├── ansible-expert.agent.md
│   ├── azure-devops-expert.agent.md
│   ├── checkmarx-expert.agent.md
│   ├── code-review-expert.agent.md
│   ├── docs-expert.agent.md
│   ├── docker-expert.agent.md
│   ├── dotnet-expert.agent.md
│   ├── gh-cli-expert.agent.md
│   ├── gitflow-expert.agent.md
│   ├── helm-expert.agent.md
│   ├── kitty-agent.agent.md
│   ├── linter.agent.md
│   └── shell-expert.agent.md
└── instructions/
    ├── adr-required.instructions.md
    ├── agent-first-selection.instructions.md
    ├── conventional-commits.instructions.md
    ├── debian-baseline.instructions.md
    ├── github-flow.instructions.md
    ├── no-mcp-servers.instructions.md
    ├── orchestrator-protocol.instructions.md
    ├── plan-before-code.instructions.md
    ├── post-implementation-review.instructions.md
    ├── pr-template-standard.instructions.md
    ├── research-parallelism.instructions.md
    ├── script-output-conventions.instructions.md
    ├── semver-tagging.instructions.md
    └── structured-review-format.instructions.md

Copilot CLI discovery: setup.sh symlinks copilot/agents/ to ~/.copilot/agents/, which the Copilot CLI discovers automatically for all projects.

Copilot in VS Code: For project-level use, copy or reference files from copilot/agents/ into .github/agents/ in the target project repo. VS Code discovers agents from .github/agents/ or paths configured in chat.agentFilesLocations.

Copilot agent wrappers use the .agent.md extension and contain only documented Copilot frontmatter fields (description, name, tools). No Claude-specific fields.

Hooks

Hooks are shell scripts that run in response to session events, providing automated pre-flight checks and security guards. All platforms support hooks with different capabilities:

Platform Events Actionable events Config source
Claude Code 26 All events support actionable output .claude/settings.json
VS Code Copilot 8 UserPromptSubmit (systemMessage), PreToolUse (deny/allow), Stop (block), others .claude/settings.json; .github/hooks/*.json (when chat.hookFilesLocations is configured)
Copilot CLI 8 preToolUse (deny only) — all other event output is ignored ~/.copilot/hooks/

The stop-hook safety net requires VS Code Copilot or Claude Code. It relies on Stop event output, which Copilot CLI ignores (the hook fires as sessionEnd but its output is discarded). The PreToolUse bash guard works on all three platforms. See ADR-037 for the rationale.

Hook Event Claude Code VS Code Copilot Copilot CLI
bash-destructive-guard.sh PreToolUse Full — deny Full — deny Works — deny supported
stop-preflight-check.sh Stop Full — description prompt Full — blocking Fires as sessionEnd but output ignored

The bash-destructive-guard.sh hook is a global guard that denies rm and mv commands targeting paths outside a configurable safe list (~/.claude/bash-guard-safe-paths.conf). It works alongside the Bash(rm:*) and Bash(mv:*) permission entries — the allow list prevents silent subagent denial, while the hook provides defense-in-depth across all agents. Relative paths within the current project and /tmp are always allowed. See Permission Evaluation for the full flow.

Hooks are configured in settings.json (Claude Code), .github/hooks/*.json (GitHub Coding Agent; VS Code Copilot when chat.hookFilesLocations is configured), and ~/.copilot/hooks/ (Copilot CLI). Restart Claude Code after any hook configuration changes.

Workflows

The orchestrator protocol and research parallelism define how the AI assistant operates. These diagrams illustrate the key communication paths and decision points.

Task Classification and Agent Routing

Every task is classified before work begins. The orchestrator checks the full agent catalog and routes to custom agents before falling back to general-purpose agents.

flowchart LR
    task["New Task"] --> classify{"Classify"}
    classify -->|Research| research["Research\nProtocol"]
    classify -->|Implementation| impl["Implementation\nProtocol"]
    classify -->|Exempt| exempt["Direct\nAction"]

    research --> catalog{"Agent Catalog:\nCustom Agent\nCovers Domain?"}
    impl --> catalog

    catalog -->|Yes| custom["Custom Agent(s)"]
    catalog -->|No| gp["General-Purpose\nAgent"]

    custom --> results["Collect Results"]
    gp --> results
    results --> synthesize["Synthesize +\nEfficacy Report"]
Loading

Agent tiers in the catalog:

Tier Role Examples
Domain Specialist Read-only advisory shell-expert, docs-expert, gh-cli-expert
Execution Provider Writes files, may delegate kitty-agent, linter

Research Parallelism

Research tasks fan out to a minimum of 3 agents in parallel (Claude Code) or sequentially (Copilot). The orchestrator waits for all agents to return before synthesizing.

flowchart TD
    task["Research Task"] --> route["Check Agent Catalog"]
    route --> fanOut["Fan Out (3+ agents)"]

    fanOut --> a1["Custom Agent 1"]
    fanOut --> a2["Custom Agent 2"]
    fanOut --> a3["Custom Agent 3"]

    a1 --> collect["Wait for All Results"]
    a2 --> collect
    a3 --> collect

    collect --> synthesize["Synthesize Best-of-Breed Answer"]
    synthesize --> report["Agent Efficacy Report"]
Loading

Planning, Implementation, and Review Lifecycle

Code changes follow a strict lifecycle: plan, get approval, implement, review. Revision loops exist at approval and review stages.

stateDiagram-v2
    [*] --> Planning
    Planning --> AwaitingApproval: present plan
    AwaitingApproval --> Planning: revisions requested
    AwaitingApproval --> Implementation: approved
    Implementation --> PostImplReview: code complete
    PostImplReview --> Implementation: issues found
    PostImplReview --> [*]: all gates pass
Loading

Permission Evaluation

A call proceeds only when the permission layer does not block it and all PreToolUse hooks return allow. The two layers operate independently: the allow list controls the approval dialog; hooks control actual execution.

flowchart TD
    call["Agent Calls Bash Tool"] --> allowCheck{"Command in\npermissions.allow?"}
    allowCheck -->|No, interactive| prompt["Prompt User"]
    allowCheck -->|No, subagent| blocked["Blocked"]
    allowCheck -->|Yes| hookCheck["PreToolUse Hooks Fire"]
    prompt -->|Approved| hookCheck
    prompt -->|Denied| blocked

    hookCheck --> globalGuard["Global Guard\n(bash-destructive-guard.sh)"]
    globalGuard --> globalCheck{"Destructive op\noutside safe paths?"}
    globalCheck -->|Yes| denied["Denied (exit 2)"]
    globalCheck -->|No| agent{"Agent-level\nguard applies?"}
    agent -->|Denied| denied
    agent -->|Allowed| execute["Execute Command"]
Loading

Safe paths are configured in ~/.claude/bash-guard-safe-paths.conf (one absolute path prefix per line). /tmp and relative paths within the current project are always allowed. Paths containing .. segments are always denied.

Platform note: On VS Code Copilot, the approval gate uses chat.tools.terminal.autoApprove (in .vscode/settings.json) instead of permissions.allow — these are independent mechanisms with no shared evaluation path. The PreToolUse hook layer works identically on both platforms. On Copilot CLI, only preToolUse deny is processed.

Post-Implementation Review

After substantive implementation work, a review pass runs before committing. Each gate must pass before proceeding. The validate.sh step applies when changes touch skills, agents, rules, or Copilot wrappers.

flowchart TD
    complete["Implementation Complete"] --> linter["Run Linter"]
    linter --> lintOk{"Pass?"}
    lintOk -->|No| fixLint["Fix Issues"]
    fixLint --> linter
    lintOk -->|Yes| tests["Verify Tests"]
    tests --> testOk{"Pass?"}
    testOk -->|No| fixTest["Investigate and Fix"]
    fixTest --> tests
    testOk -->|Yes| selfReview["Self-Review Diff"]
    selfReview --> validate["Run validate.sh"]
    validate --> ready["Ready to Commit"]
Loading

Current Skills

AI Cross-Platform Expert (skills/ai-crossplatform-expert/SKILL.md)

Cross-platform AI agent format expert. Translates between Claude Code and GitHub Copilot (CLI and VS Code) agent, skill, instruction, and rule formats. Covers frontmatter specs, wrapper generation patterns, discovery paths, coexistence strategies, and known platform fragilities.

Ansible Expert (skills/ansible-expert/SKILL.md)

Ansible expert covering playbook authoring, variable precedence, collection architecture (post-2.10), privilege escalation, Jinja2 type coercion, handler semantics, vault, inventory, roles, callback plugins, and GitHub Actions integration.

Azure DevOps Expert (skills/azure-devops-expert/SKILL.md)

Azure DevOps expert covering Azure Repos git operations, YAML pipeline authoring (stages, jobs, templates, expressions), classic release pipelines, work item management (Boards, WIQL, REST API), service connections, environments, approvals, and the az devops CLI.

Azure Infrastructure Expert (skills/azure-infra-expert/SKILL.md)

Azure infrastructure expert covering Microsoft Entra ID (app registrations, managed identities, Conditional Access, RBAC), Azure Key Vault (RBAC vs access policies, private endpoint, soft delete, purge protection), Azure Managed SignalR (Default vs Serverless modes), Storage Accounts (networking, ADLS Gen2, SAS vs RBAC), networking (Private Endpoints, Private Link, custom DNS, Private DNS Resolver), ExpressRoute (Private Peering, FastPath), and Azure Monitor / Log Analytics workspaces (DCRs, AMPLS, Sentinel linking).

Checkmarx Expert (skills/checkmarx-expert/SKILL.md)

Checkmarx One expert covering CLI tool usage, SAST/SCA/IaC scanning, authentication (API key and OAuth), local scans, scan configuration, threshold-based break-build, CI/CD integration (GitHub Actions and Azure DevOps Pipelines), config-as-code, and results triage.

Code Review Expert (skills/code-review-expert/SKILL.md)

Semantic code review covering logic correctness, design quality, security patterns, and requirement fidelity. Produces structured findings with severity classification and machine-readable verdict.

Docs Expert (skills/docs-expert/SKILL.md)

Documentation domain specialist covering best practices, content style, content curation, and Mermaid diagrams for general display and Azure DevOps. Advises on structure, audience awareness, technical writing, and diagram type selection.

Docker Expert (skills/docker-expert/SKILL.md)

Docker expert covering Dockerfile authoring, BuildKit features, rootless BuildKit, multi-stage builds, multi-platform images, secret and cache mounts, Compose v2, and container security patterns.

.NET Expert (skills/dotnet-expert/SKILL.md)

.NET expert covering .NET 10 LTS SDK, cross-platform development (macOS, Linux, Windows, containers), ASP.NET Core minimal APIs, worker services, dependency injection, EF Core, testing, publishing, and security best practices.

GH CLI Expert (skills/gh-cli-expert/SKILL.md)

GitHub CLI expert covering gh issue, gh pr, gh release, gh run, gh repo, gh gist, gh auth, gh api, and extension commands. Consults gh --help dynamically to validate flags before executing.

Git Workflow Expert (skills/gitflow-expert/SKILL.md)

Git workflow expert covering branching strategies (GitFlow, GitHub Flow, trunk-based, release branching), merge strategies, commit message conventions, release and hotfix workflows, and common anti-patterns.

Helm Expert (skills/helm-expert/SKILL.md)

Helm 3 expert covering chart authoring, values merge semantics, values layering, hooks, template debugging, chart structure, dependency management, release management, and helm diff validation.

Kitty Agent (skills/kitty-agent/SKILL.md)

Kitty terminal emulator configuration executor. Covers kitty.conf format, keybindings, color themes, session files, kittens, shell integration, and deployment patterns for Linux and macOS.

Linter (skills/linter/SKILL.md)

Multi-tool linting agent. Discovers lintable files, runs shellcheck, markdownlint, yamllint, dotnet format, helm lint, hadolint, tflint, actionlint, and ruff. Reports structured findings with auto-fix support.

Shell Expert (skills/shell-expert/SKILL.md)

Shell scripting expert covering Bash, Zsh, and POSIX sh compatibility, GNU vs BSD coreutils differences, common pitfall patterns, security concerns, shell scripting idioms, cross-platform strategies, and process management.

vCluster Expert (skills/vcluster-expert/SKILL.md)

vCluster expert covering virtual cluster lifecycle, vcluster.yaml configuration, resource syncing, networking, deployment topologies (shared nodes, dedicated nodes, private nodes, standalone), licensing tiers (OSS/Free/Enterprise), platform management, and CLI usage.

Current Agents

Agent Model Tier Description
ai-crossplatform-expert opus Domain Specialist Cross-platform format translation. Generates wrappers, validates frontmatter, flags platform fragilities.
ansible-expert opus Domain Specialist Ansible guidance. Playbook authoring, variable precedence, collection architecture, vault, CI/CD.
azure-devops-expert opus Domain Specialist Azure DevOps guidance. Pipelines, repos, boards, work items, REST API, az devops CLI.
azure-infra-expert opus Domain Specialist Azure infrastructure guidance. Entra ID, Key Vault, SignalR, Storage, Private Endpoints, ExpressRoute, Log Analytics.
checkmarx-expert opus Domain Specialist Checkmarx One scanning. CLI usage, SAST/SCA/IaC, CI/CD integration, results triage.
code-review-expert opus Domain Specialist Semantic code review. Logic errors, design quality, security concerns, requirement fidelity.
docs-expert opus Domain Specialist Documentation guidance. Best practices, content style, curation, Mermaid diagrams.
docker-expert opus Domain Specialist Docker guidance. Dockerfiles, BuildKit, multi-stage, multi-platform, Compose v2, security.
dotnet-expert opus Domain Specialist .NET guidance. .NET 10 LTS, ASP.NET Core, EF Core, worker services, cross-platform builds.
gh-cli-expert opus Domain Specialist GitHub CLI guidance. Consults gh --help dynamically. Read-only by default.
gitflow-expert opus Domain Specialist Git workflow guidance. Examines repo state, provides context-aware recommendations.
helm-expert opus Domain Specialist Helm guidance. Chart authoring, values merge, hooks, template debugging, release workflows.
kitty-agent opus Execution Provider Kitty terminal config management. Creates/edits kitty.conf, keybindings, sessions, themes.
linter sonnet Execution Provider Multi-tool linting. Discovers files, runs linters, reports findings, applies auto-fixes.
shell-expert opus Domain Specialist Shell scripting guidance. Bash/Zsh/POSIX compatibility, coreutils, security patterns.
vcluster-expert opus Domain Specialist vCluster guidance. Virtual cluster lifecycle, configuration, syncing, networking, licensing.

Current Rules

ADR Required (rules/adr-required.md)

Changes that introduce, modify, or remove conventions, patterns, or architectural decisions require an Architecture Decision Record in adrs/ using the MADR minimal template. Supersede rather than edit existing ADRs.

Agent-First Selection (rules/agent-first-selection.md)

Custom agents must be checked before using general-purpose agents. The full agent catalog must be consulted on every delegation. Using a general-purpose agent when a custom agent covers the domain is a protocol violation.

Conventional Commits (rules/conventional-commits.md)

All commit messages follow <type>(<scope>): <description> format. Valid types: feat, fix, docs, chore, refactor, test, ci, style. No authorship attributions.

Debian Baseline (rules/debian-baseline.md)

All Linux-targeting guidance assumes Debian 13 (Trixie) as the baseline distribution. Use Debian idioms: apt for package management, systemd/systemctl for services, nftables for firewall, DEB822 format for APT sources. Key differences from Ubuntu 24.04 are documented. Applies to server/VM config, Ansible, Docker base images, and distro-specific shell examples.

GitHub Flow (rules/github-flow.md)

All repos follow GitHub Flow: short-lived feature branches merged via PR into dev (the integration branch). main is the stable branch — code reaches main only via release promotion. Squash merge for feature branches; merge commit for dev-to-main promotions. Branch names use <type>/kebab-case-description.

No MCP Servers (rules/no-mcp-servers.md)

This repo prohibits MCP server usage in all content it produces or distributes. No mcp-servers in frontmatter, no .claude/settings.json in committed content, no MCP server package references. All tool access is controlled through explicit tools allowlists. This policy exists because MCP servers are the primary attack vector for OWASP ASI04 and both known Claude Code CVEs.

Orchestrator Protocol (rules/orchestrator-protocol.md)

Mandatory session-level protocol unifying agent-first selection and research parallelism. Every task must be classified as Research, Implementation, or Exempt before proceeding.

Plan Before Code (rules/plan-before-code.md)

The agent must never modify code without first presenting an implementation plan and receiving explicit user approval. The plan must specify what files change, what the changes are, and why. Reading, searching, and exploring code to build the plan requires no approval.

Post-Implementation Review (rules/post-implementation-review.md)

After substantive implementation work: run the linter agent on changed files, verify tests pass, self-review the diff, and run validate.sh when skills, agents, rules, or wrappers are touched.

PR Template Standard (rules/pr-template-standard.md)

Every repo must have a .github/PULL_REQUEST_TEMPLATE.md with four required sections: Summary, Type of Change, Test Plan, and Checklist. PR title must be valid Conventional Commits format. PRs are optional for solo developers without CI/CD; required once status checks or team members are added.

Research Parallelism (rules/research-parallelism.md)

Any research task must fan out to a minimum of 3 agents, each approaching the problem from a different angle. The orchestrator waits for all agents to return, then synthesizes a best-of-breed answer. On Claude Code, agents run in parallel; on Copilot, agents are invoked sequentially but the minimum count still applies. Every research phase must include an Agent Efficacy Report.

Script Output Conventions (rules/script-output-conventions.md)

All shell scripts use standardized output labels (OK, SKIP, WARN, INFO, ERROR), exit codes (0 = pass, 1 = errors, 2 = precondition failure), and a summary block. Scripts must use set -euo pipefail and include a usage/exit code comment block.

Secrets Guard (rules/secrets-guard.md)

setup.sh installs hooks/secrets-guard.sh as the framework repo's pre-commit hook. The hook blocks commits containing unencrypted Ansible vault files, PEM private keys, AWS access key IDs, GitHub personal access tokens, and SSH private key file paths. Override via SKIP_SECRETS_GUARD=1, .secrets-guard-allowlist at the repo root, or --no-verify (emergencies only). See ADR-047 for design.

SemVer Tagging (rules/semver-tagging.md)

Release tags use Semantic Versioning with a v prefix, cut from main as annotated tags. Version bumps follow Conventional Commits: feat bumps MINOR, fix bumps PATCH, breaking changes bump MAJOR. Pre-1.0 projects start at v0.1.0.

Structured Review Format (rules/structured-review-format.md)

All review output uses a findings table with severity classification (Critical/Error/Warning/Info) and a machine-readable verdict (PASS, PASS_WITH_WARNINGS, NEEDS_CHANGES).

Installation

Automated (recommended)

# Clone the repo
git clone git@github.com:TheSemicolon/agent-framework.git ~/.agent-framework

# Run setup — creates all symlinks, backs up existing files
~/.agent-framework/setup.sh

The setup script:

  • Creates ~/.claude/ and ~/.copilot/ if they don't exist
  • Backs up any existing items with a timestamped .bak suffix
  • Creates symlinks for Claude Code: rules/, agents/, skills/, hooks/, settings.json → ~/.claude/
  • Creates symlinks for Copilot CLI: copilot/agents/, copilot/instructions/ → ~/.copilot/
  • Creates ~/.claude/bash-guard-safe-paths.conf with default safe paths for the destructive command guard
  • Installs a pre-push git hook that runs validate.sh before every push
  • Optionally patches VS Code user settings with Copilot discovery paths and terminal auto-approve rules (requires jq)
  • Skips items that are already correctly linked
  • Is safe to re-run at any time

Manual

git clone git@github.com:TheSemicolon/agent-framework.git ~/.agent-framework

# Claude Code symlinks
mkdir -p ~/.claude
ln -s ~/.agent-framework/rules ~/.claude/rules
ln -s ~/.agent-framework/agents ~/.claude/agents
ln -s ~/.agent-framework/skills ~/.claude/skills
ln -s ~/.agent-framework/settings.json ~/.claude/settings.json

# Copilot CLI symlinks
mkdir -p ~/.copilot
ln -s ~/.agent-framework/copilot/agents ~/.copilot/agents

Verify

ls -la ~/.claude/rules ~/.claude/agents ~/.claude/settings.json ~/.claude/skills
ls -la ~/.copilot/agents

All items should show symlinks pointing to ~/.agent-framework/.

Adding New Rules

  1. Create the Claude rule file: rules/<name>.md with the frontmatter format shown above.

  2. Create the matching Copilot instruction: copilot/instructions/<name>.instructions.md with description and applyTo: '**' frontmatter. Condense the rule content for the instruction body, noting any Copilot-specific caveats (e.g., sequential invocation).

  3. Commit and push:

    cd ~/.agent-framework
git add rules/new-rule.md copilot/instructions/new-rule.instructions.md
git commit -m "feat(rules): add new-rule"
git push

  4. On other machines, git pull to pick up the change. No re-linking needed.

Adding New Skills

  1. Create a new directory in skills/ with a SKILL.md file following the agentskills.io format.
  2. Create a Claude agent wrapper in agents/ that references the skill via skills: frontmatter.
  3. Create a Copilot agent wrapper in copilot/agents/ with only Copilot-documented fields.
  4. Commit and push. Re-run setup.sh on other machines if this is the first skill (to create the skills symlink).

Use @ai-crossplatform-expert to generate correct wrappers for both platforms.

Adding New Agents

  1. Create a new .md file in agents/ with the frontmatter format shown above.
  2. If cross-platform, also create a corresponding .agent.md in copilot/agents/.
  3. Commit and push (same workflow as rules).

Modifying Settings

Claude Code: Edit settings.json in this repo directly. Changes take effect on the next Claude Code session (no restart needed for most settings).

Copilot: Copilot behavioral settings are configured through instruction file content (not a settings file). To change Copilot behavior, edit the relevant instruction in copilot/instructions/ or add project-level instructions in .github/copilot-instructions.md. VS Code-specific Copilot settings (model selection, agent paths) are configured in VS Code's own settings.json, not in this repo.

Keeping Machines in Sync

cd ~/.agent-framework && git pull

That's it. The symlinks mean any changes pulled into the repo are immediately active.

What Does NOT Belong in This Repo

Item Why Where it lives instead
.credentials.json Contains auth secrets ~/.claude/.credentials.json (local only)
history.jsonl Session history ~/.claude/ (local only)
sessions/, projects/ Session and project state ~/.claude/ (local only)
cache/, statsig/ Ephemeral caches ~/.claude/ (local only)
Auto memory (projects/*/memory/) Machine-local by design, not portable ~/.claude/projects/ (local only)

Precedence Order

Claude Code resolves conflicts using this precedence (highest wins):

  1. Managed/Enterprise — organization-wide policies (cannot be overridden)
  2. Command-line flags — temporary session overrides
  3. Project local — .claude/settings.local.json (gitignored, per-user per-repo)
  4. Project — .claude/settings.json, .claude/rules/, CLAUDE.md (committed, team-shared)
  5. User — ~/.claude/settings.json, ~/.claude/rules/, ~/.claude/CLAUDE.md (this repo, personal)

User-level rules and settings from this repo are always loaded, but project-level configuration takes priority on conflict. Command-line flags (e.g., --model sonnet) override everything except managed policies.

GitHub Copilot resolves conflicts using this precedence (highest wins):

  1. Organization policy — admin-level Copilot policies (cannot be overridden)
  2. Repository instructions — .github/copilot-instructions.md (always-on, project-level)
  3. Repository agents/instructions — .github/agents/, .github/instructions/ (project-level, scoped)
  4. User — ~/.copilot/agents/, ~/.copilot/instructions/ (this repo, personal)

Copilot instructions are additive — user-level and project-level instructions are combined. When instructions conflict, the more specific scope (project) takes precedence.

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 8

v2.0.0 Latest
Apr 28, 2026
+ 7 releases

Packages

 
 
 

Contributors

Languages