tech-debt: refactor loader.ts to remove biome-ignore complexity suppressions

[hqhq1025]

Background

On 2026-04-19, two // biome-ignore lint/complexity/noExcessiveCognitiveComplexity suppressions were added to packages/core/src/skills/loader.ts to unblock the PR pipeline:

• loadSkillsFromDir (line ~192, complexity score 19, max 15)
• parseMapping (line ~118, complexity score 23, max 15)

The suppressions were a stopgap to unblock husky pre-push (which runs pnpm lint). Multiple agents had to bypass hooks or push from temp worktrees on the same day because of these warnings.

Why this matters

The suppressions hide growing complexity. New conditionals added to either function will silently push complexity even higher while lint stays green.

Suggested refactors

loadSkillsFromDir: split into loadSingleSkill(dir, file, source) plus a top-level that does readdir + Promise.all.

parseMapping: rewrite as token + state machine, or swap in a tiny YAML subset parser (must respect ≤80MB install budget — js-yaml is too large; consider yaml-mini or hand-rolled).

Acceptance

• Both biome-ignore lines removed
• pnpm lint passes with no complexity warnings on loader.ts
• All existing skill-loader tests pass; add tests for any new helpers
• No new deps >50KB without justification

Trigger

Pick up when next touching skills loader (e.g., when PR #86 starter library is unblocked, or when adding a new skill source).

[github-actions]

Thanks for reporting this tech-debt item and for the clear acceptance criteria.

I checked the current repository state in this checkout: parseMapping and loadSkillsFromDir are still relatively large functions, but I do not see // biome-ignore lint/complexity/noExcessiveCognitiveComplexity in packages/core/src/skills/loader.ts at the moment.

Relevant code:

• packages/core/src/skills/loader.ts:118 — parseMapping(...) implementation
• packages/core/src/skills/loader.ts:192 — loadSkillsFromDir(...) implementation
• packages/core/src/skills/loader.test.ts:56 — tests for loadSkillsFromDir()
• packages/core/src/skills/loader.test.ts:193 — tests for loadAllSkills() merge/override behavior
• README.md:108 — roadmap section (project is still evolving)

Given Open CoDesign is still pre-alpha, some roadmap and quality-hardening work is tracked but not fully completed yet. Keeping this issue open as a refactor target for the next skills-loader touchpoint is reasonable.

---

open-codesign Bot