docs(onboarding): default to breeze-first setup; drop push/pull framing#326
docs(onboarding): default to breeze-first setup; drop push/pull framing#326serenakeyitan merged 1 commit intomainfrom
Conversation
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.
serenakeyitan
force-pushed
the
docs/onboarding-gardener-breeze
branch
from
332dc70 to
b3dd036
Compare
|
Rebased onto main after #325 merged. Resolved the README conflict by keeping this PR's shorter breeze-first prompt (right design — moves heavy
Net: one commit on top of main, no new commits added (rebased into the existing commit). |
yuezengwu
left a comment
yuezengwu
left a comment
There was a problem hiding this comment.
One blocking issue: the new README quick-start prompt now tells a fresh agent to read .agents/skills/first-tree/references/onboarding.md immediately after CLI install, but that path only exists after the local skill payloads have been installed. That makes the literal-paste flow fail for the exact cold-start case this section is trying to optimize. Please restore an installable entrypoint before that path reference, or point the prompt at a CLI surface that already exists after install (for example first-tree tree help onboarding).
This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.
| 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 |
There was a problem hiding this comment.
This regresses the cold-start flow: after only installing the CLI, .agents/skills/first-tree/references/onboarding.md is not on disk yet. A literal agent following this prompt will fail before it ever reaches the step that installs the skills. Can we either restore an explicit first-tree skill install step before this reference, or send the agent to a CLI entrypoint that exists immediately after install (for example first-tree tree help onboarding)?
yuezengwu
added
breeze:done
|
Missed this by 6 seconds — review landed just after I admin-merged. The critique is correct: |
yuezengwu
added
breeze:wip
## Summary Follow-up to yuezengwu's CHANGES_REQUESTED review on #326 (review arrived 6 seconds after admin-merge — addressing it here). The prompt merged in #326 told a cold-start agent to read `.agents/skills/first-tree/references/onboarding.md` right after CLI install. But that path only exists after `first-tree skill install` runs, which is part of the setup the onboarding skill itself walks the user through — classic chicken-and-egg. Points the prompt at `first-tree tree help onboarding` instead (verified in `src/products/tree/cli.ts:12,37`, which already advertises this command as the "new to first-tree" entry). The skill-path reference is now mentioned as a post-install artifact, not the starting point. ## Test plan - [x] Confirmed `first-tree tree help onboarding` is a real registered subcommand in `src/products/tree/cli.ts` - [x] Literal paste of the new prompt references only commands that exist immediately after `npm install -g first-tree` / `npx first-tree` - [ ] yuezengwu re-review Refs #326.
## Summary Docs-only patch release so npm users get the updated onboarding narrative bundled into `first-tree tree help onboarding`. Unreleased since v0.2.14: - #325 — make end-to-end onboarding prompt source/tree-agnostic - #326 — default to breeze-first setup - #327 — fix onboarding path bootstrap chicken-and-egg - #329 — add 6.4.b real source-PR trigger ## Test plan - [x] `pnpm release:check` green locally (version:check, validate:skill, typecheck, test, build, test:dist, test:release)
2 participants
Summary
gardener install-workflow(GitHub Actions) as the default, which requires source-repo write +ANTHROPIC_API_KEY+TREE_REPO_TOKEN+ a workflow-approval PR — friction a first-time user doesn't need.skills/first-tree/references/onboarding.mdStep 6: rewrite from "optional modules toggle" into agent-led setup for gardener + breeze. Two questions (source repo, watch status),breeze install, verify end-to-end. Workflow-mode deployment moved to a mention in Pitfalls for the niche power-user case; still reachable viaworkflow-mode.md.Why
Onboarding testing against v0.2.14 surfaced that the
install-workflowpath isn't realistic for most first-time users — breeze works for everyone (owners and non-owners), needs onlygh auth, and is the simpler recommendation. Presenting workflow mode as a peer of breeze in the main onboarding flow implies a deployment choice newcomers don't need to make, and pulls them into PAT/secret setup before they've even seen the chain work.Followup discussion from #291. The workflow path remains documented in
workflow-mode.mdand reachable via the Pitfalls section, so the niche case is still supported — it's just not the default.Test plan
install-workflow+ secrets inline.skills/first-tree/references/onboarding.mdStep 6 — verify the flow is: ask 2 questions → verify watch →breeze install→ trigger end-to-end → report each step. No "push mode" / "pull mode" terminology.workflow-mode.mdis still discoverable (linked from the Pitfalls bullet in Step 6).