JobForge

AI-powered job search pipeline built on opencode. Evaluate offers, generate tailored CVs, scan portals, negotiate offers, and track everything -- powered by AI agents.

Quick Start

npx --package=job-forge create-job-forge my-job-search
cd my-job-search
npm install
opencode

The scaffolded opencode.json already has three MCPs wired up — they launch automatically the first time opencode starts:

• Geometra — browser automation + PDF generation
• Gmail — reads replies from recruiters
• state-trace — typed working memory for cross-session context (resumed batches, recent decisions, repeated portal quirks). Install once with python3 -m pip install "state-trace[mcp]"; the MCP command is state-trace-mcp.

JobForge also keeps MCP-free local workflow state and policy: templates/canon.json defines URL/company/role identity keys via @razroo/iso-canon, templates/contracts.json defines tracker/apply artifact shapes via @razroo/iso-contract, templates/score.json defines weighted scoring and gates via @razroo/iso-score, templates/timeline.json defines follow-up and next-action windows via @razroo/iso-timeline, templates/prioritize.json defines next-action ranking via @razroo/iso-prioritize, templates/capabilities.json defines role capability boundaries via @razroo/iso-capabilities, templates/context.json defines deterministic mode/reference bundles via @razroo/iso-context, templates/preflight.json defines safe dispatch rounds/gates via @razroo/iso-preflight, templates/postflight.json defines safe dispatch settlement via @razroo/iso-postflight, templates/redact.json defines safe-export redaction rules via @razroo/iso-redact, templates/migrations.json defines safe consumer-project upgrades via @razroo/iso-migrate, templates/facts.json defines source-backed fact extraction via @razroo/iso-facts, .jobforge-ledger/events.jsonl records duplicate/status events via @razroo/iso-ledger, .jobforge-cache/ stores reusable JD/artifact content via @razroo/iso-cache, .jobforge-index.json indexes artifact source pointers via @razroo/iso-index, .jobforge-facts.json materializes queryable facts with provenance, .jobforge-timeline.json materializes due/overdue follow-up actions, .jobforge-prioritize.json materializes the ranked local priority queue, and .jobforge-lineage.json records stale-output checks for generated artifacts via @razroo/iso-lineage. None of these add always-on prompt or tool-schema tokens.

npm install also materializes symlinks for every supported agent harness — OpenCode, Cursor, Claude Code, and Codex — so you can run opencode, cursor, claude, or codex in the same project and each picks up the shared MCP config and instructions.

Then fill in cv.md, config/profile.yml, and portals.yml with your personal data, paste a job URL into opencode, and JobForge evaluates + tracks it.

Upgrade later: npm run update-harness (pulls latest job-forge from npm, re-syncs symlinks, applies safe consumer migrations, prints the resolved version)

Full setup guide and alternative install paths (including contributing to the harness itself): docs/SETUP.md.

What Is This

JobForge turns opencode into a full job search command center. Instead of manually tracking applications in a spreadsheet, you get an AI-powered pipeline that:

• Evaluates offers with a unified 10-dimension weighted scoring system
• Generates tailored PDFs -- ATS-optimized CVs with anti-AI-detection writing rules
• Scans portals with fuzzy dedup (catches reposts with new URLs)
• Processes in batch -- evaluate 10+ offers in parallel with sub-agents
• Tracks everything with pipeline integrity checks and canonical state management
• Manages follow-ups -- timing-based nudges so you never miss a window
• Learns from rejections -- pattern analysis across all rejections by stage, archetype, and score
• Negotiates offers -- structured comp breakdown, leverage assessment, counter-offer strategy

Important: This is NOT a spray-and-pray tool. The whole point is to apply only where there's a real match. The scoring system helps you focus on high-fit opportunities instead of wasting everyone's time. Always review before submitting.

Features

