first-tree 0.0.4 → 0.0.6

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

@@ -1,5 +1,5 @@
-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 { C as LEGACY_SKILL_ROOT, D as SOURCE_INTEGRATION_MARKER, O as installedSkillRootsDisplay, T as SKILL_ROOT, b as LEGACY_REPO_SKILL_ROOT, c as CLAUDE_SKILL_ROOT, d as FRAMEWORK_TEMPLATES_DIR, f as FRAMEWORK_VERSION, g as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, m as INSTALLED_PROGRESS, n as Repo, p as FRAMEWORK_WORKFLOWS_DIR, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_INSTRUCTIONS_FILE, v as LEGACY_FRAMEWORK_ROOT } from "./repo-Cc5U4DWT.js";
+import { a as resolveCanonicalSkillRoot, i as resolveBundledPackageRoot, n as copyCanonicalSkill, t as upsertSourceIntegrationFiles } from "./source-integration-CuKjoheT.js";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 //#region skills/first-tree/engine/runtime/upgrader.ts
@@ -37,13 +37,15 @@ 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`,
+		`- [ ] Review local customizations under ${installedSkillRootsDisplay()} and reapply them if needed`,
 		`- [ ] Re-copy any workflow updates you want from \`${FRAMEWORK_WORKFLOWS_DIR}/\` into \`.github/workflows/\``,
-		`- [ ] Re-check any local agent setup that references \`${SKILL_ROOT}/assets/framework/examples/\` or \`${SKILL_ROOT}/assets/framework/helpers/\``,
+		`- [ ] Re-check any local agent setup that references \`${CLAUDE_SKILL_ROOT}/assets/framework/examples/\` or \`${CLAUDE_SKILL_ROOT}/assets/framework/helpers/\``,
+		`- [ ] Re-check any repo scripts or workflow files that reference \`${SKILL_ROOT}/assets/framework/\``,
 		""
 	];
 	const migrationTasks = [];
 	if (layout === "legacy") migrationTasks.push("- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files");
+	if (layout === "legacy-repo-skill") lines.push("## Migration", `- [ ] Remove any stale \`${LEGACY_REPO_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`, "");
 	if (layout === "legacy-skill") migrationTasks.push(`- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`);
 	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`);
@@ -54,7 +56,8 @@ function formatUpgradeTaskList(repo, localVersion, packagedVersion, layout) {
 }
 function runUpgrade(repo, options) {
 	const workingRepo = repo ?? new Repo();
-	if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo()) {
+	const workspaceOnlyIntegration = workingRepo.hasSourceWorkspaceIntegration() && !workingRepo.looksLikeTreeRepo();
+	if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo() && !workspaceOnlyIntegration) {
 		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;
 	}
@@ -87,7 +90,30 @@ function runUpgrade(repo, options) {
 		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) {
+	const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+	const sourceRepoTreePathHint = `../${workingRepo.repoName()}-context`;
+	if (workspaceOnlyIntegration) {
+		if (layout === "skill" && missingInstalledRoots.length === 0 && packagedVersion === localVersion) {
+			const changedFiles = upsertSourceIntegrationFiles(workingRepo.root, `${workingRepo.repoName()}-context`).filter((update) => update.action !== "unchanged").map((update) => update.file);
+			if (changedFiles.length === 0) {
+				console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
+				console.log(`This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`);
+				return 0;
+			}
+			console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
+			console.log(`Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`);
+			console.log(`This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`);
+			return 0;
+		}
+		copyCanonicalSkill(sourceRoot, workingRepo.root);
+		const changedFiles = upsertSourceIntegrationFiles(workingRepo.root, `${workingRepo.repoName()}-context`).filter((update) => update.action !== "unchanged").map((update) => update.file);
+		console.log(`Refreshed ${installedSkillRootsDisplay()} in this source/workspace repo.`);
+		if (changedFiles.length > 0) console.log(`Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`);
+		else console.log(`The ${SOURCE_INTEGRATION_MARKER} marker lines in ${AGENT_INSTRUCTIONS_FILE} and ${CLAUDE_INSTRUCTIONS_FILE} were already current.`);
+		console.log(`This repo is not the Context Tree. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`);
+		return 0;
+	}
+	if (layout === "skill" && missingInstalledRoots.length === 0 && packagedVersion === localVersion) {
 		console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
 		return 0;
 	}
@@ -97,9 +123,11 @@ function runUpgrade(repo, options) {
 			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.");
+		console.log(`Migrated legacy .context-tree/ layout to ${installedSkillRootsDisplay()}.`);
+	} else if (layout === "legacy-repo-skill") console.log(`Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`);
+	else if (layout === "legacy-skill") console.log(`Migrated ${LEGACY_SKILL_ROOT}/ to ${installedSkillRootsDisplay()}.`);
+	else if (missingInstalledRoots.length > 0) console.log(`Repaired missing installed skill roots (${missingInstalledRoots.map((root) => `${root}/`).join(", ")}) and refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`);
+	else console.log(`Refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`);
 	const output = formatUpgradeTaskList(workingRepo, localVersion, packagedVersion, layout);
 	console.log(`\n${output}`);
 	writeProgress(workingRepo, output);

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

@@ -1,4 +1,4 @@
-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 { C as LEGACY_SKILL_ROOT, T as SKILL_ROOT, g as LEGACY_AGENT_INSTRUCTIONS_FILE, n as Repo, r as AGENT_INSTRUCTIONS_FILE } from "./repo-Cc5U4DWT.js";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 //#region skills/first-tree/engine/validators/members.ts
@@ -515,6 +515,10 @@ function defaultNodeValidator(root) {
 function runVerify(repo, nodeValidator) {
 	const r = repo ?? new Repo();
 	const validate = nodeValidator ?? defaultNodeValidator;
+	if (r.hasSourceWorkspaceIntegration() && !r.looksLikeTreeRepo()) {
+		console.error(`Error: this repo only has the first-tree source/workspace integration installed. Verify the dedicated tree repo instead, for example \`context-tree verify --tree-path ../${r.repoName()}-context\`.`);
+		return 1;
+	}
 	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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-tree",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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": {
@@ -30,6 +30,15 @@
     "dist",
     "skills/first-tree"
   ],
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "pnpm build",
+    "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"
+  },
+  "packageManager": "pnpm@10.25.0",
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^25.5.0",
@@ -37,12 +46,5 @@
     "typescript": "^5.8.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

