AI Artist — Engineering Specification

---
name: ai-artist-engineering-spec
description: Full 21-section engineering spec — contracts, deterministic design, compliance matrix, production checklist
title: "AI Artist --” Engineering Specification"
impact: MEDIUM
impactDescription: "Moderate improvement to quality or maintainability"
tags: engineering, spec
---

# AI Artist — Engineering Specification

> Production-grade specification for AI prompt engineering across text and image generation models at FAANG scale.

---

## 1. Overview

AI Artist provides structured prompt engineering patterns for AI text generation (Claude, GPT, Gemini) and image generation (Midjourney, DALL-E, Stable Diffusion, Flux). The skill codifies prompt construction into deterministic, composable templates that produce consistent outputs across models and domains.

The skill operates as a knowledge base, not a runtime executor. It does not call external APIs directly. It produces structured prompt artifacts that agents or users submit to target models.

---

## 2. Problem Statement

AI prompt engineering at scale faces four quantified problems:

| Problem | Measurement | Impact |
|---------|-------------|--------|
| Prompt inconsistency | Same intent produces divergent outputs across sessions | 40–60% iteration waste on prompt refinement |
| Domain knowledge fragmentation | Prompt patterns scattered across teams/docs | Duplicated effort, no institutional learning |
| Model-specific syntax errors | Wrong parameters for target model | Failed generations, wasted API credits |
| No quality feedback loop | No structured way to track prompt effectiveness | Cannot measure improvement over time |

AI Artist eliminates these by providing versioned, domain-specific prompt templates with model-aware parameter injection.

---

## 3. Design Goals

| ID | Goal | Measurable Constraint |
|----|------|-----------------------|
| G1 | Deterministic prompt construction | Same inputs + same template = identical prompt output |
| G2 | Model-portable patterns | Core prompt structure works across Claude, GPT, Gemini without modification |
| G3 | Domain-specific specialization | Separate reference files for code, marketing, image domains (≤ 4 reference files per domain) |
| G4 | Minimal iteration cycles | Target ≤ 3 refinement iterations to reach desired output quality |
| G5 | Measurable prompt quality | Every prompt includes explicit success criteria the output can be validated against |

---

## 4. Non-Goals

| ID | Excluded | Rationale |
|----|----------|-----------|
| NG1 | Direct API calls to LLM/image providers | This skill produces prompts, not API requests; execution is the caller's responsibility |
| NG2 | Prompt response evaluation | Output quality assessment is subjective and model-dependent; owned by the caller |
| NG3 | Fine-tuning or model training | Out of scope; requires specialized ML infrastructure |
| NG4 | Image post-processing | Owned by `media-processing` skill |
| NG5 | Design system generation | Owned by `studio` skill |
| NG6 | Token counting or context window management | Model-specific; handled by `context-engineering` skill |

---

## 5. System Boundaries

| Boundary | Owned | Not Owned |
|----------|-------|-----------|
| Prompt template construction | Pattern composition, parameter injection | API submission, response parsing |
| Domain knowledge | Code, marketing, image prompt patterns | Business-specific terminology |
| Model syntax | Midjourney, DALL-E, SD, Flux parameters | Model version compatibility tracking |
| Quality criteria | Defining success criteria in prompts | Evaluating whether output meets criteria |
| Prompt versioning | Template structure and naming | Storage backend, version control system |

**Side-effect boundary:** AI Artist produces text artifacts (prompts). It does not make network requests, modify files outside the prompt output, or interact with any external service.

---

## 6. Integration Model

### 6.1 Agent Contract

#### Input Schema

```
Domain: string              # One of: "text" | "image" | "code" | "marketing"
Model: string | null        # Target model: "claude" | "gpt" | "gemini" | "midjourney" | "dalle" | "sd" | "flux" | null
Template: string            # Template type: "role-task" | "subject-style" | "chain-of-thought" | "few-shot"
Parameters: {
  role: string | null       # For text: "You are a [role]"
  context: string | null    # Background, constraints, audience
  task: string              # The specific action to perform
  format: string | null     # Desired output format: "markdown" | "json" | "csv" | "plaintext"
  examples: Array<{input: string, output: string}> | null  # Few-shot examples
  constraints: Array<string> | null  # "Under 150 words", "p95 <200ms", etc.
  # Image-specific:
  subject: string | null    # What to generate
  style: string | null      # Visual aesthetic
  composition: string | null # Framing and layout
  quality: string | null    # Render quality markers
  model_params: object | null # Model-specific: --ar, --style, --seed, etc.
}
contract_version: string    # "2.0.0"
```

