nextcraft/.ciagent/PERSONAS.md

Nextcraft — PERSONAS.md

Persona Roster

v0.3 update (RESEARCH, lead-developer assessment): backend-engineer territory extended to the new engine modules (telemetry/grading/variants persistence + APIs). New phase-relevant custom personas added: sandbox-engineer (Linux-namespace isolation infra) and voice-engineer (STT/TTS + Examiner agent audio pipeline). ai-engineer re-scoped to LLM/agents/prompts + grading/variant/voice model-facing logic. security-auditor stays inactive (KYC deferred per founder directive). frontend-engineer gains real-sandbox (xterm.js), live-telemetry, and live-defense surfaces.

lead-developer

active: true
phase_specific: false
reason: Coordinates task decomposition across web, AI service, engine, and sandbox territories; resolves conflicts between frontend, backend, AI, sandbox, and voice personas
domain: coordination
frameworks:
  - next.js
  - turborepo
  - pnpm
  - fastapi
constraints:
  - pragmatic
  - battle-tested defaults
  - monorepo-architecture
territory:
  - "**/package.json"
  - "**/turbo.json"
  - "**/pnpm-workspace.yaml"
  - "**/tsconfig.json"
  - "apps/ai-service/pyproject.toml"

frontend-engineer

active: true
phase_specific: false
reason: Phase 6 real-engine learner-surface integration — xterm.js in-browser terminal, file-tree/run/test controls, live telemetry panels, live voice defense UI, live grading display. Owns all page components, layouts, surface-specific UI.
domain: frontend
frameworks:
  - react
  - next.js
  - tailwindcss
  - lucide-react
  - recharts
  - react-flow
  - "@xterm/xterm"
  - "@xterm/addon-fit"
constraints:
  - component-first
  - server-components-default
  - minimal-client-js
  - sse-client-buffering (buffer bytes, split frames on \n\n, join data: lines)
  - abortcontroller-cleanup (idempotent abort in effect cleanup)
  - websocket-lifecycle (typed messages, reconnect backoff, cleanup)
  - mediarecorder-permission-ux (mic consent, graceful no-mic fallback)
  - responsive-all-breakpoints
  - dark-mode-support
territory:
  - "apps/web/**"
  - "packages/ui/**"
  - "packages/mock-data/**"
  - "packages/types/**"

data-engineer

active: true
phase_specific: false
reason: Owns TS mock data layer schema and typed definitions + TS types for telemetry/trace/grade/variant/defense shapes the web surfaces consume. Does NOT own the Python corpus or engine stores — aligned by convention (D-021).
domain: data
frameworks:
  - typescript
constraints:
  - schema-first
  - type-safe
  - migration-ready
  - mock-data-only
territory:
  - "packages/types/**"
  - "packages/mock-data/**"

backend-engineer

active: true
phase_specific: false
reason: Owns apps/ai-service app shell, config, API endpoints (incl. WebSocket telemetry ingest), engine persistence (SQLite stores), scripts, and test harness. Extended for v0.3 engine modules.
domain: backend
frameworks:
  - fastapi
  - uvicorn
  - pydantic
  - pydantic-settings
  - httpx
  - pytest
  - sqlmodel
  - sqlalchemy
  - websockets
  - aiofiles
constraints:
  - provider-agnostic-boundaries (engine modules import nothing from agents/ or api/)
  - streaming-first
  - sqlite-first-persistence (protocol-wrapped stores, Postgres-ready, D-027)
  - secrets-via-env-only
  - mock-provider-in-tests
  - websocket-contract (typed envelopes, seq gap detection, D-026)
territory:
  - "apps/ai-service/ai_service/main.py"
  - "apps/ai-service/ai_service/config.py"
  - "apps/ai-service/ai_service/api/**"
  - "apps/ai-service/ai_service/telemetry/store.py"
  - "apps/ai-service/ai_service/telemetry/ingest.py"
  - "apps/ai-service/ai_service/grading/store.py"
  - "apps/ai-service/ai_service/variants/store.py"
  - "apps/ai-service/scripts/**"
  - "apps/ai-service/package.json"
  - "apps/ai-service/tests/api/**"
  - "turbo.json"

ai-engineer

active: true
phase_specific: false
reason: Owns the LLM provider layer, agent framework, prompt library, structured outputs, and the model-facing logic of v0.3 engines — trace-digest→rubric grading prompts (grading/features.py+engine.py), variant instantiation (variants/templates.py+generator.py), and the Examiner agent. Owns the deterministic-mock corpora.
domain: ai
frameworks:
  - pydantic
  - httpx
  - pytest
constraints:
  - provider-agnostic-protocol
  - prompts-are-code
  - json-defensive-parsing
  - never-call-cloud-in-tests
  - delta-passthrough
  - llm-sees-digest-not-raw-trace (D-028)
  - seeded-variant-reproducibility (D-029)
