first-tree 0.0.5 → 0.0.7

package/skills/first-tree/SKILL.md

@@ -28,6 +28,7 @@ repos.
 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`
@@ -58,16 +59,39 @@ repos.
 
 ### Working In A User Tree Repo
 
+- When the task is to "install and use first-tree" in an existing
+  source/workspace repo, start with
+  `references/source-workspace-installation.md` and follow that workflow
+  end-to-end before improvising.
+- 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.
+- Never run `context-tree init --here` in a source/workspace repo unless the
+  user explicitly wants that repo itself to become the dedicated Context Tree.
+  `--here` is for when you have already switched into the `*-context` 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.
+- If permissions, auth, or local filesystem constraints block the dedicated
+  repo workflow, stop and report the blocker. Do not fall back to in-place tree
+  bootstrap in the source/workspace repo.
 - `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/` or `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/`.
 - 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
@@ -108,6 +132,8 @@ repos.
 - `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, read references/source-workspace-installation.md first, 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. Never choose context-tree init --here in the source/workspace repo unless the user explicitly wants that repo itself to become the tree."

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

@@ -19,12 +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.
@@ -34,11 +37,16 @@ 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\`.
+
+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
@@ -62,6 +70,7 @@ const TEMPLATE_MAP: TemplateTarget[] = [
 
 interface TaskListContext {
   sourceRepoPath?: string;
+  sourceRepoName?: string;
   dedicatedTreeRepo?: boolean;
 }
 
@@ -106,6 +115,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.",
@@ -179,12 +205,31 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
     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(),
         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(
@@ -196,17 +241,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 (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

@@ -10,8 +10,6 @@ import {
   LEGACY_PROGRESS,
   LEGACY_REPO_SKILL_PROGRESS,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
   agentInstructionsFileCandidates,
   installedSkillRoots,
@@ -20,13 +18,17 @@ import {
   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",
@@ -216,9 +218,6 @@ export class Repo {
     if (layout === "legacy") {
       return LEGACY_PROGRESS;
     }
-    if (layout === "legacy-skill") {
-      return LEGACY_SKILL_PROGRESS;
-    }
     if (layout === "legacy-repo-skill") {
       return LEGACY_REPO_SKILL_PROGRESS;
     }
@@ -233,9 +232,6 @@ export class Repo {
     if (layout === "legacy") {
       return LEGACY_VERSION;
     }
-    if (layout === "legacy-skill") {
-      return LEGACY_SKILL_VERSION;
-    }
     if (layout === "legacy-repo-skill") {
       return LEGACY_REPO_SKILL_VERSION;
     }
@@ -273,6 +269,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 {
@@ -338,13 +351,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 {
@@ -359,6 +378,10 @@ export class Repo {
       return false;
     }
 
+    return this.hasLikelySourceRepoSignals();
+  }
+
+  private hasLikelySourceRepoSignals(): boolean {
     const entries = this.topLevelEntries().filter(
       (entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry),
     );

package/skills/first-tree/engine/runtime/adapters.ts

@@ -4,7 +4,6 @@ import {
   CLAUDE_FRAMEWORK_HELPERS_DIR,
   FRAMEWORK_EXAMPLES_DIR,
   LEGACY_REPO_SKILL_EXAMPLES_DIR,
-  LEGACY_SKILL_EXAMPLES_DIR,
   LEGACY_EXAMPLES_DIR,
 } from "#skill/engine/runtime/asset-loader.js";
 
@@ -16,7 +15,6 @@ export function claudeCodeExampleCandidates(): string[] {
     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"),
   ];
 }

package/skills/first-tree/engine/runtime/asset-loader.ts

@@ -21,6 +21,12 @@ export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
 export const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
 export const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
 export const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
+export const CLAUDE_INSTRUCTIONS_FILE = "CLAUDE.md";
+export const SOURCE_INTEGRATION_MARKER = "FIRST-TREE-SOURCE-INTEGRATION:";
+export const SOURCE_INTEGRATION_FILES = [
+  AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTRUCTIONS_FILE,
+] as const;
 
 export const CLAUDE_SKILL_AGENTS_DIR = join(CLAUDE_SKILL_ROOT, "agents");
 export const CLAUDE_SKILL_REFERENCES_DIR = join(CLAUDE_SKILL_ROOT, "references");
@@ -109,32 +115,6 @@ export const LEGACY_REPO_SKILL_PROGRESS = join(
   "progress.md",
 );
 
-export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
-export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
-export const LEGACY_SKILL_ASSET_ROOT = join(
-  LEGACY_SKILL_ROOT,
-  "assets",
-  "framework",
-);
-export const LEGACY_SKILL_VERSION = join(LEGACY_SKILL_ASSET_ROOT, "VERSION");
-export const LEGACY_SKILL_TEMPLATES_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "templates",
-);
-export const LEGACY_SKILL_WORKFLOWS_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "workflows",
-);
-export const LEGACY_SKILL_PROMPTS_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "prompts",
-);
-export const LEGACY_SKILL_EXAMPLES_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "examples",
-);
-export const LEGACY_SKILL_PROGRESS = join(LEGACY_SKILL_ROOT, "progress.md");
-
 export const LEGACY_FRAMEWORK_ROOT = ".context-tree";
 export const LEGACY_VERSION = join(LEGACY_FRAMEWORK_ROOT, "VERSION");
 export const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
@@ -147,7 +127,6 @@ export type FrameworkLayout =
   | "skill"
   | "claude-skill"
   | "legacy-repo-skill"
-  | "legacy-skill"
   | "legacy";
 
 function pathExists(root: string, relPath: string): boolean {
@@ -174,7 +153,6 @@ export function frameworkVersionCandidates(): string[] {
     FRAMEWORK_VERSION,
     CLAUDE_FRAMEWORK_VERSION,
     LEGACY_REPO_SKILL_VERSION,
-    LEGACY_SKILL_VERSION,
     LEGACY_VERSION,
   ];
 }
@@ -184,7 +162,6 @@ export function progressFileCandidates(): string[] {
     INSTALLED_PROGRESS,
     CLAUDE_INSTALLED_PROGRESS,
     LEGACY_REPO_SKILL_PROGRESS,
-    LEGACY_SKILL_PROGRESS,
     LEGACY_PROGRESS,
   ];
 }
@@ -198,7 +175,6 @@ export function frameworkTemplateDirCandidates(): string[] {
     FRAMEWORK_TEMPLATES_DIR,
     CLAUDE_FRAMEWORK_TEMPLATES_DIR,
     LEGACY_REPO_SKILL_TEMPLATES_DIR,
-    LEGACY_SKILL_TEMPLATES_DIR,
     LEGACY_TEMPLATES_DIR,
   ];
 }
@@ -208,7 +184,6 @@ export function frameworkWorkflowDirCandidates(): string[] {
     FRAMEWORK_WORKFLOWS_DIR,
     CLAUDE_FRAMEWORK_WORKFLOWS_DIR,
     LEGACY_REPO_SKILL_WORKFLOWS_DIR,
-    LEGACY_SKILL_WORKFLOWS_DIR,
     LEGACY_WORKFLOWS_DIR,
   ];
 }
@@ -218,7 +193,6 @@ export function frameworkPromptDirCandidates(): string[] {
     FRAMEWORK_PROMPTS_DIR,
     CLAUDE_FRAMEWORK_PROMPTS_DIR,
     LEGACY_REPO_SKILL_PROMPTS_DIR,
-    LEGACY_SKILL_PROMPTS_DIR,
     LEGACY_PROMPTS_DIR,
   ];
 }
@@ -228,7 +202,6 @@ export function frameworkExampleDirCandidates(): string[] {
     FRAMEWORK_EXAMPLES_DIR,
     CLAUDE_FRAMEWORK_EXAMPLES_DIR,
     LEGACY_REPO_SKILL_EXAMPLES_DIR,
-    LEGACY_SKILL_EXAMPLES_DIR,
     LEGACY_EXAMPLES_DIR,
   ];
 }
@@ -255,9 +228,6 @@ export function detectFrameworkLayout(root: string): FrameworkLayout | null {
   if (pathExists(root, LEGACY_REPO_SKILL_VERSION)) {
     return "legacy-repo-skill";
   }
-  if (pathExists(root, LEGACY_SKILL_VERSION)) {
-    return "legacy-skill";
-  }
   if (pathExists(root, LEGACY_VERSION)) {
     return "legacy";
   }

package/skills/first-tree/engine/runtime/installer.ts

@@ -5,7 +5,6 @@ import {
   BUNDLED_SKILL_ROOT,
   INSTALLED_SKILL_ROOTS,
   LEGACY_REPO_SKILL_ROOT,
-  LEGACY_SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
 
 export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
@@ -57,7 +56,6 @@ export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void
   for (const relPath of [
     ...INSTALLED_SKILL_ROOTS,
     LEGACY_REPO_SKILL_ROOT,
-    LEGACY_SKILL_ROOT,
   ]) {
     const fullPath = join(targetRoot, relPath);
     if (existsSync(fullPath)) {

package/skills/first-tree/engine/runtime/source-integration.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  SOURCE_INTEGRATION_FILES,
+  SOURCE_INTEGRATION_MARKER,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export type SourceIntegrationFile = (typeof SOURCE_INTEGRATION_FILES)[number];
+
+export interface SourceIntegrationUpdate {
+  action: "created" | "updated" | "unchanged";
+  file: SourceIntegrationFile;
+}
+
+export function buildSourceIntegrationLine(treeRepoName: string): string {
+  return (
+    `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here;`
+    + ` keep all Context Tree files only in the sibling dedicated`
+    + ` \`${treeRepoName}\` repo/submodule and update that tree when decisions`
+    + " or constraints change."
+  );
+}
+
+export function hasSourceIntegrationMarker(text: string | null): boolean {
+  if (text === null) {
+    return false;
+  }
+  return text
+    .replaceAll("\r\n", "\n")
+    .split("\n")
+    .some((line) => line.startsWith(SOURCE_INTEGRATION_MARKER));
+}
+
+export function upsertSourceIntegrationFiles(
+  root: string,
+  treeRepoName: string,
+): SourceIntegrationUpdate[] {
+  return SOURCE_INTEGRATION_FILES.map((file) =>
+    upsertSourceIntegrationFile(root, file, treeRepoName),
+  );
+}
+
+function upsertSourceIntegrationFile(
+  root: string,
+  file: SourceIntegrationFile,
+  treeRepoName: string,
+): SourceIntegrationUpdate {
+  const fullPath = join(root, file);
+  const exists = existsSync(fullPath);
+  const nextLine = buildSourceIntegrationLine(treeRepoName);
+  const current = exists ? readFileSync(fullPath, "utf-8") : null;
+  const normalized = current?.replaceAll("\r\n", "\n") ?? "";
+  const lines = normalized === "" ? [] : normalized.split("\n");
+  const markerIndex = lines.findIndex((line) =>
+    line.startsWith(SOURCE_INTEGRATION_MARKER),
+  );
+
+  if (markerIndex >= 0) {
+    if (lines[markerIndex] === nextLine) {
+      return { action: "unchanged", file };
+    }
+    lines[markerIndex] = nextLine;
+  } else {
+    if (lines.length > 0 && lines.at(-1) !== "") {
+      lines.push("");
+    }
+    lines.push(nextLine);
+  }
+
+  let nextText = lines.join("\n");
+  if (nextText !== "" && !nextText.endsWith("\n")) {
+    nextText += "\n";
+  }
+  writeFileSync(fullPath, nextText);
+
+  return {
+    action: exists ? "updated" : "created",
+    file,
+  };
+}

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

