first-tree 0.0.2 → 0.0.3

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,179 @@
+#!/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 { 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;
+
+function buildPrompt(diffPath: string): string {
+  const parts: string[] = [];
+  const files: [string, string][] = [
+    ["AGENT.md", "AGENT.md"],
+    ["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"
+}

package/skills/first-tree/assets/framework/prompts/pr-review.md

@@ -0,0 +1,38 @@
+You are a code reviewer for the context tree.
+
+Read the NODE.md of every domain touched by the PR.
+Read the leaf nodes in affected domains to check for conflicts or redundancy.
+Follow soft_links to check for conflicts with related domains.
+
+Check for:
+1. Tree structure conventions (NODE.md in folders, frontmatter with title/owners)
+2. Ownership — are the right owners declared?
+3. Principles compliance — design in tree, execution in code
+4. Soft links for cross-domain dependencies
+5. Consistency with existing nodes
+6. Clarity for agent consumption
+
+After reading the relevant tree files, output your review as a single JSON object in EXACTLY this schema:
+
+```json
+{
+  "verdict": "APPROVE" | "REQUEST_CHANGES" | "COMMENT",
+  "summary": "<1-3 sentence overall assessment>",
+  "inline_comments": [
+    {
+      "file": "<path>",
+      "line": <number>,
+      "comment": "<comment text>"
+    }
+  ]
+}
+```
+
+- `verdict` (required): one of `APPROVE`, `REQUEST_CHANGES`, or `COMMENT`.
+- `summary` (optional): concise overall assessment.
+- `inline_comments` (optional): omit the field entirely if there are none.
+
+Rules:
+- Output ONLY the JSON object, no other text.
+- CRITICAL: The `line` number MUST be a line that appears in the diff (a changed or added line). GitHub only allows inline comments on lines that are part of the diff. Do NOT comment on unchanged lines — if you need to reference an unchanged line, include it in the `summary` instead.
+- Only flag real problems in inline comments. Do NOT post positive feedback, praise, or "looks good" comments on individual lines. Do NOT suggest tiny wording improvements or stylistic nitpicks. If a change is correct, say nothing about it — silence means approval.

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

@@ -0,0 +1,48 @@
+<!-- BEGIN CONTEXT-TREE FRAMEWORK — do not edit this section -->
+# Agent Instructions for Context Tree
+
+You are working in a **Context Tree** — the living source of truth for decisions across the organization. Read and follow this before doing anything.
+
+## Principles
+
+1. **Source of truth for decisions, not execution.** The tree captures the *what* and *why* — strategic choices, cross-domain relationships, constraints. Execution details stay in source systems. 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.
+
+2. **Agents are first-class participants.** 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.
+
+3. **Transparency by default.** All information is readable by everyone. Writing requires owner approval; reading is open.
+
+4. **Git-native tree structure.** Each node is a file; each domain is a directory. Soft links allow cross-references without the complexity of a full graph. History, ownership, and review follow Git conventions.
+
+See `skills/first-tree/references/principles.md` for detailed explanations and examples.
+
+## Before Every Task
+
+1. **Read the root NODE.md** to understand the domain map.
+2. **Read the NODE.md of every domain relevant to your task.** If unsure which domains are relevant, start from root and follow the structure — it's organized by concern, not by repo.
+3. **Follow soft_links.** If a node declares `soft_links` in its frontmatter, read those linked nodes too. They exist because the domains are related.
+4. **Read leaf nodes that match your task.** NODE.md tells you what exists in each domain — scan it and read the leaves that are relevant.
+
+Do not skip this. The tree is already a compression of expensive knowledge — cross-domain relationships, strategic decisions, constraints. An agent that skips the tree will produce decisions that conflict with existing ones.
+
+## During the Task
+
+- **Decide in the tree, execute in source systems.** If the task involves a decision (not just a bug fix), draft or update the relevant tree node before executing.
+- **The tree is not for execution details.** Function signatures, DB schemas, API endpoints, ad copy — those live in source systems. The tree captures the *why* and *how things connect*.
+- **Respect ownership.** Each node declares owners in its frontmatter. If your changes touch a domain you don't own, flag it — the owner needs to review.
+
+## After Every Task
+
+Ask yourself: **Does the tree need updating?**
+
+- Did you discover something the tree didn't capture? (A cross-domain dependency, a new constraint, a decision that future agents would need.)
+- Did you find the tree was wrong or outdated? That's a tree bug — fix it.
+- Not every task changes the tree, but the question must always be asked.
+
+## Reference
+
+For ownership rules, tree structure, and key files, see [NODE.md](NODE.md) and `skills/first-tree/references/ownership-and-naming.md`.
+<!-- END CONTEXT-TREE FRAMEWORK -->
+
+# Project-Specific Instructions
+
+<!-- Add your project-specific agent instructions below this line. -->

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

@@ -0,0 +1,18 @@
+---
+title: "<Display Name>"
+owners: [<github-username>]
+type: "<human | personal_assistant | autonomous_agent>"
+role: "<role title>"
+domains:
+  - "<domain>"
+---
+
+# <Display Name>
+
+## About
+
+<!-- Who you are and what you bring to the team. -->
+
+## Current Focus
+
+<!-- What you're actively working on. -->

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

@@ -0,0 +1,45 @@
+---
+title: Members
+owners: []
+---
+
+# Members
+
+Member definitions, work scope, and personal node specifications.
+
+Members are **humans and AI agents**. Both are first-class participants in the organization — they own nodes, make decisions, and collaborate through the tree.
+
+---
+
+## Joining
+
+1. Create a personal directory under `members/` with a `NODE.md` (e.g., `members/alice/NODE.md`)
+2. Follow the required personal node format — CI will reject PRs with missing fields
+3. Be assigned as owner of relevant domain nodes
+
+---
+
+## Personal Node Format
+
+Each member is a **directory** under `members/` containing a `NODE.md`. Required frontmatter fields:
+
+```yaml
+---
+title: "<display name>"
+owners: [<github-username>]
+type: "<human | personal_assistant | autonomous_agent>"
+role: "<role in the organization>"
+domains:
+  - "<high-level domain or direction>"
+---
+```
+
+See `skills/first-tree/assets/framework/templates/member-node.md.template` for a full scaffold.
+
+---
+
+## Principles
+
+**Keep your node fresh.** Your personal node is how other members understand you. Stale information leads to poor decisions.
+
+**Trust the tree.** Communicate through the tree, not around it.

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

@@ -0,0 +1,38 @@
+---
+title: "<Your Organization>"
+owners: [<your-github-username>]
+---
+
+# <Your Organization>
+
+<!-- PLACEHOLDER: Replace this with a description of your organization and what this tree captures. -->
+
+The living source of truth for your organization. A structured knowledge base that agents and humans build and maintain together.
+
+---
+
+## Domains
+
+<!-- Add your domains here. Each domain is a top-level directory with a NODE.md.
+     Organize by concern — what an agent needs to know to act — not by repo or team.
+
+     Examples:
+     - **[engineering/](engineering/NODE.md)** — Backend, frontend, infrastructure decisions.
+     - **[product/](product/NODE.md)** — Product strategy, roadmap, user research.
+     - **[marketing/](marketing/NODE.md)** — Brand, positioning, campaigns.
+     - **[members/](members/NODE.md)** — Team member definitions and responsibilities.
+-->
+
+- **[members/](members/NODE.md)** — Team member definitions and responsibilities.
+
+---
+
+## Working with the Tree
+
+See [AGENT.md](AGENT.md) for agent instructions — the before/during/after workflow, ownership model, and tree maintenance.
+
+See [about.md](skills/first-tree/references/about.md) for background — the problem, the idea, and who it's for.
+
+See the installed framework documentation:
+- [principles.md](skills/first-tree/references/principles.md) — core principles with examples
+- [ownership-and-naming.md](skills/first-tree/references/ownership-and-naming.md) — node naming and ownership model

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

@@ -0,0 +1,31 @@
+name: Update CODEOWNERS
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ github.token }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - run: npx tsx skills/first-tree/assets/framework/helpers/generate-codeowners.ts
+
+      - name: Commit if changed
+        run: |
+          git add .github/CODEOWNERS
+          git diff --cached --quiet .github/CODEOWNERS && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "chore: update CODEOWNERS from tree ownership"
+          git push