resume-as-code-ng 2.0.2

CLI tool for git-native resume generation from structured work units

Resume as Code

Treat your career data as structured, queryable truth.

CLI tool for git-native resume generation from structured Work Units.

The Philosophy

Your career accomplishments are immutable facts — what you've done doesn't change. But every job application requires a different view of your experience.

Resume as Code inverts the traditional model: instead of editing documents, you maintain structured Work Units and generate targeted resumes as queries against your capability graph. The resume becomes a view, not a source of truth.

Read the full philosophy

Features

• Work Unit Capture — Record accomplishments with Problem-Action-Result structure and archetype templates
• Schema Validation — Ensure data quality with actionable feedback on weak verbs, missing metrics, and incomplete fields
• Hybrid Ranking — BM25 keyword matching + semantic similarity for intelligent Work Unit selection
• Skill Coverage Analysis — See which skills are covered and identify gaps before submitting
• Multiple Output Formats — Generate PDF and DOCX with consistent formatting
• Executive Templates — CTO/VP-level templates with career highlights, board roles, and publications
• Position Management — Track employment history with scope indicators (revenue, team size, P&L)
• Certification Tracking — Manage credentials with expiration status monitoring
• Full Provenance — Manifest tracks exactly which Work Units were included and why

Quick Start

Installation

From PyPI (recommended):

pip install resume-as-code

With optional features:

# LLM-powered features (anthropic, openai)
pip install resume-as-code[llm]

# NLP features (spacy)
pip install resume-as-code[nlp]

# All optional dependencies
pip install resume-as-code[llm,nlp]

From source (development):

git clone https://github.com/drbothen/resume-as-code
cd resume-as-code
uv sync --all-extras

macOS PDF Generation — WeasyPrint requires system libraries:

brew install pango cairo
export DYLD_LIBRARY_PATH="$(brew --prefix)/lib:$DYLD_LIBRARY_PATH"

Initialize Your Resume Project

# Initialize with placeholders (non-interactive)
resume init --non-interactive

# Or interactive mode for guided setup
resume init

Create Your First Work Unit

# Interactive mode with archetype template
resume new work-unit --archetype greenfield

Validate Your Data

resume validate

Generate a Resume

# Preview what will be selected
resume plan --jd job-description.txt

# Generate PDF and DOCX
resume build --jd job-description.txt

Check dist/ for your generated resume files.

Command Reference

Resource Creation

Command	Description
resume new work-unit	Create a Work Unit (use --archetype for templates)
resume new position	Create an employment position
resume new certification	Add a professional certification
resume new education	Add an education entry
resume new publication	Add a publication or speaking engagement
resume new board-role	Add a board or advisory position
resume new highlight	Add a career highlight (executive format)

Resource Management

Command	Description
resume list	List all Work Units (supports filtering)
resume list positions	List employment positions
resume list certifications	List certifications with expiration status
resume list education	List education entries
resume list highlights	List career highlights
resume list board-roles	List board and advisory roles
resume list publications	List publications and speaking engagements
resume show work-unit <id>	Show Work Unit details
resume show position <id>	Show position details
resume show certification <name>	Show certification details
resume show education <degree>	Show education entry details
resume show highlight <index>	Show career highlight details
resume show board-role <org>	Show board role details
resume show publication <title>	Show publication details
resume remove work-unit <id>	Remove a Work Unit
resume remove position <id>	Remove a position
resume remove certification <name>	Remove a certification
resume remove education <degree>	Remove an education entry
resume remove highlight <index>	Remove a career highlight
resume remove board-role <org>	Remove a board role
resume remove publication <title>	Remove a publication

Work Unit Filtering — The resume list command supports filtering:

# Filter by tag
resume list --filter tag:kubernetes

# Filter by confidence level
resume list --filter confidence:high

# Free text search (ID, title, date)
resume list --filter "migration"

# Combine filters (AND logic)
resume list --filter tag:aws --filter confidence:high

