first-tree 0.0.4 → 0.0.5

package/skills/first-tree/references/upgrade-contract.md

@@ -1,8 +1,8 @@
 # Upgrade Contract
 
 This file describes the current installed-layout contract and the compatibility
-rules we keep for legacy `skills/first-tree-cli-framework/` and
-`.context-tree/` repos.
+rules we keep for legacy `skills/first-tree/`,
+`skills/first-tree-cli-framework/`, and `.context-tree/` repos.
 
 ## Canonical Source
 
@@ -19,20 +19,35 @@ rules we keep for legacy `skills/first-tree-cli-framework/` and
 The current installed layout in a user repo is:
 
 ```text
-skills/
-  first-tree/
-    SKILL.md
-    progress.md
-    references/
-    assets/
-      framework/
-        manifest.json
-        VERSION
-        templates/
-        workflows/
-        prompts/
-        examples/
-        helpers/
+.agents/
+  skills/
+    first-tree/
+      SKILL.md
+      progress.md
+      references/
+      assets/
+        framework/
+          manifest.json
+          VERSION
+          templates/
+          workflows/
+          prompts/
+          examples/
+          helpers/
+.claude/
+  skills/
+    first-tree/
+      SKILL.md
+      references/
+      assets/
+        framework/
+          manifest.json
+          VERSION
+          templates/
+          workflows/
+          prompts/
+          examples/
+          helpers/
 ```
 
 The tree content still lives outside the skill:
@@ -41,6 +56,11 @@ The tree content still lives outside the skill:
 - `AGENTS.md`
 - `members/`
 
+The repo-owned `.agents/skills/first-tree/` path is the primary installed root
+for progress state, workflow references, and helper scripts. The matching
+`.claude/skills/first-tree/` path mirrors the same payload for Claude-facing
+skill discovery and hooks.
+
 ## Command Intent
 
 - `context-tree init`
@@ -48,7 +68,7 @@ The tree content still lives outside the skill:
     tree repo by default
   - installs the skill into the target tree repo
   - renders top-level tree scaffolding from the skill templates
-  - writes progress state to `skills/first-tree/progress.md`
+  - writes progress state to `.agents/skills/first-tree/progress.md`
 - `context-tree verify`
   - checks progress state from the installed skill
   - validates root/frontmatter/agent markers
@@ -57,8 +77,11 @@ The tree content still lives outside the skill:
   - compares the installed skill payload version to the skill bundled with the
     currently running `first-tree` package
   - refreshes the installed skill payload without overwriting tree content
+  - migrates repos that still use the previous `skills/first-tree/` path onto
+    `.agents/skills/first-tree/` and `.claude/skills/first-tree/`
   - migrates repos that still use the previous
-    `skills/first-tree-cli-framework/` path onto `skills/first-tree/`
+    `skills/first-tree-cli-framework/` path onto `.agents/skills/first-tree/`
+    and `.claude/skills/first-tree/`
   - migrates legacy `.context-tree/` repos onto the installed skill layout
   - preserves user-authored sections such as the editable part of `AGENTS.md`
 
@@ -73,14 +96,17 @@ The tree content still lives outside the skill:
 - Normal `context-tree init` and `context-tree upgrade` flows do not clone the
   source repo or require network access.
 - `context-tree verify` may still read a legacy
-  `skills/first-tree-cli-framework/...` or `.context-tree/...` layout in an
-  existing user repo so the repo can be upgraded in place.
+  `.claude/skills/first-tree/...`, `skills/first-tree/...`,
+  `skills/first-tree-cli-framework/...`, or `.context-tree/...` layout in an
+  existing user repo so the repo can be repaired or upgraded in place.
 - `context-tree upgrade` must migrate either legacy layout onto
