feat(install): add OpenCode /understand slash-command stub - #618
Open
chindris-mihai-alexandru wants to merge 5 commits into
Open
feat(install): add OpenCode /understand slash-command stub#618chindris-mihai-alexandru wants to merge 5 commits into
chindris-mihai-alexandru wants to merge 5 commits into
Conversation
- Add adal to install.sh platforms table (~/.adal/skills, per-skill) - Add adal to install.ps1 platforms table (~/.adal/skills, per-skill) - Add AdaL section to README.md with install instructions - Add AdaL to platform compatibility table - Add AdaL to supported platforms list - Add AdaL tip in install.sh and install.ps1 cmd_install functions - Update all 7 translated READMEs (es-ES, ja-JP, ko-KR, ru-RU, tr-TR, zh-CN, zh-TW)
OpenCode does not implement Claude Code's Task tool, so the LLM subagent phases of /understand cannot dispatch (upstream docs: PR Egonex-AI#388). This ships the missing activation half of that story: a real command stub instead of only documentation. - commands/opencode/understand.md: slash-command template registered by install.sh into ~/.config/opencode/commands/understand.md. Runs the deterministic pipeline (scan-project -> extract-import-map -> compute-batches), assembles a schema-valid structural graph, and launches the dashboard. References enrich-structural-graph.py to fill per-node complexity/tags/summary without LLM calls. - skills/understand/enrich-structural-graph.py: deterministic node enrichment for structural-only graphs (heuristics on sizeLines, path, language, fileCategory). Reused by the command stub; also useful for tests/benchmarks that assemble graphs without an LLM. - install.sh: link_opencode_commands/unlink_opencode_commands helpers, wired into cmd_install/cmd_uninstall for the opencode platform. Closes the manual-activation gap from issue Egonex-AI#317.
There was a problem hiding this comment.
Pull request overview
Adds an OpenCode-focused /understand command template and a deterministic enrichment helper to make structural-only graphs schema-valid, while also extending installer/docs surface area for an additional platform (AdaL) and wiring OpenCode command linking into the Bash installer.
Changes:
- Add
commands/opencode/understand.mdas an OpenCode slash-command template for the deterministic (structural-only) pipeline + dashboard launch. - Add
skills/understand/enrich-structural-graph.pyto deterministically populatecomplexity,tags, andsummaryon structural graphs. - Update installers and READMEs to support/mention AdaL, and link the OpenCode command stub during
install.sh opencode.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| understand-anything-plugin/skills/understand/enrich-structural-graph.py | New deterministic enrichment script to add required node fields for schema validity. |
| understand-anything-plugin/commands/opencode/understand.md | New OpenCode /understand template describing the structural-only pipeline and dashboard launch. |
| README.md | Adds AdaL install section and includes adal in supported platform lists/tables. |
| install.sh | Adds adal platform and OpenCode command symlink helpers, plus install tips. |
| install.ps1 | Adds adal platform and an AdaL installation tip. |
| READMEs/README.zh-TW.md | Adds AdaL row to the platform table. |
| READMEs/README.zh-CN.md | Adds AdaL row to the platform table. |
| READMEs/README.tr-TR.md | Adds AdaL row to the platform table. |
| READMEs/README.ru-RU.md | Adds AdaL row to the platform table. |
| READMEs/README.ko-KR.md | Adds AdaL row to the platform table. |
| READMEs/README.ja-JP.md | Adds AdaL row to the platform table. |
| READMEs/README.es-ES.md | Adds AdaL row to the platform table. |
Suppressed comments (3)
understand-anything-plugin/commands/opencode/understand.md:27
- The deterministic Node scripts used below import
@understand-anything/coreand fall back topackages/core/dist/*whennode_modulesisn't present. On a fresh install,packages/core/dist/does not exist yet, so these steps will fail unless you ensure the core build has been run first.
SKILL_ROOT="$(python3 -c "import os;print(os.path.realpath(os.path.expanduser('$HOME/.agents/skills/understand')))" 2>/dev/null)"
[ -d "$SKILL_ROOT" ] || SKILL_ROOT="$HOME/.understand-anything-plugin/skills/understand"
[ -d "$SKILL_ROOT" ] || { echo "[understand] skill dir not found"; exit 1; }
understand-anything-plugin/commands/opencode/understand.md:40
- This hard-codes
.uaas the data directory, but the codebase consistently uses: legacy.understand-anything/if present, otherwise.ua/(e.g.skills/understand/SKILL.md). Hard-coding.uawill write a second graph dir for existing projects and breaks the documented compatibility rule.
UA_DIR="$PROJECT_ROOT/.ua"
mkdir -p "$UA_DIR/intermediate"
node "$SKILL_ROOT/scan-project.mjs" "$PROJECT_ROOT" "$UA_DIR/intermediate/scan-result.json" --exclude-analysis-data
**understand-anything-plugin/commands/opencode/understand.md:92**
* Dashboard launch uses `GRAPH_DIR="$PROJECT_ROOT/.ua"`, which can diverge from the resolved `$UA_DIR` (legacy `.understand-anything/` vs `.ua/`). If the graph was written to the legacy dir, the dashboard will start without the expected graph.
GRAPH_DIR="$PROJECT_ROOT/.ua" npx --prefix "$HOME/.understand-anything-plugin/packages/dashboard" vite --config "$HOME/.understand-anything-plugin/packages/dashboard/vite.config.ts" --port 5173 &
</details>
---
💡 <a href="/Egonex-AI/Understand-Anything/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.
Comment on lines
+16
to
+17
| layers, or tours. See `docs/platforms/opencode.md` (upstream) for the | ||
| compatibility matrix and future directions. |
There was a problem hiding this comment.
Comment on lines
+146
to
+152
| path = Path(sys.argv[1]) | ||
| graph = json.loads(path.read_text()) | ||
| stats = enrich(graph) | ||
|
|
||
| if "--write" in sys.argv: | ||
| path.write_text(json.dumps(graph, indent=2, ensure_ascii=False)) | ||
| print(f"Wrote {path}") |
There was a problem hiding this comment.
Fixed in d470f93: read_text/write_text now pass encoding="utf-8", matching merge-batch-graphs.py and merge-subdomain-graphs.py. Added tests/skill/understand/test_enrich_structural_graph.py (16 tests) covering a --write round-trip with non-ASCII content; all pass with the existing skill test suite.
…lot review) read_text/write_text now use encoding="utf-8", matching the convention in merge-batch-graphs.py and merge-subdomain-graphs.py, so the script is immune to locale-dependent default encodings. Adds a unit test module covering complexity thresholds, tags, summary, no-overwrite semantics, and a --write round-trip with non-ASCII content.
docs/platforms/opencode.md lives in sibling PR Egonex-AI#388 and does not exist on this branch, so the slash-command template and install.sh tip pointed at a missing path. Reworded both to reference the upstream OpenCode platform documentation, matching the AdaL tip convention from 76baa9f.
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
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
Ships the command-stub half of the OpenCode activation story (issue #317, complements docs PR #388 which covers the limitation + manual procedure).
commands/opencode/understand.md— slash-command template thatinstall.sh opencodesymlinks into~/.config/opencode/commands/understand.md. It runs the deterministic pipeline (scan-project.mjs→extract-import-map.mjs→compute-batches.mjs), assembles a schema-valid structural knowledge graph, and launches the dashboard — no subagent dispatch required.skills/understand/enrich-structural-graph.py— deterministic per-node enrichment (complexity/tags/summary) for structural-only graphs, so the output passesautoFixGraphwith zero issues. Reusable by tests/benchmarks that assemble graphs without an LLM.install.sh—link_opencode_commands/unlink_opencode_commandshelpers wired intocmd_install/cmd_uninstallfor theopencodeplatform, plus a structural-only tip on install.Test plan
bash -n install.sh— syntax checkHOME:install.sh opencodecreates the symlink;--uninstall opencoderemoves itautoFixGraphreports 0 issues → dashboard serves graph/understandappears in OpenCode afterinstall.sh opencodeDeviations from plan
Co-Authored-By: opencode