| Feature | Description | |---------|-------------| | Auto-Pipeline | Paste a URL, get a full evaluation + PDF + tracker entry | | Unified Scoring | 10 weighted dimensions, consistent across all modes, with calibration anchors and deterministic job-forge score:* checks | | Anti-AI-Detection CVs | Writing rules that avoid ATS filters on Indeed, LinkedIn, Workday | | 6-Block Evaluation | Role summary, CV match, level strategy, comp research, personalization, interview prep (STAR+R) | | Interview Story Bank | Curated bank of 10-12 stories with match counts, archetype tags, and automatic pruning | | Follow-Up System | job-forge timeline:* computes timing-based nudges from local tracker/pipeline sources: Applied 7+ days ago, Contacted 5+ days ago, Interview 1-day thank-you, and 7-day interview nudge. | | Gmail Integration | MCP server configured to retrieve emails for interview callbacks, offer responses, and application status updates | | Rejection Analysis | Captures stage + reason, surfaces patterns (archetype gaps, scoring miscalibration) | | Offer Negotiation | Total comp breakdown, equity valuation, leverage from pipeline, counter-offer scripts | | Deep Research | Company research that feeds back into scores and interview prep | | Smart LinkedIn Outreach | Reads evaluation reports to craft targeted messages using top proof points | | Portal Scanner | 45+ companies pre-configured with fuzzy dedup for reposts | | Batch Processing | Parallel evaluation with opencode run workers, with honest verification flagging | | Durable Batch Orchestration | batch-runner.sh uses @razroo/iso-orchestrator for resumable bundle execution, bounded fan-out, mutexed state writes, and workflow records in .jobforge-runs/. | | Pipeline Integrity | Automated merge, dedup, status normalization, health checks | | Cost-Aware Agent Routing | Three subagents (@general-free, @general-paid, @glm-minimal) with per-task tool surfaces. On OpenCode, JobForge pins all tiers to opencode-go/deepseek-v4-flash so application runs avoid overloaded free-model pools. See Subagent Routing in AGENTS.md for the task-to-agent mapping. | | Trace + Telemetry + Guard + Contract + Score + Canon + Ledger + Capabilities + Context + Cache + Index + Facts + Timeline + Prioritize + Lineage + Preflight + Postflight + Redact + Migrate | job-forge trace:* exposes local OpenCode transcripts, job-forge telemetry:* summarizes runs, job-forge guard:* audits deterministic policy rules, templates/contracts.json enforces artifact shape with iso-contract, job-forge score:* computes/checks weighted offer scores, job-forge canon:* derives stable URL/company/role identity keys, job-forge ledger:* queries append-only workflow state, job-forge capabilities:* checks role boundaries, job-forge context:* plans mode/reference context bundles, job-forge cache:* reuses fetched JD/artifact content, job-forge index:* queries compact source pointers, job-forge facts:* materializes source-backed job/application/candidate facts, job-forge timeline:* computes due/overdue follow-up actions, job-forge prioritize:* ranks local apply/follow-up candidates, job-forge lineage:* detects stale reports/PDFs after source changes, job-forge preflight:* plans bounded apply dispatch rounds from file-backed candidate facts, job-forge postflight:* settles dispatch outcomes/artifacts/post-steps, job-forge redact:* sanitizes local exports, and job-forge migrate:* applies safe consumer-project upgrades without MCP/tool-schema overhead. | | Token Cost Visibility | job-forge tokens --days 1 for per-session breakdown; job-forge session-report --since-minutes 60 --log to flag sessions over budget and append history to data/token-usage.tsv. Auto-logged after every batch run. |

Usage

/job-forge                → Show all available commands
/job-forge {paste a JD}   → Full auto-pipeline (evaluate + PDF + tracker)
/job-forge scan           → Scan portals for new offers
/job-forge pdf            → Generate ATS-optimized CV
/job-forge batch          → Batch evaluate multiple offers
/job-forge tracker        → View application status
/job-forge apply          → Fill application forms with AI
/job-forge pipeline       → Process pending URLs
/job-forge contact        → LinkedIn outreach (uses evaluation report)
/job-forge deep           → Deep company research (feeds back into scores)
/job-forge followup       → Check what needs follow-up action
/job-forge rejection      → Record/analyze rejection patterns
/job-forge negotiation    → Structured offer negotiation
/job-forge training       → Evaluate a course/cert
/job-forge project        → Evaluate a portfolio project

