What Is the Difference Between _profile.md and _shared.md Customization in Career-Ops?

Career-Ops separates system-wide configuration from personalized user data through a layered architecture where modes/_shared.md contains auto-updatable engine logic and modes/_profile.md stores persistent user customizations that survive system upgrades.

Career-Ops employs a dual-file customization strategy to balance flexible personal configuration with stable system updates. Understanding the distinction between _profile.md and _shared.md customization ensures your career data persists while the underlying scoring engine remains current. This guide explains how these files function within the santifer/career-ops repository.

Understanding _shared.md: System-Wide Configuration

The file modes/_shared.md serves as the system context that powers the Career-Ops engine. This Markdown file contains the core, auto-updatable logic that the system relies on for evaluation workflows.

Purpose and Content

_shared.md defines the universal rules and infrastructure that apply to all users of the repository. According to the source code, it contains:

• Sources of Truth – Lists the canonical files (cv.md, article-digest.md, config/profile.yml, _profile.md) that the system reads during evaluation
• Scoring System – Defines the six evaluation blocks and global score calculation methodology
• Archetype Detection – Maps job description keywords to internal archetypes used for matching
• Global Rules – "NEVER" and "ALWAYS" directives that enforce safe, consistent behavior across the engine

Lifecycle and Auto-Updates

This file must never contain personal data because it is updated automatically when the project is upgraded. Running node update-system.mjs overwrites _shared.md with the latest upstream logic, ensuring you receive improvements to scoring algorithms and rule definitions without manual intervention.

Understanding _profile.md: User Profile Context

The file modes/_profile.md represents the user context layer where all personal career information resides. This file is generated from modes/_profile.template.md and captures your unique professional narrative.

Purpose and Content

Unlike the system file, _profile.md stores everything a person wants to customize about their job search:

• Your Target Roles – A table mapping archetypes to specific job titles you are pursuing
• Your Adaptive Framing – Projects mapped to each archetype with pointers to source files like cv.md
• Your Negotiation Scripts – Personalized salary-range language and push-back messages
• Your Location Policy – Availability, timezone preferences, and remote-work requirements
• Your Comp Targets – Market-research guidance and compensation goals

Persistence Across Updates

Created from the template on first run, _profile.md is never auto-updated. Only you (or an assistant) edit this file, ensuring that customizations survive system upgrades. When node update-system.mjs executes, it leaves your personal profile untouched while refreshing the underlying engine logic.

How the Layered Architecture Processes Both Files

The engine follows a deterministic loading order that enables safe customization. During evaluation, Career-Ops first reads _shared.md to load default scoring logic and system rules. Immediately after, it reads _profile.md to overlay your personal overrides.

As implemented in line 23 of modes/_shared.md, the system processes _profile.md after _shared.md. This sequencing ensures that any matching keys in your user profile win over the defaults. You can safely tune the system to your career without risking loss of changes when the repository is updated.

Practical Customization Examples

Accessing Both Files from a Script

When building tooling around Career-Ops, you can load both configuration layers to understand the complete context:

import { readFile } from 'fs/promises';

async function loadContext() {
  const shared = await readFile('modes/_shared.md', 'utf8');
  const profile = await readFile('modes/_profile.md', 'utf8');
  // shared provides defaults, profile provides overrides
  return { shared, profile };
}

Adding a Custom Archetype

Extend your targeting without modifying system files by editing only _profile.md:

## Your Target Roles

| Archetype | Thematic axes | What they buy |
| --------- | ------------- | ------------- |
| **Data Engineering** | Pipelines, streaming, observability | Engineers who reliably ship data pipelines at scale |

The scoring logic in _shared.md automatically recognizes this new archetype during evaluation because the user layer extends the system definitions.

Overriding System Defaults

To implement a stricter remote-work policy than the default, add to _profile.md:

## Your Location Policy

- **Remote preference:** Only fully-remote roles (no hybrid).
- **Timezone overlap:** Must overlap ≥ 6 hours with EST.

The engine honors these values because they appear in the user layer, while the generic rule in _shared.md remains unchanged for future updates.

Summary

• modes/_shared.md holds auto-updatable system logic including scoring rules, archetype detection, and global constraints that are overwritten during node update-system.mjs
• modes/_profile.md stores personal career data like target roles, negotiation scripts, and location policies that persist across system upgrades
• The engine reads _shared.md first, then overlays _profile.md values (as referenced in line 23 of the shared configuration)
• Generate your initial profile from modes/_profile.template.md and edit only _profile.md to ensure customizations survive updates

Frequently Asked Questions

What happens if I accidentally edit _shared.md?

Any changes to modes/_shared.md will be permanently lost the next time you run node update-system.mjs. The update script fetches the latest system logic and overwrites this file completely. If you need to customize behavior, use modes/_profile.md instead, which the system reads after _shared.md and which survives updates.

How do I create my initial _profile.md?

Career-Ops generates modes/_profile.md automatically from modes/_profile.template.md on your first run of the system. You should copy the template structure and fill in your specific target roles, compensation targets, and narrative framing. Never edit the template file directly; work only in your generated _profile.md.

Can I override scoring rules from _shared.md in my _profile.md?

Yes. The layered architecture explicitly supports this workflow. Because the engine processes _profile.md after _shared.md, any configuration keys or narrative instructions you define in your profile take precedence over the system defaults. This allows you to customize evaluation behavior without forking the core logic.

Where does the engine read these files in the source code?

The system references these files within the modes/ directory hierarchy. Specifically, line 23 of modes/_shared.md documents the loading sequence where _profile.md is read after the shared configuration. Additional structured data lives in config/profile.yml, which the system also accesses alongside these Markdown context files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}