-  `skills/first-tree/` and remove the old directory afterward.
-- When both layouts are present, prefer the installed skill layout.
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`, and remove
+  old skill directories afterward.
+- When both current and legacy layouts are present, prefer the
+  `.agents/skills/first-tree/` layout.
 - Existing repos may still have a legacy `AGENT.md`; `init` and `upgrade`
   must not silently overwrite it, and follow-up tasks should direct users to
-  rename it to `AGENTS.md`.
+  rename or merge it into `AGENTS.md`.
 
 ## Invariants
 

package/skills/first-tree/tests/asset-loader.test.ts

@@ -2,8 +2,11 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
+  CLAUDE_INSTALLED_PROGRESS,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
+  LEGACY_REPO_SKILL_PROGRESS,
+  LEGACY_REPO_SKILL_VERSION,
   LEGACY_SKILL_PROGRESS,
   LEGACY_SKILL_VERSION,
   LEGACY_PROGRESS,
@@ -18,7 +21,7 @@ import { useTmpDir } from "./helpers.js";
 describe("asset-loader", () => {
   it("prefers the installed skill layout when both layouts exist", () => {
     const tmp = useTmpDir();
-    mkdirSync(join(tmp.path, "skills", "first-tree", "assets", "framework"), {
+    mkdirSync(join(tmp.path, ".agents", "skills", "first-tree", "assets", "framework"), {
       recursive: true,
     });
     mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
@@ -39,6 +42,21 @@ describe("asset-loader", () => {
     expect(detectFrameworkLayout(tmp.path)).toBe("legacy");
   });
 
+  it("detects the previous workspace skill path before older layouts", () => {
+    const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, "skills", "first-tree", "assets", "framework"), {
+      recursive: true,
+    });
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, LEGACY_REPO_SKILL_VERSION), "0.2.0\n");
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("legacy-repo-skill");
+    expect(
+      resolveFirstExistingPath(tmp.path, frameworkVersionCandidates()),
+    ).toBe(LEGACY_REPO_SKILL_VERSION);
+  });
+
   it("detects the previous installed skill name before the .context-tree layout", () => {
     const tmp = useTmpDir();
     mkdirSync(
@@ -59,12 +77,16 @@ describe("asset-loader", () => {
 
   it("prefers the installed progress file candidate", () => {
     const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, ".agents", "skills", "first-tree"), { recursive: true });
+    mkdirSync(join(tmp.path, ".claude", "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, "skills", "first-tree-cli-framework"), {
       recursive: true,
     });
     mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
     writeFileSync(join(tmp.path, INSTALLED_PROGRESS), "new");
+    writeFileSync(join(tmp.path, CLAUDE_INSTALLED_PROGRESS), "claude");
+    writeFileSync(join(tmp.path, LEGACY_REPO_SKILL_PROGRESS), "old-repo-skill");
     writeFileSync(join(tmp.path, LEGACY_SKILL_PROGRESS), "old-skill");
     writeFileSync(join(tmp.path, LEGACY_PROGRESS), "old");
 

package/skills/first-tree/tests/helpers.ts

@@ -5,10 +5,13 @@ import { afterEach } from "vitest";
 import {
   AGENT_INSTRUCTIONS_FILE,
   AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_SKILL_ROOT,
   FRAMEWORK_VERSION,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
+  LEGACY_REPO_SKILL_VERSION,
   LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
+  SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
 
 interface TmpDir {
@@ -24,10 +27,20 @@ export function useTmpDir(): TmpDir {
 }
 
 export function makeFramework(root: string, version = "0.1.0"): void {
-  mkdirSync(join(root, "skills", "first-tree", "assets", "framework"), {
-    recursive: true,
-  });
+  for (const skillRoot of [SKILL_ROOT, CLAUDE_SKILL_ROOT]) {
+    mkdirSync(join(root, skillRoot, "assets", "framework"), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(root, skillRoot, "SKILL.md"),
+      "---\nname: first-tree\ndescription: installed\n---\n",
+    );
+  }
   writeFileSync(join(root, FRAMEWORK_VERSION), `${version}\n`);
+  writeFileSync(
+    join(root, CLAUDE_SKILL_ROOT, "assets", "framework", "VERSION"),
+    `${version}\n`,
+  );
 }
 
 export function makeGitRepo(root: string): void {
@@ -50,6 +63,17 @@ export function makeLegacyFramework(root: string, version = "0.1.0"): void {
   writeFileSync(join(root, LEGACY_VERSION), `${version}\n`);
 }
 
+export function makeLegacyRepoFramework(root: string, version = "0.1.0"): void {
+  mkdirSync(join(root, "skills", "first-tree", "assets", "framework"), {
+    recursive: true,
+  });
+  writeFileSync(
+    join(root, "skills", "first-tree", "SKILL.md"),
+    "---\nname: first-tree\ndescription: legacy installed\n---\n",
+  );
+  writeFileSync(join(root, LEGACY_REPO_SKILL_VERSION), `${version}\n`);
+}
+
 export function makeLegacyNamedFramework(
   root: string,
   version = "0.1.0",

package/skills/first-tree/tests/init.test.ts

@@ -100,7 +100,7 @@ describe("writeProgress", () => {
 
   it("overwrites existing file", () => {
     const tmp = useTmpDir();
-    mkdirSync(join(tmp.path, "skills", "first-tree"), {
+    mkdirSync(join(tmp.path, ".agents", "skills", "first-tree"), {
       recursive: true,
     });
     writeFileSync(join(tmp.path, INSTALLED_PROGRESS), "old");
@@ -145,7 +145,10 @@ describe("runInit", () => {
 
     expect(ret).toBe(0);
     expect(
-      existsSync(join(repoDir.path, "skills", "first-tree", "SKILL.md")),
+      existsSync(join(repoDir.path, ".agents", "skills", "first-tree", "SKILL.md")),
+    ).toBe(true);
+    expect(
+      existsSync(join(repoDir.path, ".claude", "skills", "first-tree", "SKILL.md")),
     ).toBe(true);
     expect(readFileSync(join(repoDir.path, FRAMEWORK_VERSION), "utf-8").trim()).toBe("0.2.0");
     expect(existsSync(join(repoDir.path, "NODE.md"))).toBe(true);
@@ -202,7 +205,12 @@ describe("runInit", () => {
     );
 
     expect(ret).toBe(0);
-    expect(existsSync(join(treeRepo, "skills", "first-tree", "SKILL.md"))).toBe(true);
+    expect(
+      existsSync(join(treeRepo, ".agents", "skills", "first-tree", "SKILL.md")),
+    ).toBe(true);
+    expect(
+      existsSync(join(treeRepo, ".claude", "skills", "first-tree", "SKILL.md")),
+    ).toBe(true);
     expect(existsSync(join(treeRepo, "NODE.md"))).toBe(true);
     expect(existsSync(join(treeRepo, AGENT_INSTRUCTIONS_FILE))).toBe(true);
     expect(existsSync(join(treeRepo, "members", "NODE.md"))).toBe(true);

package/skills/first-tree/tests/repo.test.ts

@@ -4,9 +4,12 @@ import { describe, expect, it } from "vitest";
 import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTALLED_PROGRESS,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
+  LEGACY_REPO_SKILL_PROGRESS,
+  LEGACY_REPO_SKILL_VERSION,
   LEGACY_SKILL_PROGRESS,
   LEGACY_SKILL_VERSION,
   LEGACY_PROGRESS,
@@ -17,6 +20,7 @@ import {
   makeFramework,
   makeGitRepo,
   makeLegacyFramework,
+  makeLegacyRepoFramework,
   makeLegacyNamedFramework,
   makeSourceRepo,
   makeSourceSkill,
@@ -182,6 +186,13 @@ describe("hasFramework", () => {
     expect(repo.hasFramework()).toBe(true);
   });
 
+  it("returns true with the previous workspace skill path", () => {
+    const tmp = useTmpDir();
+    makeLegacyRepoFramework(tmp.path);
+    const repo = new Repo(tmp.path);
+    expect(repo.hasFramework()).toBe(true);
+  });
+
   it("returns false without VERSION file", () => {
     const tmp = useTmpDir();
     const repo = new Repo(tmp.path);
@@ -213,6 +224,13 @@ describe("readVersion", () => {
     expect(repo.readVersion()).toBe("0.2.5");
   });
 
+  it("reads the previous workspace skill version", () => {
+    const tmp = useTmpDir();
+    makeLegacyRepoFramework(tmp.path, "0.2.4");
+    const repo = new Repo(tmp.path);
+    expect(repo.readVersion()).toBe("0.2.4");
+  });
+
   it("returns null when missing", () => {
     const tmp = useTmpDir();
     const repo = new Repo(tmp.path);
@@ -245,6 +263,14 @@ describe("path preferences", () => {
     expect(repo.preferredProgressPath()).toBe(LEGACY_SKILL_PROGRESS);
     expect(repo.frameworkVersionPath()).toBe(LEGACY_SKILL_VERSION);
   });
+
+  it("switches path preferences for repos using the previous workspace skill path", () => {
+    const tmp = useTmpDir();
+    makeLegacyRepoFramework(tmp.path);
+    const repo = new Repo(tmp.path);
+    expect(repo.preferredProgressPath()).toBe(LEGACY_REPO_SKILL_PROGRESS);
+    expect(repo.frameworkVersionPath()).toBe(LEGACY_REPO_SKILL_VERSION);
+  });
 });
 
 // --- agent instructions helpers ---

package/skills/first-tree/tests/rules.test.ts

@@ -29,7 +29,7 @@ describe("framework rule", () => {
     const result = framework.evaluate(repo);
     expect(result.group).toBe("Framework");
     expect(result.tasks).toHaveLength(1);
-    expect(result.tasks[0]).toContain("skills/first-tree/");
+    expect(result.tasks[0]).toContain(".agents/skills/first-tree/");
   });
 
   it("passes when framework exists", () => {
@@ -233,7 +233,9 @@ describe("ciValidation rule", () => {
     const result = ciValidation.evaluate(repo);
     expect(result.tasks).toHaveLength(4);
     expect(result.tasks[0]).toContain("validation workflow");
-    expect(result.tasks[0]).toContain("skills/first-tree/assets/framework/workflows/validate.yml");
+    expect(result.tasks[0]).toContain(
+      ".agents/skills/first-tree/assets/framework/workflows/validate.yml",
+    );
     expect(result.tasks[1]).toContain("PR reviews");
     expect(result.tasks[2]).toContain("API secret");
     expect(result.tasks[3]).toContain("CODEOWNERS");
@@ -271,7 +273,7 @@ describe("ciValidation rule", () => {
     mkdirSync(wfDir, { recursive: true });
     writeFileSync(
       join(wfDir, "pr-review.yml"),
-      "name: PR Review\non: pull_request\njobs:\n  review:\n    steps:\n      - run: npx tsx skills/first-tree/assets/framework/helpers/run-review.ts\n",
+      "name: PR Review\non: pull_request\njobs:\n  review:\n    steps:\n      - run: npx tsx .agents/skills/first-tree/assets/framework/helpers/run-review.ts\n",
     );
     const repo = new Repo(tmp.path);
     const result = ciValidation.evaluate(repo);
@@ -290,7 +292,7 @@ describe("ciValidation rule", () => {
     );
     writeFileSync(
       join(wfDir, "pr-review.yml"),
-      "name: PR Review\non: pull_request\njobs:\n  review:\n    steps:\n      - run: npx tsx skills/first-tree/assets/framework/helpers/run-review.ts\n",
+      "name: PR Review\non: pull_request\njobs:\n  review:\n    steps:\n      - run: npx tsx .agents/skills/first-tree/assets/framework/helpers/run-review.ts\n",
     );
     const repo = new Repo(tmp.path);
     const result = ciValidation.evaluate(repo);
@@ -308,11 +310,11 @@ describe("ciValidation rule", () => {
     );
     writeFileSync(
       join(wfDir, "pr-review.yml"),
-      "name: PR Review\non: pull_request\njobs:\n  review:\n    steps:\n      - run: npx tsx skills/first-tree/assets/framework/helpers/run-review.ts\n",
+      "name: PR Review\non: pull_request\njobs:\n  review:\n    steps:\n      - run: npx tsx .agents/skills/first-tree/assets/framework/helpers/run-review.ts\n",
     );
     writeFileSync(
       join(wfDir, "codeowners.yml"),
-      "name: Update CODEOWNERS\non: pull_request\njobs:\n  update:\n    steps:\n      - run: npx tsx skills/first-tree/assets/framework/helpers/generate-codeowners.ts\n",
+      "name: Update CODEOWNERS\non: pull_request\njobs:\n  update:\n    steps:\n      - run: npx tsx .agents/skills/first-tree/assets/framework/helpers/generate-codeowners.ts\n",
     );
     const repo = new Repo(tmp.path);
     const result = ciValidation.evaluate(repo);
@@ -386,7 +388,7 @@ describe("evaluateAll", () => {
     makeNode(tmp.path);
     makeAgentsMd(tmp.path, { markers: true, userContent: true });
     makeMembers(tmp.path, 1);
-    mkdirSync(join(tmp.path, ".claude"));
+    mkdirSync(join(tmp.path, ".claude"), { recursive: true });
     writeFileSync(
       join(tmp.path, ".claude", "settings.json"),
       '{"hooks": {"inject-tree-context": true}}',

package/skills/first-tree/tests/skill-artifacts.test.ts

@@ -201,6 +201,8 @@ describe("skill artifacts", () => {
     expect(read("README.md")).toContain("Canonical Documentation");
     expect(read("README.md")).toContain("references/source-map.md");
     expect(read("README.md")).toContain("skills/first-tree/");
+    expect(read("README.md")).toContain(".agents/skills/first-tree/");
+    expect(read("README.md")).toContain(".claude/skills/first-tree/");
     expect(read("README.md")).toContain("bundled canonical");
     expect(read("README.md")).toContain("dedicated tree repo");
     expect(read("README.md")).toContain("`first-tree` skill");
@@ -218,6 +220,8 @@ describe("skill artifacts", () => {
     expect(onboarding).toContain("installed CLI command is");
     expect(onboarding).toContain("currently running `first-tree` npm package");
     expect(onboarding).toContain("npx first-tree@latest upgrade");
+    expect(onboarding).toContain(".agents/skills/first-tree/");
+    expect(onboarding).toContain(".claude/skills/first-tree/");
     expect(onboarding).not.toContain("This clones the framework into `.context-tree/`");
     expect(onboarding).not.toContain("from upstream");
 
@@ -228,6 +232,8 @@ describe("skill artifacts", () => {
     expect(skillMd).toContain("maintainer-testing.md");
     expect(skillMd).toContain("currently running `first-tree` package");
     expect(skillMd).toContain("so it is not confused with the `first-tree`");
+    expect(skillMd).toContain(".agents/skills/first-tree/");
+    expect(skillMd).toContain(".claude/skills/first-tree/");
     expect(skillMd).not.toContain("canonical eval harness");
 
     const sourceMap = read("skills/first-tree/references/source-map.md");

package/skills/first-tree/tests/upgrade.test.ts

@@ -14,6 +14,7 @@ import {
   makeFramework,
   makeSourceRepo,
   makeLegacyFramework,
+  makeLegacyRepoFramework,
   makeLegacyNamedFramework,
   makeSourceSkill,
   useTmpDir,
@@ -35,7 +36,7 @@ describe("runUpgrade", () => {
     expect(existsSync(join(repoDir.path, ".context-tree"))).toBe(false);
     expect(readFileSync(join(repoDir.path, FRAMEWORK_VERSION), "utf-8").trim()).toBe("0.2.0");
     expect(readFileSync(join(repoDir.path, INSTALLED_PROGRESS), "utf-8")).toContain(
-      "skills/first-tree/assets/framework/VERSION",
+      ".agents/skills/first-tree/assets/framework/VERSION",
     );
     expect(readFileSync(join(repoDir.path, INSTALLED_PROGRESS), "utf-8")).toContain(
       `Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\``,
