first-tree 0.0.2 → 0.0.4

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/agents.md.template

@@ -0,0 +1,49 @@
+<!-- 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*.
+- **Bring source repos in as additional working directories.** When you need to inspect or edit code, open the relevant source repositories alongside this tree instead of copying execution detail into the tree.
+- **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,41 @@
+---
+title: "<Your Organization>"
+owners: [<your-github-username>]
+---
+
+# <Your Organization>
+
+<!-- PLACEHOLDER: Replace this with a description of your organization and what this tree captures across your source repos and systems. -->
+
+The living source of truth for your organization. A structured knowledge base that agents and humans build and maintain together across one or more source repositories and systems.
+
+---
+
+## 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
+
+Keep decision context here. Keep implementation detail in the source repos this
+tree describes.
+
+See [AGENTS.md](AGENTS.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

package/skills/first-tree/assets/framework/workflows/pr-review.yml

@@ -0,0 +1,146 @@
+name: PR Review
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+  issue_comment:
+    types: [created]
+
+jobs:
+  review:
+    if: >
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       contains(github.event.comment.body, '@claude'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+    env:
+      ANTHROPIC_BASE_URL: "https://openrouter.ai/api"
+      ANTHROPIC_AUTH_TOKEN: ${{ secrets.OPENROUTER_API_KEY }}
+      ANTHROPIC_API_KEY: ""
+      ANTHROPIC_DEFAULT_SONNET_MODEL: "anthropic/claude-sonnet-4.6"
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install Claude Code
+        run: curl -fsSL https://claude.ai/install.sh | bash
+
+      - name: Get PR info
+        id: pr
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number || github.event.issue.number }}
+          echo "number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+          gh pr diff "$PR_NUMBER" > /tmp/pr-diff.txt
+          gh pr view "$PR_NUMBER" --json headRefOid -q .headRefOid > /tmp/pr-head-sha.txt
+
+      - name: Run Claude review
+        run: npx tsx skills/first-tree/assets/framework/helpers/run-review.ts
+
+      - name: Parse and post review
+        run: |
+          PR_NUMBER=${{ steps.pr.outputs.number }}
+          HEAD_SHA=$(cat /tmp/pr-head-sha.txt)
+
+          # Extract fields
+          VERDICT=$(jq -r '.verdict // "COMMENT"' /tmp/review.json)
+          SUMMARY=$(jq -r '.summary // "Review completed."' /tmp/review.json)
+
+          case "$VERDICT" in
+            APPROVE) EVENT="APPROVE" ;;
+            REQUEST_CHANGES) EVENT="REQUEST_CHANGES" ;;
+            *) EVENT="COMMENT" ;;
+          esac
+
+          BODY="${SUMMARY}
+
+          ---
+          *Automated review by Claude Code via OpenRouter*"
+
+          # Check for inline comments
+          HAS_COMMENTS=$(jq 'has("inline_comments") and (.inline_comments | length > 0)' /tmp/review.json)
+
+          if [ "$HAS_COMMENTS" != "true" ]; then
+            gh api \
+              "repos/${{ github.repository }}/pulls/${PR_NUMBER}/reviews" \
+              -f body="$BODY" \
+              -f event="$EVENT" \
+              -f commit_id="$HEAD_SHA"
+          else
+            # Transform inline_comments to GitHub API format (file->path, comment->body)
+            jq '[.inline_comments[] | {path: .file, line: .line, body: .comment}]' \
+              /tmp/review.json > /tmp/comments.json
+
+            jq -n \
+              --arg body "$BODY" \
+              --arg event "$EVENT" \
+              --arg sha "$HEAD_SHA" \
+              --slurpfile comments /tmp/comments.json \
+              '{
+                body: $body,
+                event: $event,
+                commit_id: $sha,
+                comments: $comments[0]
+              }' > /tmp/review-payload.json
+
+            # Try inline review; fall back to summary-only if lines can't be resolved
+            if ! gh api \
+              "repos/${{ github.repository }}/pulls/${PR_NUMBER}/reviews" \
+              --input /tmp/review-payload.json 2>/tmp/review-api-error.txt; then
+              echo "Inline review failed, falling back to summary-only review"
+              cat /tmp/review-api-error.txt
+              INLINE_TEXT=$(jq -r '.[] | "**\(.path):\(.line)** — \(.body)"' /tmp/comments.json)
+              FALLBACK_BODY="${SUMMARY}
+
+          ### Inline Comments
+
+          ${INLINE_TEXT}
+
+          ---
+          *Automated review by Claude Code via OpenRouter*"
+              gh api \
+                "repos/${{ github.repository }}/pulls/${PR_NUMBER}/reviews" \
+                -f body="$FALLBACK_BODY" \
+                -f event="$EVENT" \
+                -f commit_id="$HEAD_SHA"
+            fi
+          fi
+
+      - name: Post full review output as comment
+        if: always()
+        run: |
+          PR_NUMBER=${{ steps.pr.outputs.number }}
+          {
+            echo "## Claude Code Review Output"
+            echo ""
+            if [ -f /tmp/review.json ] && jq empty /tmp/review.json 2>/dev/null; then
+              VERDICT=$(jq -r '.verdict // "N/A"' /tmp/review.json)
+              SUMMARY=$(jq -r '.summary // "N/A"' /tmp/review.json)
+              echo "**Verdict:** ${VERDICT}"
+              echo ""
+              echo "**Summary:** ${SUMMARY}"
+              HAS_COMMENTS=$(jq 'has("inline_comments") and (.inline_comments | length > 0)' /tmp/review.json)
+              if [ "$HAS_COMMENTS" = "true" ]; then
+                echo ""
+                echo "### Inline Comments"
+                echo ""
+                jq -r '.inline_comments[] | "#### \(.file):\(.line)\n\(.comment)\n"' /tmp/review.json
+              fi
+            else
+              echo "*No review output produced or failed to parse.*"
+            fi
+            echo ""
+            echo "---"
+            echo "*Automated review by Claude Code via OpenRouter*"
+          } > /tmp/comment-body.md
+          gh pr comment "$PR_NUMBER" --body-file /tmp/comment-body.md

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

@@ -0,0 +1,19 @@
+name: Validate Tree
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Validate tree
+        run: npx -p first-tree context-tree verify

package/skills/first-tree/engine/commands/help.ts

@@ -0,0 +1,32 @@
+const HELP_USAGE = `usage: context-tree help <topic>
+
+Topics:
+  onboarding   How to set up a context tree from scratch
+`;
+
+export { HELP_USAGE };
+
+type Output = (text: string) => void;
+
+export async function runHelp(
+  args: string[],
+  output: Output = console.log,
+): Promise<number> {
+  const topic = args[0];
+
+  if (!topic || topic === "--help" || topic === "-h") {
+    output(HELP_USAGE);
+    return 0;
+  }
+
+  switch (topic) {
+    case "onboarding": {
+      const { runOnboarding } = await import("#skill/engine/onboarding.js");
+      return runOnboarding(output);
+    }
+    default:
+      output(`Unknown help topic: ${topic}`);
+      output(HELP_USAGE);
+      return 1;
+  }
+}

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

@@ -0,0 +1 @@
+export { INIT_USAGE, parseInitArgs, runInitCli as runInit } from "#skill/engine/init.js";

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

@@ -0,0 +1 @@
+export { UPGRADE_USAGE, runUpgradeCli as runUpgrade } from "#skill/engine/upgrade.js";

package/skills/first-tree/engine/commands/verify.ts

@@ -0,0 +1 @@
+export { VERIFY_USAGE, runVerifyCli as runVerify } from "#skill/engine/verify.js";