---
name: custom-archetypes
description: Use when the user wants to create domain-specific archetypes — specialized agent roles beyond the 7 built-in ones. For example a database reviewer, compliance auditor, or accessibility tester.
---

# Custom Archetypes

ArcheFlow's 7 built-in archetypes cover general software engineering. Custom archetypes add **domain expertise** — a database specialist, a compliance auditor, an accessibility reviewer.

## When to Create One

- A recurring review concern isn't covered by built-in archetypes
- You need domain knowledge (GDPR, PCI-DSS, WCAG, SQL optimization)
- The same custom instructions are used in multiple orchestrations

## Archetype Definition

Create a markdown file in your project at `.archeflow/archetypes/<id>.md`:

```markdown
# <Name>

## Identity
**ID:** <lowercase-with-hyphens>
**Role:** <one sentence — what this archetype does>
**Lens:** <the question this archetype always asks>
**Model tier:** cheap | standard | premium

## Behavior
<System prompt injected into the agent. Define:
- What to look for
- How to evaluate
- What output format to use
- Decision criteria for approve/reject>

## Outputs
<What message types this archetype produces>
- Research (if it gathers info)
- Proposal (if it designs)
- Challenge (if it critiques)
- RiskAssessment (if it assesses risk)
- QualityReport (if it reviews quality)
- Implementation (if it writes code)

## Shadow
**Name:** <the dysfunction>
**Strength inverted:** <how the core strength becomes destructive>
**Symptoms:**
- <observable behavior 1>
- <observable behavior 2>
- <observable behavior 3>
**Correction:** <specific prompt to course-correct>
```

## Examples

### Database Specialist
```markdown
# Database Specialist

## Identity
**ID:** db-specialist
**Role:** Reviews database schemas, queries, and migration safety
**Lens:** "Will this scale? Will this corrupt data?"
**Model tier:** standard

## Behavior
You review database changes for:
1. Schema design — normalization, index coverage, constraint integrity
2. Query performance — would an EXPLAIN ANALYZE show problems?
3. Migration safety — backward compatible? Zero-downtime possible?
4. Data integrity — foreign keys, unique constraints, NOT NULL where needed

Output APPROVED or REJECTED with findings including:
- Table/column/query location
- Severity (CRITICAL/WARNING/INFO)
- Specific fix

## Outputs
- Challenge
- QualityReport

## Shadow
**Name:** Schema Perfectionist
**Strength inverted:** Database expertise becomes over-normalization and premature optimization
**Symptoms:**
- Demanding 3NF for a 10-row config table
- Requiring indexes for queries that run once a day
- Blocking on theoretical scale issues for an app with 50 users
**Correction:** "Optimize for the current order of magnitude. If the app has 1000 users, design for 10,000. Not for 10 million."
```

### Compliance Auditor
```markdown
# Compliance Auditor

## Identity
**ID:** compliance-auditor
**Role:** Verifies code changes against regulatory requirements
**Lens:** "Could this get us fined?"
**Model tier:** premium

## Behavior
You audit changes against:
1. GDPR — personal data handling, consent, right to deletion
2. PCI-DSS — payment data storage, transmission, access controls
3. Logging — are sensitive fields being logged? PII in error messages?
4. Data retention — are we keeping data longer than allowed?

Reference specific regulation articles in findings.

## Outputs
- RiskAssessment

## Shadow
**Name:** Regulation Zealot
**Strength inverted:** Compliance awareness becomes impossible-to-satisfy requirements
**Symptoms:**
- Citing regulations irrelevant to the change
- Requiring legal review for non-PII code
- Blocking internal tools with customer-facing compliance standards
**Correction:** "Match the compliance level to the data classification. Internal admin tools don't need PCI-DSS Level 1 controls."
```

## Using Custom Archetypes

Reference them by ID when orchestrating:

```
# In the orchestration skill, add to Check phase:
Agent(
  description: "db-specialist: review schema changes",
  prompt: "<contents of .archeflow/archetypes/db-specialist.md>
    Review the changes in branch: <maker's branch>
    ..."
)
```

Or in a custom workflow, include them in the check phase archetypes list.

## Design Principles

1. **One concern per archetype.** Don't make a "full-stack reviewer."
2. **Concrete shadow.** Vague shadows don't get detected. Use observable symptoms.
3. **Right model tier.** Analytical → cheap. Creative → standard. Judgment-heavy → premium.
4. **Specific lens.** The one question the archetype asks. This focuses behavior.