Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions .agent/agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,12 @@ schemas ← core ← react ← apps/web
## Key invariants

- `generateLearningPath()` is pure: no async, no network, no side effects
- `LearningPathInput` shape is the public API contract do not change without a major version bump
- `packages/react` has no Tailwind dependency CSS custom properties only
- All TypeScript types in packages are inferred from Zod schemas no manual type duplication
- The demo at /demo runs entirely on @learnkit-ai/core zero backend required
- `LearningPathInput` shape is the public API contract - do not change without a major version bump
- `packages/react` has no Tailwind dependency - CSS custom properties only
- All TypeScript types in packages are inferred from Zod schemas - no manual type duplication
- The demo at /demo runs entirely on @learnkit-ai/core - zero backend required

## Public API @learnkit-ai/core
## Public API - @learnkit-ai/core

```typescript
function generateLearningPath(input: LearningPathInput): LearningPath
Expand All @@ -76,7 +76,7 @@ Input type (LearningPathInput):
}
```

## Component API @learnkit-ai/react
## Component API - @learnkit-ai/react

```tsx
<LearningPath input={LearningPathInput} onLessonClick? theme? className? />
Expand All @@ -97,36 +97,36 @@ useLearnKit(input: LearningPathInput): { path, loading, error }
No fake social proof: no customer logos, no testimonials, no GitHub star counts,
no compliance badges (SOC 2, HIPAA, GDPR), no user or revenue metrics.

## Out of scope (project is pure OSS no hosted SaaS)
## Out of scope (project is pure OSS - no hosted SaaS)

- Any backend server (NestJS, Express, Hono, or any HTTP server)
- Any database (Prisma, Postgres, SQLite, or any persistence layer)
- Authentication of any kind
- Billing or pricing of any kind Apache-2.0, no paid tier, ever
- Billing or pricing of any kind - Apache-2.0, no paid tier, ever
- Real LLM API calls (Anthropic, OpenAI, Gemini, or any LLM provider)
- Docker or docker-compose
- Team dashboard, HR analytics, SSO, SCIM
- A hosted REST API (`apps/api`) the engine is client-side only
- A hosted REST API (`apps/api`) - the engine is client-side only
- Tracking, analytics, telemetry, phone-home

## Rules

See `.agent/rules/` for full conventions. Short version:

- No `any` without an explanatory comment
- Named exports only from packages no `export default` in packages/
- Named exports only from packages - no `export default` in packages/
- Co-locate tests: `foo.ts` → `__tests__/foo.test.ts`
- No mocking internal packages in tests only mock at system boundaries
- No mocking internal packages in tests - only mock at system boundaries
- All Zod schemas live in packages/schemas
- Stage files by name never `git add .` or `git add -A`
- Stage files by name - never `git add .` or `git add -A`
- Commit messages: imperative mood, no AI co-author lines, no file lists

## Do not touch

- `pnpm-lock.yaml`
- `packages/schemas/src/index.ts` types once stabilized they are the public API contract
- `packages/schemas/src/index.ts` types once stabilized - they are the public API contract
- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.windsurfrules`, `GEMINI.md`, `CONVENTIONS.md`
these are generated from this file; edit here and re-sync
- these are generated from this file; edit here and re-sync

## Agent config sync

Expand Down
26 changes: 13 additions & 13 deletions .agent/agents/code-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,26 +4,26 @@ You are a senior TypeScript engineer reviewing a LearnKit AI pull request.

## Behavior

- Be direct and specific point to exact file paths and line numbers
- Be direct and specific - point to exact file paths and line numbers
- Explain why something is wrong, not just that it is
- Distinguish blocking issues from warnings from nitpicks
- Do not praise assume the author is competent
- Do not praise - assume the author is competent

## Focus areas

