first-tree 0.0.2 → 0.0.4

package/skills/first-tree/engine/repo.ts

@@ -0,0 +1,360 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import {
+  AGENT_INSTRUCTIONS_FILE,
+  FRAMEWORK_VERSION,
+  LEGACY_SKILL_PROGRESS,
+  LEGACY_SKILL_VERSION,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
+  LEGACY_PROGRESS,
+  LEGACY_VERSION,
+  INSTALLED_PROGRESS,
+  agentInstructionsFileCandidates,
+  type FrameworkLayout,
+  detectFrameworkLayout,
+  frameworkVersionCandidates,
+  progressFileCandidates,
+  resolveFirstExistingPath,
+} from "#skill/engine/runtime/asset-loader.js";
+
+const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
+const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
+const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
+const EMPTY_REPO_ENTRY_ALLOWLIST = new Set([
+  ".DS_Store",
+  ".editorconfig",
+  ".gitattributes",
+  ".github",
+  ".gitignore",
+  "AGENT.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "LICENSE",
+  "LICENSE.md",
+  "LICENSE.txt",
+  "README",
+  "README.md",
+  "README.txt",
+]);
+const SOURCE_FILE_HINTS = new Set([
+  ".gitmodules",
+  "Cargo.toml",
+  "Dockerfile",
+  "Gemfile",
+  "Makefile",
+  "bun.lock",
+  "bun.lockb",
+  "docker-compose.yml",
+  "go.mod",
+  "package-lock.json",
+  "package.json",
+  "pnpm-lock.yaml",
+  "pyproject.toml",
+  "requirements.txt",
+  "tsconfig.json",
+  "uv.lock",
+  "vite.config.ts",
+  "vite.config.js",
+]);
+const SOURCE_DIR_HINTS = new Set([
+  "app",
+  "apps",
+  "backend",
+  "cli",
+  "client",
+  "docs",
+  "e2e",
+  "frontend",
+  "lib",
+  "packages",
+  "scripts",
+  "server",
+  "src",
+  "test",
+  "tests",
+]);
+
+export const FRAMEWORK_BEGIN_MARKER = "<!-- BEGIN CONTEXT-TREE FRAMEWORK";
+export const FRAMEWORK_END_MARKER = "<!-- END CONTEXT-TREE FRAMEWORK -->";
+
+export interface Frontmatter {
+  title?: string;
+  owners?: string[];
+}
+
+function hasGitMetadata(root: string): boolean {
+  try {
+    const stat = statSync(join(root, ".git"));
+    return stat.isDirectory() || stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function discoverGitRoot(start: string): string | null {
+  let dir = start;
+  while (true) {
+    if (hasGitMetadata(dir)) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+
+export class Repo {
+  readonly root: string;
+
+  constructor(root?: string) {
+    const start = resolve(root ?? process.cwd());
+    this.root = root === undefined ? discoverGitRoot(start) ?? start : start;
+  }
+
+  pathExists(relPath: string): boolean {
+    return existsSync(join(this.root, relPath));
+  }
+
+  fileContains(relPath: string, text: string): boolean {
+    const fullPath = join(this.root, relPath);
+    try {
+      const stat = statSync(fullPath);
+      if (!stat.isFile()) return false;
+      return readFileSync(fullPath, "utf-8").includes(text);
+    } catch {
+      return false;
+    }
+  }
+
+  readFile(relPath: string): string | null {
+    try {
+      return readFileSync(join(this.root, relPath), "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  frontmatter(relPath: string): Frontmatter | null {
+    const text = this.readFile(relPath);
+    if (text === null) return null;
+    const m = text.match(FRONTMATTER_RE);
+    if (!m) return null;
+    const fm = m[1];
+    const result: Frontmatter = {};
+    const titleM = fm.match(TITLE_RE);
+    if (titleM) {
+      result.title = titleM[1].trim();
+    }
+    const ownersM = fm.match(OWNERS_RE);
+    if (ownersM) {
+      const raw = ownersM[1].trim();
+      result.owners = raw
+        ? raw.split(",").map((o) => o.trim()).filter(Boolean)
+        : [];
+    }
+    return result.title !== undefined || result.owners !== undefined
+      ? result
+      : null;
+  }
+
+  anyAgentConfig(): boolean {
+    const knownConfigs = [".claude/settings.json", ".codex/config.json"];
+    return knownConfigs.some((c) => this.pathExists(c));
+  }
+
+  isGitRepo(): boolean {
+    return hasGitMetadata(this.root);
+  }
+
+  hasFramework(): boolean {
+    return this.frameworkLayout() !== null;
+  }
+
+  frameworkLayout(): FrameworkLayout | null {
+    return detectFrameworkLayout(this.root);
+  }
+
+  readVersion(): string | null {
+    const versionPath = resolveFirstExistingPath(
+      this.root,
+      frameworkVersionCandidates(),
+    );
+    if (versionPath === null) return null;
+    const text = this.readFile(versionPath);
+    return text ? text.trim() : null;
+  }
+
+  progressPath(): string | null {
+    return resolveFirstExistingPath(this.root, progressFileCandidates());
+  }
+
+  preferredProgressPath(): string {
+    const layout = this.frameworkLayout();
+    if (layout === "legacy") {
+      return LEGACY_PROGRESS;
+    }
+    if (layout === "legacy-skill") {
+      return LEGACY_SKILL_PROGRESS;
+    }
+    return INSTALLED_PROGRESS;
+  }
+
+  frameworkVersionPath(): string {
+    const layout = this.frameworkLayout();
+    if (layout === "legacy") {
+      return LEGACY_VERSION;
+    }
+    if (layout === "legacy-skill") {
+      return LEGACY_SKILL_VERSION;
+    }
+    return FRAMEWORK_VERSION;
+  }
+
+  agentInstructionsPath(): string | null {
+    return resolveFirstExistingPath(this.root, agentInstructionsFileCandidates());
+  }
+
+  hasCanonicalAgentInstructionsFile(): boolean {
+    return this.pathExists(AGENT_INSTRUCTIONS_FILE);
+  }
+
+  hasLegacyAgentInstructionsFile(): boolean {
+    return this.pathExists(LEGACY_AGENT_INSTRUCTIONS_FILE);
+  }
+
+  hasDuplicateAgentInstructionsFiles(): boolean {
+    return this.hasCanonicalAgentInstructionsFile() && this.hasLegacyAgentInstructionsFile();
+  }
+
+  readAgentInstructions(): string | null {
+    const relPath = this.agentInstructionsPath();
+    if (relPath === null) return null;
+    return this.readFile(relPath);
+  }
+
+  hasAgentInstructionsMarkers(): boolean {
+    const text = this.readAgentInstructions();
+    if (text === null) return false;
+    return text.includes(FRAMEWORK_BEGIN_MARKER) && text.includes(FRAMEWORK_END_MARKER);
+  }
+
+  hasMembers(): boolean {
+    const membersDir = join(this.root, "members");
+    try {
+      if (!statSync(membersDir).isDirectory()) return false;
+    } catch {
+      return false;
+    }
+    return existsSync(join(membersDir, "NODE.md"));
+  }
+
+  memberCount(): number {
+    const membersDir = join(this.root, "members");
+    try {
+      if (!statSync(membersDir).isDirectory()) return 0;
+    } catch {
+      return 0;
+    }
+    let count = 0;
+    const walk = (dir: string): void => {
+      for (const entry of readdirSync(dir)) {
+        const childPath = join(dir, entry);
+        try {
+          if (!statSync(childPath).isDirectory()) continue;
+        } catch {
+          continue;
+        }
+        if (existsSync(join(childPath, "NODE.md"))) {
+          count++;
+        }
+        walk(childPath);
+      }
+    };
+    walk(membersDir);
+    return count;
+  }
+
+  hasPlaceholderNode(): boolean {
+    return this.fileContains("NODE.md", "<!-- PLACEHOLDER");
+  }
+
+  repoName(): string {
+    return basename(this.root);
+  }
+
+  topLevelEntries(): string[] {
+    try {
+      return readdirSync(this.root).filter((entry) => entry !== ".git");
+    } catch {
+      return [];
+    }
+  }
+
+  looksLikeTreeRepo(): boolean {
+    if (
+      this.pathExists("package.json")
+      && this.pathExists("src/cli.ts")
+      && this.pathExists("skills/first-tree/SKILL.md")
+      && this.progressPath() === null
+      && this.frontmatter("NODE.md") === null
+      && !this.hasAgentInstructionsMarkers()
+      && !this.pathExists("members/NODE.md")
+    ) {
+      return false;
+    }
+
+    return (
+      this.progressPath() !== null
+      || this.hasFramework()
+      || this.hasAgentInstructionsMarkers()
+      || this.pathExists("members/NODE.md")
+      || this.frontmatter("NODE.md") !== null
+    );
+  }
+
+  isLikelyEmptyRepo(): boolean {
+    const relevant = this.topLevelEntries().filter(
+      (entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry),
+    );
+    return relevant.length === 0;
+  }
+
+  isLikelySourceRepo(): boolean {
+    if (this.looksLikeTreeRepo()) {
+      return false;
+    }
+
+    const entries = this.topLevelEntries().filter(
+      (entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry),
+    );
+    if (entries.length === 0) {
+      return false;
+    }
+
+    let directoryCount = 0;
+
+    for (const entry of entries) {
+      if (SOURCE_FILE_HINTS.has(entry)) {
+        return true;
+      }
+      if (isDirectory(this.root, entry)) {
+        directoryCount += 1;
+        if (SOURCE_DIR_HINTS.has(entry)) {
+          return true;
+        }
+      }
+    }
+
+    return directoryCount >= 2 || entries.length >= 4;
+  }
+}
+
+function isDirectory(root: string, relPath: string): boolean {
+  try {
+    return statSync(join(root, relPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/skills/first-tree/engine/rules/agent-instructions.ts

@@ -0,0 +1,59 @@
+import { FRAMEWORK_END_MARKER } from "#skill/engine/repo.js";
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import {
+  AGENT_INSTRUCTIONS_FILE,
+  AGENT_INSTRUCTIONS_TEMPLATE,
+  FRAMEWORK_TEMPLATES_DIR,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  const hasCanonicalInstructions = repo.hasCanonicalAgentInstructionsFile();
+  const hasLegacyInstructions = repo.hasLegacyAgentInstructionsFile();
+
+  if (!hasCanonicalInstructions && !hasLegacyInstructions) {
+    tasks.push(
+      `${AGENT_INSTRUCTIONS_FILE} is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/${AGENT_INSTRUCTIONS_TEMPLATE}\``,
+    );
+    return { group: "Agent Instructions", order: 3, tasks };
+  }
+
+  if (hasCanonicalInstructions && hasLegacyInstructions) {
+    tasks.push(
+      `Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`,
+    );
+  } else if (hasLegacyInstructions) {
+    tasks.push(
+      `Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`,
+    );
+  }
+
+  const instructionsPath = repo.agentInstructionsPath() ?? AGENT_INSTRUCTIONS_FILE;
+  if (!repo.hasAgentInstructionsMarkers()) {
+    tasks.push(
+      `\`${instructionsPath}\` exists but is missing framework markers — add \`<!-- BEGIN CONTEXT-TREE FRAMEWORK -->\` and \`<!-- END CONTEXT-TREE FRAMEWORK -->\` sections`,
+    );
+  } else {
+    const text = repo.readAgentInstructions() ?? "";
+    const afterMarker = text.split(FRAMEWORK_END_MARKER);
+    if (afterMarker.length > 1) {
+      const userSection = afterMarker[1].trim();
+      const lines = userSection
+        .split("\n")
+        .filter(
+          (l) =>
+            l.trim() &&
+            !l.trim().startsWith("#") &&
+            !l.trim().startsWith("<!--"),
+        );
+      if (lines.length === 0) {
+        tasks.push(
+          `Add your project-specific instructions below the framework markers in ${AGENT_INSTRUCTIONS_FILE}`,
+        );
+      }
+    }
+  }
+  return { group: "Agent Instructions", order: 3, tasks };
+}

package/skills/first-tree/engine/rules/agent-integration.ts

@@ -0,0 +1,19 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { FRAMEWORK_EXAMPLES_DIR } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (repo.pathExists(".claude/settings.json")) {
+    if (!repo.fileContains(".claude/settings.json", "inject-tree-context")) {
+      tasks.push(
+        `Add SessionStart hook to \`.claude/settings.json\` (see \`${FRAMEWORK_EXAMPLES_DIR}/claude-code/\`)`,
+      );
+    }
+  } else if (!repo.anyAgentConfig()) {
+    tasks.push(
+      `No agent configuration detected. Configure your agent to load tree context at session start. See \`${FRAMEWORK_EXAMPLES_DIR}/\` for supported agents. You can skip this and set it up later.`,
+    );
+  }
+  return { group: "Agent Integration", order: 5, tasks };
+}

package/skills/first-tree/engine/rules/ci-validation.ts

@@ -0,0 +1,72 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { INTERACTIVE_TOOL } from "#skill/engine/init.js";
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { FRAMEWORK_WORKFLOWS_DIR } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  let hasValidation = false;
+  let hasPrReview = false;
+  let hasCodeowners = false;
+  const workflowsDir = join(repo.root, ".github", "workflows");
+  try {
+    if (statSync(workflowsDir).isDirectory()) {
+      for (const name of readdirSync(workflowsDir)) {
+        if (!name.endsWith(".yml") && !name.endsWith(".yaml")) continue;
+        const fullPath = join(workflowsDir, name);
+        try {
+          if (!statSync(fullPath).isFile()) continue;
+          const content = readFileSync(fullPath, "utf-8");
+          if (
+            content.includes("validate_nodes") ||
+            content.includes("validate_members")
+          ) {
+            hasValidation = true;
+          }
+          if (content.includes("run-review")) {
+            hasPrReview = true;
+          }
+          if (content.includes("generate-codeowners")) {
+            hasCodeowners = true;
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  } catch {
+    // workflows dir doesn't exist
+  }
+  if (!hasValidation) {
+    tasks.push(
+      `No validation workflow found — copy \`${FRAMEWORK_WORKFLOWS_DIR}/validate.yml\` to \`.github/workflows/validate.yml\``,
+    );
+  }
+  if (!hasPrReview) {
+    tasks.push(
+      `Use ${INTERACTIVE_TOOL} to ask whether the user wants AI-powered PR reviews. Options:\n` +
+      "  1. **OpenRouter** — use an OpenRouter API key\n" +
+      "  2. **Claude API** — use a Claude API key directly\n" +
+      "  3. **Skip** — do not set up PR reviews\n" +
+      `If (1): copy \`${FRAMEWORK_WORKFLOWS_DIR}/pr-review.yml\` to \`.github/workflows/pr-review.yml\` as-is; the repo secret name is \`OPENROUTER_API_KEY\`. ` +
+      "If (2): copy the workflow and replace the `env` block with `ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}`, remove the `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, and `ANTHROPIC_DEFAULT_SONNET_MODEL` lines; the repo secret name is `ANTHROPIC_API_KEY`. " +
+      "If (3): skip this and the next task.",
+    );
+    tasks.push(
+      `Use ${INTERACTIVE_TOOL} to ask how the user wants to configure the API secret. Options:\n` +
+      "  1. **Set it now** — provide the key and the agent will run `gh secret set <SECRET_NAME> --body <KEY>`\n" +
+      "  2. **I'll do it myself** — the agent will show manual instructions\n" +
+      "If (1): ask the user to provide the key, then run `gh secret set` with the secret name from the previous step. " +
+      "If (2): tell the user to go to their repo → Settings → Secrets and variables → Actions → New repository secret, and create the secret with the name from the previous step. " +
+      "Skip this task if the user chose Skip in the previous step.",
+    );
+  }
+  if (!hasCodeowners) {
+    tasks.push(
+      `No CODEOWNERS workflow found — copy \`${FRAMEWORK_WORKFLOWS_DIR}/codeowners.yml\` to \`.github/workflows/codeowners.yml\` to auto-generate CODEOWNERS from tree ownership on every PR.`,
+    );
+  }
+  return { group: "CI / Validation", order: 6, tasks };
+}

package/skills/first-tree/engine/rules/framework.ts

@@ -0,0 +1,13 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { SKILL_ROOT } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (!repo.hasFramework()) {
+    tasks.push(
+      `\`${SKILL_ROOT}/\` not found — run \`context-tree init\` to install the framework skill bundled with the current \`first-tree\` package`,
+    );
+  }
+  return { group: "Framework", order: 1, tasks };
+}

package/skills/first-tree/engine/rules/index.ts

@@ -0,0 +1,41 @@
+import type { Repo } from "#skill/engine/repo.js";
+import * as agentInstructions from "#skill/engine/rules/agent-instructions.js";
+import * as agentIntegration from "#skill/engine/rules/agent-integration.js";
+import * as ciValidation from "#skill/engine/rules/ci-validation.js";
+import * as framework from "#skill/engine/rules/framework.js";
+import * as members from "#skill/engine/rules/members.js";
+import * as populateTree from "#skill/engine/rules/populate-tree.js";
+import * as rootNode from "#skill/engine/rules/root-node.js";
+
+export interface RuleResult {
+  group: string;
+  order: number;
+  tasks: string[];
+}
+
+interface Rule {
+  evaluate(repo: Repo): RuleResult;
+}
+
+const ALL_RULES: Rule[] = [
+  framework,
+  rootNode,
+  agentInstructions,
+  members,
+  agentIntegration,
+  ciValidation,
+  populateTree,
+];
+
+export function evaluateAll(repo: Repo): RuleResult[] {
+  const results: RuleResult[] = [];
+  for (const rule of ALL_RULES) {
+    const result = rule.evaluate(repo);
+    if (result.tasks.length > 0) {
+      results.push(result);
+    }
+  }
+  return results.sort((a, b) => a.order - b.order);
+}
+
+export { framework, rootNode, agentInstructions, members, agentIntegration, ciValidation, populateTree };

package/skills/first-tree/engine/rules/members.ts

@@ -0,0 +1,21 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (!repo.pathExists("members")) {
+    tasks.push("`members/` directory is missing — create it with a NODE.md");
+  } else if (!repo.pathExists("members/NODE.md")) {
+    tasks.push("`members/NODE.md` is missing — create it from the template");
+  }
+  if (repo.hasMembers() && repo.memberCount() === 0) {
+    tasks.push(
+      "Add at least one member node under `members/`. Analyze the user's code repositories (git history, CODEOWNERS, README contributors) to suggest members, then confirm with the user",
+    );
+  } else if (!repo.hasMembers()) {
+    tasks.push(
+      "Add at least one member node under `members/`. Analyze the user's code repositories (git history, CODEOWNERS, README contributors) to suggest members, then confirm with the user",
+    );
+  }
+  return { group: "Members", order: 4, tasks };
+}

package/skills/first-tree/engine/rules/populate-tree.ts

@@ -0,0 +1,36 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { INTERACTIVE_TOOL } from "#skill/engine/init.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+
+  tasks.push(
+    `Ask the user whether they want to populate the full context tree now using the **${INTERACTIVE_TOOL}** tool. ` +
+      "Present two options: (1) **Yes — populate the full tree**: the agent will analyze source repositories, " +
+      "create sub-domains, and populate NODE.md files for each domain and sub-domain; " +
+      "(2) **No — I'll do it later**: skip deep population and finish init with just the top-level structure. " +
+      "If the user selects No, check off all remaining items in this section and move on.",
+  );
+
+  tasks.push(
+    "If the user selected Yes: analyze the codebase (and any additional repositories the user provides) to identify " +
+      "logical sub-domains within each top-level domain. For each sub-domain, create a directory with a NODE.md " +
+      "containing proper frontmatter (title, owners) and a description of the sub-domain's purpose, boundaries, " +
+      "and key decisions. Create deeper sub-domains when a domain is large enough to warrant further decomposition.",
+  );
+
+  tasks.push(
+    "Use **sub-tasks** (TaskCreate) to parallelize the population work — create one sub-task per top-level domain " +
+      "so each domain can be populated concurrently. Each sub-task should: read the relevant source code, identify " +
+      "sub-domains, create NODE.md files, and establish soft_links between related domains.",
+  );
+
+  tasks.push(
+    "After all domains are populated, update the root NODE.md to list every top-level domain with a one-line " +
+      "description. Ensure all NODE.md files pass `context-tree verify` — valid frontmatter, no placeholders, " +
+      "and soft_links that resolve correctly.",
+  );
+
+  return { group: "Populate Tree", order: 7, tasks };
+}

package/skills/first-tree/engine/rules/root-node.ts

@@ -0,0 +1,41 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { FRAMEWORK_TEMPLATES_DIR } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (!repo.pathExists("NODE.md")) {
+    tasks.push(
+      `NODE.md is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/root-node.md.template\`. ` +
+      "Ask the user for their code repositories or project directories, then analyze the source to determine the project description and domain structure",
+    );
+  } else {
+    const fm = repo.frontmatter("NODE.md");
+    if (fm === null) {
+      tasks.push(
+        "NODE.md exists but has no frontmatter — add frontmatter with title and owners fields",
+      );
+    } else {
+      if (!fm.title || fm.title.startsWith("<")) {
+        tasks.push(
+          "NODE.md has a placeholder title — replace with your organization name",
+        );
+      }
+      if (
+        !fm.owners ||
+        fm.owners.length === 0 ||
+        (fm.owners.length === 1 && fm.owners[0].startsWith("<"))
+      ) {
+        tasks.push(
+          "NODE.md has placeholder owners — set owners to your GitHub username(s)",
+        );
+      }
+    }
+    if (repo.hasPlaceholderNode()) {
+      tasks.push(
+        "NODE.md has placeholder content — ask the user for their code repositories or project directories, then analyze the source to fill in the project description and domain structure",
+      );
+    }
+  }
+  return { group: "Root Node", order: 2, tasks };
+}

package/skills/first-tree/engine/runtime/adapters.ts

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import {
+  FRAMEWORK_EXAMPLES_DIR,
+  FRAMEWORK_HELPERS_DIR,
+  LEGACY_SKILL_EXAMPLES_DIR,
+  LEGACY_EXAMPLES_DIR,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
+export const CODEX_CONFIG_PATH = ".codex/config.json";
+
+export function claudeCodeExampleCandidates(): string[] {
+  return [
+    join(FRAMEWORK_EXAMPLES_DIR, "claude-code"),
+    join(LEGACY_SKILL_EXAMPLES_DIR, "claude-code"),
+    join(LEGACY_EXAMPLES_DIR, "claude-code"),
+  ];
+}
+
+export function injectTreeContextHint(): string {
+  return join(FRAMEWORK_HELPERS_DIR, "inject-tree-context.sh");
+}