From b3dd0362164635ff8cce74b49c5ce83d459a7866 Mon Sep 17 00:00:00 2001 From: serenakeyitan Date: Thu, 23 Apr 2026 13:41:01 -0700 Subject: [PATCH] docs(onboarding): default to breeze-first setup; drop push/pull framing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The existing onboarding prompt in README.md recommends `gardener install-workflow` (GitHub Actions) as the default end-to-end path. That path requires source-repo write access + ANTHROPIC_API_KEY + TREE_REPO_TOKEN + workflow approval — friction a first-time user doesn't need. Breeze works for everyone (owners and non-owners), needs nothing beyond `gh auth`, and is the simpler recommendation. Changes: - README.md quick-start: rewrite the "end-to-end" prompt to reference the onboarding skill and stay short. Drop the `install-workflow` + secrets walkthrough from the paste. - skills/first-tree/references/onboarding.md Step 6: rewrite from an "optional modules toggle" into agent-led setup for gardener + breeze. Two questions (source repo, watch status), `breeze install`, verify end-to-end. Workflow deployment moved to a link in Pitfalls for the niche power-user case. Rationale discussed in #291 follow-up onboarding test (v0.2.14): workflow mode serves a narrow audience (owns source repo + wants no local daemon + accepts the PAT dance). Presenting it as a peer path implies a choice newcomers don't need to make. Breeze is the right default; workflow mode stays reachable via workflow-mode.md for those who need it. --- README.md | 49 +++---- skills/first-tree/references/onboarding.md | 143 ++++++++++++++++----- 2 files changed, 124 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index ef17dc8..b86e04d 100644 --- a/README.md +++ b/README.md @@ -112,41 +112,24 @@ https://github.com//. **Driving one full gardener → breeze cycle end-to-end:** -Paste this as-is — the agent asks you for the source repo and tree repo -before running anything, so there's nothing to fill in up front. +Paste this as-is — the agent will ask you which repos to target before +running anything, so there's nothing to fill in up front. ```text -Use the latest first-tree CLI (https://github.com/agent-team-foundation/first-tree). - -Before running any command, ask me two questions and wait for my answers: - -1. "What is the source repo you ship from?" (owner/name on GitHub) -2. "What is the tree repo that stores NODE.md?" (owner/name on GitHub) - -Do not assume, guess, or infer either from the current working directory. -If either answer is missing or ambiguous, stop and re-ask. Only after I've -confirmed both, proceed. - -Prerequisites: `gh` CLI authed (`gh auth status`), `jq` installed, -Node ≥ 22, and `ANTHROPIC_API_KEY` exported locally. - -Then, using those two values: - -1. Clone both repos locally if they aren't already, and `cd` into the - source repo checkout before running anything else. -2. Run `first-tree tree inspect --json` in the source repo to confirm - classification, then run `first-tree skill install` to install the - first-tree skill, and bind to the tree repo with - `first-tree tree bind --tree-path `. -3. From inside the source repo checkout, install the gardener push-mode - workflow: `first-tree gardener install-workflow --tree-repo `. - Walk me through the required `ANTHROPIC_API_KEY` and `TREE_REPO_TOKEN` - secrets. -4. Start breeze so notifications route back to me: - `first-tree breeze install --allow-repo ,`. -5. Trigger one drift event end-to-end: source PR → tree issue → - breeze pickup → draft-node PR. Monitor both repos I gave you via - `gh pr list` / `gh issue list` on each. +I want to set up first-tree — a Context Tree that tracks decisions across +my source repos. It ships two agents: gardener (detects drift and drafts +tree updates) and breeze (a local daemon that dispatches gardener on +GitHub notifications). + +Latest release: https://github.com/agent-team-foundation/first-tree/releases/latest + +Install the CLI, then follow the onboarding skill at +`.agents/skills/first-tree/references/onboarding.md`. Before running any +setup command, ask me which source repo (owner/name) and which tree repo +(owner/name) to target, and wait for my answers — do not infer from the +current working directory. Once I've confirmed both, walk me through +setup, then trigger one drift event end-to-end so I can watch: source PR +→ tree issue → breeze pickup → draft-node PR. ``` --- diff --git a/skills/first-tree/references/onboarding.md b/skills/first-tree/references/onboarding.md index a07bfd2..f41ddab 100644 --- a/skills/first-tree/references/onboarding.md +++ b/skills/first-tree/references/onboarding.md @@ -181,41 +181,114 @@ first-tree tree verify --tree-path ../my-org-tree Do not run `first-tree tree verify` in a source/workspace root without pointing it at a tree checkout. -## Step 6: Configure Modules (Optional) - -`first-tree` ships two optional modules that live on top of the core -tree toolkit: - -- **gardener** — automated review/response on source-repo PRs and sync - PRs. Gardener subcommands (`gardener comment`, `gardener respond`) - are **enabled by default** when invoked. To turn one off, write - `.claude/gardener-config.yaml` in the tree repo with an explicit - `enabled: false` for the relevant module: - - ```yaml - target_repo: owner/app-repo # source repo to review - tree_repo: owner/tree-repo # this tree repo (for attribution) - modules: - comment: - enabled: false # disable scan/verdict on source PRs - respond: - enabled: false # disable feedback handling on sync PRs - ``` - - Omitting the file or omitting a `modules..enabled` key leaves - that subcommand enabled — invoking `first-tree gardener ` - will still run. The opt-out is explicit `enabled: false`. - - **Operational guidance:** the safest way to keep a new tree quiet - while it's still skeletal is to simply not invoke `gardener` (and not - configure `breeze` to invoke it for you) until the tree has enough - content to give useful verdicts. Noisy comments on an empty tree - train reviewers to ignore them. - -- **breeze** — local notification daemon that dispatches gardener on - real GitHub events. Only needed if you want gardener to react to - review requests and assignments in real time. See the `breeze` skill - for setup. +## Step 6: Set Up Gardener And Breeze + +Once the tree is bound (Steps 1–5), set up the two agents that keep it +alive: + +- **gardener** — detects drift between source code and the tree, + posts verdicts on source-repo PRs, and drafts tree updates. +- **breeze** — a local daemon that polls your GitHub notifications + and dispatches gardener when something relevant happens. + +Drive this agent-led, not user-led: ask the user the questions +below, verify, then install. + +**Prerequisites** — confirm before starting: +- `gh` CLI authed (`gh auth status`) +- `jq` installed +- Node ≥ 22 +- `ANTHROPIC_API_KEY` exported locally (gardener's classifier) + +### 6.1 Ask The User + +1. What source repo should gardener track? (`owner/name`) +2. What tree repo stores `NODE.md`? (`owner/name`) — this is usually + the repo the user just bound in Steps 1–5, but confirm, don't assume. +3. Are they watching the source repo on GitHub? (required — breeze polls + notifications; no watch means no notifications means nothing + dispatches) + +Do not infer any of these from the current working directory. If any +answer is missing or ambiguous, stop and re-ask. + +### 6.2 Verify Watch Status + +```bash +gh api /repos//subscription +# 200 → watching +# 404 → not watching +``` + +If 404: tell the user to open `https://github.com/` and +click **Watch → All Activity**. Do not proceed until confirmed. + +### 6.3 Install + +```bash +first-tree breeze install --allow-repo , +``` + +This creates `~/.breeze/config.yaml` (if absent) and starts the breeze +daemon. Breeze will now watch notifications on those repos and invoke +gardener as needed. + +### 6.4 Verify End-To-End + +Trigger one drift event: + +```bash +TREE_REPO_TOKEN=$(gh auth token) \ + first-tree gardener sync --tree-path \ + --open-issues --assignee +``` + +Expect, in order: + +1. Tree issue filed on the tree repo (labeled + `first-tree:sync-proposal`). +2. Breeze activity log records the pickup + (`first-tree breeze status`). +3. Draft-node PR opened against the tree repo. + +Report each step to the user as it happens. If any step is silent for +more than a couple of minutes, check `first-tree breeze doctor`. + +### Opting Modules Out (Rare) + +Gardener's `comment` and `respond` subcommands are **enabled by +default** once invoked. To silence one while the tree is still +skeletal, write `.claude/gardener-config.yaml` in the tree repo: + +```yaml +target_repo: owner/app-repo # source repo to review +tree_repo: owner/tree-repo # this tree repo (for attribution) +modules: + comment: + enabled: false + respond: + enabled: false +``` + +Only explicit `enabled: false` disables a module; missing keys leave +it on. + +The safest way to keep a new tree quiet while it's still skeletal is +simply not to invoke gardener until the tree has enough content for +useful verdicts. Noisy comments on an empty tree train reviewers to +ignore them. + +### Pitfalls + +- `gardener install` is **not** a command. Use `breeze install` to run + gardener locally via breeze, or see `workflow-mode.md` if you want + to run gardener as a GitHub Actions workflow on the source repo + (requires write access and extra secrets — not recommended for + first-time setup). +- Pull-based dispatch silently no-ops without a GitHub watch + subscription. Verify before claiming setup is complete. +- `TREE_REPO_TOKEN` must be in the environment for every `gardener` + invocation, not just at setup. ## Step 7: Publish