1. **Correctness** does it do what it claims? Are edge cases handled?
2. **API contract** is `LearningPathInput` shape preserved?
3. **Purity** is `generateLearningPath()` still pure and synchronous?
4. **Types** no `any`, types inferred from Zod, no manual duplicates
5. **Brand** no "Olé", no fake social proof, no wrong domain/scope
6. **Scope** no backend, database, auth, or LLM calls sneaking in
7. **Tests** new logic has coverage, no internal mocks
8. **Security** no secrets, no `dangerouslySetInnerHTML`, no `eval`
1. **Correctness** - does it do what it claims? Are edge cases handled?
2. **API contract** - is `LearningPathInput` shape preserved?
3. **Purity** - is `generateLearningPath()` still pure and synchronous?
4. **Types** - no `any`, types inferred from Zod, no manual duplicates
5. **Brand** - no "Olé", no fake social proof, no wrong domain/scope
6. **Scope** - no backend, database, auth, or LLM calls sneaking in
7. **Tests** - new logic has coverage, no internal mocks
8. **Security** - no secrets, no `dangerouslySetInnerHTML`, no `eval`

## Output format

```
[BLOCKING] path/to/file.ts:42 description. required action.
[WARNING] path/to/file.ts:88 description. should fix before merge.
[NITPICK] path/to/file.ts:101 optional improvement.
[BLOCKING] path/to/file.ts:42 - description. required action.
[WARNING] path/to/file.ts:88 - description. should fix before merge.
[NITPICK] path/to/file.ts:101 - optional improvement.
```
16 changes: 8 additions & 8 deletions .agent/agents/security-auditor.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,16 @@ You are a security engineer auditing LearnKit AI for vulnerabilities.
- Assume hostile input at every external boundary
- Flag anything suspicious even if not confirmed vulnerable
- Reference OWASP categories where relevant
- Only suggest real mitigations no security theater
- Only suggest real mitigations - no security theater

## v0 attack surface

v0 has no backend, no auth, no database. Focus on:

1. **Supply chain** new npm dependencies with known CVEs or suspicious provenance
2. **XSS** React rendering of user-supplied content unsafely
3. **Secret leakage** API keys, tokens, or credentials in source or .env files
4. **Code injection** `eval()`, `new Function()`, dynamic `require()` with user data
1. **Supply chain** - new npm dependencies with known CVEs or suspicious provenance
2. **XSS** - React rendering of user-supplied content unsafely
3. **Secret leakage** - API keys, tokens, or credentials in source or .env files
4. **Code injection** - `eval()`, `new Function()`, dynamic `require()` with user data

## What to look for

Expand All @@ -29,7 +29,7 @@ v0 has no backend, no auth, no database. Focus on:
## Output format

```
[CRITICAL] path/to/file.ts:14 description. required action.
[HIGH] path/to/file.ts:88 description.
[MEDIUM] path/to/file.ts:32 description.
[CRITICAL] path/to/file.ts:14 - description. required action.
[HIGH] path/to/file.ts:88 - description.
[MEDIUM] path/to/file.ts:32 - description.
```
16 changes: 8 additions & 8 deletions .agent/commands/fix-issue.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
Fix the issue: $ARGUMENTS

1. **Understand** restate the problem in one sentence before touching any code
2. **Locate** find the relevant code by searching for symbols, not by guessing paths
3. **Reproduce** write a failing Vitest test that demonstrates the bug
4. **Fix** change only what is needed to make the test pass
5. **Verify** run `pnpm test` and `pnpm typecheck` both must be clean
6. **Check scope** confirm the fix does not add backend, database, auth, or LLM calls
7. **Stage** add only the changed files by name: `git add path/to/file.ts`
8. **Commit message** imperative mood, one sentence, no AI co-author lines
1. **Understand** - restate the problem in one sentence before touching any code
2. **Locate** - find the relevant code by searching for symbols, not by guessing paths
3. **Reproduce** - write a failing Vitest test that demonstrates the bug
4. **Fix** - change only what is needed to make the test pass
5. **Verify** - run `pnpm test` and `pnpm typecheck` - both must be clean
6. **Check scope** - confirm the fix does not add backend, database, auth, or LLM calls
7. **Stage** - add only the changed files by name: `git add path/to/file.ts`
8. **Commit message** - imperative mood, one sentence, no AI co-author lines

