morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #4718] [Feature] Supported extension point for companion skills without modifying REA's SKILL.md #2465

New issue

Open

opened 2026-10-17 21:05:09 +00:00 by bsakaguchi · 4 comments

bsakaguchi commented

2026-10-17 21:05:09 +00:00

Owner

Originally created by @ShadowSwaps on GitHub (Oct 17, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/4718

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This request does not include credentials, private samples, or sensitive target data.

Area

Setup, packaging, or upgrade

Current limitation

I'm maintaining REA Reconstruction Companion. Its optional integration adds a small rule to REA's SKILL.md so the agent loads the companion alongside REA for relevant tasks.

@Rinkia reported a problem with this in issue #37: adding the rule makes REA's skill fail the canonical-file check, and following doctor's advice to run setup removes the rule again. The companion stays installed, but the automatic co-use is gone.

Desired outcome and success criteria

I agree with the reporter's suggestion of an upstream extension point. Would you be open to a supported way for companion skills to register this kind of integration without editing REA's managed skill file? A user-enabled sidecar or include seems like one option. Ideally, the canonical-file checks would stay intact, and setup/update would preserve explicitly enabled integrations or clearly report when they're disabled.

Is that a direction you'd support, or is there an existing mechanism I should use instead?

Expected interaction with targets

Read existing files or captured data; write or change files/configuration.

Target and scope details

Local skill files and client configuration. The exact include format and handling of trusted extensions still need design; this request does not include an implementation.

Verification available so far

I can suggest a sample or manual check.

Verification details

The reported sequence, with the companion installer run from its package directory, is:

rea setup --client claude_code --yes
node install.mjs --client claude-code --integration on
rea doctor
rea setup --client claude_code --yes
node install.mjs --client claude-code --integration on --check

Doctor reports skill identity drift after the integration is added. The second setup backs up the modified skill and restores the bundled copy. The final check then reports needs-install-or-repair because the rule is missing. The original report includes the exact versions and output. I've checked the relevant Doctor.ts and SetupSkill.ts code, which matches that behavior; I haven't independently rerun the full REA CLI sequence.

Alternatives considered

I'm addressing the immediate confusion in PR #38 with documentation, recovery steps and a local warning. That doesn't resolve the conflict, though. Automatically putting the rule back would just bring back the doctor warning.

Originally created by @ShadowSwaps on GitHub (Oct 17, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/4718 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This request does not include credentials, private samples, or sensitive target data. ### Area Setup, packaging, or upgrade ### Current limitation I'm maintaining REA Reconstruction Companion. Its optional integration adds a small rule to REA's SKILL.md so the agent loads the companion alongside REA for relevant tasks. @Rinkia reported a problem with this in [issue #37](https://github.com/ShadowSwaps/REA-Reconstruction-Companion/issues/37): adding the rule makes REA's skill fail the canonical-file check, and following doctor's advice to run setup removes the rule again. The companion stays installed, but the automatic co-use is gone. ### Desired outcome and success criteria I agree with the reporter's suggestion of an upstream extension point. Would you be open to a supported way for companion skills to register this kind of integration without editing REA's managed skill file? A user-enabled sidecar or include seems like one option. Ideally, the canonical-file checks would stay intact, and setup/update would preserve explicitly enabled integrations or clearly report when they're disabled. Is that a direction you'd support, or is there an existing mechanism I should use instead? ### Expected interaction with targets Read existing files or captured data; write or change files/configuration. ### Target and scope details Local skill files and client configuration. The exact include format and handling of trusted extensions still need design; this request does not include an implementation. ### Verification available so far I can suggest a sample or manual check. ### Verification details The reported sequence, with the companion installer run from its package directory, is: ```sh rea setup --client claude_code --yes node install.mjs --client claude-code --integration on rea doctor rea setup --client claude_code --yes node install.mjs --client claude-code --integration on --check ``` Doctor reports skill identity drift after the integration is added. The second setup backs up the modified skill and restores the bundled copy. The final check then reports `needs-install-or-repair` because the rule is missing. The original report includes the exact versions and output. I've checked the relevant Doctor.ts and SetupSkill.ts code, which matches that behavior; I haven't independently rerun the full REA CLI sequence. ### Alternatives considered I'm addressing the immediate confusion in [PR #38](https://github.com/ShadowSwaps/REA-Reconstruction-Companion/pull/38) with documentation, recovery steps and a local warning. That doesn't resolve the conflict, though. Automatically putting the rule back would just bring back the doctor warning.

bsakaguchi commented

2026-10-17 21:05:11 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 17, 2026):

I'd support this direction. Patching a managed SKILL.md will always fight the canonical-file check, so a sidecar include that setup reads but never writes would keep doctor's identity checks intact while letting companions register cleanly. Two thoughts: (1) make the include source explicit — e.g. only files under a dedicated companion directory or an allowlist — otherwise the canonical-file check just moves to an unchecked include path; (2) when setup restores the bundled copy, it should clearly report which enabled integrations were dropped (the final --check reporting needs-install-or-repair is exactly that silent case), so users can re-run the companion installer without confusion.

@XinwangTao commented on GitHub (Oct 17, 2026): I'd support this direction. Patching a managed SKILL.md will always fight the canonical-file check, so a sidecar include that setup reads but never writes would keep doctor's identity checks intact while letting companions register cleanly. Two thoughts: (1) make the include source explicit — e.g. only files under a dedicated companion directory or an allowlist — otherwise the canonical-file check just moves to an unchecked include path; (2) when setup restores the bundled copy, it should clearly report which enabled integrations were dropped (the final `--check` reporting needs-install-or-repair is exactly that silent case), so users can re-run the companion installer without confusion.

bsakaguchi commented

2026-10-17 21:05:11 +00:00

Author

Owner

@ShadowSwaps commented on GitHub (Oct 17, 2026):

Thanks, @XinwangTao — that makes sense. I'd prefer a supported sidecar over continuing to patch the managed skill file.

I agree that the trust boundary needs to be explicit. A dedicated per-client companion directory or explicit allowlist, with user-enabled registration and checks that reject paths escaping the configured location, would be a useful starting point. Discovery alone should not enable an integration or execute its installer. I'd also want doctor to report companion status separately, so a changed or missing companion isn't confused with drift in REA's canonical files.

For the second point, reporting which integrations were preserved, disabled or removed during setup/update would help a lot. Re-running the current companion installer restores the rule, but also recreates the canonical-file mismatch; it is only a workaround until there is a supported extension mechanism.

On my side, the companion now documents that conflict and has an optional local warning for a missing/changed rule, plus scoped recovery that preserves newer REA content. That warning depends on the companion/helper actually being invoked and able to inspect its local state, so it cannot reliably catch the case where routing itself has disappeared. It doesn't fix REA's canonical check.

One design detail I'd like to clarify: how would the agent discover/load the enabled sidecar while REA's managed SKILL.md stays unchanged? Would an upstream-owned loader/reference in the canonical skill, or a host-supported registration mechanism, be the intended route? I'd like to keep the companion's side portable across clients and adapt to the supported contract once that's settled.

@ShadowSwaps commented on GitHub (Oct 17, 2026): Thanks, @XinwangTao — that makes sense. I'd prefer a supported sidecar over continuing to patch the managed skill file. I agree that the trust boundary needs to be explicit. A dedicated per-client companion directory or explicit allowlist, with user-enabled registration and checks that reject paths escaping the configured location, would be a useful starting point. Discovery alone should not enable an integration or execute its installer. I'd also want doctor to report companion status separately, so a changed or missing companion isn't confused with drift in REA's canonical files. For the second point, reporting which integrations were preserved, disabled or removed during setup/update would help a lot. Re-running the current companion installer restores the rule, but also recreates the canonical-file mismatch; it is only a workaround until there is a supported extension mechanism. On my side, the companion now documents that conflict and has an optional local warning for a missing/changed rule, plus scoped recovery that preserves newer REA content. That warning depends on the companion/helper actually being invoked and able to inspect its local state, so it cannot reliably catch the case where routing itself has disappeared. It doesn't fix REA's canonical check. One design detail I'd like to clarify: how would the agent discover/load the enabled sidecar while REA's managed SKILL.md stays unchanged? Would an upstream-owned loader/reference in the canonical skill, or a host-supported registration mechanism, be the intended route? I'd like to keep the companion's side portable across clients and adapt to the supported contract once that's settled.

bsakaguchi commented

2026-10-31 00:34:15 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 18, 2026):