@@ -6,8 +6,9 @@ description: Maintain the canonical `first-tree` skill and the thin `context-tre
 # 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.
+`context-tree` CLI or the installed `.agents/skills/first-tree/` and
+`.claude/skills/first-tree/` payloads that `context-tree init` ships to user
+repos.
 
 ## Source Of Truth
 
@@ -17,9 +18,9 @@ Use this skill when the task depends on the exact behavior of the
   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.
+- In maintainer docs, use `context-tree` for the CLI, `skills/first-tree/` for
+  the bundled source path, and `.agents/skills/first-tree/` /
+  `.claude/skills/first-tree/` for installed user-repo paths.
 
 ## When To Read What
 
@@ -27,6 +28,7 @@ Use this skill when the task depends on the exact behavior of the
 2. Read the user-facing reference that matches the task:
    - `references/onboarding.md`
    - `references/about.md`
+   - `references/source-workspace-installation.md`
    - `references/principles.md`
    - `references/ownership-and-naming.md`
    - `references/upgrade-contract.md`
@@ -57,15 +59,29 @@ Use this skill when the task depends on the exact behavior of the
 
 ### Working In A User Tree Repo
 
+- When a user asks to install first-tree for an existing source/workspace repo,
+  the current repo keeps only the installed skill plus a
+  `FIRST-TREE-SOURCE-INTEGRATION:` line in `AGENTS.md` and `CLAUDE.md`. Do not
+  create `NODE.md`, `members/`, or tree-scoped `AGENTS.md` there.
 - `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.
+  repo when invoked from a source/workspace repo. It installs the bundled skill
+  into the source/workspace repo and scaffolds tree files only in the
+  dedicated tree 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
+  scaffolds `.agents/skills/first-tree/`, `.claude/skills/first-tree/`,
   `NODE.md`, `AGENTS.md`, and `members/NODE.md`.
+- The default source/workspace workflow is: create or reuse `<repo>-context`,
+  prefer pushing it in the same GitHub organization as the source repo, add it
+  back to the source/workspace repo as a git submodule, and open a PR to the
+  source/workspace repo's default branch instead of merging automatically.
 - `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/`.
