arossia94/career-ops

1. Overall shape

Career-Ops is a local-first job search operating system, not a hosted app. The machine running the repo is the control plane: it reads your CV/profile, talks to an AI model or CLI, automates browser work against job portals, and writes results back to local files.

2. Primary user interface: slash-command modes

The core behavior is encoded in modes/*.md. These are the repo’s “commands” for tasks like evaluation, PDF generation, scanning, batch processing, tracker management, deep research, interview prep, and follow-up. They are designed to be reused across Claude Code, Gemini CLI, and other supported coding CLIs via the shared agent instructions in AGENTS.md, CLAUDE.md, and the provider-specific skill folders.

3. Main orchestration flow

The standard pipeline is: input a job URL or description → classify the role/archetype → evaluate fit against cv.md and profile data → generate a report/PDF → update the tracker. This is the central data flow the architecture is built around, and most tools in the repo either feed this pipeline or consume its outputs.

4. Evaluation and reasoning layer

The evaluation subsystem produces structured job analyses: role summary, CV match, level strategy, comp research, personalization, and interview prep. It appears to rely on prompt templates plus local source files such as the CV, profile config, proof points, and shared mode text. The important boundary here is that the AI is recommended/assistive; the repo does not auto-submit applications.

5. Portal scanning and browser automation

The scanning subsystem uses Playwright and portal-specific configuration to discover roles from company pages and supported job boards such as Greenhouse, Ashby, Lever, Wellfound, Workable, and RemoteFront. Portal definitions live in templates/portals.example.yml and likely become a user-local portals.yml. This is the repo’s web-automation boundary: it reaches out to external sites, but keeps the results local.

6. Artifact generation

Outputs are generated into separate local folders: reports/ for markdown evaluations, output/ for PDFs, and data/ for tracking state. PDF generation is template-driven via templates/cv-template.html and templates/cv-template.tex, with embedded fonts in fonts/. The architecture treats report generation and PDF rendering as distinct steps, so the same evaluation can feed multiple output formats.

7. Single source of truth for tracking

The tracking layer stores application/candidate pipeline state locally using markdown/YAML/TSV-style data and canonical status definitions in templates/states.yml. Utility scripts such as merge-tracker.mjs, dedup-tracker.mjs, normalize-statuses.mjs, and verify-pipeline.mjs indicate that data integrity is a first-class concern: deduplication, normalization, merge safety, and health checks are part of the system design.

8. Batch and parallel processing

batch/ is a separate execution path for high-throughput evaluation. It uses a self-contained worker prompt and a shell runner, implying fan-out to multiple AI workers/sub-agents for parallel processing of many listings. This is a throughput-oriented subsystem distinct from the interactive single-offer flow.

9. Terminal dashboard subsystem

The dashboard/ directory is a standalone Go application built with Bubble Tea and Lipgloss. It reads the same local job/pipeline data and presents it as a TUI for browsing, filtering, sorting, previewing, and changing status. Architecturally, it is a read-heavy UI over the local tracker, not a separate backend.

10. Customization and user-owned inputs

The repo is intentionally user-customized through local files like cv.md, config/profile.yml, portals.yml, and optional reference material in examples/, jds/, writing-samples/, and interview-prep/. That means the system’s behavior is heavily shaped by user-owned content rather than hardcoded application data.

11. Localization and role-specific modes

There are localized mode sets under modes/de/ and several specialized command families such as apply, contact outreach, deep research, training, project review, and resume/PDF generation. This suggests the architecture is modular by job-search task, with language variants and role variants layered on the same shared workflow.

12. Automation, validation, and maintenance scripts

The root-level .mjs scripts and helpers like doctor.mjs, check-liveness.mjs, cv-sync-check.mjs, scan.mjs, and generate-pdf.mjs form the maintenance and automation layer. These keep the local system healthy, ensure the CV/tracker stay aligned, and support repeatable execution outside the interactive CLI experience.

13. External dependencies and boundaries

The main external boundaries are: AI providers/CLIs, browser automation against job portals, and job-board/company sites. The repo also depends on local tooling ecosystems: Node.js for orchestration/scripts, Go for the dashboard, Playwright for web interaction and PDF-related rendering, and GitHub Actions for CI/release checks.

14. CI and repository governance

The GitHub workflows, issue templates, release automation, dependency review, SBOM, and security tooling suggest the repo is maintained like a productized open-source tool. That infrastructure supports code quality and releases, but the runtime architecture remains local and user-operated rather than server-hosted.