Do not refactor unrelated code while fixing. Do not change `LearningPathInput`
shape unless the issue explicitly requires it.
12 changes: 6 additions & 6 deletions .agent/commands/review.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ Check each category. Reference exact file paths and line numbers.
**1. Correctness**
- Does the code do what it claims?
- Are edge cases handled (empty arrays, undefined inputs, unsupported roles)?
- Does `generateLearningPath()` remain pure no async, no side effects?
- Does `generateLearningPath()` remain pure - no async, no side effects?

**2. Types**
- No `any` without an explanatory comment
- All types inferred from Zod schemas no manual duplicates
- All types inferred from Zod schemas - no manual duplicates
- No type assertions (`as Foo`) that could hide runtime errors

**3. Brand**
Expand Down Expand Up @@ -44,12 +44,12 @@ Check each category. Reference exact file paths and line numbers.
- No `export default` from `packages/`
- Files co-located with their tests

Output format one line per finding:
Output format - one line per finding:

```
[BLOCKING] path/to/file.ts:42 problem description. required action.
[WARNING] path/to/file.ts:88 problem description. should fix before merge.
[NITPICK] path/to/file.ts:101 optional suggestion.
[BLOCKING] path/to/file.ts:42 - problem description. required action.
[WARNING] path/to/file.ts:88 - problem description. should fix before merge.
[NITPICK] path/to/file.ts:101 - optional suggestion.
```

Do not summarize what the code does. Do not praise. Be specific.
10 changes: 5 additions & 5 deletions .agent/rules/api-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ may change freely.

`LearningPathInput` is locked for v0:

- Do not add required fields it is a breaking change
- Do not add required fields - it is a breaking change
- Optional fields (`companyContext?`) may be added in minor versions
- Renaming, removing, or changing the type of any field is a major version bump
- Do not change the output shape of `generateLearningPath()` without a major bump
Expand All @@ -35,7 +35,7 @@ export type { LearningPath, LearningPathInput, Lesson }
export default function generateLearningPath(...)
```

Exception: Next.js App Router page components require `export default` this
Exception: Next.js App Router page components require `export default` - this
applies only inside `apps/web/app/`.

## Zod schemas
Expand All @@ -49,10 +49,10 @@ applies only inside `apps/web/app/`.
## Error handling

- `generateLearningPath()` never throws for input that passes Zod validation
- Unknown or unsupported roles return a valid generic LearningPath documented fallback,
- Unknown or unsupported roles return a valid generic LearningPath - documented fallback,
not an exception
- Invalid input that fails Zod parse surfaces as `ZodError` callers can catch it
- No `console.error` in packages surface errors to the caller
- Invalid input that fails Zod parse surfaces as `ZodError` - callers can catch it
- No `console.error` in packages - surface errors to the caller

## Versioning

Expand Down
18 changes: 9 additions & 9 deletions .agent/rules/code-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## TypeScript

- Strict mode everywhere `tsconfig.base.json` sets `"strict": true`
- Strict mode everywhere - `tsconfig.base.json` sets `"strict": true`
- No `any` without a comment explaining why it cannot be avoided
- Named exports only from packages no `export default` inside `packages/`
- Named exports only from packages - no `export default` inside `packages/`
- Prefer `type` over `interface` for data shapes; use `interface` only for
extension points that consumers are expected to augment
- Infer types from Zod schemas do not write matching manual types alongside them
- Infer types from Zod schemas - do not write matching manual types alongside them
- `const` over `let`, never `var`
- Arrow functions for callbacks and inline expressions
- `async`/`await` over `.then()` chains
Expand All @@ -23,24 +23,24 @@

## File size

- Aim for ~100 lines per file split when longer
- Aim for ~100 lines per file - split when longer
- One primary export per file
- No barrel re-export chains deeper than one level (`index.ts` re-exports direct sources)
- No circular imports dependency graph must be a DAG
- No circular imports - dependency graph must be a DAG

## Comments

- No comments explaining what the code does use clear names instead
- No comments explaining what the code does - use clear names instead
- Comments only for: non-obvious constraints, invariants, or bug workarounds
- No `// TODO` committed to main open a GitHub issue instead
- No `// TODO` committed to main - open a GitHub issue instead

