claude-mods/AGENTS.md

Agent Instructions

Project Overview

This is claude-mods - a collection of custom extensions for Claude Code:

• 3 expert agents for pure context-isolation/worker roles (git-agent, firecrawl-expert, project-organizer) - every domain-knowledge agent became an -ops skill (v3.0, skills-first)
• 3 commands for session management and git orchestration (/sync, /save, /git-ops)
• 103 skills for CLI tools, patterns, workflows, and development tasks (incl. rembg-ops for transparent-PNG cutouts of flat illustration/sticker/avatar art with a deterministic fallback ladder past rembg's ML failure modes; parallel-ops as the router for the parallel/recurring-agent-work family — fleet-ops, fleet-worker, fleetflow (extracted to X:\Forge\fleetflow, mounted as a skill via junction), loop-ops, iterate, spawn — read it first when that family is ambiguous; repo-doctor for agentic-quality repo audits; svg-brand-tint-ops for zero-dep in-browser SVG brand-recolour + Potrace-stage raster vectorising; r-ops for tidyverse-first modern R / data analysis; loop-ops for outer-loop design discipline; ffmpeg-ops for probe-first media processing and EDL-driven editing; supply-chain-defense for behavioural-first dependency security; prompt-injection-defense for instruction-integrity scanning; pypi-ops for OIDC Trusted Publishing to PyPI; net-ops for network troubleshooting; windows-ops / mac-ops for workstation diagnostics; fleet-worker for cheap parallel worker delegation)
• 13 output styles for response personality (Vesper, Spartan, Mentor, Executive, Pair, Atlas, Coach, Harbour, Meridian, Noir, Roast, Sage, Scout)
• 13 hooks for pre-commit linting, post-edit formatting, dangerous command warnings, uv enforcement, dependency-install + manifest-edit supply-chain advisories, hidden-Unicode scanning (session-start + pre-commit), live config-change + worktree guards, mid-session peer-writer guard + touched-files ledger, and pmail notifications - security set auto-wired via plugin hooks.json
• Pigeon inter-session messaging (pigeon send/read/reply) - SQLite-backed pmail at ~/.claude/pmail.db

Installation

# Step 1: Add the marketplace
/plugin marketplace add 0xDarkMatter/claude-mods

# Step 2: Install the plugin (globally)
/plugin install claude-mods@0xDarkMatter-claude-mods

# Or clone and run install script
git clone https://github.com/0xDarkMatter/claude-mods.git
cd claude-mods && ./scripts/install.sh  # or .\scripts\install.ps1 on Windows

Key Directories

Directory	Purpose
.claude-plugin/	Plugin metadata (plugin.json)
agents/	Expert subagent prompts (.md files)
commands/	Slash command definitions
skills/	Skill definitions with SKILL.md
output-styles/	Response personalities (13 styles incl. vesper, atlas, noir, roast, scout)
hooks/	Working hook scripts (lint, format, safety, pmail)
rules/	Claude Code rules (14 files: agentic-quality, cli-tools, commit-style, dev-servers, loop-engineering, modern-tools, naming-conventions, prompt-injection, public-posts, release-review, shell-preference, skill-agent-updates, supply-chain, worktree-boundaries)
tools/	Modern CLI toolkit documentation
tests/	Validation scripts + justfile
scripts/	Install scripts
docs/	ARCHITECTURE.md, SKILL-CREATION-PROTOCOL.md (start here to build a skill), SKILL-SUBAGENT-REFERENCE.md, SKILL-RESOURCE-PROTOCOL.md, WORKFLOWS.md, PLAN.md, RESERVED-COMMANDS.md, TERMINAL-DESIGN.md; archive/ (completed-migration records), references/ (vendored guides)

Session Init

On "INIT:" message at session start:

1. Read the specified file (.claude/.context-init.md)
2. Proceed with user request - no summary needed

Key Resources

Resource	Description
rules/cli-tools.md	Modern CLI tool preferences (rg, fd, eza, bat)
rules/prompt-injection.md	Instruction-integrity defense - scan-on-entry, sanitize-on-ingest
skills/cli-ops/	Production CLI patterns - agentic workflows, OS keyring auth, stream separation
docs/WORKFLOWS.md	10 workflow patterns from Anthropic best practices
skills/tool-discovery/	Find the right library for any task
hooks/README.md	Pre/post execution hook examples
skills/pigeon/	Inter-session pmail - send, read, reply, broadcast, search across projects
skills/auto-skill/	Auto-detect skill-worthy workflows; Stop hook suggests after complex sessions. /auto-skill on/off/status to toggle
skills/supply-chain-defense/	Behavioural-first dependency security - Socket.dev depscore MCP, exposure-check (IOC match across npm/pnpm/yarn/bun/PyPI/Composer/Cargo/Go/RubyGems + extensions), integrity-audit (persistence), scan-extensions, install/manifest hooks. Paired with rules/supply-chain.md
skills/repo-doctor/	Agentic-quality auditor - scores any repo (entry docs, comments, structure, gates, doc-pairing) with --json + --strict CI gate; monorepo-structure + comment-doctrine references. Paired with rules/agentic-quality.md
skills/parallel-ops/	Router for the parallel/recurring-agent-work family (fleet-ops, fleet-worker, fleetflow — own repo at X:\Forge\fleetflow — loop-ops, iterate, spawn) - read first when it's unclear which one owns a fan-out/schedule/delegation ask
X:\Forge\fleetflow (own repo)	Heterogeneous GLM/Codex/Grok/Pi/Anthropic worker fleets from one session; extracted 2026-08-01, mounted as /fleetflow via junction at ~/.claude/skills/fleetflow
tests/validate.sh	Frontmatter + naming gate; enforces the description-budget cap (combined description+when_to_use, hard-fails over budget)
tests/doc-drift.sh	Counts-on-disk vs docs gate; also checks section-map markers and skill-frontmatter ghost references (related-skills/depends-on naming a skill not on disk)

Quick Reference

CLI Tools: Use rg over grep, fd over find, eza over ls, bat over cat, markitdown for documents

Web Fetching: WebFetch → Jina (r.jina.ai/) → firecrawl → firecrawl-expert agent

Extended Thinking: "think" < "think hard" < "think harder" < "ultrathink"

Tasks API: Use TaskCreate, TaskList, TaskUpdate, TaskGet for task management. Tasks are session-scoped (don't persist). Use /save to capture and /sync to restore.

Session Cache: v3.1 schema stores full task objects, session ID (for --resume), PR linkage (for --from-pr), and writes a summary to native MEMORY.md. Backwards compatible with v3.0.

Pigeon (pmail): pigeon send <project> "subject" "body" | pigeon read | pigeon reply <id> "body" | pigeon status | pigeon broadcast "subject" "body". Attach files with --attach <path>. Disable per-project: touch .claude/pigeon.disable. DB at ~/.claude/pmail.db, scripts at ~/.claude/pigeon/.

Performance

MCP Tool Search: When using multiple MCP servers, enable tool search to save context:

// .claude/settings.local.json
{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

Value	Behavior
"auto"	Enable when MCP tools > 10% context (default)
"true"	Always enabled (recommended with many MCP servers)
"false"	Disabled, all tools loaded upfront

Requires Sonnet 4+ or Opus 4+.

Landmines

• A skill's own test suite can assert on its own frontmatter shape (e.g. r-ops/tests/run.sh requires when_to_use: to exist). A trim/edit pass touching only the SKILL.md body can still break CI if it drops a field a sibling suite polices — read the skill's tests/run.sh before removing any frontmatter field, not just the SKILL.md itself.
• The landing gate must run the FULL per-skill suite sweep (skills/*/tests/run.sh, all of them), never just the touched lanes' — suites assert on shared/sibling files, so a change in one skill can silently break another's gate.
• Line endings: .gitattributes pins *.sh (and, via * text=auto eol=lf, every file git detects as text) to LF — bash dies on CRLF ($'\r': command not found, shebang exit 127). A checkout that predates the pin still carries CRLF until its files are re-smudged (delete + git checkout -- .), and scripts/install.ps1 strips CRs from installed shell scripts as a backstop. Extension-less shebang scripts ride on git's text-detection heuristic — if one ever reads as binary (e.g. embedded NUL), pin it in .gitattributes explicitly.
• Executable bit on commit: scripts under skills/*/scripts/ and hooks/*.sh must be tracked 100755. Git on Windows won't set this for you — tests/check-exec-bits.sh gates it; a script that "works locally" but fails bash foo.sh for another contributor is almost always a missing exec bit, not a logic bug.
• Coupled golden fixtures: some skill tests compare output against a fixture file colocated in the same tests/ dir — editing the skill's output format without regenerating the fixture is a silent, not loud, break (diff the fixture, don't just eyeball the code change).
• Never touch .claude/worktrees/ or any repo's git worktree state (see rules/worktree-boundaries.md) — it looks orphaned and isn't.

Testing

just check        # THE gate: validate + doc-drift + resource contracts + skill suites
just check-fast   # same minus the per-skill behavioural suites