Orchestrator/privat/CV/SPEC.md

SPEC.md — Personal Knowledge Base

Purpose

A file-based personal knowledge graph that stores structured professional information in YAML, enabling tailored CV generation, interview-based knowledge collection, speaker introductions, and iterative review workflows. The file system is the database — no build step, no server, no compilation required.

Tech Stack

Layer	Technology
Data format	YAML (one file per entity)
Validation & logic	TypeScript (strict mode)
Testing	Vitest + fast-check (property-based)
Runtime	Node.js (v24+)
Version control	Git
Automation	Kiro skills (.kiro/skills/)

Architecture

project-root/
├── kb/                        # Knowledge base data (YAML entities)
│   ├── profiles/              # Person profiles
│   ├── experiences/           # Work experiences
│   ├── skills/                # Skills
│   ├── organizations/         # Organizations
│   ├── projects/              # Projects
│   ├── certifications/        # Certifications
│   ├── tandems/               # Job sharing tandems
│   └── graph-index.yaml       # Central entity/relationship index
├── templates/                 # Document generation templates
├── output/                    # Generated documents (CVs, intros)
├── sources/                   # Imported source documents
├── src/                       # TypeScript validation and logic
│   ├── schemas/               # Entity interfaces and validation
│   ├── io/                    # YAML serialization and file I/O
│   ├── graph/                 # Graph index management
│   ├── interview/             # Gap and conflict detection
│   ├── cv/                    # Relevance selection and tandem generation
│   ├── intro/                 # Introduction generation
│   └── review/                # Completeness scoring and prioritization
└── .kiro/skills/              # Kiro agent skills
    ├── interview-collect/     # Knowledge collection via interview
    ├── cv-generate/           # Tailored CV generation
    ├── talk-intro/            # Speaker introduction generation
    └── kb-review/             # Knowledge base review

Entity Types

• Person — name, contact, summary, education, languages, references to skills/experiences/certifications
• Experience — title, organization, dates, description, achievements, skills-used
• Skill — name, category, level, years, context
• Organization — name, industry, optional parent
• Project — name, description, organization, dates, skills-used, persons
• Certification — name, issuer, date, expires, person
• Tandem — exactly 2 partners, shared-vision, complementary-skills, collaboration-model

Relationship Types

has_skill, worked_at, collaborated_with, applied_for, partners_with

Kiro Skills

Skill	Purpose
interview-collect	Focused interview sessions (max 10 questions) to collect/update KB data
cv-generate	Tailored CVs matched against job postings; supports tandem applications
talk-intro	Speaker introductions in 3 length variants adapted to event context
kb-review	Completeness scoring, staleness detection, review prioritization

Conventions

• File naming: kebab-case (<entity-id>.yaml)
• One file per entity
• Graph index updated on every entity change
• All data human-readable and diffable in Git
• TypeScript interfaces use camelCase (deserialized form of kebab-case YAML)

Rules

1. Never fabricate content in generated documents — only use data present in the knowledge base.
2. Validate entities against schema before persisting.
3. Enforce temporal consistency (start ≤ end) for time-bound entities.
4. Create and use Kiro skills whenever a task of more than 5 lines of code runs for the second time.

Correctness Properties

15 formal properties validated via property-based testing (fast-check):

1. Entity serialization round-trip
2. Entity schema validation
3. Temporal consistency
4. Graph index consistency
5. Tandem entity integrity
6. Interview session question limit (≤ 10)
7. Gap detection completeness
8. Conflict detection
9. CV relevance selection ordering
10. Tandem application document set (exactly 3 docs)
11. CV output validity and traceability
12. Introduction length variants (short < medium < long)
13. Completeness score calculation
14. Review prioritization ordering
15. File naming convention (kebab-case)

Current State

• Directory structure: created
• TypeScript project: initialized, dependencies installed
• Entity interfaces: defined (src/schemas/types.ts)
• Validation, I/O, graph, skills, tests: pending implementation