first-tree 0.0.3 → 0.0.4

package/dist/{repo-BTJG8BU1.js → repo-DY57bMqr.js}

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
-const SKILL_ROOT = join("skills", "first-tree");
+import { basename, dirname, join, resolve } from "node:path";
+//#region skills/first-tree/engine/runtime/asset-loader.ts
+const SKILL_NAME = "first-tree";
+const SKILL_ROOT = join("skills", SKILL_NAME);
 join(SKILL_ROOT, "agents");
 join(SKILL_ROOT, "references");
 const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
@@ -12,7 +14,11 @@ 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 AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
+const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
+const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
+const LEGACY_SKILL_NAME = "first-tree-cli-framework";
+const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
 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");
@@ -49,6 +55,9 @@ function progressFileCandidates() {
 		LEGACY_PROGRESS
 	];
 }
+function agentInstructionsFileCandidates() {
+	return [AGENT_INSTRUCTIONS_FILE, LEGACY_AGENT_INSTRUCTIONS_FILE];
+}
 function resolveFirstExistingPath(root, candidates) {
 	for (const candidate of candidates) if (pathExists(root, candidate)) return candidate;
 	return null;
@@ -64,11 +73,82 @@ function detectFrameworkLayout(root) {
 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"
+]);
 const FRAMEWORK_END_MARKER = "<!-- END CONTEXT-TREE FRAMEWORK -->";
