pal-e-docs

Convention: Agent Design Principles

convention-agent-design Convention

active convention agent
Project

Core Principle

Agents are tied to WORKFLOWS, not DOMAINS. Dev writes code, QA reviews code — that's the workflow boundary. Claude Opus already has domain expertise — don't pre-load it.

When Specialization Helps

Specialization adds value when it adds CAPABILITY:
  • Tools the model can't access otherwise (Impeccable design skills, tofu commands)
  • Process enforcement the model wouldn't follow naturally (ruff format before commit)
  • Explicit severity calibration (BLOCKER criteria for test coverage)

When Specialization Hurts

Specialization hurts when it only adds CONSTRAINTS:
  • "Never write frontend" — the model naturally stays in-domain based on repo/issue context
  • Domain-specific checklists that replace generic ones — trades must-have generic coverage for nice-to-have domain nits
  • Separate QA agents per domain — constrained attention rather than adding capability

Evidence: Phase 12v L2 Quality Comparison (2026-03-15)

  • Legacy generic QA: 6 blockers found (missing tests, DRY, input validation, SQL concatenation)
  • Domain-specialized QA: 0 blockers found, 7 domain-specific nits (a11y, Alembic, responsive)
  • Root cause: specialization REDIRECTED attention, didn't ADD knowledge
  • Decision: consolidated 9-agent model back to 5-agent model (PR #108)

Skill Containment

  • Global skills pollute every session — use disable-model-invocation: true for domain-specific skills
  • Project-scope skills when possible (.claude/skills/ in repo dir)
  • Plugins for proper namespacing and per-project installation
  • Context budget: 2% of context window for skill descriptions. Don't waste it.

Current Model (5 agents)

Betty Sue (management), Penny (comms), Dev (all domains + Impeccable + tofu + ruff), QA (generic code quality + dynamic domain expertise + PROCESS OBSERVATIONS), Dottie (docs)
  • agent-workflow — operating model SOP
  • arch-domain-pal-e-agency — org chart
  • phase-pal-e-agency-12-agent-specialization — full Phase 12 history
  • convention-agent-skill-mcp-wiring — how agents connect to tools