@taejung3852/project-scaffold 0.1.0

package/lib/agents.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import readline from "node:readline/promises";
+import {
+  agentRegistry,
+  detectAgents,
+  getAgent,
+  normalizeAgentId,
+  registrySource,
+  supportedAgentIds,
+  uniqueProjectSkillDirs,
+} from "./agents-registry.js";
+
+export const supportedAgents = supportedAgentIds;
+
+function writeFileSafely(file, content, force, managedFiles) {
+  if (fs.existsSync(file) && !force) return false;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+  managedFiles?.add(file);
+  return true;
+}
+
+function existingEntry(file) {
+  try {
+    return fs.lstatSync(file);
+  } catch {
+    return null;
+  }
+}
+
+function linkSkill(skillDir, link, force, managedFiles) {
+  fs.mkdirSync(path.dirname(link), { recursive: true });
+  const existing = existingEntry(link);
+  if (existing) {
+    if (!existing.isSymbolicLink() && !force) return false;
+    fs.rmSync(link, { recursive: true, force: true });
+  }
+  const relativeTarget = path.relative(path.dirname(link), skillDir) || ".";
+  fs.symlinkSync(relativeTarget, link, "dir");
+  managedFiles?.add(link);
+  return true;
+}
+
+function skillEntries(target) {
+  const root = path.join(target, "skills");
+  if (!fs.existsSync(root)) throw new Error("skills/가 없습니다. init 또는 add를 먼저 실행하세요.");
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, "SKILL.md")))
+    .map((entry) => ({ name: entry.name, dir: path.join(root, entry.name) }));
+}
+
+function setupSkillDirectory(target, folder, force, managedFiles) {
+  if (folder === "skills") return;
+  for (const skill of skillEntries(target)) {
+    linkSkill(skill.dir, path.join(target, folder, skill.name), force, managedFiles);
+  }
+}
+
+function setupAgentsWrapper(target, force, managedFiles) {
+  writeFileSafely(path.join(target, "AGENTS.md"), "@AGENT.md\n", force, managedFiles);
+}
+
+function setupHermesContext(target, force, managedFiles) {
+  writeFileSafely(path.join(target, ".hermes.md"), "@AGENT.md\n", force, managedFiles);
+  writeFileSafely(
+    path.join(target, "cli-config.yaml"),
+    "terminal:\n  docker_mount_cwd_to_workspace: true\n",
+    force,
+    managedFiles,
+  );
+  console.log("  ℹ️  Hermes 전역 external_dirs 등록은 환경별 설정이므로 doctor 안내를 확인하세요.");
+}
+
+function ensureAdapterGitignore(target, agents, managedFiles) {
+  const file = path.join(target, ".gitignore");
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const existingLines = new Set(existing.split("\n"));
+  const additions = uniqueProjectSkillDirs(agents)
+    .filter((directory) => directory !== "skills")
+    .map((directory) => `${directory.replaceAll("\\", "/").replace(/\/$/, "")}/`)
+    .filter((directory) => !existingLines.has(directory));
+  if (additions.length === 0) return;
+
+  const prefix = existing.length > 0 ? `${existing.trimEnd()}\n\n` : "";
+  fs.writeFileSync(file, `${prefix}# project-scaffold agent adapters\n${additions.join("\n")}\n`);
+  managedFiles?.add(file);
+}
+
+export function normalizeAgents(values) {
+  const normalized = values.map((value) => value.trim().toLowerCase()).filter(Boolean);
+  const expanded = normalized.includes("all") || normalized.includes("*") ? supportedAgentIds : normalized;
+  const unique = [...new Set(expanded.map(normalizeAgentId))];
+  const unknown = unique.filter((agent) => !getAgent(agent));
+  if (unknown.length > 0) {
+    throw new Error(`지원하지 않는 에이전트: ${unknown.join(", ")}\n'project-scaffold agents'로 전체 목록을 확인하세요.`);
+  }
+  return unique;
+}
+
+export function registryLines() {
+  const groups = new Map();
+  for (const agent of Object.values(agentRegistry)) {
+    const ids = groups.get(agent.projectSkillsDir) ?? [];
+    ids.push(agent.id);
+    groups.set(agent.projectSkillsDir, ids);
+  }
+  const lines = [
+    `지원 에이전트 ${supportedAgentIds.length}개 — skills@${registrySource.version} 기준`,
+    "",
+  ];
+  for (const [directory, ids] of [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`${directory}: ${ids.sort().join(", ")}`);
+  }
+  return lines;
+}
+
+export async function chooseAgents(values, yes = false, target = process.cwd()) {
+  if (values.length > 0) return normalizeAgents(values);
+
+  const detected = detectAgents({ target });
+  const defaults = detected.length > 0 ? detected : ["universal"];
+  if (yes || !process.stdin.isTTY) return defaults;
+
+  if (detected.length > 0) {
+    console.log(`\n감지된 에이전트: ${detected.join(", ")}`);
+  } else {
+    console.log("\n자동 감지된 에이전트가 없습니다.");
+    console.log("추천: claude-code, codex, cursor, gemini-cli, github-copilot, opencode, windsurf, universal");
+  }
+  console.log("쉼표로 복수 선택할 수 있습니다. 전체 목록은 'list', 모두 설치는 'all'입니다.");
+
+  const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let answer = await terminal.question(`선택 [${defaults.join(",")}]: `);
+  if (answer.trim().toLowerCase() === "list") {
+    console.log(`\n${registryLines().join("\n")}\n`);
+    answer = await terminal.question(`선택 [${defaults.join(",")}]: `);
+  }
+  terminal.close();
+  return normalizeAgents((answer || defaults.join(",")).split(","));
+}
+
+export function configureAgents({ target, agents, force = false, managedFiles = new Set() }) {
+  const normalized = normalizeAgents(agents);
+  for (const directory of uniqueProjectSkillDirs(normalized)) {
+    console.log(`  → ${directory}`);
+    setupSkillDirectory(target, directory, force, managedFiles);
+  }
+
+  setupAgentsWrapper(target, force, managedFiles);
+  if (normalized.includes("claude-code")) {
+    writeFileSafely(path.join(target, "CLAUDE.md"), "@AGENT.md\n", force, managedFiles);
+  }
+  if (normalized.includes("hermes-agent")) setupHermesContext(target, force, managedFiles);
+  ensureAdapterGitignore(target, normalized, managedFiles);
+  return managedFiles;
+}
+
+export function agentChecks(target, agents) {
+  const normalized = normalizeAgents(agents);
+  const checks = uniqueProjectSkillDirs(normalized).map((directory) => ({
+    label: `skills 경로 ${directory}`,
+    ok: fs.existsSync(path.join(target, directory)),
+  }));
+  checks.push({ label: "AGENTS.md wrapper", ok: fs.existsSync(path.join(target, "AGENTS.md")) });
+  if (normalized.includes("claude-code")) {
+    checks.push({ label: "CLAUDE.md wrapper", ok: fs.existsSync(path.join(target, "CLAUDE.md")) });
+  }
+  if (normalized.includes("hermes-agent")) {
+    checks.push({ label: "Hermes context", ok: fs.existsSync(path.join(target, ".hermes.md")) });
+  }
+  return checks;
+}
+
+export async function addAgents(options) {
+  const target = path.resolve(options.target ?? process.cwd());
+  if (!fs.existsSync(path.join(target, ".git"))) throw new Error(`${target}은 Git 저장소가 아닙니다.`);
+  const agents = await chooseAgents(options.agents ?? [], options.yes, target);
+  const manifestFile = path.join(target, ".project-scaffold", "manifest.json");
+  let manifest = {};
+  if (fs.existsSync(manifestFile)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+    } catch {
+      throw new Error(`설치 manifest가 손상되었습니다: ${manifestFile}`);
+    }
+  }
+  const managedFiles = configureAgents({ target, agents, force: options.force });
+  manifest.agents = [...new Set([...(manifest.agents ?? []).map(normalizeAgentId), ...agents])];
+  manifest.agentRegistry = registrySource;
+  manifest.updatedAt = new Date().toISOString();
+  manifest.managedFiles = [
+    ...new Set([
+      ...(manifest.managedFiles ?? []),
+      ...[...managedFiles].map((file) => path.relative(target, file)),
+    ]),
+  ].sort();
+  fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
+  fs.writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log(`\n✅ 에이전트 설정 완료: ${agents.join(", ")}`);
+}

