kordexa 0.0.0-stage → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/commands/eduorchestrate-card.md +5 -0
- package/.claude/commands/eduorchestrate-log.md +6 -0
- package/.claude/commands/eduorchestrate-next.md +5 -0
- package/.claude/commands/eduorchestrate-research.md +6 -0
- package/.claude/commands/eduorchestrate-send.md +5 -0
- package/.claude/commands/eduorchestrate-status.md +5 -0
- package/.claude/commands/eduorchestrate-weekly.md +6 -0
- package/.claude/commands/kordexa-card.md +5 -0
- package/.claude/commands/kordexa-log.md +6 -0
- package/.claude/commands/kordexa-next.md +5 -0
- package/.claude/commands/kordexa-research.md +6 -0
- package/.claude/commands/kordexa-send.md +5 -0
- package/.claude/commands/kordexa-status.md +5 -0
- package/.claude/commands/kordexa-weekly.md +6 -0
- package/.claude/skills/eduorchestrate/SKILL.md +24 -0
- package/.claude/skills/kordexa/SKILL.md +24 -0
- package/.eduorchestrate/adapters/antigravity/manifest.json +31 -0
- package/.eduorchestrate/adapters/codex/AGENTS.md +23 -0
- package/.eduorchestrate/adapters/generic/EDUORCHESTRATE.md +19 -0
- package/.eduorchestrate/adapters/hermas/manifest.json +31 -0
- package/.eduorchestrate/adapters/openclaw/SKILL.md +24 -0
- package/.eduorchestrate/mcp/manifest.json +19 -0
- package/.eduorchestrate/mcp/server.js +47 -0
- package/.kordexa/adapters/antigravity/manifest.json +31 -0
- package/.kordexa/adapters/codex/AGENTS.md +23 -0
- package/.kordexa/adapters/generic/KORDEXA.md +19 -0
- package/.kordexa/adapters/hermas/manifest.json +31 -0
- package/.kordexa/adapters/openclaw/SKILL.md +24 -0
- package/.kordexa/mcp/manifest.json +19 -0
- package/.kordexa/mcp/server.js +47 -0
- package/AGENTS.md +25 -0
- package/GEMINI.md +7 -0
- package/LICENSE +22 -0
- package/README.md +311 -2
- package/agents/eduorchestrate-agent.yaml +18 -0
- package/agents/kordexa-agent.yaml +18 -0
- package/bin/kordexa.js +8 -0
- package/package.json +38 -4
- package/skills/eduorchestrate/SKILL.md +115 -0
- package/skills/eduorchestrate/agents/openai.yaml +4 -0
- package/skills/eduorchestrate/assets/default-terminal-card.svg +1 -0
- package/skills/eduorchestrate/references/agent-contracts.md +107 -0
- package/skills/eduorchestrate/references/learning-system.md +119 -0
- package/skills/kordexa/SKILL.md +115 -0
- package/skills/kordexa/agents/openai.yaml +4 -0
- package/skills/kordexa/assets/default-terminal-card.svg +1 -0
- package/skills/kordexa/references/agent-contracts.md +107 -0
- package/skills/kordexa/references/learning-system.md +119 -0
- package/src/adapters.js +203 -0
- package/src/card-components.js +103 -0
- package/src/cli.js +505 -0
- package/src/config.js +118 -0
- package/src/courses.js +150 -0
- package/src/email.js +173 -0
- package/src/harness.js +130 -0
- package/src/planner.js +423 -0
- package/src/progress.js +93 -0
- package/src/progression-card.js +137 -0
- package/src/prompts.js +77 -0
- package/src/research.js +288 -0
- package/src/workflow.js +161 -0
- package/tests/node/eduorchestrate.test.js +558 -0
- package/tests/node/launch-ready.test.js +101 -0
- package/tests/node/safe-setup.test.js +313 -0
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# EduOrchestrate Agent Contracts
|
|
2
|
+
|
|
3
|
+
## Shared Input
|
|
4
|
+
|
|
5
|
+
All agents receive a learner profile with:
|
|
6
|
+
|
|
7
|
+
- `name`
|
|
8
|
+
- `email`
|
|
9
|
+
- `targetRole`
|
|
10
|
+
- `currentStage`
|
|
11
|
+
- `weeklyHours`
|
|
12
|
+
- `dailyEmailTime`
|
|
13
|
+
- `timezone`
|
|
14
|
+
|
|
15
|
+
Agents should also accept current `30-day-plan`, `progressLog`, and recent `researchDigests` when available.
|
|
16
|
+
|
|
17
|
+
## Harness
|
|
18
|
+
|
|
19
|
+
Input: learner profile, current plan, and run mode.
|
|
20
|
+
|
|
21
|
+
Output:
|
|
22
|
+
|
|
23
|
+
- compact load order
|
|
24
|
+
- token budget rules
|
|
25
|
+
- research command policy
|
|
26
|
+
- email preview/send policy
|
|
27
|
+
- progress/card artifact paths
|
|
28
|
+
|
|
29
|
+
Decision rule: load the harness before detailed references, call CLI programs for stateful work, and summarize artifact paths instead of pasting large files or card source.
|
|
30
|
+
|
|
31
|
+
## GoalMapper
|
|
32
|
+
|
|
33
|
+
Input: learner profile.
|
|
34
|
+
|
|
35
|
+
Output:
|
|
36
|
+
|
|
37
|
+
- normalized role key
|
|
38
|
+
- priority skill list
|
|
39
|
+
- daily load rule
|
|
40
|
+
- gap notes when current stage is below the role expectation
|
|
41
|
+
|
|
42
|
+
Decision rule: prefer the smallest skill set that can produce role-relevant artifacts in the next 30 days.
|
|
43
|
+
|
|
44
|
+
## CurriculumPlanner
|
|
45
|
+
|
|
46
|
+
Input: learner profile and GoalMapper output.
|
|
47
|
+
|
|
48
|
+
Output:
|
|
49
|
+
|
|
50
|
+
- 30 daily plan entries
|
|
51
|
+
- concept focus for each day
|
|
52
|
+
- practical task for each day
|
|
53
|
+
- proof/evidence expectation for each day
|
|
54
|
+
- next-day bridge
|
|
55
|
+
|
|
56
|
+
Decision rule: schedule less theory when weekly hours are low; keep build work present every day.
|
|
57
|
+
|
|
58
|
+
## Researcher
|
|
59
|
+
|
|
60
|
+
Input: target role, day topic, and optional seed sources.
|
|
61
|
+
|
|
62
|
+
Output:
|
|
63
|
+
|
|
64
|
+
- dated digest
|
|
65
|
+
- source list with title, URL, accessed date, and relevance
|
|
66
|
+
- recommendations that alter or confirm the current learning path
|
|
67
|
+
|
|
68
|
+
Decision rule: use official documentation, release notes, reputable educational sources, YouTube search links, and GitHub sample-code search links without inventing fetched results.
|
|
69
|
+
|
|
70
|
+
## BuildMentor
|
|
71
|
+
|
|
72
|
+
Input: target role, day topic, roadmap stage, and learner constraints.
|
|
73
|
+
|
|
74
|
+
Output:
|
|
75
|
+
|
|
76
|
+
- project framing
|
|
77
|
+
- build steps
|
|
78
|
+
- deliverables
|
|
79
|
+
- evidence checklist
|
|
80
|
+
- stretch task only if the base build is complete
|
|
81
|
+
|
|
82
|
+
Decision rule: every guide must lead to a concrete artifact that can be shown in a portfolio, interview, or review.
|
|
83
|
+
|
|
84
|
+
## FocusCoach
|
|
85
|
+
|
|
86
|
+
Input: learner profile, 30-day plan, and progress log.
|
|
87
|
+
|
|
88
|
+
Output:
|
|
89
|
+
|
|
90
|
+
- current daily focus
|
|
91
|
+
- overload warnings
|
|
92
|
+
- cut list for distracting resources or tools
|
|
93
|
+
|
|
94
|
+
Decision rule: cap each day at one topic and one artifact.
|
|
95
|
+
|
|
96
|
+
## Evaluator
|
|
97
|
+
|
|
98
|
+
Input: progress log, evidence, blocker, and current plan.
|
|
99
|
+
|
|
100
|
+
Output:
|
|
101
|
+
|
|
102
|
+
- progress summary
|
|
103
|
+
- evidence quality assessment
|
|
104
|
+
- next action
|
|
105
|
+
- plan adjustment if needed
|
|
106
|
+
|
|
107
|
+
Decision rule: do not count passive consumption as completion unless it produced notes, code, a demo, a solved problem set, or another reviewable artifact.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# EduOrchestrate Learning System
|
|
2
|
+
|
|
3
|
+
## Operating Loop
|
|
4
|
+
|
|
5
|
+
Run the learner through this loop:
|
|
6
|
+
|
|
7
|
+
1. Define the role outcome.
|
|
8
|
+
2. Identify the smallest useful skill gap.
|
|
9
|
+
3. Choose current sources when freshness matters.
|
|
10
|
+
4. Build a small artifact.
|
|
11
|
+
5. Log evidence.
|
|
12
|
+
6. Review and adjust the next day.
|
|
13
|
+
|
|
14
|
+
The system is not a motivational chatbot. It is a training orchestrator that protects learner focus and converts learning into job-role evidence.
|
|
15
|
+
|
|
16
|
+
## Harness Policy
|
|
17
|
+
|
|
18
|
+
Use `npx kordexa harness` as the first command for agent runs after initialization.
|
|
19
|
+
|
|
20
|
+
The harness keeps the skill token-conscious by:
|
|
21
|
+
|
|
22
|
+
- loading `data/eduorchestrate-harness.json` before broader docs
|
|
23
|
+
- loading only the active plan day unless the user asks for a full review
|
|
24
|
+
- calling CLI programs for research, mail, progress, and cards instead of recreating their outputs
|
|
25
|
+
- using `npx kordexa courses` for role-specific official course catalogs and newsletters
|
|
26
|
+
- keeping source digests as artifacts and summarizing only the useful entries
|
|
27
|
+
- previewing email with `send-today --dry-run` before sending unless the user explicitly asks to send
|
|
28
|
+
- treating every resumable browser or workspace agent session as a daily-mail checkpoint on resume: load harness/status, resolve today's plan day, and run `send-today` after SMTP setup, or `send-today --dry-run` when secrets or approval are missing
|
|
29
|
+
- never exposing SMTP secrets or pasting SVG/card source into chat
|
|
30
|
+
|
|
31
|
+
## 30-Day Plan Policy
|
|
32
|
+
|
|
33
|
+
A good plan has:
|
|
34
|
+
|
|
35
|
+
- role-specific skills instead of generic study topics
|
|
36
|
+
- one visible artifact or proof item per day
|
|
37
|
+
- current-technology references where useful
|
|
38
|
+
- trend-scanning entry points for current tools, models, frameworks, and practices
|
|
39
|
+
- review points based on evidence, not time spent
|
|
40
|
+
- daily email text that can be acted on immediately
|
|
41
|
+
- progress logging and weekly summaries
|
|
42
|
+
- source digests that distinguish official sources from search entry points
|
|
43
|
+
- a prebuilt skill progression card loaded from the skill package or CLI artifact
|
|
44
|
+
|
|
45
|
+
Avoid course-list plans. Courses can be sources, but the plan should be organized around capability and proof.
|
|
46
|
+
|
|
47
|
+
The learner may choose any plan length, but the minimum is always 30 days. If the learner asks for fewer days, generate 30 days. If they ask for more, extend the plan with next-skill ramp and trend-refresh days.
|
|
48
|
+
|
|
49
|
+
## Practical Build Guide Policy
|
|
50
|
+
|
|
51
|
+
Every daily guide should include:
|
|
52
|
+
|
|
53
|
+
- problem statement or role context
|
|
54
|
+
- smallest useful action
|
|
55
|
+
- setup/build task
|
|
56
|
+
- source links to research
|
|
57
|
+
- evidence checklist
|
|
58
|
+
- next-day bridge
|
|
59
|
+
|
|
60
|
+
For technical roles, evidence should normally include code, tests, logs, screenshots, demo notes, benchmark output, or a written design decision.
|
|
61
|
+
|
|
62
|
+
## Progress Policy
|
|
63
|
+
|
|
64
|
+
Progress entries should capture:
|
|
65
|
+
|
|
66
|
+
- day number
|
|
67
|
+
- what was completed
|
|
68
|
+
- evidence link or notes
|
|
69
|
+
- time spent
|
|
70
|
+
- confidence score
|
|
71
|
+
- blocker, if any
|
|
72
|
+
|
|
73
|
+
Use confidence and blockers to decide whether to advance, repeat, or narrow the next task.
|
|
74
|
+
|
|
75
|
+
## Skill Progression Card Policy
|
|
76
|
+
|
|
77
|
+
The card UI is a prebuilt program and bundled asset, not an agent-authored response. Never type, recreate, or hand-design the card in prompts.
|
|
78
|
+
|
|
79
|
+
On initialization, copy the bundled default card from `skills/eduorchestrate/assets/default-terminal-card.svg` to `data/default-terminal-card.svg`.
|
|
80
|
+
|
|
81
|
+
When learner-specific state is needed, call the prebuilt CLI program to write `data/progression-card.md`, `data/progression-card.json`, and `data/terminal-card.svg`.
|
|
82
|
+
|
|
83
|
+
The card must include:
|
|
84
|
+
|
|
85
|
+
- target role as the main heading
|
|
86
|
+
- selected skill as the second heading
|
|
87
|
+
- current learning topic
|
|
88
|
+
- completed days and total plan days
|
|
89
|
+
- GitHub-commit-style grid where `#` is complete, `>` is active, and `.` is upcoming
|
|
90
|
+
- terminal card with `npx kordexa status`, role, skill, progress, current day, next action, latest evidence, and momentum
|
|
91
|
+
- SVG terminal-card replica in `data/terminal-card.svg`
|
|
92
|
+
|
|
93
|
+
Keep the card text portable so any agent can load it into email, chat, Markdown previews, or issue comments.
|
|
94
|
+
|
|
95
|
+
Agents should load `data/default-terminal-card.svg`, `data/terminal-card.svg`, or call `npx kordexa progress-card` / `npx kordexa terminal-card`. The repo owns the compact component renderer.
|
|
96
|
+
|
|
97
|
+
## Freshness Policy
|
|
98
|
+
|
|
99
|
+
Use current research for:
|
|
100
|
+
|
|
101
|
+
- rapidly changing tools, APIs, frameworks, models, and security threats
|
|
102
|
+
- job-market expectations for a target role
|
|
103
|
+
- project implementation choices that depend on recent releases
|
|
104
|
+
- deciding whether the next skill recommendation should change after the current plan
|
|
105
|
+
|
|
106
|
+
Do not browse for stable fundamentals unless the learner asks for sources.
|
|
107
|
+
|
|
108
|
+
## Course Source Policy
|
|
109
|
+
|
|
110
|
+
Use `npx kordexa courses` to produce `data/learning-sources.json` and `data/learning-sources.md`.
|
|
111
|
+
|
|
112
|
+
Course recommendations should:
|
|
113
|
+
|
|
114
|
+
- prefer official company catalogs, docs, academies, and skill programs
|
|
115
|
+
- include free or free-discovery MNC sources when available
|
|
116
|
+
- avoid Coursera and Udemy unless the learner explicitly asks for marketplaces
|
|
117
|
+
- include newsletters or official update feeds for staying current
|
|
118
|
+
- verify current availability before saying a course is open, free, or newly offered
|
|
119
|
+
- keep email recommendations short: two course sources and two update feeds by default
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kordexa
|
|
3
|
+
description: Universal /kordexa agent skill for job-role learners. Use when an agent needs to expose or honor /kordexa, onboard a learner, ask what they are currently learning, ask which first skill they want to focus on, create an adaptive role plan with a fixed 30-day minimum, research trending technology updates with sources, send daily learning emails, recommend the next skill after the plan window, create practical build guides, track progress, load the prebuilt skill progression card, generate weekly summaries, diagnose setup, configure email secrets, and keep the learner focused on the next useful action.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Kordexa
|
|
7
|
+
|
|
8
|
+
Visible command: `/kordexa`.
|
|
9
|
+
|
|
10
|
+
If the host agent cannot register slash commands, treat `kordexa` or `use Kordexa` (or legacy `eduorchestrate`) as equivalent to `/kordexa`.
|
|
11
|
+
|
|
12
|
+
## Core Workflow
|
|
13
|
+
|
|
14
|
+
Use Kordexa to guide a learner from a target job role to focused daily execution:
|
|
15
|
+
|
|
16
|
+
1. Capture the learner profile: name, email, target role, current learning topic, first skill focus, current stage, weekly hours, requested plan length, daily email time, and timezone.
|
|
17
|
+
2. Generate the first plan with a 30-day minimum, even if the learner requests fewer days.
|
|
18
|
+
3. Load the compact harness before research, mail, progress, or review work.
|
|
19
|
+
4. Research current and trending updates only when they affect the learner's roadmap or build work.
|
|
20
|
+
5. Convert each day into a practical build action with visible proof.
|
|
21
|
+
6. Send or preview the daily plan email. For every supported agent, not only Codex, a resumable browser or workspace instance must treat resume as a daily-mail checkpoint: load the harness or status, resolve the current plan day, and run `npx kordexa send-today` after SMTP setup. If secrets or approval are missing, run `npx kordexa send-today --dry-run` and ask before sending.
|
|
22
|
+
7. Load the prebuilt skill learning card; never recreate or type card UI in the agent response.
|
|
23
|
+
8. Review progress evidence and recommend one next action.
|
|
24
|
+
9. After the plan window, recommend the next skill to learn.
|
|
25
|
+
|
|
26
|
+
Prefer practical output over long curriculum text. Keep the active plan narrow: one core topic, one build artifact, and one review loop per day.
|
|
27
|
+
|
|
28
|
+
## NPX CLI
|
|
29
|
+
|
|
30
|
+
Use the NPX CLI:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx kordexa
|
|
34
|
+
npx kordexa /kordexa
|
|
35
|
+
npx kordexa plan --role "Agentic AI and LLM Engineer"
|
|
36
|
+
npx kordexa plan --role "Agentic AI and LLM Engineer" --skill "RAG evaluation" --days 45
|
|
37
|
+
npx kordexa harness
|
|
38
|
+
npx kordexa courses
|
|
39
|
+
npx kordexa status
|
|
40
|
+
npx kordexa research --day 1
|
|
41
|
+
npx kordexa send-today --dry-run
|
|
42
|
+
npx kordexa log-progress --day 1 --completed "Built setup" --evidence "Repo link"
|
|
43
|
+
npx kordexa weekly-summary --week 1
|
|
44
|
+
npx kordexa progress-card
|
|
45
|
+
npx kordexa terminal-card
|
|
46
|
+
npx kordexa recommend-next
|
|
47
|
+
npx kordexa setup-secrets
|
|
48
|
+
npx kordexa doctor
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The CLI stores local state in `data/` by default:
|
|
52
|
+
|
|
53
|
+
- `30-day-plan.json`
|
|
54
|
+
- `kordexa-harness.json`
|
|
55
|
+
- `kordexa-harness.md`
|
|
56
|
+
- `learning-sources.json`
|
|
57
|
+
- `learning-sources.md`
|
|
58
|
+
- `research-digests/*.json`
|
|
59
|
+
- `progress-log.json`
|
|
60
|
+
- `default-terminal-card.svg`
|
|
61
|
+
- `progression-card.md`
|
|
62
|
+
- `progression-card.json`
|
|
63
|
+
- `terminal-card.svg`
|
|
64
|
+
- `weekly-summary-*.json`
|
|
65
|
+
- generated email previews and runtime outputs
|
|
66
|
+
|
|
67
|
+
Plan length can be greater than 30 days. If the learner asks for less than 30 days, still generate 30 days.
|
|
68
|
+
|
|
69
|
+
## Specialist Agents
|
|
70
|
+
|
|
71
|
+
Treat the system as a typed multi-agent workflow, even when a single model is executing it:
|
|
72
|
+
|
|
73
|
+
- `GoalMapper`: translate target role and current stage into priority skills.
|
|
74
|
+
- `CurriculumPlanner`: create milestones and a daily focus plan.
|
|
75
|
+
- `Researcher`: gather dated, sourced updates from official docs, release notes, or reputable technical sources.
|
|
76
|
+
- `BuildMentor`: turn topics into practical projects with deliverables.
|
|
77
|
+
- `FocusCoach`: limit scope and prevent resource overload.
|
|
78
|
+
- `Evaluator`: review learner evidence and adjust the next action.
|
|
79
|
+
|
|
80
|
+
For exact contracts, read `references/agent-contracts.md`. For learning-loop policy and roadmap behavior, read `references/learning-system.md`.
|
|
81
|
+
|
|
82
|
+
## Universal Agent Adapters
|
|
83
|
+
|
|
84
|
+
The setup command writes adapter files so common agents can honor `/kordexa`:
|
|
85
|
+
|
|
86
|
+
- Claude Code: `.claude/skills/kordexa/SKILL.md`
|
|
87
|
+
- Codex and generic coding agents: `AGENTS.md`
|
|
88
|
+
- Gemini: `GEMINI.md`
|
|
89
|
+
- OpenClaw: `.kordexa/adapters/openclaw/SKILL.md`
|
|
90
|
+
- Antigravity: `.kordexa/adapters/antigravity/manifest.json`
|
|
91
|
+
- Hermas: `.kordexa/adapters/hermas/manifest.json`
|
|
92
|
+
- MCP-capable agents: `.kordexa/mcp/manifest.json`
|
|
93
|
+
|
|
94
|
+
## Role Blueprints
|
|
95
|
+
|
|
96
|
+
Use built-in blueprints for:
|
|
97
|
+
|
|
98
|
+
- Agentic AI and LLM Engineer
|
|
99
|
+
- Full-Stack Developer
|
|
100
|
+
- Cybersecurity Analyst
|
|
101
|
+
- Data Scientist
|
|
102
|
+
|
|
103
|
+
For other roles, infer the closest blueprint and keep the plan artifact-driven.
|
|
104
|
+
|
|
105
|
+
## Research Rules
|
|
106
|
+
|
|
107
|
+
When the learner asks for current technology edge, browse or otherwise verify current sources if the runtime supports it. Every update must include:
|
|
108
|
+
|
|
109
|
+
- source title
|
|
110
|
+
- source URL
|
|
111
|
+
- access or publication date
|
|
112
|
+
- why it matters to the target role
|
|
113
|
+
- one concrete practice task
|
|
114
|
+
|
|
115
|
+
Do not change the roadmap because a technology is trendy. Change it only when the update improves employability, project quality, interview readiness, or safety.
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
interface:
|
|
2
|
+
display_name: "Kordexa"
|
|
3
|
+
short_description: "Slash agent learning coach"
|
|
4
|
+
default_prompt: "Use $kordexa to start my /kordexa learning plan. On resume in a browser or workspace instance, check status and send today's due mail after SMTP setup, or dry-run if secrets or approval are missing."
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="720" height="298" viewBox="0 0 720 298" role="img" aria-label="Kordexa default terminal progress card"><rect width="720" height="298" rx="14" fill="#0D1117"/><rect x="1" y="1" width="718" height="296" rx="13" fill="none" stroke="#30363D" stroke-width="2"/><rect x="1" y="1" width="718" height="46" rx="13" fill="#161B22"/><path d="M1 46H719" stroke="#30363D" stroke-width="2"/><circle cx="26" cy="24" r="6" fill="#FF5F56"/><circle cx="46" cy="24" r="6" fill="#FFBD2E"/><circle cx="66" cy="24" r="6" fill="#27C93F"/><text x="360" y="30" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="13" fill="#8B949E">kordexa-terminal</text><text x="28" y="78" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#7EE787">$ npx kordexa status</text><text x="28" y="102" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">role="choose target role"</text><text x="28" y="126" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">skill="choose first skill"</text><text x="28" y="150" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">progress="0/30 days"</text><text x="28" y="174" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">current_day="1: initialize learning path"</text><text x="28" y="198" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">next_action="run npx kordexa"</text><text x="28" y="222" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">latest_evidence="not logged yet"</text><text x="28" y="246" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">momentum="not-started"</text></svg>
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Kordexa Agent Contracts
|
|
2
|
+
|
|
3
|
+
## Shared Input
|
|
4
|
+
|
|
5
|
+
All agents receive a learner profile with:
|
|
6
|
+
|
|
7
|
+
- `name`
|
|
8
|
+
- `email`
|
|
9
|
+
- `targetRole`
|
|
10
|
+
- `currentStage`
|
|
11
|
+
- `weeklyHours`
|
|
12
|
+
- `dailyEmailTime`
|
|
13
|
+
- `timezone`
|
|
14
|
+
|
|
15
|
+
Agents should also accept current `30-day-plan`, `progressLog`, and recent `researchDigests` when available.
|
|
16
|
+
|
|
17
|
+
## Harness
|
|
18
|
+
|
|
19
|
+
Input: learner profile, current plan, and run mode.
|
|
20
|
+
|
|
21
|
+
Output:
|
|
22
|
+
|
|
23
|
+
- compact load order
|
|
24
|
+
- token budget rules
|
|
25
|
+
- research command policy
|
|
26
|
+
- email preview/send policy
|
|
27
|
+
- progress/card artifact paths
|
|
28
|
+
|
|
29
|
+
Decision rule: load the harness before detailed references, call CLI programs for stateful work, and summarize artifact paths instead of pasting large files or card source.
|
|
30
|
+
|
|
31
|
+
## GoalMapper
|
|
32
|
+
|
|
33
|
+
Input: learner profile.
|
|
34
|
+
|
|
35
|
+
Output:
|
|
36
|
+
|
|
37
|
+
- normalized role key
|
|
38
|
+
- priority skill list
|
|
39
|
+
- daily load rule
|
|
40
|
+
- gap notes when current stage is below the role expectation
|
|
41
|
+
|
|
42
|
+
Decision rule: prefer the smallest skill set that can produce role-relevant artifacts in the next 30 days.
|
|
43
|
+
|
|
44
|
+
## CurriculumPlanner
|
|
45
|
+
|
|
46
|
+
Input: learner profile and GoalMapper output.
|
|
47
|
+
|
|
48
|
+
Output:
|
|
49
|
+
|
|
50
|
+
- 30 daily plan entries
|
|
51
|
+
- concept focus for each day
|
|
52
|
+
- practical task for each day
|
|
53
|
+
- proof/evidence expectation for each day
|
|
54
|
+
- next-day bridge
|
|
55
|
+
|
|
56
|
+
Decision rule: schedule less theory when weekly hours are low; keep build work present every day.
|
|
57
|
+
|
|
58
|
+
## Researcher
|
|
59
|
+
|
|
60
|
+
Input: target role, day topic, and optional seed sources.
|
|
61
|
+
|
|
62
|
+
Output:
|
|
63
|
+
|
|
64
|
+
- dated digest
|
|
65
|
+
- source list with title, URL, accessed date, and relevance
|
|
66
|
+
- recommendations that alter or confirm the current learning path
|
|
67
|
+
|
|
68
|
+
Decision rule: use official documentation, release notes, reputable educational sources, YouTube search links, and GitHub sample-code search links without inventing fetched results.
|
|
69
|
+
|
|
70
|
+
## BuildMentor
|
|
71
|
+
|
|
72
|
+
Input: target role, day topic, roadmap stage, and learner constraints.
|
|
73
|
+
|
|
74
|
+
Output:
|
|
75
|
+
|
|
76
|
+
- project framing
|
|
77
|
+
- build steps
|
|
78
|
+
- deliverables
|
|
79
|
+
- evidence checklist
|
|
80
|
+
- stretch task only if the base build is complete
|
|
81
|
+
|
|
82
|
+
Decision rule: every guide must lead to a concrete artifact that can be shown in a portfolio, interview, or review.
|
|
83
|
+
|
|
84
|
+
## FocusCoach
|
|
85
|
+
|
|
86
|
+
Input: learner profile, 30-day plan, and progress log.
|
|
87
|
+
|
|
88
|
+
Output:
|
|
89
|
+
|
|
90
|
+
- current daily focus
|
|
91
|
+
- overload warnings
|
|
92
|
+
- cut list for distracting resources or tools
|
|
93
|
+
|
|
94
|
+
Decision rule: cap each day at one topic and one artifact.
|
|
95
|
+
|
|
96
|
+
## Evaluator
|
|
97
|
+
|
|
98
|
+
Input: progress log, evidence, blocker, and current plan.
|
|
99
|
+
|
|
100
|
+
Output:
|
|
101
|
+
|
|
102
|
+
- progress summary
|
|
103
|
+
- evidence quality assessment
|
|
104
|
+
- next action
|
|
105
|
+
- plan adjustment if needed
|
|
106
|
+
|
|
107
|
+
Decision rule: do not count passive consumption as completion unless it produced notes, code, a demo, a solved problem set, or another reviewable artifact.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# Kordexa Learning System
|
|
2
|
+
|
|
3
|
+
## Operating Loop
|
|
4
|
+
|
|
5
|
+
Run the learner through this loop:
|
|
6
|
+
|
|
7
|
+
1. Define the role outcome.
|
|
8
|
+
2. Identify the smallest useful skill gap.
|
|
9
|
+
3. Choose current sources when freshness matters.
|
|
10
|
+
4. Build a small artifact.
|
|
11
|
+
5. Log evidence.
|
|
12
|
+
6. Review and adjust the next day.
|
|
13
|
+
|
|
14
|
+
The system is not a motivational chatbot. It is a training orchestrator that protects learner focus and converts learning into job-role evidence.
|
|
15
|
+
|
|
16
|
+
## Harness Policy
|
|
17
|
+
|
|
18
|
+
Use `npx kordexa harness` as the first command for agent runs after initialization.
|
|
19
|
+
|
|
20
|
+
The harness keeps the skill token-conscious by:
|
|
21
|
+
|
|
22
|
+
- loading `data/kordexa-harness.json` before broader docs
|
|
23
|
+
- loading only the active plan day unless the user asks for a full review
|
|
24
|
+
- calling CLI programs for research, mail, progress, and cards instead of recreating their outputs
|
|
25
|
+
- using `npx kordexa courses` for role-specific official course catalogs and newsletters
|
|
26
|
+
- keeping source digests as artifacts and summarizing only the useful entries
|
|
27
|
+
- previewing email with `send-today --dry-run` before sending unless the user explicitly asks to send
|
|
28
|
+
- treating every resumable browser or workspace agent session as a daily-mail checkpoint on resume: load harness/status, resolve today's plan day, and run `send-today` after SMTP setup, or `send-today --dry-run` when secrets or approval are missing
|
|
29
|
+
- never exposing SMTP secrets or pasting SVG/card source into chat
|
|
30
|
+
|
|
31
|
+
## 30-Day Plan Policy
|
|
32
|
+
|
|
33
|
+
A good plan has:
|
|
34
|
+
|
|
35
|
+
- role-specific skills instead of generic study topics
|
|
36
|
+
- one visible artifact or proof item per day
|
|
37
|
+
- current-technology references where useful
|
|
38
|
+
- trend-scanning entry points for current tools, models, frameworks, and practices
|
|
39
|
+
- review points based on evidence, not time spent
|
|
40
|
+
- daily email text that can be acted on immediately
|
|
41
|
+
- progress logging and weekly summaries
|
|
42
|
+
- source digests that distinguish official sources from search entry points
|
|
43
|
+
- a prebuilt skill progression card loaded from the skill package or CLI artifact
|
|
44
|
+
|
|
45
|
+
Avoid course-list plans. Courses can be sources, but the plan should be organized around capability and proof.
|
|
46
|
+
|
|
47
|
+
The learner may choose any plan length, but the minimum is always 30 days. If the learner asks for fewer days, generate 30 days. If they ask for more, extend the plan with next-skill ramp and trend-refresh days.
|
|
48
|
+
|
|
49
|
+
## Practical Build Guide Policy
|
|
50
|
+
|
|
51
|
+
Every daily guide should include:
|
|
52
|
+
|
|
53
|
+
- problem statement or role context
|
|
54
|
+
- smallest useful action
|
|
55
|
+
- setup/build task
|
|
56
|
+
- source links to research
|
|
57
|
+
- evidence checklist
|
|
58
|
+
- next-day bridge
|
|
59
|
+
|
|
60
|
+
For technical roles, evidence should normally include code, tests, logs, screenshots, demo notes, benchmark output, or a written design decision.
|
|
61
|
+
|
|
62
|
+
## Progress Policy
|
|
63
|
+
|
|
64
|
+
Progress entries should capture:
|
|
65
|
+
|
|
66
|
+
- day number
|
|
67
|
+
- what was completed
|
|
68
|
+
- evidence link or notes
|
|
69
|
+
- time spent
|
|
70
|
+
- confidence score
|
|
71
|
+
- blocker, if any
|
|
72
|
+
|
|
73
|
+
Use confidence and blockers to decide whether to advance, repeat, or narrow the next task.
|
|
74
|
+
|
|
75
|
+
## Skill Progression Card Policy
|
|
76
|
+
|
|
77
|
+
The card UI is a prebuilt program and bundled asset, not an agent-authored response. Never type, recreate, or hand-design the card in prompts.
|
|
78
|
+
|
|
79
|
+
On initialization, copy the bundled default card from `skills/kordexa/assets/default-terminal-card.svg` to `data/default-terminal-card.svg`.
|
|
80
|
+
|
|
81
|
+
When learner-specific state is needed, call the prebuilt CLI program to write `data/progression-card.md`, `data/progression-card.json`, and `data/terminal-card.svg`.
|
|
82
|
+
|
|
83
|
+
The card must include:
|
|
84
|
+
|
|
85
|
+
- target role as the main heading
|
|
86
|
+
- selected skill as the second heading
|
|
87
|
+
- current learning topic
|
|
88
|
+
- completed days and total plan days
|
|
89
|
+
- GitHub-commit-style grid where `#` is complete, `>` is active, and `.` is upcoming
|
|
90
|
+
- terminal card with `npx kordexa status`, role, skill, progress, current day, next action, latest evidence, and momentum
|
|
91
|
+
- SVG terminal-card replica in `data/terminal-card.svg`
|
|
92
|
+
|
|
93
|
+
Keep the card text portable so any agent can load it into email, chat, Markdown previews, or issue comments.
|
|
94
|
+
|
|
95
|
+
Agents should load `data/default-terminal-card.svg`, `data/terminal-card.svg`, or call `npx kordexa progress-card` / `npx kordexa terminal-card`. The repo owns the compact component renderer.
|
|
96
|
+
|
|
97
|
+
## Freshness Policy
|
|
98
|
+
|
|
99
|
+
Use current research for:
|
|
100
|
+
|
|
101
|
+
- rapidly changing tools, APIs, frameworks, models, and security threats
|
|
102
|
+
- job-market expectations for a target role
|
|
103
|
+
- project implementation choices that depend on recent releases
|
|
104
|
+
- deciding whether the next skill recommendation should change after the current plan
|
|
105
|
+
|
|
106
|
+
Do not browse for stable fundamentals unless the learner asks for sources.
|
|
107
|
+
|
|
108
|
+
## Course Source Policy
|
|
109
|
+
|
|
110
|
+
Use `npx kordexa courses` to produce `data/learning-sources.json` and `data/learning-sources.md`.
|
|
111
|
+
|
|
112
|
+
Course recommendations should:
|
|
113
|
+
|
|
114
|
+
- prefer official company catalogs, docs, academies, and skill programs
|
|
115
|
+
- include free or free-discovery MNC sources when available
|
|
116
|
+
- avoid Coursera and Udemy unless the learner explicitly asks for marketplaces
|
|
117
|
+
- include newsletters or official update feeds for staying current
|
|
118
|
+
- verify current availability before saying a course is open, free, or newly offered
|
|
119
|
+
- keep email recommendations short: two course sources and two update feeds by default
|