+  with the currently running `first-tree` package. In a source/workspace repo
+  it refreshes only the local skill plus the
+  `FIRST-TREE-SOURCE-INTEGRATION:` line; upgrade the dedicated tree repo
+  separately with `--tree-path`. To pick up a newer framework, run a newer
+  package version first. It also migrates older repos that still use
+  `skills/first-tree/` or `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
@@ -79,6 +95,8 @@ Use this skill when the task depends on the exact behavior of the
 - 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 the CLI name written as `context-tree` in maintainer and user-facing
+  docs so it is not confused with the `first-tree` package that ships it.
 - Keep normal `init` / `upgrade` flows self-contained. They must work from the
   skill bundled in the current package without cloning the source repo or
   relying on network access.
@@ -104,6 +122,8 @@ Use this skill when the task depends on the exact behavior of the
 - `engine/`: canonical framework and CLI behavior
 - `tests/`: canonical unit and structure validation
 - `references/source-map.md`: canonical reading index
+- `references/source-workspace-installation.md`: source/workspace install
+  contract
 - `references/maintainer-architecture.md`: source-repo architecture and
   invariants
 - `references/maintainer-thin-cli.md`: root shell contract

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

@@ -1,4 +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."
+  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. When a source/workspace repo installs first-tree, keep that repo limited to local skill integration plus the FIRST-TREE-SOURCE-INTEGRATION marker lines, and keep all NODE.md/tree content only in a dedicated sibling *-context repo."

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

@@ -6,9 +6,9 @@ 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
+cp .claude/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.
+The `SessionStart` hook runs `./.claude/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

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./skills/first-tree/assets/framework/helpers/inject-tree-context.sh"
+            "command": "./.claude/skills/first-tree/assets/framework/helpers/inject-tree-context.sh"
           }
         ]
       }

package/skills/first-tree/assets/framework/helpers/generate-codeowners.ts

@@ -205,7 +205,7 @@ export function generate(
       return 0;
     }
     console.log(
-      "CODEOWNERS is out-of-date. Run: npx tsx skills/first-tree/assets/framework/helpers/generate-codeowners.ts",
+      "CODEOWNERS is out-of-date. Run: npx tsx .agents/skills/first-tree/assets/framework/helpers/generate-codeowners.ts",
     );
     return 1;
   }

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

@@ -39,7 +39,7 @@ function buildPrompt(diffPath: string): string {
     ["Root NODE.md", "NODE.md"],
     [
       "Review Instructions",
-      "skills/first-tree/assets/framework/prompts/pr-review.md",
+      ".agents/skills/first-tree/assets/framework/prompts/pr-review.md",
     ],
   ];
   for (const [heading, path] of files) {

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

@@ -13,7 +13,7 @@ You are working in a **Context Tree** — the living source of truth for decisio
 
 4. **Git-native tree structure.** Each node is a file; each domain is a directory. Soft links allow cross-references without the complexity of a full graph. History, ownership, and review follow Git conventions.
 
-See `skills/first-tree/references/principles.md` for detailed explanations and examples.
+See `.agents/skills/first-tree/references/principles.md` for detailed explanations and examples.
 
 ## Before Every Task
 
@@ -41,7 +41,7 @@ Ask yourself: **Does the tree need updating?**
 
 ## Reference
 
-For ownership rules, tree structure, and key files, see [NODE.md](NODE.md) and `skills/first-tree/references/ownership-and-naming.md`.
+For ownership rules, tree structure, and key files, see [NODE.md](NODE.md) and `.agents/skills/first-tree/references/ownership-and-naming.md`.
 <!-- END CONTEXT-TREE FRAMEWORK -->
 
 # Project-Specific Instructions

package/skills/first-tree/assets/framework/templates/members-domain.md.template

@@ -34,7 +34,7 @@ domains:
 ---
 ```
 
-See `skills/first-tree/assets/framework/templates/member-node.md.template` for a full scaffold.
+See `.agents/skills/first-tree/assets/framework/templates/member-node.md.template` for a full scaffold.
 
 ---
 

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

@@ -34,8 +34,8 @@ 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.
+See [about.md](.agents/skills/first-tree/references/about.md) for background — the problem, the idea, and who it's for.
 
 See the installed framework documentation:
-- [principles.md](skills/first-tree/references/principles.md) — core principles with examples
-- [ownership-and-naming.md](skills/first-tree/references/ownership-and-naming.md) — node naming and ownership model
+- [principles.md](.agents/skills/first-tree/references/principles.md) — core principles with examples
+- [ownership-and-naming.md](.agents/skills/first-tree/references/ownership-and-naming.md) — node naming and ownership model

package/skills/first-tree/assets/framework/workflows/codeowners.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           node-version: "22"
 
-      - run: npx tsx skills/first-tree/assets/framework/helpers/generate-codeowners.ts
+      - run: npx tsx .agents/skills/first-tree/assets/framework/helpers/generate-codeowners.ts
 
       - name: Commit if changed
         run: |

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

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

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

@@ -19,11 +19,15 @@ import {
 import {
   AGENT_INSTRUCTIONS_FILE,
   AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_INSTRUCTIONS_FILE,
   FRAMEWORK_ASSET_ROOT,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
+  installedSkillRootsDisplay,
+  SOURCE_INTEGRATION_MARKER,
 } from "#skill/engine/runtime/asset-loader.js";
+import { upsertSourceIntegrationFiles } from "#skill/engine/runtime/source-integration.js";
 
 /**
  * The interactive prompt tool the agent should use to present choices.
@@ -33,8 +37,10 @@ import {
 export const INTERACTIVE_TOOL = "AskUserQuestion";
 export const INIT_USAGE = `usage: context-tree init [--here] [--tree-name NAME] [--tree-path PATH]
 
-By default, running \`context-tree init\` inside a source or workspace repo creates
-a sibling dedicated tree repo named \`<repo>-context\`.
+By default, running \`context-tree init\` inside a source or workspace repo installs
+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\`.
 
 Options:
   --here             Initialize the current repo in place
@@ -61,13 +67,14 @@ const TEMPLATE_MAP: TemplateTarget[] = [
 
 interface TaskListContext {
   sourceRepoPath?: string;
+  sourceRepoName?: string;
   dedicatedTreeRepo?: boolean;
 }
 
 function installSkill(source: string, target: string): void {
   copyCanonicalSkill(source, target);
   console.log(
-    "  Installed skills/first-tree/ from the bundled first-tree package",
+    `  Installed ${installedSkillRootsDisplay()} from the bundled first-tree package`,
   );
 }
 
@@ -105,6 +112,23 @@ export function formatTaskList(
     if (context.sourceRepoPath) {
       lines.push(`**Bootstrap source repo:** \`${context.sourceRepoPath}\``, "");
     }
