first-tree 0.0.6 → 0.0.8

package/README.md

@@ -43,6 +43,7 @@ sibling dedicated tree repo.
 cd my-app
 npx first-tree init
 cd ../my-app-context
+context-tree publish --open-pr
 ```
 
 If you already created a dedicated tree repo yourself, initialize it in place:
@@ -53,6 +54,10 @@ git init
 context-tree init --here
 ```
 
+Only use `--here` after you have already switched into the dedicated tree repo.
+Do not use it inside the source/workspace repo unless you intentionally want
+that repo itself to become the Context Tree.
+
 - `context-tree init` installs `.agents/skills/first-tree/` and
   `.claude/skills/first-tree/` in the current source/workspace repo, appends a
   single `FIRST-TREE-SOURCE-INTEGRATION:` line to root `AGENTS.md` and
@@ -62,10 +67,13 @@ context-tree init --here
 - Never create `NODE.md`, `members/`, or tree-scoped `AGENTS.md` in the
   source/workspace repo. Those files live only in the dedicated `*-context`
   repo.
-- After creating the dedicated tree repo, prefer pushing it to the same GitHub
-  organization as the source repo, add it back as a git submodule, and open a
-  PR to the source/workspace repo's default branch instead of merging
-  automatically.
+- After drafting the initial tree version, run `context-tree publish --open-pr`
+  from the dedicated tree repo. That command creates or reuses the GitHub
+  `*-context` repo, adds it back to the source/workspace repo as a git
+  submodule, and opens a PR instead of merging automatically.
+- After `context-tree publish` succeeds, treat the source repo's submodule
+  checkout as the canonical local working copy for the tree. The temporary
+  sibling bootstrap checkout can be deleted when you no longer need it.
 - `context-tree verify` checks both the progress checklist and deterministic
   tree validation. It is expected to fail until the required onboarding tasks
   are complete.
@@ -84,7 +92,8 @@ runtime.
 
 | Command | What it does |
 | --- | --- |
-| `context-tree init` | Install source/workspace integration locally and create or refresh a dedicated context tree repo; use `--here` to initialize the current repo in place |
+| `context-tree init` | Install source/workspace integration locally and create or refresh a dedicated context tree repo; use `--here` only when you are already inside the dedicated tree repo |
+| `context-tree publish` | Publish a dedicated tree repo to GitHub, add it back to the source/workspace repo as a submodule, and optionally open the source-repo PR |
 | `context-tree verify` | Run verification checks against the current tree |
 | `context-tree upgrade` | Refresh the installed skill from the current `first-tree` npm package; in a source/workspace repo it updates only local integration, while tree repos also get follow-up tasks |
 | `context-tree help onboarding` | Print the onboarding guide |
@@ -108,6 +117,8 @@ runtime.
 ## Runtime And Maintainer Prerequisites
 
 - User trees: the onboarding guide targets Node.js 18+.
+- `context-tree publish` also expects GitHub CLI (`gh`) to be installed and
+  authenticated against GitHub.
 - This source repo: use Node.js 22 and pnpm 10 to match CI and the checked-in
   package manager version.
 

package/dist/bootstrap-YRjfHJp7.js