territory:
  - "apps/ai-service/ai_service/llm/**"
  - "apps/ai-service/ai_service/agents/**"
  - "apps/ai-service/ai_service/prompts/**"
  - "apps/ai-service/ai_service/corpus/**"
  - "apps/ai-service/ai_service/grading/features.py"
  - "apps/ai-service/ai_service/grading/engine.py"
  - "apps/ai-service/ai_service/variants/templates.py"
  - "apps/ai-service/ai_service/variants/generator.py"
  - "apps/ai-service/tests/llm/**"
  - "apps/ai-service/tests/agents/**"

sandbox-engineer

active: true
phase_specific: true
reason: v0.3 custom persona (RESEARCH) — owns the sandbox fabric: SandboxBackend protocol, unshare-based Linux user/mount/pid/net namespace spawner, per-sandbox workdir, resource limits, lifecycle manager, concurrency guard, and the in-sandbox capture agent. Probe-verified isolation on this box (D-024).
domain: infra
frameworks:
  - python
  - linux-namespaces
  - asyncio
  - pytest
constraints:
  - isolation-verified (probe must show in-ns uid=0, network isolated, writes to workdir only)
  - backend-protocol-swap (no containerd assumption; D-024)
  - resource-limits-enforced (cpu/mem/time quotas observable)
  - no-daemon (subprocess-only; no docker/containerd service)
  - capacity-guard (1-5 concurrent; 503 when full, D-032)
territory:
  - "apps/ai-service/ai_service/sandbox/**"
  - "apps/ai-service/scripts/sandbox-agent.py"
  - "apps/ai-service/tests/sandbox/**"

voice-engineer

active: true
phase_specific: true
reason: v0.3 custom persona (RESEARCH) — owns the voice layer: VoiceProvider protocol, STT/TTS against a compatible endpoint, deterministic mock (tests never call a voice API), browser-native fallback, and the media-path wiring consumed by the Examiner agent and assessment UI.
domain: ai-media
frameworks:
  - pydantic
  - httpx
  - pytest
  - web-mediarecorder
constraints:
  - provider-agnostic-protocol (D-030)
  - never-call-voice-api-in-tests
  - browser-native-fallback (no-key path still functions)
  - bounded-turn-latency (conversational feel budget)
territory:
  - "apps/ai-service/ai_service/voice/**"
  - "apps/ai-service/tests/voice/**"

design-system-engineer

active: true
phase_specific: false
reason: Owns the shared component library, design tokens, and visual consistency. v0.3 duty: new primitives for the real build/assessment surfaces (terminal frame, telemetry status indicator, mic/record control, grade badge, defense transcript viewer).
domain: frontend
frameworks:
  - tailwindcss
  - storybook
  - lucide-react
constraints:
  - design-token-driven
  - wcag-aa-contrast
  - dark-mode-required
  - consistent-across-surfaces
territory:
  - "packages/ui/**"

security-auditor

active: false
phase_specific: false
reason: Identity/age-gating (KYC) deferred beyond v0.3 per founder directive (A-110) — no real auth or PII backend lands this milestone. Security coverage remains: verifier's STRIDE layer + Phase 7 secrets-hygiene checklist (keys absent from code/logs/commits/errors, localhost-only CORS, no PII in prompts). Sandbox isolation safety is owned by sandbox-engineer's probe-verified constraint.
domain: security
frameworks: []
constraints: []
territory: []

Phase-Specific Personas

Persona	Phases	Removed After
sandbox-engineer	1 (primary), 2, 6	persists while sandbox fabric exists
voice-engineer	5 (primary), 6	persists while voice defense exists

All other active personas span the entire milestone. data-engineer and design-system-engineer are light-touch outside their phases.

Territory Conflict Resolution

Conflict	Resolution
frontend-engineer vs data-engineer (packages/types, packages/mock-data)	data-engineer owns type definitions and mock data schema (incl. new telemetry/grade/variant/defense TS types); frontend-engineer consumes them.
frontend-engineer vs design-system-engineer (packages/ui)	design-system-engineer owns design tokens and primitive components (terminal frame, mic control, grade badge); frontend-engineer owns composite components and page-level UI.
ai-engineer vs backend-engineer (grading/variants)	ai-engineer owns the model-facing files (features/engine/templates/generator = LLM logic + prompts); backend-engineer owns the persistence stores + API endpoints. Boundary: stores are pure SQLite; engine logic is pure compute.
sandbox-engineer vs backend-engineer (sandbox/)	sandbox-engineer owns ai_service/sandbox/** + capture agent; backend-engineer owns the API route that composes sandbox/manager.py via DI. manager.py has a narrow typed interface consumed by api/.
voice-engineer vs ai-engineer (Examiner agent)	ai-engineer owns agents/examiner.py + its prompt; voice-engineer owns voice/** (audio in/out). Examiner calls voice/ through the VoiceProvider protocol — never imports concrete providers.
ai-engineer vs data-engineer (mock duplication)	ai-engineer owns ai_service/corpus/ (Python); data-engineer owns packages/mock-data (TS). Shared IDs/shapes aligned by convention (D-021).
lead-developer vs any	lead-developer coordinates only, does not directly modify code files.