kin/agents/specialists.yaml

# Kin specialist pool — roles available for pipeline construction.
# PM selects from this pool based on task type.

specialists:
  pm:
    name: "Project Manager"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Decomposes tasks, selects specialists, builds pipelines. See also: return_analyst (injected when return_count>=3 for escalation analysis)."
    permissions: read_only
    context_rules:
      decisions: all
      modules: all

  architect:
    name: "Software Architect"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Designs solutions, reviews structure, writes specs"
    permissions: read_only
    context_rules:
      decisions: all
      modules: all

  debugger:
    name: "Debugger"
    model: sonnet
    tools: [Read, Grep, Glob, Bash]
    description: "Finds root causes, reads logs, traces execution"
    permissions: read_bash
    working_dir: project
    context_rules:
      decisions: [gotcha, workaround]

  frontend_dev:
    name: "Frontend Developer"
    model: sonnet
    tools: [Read, Write, Edit, Bash, Glob, Grep]
    description: "Implements UI: Vue, CSS, components, composables"
    permissions: full
    working_dir: project
    context_rules:
      decisions: [gotcha, workaround, convention]

  backend_dev:
    name: "Backend Developer"
    model: sonnet
    tools: [Read, Write, Edit, Bash, Glob, Grep]
    description: "Implements API, services, database, business logic"
    permissions: full
    working_dir: project
    context_rules:
      decisions: [gotcha, workaround, convention]

  tester:
    name: "Tester"
    model: sonnet
    tools: [Read, Write, Bash, Glob, Grep]
    description: "Writes and runs tests, verifies fixes"
    permissions: full
    working_dir: project
    context_rules:
      decisions: []

  reviewer:
    name: "Code Reviewer"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Reviews code for quality, conventions, bugs"
    permissions: read_only
    context_rules:
      decisions: [convention]

  security:
    name: "Security Engineer"
    model: sonnet
    tools: [Read, Grep, Glob, Bash]
    description: "OWASP audit, auth checks, secrets scan, vulnerability analysis"
    permissions: read_bash
    working_dir: project
    context_rules:
      decisions_category: security

  sysadmin:
    name: "Sysadmin"
    model: sonnet
    tools: [Bash, Read]
    description: "SSH-based server scanner: maps running services, open ports, configs, versions via remote commands"
    permissions: read_bash
    context_rules:
      decisions: all
      modules: all

  tech_researcher:
    name: "Tech Researcher"
    model: sonnet
    tools: [Read, Grep, Glob, WebFetch, Bash]
    description: "Studies external APIs (docs, endpoints, limits, quirks), compares with codebase, produces structured review. Use for external API research only. For repository/codebase analysis use repo_researcher."
    permissions: read_only
    context_rules:
      decisions: [gotcha, workaround]
    output_schema:
      status: "done | partial | blocked"
      api_overview: string
      endpoints: "array of { method, path, description, params, response_schema }"
      rate_limits: "{ requests_per_minute, requests_per_day, notes }"
      auth_method: string
      data_schemas: "array of { name, fields }"
      limitations: "array of strings"
      gotchas: "array of strings"
      codebase_diff: "array of { file, line_hint, issue, suggestion }"
      notes: string

  repo_researcher:
    name: "Repo Researcher"
    model: sonnet
    tools: [Read, Grep, Glob, WebFetch, Bash]
    description: "Analyses repositories and codebases: maps structure, tech stack, architecture, strengths, weaknesses, and integration points. Use for repository/codebase analysis only. For external API research use tech_researcher."
    permissions: read_only
    context_rules:
      decisions: [gotcha, workaround]
    output_schema:
      status: "done | partial | blocked"
      repo_overview: string
      tech_stack: "{ languages, frameworks, databases, infrastructure, build_tools }"
      architecture_summary: string
      key_components: "array of { name, path, role, dependencies }"
      strengths: "array of strings"
      weaknesses: "array of strings"
      integration_points: "array of strings"
      gotchas: "array of strings"
      notes: string

  constitution:
    name: "Constitution Agent"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Defines project principles, constraints, and non-negotiables. First step in spec-driven workflow."
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      principles: "array of strings"
      constraints: "array of strings"
      goals: "array of strings"

  spec:
    name: "Spec Agent"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Creates detailed feature specification from constitution output. Second step in spec-driven workflow."
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      overview: string
      features: "array of { name, description, acceptance_criteria }"
      data_model: "array of { entity, fields }"
      api_contracts: "array of { method, path, body, response }"
      acceptance_criteria: string

  constitutional_validator:
    name: "Constitutional Validator"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Gate agent: validates mission alignment, stack alignment, and complexity appropriateness before implementation begins"
    permissions: read_only
    gate: true
    context_rules:
      decisions: all
      modules: all
    output_schema:
      verdict: "approved | changes_required | escalated | blocked"
      violations: "array of { principle, severity: critical|high|medium, description, suggestion }"
      escalation_reason: "string (only when escalated)"
      summary: "string"

  task_decomposer:
    name: "Task Decomposer"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Decomposes architect output into concrete implementation tasks. Creates child tasks in DB."
    permissions: read_only
    context_rules:
      decisions: all
      modules: all
    output_schema:
      tasks: "array of { title, brief, priority, category, acceptance_criteria }"

  # Department heads — Opus-level coordinators that plan work within their department
  # and spawn internal sub-pipelines of Sonnet workers.

  backend_head:
    name: "Backend Department Head"
    model: opus
    execution_type: department_head
    department: backend
    tools: [Read, Grep, Glob]
    description: "Plans backend work, coordinates architect/backend_dev/tester within backend department"
    permissions: read_only
    context_rules:
      decisions: all
      modules: all
    output_schema:
      context_packet: "{ architecture_notes: string, key_files: array, constraints: array, unknowns: array, handoff_for: string }"

  frontend_head:
    name: "Frontend Department Head"
    model: opus
    execution_type: department_head
    department: frontend
    tools: [Read, Grep, Glob]
    description: "Plans frontend work, coordinates frontend_dev/tester within frontend department"
    permissions: read_only
    context_rules:
      decisions: all
      modules: all
    output_schema:
      context_packet: "{ architecture_notes: string, key_files: array, constraints: array, unknowns: array, handoff_for: string }"

  qa_head:
    name: "QA Department Head"
    model: opus
    execution_type: department_head
    department: qa
    tools: [Read, Grep, Glob]
    description: "Plans QA work, coordinates tester/reviewer within QA department"
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      context_packet: "{ architecture_notes: string, key_files: array, constraints: array, unknowns: array, handoff_for: string }"

  security_head:
    name: "Security Department Head"
    model: opus
    execution_type: department_head
    department: security
    tools: [Read, Grep, Glob]
    description: "Plans security work, coordinates security engineer within security department"
    permissions: read_only
    context_rules:
      decisions_category: security
    output_schema:
      context_packet: "{ architecture_notes: string, key_files: array, constraints: array, unknowns: array, handoff_for: string }"

  infra_head:
    name: "Infrastructure Department Head"
    model: opus
    execution_type: department_head
    department: infra
    tools: [Read, Grep, Glob]
    description: "Plans infrastructure work, coordinates sysadmin/debugger within infra department"
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      context_packet: "{ architecture_notes: string, key_files: array, constraints: array, unknowns: array, handoff_for: string }"

  prompt_engineer:
    name: "Prompt Engineer"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Designs and optimises prompts for LLM agents, evaluates output quality, recommends model selection"
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      status: "done | partial | blocked"
      prompt_design: "{ objective: string, prompt_structure: string, key_instructions: array, examples: array }"
      quality_evaluation: "{ criteria: array of { metric, score: 1-5, rationale }, overall_score: 1-5, findings: array }"
      model_recommendation: "{ recommended_model: string, rationale: string, alternatives: array of { model, tradeoffs } }"
      notes: string

  cto_advisor:
    name: "CTO Advisor"
    model: opus
    tools: [Read, Grep, Glob]
    description: "Strategic technical reviewer: evaluates architectural plans for business risks, scalability, and platform vs product complexity. Analysis-only — no code changes. See also: constitutional_validator (alignment gate), architect (plan author)."
    permissions: read_only
    context_rules:
      decisions: all
      modules: all
    output_schema:
      status: "done | partial | blocked"
      scalability_assessment: "{ score: 1-5, notes: string, platform_vs_product: platform|product|hybrid, complexity_appropriateness: appropriate|over-engineered|under-engineered }"
      strategic_risks: "array of { risk: string, severity: critical|high|medium|low, mitigation: string }"
      strategic_verdict: "approved | concerns | critical_concerns"
      recommendation: "string — final strategic recommendation"
      notes: string

  knowledge_synthesizer:
    name: "Knowledge Synthesizer"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Aggregates multi-agent research outputs into unified, confidence-rated knowledge base for the Architect"
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      unified_findings: "array of strings"
      confidence_rated_conclusions: "array of { conclusion, confidence: high|medium|low, supporting_roles, rationale }"
      unresolved_conflicts: "array of { topic, positions: { role: position }, recommendation }"
      prioritized_actions: "array of strings"
      phases_context_used: "array of role names"

  research_head:
    name: "Research Department Head"
    model: opus
    execution_type: department_head
    department: research
    tools: [Read, Grep, Glob]
    description: "Plans research work, coordinates tech_researcher/repo_researcher/architect/prompt_engineer within research department. tech_researcher — for external API research; repo_researcher — for repository/codebase analysis."
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      context_packet: "{ architecture_notes: string, key_files: array, constraints: array, unknowns: array, handoff_for: string }"

  error_coordinator:
    name: "Error Coordinator"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Triages ≥2 related bugs: clusters by causal boundary (shared_dependency > release_boundary > configuration_boundary), separates primary faults from cascading symptoms, builds investigation streams. Activates when ≥2 related bugs in one investigation. See also: debugger (single-bug, direct execution)."
    permissions: read_only
    context_rules:
      decisions: [gotcha, workaround]
    output_schema:
      status: "done | partial | blocked"
      fault_groups: "array of { group_id, causal_boundary_type, boundary_evidence, bugs: array }"
      primary_faults: "array of { bug_id, hypothesis, confidence: high|medium|low }"
      cascading_symptoms: "array of { bug_id, caused_by: bug_id }"
      streams: "array of { specialist, scope, bugs: array, priority: high|medium|low }"
      reintegration_checklist: "array of strings"

  return_analyst:
    name: "Return Analyst"
    model: sonnet
    tools: [Read, Grep, Glob]
    description: "Analyses recurring task return patterns (full PM returns, not revisions), identifies root causes, refines brief, recommends escalation to dept_head. Standalone specialist — NOT a department worker. Injected by PM when return_count>=3. See also: pm (routing rule), analyst (intra-pipeline revision analysis), cto_advisor/dept_heads (escalation targets)."
    permissions: read_only
    context_rules:
      decisions: all
    output_schema:
      status: "done | partial | blocked"
      root_cause_analysis: string
      refined_brief: string
      clarification_list: "array of strings"
      escalate_to_dept_head: "bool"

  marketing_head:
    name: "Marketing Department Head"
    model: opus
    execution_type: department_head
    department: marketing
    tools: [Read, Grep, Glob]
    description: "Plans marketing work, coordinates tech_researcher/spec within marketing department"
    permissions: read_only
    context_rules:
      decisions: all
      modules: all
    output_schema:
      context_packet: "{ architecture_notes: string, key_files: array, constraints: array, unknowns: array, handoff_for: string }"

