first-tree 0.0.4 → 0.0.6

package/skills/first-tree/references/onboarding.md

@@ -56,16 +56,19 @@ Information an agent needs to **decide** on an approach — not to execute it.
 - A source/workspace Git repository, or an already-created dedicated tree repo
 - Node.js 18+
 - The npm package is `first-tree`, the installed CLI command is
-  `context-tree`, and the installed skill directory in the tree is
-  `skills/first-tree/`
+  `context-tree`.
+- `context-tree init` installs the framework skill into
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`.
 - Use `npx first-tree init` for one-off runs, or `npm install -g first-tree`
   to add the `context-tree` command to your PATH
 
 ### Step 1: Initialize
 
 Recommended workflow: run `context-tree init` from your source or workspace repo.
-The CLI will create a sibling dedicated tree repo named `<repo>-context` by
-default and install the framework there.
+The CLI will install the bundled skill in the current repo, update root
+`AGENTS.md` and `CLAUDE.md` with a `FIRST-TREE-SOURCE-INTEGRATION:` line, and
+create a sibling dedicated tree repo named `<repo>-context` by default. Tree
+files are scaffolded only in the dedicated tree repo.
 
 ```bash
 cd my-org
@@ -81,24 +84,43 @@ git init
 context-tree init --here
 ```
 
-Either way, the framework installs into `skills/first-tree/`, renders
-scaffolding (`NODE.md`, `AGENTS.md`, `members/NODE.md`), and generates a task
-list in `skills/first-tree/progress.md`.
+Either way, the framework installs into `.agents/skills/first-tree/` and
+`.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,
+`members/NODE.md`), and generates a task list in
+`.agents/skills/first-tree/progress.md`.
 
 Publishing tip: keep the tree repo in the same GitHub organization as the
 source repo unless you have a reason not to.
 
+Hard boundary: do **not** create `NODE.md`, `members/`, or tree-scoped
+`AGENTS.md` in the source/workspace repo. Those files belong only in the
+dedicated `*-context` repo.
+
+Default agent workflow after initialization:
+
+1. Create and push the dedicated `*-context` repo in the same GitHub
+   organization as the source repo.
+2. Add the dedicated tree repo back to the source/workspace repo as a `git submodule`.
+3. Open a PR against the source/workspace repo's default branch for the local
+   skill integration plus the new submodule pointer. Do not merge it
+   automatically.
+
 ### Step 2: Work Through the Task List
 
-Read `skills/first-tree/progress.md`. It contains a checklist tailored to the current state of the repo. Complete each task:
+Read `.agents/skills/first-tree/progress.md`. It contains a checklist tailored
+to the current state of the repo. Complete each task:
 
 - Fill in `NODE.md` with your organization name, owners, and domains
 - Add project-specific instructions to `AGENTS.md` below the framework markers
 - Create member nodes under `members/`
-- Optionally configure agent integration (e.g., Claude Code session hooks)
-- Copy validation workflows from `skills/first-tree/assets/framework/workflows/` to `.github/workflows/`
+- Optionally configure agent integration (for Claude Code, the installed hook
+  assets live under `.claude/skills/first-tree/`)
+- Copy validation workflows from
+  `.agents/skills/first-tree/assets/framework/workflows/` to
+  `.github/workflows/`
 
-As you complete each task, check it off in `skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.
+As you complete each task, check it off in
+`.agents/skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.
 
 ### Step 3: Verify
 
@@ -112,7 +134,13 @@ Or, from your source/workspace repo:
 context-tree verify --tree-path ../my-org-context
 ```
 
-This fails if any items in `skills/first-tree/progress.md` remain unchecked, and runs deterministic checks (valid frontmatter, node structure, member nodes exist).
+This fails if any items in `.agents/skills/first-tree/progress.md` remain
+unchecked, and runs deterministic checks (valid frontmatter, node structure,
+member nodes exist).
+
+Do not run `context-tree verify` in the source/workspace repo itself. That repo
+only carries the installed skill plus the
+`FIRST-TREE-SOURCE-INTEGRATION:` line.
 
 ### Step 4: Design Your Domains
 
@@ -149,7 +177,7 @@ The tree doesn't duplicate source code — it captures what connects things and
 
 | Command | Description |
 |---------|-------------|
-| `context-tree init` | Create or refresh a dedicated tree repo. By default, running in a source/workspace repo creates a sibling `<repo>-context`; use `--here` to initialize the current repo in place. |
+| `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` to initialize the current repo in place. |
 | `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. Use `--tree-path` when invoking from another working directory. |
 | `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. |
 | `context-tree help onboarding` | Print this onboarding guide. |
@@ -164,13 +192,19 @@ When the framework updates:
 context-tree upgrade
 ```
 
