# Nextcraft — PERSONAS.md

## Persona Roster

> **v0.4 update (RESEARCH, lead-developer assessment):** milestone pivoted to Distribution & Bootstrap CLI (founder directive D-016). New custom persona **cli-engineer** (domain `cli`) owns apps/cli end-to-end: doctor/bootstrap/verify/dev commands, checks, spawn wrappers, the SEA binary build, the one-liner install script, and the release-asset pipeline. backend-engineer retains the scripts/ + turbo/root-package integration surface. **sandbox-engineer and voice-engineer deactivated** (their v0.3 code is complete and untouched this milestone — reason fields below). ai-engineer light-touch (no model-facing work in v0.4). **security-auditor re-activated (phase-specific)** for the install pipeline: curl|bash attack surface, checksum trust, PATH writes, secrets handling in the release flow. frontend-engineer/design-system-engineer/data-engineer inactive (zero UI/data-scope tasks in v0.4 — retained below with reasons).

### lead-developer
```yaml
active: true
phase_specific: false
reason: Coordinates task decomposition across CLI, scripts, release-pipeline, and docs territories; resolves cli-engineer/backend-engineer boundary (scripts vs CLI)
domain: coordination
frameworks:
  - next.js
  - turborepo
  - pnpm
  - node
constraints:
  - pragmatic
  - battle-tested defaults
  - monorepo-architecture
territory:
  - "**/package.json"
  - "**/turbo.json"
  - "**/pnpm-workspace.yaml"
  - "**/tsconfig.json"
  - "apps/ai-service/pyproject.toml"
```

### cli-engineer
```yaml
active: true
phase_specific: false
reason: v0.4 custom persona (RESEARCH) — owns the distribution milestone core: nextcraft CLI (doctor/bootstrap/verify/dev), pure check logic, spawn wrappers with timeouts, Node SEA binary build (D-033), one-liner install.sh (D-035), checksum sidecar, and Gitea release-asset upload (D-036)
domain: cli
frameworks:
  - node
  - typescript
  - node:test
  - esbuild
  - node-sea
  - posix-sh
constraints:
  - stdlib-only-runtime (no runtime npm deps; esbuild dev-only)
  - thin-wrapper (never re-implement scripts/bootstrap.sh or dev.sh — compose via spawn, A-202/A-209)
  - timeout-every-spawn (no unbounded subprocess)
  - actionable-errors (every failed check tells the user how to fix it)
  - graceful-degradation (install never hard-fails; source-bootstrap fallback, A-206)
  - checksum-before-install (sha256 verify before chmod+install, A-207)
  - secrets-never-in-cli (no key generation; .env.example -> .env copy only, A-210)
  - fail-loud-exit-codes (0 ok / 1 failure / 2 usage)
territory:
  - "apps/cli/**"
  - "scripts/install.sh"
  - "scripts/release-assets.sh"
```

### backend-engineer
```yaml
active: true
phase_specific: false
reason: Owns the script + monorepo integration surface the CLI composes: apps/ai-service/scripts/*, root package.json cli:* passthrough scripts, turbo task wiring (D-037/D-022). Python ai-service itself is untouched this milestone (v0.3 complete).
domain: backend
frameworks:
  - fastapi
  - bash
  - turborepo
  - pnpm
constraints:
  - scripts-are-truth (bootstrap.sh/dev.sh stay the single source of bootstrap orchestration; CLI only wraps)
  - idempotent-scripts (re-runnable without side effects)
  - secrets-via-env-only (D-014; dev.sh exports from .ciagent/.env.secrets)
territory:
  - "apps/ai-service/scripts/**"
  - "apps/ai-service/package.json"
  - "package.json"
  - "turbo.json"
  - ".gitignore"
```

