{ "markdown": "
\n\n# DeepRefine-Skill\n\n\n\n\n\n\n
\n \"DeepRefine\n\n 
██████╗ ███████╗███████╗██████╗ ██████╗ ███████╗███████╗██╗███╗   ██╗███████╗\n██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝██║████╗  ██║██╔════╝\n██║  ██║█████╗  █████╗  ██████╔╝██████╔╝█████╗  █████╗  ██║██╔██╗ ██║█████╗\n██║  ██║██╔══╝  ██╔══╝  ██╔═══╝ ██╔══██╗██╔══╝  ██╔══╝  ██║██║╚██╗██║██╔══╝\n██████╔╝███████╗███████╗██║     ██║  ██║███████╗██║     ██║██║ ╚████║███████╗\n╚═════╝ ╚══════╝╚══════╝╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝
\n
\n\n[![PyPi](https://img.shields.io/badge/PyPi-v0.2.0-blue.svg)](https://pypi.org/project/deeprefine-cli/0.2.0/)\n[![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.2.0/)\n[![Paper](https://img.shields.io/badge/Paper-DeepRefine-b31b1b.svg)](https://arxiv.org/pdf/2605.10488)\n[![Project](https://img.shields.io/badge/Project-DeepRefine-green.svg)](https://github.com/HKUST-KnowComp/DeepRefine)\n\n
\n\nDeepRefine-Skill plugs into agent workflows and use a single command `/deeprefine` in your agent (Cursor, Copilot CLI, Gemini CLI, Codex, OpenCode, Claude Code) to refine and evolve your LLM-Wiki (e.g., **[graphify](https://github.com/safishamsi/graphify)**) knowledge base.\n\n

\n\"Demo:\n

\n\nIt refines your graphify knowledge graph for better future retrieval and Q&A quality.\n\nSupported agent frameworks:\n\n

\n \"Cursor\"  \n \"Gemini  \n \"Copilot  \n \"Copilot  \n \"Copilot  \n \"Copilot  \n

\n\n---\n\n## News\n- **[2026/7/10] v0.2.0** - Claude Code and OpenCode adapters: `deeprefine claude install` / `deeprefine opencode install`, bundled skill + command templates.\n- **[2026/7/3] v0.1.9** - Release with Codex, Copilot CLI, and Gemini CLI skills bundled; dry-run-first refinement, evidence-aware action review (HIGH/MEDIUM/LOW), ambiguous-node warnings, and LOW-confidence apply guard.\n- **[2026/6/24] v0.1.9** - Codex skill supported.\n- **[2026/6/18] v0.1.9** - Gemini CLI and Copilot CLI supported.\n- **[2026/6/17] v0.1.9** - Added dry-run-first refinement, evidence-aware action review, ambiguous-node warnings, and LOW-confidence apply guard.\n- **[2026/6/15] v0.1.8** - Aligned interaction memory with LLM-Wiki (graphify) and fixed the single query refinement issue.\n- **[2026/6/2] v0.1.7** — Cursor skill + `deeprefine refine` with configurable API. And strict DeepRefine agent loop.\n\n## Agent CLI (Recommended)\n\nThis is the default mode and the main workflow for this project.\n\n### One-time setup\n\n```bash\npip install deeprefine-cli graphifyy\n\ncd /path/to/your-kb-project\ngraphify cursor install\n\n# for Cursor\ndeeprefine cursor install\n# for Copilot CLI\ndeeprefine copilot install\n# for Gemini CLI\ndeeprefine gemini install # or deeprefine gemini link\n# for Codex\ndeeprefine codex install\n# for Claude Code\ndeeprefine claude install\n# for OpenCode\ndeeprefine opencode install\n```\n\nAfter upgrading the package, run the command again to refresh local skill files.\n\n### Typical session (Agent CLI)\n\n```bash\n/graphify .\n/graphify ./ --wiki\n/graphify query \"your question 1\"\n/graphify query \"your question 2\"\n# ..\n/deeprefine\n```\n\n### What `/deeprefine` does now (default queue behavior)\n
\nProcedures:\n\nWhen you run `/deeprefine`, it should follow this order:\n\n1. `deeprefine history sync-memory`\n - import queries from `graphify-out/memory/query_*.md`\n - write to `graphify-out/.deeprefine/history.jsonl`\n2. load pending queries from `history.jsonl` (`refined != true`)\n3. refine pending queries sequentially\n4. for refinement-path queries, generate `` actions and run `deeprefine review`\n5. stop in dry-run mode and show the review report; do **not** modify `graph.json` yet\n6. only after user approval, run `deeprefine apply --refresh-wiki` and then `deeprefine loop finish`\n\n
\n\n### Agent artifacts\n\n```text\ngraphify-out/\n├── graph.json # graphify main graph; unchanged until apply approval\n├── memory/\n│ └── query_*.md # graphify query logs (sync source)\n└── .deeprefine/\n ├── history.jsonl # DeepRefine-maintained history queue\n ├── graph.json.bak # backup before first apply in this run\n ├── checkpoints/graph.checkpoint..json # post-state graph after each apply\n ├── checkpoints.json # checkpoint timeline registry\n ├── loop_trace_.json # per-query loop audit trace\n ├── refinement_results_.jsonl # per-day run log\n ├── refinement_actions_*.txt # optional; only when refinement path is taken\n ├── proposed_refinement_actions_*.txt # CLI dry-run proposed actions\n ├── proposed_refinement_review_*.md # evidence-aware review report\n └── proposed_refinement_review_*.json # optional structured review report\n```\n\n### Agent-related commands\n\nRun from your KB project root.\n\n| Command | Description |\n|---------|-------------|\n| `deeprefine cursor install` | Install `/deeprefine` skill for Cursor (`.cursor/skills/deeprefine/`) |\n| `deeprefine cursor install --user` | Install Cursor skill for all projects (`~/.cursor/skills/`) |\n| `deeprefine copilot install` | Install `/deeprefine` skill for Copilot CLI (`.github/skills/deeprefine/`) |\n| `deeprefine copilot install --user` | Install Copilot CLI skill for all projects (`~/.copilot/skills/`) |\n| `deeprefine copilot uninstall` | Remove Copilot CLI skill |\n| `deeprefine codex install` | Install `$deeprefine` skill for Codex (`.agents/skills/deeprefine/`) |\n| `deeprefine codex install --user` | Install Codex skill for all projects (`~/.codex/skills/deeprefine/`) |\n| `deeprefine codex uninstall` | Remove Codex skill |\n| `deeprefine claude install` | Install `/deeprefine` skill for Claude Code (`.claude/skills/deeprefine/`) |\n| `deeprefine claude install --user` | Install Claude Code skill for all projects (`~/.claude/skills/deeprefine/`) |\n| `deeprefine claude uninstall` | Remove the Claude Code skill |\n| `deeprefine opencode install` | Install `/deeprefine` skill + commands for OpenCode (`.opencode/`) |\n| `deeprefine opencode install --user` | Install OpenCode skill for all projects (`~/.opencode/`) |\n| `deeprefine opencode uninstall` | Remove the OpenCode skill and commands |\n| `deeprefine gemini path` | Print the extension root used for Gemini CLI |\n| `deeprefine gemini link` | Link the current source checkout with `gemini extensions link` |\n| `deeprefine gemini install` | Install the bundled extension with `gemini extensions install` |\n| `deeprefine gemini install --copy-only` | Manual fallback copy to `~/.gemini/extensions/deeprefine-skill` |\n| `deeprefine gemini uninstall` | Remove the extension with Gemini CLI's manager |\n| `deeprefine history sync-memory` | Import `graphify-out/memory/query_*.md` into DeepRefine history |\n| `deeprefine history list --pending` | Show unrefined queue |\n| `deeprefine loop init --query \"...\"` | Create `loop_trace_.json` template |\n| `deeprefine loop validate --trace-file T` | Validate trace against DeepRefine control flow |\n| `deeprefine review --trace-file T --refinement-file F` | Review proposed actions with HIGH/MEDIUM/LOW evidence labels; no graph write |\n| `deeprefine apply --refresh-wiki --trace-file T --refinement-file F` | Apply actions and regenerate `graphify-out/wiki` from the refined graph; graph + Wiki are committed together |\n| `deeprefine apply --refresh-wiki --allow-low-confidence --trace-file T --refinement-file F` | Refresh the Wiki while explicitly overriding the LOW-confidence guard |\n| `deeprefine loop finish --trace-file T [--refinement-file F]` | Persist results and mark history refined |\n\n### Evidence-aware review and safe apply\n\n`/deeprefine` should default to dry-run-first behavior. Proposed actions are reviewed before they can modify `graphify-out/graph.json`. Each action is labeled:\n\n| Label | Meaning |\n|-------|---------|\n| `HIGH` | Direct graph or code evidence exists. |\n| `MEDIUM` | k-hop context supports the action, but direct code or exact-edge evidence is missing. |\n| `LOW` | Node names are ambiguous, too broad, cross-community, or cannot be grounded in `graph.json`. |\n\nBare function names such as `main()`, `run()`, `train()`, `test()`, and `setup()` are treated as ambiguous. Prefer file-qualified names:\n\n```text\nBAD: insert_edge(\"main()\", \"calls\", \"Trainer\")\nGOOD: insert_edge(\"pretraining/pretraining_CLIP_fine-grained.py::main()\", \"calls\", \"Trainer\")\n```\n\n`deeprefine apply` refuses LOW-confidence actions by default. Use `--allow-low-confidence` only when the user explicitly accepts the risk.\n\nWhen the knowledge base was created with Graphify Wiki output, use `--refresh-wiki`. DeepRefine stages the refined graph, regenerates the Wiki with `graphify export wiki`, validates `wiki/index.md`, and only then replaces the production graph and Wiki. If export fails, the existing graph and Wiki remain unchanged.\n\n---\n\n## Codex Integration\n\n
\nSetup, commands, and session usage\n\nDeepRefine works as a Codex skill. The installer writes the Codex-specific\nskill file to `.agents/skills/deeprefine/SKILL.md` and UI metadata to\n`.agents/skills/deeprefine/agents/openai.yaml`. It also installs focused\nreferences under `.agents/skills/deeprefine/references/` for the refinement\nworkflow, LLM prompts, and trace/command details.\n\n### One-time setup\n\n```bash\ncd /path/to/your-kb-project\npip install deeprefine-cli\ndeeprefine codex install --project\n```\n\nAfter upgrading the package, run `deeprefine codex install --project` again to\nrefresh the local skill files. Restart or reload Codex, then invoke:\n\n```text\n$deeprefine\n/deeprefine\n```\n\n### Codex commands\n\n| Command | Description |\n|---------|-------------|\n| `deeprefine codex install` | Install the Codex skill into `.agents/skills/deeprefine/` |\n| `deeprefine codex install --user` | Install the Codex skill into `~/.codex/skills/deeprefine/` |\n| `deeprefine codex uninstall` | Remove the Codex skill |\n\n### Codex session\n\n```text\n$deeprefine\n```\n\nCodex runs the full agent-native refinement loop for pending queries, stops after\n`deeprefine review`, and presents the HIGH/MEDIUM/LOW report. Reply with an\nexplicit apply/approve message only after reviewing the proposed actions.\n\nSee [`docs/codex.md`](docs/codex.md) for details.\n\n
\n\n---\n\n## Copilot CLI Integration\n\n
\nSetup, commands, and session usage\n\nDeepRefine works as a GitHub Copilot CLI agent skill. The skill file is\ninstalled into `.github/skills/deeprefine/SKILL.md` and auto-discovered by\nCopilot. Shell commands are pre-approved via `allowed-tools: shell`.\n\n### One-time setup\n\n```bash\ncd /path/to/your-kb-project\npip install deeprefine-cli\ndeeprefine copilot install --project\n```\n\nAfter upgrading the package, run `deeprefine copilot install --project` again\nto refresh the local skill file. Start a Copilot CLI session and reload:\n\n```text\n/skills reload\n/skills info deeprefine\n```\n\n### Mode detection\n\nCopilot CLI does not natively support sub-commands, so the skill uses\nkeyword-based mode detection in the SKILL.md preamble:\n\n| Mode | Trigger keywords | Behavior |\n|------|-----------------|----------|\n| **Full workflow** | `/deeprefine`, \"refine\", \"improve\", \"fix\" | Full refinement loop; stops after dry-run review; asks for approval |\n| **Review only** | \"review\", \"check\", \"audit\", \"inspect\", \"dry-run\" | Reads trace + refinement file; shows HIGH/MEDIUM/LOW report; no graph writes |\n| **Apply only** | \"approve\", \"apply\", \"write\", \"go ahead\" | Runs `deeprefine apply` only after a prior review; requires explicit user approval in the current message |\n\n### Copilot CLI session\n\n```text\n/deeprefine\n```\n\nThe agent runs the full refinement loop for all pending queries. For\nrefinement-path queries, it stops after the dry-run review and asks:\n\n```text\n[HIGH] insert_edge(\"trainer.py::train_epoch()\", \"calls\", \"validate()\")\nEvidence: Direct code evidence in trainer.py.\n[MEDIUM] insert_edge(\"data.py::load()\", \"imports\", \"torch\")\nWarning: No direct code evidence found.\n\nApply only after review. Approve?\n```\n\nReply \"apply\" or \"go ahead\" to proceed; the agent will run\n`deeprefine apply` in the follow-up turn.\n\n
\n\n---\n\n## Gemini CLI Integration\n\n
\nSetup, commands, and session usage\n\nDeepRefine can also be used as a Gemini CLI extension. This keeps the same safe,\ndry-run-first DeepRefine workflow while making `/deeprefine` available inside\nGemini CLI.\n\n### One-time setup for local development\n\n```bash\ncd /path/to/DeepRefine-Skill\npip install -e .\ndeeprefine gemini link\n```\n\n`deeprefine gemini link` calls Gemini CLI's official extension manager:\n\n```bash\ngemini extensions link /path/to/DeepRefine-Skill\n```\n\nRestart Gemini CLI after linking. Then check:\n\n```text\n/extensions list\n/commands list\n```\n\nExpected commands:\n\n```text\n/deeprefine\n/deeprefine:review\n/deeprefine:apply\n```\n\n### Gemini CLI commands\n\n| Command | Description |\n|---------|-------------|\n| `deeprefine gemini path` | Print the extension root used for Gemini CLI |\n| `deeprefine gemini link` | Link the current source checkout with `gemini extensions link` |\n| `deeprefine gemini install` | Install the bundled extension with `gemini extensions install` |\n| `deeprefine gemini install --copy-only` | Manual fallback copy to `~/.gemini/extensions/deeprefine-skill` |\n| `deeprefine gemini uninstall` | Remove the extension with Gemini CLI's manager |\n\nFor normal source development, prefer `deeprefine gemini link`. It makes the\nextension visible to `/extensions list`, whereas copying files alone may not\nregister the extension in newer Gemini CLI versions.\n\n### Gemini CLI session\n\n```bash\ngemini\n```\n\nThen run:\n\n```text\n/deeprefine\n/deeprefine:review \"Why is the graph missing the data loading path?\"\n/deeprefine:apply \"Apply the approved refinement actions from the valid trace.\"\n```\n\nThe extension files are located at the repository root and are also bundled under\n`deeprefine_skill/gemini_extension/` for wheel installs. See\n[`docs/gemini-cli.md`](docs/gemini-cli.md) for details.\n\n
\n\n## OpenCode Integration\n\n
\nSetup, commands, and session usage\n\n### Prerequisites\n\n- **OpenCode CLI** installed and configured\n- **graphify** CLI available on your PATH\n- **Python 3.10+** with `deeprefine-cli` installed\n- A `graphify-out/graph.json` knowledge graph in your project\n\n### Setup\n\n```bash\n# Install into the current project\ndeeprefine opencode install --project\n\n# Install globally (all projects)\ndeeprefine opencode install --user\n```\n\nThis installs **4 files**:\n\n| Destination | Source | Purpose |\n|------------|--------|---------|\n| `.opencode/skills/deeprefine/SKILL.md` | `SKILL_OPENCODE.md` | Agent harness with 6 OpenCode-native optimizations |\n| `.opencode/commands/deeprefine.md` | `commands/opencode/deeprefine.md` | Full workflow entrypoint (`/deeprefine`) |\n| `.opencode/commands/deeprefine-review.md` | `commands/opencode/deeprefine-review.md` | Review-only entrypoint (`/deeprefine-review`) |\n| `.opencode/commands/deeprefine-apply.md` | `commands/opencode/deeprefine-apply.md` | Apply-only entrypoint (`/deeprefine-apply`) |\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/deeprefine` | Full pipeline: sync → judge → abduction → refinement → 5-Oracle review → (await approval) → apply → post-apply verify |\n| `/deeprefine-review` | Review only: read existing actions → 5-Oracle audit → evidence review → present results |\n| `/deeprefine-apply` | Apply only: read reviewed actions → confirm → apply → post-apply verify → finish |\n\n### Model Configuration\n\nOpenCode supports per-phase model routing via environment variables:\n\n| Variable | Phase | Purpose |\n|----------|-------|---------|\n| `DEEPREFINE_JUDGE_MODEL` | Judgement (`Yes/No`) | Fast, cheap model for binary classification (e.g., `gpt-4o-mini`) |\n| `DEEPREFINE_REFINE_MODEL` | Abduction + Refinement | Strong reasoning model for complex causal analysis (e.g., `claude-sonnet-4-20250514`) |\n\nIf either variable is unset, the session default model is used.\n\n### OpenCode-Native Optimizations\n\nDeepRefine on OpenCode includes 6 platform-native optimizations not available in Cursor or Cline:\n\n1. **Parallel query processing** — Multiple pending queries are dispatched to parallel subagents via `task()`, reducing wall-clock time to ~1 query's duration\n2. **Phase-specific model routing** — Binary judgement uses a cheap model; complex abduction/refinement uses a strong model\n3. **Structured progress tracking** — `todowrite()` replaces text checklists, enabling real-time progress visibility and cross-session resumption\n4. **5-Oracle parallel review** — Five specialized oracle subagents audit refinement actions from orthogonal angles (completeness, correctness, safety, consistency, edge-cases) before any graph mutation\n5. **Post-apply auto-verification** — After applying refinement actions, the original query is re-run to confirm the graph fix actually resolved the issue\n6. **Evidence ledger** — Every phase boundary writes a structured JSONL entry (`graphify-out/.deeprefine/ledger.jsonl`) with timestamps, artifacts, and QA results for full auditability\n\n### Uninstall\n\n```bash\ndeeprefine opencode uninstall --project\n```\n
\n\n\n---\n\n## Claude Code Integration\n\n
\nSetup, commands, and session usage\n\nDeepRefine works as a Claude Code Agent Skill. The installer writes the\nClaude-specific skill file to `.claude/skills/deeprefine/SKILL.md`, along with\nindependently maintained references under\n`.claude/skills/deeprefine/references/` for the refinement workflow, LLM\nprompts, and trace/command details.\n\n### One-time setup\n\n```bash\ncd /path/to/your-kb-project\npip install deeprefine-cli\ndeeprefine claude install --project\n```\n\nAfter upgrading the package, run `deeprefine claude install --project` again\nto refresh the local skill files. Restart Claude Code, then invoke:\n\n```text\n/deeprefine\n```\n\n### Claude Code commands\n\n| Command | Description |\n|---------|-------------|\n| `deeprefine claude install` | Install the Claude Code skill into `.claude/skills/deeprefine/` |\n| `deeprefine claude install --user` | Install the Claude Code skill into `~/.claude/skills/deeprefine/` |\n| `deeprefine claude uninstall` | Remove the Claude Code skill |\n\n### Claude Code session\n\n```text\n/deeprefine\n```\n\nClaude Code runs the full refinement loop for pending queries, stops after\n`deeprefine review`, and presents the HIGH/MEDIUM/LOW report. Reply with an\nexplicit apply/approve message only after reviewing the proposed actions.\n\n
\n\n---\n\n## Terminal CLI (FAISS + API/vLLM)\n\n
\nRequirements, environment, workflow, and commands\n\nUse this section when you want a pure terminal workflow without Cursor `/deeprefine`.\n\n### Extra requirements\n\n- DeepRefine repository installed in `atlastune`\n- Inference backend configured (API or vLLM)\n\n```bash\nconda activate atlastune\ncd /path/to/DeepRefine && pip install -e .\npip install deeprefine-cli\n\n# Optional, if DeepRefine repo is elsewhere\nexport DEEPREFINE_REPO=/path/to/DeepRefine\n```\n\n### Inference environment (CLI mode)\n\n| Variable | Default |\n|----------|---------|\n| `DEEPREFINE_LLM_URL` | *(empty; SDK default)* |\n| `DEEPREFINE_EMBED_URL` | *(empty; SDK default)* |\n| `DEEPREFINE_API_KEY` | fallback to `OPENAI_API_KEY` |\n| `DEEPREFINE_LLM_API_KEY` | fallback to `DEEPREFINE_API_KEY` |\n| `DEEPREFINE_EMBED_API_KEY` | fallback to `DEEPREFINE_API_KEY` |\n| `DEEPREFINE_MODEL` | `gpt-4.1-mini` |\n| `DEEPREFINE_EMBED_MODEL` | `text-embedding-3-small` |\n\n### Terminal workflow\n\n```bash\ncd /path/to/your-kb-project\n\n# Option A: import from graphify memory first (recommended)\ndeeprefine history sync-memory\ndeeprefine history list --pending\ndeeprefine refine # dry-run: proposed actions + review, no graph write\ndeeprefine refine --apply # optional: write accepted CLI refine changes\n\n# Option B: add one explicit query\ndeeprefine history add --query \"your question\"\ndeeprefine refine # dry-run by default\n```\n\n### Terminal commands\n\n| Command | Description |\n|---------|-------------|\n| `deeprefine history add --query \"...\"` | Append one query to history |\n| `deeprefine history list` | List all history rows |\n| `deeprefine history sync-memory` | Import graphify memory queries into history |\n| `deeprefine history list --pending` | List only unrefined queries |\n| `deeprefine refine` | Generate proposed actions for all pending queries; dry-run by default |\n| `deeprefine refine --query \"...\"` | Generate proposed actions for a single query; dry-run by default |\n| `deeprefine refine --apply` | Persist accepted CLI refine changes to `graph.json` |\n| `deeprefine refine --rebuild-index` | Rebuild FAISS before refine |\n| `deeprefine index --rebuild` | Rebuild FAISS cache only |\n\n\n\n## Installation\n\n| Method | Command |\n|--------|---------|\n| **PyPI** | `pip install deeprefine-cli==0.2.0` |\n| **Source** | `pip install -e /path/to/DeepRefine-Skill` |\n\n```bash\ndeeprefine --help\n# Expect: cursor, copilot, codex, claude, opencode, gemini, history, index, refine, review, apply, loop\n```\n
\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n", "bytes": 23293, "sha": "375cc1c2a255670cacbe7665cc8e3376da9bcea6b648052c1c574f768d5c1125", "repo_slug": "hkust-knowcomp/deeprefine-skill", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_hkust_knowcomp_deeprefine_skill_77959dd0/readme" }