#### Output Schema

```
Status: "success" | "error"
Data: {
  prompt: string            # The constructed prompt, ready for submission
  model: string             # Target model the prompt is formatted for
  domain: string            # Domain used
  template: string          # Template applied
  token_estimate: number    # Estimated token count (approximate, ±10%)
  success_criteria: Array<string>  # Measurable criteria extracted from constraints
  metadata: {
    version: string         # Prompt template version
    parameters_used: object # Echo of input parameters for reproducibility
    contract_version: string    # "2.0.0"
    backward_compatibility: string  # "breaking"
  }
}
Error: ErrorSchema | null
```

**Contract Version:** 2.0.0
**Backward Compatibility:** breaking (first hardened version)
**Breaking Changes:** None — new spec for first hardening

#### Error Schema

```
Code: string        # From Error Taxonomy (Section 11)
Message: string     # Human-readable, single line
Domain: string      # text | image | code | marketing
Recoverable: boolean
```

#### Deterministic Guarantees

- Same `Domain` + `Template` + `Parameters` = identical `prompt` output, character-for-character.
- Template selection is deterministic: no randomization, no A/B selection.
- Model parameter injection follows fixed ordering rules (subject → style → composition → quality → model_params).
- Token estimates use a fixed heuristic (4 chars per token for English text); no external API calls.

#### What Agents May Assume

- Output `prompt` is syntactically valid for the specified `model`.
- Model-specific parameters (e.g., `--ar 16:9` for Midjourney) are injected in the correct position and format.
- `success_criteria` contains all measurable constraints from the input, extracted verbatim.
- The skill is stateless; no prior invocation affects current output.

#### What Agents Must NOT Assume

- The generated prompt will produce the desired output from the target model (model behavior is non-deterministic).
- Token estimates are exact; they are heuristic-based with ±10% variance.
- Prompt templates are compatible across model versions (model syntax may change across versions).
- The skill validates prompt content for safety, bias, or policy compliance.

#### Side-Effect Boundaries

| Operation | Side Effects |
|-----------|-------------|
| Prompt construction | None; pure function producing text output |
| Template lookup | Read-only access to `rules/` directory |
| Parameter injection | None; string interpolation only |
| Token estimation | None; arithmetic calculation only |

### 6.2 Workflow Contract

#### Invocation Pattern

```
1. Select domain (text | image | code | marketing)
2. Choose template (role-task | subject-style | chain-of-thought | few-shot)
3. Provide parameters (role, task, constraints, examples, etc.)
4. Receive constructed prompt
5. Submit prompt to target model (caller's responsibility)
6. Evaluate output against success_criteria (caller's responsibility)
7. If unsatisfactory: refine parameters, re-invoke (max 3 iterations recommended)
```

#### Execution Guarantees

- Prompt construction is synchronous and completes in a single invocation.
- No background processes, no deferred execution, no callbacks.
- Output is complete and self-contained; no partial prompts are returned.

#### Failure Propagation Model

| Failure Severity | Propagation | Workflow Action |
|-----------------|-------------|-----------------|
| Invalid domain/template | Return error to caller | Fix input parameters |
| Missing required parameter | Return error to caller | Supply missing parameter |
| Unknown model | Return error to caller | Use supported model or null for generic |
| Template file missing | Return error to caller | Verify skill installation |

Failures are isolated to the current invocation. No state carries between invocations.

#### Retry Boundaries

- AI Artist does not retry internally. Given deterministic output, retrying the same input produces the same output.
- Callers should modify parameters between retries to produce different prompt variations.
- Recommended maximum iterations: 3 per generation task.

#### Isolation Model

- Each invocation is stateless and independent.
- No shared state between invocations, sessions, or agents.
- Template files are read-only resources.

#### Idempotency Expectations