### security-auditor
```yaml
active: true
phase_specific: true
reason: v0.4 re-activated (phase-specific) — the install pipeline is the first externally-consumed attack surface: curl|bash piping, latest-release resolution, checksum trust root, PATH writes to ~/.local/bin, download tempdir hygiene, release-asset upload token handling. No KYC/PII work (still v0.5).
domain: security
frameworks:
  - posix-sh
  - curl
  - sha256sum
constraints:
  - STRIDE-classified
  - no-pipe-to-shell-without-checksum (download -> verify -> install order)
  - tmpdir-safe (mktemp, no predictable paths, trap cleanup)
  - token-never-echoed (release upload resolves .env* only, never logs)
territory:
  - "scripts/install.sh"
  - "scripts/release-assets.sh"
  - "apps/cli/src/lib/spawn.ts"
```

### ai-engineer
```yaml
active: true
phase_specific: false
reason: Light-touch v0.4 — no model-facing work in the distribution milestone; retained to guard the CLI against touching agent/engine boundaries and to keep territory mappings accurate for v0.5 (voice real-path, seq-lease).
domain: ai
frameworks:
  - pydantic
  - httpx
  - pytest
constraints:
  - provider-agnostic-protocol
  - never-call-cloud-in-tests
territory:
  - "apps/ai-service/ai_service/llm/**"
  - "apps/ai-service/ai_service/agents/**"
  - "apps/ai-service/ai_service/prompts/**"
```

### frontend-engineer
```yaml
active: false
phase_specific: false
reason: v0.4 has zero UI-scope work (no web/pages/components changes planned in the distribution milestone); v0.3 surfaces are complete. Reactivated at v0.5 when deferred UX work resumes.
domain: frontend
frameworks:
  - react
  - next.js
  - tailwindcss
constraints:
  - component-first
  - server-components-default
territory:
  - "apps/web/**"
  - "packages/ui/**"
```

### design-system-engineer
```yaml
active: false
phase_specific: false
reason: No design-token or primitive work in v0.4; roster retained for v0.5.
domain: frontend
frameworks:
  - tailwindcss
  - storybook
constraints:
  - design-token-driven
  - wcag-aa-contrast
territory:
  - "packages/ui/**"
```

### data-engineer
```yaml
active: false
phase_specific: false
reason: No schema/mock-data work in v0.4; types packages untouched. Reactivated if CLI surfaces need shared types (not planned — CLI is self-contained).
domain: data
frameworks:
  - typescript
constraints:
  - schema-first
  - type-safe
territory:
  - "packages/types/**"
  - "packages/mock-data/**"
```

### sandbox-engineer
```yaml
active: false
phase_specific: false
reason: v0.3 persona — sandbox fabric shipped complete (v0.2.x series); v0.4 touches no sandbox code. doctor only *checks* unshare availability; no sandbox logic changes. Reactivated at v0.5 (design/sim environments).
domain: infra
frameworks:
  - python
  - linux-namespaces
constraints: []
territory:
  - "apps/ai-service/ai_service/sandbox/**"
```

### voice-engineer
```yaml
active: false
phase_specific: false
reason: v0.3 persona — voice defense shipped complete (mock-first, CUT-1); real server STT/TTS moved to v0.5 per D-016. No v0.4 voice work.
domain: ai-media
frameworks: []
constraints: []
territory:
  - "apps/ai-service/ai_service/voice/**"
```

## Phase-Specific Personas

| Persona | Phases | Removed After |
|---------|--------|---------------|
| security-auditor | 2 (primary: install pipeline), 3, 4 (final review) | milestone complete |

All other personas span the milestone. Deactivated personas receive no tasks.

## Territory Conflict Resolution

| Conflict | Resolution |
|----------|------------|
| cli-engineer vs backend-engineer (scripts/) | backend-engineer owns `apps/ai-service/scripts/**` + root `package.json`/`turbo.json` wiring; cli-engineer owns `apps/cli/**` + top-level `scripts/install.sh` + `scripts/release-assets.sh` and *consumes* backend scripts via spawn — never edits them |
| cli-engineer vs security-auditor (install.sh) | cli-engineer implements; security-auditor reviews + may patch security defects directly in install.sh/spawn.ts (its territory) |
| lead-developer vs any | lead-developer coordinates only, does not directly modify code files |