# Departments — PM uses these when routing complex cross-domain tasks to department heads
departments:
  backend:
    head: backend_head
    workers: [architect, backend_dev, tester, reviewer]
    description: "Backend development: API, database, business logic"

  frontend:
    head: frontend_head
    workers: [frontend_dev, tester, reviewer]
    description: "Frontend development: Vue, CSS, components, composables"

  qa:
    head: qa_head
    workers: [tester, reviewer]
    description: "Quality assurance: testing and code review"

  security:
    head: security_head
    workers: [security, reviewer]
    description: "Security: OWASP audit, vulnerability analysis, remediation"

  infra:
    head: infra_head
    workers: [sysadmin, debugger, reviewer]
    description: "Infrastructure: DevOps, deployment, server management"

  research:
    head: research_head
    workers: [tech_researcher, repo_researcher, architect, prompt_engineer]
    description: "Technical research (API and codebase), architecture planning, and prompt engineering. tech_researcher — external APIs; repo_researcher — repositories/codebases."

  marketing:
    head: marketing_head
    workers: [tech_researcher, spec]
    description: "Marketing: market research, positioning, content strategy, SEO"

# Route templates — PM uses these to build pipelines
routes:
  debug:
    steps: [debugger, tester, frontend_dev, tester]
    description: "Find bug → verify → fix → verify fix"

  feature:
    steps: [architect, constitutional_validator, frontend_dev, tester, reviewer]
    description: "Design → validate → implement → test → review"

  refactor:
    steps: [architect, frontend_dev, tester, reviewer]
    description: "Plan refactor → implement → test → review"

  hotfix:
    steps: [debugger, frontend_dev, tester]
    description: "Find → fix → verify (fast track)"

  security_audit:
    steps: [security, architect]
    description: "Audit → remediation plan"

  api_research:
    steps: [tech_researcher, architect]
    description: "Study external API → integration plan"

  infra_scan:
    steps: [sysadmin, reviewer]
    description: "SSH scan server → map services/ports/configs → review findings"

  infra_debug:
    steps: [sysadmin, debugger, reviewer]
    description: "SSH diagnose → find root cause → verify fix plan"

  spec_driven:
    steps: [constitution, spec, architect, constitutional_validator, task_decomposer]
    description: "Constitution → spec → implementation plan → decompose into tasks"

  dept_feature:
    steps: [backend_head, frontend_head, qa_head]
    description: "Full-stack feature: backend dept → frontend dept → QA dept"

  dept_fullstack:
    steps: [backend_head, frontend_head]
    description: "Full-stack feature without dedicated QA pass"

  dept_security_audit:
    steps: [security_head, qa_head]
    description: "Security audit followed by QA verification"

  dept_backend:
    steps: [backend_head]
    description: "Backend-only task routed through department head"

  dept_frontend:
    steps: [frontend_head]
    description: "Frontend-only task routed through department head"

  dept_marketing:
    steps: [marketing_head]
    description: "Marketing task routed through department head"

  dept_infra:
    steps: [infra_head]
    description: "Infrastructure task routed through department head"

  dept_research:
    steps: [research_head]
    description: "Research task routed through department head"

  multi_bug_debug:
    steps: [error_coordinator, debugger, tester]
    description: "Triage multiple related bugs → debug root cause → verify fix"