AgentMaster

# AgentMaster — Agent Context

## Overview
Meta-orchestrator for AI coding agents. One skill (`/agent-master`) routes all tasks to the right combination of installed skills across caveman (output compression), superpowers (dev workflow), claude-skills (domain expertise), and curated tactical libraries (impeccable, anthropic-official, wshobson, davila7). Supports 11 platforms via auto-generated platform files.

## Stack
- **Language**: Bash (scripts), Node.js (Tool-Stack-Reference generators)
- **Format**: SKILL.md files with YAML frontmatter + markdown body
- **Platforms**: Claude Code, Cursor, Windsurf, Cline, Codex, Gemini CLI, Antigravity, OpenCode, Augment, Aider, GitHub Copilot

## Key Dirs & Files
```
skills/                        ← SOURCE OF TRUTH — edit skills here only
  agent-master/SKILL.md        ← Main orchestrator (25 routing categories)
  codereview/SKILL.md          ← /codereview skill
  devops/SKILL.md              ← DevOps skill
  repomix-pack/SKILL.md        ← Whole-repo snapshot via repomix
  security-audit/SKILL.md      ← Security audit skill
  task-viewer/SKILL.md         ← Launches claude-task-viewer dashboard (app path in ~/.claude/.agentmaster-cache/task-viewer.path)

scripts/
  convert.sh / convert.ps1     ← Regenerates ALL platform files from skills/
  update.sh                    ← Pulls latest dependency repos to ~/.claude/skills/ (honors .dev marker)
  install-platform.sh / .ps1   ← Installs to a specific platform dir
  dev-sync.sh / dev-sync.ps1   ← Push local working tree → live install (bypass git); writes .dev marker
  scaffold.sh / scaffold.ps1   ← Report/create the canonical project-doc spine (templates in scripts/templates/)
  routes.sh                    ← Routing log/overrides/unrouted; `routes analyze` ranks misroutes
  doctor.sh                    ← Health check (skills, caches, pins, convert drift, dev mode)
tests/
  smoke.sh                     ← No-network CI checks: frontmatter, convert determinism, scaffold, syntax
.github/workflows/
  ci.yml                       ← shellcheck (error severity) + smoke tests
  check-git-identity.yml       ← Blocks edstellarmarketing identity on non-owned repos

Tool-Stack-Reference/
  hub/                         ← 62 markdown files: 1524 tools + 1767 tech (committed)
  scripts/extract.js           ← Parse master-hub.html → JSON (run manually when HTML updates)
  scripts/generate-md.js       ← JSON → hub/*.md (run manually when HTML updates)
  README.md                    ← Workflow docs for regenerating hub/

.cursor/rules/                 ← Auto-generated — DO NOT edit directly
.windsurf/ .clinerules/ etc.   ← Auto-generated — DO NOT edit directly
CONVENTIONS.md                 ← Auto-generated (Aider format) — DO NOT edit directly
.github/copilot-instructions.md ← Auto-generated — DO NOT edit directly
```

## How to Run / Build / Test
```bash
# Add/edit a skill
vim skills/agent-master/SKILL.md

# Regenerate all platform files after skill changes
bash scripts/convert.sh --all

# Fast local dev loop (skip commit+push+update; writes a .dev marker)
bash scripts/dev-sync.sh          # push working tree -> live install
bash scripts/dev-sync.sh --off    # resume normal auto-update

# Run tests (CI runs this + shellcheck --severity=error)
bash tests/smoke.sh

# Install to Claude Code
bash install.sh

# Install to a specific platform
bash scripts/install-platform.sh cursor

# Update all dependency skills (caveman, superpowers, claude-skills, claude-mem,
# impeccable, anthropic-official, wshobson, davila7)
bash scripts/update.sh
```

## Env Vars Needed
None. No `.env` file required.

## Agent-Specific Notes

