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.
Files changed (64) hide show
  1. package/.claude/commands/eduorchestrate-card.md +5 -0
  2. package/.claude/commands/eduorchestrate-log.md +6 -0
  3. package/.claude/commands/eduorchestrate-next.md +5 -0
  4. package/.claude/commands/eduorchestrate-research.md +6 -0
  5. package/.claude/commands/eduorchestrate-send.md +5 -0
  6. package/.claude/commands/eduorchestrate-status.md +5 -0
  7. package/.claude/commands/eduorchestrate-weekly.md +6 -0
  8. package/.claude/commands/kordexa-card.md +5 -0
  9. package/.claude/commands/kordexa-log.md +6 -0
  10. package/.claude/commands/kordexa-next.md +5 -0
  11. package/.claude/commands/kordexa-research.md +6 -0
  12. package/.claude/commands/kordexa-send.md +5 -0
  13. package/.claude/commands/kordexa-status.md +5 -0
  14. package/.claude/commands/kordexa-weekly.md +6 -0
  15. package/.claude/skills/eduorchestrate/SKILL.md +24 -0
  16. package/.claude/skills/kordexa/SKILL.md +24 -0
  17. package/.eduorchestrate/adapters/antigravity/manifest.json +31 -0
  18. package/.eduorchestrate/adapters/codex/AGENTS.md +23 -0
  19. package/.eduorchestrate/adapters/generic/EDUORCHESTRATE.md +19 -0
  20. package/.eduorchestrate/adapters/hermas/manifest.json +31 -0
  21. package/.eduorchestrate/adapters/openclaw/SKILL.md +24 -0
  22. package/.eduorchestrate/mcp/manifest.json +19 -0
  23. package/.eduorchestrate/mcp/server.js +47 -0
  24. package/.kordexa/adapters/antigravity/manifest.json +31 -0
  25. package/.kordexa/adapters/codex/AGENTS.md +23 -0
  26. package/.kordexa/adapters/generic/KORDEXA.md +19 -0
  27. package/.kordexa/adapters/hermas/manifest.json +31 -0
  28. package/.kordexa/adapters/openclaw/SKILL.md +24 -0
  29. package/.kordexa/mcp/manifest.json +19 -0
  30. package/.kordexa/mcp/server.js +47 -0
  31. package/AGENTS.md +25 -0
  32. package/GEMINI.md +7 -0
  33. package/LICENSE +22 -0
  34. package/README.md +311 -2
  35. package/agents/eduorchestrate-agent.yaml +18 -0
  36. package/agents/kordexa-agent.yaml +18 -0
  37. package/bin/kordexa.js +8 -0
  38. package/package.json +38 -4
  39. package/skills/eduorchestrate/SKILL.md +115 -0
  40. package/skills/eduorchestrate/agents/openai.yaml +4 -0
  41. package/skills/eduorchestrate/assets/default-terminal-card.svg +1 -0
  42. package/skills/eduorchestrate/references/agent-contracts.md +107 -0
  43. package/skills/eduorchestrate/references/learning-system.md +119 -0
  44. package/skills/kordexa/SKILL.md +115 -0
  45. package/skills/kordexa/agents/openai.yaml +4 -0
  46. package/skills/kordexa/assets/default-terminal-card.svg +1 -0
  47. package/skills/kordexa/references/agent-contracts.md +107 -0
  48. package/skills/kordexa/references/learning-system.md +119 -0
  49. package/src/adapters.js +203 -0
  50. package/src/card-components.js +103 -0
  51. package/src/cli.js +505 -0
  52. package/src/config.js +118 -0
  53. package/src/courses.js +150 -0
  54. package/src/email.js +173 -0
  55. package/src/harness.js +130 -0
  56. package/src/planner.js +423 -0
  57. package/src/progress.js +93 -0
  58. package/src/progression-card.js +137 -0
  59. package/src/prompts.js +77 -0
  60. package/src/research.js +288 -0
  61. package/src/workflow.js +161 -0
  62. package/tests/node/eduorchestrate.test.js +558 -0
  63. package/tests/node/launch-ready.test.js +101 -0
  64. 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=&quot;choose target role&quot;</text><text x="28" y="126" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">skill=&quot;choose first skill&quot;</text><text x="28" y="150" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">progress=&quot;0/30 days&quot;</text><text x="28" y="174" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">current_day=&quot;1: initialize learning path&quot;</text><text x="28" y="198" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">next_action=&quot;run npx kordexa&quot;</text><text x="28" y="222" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">latest_evidence=&quot;not logged yet&quot;</text><text x="28" y="246" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" font-size="15" fill="#C9D1D9">momentum=&quot;not-started&quot;</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