-`context-tree upgrade` refreshes `skills/first-tree/` from the
-skill bundled with the currently running `first-tree` npm package, preserves your
-tree content, and generates follow-up tasks in
-`skills/first-tree/progress.md`.
+`context-tree upgrade` refreshes `.agents/skills/first-tree/` and
+`.claude/skills/first-tree/` from the skill bundled with the currently running
+`first-tree` npm package, preserves your tree content, and generates follow-up
+tasks in `.agents/skills/first-tree/progress.md`.
+
+If you run `context-tree upgrade` in the source/workspace repo, it refreshes
+only the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.
+Run `context-tree upgrade --tree-path ../my-org-context` to upgrade the
+dedicated tree repo itself.
 
-If your repo still uses the older `skills/first-tree-cli-framework/` path,
-`context-tree upgrade` will migrate it to `skills/first-tree/` first.
+If your repo still uses the older `skills/first-tree/`,
+`skills/first-tree-cli-framework/`, or `.context-tree/` layouts,
+`context-tree upgrade` will migrate it to the current installed layout first.
 
 To pick up a newer framework release, first run a newer package version, for
 example `npx first-tree@latest upgrade`, or update your global `first-tree`
@@ -180,6 +214,7 @@ install before running `context-tree upgrade`.
 
 ## Further Reading
 
