first-tree 0.0.2 → 0.0.4

package/package.json

@@ -1,25 +1,48 @@
 {
   "name": "first-tree",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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": {
+    "url": "https://github.com/agent-team-foundation/first-tree/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agent-team-foundation/first-tree.git"
+  },
+  "keywords": [
+    "context-tree",
+    "cli",
+    "agents",
+    "knowledge-base",
+    "markdown"
+  ],
   "type": "module",
   "bin": {
     "context-tree": "./dist/cli.js"
   },
+  "imports": {
+    "#skill/*": "./skills/first-tree/*",
+    "#evals/*": "./evals/*",
+    "#src/*": "./src/*"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills/first-tree"
   ],
-  "scripts": {
-    "build": "tsdown src/cli.ts --format esm --out-dir dist",
-    "prepack": "pnpm build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsdown": "^0.12.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.2.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

@@ -0,0 +1,113 @@
+---
+name: first-tree
+description: Maintain the canonical `first-tree` skill and the thin `context-tree` CLI distributed by the `first-tree` npm package. Use when modifying `context-tree` commands (`init`, `verify`, `upgrade`, `help onboarding`), the installed skill payload under `assets/framework/`, maintainer references, or the build, packaging, test, and CI wiring that supports the framework.
+---
+
+# 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.
+
+## Source Of Truth
+
+- `skills/first-tree/` is the only canonical copy.
+- `references/` holds the explanatory docs the skill should load on demand.
+- `assets/framework/` holds the runtime payload that gets installed into user
+  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.
+
+## When To Read What
+
+1. Start with `references/source-map.md` to locate the right files.
+2. Read the user-facing reference that matches the task:
+   - `references/onboarding.md`
+   - `references/about.md`
+   - `references/principles.md`
+   - `references/ownership-and-naming.md`
+   - `references/upgrade-contract.md`
+3. Read the maintainer reference that matches the shell or validation surface:
+   - `references/maintainer-architecture.md`
+   - `references/maintainer-thin-cli.md`
+   - `references/maintainer-build-and-distribution.md`
+   - `references/maintainer-testing.md`
+4. Open `engine/` when changing `init`, `verify`, `upgrade`, command routing,
+   repo inspection, rules, runtime helpers, or validators.
+5. Open `assets/framework/` only when the task changes shipped templates,
+   workflows, prompts, examples, or helper scripts.
+6. Open `tests/` when changing validation coverage or maintainer workflows.
+7. Use `./scripts/run-local-cli.sh <command>` when you need to exercise the
+   live CLI from this repo.
+
+## Working Modes
+
+### Maintaining `first-tree`
+
+- Treat this repo as the distribution source for one canonical skill plus a
+  thin CLI shell, not as a tree repo.
+- Keep command behavior, validator behavior, shipped assets, maintainer
+  references, and package shell aligned.
+- If root README/AGENTS/CI text explains something non-obvious, migrate that
+  information into `references/` and trim the root file back down.
+- If you change runtime assets or skill references, run `pnpm validate:skill`.
+
+### Working In A User Tree Repo
+
+- `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.
+- `context-tree init` installs this skill into the target tree repo and
+  `NODE.md`, `AGENTS.md`, and `members/NODE.md`.
+- `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/`.
+- 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
+  stays in source systems.
+
+## Non-Negotiables
+
+- Preserve the CLI contract that it scaffolds, prints task lists, and validates
+  state; it does not fully automate tree maintenance.
+- Keep shipped assets generic. They must not contain org-specific content.
+- 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 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.
+- Make upgrade behavior explicit. If you change installed paths, update
+  `references/upgrade-contract.md`, task text, and tests together.
+
+## Validation
+
+- Repo checks: `pnpm typecheck`, `pnpm test`, `pnpm build`
+- Packaging check: `pnpm pack` when changing package contents or install/upgrade
+  behavior
+- Skill checks:
+  - `pnpm validate:skill`
+  - `python3 ./skills/first-tree/scripts/quick_validate.py ./skills/first-tree`
+  - `bash ./skills/first-tree/scripts/check-skill-sync.sh`
+
+## Key Files
+
+- `assets/framework/manifest.json`: runtime asset contract
+- `assets/framework/templates/`: generated scaffolds
+- `assets/framework/workflows/`: CI templates
+- `assets/framework/helpers/`: shipped helper scripts and review tooling
+- `engine/`: canonical framework and CLI behavior
+- `tests/`: canonical unit and structure validation
+- `references/source-map.md`: canonical reading index
+- `references/maintainer-architecture.md`: source-repo architecture and
+  invariants
+- `references/maintainer-thin-cli.md`: root shell contract
+- `references/maintainer-build-and-distribution.md`: packaging and release
+  guidance
+- `references/maintainer-testing.md`: validation workflow
+- `references/upgrade-contract.md`: installed layout and upgrade semantics

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

@@ -0,0 +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."

package/skills/first-tree/assets/framework/VERSION

@@ -0,0 +1 @@
+0.2.0

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

@@ -0,0 +1,14 @@
+# Claude Code Integration
+
+## Setup
+
+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
+```
+
+## 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.

package/skills/first-tree/assets/framework/examples/claude-code/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./skills/first-tree/assets/framework/helpers/inject-tree-context.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,224 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
+const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
+const SKIP = new Set(["node_modules", "__pycache__"]);
+
+export function parseOwners(path: string): string[] | null {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+  const fm = text.match(FRONTMATTER_RE);
+  if (!fm) return null;
+  const m = fm[1].match(OWNERS_RE);
+  if (!m) return null;
+  const raw = m[1].trim();
+  if (!raw) return []; // owners: [] — will inherit
+  return raw
+    .split(",")
+    .map((o) => o.trim())
+    .filter(Boolean);
+}
+
+export function resolveNodeOwners(
+  folder: string,
+  treeRoot: string,
+  cache: Map<string, string[]>,
+): string[] {
+  if (cache.has(folder)) return cache.get(folder)!;
+
+  const nodeMd = join(folder, "NODE.md");
+  const owners = parseOwners(nodeMd);
+
+  let resolved: string[];
+  if (owners === null || owners.length === 0) {
+    const parent = dirname(folder);
+    if (parent.length >= treeRoot.length && parent !== folder) {
+      resolved = resolveNodeOwners(parent, treeRoot, cache);
+    } else {
+      resolved = [];
+    }
+  } else {
+    resolved = owners;
+  }
+
+  cache.set(folder, resolved);
+  return resolved;
+}
+
+function isWildcard(owners: string[] | null): boolean {
+  return owners !== null && owners.includes("*");
+}
+
+function codeownersPath(path: string, treeRoot: string): string {
+  const r = relative(treeRoot, path).replace(/\\/g, "/");
+  try {
+    if (statSync(path).isDirectory()) return `/${r}/`;
+  } catch {
+    // not a dir
+  }
+  return `/${r}`;
+}
+
+export function formatOwners(owners: string[]): string {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const o of owners) {
+    if (!seen.has(o)) {
+      seen.add(o);
+      result.push(`@${o}`);
+    }
+  }
+  return result.join(" ");
+}
+
+export function collectEntries(
+  root: string,
+): [string, string[]][] {
+  const nodeCache = new Map<string, string[]>();
+  const entries: [string, string[]][] = [];
+
+  function walk(dir: string): void {
+    let names: string[];
+    try {
+      names = readdirSync(dir).sort();
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const full = join(dir, name);
+      const parts = relative(root, full).split("/");
+      if (parts.some((p) => SKIP.has(p) || p.startsWith("."))) continue;
+      try {
+        if (!statSync(full).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      if (!existsSync(join(full, "NODE.md"))) {
+        walk(full);
+        continue;
+      }
+
+      const folderOwners = resolveNodeOwners(full, root, nodeCache);
+
+      if (folderOwners.length > 0 && !isWildcard(folderOwners)) {
+        entries.push([codeownersPath(full, root), folderOwners]);
+      }
+
+      // Leaf files
+      for (const child of readdirSync(full).sort()) {
+        const childPath = join(full, child);
+        try {
+          if (
+            !statSync(childPath).isFile() ||
+            !child.endsWith(".md") ||
+            child === "NODE.md"
+          )
+            continue;
+        } catch {
+          continue;
+        }
+        const leafOwners = parseOwners(childPath);
+        if (isWildcard(leafOwners)) continue;
+        if (leafOwners && leafOwners.length > 0) {
+          const nonWildcardFolder = folderOwners.filter((o) => o !== "*");
+          const combined = [
+            ...nonWildcardFolder,
+            ...leafOwners.filter((o) => !nonWildcardFolder.includes(o)),
+          ];
+          if (combined.length > 0) {
+            entries.push([codeownersPath(childPath, root), combined]);
+          }
+        }
+      }
+
+      walk(full);
+    }
+  }
+
+  walk(root);
+
+  // Root-level leaf files
+  const rootOwners = resolveNodeOwners(root, root, nodeCache);
+  for (const child of readdirSync(root).sort()) {
+    const childPath = join(root, child);
+    try {
+      if (
+        !statSync(childPath).isFile() ||
+        !child.endsWith(".md") ||
+        child === "NODE.md"
+      )
+        continue;
+    } catch {
+      continue;
+    }
+    const leafOwners = parseOwners(childPath);
+    if (isWildcard(leafOwners)) continue;
+    if (leafOwners && leafOwners.length > 0) {
+      const combined = [
+        ...rootOwners,
+        ...leafOwners.filter((o) => !rootOwners.includes(o)),
+      ];
+      entries.push([codeownersPath(childPath, root), combined]);
+    }
+  }
+
+  // Root entry (catch-all)
+  if (rootOwners.length > 0) {
+    entries.unshift(["/*", rootOwners]);
+  }
+
+  return entries;
+}
+
+export function generate(
+  treeRoot: string,
+  opts?: { check?: boolean },
+): number {
+  const check = opts?.check ?? false;
+  const entries = collectEntries(treeRoot);
+  const codeownersFile = join(treeRoot, ".github", "CODEOWNERS");
+
+  const lines = ["# Auto-generated from Context Tree. Do not edit manually.", ""];
+  for (const [pattern, owners] of entries) {
+    if (owners.length > 0) {
+      lines.push(`${pattern.padEnd(50)} ${formatOwners(owners)}`);
+    }
+  }
+  lines.push(""); // trailing newline
+  const content = lines.join("\n");
+
+  if (check) {
+    if (existsSync(codeownersFile) && readFileSync(codeownersFile, "utf-8") === content) {
+      console.log("CODEOWNERS is up-to-date.");
+      return 0;
+    }
+    console.log(
+      "CODEOWNERS is out-of-date. Run: npx tsx skills/first-tree/assets/framework/helpers/generate-codeowners.ts",
+    );
+    return 1;
+  }
+
+  mkdirSync(dirname(codeownersFile), { recursive: true });
+  writeFileSync(codeownersFile, content);
+  console.log(`Wrote ${relative(treeRoot, codeownersFile)}`);
+  return 0;
+}
+
+const isDirectRun =
+  process.argv[1]?.endsWith("generate-codeowners.ts") ||
+  process.argv[1]?.endsWith("generate-codeowners.js");
+if (isDirectRun) {
+  process.exit(generate(process.cwd()));
+}

package/skills/first-tree/assets/framework/helpers/inject-tree-context.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Injects NODE.md content as additionalContext at session start.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TREE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+NODE_MD="$TREE_ROOT/NODE.md"
+
+if [ -f "$NODE_MD" ]; then
+  # Escape for JSON: backslashes, double quotes, newlines, tabs, carriage returns
+  CONTENT=$(sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' -e 's/\r/\\r/g' "$NODE_MD" | awk '{printf "%s\\n", $0}' | sed 's/\\n$//')
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"${CONTENT}\"}}"
+  exit 0
+fi
+
+exit 0

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

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * Run Claude Code review and extract structured JSON output.
+ *
+ * Builds the review prompt, invokes Claude Code with stream-json output,
+ * extracts text from the stream, parses the review JSON, and retries up
+ * to 3 times on failure. Writes the validated review JSON to /tmp/review.json.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CLAUDE_BIN = join(homedir(), ".local", "bin", "claude");
+const MAX_ATTEMPTS = 3;
+// Per-invocation budget cap. Worst case is $1.50 total (3 × $0.50),
+// though retries are cheap in practice due to cached context via --continue.
+const MAX_BUDGET_USD = 0.5;
+const AGENT_INSTRUCTIONS_PATHS = ["AGENTS.md", "AGENT.md"] as const;
+
+function resolveAgentInstructionsPath(): string {
+  for (const candidate of AGENT_INSTRUCTIONS_PATHS) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    "Missing AGENTS.md in repo root (legacy AGENT.md is also accepted during migration).",
+  );
+}
+
+function buildPrompt(diffPath: string): string {
+  const parts: string[] = [];
+  const agentInstructionsPath = resolveAgentInstructionsPath();
+  const files: [string, string][] = [
+    [agentInstructionsPath, agentInstructionsPath],
+    ["Root NODE.md", "NODE.md"],
+    [
+      "Review Instructions",
+      "skills/first-tree/assets/framework/prompts/pr-review.md",
+    ],
+  ];
+  for (const [heading, path] of files) {
+    const content = readFileSync(path, "utf-8");
+    parts.push(`## ${heading}\n\n${content}`);
+  }
+  const diff = readFileSync(diffPath, "utf-8");
+  parts.push(`## PR Diff\n\n\`\`\`\n${diff}\`\`\``);
+  return parts.join("\n\n");
+}
+
+export function extractStreamText(jsonl: string): string {
+  const textParts: string[] = [];
+  let resultText = "";
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (msg.type === "assistant") {
+      const message = msg.message as Record<string, unknown> | undefined;
+      const content = message?.content as Array<Record<string, unknown>> | undefined;
+      if (content) {
+        for (const block of content) {
+          if (block.type === "text" && typeof block.text === "string") {
+            textParts.push(block.text);
+          }
+        }
+      }
+    }
+    if (msg.type === "result") {
+      const r = msg.result;
+      if (typeof r === "string" && r) {
+        resultText = r;
+      }
+    }
+  }
+  // Prefer assistant text blocks; fall back to result field
+  return textParts.length > 0 ? textParts.join("") : resultText;
+}
+
+function runClaude(opts: { prompt?: string; continueSession?: boolean }): string {
+  const cmd = [
+    "-p",
+    "--dangerously-skip-permissions",
+    "--output-format", "stream-json",
+    "--verbose",
+    "--max-budget-usd", String(MAX_BUDGET_USD),
+  ];
+  if (opts.continueSession) {
+    cmd.push("--continue");
+  }
+
+  try {
+    const stdout = execFileSync(CLAUDE_BIN, cmd, {
+      input: opts.prompt,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "inherit"],
+      maxBuffer: 50 * 1024 * 1024,
+    });
+    return extractStreamText(stdout);
+  } catch (err: unknown) {
+    const code = (err as { status?: number }).status ?? 1;
+    console.error(`::error::Claude exited with code ${code}`);
+    process.exit(1);
+  }
+}
+
+export interface Review {
+  verdict: string;
+  summary?: string;
+  inline_comments?: Array<{ file: string; line: number; comment: string }>;
+}
+
+export function extractReviewJson(text: string): Review | null {
+  if (!text.trim()) return null;
+  // Strip markdown fences
+  let cleaned = text.replace(/```json\s*/g, "").replace(/```\s*/g, "");
+  const match = cleaned.match(/\{[\s\S]*\}/);
+  if (!match) return null;
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(match[0]);
+  } catch {
+    return null;
+  }
+  if (!obj.verdict) return null;
+  return obj as unknown as Review;
+}
+
+function main(): void {
+  const prompt = buildPrompt("/tmp/pr-diff.txt");
+  console.log(`=== Prompt size: ${Buffer.byteLength(prompt)} bytes ===`);
+
+  let text = runClaude({ prompt });
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    if (text.trim()) {
+      console.log(`=== Attempt ${attempt}: Raw output ===`);
+      console.log(text);
+      console.log("=== End raw output ===");
+    } else {
+      console.log(`=== Attempt ${attempt}: Empty output ===`);
+    }
+
+    const review = extractReviewJson(text);
+    if (review) {
+      console.log(
+        `Valid JSON with verdict='${review.verdict}' extracted on attempt ${attempt}`,
+      );
+      writeFileSync("/tmp/review.json", JSON.stringify(review));
+      return;
+    }
+
+    if (attempt === MAX_ATTEMPTS) {
+      console.error(
+        `::error::Failed to extract valid review JSON after ${MAX_ATTEMPTS} attempts`,
+      );
+      process.exit(1);
+    }
+
+    let retryMsg: string;
+    if (text.trim()) {
+      retryMsg =
+        "Your previous output could not be parsed as valid review JSON. " +
+        "Please output ONLY a valid JSON object matching the required schema " +
+        "(with verdict, optional summary, optional inline_comments). " +
+        "No other text, no markdown fences.";
+    } else {
+      retryMsg =
+        "You did not produce any visible text output. " +
+        "Please output ONLY the review as a valid JSON object with " +
+        "verdict (required), summary (optional), and inline_comments (optional). " +
+        "No other text, no markdown fences.";
+    }
+
+    console.log(`::warning::Attempt ${attempt} failed, asking Claude to retry...`);
+    text = runClaude({ prompt: retryMsg, continueSession: true });
+  }
+}
+
+const isDirectRun =
+  process.argv[1]?.endsWith("run-review.ts") ||
+  process.argv[1]?.endsWith("run-review.js");
+if (isDirectRun) {
+  main();
+}

package/skills/first-tree/assets/framework/manifest.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "skillName": "first-tree",
+  "runtimeAssetRoot": "assets/framework",
+  "versionFile": "VERSION",
+  "templatesDir": "templates",
+  "workflowsDir": "workflows",
+  "promptsDir": "prompts",
+  "examplesDir": "examples",
+  "helpersDir": "helpers"
+}