You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by "justinmclean (via GitHub)" <gi...@apache.org> on 2026/07/28 23:56:04 UTC
[I] Fix the two broken instructions in the add-a-harness recipe [magpie]
justinmclean opened a new issue, #997:
URL: https://github.com/apache/magpie/issues/997
## Summary
`docs/adapters/add-a-harness.md` is the recipe for wiring a new agent runtime into Magpie. Two
of its copy-and-run instructions do not match the repository: the agent-guard file layout in
Step 2, and the verification command in Step 1. Correct both.
## Background
The doc exists, in its own words, "so the extension point is a recipe, not tribal knowledge", so
a wrong path or command costs exactly the reader it was written for.
**Step 2 shows a layout that does not exist.** It draws the agent-guard package as
`tools/agent-guard/agent_guard/` with an `adapters/` directory holding one file per harness
(`claude.py`, `opencode.py`, `<your-runtime>.py`). The real package root is
`tools/agent-guard/src/agent_guard/`, and there is no `adapters/` directory at all. Each
harness is a function in `__init__.py` — `opencode_main()`, `kiro_main()` — selected by flag
routing (`--opencode`, `--kiro`) near the bottom of the same file. A contributor who follows
the recipe creates a file that nothing imports.
The Kiro integration (PR #768) says in its commit message that it followed this recipe, and it
did **not** do what Step 2 describes — it added `kiro_main()` plus a `--kiro` branch. So the
recipe's first real user had to work out the true shape anyway.
**Step 1's verification command fails.** It gives
`uv run --project tools/symlink-lint python3 -m symlink_lint`. Running a package with
`python3 -m` needs a `__main__.py`, and `tools/symlink-lint/src/symlink_lint/` contains only
`__init__.py`, so the command exits with "No module named `symlink_lint.__main__`". The tool
ships a console script instead. This is the command the reader runs right after hand-creating
symlinks, so the spurious failure looks like their symlinks are broken.
## Where to look
- `docs/adapters/add-a-harness.md` — Step 1's verification command and Step 2's file-tree block.
- `tools/agent-guard/src/agent_guard/__init__.py` — search for `def opencode_main`,
`def kiro_main`, and the flag routing near the end of the file, to describe the real shape.
- `tools/symlink-lint/pyproject.toml` — the `[project.scripts]` entry gives the real command
name.
- Other docs in the repo that invoke per-tool commands show the `uv run` form in use.
## Acceptance criteria
- [ ] Step 2's file tree matches the real package: the `src/` layer is present and no
`adapters/` directory is shown.
- [ ] Step 2 describes adding a harness the way the code actually does it (a `*_main()`
function plus a flag branch), rather than a new file per harness.
- [ ] Step 1's verification command runs successfully in a clean checkout.
- [ ] `prek run --all-files` passes.
## Estimated effort
~1 hour for someone new to the codebase. No code changes; the work is reading
`agent_guard/__init__.py` closely enough to describe it correctly.
## Getting started
[[How to contribute](https://github.com/apache/airflow-steward/blob/main/CONTRIBUTING.md#your-first-contribution)](https://github.com/apache/airflow-steward/blob/main/CONTRIBUTING.md#your-first-contribution)
This issue was drafted with the help of an AI-assisted tool and reviewed by a Magpie maintainer before posting. If anything here is unclear or looks wrong, say so on the issue: a real person is reading.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Fix the two broken instructions in the add-a-harness recipe [magpie]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk closed issue #997: Fix the two broken instructions in the add-a-harness recipe
URL: https://github.com/apache/magpie/issues/997
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org