@@ -79,6 +80,24 @@ describe("runUpgrade", () => {
     );
   });
 
+  it("migrates repos that still use the previous workspace skill path", () => {
+    const repoDir = useTmpDir();
+    const sourceDir = useTmpDir();
+    makeLegacyRepoFramework(repoDir.path, "0.1.0");
+    makeSourceSkill(sourceDir.path, "0.2.0");
+
+    const result = runUpgrade(new Repo(repoDir.path), {
+      sourceRoot: sourceDir.path,
+    });
+
+    expect(result).toBe(0);
+    expect(existsSync(join(repoDir.path, "skills", "first-tree"))).toBe(false);
+    expect(readFileSync(join(repoDir.path, FRAMEWORK_VERSION), "utf-8").trim()).toBe("0.2.0");
+    expect(readFileSync(join(repoDir.path, INSTALLED_PROGRESS), "utf-8")).toContain(
+      "skills/first-tree/",
+    );
+  });
+
   it("refuses to replace a newer installed skill with an older packaged skill", () => {
     const repoDir = useTmpDir();
     const sourceDir = useTmpDir();

package/skills/first-tree/tests/verify.test.ts

@@ -43,7 +43,7 @@ describe("checkProgress", () => {
 
   it("returns empty when all checked", () => {
     const tmp = useTmpDir();
-    mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
+    makeFramework(tmp.path);
     writeFileSync(
       join(tmp.path, INSTALLED_PROGRESS),
       "# Progress\n- [x] Task one\n- [x] Task two\n",
@@ -54,7 +54,7 @@ describe("checkProgress", () => {
 
   it("returns unchecked items", () => {
     const tmp = useTmpDir();
-    mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
+    makeFramework(tmp.path);
     writeFileSync(
       join(tmp.path, INSTALLED_PROGRESS),
       "# Progress\n- [x] Done task\n- [ ] Pending task\n- [ ] Another pending\n",
@@ -65,7 +65,7 @@ describe("checkProgress", () => {
 
   it("returns empty for empty progress", () => {
     const tmp = useTmpDir();
-    mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
+    makeFramework(tmp.path);
     writeFileSync(join(tmp.path, INSTALLED_PROGRESS), "");
     const repo = new Repo(tmp.path);
     expect(checkProgress(repo)).toEqual([]);

package/dist/onboarding-C9cYSE6F.js

@@ -1,2 +0,0 @@
-import { t as runOnboarding } from "./onboarding-CPP8fF4D.js";
-export { runOnboarding };

package/dist/onboarding-CPP8fF4D.js

@@ -1,10 +0,0 @@
-//#region skills/first-tree/references/onboarding.md
-var onboarding_default = "# Context Tree Onboarding\n\nYou are setting up a **Context Tree** — the living source of truth for an organization. This document tells you what it is and how to bootstrap one.\n\n---\n\n## What Is a Context Tree\n\nA Context Tree is a Git repository where every directory is a **domain** and every file is a **node**. Each node captures decisions, designs, and cross-domain relationships — the knowledge that would otherwise scatter across PRs, documents, and people's heads.\n\nKey properties:\n\n- **Nodes are markdown files.** Each directory has a `NODE.md` that describes the domain. Leaf `.md` files capture specific decisions or designs.\n- **Every node has an owner.** Declared in YAML frontmatter. Owners approve changes to their nodes.\n- **Organized by concern, not by repo or team.** An agent working on \"add SSO\" finds all auth context in one place — not split across 4 repos.\n- **The tree is never a snapshot — it's the current state.** When decisions change, the tree updates. Stale nodes are bugs.\n\n### Frontmatter Format\n\nEvery node has frontmatter:\n\n```yaml\n---\ntitle: \"Auth Architecture\"\nowners: [alice, bob]\nsoft_links: [/infrastructure/deployments]\n---\n```\n\n- `owners` — who can approve changes. `owners: []` inherits from parent. `owners: [*]` means anyone.\n- `soft_links` — cross-references to related nodes in other domains.\n\n### What Belongs in the Tree\n\nInformation an agent needs to **decide** on an approach — not to execute it.\n\n**Yes:** \"Auth spans 4 repos: backend issues JWTs, frontend uses Better Auth, extension uses OAuth popup, desktop uses localhost callback.\"\n\n**No:** The function signature of `auth_service.verify()` — that's in the code.\n\n---\n\n## Four Principles\n\n1. **Source of truth for decisions, not execution.** The tree captures the *what* and *why*. Execution details stay in source systems.\n2. **Agents are first-class participants.** The tree is designed for agents to navigate and update.\n3. **Transparency by default.** Reading is open to all. Writing requires owner approval.\n4. **Git-native.** Nodes are files, domains are directories. History, ownership, and review follow Git conventions.\n\n---\n\n## How to Set Up a Context Tree\n\n### Prerequisites\n\n- A source/workspace Git repository, or an already-created dedicated tree repo\n- Node.js 18+\n- The npm package is `first-tree`, the installed CLI command is\n  `context-tree`, and the installed skill directory in the tree is\n  `skills/first-tree/`\n- Use `npx first-tree init` for one-off runs, or `npm install -g first-tree`\n  to add the `context-tree` command to your PATH\n\n### Step 1: Initialize\n\nRecommended workflow: run `context-tree init` from your source or workspace repo.\nThe CLI will create a sibling dedicated tree repo named `<repo>-context` by\ndefault and install the framework there.\n\n```bash\ncd my-org\ncontext-tree init\ncd ../my-org-context\n```\n\nIf you already created a dedicated tree repo manually, initialize it in place:\n\n```bash\nmkdir my-org-context && cd my-org-context\ngit init\ncontext-tree init --here\n```\n\nEither way, the framework installs into `skills/first-tree/`, renders\nscaffolding (`NODE.md`, `AGENTS.md`, `members/NODE.md`), and generates a task\nlist in `skills/first-tree/progress.md`.\n\nPublishing tip: keep the tree repo in the same GitHub organization as the\nsource repo unless you have a reason not to.\n\n### Step 2: Work Through the Task List\n\nRead `skills/first-tree/progress.md`. It contains a checklist tailored to the current state of the repo. Complete each task:\n\n- Fill in `NODE.md` with your organization name, owners, and domains\n- Add project-specific instructions to `AGENTS.md` below the framework markers\n- Create member nodes under `members/`\n- Optionally configure agent integration (e.g., Claude Code session hooks)\n- Copy validation workflows from `skills/first-tree/assets/framework/workflows/` to `.github/workflows/`\n\nAs you complete each task, check it off in `skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.\n\n### Step 3: Verify\n\n```bash\ncontext-tree verify\n```\n\nOr, from your source/workspace repo:\n\n```bash\ncontext-tree verify --tree-path ../my-org-context\n```\n\nThis fails if any items in `skills/first-tree/progress.md` remain unchecked, and runs deterministic checks (valid frontmatter, node structure, member nodes exist).\n\n### Step 4: Design Your Domains\n\nCreate top-level directories for your organization's primary concerns. Each needs a `NODE.md`:\n\n```\nmy-org-tree/\n  NODE.md              # root — lists all domains\n  engineering/\n    NODE.md            # decisions about architecture, infra, tooling\n  product/\n    NODE.md            # strategy, roadmap, user research\n  marketing/\n    NODE.md            # positioning, campaigns\n  members/\n    NODE.md            # team members and agents\n    alice/\n      NODE.md          # individual member node\n```\n\n### Step 5: Populate from Existing Work\n\nFor each domain, extract knowledge from existing repos, docs, and systems:\n\n- Decisions and their rationale\n- Cross-domain relationships and dependencies\n- Constraints that aren't obvious from the code\n\nThe tree doesn't duplicate source code — it captures what connects things and why they were built that way.\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `context-tree init` | Create or refresh a dedicated tree repo. By default, running in a source/workspace repo creates a sibling `<repo>-context`; use `--here` to initialize the current repo in place. |\n| `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. Use `--tree-path` when invoking from another working directory. |\n| `context-tree upgrade` | Refresh the installed framework skill from the currently running `first-tree` npm package and generate follow-up tasks. Use `--tree-path` when invoking from another working directory. |\n| `context-tree help onboarding` | Print this onboarding guide. |\n\n---\n\n## Upgrading the Framework\n\nWhen the framework updates:\n\n```bash\ncontext-tree upgrade\n```\n\n`context-tree upgrade` refreshes `skills/first-tree/` from the\nskill bundled with the currently running `first-tree` npm package, preserves your\ntree content, and generates follow-up tasks in\n`skills/first-tree/progress.md`.\n\nIf your repo still uses the older `skills/first-tree-cli-framework/` path,\n`context-tree upgrade` will migrate it to `skills/first-tree/` first.\n\nTo pick up a newer framework release, first run a newer package version, for\nexample `npx first-tree@latest upgrade`, or update your global `first-tree`\ninstall before running `context-tree upgrade`.\n\n---\n\n## Further Reading\n\n- `skills/first-tree/references/principles.md` — Core principles with detailed examples\n- `skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned\n- `AGENTS.md` in your tree — The before/during/after workflow for every task\n";
-//#endregion
-//#region skills/first-tree/engine/onboarding.ts
-function runOnboarding(output = console.log) {
-	output(onboarding_default);
-	return 0;
-}
-//#endregion
-export { onboarding_default as n, runOnboarding as t };