-- `skills/first-tree/references/principles.md` — Core principles with detailed examples
-- `skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned
+- `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples
+- `.agents/skills/first-tree/references/source-workspace-installation.md` — Source/workspace install contract
+- `.agents/skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned
 - `AGENTS.md` in your tree — The before/during/after workflow for every task

package/skills/first-tree/references/principles.md

@@ -5,25 +5,26 @@ owners: []
 
 # Tree Principles
 
-This document explains the core principles of Context Tree with concrete examples.
+This document explains the four core principles of Context Tree and how to
+apply them in practice. Read them in order: principle 1 defines what the tree
+is for, principle 2 explains how to organize it, principle 3 clarifies access
+and ownership, and principle 4 explains why the structure is tree-shaped and
+Git-native.
 
 ---
 
 ## 1. Source of truth for decisions, not execution
 
-The tree captures the *what* and *why* — strategic choices, cross-domain relationships, constraints. An agent should be able to read the tree and produce a correct approach without consulting source systems.
+The tree captures the *what* and *why* - strategic choices, cross-domain
+relationships, and constraints. An agent should be able to read the tree and
+decide on the right approach before consulting source systems for
+implementation details.
 
-### Workflow
+### The decision test
 
-1. Human says: "Let's add SSO to our product."
-2. Agent reads relevant tree nodes (e.g., `platform/`, `environment/`).
-3. Agent writes a top-level design based on tree context alone.
-4. Human reviews and approves.
-5. Agent explores source systems to build a detailed execution plan.
-6. If source systems reveal something the tree didn't capture — update the tree, revisit with the human, then proceed.
-7. After execution is complete, update the tree to reflect any new decisions.
-
-This applies to all tasks — features, campaigns, hiring decisions, refactors. Not every task requires a tree update, but the tree is always the starting point, and the question "does the tree need updating?" is always asked at the end.
+If an agent needs this information to *decide* on an approach, it belongs in
+the tree. If the agent only needs it to *execute*, it stays in the source
+system.
 
 ### What belongs in the tree
 
@@ -32,82 +33,121 @@ This applies to all tasks — features, campaigns, hiring decisions, refactors.
 - "We target academic researchers and AI-native teams because they have the highest tolerance for an agent-centric workflow."
 - "Q3 campaign focuses on developer communities because enterprise sales cycle is too long for our current stage."
 
-### What does NOT belong in the tree
+### What does not belong in the tree
 
-- The function signature of `retrieval_service.search()` — read the code.
-- The database schema for the `chunk_embeddings` table — read the models.
-- The current ad copy for a campaign — read the campaign tool.
-- The current list of API endpoints — read the route files.
-- The exact interview questions for a role — read the hiring doc.
+- The function signature of `retrieval_service.search()` - read the code.
+- The database schema for the `chunk_embeddings` table - read the models.
+- The current ad copy for a campaign - read the campaign tool.
+- The current list of API endpoints - read the route files.
+- The exact interview questions for a role - read the hiring doc.
 
-### The test
+### Good node examples
 
-If an agent needs this information to *decide* on an approach, it belongs in the tree. If the agent only needs it to *execute*, it stays in the source system.
+**Cross-domain relationships:** "Auth touches 4 repos: backend (JWT issuance), frontend (Better Auth client), browser extension (OAuth popup + device token), desktop (localhost callback server + JWT storage)." - An agent would need to search across all repos to piece this together.
 
-### When inconsistency is found
+**Strategic decisions with rationale:** "We use Reciprocal Rank Fusion to combine vector and BM25 results because pure vector search missed keyword-heavy queries and pure BM25 missed semantic matches." - This is nowhere in the source systems.
 
-If an agent reads the tree, makes a decision, then discovers a source system contradicts the tree — that's a tree bug. The tree must be corrected before proceeding. This is how the tree stays accurate: every completed task is an opportunity to validate and update it.
+**Domain state summaries:** "The ingestion pipeline has 6 stages: download -> extract -> parse -> chunk -> embed -> store. PDF extraction uses MinerU (cloud). PPTX uses python-pptx locally." - An agent could trace this through 6+ files, or read one node.
 
----
+### Bad node examples
 
-## 2. Agents are first-class participants
+- Restating what one source file already says clearly.
+- Documenting stable, well-known patterns (e.g., "we use FastAPI for the backend").
+- Listing things that change frequently without decision implications.
 
-The tree is designed to be navigated and updated by agents, not just humans. Domains are organized by concern — what an agent needs to know to act — not by repo, team, or org chart.
+### Use judgment, not a checklist
 
-### Why organize by concern?
+Not every task needs a tree update. A pure UI bug fix probably does not. But
+do not assume - a "simple" feature like dark mode becomes a tree-worthy
+decision once it involves auto mode, cross-device persistence, or desktop app
+coordination. Evaluate each task in context.
 
-An agent working on "add SSO support" doesn't think in terms of repos (backend, frontend, extension, desktop) or org structure (engineering vs. product). It needs all auth context — the why, the how, the cross-domain implications — in one place. Organizing by concern puts that context together.
+### How this works during a task
+
+1. Human says: "Let's add SSO to our product."
+2. Agent reads relevant tree nodes (e.g., `platform/`, `environment/`).
+3. Agent writes a top-level design based on tree context alone.
+4. Human reviews and approves.
+5. Agent explores source systems to build a detailed execution plan.
+6. If source systems reveal something the tree did not capture, update the
+   tree, revisit with the human, then proceed.
+7. After execution is complete, update the tree to reflect any new decisions.
 
-### Domain placement
+This applies to all tasks - features, campaigns, hiring decisions, refactors.
+Not every task requires a tree update, but the tree is always the starting
+point, and the question "does the tree need updating?" is always asked at the
+end.
 
-A feature or decision lives in the domain that owns the primary concern, with soft links to other domains for discoverability:
+### When the tree and source systems disagree
 
-- "Add SSO support" → `platform/` (auth decision), soft links to `environment/` (extension/desktop auth flows)
-- "Support PPTX parsing" → `knowledge/` (ingestion). Clear, single domain.
-- "Q3 developer campaign" → `marketing/` (go-to-market), soft link to product domain (feature positioning)
-- "Agent remembers user preferences" → `agent/` (memory)
-- "Hire a frontend engineer" → `people/hiring/` (role decision), soft link to the team they'd join
+If an agent reads the tree, makes a decision, then discovers a source system
+contradicts the tree, that is a tree bug. The tree must be corrected before
+proceeding. This is how the tree stays accurate: every completed task is an
+opportunity to validate and update it.
 
-### When to create subdomains
+---
 
-Start flat. Split when an agent can't scan a NODE.md and quickly determine where to go next. If a domain accumulates enough leaf nodes on a single topic, that topic is ready to become a subdomain.
+## 2. Agents are first-class participants
 
-### Whether something belongs in the tree is a judgment call
+The tree is designed to be navigated and updated by agents, not just humans.
+Domains are organized by concern - what an agent needs to know to act - not by
+repo, team, or org chart.
 
-Not every task needs a tree update. A pure UI bug fix probably doesn't. But don't assume — a "simple" feature like dark mode becomes a tree-worthy decision once it involves auto mode, cross-device persistence, or desktop app coordination. Evaluate per task.
+### Organize by concern
 
----
+An agent working on "add SSO support" does not think in terms of repos
+(backend, frontend, extension, desktop) or org structure (engineering vs.
+product). It needs all auth context - the why, the how, and the cross-domain
+implications - in one place. Organizing by concern puts that context together.
 
-## 3. Transparency by default
+### Place work in the domain of the primary concern
 
-All information in the tree is readable by everyone — humans and agents alike. Writing requires owner approval; reading is open.
+A feature or decision lives in the domain that owns the primary concern, with
+soft links to other domains for discoverability:
 
-This means any agent can build full context by traversing the tree. No domain is hidden. The ownership model controls who can *change* the tree, not who can *read* it.
+- "Add SSO support" -> `platform/` (auth decision), soft links to
+  `environment/` (extension/desktop auth flows)
+- "Support PPTX parsing" -> `knowledge/` (ingestion). Clear, single domain.
+- "Q3 developer campaign" -> `marketing/` (go-to-market), soft link to the
+  product domain (feature positioning)
+- "Agent remembers user preferences" -> `agent/` (memory)
+- "Hire a frontend engineer" -> `people/hiring/` (role decision), soft link to
+  the team they would join
 
----
+### Start flat, then split when needed
 
-## 4. Git-native tree structure
+Start flat. Split when an agent cannot scan a `NODE.md` and quickly determine
+where to go next. If a domain accumulates enough leaf nodes on a single topic,
+that topic is ready to become a subdomain.
 
-Each node is a file; each domain is a directory. The tree is a Git repository.
+---
 
-### Why a tree?
+## 3. Transparency by default
 
-A tree structure keeps information organized and navigable. Soft links allow cross-references where needed without the complexity of a full graph. An agent can start at any node and traverse up (broader context) or down (more detail) predictably.
+All information in the tree is readable by everyone - humans and agents alike.
+Reading is open; writing requires owner approval.
 
-### Why Git?
+This means any agent can build full context by traversing the tree. No domain
+is hidden. The ownership model controls who can *change* the tree, not who can
+*read* it.
 
-History, ownership, and review follow the same model software engineering has refined for decades. Every change is a commit, every decision is reviewable in a PR, and the full history of how the tree evolved is preserved.
+---
 
-### Examples of good nodes
+## 4. Git-native tree structure
 
-**Cross-domain relationships:** "Auth touches 4 repos: backend (JWT issuance), frontend (Better Auth client), browser extension (OAuth popup + device token), desktop (localhost callback server + JWT storage)." — An agent would need to search across all repos to piece this together.
+Each node is a file, each domain is a directory, and the tree itself is a Git
+repository. The tree shape gives predictable navigation; Git provides history,
+review, and ownership workflows.
 
-**Strategic decisions with rationale:** "We use Reciprocal Rank Fusion to combine vector and BM25 results because pure vector search missed keyword-heavy queries and pure BM25 missed semantic matches." — This is nowhere in the source systems.
+### Why a tree
 
-**Domain state summaries:** "The ingestion pipeline has 6 stages: download → extract → parse → chunk → embed → store. PDF extraction uses MinerU (cloud). PPTX uses python-pptx locally." — An agent could trace this through 6+ files, or read one node.
+A tree structure keeps information organized and navigable. Soft links allow
+cross-references where needed without the complexity of a full graph. An agent
+can start at any node and traverse up (broader context) or down (more detail)
+predictably.
 
-### Examples of bad nodes
+### Why Git
 
-- Restating what one source file already says clearly.
-- Documenting stable, well-known patterns (e.g., "we use FastAPI for the backend").
-- Listing things that change frequently without decision implications.
+History, ownership, and review follow the same model software engineering has
+refined for decades. Every change is a commit, every decision is reviewable in
+a PR, and the full history of how the tree evolved is preserved.

package/skills/first-tree/references/source-map.md

@@ -11,6 +11,7 @@ information should be discoverable from this file.
 | `SKILL.md` | Trigger conditions, workflow, and validation contract |
 | `references/about.md` | Product framing for what Context Tree is and is not |
 | `references/onboarding.md` | The onboarding narrative that `help onboarding` and `init` surface |
+| `references/source-workspace-installation.md` | Contract for source/workspace installs vs dedicated tree repos |
 | `references/principles.md` | Decision-model reference |
 | `references/ownership-and-naming.md` | Ownership contract |
 | `references/upgrade-contract.md` | Installed layout and upgrade semantics |

package/skills/first-tree/references/source-workspace-installation.md

@@ -0,0 +1,52 @@
+---
+title: "Source/Workspace Installation Contract"
+owners: []
+---
+
+# Source/Workspace Installation Contract
+
+This reference defines what it means to "install and use first-tree" in an
+existing source or workspace repository.
+
+## Core Boundary
+
+- The current source/workspace repo is **not** the Context Tree.
+- The current source/workspace repo should carry only the installed
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/` skill roots
+  plus a single `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+  `CLAUDE.md`.
+- `NODE.md`, `members/`, and tree-scoped `AGENTS.md` content belong only in a
+  dedicated `*-context` repo.
+- If a task changes decisions, rationale, ownership, or constraints, update
+  the dedicated tree repo rather than copying that material into the source
+  repo.
+
+## Default Agent Workflow
+
+When an agent is asked to install first-tree for a source/workspace repo, the
+default workflow is:
+
+1. Install the bundled first-tree skill into the current repo.
+2. Upsert the `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+   `CLAUDE.md`.
+3. Create a sibling dedicated tree repo named `<repo>-context`.
+4. Prefer creating and pushing that repo in the same GitHub organization as
+   the source repo, matching the source repo's default visibility unless the
+   user asks for something else.
+5. Add the dedicated tree repo back to the source/workspace repo as a `git submodule`.
+6. Run `context-tree init --here` inside the dedicated tree repo.
+7. Draft the first tree version from the real codebase, docs, and ownership
+   signals.
+8. Open a PR against the source/workspace repo's default branch for the local
+   skill integration plus the new submodule pointer. Do not merge it
+   automatically.
+
+## Verification And Upgrade
+
+- Do not run `context-tree verify` in the source/workspace repo. Verify the
+  dedicated tree repo instead, for example
+  `context-tree verify --tree-path ../my-repo-context`.
+- Running `context-tree upgrade` in the source/workspace repo refreshes only
+  the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.
+- Run `context-tree upgrade --tree-path ../my-repo-context` to upgrade the
+  dedicated tree repo itself.

