AI Agent Agency

Your Virtual Development Team in a High-Rise Penthouse Studio

Enterprise-quality consistency. Zero labor cost. No white backgrounds.

Getting Started | Agent Roster | Configuration | Documentation

What Is This?

The AI Agent Agency is a framework for organizing AI-assisted development around specialized agent personas. Instead of one general-purpose AI assistant, you build a team of specialists—each with defined roles, distinct personalities, file ownership, and automated audit protocols.

Think of it as staffing a virtual game studio where every agent has a desk in your penthouse suite, and they never approve white backgrounds.

Where this framework is used

Clone it to build your own team, or carry it inside a project as a read-only submodule with that project's customizations kept beside it. The seven desks in agents/ are the showcase team from JenniNexus Studio. Studios with their own characters keep that roster in their own private repo instead of adding desks here. Contract: docs/CONSUMERS.md.

Using Agency inside another repo? Cheat sheet: docs/CONSUMERS.md — status, sync --commit, overlay <Agent>, protect. Customize a desk without forking it: node storage/agency/scripts/consumer.mjs overlay Bloggie.

Lore SSOT

This README section is the one lore pointer other repos link to.

This public repo holds the default/public agents only: the seven desks in agents/*.md plus the shared loft attributes in docs/STUDIO-VOICE.md. Personality, role, audit pattern and ### Discord chatVoice (community register) for those seven are edited here and nowhere else.
Consumers are read-only. A project that carries this repo as a submodule never edits or pushes inside it. It customizes in the gitignored overlay folder projects/<project>/ of its checkout and moves its pin with scripts/consumer.mjs sync. An overlay names the public agent it extends (for example "extends public agents/Bloggie.md") and adds only that project's paths, audits, scores and lore.
Never fork a whole copy of the lore. An independent roster is that studio's own lore, owned in its own repository, and never copied back here.
Runtime catalogues (Discord faces, chatVoice samples in a bot's JSON) are consumers of this lore, not second sources. Writing-register routing is the optional Voice Seed registry.json.

Voice Seed is optional. Agency is the loft-character prose SSOT. Clone Voice Seed beside this repo only if you want a register map so résumé voice, Patreon voice, and loft chatVoice stay in separate rooms. Do not add it as a git submodule.

Theme Designer is optional. Clone Theme Designer only if you want a teaching --brand-accent to copy into ART-STYLE / CSS. Never @import it (or www-theme-kit). Full walk: docs/GETTING-STARTED.md.

Bot Seed is optional. Agency is lore. Clone Bot Seed only if you want a Discord Gateway greeter / loft runtime. Do not add it as a git submodule.

Why Agent Personas?

Traditional AI Use	Agent Agency Approach
One assistant for everything	Specialized experts per domain
Context resets each conversation	Persistent protocols and standards
Ad-hoc quality checking	Automated weekly audits
Unclear responsibilities	Explicit file ownership
Inconsistent enforcement	Codified rules with red flags

The 5 Core Audit Areas

Before building a custom team, start with the five categories that catch 90% of recurring drift:

#	Audit Area	What It Catches	Starter Agent
1	Theme & Design Tokens	Hardcoded hex, missing CSS vars, dark/light mode inconsistency, WCAG contrast	StyleGuard
2	Layout & UX	Broken breakpoints, spacing inconsistency, missing responsive rules, visual hierarchy drift	LayoutArchitect
3	Content Quality	Inconsistent formatting, missing metadata, broken structure, stale copy	ContentEditor
4	Media & Assets	Unoptimized images, wrong aspect ratios, missing lazy loading, broken embeds	AssetManager
5	SEO & Performance	Missing JSON-LD, bad og:image, PageSpeed regressions, uncrawled pages	MetricsGuard

See templates/AGENT-TEMPLATE.md and mcp.example.json to build your own team around these areas.

Showcase Team (JenniNexus Studio)

The agents/ directory includes a fully-built example team from a real production studio. Use these as inspiration — their profiles, audit checklists, and red flags are what yours should look like.

These are project-inspired showcase agents adapted into public examples. Excellent reference material but not meant to be used as-is. Start from mcp.example.json and templates/AGENT-TEMPLATE.md instead.

Vidette _{Video & Image Display} _{📅 Monday · 🎨 #66c0f4} _{"If it's not 16:9, it's not right."}	Bloggie _{Blog & Content Quality} _{📅 Tuesday · 🎨 #FFB020} _{"Structure is kindness to your reader."}	GraphViz _{Theme & Visual Harmony} _{📅 Wednesday · 🎨 #A563D1} _{"Investors don't fund white backgrounds."}	GamerGirl _{Game Pages & Platform CTAs} _{📅 Thursday · 🎨 #FF2E88} _{"Your game page is your pitch deck."}
DivineDesign _{Layout & Architecture} _{📅 Friday · 🎨 #00D4AA} _{"Spacing is not decoration. It's structure."}	Metrica _{SEO, Analytics & Performance} _{📅 Saturday · 🎨 #39ff14} _{"If it's not indexed, it doesn't exist."}	Vixel _{VR/Game Project Site} _{📅 Sunday · 🎨 #FF6B4A} _{"Pixels don't lie. Fix the mixin."}	_{+ Your Agent Copy the template, define your domain}

Friday PM: Implementation day — all agents collaborate to fix flagged issues.

Public portrait masters use resources/images/agents/<name>-1x1.webp and <name>-16x9.webp; the table displays the square variant at 80×80. See docs/ART-STYLE.md for generation conventions.

See individual agent files in agents/ for complete profiles, validation checklists, and red flags.

Quick Start

Longer clone walk (template → specialty → projects/ → optional Voice Seed / Theme Designer → portraits): docs/GETTING-STARTED.md.

1. Clone & Configure

git clone https://github.com/jenninexus/agency.git
cd agency
cp mcp.example.json mcp.json
cp .vscode/mcp.example.json .vscode/mcp.json
# Edit mcp.json — update studio name, agent domains, file paths.
# Keep mcp.json local; it is gitignored so personal MCP/project paths are not pushed.

2. Create Your First Agent

cp templates/AGENT-TEMPLATE.md agents/YourAgent.md

3. Reference in AI Conversations

@GraphViz.md - Review this CSS for theme compliance
@Bloggie.md - Check this blog post structure
@DivineDesign.md - Audit the page layout and UX

4. Open the Workspace

Copy the workspace template and open it in VS Code:

cp agency.example.code-workspace agency.code-workspace

Open agency.code-workspace for the full penthouse studio experience.

5. Enable Background Image (Optional)

The workspace includes settings for the shalldie.background extension to display agent artwork behind your code.

Install the recommended extension when prompted (or search shalldie.background)

Update the image URL in the workspace file:

"background.customImages": [
  "https://raw.githubusercontent.com/jenninexus/agency/main/resources/images/banner.jpg"
]

Or use a local path: file:///path/to/agency/resources/images/banner.jpg

Reload VS Code - you may see a "corrupted" warning (this is normal, click "Don't show again")
Add more agent images to resources/images/ for a slideshow - the extension cycles every 30 seconds

Configuration

All agent metadata, schedules, and coordination rules live in a local registry copied from the public template:

File	Purpose
`mcp.example.json`	Public sanitized agent registry template (tracked)
`mcp.json`	Local registry for your project (gitignored, copy from `mcp.example.json`)
`.vscode/mcp.example.json`	VS Code MCP server entry template (tracked)
`.vscode/mcp.json`	Local VS Code MCP server entry (gitignored)

Public vs Local Configuration

Track mcp.example.json only when the data is generic, sanitized, and useful to other projects.
Keep mcp.json local for personal paths, private MCP servers, project names, audit outputs, and per-project rosters.
Track .vscode/mcp.example.json as a minimal server stub only.
Keep .vscode/mcp.json local because MCP hosts often need machine-specific paths or environment variables.
Put project-specific agents and overrides in projects/<project-name>/; that directory is gitignored by default.

Universal Rules (Non-Negotiable)

No white backgrounds — Light mode uses lavender #F9F3FB
CSS variables over hex — Theme-aware always
No inline styles — All styling via CSS classes
Test both themes — Light and dark mode verification
Document changes — Update agent changelog

Color Rules

Context	Allowed	Banned
Light Background	`#F9F3FB`	`#FFFFFF`, `#FAFAFA`, `#F8F9FA`, `#F7F7F7`
Dark Background	`#121218`	Pure black `#000000`

Project Structure

agency/
├── README.md                          # You are here
├── package.json                       # npm run mcp convenience script
├── mcp.example.json                   # Public agent registry template (copy to mcp.json)
├── mcp.json                           # Local populated registry (gitignored)
├── .env.example                       # Environment variable template
├── agency.example.code-workspace      # VS Code workspace (copy to agency.code-workspace)
│
├── .github/
│   └── copilot-instructions.md        # Auto-loaded by GitHub Copilot
│
├── .vscode/
│   ├── mcp.example.json               # VS Code MCP server entry only (copy to .vscode/mcp.json)
│   └── settings.example.json          # Workspace defaults template (copy to settings.json, gitignored)
│
├── agents/                            # Showcase agent profiles (public examples)
│   ├── characters.yaml                # AI image generation prompts (gitignored)
│   ├── Vidette.md                     # Video & Media specialist (Mon)
│   ├── Bloggie.md                     # Blog & Content specialist (Tue)
│   ├── GraphViz.md                    # Theme & Visual specialist (Wed)
│   ├── GamerGirl.md                   # Game pages & platform CTAs (Thu)
│   ├── DivineDesign.md                # Layout & Architecture specialist (Fri)
│   ├── Metrica.md                     # SEO, Analytics & Performance specialist (Sat)
│   └── Vixel.md                       # VR/Game site specialist (Sun)
│
├── projects/                          # Project-specific agent rosters (local only)
│   └── README.md                      # How projects/ works — subdirs are gitignored
│
├── resources/                         # Agent media assets
│   ├── images/
│   │   ├── banner.jpg                 # README header banner
│   │   └── agents/                    # Square portraits for README cards (80×80)
│   │       └── <name>-1x1.webp        # vidette, bloggie, graphviz, gamergirl, …
│   └── video/
│       └── .gitkeep
│
├── docs/                              # Framework documentation
│   ├── GETTING-STARTED.md             # Clone walk + optional Voice Seed / Theme Designer
│   ├── ART-STYLE.md                   # Shared aesthetic + per-agent visual identity
│   ├── STUDIO-VOICE.md                # Shared loft voice
│   ├── AGENT-GUIDE.md                 # Character creation & design guide
│   ├── SCHEDULE.md                    # Weekly audit cadence template
│   ├── WORKFLOW.md                    # Edit + MCP + submodule sync guide
│   └── OPTIMIZATION-IDEAS.md          # IDE/workflow integration strategies
│
├── templates/
│   └── AGENT-TEMPLATE.md              # Blank agent profile template
│
├── examples/
│   ├── StyleGuard.md                  # Full working example agent
│   └── AgentRoster.md                 # Example team roster doc (showcase loft)
│
├── scripts/                           # Audit automation + MCP server
│   ├── mcp-server.js                  # MCP stdio server (zero deps, Node 18+)
│   ├── _audit-common.ps1              # Shared audit utilities
│   ├── audit-template.ps1             # Audit script template
│   └── consumer.mjs                   # Submodule consumer: status · check · sync · protect
│
└── audits/                            # Generated audit reports (gitignored)
    └── .gitkeep

Documentation

Document	Description
`docs/GETTING-STARTED.md`	Clone walk: template → specialty → `projects/` → optional Voice Seed / Theme Designer
`docs/AGENT-GUIDE.md`	Character creation guide with visual design system
`docs/SCHEDULE.md`	Weekly audit schedule and cross-agent coordination
`docs/OPTIMIZATION-IDEAS.md`	VS Code, Claude Code & workflow integration strategies
`templates/AGENT-TEMPLATE.md`	Full agent profile template (200+ lines)
`examples/StyleGuard.md`	Full working example agent with checklists and red flags
`examples/AgentRoster.md`	Example team roster doc (showcase 7-desk loft)
`docs/ART-STYLE.md`	Shared studio aesthetic, per-agent colors, portrait generation conventions
`docs/STUDIO-VOICE.md`	Shared loft voice; optional Voice Seed map pointer
`docs/CONSUMERS.md`	Read-only submodule contract, overlays, sync and guard
`docs/PUBLIC-LOCAL-SPLIT.md`	Two-layer pattern: public framework agents vs project-specific overrides in `projects/`

Portrait Generation

Agent portraits are generated via AI image APIs. Studio default is jenninexus/gen-ai (GROK_API_KEY in that clone’s .env — never commit keys here). Publish square resources/images/agents/<name>-1x1.webp and landscape <name>-16x9.webp masters; the showcase cards display the square variant at 80×80.

See docs/ART-STYLE.md for the shared aesthetic, per-agent accent colors, and prompt conventions. Copy agents/characters.yaml.example to agents/characters.yaml (gitignored) and generate with gen-ai / DALL-E / Midjourney. This repo does not ship a portrait generator script.

Agent Communication Protocol

Code Comments

// @GRAPHVIZ: Theme compliance required - no white backgrounds
// @VIDETTE: Video grid requires 16:9 aspect ratio enforcement
// @GAMERGIRL: Game page needs hero section with platform CTAs

Commit Messages

git commit -m "[GRAPHVIZ] Updated dark mode glass effects"
git commit -m "[BLOGGIE] Fixed tag system to use anchor tags"

Cross-References

When multiple agents collaborate, use the coordination matrix in local mcp.json to identify dependencies.

Advanced Integration

VS Code Tasks

{
  "label": "Run GraphViz Audit",
  "type": "shell",
  "command": "pwsh -File scripts/audit-template.ps1"
}

GitHub Actions

on:
  schedule:
    - cron: '0 9 * * 1'  # Monday 9am - Vidette's audit day
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pwsh scripts/audit-template.ps1

MCP Integration (Claude Code, Cursor, Zed, Cline)

Copy the public examples, then start the server:

cp mcp.example.json mcp.json
cp .vscode/mcp.example.json .vscode/mcp.json

node scripts/mcp-server.js   # or: npm run mcp

Tools available: agency_list_agents, agency_get_agent, agency_get_agent_for_file, agency_get_schedule, agency_get_rules.

GitHub Copilot

.github/copilot-instructions.md is auto-loaded by Copilot — no server needed. Agent rules, file ownership, and red flags are injected as context.

Claude Code Integration

CLAUDE.md Integration: Add agent references to your project's CLAUDE.md for automatic context:

## Agent Team
- 5 AI agents covering theme, layout, content, assets, and SEO
- Agent profiles: `agents/*.md`
- Agent registry: `mcp.json` (copy from `mcp.example.json`, gitignored)
- MCP server config: `.vscode/mcp.json` (copy from `.vscode/mcp.example.json`, gitignored)
- Audit scripts: `scripts/audit-*.ps1`
- Audit results: `audits/AUDIT_*.md`

Claude Code Skills (Slash Commands): Create custom skills in .claude/commands/ for agent operations:

.claude/commands/
├── agent-supervisor.md   # Full audit + health dashboard
├── agent-audit.md        # Quick-run specific agent audit
└── agent-status.md       # Status check without running audits

Direct Agent Invocation:

Read @GraphViz.md and audit src/styles/ for theme compliance
Run the Wednesday audit checklist from @GraphViz.md
@Vidette.md audit the video pages for duplicate script loads

Environment Variables: Copy .env.example to .env and configure paths for your project:

cp .env.example .env
# Edit .env with your project paths

The audit scripts use these paths automatically via _audit-common.ps1.

Using as a Submodule

Embed the framework in any project as a read-only git submodule. Customizations stay in the project's gitignored overlay folder; changes to the desks themselves are made in this repo's own checkout and pulled in with one command. Full contract: docs/CONSUMERS.md.

Initial Setup

git submodule add https://github.com/jenninexus/agency.git storage/agency
node storage/agency/scripts/consumer.mjs protect   # no push URL, refusing pre-push, pre-commit guard

Overlay Pattern

storage/agency/agents/GraphViz.md       ← public desk (read-only here)
storage/agency/projects/yourproject/    ← your overlays (gitignored by this repo)
  GraphViz.md                           ← "Extends public agents/GraphViz.md" + project paths, scripts
  generations/                          ← raw portrait output (local only)

See projects/README.md and docs/PUBLIC-LOCAL-SPLIT.md.

Updating the Submodule

# 1. Edit in the agency checkout (never inside a consumer)
cd /path/to/agency
git add <files> && git commit -m "docs(Bloggie): ..." && git push

# 2. In each consuming project
node storage/agency/scripts/consumer.mjs status          # pin vs origin/main, edits, overlays
node storage/agency/scripts/consumer.mjs sync --commit   # fetch, move the pin, commit the gitlink only

The pre-commit guard refuses a consumer commit while the submodule has edits or pins a commit that is not on origin/main.

Future Agents (Roadmap)

Agent	Role	Status
Codex	Build System & DevOps	Planned
Tagster	Tag System Specialist	Planned
Linklord	External Links & APIs	Planned
Docster	Documentation Manager	Planned
Testrix	Testing & QA	Planned

Extra portraits in resources/images/agents/ (if present locally) are not extra public agents. The public roster is the seven desks above. Other studio crews live in gitignored projects/ or a consuming site's own agency tree.

Philosophy

"Investors don't fund white backgrounds." — GraphViz

The AI Agent Agency isn't just organization—it's a mindset:

Specialize — Create experts, not generalists
Automate — Weekly audits catch drift before it compounds
Document — Explicit rules beat implicit assumptions
Coordinate — Clear ownership prevents conflicts
Iterate — Add agents as your project grows

Contributing

This framework is designed to be adapted:

Create and share new agent templates
Add audit script examples
Improve documentation
Share your agent team configurations

MIT — use, fork, customize

If this helps you build better agent teams:

Star this repo · Links · Patreon · Paypal

Published by Jenni at Monofinity Studio.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
agents		agents
audits		audits
docs		docs
examples		examples
projects		projects
resources		resources
scripts		scripts
templates		templates
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
agency.example.code-workspace		agency.example.code-workspace
agency.html.example		agency.html.example
mcp.example.json		mcp.example.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation