first-tree 0.0.4 → 0.0.5

package/skills/first-tree/assets/framework/workflows/pr-review.yml

@@ -45,7 +45,7 @@ jobs:
           gh pr view "$PR_NUMBER" --json headRefOid -q .headRefOid > /tmp/pr-head-sha.txt
 
       - name: Run Claude review
-        run: npx tsx skills/first-tree/assets/framework/helpers/run-review.ts
+        run: npx tsx .agents/skills/first-tree/assets/framework/helpers/run-review.ts
 
       - name: Parse and post review
         run: |

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

@@ -23,6 +23,7 @@ import {
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
+  installedSkillRootsDisplay,
 } from "#skill/engine/runtime/asset-loader.js";
 
 /**
@@ -67,7 +68,7 @@ interface TaskListContext {
 function installSkill(source: string, target: string): void {
   copyCanonicalSkill(source, target);
   console.log(
-    "  Installed skills/first-tree/ from the bundled first-tree package",
+    `  Installed ${installedSkillRootsDisplay()} from the bundled first-tree package`,
   );
 }
 
@@ -198,7 +199,7 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
     console.log();
   }
 
-  if (!r.hasFramework()) {
+  if (!r.hasCurrentInstalledSkill()) {
     try {
       const sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
       console.log(

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

@@ -2,14 +2,19 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_FRAMEWORK_VERSION,
+  CLAUDE_INSTALLED_PROGRESS,
   FRAMEWORK_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
+  INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_PROGRESS,
+  LEGACY_REPO_SKILL_PROGRESS,
+  LEGACY_REPO_SKILL_VERSION,
+  LEGACY_SKILL_PROGRESS,
+  LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
-  INSTALLED_PROGRESS,
   agentInstructionsFileCandidates,
+  installedSkillRoots,
   type FrameworkLayout,
   detectFrameworkLayout,
   frameworkVersionCandidates,
@@ -164,6 +169,22 @@ export class Repo {
     return knownConfigs.some((c) => this.pathExists(c));
   }
 
+  installedSkillRoots(): string[] {
+    return installedSkillRoots();
+  }
+
+  missingInstalledSkillRoots(): string[] {
+    return this.installedSkillRoots().filter(
+      (root) =>
+        !this.pathExists(join(root, "SKILL.md")) ||
+        !this.pathExists(join(root, "assets", "framework", "VERSION")),
+    );
+  }
+
+  hasCurrentInstalledSkill(): boolean {
+    return this.missingInstalledSkillRoots().length === 0;
+  }
+
   isGitRepo(): boolean {
     return hasGitMetadata(this.root);
   }
@@ -198,6 +219,12 @@ export class Repo {
     if (layout === "legacy-skill") {
       return LEGACY_SKILL_PROGRESS;
     }
+    if (layout === "legacy-repo-skill") {
+      return LEGACY_REPO_SKILL_PROGRESS;
+    }
+    if (layout === "claude-skill") {
+      return CLAUDE_INSTALLED_PROGRESS;
+    }
     return INSTALLED_PROGRESS;
   }
 
@@ -209,6 +236,12 @@ export class Repo {
     if (layout === "legacy-skill") {
       return LEGACY_SKILL_VERSION;
     }
+    if (layout === "legacy-repo-skill") {
+      return LEGACY_REPO_SKILL_VERSION;
+    }
+    if (layout === "claude-skill") {
+      return CLAUDE_FRAMEWORK_VERSION;
+    }
     return FRAMEWORK_VERSION;
   }
 

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

@@ -1,13 +1,15 @@
 import type { Repo } from "#skill/engine/repo.js";
 import type { RuleResult } from "#skill/engine/rules/index.js";
+import { claudeCodeExampleCandidates } from "#skill/engine/runtime/adapters.js";
 import { FRAMEWORK_EXAMPLES_DIR } from "#skill/engine/runtime/asset-loader.js";
 
 export function evaluate(repo: Repo): RuleResult {
   const tasks: string[] = [];
+  const [claudeExamplePath] = claudeCodeExampleCandidates();
   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/\`)`,
+        `Add SessionStart hook to \`.claude/settings.json\` (see \`${claudeExamplePath}/\`)`,
       );
     }
   } else if (!repo.anyAgentConfig()) {

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

@@ -1,12 +1,12 @@
 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";
+import { installedSkillRootsDisplay } 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`,
+      `${installedSkillRootsDisplay()} 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/runtime/adapters.ts

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import {
+  CLAUDE_FRAMEWORK_EXAMPLES_DIR,
+  CLAUDE_FRAMEWORK_HELPERS_DIR,
   FRAMEWORK_EXAMPLES_DIR,
-  FRAMEWORK_HELPERS_DIR,
+  LEGACY_REPO_SKILL_EXAMPLES_DIR,
   LEGACY_SKILL_EXAMPLES_DIR,
   LEGACY_EXAMPLES_DIR,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -11,12 +13,14 @@ export const CODEX_CONFIG_PATH = ".codex/config.json";
 
 export function claudeCodeExampleCandidates(): string[] {
   return [
+    join(CLAUDE_FRAMEWORK_EXAMPLES_DIR, "claude-code"),
     join(FRAMEWORK_EXAMPLES_DIR, "claude-code"),
+    join(LEGACY_REPO_SKILL_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");
+  return join(CLAUDE_FRAMEWORK_HELPERS_DIR, "inject-tree-context.sh");
 }

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

@@ -2,7 +2,11 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 export const SKILL_NAME = "first-tree";
-export const SKILL_ROOT = join("skills", SKILL_NAME);
+export const BUNDLED_SKILL_ROOT = join("skills", SKILL_NAME);
+export const SKILL_ROOT = join(".agents", "skills", SKILL_NAME);
+export const CLAUDE_SKILL_ROOT = join(".claude", "skills", SKILL_NAME);
+export const INSTALLED_SKILL_ROOTS = [SKILL_ROOT, CLAUDE_SKILL_ROOT] as const;
+
 export const SKILL_AGENTS_DIR = join(SKILL_ROOT, "agents");
 export const SKILL_REFERENCES_DIR = join(SKILL_ROOT, "references");
 export const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
@@ -18,6 +22,93 @@ 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 CLAUDE_SKILL_AGENTS_DIR = join(CLAUDE_SKILL_ROOT, "agents");
+export const CLAUDE_SKILL_REFERENCES_DIR = join(CLAUDE_SKILL_ROOT, "references");
+export const CLAUDE_FRAMEWORK_ASSET_ROOT = join(
+  CLAUDE_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const CLAUDE_FRAMEWORK_MANIFEST = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "manifest.json",
+);
+export const CLAUDE_FRAMEWORK_VERSION = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "VERSION",
+);
+export const CLAUDE_FRAMEWORK_TEMPLATES_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "templates",
+);
+export const CLAUDE_FRAMEWORK_WORKFLOWS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "workflows",
+);
+export const CLAUDE_FRAMEWORK_PROMPTS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "prompts",
+);
+export const CLAUDE_FRAMEWORK_EXAMPLES_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "examples",
+);
+export const CLAUDE_FRAMEWORK_HELPERS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "helpers",
+);
+export const CLAUDE_INSTALLED_PROGRESS = join(
+  CLAUDE_SKILL_ROOT,
+  "progress.md",
+);
+
+export const LEGACY_REPO_SKILL_ROOT = join("skills", SKILL_NAME);
+export const LEGACY_REPO_SKILL_AGENTS_DIR = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "agents",
+);
+export const LEGACY_REPO_SKILL_REFERENCES_DIR = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "references",
+);
+export const LEGACY_REPO_SKILL_ASSET_ROOT = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const LEGACY_REPO_SKILL_MANIFEST = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "manifest.json",
+);
+export const LEGACY_REPO_SKILL_VERSION = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "VERSION",
+);
+export const LEGACY_REPO_SKILL_TEMPLATES_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "templates",
+);
+export const LEGACY_REPO_SKILL_WORKFLOWS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "workflows",
+);
+export const LEGACY_REPO_SKILL_PROMPTS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "prompts",
+);
+export const LEGACY_REPO_SKILL_EXAMPLES_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "examples",
+);
+export const LEGACY_REPO_SKILL_HELPERS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "helpers",
+);
+export const LEGACY_REPO_SKILL_PROGRESS = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "progress.md",
+);
+
 export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
 export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
 export const LEGACY_SKILL_ASSET_ROOT = join(
@@ -52,7 +143,12 @@ export const LEGACY_WORKFLOWS_DIR = join(LEGACY_FRAMEWORK_ROOT, "workflows");
 export const LEGACY_PROMPTS_DIR = join(LEGACY_FRAMEWORK_ROOT, "prompts");
 export const LEGACY_EXAMPLES_DIR = join(LEGACY_FRAMEWORK_ROOT, "examples");
 
-export type FrameworkLayout = "skill" | "legacy-skill" | "legacy";
+export type FrameworkLayout =
+  | "skill"
+  | "claude-skill"
+  | "legacy-repo-skill"
+  | "legacy-skill"
+  | "legacy";
 
 function pathExists(root: string, relPath: string): boolean {
   const fullPath = join(root, relPath);
@@ -63,12 +159,34 @@ function pathExists(root: string, relPath: string): boolean {
   }
 }
 
+export function installedSkillRoots(): string[] {
+  return [...INSTALLED_SKILL_ROOTS];
+}
+
+export function installedSkillRootsDisplay(): string {
+  return installedSkillRoots()
+    .map((root) => `\`${root}/\``)
+    .join(" and ");
+}
+
 export function frameworkVersionCandidates(): string[] {
-  return [FRAMEWORK_VERSION, LEGACY_SKILL_VERSION, LEGACY_VERSION];
+  return [
+    FRAMEWORK_VERSION,
+    CLAUDE_FRAMEWORK_VERSION,
+    LEGACY_REPO_SKILL_VERSION,
+    LEGACY_SKILL_VERSION,
+    LEGACY_VERSION,
+  ];
 }
 
 export function progressFileCandidates(): string[] {
-  return [INSTALLED_PROGRESS, LEGACY_SKILL_PROGRESS, LEGACY_PROGRESS];
+  return [
+    INSTALLED_PROGRESS,
+    CLAUDE_INSTALLED_PROGRESS,
+    LEGACY_REPO_SKILL_PROGRESS,
+    LEGACY_SKILL_PROGRESS,
+    LEGACY_PROGRESS,
+  ];
 }
 
 export function agentInstructionsFileCandidates(): string[] {
@@ -78,6 +196,8 @@ export function agentInstructionsFileCandidates(): string[] {
 export function frameworkTemplateDirCandidates(): string[] {
   return [
     FRAMEWORK_TEMPLATES_DIR,
+    CLAUDE_FRAMEWORK_TEMPLATES_DIR,
+    LEGACY_REPO_SKILL_TEMPLATES_DIR,
     LEGACY_SKILL_TEMPLATES_DIR,
     LEGACY_TEMPLATES_DIR,
   ];
@@ -86,6 +206,8 @@ export function frameworkTemplateDirCandidates(): string[] {
 export function frameworkWorkflowDirCandidates(): string[] {
   return [
     FRAMEWORK_WORKFLOWS_DIR,
+    CLAUDE_FRAMEWORK_WORKFLOWS_DIR,
+    LEGACY_REPO_SKILL_WORKFLOWS_DIR,
     LEGACY_SKILL_WORKFLOWS_DIR,
     LEGACY_WORKFLOWS_DIR,
   ];
@@ -94,6 +216,8 @@ export function frameworkWorkflowDirCandidates(): string[] {
 export function frameworkPromptDirCandidates(): string[] {
   return [
     FRAMEWORK_PROMPTS_DIR,
+    CLAUDE_FRAMEWORK_PROMPTS_DIR,
+    LEGACY_REPO_SKILL_PROMPTS_DIR,
     LEGACY_SKILL_PROMPTS_DIR,
     LEGACY_PROMPTS_DIR,
   ];
@@ -102,6 +226,8 @@ export function frameworkPromptDirCandidates(): string[] {
 export function frameworkExampleDirCandidates(): string[] {
   return [
     FRAMEWORK_EXAMPLES_DIR,
+    CLAUDE_FRAMEWORK_EXAMPLES_DIR,
+    LEGACY_REPO_SKILL_EXAMPLES_DIR,
     LEGACY_SKILL_EXAMPLES_DIR,
     LEGACY_EXAMPLES_DIR,
   ];
@@ -123,6 +249,12 @@ export function detectFrameworkLayout(root: string): FrameworkLayout | null {
   if (pathExists(root, FRAMEWORK_VERSION)) {
     return "skill";
   }
+  if (pathExists(root, CLAUDE_FRAMEWORK_VERSION)) {
+    return "claude-skill";
+  }
+  if (pathExists(root, LEGACY_REPO_SKILL_VERSION)) {
+    return "legacy-repo-skill";
+  }
   if (pathExists(root, LEGACY_SKILL_VERSION)) {
     return "legacy-skill";
   }

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

@@ -2,9 +2,10 @@ import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-  FRAMEWORK_ASSET_ROOT,
+  BUNDLED_SKILL_ROOT,
+  INSTALLED_SKILL_ROOTS,
+  LEGACY_REPO_SKILL_ROOT,
   LEGACY_SKILL_ROOT,
-  SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
 
 export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
@@ -12,7 +13,7 @@ export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
   while (true) {
     if (
       existsSync(join(dir, "package.json")) &&
-      existsSync(join(dir, SKILL_ROOT, "SKILL.md"))
+      existsSync(join(dir, BUNDLED_SKILL_ROOT, "SKILL.md"))
     ) {
       return dir;
     }
@@ -38,7 +39,7 @@ export function resolveCanonicalSkillRoot(sourceRoot: string): string {
     return directSkillRoot;
   }
 
-  const nestedSkillRoot = join(sourceRoot, SKILL_ROOT);
+  const nestedSkillRoot = join(sourceRoot, BUNDLED_SKILL_ROOT);
   if (
     existsSync(join(nestedSkillRoot, "SKILL.md")) &&
     existsSync(join(nestedSkillRoot, "assets", "framework", "VERSION"))
@@ -53,16 +54,21 @@ export function resolveCanonicalSkillRoot(sourceRoot: string): string {
 
 export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void {
   const src = resolveCanonicalSkillRoot(sourceRoot);
-  const dst = join(targetRoot, SKILL_ROOT);
-  const legacyDst = join(targetRoot, LEGACY_SKILL_ROOT);
-  if (existsSync(dst)) {
-    rmSync(dst, { recursive: true, force: true });
+  for (const relPath of [
+    ...INSTALLED_SKILL_ROOTS,
+    LEGACY_REPO_SKILL_ROOT,
+    LEGACY_SKILL_ROOT,
+  ]) {
+    const fullPath = join(targetRoot, relPath);
+    if (existsSync(fullPath)) {
+      rmSync(fullPath, { recursive: true, force: true });
+    }
   }
-  if (legacyDst !== dst && existsSync(legacyDst)) {
-    rmSync(legacyDst, { recursive: true, force: true });
+  for (const relPath of INSTALLED_SKILL_ROOTS) {
+    const dst = join(targetRoot, relPath);
+    mkdirSync(dirname(dst), { recursive: true });
+    cpSync(src, dst, { recursive: true });
   }
-  mkdirSync(dirname(dst), { recursive: true });
-  cpSync(src, dst, { recursive: true });
 }
 
 export function renderTemplateFile(

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

@@ -4,14 +4,17 @@ import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
   AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_SKILL_ROOT,
   FRAMEWORK_WORKFLOWS_DIR,
   FRAMEWORK_TEMPLATES_DIR,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_FRAMEWORK_ROOT,
+  LEGACY_REPO_SKILL_ROOT,
   LEGACY_SKILL_ROOT,
   SKILL_ROOT,
+  installedSkillRootsDisplay,
   type FrameworkLayout,
 } from "#skill/engine/runtime/asset-loader.js";
 import {
@@ -45,9 +48,10 @@ function formatUpgradeTaskList(
   const lines: string[] = [
     `# Context Tree Upgrade — v${localVersion} -> v${packagedVersion}\n`,
     "## Installed Skill",
-    `- [ ] Review local customizations under \`${SKILL_ROOT}/\` and reapply them if needed`,
+    `- [ ] Review local customizations under ${installedSkillRootsDisplay()} and reapply them if needed`,
     `- [ ] Re-copy any workflow updates you want from \`${FRAMEWORK_WORKFLOWS_DIR}/\` into \`.github/workflows/\``,
-    `- [ ] Re-check any local agent setup that references \`${SKILL_ROOT}/assets/framework/examples/\` or \`${SKILL_ROOT}/assets/framework/helpers/\``,
+    `- [ ] Re-check any local agent setup that references \`${CLAUDE_SKILL_ROOT}/assets/framework/examples/\` or \`${CLAUDE_SKILL_ROOT}/assets/framework/helpers/\``,
+    `- [ ] Re-check any repo scripts or workflow files that reference \`${SKILL_ROOT}/assets/framework/\``,
     "",
   ];
 
@@ -58,6 +62,14 @@ function formatUpgradeTaskList(
     );
   }
 
+  if (layout === "legacy-repo-skill") {
+    lines.push(
+      "## Migration",
+      `- [ ] Remove any stale \`${LEGACY_REPO_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
+      "",
+    );
+  }
+
   if (layout === "legacy-skill") {
     migrationTasks.push(
       `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
@@ -165,7 +177,12 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
     return 1;
   }
 
-  if (layout === "skill" && packagedVersion === localVersion) {
+  const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+  if (
+    layout === "skill" &&
+    missingInstalledRoots.length === 0 &&
+    packagedVersion === localVersion
+  ) {
     console.log(
       `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
     );
@@ -179,16 +196,26 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
       force: true,
     });
     console.log(
-      "Migrated legacy .context-tree/ layout to skills/first-tree/.",
+      `Migrated legacy .context-tree/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else if (layout === "legacy-skill") {
+  } else if (layout === "legacy-repo-skill") {
     console.log(
-      "Migrated skills/first-tree-cli-framework/ to skills/first-tree/.",
+      `Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else {
+  } else if (layout === "legacy-skill") {
     console.log(
-      "Refreshed skills/first-tree/ from the bundled first-tree package.",
+      `Migrated ${LEGACY_SKILL_ROOT}/ to ${installedSkillRootsDisplay()}.`,
     );
+  } else {
+    if (missingInstalledRoots.length > 0) {
+      console.log(
+        `Repaired missing installed skill roots (${missingInstalledRoots.map((root) => `${root}/`).join(", ")}) and refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`,
+      );
+    } else {
+      console.log(
+        `Refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`,
+      );
+    }
   }
 
   const output = formatUpgradeTaskList(

package/skills/first-tree/references/onboarding.md

@@ -56,8 +56,9 @@ Information an agent needs to **decide** on an approach — not to execute it.
 - A source/workspace Git repository, or an already-created dedicated tree repo
 - Node.js 18+
 - The npm package is `first-tree`, the installed CLI command is
-  `context-tree`, and the installed skill directory in the tree is
-  `skills/first-tree/`
+  `context-tree`.
+- `context-tree init` installs the framework skill into
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`.
 - Use `npx first-tree init` for one-off runs, or `npm install -g first-tree`
   to add the `context-tree` command to your PATH
 
@@ -81,24 +82,30 @@ git init
 context-tree init --here
 ```
 
-Either way, the framework installs into `skills/first-tree/`, renders
-scaffolding (`NODE.md`, `AGENTS.md`, `members/NODE.md`), and generates a task
-list in `skills/first-tree/progress.md`.
+Either way, the framework installs into `.agents/skills/first-tree/` and
+`.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,
+`members/NODE.md`), and generates a task list in
+`.agents/skills/first-tree/progress.md`.
 
 Publishing tip: keep the tree repo in the same GitHub organization as the
 source repo unless you have a reason not to.
 
 ### Step 2: Work Through the Task List
 
-Read `skills/first-tree/progress.md`. It contains a checklist tailored to the current state of the repo. Complete each task:
+Read `.agents/skills/first-tree/progress.md`. It contains a checklist tailored
+to the current state of the repo. Complete each task:
 
 - Fill in `NODE.md` with your organization name, owners, and domains
 - Add project-specific instructions to `AGENTS.md` below the framework markers
 - Create member nodes under `members/`
-- Optionally configure agent integration (e.g., Claude Code session hooks)
-- Copy validation workflows from `skills/first-tree/assets/framework/workflows/` to `.github/workflows/`
+- Optionally configure agent integration (for Claude Code, the installed hook
+  assets live under `.claude/skills/first-tree/`)
+- Copy validation workflows from
+  `.agents/skills/first-tree/assets/framework/workflows/` to
+  `.github/workflows/`
 
-As you complete each task, check it off in `skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.
+As you complete each task, check it off in
+`.agents/skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.
 
 ### Step 3: Verify
 
@@ -112,7 +119,9 @@ Or, from your source/workspace repo:
 context-tree verify --tree-path ../my-org-context
 ```
 
-This fails if any items in `skills/first-tree/progress.md` remain unchecked, and runs deterministic checks (valid frontmatter, node structure, member nodes exist).
+This fails if any items in `.agents/skills/first-tree/progress.md` remain
+unchecked, and runs deterministic checks (valid frontmatter, node structure,
+member nodes exist).
 
 ### Step 4: Design Your Domains
 
@@ -164,13 +173,14 @@ When the framework updates:
 context-tree upgrade
 ```
 
-`context-tree upgrade` refreshes `skills/first-tree/` from the
-skill bundled with the currently running `first-tree` npm package, preserves your
-tree content, and generates follow-up tasks in
-`skills/first-tree/progress.md`.
+`context-tree upgrade` refreshes `.agents/skills/first-tree/` and
+`.claude/skills/first-tree/` from the skill bundled with the currently running
+`first-tree` npm package, preserves your tree content, and generates follow-up
+tasks in `.agents/skills/first-tree/progress.md`.
 
-If your repo still uses the older `skills/first-tree-cli-framework/` path,
-`context-tree upgrade` will migrate it to `skills/first-tree/` first.
+If your repo still uses the older `skills/first-tree/`,
+`skills/first-tree-cli-framework/`, or `.context-tree/` layouts,
+`context-tree upgrade` will migrate it to the current installed layout first.
 
 To pick up a newer framework release, first run a newer package version, for
 example `npx first-tree@latest upgrade`, or update your global `first-tree`
@@ -180,6 +190,6 @@ install before running `context-tree upgrade`.
 
 ## Further Reading
 
-- `skills/first-tree/references/principles.md` — Core principles with detailed examples
-- `skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned
+- `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples
+- `.agents/skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned
 - `AGENTS.md` in your tree — The before/during/after workflow for every task