package/skills/first-tree/references/upgrade-contract.md

@@ -1,8 +1,8 @@
 # Upgrade Contract
 
 This file describes the current installed-layout contract and the compatibility
-rules we keep for legacy `skills/first-tree-cli-framework/` and
-`.context-tree/` repos.
+rules we keep for legacy `skills/first-tree/`,
+`skills/first-tree-cli-framework/`, and `.context-tree/` repos.
 
 ## Canonical Source
 
@@ -16,49 +16,85 @@ rules we keep for legacy `skills/first-tree-cli-framework/` and
 
 ## Installed Layout
 
-The current installed layout in a user repo is:
+The current installed layout in a source/workspace repo or dedicated tree repo
+is:
 
 ```text
-skills/
-  first-tree/
-    SKILL.md
-    progress.md
-    references/
-    assets/
-      framework/
-        manifest.json
-        VERSION
-        templates/
-        workflows/
-        prompts/
-        examples/
-        helpers/
+.agents/
+  skills/
+    first-tree/
+      SKILL.md
+      progress.md
+      references/
+      assets/
+        framework/
+          manifest.json
+          VERSION
+          templates/
+          workflows/
+          prompts/
+          examples/
+          helpers/
+.claude/
+  skills/
+    first-tree/
+      SKILL.md
+      references/
+      assets/
+        framework/
+          manifest.json
+          VERSION
+          templates/
+          workflows/
+          prompts/
+          examples/
+          helpers/
 ```
 
