first-tree 0.0.2 → 0.0.3

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

@@ -0,0 +1,85 @@
+# 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.
+
+## Canonical Source
+
+- `skills/first-tree/` is the only source of truth.
+- `references/` contains explanatory material.
+- `assets/framework/` contains the shipped runtime payload.
+- The distributable `first-tree` package must carry the canonical skill inside
+  the package itself.
+- The source repo does not keep a root `.context-tree/`, `docs/`, mirror skill
+  directories, or a bundled repo snapshot.
+
+## Installed Layout
+
+The current installed layout in a user repo is:
+
+```text
+skills/
+  first-tree/
+    SKILL.md
+    progress.md
+    references/
+    assets/
+      framework/
+        manifest.json
+        VERSION
+        templates/
+        workflows/
+        prompts/
+        examples/
+        helpers/
+```
+
+The tree content still lives outside the skill:
+
+- `NODE.md`
+- `AGENT.md`
+- `members/`
+
+## Command Intent
+
+- `context-tree init`
+  - installs the skill into the target repo
+  - renders top-level tree scaffolding from the skill templates
+  - writes progress state to `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
+- `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
+  - migrates repos that still use the previous
+    `skills/first-tree-cli-framework/` path onto `skills/first-tree/`
+  - migrates legacy `.context-tree/` repos onto the installed skill layout
+  - preserves user-authored sections such as the editable part of `AGENT.md`
+
+## Compatibility Rules For Legacy Trees
+
+- `context-tree init` only installs the skill layout; it never creates a new
+  `.context-tree/`.
+- 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.
+- `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.
+
+## Invariants
+
+- Templates, workflows, prompts, helper scripts, and explanatory references
+  must stay aligned.
+- If a change affects installed payload contents, bump
+  `assets/framework/VERSION` so packaged upgrades can detect it.
+- Ownership behavior must stay identical across layout changes.
+- The tree remains decision-focused; execution detail stays in source systems.
+- A path migration is incomplete if task text, docs, tests, and runtime assets
+  disagree about where the framework lives.

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+find_repo_root() {
+  local dir="$SKILL_DIR"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]] && grep -q '"name": "first-tree"' "$dir/package.json"; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+require_file() {
+  local path="$1"
+  if [[ ! -f "$path" ]]; then
+    echo "Missing file: $path" >&2
+    exit 1
+  fi
+}
+
+REPO_ROOT="$(find_repo_root || true)"
+SOURCE_DIR=""
+if [[ -n "$REPO_ROOT" ]]; then
+  SOURCE_DIR="$REPO_ROOT/skills/first-tree"
+fi
+
+if [[ -z "$REPO_ROOT" || "$SKILL_DIR" != "$SOURCE_DIR" ]]; then
+  echo "Run this script from the source-of-truth skill at skills/first-tree inside a live first-tree checkout." >&2
+  exit 1
+fi
+
+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/principles.md"
+require_file "$SOURCE_DIR/references/ownership-and-naming.md"
+require_file "$SOURCE_DIR/references/source-map.md"
+require_file "$SOURCE_DIR/references/upgrade-contract.md"
+require_file "$SOURCE_DIR/references/maintainer-architecture.md"
+require_file "$SOURCE_DIR/references/maintainer-thin-cli.md"
+require_file "$SOURCE_DIR/references/maintainer-build-and-distribution.md"
+require_file "$SOURCE_DIR/references/maintainer-testing.md"
+require_file "$SOURCE_DIR/engine/init.ts"
+require_file "$SOURCE_DIR/engine/onboarding.ts"
+require_file "$SOURCE_DIR/engine/repo.ts"
+require_file "$SOURCE_DIR/engine/upgrade.ts"
+require_file "$SOURCE_DIR/engine/verify.ts"
+require_file "$SOURCE_DIR/engine/commands/help.ts"
+require_file "$SOURCE_DIR/engine/commands/init.ts"
+require_file "$SOURCE_DIR/engine/commands/upgrade.ts"
+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/upgrader.ts"
+require_file "$SOURCE_DIR/engine/runtime/adapters.ts"
+require_file "$SOURCE_DIR/engine/validators/members.ts"
+require_file "$SOURCE_DIR/engine/validators/nodes.ts"
+require_file "$SOURCE_DIR/tests/init.test.ts"
+require_file "$SOURCE_DIR/tests/verify.test.ts"
+require_file "$SOURCE_DIR/tests/skill-artifacts.test.ts"
+require_file "$SOURCE_DIR/assets/framework/manifest.json"
+require_file "$SOURCE_DIR/assets/framework/VERSION"
+require_file "$SOURCE_DIR/assets/framework/prompts/pr-review.md"
+require_file "$SOURCE_DIR/assets/framework/templates/root-node.md.template"
+require_file "$SOURCE_DIR/assets/framework/templates/agent.md.template"
+require_file "$SOURCE_DIR/assets/framework/templates/members-domain.md.template"
+require_file "$SOURCE_DIR/assets/framework/templates/member-node.md.template"
+require_file "$SOURCE_DIR/assets/framework/workflows/validate.yml"
+require_file "$SOURCE_DIR/assets/framework/workflows/pr-review.yml"
+require_file "$SOURCE_DIR/assets/framework/workflows/codeowners.yml"
+require_file "$SOURCE_DIR/assets/framework/examples/claude-code/README.md"
+require_file "$SOURCE_DIR/assets/framework/examples/claude-code/settings.json"
+require_file "$SOURCE_DIR/assets/framework/helpers/generate-codeowners.ts"
+require_file "$SOURCE_DIR/assets/framework/helpers/run-review.ts"
+require_file "$SOURCE_DIR/assets/framework/helpers/inject-tree-context.sh"
+
+# Check for legacy artifacts that should not be committed.
+# Use git ls-files to ignore untracked local files (e.g. .claude/settings.local.json).
+for legacy_path in \
+  ".agents" \
+  ".claude" \
+  ".context-tree" \
+  "docs" \
+  "skills/first-tree-cli-framework" \
+  "tests" \
+  "skills/first-tree/references/repo-snapshot"
+do
+  if git -C "$REPO_ROOT" ls-files --error-unmatch "$legacy_path" >/dev/null 2>&1; then
+    echo "Unexpected legacy artifact tracked in git: $legacy_path" >&2
+    exit 1
+  fi
+done
+
+if [[ -e "$SOURCE_DIR/evals" ]]; then
+  echo "Skill should not contain repo-only eval tooling." >&2
+  exit 1
+fi
+
+require_file "$REPO_ROOT/evals/context-tree-eval.test.ts"
+require_file "$REPO_ROOT/evals/README.md"
+require_file "$REPO_ROOT/evals/helpers/case-loader.ts"
+require_file "$REPO_ROOT/evals/scripts/tree-manager.ts"
+require_file "$REPO_ROOT/evals/tests/eval-helpers.test.ts"
+
+if grep -q '"#docs/\*"' "$REPO_ROOT/package.json"; then
+  echo "package.json still exposes the legacy #docs import alias." >&2
+  exit 1
+fi
+
+if ! grep -q '"#skill/\*"' "$REPO_ROOT/package.json"; then
+  echo "package.json is missing the canonical #skill import alias." >&2
+  exit 1
+fi
+
+if ! grep -q '"skills/first-tree"' "$REPO_ROOT/package.json"; then
+  echo "package.json is missing the canonical skill in the published files list." >&2
+  exit 1
+fi
+
+if ! grep -q '#skill/engine/commands/init.js' "$REPO_ROOT/src/cli.ts"; then
+  echo "src/cli.ts is not dispatching to the skill-owned engine." >&2
+  exit 1
+fi
+
+echo "Canonical skill structure is clean."

package/skills/first-tree/scripts/quick_validate.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""
+Portable quick validator for a skill directory.
+
+This version is intentionally self-contained so it can run in CI and in copied
+skill folders without depending on external Python packages.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+MAX_SKILL_NAME_LENGTH = 64
+
+
+def extract_frontmatter(text: str) -> tuple[bool, str]:
+    if not text.startswith("---\n"):
+        return False, "No YAML frontmatter found"
+    match = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+    return True, match.group(1)
+
+
+def parse_simple_frontmatter(frontmatter: str) -> dict[str, str]:
+    data: dict[str, str] = {}
+    for line in frontmatter.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if ":" not in stripped:
+            continue
+        key, value = stripped.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+        if value.startswith(("'", '"')) and value.endswith(("'", '"')) and len(value) >= 2:
+            value = value[1:-1]
+        data[key] = value
+    return data
+
+
+def validate_skill(skill_path: str) -> tuple[bool, str]:
+    skill_dir = Path(skill_path)
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    content = skill_md.read_text()
+    ok, frontmatter_or_error = extract_frontmatter(content)
+    if not ok:
+        return False, frontmatter_or_error
+
+    frontmatter = parse_simple_frontmatter(frontmatter_or_error)
+
+    unexpected = set(frontmatter.keys()) - {"name", "description"}
+    if unexpected:
+      return False, f"Unexpected key(s) in frontmatter: {', '.join(sorted(unexpected))}"
+
+    name = frontmatter.get("name", "").strip()
+    if not name:
+        return False, "Missing 'name' in frontmatter"
+    if not re.match(r"^[a-z0-9-]+$", name):
+        return False, f"Name '{name}' should be hyphen-case"
+    if name.startswith("-") or name.endswith("-") or "--" in name:
+        return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        return False, f"Name is too long ({len(name)} > {MAX_SKILL_NAME_LENGTH})"
+
+    description = frontmatter.get("description", "").strip()
+    if not description:
+        return False, "Missing 'description' in frontmatter"
+    if len(description) > 1024:
+        return False, f"Description is too long ({len(description)} > 1024)"
+
+    openai_yaml = skill_dir / "agents" / "openai.yaml"
+    if not openai_yaml.exists():
+        return False, "agents/openai.yaml not found"
+
+    return True, "Skill is valid!"
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: quick_validate.py <skill_directory>")
+        return 1
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    return 0 if valid else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/first-tree/scripts/run-local-cli.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+INSTALL_GUIDE="${SKILL_DIR}/references/onboarding.md"
+
+find_repo_root() {
+  local dir="$SKILL_DIR"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]] && grep -q '"name": "first-tree"' "$dir/package.json"; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+REPO_ROOT="$(find_repo_root || true)"
+
+if [[ -n "${REPO_ROOT}" ]]; then
+  cd "$REPO_ROOT"
+  pnpm build >/dev/null
+  exec node dist/cli.js "$@"
+fi
+
+if command -v context-tree >/dev/null 2>&1; then
+  exec context-tree "$@"
+fi
+
+echo "Could not find a live first-tree checkout or a 'context-tree' binary on PATH." >&2
+echo "Install the npm package 'first-tree' if you want the portable runner to invoke the CLI outside the repo." >&2
+echo "Read the onboarding guide at: ${INSTALL_GUIDE}" >&2
+exit 1

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

@@ -0,0 +1,75 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  FRAMEWORK_VERSION,
+  INSTALLED_PROGRESS,
+  LEGACY_SKILL_PROGRESS,
+  LEGACY_SKILL_VERSION,
+  LEGACY_PROGRESS,
+  LEGACY_VERSION,
+  detectFrameworkLayout,
+  frameworkVersionCandidates,
+  progressFileCandidates,
+  resolveFirstExistingPath,
+} from "#skill/engine/runtime/asset-loader.js";
+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"), {
+      recursive: true,
+    });
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, FRAMEWORK_VERSION), "0.2.0\n");
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("skill");
+    expect(resolveFirstExistingPath(tmp.path, [FRAMEWORK_VERSION, LEGACY_VERSION])).toBe(
+      FRAMEWORK_VERSION,
+    );
+  });
+
+  it("falls back to the legacy layout when the skill is not installed", () => {
+    const tmp = useTmpDir();
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("legacy");
+  });
+
+  it("detects the previous installed skill name before the .context-tree layout", () => {
+    const tmp = useTmpDir();
+    mkdirSync(
+      join(tmp.path, "skills", "first-tree-cli-framework", "assets", "framework"),
+      {
+        recursive: true,
+      },
+    );
+    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
+    writeFileSync(join(tmp.path, LEGACY_SKILL_VERSION), "0.2.0\n");
+    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
+
+    expect(detectFrameworkLayout(tmp.path)).toBe("legacy-skill");
+    expect(
+      resolveFirstExistingPath(tmp.path, frameworkVersionCandidates()),
+    ).toBe(LEGACY_SKILL_VERSION);
+  });
+
+  it("prefers the installed progress file candidate", () => {
+    const tmp = useTmpDir();
+    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, LEGACY_SKILL_PROGRESS), "old-skill");
+    writeFileSync(join(tmp.path, LEGACY_PROGRESS), "old");
+
+    expect(resolveFirstExistingPath(tmp.path, progressFileCandidates())).toBe(
+      INSTALLED_PROGRESS,
+    );
+  });
+});

package/skills/first-tree/tests/generate-codeowners.test.ts

@@ -0,0 +1,94 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  parseOwners,
+  resolveNodeOwners,
+  collectEntries,
+  formatOwners,
+} from "../assets/framework/helpers/generate-codeowners.js";
+import { useTmpDir } from "./helpers.js";
+
+function write(root: string, relPath: string, content: string): string {
+  const p = join(root, relPath);
+  mkdirSync(join(p, ".."), { recursive: true });
+  writeFileSync(p, content);
+  return p;
+}
+
+// --- parseOwners ---
+
+describe("parseOwners", () => {
+  it("parses valid owners", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "---\nowners: [alice, bob]\n---\n");
+    expect(parseOwners(p)).toEqual(["alice", "bob"]);
+  });
+
+  it("handles empty owners", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "---\nowners: []\n---\n");
+    expect(parseOwners(p)).toEqual([]);
+  });
+
+  it("handles wildcard", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "---\nowners: [*]\n---\n");
+    expect(parseOwners(p)).toEqual(["*"]);
+  });
+
+  it("returns null for no frontmatter", () => {
+    const tmp = useTmpDir();
+    const p = write(tmp.path, "NODE.md", "# Just a heading\n");
+    expect(parseOwners(p)).toBeNull();
+  });
+});
+
+// --- resolveNodeOwners ---
+
+describe("resolveNodeOwners", () => {
+  it("returns direct owners", () => {
+    const tmp = useTmpDir();
+    write(tmp.path, "NODE.md", "---\nowners: [root-owner]\n---\n");
+    write(tmp.path, "domain/NODE.md", "---\nowners: [domain-owner]\n---\n");
+    const cache = new Map<string, string[]>();
+    const result = resolveNodeOwners(join(tmp.path, "domain"), tmp.path, cache);
+    expect(result).toEqual(["domain-owner"]);
+  });
+
+  it("inherits from parent", () => {
+    const tmp = useTmpDir();
+    write(tmp.path, "NODE.md", "---\nowners: [root-owner]\n---\n");
+    write(tmp.path, "domain/NODE.md", "---\nowners: []\n---\n");
+    const cache = new Map<string, string[]>();
+    const result = resolveNodeOwners(join(tmp.path, "domain"), tmp.path, cache);
+    expect(result).toEqual(["root-owner"]);
+  });
+});
+
+// --- collectEntries ---
+
+describe("collectEntries", () => {
+  it("excludes dot-prefixed dirs", () => {
+    const tmp = useTmpDir();
+    write(tmp.path, "NODE.md", "---\nowners: [root]\n---\n# Root\n");
+    write(tmp.path, "domain/NODE.md", "---\nowners: [alice]\n---\n# Domain\n");
+    write(tmp.path, ".hidden/NODE.md", "---\nowners: [secret]\n---\n# Hidden\n");
+    const entries = collectEntries(tmp.path);
+    const patterns = entries.map(([pat]) => pat);
+    expect(patterns.some((p) => p.includes("domain"))).toBe(true);
+    expect(patterns.some((p) => p.includes(".hidden"))).toBe(false);
+  });
+});
+
+// --- formatOwners ---
+
+describe("formatOwners", () => {
+  it("deduplicates owners", () => {
+    expect(formatOwners(["alice", "bob", "alice"])).toBe("@alice @bob");
+  });
+
+  it("adds @ prefix", () => {
+    expect(formatOwners(["alice"])).toBe("@alice");
+  });
+});

package/skills/first-tree/tests/helpers.ts

@@ -0,0 +1,149 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach } from "vitest";
+import {
+  FRAMEWORK_VERSION,
+  LEGACY_SKILL_VERSION,
+  LEGACY_VERSION,
+} from "#skill/engine/runtime/asset-loader.js";
+
+interface TmpDir {
+  path: string;
+}
+
+export function useTmpDir(): TmpDir {
+  const dir = mkdtempSync(join(tmpdir(), "ct-test-"));
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+  return { path: dir };
+}
+
+export function makeFramework(root: string, version = "0.1.0"): void {
+  mkdirSync(join(root, "skills", "first-tree", "assets", "framework"), {
+    recursive: true,
+  });
+  writeFileSync(join(root, FRAMEWORK_VERSION), `${version}\n`);
+}
+
+export function makeLegacyFramework(root: string, version = "0.1.0"): void {
+  const ct = join(root, ".context-tree");
+  mkdirSync(ct, { recursive: true });
+  writeFileSync(join(root, LEGACY_VERSION), `${version}\n`);
+}
+
+export function makeLegacyNamedFramework(
+  root: string,
+  version = "0.1.0",
+): void {
+  mkdirSync(
+    join(root, "skills", "first-tree-cli-framework", "assets", "framework"),
+    {
+      recursive: true,
+    },
+  );
+  writeFileSync(join(root, LEGACY_SKILL_VERSION), `${version}\n`);
+}
+
+export function makeSourceSkill(root: string, version = "0.2.0"): void {
+  const skillRoot = join(root, "skills", "first-tree");
+  mkdirSync(join(skillRoot, "agents"), { recursive: true });
+  mkdirSync(join(skillRoot, "assets", "framework", "templates"), {
+    recursive: true,
+  });
+
+  writeFileSync(
+    join(skillRoot, "SKILL.md"),
+    "---\nname: first-tree\ndescription: test\n---\n",
+  );
+  writeFileSync(
+    join(skillRoot, "agents", "openai.yaml"),
+    "display_name: First Tree\nshort_description: test\n",
+  );
+  writeFileSync(
+    join(skillRoot, "assets", "framework", "manifest.json"),
+    "{}\n",
+  );
+  writeFileSync(
+    join(skillRoot, "assets", "framework", "VERSION"),
+    `${version}\n`,
+  );
+  writeFileSync(
+    join(
+      skillRoot,
+      "assets",
+      "framework",
+      "templates",
+      "root-node.md.template",
+    ),
+    "---\ntitle: Example Tree\nowners: [alice]\n---\n# Example Tree\n",
+  );
+  writeFileSync(
+    join(
+      skillRoot,
+      "assets",
+      "framework",
+      "templates",
+      "agent.md.template",
+    ),
+    "<!-- BEGIN CONTEXT-TREE FRAMEWORK -->\nframework text\n<!-- END CONTEXT-TREE FRAMEWORK -->\n",
+  );
+  writeFileSync(
+    join(
+      skillRoot,
+      "assets",
+      "framework",
+      "templates",
+      "members-domain.md.template",
+    ),
+    "---\ntitle: Members\nowners: [alice]\n---\n# Members\n",
+  );
+}
+
+export function makeNode(
+  root: string,
+  opts?: { placeholder?: boolean },
+): void {
+  const body = opts?.placeholder
+    ? "<!-- PLACEHOLDER -->\n"
+    : "# Real content\n";
+  writeFileSync(
+    join(root, "NODE.md"),
+    `---\ntitle: My Org\nowners: [alice]\n---\n${body}`,
+  );
+}
+
+export function makeAgentMd(
+  root: string,
+  opts?: { markers?: boolean; userContent?: boolean },
+): void {
+  const markers = opts?.markers ?? true;
+  const userContent = opts?.userContent ?? false;
+  const parts: string[] = [];
+  if (markers) {
+    parts.push(
+      "<!-- BEGIN CONTEXT-TREE FRAMEWORK -->\nframework stuff\n<!-- END CONTEXT-TREE FRAMEWORK -->",
+    );
+  } else {
+    parts.push("# Agent instructions\n");
+  }
+  if (userContent) {
+    parts.push("\n# Project-specific\nThis is real user content.\n");
+  }
+  writeFileSync(join(root, "AGENT.md"), parts.join("\n"));
+}
+
+export function makeMembers(root: string, count = 1): void {
+  const membersDir = join(root, "members");
+  mkdirSync(membersDir, { recursive: true });
+  writeFileSync(
+    join(membersDir, "NODE.md"),
+    "---\ntitle: Members\n---\n",
+  );
+  for (let i = 0; i < count; i++) {
+    const d = join(membersDir, `member-${i}`);
+    mkdirSync(d);
+    writeFileSync(join(d, "NODE.md"), `---\ntitle: Member ${i}\nowners: [member-${i}]\ntype: human\nrole: Engineer\ndomains:\n  - engineering\n---\n`);
+  }
+}