Fix ambient.json field documentation to match platform#92
Fix ambient.json field documentation to match platform#92jwm4 merged 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 |
|
@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
| - **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`.
There was a problem hiding this comment.
These contradictions are in FIELD_REFERENCE.md files which are slated for removal entirely in #95. We'll skip patching them here since the files are going away.
This comment was posted by Claude Code under the supervision of Bill Murdock.
1 participant
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.