wotai-dev/woterclip/persona-import

Import Persona from Paperclip

Convert a Paperclip agent directory into a WoterClip persona. Maps Paperclip's agent structure (SOUL.md, AGENTS.md, HEARTBEAT.md, TOOLS.md) to WoterClip's persona structure (SOUL.md, TOOLS.md, config.yaml).

Prerequisites

• .woterclip/config.yaml must exist (run /woterclip-init first)
• User must provide the path to the Paperclip agent directory

File Mapping

Import Procedure

Step 1: Read Source

Ask the user for the Paperclip agent directory path. Read all files present:

• SOUL.md (required)
• AGENTS.md (optional)
• HEARTBEAT.md (optional)
• TOOLS.md (optional)

If SOUL.md doesn't exist, stop — this is not a valid Paperclip agent directory.

Step 2: Ask for Persona Details

Ask the user:

1. Persona name — e.g., "Backend Engineer" (pre-fill from SOUL.md if obvious)
2. GitHub label — e.g., backend (must be unique)
3. Role type — engineer, orchestrator, analyst, or custom
4. Model — opus, sonnet, or haiku (suggest based on role)
5. Escalates to — default: ceo

Step 3: Transform SOUL.md

1. Start with the Paperclip SOUL.md content
2. From HEARTBEAT.md: extract the role-specific section (usually the bottom half, after the generic heartbeat steps). Append as a "## Working Style" or "## Role Responsibilities" section
3. From AGENTS.md: extract safety rules and boundaries. Append to the "## Boundaries" section
4. Add a WoterClip-specific "## Quality Checklist" section if not present
5. Drop any Paperclip-specific references (workspace paths, PARA memory, budget tracking)

Step 4: Transform TOOLS.md

1. Start with the Paperclip TOOLS.md content
2. Replace Paperclip API references:

• paperclip skill → gh CLI commands (gh issue view/edit/comment, etc.)
• para-memory-files → drop (replaced by Claude Code built-in memory)
• Paperclip API calls (POST /checkout, PATCH /api/issues) → gh CLI equivalents

1. Add a "## Required" section listing gh and any other tools
2. If AGENTS.md references playbooks, note them for manual migration

Step 5: Generate config.yaml

Create the persona config:

name: <Name>
role: <role>
label: <label>
escalates_to: <escalates_to>
 
required_tools:
  - gh
  # additional tools based on TOOLS.md
 
runtime:
  model: <model>
  thinking_effort: <high for opus, medium otherwise>
  max_turns: <300 for opus, 200 for sonnet, 100 for haiku>
  enable_chrome: false
  timeout: 0
  extra_args: []

Step 6: Write Files

1. Create .woterclip/personas/<label>/
2. Write SOUL.md, TOOLS.md, config.yaml
3. Update .woterclip/config.yaml to add the persona to the personas map
4. Create the GitHub label if it doesn't exist (gh label create)

Step 7: Summary

Imported: <Name> (from <source-path>)
  Label:    <label>
  Model:    <model>
 
Files created:
  ✓ .woterclip/personas/<label>/SOUL.md
  ✓ .woterclip/personas/<label>/TOOLS.md
  ✓ .woterclip/personas/<label>/config.yaml
 
What was imported:
  ✓ SOUL.md — identity and posture
  ✓ HEARTBEAT.md — role responsibilities (appended to SOUL.md)
  ✓ AGENTS.md — safety rules (appended to Boundaries)
  ✓ TOOLS.md — tool list (Paperclip refs replaced)
 
What was NOT imported:
  ✗ Budget tracking (no WoterClip equivalent)
  ✗ PARA memory (replaced by Claude Code built-in memory)
  ✗ Approval workflows (not in v1)
 
Review SOUL.md and customize for this project's specific needs.