first-tree

A Git-native knowledge layer for your team — and a three-tool suite that keeps it alive.

first-tree publishes the first-tree CLI and its bundled agent skills. A
Context Tree is the living source of truth for decisions, ownership, and
cross-domain relationships that humans and agents maintain together —
first-tree is the toolkit that lets agents build, tend, and react to it.

The Three Tools

┌──────────────────────────────────────────────────────────────────────┐
│                         first-tree (umbrella CLI)                    │
├──────────────┬───────────────────────────┬───────────────────────────┤
│    tree      │        gardener           │          breeze           │
│  toolkit     │    local daemon           │     local daemon          │
├──────────────┼───────────────────────────┼───────────────────────────┤
│  init, bind, │ watches source repos →    │ watches gh notifications  │
│  sync,       │ opens issues on the tree  │ → labels / routes / drafts│
│  publish,    │ repo & assigns owners;    │ replies for PRs, issues,  │
│  verify, ... │ responds to sync-PR       │ discussions, reviews.     │
│              │ review feedback.          │                           │
└──────────────┴───────────────────────────┴───────────────────────────┘
                           │
                   ┌───────┴────────┐
                   │ first-tree     │  ← umbrella skill:
                   │    skill       │    methodology, references,
                   │                │    routing into the product skills
                   └────────────────┘

Every product ships:

• an operational handbook at skills/<name>/SKILL.md (loaded into agents),
• a lazy CLI dispatcher at src/products/<name>/cli.ts,
• its own semver'd VERSION file, independent from the npm package version.

The umbrella first-tree skill at skills/first-tree/
is the single entry point an agent reads first — it teaches the Context Tree
methodology and routes to the three product skills above. The CLI also exposes
one maintenance namespace — first-tree skill ... — for skill
installation, diagnosis, and repair. It is not a fourth product.

Install And Run

The npm package and installed CLI command are both first-tree.

• One-off use without installing globally:

  npx first-tree tree inspect --json
  npx first-tree tree init
  

  For automation, hooks, or CI templates, prefer the more explicit form:

  npx -p first-tree first-tree tree inspect --json
  

• Global install:

  npm install -g first-tree
  first-tree tree init
  

• Show the installed CLI version:

  first-tree --version
  

• Show the command list:

  first-tree --help
  

Quick Start For Agents

Paste one of these into Claude Code, Codex, or any agent — from the root you
want to onboard:

First person on the team:

