first-tree 0.0.3 → 0.0.4

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

@@ -1,9 +1,12 @@
+import { execFileSync } from "node:child_process";
 import {
   existsSync,
   mkdirSync,
+  readdirSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { Repo } from "#skill/engine/repo.js";
 import { ONBOARDING_TEXT } from "#skill/engine/onboarding.js";
 import { evaluateAll } from "#skill/engine/rules/index.js";
@@ -14,9 +17,12 @@ import {
   resolveBundledPackageRoot,
 } from "#skill/engine/runtime/installer.js";
 import {
+  AGENT_INSTRUCTIONS_FILE,
+  AGENT_INSTRUCTIONS_TEMPLATE,
   FRAMEWORK_ASSET_ROOT,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
+  LEGACY_AGENT_INSTRUCTIONS_FILE,
 } from "#skill/engine/runtime/asset-loader.js";
 
 /**
@@ -25,13 +31,39 @@ import {
  * all generated task text at once.
  */
 export const INTERACTIVE_TOOL = "AskUserQuestion";
+export const INIT_USAGE = `usage: context-tree init [--here] [--tree-name NAME] [--tree-path PATH]
 
-const TEMPLATE_MAP: [string, string][] = [
-  ["root-node.md.template", "NODE.md"],
-  ["agent.md.template", "AGENT.md"],
-  ["members-domain.md.template", "members/NODE.md"],
+By default, running \`context-tree init\` inside a source or workspace repo creates
+a sibling dedicated tree repo named \`<repo>-context\`.
+
+Options:
+  --here             Initialize the current repo in place
+  --tree-name NAME   Name the dedicated sibling tree repo to create
+  --tree-path PATH   Use an explicit tree repo path
+  --help             Show this help message
+`;
+
+interface TemplateTarget {
+  templateName: string;
+  targetPath: string;
+  skipIfExists?: string[];
+}
+
+const TEMPLATE_MAP: TemplateTarget[] = [
+  { templateName: "root-node.md.template", targetPath: "NODE.md" },
+  {
+    templateName: AGENT_INSTRUCTIONS_TEMPLATE,
+    targetPath: AGENT_INSTRUCTIONS_FILE,
+    skipIfExists: [AGENT_INSTRUCTIONS_FILE, LEGACY_AGENT_INSTRUCTIONS_FILE],
+  },
+  { templateName: "members-domain.md.template", targetPath: "members/NODE.md" },
 ];
 
+interface TaskListContext {
+  sourceRepoPath?: string;
+  dedicatedTreeRepo?: boolean;
+}
+
 function installSkill(source: string, target: string): void {
   copyCanonicalSkill(source, target);
   console.log(
@@ -41,18 +73,46 @@ function installSkill(source: string, target: string): void {
 
 function renderTemplates(target: string): void {
   const frameworkDir = join(target, FRAMEWORK_ASSET_ROOT);
-  for (const [templateName, targetPath] of TEMPLATE_MAP) {
-    if (existsSync(join(target, targetPath))) {
-      console.log(`  Skipped ${targetPath} (already exists)`);
+  for (const { templateName, targetPath, skipIfExists } of TEMPLATE_MAP) {
+    const existingPaths = skipIfExists ?? [targetPath];
+    const existingPath = existingPaths.find((candidate) =>
+      existsSync(join(target, candidate)),
+    );
+
+    if (existingPath !== undefined) {
+      console.log(`  Skipped ${targetPath} (found existing ${existingPath})`);
     } else if (renderTemplateFile(frameworkDir, templateName, target, targetPath)) {
       console.log(`  Created ${targetPath}`);
     }
   }
 }
 
-export function formatTaskList(groups: RuleResult[]): string {
+export function formatTaskList(
+  groups: RuleResult[],
+  context?: TaskListContext,
+): string {
   const lines: string[] = [
     "# Context Tree Init\n",
+  ];
+
+  if (context?.dedicatedTreeRepo) {
+    lines.push(
+      "This repository is the dedicated Context Tree. Keep decisions, rationale," +
+        " cross-domain relationships, and ownership here; keep execution detail" +
+        " in your source repositories.",
+      "",
+    );
+    if (context.sourceRepoPath) {
+      lines.push(`**Bootstrap source repo:** \`${context.sourceRepoPath}\``, "");
+    }
+    lines.push(
+      "When you publish this tree repo, keep it in the same GitHub organization" +
+        " as the source repo unless you have a reason not to.",
+      "",
+    );
+  }
+
+  lines.push(
     "**Agent instructions:** Before starting work, analyze the full task list below and" +
       " identify all information you need from the user. Ask the user for their code" +
       " repositories or project directories so you can analyze the source yourself —" +
@@ -61,7 +121,7 @@ export function formatTaskList(groups: RuleResult[]): string {
       ` **${INTERACTIVE_TOOL}** tool with structured options — present selectable choices` +
       " (with label and description) so the user can pick instead of typing free-form" +
       ` answers. You may batch up to 4 questions per ${INTERACTIVE_TOOL} call.\n`,
-  ];
+  );
   for (const group of groups) {
     lines.push(`## ${group.group}`);
     for (const task of group.tasks) {
@@ -75,7 +135,9 @@ export function formatTaskList(groups: RuleResult[]): string {
   );
   lines.push(`- [ ] \`${FRAMEWORK_VERSION}\` exists`);
   lines.push("- [ ] Root NODE.md has valid frontmatter (title, owners)");
-  lines.push("- [ ] AGENT.md exists with framework markers");
+  lines.push(
+    `- [ ] \`${AGENT_INSTRUCTIONS_FILE}\` is the only agent instructions file and has framework markers`,
+  );
   lines.push("- [ ] `context-tree verify` passes with no errors");
   lines.push("- [ ] At least one member node exists");
   lines.push("");
@@ -99,17 +161,42 @@ export function writeProgress(repo: Repo, content: string): void {
 
 export interface InitOptions {
   sourceRoot?: string;
+  here?: boolean;
+  treeName?: string;
+  treePath?: string;
+  currentCwd?: string;
+  gitInitializer?: (root: string) => void;
 }
 
 export function runInit(repo?: Repo, options?: InitOptions): number {
-  const r = repo ?? new Repo();
-
-  if (!r.isGitRepo()) {
+  const sourceRepo = repo ?? new Repo();
+  const initTarget = resolveInitTarget(sourceRepo, options);
+  if (initTarget.ok === false) {
     console.error(
-      "Error: not a git repository. Initialize one first:\n  git init",
+      `Error: ${initTarget.message}`,
     );
     return 1;
   }
+  const r = initTarget.repo;
+  const taskListContext = initTarget.dedicatedTreeRepo
+    ? {
+        dedicatedTreeRepo: true,
+        sourceRepoPath: relativePathFrom(r.root, sourceRepo.root),
+      }
+    : undefined;
+
+  if (initTarget.dedicatedTreeRepo) {
+    console.log(
+      "Recommended workflow: keep the Context Tree in a dedicated repo separate" +
+        " from your source/workspace repo.",
+    );
+    console.log(`  Source repo: ${sourceRepo.root}`);
+    console.log(`  Tree repo:   ${r.root}`);
+    if (initTarget.createdGitRepo) {
+      console.log("  Initialized a new git repo for the tree.");
+    }
+    console.log();
+  }
 
   if (!r.hasFramework()) {
     try {
@@ -137,9 +224,191 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
     return 0;
   }
 
-  const output = formatTaskList(groups);
+  const output = formatTaskList(groups, taskListContext);
   console.log(output);
   writeProgress(r, output);
   console.log(`Progress file written to ${r.preferredProgressPath()}`);
+  if (initTarget.dedicatedTreeRepo) {
+    console.log(
+      `Continue in ${relativePathFrom(sourceRepo.root, r.root)} and keep your source repos available as additional working directories when you populate the tree.`,
+    );
+  }
   return 0;
 }
+
+export interface ParsedInitArgs {
+  here?: boolean;
+  treeName?: string;
+  treePath?: string;
+}
+
+export function parseInitArgs(
+  args: string[],
+): ParsedInitArgs | { error: string } {
+  const parsed: ParsedInitArgs = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    switch (arg) {
+      case "--here":
+        parsed.here = true;
+        break;
+      case "--tree-name": {
+        const value = args[index + 1];
+        if (!value) {
+          return { error: "Missing value for --tree-name" };
+        }
+        parsed.treeName = value;
+        index += 1;
+        break;
+      }
+      case "--tree-path": {
+        const value = args[index + 1];
+        if (!value) {
+          return { error: "Missing value for --tree-path" };
+        }
+        parsed.treePath = value;
+        index += 1;
+        break;
+      }
+      default:
+        return { error: `Unknown init option: ${arg}` };
+    }
+  }
+
+  if (parsed.here && parsed.treeName) {
+    return { error: "Cannot combine --here with --tree-name" };
+  }
+  if (parsed.here && parsed.treePath) {
+    return { error: "Cannot combine --here with --tree-path" };
+  }
+  if (parsed.treeName && parsed.treePath) {
+    return { error: "Cannot combine --tree-name with --tree-path" };
+  }
+
+  return parsed;
+}
+
+export function runInitCli(args: string[] = []): number {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(INIT_USAGE);
+    return 0;
+  }
+
+  const parsed = parseInitArgs(args);
+  if ("error" in parsed) {
+    console.error(parsed.error);
+    console.log(INIT_USAGE);
+    return 1;
+  }
+
+  return runInit(undefined, parsed);
+}
+
+interface ResolvedInitTarget {
+  ok: true;
+  createdGitRepo: boolean;
+  dedicatedTreeRepo: boolean;
+  repo: Repo;
+}
+
+interface FailedInitTarget {
+  message: string;
+  ok: false;
+}
+
+function resolveInitTarget(
+  sourceRepo: Repo,
+  options?: InitOptions,
+): FailedInitTarget | ResolvedInitTarget {
+  if (!sourceRepo.isGitRepo()) {
+    return {
+      ok: false,
+      message:
+        "not a git repository. Run this from your source/workspace repo, or create a dedicated tree repo first:\n  git init\n  context-tree init --here",
+    };
+  }
+
+  const targetRoot = determineTargetRoot(sourceRepo, options);
+  const dedicatedTreeRepo = targetRoot !== sourceRepo.root;
+  let createdGitRepo = false;
+  try {
+    createdGitRepo = ensureGitRepo(targetRoot, options?.gitInitializer);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "unknown error";
+    return {
+      ok: false,
+      message,
+    };
+  }
+
+  return {
+    ok: true,
+    createdGitRepo,
+    dedicatedTreeRepo,
+    repo: new Repo(targetRoot),
+  };
+}
+
+function determineTargetRoot(sourceRepo: Repo, options?: InitOptions): string {
+  if (options?.treePath) {
+    return resolve(options.currentCwd ?? process.cwd(), options.treePath);
+  }
+
+  if (options?.here) {
+    return sourceRepo.root;
+  }
+
+  if (options?.treeName) {
+    return join(dirname(sourceRepo.root), options.treeName);
+  }
+
+  if (
+    sourceRepo.looksLikeTreeRepo()
+    || sourceRepo.isLikelyEmptyRepo()
+    || !sourceRepo.isLikelySourceRepo()
+  ) {
+    return sourceRepo.root;
+  }
+
+  return join(dirname(sourceRepo.root), `${sourceRepo.repoName()}-context`);
+}
+
+function ensureGitRepo(
+  targetRoot: string,
+  gitInitializer?: (root: string) => void,
+): boolean {
+  if (existsSync(targetRoot)) {
+    if (!statSync(targetRoot).isDirectory()) {
+      throw new Error(`Target path is not a directory: ${targetRoot}`);
+    }
+    if (new Repo(targetRoot).isGitRepo()) {
+      return false;
+    }
+    if (readdirSync(targetRoot).length !== 0) {
+      throw new Error(
+        `Target path exists and is not a git repository: ${targetRoot}. Run \`git init\` there first or choose a different tree path.`,
+      );
+    }
+  } else {
+    mkdirSync(targetRoot, { recursive: true });
+  }
+
+  (gitInitializer ?? defaultGitInitializer)(targetRoot);
+  return true;
+}
+
+function defaultGitInitializer(root: string): void {
+  execFileSync("git", ["init"], {
+    cwd: root,
+    stdio: "ignore",
+  });
+}
+
+function relativePathFrom(from: string, to: string): string {
+  const rel = relative(from, to);
+  if (rel === "") {
+    return ".";
+  }
+  return rel.startsWith("..") ? rel : `./${rel}`;
+}

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

@@ -1,12 +1,15 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+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,
@@ -17,6 +20,59 @@ import {
 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 -->";
@@ -26,11 +82,35 @@ export interface Frontmatter {
   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) {
-    this.root = resolve(root ?? process.cwd());
+    const start = resolve(root ?? process.cwd());
+    this.root = root === undefined ? discoverGitRoot(start) ?? start : start;
   }
 
   pathExists(relPath: string): boolean {
@@ -85,11 +165,7 @@ export class Repo {
   }
 
   isGitRepo(): boolean {
-    try {
-      return statSync(join(this.root, ".git")).isDirectory();
-    } catch {
-      return false;
-    }
+    return hasGitMetadata(this.root);
   }
 
   hasFramework(): boolean {
@@ -136,8 +212,30 @@ export class Repo {
     return FRAMEWORK_VERSION;
   }
 
-  hasAgentMdMarkers(): boolean {
-    const text = this.readFile("AGENT.md");
+  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);
   }
@@ -181,4 +279,82 @@ export class Repo {
   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

@@ -1,20 +1,42 @@
 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 { FRAMEWORK_TEMPLATES_DIR } from "#skill/engine/runtime/asset-loader.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[] = [];
-  if (!repo.pathExists("AGENT.md")) {
+  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(
-      `AGENT.md is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/agent.md.template\``,
+      `Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`,
     );
-  } else if (!repo.hasAgentMdMarkers()) {
+  } 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(
-      "AGENT.md exists but is missing framework markers — add `<!-- BEGIN CONTEXT-TREE FRAMEWORK -->` and `<!-- END CONTEXT-TREE FRAMEWORK -->` sections",
+      `\`${instructionsPath}\` exists but is missing framework markers — add \`<!-- BEGIN CONTEXT-TREE FRAMEWORK -->\` and \`<!-- END CONTEXT-TREE FRAMEWORK -->\` sections`,
     );
   } else {
-    const text = repo.readFile("AGENT.md") ?? "";
+    const text = repo.readAgentInstructions() ?? "";
     const afterMarker = text.split(FRAMEWORK_END_MARKER);
     if (afterMarker.length > 1) {
       const userSection = afterMarker[1].trim();
@@ -28,7 +50,7 @@ export function evaluate(repo: Repo): RuleResult {
         );
       if (lines.length === 0) {
         tasks.push(
-          "Add your project-specific instructions below the framework markers in AGENT.md",
+          `Add your project-specific instructions below the framework markers in ${AGENT_INSTRUCTIONS_FILE}`,
         );
       }
     }

package/skills/first-tree/engine/runtime/asset-loader.ts

@@ -14,6 +14,9 @@ export const FRAMEWORK_PROMPTS_DIR = join(FRAMEWORK_ASSET_ROOT, "prompts");
 export const FRAMEWORK_EXAMPLES_DIR = join(FRAMEWORK_ASSET_ROOT, "examples");
 export const FRAMEWORK_HELPERS_DIR = join(FRAMEWORK_ASSET_ROOT, "helpers");
 export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
+export const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
+export const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
+export const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
 
 export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
 export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
@@ -68,6 +71,10 @@ export function progressFileCandidates(): string[] {
   return [INSTALLED_PROGRESS, LEGACY_SKILL_PROGRESS, LEGACY_PROGRESS];
 }
 
+export function agentInstructionsFileCandidates(): string[] {
+  return [AGENT_INSTRUCTIONS_FILE, LEGACY_AGENT_INSTRUCTIONS_FILE];
+}
+
 export function frameworkTemplateDirCandidates(): string[] {
   return [
     FRAMEWORK_TEMPLATES_DIR,