@nick848/fet 1.0.5 → 1.0.6

package/README.md

@@ -131,6 +131,32 @@ $env:FET_REAL_OPENSPEC='1'; npm run test:real-openspec
 
 MIT
 
+### 可选 GitNexus 图谱支持
+
+FET 会在 `fet init` 时检测可选的 `gitnexus` 可执行文件，并把结果记录到 `openspec/fet-state.json`。如果没有安装 GitNexus，初始化只会给出一次推荐提示，主流程会继续执行；`fet doctor` 也会把缺失 GitNexus 作为提示性 warning，而不是阻断问题。
+
+二阶段图谱命令统一放在 `fet graph` 下：
+
+- `fet graph status`：检查 GitNexus、图谱路径和当前状态，并更新 FET 状态。
+- `fet graph setup`：生成 `.fet/graph-setup.md`，用于安装和 IDE 辅助配置引导；FET 不会自动安装 GitNexus。
+- `fet graph init`：执行 `gitnexus analyze`，用于首次构建图谱。
+- `fet graph refresh`：再次执行 `gitnexus analyze`，用于刷新图谱。
+- `fet graph doctor`：检查图谱集成健康状态，缺失只提示，不阻断 FET/OpenSpec 命令。
+- `fet graph handoff`：生成 `.fet/graph-handoff.md`，供 Cursor、Codex、OpenCode 等 IDE AI 在大范围扫描前优先参考图谱上下文。
+
+默认情况下，FET 会从 `PATH` 查找 `gitnexus`，并认为图谱目录是 `.gitnexus`。高级用户可以通过 `FET_GITNEXUS_EXECUTABLE`、`FET_GITNEXUS_COMMAND`、`FET_GITNEXUS_GRAPH_PATH` 覆盖默认行为。
+
+### Andrej Karpathy Skills
+
+`fet init` 和 `fet update-context` 会为当前工程加入一份 FET 管理的 Andrej Karpathy 风格编码指南。FET 不假设 Codex 或 OpenCode 会主动读取 `CLAUDE.md`，因此会把指南同步到 FET 自己的上下文文件中：
+
+- `CLAUDE.md`：追加或刷新 `FET:BEGIN ANDREJ-KARPATHY-SKILLS` 管理块，供 Claude Code、Codex、OpenCode 等能读取项目根文档的 AI 工具使用。
+- `.cursor/rules/karpathy-guidelines.mdc`：为 Cursor 生成项目规则。若该文件已存在且不是 FET 管理文件，FET 会保留原文件并给出 warning。
+- `.fet/karpathy-guidelines.md`：通用 IDE handoff，供 OpenCode 或其他不读取 `CLAUDE.md` 的工具显式读取。
+- `.codex/fet/karpathy-guidelines.md`：Codex 专用上下文；FET 生成的 Codex context、command guide 和 slash prompt 会明确要求读取该文件。
+
+这份指南不会复制第三方仓库全文，而是基于 `andrej-karpathy-skills` 的使用目标生成项目级精简规则：先思考、保持简单、精准修改、按目标验证。来源项目：<https://github.com/forrestchang/andrej-karpathy-skills>。
+
 ## English
 
 FET is a frontend development workflow orchestration CLI built around OpenSpec. It does not generate business code directly. Instead, it proxies OpenSpec commands, maintains local workflow state, generates auditable project context, and helps AI coding tools such as Cursor and Codex load the right files.
@@ -199,6 +225,17 @@ FET can detect an optional `gitnexus` executable during `fet init` and records t
 
 Generated Cursor and Codex instructions tell the IDE AI to prefer GitNexus graph context before broad repository scans when that context is available. FET does not install GitNexus, generate graphs, or require graph support for any command.
 
+### Andrej Karpathy Skills
+
+`fet init` and `fet update-context` add FET-managed Andrej Karpathy inspired coding guidelines. FET does not assume Codex, OpenCode, or other IDE agents will read `CLAUDE.md` automatically, so the guidelines are also written into FET-owned context files:
+
+- `CLAUDE.md` receives a managed `FET:BEGIN ANDREJ-KARPATHY-SKILLS` block for tools that do read root-level Claude guidance.
+- `.fet/karpathy-guidelines.md` is the generic handoff for OpenCode or other IDEs.
+- `.codex/fet/karpathy-guidelines.md` is the Codex-specific copy; generated Codex context, command guides, and slash prompts explicitly ask Codex to read it.
+- `.cursor/rules/karpathy-guidelines.mdc` is the Cursor project rule.
+
+The generated guidance is a concise project-level adaptation of `andrej-karpathy-skills`: think before coding, keep changes simple, edit precisely, and verify against concrete goals.
+
 Phase-two graph commands are available under `fet graph`:
 
 - `fet graph status` checks GitNexus, the configured graph path, and records the result.
