Implement skill loader and resolver for agent context (CS-10478)

[habdelra]

Depends on #4229 — that PR must be reviewed and merged first. This branch is based on cs-10476-define-factoryagent-interface-and-openrouter-integration-v2.

Summary

• DefaultSkillResolver maps ticket context → skill names using keyword matching. Always loads boxel-development + boxel-file-structure; conditionally adds ember-best-practices (for .gts/component work), software-factory-operations (for delivery workflow), and CLI skills (boxel-sync, boxel-restore, etc.) based on ticket content. KnowledgeArticle tags can also specify additional skills.
• SkillLoader reads SKILL.md + references/ or rules/+AGENTS.md from disk with multi-directory search (package-local .agents/skills/ first, then monorepo root for shared skills like ember-best-practices). Caches for the factory run duration.
• enforceSkillBudget() sorts skills by priority, drops lowest-priority skills when a token budget is exceeded, and filters boxel-development references by ticket keyword relevance.
• Smoke script (pnpm factory:skill-smoke) for quick CLI verification — no servers or API keys needed.
• 38 QUnit tests covering resolution, loading, caching, budget enforcement, fallback directories, and re-resolution across tickets.

Files

File	Purpose
scripts/lib/factory-skill-loader.ts	Core implementation (SkillResolver, SkillLoader, budget enforcement)
scripts/factory-skill-smoke.ts	CLI smoke script
tests/factory-skill-loader.test.ts	38 QUnit unit tests
tests/index.ts	Register test file
package.json	Add factory:skill-smoke script

Try it out

From packages/software-factory/, run:

1. Unit tests (38 tests)

pnpm test:node

You should see all tests pass, including the new factory-skill-loader tests:

ok 63 factory-skill-loader > DefaultSkillResolver > always includes boxel-development and boxel-file-structure
ok 64 factory-skill-loader > DefaultSkillResolver > includes ember-best-practices when ticket mentions .gts
...
ok 100 factory-skill-loader > re-resolution on new ticket > cache can be cleared between tickets for fresh loading
1..116
# pass 116
# fail 0

2. Smoke test — basic skill discovery

pnpm factory:skill-smoke

Expected output — resolves skills for 4 sample tickets, then lists all 10 discoverable skills:

=== Skill Loader & Resolver Smoke Test ===

--- Generic card work (base case) ---
  Ticket: Create a contact card
  Resolved skills: [boxel-development, boxel-file-structure]
  Loaded: 2/2 skills
    - boxel-development: ~24036 tokens + 19 reference(s)
    - boxel-file-structure: ~1964 tokens

--- .gts component work (triggers ember-best-practices) ---
  Ticket: Build a dashboard component
  Resolved skills: [boxel-development, boxel-file-structure, ember-best-practices]
  Loaded: 3/3 skills
    - boxel-development: ~24036 tokens + 19 reference(s)
    - boxel-file-structure: ~1964 tokens
    - ember-best-practices: ~60336 tokens + 1 reference(s)

...

--- All discoverable skills ---
  boxel-development: ~24036 tokens (19 refs)
  boxel-file-structure: ~1964 tokens
  ember-best-practices: ~60336 tokens (1 refs)
  software-factory-operations: ~787 tokens
  boxel-sync: ~439 tokens
  boxel-track: ~787 tokens
  boxel-watch: ~488 tokens
  boxel-restore: ~523 tokens
  boxel-repair: ~415 tokens
  boxel-setup: ~615 tokens
  Total: ~90390 tokens across 10 skills

Smoke test passed.

3. Smoke test — with token budget

pnpm factory:skill-smoke --max-tokens 30000

Same output as above, but each ticket section now shows budget enforcement. Notice ember-best-practices (~60k tokens) gets dropped when it won't fit:

--- .gts component work (triggers ember-best-practices) ---
  ...
  Budget (30000 tokens): 2/3 skills kept (8310/86336 tokens)
  Dropped: [ember-best-practices]

4. Smoke test — custom ticket text

pnpm factory:skill-smoke --ticket-text "Create a .gts component with styling"

Resolves skills for your custom ticket description instead of the built-in samples.

Test plan

• Unit tests for skill resolution with different ticket types
• Unit tests for skill loading (SKILL.md, references/, rules/ patterns)
• Test context budget enforcement (drop low-priority skills when over limit)
• Test caching behavior (loaded once, reused across iterations)
• Test re-resolution when advancing to a new ticket
• Test fallback directory loading (monorepo root for ember-best-practices)
• Smoke script verifies end-to-end against real skill files on disk

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a9a3294661

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds the “skills” discovery pipeline for the software-factory agent context: resolving which skills apply to a ticket, loading their on-disk content (including references / compiled rules), and enforcing a token budget so the agent prompt stays bounded.

Changes:

• Introduces DefaultSkillResolver, SkillLoader, token estimation, and enforceSkillBudget() in a new library module.
• Adds a CLI smoke script (factory:skill-smoke) to validate resolver/loader behavior without servers or API keys.
• Adds comprehensive QUnit coverage and wires the new test module into the existing node test index.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/software-factory/scripts/lib/factory-skill-loader.ts	Core skill resolution/loading logic, token estimation, and budget enforcement.
packages/software-factory/scripts/factory-skill-smoke.ts	CLI smoke test for end-to-end skill discovery/loading and budget behavior.
packages/software-factory/tests/factory-skill-loader.test.ts	New unit tests covering resolution, loading, caching, fallback dirs, and budgeting.
packages/software-factory/tests/index.ts	Registers the new test module.
packages/software-factory/package.json	Adds factory:skill-smoke script.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.