Agreed on all three points — discovery alone must not enable an integration, and separating companion status from canonical-file drift in doctor is exactly the right split (otherwise a missing companion would read as a broken install and trigger need-install-or-repair). On the trust boundary, a dedicated per-client companion directory with path-escaping checks sounds good. One more thing worth considering: pin companion manifests to a schema version so future REA releases can migrate them instead of silently ignoring older entries. Happy to review a draft PR if you open one.

@XinwangTao commented on GitHub (Oct 18, 2026): Agreed on all three points — discovery alone must not enable an integration, and separating companion status from canonical-file drift in doctor is exactly the right split (otherwise a missing companion would read as a broken install and trigger need-install-or-repair). On the trust boundary, a dedicated per-client companion directory with path-escaping checks sounds good. One more thing worth considering: pin companion manifests to a schema version so future REA releases can migrate them instead of silently ignoring older entries. Happy to review a draft PR if you open one.

bsakaguchi commented

2026-10-31 00:34:16 +00:00

Author

Owner

@ShadowSwaps commented on GitHub (Oct 18, 2026):

Thanks for offering to review, @XinwangTao. I've opened PR #4970 with a proposed integration contract, an example manifest and an instruction fixture.

The proposal covers explicit opt-in and path boundaries, separate companion health reporting, setup/update behavior, and versioned manifests with handling for unsupported schemas and future migrations.

The PR is now ready for review and remains a design-only proposal. I'd appreciate your feedback on the loading mechanism, trusted client/profile binding, installation ownership, and the schema/migration approach before moving toward implementation.

@ShadowSwaps commented on GitHub (Oct 18, 2026): Thanks for offering to review, @XinwangTao. I've opened PR #4970 with a proposed integration contract, an example manifest and an instruction fixture. The proposal covers explicit opt-in and path boundaries, separate companion health reporting, setup/update behavior, and versioned manifests with handling for unsupported schemas and future migrations. The PR is now ready for review and remains a design-only proposal. I'd appreciate your feedback on the loading mechanism, trusted client/profile binding, installation ownership, and the schema/migration approach before moving toward implementation.

bsakaguchi referenced this issue

2026-10-31 00:40:20 +00:00

[GH-ISSUE #5654] [Tracker] Open PRs that can't merge yet: conflicts and red CI (October 2026) #3425

bsakaguchi referenced this issue

2026-10-31 01:05:08 +00:00

[PR #2465] fix(javascript): preserve intrinsic invocation read identity #5248