You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The core package (which the CLI and Web UI consume) and the intelligence package (which the prompt pack and eval fixtures
consume) each maintain their own archetype registry. They use
different types, different IDs, and have no shared source of truth.
This causes three concrete problems for the project:
The README's "8 archetypes" claim was wrong — core has 7, intelligence has 3. Auditors found the gap and corrected it.
A user-facing PM resume misdetects as backend-engineer —
because the live detector (in core) only knows about ai-product-manager, never the plain product-manager that intelligence knows about. Plain-PM detection is functionally
broken in the public surface.
pnpm eval tests a different system than the CLI/Web UI use.
The golden fixtures (pm-strong, swe-strong, data-ml-strong)
run against intelligence.detectArchetype and the Archetype
type. They never exercise the live core.evaluate() path.
Until this is consolidated, every new archetype has to be added in
two places, with two key shapes, and two detectArchetype
implementations — all with the risk that one drifts from the other.
Both expose listArchetypes(), getArchetype(id), detectArchetype(text).
Goal
After this is closed, one archetype registry is the source of
truth. All consumers (packages/core, packages/cli, apps/web-ui, packages/prompts, packages/eval, .claude/skills/cv-evaluation/)
import from the same place. The Archetype type lives in @cv-builder/schemas and is the only one. RoleArchetype is
removed.
Recommended approach (high level — design freedom belongs to the PR)
The cleanest design is:
Promote packages/schemas/src/archetype.ts to the canonical Archetype schema. Add version to the existing core entries
(just "1.0.0"; no semantic change).
Move the merged archetype files into packages/intelligence/src/archetypes/
(it's already the place the prompts and skill reference).
Re-implement core.detectArchetype and core.listArchetypes as
thin re-exports of intelligence.detectArchetype / intelligence.listArchetypes. The existing core.getArchetype
becomes listArchetypes().find(...) or delegates.
Update packages/core/src/evaluator/index.ts to use the Archetype
shape (notably, the EvaluationResult.archetype field gains a version string — wire it through and bump the docs).
Update packages/eval/fixtures/ to use the consolidated IDs (or
alias the existing fixture archetypes to the merged IDs).
Add version to every existing Archetype file in packages/intelligence/src/archetypes/*.ts if not already there
(the three currently shipping — software-engineer, product-manager, data-ml-engineer — already do).
This is a medium-to-large refactor (~10 files, schema migration,
test updates). It does not add new role types — it only merges.
Scope fence (do not do in this PR)
No new role archetypes. Adding roles on top of an unmerged
registry widens the eventual migration. Land the merge first, add
roles after.
No LLM provider changes. Provider work is in packages/llm
(separate).
No prompt-package changes other than anything required to
consume the merged Archetype shape.
Acceptance criteria
packages/core no longer defines its own archetype registry;
it re-exports from packages/intelligence.
pnpm --filter @cv-builder/cli start archetypes and pnpm eval both produce the same list of archetypes with the
same IDs and display names.
apps/web-ui/src/app/results/page.tsx still renders result.archetype.name correctly (no UI change required).
Golden fixtures (packages/eval/fixtures/{swe,pm,data-ml}-strong/expected.json)
continue to pass without modification (or with a one-line
alias update if IDs changed — that is acceptable).
pnpm test, pnpm lint, pnpm build all green.
RoleArchetype removed from packages/core/src/types.ts; EvaluationResult.archetype is typed as packages/schemas/src/archetype.tsArchetype.
Tests needed
Cross-package integration test asserting that the evaluator's
detected archetype has the same id and name as intelligence.detectArchetype(cv).id on a small set of fixtures.
Unit tests preserved from the existing packages/eval/src/__tests__/fixtures.test.ts.
docs/ARCHETECTURE.md —
remove the language that puts core and intelligence on
parallel footings for archetypes. After the merge, intelligence becomes the only owner.
Update the packages/intelligence/README.md "Archetypes" section
to reflect that it is now the canonical source (and remove the core's 'How to add an archetype' comments from packages/core/src/archetypes/index.ts).
Add a short paragraph in this file's conclusion pointing to
the audit.
Related issues / docs
Source: docs/ARCHETYPE_GAP_AUDIT.md
— the audit identified the duplicate registry as the second-most
critical gap.
Why this matters for Tech Immigrants
The
corepackage (which the CLI and Web UI consume) and theintelligencepackage (which the prompt pack and eval fixturesconsume) each maintain their own archetype registry. They use
different types, different IDs, and have no shared source of truth.
This causes three concrete problems for the project:
corehas 7,intelligencehas 3. Auditors found the gap and corrected it.backend-engineer—because the live detector (in
core) only knows aboutai-product-manager, never the plainproduct-managerthatintelligenceknows about. Plain-PM detection is functionallybroken in the public surface.
pnpm evaltests a different system than the CLI/Web UI use.The golden fixtures (
pm-strong,swe-strong,data-ml-strong)run against
intelligence.detectArchetypeand theArchetypetype. They never exercise the live
core.evaluate()path.Until this is consolidated, every new archetype has to be added in
two places, with two key shapes, and two
detectArchetypeimplementations — all with the risk that one drifts from the other.
Current state
version?@cv-builder/corepackages/core/src/archetypes/index.tsRoleArchetype(plain TS,packages/core/src/types.ts)@cv-builder/intelligencepackages/intelligence/src/archetypes/index.tsArchetype(Zod,packages/schemas/src/archetype.ts)Both expose
listArchetypes(),getArchetype(id),detectArchetype(text).Goal
After this is closed, one archetype registry is the source of
truth. All consumers (
packages/core,packages/cli,apps/web-ui,packages/prompts,packages/eval,.claude/skills/cv-evaluation/)import from the same place. The
Archetypetype lives in@cv-builder/schemasand is the only one.RoleArchetypeisremoved.
Recommended approach (high level — design freedom belongs to the PR)
The cleanest design is:
packages/schemas/src/archetype.tsto the canonicalArchetypeschema. Addversionto the existingcoreentries(just
"1.0.0"; no semantic change).packages/intelligence/src/archetypes/(it's already the place the prompts and skill reference).
core.detectArchetypeandcore.listArchetypesasthin re-exports of
intelligence.detectArchetype/intelligence.listArchetypes. The existingcore.getArchetypebecomes
listArchetypes().find(...)or delegates.packages/core/src/evaluator/index.tsto use theArchetypeshape (notably, the
EvaluationResult.archetypefield gains aversionstring — wire it through and bump the docs).packages/eval/fixtures/to use the consolidated IDs (oralias the existing fixture archetypes to the merged IDs).
versionto every existingArchetypefile inpackages/intelligence/src/archetypes/*.tsif not already there(the three currently shipping —
software-engineer,product-manager,data-ml-engineer— already do).This is a medium-to-large refactor (~10 files, schema migration,
test updates). It does not add new role types — it only merges.
Scope fence (do not do in this PR)
registry widens the eventual migration. Land the merge first, add
roles after.
packages/llm(separate).
consume the merged
Archetypeshape.Acceptance criteria
packages/coreno longer defines its own archetype registry;it re-exports from
packages/intelligence.pnpm --filter @cv-builder/cli start archetypesandpnpm evalboth produce the same list of archetypes with thesame IDs and display names.
apps/web-ui/src/app/results/page.tsxstill rendersresult.archetype.namecorrectly (no UI change required).packages/eval/fixtures/{swe,pm,data-ml}-strong/expected.json)continue to pass without modification (or with a one-line
alias update if IDs changed — that is acceptable).
pnpm test,pnpm lint,pnpm buildall green.RoleArchetyperemoved frompackages/core/src/types.ts;EvaluationResult.archetypeis typed aspackages/schemas/src/archetype.tsArchetype.Tests needed
detected archetype has the same id and name as
intelligence.detectArchetype(cv).idon a small set of fixtures.packages/eval/src/__tests__/fixtures.test.ts.core.detectArchetypeunit test (the currently-open issue [Core] Add unit tests for archetype detection #15,[Core] Add unit tests for archetype detection, can land as partof this work).
Docs / updates needed
docs/ARCHETECTURE.md—remove the language that puts
coreandintelligenceonparallel footings for archetypes. After the merge,
intelligencebecomes the only owner.packages/intelligence/README.md"Archetypes" sectionto reflect that it is now the canonical source (and remove the
core's 'How to add an archetype' comments frompackages/core/src/archetypes/index.ts).the audit.
Related issues / docs
docs/ARCHETYPE_GAP_AUDIT.md— the audit identified the duplicate registry as the second-most
critical gap.
product-managertocore),the merged registry will have a plain PM. This consolidation can
land in either order, but landing Add plain Product Manager archetype to packages/core (no AI keywords) #90 first means the merge
ships with PM included.