agent-skillboard 0.1.2 → 0.2.2

package/src/workspace.mjs

@@ -1,9 +1,12 @@
 import { readdir, readFile, realpath, stat } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import YAML from "yaml";
 import {
   readBoolean,
+  readOptionalRecord,
   readOptionalString,
+  readRequiredString,
   readString,
   readStringList,
   requireRecord
@@ -20,40 +23,106 @@ import { normalizeSkillPath } from "./skill-paths.mjs";
 export async function loadWorkspace(options) {
   const configText = await readFile(options.configPath, "utf8");
   const parsed = YAML.parse(configText);
-  const config = requireRecord(parsed, "config root");
-  const version = parseVersion(config.version);
-  const skills = parseSkills(config.skills);
-  return {
-    version,
-    defaults: parseDefaults(config.defaults),
-    installedSkills: await discoverInstalledSkills(options.skillsRoot, skills),
-    skills,
-    capabilities: parseCapabilities(config.capabilities),
-    harnesses: parseHarnesses(config.harnesses),
-    installUnits: parseInstallUnits(config.install_units),
-    workflows: parseWorkflows(config.workflows)
-  };
-}
-
-async function discoverInstalledSkills(skillsRoot, declaredSkills) {
-  if (skillsRoot === undefined) {
-    return [];
-  }
-  const skillFiles = await findSkillFiles(skillsRoot);
-  const installed = [];
-  for (const file of skillFiles) {
-    const frontmatter = parseSkillFrontmatter(await readFile(file, "utf8"));
-    const path = relative(skillsRoot, file).replaceAll("\\", "/").replace(/\/SKILL\.md$/, "");
-    const declared = declaredSkills.find((skill) => skill.path === path);
-    installed.push({
-      id: declared?.id ?? frontmatter.name ?? path,
-      name: frontmatter.name,
-      description: frontmatter.description,
-      path
-    });
-  }
-  return installed.sort((left, right) => left.path.localeCompare(right.path));
-}
+  const config = requireRecord(parsed, "config root");
+  const version = parseVersion(config.version);
+  const skills = parseSkills(config.skills);
+  const installUnits = parseInstallUnits(config.install_units);
+  return {
+    version,
+    defaults: parseDefaults(config.defaults),
+    installedSkills: await discoverInstalledSkills(options.skillsRoot, skills, {
+      configPath: options.configPath,
+      env: options.env ?? process.env,
+      home: options.home,
+      installUnits
+    }),
+    skills,
+    capabilities: parseCapabilities(config.capabilities),
+    harnesses: parseHarnesses(config.harnesses),
+    installUnits,
+    workflows: parseWorkflows(config.workflows)
+  };
+}
+
+async function discoverInstalledSkills(skillsRoot, declaredSkills, options = {}) {
+  const installed = [];
+  const installedKeys = new Set();
+  if (skillsRoot !== undefined) {
+    const skillFiles = await findSkillFiles(skillsRoot);
+    for (const file of skillFiles) {
+      const frontmatter = parseSkillFrontmatter(await readFile(file, "utf8"));
+      const path = relative(skillsRoot, file).replaceAll("\\", "/").replace(/\/SKILL\.md$/, "");
+      const declared = declaredSkills.find((skill) => skill.path === path);
+      appendInstalledSkill(installed, installedKeys, {
+        id: declared?.id ?? frontmatter.name ?? path,
+        name: frontmatter.name,
+        description: frontmatter.description,
+        path
+      });
+    }
+  }
+  await appendInstallUnitSkillMetadata(installed, installedKeys, declaredSkills, options);
+  return installed.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+async function appendInstallUnitSkillMetadata(installed, installedKeys, declaredSkills, options) {
+  const units = new Map((options.installUnits ?? []).map((unit) => [unit.id, unit]));
+  for (const skill of declaredSkills) {
+    if (installedKeys.has(skill.id) || installedKeys.has(skill.path)) {
+      continue;
+    }
+    const unit = units.get(skill.ownerInstallUnit);
+    const root = resolveStoredPath(unit?.cachePath, options);
+    if (root === undefined) {
+      continue;
+    }
+    const frontmatter = await readOptionalSkillFrontmatter(join(root, skill.path, "SKILL.md"));
+    if (frontmatter === null) {
+      continue;
+    }
+    appendInstalledSkill(installed, installedKeys, {
+      id: skill.id,
+      name: frontmatter.name,
+      description: frontmatter.description,
+      path: skill.path
+    });
+  }
+}
+
+async function readOptionalSkillFrontmatter(file) {
+  const text = await readFile(file, "utf8").catch(() => null);
+  if (text === null) {
+    return null;
+  }
+  try {
+    return parseSkillFrontmatter(text);
+  } catch {
+    return null;
+  }
+}
+
+function appendInstalledSkill(installed, installedKeys, skill) {
+  installed.push(skill);
+  installedKeys.add(skill.id);
+  installedKeys.add(skill.path);
+}
+
+function resolveStoredPath(value, options) {
+  if (value === undefined || value.trim() === "") {
+    return undefined;
+  }
+  const home = options.home ?? options.env?.HOME ?? options.env?.USERPROFILE ?? homedir();
+  if (value === "~") {
+    return home;
+  }
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return join(home, value.slice(2));
+  }
+  if (isAbsolute(value)) {
+    return value;
+  }
+  return resolve(dirname(options.configPath ?? "."), value);
+}
 
 async function findSkillFiles(root, seen = new Set()) {
   const files = [];
@@ -144,14 +213,43 @@ function parseSkills(value) {
       invocation,
       exposure,
       category: readString(skill, "category", "uncategorized"),
-      canonicalFor: readStringList(skill, "canonical_for"),
-      conflictsWith: readStringList(skill, "conflicts_with"),
-      replacedBy: readOptionalString(skill, "replaced_by"),
-      ownerInstallUnit: readOptionalString(skill, "owner_install_unit")
-    };
-  });
-}
-
+      canonicalFor: readStringList(skill, "canonical_for"),
+      conflictsWith: readStringList(skill, "conflicts_with"),
+      replacedBy: readOptionalString(skill, "replaced_by"),
+      ownerInstallUnit: readOptionalString(skill, "owner_install_unit"),
+      variant: parseSkillVariant(skill, `skills.${id}.variant`)
+    };
+  });
+}
+
+function parseSkillVariant(skill, label) {
+  const raw = readOptionalRecord(skill, "variant", label);
+  if (raw === undefined) {
+    return null;
+  }
+  const approved = readOptionalRecord(raw, "approved", `${label}.approved`);
+  return {
+    of: readRequiredString(raw, "of", `${label}.of`),
+    adaptedFor: readOptionalString(raw, "adapted_for") ?? null,
+    capability: readRequiredString(raw, "capability", `${label}.capability`),
+    workflow: readRequiredString(raw, "workflow", `${label}.workflow`),
+    status: readRequiredString(raw, "status", `${label}.status`),
+    base: parseVariantCheckpoint(raw, "base", `${label}.base`),
+    ...(approved === undefined ? {} : { approved: parseVariantCheckpoint(raw, "approved", `${label}.approved`) })
+  };
+}
+
+function parseVariantCheckpoint(raw, key, label) {
+  const checkpoint = readOptionalRecord(raw, key, label);
+  if (checkpoint === undefined) {
+    throw new Error(`${label} must be a mapping`);
+  }
+  return {
+    contentDigest: readRequiredString(checkpoint, "content_digest", `${label}.content_digest`),
+    snapshot: readRequiredString(checkpoint, "snapshot", `${label}.snapshot`)
+  };
+}
+
 function parseCapabilities(value) {
   const raw = requireRecord(value ?? {}, "capabilities");
   return Object.entries(raw).map(([name, entry]) => {

package/tsconfig.lsp.json

@@ -11,5 +11,5 @@
     "strict": false,
     "noImplicitAny": false
   },
-  "include": ["bin/**/*.mjs", "src/**/*.mjs", "test/**/*.mjs"]
+  "include": ["bin/**/*.mjs", "src/**/*.mjs", "test/**/*.mjs", ".github/scripts/**/*.mjs"]
 }

package/docs/plans/20260625-080025-skillboard-mvp-review.md

@@ -1,189 +0,0 @@
-# skillboard-mvp-review
-
-- Skill: tdd-work-continuity
-- Agent: hermes
-- Created: 2026-06-25T08:00:25Z
-- Updated: 2026-06-25T10:05:00Z
-- Workdir: /home/nyxxir/skillboard
-- Status: completed
-
-## Goal
-
-SkillBoard(`skill-control-plane`)의 MVP 기능과 낶부 도메인 설계를 검토하고, **처음 사용자가 skill을 가져다 붙이고 이용 및 삭제하는 불편을 해소하는 방향인지**, **도메인 설계가 적합하고 확장 가능한지**를 평가한다. 이전 대화에서 제안한 4.1~4.3 UX 개선 항목도 포함된 실행 계획을 문서화한다.
-
-## Context
-
-- Repo: `/home/nyxxir/skillboard`
-- Relevant files:
-  - `src/cli.mjs` — CLI 라우터
-  - `src/control.mjs` — skill/workflow/harness/capability CRUD, `can-use`, `guard`, trust/source 분류
-  - `src/domain/rules/*.mjs` — 정책 규칙 엔진
-  - `src/workspace.mjs` — config 파싱, `SKILL.md` frontmatter 파싱
-  - `src/agent-inventory.mjs` — 설치된 agent skill 자동 스캔/병합
-  - `src/brief-cli.mjs`, `src/brief-renderer.mjs`, `src/advisor.mjs` — AI/사용자 브리핑
-  - `src/impact.mjs`, `src/reconcile.mjs` — 영향도/재조정 분석
-  - `src/init.mjs`, `src/uninstall.mjs` — 생명주기
-- Constraints:
-  - MVP 단계, npm publish 전 (`version: 0.1.0`)
-  - Node.js >= 20, ESM, yaml 의존성 하나
-  - cross-platform CI (ubuntu/macOS/windows × node 20/22)
-
-## Findings Summary
-
-### 1. 도메인 설계: 적합하고 확장 가능함 (Score: 8/10)
-
-**핵심 엔티티 5개**가 skill 생태계의 실제 관심사를 잘 반영한다.
-
-| Entity | 역할 | 적합성 |
-|--------|------|--------|
-| `skills` | 선언된 스킬의 상태/호출방식/노출범위 | ✅ 적절. status/invocation/exposure 3중 분리로 정책 표현력 높음 |
-| `capabilities` | 역할 기반 스킬 추상화 | ✅ 적절. canonical/alternatives/default_policy로 교체/대안 추천 가능 |
-| `workflows` | 스킬이 활성화되는 맥락 | ✅ 적절. active_skills/blocked_skills/required_capabilities로 명시적 제어 |
-| `harnesses` | runtime/command 제공자 추적 | ✅ 적절. harness 제거 시 workflow 영향도 파악 가능 |
-| `install_units` | plugin/marketplace/harness 등의 부모 단위 | ✅ 매우 적절. skill 평탄화 문제 해결 |
-
-**확장 가능성**
-- `INSTALL_UNIT_KIND_VALUES`에 `skill`, `plugin`, `marketplace`, `harness`, `mcp-server`, `hook`, `agent`, `lsp`, `custom`을 두어 새로운 runtime primitive 추가가 용이함.
-- `source_classes.mjs`의 우선순위/분류 함수가 데이터 기반으로 되어 있어 새 source class 추가가 쉬움.
-- `source profile` 어댑터 모델이 하드코딩을 피하고 데이터 주도 import를 지향함.
-
-**위험 요소**
-- `src/control.mjs`가 1000줄에 달해 단일 책임 위반. `can-use`, CRUD, trust/source, YAML 쓰기, hook 설치 등이 한 파일에 있어 장기 유지보수 부담.
-- `status` 값이 14개로 많고, `status`와 `invocation` 간의 유효 조합 규칙이 복잡(`SKILL-STATUS-001`). 새로운 상태 추가 시 규칙 행렬이 기하급수적으로 늘어날 수 있음.
-- `capability`가 workflow-scoped `required_capabilities`와 global `capabilities`로 이중 정의됨. 의도는 명확하지만 사용자 입장에서 학습 곡선이 있음.
-
-### 2. 사용자 불편 해소 vs 가중
-
-#### 해소하는 설계
-
-| 기능 | 불편 해소 메커니즘 |
-|------|------------------|
-| `init` 시 자동 스캔 + `active-manual` 연결 | 기존 수동 스킬을 따로 등록하지 않아도 `can-use`/`guard`로 계속 사용 가능 |
-| `deny-by-default` + quarantine | 설치만으로 AI가 스킬을 부르는 것을 원천 차단 |
-| `impact disable` | 스킬 제거 전 영향받는 workflow/capability를 사전에 노출 |
-| 대부분의 mutating 명령에 `--dry-run` | 실수로 config를 망치는 위험 감소 |
-| `brief --json` | 에이전트가 정책을 직접 해석하지 않고 control plane에 질의 |
-| `uninstall`이 사용자 파일 보존 | 도구를 빼도 skill 파일과 사용자 config는 남음 |
-
-#### 가중할 수 있는 설계
-
-| 지점 | 불편 가능성 | 심각도 |
-|------|------------|--------|
-| 매번 `--config skillboard.config.yaml --skills skills` 필요 | 일상 명령이 번거로움 | 중간 |
-| `SKILL.md` frontmatter 누락 시 메시지가 모호함 | 처음 사용자가 문서를 찾아야 함 | 높음 |
-| `doctor` 출력이 길고 `--summary` 부재 | 매일 보기에 피로함 | 중간 |
-| `add workflow` 시 `--harness`를 명시해야 함 | harness 개념을 모르는 사용자에게 진입 장벽 | 중간 |
-| `status`/`invocation`/`exposure`/`trust_level` 용어가 많음 | 정책 도구이므로 불가피하지만, 온볭딩 문서가 중요 | 중간 |
-| `init` 후 생성되는 config가 수십 개 스킬로 즉시 커짐 | 실제로 설치된 게 많으면 압도적 | 낮음~중간 |
-
-**종합 판단**: 보안/통제를 얻는 대가로 적정 수준의 복잡성을 요구한다. 다만 **처음 사용자의 첫 5분**을 더 부드럽게 만들면 Adoption이 크게 올라갈 것이다.
-
-### 3. MVP 기능 검증 결과
-
-| 기능 | 상태 | 비고 |
-|------|------|------|
-| `init` | ✅ 정상 | bridge 파일, config, 디렉토리 생성, 자동 스캔 |
-| `doctor`/`status` | ✅ 정상 | safe-mode, strict 모드, JSON 출력 |
-| `brief` | ✅ 정상 | text/JSON, action cards, unknown workflow 처리 |
-| `add skill/workflow/harness` | ✅ 정상 | dry-run, 자동 status 승격 |
-| `activate`/`block`/`quarantine` | ✅ 정상 | workflow-scoped |
-| `can-use`/`guard` | ✅ 정상 | 정책 위반 시 거부 |
-| `impact disable` | ✅ 정상 | affected workflows/alternatives/risk |
-| `remove skill` | ✅ 정상 | 참조 시 거부, `--force`로 정리 |
-| `uninstall` | ✅ 정상 | 보수적 제거, dry-run |
-| `inventory refresh`/`detect` | ✅ 정상 | runtime component 감지 |
-| `sources refresh`/`audit` | ✅ 정상 | Git source digest pin |
-| `import`/`merge` | ✅ 정상 | built-in profiles |
-| `check` | ✅ 정상 | policy reference/rules |
-| `dashboard` | ✅ 정상 | markdown 보고서 |
-| `hook install` | ✅ 정상 | dry-run preview |
-
-### 4. 핵심 코드 품질 관찰
-
-- **정책 엔진**: `src/domain/rules/*.mjs`가 rule-id 기반으로 깔끔하게 분리되어 있어 새 규칙 추가가 쉬움.
-- **workspace 로딩**: `workspace.mjs`가 config 파싱과 설치 skill discovery를 분리. `SKILL.md` frontmatter 강제는 정합성을 위해 필요하지만, 에러 메시지가 개선되어야 함.
-- **control.mjs**: 거대 파일. CRUD, policy runtime, source classification, hook 설치 등을 분리하면 가독성과 테스트 용이성이 향상.
-- **writeCheckedConfig**: 임시 파일에 쓰고 policy + usability 검증 후 rename하는 방식은 안전함. dry-run과 실제 적용의 경계도 명확.
-- **agent-inventory**: detector 기반 스캔이 확장 가능. 다만 detector matching이 경로 suffix에 의존해 Windows/Linux 경로를 모두 고려한 점은 긍정적.
-
-## Plan
-
-### Phase 1: 첫 5분 UX 다듬기 (4.1)
-
-- [x] `workspace.mjs`의 `parseSkillFrontmatter` 에러 메시지 개선
-  - "SKILL.md is missing YAML frontmatter" → 필요한 frontmatter 예시와 docs/user-flow.md 링크 포함
-  - 예상 영향: `src/workspace.mjs` 1함수, test 1~2개 추가
-- [x] `add workflow`에서 `--harness` 누락 시 usage dump 대신 사용 가능한 harness 목록 제시
-  - 예상 영향: `src/cli.mjs` 또는 `src/control.mjs`의 `addWorkflow`
-- [x] `doctor`에 `--summary` 플래그 추가 (또는 기본 출력에서 1줄 status + 핵심 warnings만)
-  - 예상 영향: `src/doctor.mjs`, `src/report.mjs` 수정
-- [x] CLI 글로벌 defaults 파일/디렉토리 탐지: `--config`, `--skills` 미지정 시 현재 디렉토리의 `skillboard.config.yaml`과 `skills/`를 기본으로 사용하도록 개선
-  - 예상 영향: `src/cli.mjs` option parser, test 보강
-
-### Phase 2: 생태계 연결 및 문서 (4.2)
-
-- [x] `CONTRIBUTING.md` 작성: 개발 환경, 테스트 실행, source profile 추가 방법
-- [x] built-in profile 추가 가이드 문서화 (`docs/adapters.md` 보강 또는 `docs/profiles.md` 신규)
-- [x] README의 install 전/후 명령어 섹션 정리 (`skillboard` vs `node bin/skillboard.mjs` 구분 강조)
-- [x] 본 프로젝트에 `AGENTS.md`/`CLAUDE.md` bridge 적용 검토 (dogfooding)
-
-### Phase 3: 성능 및 구조 (4.3)
-
-- [x] `npm test` 실행 시간 프로파일링
-  - 병목이 되는 CLI 통합 테스트 식별
-  - 가능하다면 독립적인 단위 테스트와 통합 테스트 분리 (`npm run test:unit`, `npm run test:integration`)
-- [x] `src/control.mjs` 분리
-  - `skill-crud.mjs`, `workflow-crud.mjs`, `trust-source.mjs`, `can-use-guard.mjs`, `config-write.mjs` 등으로 쪼개기
-  - 예상 영향: 낶부 구조 개선, 기존 테스트 그대로 통과해야 함
-- [x] `doctor`/`brief`의 중복 workspace 로딩 최소화 (cache 또는 단일 로드 경로)
-
-### Phase 4: 도메인 정제 (선택, 높은 가치)
-
-- [x] `status`/`invocation` 매트릭스 검토: 14×7 조합 중 실제로 사용되는 조합을 문서화하고, 불필요한 조합은 deprecate 또는 명시적 금지
-- [x] `capability`의 global 정의와 workflow-scope `required_capabilities` 관계를 docs에 명확히 시각화
-- [x] `install_unit`의 `trust_level`과 `permission_risk` 조합에 따른 자동 권고 정책을 advisor action cards로 노출
-
-## TDD Notes
-
-- Red: Add failing tests for newly invalid status/invocation combos, capability docs, trust/risk action cards.
-- Green: Implement matrix, docs, and action card logic.
-- Refactor: `control.mjs` split into `src/control/*.mjs` modules; public API preserved.
-
-## Verification
-
-- Commands to run:
-  - `npm run diagnostics`
-  - `npm run test:unit`
-  - `npm run test:integration`
-  - `npm run check`
-  - `node bin/skillboard.mjs brief --config skillboard.config.yaml --skills skills`
-  - `git diff --check`
-- Results:
-  - TypeScript diagnostics: ✅
-  - `npm run test:unit`: 47 passed
-  - `npm run test:integration`: 103 passed
-  - `npm run check`: 161 passed
-  - CLI smoke test: ✅
-  - `git diff --check`: ✅
-
-## Decisions
-
-- **즉시 개선 권장**: 4.1 frontmatter 에러 메시지, `--config/--skills` 기본값, `doctor --summary`
-- **중기 개선 권장**: `control.mjs` 분리, test suite 분리, `CONTRIBUTING.md`
-- **도메인 설계는 유지**: 5개 엔티티 구조와 deny-by-default 정책은 변경하지 않음. 세부 상태/호출 매트릭스만 정제
-- **변경사항은 unstaged로 보관**: 사용자가 직접 커밋 지시 전까지 git index에 추가하지 않음
-
-## Resume State
-
-- Done: Phase 1~4 모두 완료. 모든 테스트 통과. 문서/워크로그 정리 완료.
-- In progress: 없음.
-- Next command: 사용자가 커밋/푸시 지시 또는 추가 개선 항목 제시
-- Open risks:
-  - `.skillboard/`와 `.omo/` 등 untracked artifact는 별도 정리 필요
-  - npm pack 시 포함 여부는 `test/package.test.mjs`에서 검증 완료
-
-## Progress Log
-
-- 2026-06-25T08:00:25Z: Plan created.
-- 2026-06-25T08:45:00Z: Domain audit, friction analysis, and improvement plan written.
-- 2026-06-25T10:05:00Z: Phase 1~4 implementation completed. All 161 tests passing.

package/docs/plans/README.md

@@ -1,20 +0,0 @@
-# Agent Handoff Plans
-
-This directory contains durable plans that can be picked up by another agent
-(such as Hermes) when the original author is not available.
-
-## Conventions
-
-- Each plan file is named `<timestamp>-<slug>.md`.
-- The `Status:` field in the frontmatter controls the lifecycle:
-  - `pending` — waiting for an agent to pick it up
-  - `assigned` — an agent is currently working on it
-  - `consumed` — the agent has finished the planned work
-- Agents should only pick up files with `Status: pending`.
-- After picking up a plan, change the status to `assigned` and commit.
-- After completing the work, change the status to `consumed` and commit.
-
-## Current Plans
-
-- `20260625-080025-skillboard-mvp-review.md` — SkillBoard MVP feature/domain
-  review and UX improvement plan (Status: completed)