@@ -262,9 +299,13 @@ FET may create or update:
 - `CHANGELOG.md`
 - `.fet/graph-setup.md`
 - `.fet/graph-handoff.md`
+- `.fet/karpathy-guidelines.md`
+- `CLAUDE.md`
 - `.cursor/skills/fet-*/SKILL.md`
 - `.cursor/rules/fet-context.mdc`
+- `.cursor/rules/karpathy-guidelines.mdc`
 - `.codex/fet/context.md`
+- `.codex/fet/karpathy-guidelines.md`
 - `.codex/fet/commands/*.md`
 - `$CODEX_HOME/prompts/fet-*.md` for Codex native slash commands. If `CODEX_HOME` is not set, FET uses `~/.codex`.
 - `.fet/fill-context.md` as a generic IDE handoff for tools without native command support.

package/dist/cli/index.js

@@ -368,6 +368,12 @@ ${routes || "| [NEEDS LLM INPUT] | [NEEDS LLM INPUT] | low |"}
 
 [NEEDS LLM INPUT]
 
+## AI Work Guidelines
+
+- Prefer the project-level Andrej Karpathy inspired guidelines in .fet/karpathy-guidelines.md when using FET-managed IDE workflows.
+- For Codex, also read .codex/fet/karpathy-guidelines.md when present.
+- Treat those guidelines as secondary to the user's latest request and explicit OpenSpec artifacts.
+
 ## Scanner Metadata
 
 - Generated At: ${scan.generatedAt}
@@ -415,6 +421,97 @@ function renderFetConfig(scan) {
   });
 }
 
+// src/templates/karpathy-skills.ts
+var KARPATHY_SKILLS_SOURCE = "https://github.com/forrestchang/andrej-karpathy-skills";
+var BEGIN = "<!-- FET:BEGIN ANDREJ-KARPATHY-SKILLS -->";
+var END = "<!-- FET:END ANDREJ-KARPATHY-SKILLS -->";
+function mergeKarpathyClaudeMd(existing) {
+  const block = renderManagedBlock(renderKarpathyClaudeGuidelines());
+  if (!existing || !existing.trim()) {
+    return `${block}
+`;
+  }
+  const start = existing.indexOf(BEGIN);
+  const end = existing.indexOf(END);
+  if (start !== -1 && end !== -1 && end > start) {
+    return `${existing.slice(0, start)}${block}${existing.slice(end + END.length)}`;
+  }
+  return `${existing.replace(/\s*$/, "")}
+
+${block}
+`;
+}
+function renderKarpathyCursorRule() {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: karpathy-skills
+FET:END -->
+
+---
+description: Andrej Karpathy inspired coding guidelines
+alwaysApply: true
+---
+
+${renderKarpathyGuidelinesBody()}
+`;
+}
+function renderKarpathyFetHandoff() {
+  return `<!-- FET:MANAGED
+schemaVersion: 1
+generator: karpathy-skills
+FET:END -->
+
+# Andrej Karpathy Inspired Coding Guidelines
+
+${renderKarpathyGuidelinesBody()}
+`;
+}
+function renderManagedBlock(content) {
+  return `${BEGIN}
+${content}
+${END}`;
+}
+function renderKarpathyClaudeGuidelines() {
+  return `# Andrej Karpathy Inspired Coding Guidelines
+
+${renderKarpathyGuidelinesBody()}`;
+}
+function renderKarpathyGuidelinesBody() {
+  return `Source: ${KARPATHY_SKILLS_SOURCE}
+
+Use these project-level guidelines together with AGENTS.md, OpenSpec artifacts, and the user's latest request.
+
+## Think Before Coding
+
+- State important assumptions before editing.
+- Ask for clarification when ambiguity would change the implementation.
+- Surface tradeoffs instead of silently choosing a risky path.
+- Push back when a simpler approach better fits the request.
+
+## Simplicity First
+
+- Solve the requested problem with the smallest clear change.
+- Avoid speculative features, configuration, or abstraction.
+- Do not create abstractions for one-off code.
+- Prefer deleting complexity introduced by your own change over adding more structure.
+
+## Precise Edits
+
+- Touch only files and lines that directly serve the task.
+- Preserve existing style even when you personally prefer another pattern.
+- Do not refactor nearby code, comments, or formatting unless the task requires it.
+- Remove only dead imports, variables, or helpers made obsolete by your own change.
+
+## Goal-Driven Execution
+
+- Convert vague work into concrete success criteria.
+- For bugs, prefer a reproducing test or clear verification before the fix.
+- For multi-step work, keep a short plan and verify each meaningful step.
+- Continue iterating until the success criteria are met or a blocker is explicit.
+
+These guidelines intentionally favor caution over speed for non-trivial work. For obvious one-line fixes, use judgment and stay lightweight.`;
+}
+
 // src/templates/verify-instructions.ts
 function renderVerifyInstructions(changeId, generatedAt = (/* @__PURE__ */ new Date()).toISOString()) {
   return `---
@@ -442,8 +539,8 @@ fet verify --done --change ${changeId}
 }
 
 // src/templates/gitignore.ts
