docs(skills): add local-development skill for contributor onboarding#539
docs(skills): add local-development skill for contributor onboarding#539jonel-richardson wants to merge 6 commits intoplastic-labs:mainfrom
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdded a new local-development skill document at Changes
Sequence Diagram(s)(omitted — changes are documentation and config only) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
.claude/skills/local-development/SKILL.md (1)
83-121: Consider clarifying the minimal required environment variables.The
.envsection lists many variables but could be clearer about the absolute minimum needed to get started. While the comment on line 82 says "Required variables," the list includes many optional ones (commented alternatives, thinking budgets, etc.).📝 Suggested clarification
Consider adding a subsection structure:
**Minimal required variables for local development:** ```env DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres LLM_OPENAI_COMPATIBLE_BASE_URL=https://openrouter.ai/api/v1 LLM_OPENAI_COMPATIBLE_API_KEY=your-api-key-here DERIVER_MODEL=google/gemini-2.5-flash AUTH_USE_AUTH=falseAdditional configuration (see .env.template for all options):
- Per-subsystem provider/model overrides
- Direct vendor keys (alternatives to custom endpoint)
- Dialectic levels configuration
- Thinking budget tokens
</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.claude/skills/local-development/SKILL.md around lines 83 - 121, Add a clear
"Minimal required variables for local development" subsection under the existing
"Required variables" block that lists only the absolute essentials (reference
the variables DB_CONNECTION_URI, LLM_OPENAI_COMPATIBLE_BASE_URL,
LLM_OPENAI_COMPATIBLE_API_KEY, a default DERIVER_MODEL value, and
AUTH_USE_AUTH=false as an example), then add a one-line pointer to the full
.env.template for all optional settings (per-subsystem provider/model overrides,
direct vendor keys, dialectic levels, thinking budgets) so readers can
distinguish minimal vs. optional configuration.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/settings.local.json:
- Around line 4-7: Update the Bash permission entries in
.claude/settings.local.json so they reference the actual files under
examples/zo/tools/ instead of bare filenames, and remove the non-existent
setup.py entry; specifically replace the "Bash(python -m py_compile
save_memory.py)", "Bash(python -m py_compile query_memory.py)", and "Bash(python
-m py_compile get_context.py)" entries with calls that use the full paths to
examples/zo/tools/save_memory.py, examples/zo/tools/query_memory.py, and
examples/zo/tools/get_context.py respectively, and delete the "Bash(python -m
py_compile setup.py)" line (or add a real setup.py if that file is intended to
exist).In @.claude/skills/local-development/SKILL.md:
- Line 27: Update the uv version requirement in the prerequisites entry that
currently reads "uv: 0.4.9+" to match the actual minimum required version
0.5.0 (as referenced in README.md); locate the "uv" bullet in
.claude/skills/local-development/SKILL.md and change the displayed minimum from
0.4.9+ to 0.5.0 and ensure the installation instructions remain unchanged.- Line 249: Remove the stray instruction "uv add --dev pre-commit" from the
documentation (the line in SKILL.md that currently contains that exact command)
because pre-commit is already declared in pyproject.toml; simply delete that
line and adjust surrounding text/numbering if needed so the instructions flow
correctly.
Nitpick comments:
In @.claude/skills/local-development/SKILL.md:
- Around line 83-121: Add a clear "Minimal required variables for local
development" subsection under the existing "Required variables" block that lists
only the absolute essentials (reference the variables DB_CONNECTION_URI,
LLM_OPENAI_COMPATIBLE_BASE_URL, LLM_OPENAI_COMPATIBLE_API_KEY, a default
DERIVER_MODEL value, and AUTH_USE_AUTH=false as an example), then add a one-line
pointer to the full .env.template for all optional settings (per-subsystem
provider/model overrides, direct vendor keys, dialectic levels, thinking
budgets) so readers can distinguish minimal vs. optional configuration.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `751d64ee-3a87-4f45-b8ca-83bb01b537b7` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 5b6bd59030faca74794360624e98e0534ecd05e0 and 6cd1bebad8f90ad7960a7e6c9606005a827b45f7. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `.claude/settings.local.json` * `.claude/skills/local-development/SKILL.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| "Bash(python -m py_compile setup.py)", | ||
| "Bash(python -m py_compile save_memory.py)", | ||
| "Bash(python -m py_compile query_memory.py)", | ||
| "Bash(python -m py_compile get_context.py)", |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Locate the Python files referenced in permissions
fd -t f "^(setup\.py|save_memory\.py|query_memory\.py|get_context\.py)$"Repository: plastic-labs/honcho
Length of output: 198
🏁 Script executed:
#!/bin/bash
# Find setup.py anywhere in repo
fd -t f "setup\.py$"
# Read the settings.local.json file to see full context
echo "=== Contents of .claude/settings.local.json ==="
cat ".claude/settings.local.json" 2>/dev/null || echo "File not found"Repository: plastic-labs/honcho
Length of output: 394
🏁 Script executed:
#!/bin/bash
# More thorough search for setup.py
echo "=== Searching for setup.py ==="
fd "setup" --type f
echo ""
echo "=== Checking repo root ==="
ls -la setup.py 2>&1 || echo "setup.py not at repo root"
echo ""
echo "=== Git tracking status ==="
git ls-files | grep -E "(setup|get_context|save_memory|query_memory)" | sortRepository: plastic-labs/honcho
Length of output: 478
Update paths and remove non-existent file reference.
The permissions reference bare filenames that will fail from the repository root. Additionally, setup.py does not exist in the repository.
For the three files that exist in examples/zo/tools/, add the full paths:
- "Bash(python -m py_compile setup.py)",
- "Bash(python -m py_compile save_memory.py)",
- "Bash(python -m py_compile query_memory.py)",
- "Bash(python -m py_compile get_context.py)",
+ "Bash(python -m py_compile examples/zo/tools/save_memory.py)",
+ "Bash(python -m py_compile examples/zo/tools/query_memory.py)",
+ "Bash(python -m py_compile examples/zo/tools/get_context.py)",Remove the setup.py entry entirely or create the file if it should exist.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "Bash(python -m py_compile setup.py)", | |
| "Bash(python -m py_compile save_memory.py)", | |
| "Bash(python -m py_compile query_memory.py)", | |
| "Bash(python -m py_compile get_context.py)", | |
| "Bash(python -m py_compile examples/zo/tools/save_memory.py)", | |
| "Bash(python -m py_compile examples/zo/tools/query_memory.py)", | |
| "Bash(python -m py_compile examples/zo/tools/get_context.py)", |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/settings.local.json around lines 4 - 7, Update the Bash permission
entries in .claude/settings.local.json so they reference the actual files under
examples/zo/tools/ instead of bare filenames, and remove the non-existent
setup.py entry; specifically replace the "Bash(python -m py_compile
save_memory.py)", "Bash(python -m py_compile query_memory.py)", and "Bash(python
-m py_compile get_context.py)" entries with calls that use the full paths to
examples/zo/tools/save_memory.py, examples/zo/tools/query_memory.py, and
examples/zo/tools/get_context.py respectively, and delete the "Bash(python -m
py_compile setup.py)" line (or add a real setup.py if that file is intended to
exist).
|
Thanks for the thorough review! settings.local.json removed from tracking and added to .gitignore All three addressed in the latest push. |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/local-development/SKILL.md:
- Line 4: The allowed-tools entry in SKILL.md is too restrictive and prevents
contributors from running required CLI steps (git, curl, and general
troubleshooting shell commands); update the allowed-tools value on the line
containing "allowed-tools:" to include the necessary tools (e.g., add
Bash(git:*), Bash(curl:*), and a more general Bash(sh:* or bash:*) or specific
troubleshooting commands) so the documented workflow can run clone/pull, health
checks, and debugging commands; keep the existing uv/docker/cp/alembic entries
and only expand the list to include these additional Bash tool tokens.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 34f92db3-4cbe-4fe6-ba8c-dffa03687f45
📒 Files selected for processing (2)
.claude/skills/local-development/SKILL.md.gitignore
✅ Files skipped from review due to trivial changes (1)
- .gitignore
|
Good catch — updated allowed-tools to include git, curl, lsof, kill, netstat, and taskkill so the full documented workflow can execute. |
|
All CodeRabbit feedback addressed. Ready for maintainer review whenever you get a chance! |
|
Thanks for opening this! In the future, keep the same work on the same PR. Just update your old one instead of opening a new PR. By keeping the same PR it helps keep reviewer history consistent and orderly. I asked for you to "confirm the skill actually works by running through it with your AI of choice and sharing the output. " #509 (comment) This PR is blocked waiting for this. |
jonel-richardson
force-pushed
the
docs/local-development-skill-v2
branch
from
e7ab13a to
583c532
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
.claude/skills/local-development/SKILL.md (1)
246-253: Use a shell-agnostic pre-commit install command.The multiline backslash continuation is bash-specific. A single-line command is safer for copy/paste across macOS/Linux/Windows shells.
Suggested doc fix
```bash -uv run pre-commit install \ - --hook-type pre-commit \ - --hook-type commit-msg \ - --hook-type pre-push +uv run pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.claude/skills/local-development/SKILL.md around lines 246 - 253, The
documented install command for pre-commit uses a bash-specific backslash line
continuation; replace the multiline form with a single-line invocation of the
same command so it’s shell-agnostic: update the example that calls "uv run
pre-commit install" and the repeated "--hook-type" flags to be on one line
(i.e., "uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
--hook-type pre-push") to ensure it copies and runs correctly across
macOS/Linux/Windows shells.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/local-development/SKILL.md:
- Around line 24-30: The Prerequisites section is missing Bun, which is required
by the later "bun run tsc --noEmit" step; update the "Prerequisites" list to add
Bun (minimum version) and a brief install line so contributors know to install
it before running the TypeScript SDK type-check step. Reference the
"Prerequisites" heading and the "bun run tsc --noEmit" command when adding the
Bun entry and include a recommended install command or link and a minimum
supported version.- Line 4: The allowed-tools block named "allowed-tools" currently omits sudo and
xcode-select while the SKILL.md code blocks run those commands; either add the
missing executables to the allowlist (e.g., include sudo and xcode-select
entries) or annotate the relevant code blocks as manual/non-executable so the
agent won't attempt to run them; update the "allowed-tools" block and the
corresponding code block headings in SKILL.md (search for the code fences that
show sudo and xcode-select) to keep the documentation and execution policy
consistent.
Nitpick comments:
In @.claude/skills/local-development/SKILL.md:
- Around line 246-253: The documented install command for pre-commit uses a
bash-specific backslash line continuation; replace the multiline form with a
single-line invocation of the same command so it’s shell-agnostic: update the
example that calls "uv run pre-commit install" and the repeated "--hook-type"
flags to be on one line (i.e., "uv run pre-commit install --hook-type pre-commit
--hook-type commit-msg --hook-type pre-push") to ensure it copies and runs
correctly across macOS/Linux/Windows shells.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `f0743cc7-8076-46ad-bd2c-b9c43f1cdfac` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between e7ab13ac1c3d5bd8673b943844789c9b323be287 and 583c53203e0e6f107faf50b65837e72dc248a21d. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `.claude/skills/local-development/SKILL.md` * `.gitignore` </details> <details> <summary>✅ Files skipped from review due to trivial changes (1)</summary> * .gitignore </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
|
Testing output: skill verified with Claude Code in WSL2 Ran through the skill end-to-end on a local machine using Claude Code as the AI. Environment: WSL2 (Ubuntu) on Windows, Docker Desktop with WSL2 integration, Python 3.11, uv 0.11.6. Setup steps completed:
Trigger phrase results (Claude Code):
Trigger | Result
-- | --
"Help me set up Honcho locally" | ✅ Detected running environment, listed next steps, warned about dialectic level config
"How do I run the deriver?" | ✅ Correct command + Redis/DB/API key requirements
"My database connection isn't working" | ✅ 8-step troubleshooting sequence including WSL2 Docker check
"How do I run the tests?" | ✅ pytest commands + TypeScript SDK note about bun test
Gaps found and fixed in this push:
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/local-development/SKILL.md:
- Around line 151-152: Update every occurrence of the docker compose command and
references that use the service name "database" to use the actual service name
"postgres" instead; search for the exact string "docker compose up -d database
redis" and other mentions of the service token "database" (notably the
occurrences indicated at the review: lines around 154, 397, 408, 537-538,
544-545, 559) and replace them with "docker compose up -d postgres redis" (and
update any explanatory text that names the service to say "postgres" instead of
"database") so the docs match the compose file service names.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 1d56e011-f03b-4cd9-975b-64a27c587073
📒 Files selected for processing (1)
.claude/skills/local-development/SKILL.md
|
Thanks for the contribution @jonel-richardson! We're closing this out. The skill overlaps heavily with our existing CLAUDE.md and we'd rather keep one source of truth than maintain two that drift apart. We've closed #407 as well. |
2 participants
docs(skills): add local-development skill for contributor onboarding
Closes #407
What this adds
A new Claude Code skill at
.claude/skills/local-development/SKILL.mdthat guides contributors through setting up and running Honcho locally. The skill activates when contributors ask things like "Help me set up Honcho locally", "How do I run the deriver?", "My database connection isn't working", or "How do I run the tests?"What the skill covers
.envconfiguration with correct credentials and all required vars/healthendpoint verificationTesting
Tested with Claude Code against the actual repo files. All four trigger phrases from the issue verified:
19/19 env vars in the
.envexample block verified line-by-line against.env.template. All commands verified againstCLAUDE.md,docker-compose.yml.example,pyproject.toml, andsrc/main.py.Notes
This PR supersedes my earlier draft (
docs/local-development-skill) and is rebased on main after #510 merged. The env config block reflects the new OpenAI-compatible provider defaults introduced in #510.@ajspig
Summary by CodeRabbit
Documentation
Chores