| Operation | Idempotent | Notes |
|-----------|-----------|-------|
| Prompt construction | Yes | Same inputs = same output, always |
| Template lookup | Yes | Read-only, no mutation |
| Token estimation | Yes | Deterministic arithmetic |

---

## 7. Execution Model

### 3-Phase Lifecycle

| Phase | Action | Output |
|-------|--------|--------|
| **Parse** | Validate domain, template, parameters | Validated input or error |
| **Compose** | Apply template, inject parameters, format for model | Structured prompt string |
| **Emit** | Return prompt with metadata and success criteria | Complete output schema |

**All phases execute synchronously in a single invocation.** There is no async pipeline, no queue, no deferred processing.

---

## 8. Deterministic Design Principles

| Principle | Enforcement |
|-----------|-------------|
| No randomization | Template selection, parameter ordering, and output formatting are fixed |
| No external calls | Prompt construction uses only local template files and input parameters |
| No ambient state | Each invocation operates solely on explicit inputs |
| Fixed parameter ordering | Image prompts: subject → style → composition → quality → model_params |
| Reproducible output | Input parameters are echoed in output metadata for full reproducibility |

---

## 9. State & Idempotency Model

### State Machine

```
States: IDLE (single state — skill is stateless)
Transitions: None — each invocation is independent
```

AI Artist maintains zero persistent state. Every invocation starts from a clean state and produces output solely from inputs + template files. This makes the skill fully idempotent: invoking it N times with identical inputs produces N identical outputs.

### Template Versioning

- Templates are versioned via `metadata.version` in the SKILL.md frontmatter.
- Template changes that alter output format require a version bump.
- Callers can pin to a specific version by referencing a specific template revision.

---

## 10. Failure Handling Strategy

| Failure Class | Behavior | Caller Recovery |
|---------------|----------|-----------------|
| Unknown domain | Return `ERR_INVALID_DOMAIN` | Use one of: text, image, code, marketing |
| Unknown template | Return `ERR_INVALID_TEMPLATE` | Use one of: role-task, subject-style, chain-of-thought, few-shot |
| Missing required parameter | Return `ERR_MISSING_PARAM` with field name | Supply the missing parameter |
| Unknown model | Return `ERR_UNKNOWN_MODEL` | Use supported model or null for generic format |
| Template file not found | Return `ERR_TEMPLATE_NOT_FOUND` | Verify skill installation integrity |
| Conflicting parameters | Return `ERR_PARAM_CONFLICT` with conflicting fields | Resolve the conflict |
| Parameter exceeds length limit | Return `ERR_PARAM_TOO_LONG` with field and limit | Shorten the parameter value |

**Invariant:** Every failure returns a structured error. No invocation fails silently or returns a partial prompt.

---

## 11. Error Taxonomy

| Code | Category | Recoverable | Description |
|------|----------|-------------|-------------|
| `ERR_INVALID_DOMAIN` | Validation | No | Domain is not one of: text, image, code, marketing |
| `ERR_INVALID_TEMPLATE` | Validation | No | Template is not one of the supported types |
| `ERR_MISSING_PARAM` | Validation | Yes | Required parameter is null or empty |
| `ERR_UNKNOWN_MODEL` | Validation | Yes | Model identifier not recognized; generic format used as fallback |
| `ERR_TEMPLATE_NOT_FOUND` | Infrastructure | No | Reference template file missing from skill directory |
| `ERR_PARAM_CONFLICT` | Validation | Yes | Two parameters contradict each other (e.g., format=json + template=subject-style) |
| `ERR_PARAM_TOO_LONG` | Validation | Yes | Parameter exceeds maximum character limit |

---

## 12. Timeout & Retry Policy

| Parameter | Value | Rationale |
|-----------|-------|-----------|
| Execution timeout | N/A | Prompt construction is synchronous string manipulation; completes in < 50ms |
| Internal retries | Zero | Deterministic output makes retries meaningless for same input |
| Caller retry limit | 3 iterations recommended | Each retry should modify parameters to vary output |
| Template file read timeout | 1,000 ms | Filesystem read; fail immediately if file is inaccessible |

**Retry policy:** Zero internal retries. Since output is deterministic, retrying the same input produces the same result. Callers should modify parameters between invocations.

---

## 13. Observability & Logging Schema

### Log Entry Format

