# How to Customize Archetypes and Negotiation Scripts in career‑ops

> Learn how to customize archetypes and negotiation scripts in career-ops by editing your profile files. Personalize your career development experience efficiently.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: how-to-guide
- Published: 2026-08-28

---

**To customize archetypes and negotiation scripts in career‑ops, edit [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) for your personal content and optionally [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) for CLI integration—never modify the system files in [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md).**

Customizing archetypes and negotiation scripts is the core personalization workflow in **career‑ops**, an open-source career management tool by [santifer](https://github.com/santifer/career-ops). The repository uses a layered architecture that separates immutable system logic from user-specific content, allowing you to tailor role-matching and offer negotiation without risking your changes on future updates.

## Understanding the Layered Architecture

career‑ops loads content in two distinct layers. Understanding this precedence rule is essential to customizing archetypes and negotiation scripts correctly.

| Layer | Purpose | Where to edit |
|-------|---------|-------------|
| **System Layer** | Default scoring rules, market vocabulary, and baseline logic. | [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) — **do not edit for personalization** |
| **User Layer** | Your target roles, archetypes, narrative framing, proof points, and negotiation scripts. | [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) (from [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md)) and [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) |

The loading sequence is hardcoded: [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) is parsed **first**, then [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) is overlaid. Because your user-layer file loads last, **your overrides always take precedence**. This is explicitly documented in the template header at [`modes/_profile.template.md#L3-L11`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md#L3-L11):

> "This file is loaded *after* [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md), so anything you define here wins."

This design means you can safely pull repository updates without merge conflicts in your personalized content.

## Customizing Archetypes in career‑ops

Archetypes define the roles you are targeting, the thematic axes that characterize each, and the value propositions that resonate with hiring managers for those positions.

### Editing the Archetype Table

In [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md), locate the **Your Target Roles** section. This Markdown table is where you enumerate your archetypes:

```markdown

## Your Target Roles

| Archetype | Thematic axes | What they buy |
|-----------|---------------|---------------|
| **Data Engineer** | Pipelines, warehousing, GDPR | Companies that need scalable data platforms |
| **Machine Learning Engineer** | Model ops, feature stores, monitoring | Teams building production AI |
| **AI Product Manager** | Roadmapping, stakeholder alignment, metrics | Product orgs looking for AI‑driven products |

```

The system parses this table during evaluation mode to compute **fit scores** against job postings. Each row you add, remove, or reorder directly influences how [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) scores opportunities.

### Syncing Archetypes for CLI Filtering

To enable the CLI to filter and prioritize scans based on your archetypes, mirror your archetypes in [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml):

```yaml
target_roles:
  archetypes:
    - name: "Data Engineer"
      level: "Senior"
      fit: "primary"
    - name: "Machine Learning Engineer"
      level: "Staff"
      fit: "secondary"
    - name: "AI Product Manager"
      level: "Senior"
      fit: "adjacent"

```

According to the career‑ops source code, `node doctor.mjs` and other entry points read [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) for raw structured data before applying your Markdown overrides. The `target_roles.archetypes` list drives downstream tooling behavior, including scan filtering and report prioritization.

## Customizing Negotiation Scripts in career‑ops

Negotiation scripts are pre-written language blocks that the system injects into generated reports, offer-prep documents, and email drafts. These live in the same user-layer file as your archetypes.

### Editing Negotiation Script Blocks

In [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md), scroll to the **Your Negotiation Scripts** section. This section contains free-form Markdown that the engine extracts and inserts into the "Negotiation" block of evaluation reports.

```markdown

## Your Negotiation Scripts

**Salary expectations:**
> "Based on market data for this role, I'm targeting $120K–$150K total compensation. I'm open to structuring the package to include equity or bonus."

**Geographic discount pushback:**
> "My performance is location‑agnostic; the outcomes I've delivered are remote‑first. I prefer a remote arrangement with occasional onsite syncs."

**When offered below target:**
> "I appreciate the offer. My research indicates similar roles at $130K–$150K. Could we explore a higher base or additional equity?"

```

Because these are plain Markdown sections, you can:
- Add new script categories (e.g., "Relocation assistance," "Signing bonus")
- Reorder existing blocks by priority
- Delete boilerplate you do not need

The evaluation engine in [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) consumes these sections verbatim when building your personalized negotiation brief.

## Step-by-Step Setup Workflow

Follow this sequence to activate your customizations for the first time:

1. **Copy the profile template**
   ```bash
   cp modes/_profile.template.md modes/_profile.md
   ```

2. **Edit [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md)** — Replace placeholder archetypes and negotiation blocks with your own content using the snippet patterns above.

3. **Optionally configure [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml)** — Copy the example and fill in your details:
   ```bash
   cp config/profile.example.yml config/profile.yml
   ```

   Edit `target_roles.archetypes` to match your [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) table for CLI integration.

4. **Verify your customization** — Run a command and inspect the output:
   ```bash
   codex exec "career‑ops oferta <job-url>"
   ```

   Your archetype table and negotiation scripts will appear in the generated report's evaluation and negotiation sections.

## How the System Processes Your Customizations

The architectural flow is implemented across three phases, as defined in the career‑ops source code:

1. **Load profile** — Entry points like `node doctor.mjs` ingest [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) for core personal data (name, location, compensation ranges).

2. **Read overrides** — The mode loader parses [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) for system defaults, then immediately overlays [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md).

3. **Evaluation** — When [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) processes a job posting, it pulls your archetype table to compute fit scores and inserts your negotiation scripts into the report's final "Negotiation" block.

This data contract is enforced by the merge logic that handles the two layers. No code changes are required to personalize archetypes and negotiation scripts—only edits to the designated user-layer files.

## Key Files Reference

| File | Purpose |
|------|---------|
| [[`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md)](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md) | Starter template with annotated sections for archetypes, framing, and negotiation scripts. |
| [[`config/profile.example.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.example.yml)](https://github.com/santifer/career-ops/blob/main/config/profile.example.yml) | Schema for structured personal data that the CLI reads before Markdown overrides. |
| [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) | System defaults and scoring logic—**read-only for users**. |
| [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) | Evaluation mode that consumes your archetypes and scripts to generate reports. |

## Summary

- **Edit [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md)** to customize archetypes and negotiation scripts—this is the sole supported user-layer file for personal content.
- **Optionally edit [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml)** to enable CLI filtering and tooling integration for your archetypes.
- **Never modify [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md)**; it contains system defaults that are overwritten on repository updates.
- The **overlay loading order** ([`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) first, [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) second) guarantees your customizations always apply.
- Changes take effect immediately on the next report generation—no rebuild or restart required.

## Frequently Asked Questions

### What happens if I edit [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) instead of [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md)?

Your changes will work temporarily, but will be lost when you pull repository updates. The [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) file is tracked in version control and overwritten on every sync. The [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) file is gitignored by convention, ensuring your personalizations persist across updates.

### How does the system know which archetype fits a job posting?

The evaluation engine in [`modes/oferta.md`](https://github.com/santifer/career-ops/blob/main/modes/oferta.md) parses your archetype table from [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) and matches keywords in the job description against your "Thematic axes" column. It produces a fit score based on this intersection, weighted by your [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) `fit` declarations (`primary`, `secondary`, `adjacent`).

### Can I use multiple [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) files for different career pivots?

The current architecture supports a single [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) per workspace. For distinct career pivots, maintain separate directories or branches with isolated [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) files, then symlink or copy the appropriate version before running commands.

### Do I need to restart the CLI after editing my profile files?

No. Both [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) and [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml) are read fresh on every command execution. Changes are immediate—no daemon, cache invalidation, or restart is required.