-The tree content still lives outside the skill:
+For a source/workspace repo, the local integration stops there. It should also
+carry a single `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+`CLAUDE.md`, but it must not contain tree content.
+
+For a dedicated tree repo, the tree content still lives outside the skill:
 
 - `NODE.md`
 - `AGENTS.md`
 - `members/`
 
+The repo-owned `.agents/skills/first-tree/` path is the primary installed root
+for progress state, workflow references, and helper scripts. The matching
+`.claude/skills/first-tree/` path mirrors the same payload for Claude-facing
+skill discovery and hooks.
+
 ## Command Intent
 
 - `context-tree init`
   - when run in a source/workspace repo, creates or reuses a sibling dedicated
     tree repo by default
+  - installs the skill into the source/workspace repo without creating tree
+    files there
+  - upserts the `FIRST-TREE-SOURCE-INTEGRATION:` line in root `AGENTS.md` and
+    `CLAUDE.md`
   - installs the skill into the target tree repo
-  - renders top-level tree scaffolding from the skill templates
-  - writes progress state to `skills/first-tree/progress.md`
+  - renders top-level tree scaffolding only in the target tree repo
+  - writes progress state only to the dedicated tree repo at
+    `.agents/skills/first-tree/progress.md`
 - `context-tree verify`
   - checks progress state from the installed skill
   - validates root/frontmatter/agent markers
   - runs node and member validators
+  - must reject source/workspace repos that carry only local integration
 - `context-tree upgrade`
   - compares the installed skill payload version to the skill bundled with the
     currently running `first-tree` package
   - refreshes the installed skill payload without overwriting tree content
+  - when run in a source/workspace repo, refreshes only the local installed
+    skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines
+  - migrates repos that still use the previous `skills/first-tree/` path onto
+    `.agents/skills/first-tree/` and `.claude/skills/first-tree/`
   - migrates repos that still use the previous
-    `skills/first-tree-cli-framework/` path onto `skills/first-tree/`
+    `skills/first-tree-cli-framework/` path onto `.agents/skills/first-tree/`
+    and `.claude/skills/first-tree/`
   - migrates legacy `.context-tree/` repos onto the installed skill layout
   - preserves user-authored sections such as the editable part of `AGENTS.md`
 
@@ -70,17 +106,22 @@ The tree content still lives outside the skill:
 - Default dedicated-tree-repo creation is local-only. The CLI may create a new
   sibling git repo on disk, but it must not clone the source repo or depend on
   network access.
+- Source/workspace repos must never receive `NODE.md`, `members/`, or
+  tree-scoped `AGENTS.md` from default init flows.
 - Normal `context-tree init` and `context-tree upgrade` flows do not clone the
   source repo or require network access.
 - `context-tree verify` may still read a legacy
-  `skills/first-tree-cli-framework/...` or `.context-tree/...` layout in an
-  existing user repo so the repo can be upgraded in place.
+  `.claude/skills/first-tree/...`, `skills/first-tree/...`,
+  `skills/first-tree-cli-framework/...`, or `.context-tree/...` layout in an
+  existing user repo so the repo can be repaired or upgraded in place.
 - `context-tree upgrade` must migrate either legacy layout onto
-  `skills/first-tree/` and remove the old directory afterward.
-- When both layouts are present, prefer the installed skill layout.
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`, and remove
+  old skill directories afterward.
+- When both current and legacy layouts are present, prefer the
+  `.agents/skills/first-tree/` layout.
 - Existing repos may still have a legacy `AGENT.md`; `init` and `upgrade`
   must not silently overwrite it, and follow-up tasks should direct users to