+    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("");
+    }
     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.",
@@ -181,9 +205,19 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
   const taskListContext = initTarget.dedicatedTreeRepo
     ? {
         dedicatedTreeRepo: true,
+        sourceRepoName: sourceRepo.repoName(),
         sourceRepoPath: relativePathFrom(r.root, sourceRepo.root),
       }
     : undefined;
+  let sourceRoot: string | null = null;
+
+  const resolveSourceRoot = (): string => {
+    if (sourceRoot !== null) {
+      return sourceRoot;
+    }
+    sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+    return sourceRoot;
+  };
 
   if (initTarget.dedicatedTreeRepo) {
     console.log(
@@ -195,17 +229,55 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
     if (initTarget.createdGitRepo) {
       console.log("  Initialized a new git repo for the tree.");
     }
+    console.log(
+      "  The source/workspace repo should keep only the installed skill and the" +
+        ` ${SOURCE_INTEGRATION_MARKER} lines in ${AGENT_INSTRUCTIONS_FILE} and ${CLAUDE_INSTRUCTIONS_FILE}.`,
+    );
+    console.log(
+      `  Never add NODE.md, members/, or tree-scoped ${AGENT_INSTRUCTIONS_FILE} to the source/workspace repo.`,
+    );
     console.log();
   }
 
-  if (!r.hasFramework()) {
+  if (initTarget.dedicatedTreeRepo) {
+    try {
+      const resolvedSourceRoot = resolveSourceRoot();
+      const hadSourceSkill = sourceRepo.hasCurrentInstalledSkill();
+      if (!hadSourceSkill) {
+        console.log(
+          "Installing the first-tree skill into the source/workspace repo...",
+        );
+        installSkill(resolvedSourceRoot, sourceRepo.root);
+      }
+      const updates = upsertSourceIntegrationFiles(sourceRepo.root, r.repoName());
+      const changedFiles = updates
+        .filter((update) => update.action !== "unchanged")
+        .map((update) => update.file);
+      if (changedFiles.length > 0) {
+        console.log(
+          `  Updated source/workspace instructions in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}`,
+        );
+      } else {
+        console.log(
+          `  Source/workspace instructions already contain ${SOURCE_INTEGRATION_MARKER}`,
+        );
+      }
+      console.log();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "unknown error";
+      console.error(`Error: ${message}`);
+      return 1;
+    }
+  }
+
+  if (!r.hasCurrentInstalledSkill()) {
     try {
-      const sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+      const resolvedSourceRoot = resolveSourceRoot();
       console.log(
         "Installing the framework skill bundled with this first-tree package...",
       );
       console.log("Installing skill and scaffolding...");
-      installSkill(sourceRoot, r.root);
+      installSkill(resolvedSourceRoot, r.root);
       renderTemplates(r.root);
       console.log();
     } catch (err) {

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

@@ -2,26 +2,35 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_FRAMEWORK_VERSION,
+  CLAUDE_INSTALLED_PROGRESS,
   FRAMEWORK_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
+  INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_PROGRESS,
+  LEGACY_REPO_SKILL_PROGRESS,
+  LEGACY_REPO_SKILL_VERSION,
+  LEGACY_SKILL_PROGRESS,
+  LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
-  INSTALLED_PROGRESS,
   agentInstructionsFileCandidates,
+  installedSkillRoots,
   type FrameworkLayout,
   detectFrameworkLayout,
   frameworkVersionCandidates,
   progressFileCandidates,
   resolveFirstExistingPath,
+  SOURCE_INTEGRATION_FILES,
+  SOURCE_INTEGRATION_MARKER,
 } from "#skill/engine/runtime/asset-loader.js";
 
 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([
+  ".agents",
   ".DS_Store",
+  ".claude",
   ".editorconfig",
   ".gitattributes",
   ".github",
@@ -164,6 +173,22 @@ export class Repo {
     return knownConfigs.some((c) => this.pathExists(c));
   }
 
+  installedSkillRoots(): string[] {
+    return installedSkillRoots();
+  }
+
+  missingInstalledSkillRoots(): string[] {
+    return this.installedSkillRoots().filter(
+      (root) =>
+        !this.pathExists(join(root, "SKILL.md")) ||
+        !this.pathExists(join(root, "assets", "framework", "VERSION")),
+    );
+  }
+
+  hasCurrentInstalledSkill(): boolean {
+    return this.missingInstalledSkillRoots().length === 0;
+  }
+
   isGitRepo(): boolean {
     return hasGitMetadata(this.root);
   }
@@ -198,6 +223,12 @@ export class Repo {
     if (layout === "legacy-skill") {
       return LEGACY_SKILL_PROGRESS;
     }
+    if (layout === "legacy-repo-skill") {
+      return LEGACY_REPO_SKILL_PROGRESS;
+    }
+    if (layout === "claude-skill") {
+      return CLAUDE_INSTALLED_PROGRESS;
+    }
     return INSTALLED_PROGRESS;
   }
 
@@ -209,6 +240,12 @@ export class Repo {
     if (layout === "legacy-skill") {
       return LEGACY_SKILL_VERSION;
     }
+    if (layout === "legacy-repo-skill") {
+      return LEGACY_REPO_SKILL_VERSION;
+    }
+    if (layout === "claude-skill") {
+      return CLAUDE_FRAMEWORK_VERSION;
+    }
     return FRAMEWORK_VERSION;
   }
 
@@ -240,6 +277,23 @@ export class Repo {
     return text.includes(FRAMEWORK_BEGIN_MARKER) && text.includes(FRAMEWORK_END_MARKER);
   }
 
+  hasSourceIntegrationFile(relPath: string): boolean {
+    return this.fileContains(relPath, SOURCE_INTEGRATION_MARKER);
+  }
+
+  hasSourceWorkspaceIntegration(): boolean {
+    return SOURCE_INTEGRATION_FILES.some((file) => this.hasSourceIntegrationFile(file));
+  }
+
+  hasTreeContent(): boolean {
+    return (
+      this.progressPath() !== null
+      || this.hasAgentInstructionsMarkers()
+      || this.pathExists("members/NODE.md")
+      || this.frontmatter("NODE.md") !== null
+    );
+  }
+
   hasMembers(): boolean {
     const membersDir = join(this.root, "members");
     try {
@@ -305,13 +359,19 @@ export class Repo {
       return false;
     }
 
-    return (
-      this.progressPath() !== null
-      || this.hasFramework()
-      || this.hasAgentInstructionsMarkers()
-      || this.pathExists("members/NODE.md")
-      || this.frontmatter("NODE.md") !== null
-    );
+    if (this.hasTreeContent()) {
+      return true;
+    }
+
+    if (this.hasFramework() && this.hasSourceWorkspaceIntegration()) {
+      return false;
+    }
+
+    if (this.hasFramework()) {
+      return !this.hasLikelySourceRepoSignals();
+    }
+
+    return false;
   }
 
   isLikelyEmptyRepo(): boolean {
@@ -326,6 +386,10 @@ export class Repo {
       return false;
     }
 
+    return this.hasLikelySourceRepoSignals();
+  }
+
+  private hasLikelySourceRepoSignals(): boolean {
     const entries = this.topLevelEntries().filter(
       (entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry),
     );