+function hasGitMetadata(root) {
+	try {
+		const stat = statSync(join(root, ".git"));
+		return stat.isDirectory() || stat.isFile();
+	} catch {
+		return false;
+	}
+}
+function discoverGitRoot(start) {
+	let dir = start;
+	while (true) {
+		if (hasGitMetadata(dir)) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
 var Repo = class {
 	root;
 	constructor(root) {
-		this.root = resolve(root ?? process.cwd());
+		const start = resolve(root ?? process.cwd());
+		this.root = root === void 0 ? discoverGitRoot(start) ?? start : start;
 	}
 	pathExists(relPath) {
 		return existsSync(join(this.root, relPath));
@@ -109,11 +189,7 @@ var Repo = class {
 		return [".claude/settings.json", ".codex/config.json"].some((c) => this.pathExists(c));
 	}
 	isGitRepo() {
-		try {
-			return statSync(join(this.root, ".git")).isDirectory();
-		} catch {
-			return false;
-		}
+		return hasGitMetadata(this.root);
 	}
 	hasFramework() {
 		return this.frameworkLayout() !== null;
@@ -142,8 +218,25 @@ var Repo = class {
 		if (layout === "legacy-skill") return LEGACY_SKILL_VERSION;
 		return FRAMEWORK_VERSION;
 	}
-	hasAgentMdMarkers() {
-		const text = this.readFile("AGENT.md");
+	agentInstructionsPath() {
+		return resolveFirstExistingPath(this.root, agentInstructionsFileCandidates());
+	}
+	hasCanonicalAgentInstructionsFile() {
+		return this.pathExists(AGENT_INSTRUCTIONS_FILE);
+	}
+	hasLegacyAgentInstructionsFile() {
+		return this.pathExists(LEGACY_AGENT_INSTRUCTIONS_FILE);
+	}
+	hasDuplicateAgentInstructionsFiles() {
+		return this.hasCanonicalAgentInstructionsFile() && this.hasLegacyAgentInstructionsFile();
+	}
+	readAgentInstructions() {
+		const relPath = this.agentInstructionsPath();
+		if (relPath === null) return null;
+		return this.readFile(relPath);
+	}
+	hasAgentInstructionsMarkers() {
+		const text = this.readAgentInstructions();
 		if (text === null) return false;
 		return text.includes("<!-- BEGIN CONTEXT-TREE FRAMEWORK") && text.includes("<!-- END CONTEXT-TREE FRAMEWORK -->");
 	}
@@ -182,6 +275,44 @@ var Repo = class {
 	hasPlaceholderNode() {
 		return this.fileContains("NODE.md", "<!-- PLACEHOLDER");
 	}
+	repoName() {
+		return basename(this.root);
+	}
+	topLevelEntries() {
+		try {
+			return readdirSync(this.root).filter((entry) => entry !== ".git");
+		} catch {
+			return [];
+		}
+	}
+	looksLikeTreeRepo() {
+		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() {
+		return this.topLevelEntries().filter((entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry)).length === 0;
+	}
+	isLikelySourceRepo() {
+		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, relPath) {
+	try {
+		return statSync(join(root, relPath)).isDirectory();
+	} catch {
+		return false;
+	}
+}
 //#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 };
+export { FRAMEWORK_ASSET_ROOT as a, FRAMEWORK_VERSION as c, LEGACY_AGENT_INSTRUCTIONS_FILE as d, LEGACY_FRAMEWORK_ROOT as f, SKILL_ROOT as g, SKILL_NAME as h, AGENT_INSTRUCTIONS_TEMPLATE as i, FRAMEWORK_WORKFLOWS_DIR as l, LEGACY_SKILL_ROOT as m, Repo as n, FRAMEWORK_EXAMPLES_DIR as o, LEGACY_SKILL_NAME as p, AGENT_INSTRUCTIONS_FILE as r, FRAMEWORK_TEMPLATES_DIR as s, FRAMEWORK_END_MARKER as t, INSTALLED_PROGRESS as u };

package/dist/{upgrade-COGgI7Rj.js → upgrade-Cgx_K2HM.js}

@@ -1,7 +1,7 @@
-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 { c as FRAMEWORK_VERSION, d as LEGACY_AGENT_INSTRUCTIONS_FILE, f as LEGACY_FRAMEWORK_ROOT, g as SKILL_ROOT, i as AGENT_INSTRUCTIONS_TEMPLATE, l as FRAMEWORK_WORKFLOWS_DIR, m as LEGACY_SKILL_ROOT, n as Repo, r as AGENT_INSTRUCTIONS_FILE, s as FRAMEWORK_TEMPLATES_DIR, u as INSTALLED_PROGRESS } from "./repo-DY57bMqr.js";
+import { i as resolveCanonicalSkillRoot, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-cH7N4RNj.js";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 //#region skills/first-tree/engine/runtime/upgrader.ts
 function compareFrameworkVersions(left, right) {
 	const result = left.localeCompare(right, void 0, {
@@ -22,6 +22,12 @@ function readSourceVersion(sourceRoot) {
 }
 //#endregion
 //#region skills/first-tree/engine/upgrade.ts
+const UPGRADE_USAGE = `usage: context-tree upgrade [--tree-path PATH]
+
+Options:
+  --tree-path PATH   Upgrade a tree repo from another working directory
+  --help             Show this help message
+`;
 function writeProgress(repo, content) {
 	const progressPath = join(repo.root, repo.preferredProgressPath());
 	mkdirSync(dirname(progressPath), { recursive: true });
@@ -36,14 +42,22 @@ function formatUpgradeTaskList(repo, localVersion, packagedVersion, layout) {
 		`- [ ] 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`, "");
+	const migrationTasks = [];
+	if (layout === "legacy") migrationTasks.push("- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files");
+	if (layout === "legacy-skill") migrationTasks.push(`- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`);
+	if (repo.hasCanonicalAgentInstructionsFile() && repo.hasLegacyAgentInstructionsFile()) migrationTasks.push(`- [ ] Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`);
+	else if (repo.hasLegacyAgentInstructionsFile()) migrationTasks.push(`- [ ] Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`);
+	if (migrationTasks.length > 0) lines.push("## Migration", ...migrationTasks, "");
+	if (repo.hasAgentInstructionsMarkers()) lines.push("## Agent Instructions", `- [ ] Compare the framework section in \`${AGENT_INSTRUCTIONS_FILE}\` with \`${FRAMEWORK_TEMPLATES_DIR}/${AGENT_INSTRUCTIONS_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.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo()) {
+		console.error("Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to upgrade an existing tree repo.");
+		return 1;
+	}
 	if (!workingRepo.hasFramework()) {
 		console.error("Error: no installed framework skill found. Run `context-tree init` first.");
 		return 1;
@@ -92,5 +106,30 @@ function runUpgrade(repo, options) {
 	console.log(`Progress file written to ${workingRepo.preferredProgressPath()}`);
 	return 0;
 }
+function runUpgradeCli(args = []) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(UPGRADE_USAGE);
+		return 0;
+	}
+	let treePath;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--tree-path") {
+			const value = args[index + 1];
+			if (!value) {
+				console.error("Missing value for --tree-path");
+				console.log(UPGRADE_USAGE);
+				return 1;
+			}
+			treePath = value;
+			index += 1;
+			continue;
+		}
+		console.error(`Unknown upgrade option: ${arg}`);
+		console.log(UPGRADE_USAGE);
+		return 1;
+	}
+	return runUpgrade(treePath ? new Repo(resolve(process.cwd(), treePath)) : void 0);
+}
 //#endregion
-export { runUpgrade };
+export { runUpgradeCli as runUpgrade };

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

@@ -1,6 +1,6 @@
-import { n as Repo } from "./repo-BTJG8BU1.js";
+import { d as LEGACY_AGENT_INSTRUCTIONS_FILE, g as SKILL_ROOT, m as LEGACY_SKILL_ROOT, n as Repo, r as AGENT_INSTRUCTIONS_FILE } from "./repo-DY57bMqr.js";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
 //#region skills/first-tree/engine/validators/members.ts
 const FRONTMATTER_RE$1 = /^---\s*\n(.*?)\n---/s;
 const VALID_TYPES = new Set([
@@ -133,7 +133,11 @@ const SOFT_LINKS_BLOCK_RE = /^soft_links:\s*\n((?:\s+-\s+.+\n?)+)/m;
 const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
 const GITHUB_USER_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/;
 const SKIP = new Set(["node_modules", "__pycache__"]);
-const SKIP_FILES = new Set(["AGENT.md", "CLAUDE.md"]);
+const SKIP_FILES = new Set([
+	AGENT_INSTRUCTIONS_FILE,
+	LEGACY_AGENT_INSTRUCTIONS_FILE,
+	"CLAUDE.md"
+]);
 const MIN_BODY_LENGTH = 20;
 var Findings = class {
 	errors = [];
@@ -181,8 +185,23 @@ function setTreeRoot(root) {
 function rel(path) {
 	return relative(treeRoot, path);
 }
+function isInstalledSkillPath(relPath) {
+	return relPath === SKILL_ROOT || relPath.startsWith(`${SKILL_ROOT}/`) || relPath === LEGACY_SKILL_ROOT || relPath.startsWith(`${LEGACY_SKILL_ROOT}/`);
+}
+function isFrameworkContainerDir(relPath, fullPath) {
+	if (relPath !== "skills") return false;
+	try {
+		const entries = readdirSync(fullPath).filter((entry) => !entry.startsWith("."));
+		if (entries.length === 0) return false;
+		return entries.every((entry) => entry === "first-tree" || entry === "first-tree-cli-framework");
+	} catch {
+		return false;
+	}
+}
 function shouldSkip(path) {
-	return relative(treeRoot, path).split("/").some((part) => SKIP.has(part) || part.startsWith("."));
+	const relPath = relative(treeRoot, path);
+	if (relPath.split("/").some((part) => SKIP.has(part) || part.startsWith("."))) return true;
+	return isInstalledSkillPath(relPath) || isFrameworkContainerDir(relPath, path);
 }
 function readText(path) {
 	if (!textCache.has(path)) try {
@@ -469,6 +488,12 @@ function runValidateNodes(root) {
 //#endregion
 //#region skills/first-tree/engine/verify.ts
 const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
+const VERIFY_USAGE = `usage: context-tree verify [--tree-path PATH]
+
+Options:
+  --tree-path PATH   Verify a tree repo from another working directory
+  --help             Show this help message
+`;
 function check(label, passed) {
 	console.log(`  ${passed ? "✓" : "✗"} [${passed ? "PASS" : "FAIL"}] ${label}`);
 	return passed;
@@ -490,6 +515,10 @@ function defaultNodeValidator(root) {
 function runVerify(repo, nodeValidator) {
 	const r = repo ?? new Repo();
 	const validate = nodeValidator ?? defaultNodeValidator;
+	if (r.isLikelySourceRepo() && !r.looksLikeTreeRepo()) {
+		console.error("Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to verify an existing tree repo.");
+		return 1;
+	}
 	let allPassed = true;
 	const progressPath = r.progressPath() ?? r.preferredProgressPath();
 	const frameworkVersionPath = r.frameworkVersionPath();
@@ -506,7 +535,13 @@ function runVerify(repo, nodeValidator) {
 	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;
+	const hasCanonicalAgentInstructions = r.hasCanonicalAgentInstructionsFile();
+	const hasLegacyAgentInstructions = r.hasLegacyAgentInstructionsFile();
+	if (hasLegacyAgentInstructions) {
+		const followUp = hasCanonicalAgentInstructions ? `Remove legacy \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` after confirming its contents are in \`${AGENT_INSTRUCTIONS_FILE}\`.` : `Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\`.`;
+		console.log(`  Legacy agent instructions detected. ${followUp}\n`);
+	}
+	allPassed = check(`AGENTS.md is the only agent instructions file and has framework markers`, hasCanonicalAgentInstructions && !hasLegacyAgentInstructions && r.hasAgentInstructionsMarkers()) && allPassed;
 	const { exitCode } = validate(r.root);
 	allPassed = check("Node validation passes", exitCode === 0) && allPassed;
 	allPassed = check("Member validation passes", runValidateMembers(r.root).exitCode === 0) && allPassed;
@@ -515,5 +550,30 @@ function runVerify(repo, nodeValidator) {
 	else console.log("Some checks failed. See above for details.");
 	return allPassed ? 0 : 1;
 }
+function runVerifyCli(args = []) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(VERIFY_USAGE);
+		return 0;
+	}
+	let treePath;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--tree-path") {
+			const value = args[index + 1];
+			if (!value) {
+				console.error("Missing value for --tree-path");
+				console.log(VERIFY_USAGE);
+				return 1;
+			}
+			treePath = value;
+			index += 1;
+			continue;
+		}
+		console.error(`Unknown verify option: ${arg}`);
+		console.log(VERIFY_USAGE);
+		return 1;
+	}
+	return runVerify(treePath ? new Repo(resolve(process.cwd(), treePath)) : void 0);
+}
 //#endregion
-export { runVerify };
+export { runVerifyCli as runVerify };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-tree",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "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": {

package/skills/first-tree/SKILL.md

@@ -51,14 +51,17 @@ Use this skill when the task depends on the exact behavior of the
   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
+- If root README/AGENTS/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 init` defaults to creating or reusing a sibling dedicated tree
+  repo when invoked from a source/workspace repo. Use `--here` to initialize
+  the current repo in place when you are already inside the tree repo.
+- `context-tree init` installs this skill into the target tree repo and
+  `NODE.md`, `AGENTS.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
@@ -77,7 +80,8 @@ Use this skill when the task depends on the exact behavior of the
 - 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.
+  skill bundled in the current package without cloning the source repo or
+  relying on network access.
 - Make upgrade behavior explicit. If you change installed paths, update
   `references/upgrade-contract.md`, task text, and tests together.
 

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

@@ -1 +1 @@
-0.1.0
+0.2.0

package/skills/first-tree/assets/framework/helpers/run-review.ts

@@ -8,7 +8,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -17,11 +17,25 @@ const MAX_ATTEMPTS = 3;
 // Per-invocation budget cap. Worst case is $1.50 total (3 × $0.50),
 // though retries are cheap in practice due to cached context via --continue.
 const MAX_BUDGET_USD = 0.5;
+const AGENT_INSTRUCTIONS_PATHS = ["AGENTS.md", "AGENT.md"] as const;
+
+function resolveAgentInstructionsPath(): string {
+  for (const candidate of AGENT_INSTRUCTIONS_PATHS) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    "Missing AGENTS.md in repo root (legacy AGENT.md is also accepted during migration).",
+  );
+}
 
 function buildPrompt(diffPath: string): string {
   const parts: string[] = [];
+  const agentInstructionsPath = resolveAgentInstructionsPath();
   const files: [string, string][] = [
-    ["AGENT.md", "AGENT.md"],
+    [agentInstructionsPath, agentInstructionsPath],
     ["Root NODE.md", "NODE.md"],
     [
       "Review Instructions",

package/skills/first-tree/assets/framework/templates/{agent.md.template → agents.md.template}

@@ -28,6 +28,7 @@ Do not skip this. The tree is already a compression of expensive knowledge — c
 
 - **Decide in the tree, execute in source systems.** If the task involves a decision (not just a bug fix), draft or update the relevant tree node before executing.
 - **The tree is not for execution details.** Function signatures, DB schemas, API endpoints, ad copy — those live in source systems. The tree captures the *why* and *how things connect*.
+- **Bring source repos in as additional working directories.** When you need to inspect or edit code, open the relevant source repositories alongside this tree instead of copying execution detail into the tree.
 - **Respect ownership.** Each node declares owners in its frontmatter. If your changes touch a domain you don't own, flag it — the owner needs to review.
 
 ## After Every Task

package/skills/first-tree/assets/framework/templates/root-node.md.template

@@ -5,9 +5,9 @@ owners: [<your-github-username>]
 
 # <Your Organization>
 
-<!-- PLACEHOLDER: Replace this with a description of your organization and what this tree captures. -->
+<!-- PLACEHOLDER: Replace this with a description of your organization and what this tree captures across your source repos and systems. -->
 
-The living source of truth for your organization. A structured knowledge base that agents and humans build and maintain together.
+The living source of truth for your organization. A structured knowledge base that agents and humans build and maintain together across one or more source repositories and systems.
 
 ---
 
@@ -29,7 +29,10 @@ The living source of truth for your organization. A structured knowledge base th
 
 ## Working with the Tree
 
-See [AGENT.md](AGENT.md) for agent instructions — the before/during/after workflow, ownership model, and tree maintenance.
+Keep decision context here. Keep implementation detail in the source repos this
+tree describes.
+
+See [AGENTS.md](AGENTS.md) for agent instructions — the before/during/after workflow, ownership model, and tree maintenance.
 
 See [about.md](skills/first-tree/references/about.md) for background — the problem, the idea, and who it's for.
 

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

@@ -1 +1 @@
-export * from "#skill/engine/init.js";
+export { INIT_USAGE, parseInitArgs, runInitCli as runInit } from "#skill/engine/init.js";

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

@@ -1 +1 @@
-export * from "#skill/engine/upgrade.js";
+export { UPGRADE_USAGE, runUpgradeCli as runUpgrade } from "#skill/engine/upgrade.js";

package/skills/first-tree/engine/commands/verify.ts

@@ -1 +1 @@
-export * from "#skill/engine/verify.js";
+export { VERIFY_USAGE, runVerifyCli as runVerify } from "#skill/engine/verify.js";