-  rename it to `AGENTS.md`.
+  rename or merge it into `AGENTS.md`.
 
 ## Invariants
 

package/skills/first-tree/scripts/check-skill-sync.sh

@@ -39,6 +39,7 @@ require_file "$SOURCE_DIR/SKILL.md"
 require_file "$SOURCE_DIR/agents/openai.yaml"
 require_file "$SOURCE_DIR/references/about.md"
 require_file "$SOURCE_DIR/references/onboarding.md"
+require_file "$SOURCE_DIR/references/source-workspace-installation.md"
 require_file "$SOURCE_DIR/references/principles.md"
 require_file "$SOURCE_DIR/references/ownership-and-naming.md"
 require_file "$SOURCE_DIR/references/source-map.md"
@@ -59,6 +60,7 @@ require_file "$SOURCE_DIR/engine/commands/verify.ts"
 require_file "$SOURCE_DIR/engine/rules/index.ts"
 require_file "$SOURCE_DIR/engine/runtime/asset-loader.ts"
 require_file "$SOURCE_DIR/engine/runtime/installer.ts"
+require_file "$SOURCE_DIR/engine/runtime/source-integration.ts"
 require_file "$SOURCE_DIR/engine/runtime/upgrader.ts"
 require_file "$SOURCE_DIR/engine/runtime/adapters.ts"
 require_file "$SOURCE_DIR/engine/validators/members.ts"

