feat(agents): add named agents with AgentFactory integration for consistent agent triggering

[sti0]

This PR needs slightly adjustments if #322 gets merged first.

Summary

• Introduces three persistent named agents (The Engineer, The Architect, The Intern) with backstories and personality traits
• Integrates named agents into AgentFactory CLI for consistent triggering behavior
• Adds role-based agent selection for semantic task routing
• Maintains backward compatibility with existing dynamic trait composition

The Problem

Named agents existed in concept but didn't trigger consistently.

The previous implementation had named agent definitions scattered across documentation, but lacked the critical integration with AgentFactory that custom/dynamic agents had. This meant:

Agent Type	Before	After
Custom Agents	AgentFactory.ts --traits "..." → JSON output → Task()	Same (unchanged)
Named Agents	Manual prompt composition, no factory support	AgentFactory.ts --named engineer → JSON output → Task()

Custom agents followed a disciplined workflow:

1. Run AgentFactory.ts with traits
2. Get structured JSON output (prompt, voice_id, model)
3. Pass to Task() with subagent_type: "general-purpose"

Named agents had no equivalent path, leading to:

• Inconsistent prompt generation
• No voice mapping integration
• Manual agent selection without role-based routing
• Bypassing the constitutional rule that ALL agents must go through AgentFactory

The Solution

Named agents now use the same AgentFactory workflow as custom agents.

New CLI Parameters

# Named agent by key
bun run AgentFactory.ts --named engineer --task "Implement feature" --output json

# Named agent by role (semantic selection)
bun run AgentFactory.ts --role implementer --task "Build API" --output json

# List available named agents and roles
bun run AgentFactory.ts --list-named

Named Agent Definitions

Agent	Key	Model	Use For
The Engineer	engineer	sonnet	Implementation, code quality, technical decisions
The Architect	architect	opus	Design review, spec compliance, strategic vision
The Intern	intern	haiku	Grunt work, simple tasks, quick wins

Role Mappings

Semantic role names automatically resolve to the appropriate named agent:

Role	Maps To
implementer, developer, coder	The Engineer
spec_reviewer, architecture, design, planner	The Architect
code_quality_reviewer, quality, reviewer	The Engineer
grunt_work, simple_task, quick_task	The Intern

Changes

New Files

File	Purpose
Data/NamedAgents.yaml	Named agent definitions (backstories, traits, communication styles)
Templates/NamedAgent.hbs	Handlebars template for named agent prompt generation

Modified Files

File	Changes
Tools/AgentFactory.ts	Added --named, --role, --list-named support; NamedAgentDefinition interface
SKILL.md	Updated routing documentation for named agents
README.md	Added Named Agents section, role mappings, updated changelog
INSTALL.md	Added new files to installation steps

Deleted Files

File	Reason
AgentPersonalities.md	Redundant with NamedAgents.yaml (single source of truth)

Test Plan

• --list-named shows all three agents with roles
• --named engineer generates valid prompt with correct model (sonnet)
• --named architect generates valid prompt with correct model (opus)
• --named intern generates valid prompt with correct model (haiku)
• --role implementer correctly resolves to engineer
• --role spec_reviewer correctly resolves to architect
• --traits "security,skeptical,thorough" still works (backward compatibility)
• Response format uses [AGENT:engineer] tag for voice integration
• All JSON output includes prompt, voice_id, and model fields

Migration

No breaking changes. Existing --traits usage continues to work.

New capability: Use --named or --role for persistent agent identities instead of ad-hoc trait composition.

---

🤖 Generated with Claude Code

[artile]

Good job Timo!

[smarshall54]

Why does PAI implement a parallel agent system instead of extending claude's? this seems to lead to inconsistent invocation - sometimes, the model decides to run the PAI agent and other times it can try to run a claude sub-agent task. This PR goes in a great direction but still doesn't bridge the two.

Not to mention the poor UX of having two claude /commands (/agents and /Agents) and a .claude/agents and a .claude/CORE/Agents/.

Anyone have opinions on this?

[danielmiessler]

Thank you @sti0 for this named agents feature! 🙏

We've released PAI v2.1 which restructured everything from kai-* to pai-*. Your contributions and feature ideas have been incredibly valuable in shaping the direction of PAI.

The named agents concept is great - if you'd like to re-apply this against Packs/pai-agents-skill/, we'd love to see it!

See the release: https://github.com/danielmiessler/PAI/releases/tag/v2.1.0