Validation and Generation

Command	Description
resume validate	Validate Work Units against schema
resume validate --content-quality	Check weak verbs and quantification
resume validate --content-density	Check bullet point character limits
resume validate --check-positions	Verify position references exist
resume plan --jd <file>	Preview Work Unit selection for a JD
resume plan --top <n>	Select top N Work Units (default: 8)
resume plan --show-excluded	Show top 5 excluded Work Units with reasons
resume plan --output <file>	Save plan to file for later use
resume plan --load <file>	Load and display a saved plan
resume build --jd <file>	Generate resume files
resume build --plan <file>	Build from a saved plan file
resume build --format <type>	Output format: pdf, docx, or all
resume build --template <name>	Template to use (modern, executive)

Utility Commands

Command	Description
resume config	View current configuration
resume config --list	Show all config values with sources
resume cache stats	Show embedding cache statistics
resume cache clear	Clear stale cache entries

Schema Migration

Command	Description
resume migrate --status	Show current schema version and migration status
resume migrate --dry-run	Preview changes without modifying files
resume migrate	Apply schema migrations (with confirmation)
resume migrate --rollback <backup>	Restore from backup directory

Migrations automatically detect legacy configs (no schema_version field) and offer to upgrade them. Backups are created before any changes.

Global Flags

Flag	Description
--json	Output in JSON format for scripting
-v, --verbose	Show verbose debug output
-q, --quiet	Suppress output, exit code only
-y, --yes	Skip confirmation prompts (remove commands)

Work Unit Archetypes

Archetypes are pre-filled templates that provide structure and guidance for common achievement types. Each archetype includes PAR (Problem-Action-Result) prompts, example text, and relevant fields.

Archetype	Use Case	Best For
greenfield	New system/feature built from scratch	Launching products, building platforms, creating new capabilities
incident	Production incident response	Outages, security events, escalations, on-call heroics
optimization	Performance or cost improvements	Reducing latency, cutting costs, improving efficiency
migration	System/data migration projects	Cloud migrations, platform upgrades, technology transitions
leadership	Team building and mentorship	Hiring, growing teams, developing talent, culture initiatives
transformation	Large-scale organizational change	Digital transformation, process overhauls, major initiatives
strategic	Strategic initiatives and planning	Roadmap definition, architecture decisions, cross-org alignment
cultural	Culture and values initiatives	DEI programs, engagement improvements, organizational health
minimal	Quick capture with basic structure	Fast notes when you'll fill in details later

Using Archetypes

# Interactive mode (opens editor with template)
resume new work-unit --archetype greenfield

# Non-interactive with title (for LLM/scripting)
resume new work-unit --archetype incident \
  --title "Resolved P1 database outage" \
  --position-id pos-techcorp-engineer \
  --no-edit

Examples

Creating Work Units for Different Scenarios

# Project from scratch
resume new work-unit --archetype greenfield \
  --title "Built multi-region deployment platform"

# Incident response
resume new work-unit --archetype incident \
  --title "Resolved P1 outage affecting 50K users"

# Leadership/team building
resume new work-unit --archetype leadership \
  --title "Scaled engineering team from 5 to 25 engineers"

# Cost optimization
resume new work-unit --archetype optimization \
  --title "Reduced cloud spend by 40% through right-sizing"

# Platform migration
resume new work-unit --archetype migration \
  --title "Led zero-downtime migration to Kubernetes"

Creating Position History

# Pipe-separated format (LLM-friendly)
resume new position "TechCorp|Senior Platform Engineer|2022-01|"

# With executive scope indicators
resume new position \
  --employer "Acme Corp" \
  --title "CTO" \
  --start-date 2020-01 \
  --scope-revenue "\$500M" \
  --scope-team-size 150 \
  --scope-pl "\$100M"

Linking Work Units to Positions

# Check position IDs
resume --json list positions | jq '.[].id'

