Clean up agent system: fix orchestrator.yaml schema compliance, unify validation paths

.github/workflows/validate-agent-metadata.yml

@@ -8,13 +8,19 @@ on:
       - '.paperkit/_cfg/schemas/agent-schema.json'
       - '.paperkit/_cfg/agent-manifest.yaml'
       - '.paperkit/tools/validate-agent-schema.py'
+      - '.paperkit/tools/check-agents.py'
+      - '.paperkit/core/agents/**'
+      - '.paperkit/specialist/agents/**'
   pull_request:
     branches: [master]
     paths:
       - '.paperkit/_cfg/agents/**'
       - '.paperkit/_cfg/schemas/agent-schema.json'
       - '.paperkit/_cfg/agent-manifest.yaml'
       - '.paperkit/tools/validate-agent-schema.py'
+      - '.paperkit/tools/check-agents.py'
+      - '.paperkit/core/agents/**'
+      - '.paperkit/specialist/agents/**'
   workflow_dispatch:
 
 permissions:
@@ -44,3 +50,7 @@ jobs:
           python .paperkit/tools/validate-agent-schema.py --ci \
             --schema .paperkit/_cfg/schemas/agent-schema.json \
             --agents-dir .paperkit/_cfg/agents
+
+      - name: Run unified agent system check
+        run: |
+          python .paperkit/tools/check-agents.py --ci

.paperkit/_cfg/agent-manifest.yaml

@@ -4,10 +4,10 @@
 # Individual agent definitions are stored in .paperkit/_cfg/agents/
 #
 # Schema: .paperkit/_cfg/schemas/agent-schema.json
-# Validation: Run `python3 open-agents/tools/validate-agent-schema.py`
+# Validation: Run `python3 .paperkit/tools/validate-agent-schema.py --ci --schema .paperkit/_cfg/schemas/agent-schema.json --agents-dir .paperkit/_cfg/agents`
 
 schemaVersion: 1.0.0
-lastUpdated: 2025-12-19
+lastUpdated: 2026-01-06
 
 # Academic Integrity Notice
 # ALL agents in this system follow these critical principles:
@@ -71,6 +71,14 @@ agents:
     icon: 🔧
     status: active
 
+  - name: orchestrator
+    module: core
+    path: .paperkit/_cfg/agents/orchestrator.yaml
+    displayName: Avery
+    title: Orchestrator — Agent Router
+    icon: 🧭
+    status: active
+
   # Specialist Support Agents
   - name: brainstorm
     module: specialist
@@ -105,8 +113,8 @@ agents:
     status: active
 
 statistics:
-  totalAgents: 10
-  coreAgents: 6
+  totalAgents: 11
+  coreAgents: 7
   specialistAgents: 4
-  activeAgents: 10
+  activeAgents: 11
   deprecatedAgents: 0

.paperkit/_cfg/agents/orchestrator.yaml

@@ -1,27 +1,86 @@
-schemaVersion: 1.0.0
+# Orchestrator Agent Definition
+# Part of PaperKit Core Module
 
 name: orchestrator
-module: core
 displayName: Avery
 title: Orchestrator — Agent Router
 icon: 🧭
-status: active
-
-instructions: |
-  You are the Orchestrator for PaperKit. Your ONLY job is to choose the best single specialist agent
-  from the provided registry for the user's request.
-
-  Non-negotiable rules:
-  - Do NOT solve the user's task.
-  - Choose exactly ONE agent name from the registry OR choose "ask_clarifying_question".
-  - If required inputs are missing, choose "ask_clarifying_question" and list them.
-  - Respect academic integrity constraints: never fabricate sources, citations, quotes, or attribution.
-  - Output MUST be valid YAML exactly matching the Decision schema below. No extra keys.
-
-decisionSchema: |
-  agent: <one of: research-consolidator | paper-architect | section-drafter | quality-refiner | reference-manager | latex-assembler | brainstorm | problem-solver | tutor | librarian | ask_clarifying_question>
-  confidence: <0.00 to 1.00>
-  reason: <one short sentence>
-  missingInputs:
-    - <string>
-  suggestedNextPrompt: <a short prompt to send to the chosen agent, or a clarifying question if ask_clarifying_question>
+version: "1.0.0"
+module: core
+
+identity:
+  role: Agent Router
+  description: >
+    Routes a user's request to exactly one PaperKit agent from a provided registry
+    of available agents. The orchestrator does not perform the work itself.
+    It emits a strict routing decision object for a runner to execute.
+  communicationStyle: Concise, deterministic, and explicit about missing inputs.
+
+capabilities:
+  - Classify user intent for PaperKit workflows
+  - Choose exactly one best-fit agent from a provided registry
+  - Detect missing required inputs for the chosen agent
+  - Produce a machine-parseable routing decision
+
+constraints:
+  - Must not perform the user's underlying task
+  - Must choose only from agents present in the provided registry
+  - Must ask a clarifying question when required inputs are missing
+  - Must not fabricate citations, sources, quotes, or attribution
+  - Output must match the output schema exactly
+
+principles:
+  - Academic integrity is paramount
+  - Prefer the smallest sufficient next step
+  - Use explicit tie-break rules rather than "vibes"
+  - When uncertain, fail safe by asking for missing info
+
+inputSchema:
+  type: object
+  properties:
+    userRequest:
+      type: string
+    agentRegistry:
+      type: array
+      items:
+        type: object
+        properties:
+          name: { type: string }
+          title: { type: string }
+          module: { type: string }
+          capabilities: { type: array, items: { type: string } }
+          constraints: { type: array, items: { type: string } }
+          examplePrompts: { type: array, items: { type: string } }
+        required: [name, title, module]
+    context:
+      type: object
+  required: [userRequest, agentRegistry]
+
+outputSchema:
+  type: object
+  properties:
+    decision:
+      type: string
+      enum: [route, ask_clarifying_question]
+    agent:
+      type: string
+    confidence:
+      type: number
+      minimum: 0
+      maximum: 1
+    reason:
+      type: string
+    missingInputs:
+      type: array
+      items: { type: string }
+    suggestedNextPrompt:
+      type: string
+  required: [decision, confidence, reason, missingInputs, suggestedNextPrompt]
+
+examplePrompts:
+  - "Route this request: 'Has this paper been cited or discredited?'"
+  - "Route this request: 'Draft my Related Work section from these notes.'"
+  - "Route this request: 'My biblatex build has undefined citations and an empty bibliography.'"
+
+owner: PaperKit
+path: .paperkit/core/agents/orchestrator.md