@@ -0,0 +1,28 @@
+import { a as BOOTSTRAP_STATE } from "./repo-BeVpMoHi.js";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region skills/first-tree/engine/runtime/bootstrap.ts
+function bootstrapStatePath(root) {
+	return join(root, BOOTSTRAP_STATE);
+}
+function readBootstrapState(root) {
+	const path = bootstrapStatePath(root);
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8"));
+		if (typeof parsed.sourceRepoName !== "string" || typeof parsed.sourceRepoPath !== "string" || typeof parsed.treeRepoName !== "string") return null;
+		return {
+			sourceRepoName: parsed.sourceRepoName,
+			sourceRepoPath: parsed.sourceRepoPath,
+			treeRepoName: parsed.treeRepoName
+		};
+	} catch {
+		return null;
+	}
+}
+function writeBootstrapState(root, state) {
+	const path = bootstrapStatePath(root);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+//#endregion
+export { writeBootstrapState as n, readBootstrapState as t };

package/dist/cli.js

@@ -8,6 +8,7 @@ const USAGE = `usage: context-tree <command>
 
 Commands:
   init      Install source/workspace integration and create or refresh a dedicated context tree repo
+  publish   Publish a dedicated tree repo to GitHub and reconnect it to the source repo
   verify    Run verification checks against a tree repo
   upgrade   Refresh the installed skill in a tree repo
   help      Show help for a topic (e.g. \`help onboarding\`)
@@ -18,9 +19,13 @@ Options:
 
 Common examples:
   context-tree init
-  context-tree init --here
+  context-tree publish --open-pr
+  mkdir my-org-context && cd my-org-context && git init && context-tree init --here
   context-tree verify --tree-path ../my-org-context
   context-tree upgrade --tree-path ../my-org-context
+
+Note:
+  \`--here\` is for when the current repo is already the dedicated tree repo.
 `;
 function isDirectExecution(argv1, metaUrl = import.meta.url) {
 	if (argv1 === void 0) return false;
@@ -44,18 +49,22 @@ async function runCli(args, output = console.log) {
 	const command = args[0];
 	switch (command) {
 		case "init": {
-			const { runInit } = await import("./init-BgGH2_yC.js");
+			const { runInit } = await import("./init-DjSVkUeR.js");
 			return runInit(args.slice(1));
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-G8gNXzDX.js");
+			const { runVerify } = await import("./verify-Chhm1vOF.js");
 			return runVerify(args.slice(1));
 		}
+		case "publish": {
+			const { runPublish } = await import("./publish-D0crNDjz.js");
+			return runPublish(args.slice(1));
+		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-BvA9oKmi.js");
+			const { runUpgrade } = await import("./upgrade-B_NTlNrx.js");
 			return runUpgrade(args.slice(1));
 		}
-		case "help": return (await import("./help-DV9-AaFp.js")).runHelp(args.slice(1), write);
+		case "help": return (await import("./help-CDfaFrzl.js")).runHelp(args.slice(1), write);
 		default:
 			write(`Unknown command: ${command}`);
 			write(USAGE);

package/dist/{help-DV9-AaFp.js → help-CDfaFrzl.js}

@@ -12,7 +12,7 @@ async function runHelp(args, output = console.log) {
 	}
 	switch (topic) {
 		case "onboarding": {
-			const { runOnboarding } = await import("./onboarding-lASHHmgO.js");
+			const { runOnboarding } = await import("./onboarding-Ce033qaW.js");
 			return runOnboarding(output);
 		}
 		default:

package/dist/{init-BgGH2_yC.js → init-DjSVkUeR.js}

@@ -1,6 +1,7 @@
-import { D as SOURCE_INTEGRATION_MARKER, O as installedSkillRootsDisplay, _ as LEGACY_EXAMPLES_DIR, d as FRAMEWORK_TEMPLATES_DIR, f as FRAMEWORK_VERSION, g as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, l as FRAMEWORK_ASSET_ROOT, m as INSTALLED_PROGRESS, n as Repo, o as CLAUDE_FRAMEWORK_EXAMPLES_DIR, p as FRAMEWORK_WORKFLOWS_DIR, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_INSTRUCTIONS_FILE, t as FRAMEWORK_END_MARKER, u as FRAMEWORK_EXAMPLES_DIR, x as LEGACY_SKILL_EXAMPLES_DIR, y as LEGACY_REPO_SKILL_EXAMPLES_DIR } from "./repo-Cc5U4DWT.js";
-import { n as onboarding_default } from "./onboarding-D7fGGOMN.js";
-import { i as resolveBundledPackageRoot, n as copyCanonicalSkill, r as renderTemplateFile, t as upsertSourceIntegrationFiles } from "./source-integration-CuKjoheT.js";
+import { E as installedSkillRootsDisplay, T as SOURCE_INTEGRATION_MARKER, _ as LEGACY_AGENT_INSTRUCTIONS_FILE, b as LEGACY_REPO_SKILL_EXAMPLES_DIR, c as CLAUDE_INSTRUCTIONS_FILE, d as FRAMEWORK_EXAMPLES_DIR, f as FRAMEWORK_TEMPLATES_DIR, h as INSTALLED_PROGRESS, i as AGENT_INSTRUCTIONS_TEMPLATE, m as FRAMEWORK_WORKFLOWS_DIR, n as Repo, p as FRAMEWORK_VERSION, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_FRAMEWORK_EXAMPLES_DIR, t as FRAMEWORK_END_MARKER, u as FRAMEWORK_ASSET_ROOT, v as LEGACY_EXAMPLES_DIR } from "./repo-BeVpMoHi.js";
+import { n as onboarding_default } from "./onboarding-BiHx2jy5.js";
+import { i as resolveBundledPackageRoot, n as copyCanonicalSkill, r as renderTemplateFile, t as upsertSourceIntegrationFiles } from "./source-integration-DMxnl8Dw.js";
+import { n as writeBootstrapState } from "./bootstrap-YRjfHJp7.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { dirname, join, relative, resolve } from "node:path";
@@ -53,7 +54,6 @@ function claudeCodeExampleCandidates() {
 		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")
 	];
 }
@@ -210,8 +210,11 @@ the first-tree skill in the current repo, updates \`AGENTS.md\` and \`CLAUDE.md\
 with a \`${SOURCE_INTEGRATION_MARKER}\` line, and creates a sibling dedicated tree
 repo named \`<repo>-context\`.
 
+Do not use \`--here\` inside a source/workspace repo unless you explicitly want
+that repo itself to become the Context Tree.
+
 Options:
-  --here             Initialize the current repo in place
+  --here             Initialize the current repo in place after you are already in the dedicated tree repo
   --tree-name NAME   Name the dedicated sibling tree repo to create
   --tree-path PATH   Use an explicit tree repo path
   --help             Show this help message
@@ -251,9 +254,8 @@ function formatTaskList(groups, context) {
 		if (context.sourceRepoName) {
 			lines.push(`**Source/workspace contract:** Keep \`${context.sourceRepoName}\` limited to the installed skill plus the \`${SOURCE_INTEGRATION_MARKER}\` lines in \`${AGENT_INSTRUCTIONS_FILE}\` and \`${CLAUDE_INSTRUCTIONS_FILE}\`. Never add \`NODE.md\`, \`members/\`, or tree-scoped \`${AGENT_INSTRUCTIONS_FILE}\` there.`, "");
 			lines.push("## Source Workspace Workflow");
-			lines.push(`- [ ] Publish this dedicated tree repo to the same GitHub organization as \`${context.sourceRepoName}\``);
-			lines.push(`- [ ] Add this tree repo back to \`${context.sourceRepoName}\` as a git submodule after the remote exists`);
-			lines.push(`- [ ] Open a PR against the source/workspace repo's default branch with only the installed skill, the \`${SOURCE_INTEGRATION_MARKER}\` marker lines in \`${AGENT_INSTRUCTIONS_FILE}\` / \`${CLAUDE_INSTRUCTIONS_FILE}\`, and the new submodule pointer`);
+			lines.push(`- [ ] When this initial tree version is ready, run \`context-tree publish --open-pr\` from this dedicated tree repo. It will create or reuse the GitHub \`*-context\` repo, add it back to \`${context.sourceRepoName}\` as a git submodule, and open the source/workspace PR.`);
+			lines.push(`- [ ] After publish succeeds, treat the source/workspace repo's \`${context.sourceRepoName}\` submodule checkout as the canonical local working copy for this tree. The temporary sibling bootstrap repo can be deleted when you no longer need it.`);
 			lines.push("");
 		}
 		lines.push("When you publish this tree repo, keep it in the same GitHub organization as the source repo unless you have a reason not to.", "");
@@ -291,6 +293,10 @@ function runInit(repo, options) {
 		return 1;
 	}
 	const r = initTarget.repo;
+	if (options?.here && sourceRepo.isLikelySourceRepo() && !sourceRepo.looksLikeTreeRepo()) {
+		console.log(`Warning: \`context-tree init --here\` is initializing this source/workspace repo in place. This will create \`NODE.md\`, \`members/\`, and tree-scoped ${AGENT_INSTRUCTIONS_FILE} here. Use plain \`context-tree init\` to create a sibling dedicated tree repo instead.`);
+		console.log();
+	}
 	const taskListContext = initTarget.dedicatedTreeRepo ? {
 		dedicatedTreeRepo: true,
 		sourceRepoName: sourceRepo.repoName(),
@@ -338,6 +344,11 @@ function runInit(repo, options) {
 		console.error(`Error: ${message}`);
 		return 1;
 	}
+	if (initTarget.dedicatedTreeRepo) writeBootstrapState(r.root, {
+		sourceRepoName: sourceRepo.repoName(),
+		sourceRepoPath: relativePathFrom(r.root, sourceRepo.root),
+		treeRepoName: r.repoName()
+	});
 	console.log(onboarding_default);
 	console.log("---\n");
 	const groups = evaluateAll(r);

package/dist/onboarding-BiHx2jy5.js

@@ -0,0 +1,10 @@
+//#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- GitHub CLI (`gh`) if you want `context-tree publish` to create the remote\n  `*-context` repo and open the source-repo PR for you\n- The npm package is `first-tree`, the installed CLI command is\n  `context-tree`.\n- `context-tree init` installs the framework skill into\n  `.agents/skills/first-tree/` and `.claude/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 install the bundled skill in the current repo, update root\n`AGENTS.md` and `CLAUDE.md` with a `FIRST-TREE-SOURCE-INTEGRATION:` line, and\ncreate a sibling dedicated tree repo named `<repo>-context` by default. Tree\nfiles are scaffolded only in the dedicated tree repo.\n\n```bash\ncd my-org\ncontext-tree init\ncd ../my-org-context\ncontext-tree publish --open-pr\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\nOnly use `--here` after you have already switched into the dedicated tree repo.\nDo not use it inside the source/workspace repo unless you intentionally want\nthat repo itself to become the Context Tree.\n\nEither way, the framework installs into `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,\n`members/NODE.md`), and generates a task list in\n`.agents/skills/first-tree/progress.md`.\n\nHard boundary: do **not** create `NODE.md`, `members/`, or tree-scoped\n`AGENTS.md` in the source/workspace repo. Those files belong only in the\ndedicated `*-context` repo.\n\nDefault agent workflow after initialization:\n\n1. Draft the initial tree version in the dedicated `*-context` repo.\n2. Run `context-tree publish --open-pr` from that dedicated tree repo. It will\n   create or reuse the GitHub `*-context` repo in the same owner/org as the\n   source repo, add it back to the source/workspace repo as a `git submodule`,\n   and open the source-repo PR.\n3. After publish succeeds, treat the source repo's submodule checkout as the\n   canonical local working copy for the tree. The temporary sibling bootstrap\n   checkout can be deleted when you no longer need it.\n\n### Step 2: Work Through the Task List\n\nRead `.agents/skills/first-tree/progress.md`. It contains a checklist tailored\nto 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 (for Claude Code, the installed hook\n  assets live under `.claude/skills/first-tree/`)\n- Copy validation workflows from\n  `.agents/skills/first-tree/assets/framework/workflows/` to\n  `.github/workflows/`\n\nAs you complete each task, check it off in\n`.agents/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 `.agents/skills/first-tree/progress.md` remain\nunchecked, and runs deterministic checks (valid frontmatter, node structure,\nmember nodes exist).\n\nDo not run `context-tree verify` in the source/workspace repo itself. That repo\nonly carries the installed skill plus the\n`FIRST-TREE-SOURCE-INTEGRATION:` line.\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` | Install local source/workspace integration and create or refresh a dedicated tree repo. By default, running in a source/workspace repo creates a sibling `<repo>-context`; use `--here` only when you are already inside the dedicated tree repo. |\n| `context-tree publish` | Publish a dedicated tree repo to GitHub, add it back to the source/workspace repo as a submodule, and optionally open the source-repo PR. |\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 `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/` from the skill bundled with the currently running\n`first-tree` npm package, preserves your tree content, and generates follow-up\ntasks in `.agents/skills/first-tree/progress.md`.\n\nIf you run `context-tree upgrade` in the source/workspace repo, it refreshes\nonly the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.\nRun `context-tree upgrade --tree-path ../my-org-context` to upgrade the\ndedicated tree repo itself.\n\nIf your repo still uses the older `skills/first-tree/` or `.context-tree/` layouts,\n`context-tree upgrade` will migrate it to the current installed layout 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- `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples\n- `.agents/skills/first-tree/references/source-workspace-installation.md` — Source/workspace install contract\n- `.agents/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 };

package/dist/onboarding-Ce033qaW.js

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