feat(cli): teach conventions via scaffolded AGENTS.md, drop skill-install from setup prompt#1110
Merged
Conversation
…l-install from setup prompt The landing "copy setup prompt" told coding agents to `/plugin install lobu` first — a Claude-Code-only command that breaks the cursor/opencode claim, and an unnecessary dependency. The conventions the skill carried now ship in the scaffolded project itself. - AGENTS.md.tmpl: was a one-line `@TESTING.md` stub teaching nothing about the config API. Now documents the model, prereqs, layout, the full `define*` API (agent, chat platforms, entities, connections, auth/secrets, watchers/reactions), the bundled connector keys (e.g. Gmail is `google_gmail`), and conventions. It's auto-loaded by the coding agent and ships with the CLI version, so no install and no drift. - LandingPage.tsx: setup prompt is now pure-CLI and interview-first, with an env preflight, provider selection, a `validate` gate, and "trigger the source manually" — the gaps two teammate dry-runs exposed. - README.md.tmpl: fix stale "local PGlite" → embedded PostgreSQL. - owletto: correct the stale `lobu.toml` skill reference to `lobu.config.ts`. Verified: AGENTS.md.tmpl renders via the real `renderTemplate` (substitutions, sections, no stray vars); `make build-packages` + landing build green; a config written per the new AGENTS.md guidance (slack `platforms`, `google_gmail` connection, watcher, entity, auth profile) passes `lobu validate`.
📝 WalkthroughWalkthroughExpanded the CLI AGENTS template into a full project guide and updated the CLI README to document embedded PostgreSQL as the default. Made ChangesSetup Documentation & CLI Config Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint skipped: no ESLint configuration detected in root package.json. To enable, add Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/cli/src/templates/AGENTS.md.tmpl`:
- Around line 25-29: Update the prerequisites paragraph in AGENTS.md.tmpl so it
no longer insists a reachable Postgres is always required: clarify that Node
22–24 and an LLM key are always needed, but a reachable Postgres with the
pgvector extension is required only when the user sets DATABASE_URL to use an
external DB; otherwise explain that `lobu run` starts an embedded PostgreSQL by
default and keep the note about `isolated-vm` build rejection for Node 25+.
Specifically edit the sentence mentioning "a reachable Postgres" to be
conditional on external DATABASE_URL usage and keep references to `lobu run`,
`DATABASE_URL`, `pgvector`, and `isolated-vm`.
In `@packages/cli/src/templates/README.md.tmpl`:
- Line 7: Update the README template sentence to reflect actual `lobu run`
behavior: state that the embedded Postgres cluster data is created under the run
root at `.lobu/pgdata` (not `~/.lobu/data`), and clarify that `LOBU_DATA_DIR`
points to the run root which can be overridden; reference the `lobu run`
command, the `LOBU_DATA_DIR` env var, and the `.lobu/pgdata` path in the revised
sentence.
In `@packages/landing/src/components/LandingPage.tsx`:
- Line 40: The setup prompt in LandingPage.tsx incorrectly forces a reachable
external Postgres before continuing; update the validation and UI text (e.g., in
the component LandingPage and any helper like validateEnvironment or
onStartSetup) so Postgres is optional by default and only required when the user
explicitly selects "use external Postgres"; change the prompt/logic to accept
the embedded-Postgres default path and only perform a connectivity check when
the external-Postgres option is chosen, and adjust the displayed instruction
string to remove the mandatory external-Postgres requirement.
In `@packages/owletto`:
- Line 1: The PR is pinned to an off-main commit
(a317d4e1aa84da77fb566ba594ca5f6bd134a789) which breaks deployment; first merge
the feat/cli-prompt-cleanup branch into owletto/main so that the commit becomes
reachable from main, then update the submodule pointer in this repo to reference
the merged commit on owletto/main (replace the current SHA with the merged
commit SHA) and commit that submodule update so CI/FluxCD reads a main-reachable
SHA.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 6fe4ac5d-d8ae-49ce-85ea-57e85740c29f
📒 Files selected for processing (4)
packages/cli/src/templates/AGENTS.md.tmplpackages/cli/src/templates/README.md.tmplpackages/landing/src/components/LandingPage.tsxpackages/owletto
| ## Quick Start | ||
|
|
||
| Lobu boots as a single Node process. By default `lobu run` uses local PGlite with pgvector enabled and stores data under `~/.lobu/data` (override with `LOBU_DATA_DIR`). Set `DATABASE_URL` in `.env` only when you want to use an external Postgres instead. | ||
| Lobu boots as a single Node process. By default `lobu run` starts an embedded PostgreSQL (with pgvector) and stores data under `~/.lobu/data` (override with `LOBU_DATA_DIR`). Set `DATABASE_URL` in `.env` only when you want to use an external Postgres instead. |
There was a problem hiding this comment.
Default embedded data path in docs appears incorrect.
This line says data lives under ~/.lobu/data and references LOBU_DATA_DIR, but runtime behavior indicates embedded DB resolves to a root and stores cluster data at .lobu/pgdata beneath it. Please align this sentence with actual lobu run behavior to prevent operator confusion.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/cli/src/templates/README.md.tmpl` at line 7, Update the README
template sentence to reflect actual `lobu run` behavior: state that the embedded
Postgres cluster data is created under the run root at `.lobu/pgdata` (not
`~/.lobu/data`), and clarify that `LOBU_DATA_DIR` points to the run root which
can be overridden; reference the `lobu run` command, the `LOBU_DATA_DIR` env
var, and the `.lobu/pgdata` path in the revised sentence.
| @@ -1 +1 @@ | |||
| Subproject commit 36c39bfc17ae0ed98f5dcee78c5f43cf202abe50 | |||
| Subproject commit a317d4e1aa84da77fb566ba594ca5f6bd134a789 | |||
There was a problem hiding this comment.
Pipeline failure: Pinned SHA is not on owletto/main and breaks deployment.
The CI check confirms that commit a317d4e1aa84da77fb566ba594ca5f6bd134a789 is not reachable from owletto/main. This violates the repository's hard rule that prevents off-main submodule pins. Per the workflow context, FluxCD reads charts from owletto/main, so this pin will break deployment.
The PR objectives mention pushing branch feat/cli-prompt-cleanup to owletto, which suggests this commit is from that feature branch.
Required fix:
- Merge the
feat/cli-prompt-cleanupbranch toowletto/mainfirst - Then update this submodule pointer to reference the merged commit
🧰 Tools
🪛 GitHub Actions: Submodule Drift / check-drift
[error] 1-1: Hard rule failed: Pinned SHA $PINNED is not reachable from owletto/main. Error emitted: "Pinned SHA $PINNED is not reachable from owletto/main."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/owletto` at line 1, The PR is pinned to an off-main commit
(a317d4e1aa84da77fb566ba594ca5f6bd134a789) which breaks deployment; first merge
the feat/cli-prompt-cleanup branch into owletto/main so that the commit becomes
reachable from main, then update the submodule pointer in this repo to reference
the merged commit on owletto/main (replace the current SHA with the merged
commit SHA) and commit that submodule update so CI/FluxCD reads a main-reachable
SHA.
Member
Author
|
bug_free 62, simplicity 78, slop 0, bugs 3, 0 blockers Typecheck/unit passed. [env] Integration failed in untouched server tests because embedded Postgres init hit shared-memory exhaustion. Explored CLI: ran local runCli init --yes; scaffold succeeded and generated AGENTS.md, exposing the prerequisite/example issues. Suggested fixes
Full verdict JSON{
"bug_free_confidence": 62,
"bugs": 3,
"slop": 0,
"simplicity": 78,
"blockers": [],
"change_type": "feat",
"behavior_change_risk": "medium",
"tests_adequate": false,
"suggested_fixes": [
{
"file": "packages/cli/src/templates/AGENTS.md.tmpl",
"line": 60,
"change": "Replace `dir: \".\"` with `dir: \"./agents/{{PROJECT_NAME}}\"` or omit `dir` so the sample matches the scaffolded agent markdown files."
},
{
"file": "packages/cli/src/templates/AGENTS.md.tmpl",
"line": 109,
"change": "Split the auth profile into `const ghAuth = defineAuthProfile(...)`, set `authProfile: ghAuth`, and change the wire-up example to `authProfiles: [ghAuth]`."
},
{
"file": "packages/cli/src/templates/AGENTS.md.tmpl",
"line": 25,
"change": "Do not require a reachable external Postgres by default; say embedded PostgreSQL with pgvector is used unless `DATABASE_URL` is set to a postgres URL."
},
{
"file": "packages/landing/src/components/LandingPage.tsx",
"line": 40,
"change": "Remove `a reachable Postgres with pgvector` from the prerequisite check or qualify it as only needed when using external `DATABASE_URL`."
}
],
"notes": "Typecheck/unit passed. [env] Integration failed in untouched server tests because embedded Postgres init hit shared-memory exhaustion. Explored CLI: ran local runCli init --yes; scaffold succeeded and generated AGENTS.md, exposing the prerequisite/example issues.",
"categories": {
"src": 23,
"tests": 0,
"docs": 198,
"config": 0,
"deps": 0,
"migrations": 0,
"ci": 0,
"generated": 0
}
}Local review gate — branch protection can require the |
Onboarding flow (idea-first, embedded-PG): - Prompt opens with the idea/interview, not a plumbing preflight; provider key is the only real env ask (Postgres is the embedded default — DATABASE_URL only for external). Node check is silent. - Surface the built-in connector breadth + the custom-connector option at the data-source question; collect all secrets in one batch after the interview. - Agent explains the model (incremental/checkpointed feeds, events → memory → entities, watcher + chat) in plain terms before writing config. - AGENTS.md documents incremental/checkpointed feeds and the "explain it" step. make review fixes (PR #1110, bug_free 62 → addressed): - AGENTS.md agent example omits `dir` so it matches the scaffolded agents/<id>/ markdown (was `dir: "."`, a mismatch). - AGENTS.md connection example uses a named-const auth profile listed in defineConfig({ authProfiles }) instead of an inline defineAuthProfile that never registers. - Postgres-requirement framing already softened to embedded-PG (the other two suggested fixes). Re-verified: AGENTS.md renders clean; landing builds; a config matching the new examples (omitted dir, named-const ghAuth, slack platforms, github feed, watcher) passes `lobu validate`. (Integration suite fail in `make review` was the known macOS shared-memory exhaustion in untouched server tests, not this change.)
A `rest` platform — the documented way to expose an agent over the HTTP Agent
API — has no credentials, so `{ type: "rest" }` (or `config: {}`) made
map-config's `Object.entries(p.config)` throw "Cannot convert undefined or null
to object" with no field/file context. A first-time user following the prompt to
expose their bot as an API hit a dead-end during `lobu validate`.
- map-config: `Object.entries(p.config ?? {})` — null-guard the platform config map.
- define.ts: `Platform.config` is now optional (rest needs none).
- AGENTS.md.tmpl: platforms example shows both a Slack bot and the `rest` HTTP API
(`config: {}`) with the endpoint, so users copy the working form.
Repro (red→green): a config with `{ type: "rest" }` threw during `lobu validate`;
now `slack + rest` and bare `{ type: "rest" }` both validate clean. Found by a
live skill-free cold-start dry-run building a GitHub-triage agent exposed over
both Slack and the HTTP API.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/landing/src/components/LandingPage.tsx`:
- Line 44: The landing copy in the LandingPage component contains an em dash in
the string fragment "and more — or" which violates the no-em-dash rule for
packages/landing; update the user-facing text in the LandingPage component
(search for the phrase "and more — or" in LandingPage.tsx) and replace the em
dash with a comma or period (e.g., "and more, or" or "and more. Or") to comply
with the guideline.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: e076443b-57aa-4a3a-a74c-993f8e3dbb0f
📒 Files selected for processing (4)
packages/cli/src/commands/_lib/apply/map-config.tspackages/cli/src/config/define.tspackages/cli/src/templates/AGENTS.md.tmplpackages/landing/src/components/LandingPage.tsx
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/cli/src/templates/AGENTS.md.tmpl
| - What is the agent for? (one sentence) | ||
| - Who uses it: just me, my team, or each of my customers (multi-tenant)? | ||
| - What should it remember? (we'll model this as 1-3 entity types) | ||
| - Where does its data come from? Lobu has built-in connectors for Slack, Gmail, GitHub, Google Calendar, Outlook, websites, RSS, Reddit, X, LinkedIn, YouTube, Hacker News, Product Hunt, and more — or you can write a custom connector for any other source (an API, a webhook, a CSV). Tell me the source and I'll map it to a built-in connector or plan a custom one. Pick one to start. |
There was a problem hiding this comment.
Replace the em dash in landing copy.
Line 44 uses an em dash in user-facing text (...and more — or...), which violates landing copy rules. Replace it with a comma or period.
As per coding guidelines, "packages/landing/**/*.{ts,tsx,md}: No em dashes in user-facing text in landing copy".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/landing/src/components/LandingPage.tsx` at line 44, The landing copy
in the LandingPage component contains an em dash in the string fragment "and
more — or" which violates the no-em-dash rule for packages/landing; update the
user-facing text in the LandingPage component (search for the phrase "and more —
or" in LandingPage.tsx) and replace the em dash with a comma or period (e.g.,
"and more, or" or "and more. Or") to comply with the guideline.
This was referenced May 28, 2026
buremba
added a commit
that referenced
this pull request
May 28, 2026
…ill; provider-id align; clean-test-pg target (#1113) * fix(cli): scaffolded projects validate/run with zero install (no bun required) Onboarding follow-ups to #1110, addressing user feedback that the lobu CLI should not require users to invoke bun (or any package manager) by hand. - desired-state.ts (loadProjectConfig): alias `@lobu/cli/config` and `@lobu/connector-sdk` to the running CLI's own copies via jiti's `alias` option (resolved with `import.meta.resolve`). A fresh `lobu init` project now validates/runs with no `bun install` step — the user has the CLI, that's enough. Drops the "Run `bun install` ..." error message; a real resolution failure still surfaces verbatim. - skills/lobu/SKILL.md: slim to existing-project + memory; drop First-Time Setup (now owned by the scaffolded AGENTS.md + landing prompt). This is the change that didn't land in the #1110 squash (the slim commit didn't push before merge); reapplying here. - AGENTS.md.tmpl: align the provider example with what `lobu init` generates (`id: "claude"`, not the `anthropic` alias; real model id). Verified: `lobu validate` on a config under $HOME with no node_modules anywhere in the ancestor tree → "lobu.config.ts is valid" (was: "Run `bun install`..." error). tsc + biome green on rebuild. * chore(make): add clean-test-pg to reap orphaned lobu-test-pg clusters (macOS SHMMNI)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
When someone copies the landing "setup prompt" into a coding agent, the agent should interview them and build a Lobu project using only the CLI — no separately-installed skill/plugin. The old prompt told it to
/plugin install lobufirst (a Claude-Code-only command that contradicted the "works in cursor/opencode" claim), and the conventions the skill carried lived only in that skill. This moves the conventions into the scaffolded project itself, so there's nothing to install and nothing to drift.What
AGENTS.md.tmpl— was a one-line@TESTING.mdstub that taught the agent nothing about the config API. Now documents the model, prerequisites, layout, the fulldefine*surface (agent, chat platforms, entities, connections, auth/secrets, watchers/reactions), the bundled connector keys (e.g. Gmail isgoogle_gmail, notgmail), and the conventions. Auto-loaded by the coding agent; ships with the CLI version.LandingPage.tsx— setup prompt is now pure-CLI and interview-first, with an environment preflight, provider selection, avalidategate, and "trigger the source manually." No more/plugin install.README.md.tmpl— fix stale "local PGlite" → embedded PostgreSQL (two lines).lobu.tomlskill reference tolobu.config.ts(pointer bumped; owletto branchfeat/cli-prompt-cleanuppushed first).The
lobuskill is kept (it still serves existing-project lifecycle work and thenpx skills addpath); the landing flow simply no longer depends on it.How it was validated
Two teammate dry-runs drove the prompt design:
validategaps now folded in.defineAgent({ platforms })) and the real connector key (google_gmail) weren't reachable — both now documented.E2E:
AGENTS.md.tmplrenders via the realrenderTemplate— all substitutions, all new sections, no stray{{vars}}.make build-packages+ landing build green; pre-committsc --noEmit+ biome green.platforms,google_gmailconnection + feed, watcher, entity, auth profile) passeslobu validate.Not covered / follow-ups
lobu initto completion needs a TTY; verified the template it writes viarenderTemplatedirectly instead.lobu connectors listdiscovery command — AGENTS.md lists the keys and says "don't guess config; useconnector run <key> --check," but a dedicated catalog (CLI or docs) would close it fully.Summary by CodeRabbit
Documentation
Bug Fixes
Chores