-var BEGIN = "# FET:BEGIN LOCAL STATE";
-var END = "# FET:END LOCAL STATE";
+var BEGIN2 = "# FET:BEGIN LOCAL STATE";
+var END2 = "# FET:END LOCAL STATE";
 var RULES = [
   "openspec/fet-state.json",
   "openspec/.fet.lock",
@@ -453,17 +550,17 @@ var RULES = [
   ".gitnexus/"
 ];
 function mergeGitignore(existing) {
-  const block = `${BEGIN}
+  const block = `${BEGIN2}
 ${RULES.join("\n")}
-${END}`;
+${END2}`;
   if (!existing || !existing.trim()) {
     return `${block}
 `;
   }
-  const start = existing.indexOf(BEGIN);
-  const end = existing.indexOf(END);
+  const start = existing.indexOf(BEGIN2);
+  const end = existing.indexOf(END2);
   if (start !== -1 && end !== -1 && end > start) {
-    return `${existing.slice(0, start)}${block}${existing.slice(end + END.length)}`;
+    return `${existing.slice(0, start)}${block}${existing.slice(end + END2.length)}`;
   }
   return `${existing.replace(/\s*$/, "")}
 
@@ -529,7 +626,12 @@ async function updateContextFiles(ctx) {
   const scan = await ctx.scanner.scan(ctx.projectRoot, {});
   const agentsPath = join7(ctx.projectRoot, "AGENTS.md");
   const configPath = join7(ctx.projectRoot, "openspec", "config.yaml");
+  const claudePath = join7(ctx.projectRoot, "CLAUDE.md");
+  const karpathyHandoffPath = join7(ctx.projectRoot, ".fet", "karpathy-guidelines.md");
+  const karpathyCursorPath = join7(ctx.projectRoot, ".cursor", "rules", "karpathy-guidelines.mdc");
   const existingAgents = await readOptional(agentsPath);
+  const existingClaude = await readOptional(claudePath);
+  const existingKarpathyCursor = await readOptional(karpathyCursorPath);
   const warnings = [...scan.warnings];
   if (existingAgents && hasInvalidManagedAutoRegion(existingAgents)) {
     throw new FetError({
@@ -555,6 +657,13 @@ async function updateContextFiles(ctx) {
   }
   await atomicWrite(agentsPath, replaceManagedRegion(existingAgents, renderAgentsMd(scan)));
   await atomicWrite(configPath, await mergeFetConfig(configPath, renderFetConfig(scan)));
+  await atomicWrite(claudePath, mergeKarpathyClaudeMd(existingClaude));
+  await atomicWrite(karpathyHandoffPath, renderKarpathyFetHandoff());
+  if (!existingKarpathyCursor || existingKarpathyCursor.includes("FET:MANAGED")) {
+    await atomicWrite(karpathyCursorPath, renderKarpathyCursorRule());
+  } else {
+    warnings.push(".cursor/rules/karpathy-guidelines.mdc exists and is not managed by FET; leaving it unchanged.");
+  }
   const placeholderCount = await countAgentsLlmPlaceholders(ctx.projectRoot);
   if (placeholderCount > 0) {
     warnings.push(renderAgentsPlaceholderWarning(placeholderCount));
@@ -804,11 +913,12 @@ FET:END -->
 Use the IDE AI to complete FET-generated placeholders.
 
 1. Read AGENTS.md and openspec/config.yaml.
-2. Inspect README files, package scripts, routes, tests, source layout, and project conventions.
-3. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete project-specific content.
-4. Preserve FET managed markers.
-5. Do not modify business code.
-6. Run \`fet doctor\` and confirm no AGENTS.md placeholder warning remains.
+2. Read .fet/karpathy-guidelines.md when it exists. For Codex, also read .codex/fet/karpathy-guidelines.md when it exists.
+3. Inspect README files, package scripts, routes, tests, source layout, and project conventions.
+4. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete project-specific content.
+5. Preserve FET managed markers.
+6. Do not modify business code.
+7. Run \`fet doctor\` and confirm no AGENTS.md placeholder warning remains.
 `;
 }
 
@@ -1796,6 +1906,7 @@ Before doing FET or OpenSpec work in Codex, read:
 
 - AGENTS.md
 - openspec/config.yaml
+- .codex/fet/karpathy-guidelines.md
 - the active change files under openspec/changes/<change-id>/, when a change is selected
 
 If GitNexus code graph context is available in the IDE or MCP tools, prefer it before broad repository scans. Use it to identify relevant modules, dependencies, and insertion points, then read only the concrete source files needed. If GitNexus is unavailable, continue with the normal FET/OpenSpec workflow.
@@ -1807,10 +1918,13 @@ Command guides live in .codex/fet/commands/.
   };
 }
 function codexCommandFiles() {
-  return FET_ADAPTER_COMMANDS.map((command) => ({
-    path: `.codex/fet/commands/${command}.md`,
-    content: renderCommand(command)
-  }));
+  return [
+    codexKarpathyGuidelinesFile(),
+    ...FET_ADAPTER_COMMANDS.map((command) => ({
+      path: `.codex/fet/commands/${command}.md`,
+      content: renderCommand(command)
+    }))
+  ];
 }
 function codexSlashPromptFiles() {
   return FET_ADAPTER_COMMANDS.map((command) => ({
@@ -1818,6 +1932,22 @@ function codexSlashPromptFiles() {
     content: renderSlashPrompt(command)
   }));
 }
+function codexKarpathyGuidelinesFile() {
+  return {
+    path: ".codex/fet/karpathy-guidelines.md",
+    content: `<!-- FET:MANAGED
+schemaVersion: 1
+fetVersion: ${FET_VERSION}
+generator: codex-adapter
+adapterVersion: 1
+FET:END -->
+
+# Andrej Karpathy Inspired Coding Guidelines
+
+${renderKarpathyGuidelinesBody()}
+`
+  };
+}
 function renderCommand(command) {
   if (command === "fill-context") {
     return renderFillContextCommand();
@@ -1843,6 +1973,8 @@ ${renderIdeModelPolicy(command)}
 
 When the user asks Codex to run the FET ${command} workflow, first make sure the project context is loaded from AGENTS.md and openspec/config.yaml.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally.
 
 Then run:
@@ -1871,6 +2003,8 @@ ${renderIdeModelPolicy("passthrough")}
 
 When the user asks Codex to run an OpenSpec command that FET does not manage as a first-class workflow command, use FET passthrough instead of calling OpenSpec directly.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally.
 
 Then run:
@@ -1899,6 +2033,8 @@ ${renderIdeModelPolicy(command)}
 
 When the user asks Codex to work with optional GitNexus graph support, use FET as the entry point.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally.
 
 Run:
@@ -1970,6 +2106,8 @@ Use FET as the entry point for this OpenSpec workflow.
 
 Before running the command, make sure the relevant project context is loaded from AGENTS.md and openspec/config.yaml. If a change id is needed and was not provided, infer it from the active FET/OpenSpec state when unambiguous; otherwise ask the user for the change id.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally.
 
 Run:
@@ -1996,6 +2134,8 @@ ${renderIdeModelPolicy("fill-context")}
 
 Use this command to complete FET-generated project context placeholders with Codex.
 
+Also read .codex/fet/karpathy-guidelines.md and follow it unless it conflicts with the user's latest request or OpenSpec artifacts.
+
 If GitNexus graph context is available, consult it before broad source scans and use it to narrow the files you read. If it is unavailable, continue normally.
 
 First run:
@@ -2020,16 +2160,17 @@ Steps:
    fet fill-context
    \`\`\`
 2. Read AGENTS.md and openspec/config.yaml.
-3. Inspect the project to understand:
+3. Read .codex/fet/karpathy-guidelines.md.
+4. Inspect the project to understand:
    - source structure and major modules
    - framework and routing conventions
    - scripts, test commands, and build commands
    - coding conventions and project-specific patterns
    - important docs such as README files
-4. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete, concise project-specific content.
-5. Preserve FET managed markers such as \`FET:BEGIN AUTO\`, \`FET:END AUTO\`, \`FET:BEGIN USER\`, and \`FET:END USER\`.
-6. Do not modify business code.
-7. Run:
+5. Replace every \`[NEEDS LLM INPUT]\` or \`[NEED LLM INPUT]\` placeholder in AGENTS.md with concrete, concise project-specific content.
+6. Preserve FET managed markers such as \`FET:BEGIN AUTO\`, \`FET:END AUTO\`, \`FET:BEGIN USER\`, and \`FET:END USER\`.
+7. Do not modify business code.
+8. Run:
    \`\`\`sh
    fet doctor
    \`\`\`