pal-e-docs

Agent Paradigm

agent-paradigm Doc

architecture active agent mermaid
Project

Agent Paradigm

The 5-layer model for how AI agents operate on the pal-e platform. Each layer has a distinct role and clean boundaries. This is the corrected paradigm — the previous "four pillars" model (enforcement-architecture) is correct but incomplete, missing the Events layer.



          
  
Layer 1: Events



          
    
Events are lifecycle moments — things that happen during a Claude Code session. They are the trigger system. Nothing else fires without an event.



          
  
    
      
  • 16 events total (see hook-events-reference for the complete list)
    • 
      
  • Categories: Session, User, Tools, Agents, Config, Git
    • 
      
  • Events themselves don't DO anything — they fire, and hooks attach to them
    • 
      
  • Key events: SessionStart, PreToolUse, PostToolUse, SubagentStart, Stop
    • 



          
  
Layer 2: Hooks



          
    
Hooks attach to events and enforce rules. They are shell scripts that run when events fire. Hooks are the hard enforcement layer — agents cannot bypass them.



          
  
    
      
  • Inject context — SessionStart queries pal-e-docs for project page, SOPs, active plans
    • 
      
  • Block bad actions — PreToolUse prevents main commits, unauthorized merges, missing issues
    • 
      
  • Block unauthorized spawns — SubagentStart prevents native delegation without plan context (exit 2)
    • 
      
  • Remind workflows — PostToolUse triggers review-fix loop reminders after PR submission
    • 
      
  • Guard both Bash commands AND MCP tool calls via separate matchers
    • 



          
  
Layer 3: MCP (Data + Operations)



          
    
MCP servers provide queryable data and structured operations. They are the knowledge layer.



          
  
    
      
  • pal-e-docs MCP: 14 tools — notes, projects, tags, links, repos. The knowledge base.
    • 
      
  • forgejo-mcp: 12 tools — issues, PRs, branches, reviews. Git operations with SOP awareness.
    • 
      
  • Data is structured and tagged — agents query by tag intersection, not file paths
    • 
      
  • MCP is the single source of truth — no scattered local files
    • 



          
  
Layer 4: Skills



          
    
Skills define multi-step workflows that use MCP tools. They are thin orchestration layers — the content lives in pal-e-docs, not in the skill definition.



          
  
    
      
  • /plan — fetches plan template, creates plan note, archives previous, updates project page
    • 
      
  • /review-pr — orchestrates review-fix loop using forgejo-mcp tools
    • 
      
  • Skills reference templates and SOPs by slug
    • 
      
  • Invoked by users via /skill-name syntax
    • 
      
  • Skills can delegate to agents via context: fork + agent field (convenience wiring)
    • 



          
  
Layer 5: Agents



          
    
Agents are stateless roles that follow skills and query MCP. Context comes from the system, not from memory.



          
  
    
      
  • Betty Sue: Main session coordinator. Plans, manages docs, spawns agents. Injected via SessionStart hook, not a subagent.
    • 
      
  • Dev Agent: Writes code, manages repos, creates PRs. Follows SOPs injected at session start.
    • 
      
  • QA Agent: Reviews PRs for correctness and SOP compliance. Read-only tools.
    • 
      
  • Issue Creator: Proposes well-formed issues from plan phases.
    • 
      
  • Review agents: Fresh-context agents spawned by /review-pr to review diffs.
    • 
      
  • Fix agents: Task agents that address review findings.
    • 



          
  
How They Compose



          
  
    
      
  • Event (SessionStart) fires → Hook queries MCP (pal-e-docs) → context injected into agent
    • 
      
  • Agent receives task → queries MCP for SOPs and current state
    • 
      
  • Agent follows Skill workflow → skill uses MCP tools
    • 
      
  • Every tool call triggers Events (PreToolUse, PostToolUse) → Hooks guard and remind
    • 
      
  • Agent updates MCP (pal-e-docs) with new knowledge → cycle continues
    • 



          
  
Key Insight



          
    
The previous "four pillars" model describes Hooks, MCP, Skills, and Agents as co-equal pillars. The corrected model shows they are layers with a directional flow: Events trigger Hooks, Hooks use MCP, MCP feeds Skills, Skills are run by Agents. The cycle is closed because Agent work triggers new Events.



          
  


          
  
    
      
  • hook-events-reference — complete event list with inputs and outputs
    • 
      
  • enforcement-architecture — enforcement layer detail with stack hierarchy (Note: the three operating model pillars — Platform, Docs, Agency — are separate from these enforcement layers.)
    • 
      
  • agent-workflow — practical agent workflow SOP
    •