first-tree 0.0.2 → 0.0.3

package/dist/repo-BTJG8BU1.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+const SKILL_ROOT = join("skills", "first-tree");
+join(SKILL_ROOT, "agents");
+join(SKILL_ROOT, "references");
+const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
+join(FRAMEWORK_ASSET_ROOT, "manifest.json");
+const FRAMEWORK_VERSION = join(FRAMEWORK_ASSET_ROOT, "VERSION");
+const FRAMEWORK_TEMPLATES_DIR = join(FRAMEWORK_ASSET_ROOT, "templates");
+const FRAMEWORK_WORKFLOWS_DIR = join(FRAMEWORK_ASSET_ROOT, "workflows");
+join(FRAMEWORK_ASSET_ROOT, "prompts");
+const FRAMEWORK_EXAMPLES_DIR = join(FRAMEWORK_ASSET_ROOT, "examples");
+join(FRAMEWORK_ASSET_ROOT, "helpers");
+const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
+const LEGACY_SKILL_ROOT = join("skills", "first-tree-cli-framework");
+const LEGACY_SKILL_ASSET_ROOT = join(LEGACY_SKILL_ROOT, "assets", "framework");
+const LEGACY_SKILL_VERSION = join(LEGACY_SKILL_ASSET_ROOT, "VERSION");
+join(LEGACY_SKILL_ASSET_ROOT, "templates");
+join(LEGACY_SKILL_ASSET_ROOT, "workflows");
+join(LEGACY_SKILL_ASSET_ROOT, "prompts");
+join(LEGACY_SKILL_ASSET_ROOT, "examples");
+const LEGACY_SKILL_PROGRESS = join(LEGACY_SKILL_ROOT, "progress.md");
+const LEGACY_FRAMEWORK_ROOT = ".context-tree";
+const LEGACY_VERSION = join(LEGACY_FRAMEWORK_ROOT, "VERSION");
+const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
+join(LEGACY_FRAMEWORK_ROOT, "templates");
+join(LEGACY_FRAMEWORK_ROOT, "workflows");
+join(LEGACY_FRAMEWORK_ROOT, "prompts");
+join(LEGACY_FRAMEWORK_ROOT, "examples");
+function pathExists(root, relPath) {
+	const fullPath = join(root, relPath);
+	try {
+		return existsSync(fullPath);
+	} catch {
+		return false;
+	}
+}
+function frameworkVersionCandidates() {
+	return [
+		FRAMEWORK_VERSION,
+		LEGACY_SKILL_VERSION,
+		LEGACY_VERSION
+	];
+}
+function progressFileCandidates() {
+	return [
+		INSTALLED_PROGRESS,
+		LEGACY_SKILL_PROGRESS,
+		LEGACY_PROGRESS
+	];
+}
+function resolveFirstExistingPath(root, candidates) {
+	for (const candidate of candidates) if (pathExists(root, candidate)) return candidate;
+	return null;
+}
+function detectFrameworkLayout(root) {
+	if (pathExists(root, FRAMEWORK_VERSION)) return "skill";
+	if (pathExists(root, LEGACY_SKILL_VERSION)) return "legacy-skill";
+	if (pathExists(root, LEGACY_VERSION)) return "legacy";
+	return null;
+}
+//#endregion
+//#region skills/first-tree/engine/repo.ts
+const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
+const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
+const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
+const FRAMEWORK_END_MARKER = "<!-- END CONTEXT-TREE FRAMEWORK -->";
+var Repo = class {
+	root;
+	constructor(root) {
+		this.root = resolve(root ?? process.cwd());
+	}
+	pathExists(relPath) {
+		return existsSync(join(this.root, relPath));
+	}
+	fileContains(relPath, text) {
+		const fullPath = join(this.root, relPath);
+		try {
+			if (!statSync(fullPath).isFile()) return false;
+			return readFileSync(fullPath, "utf-8").includes(text);
+		} catch {
+			return false;
+		}
+	}
+	readFile(relPath) {
+		try {
+			return readFileSync(join(this.root, relPath), "utf-8");
+		} catch {
+			return null;
+		}
+	}
+	frontmatter(relPath) {
+		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 = {};
+		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 !== void 0 || result.owners !== void 0 ? result : null;
+	}
+	anyAgentConfig() {
+		return [".claude/settings.json", ".codex/config.json"].some((c) => this.pathExists(c));
+	}
+	isGitRepo() {
+		try {
+			return statSync(join(this.root, ".git")).isDirectory();
+		} catch {
+			return false;
+		}
+	}
+	hasFramework() {
+		return this.frameworkLayout() !== null;
+	}
+	frameworkLayout() {
+		return detectFrameworkLayout(this.root);
+	}
+	readVersion() {
+		const versionPath = resolveFirstExistingPath(this.root, frameworkVersionCandidates());
+		if (versionPath === null) return null;
+		const text = this.readFile(versionPath);
+		return text ? text.trim() : null;
+	}
+	progressPath() {
+		return resolveFirstExistingPath(this.root, progressFileCandidates());
+	}
+	preferredProgressPath() {
+		const layout = this.frameworkLayout();
+		if (layout === "legacy") return LEGACY_PROGRESS;
+		if (layout === "legacy-skill") return LEGACY_SKILL_PROGRESS;
+		return INSTALLED_PROGRESS;
+	}
+	frameworkVersionPath() {
+		const layout = this.frameworkLayout();
+		if (layout === "legacy") return LEGACY_VERSION;
+		if (layout === "legacy-skill") return LEGACY_SKILL_VERSION;
+		return FRAMEWORK_VERSION;
+	}
+	hasAgentMdMarkers() {
+		const text = this.readFile("AGENT.md");
+		if (text === null) return false;
+		return text.includes("<!-- BEGIN CONTEXT-TREE FRAMEWORK") && text.includes("<!-- END CONTEXT-TREE FRAMEWORK -->");
+	}
+	hasMembers() {
+		const membersDir = join(this.root, "members");
+		try {
+			if (!statSync(membersDir).isDirectory()) return false;
+		} catch {
+			return false;
+		}
+		return existsSync(join(membersDir, "NODE.md"));
+	}
+	memberCount() {
+		const membersDir = join(this.root, "members");
+		try {
+			if (!statSync(membersDir).isDirectory()) return 0;
+		} catch {
+			return 0;
+		}
+		let count = 0;
+		const walk = (dir) => {
+			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() {
+		return this.fileContains("NODE.md", "<!-- PLACEHOLDER");
+	}
+};
+//#endregion
+export { FRAMEWORK_TEMPLATES_DIR as a, INSTALLED_PROGRESS as c, SKILL_ROOT as d, FRAMEWORK_EXAMPLES_DIR as i, LEGACY_FRAMEWORK_ROOT as l, Repo as n, FRAMEWORK_VERSION as o, FRAMEWORK_ASSET_ROOT as r, FRAMEWORK_WORKFLOWS_DIR as s, FRAMEWORK_END_MARKER as t, LEGACY_SKILL_ROOT as u };

package/dist/upgrade-COGgI7Rj.js

@@ -0,0 +1,96 @@
+import { a as FRAMEWORK_TEMPLATES_DIR, c as INSTALLED_PROGRESS, d as SKILL_ROOT, l as LEGACY_FRAMEWORK_ROOT, n as Repo, o as FRAMEWORK_VERSION, s as FRAMEWORK_WORKFLOWS_DIR, u as LEGACY_SKILL_ROOT } from "./repo-BTJG8BU1.js";
+import { i as resolveCanonicalSkillRoot, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-rcZpGLnM.js";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region skills/first-tree/engine/runtime/upgrader.ts
+function compareFrameworkVersions(left, right) {
+	const result = left.localeCompare(right, void 0, {
+		numeric: true,
+		sensitivity: "base"
+	});
+	if (result < 0) return -1;
+	if (result > 0) return 1;
+	return 0;
+}
+function readSourceVersion(sourceRoot) {
+	const versionPath = join(resolveCanonicalSkillRoot(sourceRoot), "assets", "framework", "VERSION");
+	try {
+		return readFileSync(versionPath, "utf-8").trim();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region skills/first-tree/engine/upgrade.ts
+function writeProgress(repo, content) {
+	const progressPath = join(repo.root, repo.preferredProgressPath());
+	mkdirSync(dirname(progressPath), { recursive: true });
+	writeFileSync(progressPath, content);
+}
+function formatUpgradeTaskList(repo, localVersion, packagedVersion, layout) {
+	const lines = [
+		`# Context Tree Upgrade — v${localVersion} -> v${packagedVersion}\n`,
+		"## Installed Skill",
+		`- [ ] Review local customizations under \`${SKILL_ROOT}/\` 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/\``,
+		""
+	];
+	if (layout === "legacy") lines.push("## Migration", "- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files", "");
+	if (layout === "legacy-skill") lines.push("## Migration", `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`, "");
+	if (repo.hasAgentMdMarkers()) lines.push("## Agent Instructions", `- [ ] Compare the framework section in \`AGENT.md\` with \`${FRAMEWORK_TEMPLATES_DIR}/agent.md.template\` and update the content between the markers if needed`, "");
+	lines.push("## Verification", `- [ ] \`${FRAMEWORK_VERSION}\` reads \`${packagedVersion}\``, "- [ ] `context-tree verify` passes", "", "---", "", `**Important:** As you complete each task, check it off in \`${INSTALLED_PROGRESS}\` by changing \`- [ ]\` to \`- [x]\`. Run \`context-tree verify\` when done — it will fail if any items remain unchecked.`, "");
+	return lines.join("\n");
+}
+function runUpgrade(repo, options) {
+	const workingRepo = repo ?? new Repo();
+	if (!workingRepo.hasFramework()) {
+		console.error("Error: no installed framework skill found. Run `context-tree init` first.");
+		return 1;
+	}
+	const layout = workingRepo.frameworkLayout();
+	if (layout === null) {
+		console.error("Error: no installed framework skill found. Run `context-tree init` first.");
+		return 1;
+	}
+	const localVersion = workingRepo.readVersion() ?? "unknown";
+	console.log(`Local framework version: ${localVersion}\n`);
+	console.log("Checking the framework skill bundled with this first-tree package...");
+	let sourceRoot;
+	try {
+		sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : "unknown error";
+		console.error(`Error: ${message}`);
+		return 1;
+	}
+	const packagedVersion = readSourceVersion(sourceRoot);
+	if (packagedVersion === null) {
+		console.log("Could not read the bundled framework version. Reinstall or update `first-tree` and try again.");
+		return 1;
+	}
+	if (localVersion !== "unknown" && compareFrameworkVersions(localVersion, packagedVersion) > 0) {
+		console.log("The installed framework is newer than the skill bundled with this `first-tree` package. Install a newer package version before running `context-tree upgrade`.");
+		return 1;
+	}
+	if (layout === "skill" && packagedVersion === localVersion) {
+		console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
+		return 0;
+	}
+	copyCanonicalSkill(sourceRoot, workingRepo.root);
+	if (layout === "legacy") {
+		rmSync(join(workingRepo.root, LEGACY_FRAMEWORK_ROOT), {
+			recursive: true,
+			force: true
+		});
+		console.log("Migrated legacy .context-tree/ layout to skills/first-tree/.");
+	} else if (layout === "legacy-skill") console.log("Migrated skills/first-tree-cli-framework/ to skills/first-tree/.");
+	else console.log("Refreshed skills/first-tree/ from the bundled first-tree package.");
+	const output = formatUpgradeTaskList(workingRepo, localVersion, packagedVersion, layout);
+	console.log(`\n${output}`);
+	writeProgress(workingRepo, output);
+	console.log(`Progress file written to ${workingRepo.preferredProgressPath()}`);
+	return 0;
+}
+//#endregion
+export { runUpgrade };

package/dist/{verify-CSRIkuoM.js → verify-CxN6JiV9.js}

@@ -1,7 +1,7 @@
-import { n as Repo } from "./repo-BByc3VvM.js";
+import { n as Repo } from "./repo-BTJG8BU1.js";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-//#region src/validators/members.ts
+//#region skills/first-tree/engine/validators/members.ts
 const FRONTMATTER_RE$1 = /^---\s*\n(.*?)\n---/s;
 const VALID_TYPES = new Set([
 	"human",
@@ -64,25 +64,51 @@ function runValidateMembers(treeRoot) {
 	}
 	const allErrors = [];
 	let memberCount = 0;
-	for (const child of readdirSync(membersDir).sort()) {
-		const childPath = join(membersDir, child);
-		try {
-			const stat = statSync(childPath);
-			if (stat.isFile() && child.endsWith(".md") && child !== "NODE.md") {
-				allErrors.push(`${rel$1(childPath, treeRoot)}: member must be a directory with NODE.md, not a standalone file — use members/${child.replace(/\.md$/, "")}/NODE.md instead`);
+	const nameOccurrences = /* @__PURE__ */ new Map();
+	const members = [];
+	function walk(dir) {
+		for (const child of readdirSync(dir).sort()) {
+			const childPath = join(dir, child);
+			try {
+				const stat = statSync(childPath);
+				if (stat.isFile() && child.endsWith(".md") && child !== "NODE.md") {
+					allErrors.push(`${rel$1(childPath, treeRoot)}: member must be a directory with NODE.md, not a standalone file — use ${rel$1(dir, treeRoot)}/${child.replace(/\.md$/, "")}/NODE.md instead`);
+					continue;
+				}
+				if (!stat.isDirectory()) continue;
+			} catch {
 				continue;
 			}
-			if (!stat.isDirectory()) continue;
-		} catch {
-			continue;
-		}
-		const nodePath = join(childPath, "NODE.md");
-		if (!existsSync(nodePath)) {
-			allErrors.push(`${rel$1(childPath, treeRoot)}/: directory exists but missing NODE.md`);
-			continue;
+			const relPath = relative(membersDir, childPath);
+			const occurrences = nameOccurrences.get(child) ?? [];
+			occurrences.push(relPath);
+			nameOccurrences.set(child, occurrences);
+			const nodePath = join(childPath, "NODE.md");
+			if (!existsSync(nodePath)) {
+				allErrors.push(`${rel$1(childPath, treeRoot)}/: directory exists but missing NODE.md`);
+				walk(childPath);
+				continue;
+			}
+			memberCount++;
+			allErrors.push(...validateMember(nodePath, treeRoot));
+			const fm = parseFrontmatter$1(nodePath);
+			if (fm) members.push({
+				name: child,
+				relPath,
+				type: extractScalar(fm, "type"),
+				delegateMention: extractScalar(fm, "delegate_mention")
+			});
+			walk(childPath);
 		}
-		memberCount++;
-		allErrors.push(...validateMember(nodePath, treeRoot));
+	}
+	walk(membersDir);
+	for (const [name, paths] of nameOccurrences) if (paths.length > 1) allErrors.push(`Duplicate member directory name '${name}' found at: ${paths.map((p) => `members/${p}`).join(", ")} — directory names must be unique across all levels under members/`);
+	const memberByName = new Map(members.map((m) => [m.name, m]));
+	for (const member of members) {
+		if (!member.delegateMention) continue;
+		const target = memberByName.get(member.delegateMention);
+		if (!target) allErrors.push(`members/${member.relPath}/NODE.md: delegate_mention '${member.delegateMention}' references non-existent member — the target must be a directory under members/`);
+		else if (target.type !== "personal_assistant") allErrors.push(`members/${member.relPath}/NODE.md: delegate_mention '${member.delegateMention}' must reference a member with type 'personal_assistant', but '${target.name}' has type '${target.type}'`);
 	}
 	if (allErrors.length > 0) {
 		console.log(`Found ${allErrors.length} member validation error(s):\n`);
@@ -99,7 +125,7 @@ function runValidateMembers(treeRoot) {
 	};
 }
 //#endregion
-//#region src/validators/nodes.ts
+//#region skills/first-tree/engine/validators/nodes.ts
 const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
 const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
 const SOFT_LINKS_INLINE_RE = /^soft_links:\s*\[([^\]]*)\]/m;
@@ -441,14 +467,15 @@ function runValidateNodes(root) {
 	};
 }
 //#endregion
-//#region src/verify.ts
+//#region skills/first-tree/engine/verify.ts
 const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
 function check(label, passed) {
 	console.log(`  ${passed ? "✓" : "✗"} [${passed ? "PASS" : "FAIL"}] ${label}`);
 	return passed;
 }
 function checkProgress(repo) {
-	const text = repo.readFile(".context-tree/progress.md");
+	const progressPath = repo.progressPath();
+	const text = progressPath === null ? null : repo.readFile(progressPath);
 	if (text === null) return [];
 	const matches = [];
 	let m;
@@ -464,17 +491,19 @@ function runVerify(repo, nodeValidator) {
 	const r = repo ?? new Repo();
 	const validate = nodeValidator ?? defaultNodeValidator;
 	let allPassed = true;
+	const progressPath = r.progressPath() ?? r.preferredProgressPath();
+	const frameworkVersionPath = r.frameworkVersionPath();
 	console.log("Context Tree Verification\n");
 	const unchecked = checkProgress(r);
 	if (unchecked.length > 0) {
-		console.log("  Unchecked items in .context-tree/progress.md:\n");
+		console.log(`  Unchecked items in ${progressPath}:\n`);
 		for (const item of unchecked) console.log(`    - [ ] ${item}`);
 		console.log();
-		console.log("  Verify each step above and check it off in progress.md before running verify again.\n");
+		console.log(`  Verify each step above and check it off in ${progressPath} before running verify again.\n`);
 		allPassed = false;
 	}
 	console.log("  Checks:\n");
-	allPassed = check(".context-tree/VERSION exists", r.hasFramework()) && allPassed;
+	allPassed = check(`${frameworkVersionPath} exists`, r.hasFramework()) && allPassed;
 	const fm = r.frontmatter("NODE.md");
 	allPassed = check("Root NODE.md has valid frontmatter (title, owners)", fm !== null && fm.title !== void 0 && fm.owners !== void 0) && allPassed;
 	allPassed = check("AGENT.md exists with framework markers", r.hasAgentMdMarkers()) && allPassed;

package/package.json

@@ -1,25 +1,48 @@
 {
   "name": "first-tree",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "CLI tools for Context Tree — the living source of truth for your organization.",
+  "homepage": "https://github.com/agent-team-foundation/first-tree#readme",
+  "bugs": {
+    "url": "https://github.com/agent-team-foundation/first-tree/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agent-team-foundation/first-tree.git"
+  },
+  "keywords": [
+    "context-tree",
+    "cli",
+    "agents",
+    "knowledge-base",
+    "markdown"
+  ],
   "type": "module",
   "bin": {
     "context-tree": "./dist/cli.js"
   },
+  "imports": {
+    "#skill/*": "./skills/first-tree/*",
+    "#evals/*": "./evals/*",
+    "#src/*": "./src/*"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills/first-tree"
   ],
-  "scripts": {
-    "build": "tsdown src/cli.ts --format esm --out-dir dist",
-    "prepack": "pnpm build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsdown": "^0.12.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.2.0"
+    "vitest": "^3.2.0",
+    "yaml": "^2.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "eval": "vitest run --config vitest.eval.config.ts",
+    "typecheck": "tsc --noEmit",
+    "validate:skill": "python3 ./skills/first-tree/scripts/quick_validate.py ./skills/first-tree && bash ./skills/first-tree/scripts/check-skill-sync.sh"
   }
-}
+}

package/skills/first-tree/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: first-tree
+description: Maintain the canonical `first-tree` skill and the thin `context-tree` CLI distributed by the `first-tree` npm package. Use when modifying `context-tree` commands (`init`, `verify`, `upgrade`, `help onboarding`), the installed skill payload under `assets/framework/`, maintainer references, or the build, packaging, test, and CI wiring that supports the framework.
+---
+
+# First Tree
+
+Use this skill when the task depends on the exact behavior of the
+`context-tree` CLI or the installed `skills/first-tree/` payload that
+`context-tree init` ships to user repos.
+
+## Source Of Truth
+
+- `skills/first-tree/` is the only canonical copy.
+- `references/` holds the explanatory docs the skill should load on demand.
+- `assets/framework/` holds the runtime payload that gets installed into user
+  repos.
+- `engine/` holds the canonical framework and CLI behavior.
+- `scripts/` holds maintenance helpers for validating and running the skill.
+- In maintainer docs, use `context-tree` for the CLI and `skills/first-tree/`
+  for the installed skill path so it is not confused with the `first-tree`
+  npm package.
+
+## When To Read What
+
+1. Start with `references/source-map.md` to locate the right files.
+2. Read the user-facing reference that matches the task:
+   - `references/onboarding.md`
+   - `references/about.md`
+   - `references/principles.md`
+   - `references/ownership-and-naming.md`
+   - `references/upgrade-contract.md`
+3. Read the maintainer reference that matches the shell or validation surface:
+   - `references/maintainer-architecture.md`
+   - `references/maintainer-thin-cli.md`
+   - `references/maintainer-build-and-distribution.md`
+   - `references/maintainer-testing.md`
+4. Open `engine/` when changing `init`, `verify`, `upgrade`, command routing,
+   repo inspection, rules, runtime helpers, or validators.
+5. Open `assets/framework/` only when the task changes shipped templates,
+   workflows, prompts, examples, or helper scripts.
+6. Open `tests/` when changing validation coverage or maintainer workflows.
+7. Use `./scripts/run-local-cli.sh <command>` when you need to exercise the
+   live CLI from this repo.
+
+## Working Modes
+
+### Maintaining `first-tree`
+
+- Treat this repo as the distribution source for one canonical skill plus a
+  thin CLI shell, not as a tree repo.
+- Keep command behavior, validator behavior, shipped assets, maintainer
+  references, and package shell aligned.
+- If root README/AGENT/CI text explains something non-obvious, migrate that
+  information into `references/` and trim the root file back down.
+- If you change runtime assets or skill references, run `pnpm validate:skill`.
+
+### Working In A User Tree Repo
+
+- `context-tree init` installs this skill into the user's repo and scaffolds
+  `NODE.md`, `AGENT.md`, and `members/NODE.md`.
+- `context-tree upgrade` refreshes the installed skill from the copy bundled
+  with the currently running `first-tree` package. To pick up a newer
+  framework, run a newer package version first. It also migrates older repos
+  that still use `skills/first-tree-cli-framework/`.
+- The user's tree content lives outside the skill; the skill only carries the
+  reusable framework payload plus maintenance guidance.
+- The tree still stores decisions, constraints, and ownership; execution detail
+  stays in source systems.
+
+## Non-Negotiables
+
+- Preserve the CLI contract that it scaffolds, prints task lists, and validates
+  state; it does not fully automate tree maintenance.
+- Keep shipped assets generic. They must not contain org-specific content.
+- Keep decision knowledge in the tree and execution detail in source systems.
+- Keep the skill as the only canonical knowledge source. The root CLI/package
+  shell must not become a second source of framework semantics.
+- Keep normal `init` / `upgrade` flows self-contained. They must work from the
+  skill bundled in the current package without cloning the source repo.
+- Make upgrade behavior explicit. If you change installed paths, update
+  `references/upgrade-contract.md`, task text, and tests together.
+
+## Validation
+
+- Repo checks: `pnpm typecheck`, `pnpm test`, `pnpm build`
+- Packaging check: `pnpm pack` when changing package contents or install/upgrade
+  behavior
+- Skill checks:
+  - `pnpm validate:skill`
+  - `python3 ./skills/first-tree/scripts/quick_validate.py ./skills/first-tree`
+  - `bash ./skills/first-tree/scripts/check-skill-sync.sh`
+
+## Key Files
+
+- `assets/framework/manifest.json`: runtime asset contract
+- `assets/framework/templates/`: generated scaffolds
+- `assets/framework/workflows/`: CI templates
+- `assets/framework/helpers/`: shipped helper scripts and review tooling
+- `engine/`: canonical framework and CLI behavior
+- `tests/`: canonical unit and structure validation
+- `references/source-map.md`: canonical reading index
+- `references/maintainer-architecture.md`: source-repo architecture and
+  invariants
+- `references/maintainer-thin-cli.md`: root shell contract
+- `references/maintainer-build-and-distribution.md`: packaging and release
+  guidance
+- `references/maintainer-testing.md`: validation workflow
+- `references/upgrade-contract.md`: installed layout and upgrade semantics

package/skills/first-tree/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "First Tree"
+  short_description: "Maintain the First Tree skill and thin Context Tree CLI"
+  default_prompt: "Use $first-tree to maintain the canonical first-tree skill, its thin context-tree CLI, or its build, packaging, test, eval, and CI wiring."

package/skills/first-tree/assets/framework/VERSION

@@ -0,0 +1 @@
+0.1.0

package/skills/first-tree/assets/framework/examples/claude-code/README.md

@@ -0,0 +1,14 @@
+# Claude Code Integration
+
+## Setup
+
+Copy `settings.json` to your tree repo's `.claude/` directory:
+
+```bash
+mkdir -p .claude
+cp skills/first-tree/assets/framework/examples/claude-code/settings.json .claude/settings.json
+```
+
+## What It Does
+
+The `SessionStart` hook runs `./skills/first-tree/assets/framework/helpers/inject-tree-context.sh` when a Claude Code session begins. This injects the root `NODE.md` content as additional context, giving the agent an overview of the tree structure before any task.

package/skills/first-tree/assets/framework/examples/claude-code/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./skills/first-tree/assets/framework/helpers/inject-tree-context.sh"
+          }
+        ]
+      }
+    ]
+  }
+}