```json
{
  "trace_id": "uuid",
  "skill_name": "ai-artist",
  "contract_version": "2.0.0",
  "execution_id": "uuid",
  "timestamp": "ISO-8601",
  "domain": "string",
  "model": "string|null",
  "template": "string",
  "status": "success|error",
  "error_code": "string|null",
  "prompt_length_chars": "number",
  "token_estimate": "number",
  "duration_ms": "number",
  "parameters_hash": "string"
}
```

### Required Log Points

| Event | Log Level | Fields |
|-------|-----------|--------|
| Prompt constructed | INFO | All fields |
| Construction failed | ERROR | All fields + error_code |
| Template file read | DEBUG | template path, read duration |
| Unknown model fallback | WARN | requested model, fallback used |

### Metrics

| Metric | Type | Unit |
|--------|------|------|
| `prompt.construction.duration` | Histogram | ms |
| `prompt.construction.error_rate` | Counter | per error_code |
| `prompt.output.char_count` | Histogram | characters |
| `prompt.output.token_estimate` | Histogram | tokens |
| `prompt.domain.usage` | Counter | per domain |
| `prompt.model.usage` | Counter | per model |

---

## 14. Security & Trust Model

### Content Safety

- AI Artist does not filter or validate prompt content for safety, bias, or policy compliance.
- Content moderation is the caller's responsibility before submitting generated prompts to target models.
- This boundary is explicit: the skill is a prompt construction tool, not a content governance tool.

### Credential Handling

- AI Artist does not store, process, or transmit API keys, tokens, or credentials.
- Model-specific authentication is the caller's responsibility.

### Template Integrity

- Template files in `rules/` are read-only resources.
- Template modifications require a version bump in SKILL.md frontmatter.
- No runtime template injection; templates are static files, not user-supplied code.

### Input Sanitization

- User-supplied parameters are interpolated as literal strings into templates.
- No template evaluation engine (no eval, no code execution from parameters).
- Parameters containing template syntax markers are escaped before interpolation.

### Multi-Tenant Boundaries

- Each invocation is stateless; no data persists between invocations.
- No invocation can access parameters or outputs from another invocation.

---

## 15. Scalability Model

| Dimension | Constraint | Mitigation |
|-----------|-----------|------------|
| Throughput | CPU-bound string manipulation | Scales linearly with CPU; no bottleneck |
| Concurrency | Stateless invocations | Unlimited parallel invocations; no shared state |
| Template storage | 4 reference files (~8 KB total) | Static files; no growth concern |
| Memory per invocation | < 1 MB (prompt + metadata) | No accumulation; GC after return |
| Network | Zero network calls | No external dependency |

### Capacity Planning

| Metric | Per Invocation | Per Node |
|--------|---------------|----------|
| CPU | < 5 ms computation | 200,000+ invocations/second (single core) |
| Memory | < 1 MB | Bound only by concurrent invocations |
| Disk I/O | Single template file read (~2 KB) | Cached by OS after first read |
| Network | Zero | Zero |

---

## 16. Concurrency Model

| Scope | Model | Behavior |
|-------|-------|----------|
| Within invocation | Sequential | Parse → Compose → Emit, no internal parallelism |
| Across invocations | Fully parallel | No shared state, no locks, no coordination needed |
| Template access | Read-only shared | Multiple concurrent reads are safe; no write contention |

**No undefined behavior:** Since the skill is stateless with read-only resource access, any level of concurrency is safe by design.

---

## 17. Resource Lifecycle Management

| Resource | Created By | Destroyed By | Max Lifetime |
|----------|-----------|-------------|--------------|
| Prompt string | Compose phase | Caller (after consumption) | Invocation scope |
| Template file handle | Parse phase | Emit phase (auto-close) | < 10 ms |
| Input parameters | Caller | Invocation completion | Invocation scope |
| Output metadata | Emit phase | Caller (after consumption) | Invocation scope |

**Leak prevention:** All resources are scoped to a single invocation. No persistent handles, connections, or buffers.

---

## 18. Performance Constraints