package/skills/first-tree/tests/asset-loader.test.ts

@@ -2,8 +2,11 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
+  CLAUDE_INSTALLED_PROGRESS,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
+  LEGACY_REPO_SKILL_PROGRESS,
+  LEGACY_REPO_SKILL_VERSION,
   LEGACY_SKILL_PROGRESS,
   LEGACY_SKILL_VERSION,
   LEGACY_PROGRESS,
@@ -18,7 +21,7 @@ import { useTmpDir } from "./helpers.js";
 describe("asset-loader", () => {
   it("prefers the installed skill layout when both layouts exist", () => {
     const tmp = useTmpDir();
-    mkdirSync(join(tmp.path, "skills", "first-tree", "assets", "framework"), {
+    mkdirSync(join(tmp.path, ".agents", "skills", "first-tree", "assets", "framework"), {
       recursive: true,
     });
     mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
@@ -39,6 +42,21 @@ describe("asset-loader", () => {
     expect(detectFrameworkLayout(tmp.path)).toBe("legacy");
   });
 
+  it("detects the previous workspace skill path before older layouts", () => {
+    const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, "skills", "first-tree", "assets", "framework"), {
+      recursive: true,
+    });
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, LEGACY_REPO_SKILL_VERSION), "0.2.0\n");
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("legacy-repo-skill");
+    expect(
+      resolveFirstExistingPath(tmp.path, frameworkVersionCandidates()),
+    ).toBe(LEGACY_REPO_SKILL_VERSION);
+  });
+
   it("detects the previous installed skill name before the .context-tree layout", () => {
     const tmp = useTmpDir();
     mkdirSync(
@@ -59,12 +77,16 @@ describe("asset-loader", () => {
 
   it("prefers the installed progress file candidate", () => {
     const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, ".agents", "skills", "first-tree"), { recursive: true });
+    mkdirSync(join(tmp.path, ".claude", "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, "skills", "first-tree-cli-framework"), {
       recursive: true,
     });
     mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
     writeFileSync(join(tmp.path, INSTALLED_PROGRESS), "new");
+    writeFileSync(join(tmp.path, CLAUDE_INSTALLED_PROGRESS), "claude");
+    writeFileSync(join(tmp.path, LEGACY_REPO_SKILL_PROGRESS), "old-repo-skill");
     writeFileSync(join(tmp.path, LEGACY_SKILL_PROGRESS), "old-skill");
     writeFileSync(join(tmp.path, LEGACY_PROGRESS), "old");