# Create work unit linked to position
resume new work-unit \
  --position-id pos-techcorp-senior-platform-engineer \
  --title "Reduced deployment time by 80%"

# Or create both together
resume new work-unit \
  --position "StartupXYZ|Lead Engineer|2023-01|" \
  --title "Led cloud migration saving \$2M annually"

Using JSON Output for Scripting

# Get work units as JSON
resume --json list | jq '.data[] | .id'

# Validate and check for errors
resume --json validate
if [ $? -ne 0 ]; then echo "Validation failed"; fi

# Plan and extract selected work units
resume --json plan --jd job.txt | jq '.selected_work_units[].id'

Adding Certifications and Education

# Certification with expiration
resume new certification "CISSP|ISC2|2023-06|2026-06"

# Education
resume new education "BS Computer Science|UT Austin|2012|Magna Cum Laude"

Configuration

Project Configuration (.resume.yaml)

# Profile (resume header)
profile:
  name: "Your Name"
  email: "[e-mail]"
  phone: "[phone]"
  location: "Austin, TX"
  linkedin: https://linkedin.com/in/yourprofile
  github: https://github.com/yourhandle
  title: "Senior Software Engineer"

# Output settings
output_dir: ./dist
default_format: both  # pdf, docx, or both
default_template: modern

# Ranking weights (adjust for different JD styles)
scoring_weights:
  bm25_weight: 1.0      # Keyword matching
  semantic_weight: 1.0  # Meaning similarity

# Skills curation
skills:
  max_display: 15
  exclude:
    - "Microsoft Office"
  prioritize:
    - "Kubernetes"
    - "AWS"

# Executive format additions
career_highlights:
  - "Led $500M digital transformation"
  - "Built engineering org from 15 to 150"

certifications:
  - name: "AWS Solutions Architect"
    issuer: "Amazon"
    date: "2023-01"

education:
  - degree: "BS Computer Science"
    institution: "UT Austin"
    year: "2012"

Configuration Hierarchy

Resume as Code loads configuration from multiple sources (highest priority first):

1. CLI flags — --output-dir ./custom
2. Environment variables — RESUME_OUTPUT_DIR
3. Project config — .resume.yaml in project root
4. User config — ~/.config/resume-as-code/config.yaml
5. Defaults — Built-in defaults

See Data Model Reference for complete schema documentation.

Documentation

For detailed documentation, see the docs/ folder:

Document	Description
Philosophy	Why "Resume as Code" works — the data-centric approach
Data Model	Work Units, Positions, and entity schemas
Workflow	The Capture → Validate → Plan → Build pipeline
Template Authoring	Creating custom resume templates

Development

Setup

# Clone repository
git clone https://github.com/drbothen/resume-as-code
cd resume-as-code

# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Code quality
uv run ruff check src tests --fix
uv run ruff format src tests
uv run mypy src --strict

Project Structure

src/resume_as_code/
├── commands/     # CLI commands (Click)
├── models/       # Pydantic data models
├── services/     # Business logic
├── providers/    # Output generation (PDF, DOCX)
└── utils/        # Utility functions

Contributing

Development Workflow

1. Fork and clone the repository
2. Create a feature branch from develop: git checkout -b feature/your-feature
3. Make changes with tests
4. Run quality checks: uv run ruff check && uv run mypy src --strict && uv run pytest
5. Submit a PR to develop

Code Quality Requirements

• Type hints on all public functions (mypy --strict must pass)
• Tests for new functionality (pytest with good coverage)
• Linting compliance (ruff check with zero errors)
• Conventional commit messages

Commit Message Format

<type>(<scope>): <description>

feat(cli): add --format flag to build command
fix(ranking): handle empty job descriptions
docs(readme): add configuration examples

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Branch Strategy

• main — Production releases
• develop — Integration branch (PR target)
• feature/* — New features
• fix/* — Bug fixes
• spike/* — Research and exploration
• hotfix/* — Emergency production fixes
• release/* — Release preparation

License

MIT License — see LICENSE