docs: add power-user quickstart and update structure#73
Open
amirbahador-hub wants to merge 26 commits into
Open
docs: add power-user quickstart and update structure#73amirbahador-hub wants to merge 26 commits into
amirbahador-hub wants to merge 26 commits into
Conversation
Shared, validated contract for CV Builder surfaces: Resume, JobDescription, Archetype, Issue, Claim, and EvalResult (with required rubric/archetype versions). Closes #47
Scoring brain the prompts reference: rubric v1 (six weighted dimensions with 0-5 anchors), three role archetypes (Software Engineer, Product Manager, Data & ML Engineer), keyword-based detectArchetype, and the ATS and claim validator specs. Closes #63
The three Phase 1 prompts a power user's agent runs. Markdown templates are the source of truth; renderers inject the live rubric, archetype weights, and claim rules so each assembled prompt is self-contained and stays in sync with the intelligence package. Every prompt asks for JSON matching its schema. Closes #64
Clone the repo, open Claude Code, run /evaluate-cv: the cv-evaluation skill runs extract -> detect -> score -> validate-claims locally, reading the prompts and rubric straight from the repo (no build). A SessionStart hook greets the user with the available commands on open. Skill subfiles point at the package sources to avoid drift. Closes #65
Five fixtures across the three archetypes (including an ATS-hostile resume) guard the deterministic layer: for each, the detected archetype and ATS read must match expectations and the resume must parse against the schema. No LLM involved. Wired as a pnpm eval task and a CI step. Closes #66
README gets a 'Power User — run it with Claude Code' section (clone, open Claude Code, /evaluate-cv) linking apps/cli/README.md, and the architecture tree plus the CONTRIBUTING structure now list schemas, intelligence, prompts, eval, and apps/cli. Closes #67
Collaborator
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds Phase 1 CV evaluation: Zod schemas, intelligence (rubric, archetypes, detection, ATS/claim validators), prompt templates and renderers, golden-fixture eval harness, and Claude Code command/skill docs and session hook for local resume scoring. ChangesCore CV Evaluation System
Golden Fixture Testing
Claude Code Power-User Surface
Sequence Diagram(s)sequenceDiagram
participant ClaudeCode
participant WelcomeScript
participant EvaluateCvCommand
participant CvEvaluationSkill
participant EvalResultSchema
ClaudeCode->>WelcomeScript: SessionStart hook
WelcomeScript-->>ClaudeCode: systemMessage menu
ClaudeCode->>EvaluateCvCommand: /evaluate-cv <resume> [--jd]
EvaluateCvCommand->>CvEvaluationSkill: extract -> detect -> score -> validate-claims
CvEvaluationSkill->>EvalResultSchema: validate EvalResult
EvalResultSchema-->>ClaudeCode: score breakdown, issues, claims
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (3)
packages/prompts/src/index.ts (1)
37-43: ⚡ Quick winRender weights in rubric order.
Object.entries(archetype.evaluationWeights)makes the prompt depend on insertion order, so a reordered archetype object can silently change the scoring text. Build the list fromRUBRIC.dimensionsand look up each weight by key to keep the prompt stable.♻️ Proposed fix
- const weights = Object.entries(archetype.evaluationWeights) - .map(([key, value]) => `- ${key}: ${value}`) + const weights = RUBRIC.dimensions + .map((dimension) => `- ${dimension.key}: ${archetype.evaluationWeights[dimension.key]}`) .join("\n");🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/prompts/src/index.ts` around lines 37 - 43, The weights list currently iterates Object.entries(archetype.evaluationWeights) which depends on insertion order; instead build weights from RUBRIC.dimensions to preserve rubric order: map over RUBRIC.dimensions (the same array used to build rubric) and for each dimension (e.g., in the map callback for RUBRIC.dimensions) lookup the corresponding weight from archetype.evaluationWeights using the dimension's key/name (e.g., d.name or d.key) and format `- ${d.name}: ${weight}`; also handle missing weights with a sensible default or explicit indicator so the prompt remains stable (references: archetype.evaluationWeights, RUBRIC.dimensions, weights variable).packages/intelligence/src/archetypes/index.ts (1)
20-22: ⚡ Quick winReturn a copy from
listArchetypes().
ARCHETYPESis the live backing array, so any downstreampush/splicecan silently change detection results. Returning a shallow copy keeps the helper stable; if you want full immutability, considerReadonlyArray/Object.freezefor the registry too.♻️ Suggested change
export function listArchetypes(): Archetype[] { - return ARCHETYPES; + return [...ARCHETYPES]; }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/intelligence/src/archetypes/index.ts` around lines 20 - 22, listArchetypes currently returns the live ARCHETYPES array which allows callers to mutate the registry; change listArchetypes to return a shallow copy of ARCHETYPES (e.g., using a copy operation) so callers cannot push/splice the original; optionally consider converting ARCHETYPES to a ReadonlyArray or applying Object.freeze for stronger immutability guarantees later..claude/skills/cv-evaluation/SKILL.md (1)
25-30: ⚡ Quick winDon't hard-require three findings.
A fixed minimum can push the agent to invent filler issues on stronger resumes just to satisfy the quota. Make this "up to 3" and only return findings that are directly supported by quoted text.
♻️ Suggested change
- Surface **at least 3** issues, each quoting the exact - resume text and giving a concrete fix. + Surface the most material issues (up to 3). Only include findings that are + directly supported by quoted text, and return fewer than 3 if that's all the + resume justifies.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/cv-evaluation/SKILL.md around lines 25 - 30, The step requiring "Surface **at least 3** issues" is too rigid and should be relaxed; update the SKILL.md step 3 wording to "Surface up to 3 issues" and add an explicit instruction to only return findings that are directly supported by quoted resume text (no filler), keeping the rest of the references to `packages/prompts/prompts/score.md`, `rubric.md`, and `scoring.md` unchanged; ensure the phrasing ties this behaviour to the scoring prompt (score.md) so the agent enforces the "up to 3" and "only supported findings" constraint when generating outputs.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/settings.json:
- Around line 2-4: permissions.allow currently lacks file-write capability which
breaks the new /setup-profile resume-save flow; update the settings object
(permissions.allow) to include the appropriate write permission (e.g., "Write"
or "FileWrite" depending on your runtime's permission token) so the agent can
create/save the resume file when the /setup-profile flow runs.
In `@CONTRIBUTING.md`:
- Around line 25-37: The "Adding a New Archetype" example in CONTRIBUTING.md
still references the old packages/core path and ARCHETYPES.set(...); update the
example to point contributors to packages/intelligence and use the new
array-based registry shape from packages/intelligence/src/archetypes/index.ts
(e.g., add or export the archetype into the registry array instead of calling
ARCHETYPES.set). Replace any occurrences of ARCHETYPES.set(...) and the
packages/core path with the new registry interaction and packages/intelligence
location so the example matches the current API.
In `@packages/eval/src/__tests__/fixtures.test.ts`:
- Around line 19-68: The test harness reads jd.md in loadFixtures() and
populates Fixture.jd but never asserts on it; either stop reading jd.md (remove
jdPath/existsSync/readFileSync usage in loadFixtures or drop jd property) or add
assertions that use f.jd (e.g., a new test in the per-fixture describe block
that validates JD presence/format or JD-specific behavior for fixtures that
include jd) so the swe-with-jd fixture actually exercises JD logic; update the
Fixture interface and loadFixtures() accordingly (look for loadFixtures,
Fixture.jd, and the per-fixture test loop to make the change).
In `@packages/intelligence/src/detect.ts`:
- Around line 12-26: The detectArchetype function currently falls back to
DEFAULT_ARCHETYPE even when a caller provided a custom archetypes array; change
the fallback to prefer the caller-supplied first archetype by initializing best
to archetypes[0] ?? DEFAULT_ARCHETYPE (and keep bestScore = 0), so
detectArchetype and its loop use that initial choice instead of always returning
DEFAULT_ARCHETYPE when no matches are found.
In `@packages/intelligence/src/validators/ats.ts`:
- Line 32: The regex used to detect tab-delimited layout on resumeText only
matches when there are two tabs (/\t.*\t/) and therefore misses common rows like
"Role\tCompany"; update the check in the ATS validation to detect a single tab
anywhere in resumeText (i.e., replace the /\t.*\t/ test with a pattern that
matches at least one tab such as /\t/) so that the condition if
(/\|.*\|/.test(resumeText) || /\t.*\t/.test(resumeText)) correctly flags
tab-delimited content; target the line using the resumeText variable and the
existing conditional expression.
---
Nitpick comments:
In @.claude/skills/cv-evaluation/SKILL.md:
- Around line 25-30: The step requiring "Surface **at least 3** issues" is too
rigid and should be relaxed; update the SKILL.md step 3 wording to "Surface up
to 3 issues" and add an explicit instruction to only return findings that are
directly supported by quoted resume text (no filler), keeping the rest of the
references to `packages/prompts/prompts/score.md`, `rubric.md`, and `scoring.md`
unchanged; ensure the phrasing ties this behaviour to the scoring prompt
(score.md) so the agent enforces the "up to 3" and "only supported findings"
constraint when generating outputs.
In `@packages/intelligence/src/archetypes/index.ts`:
- Around line 20-22: listArchetypes currently returns the live ARCHETYPES array
which allows callers to mutate the registry; change listArchetypes to return a
shallow copy of ARCHETYPES (e.g., using a copy operation) so callers cannot
push/splice the original; optionally consider converting ARCHETYPES to a
ReadonlyArray or applying Object.freeze for stronger immutability guarantees
later.
In `@packages/prompts/src/index.ts`:
- Around line 37-43: The weights list currently iterates
Object.entries(archetype.evaluationWeights) which depends on insertion order;
instead build weights from RUBRIC.dimensions to preserve rubric order: map over
RUBRIC.dimensions (the same array used to build rubric) and for each dimension
(e.g., in the map callback for RUBRIC.dimensions) lookup the corresponding
weight from archetype.evaluationWeights using the dimension's key/name (e.g.,
d.name or d.key) and format `- ${d.name}: ${weight}`; also handle missing
weights with a sensible default or explicit indicator so the prompt remains
stable (references: archetype.evaluationWeights, RUBRIC.dimensions, weights
variable).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 800c66f2-5cf6-4604-9606-5b2c5c10ea9d
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (66)
.claude/commands/evaluate-cv.md.claude/commands/setup-profile.md.claude/settings.json.claude/skills/cv-evaluation/SKILL.md.claude/skills/cv-evaluation/archetypes.md.claude/skills/cv-evaluation/claim-validation.md.claude/skills/cv-evaluation/rubric.md.claude/skills/cv-evaluation/scoring.md.claude/welcome.sh.github/workflows/ci.ymlCLAUDE.mdCONTRIBUTING.mdREADME.mdapps/cli/README.mdapps/cli/package.jsonpackage.jsonpackages/eval/README.mdpackages/eval/fixtures/data-ml-strong/expected.jsonpackages/eval/fixtures/data-ml-strong/resume.mdpackages/eval/fixtures/pm-strong/expected.jsonpackages/eval/fixtures/pm-strong/resume.mdpackages/eval/fixtures/swe-strong/expected.jsonpackages/eval/fixtures/swe-strong/resume.mdpackages/eval/fixtures/swe-weak-table/expected.jsonpackages/eval/fixtures/swe-weak-table/resume.mdpackages/eval/fixtures/swe-with-jd/expected.jsonpackages/eval/fixtures/swe-with-jd/jd.mdpackages/eval/fixtures/swe-with-jd/resume.mdpackages/eval/package.jsonpackages/eval/src/__tests__/fixtures.test.tspackages/eval/tsconfig.jsonpackages/eval/vitest.config.tspackages/intelligence/README.mdpackages/intelligence/package.jsonpackages/intelligence/src/__tests__/intelligence.test.tspackages/intelligence/src/archetypes/data-ml-engineer.tspackages/intelligence/src/archetypes/index.tspackages/intelligence/src/archetypes/product-manager.tspackages/intelligence/src/archetypes/software-engineer.tspackages/intelligence/src/detect.tspackages/intelligence/src/index.tspackages/intelligence/src/rubric.tspackages/intelligence/src/validators/ats.tspackages/intelligence/src/validators/claims.tspackages/intelligence/tsconfig.jsonpackages/intelligence/vitest.config.tspackages/prompts/README.mdpackages/prompts/package.jsonpackages/prompts/prompts/extract.mdpackages/prompts/prompts/score.mdpackages/prompts/prompts/validate-claims.mdpackages/prompts/src/__tests__/prompts.test.tspackages/prompts/src/index.tspackages/prompts/tsconfig.jsonpackages/prompts/vitest.config.tspackages/schemas/README.mdpackages/schemas/package.jsonpackages/schemas/src/__tests__/schemas.test.tspackages/schemas/src/archetype.tspackages/schemas/src/evaluation.tspackages/schemas/src/index.tspackages/schemas/src/job-description.tspackages/schemas/src/resume.tspackages/schemas/tsconfig.jsonpackages/schemas/vitest.config.tsturbo.json
added 13 commits
June 12, 2026 13:33
…to feature/intelligence-rubric-archetypes
…etypes' into feature/prompts-pack
…le readme example
…re/cli-power-user-pack
…o feature/eval-harness # Conflicts: # package.json
…power-user-quickstart
…ist in detect fallback
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
CONTRIBUTING.md (1)
24-38:⚠️ Potential issue | 🟡 MinorCONTRIBUTING.md: keep
packages/cli/—it exists; clarify the “two CLIs” distinction
packages/cli/package.jsonis present (@cv-builder/cli) and defines thecv-builderbinary, so thepackages/cli/entry in the structure snippet is accurate.apps/cli/is a separate “power-user” pack (@cv-builder/power-user); adjust the snippet wording if you want to make the relationship clearer.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@CONTRIBUTING.md` around lines 24 - 38, Keep the packages/cli/ entry — it corresponds to packages/cli/package.json and the `@cv-builder/cli` binary — and clarify the two-CLI distinction by noting that apps/cli/ is a separate power-user package (apps/cli/ with package name `@cv-builder/power-user`), so update the CONTRIBUTING.md tree description to explicitly state packages/cli is the core CLI and apps/cli is the power-user CLI.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@CONTRIBUTING.md`:
- Around line 24-38: Keep the packages/cli/ entry — it corresponds to
packages/cli/package.json and the `@cv-builder/cli` binary — and clarify the
two-CLI distinction by noting that apps/cli/ is a separate power-user package
(apps/cli/ with package name `@cv-builder/power-user`), so update the
CONTRIBUTING.md tree description to explicitly state packages/cli is the core
CLI and apps/cli is the power-user CLI.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 9198de7c-832a-48ca-bedb-0fbd822216aa
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml,!**/pnpm-lock.yaml
📒 Files selected for processing (18)
.claude/skills/cv-evaluation/SKILL.mdCONTRIBUTING.mdapps/cli/README.mdpackage.jsonpackages/eval/src/__tests__/fixtures.test.tspackages/intelligence/package.jsonpackages/intelligence/src/__tests__/intelligence.test.tspackages/intelligence/src/archetypes/index.tspackages/intelligence/src/detect.tspackages/intelligence/src/index.tspackages/intelligence/src/rubric.tspackages/intelligence/src/validators/ats.tspackages/prompts/README.mdpackages/prompts/prompts/extract.mdpackages/prompts/src/index.tspackages/schemas/src/__tests__/schemas.test.tspackages/schemas/src/evaluation.tspackages/schemas/src/index.ts
✅ Files skipped from review due to trivial changes (2)
- packages/prompts/README.md
- packages/intelligence/src/index.ts
🚧 Files skipped from review as they are similar to previous changes (12)
- package.json
- apps/cli/README.md
- packages/eval/src/tests/fixtures.test.ts
- packages/intelligence/src/rubric.ts
- packages/intelligence/src/validators/ats.ts
- packages/schemas/src/tests/schemas.test.ts
- packages/intelligence/src/archetypes/index.ts
- packages/intelligence/src/tests/intelligence.test.ts
- .claude/skills/cv-evaluation/SKILL.md
- packages/intelligence/package.json
- packages/prompts/src/index.ts
- packages/schemas/src/index.ts
added 5 commits
June 12, 2026 17:43
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
open Claude Code →
/evaluate-cv), linkingapps/cli/README.md.tree to list the new packages:
schemas,intelligence,prompts,eval,and
apps/cli(plus.claude/).packages/intelligence(where therubric/archetypes now live).
Related issue
Closes #67
Type of change
Note for reviewers
Final PR in the Phase-1 power-user stack: #47 → #63 → #64 → #65 → #66 → #67.
The full stack
2e07cd9 docs #67 ← docs/power-user-quickstart
c44edf1 test(eval) #66 ← feature/eval-harness
131083a feat(cli) #65 ← feature/cli-power-user-pack
7b09845 feat(prompts) #64 ← feature/prompts-pack
eee572d feat(intelligence) #63 ← feature/intelligence-rubric-archetypes
f16790b feat(schemas) #47 ← feature/schemas-zod-contract
main
Summary by CodeRabbit
New Features
Documentation
Tests