docs(agent): add config authoring workflow guide#305
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new maintainer/agent-facing guide for authoring, validating, and shipping curated html2rss YAML configs in this repository.
Changes:
- Introduces
AGENTS.mddescribing config scoping principles, surface/selector strategy, and quality gates. - Documents a validation/debug loop (validate → feed → selector tightening) plus fetch verification steps (Faraday vs Browserless).
- Defines reporting expectations for config work (accepted/downgraded/dropped, commands run, residual risks).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Do not add complexity to recover weak optional fields. | ||
|
|
||
| ## Chrome MCP | ||
|
|
There was a problem hiding this comment.
"Chrome MCP" is introduced as a required inspection tool, but the acronym/tooling isn’t defined anywhere else in the repo. Consider adding a brief definition (what it is, how to access/run it, and/or a link) so new contributors/agents can follow the workflow without prior context.
| Chrome MCP is the Chrome-based page inspection tool exposed to agents for this project. It lets you open a URL in a real browser, inspect the fully rendered DOM, and capture accessibility snapshots to refine selectors. In an agent workspace, invoke the **Chrome MCP** tool and provide the target URL; in a local browser session, you can mirror the same workflow using Chrome plus DevTools. |
| Assume the `html2rss` CLI is available on `PATH` when working against the sibling core repo. | ||
|
|
||
| - Use `html2rss ...` in examples and one-off validation commands. | ||
| - If the CLI is not installed globally in the current environment, run the equivalent command from the sibling `html2rss/` checkout, typically `bundle exec exe/html2rss ...`. | ||
| - In this repo, keep using `make ...` and `bundle exec rspec ...` because those are the implemented entrypoints. |
There was a problem hiding this comment.
This guide assumes a sibling checkout at ../html2rss and a globally available html2rss CLI. Since this repo’s README documents validating/running configs via Bundler (e.g., bundle exec html2rss validate ...), consider adding the bundle exec html2rss validate/feed ... equivalents here (or explicitly stating when the sibling core-repo workflow is required/preferred) to avoid conflicting guidance.
| Assume the `html2rss` CLI is available on `PATH` when working against the sibling core repo. | |
| - Use `html2rss ...` in examples and one-off validation commands. | |
| - If the CLI is not installed globally in the current environment, run the equivalent command from the sibling `html2rss/` checkout, typically `bundle exec exe/html2rss ...`. | |
| - In this repo, keep using `make ...` and `bundle exec rspec ...` because those are the implemented entrypoints. | |
| Assume the `html2rss` CLI is available on `PATH` when working against the sibling core repo, or available via Bundler in this repo. | |
| - When a global CLI is installed, use `html2rss ...` in examples and one-off validation commands. | |
| - When running via Bundler (the default in this repo), use the README-style equivalents, for example: | |
| - `bundle exec html2rss validate path/to/config.yml` | |
| - `bundle exec html2rss feed path/to/config.yml` | |
| - If you are working directly in a sibling `html2rss/` core checkout without a global install, run the CLI via that repo, typically `bundle exec exe/html2rss ...`. | |
| - In this configs repo, keep using `make ...` and `bundle exec rspec ...` for repo-level tasks because those are the implemented entrypoints. |
Summary