pal-e-docs

Phase 7f-2: Agent spawn requirements schema

phase-7f-2-agent-spawn-schema Phase

Project
Goal: Replace hardcoded regex checks in check-agent-spawn.sh with a JSON schema that defines input requirements per agent type. The schema doubles as documentation and enforcement.
Owner: Dev agent
Repo: claude-custom
Parent: Phase 7f (Doc Cleanup + SOP Hardening)
Depends on: Phase 7f-1 (issue-gate hook must be live first)

Why

Inspired by data augmentation patterns where inputs and outputs are clearly defined to scope exactly where intelligence is needed. Each agent type has implicit requirements that live in Betty Sue's head. A JSON schema makes the contract explicit, validated by the hook, and self-documenting.
Currently check-agent-spawn.sh uses hardcoded regexes. Adding a new agent type means editing bash. With a schema, adding an agent type means adding a JSON entry.

Schema Design

Deliverables

  • Schema file: schemas/agent-spawn-requirements.json — defines required_patterns, description, produces, isolation per agent type
  • Hook update: check-agent-spawn.sh reads the schema, validates prompt against required_patterns for the given subagent_type. Falls back to deny-all if type not in schema.
  • Convention note update: agent-spawn-conventions references the schema as the source of truth for spawn requirements

Acceptance Criteria

  • Schema file exists and is valid JSON
  • Hook validates all required_patterns for the given subagent_type
  • Unknown subagent_type defaults to deny
  • Adding a new agent type = adding a JSON entry (no bash changes)
  • Existing spawn patterns (dev with issue, Dottie with plan) still pass

Architecture Note

This is the minimal version — JSON + bash + jq. If we ever move to Claude Agent SDK for custom orchestration, the schema becomes a Pydantic model. But for now, ~50 lines of bash + a config file gets 100% of the value.
  • phase-7f-1-deprecate-issue-creator — prerequisite (issue-gate hook)
  • agent-spawn-conventions — convention to update
  • phase-postgres-7f-doc-cleanup-sop — parent phase