diff --git a/.claude/commands/evaluate-cv.md b/.claude/commands/evaluate-cv.md new file mode 100644 index 0000000..6e14ee7 --- /dev/null +++ b/.claude/commands/evaluate-cv.md @@ -0,0 +1,16 @@ +--- +description: Score a resume against the CV Builder rubric, fully locally +argument-hint: [--jd ] +--- + +Evaluate the resume using the `cv-evaluation` skill. + +Arguments: $ARGUMENTS + +- The first argument is the path to the resume (PDF, markdown, or text). +- An optional `--jd ` adds a job description as keyword context only. + +Read the file(s), run the extract → detect → score → validate-claims pipeline, +validate the result against `EvalResultSchema`, then present the overall score, +the per-dimension breakdown, the top issues with fixes, and any unsupported +claims. Nothing leaves this machine. diff --git a/.claude/commands/setup-profile.md b/.claude/commands/setup-profile.md new file mode 100644 index 0000000..2eca1cd --- /dev/null +++ b/.claude/commands/setup-profile.md @@ -0,0 +1,15 @@ +--- +description: Gather a resume to evaluate, three ways +argument-hint: [path-to-file] +--- + +Help the user get a resume ready for `/evaluate-cv`. Pick the path that fits: + +1. **File** — if `$ARGUMENTS` names a file, read it and confirm what you found. +2. **Paste** — if they pasted resume text, use it directly. +3. **Interview** — if they have nothing prepared, ask a short, focused set of + questions (roles, dates, what they built, measurable outcomes, links) and + assemble a plain-text resume from their answers. + +Once you have the resume text, save it to a file the user chooses and tell them +to run `/evaluate-cv `. Don't invent details they didn't give you. diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..8d1b317 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,17 @@ +{ + "permissions": { + "allow": ["Read", "Glob", "Grep"] + }, + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/welcome.sh\"" + } + ] + } + ] + } +} diff --git a/.claude/skills/cv-evaluation/SKILL.md b/.claude/skills/cv-evaluation/SKILL.md new file mode 100644 index 0000000..b099c96 --- /dev/null +++ b/.claude/skills/cv-evaluation/SKILL.md @@ -0,0 +1,46 @@ +--- +name: cv-evaluation +description: Evaluate a resume against the CV Builder rubric and return a scored, schema-valid EvalResult. Use when the user wants their CV or resume scored, critiqued, or checked for ATS issues and unsupported claims. +--- + +# CV Evaluation + +Run a resume through the same four-step evaluation the hosted product uses, +entirely locally. Everything you need lives in this repo — read the source, don't +guess. + +## Inputs + +- A resume file (PDF, markdown, or plain text). For PDF, read the text content. +- Optionally a job description, used only as keyword context (Phase 1 does not + fit-score against a JD). + +## Pipeline + +1. **Extract.** Apply `packages/prompts/prompts/extract.md` to the raw resume + text to produce a structured `Resume`. +2. **Detect archetype.** Match the resume against the role archetypes in + `packages/intelligence/src/archetypes/`. Pick the best fit; default to + Software Engineer when there's no clear signal. See [archetypes](./archetypes.md). +3. **Score.** Apply `packages/prompts/prompts/score.md` with the detected + archetype's weights and the rubric. See [rubric](./rubric.md) and + [scoring](./scoring.md). Surface **at least 3** issues, each quoting the exact + resume text and giving a concrete fix. +4. **Validate claims.** Apply `packages/prompts/prompts/validate-claims.md` to + flag unsupported claims. See [claim-validation](./claim-validation.md). + +## Output + +Produce one `EvalResult` (schema: `packages/schemas/src/evaluation.ts`). It must +carry `rubricVersion` and `archetypeVersion`. Validate the object against +`EvalResultSchema` before presenting it — never show an unvalidated result. + +Run the validation from inside `packages/schemas` (zod only resolves there under +pnpm's layout). Pipe the JSON to node over stdin rather than writing it to a +file, so nothing derived from the resume touches the working tree. If +dependencies aren't installed, don't error out: check the object field by field +against `evaluation.ts` instead, and tell the user that running `pnpm install` +enables strict validation. + +Then summarize for the user: overall score, the per-dimension breakdown, the top +issues with their fixes, and any unsupported claims. diff --git a/.claude/skills/cv-evaluation/archetypes.md b/.claude/skills/cv-evaluation/archetypes.md new file mode 100644 index 0000000..a5646cd --- /dev/null +++ b/.claude/skills/cv-evaluation/archetypes.md @@ -0,0 +1,10 @@ +# Archetypes + +Each role archetype (keywords, dimension weights, action verbs, anti-patterns) +is one file in `packages/intelligence/src/archetypes/`. Read the relevant file — +the weights there drive the overall score, so use them exactly. + +To detect the archetype: count how many of each archetype's keywords appear in +the resume and pick the highest. The same heuristic is implemented in +`packages/intelligence/src/detect.ts` (`detectArchetype`). When nothing clearly +matches, use Software Engineer. diff --git a/.claude/skills/cv-evaluation/claim-validation.md b/.claude/skills/cv-evaluation/claim-validation.md new file mode 100644 index 0000000..aa83af1 --- /dev/null +++ b/.claude/skills/cv-evaluation/claim-validation.md @@ -0,0 +1,9 @@ +# Claim Validation + +The prompt and the rules for what counts as an unsupported claim are in +`packages/prompts/prompts/validate-claims.md` (rules sourced from +`packages/intelligence/src/validators/claims.ts`). + +Goal: catch what a recruiter would quietly distrust — a metric with no scope, a +tool listed but never used in a bullet, a seniority claim with no team size or +reach. For each flagged claim, say what's missing, not just that it's weak. diff --git a/.claude/skills/cv-evaluation/rubric.md b/.claude/skills/cv-evaluation/rubric.md new file mode 100644 index 0000000..487b690 --- /dev/null +++ b/.claude/skills/cv-evaluation/rubric.md @@ -0,0 +1,8 @@ +# Rubric + +The six dimensions, their 0–5 anchors, and the current `RUBRIC_VERSION` are +defined in `packages/intelligence/src/rubric.ts`. Read that file — it is the +source of truth. Don't reproduce the anchors from memory. + +Score each dimension on its own 0–5 scale, then weight by the archetype (see +[archetypes](./archetypes.md)) to get the overall 0–5 score. diff --git a/.claude/skills/cv-evaluation/scoring.md b/.claude/skills/cv-evaluation/scoring.md new file mode 100644 index 0000000..cca6563 --- /dev/null +++ b/.claude/skills/cv-evaluation/scoring.md @@ -0,0 +1,12 @@ +# Scoring + +The scoring instructions and exact output shape are in +`packages/prompts/prompts/score.md`. Fill its `{{...}}` placeholders from the +detected archetype's weights and the rubric. + +Hold the line on quality: + +- Every issue quotes the exact resume text it's about — no paraphrasing. +- Every issue has a concrete fix, not "consider improving this". +- Overall score = sum(dimension score × weight), on the 0–5 scale. +- Be honest. A weak resume should score low; inflating it doesn't help anyone. diff --git a/.claude/welcome.sh b/.claude/welcome.sh new file mode 100755 index 0000000..75a590d --- /dev/null +++ b/.claude/welcome.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# Emits the CV Builder menu as a SessionStart hook systemMessage, shown to the +# user when they open Claude Code at the repo root. + +# No jq → skip the banner rather than break the session start. +command -v jq >/dev/null 2>&1 || exit 0 + +read -r -d '' MENU <<'EOF' +CV Builder — evaluate your resume locally and privately. Nothing leaves your machine. + + /evaluate-cv [--jd ] Score a resume against the rubric + /setup-profile Assemble a resume if you don't have a file yet + +No build or install needed to evaluate. + +What would you like to do? +EOF + +jq -n --arg msg "$MENU" '{systemMessage: $msg}' diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 12049ed..604bf28 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -1,10 +1,12 @@ -# yaml-language-server: $schema=https://docs.coderabbit.ai/schema.json +# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json language: en-US +early_access: false reviews: profile: chill request_changes_workflow: false high_level_summary: true + poem: false review_status: true auto_review: enabled: true @@ -13,6 +15,38 @@ reviews: - main path_filters: - "!**/pnpm-lock.yaml" + - "!**/dist/**" + - "!**/.turbo/**" + - "!**/node_modules/**" + - "!**/*.snap" + path_instructions: + - path: "packages/core/**" + instructions: > + This is the core CV evaluation/builder logic. Prioritize correctness of + rules, evaluator scoring, and types. Flag changes to public APIs in + src/index.ts and anything in src/types.ts that could break consumers. + New rules/archetypes/evaluator behavior should have matching vitest tests. + - path: "packages/cli/**" + instructions: > + CLI for the CV builder. Watch for unhandled errors, confusing output, + and missing input validation. Behavior changes should be covered by tests. + - path: "packages/web/**" + instructions: > + Web frontend. Check accessibility, error/loading states, and that UI + stays consistent with the core package's data model. + - path: "**/*.md" + instructions: > + Docs for an open-source project. Check clarity and that setup/commands + match the actual scripts in package.json. + tools: + eslint: + enabled: true + markdownlint: + enabled: true chat: auto_reply: true + +knowledge_base: + learnings: + scope: auto diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f684e8b..baf2873 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -3,7 +3,7 @@ name: Bug Report about: Something isn't working correctly title: "[Bug] " labels: bug -assignees: '' +assignees: "" --- ## What happened? diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 812e5c5..34d1975 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -3,7 +3,7 @@ name: Feature Request about: Suggest a new feature or improvement title: "[Feature] " labels: enhancement -assignees: '' +assignees: "" --- ## Problem diff --git a/.github/ISSUE_TEMPLATE/new_archetype.md b/.github/ISSUE_TEMPLATE/new_archetype.md index a94d002..09b9777 100644 --- a/.github/ISSUE_TEMPLATE/new_archetype.md +++ b/.github/ISSUE_TEMPLATE/new_archetype.md @@ -3,7 +3,7 @@ name: New Role Archetype about: Add a new role type (e.g., "Mobile Engineer", "Security Engineer") title: "[Archetype] " labels: archetype, good first issue -assignees: '' +assignees: "" --- ## Role name @@ -26,14 +26,14 @@ List the key terms recruiters look for in this role: How should the 6 dimensions be weighted for this role? -| Dimension | Suggested weight | -|-----------|-----------------| -| Shipped Evidence | ? | -| Quantified Impact | ? | -| Tooling Visibility | ? | -| ATS Compatibility | ? | -| Keyword Match | ? | -| Public Proof | ? | +| Dimension | Suggested weight | +| ------------------ | ---------------- | +| Shipped Evidence | ? | +| Quantified Impact | ? | +| Tooling Visibility | ? | +| ATS Compatibility | ? | +| Keyword Match | ? | +| Public Proof | ? | ## Action verbs (10+) diff --git a/.github/ISSUE_TEMPLATE/new_rule.md b/.github/ISSUE_TEMPLATE/new_rule.md index 9787b31..87850ab 100644 --- a/.github/ISSUE_TEMPLATE/new_rule.md +++ b/.github/ISSUE_TEMPLATE/new_rule.md @@ -3,7 +3,7 @@ name: New Evaluation Rule about: Propose a new CV evaluation rule (anti-pattern or positive pattern) title: "[Rule] " labels: rules, good first issue -assignees: '' +assignees: "" --- ## Rule type diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3b3a5e3..d2c97b3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,7 +4,7 @@ Brief description of the change. ## Related issue -Closes #___ +Closes #\_\_\_ ## Type of change @@ -25,5 +25,5 @@ Closes #___ ## Screenshots (if UI change) -Before | After ---- | --- +| Before | After | +| ------ | ----- | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6b80541..5935c96 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,4 +29,6 @@ jobs: - run: pnpm test + - run: pnpm eval + - run: pnpm build diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..eae9328 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,25 @@ +# CV Builder + +Open source, privacy-first resume evaluator. This repo doubles as a **power-user +pack**: clone it, open Claude Code here, and evaluate your resume locally with +your own agent — nothing leaves your machine. + +## Power-user commands + +- `/evaluate-cv [--jd ]` — score a resume against + the rubric and surface issues + unsupported claims. +- `/setup-profile` — assemble a resume if you don't have a file ready. + +## No build needed for evaluation + +The `cv-evaluation` skill (`.claude/skills/cv-evaluation/`) reads the prompts in +`packages/prompts/prompts/` and the rubric/archetypes in +`packages/intelligence/src/` straight from the repo, and returns an `EvalResult` +validated against `packages/schemas`. `pnpm install` is only needed to run the +package tests or the web app — not for the power-user flow. + +## Repo shape + +pnpm + turbo monorepo. `packages/schemas` (contract) → `packages/intelligence` +(rubric + archetypes) → `packages/prompts` (the prompt pack) → the skill ties +them together. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb93545..1c3f88d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,11 +27,18 @@ line endings, and a few Windows-specific gotchas that commonly block first-time ``` packages/ -├── core/ # Evaluation engine — TypeScript library -├── cli/ # Command-line tool -└── web/ # Browser UI (Next.js) -research/ # Sources and data backing our rules -docs/ # Architecture and guides +├── schemas/ # Zod contract shared across surfaces +├── intelligence/ # Rubric, archetypes, validators +├── prompts/ # extract / score / validate-claims prompt pack +├── core/ # Deterministic evaluation engine +├── cli/ # Command-line tool +└── eval/ # Golden fixtures (pnpm eval) +apps/ +├── cli/ # Power-user pack — quickstart for Claude Code +└── web-ui/ # Browser UI (Next.js) +.claude/ # Claude Code skill + slash commands +research/ # Sources and data backing our rules +docs/ # Architecture and guides ``` ## Development Workflow @@ -117,14 +124,18 @@ This is the easiest way to make a meaningful impact: 1. Open an issue using the "New Role Archetype" template 2. Research 15-30 keywords for the role (check real job postings) -3. Add the archetype to `packages/core/src/archetypes/index.ts` +3. Add a new file in `packages/intelligence/src/archetypes/` and register it in + the `ARCHETYPES` array in `packages/intelligence/src/archetypes/index.ts` 4. Add tests 5. Submit a PR Example archetype structure: ```typescript -ARCHETYPES.set("mobile-engineer", { +// packages/intelligence/src/archetypes/mobile-engineer.ts +import type { Archetype } from "@cv-builder/schemas"; + +export const mobileEngineer: Archetype = { id: "mobile-engineer", name: "Mobile Engineer", description: "iOS/Android engineers building native and cross-platform apps", @@ -139,7 +150,8 @@ ARCHETYPES.set("mobile-engineer", { }, actionVerbs: ["Built", "Shipped", "Optimized", ...], antiPatterns: ["familiar with mobile development", ...], -}); + version: "1.0.0", +}; ``` ## Adding a New Rule @@ -152,6 +164,129 @@ ARCHETYPES.set("mobile-engineer", { --- +## Contributing Without Code + +You don't need to write TypeScript to make a meaningful contribution. Most of +the work that makes this project useful — research, rules, anti-patterns, +sample CVs, translations, docs — comes from people with domain expertise, not +engineering skills. If you've ever reviewed a friend's CV, you've already done +80% of the work for several of these paths. + +### Five ways to contribute without coding + +#### 1. Add a research source + +Every scoring rule and keyword list should trace back to evidence — recruiter +interviews, hiring-manager surveys, market data. We currently cite 250+ +sources in [`research/sources.md`](research/sources.md). The bar to add one is +low and the impact is real. + +**How to do it:** +1. Find a credible source (recruiter post, hiring study, industry report). + Personal blogs and unsubstantiated opinions don't count — published or + institutional sources where possible. +2. Open an issue with the `research` label. Include: + - The source (URL + author + date) + - The specific claim it supports + - Which rule, archetype, or anti-pattern it backs +3. A maintainer will review and merge it into `research/sources.md` (or open a + PR if you'd like to do it yourself). + +**Example:** +> Source: "The 7 Things Recruiters Look For First" — John Smith, 2025. +> Supports: `keywordMatch` rubric dimension. +> Specific claim: "80% of recruiters spend less than 6 seconds on initial scan; +> keyword presence is the dominant factor in pass/fail." + +**Time cost:** 10–20 minutes per source. + +#### 2. Propose an anti-pattern + +Every archetype ships with an `antiPatterns` list — phrases like *"passionate +about products"*, *"leveraged synergies"*, *"team player"*, *"familiar with X"* +that read as filler to recruiters. These come from real CVs and real recruiter +feedback, not from a textbook. If you've spotted one in the wild, add it. + +**How to do it:** +1. Find a phrase in your own CV (or a friend's) that you now realize was filler. +2. Check [`packages/core/src/archetypes/`](packages/core/src/archetypes/) — if + it's not already listed for the relevant archetype, open an issue with the + `rules` label. +3. Include: + - The phrase + - Which archetype it's relevant to (or "all") + - Why it reads as filler (1–2 sentences) + +**Time cost:** 5–10 minutes per anti-pattern. + +#### 3. Provide a sample CV (or job description) + +We don't have public test fixtures. That means contributors writing scoring +rules have nothing to test against, and users have nothing to compare their +own CV to. A small library of sample CVs — deliberately imperfect, with weak +metrics, vague impact, missing quantification — would unlock both contributor +testing and user demos. + +**How to do it:** +1. Author a fictional CV: 1 page, 3–5 years of experience, deliberately + include 2–3 weak spots. Or anonymize your own. +2. Pair it with a fictional job description. +3. Open an issue with the `examples` label and attach both files (or paste + inline). +4. Maintainers will add to `examples/` (we'll create the directory). + +**Time cost:** 30–45 minutes per pair. + +#### 4. Improve the docs + +Docs gaps are everywhere. The `docs/` directory has architecture notes, a +phase-1 plan, and an issues seed — but no contributor onboarding doc, no +"frequently asked questions," no "I just got a bad score, what do I do" +guide, no CLI troubleshooting, no glossary of evaluation terms. Each of +these is a 1-page writeup. + +**How to do it:** +1. Pick a gap from the list above (or one you've personally hit). +2. Write the doc in `docs/`. +3. Open a PR using the branch naming `docs/`. + +**Time cost:** 30–90 minutes per doc. + +#### 5. Triage issues and help others + +The fastest way to become a recognized contributor is to be the person who +answers questions. Right now most issues get one response from a maintainer +— if you can answer even one open issue, you free maintainer time and signal +"I'm here, I know this codebase." + +**How to do it:** +1. Look at issues with the `help wanted` or `good first issue` label. +2. If you can answer a question (even partially), comment. If you can reproduce + a bug, comment with the steps. +3. If you're confident a label is missing or an issue is a duplicate, suggest + it via a comment (maintainers will adjust labels). + +**Time cost:** 5–15 minutes per issue. + +--- + +### How to submit a non-code contribution + +The workflow is the same as code, minus the obvious steps: + +1. **Open an issue first** using the most relevant label (`research`, `rules`, + `examples`, `docs`). Comment "I'll take this" to claim it. +2. **For docs / examples:** fork → branch → PR. Branch-naming + conventions from the [Development Workflow](#development-workflow) section + still apply (`docs/`, `archetype/`, etc.). +3. **For research / anti-patterns / triage:** an issue is enough — no PR + needed unless you want to write the change yourself. + +A maintainer will respond within 48 hours. If you don't hear back, ping the +[Telegram group](https://t.me/techimmigrants). + +--- + ## Guidelines - **One issue = one PR.** Don't bundle unrelated changes. diff --git a/README.md b/README.md index d46e084..913c917 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,12 @@ pnpm --filter @cv-builder/cli start evaluate ./my-cv.md --jd ./job.md pnpm --filter @cv-builder/cli start archetypes ``` +### Power User — run it with Claude Code + +Clone the repo, open [Claude Code](https://claude.com/claude-code) at the root, and run `/evaluate-cv ./your-resume.pdf`. The evaluation runs entirely on your machine with your own agent — no server, no account, nothing leaves your computer. No build needed. + +See [apps/cli/README.md](apps/cli/README.md) for the full guide. + ### Web UI (coming soon) A browser-based interface where you paste your CV and JD, get instant feedback, and export a tailored PDF. No sign-up required, no data leaves your browser. @@ -79,9 +85,16 @@ A browser-based interface where you paste your CV and JD, get instant feedback, ``` packages/ -├── core/ # Evaluation engine (the brain) -├── cli/ # Command-line interface -└── web/ # Browser UI (coming soon) +├── schemas/ # Zod contract shared by every surface +├── intelligence/ # Rubric, archetypes, validators (the brain) +├── prompts/ # extract / score / validate-claims prompt pack +├── core/ # Deterministic evaluation engine +├── cli/ # Command-line interface +└── eval/ # Golden fixtures (pnpm eval) +apps/ +├── cli/ # Power-user quickstart +└── web-ui/ # Browser UI (coming soon) +.claude/ # Claude Code skill + slash commands (power-user surface) ``` See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full technical design. @@ -106,7 +119,7 @@ pnpm test | Your skill | Start here | |------------|-----------| -| TypeScript / Backend | `packages/core/` — scoring algorithms, new archetypes | +| TypeScript / Backend | `packages/intelligence/` — rubric, new archetypes, validators | | React / Frontend | `apps/web-ui/` — build the UI from scratch | | CLI / Node.js | `packages/cli/` — new commands, output formatting | | Research / Writing | `research/` — find sources, validate rules | @@ -132,8 +145,10 @@ Currently built-in: - AI Product Manager - AI Engineer +- Machine Learning Engineer - Backend Engineer - Frontend Engineer +- QA / Test Engineer - DevOps / SRE - Data Engineer @@ -145,7 +160,7 @@ Currently built-in: ### v0.1 (Current Sprint) - [x] Core evaluation engine with 6 dimensions -- [x] 6 role archetypes +- [x] 8 role archetypes - [x] Universal anti-pattern detection - [x] CLI: basic evaluate command - [ ] Unit tests for scoring logic diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..b872096 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,93 @@ +# Roadmap + +This file tracks **what we're actively working on right now** and **what's +open for grabs**. For the **vision** (v0.1, v0.2, v0.3), see the +[README Roadmap section](README.md#roadmap). This file is the **current state** +— what maintainers and contributors are doing this week and next. + +## How to read this + +- 🚧 **In progress** — assigned, being worked on, has an ETA. Don't pick up + unless you coordinate with the assignee. +- 🎯 **Up next** — open for grabs. Comment "I'll take this" on the linked + issue to claim it. Every item here is sized for one PR. +- 🅿️ **Parked** — explicitly deprioritized for now. Pick up only after + discussion with a maintainer. + +**If you're a new contributor, start in 🎯 Up next.** Every item there has +an acceptance bar reachable in a single sitting (1–4 hours). + +--- + +## 🚧 In progress + +| Item | Owner | ETA | Notes | +|---|---|---|---| +| **Merge Phase-1 stack** — PRs [#68](https://github.com/TechImmigrants/cv-builder/pull/68), [#69](https://github.com/TechImmigrants/cv-builder/pull/69), [#70](https://github.com/TechImmigrants/cv-builder/pull/70), [#71](https://github.com/TechImmigrants/cv-builder/pull/71), [#72](https://github.com/TechImmigrants/cv-builder/pull/72), [#73](https://github.com/TechImmigrants/cv-builder/pull/73) | @saharpak | **ASAP** | Open since 2026-06-07. Currently the single biggest contributor-experience blocker — new contributors cloning `main` get a different product than what's documented. **Reviewer help urgently wanted — see below.** | +| CV/JD input screen with file upload — PR [#76](https://github.com/TechImmigrants/cv-builder/pull/76) | unassigned | TBD | Two-column input screen. Depends on Phase-1 merge. | +| CodeRabbit config expansion — PR [#75](https://github.com/TechImmigrants/cv-builder/pull/75) | unassigned | TBD | Per-package review guidance. | +| Rule: flag outdated technologies — PR [#74](https://github.com/TechImmigrants/cv-builder/pull/74) | unassigned | TBD | Resolves issue [#53](https://github.com/TechImmigrants/cv-builder/issues/53). | +| CI: web UI deploy previews on Cloudflare Pages — PR [#78](https://github.com/TechImmigrants/cv-builder/pull/78) | unassigned | TBD | Path-filtered workflow. | + +> ### ⚠️ Reviewer help wanted on Phase-1 PRs +> +> The bottleneck isn't writing code — it's review bandwidth. If you have +> **TypeScript + zod** experience and can review one of #68–#73, comment on +> the PR. A 30-minute review from someone other than the maintainer unblocks +> the entire stack and signals to the rest of the contributor base that the +> project is moving. + +--- + +## 🎯 Up next — open for grabs + +These have linked issues, explicit acceptance criteria, and a one-PR-sized +scope. **Comment "I'll take this" on the issue to claim.** + +| Item | Effort | Issue | Notes | +|---|---|---|---| +| Add integration test for full evaluation pipeline | M (2–4 h) | [#51](https://github.com/TechImmigrants/cv-builder/issues/51) | `help wanted`, `core`. End-to-end test of `evaluate()`. | +| Add GitHub Actions workflow for lint + tests | S (1–2 h) | [#46](https://github.com/TechImmigrants/cv-builder/issues/46) | `help wanted`, `core`. May already partially exist — check `.github/workflows/` first. | +| Convert `types.ts` to Zod schemas | M | [#47](https://github.com/TechImmigrants/cv-builder/issues/47) | `enhancement`, `core`. | +| Add example test CVs for local development | S (30–60 min) | [#50](https://github.com/TechImmigrants/cv-builder/issues/50) | `good first issue`. Author 2–3 fictional CVs + 1 JD. | +| Rule: flag generic summary / objective section | S | [#45](https://github.com/TechImmigrants/cv-builder/issues/45) | `good first issue`, `rules`. | +| Rule: detect missing action verbs in bullet points | S | [#52](https://github.com/TechImmigrants/cv-builder/issues/52) | `good first issue`, `rules`. | +| Rule: flag outdated technologies | S | [#53](https://github.com/TechImmigrants/cv-builder/issues/53) | `good first issue`, `rules`. **PR #74 already in flight — check before starting.** | +| Add per-dimension feedback strings to evaluator | S | [#48](https://github.com/TechImmigrants/cv-builder/issues/48) | `enhancement`, `core`. | +| Fix: flag missing contact information | S | [#55](https://github.com/TechImmigrants/cv-builder/pull/55) | `core`. PR already open — needs review. | +| New archetype: **AI Engineer** | M | (open issue) | Use the [New Archetype template](.github/ISSUE_TEMPLATE/new_archetype.md). Top priority for the 2026 market. | +| New archetype: **AI Product Manager** | M | (open issue) | Top priority for the 2026 market. | +| New archetypes: Backend / Frontend / DevOps | M each | (open issue) | Currently advertised in README but unimplemented. | +| Land CONTRIBUTING.md "no-code" section | S | (open issue) | The draft this file came from. | +| Write `docs/faq.md` ("I got a bad score, what now?") | S | (open issue) | | +| Write `docs/cli-troubleshooting.md` | S | (open issue) | | +| Write `docs/evaluation-glossary.md` | S | (open issue) | | + +--- + +## 🅿️ Parked + +| Item | Why parked | When to revisit | +|---|---|---| +| PDF export | Real effort; needs design decisions (template engine, fonts, ATS-safe output). | After Phase-1 merge + web UI MVP. | +| VS Code / Cursor extension | Significant scope; needs stable core API first. | After PDF export and at least 8 archetypes shipped. | +| Self-hosted deployment guide | Requires production stability first. | After v0.2 lands. | +| LLM-enhanced mode (rewrite suggestions) | Cost implications and prompt-design work. | After core scoring is stable. | +| Side-by-side tailoring editor | Needs mature web UI. | After web UI MVP ships. | +| Localization (multiple languages) — beyond README | Translation tooling, RTL support, glossary. | After first 3 README translations land. | +| Before/after examples library | Needs curation and editorial review. | After core scoring is stable. | + +--- + +## How to influence this roadmap + +- **Pick up an item from 🎯 Up next** — comment "I'll take this" on the issue. +- **Suggest new items** — open an issue with the relevant label. +- **Push a 🅿️ Parked item** — if you think something should be un-parked, + open an issue with the `roadmap` label and the rationale. +- **Help review Phase-1 PRs** — the single highest-leverage thing a + TypeScript-comfortable contributor can do this week. + +--- + +*Last updated: 2026-06-22* diff --git a/apps/cli/README.md b/apps/cli/README.md new file mode 100644 index 0000000..2ab0fc7 --- /dev/null +++ b/apps/cli/README.md @@ -0,0 +1,60 @@ +# Power User — evaluate your resume locally + +Run the full CV evaluation on your own machine with your own +[Claude Code](https://claude.com/claude-code). Your resume never leaves your +computer — no server, no account, no API keys in this repo. + +## Quickstart + +```bash +git clone https://github.com/TechImmigrants/cv-builder.git +cd cv-builder +claude # open Claude Code at the repo root +``` + +No build or install is needed to evaluate — the skill reads the prompts and +rubric straight from the repo. (`pnpm install` is only for running the package +tests or the web app.) + +Then, inside Claude Code: + +```text +/evaluate-cv ./my-resume.pdf +``` + +Optionally add a job description as keyword context: + +```text +/evaluate-cv ./my-resume.pdf --jd ./job.md +``` + +No resume handy? Run `/setup-profile` and it'll help you assemble one. + +## What you get + +An honest, role-adaptive score (0–5) with: + +- a per-dimension breakdown across the six rubric dimensions, +- at least three specific issues, each quoting the exact line and giving a fix, +- any unsupported claims a recruiter would distrust, +- an ATS-compatibility read. + +## How it works + +The `/evaluate-cv` command drives the **cv-evaluation** skill +(`.claude/skills/cv-evaluation/`), which runs four steps against this repo: + +| Step | Source | +|---|---| +| Extract structured resume | `packages/prompts/prompts/extract.md` | +| Detect role archetype | `packages/intelligence/src/archetypes/` | +| Score against the rubric | `packages/prompts/prompts/score.md` + `packages/intelligence/src/rubric.ts` | +| Flag unsupported claims | `packages/prompts/prompts/validate-claims.md` | + +The result is validated against `EvalResultSchema` +(`packages/schemas`) before you see it. + +## Privacy + +Everything runs through your local Claude Code. This pack makes no network calls +of its own and stores nothing. diff --git a/apps/cli/package.json b/apps/cli/package.json new file mode 100644 index 0000000..4ee4ad1 --- /dev/null +++ b/apps/cli/package.json @@ -0,0 +1,6 @@ +{ + "name": "@cv-builder/power-user", + "version": "0.1.0", + "description": "Power-user pack: evaluate your resume locally with your own Claude Code", + "private": true +} diff --git a/apps/web-ui/AGENTS.md b/apps/web-ui/AGENTS.md index 8bd0e39..c153a9b 100644 --- a/apps/web-ui/AGENTS.md +++ b/apps/web-ui/AGENTS.md @@ -1,5 +1,7 @@ + # This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. + diff --git a/apps/web-ui/README.md b/apps/web-ui/README.md index f35ce8c..4cd6eeb 100644 --- a/apps/web-ui/README.md +++ b/apps/web-ui/README.md @@ -17,12 +17,12 @@ Then open [http://localhost:3000](http://localhost:3000). ## Scripts -| Command | Purpose | -| --- |----------------------------| -| `pnpm dev` | Start the local dev server | +| Command | Purpose | +| ------------ | -------------------------- | +| `pnpm dev` | Start the local dev server | | `pnpm build` | Build the production app | | `pnpm start` | Run the production build | -| `pnpm lint` | Run lint checks | +| `pnpm lint` | Run lint checks | ## Main files diff --git a/apps/web-ui/public/file.svg b/apps/web-ui/public/file.svg deleted file mode 100644 index 004145c..0000000 --- a/apps/web-ui/public/file.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/apps/web-ui/src/app/components/EvaluateForm.tsx b/apps/web-ui/src/app/components/EvaluateForm.tsx new file mode 100644 index 0000000..92fd453 --- /dev/null +++ b/apps/web-ui/src/app/components/EvaluateForm.tsx @@ -0,0 +1,97 @@ +"use client"; + +import { evaluate } from "@cv-builder/core"; +import { useRouter } from "next/navigation"; +import { useState } from "react"; +import { saveEvaluationResult } from "../lib/evaluation-storage"; +import { FileUpload } from "./FileUpload"; +import { TextStats } from "./TextStats"; + +export function EvaluateForm() { + const router = useRouter(); + + const [cv, setCv] = useState(""); + const [jd, setJd] = useState(""); + const [loading, setLoading] = useState(false); + + async function handleEvaluate() { + if (!cv.trim()) { + alert("Please paste your CV."); + return; + } + + setLoading(true); + + try { + const result = await evaluate({ + cv: { + content: cv, + format: "plaintext", + }, + jd: { + content: jd, + }, + }); + + saveEvaluationResult(result); + + router.push("/results"); + } catch (error) { + console.error(error); + alert("Evaluation failed."); + } finally { + setLoading(false); + } + } + + return ( +
+
+
+ + +