Or just paste a job URL or description directly -- JobForge auto-detects it and runs the full pipeline.

The system is designed to be customized by opencode itself. Modes, archetypes, scoring weights, negotiation scripts -- just ask opencode to change them: "Change the archetypes to backend engineering roles", "Add these 5 companies to portals.yml", "Update my profile with this CV I'm pasting".

How It Works

You paste a job URL or description
        │
        ▼
┌──────────────────┐
│  Archetype       │  Classifies: LLMOps / Agentic / PM / SA / FDE / Transformation
│  Detection       │
└────────┬─────────┘
         │
┌────────▼─────────┐
│  A-F Evaluation   │  Match, gaps, comp research, STAR stories
│  (reads cv.md)    │  Unified 10-dimension scoring model + iso-score checks
└────────┬─────────┘
         │
    ┌────┼────┐
    ▼    ▼    ▼
 Report  PDF  Tracker
  .md   .pdf   .tsv
         │
    ┌────┼────┐
    ▼    ▼    ▼
 Apply  Follow  Negotiate
        up      (if offer)

Project Structure

Your personal project (after npx --package=job-forge create-job-forge my-search):

my-search/
├── package.json                  # depends on "job-forge": "^2.0.0" (npm registry)
├── opencode.json                 # thin config — enables MCPs + states.yml
├── cv.md                         # your CV (personal)
├── article-digest.md             # your proof points (optional, personal)
├── portals.yml                   # companies to scan (personal)
├── config/profile.yml            # your identity, target roles (personal)
├── data/                         # applications, pipeline, scan history (personal, gitignored)
├── .jobforge-ledger/              # append-only local workflow events (personal, gitignored)
├── .jobforge-cache/               # content-addressed local JD/artifact cache (personal, gitignored)
├── .jobforge-index.json           # deterministic artifact lookup index (generated, gitignored)
├── .jobforge-facts.json           # deterministic fact set with provenance (generated, gitignored)
├── .jobforge-timeline.json        # deterministic follow-up action plan (generated, gitignored)
├── .jobforge-prioritize.json      # deterministic next-action ranking (generated, gitignored)
├── .jobforge-lineage.json         # report/PDF lineage and stale-output checks (generated, gitignored)
├── .jobforge-redacted/            # sanitized local exports (generated, gitignored)
├── reports/                      # generated evaluation reports (personal, gitignored)
├── batch/{batch-input,batch-state}.tsv, tracker-additions/, logs/   # personal
├── .jobforge-runs/                # durable batch workflow records (generated)
├── AGENTS.md                     # personal overrides (opencode + codex)
├── CLAUDE.md                     # personal overrides (Claude Code), @-imports CLAUDE.harness.md
│
│ # ↓ symlinks into node_modules/job-forge/, regenerated by postinstall sync.mjs
├── AGENTS.harness.md             # → harness instructions (loaded via opencode.json)
├── CLAUDE.harness.md             # → harness instructions (imported from personal CLAUDE.md)
├── .mcp.json                     # → Claude Code MCP config
├── .codex/config.toml            # → Codex MCP config
├── .cursor/mcp.json              # → Cursor MCP config
├── .cursor/rules/main.mdc        # → Cursor always-apply rule
├── .opencode/skills/job-forge.md # → skill router
├── .opencode/agents/             # → @general-free, @general-paid, @glm-minimal
├── modes/                        # → _shared.md + skill modes
├── templates/                    # → states.yml, portals.example.yml, cv-template.html, canon.json, score.json, timeline.json, prioritize.json, capabilities.json, context.json, index.json, facts.json, preflight.json, postflight.json, redact.json, migrations.json
├── batch/batch-prompt.md         # → batch worker prompt
├── batch/batch-runner.sh         # → parallel orchestrator
│
└── node_modules/job-forge/       # the harness (from npm: `[email protected]`)

Symlinks are regenerated on every npm install via the package's postinstall hook. You never have to know about harness internals — just edit cv.md, portals.yml, and config/profile.yml.

The harness itself (this repo, what gets published as job-forge on npm):