### What to avoid
- **Never edit platform files directly** (`.cursor/`, `.windsurf/`, `.clinerules/`, CONVENTIONS.md, copilot-instructions.md) — they're regenerated by `convert.sh` and changes will be overwritten
- **Never run `convert.sh` as aider/copilot only** mid-session — it truncates and rewrites the whole aggregate file; run `--all` for consistency
- **Don't move hub/*.md files** — RULES.md references exact paths

### Sensitive areas
- `scripts/update.sh` contains GitHub repo URLs for dependencies — these are public repos but treat as config, not logic
- `Tool-Stack-Reference/master-hub.html` is gitignored (large file, source data)

### Known gotchas
- After editing `skills/agent-master/SKILL.md`, must run `bash scripts/convert.sh --all` OR the 8 platform-specific files will be stale
- `scripts/update.sh` uses `set -e` — any non-subshelled `cd` that fails will silently put subsequent commands in the wrong directory. Fixed to use `git -C` pattern
- `Tool-Stack-Reference/hub-*.json` are gitignored intermediates — if hub/ looks outdated, regenerate from master-hub.html

### Domain-layer note (important)
The `claude-skills` repo (alirezarezvani/claude-skills) is a **plugin-of-plugins**: its domain dirs (`engineering-team`, `marketing-skill`, `c-level-advisor`, `finance`, `product-team`, `project-management`, `ra-qm-team`, `business-growth`) are bundles nested 2-3 levels deep (`<dir>/skills/<skill>/SKILL.md` or `<dir>/<subplugin>/skills/<skill>/SKILL.md`) — the flat, one-level installer can't consume them, so `skill_source=.` only ever installed `loop-library`. The routing table used to point business-domain categories at these bundle names, which never resolved to an installed skill. **Fixed by repointing the business-domain layer to the loaded `anthropic-skills:*` plugin** (marketing→running-marketing, sales/growth→executing-sales, product→building-product, strategy→gtm-foundations, finance→setting-pricing+xlsx, compliance→compliance-handling). Coverage is honest-but-thin for finance (no valuation/DCF skill), project-management (no Jira/scrum skill), and regulated compliance (no FDA/ISO/MDR skill) — the routing rows say so. To get deeper business skills later, wire the flat claude-skills subsets (e.g. `marketing-skill/skills`, `ra-qm-team/skills`) as curated manifest lines — but they overlap heavily with anthropic-skills.

### Routing categories (26 total)
Build/Create, Refactor, Debug/Fix, Code Review, Commit/Ship, Test, Marketing, Strategy/Business, Product, Finance, Business Growth, Project Mgmt, Compliance, DevOps/Deploy, Database Design, Security, UI/UX Design, Documentation, Research, Memory/History, Explore Codebase, Whole-Codebase Analysis, LLM/AI App Dev, Task Dashboard, Meta/Skill Discovery, Simple Question

Beyond the 26 primary categories, `SKILL.md` has an **Extended Skill Clusters** table that
maps the ~86 installed-but-non-primary skills (Python depth, event-sourcing/DDD, managed
databases, security technique, docs/design, claude-mem, skill authoring, caveman-cloud, PR
utilities) to the category they surface within. Update that table when new skills are wired.

### Project doc spine + scaffolding
Mature repos in this workspace share a 4-file spine: `README.md` + `AGENTS.md` +
`CLAUDE.md`(`@AGENTS.md`) + `PROJECTLOG.md`. `PROJECTLOG.md` is the canonical name
(4 repos vs 2 with `PROJECT_LOG.md`) and follows a fixed template: STATUS
(current/ongoing/pending/blocked/done/decisions/verification) then REFERENCE
(what-it-is/stack/data-model/loop/env/commands/conventions).

`/agent-master scaffold` reports which spine files the current project is missing;
`scaffold apply` creates them from `scripts/templates/*.tmpl` (never overwrites,
substitutes project name + date). The orchestrator also runs a report-only scaffold
check once per session and *suggests* (never auto-writes) the missing files. Scripts:
`scripts/scaffold.sh` + `scripts/scaffold.ps1`; templates in `scripts/templates/`.

