@taejung3852/project-scaffold 0.1.0

package/README.md

@@ -0,0 +1,247 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/taejung3852/project-scaffold/master/assets/logo.png" width="200" alt="project-scaffold logo" />
+</p>
+
+# project-scaffold
+
+> An LLM Wiki-based development context layer that gives AI project memory and gives humans back project control
+
+[![Node.js](https://img.shields.io/badge/CLI-Node.js_20+-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Markdown](https://img.shields.io/badge/Knowledge-LLM_Wiki-000000?logo=markdown)](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+[![Skills](https://img.shields.io/badge/Core_Skills-3-1D3461)](./skills)
+
+<p align="center">English | <a href="README.kr.md">한국어</a></p>
+
+---
+
+## What it solves
+
+AI coding agents move quickly, but new sessions often lose the project's character, earlier decisions, user preferences, and overall work history. Repeating all of that in a long prompt is expensive and hard for humans to follow.
+
+project-scaffold addresses this with two layers:
+
+- **Agent Memory Layer** — accumulates project context in `raw/` and `wiki/`.
+- **Human Control Plane** — briefs the human on the current goal, recent changes, decisions, and next action.
+
+Users do not memorize twelve commands. The agent routes each request to one of three skills: `/wiki`, `/brief`, or `/review`.
+
+## Quick start
+
+Requires Node.js 20+ and a Git repository.
+
+### New project
+
+```bash
+mkdir my-project && cd my-project
+git init
+npx @taejung3852/project-scaffold@latest init --agent claude-code,codex
+```
+
+Then start the project interview inside your AI agent:
+
+```text
+/wiki
+```
+
+Because no conventions exist yet, `/wiki` recommends project setup as the first action.
+
+### Existing project
+
+```bash
+cd /path/to/existing-project
+npx @taejung3852/project-scaffold@latest add --agent claude-code,cursor
+```
+
+Existing files are preserved by default. Use `--force` only when you explicitly want to replace scaffold-managed files.
+
+When migrating from the former twelve-skill version, the following command removes legacy skills and self-evolution files. Review your diff first because customized legacy skills are also removed.
+
+```bash
+npx @taejung3852/project-scaffold@latest add --agent claude-code,codex --force
+```
+
+### Add agents and verify the installation
+
+```bash
+npx @taejung3852/project-scaffold@latest add-agent --agent codex,cursor
+npx @taejung3852/project-scaffold@latest doctor
+```
+
+Installation state is stored in `.project-scaffold/manifest.json`.
+
+## Three core skills
+
+### `/wiki` — project knowledge lifecycle
+
+Calling `/wiki` by itself inspects the project and recommends what to do next. Users do not need to remember the internal capabilities below.
+
+| Mode | Role |
+|---|---|
+| `setup` | Scan the codebase and run the 14-category convention interview |
+| `capture` | Preserve meeting and decision sources in `raw/` |
+| `devlog` | Draft a development log from git and conversation context |
+| `ingest` | Compile pending raw sources into the structured wiki |
+| `query` | Answer from project character, previous decisions, and records |
+| `lint` | Detect broken links, orphan pages, contradictions, and stale knowledge |
+
+```text
+/wiki
+Why did we choose this architecture?
+Record this decision.
+```
+
+### `/brief` — human-centered briefing
+
+Calling `/brief` by itself inspects recent git and devlog context, then puts the most relevant briefing action first.
+
+The default briefing answers:
+
+1. What are we doing now?
+2. Why are we doing it?
+3. What changed since the last check-in?
+4. What does the human need to decide?
+5. What is the next action?
+6. Where is the supporting evidence?
+
+| Mode | Role |
+|---|---|
+| default | 30-second briefing, expandable to five-minute or deep views |
+| `dashboard` | Refresh TODOs, milestones, recent devlogs, and warnings |
+| `report` | Create meeting, interview, ADR, or sprint reports |
+| `handoff` | Save and restore context for another session or agent |
+
+```text
+/brief
+Explain the recent changes in detail.
+Leave a handoff for the next session.
+```
+
+### `/review` — convention-grounded change review
+
+Combines static analysis with LLM review against `wiki/conventions/`:
+
+- naming and architecture dependencies
+- missing tests
+- error handling
+- security and hard-coded secrets
+- project-specific review rules
+
+It reports evidence and proposed fixes without automatically changing the code.
+
+## Users do not need to remember skill names
+
+`AGENT.md` acts as the intent router.
+
+| User request | Agent behavior |
+|---|---|
+| “Where are we now?” | `/brief` |
+| “Why did we choose this database?” | `/wiki` routes to project Q&A |
+| “Record this decision.” | `/wiki` routes to decision capture |
+| “Summarize today's work.” | `/wiki` routes to devlog |
+| “Review this before the PR.” | `/review` |
+
+Every agent adapter uses `AGENT.md` as the shared source of truth.
+
+## LLM Wiki structure
+
+```text
+raw/                     immutable human-authored sources
+  └─ compiled by /wiki when appropriate
+wiki/                    agent-maintained project knowledge
+  ├─ conventions/        project rules
+  ├─ decisions/          technical and product decisions
+  ├─ devlog/             curated development history
+  ├─ sources/            raw source summaries
+  ├─ synthesis/          answers connecting multiple documents
+  ├─ index.md            navigation entry point
+  ├─ dashboard.md        current state
+  └─ log.md              wiki operation history
+AGENT.md                 intent routing and invariant project rules
+SOUL.md                  user preferences and assistant persona
+```
+
+The body of `raw/` is immutable. When the wiki finds a contradiction, it preserves both sources instead of silently replacing one.
+
+## Supported agents
+
+The CLI supports all 73 agent IDs and project paths from the official [`skills@1.5.16`](https://github.com/vercel-labs/skills) registry.
+
+| Path type | Examples |
+|---|---|
+| shared `.agents/skills/` | Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Amp, Warp, Zed, and others |
+| `.claude/skills/` | Claude Code |
+| `.continue/skills/` | Continue |
+| `.hermes/skills/` | Hermes Agent |
+| `.windsurf/skills/` | Windsurf |
+| other dedicated paths | Goose, Kiro CLI, Roo Code, Qwen Code, AiderDesk, and others |
+
+```bash
+npx @taejung3852/project-scaffold@latest agents
+```
+
+Use this command to see every ID and path. `--agent all` and `--agent '*'` are also supported.
+
+The CLI installs canonical `skills/{wiki,brief,review}` once and deduplicates agents that share the same target directory. Without `--agent`, it recommends reliably detected local agents and falls back to universal `.agents/skills/` when none are found. Existing aliases such as `claude` and `hermes` remain supported.
+
+## Installed structure
+
+```text
+[your-project]/
+├── .project-scaffold/manifest.json
+├── AGENT.md
+├── SOUL.md
+├── skills/
+│   ├── wiki/
+│   │   ├── SKILL.md
+│   │   └── references/
+│   ├── brief/
+│   │   ├── SKILL.md
+│   │   └── references/
+│   └── review/SKILL.md
+├── wiki/
+│   ├── index.md
+│   ├── dashboard.md
+│   ├── log.md
+│   └── devlog/
+├── raw/
+└── .hooks/
+```
+
+The Node CLI is the only installer entry point. The legacy shell installers have been removed.
+
+## Git hooks
+
+- `pre-commit` — checks staged blobs for secrets and available static-analysis rules, handles spaces safely, and never downloads tools
+- `post-commit` — records commit messages and changed files as stable Markdown under `raw/dev-logs/`
+
+Existing hooks are preserved by default.
+
+## Obsidian and Graphify
+
+- Open `wiki/` as an Obsidian vault for human navigation.
+- When Graphify is installed, update the knowledge graph after wiki changes.
+- Both are optional; the core LLM Wiki workflow works without them.
+
+## Development and release
+
+```bash
+npm test
+npm run check
+npm pack --dry-run
+```
+
+Publish only after the full feature and documentation pass is complete.
+
+```bash
+npm publish --access public
+```
+
+## Current status
+
+| Item | Status |
+|---|---|
+| Node CLI (`init`, `add`, `add-agent`, `agents`, `doctor`) | ✅ Implemented |
+| 73-agent registry based on skills@1.5.16 | ✅ Implemented |
+| Three core skills (`wiki`, `brief`, `review`) | ✅ Implemented |
+| Hermes-style usage tracking and self-evolution | 🗑️ Removed |
+| Initial npm publish | ⏳ After all planned changes |

package/SOUL.md

@@ -0,0 +1,54 @@
+# SOUL.md — AI 비서 페르소나
+
+> 개인 설정 파일입니다. `/wiki`의 초기 설정이 AGENT.md를 갱신해도 이 파일은 변경되지 않습니다.
+> 초기 설정 카테고리 14에서 설정하거나 직접 수정하세요.
+
+---
+
+## 말투
+
+| 항목 | 설정 |
+|---|---|
+| 격식 | 비격식체 (반말 허용) |
+| 길이 | 간결하게. 요약 없이 핵심만 |
+| 어조 | 동료처럼. 지시하지 않고 함께 고민 |
+
+---
+
+## 전문성 가정
+
+| 항목 | 설정 |
+|---|---|
+| 기본 수준 | 개발 기초는 안다고 가정 |
+| 설명 방식 | WHY 중심. 코드 한 줄씩 설명 금지 |
+| 모르는 게 있으면 | 먼저 물어봐서 수준 파악 |
+
+---
+
+## 판단·피드백 방식
+
+| 항목 | 설정 |
+|---|---|
+| 내가 틀렸을 때 | 바로 말해. 돌려 말하지 않아도 됨 |
+| 선택지가 있을 때 | 추천 하나 + 이유. 목록 나열 금지 |
+| 확신 없을 때 | 모른다고 말하고 같이 찾아 |
+
+---
+
+## 불확실·위험한 상황
+
+| 항목 | 설정 |
+|---|---|
+| 파괴적 작업 | 반드시 먼저 물어봐 |
+| 애매한 요청 | 바로 실행하지 말고 의도 확인 |
+| 큰 변경 전 | 계획 먼저 보여주고 승인 받아 |
+
+---
+
+## 언어
+
+| 항목 | 설정 |
+|---|---|
+| 기본 언어 | 한국어 |
+| 코드·기술 용어 | 영어 원어 유지 |
+| 영어로 질문 받으면 | 한국어로 답 |

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-Party Notices
+
+## vercel-labs/skills
+
+The agent identifiers and project skill-directory mappings in
+`lib/agents-registry.js` are derived from `skills@1.5.16`.
+
+- Source: https://github.com/vercel-labs/skills
+- Package: https://www.npmjs.com/package/skills
+- License: MIT
+
+No runtime code from the `skills` package is bundled or executed by
+project-scaffold. The registry is vendored so installation remains deterministic
+and works without a nested network dependency.

package/bin/project-scaffold.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { addAgents, registryLines } from "../lib/agents.js";
+import { doctor, install } from "../lib/install.js";
+
+const HELP = `
+project-scaffold — LLM Wiki 기반 AI 개발 컨텍스트 설치 도구
+
+사용법:
+  project-scaffold init [경로] [옵션]       새 프로젝트에 초기화
+  project-scaffold add [경로] [옵션]        기존 프로젝트에 설치
+  project-scaffold add-agent [경로] [옵션]  에이전트 어댑터 추가
+  project-scaffold doctor [경로]            설치 상태 검사
+  project-scaffold agents                   지원 에이전트와 설치 경로 목록
+
+옵션:
+  -a, --agent <목록>   쉼표로 구분한 에이전트 ID 또는 all
+                       전체 목록: project-scaffold agents
+  -t, --target <경로>  대상 Git 저장소 경로
+  -y, --yes            질문 없이 자동 감지값 사용 (미감지 시 universal)
+      --force          기존 scaffold 관리 파일 덮어쓰기
+      --skip-hooks     Git hook 설치 생략
+      --skip-graphify  Graphify 등록 생략
+      --json           doctor 결과를 JSON으로 출력
+  -h, --help           도움말 출력
+
+예시:
+  npx @taejung3852/project-scaffold@latest init --agent claude-code,codex
+  npx @taejung3852/project-scaffold@latest add ~/workspace/my-app --agent all
+  npx @taejung3852/project-scaffold@latest doctor
+`;
+
+function parseArgs(argv) {
+  const options = {
+    command: "help",
+    target: undefined,
+    agents: [],
+    yes: false,
+    force: false,
+    hooks: true,
+    graphify: true,
+    json: false,
+  };
+
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith("-")) {
+    options.command = args.shift();
+  }
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === "-h" || arg === "--help") {
+      options.command = "help";
+    } else if (arg === "-y" || arg === "--yes") {
+      options.yes = true;
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--skip-hooks") {
+      options.hooks = false;
+    } else if (arg === "--skip-graphify") {
+      options.graphify = false;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "-a" || arg === "--agent") {
+      const value = args.shift();
+      if (!value) throw new Error(`${arg} 뒤에 에이전트 목록이 필요합니다.`);
+      options.agents.push(...value.split(","));
+    } else if (arg.startsWith("--agent=")) {
+      options.agents.push(...arg.slice("--agent=".length).split(","));
+    } else if (arg === "-t" || arg === "--target") {
+      const value = args.shift();
+      if (!value) throw new Error(`${arg} 뒤에 경로가 필요합니다.`);
+      options.target = value;
+    } else if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+    } else if (!arg.startsWith("-") && !options.target) {
+      options.target = arg;
+    } else {
+      throw new Error(`알 수 없는 옵션: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.command === "help") {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (options.command === "init" || options.command === "add") {
+    await install({ ...options, mode: options.command });
+    return;
+  }
+
+  if (options.command === "add-agent") {
+    await addAgents(options);
+    return;
+  }
+
+  if (options.command === "doctor") {
+    const result = await doctor(options);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (options.command === "agents") {
+    console.log(registryLines().join("\n"));
+    return;
+  }
+
+  throw new Error(`알 수 없는 명령: ${options.command}\n${HELP}`);
+}
+
+main().catch((error) => {
+  console.error(`❌ ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/agents-registry.js

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const registrySource = Object.freeze({
+  package: "skills",
+  version: "1.5.16",
+  repository: "https://github.com/vercel-labs/skills",
+});
+
+const universalAgents = [
+  "amp",
+  "antigravity",
+  "antigravity-cli",
+  "cline",
+  "codex",
+  "cursor",
+  "deepagents",
+  "dexto",
+  "firebender",
+  "gemini-cli",
+  "github-copilot",
+  "kimi-code-cli",
+  "loaf",
+  "opencode",
+  "promptscript",
+  "replit",
+  "universal",
+  "warp",
+  "zed",
+];
+
+const customAgentPaths = {
+  "aider-desk": ".aider-desk/skills",
+  astrbot: "data/skills",
+  "autohand-code": ".autohand/skills",
+  augment: ".augment/skills",
+  bob: ".bob/skills",
+  "claude-code": ".claude/skills",
+  openclaw: "skills",
+  "codearts-agent": ".codeartsdoer/skills",
+  codebuddy: ".codebuddy/skills",
+  codemaker: ".codemaker/skills",
+  codestudio: ".codestudio/skills",
+  "command-code": ".commandcode/skills",
+  continue: ".continue/skills",
+  cortex: ".cortex/skills",
+  crush: ".crush/skills",
+  devin: ".devin/skills",
+  droid: ".factory/skills",
+  eve: "agent/skills",
+  forgecode: ".forge/skills",
+  goose: ".goose/skills",
+  "hermes-agent": ".hermes/skills",
+  "inference-sh": ".inferencesh/skills",
+  jazz: ".jazz/skills",
+  junie: ".junie/skills",
+  "iflow-cli": ".iflow/skills",
+  kilo: ".kilocode/skills",
+  "kiro-cli": ".kiro/skills",
+  kode: ".kode/skills",
+  lingma: ".lingma/skills",
+  mcpjam: ".mcpjam/skills",
+  "mistral-vibe": ".vibe/skills",
+  moxby: ".moxby/skills",
+  mux: ".mux/skills",
+  openhands: ".openhands/skills",
+  ona: ".ona/skills",
+  pi: ".pi/skills",
+  qoder: ".qoder/skills",
+  "qoder-cn": ".qoder/skills",
+  "qwen-code": ".qwen/skills",
+  reasonix: ".reasonix/skills",
+  rovodev: ".rovodev/skills",
+  roo: ".roo/skills",
+  "tabnine-cli": ".tabnine/agent/skills",
+  terramind: ".terramind/skills",
+  tinycloud: ".tinycloud/skills",
+  trae: ".trae/skills",
+  "trae-cn": ".trae/skills",
+  windsurf: ".windsurf/skills",
+  zcode: ".zcode/skills",
+  zencoder: ".zencoder/skills",
+  zenflow: ".zencoder/skills",
+  neovate: ".neovate/skills",
+  pochi: ".pochi/skills",
+  adal: ".adal/skills",
+};
+
+const displayNameOverrides = {
+  "aider-desk": "AiderDesk",
+  "autohand-code": "Autohand Code CLI",
+  bob: "IBM Bob",
+  "claude-code": "Claude Code",
+  "codearts-agent": "CodeArts Agent",
+  codestudio: "Code Studio",
+  codex: "Codex",
+  cortex: "Cortex Code",
+  deepagents: "Deep Agents",
+  devin: "Devin for Terminal",
+  droid: "Droid",
+  "gemini-cli": "Gemini CLI",
+  "github-copilot": "GitHub Copilot",
+  "hermes-agent": "Hermes Agent",
+  "iflow-cli": "iFlow CLI",
+  "inference-sh": "inference.sh",
+  kilo: "Kilo Code",
+  "kimi-code-cli": "Kimi Code CLI",
+  "kiro-cli": "Kiro CLI",
+  "mistral-vibe": "Mistral Vibe",
+  opencode: "OpenCode",
+  openhands: "OpenHands",
+  "qoder-cn": "Qoder CN",
+  "qwen-code": "Qwen Code",
+  roo: "Roo Code",
+  "tabnine-cli": "Tabnine CLI",
+  "trae-cn": "Trae CN",
+  zcode: "ZCode",
+};
+
+export const agentAliases = Object.freeze({
+  claude: "claude-code",
+  hermes: "hermes-agent",
+  "continue-dev": "continue",
+});
+
+function titleCase(id) {
+  return id
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+const entries = [
+  ...universalAgents.map((id) => [id, ".agents/skills"]),
+  ...Object.entries(customAgentPaths),
+].map(([id, projectSkillsDir]) => ({
+  id,
+  displayName: displayNameOverrides[id] ?? titleCase(id),
+  projectSkillsDir,
+}));
+
+export const agentRegistry = Object.freeze(
+  Object.fromEntries(entries.sort((a, b) => a.id.localeCompare(b.id)).map((entry) => [entry.id, Object.freeze(entry)])),
+);
+
+export const supportedAgentIds = Object.freeze(Object.keys(agentRegistry));
+
+export function normalizeAgentId(value) {
+  const normalized = value.trim().toLowerCase();
+  return agentAliases[normalized] ?? normalized;
+}
+
+export function getAgent(id) {
+  return agentRegistry[normalizeAgentId(id)];
+}
+
+const detectionPaths = {
+  "aider-desk": ["~/.aider-desk"],
+  antigravity: ["~/.gemini/antigravity"],
+  "antigravity-cli": ["~/.gemini/antigravity-cli"],
+  "claude-code": ["~/.claude"],
+  codex: ["$CODEX_HOME", "~/.codex", "/etc/codex"],
+  continue: ["~/.continue", ".continue"],
+  cursor: ["~/.cursor", ".cursor"],
+  devin: ["~/.config/devin"],
+  droid: ["~/.factory"],
+  "gemini-cli": ["~/.gemini"],
+  goose: ["~/.config/goose"],
+  "hermes-agent": ["~/.hermes"],
+  "kiro-cli": ["~/.kiro"],
+  opencode: ["~/.config/opencode"],
+  windsurf: ["~/.codeium/windsurf"],
+};
+
+function expandDetectionPath(value, target, home, env) {
+  if (value === "$CODEX_HOME") return env.CODEX_HOME?.trim() || null;
+  if (value.startsWith("~/")) return path.join(home, value.slice(2));
+  if (path.isAbsolute(value)) return value;
+  return path.join(target, value);
+}
+
+export function detectAgents({ target = process.cwd(), home = os.homedir(), env = process.env } = {}) {
+  return Object.entries(detectionPaths)
+    .filter(([, candidates]) =>
+      candidates.some((candidate) => {
+        const expanded = expandDetectionPath(candidate, target, home, env);
+        return expanded ? fs.existsSync(expanded) : false;
+      }),
+    )
+    .map(([id]) => id)
+    .sort();
+}
+
+export function uniqueProjectSkillDirs(agentIds) {
+  return [...new Set(agentIds.map((id) => getAgent(id)?.projectSkillsDir).filter(Boolean))];
+}