JobForge/
├── iso/                          # ← SOURCE OF TRUTH for harness configuration
│   ├── instructions.md           # → AGENTS.md + CLAUDE.md (Claude Code / Codex / Cursor)
│   ├── mcp.json                  # → .mcp.json + .cursor/mcp.json + .codex/config.toml + opencode.json
│   ├── agents/*.md               # → .opencode/agents/*.md (general-free, general-paid, glm-minimal)
│   ├── commands/job-forge.md     # → .opencode/skills/job-forge.md
│   └── config.json               # per-harness top-level extras (e.g. opencode `instructions` array)
│
├── package.json                  # bin: job-forge, create-job-forge; prepack runs iso-harness
├── bin/
│   ├── job-forge.mjs             # CLI dispatcher (merge/verify/pdf/tokens/sync/...)
│   ├── sync.mjs                  # postinstall: creates symlinks in consumer project
│   └── create-job-forge.mjs      # scaffolder
├── modes/                        # _shared.md + 16 skill modes
├── templates/                    # cv-template.html, portals.example.yml, states.yml, canon.json, score.json, timeline.json, prioritize.json, capabilities.json, context.json, facts.json, preflight.json, postflight.json, redact.json, migrations.json
├── config/profile.example.yml    # template for consumer's profile.yml
├── batch/{batch-prompt.md,batch-runner.sh}   # batch orchestrator
├── scripts/
│   ├── batch-orchestrator.mjs    # iso-orchestrator-backed batch control loop
│   ├── tracker-line.mjs          # iso-contract-backed tracker TSV renderer
│   ├── ledger.mjs                # iso-ledger-backed workflow-state CLI
│   ├── capabilities.mjs          # iso-capabilities-backed role policy CLI
│   ├── context.mjs               # iso-context-backed context bundle CLI
│   ├── cache.mjs                 # iso-cache-backed local artifact cache CLI
│   ├── index.mjs                 # iso-index-backed artifact lookup CLI
│   ├── facts.mjs                 # iso-facts-backed local fact materialization
│   ├── timeline.mjs              # iso-timeline-backed follow-up planning CLI
│   ├── prioritize.mjs            # iso-prioritize-backed next-action ranking
│   ├── lineage.mjs               # iso-lineage-backed stale artifact checks
│   ├── score.mjs                 # iso-score-backed offer scoring CLI
│   ├── canon.mjs                 # iso-canon-backed identity normalization CLI
│   ├── preflight.mjs             # iso-preflight-backed dispatch planning CLI
│   ├── postflight.mjs            # iso-postflight-backed dispatch settlement CLI
│   ├── redact.mjs                # iso-redact-backed safe-export redaction CLI
│   ├── migrate.mjs               # iso-migrate-backed consumer-project migrations
│   ├── token-usage-report.mjs    # opencode cost analyzer
│   └── release/check-source.mjs  # version gate for npm publish
├── tracker-lib.mjs / merge-tracker.mjs / dedup-tracker.mjs / verify-pipeline.mjs
├── normalize-statuses.mjs / generate-pdf.mjs / cv-sync-check.mjs
├── dashboard/                    # optional Go TUI
├── fonts/                        # Space Grotesk + DM Sans (for PDF)
├── docs/                         # architecture, setup, customization
└── .github/workflows/            # quality.yml + release.yml (CI publish to npm)

All per-harness config trees (.opencode/, .cursor/, .claude/, .codex/, CLAUDE.md, AGENTS.md, .mcp.json, opencode.json) are generated from iso/ by @razroo/iso-harness and gitignored in this repo. npm run build:config regenerates them locally; prepack regenerates them into the tarball at publish time so consumers get everything pre-baked.

Documentation

Index and cross-links: docs/README.md.

• Setup — both install paths, profile, CV, portals, verify, token tracking, troubleshooting
• Architecture — package architecture, modes, evaluation flow, batch runner, pipeline scripts
• Customization — archetypes, scanner keywords, CV template, states, customizing symlinked modes
• Model Routing — the three cost-tiered subagents, why the architecture exists, and how to swap models or add your own
• Contributing — branch workflow, quality gate, and ideas for PRs

License

MIT