## React

- Functional components only
- Props typed with `type`, not `interface`, unless explicitly designed for extension
- No prop spreading except when forwarding to a native HTML element
- No inline `style` objects use CSS custom properties (`--lk-*`) or Tailwind classes
- `packages/react` must not import Tailwind CSS custom properties only
- No inline `style` objects - use CSS custom properties (`--lk-*`) or Tailwind classes
- `packages/react` must not import Tailwind - CSS custom properties only

## Formatting

Expand Down
16 changes: 8 additions & 8 deletions .agent/rules/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## Secrets

- No API keys, tokens, passwords, or secrets in source code ever
- No API keys, tokens, passwords, or secrets in source code - ever
- `.env.example` must contain only placeholder values: `SOME_KEY=your_key_here`
- `.env` and `.env.local` are gitignored verify before every commit
- `.env` and `.env.local` are gitignored - verify before every commit
- Run `git diff --staged` and scan for secrets before committing

## Input validation
Expand All @@ -17,14 +17,14 @@

## React output

- No `dangerouslySetInnerHTML` render all text as React children
- No `dangerouslySetInnerHTML` - render all text as React children
- No user-supplied strings injected into CSS custom properties at runtime
- All external links (`<a href>` to third-party domains): add `rel="noopener noreferrer"`
- Images from external URLs: validate domain allowlist if added in future

## Dependencies

- Review every new dependency before adding prefer small, audited, well-maintained packages
- Review every new dependency before adding - prefer small, audited, well-maintained packages
- Run `pnpm audit` before merging any PR that changes `pnpm-lock.yaml`
- Do not add packages with known critical CVEs
- Prefer packages with TypeScript types built-in or `@types/*` available
Expand All @@ -34,9 +34,9 @@
v0 has no backend, no auth, no database, no user accounts.
Main risks in scope:

1. **Supply chain** malicious or compromised npm packages
2. **XSS** unsafe React rendering of user-supplied content
3. **Secret leakage** accidentally committed `.env` or API keys
1. **Supply chain** - malicious or compromised npm packages
2. **XSS** - unsafe React rendering of user-supplied content
3. **Secret leakage** - accidentally committed `.env` or API keys

Do not add attack surface in v0. If a feature requires auth, a server,
or data persistence it belongs in v1, not here.
or data persistence - it belongs in v1, not here.
10 changes: 5 additions & 5 deletions .agent/rules/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,22 +15,22 @@ packages/core/src/__tests__/generator.test.ts

## Writing tests

- Test behavior, not implementation assert what a function returns, not how it works internally
- Test behavior, not implementation - assert what a function returns, not how it works internally
- One logical assertion per test where possible
- Test names describe the scenario in plain English:
`it('returns a fallback path for an unsupported role')`
- No `describe` nesting deeper than two levels
- Prefer independent tests avoid shared mutable state between tests
- Prefer independent tests - avoid shared mutable state between tests
- No `beforeAll`/`afterAll` unless there is no reasonable alternative

## Mocking

- Mock only at system boundaries: HTTP, filesystem, clocks, external APIs
- Never mock internal packages import and use the real implementation
- Never mock internal packages - import and use the real implementation
- Never mock `@learnkit-ai/core` inside `@learnkit-ai/react` tests
- Never mock `@learnkit-ai/schemas` anywhere

## Required coverage packages/core
## Required coverage - packages/core

These scenarios must have explicit tests:

Expand All @@ -42,7 +42,7 @@ These scenarios must have explicit tests:
- Unknown/unsupported role returns a valid LearningPath (no throw, no undefined)
- Output validates against `learningPathSchema` from @learnkit-ai/schemas

## Required coverage packages/schemas
## Required coverage - packages/schemas

- Each Zod schema accepts a known-valid object without error
- Each Zod schema rejects a known-invalid object with a ZodError
Expand Down
Loading
Loading