| Operation | P50 Target | P99 Target | Hard Limit |
|-----------|-----------|-----------|------------|
| Full prompt construction | < 5 ms | < 20 ms | 50 ms |
| Template file read | < 1 ms | < 5 ms | 1,000 ms |
| Token estimation | < 1 ms | < 1 ms | 5 ms |
| Output prompt size (text) | ≤ 500 chars | ≤ 2,000 chars | 10,000 chars |
| Output prompt size (image) | ≤ 200 chars | ≤ 500 chars | 2,000 chars |

---

## 19. Operational Risks

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Model syntax changes | Medium | Prompts use outdated parameters | Version model syntax in `rules/model-syntax.md`; update on model releases |
| Prompt injection via parameters | Medium | Malicious content in generated prompts | Caller responsibility; AI Artist does literal interpolation, not evaluation |
| Template file corruption | Low | Construction failures | `ERR_TEMPLATE_NOT_FOUND`; re-install skill from source |
| Over-reliance on token estimates | High | Prompts exceed model context window | Estimates are ±10%; callers must validate against actual model limits |
| Domain pattern staleness | Medium | Patterns become less effective over time | Periodic review cycle; version bumps signal updates |

---

## 20. Compliance with skill-design-guide.md

| Requirement | Status | Evidence |
|-------------|--------|----------|
| YAML frontmatter complete | ✅ | name, description, metadata with category, version, triggers, coordinates_with, success_metrics |
| SKILL.md < 200 lines | ✅ | Entry point SKILL.md under 200 lines; details in rules/ |
| Prerequisites documented | ✅ | No external dependencies required |
| When to Use section | ✅ | Domain-based decision matrix |
| Quick Reference with patterns | ✅ | LLM and image prompt patterns with examples |
| Core content matches skill type | ✅ | Expert type: domain knowledge tables, prompt patterns |
| Troubleshooting section | ✅ | Problem/solution table |
| Related section | ✅ | Cross-links to studio, media-processing |
| Content Map for multi-file | ✅ | Links to 4 reference files + engineering-spec.md |
| Contract versioning | ✅ | contract_version, backward_compatibility, breaking_changes |
| Compliance matrix structured | ✅ | This table with ✅/❌ + evidence |

---

## 21. Production Readiness Checklist

| Category | Check | Status |
|----------|-------|--------|
| **Functionality** | All 4 domains (text, image, code, marketing) specified | ✅ |
| **Functionality** | All 4 templates (role-task, subject-style, chain-of-thought, few-shot) specified | ✅ |
| **Functionality** | 7 model targets specified with fallback behavior | ✅ |
| **Contracts** | Input/output/error schemas defined | ✅ |
| **Contracts** | Agent assumptions and non-assumptions documented | ✅ |
| **Contracts** | Workflow invocation pattern specified | ✅ |
| **Failure** | Error taxonomy with 7 categorized error codes | ✅ |
| **Failure** | No silent failures; every error returns structured response | ✅ |
| **Failure** | Retry policy: zero internal retries, caller-owned | ✅ |
| **Determinism** | Same inputs = same output guaranteed | ✅ |
| **Determinism** | No randomization, no external calls, no ambient state | ✅ |
| **Security** | No credential handling; no content filtering (explicit boundary) | ✅ |
| **Security** | Input sanitization: literal interpolation, no eval | ✅ |
| **Observability** | Structured log schema with 4 log points | ✅ |
| **Observability** | 6 metrics defined with types and units | ✅ |
| **Performance** | P50/P99 targets for all operations | ✅ |
| **Scalability** | Stateless; unlimited parallel invocations | ✅ |
| **Concurrency** | No shared state; read-only template access | ✅ |
| **Resources** | All resources scoped to invocation lifetime | ✅ |
| **Idempotency** | Fully idempotent — all operations are pure functions | ✅ |
| **Compliance** | All skill-design-guide.md sections present | ✅ |

---



---

## 🔗 Related

| File | When to Read |
|------|-------------|
| [image-prompts.md](image-prompts.md) | Image generation techniques |
| [domain-marketing.md](domain-marketing.md) | Marketing copy patterns |
| [domain-code.md](domain-code.md) | Code generation patterns |
| [model-syntax.md](model-syntax.md) | Model-specific parameters |
| [../SKILL.md](../SKILL.md) | Quick reference and anti-patterns |

---

⚡ PikaKit v3.9.162