claude-archeflow-plugin/skills/custom-archetypes/SKILL.md

name, description

name	description
custom-archetypes	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:

# <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

# 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

# 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.

Archetype Composition

Combine two archetypes into a focused super-reviewer when you need a specific perspective but don't want to spawn two agents:

# .archeflow/archetypes/security-breaker.md

## Identity
**ID:** security-breaker
**Composed of:** Guardian + Trickster
**Role:** Security review with active exploitation attempts
**Lens:** "Can I break the security model? How?"
**Model tier:** standard

## Behavior
Combine Guardian's checklist-driven security review with Trickster's
adversarial testing. For each Guardian finding, attempt to exploit it.
Only report findings you can actually reproduce.

## Shadow
**Name:** Security Theater
**Strength inverted:** Both shadows compound — paranoid blocking + noise
**Correction:** "Only report findings with reproduction steps. Max 5."

Rules for composition:

• Max 2 archetypes combined (more defeats the purpose)
• Combined shadow must address both source shadows
• Use when spawning both separately would waste tokens on overlapping context

Team Presets

Save common team configurations for your project in .archeflow/teams/:

# .archeflow/teams/backend.yaml
name: backend
description: Standard backend development team
plan: [explorer, creator]
do: [maker]
check: [guardian, sage]
exit: all_approved
max_cycles: 2

# .archeflow/teams/security-audit.yaml
name: security-audit
description: Security-focused review team
plan: [explorer, creator]
do: [maker]
check: [guardian, trickster, compliance-auditor]
exit: all_approved
max_cycles: 3

Use in orchestration: "Use the backend team preset" or "Run security-audit workflow on this change"

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.
5. Composition over sprawl. Combine before creating from scratch. 2 composed > 3 separate.