Fix ambient.json field documentation to match platform#92
Open
jwm4 wants to merge 2 commits intoambient-code:mainfrom
Open
Fix ambient.json field documentation to match platform#92jwm4 wants to merge 2 commits intoambient-code:mainfrom
jwm4 wants to merge 2 commits intoambient-code:mainfrom
Conversation
Audited all ambient.json fields against the platform runner code (ambient-runner) and corrected documentation that didn't match: - startupPrompt: Document that it's sent TO the agent as a hidden user message, not displayed to the user. Update all examples to use directive style instead of canned greetings. - greeting: Remove — field is not implemented in the platform. - enabled: Remove — not read from ambient.json by the runner. - rubric: Remove — only partially implemented, doesn't fit long-term strategy of keeping ambient.json lightweight and portable. - results: Clarify it's informational only, not read by the platform at runtime. - Remove fictional optional fields (version, author, tags, icon) from FIELD_REFERENCE docs and workflow-creator skill. - Fix stale code paths (claude-code-runner → ambient-runner). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
WalkthroughThis pull request redefines Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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 |
Contributor
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
workflows/cve-fixer/FIELD_REFERENCE.md (1)
63-71:⚠️ Potential issue | 🟡 MinorIncomplete cleanup: orphaned JSON content.
Lines 67-71 contain JSON fragments that don't relate to the new content at lines 65-66 about updating
systemPromptand command files. This appears to be leftover environment-based configuration content that should have been removed per the PR's objective to simplify customization instructions.🧹 Suggested cleanup
Remove lines 67-71 (the orphaned JSON content) so the section reads:
### Changing artifact location To use a different base directory, update: 1. `systemPrompt` OUTPUT LOCATIONS section 2. All command files in `.claude/commands/` to reference new paths in their ## Output sections - "ARTIFACTS_DIR": "artifacts/cve-fixer", - "SCAN_TOOLS": "snyk,npm-audit,trivy", - "LOG_LEVEL": "info" -} -```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/cve-fixer/FIELD_REFERENCE.md` around lines 63 - 71, Remove the orphaned JSON fragment containing the keys "ARTIFACTS_DIR", "SCAN_TOOLS", and "LOG_LEVEL" from the FIELD_REFERENCE.md section so the guidance about updating the systemPrompt OUTPUT LOCATIONS and the ## Output sections of command files in .claude/commands/ stands alone; delete the stray lines that look like environment/config JSON (the leftover JSON fragment) so the section reads cleanly with only the instructional text.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@workflows/cve-fixer/FIELD_REFERENCE.md`:
- Around line 63-71: Remove the orphaned JSON fragment containing the keys
"ARTIFACTS_DIR", "SCAN_TOOLS", and "LOG_LEVEL" from the FIELD_REFERENCE.md
section so the guidance about updating the systemPrompt OUTPUT LOCATIONS and the
## Output sections of command files in .claude/commands/ stands alone; delete
the stray lines that look like environment/config JSON (the leftover JSON
fragment) so the section reads cleanly with only the instructional text.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 69ff71eb-b572-4c67-9dcb-e7f7e4d6019f
📒 Files selected for processing (7)
.claude/skills/workflow-creator/SKILL.mdAGENTS.mdAMBIENT_JSON_SCHEMA.mdWORKFLOW_DEVELOPMENT_GUIDE.mdinternal-workflows/template-workflow/.ambient/ambient.jsonworkflows/cve-fixer/FIELD_REFERENCE.mdworkflows/triage/FIELD_REFERENCE.md
Address CodeRabbit review feedback: leftover JSON lines from a removed "environment configuration" example were dangling after the artifact path customization instructions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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 `@workflows/cve-fixer/FIELD_REFERENCE.md`:
- Around line 44-45: The doc now declares the `results` field is
informational-only but later sections still treat `results` as operational and
still require a `version` field; update FIELD_REFERENCE.md to remove those
contradictions by changing all occurrences that describe `results` as an
operational/required field to reflect it is informational-only (search for
mentions of `results` in the sections that describe outputs/behavior) and remove
or mark as obsolete the guidance that requires a `version` field (search for
`version` usages and related requirement language) so the document consistently
describes `results` as informational and no longer mandates `version`.
🪄 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: ASSERTIVE
Plan: Pro
Run ID: 28e87e73-0c91-4693-b7e6-3325c122a43b
📒 Files selected for processing (1)
workflows/cve-fixer/FIELD_REFERENCE.md
Comment on lines
+44
to
+45
| - **Purpose:** Documents which artifact types the workflow produces and where | ||
| - **Note:** This field is informational only -- the platform does not read it at runtime |
There was a problem hiding this comment.
Resolve remaining contradictions after making results informational-only.
These updates conflict with later sections that still make results operational (Line 114, Line 115, Line 125, Line 137) and still require a version field (Line 127), which reintroduces removed/obsolete guidance.
Suggested doc cleanup
## Validation Checklist
@@
-- [ ] Output paths in `results` match those referenced in `systemPrompt`
-- [ ] Output paths in `results` match those in command files' ## Output sections
+- [ ] Output locations in `systemPrompt` match command files' ## Output sections
## Configuration Best Practices
@@
-3. **Maintain consistency:** Ensure artifact paths are identical across ambient.json, systemPrompt, and command files.
+3. **Maintain consistency:** Ensure output locations are consistent between `systemPrompt` and command files.
@@
-4. **Version your workflow:** Update version field when making significant changes to track evolution.
+4. **Track workflow changes:** Document significant configuration changes in this FIELD_REFERENCE and related guides.
## Troubleshooting Configuration Issues
@@
-**Solution:** Verify paths in `results` match actual output locations. Use glob patterns correctly (`**/*.md` for recursive).
+**Solution:** Verify output locations defined in `systemPrompt` and command files are accurate and use correct glob patterns where applicable (`**/*.md` for recursive).As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
Also applies to: 63-67
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/cve-fixer/FIELD_REFERENCE.md` around lines 44 - 45, The doc now
declares the `results` field is informational-only but later sections still
treat `results` as operational and still require a `version` field; update
FIELD_REFERENCE.md to remove those contradictions by changing all occurrences
that describe `results` as an operational/required field to reflect it is
informational-only (search for mentions of `results` in the sections that
describe outputs/behavior) and remove or mark as obsolete the guidance that
requires a `version` field (search for `version` usages and related requirement
language) so the document consistently describes `results` as informational and
no longer mandates `version`.
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
1 participant
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
ambient.jsonfields against the actual platform runner code (ambient-runner) and corrected documentation that didn't match realitystartupPrompt: Documented that it's sent TO the agent as a hidden user message (not displayed to the user). Updated all examples to directive style.greeting,enabled,rubric: Removed — these fields are either not implemented or only partially implemented in the platform and don't fit the long-term strategy of keepingambient.jsonlightweightresults: Clarified it's informational only — not read by the platform at runtimeversion,author,tags,icon) from FIELD_REFERENCE docs and workflow-creator skillclaude-code-runner→ambient-runner)Files changed
AMBIENT_JSON_SCHEMA.md— main schema reference (largest changes)AGENTS.md— field table, examples, modification guidanceWORKFLOW_DEVELOPMENT_GUIDE.md— field table, example, checklist.claude/skills/workflow-creator/SKILL.md— template generation, field reference sectionworkflows/triage/FIELD_REFERENCE.md— field descriptionsworkflows/cve-fixer/FIELD_REFERENCE.md— field descriptions, removed fictional fieldsinternal-workflows/template-workflow/.ambient/ambient.json— rewrite startupPrompt as directiveTest plan
AMBIENT_JSON_SCHEMA.mdaccurately reflects platform coderesultsor removed fields🤖 Generated with Claude Code
This comment comes from Claude Code under the supervision of Bill Murdock.