package/lib/install.js

@@ -0,0 +1,342 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { agentChecks, chooseAgents, configureAgents } from "./agents.js";
+import { registrySource } from "./agents-registry.js";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+const scaffoldDirectories = [".hooks", ".obsidian-template"];
+const scaffoldFiles = ["AGENT.md", "SOUL.md"];
+const wikiDirectories = ["conventions", "decisions", "devlog", "meetings", "synthesis", "sources"];
+const rawDirectories = ["meetings", "decisions", "dev-logs", "ideas"];
+const legacySkillNames = [
+  "setup",
+  "capture",
+  "devlog",
+  "ingest",
+  "query",
+  "code-lint",
+  "wiki-lint",
+  "dashboard",
+  "curate",
+  "report",
+  "help",
+  "handoff",
+];
+const legacyEvolutionFiles = [
+  "skills/.usage.json",
+  "scripts/skill_usage.py",
+  "scripts/curator.py",
+  "scripts/prompt_builder.py",
+  "scripts/skill_manager.py",
+];
+const currentSkillNames = ["wiki", "brief", "review"];
+
+function relative(target, file) {
+  return path.relative(target, file);
+}
+
+function copyTree(source, destination, force, target, managedFiles) {
+  if (!fs.existsSync(source)) return;
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const destinationPath = path.join(destination, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      copyTree(sourcePath, destinationPath, force, target, managedFiles);
+    } else if (entry.isFile() && (force || !fs.existsSync(destinationPath))) {
+      fs.copyFileSync(sourcePath, destinationPath);
+      managedFiles.add(relative(target, destinationPath));
+    }
+  }
+}
+
+function copyFile(source, destination, force, target, managedFiles) {
+  if (!fs.existsSync(source) || (fs.existsSync(destination) && !force)) return;
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+  managedFiles.add(relative(target, destination));
+}
+
+function copySkills(target, force, managedFiles) {
+  const sourceRoot = path.join(packageRoot, "skills");
+  const destinationRoot = path.join(target, "skills");
+  for (const entry of fs.readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const source = path.join(sourceRoot, entry.name);
+    if (!fs.existsSync(path.join(source, "SKILL.md"))) continue;
+    copyTree(source, path.join(destinationRoot, entry.name), force, target, managedFiles);
+  }
+}
+
+function activeLegacySkills(target) {
+  return legacySkillNames.filter((name) => fs.existsSync(path.join(target, "skills", name, "SKILL.md")));
+}
+
+function pathExistsWithoutFollowing(file) {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function legacyArtifacts(target) {
+  const files = [...legacyEvolutionFiles];
+  for (const name of currentSkillNames) {
+    files.push(`.cursor/rules/${name}.mdc`, `.continue/prompts/${name}.md`);
+  }
+  for (const name of legacySkillNames) {
+    files.push(
+      `skills/${name}/SKILL.md`,
+      `.claude/skills/${name}`,
+      `.agents/skills/${name}`,
+      `.windsurf/skills/${name}`,
+      `.hermes/skills/${name}`,
+      `.cursor/rules/${name}.mdc`,
+      `.continue/prompts/${name}.md`,
+    );
+  }
+  return files.filter((file) => pathExistsWithoutFollowing(path.join(target, file)));
+}
+
+function removeLegacySkillState(target, force) {
+  const active = activeLegacySkills(target);
+  if (active.length > 0 && !force) {
+    console.log(`  ⚠️  이전 스킬 감지: ${active.join(", ")}`);
+    console.log("     3스킬 구조로 마이그레이션하려면 --force를 사용하세요.");
+    return;
+  }
+  if (!force) return;
+
+  for (const name of legacySkillNames) {
+    fs.rmSync(path.join(target, "skills", name), { recursive: true, force: true });
+    for (const folder of [".claude/skills", ".agents/skills", ".windsurf/skills", ".hermes/skills"]) {
+      fs.rmSync(path.join(target, folder, name), { recursive: true, force: true });
+    }
+    fs.rmSync(path.join(target, ".cursor", "rules", `${name}.mdc`), { force: true });
+    fs.rmSync(path.join(target, ".continue", "prompts", `${name}.md`), { force: true });
+  }
+  for (const file of legacyEvolutionFiles) fs.rmSync(path.join(target, file), { force: true });
+
+  const aiderConfig = path.join(target, ".aider.conf.yml");
+  if (fs.existsSync(aiderConfig)) {
+    const legacyLines = new Set(legacySkillNames.map((name) => `skills/${name}/SKILL.md`));
+    const cleaned = fs
+      .readFileSync(aiderConfig, "utf8")
+      .split("\n")
+      .filter((line) => !legacyLines.has(line.replace(/^\s*-\s*/, "").trim()))
+      .join("\n");
+    fs.writeFileSync(aiderConfig, cleaned);
+  }
+  if (active.length > 0) console.log(`  ✅ 이전 스킬 ${active.length}개와 자가 진화 상태 제거`);
+}
+
+function removeDeprecatedAdapterState(target, force) {
+  if (!force) return;
+  for (const name of currentSkillNames) {
+    fs.rmSync(path.join(target, ".cursor", "rules", `${name}.mdc`), { force: true });
+    fs.rmSync(path.join(target, ".continue", "prompts", `${name}.md`), { force: true });
+  }
+}
+
+function mergeGitignore(target, managedFiles) {
+  const source = path.join(packageRoot, "templates", "gitignore");
+  const destination = path.join(target, ".gitignore");
+  const existing = fs.existsSync(destination) ? fs.readFileSync(destination, "utf8") : "";
+  const sourceLines = fs.readFileSync(source, "utf8").split("\n");
+  const additions = sourceLines.filter((line) => line && !line.startsWith("#") && !existing.split("\n").includes(line));
+  if (!fs.existsSync(destination)) {
+    fs.writeFileSync(destination, fs.readFileSync(source));
+    managedFiles.add(".gitignore");
+  } else if (additions.length > 0) {
+    fs.appendFileSync(destination, `\n# project-scaffold\n${additions.join("\n")}\n`);
+    managedFiles.add(".gitignore");
+  }
+}
+
+function writeIfMissing(file, content, target, managedFiles) {
+  if (fs.existsSync(file)) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+  managedFiles.add(relative(target, file));
+}
+
+function createKnowledgeStructure(target, managedFiles) {
+  const today = new Date().toISOString().slice(0, 10);
+  for (const directory of wikiDirectories) {
+    const keep = path.join(target, "wiki", directory, ".gitkeep");
+    writeIfMissing(keep, "", target, managedFiles);
+  }
+  for (const directory of rawDirectories) {
+    const keep = path.join(target, "raw", directory, ".gitkeep");
+    writeIfMissing(keep, "", target, managedFiles);
+  }
+  writeIfMissing(
+    path.join(target, "wiki", "index.md"),
+    `---\ntitle: Wiki Index\nupdated: ${today}\n---\n\n# Wiki Index\n\n> /wiki를 실행하면 현재 상태를 보고 초기 설정을 추천합니다.\n\n## 통계\n\n| 항목 | 수 |\n|---|---|\n| 전체 페이지 | 0 |\n| Conventions | 0 |\n| Sources | 0 |\n\n마지막 업데이트: ${today}\n`,
+    target,
+    managedFiles,
+  );
+  writeIfMissing(
+    path.join(target, "wiki", "log.md"),
+    `---\ntitle: Wiki Log\nupdated: ${today}\n---\n\n# Wiki Operation Log\n\n> 모든 ingest·query·lint 오퍼레이션이 여기에 기록됩니다.\n\n---\n`,
+    target,
+    managedFiles,
+  );
+  writeIfMissing(
+    path.join(target, "wiki", "dashboard.md"),
+    `---\ntitle: Dashboard\nupdated: ${today}\n---\n\n# 프로젝트 대시보드\n\n> /brief를 실행해 현황판 갱신을 선택하세요.\n\n## 📋 오늘 할 일\n\n- [ ] /wiki를 실행하여 프로젝트 초기 설정\n\n## ⚠️ 주의 필요\n\n- wiki/conventions/ 비어있음 → /wiki 초기 설정 필요\n`,
+    target,
+    managedFiles,
+  );
+  copyTree(path.join(packageRoot, ".obsidian-template"), path.join(target, "wiki", ".obsidian"), false, target, managedFiles);
+}
+
+function installHooks(target, force, managedFiles) {
+  const hooks = [
+    ["convention-check.sh", "pre-commit"],
+    ["devlog-auto.sh", "post-commit"],
+  ];
+  for (const [sourceName, destinationName] of hooks) {
+    const destination = path.join(target, ".git", "hooks", destinationName);
+    if (fs.existsSync(destination) && !force) {
+      console.log(`  ⏭  기존 ${destinationName} hook 보존`);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(path.join(packageRoot, ".hooks", sourceName), destination);
+    fs.chmodSync(destination, 0o755);
+    managedFiles.add(relative(target, destination));
+  }
+}
+
+function commandExists(command) {
+  return spawnSync(command, ["--help"], { stdio: "ignore" }).status === 0;
+}
+
+function setupGraphify(enabled) {
+  if (!enabled) return "skipped";
+  if (!commandExists("graphify")) {
+    console.log("  ⚠️  Graphify 미설치: pip install graphifyy && graphify install");
+    return "not-installed";
+  }
+  const result = spawnSync("graphify", ["install"], { stdio: "inherit" });
+  return result.status === 0 ? "installed" : "failed";
+}
+
+function writeManifest(target, manifest) {
+  const file = path.join(target, ".project-scaffold", "manifest.json");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+export async function install(options) {
+  const target = path.resolve(options.target ?? process.cwd());
+  if (!fs.existsSync(target)) throw new Error(`대상 경로가 없습니다: ${target}`);
+  if (!fs.existsSync(path.join(target, ".git"))) throw new Error(`${target}은 Git 저장소가 아닙니다.`);
+  if (target === packageRoot) throw new Error("project-scaffold 저장소 자체에는 설치할 수 없습니다. 다른 Git 저장소를 지정하세요.");
+
+  const agents = await chooseAgents(options.agents ?? [], options.yes, target);
+  const managedFiles = new Set();
+
+  console.log(`🚀 project-scaffold ${options.mode}\n  대상: ${target}\n  에이전트: ${agents.join(", ")}`);
+  console.log("\n📦 scaffold 파일 설치");
+  removeLegacySkillState(target, options.force);
+  removeDeprecatedAdapterState(target, options.force);
+  copySkills(target, options.force, managedFiles);
+  for (const directory of scaffoldDirectories) {
+    copyTree(path.join(packageRoot, directory), path.join(target, directory), options.force, target, managedFiles);
+  }
+  for (const file of scaffoldFiles) {
+    copyFile(path.join(packageRoot, file), path.join(target, file), options.force, target, managedFiles);
+  }
+  mergeGitignore(target, managedFiles);
+
+  console.log("📚 LLM Wiki 구조 생성");
+  createKnowledgeStructure(target, managedFiles);
+
+  if (options.hooks) {
+    console.log("🔗 Git hook 설치");
+    installHooks(target, options.force, managedFiles);
+  }
+
+  console.log("🤖 에이전트 어댑터 설정");
+  const adapterFiles = configureAgents({ target, agents, force: options.force, managedFiles: new Set() });
+
+  console.log("🧠 Graphify 확인");
+  const graphify = setupGraphify(options.graphify);
+  const allManagedFiles = new Set(managedFiles);
+  for (const file of adapterFiles) allManagedFiles.add(relative(target, file));
+  for (const checkPath of ["CLAUDE.md", "AGENTS.md", ".cursorrules", ".hermes.md", "cli-config.yaml", ".aider.conf.yml"]) {
+    if (fs.existsSync(path.join(target, checkPath))) allManagedFiles.add(checkPath);
+  }
+  writeManifest(target, {
+    schemaVersion: 1,
+    package: packageJson.name,
+    version: packageJson.version,
+    mode: options.mode,
+    installedAt: new Date().toISOString(),
+    agents,
+    agentRegistry: registrySource,
+    features: { hooks: options.hooks, graphify },
+    managedFiles: [...allManagedFiles].sort(),
+  });
+
+  console.log("\n✅ 설치 완료");
+  console.log(`  다음 단계: ${agents[0]}에서 프로젝트를 열고 /wiki를 실행하세요.`);
+  console.log("  상태 검사: npx @taejung3852/project-scaffold@latest doctor");
+}
+
+function loadManifest(target) {
+  const file = path.join(target, ".project-scaffold", "manifest.json");
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function doctor(options) {
+  const target = path.resolve(options.target ?? process.cwd());
+  const manifest = loadManifest(target);
+  const checks = [
+    { label: "Git 저장소", ok: fs.existsSync(path.join(target, ".git")) },
+    { label: "설치 manifest", ok: manifest !== null },
+    {
+      label: `agent registry skills@${registrySource.version}`,
+      ok: manifest?.agentRegistry?.version === registrySource.version,
+    },
+    { label: "AGENT.md", ok: fs.existsSync(path.join(target, "AGENT.md")) },
+    { label: "skills/", ok: fs.existsSync(path.join(target, "skills")) },
+    { label: "legacy 스킬·자가 진화 상태 없음", ok: legacyArtifacts(target).length === 0 },
+    { label: "wiki/index.md", ok: fs.existsSync(path.join(target, "wiki", "index.md")) },
+    { label: "raw/", ok: fs.existsSync(path.join(target, "raw")) },
+  ];
+  if (manifest?.features?.hooks) {
+    checks.push(
+      { label: "pre-commit hook", ok: fs.existsSync(path.join(target, ".git", "hooks", "pre-commit")) },
+      { label: "post-commit hook", ok: fs.existsSync(path.join(target, ".git", "hooks", "post-commit")) },
+    );
+  }
+  checks.push(...agentChecks(target, manifest?.agents ?? []));
+  const result = { ok: checks.every((check) => check.ok), target, version: manifest?.version ?? null, checks };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`project-scaffold doctor\n대상: ${target}\n`);
+    for (const check of checks) console.log(`${check.ok ? "✅" : "❌"} ${check.label}`);
+    if (manifest?.agents?.includes("hermes-agent")) {
+      console.log("ℹ️  Hermes는 ~/.hermes/config.yaml의 skills.external_dirs에 프로젝트 skills/ 경로를 등록해야 합니다.");
+    }
+    console.log(result.ok ? "\n✅ 설치 상태가 정상입니다." : "\n❌ 누락된 항목을 확인하세요.");
+  }
+  return result;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@taejung3852/project-scaffold",
+  "version": "0.1.0",
+  "description": "LLM Wiki-based project context scaffold for AI coding agents",
+  "type": "module",
+  "bin": {
+    "project-scaffold": "bin/project-scaffold.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "skills/",
+    ".hooks/",
+    ".obsidian-template/",
+    "AGENT.md",
+    "SOUL.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check bin/project-scaffold.js && node --check lib/install.js && node --check lib/agents.js && node --check lib/agents-registry.js",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taejung3852/project-scaffold.git"
+  }
+}

package/skills/brief/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: brief
+description: "프로젝트 현황을 사람이 따라갈 수 있는 브리핑으로 정리한다. 현재 목표, 변경점, 결정 필요 항목, 다음 행동을 30초·5분·상세 깊이로 설명하고 dashboard, 회의·스프린트·ADR report, 세션 handoff를 생성한다. 진행 상황 파악, 대시보드 갱신, 보고서 작성, 세션 인계가 필요할 때 사용."
+---
+
+# /brief — 사람 중심 프로젝트 브리핑
+
+항상 사람이 현재 상황과 자신의 결정 지점을 빠르게 파악하도록 구성한다.
+
+## 사용자 호출 UX
+
+자연어 요청에서 목적이 명확하면 묻지 말고 바로 적절한 작업을 수행한다.
+
+- “지금 어디까지 했어?” → 기본 현황 브리핑
+- “회의 내용 공유용으로 정리해줘” → report
+- “다음 세션에서 이어가게 해줘” → handoff
+
+사용자가 **`/brief`만 단독으로 호출하면**, git 상태·최근 devlog·대화 흐름을 먼저 확인하고 가장 적절한 항목을 추천한다. 내부 모드명 대신 사람이 이해하는 행동으로 묻는다.
+
+```text
+지금 맥락상 "현재 상태와 다음 우선순위 확인"이 가장 적절해 보여요.
+
+1. 현재 상태를 30초로 보기 ← 추천
+2. 최근 변화까지 5분으로 보기
+3. 프로젝트 현황판 갱신하기
+4. 회의·ADR·스프린트 문서 만들기
+5. 다음 세션용 인계 남기기
+
+어떤 걸 할까요? 번호나 원하는 내용을 말해줘도 됩니다.
+```
+
+추천 근거는 한 줄만 말한다. 사용자가 번호 대신 자연어로 답해도 의도를 다시 해석한다. 이미 목적이 분명한 요청에는 선택 메뉴를 보여주지 않는다.
+
+## 기본 브리핑
+
+별도 모드가 없으면 다음 순서로 답한다.
+
+1. **Now** — 지금 목표와 현재 작업
+2. **Why** — 이 작업을 하는 이유
+3. **Since last visit** — 최근 코드·문서·결정 변화
+4. **Decision queue** — 사용자가 판단해야 할 항목
+5. **Next** — 가장 가까운 다음 한 단계
+6. **Sources** — 관련 wiki·devlog·코드 경로
+
+기본 깊이는 30초 분량이다. 사용자가 더 알고 싶어 하면 5분 또는 상세 보기로 확장한다. 진행률은 구현 근거가 있을 때만 숫자로 표시하고, 미구현 계획은 0%로 둔다.
+
+## 내부 모드 라우팅
+
+| 모드 | 대표 의도 | 읽을 참조 |
+|---|---|---|
+| `dashboard` | 현황판 갱신, TODO·마일스톤 관리, terminal/web 렌더 | `references/dashboard.md` |
+| `report` | 회의록, 인터뷰, ADR, 스프린트 요약 | `references/report.md` |
+| `handoff` | 세션 저장·복원·목록·정리 | `references/handoff.md` |
+
+사용자가 프로젝트 현황, 최근 변경, 다음 우선순위를 물으면 명시적 호출이 없어도 기본 브리핑으로 처리한다.
+
+## 공통 원칙
+
+- 완료된 구현과 미래 계획을 분리한다.
+- 요약만 제공하고 끝내지 말고 사용자가 결정해야 할 지점을 드러낸다.
+- 원본과 해석을 구분하고 관련 파일로 이동할 수 있게 한다.
+- 같은 내용을 여러 산출물에 복제하지 말고 기존 PR·커밋·wiki 경로를 참조한다.
+- 민감 정보는 handoff와 report에 저장하기 전에 검열한다.

package/skills/brief/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Project Brief"
+  short_description: "프로젝트 현황과 결정 지점을 사람 중심으로 브리핑"
+  default_prompt: "Use $brief to explain the current project state at the right depth."