Use the latest first-tree CLI (https://github.com/agent-team-foundation/first-tree).
Run `first-tree tree inspect --json` to classify the current folder, then install
the skill and onboard this repo or workspace by creating a new Context Tree.

Joining an existing tree:

Use the latest first-tree CLI (https://github.com/agent-team-foundation/first-tree).
Run `first-tree tree inspect --json`, install the skill, and bind this repo or
workspace to the existing shared tree at
https://github.com/<your-org>/<your-tree-repo>.

Onboarding Modes

first-tree models onboarding with three explicit concepts:

• source / workspace root — the repo or folder that gets local agent integration
• tree repo — the Git repo that stores NODE.md, domains, members, decisions
• binding — metadata that links a source to a tree

Four first-class paths:

When the current root is a workspace, the workspace root gets local integration
plus .first-tree/source.json (with workspace members), and discovered child
repos become workspace-members bound to the same shared tree.

See skills/first-tree/references/onboarding.md
for the full guide, and run first-tree tree help onboarding to print it.

What Lives Where

<source-repo-or-workspace>/
  .agents/skills/first-tree/
  .claude/skills/first-tree
  WHITEPAPER.md
  AGENTS.md
  CLAUDE.md
  .first-tree/
    source.json              # includes workspace members for workspace roots
  … your code …

<tree-repo>/
  .agents/skills/first-tree/
  .claude/skills/first-tree
  .first-tree/
    VERSION
    progress.md
    tree.json
    bindings/<source-id>.json
    bootstrap.json
  source-repos.md
  NODE.md
  AGENTS.md
  CLAUDE.md
  members/NODE.md
  … tree domains …

The source/workspace root is never a tree — it never contains NODE.md,
members/, or tree-scoped AGENTS.md / CLAUDE.md. Source-side state lives
under .first-tree/source.json; tree-side state lives under
.first-tree/tree.json and .first-tree/bindings/<source-id>.json. The
default dedicated tree repo name is <repo>-tree, while shared tree setups
continue to work cleanly for multi-repo workspaces.

Commands

Package And Command

• The npm package is first-tree.
• The installed CLI command is also first-tree.
• The CLI dispatches into three products: tree, breeze, gardener.
• The CLI also exposes one maintenance namespace: skill.
  Run first-tree --help for the routing.
• The published package ships four skill payloads, each with the same
  name in the package and when installed into a user repo:
  • skills/first-tree/ — the umbrella entry-point first-tree skill (methodology, references, routing).
  • skills/tree/, skills/breeze/, skills/gardener/ — one operational handbook per product CLI.
• In this source repo, .agents/skills/first-tree/ and .claude/skills/first-tree/
  (plus the three product equivalents) are tracked symlink aliases back to the
  four skills/<name>/ payloads, so local agents resolve the same skills the
  package ships.
• npx first-tree <namespace> <command> is the recommended human-facing
  one-off entrypoint.
• For automation, hooks, and CI templates, prefer the more explicit
  npx -p first-tree first-tree <namespace> <command> form.

Canonical Documentation

User-facing references ship under skills/first-tree/references/ and get
copied into user repos by first-tree tree init / first-tree tree bind:

• Methodology overview: skills/first-tree/references/whitepaper.md
• Onboarding guide: skills/first-tree/references/onboarding.md
• Source/workspace install contract:
  skills/first-tree/references/source-workspace-installation.md
• Upgrade and layout contract:
  skills/first-tree/references/upgrade-contract.md

Decision-grade design knowledge for this project lives in the bound Context Tree
under first-tree-skill-cli/, not in this repo:

• Canonical architecture: first-tree-skill-cli/repo-architecture.md
• Canonical sync design: first-tree-skill-cli/sync.md

Repo-local maintainer notes live in:

• docs/source-map.md
• docs/architecture/overview.md
• docs/architecture/thin-cli.md
• docs/architecture/versioning.md
• docs/build/distribution.md
• docs/testing/overview.md
• docs/design/sync.md

These are implementation-only and never ship.

Repository Layout (For Contributors)

src/
  cli.ts                  # umbrella dispatcher
  products/
    manifest.ts           # single source of truth for product/meta registration
    tree/                 # tree product (CLI + engine)
    breeze/               # breeze product (CLI + engine + daemon)
    gardener/             # gardener product (CLI + engine)
  meta/
    skill-tools/          # `first-tree skill ...` maintenance commands
  shared/
    version.ts            # shared VERSION/package readers
assets/
  tree/                   # runtime assets installed into user repos
  breeze/                 # breeze dashboard HTML
skills/
  first-tree/             # umbrella skill (methodology + routing)
  tree/ breeze/ gardener/ # per-product operational handbooks
tests/
  tree/ breeze/ gardener/ meta/ e2e/     # grouped by product
docs/                     # maintainer-only implementation notes
evals/                    # maintainer-only evaluation harness

See AGENTS.md (== CLAUDE.md) for maintainer rules, and
docs/source-map.md for the annotated file map.

Developing

pnpm install --frozen-lockfile
pnpm validate:skill
pnpm typecheck
pnpm test
pnpm build
pnpm pack            # when package contents change

Evals live in evals/ — see evals/README.md.

Contributing And Security

• GitHub issue forms for bugs and feature requests.
• CONTRIBUTING.md for local setup and validation expectations.
• CODE_OF_CONDUCT.md for community expectations.
• SECURITY.md for vulnerability reporting.

License

Apache 2.0