### Context files across the workspace
`AGENTS.md` (dup: lowercase `agents.md`) is the real context; `CLAUDE.md` is a one-line
`@AGENTS.md` import that never drifts. `convert.sh` does NOT manage any of these three —
they are hand-maintained. Backfilled `CLAUDE.md` pointers into AgentMaster, Content-Wiz,
Email-Automator, cybersecurity-academy (2026-09-09); a global `~/.claude/CLAUDE.md` and
project memory under `~/.claude/projects/.../memory/` were also seeded.

### Dependency repo survey (repos.manifest)

| Name | Upstream | skill_source | Notes |
|------|----------|---------------|-------|
| caveman | JuliusBrussee/caveman | skills | Output compression |
| superpowers | obra/superpowers | skills | Dev workflow discipline |
| claude-skills | alirezarezvani/claude-skills | . | Domain-expertise ecosystem (marketing, product, finance, etc.) |
| claude-mem | thedotmack/claude-mem | plugin/skills | Session memory, timeline, knowledge-agent |
| impeccable | pbakaus/impeccable | plugin/skills | Frontend design/polish/audit, 1 skill + 23 commands |
| anthropic-official | anthropics/skills | skills | Official Anthropic skills (docx, pdf, pptx, xlsx, frontend-design, mcp-builder, skill-creator, webapp-testing, etc.) |
| wshobson | wshobson/agents | plugins/{backend-development,security-scanning,llm-application-dev,cicd-automation,kubernetes-operations,python-development,javascript-typescript,frontend-mobile-development,ui-design,cloud-infrastructure,observability-monitoring,incident-response,developer-essentials,data-engineering,documentation-generation}/skills | 15 curated subsets (96 skills) out of 44 available plugins (see below). One repo name, 15 manifest lines — installer clones once, copies each subset. |
| davila7 | davila7/claude-code-templates | cli-tool/components/skills/git, cli-tool/components/skills/database | 2 curated categories out of ~27 available (see below). `document-processing` deliberately excluded — its skills are literally named `docx`/`pdf`/`pptx`/`xlsx` and would silently overwrite anthropic-official's versions (last-writer-wins collision). |

**Available but NOT wired** (add a `repos.manifest` line under the existing `wshobson`/`davila7` name to enable):
- wshobson/agents plugins (29 more): accessibility-compliance, agent-teams, api-scaffolding, blockchain-web3, brand-landingpage, business-analytics, database-design, framework-migration, game-development, hr-legal-compliance, machine-learning-ops, payment-processing, quantitative-trading, reverse-engineering, shell-scripting, systems-programming, and more — run `curl -s https://api.github.com/repos/wshobson/agents/git/trees/main?recursive=1 | grep -o '"path": *"plugins/[^/]*/skills/[^"]*SKILL.md"'` for the live list. (Wired, 15: backend-development, security-scanning, llm-application-dev, cicd-automation, kubernetes-operations, python-development, javascript-typescript, frontend-mobile-development, ui-design, cloud-infrastructure, observability-monitoring, incident-response, developer-essentials, data-engineering, documentation-generation.)
- davila7/claude-code-templates categories (~25 more): development (227 skills — huge, review before wiring), scientific (139), ai-research (130), business-marketing (49), productivity (46), security (44 — offensive/pentest-flavored, distinct from `security-audit`), creative-design (42), enterprise-communication (33), web-development (30), workflow-automation (22), career (21), document-processing (18 — **do not wire**, see collision note above), utilities (12), railway (12), web-data (6), sentry (6), pocketbase (6), ai-maestro (6), media (5), video (4), and a few 1-3 skill niches.

Before wiring any more of these: re-run the collision check (`comm -12` current skill names vs candidate skill dir names) — `document-processing` was not the only one likely to collide, just the one caught so far.

More agent context in Surya8991/AgentMaster

8 other files this repository gives its agents.