@@ -4,6 +4,7 @@ import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
   AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_INSTRUCTIONS_FILE,
   CLAUDE_SKILL_ROOT,
   FRAMEWORK_WORKFLOWS_DIR,
   FRAMEWORK_TEMPLATES_DIR,
@@ -12,8 +13,8 @@ import {
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_FRAMEWORK_ROOT,
   LEGACY_REPO_SKILL_ROOT,
-  LEGACY_SKILL_ROOT,
   SKILL_ROOT,
+  SOURCE_INTEGRATION_MARKER,
   installedSkillRootsDisplay,
   type FrameworkLayout,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -21,6 +22,7 @@ import {
   copyCanonicalSkill,
   resolveBundledPackageRoot,
 } from "#skill/engine/runtime/installer.js";
+import { upsertSourceIntegrationFiles } from "#skill/engine/runtime/source-integration.js";
 import {
   compareFrameworkVersions,
   readSourceVersion,
@@ -70,12 +72,6 @@ function formatUpgradeTaskList(
     );
   }
 
-  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`,
@@ -121,8 +117,10 @@ export interface UpgradeOptions {
 
 export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
   const workingRepo = repo ?? new Repo();
+  const workspaceOnlyIntegration =
+    workingRepo.hasSourceWorkspaceIntegration() && !workingRepo.looksLikeTreeRepo();
 
-  if (workingRepo.isLikelySourceRepo() && !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.",
     );
@@ -178,6 +176,68 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
   }
 
   const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+  const sourceRepoTreePathHint = `../${workingRepo.repoName()}-context`;
+
+  if (workspaceOnlyIntegration) {
+    if (
+      layout === "skill" &&
+      missingInstalledRoots.length === 0 &&
+      packagedVersion === localVersion
+    ) {
+      const updates = upsertSourceIntegrationFiles(
+        workingRepo.root,
+        `${workingRepo.repoName()}-context`,
+      );
+      const changedFiles = updates
+        .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 updates = upsertSourceIntegrationFiles(
+      workingRepo.root,
+      `${workingRepo.repoName()}-context`,
+    );
+    const changedFiles = updates
+      .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 &&
@@ -202,10 +262,6 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
     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(