feat(claude-md, autodetect): trim CLAUDE.md template + widen v4l2 filter#93
Open
craigm26 wants to merge 1 commit into
Open
feat(claude-md, autodetect): trim CLAUDE.md template + widen v4l2 filter#93craigm26 wants to merge 1 commit into
craigm26 wants to merge 1 commit into
Conversation
Two harness-engineering hygiene fixes that came out of applying OpenAI's progressive-disclosure lens (https://openai.com/index/harness-engineering/) to the robot-md doc surface. CLAUDE.md template (cli/src/robot_md/claude_md.py) -------------------------------------------------- Collapse the standalone "Tooling available in this workspace" code block and "MCP resources" bullet list into the intent → resource routing table itself. Every line in the file now either routes an intent or states an always-applicable fact. New routing rows added for the narrow MCP slices that ship in robot-md-mcp PR #13: /drivers, /physics, /kinematics, /cameras, /poses, /vision, plus /frontmatter labeled "fallback when no narrow slice fits (escape hatch)". New routing row added for the spec/design-rationale intent ("Why is the manifest shaped this way?") pointing at this repo's spec/ + docs/design/ as one-hop external references. /context flagged explicitly as on-demand only ("don't auto-fetch at session start"). CLAUDE.md is now the unambiguous eager entry, /context is for operator-triggered "brief me" use. Net effect on a real robot's CLAUDE.md: 75 → 65 lines despite gaining 8 new routing rows, because the duplicated Tooling/MCP sections went away. All 17 existing tests in tests/test_claude_md.py pass unchanged, including the contract that all 6 python-MCP tool names (validate/render/estop/estop_clear/execute_capability/execute_task) appear somewhere in the output. V4L2 autodetect filter (cli/src/robot_md/autodetect.py) ------------------------------------------------------- V4L2_KNOWN_NON_CAMERA_PREFIXES widened from a single-entry tuple ("pispbe-") to a richer set covering the Pi 5 ISP/codec node names that were leaking through. The trailing dash forced the old filter to miss bare-name nodes (e.g. v4l2-ctl on some Pi configs reports "pispbe" without the "-input" suffix), and there was no coverage at all for rpi-hevc-dec / rpi-hevc-enc / rpi-mfc / bcm2835-codec / bcm2835-isp / pisp-fe. Concrete impact on a Pi 5 + so-arm101 manifest: 17 stale "cameras" (16 pispbe-video* + 1 rpi-hevc-dec-video19), all with empty extrinsic, no longer auto-add to the manifest. Existing manifests authored under the old filter still carry these entries — autofix tracked in #91. Each prefix entry is documented with provenance. The dash was removed from "pispbe" so str.startswith matches bare and suffixed variants alike. Three new regression tests: test_bare_pispbe_model_is_filtered — covers the v4l2-ctl bare-name case test_rpi_hevc_decoder_is_filtered — covers the HEVC decoder leak test_pisp_fe_frontend_is_filtered — covers Pi 5 ISP front-end nodes Existing test_pispbe_video_nodes_are_filtered preserves backward compatibility; only its inner assertion loosened from startswith("pispbe-") to startswith("pispbe"). Test plan --------- pytest cli/tests/test_claude_md.py → 17/17 pytest cli/tests/test_autodetect_v4l2_filter.py → 4/4 pytest cli/tests/test_autodetect*.py → 30/30 pytest cli/tests/test_parser.py test_render.py → 15/15 pytest cli/tests/test_validate.py test_schema.py → 15/15 pytest cli/tests/test_context.py → 6/6 Full suite (excluding hardware/integration/manual): 1224/1226. The 2 failures are pre-existing SSL timeouts in test_register.py, unrelated to this PR (confirmed against main). Follow-ups tracked in #91 (robot-md doctor --autofix-cameras to backfill the filter to existing manifests) and #92 (robot-md docs CLI verb for spec/design breadcrumb beyond the routing-table mention). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR tightens the agent-facing CLAUDE.md template (progressive-disclosure routing table) and improves camera autodetection hygiene by filtering additional Raspberry Pi V4L2 non-camera nodes.
Changes:
- Trimmed/restructured the generated CLAUDE.md template into a compact intent → resource/tool routing table (including new narrow “slice” routes).
- Broadened the V4L2 non-camera prefix filter to exclude additional Pi ISP/codec nodes.
- Added regression tests covering the widened V4L2 filter behavior (bare
pispbe,rpi-hevc-dec,pisp-fe-*).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| cli/tests/test_autodetect_v4l2_filter.py | Adds regression tests ensuring non-camera Pi V4L2 nodes are excluded from autodetected cameras. |
| cli/src/robot_md/claude_md.py | Rewrites the embedded CLAUDE.md template into a smaller intent-routing table and adds new routing rows. |
| cli/src/robot_md/autodetect.py | Expands V4L2_KNOWN_NON_CAMERA_PREFIXES and clarifies matching semantics. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+40
to
+45
| | "What drivers? What port? What baud?" | resource `robot-md://{{ROBOT_NAME}}/drivers` | | ||
| | "What's the workspace? IK provider? DoF?" | resource `robot-md://{{ROBOT_NAME}}/physics` | | ||
| | "Servo_id of <joint>?" / joint limits / DH params | resource `robot-md://{{ROBOT_NAME}}/kinematics` | | ||
| | "Camera extrinsic / intrinsic?" / "Is the OAK-D calibrated?" | resource `robot-md://{{ROBOT_NAME}}/cameras` | | ||
| | "What joints does the `ready` pose set?" | resource `robot-md://{{ROBOT_NAME}}/poses` | | ||
| | "What HSV range detects `red_lego`?" / declared visual targets | resource `robot-md://{{ROBOT_NAME}}/vision` | |
Comment on lines
+225
to
+230
| "pisp-fe", # Raspberry Pi ISP front-end nodes (Pi 5). | ||
| "rpi-hevc-dec", # Pi HEVC hardware decoder (not a camera). | ||
| "rpi-hevc-enc", # Pi HEVC hardware encoder (not a camera). | ||
| "rpi-mfc", # Pi multi-format codec (not a camera). | ||
| "bcm2835-codec", # BCM2835/2837/2711 codec (not a camera). | ||
| "bcm2835-isp", # BCM2835/2837/2711 ISP nodes. |
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
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.
Summary
Two harness-engineering hygiene fixes from applying OpenAI's progressive-disclosure lens to the robot-md doc surface.
/drivers,/physics,/kinematics,/cameras,/poses,/vision) shipping in robot-md-mcp#13, plus a row routing the "why is this shaped this way?" intent to this repo'sspec/+docs/design/./contextmarked on-demand only. Net effect on a real robot: 75 → 65 lines despite gaining 8 routing rows.V4L2_KNOWN_NON_CAMERA_PREFIXESexpanded from a single"pispbe-"entry (which missed bare-name nodes and didn't cover the HEVC decoder / ISP front-end / BCM codec nodes) to a documented set covering Pi 5 ISP back-end + front-end, HEVC dec/enc, MFC, and BCM2835 codec/ISP. Each entry has provenance.Real-world impact
Concrete failure mode caught: an operator's Pi 5 + so-arm101 manifest was 500 lines with 17 stale "cameras" (16
pispbe-video*+ 1rpi-hevc-dec-video19), all with empty extrinsic. The old filter only matched"pispbe-"(with dash) — barepispbeslipped through, as didrpi-hevc-dec. Future manifests skip these; backfill for existing manifests tracked in #91.Test plan
pytest cli/tests/test_claude_md.py→ 17/17 passing (no test changes; contracts preserved)pytest cli/tests/test_autodetect_v4l2_filter.py→ 4/4 passing (3 new regression tests for bare-pispbe, rpi-hevc-dec, pisp-fe)pytest cli/tests/test_autodetect*.py→ 30/30test_register.pyconfirmed unrelated against mainrobot-md claude-mdagainst a real ROBOT.md produces the new layout;robot-md validateconfirms the trimmed manifest is schema-conformanttest_template_lists_all_six_mcp_toolsandtest_template_motion_row_points_at_execute_capabilitystill pass — all six python-MCP tool names (validate/render/estop/estop_clear/execute_capability/execute_task) still appear in the rendered outputFollow-ups (not in this PR)
robot-md doctor --autofix-cameras: backfill the v4l2 filter to existing manifestsrobot-md docsCLI verb: turn the spec breadcrumb into a real surface🤖 Generated with Claude Code