feat(dotagent): initial public release

Author: 0xble

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Neovim
+        uses: rhysd/action-setup-vim@v1
+        with:
+          neovim: stable
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install markdownlint-cli2
+        run: npm install --global markdownlint-cli2
+
+      - name: Run headless tests
+        run: nvim --headless -u NONE "+lua dofile(\"tests/run.lua\")" +qa!
+
+      - name: Run health smoke test
+        run: |
+          nvim --headless -u NONE "+set rtp+=$GITHUB_WORKSPACE" \
+            "+lua require('dotagent').setup({ activation = { mode = 'manual' }, sources = { { type = 'items', items = {} } } })" \
+            "+lua require('dotagent.completion.blink').provider()" \
+            "+checkhealth dotagent" +qa!
+
+      - name: Lint README
+        run: markdownlint-cli2 README.md

.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+doc/tags

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,147 @@
+# dotagent.nvim
+
+`dotagent.nvim` provides `$`-prefixed completion for local agent commands and skills inside Neovim.
+
+It is intentionally conservative by default. The plugin stays off in normal editing buffers unless you explicitly attach it or launch Neovim through an external-editor flow marked with `DOTAGENT_EDITOR_PROMPT=1`.
+
+## Requirements
+
+- Neovim 0.10+
+- `saghen/blink.cmp`
+
+## Release Status
+
+The current recommended first public tag is `v0.1.0`.
+
+The plugin uses git tags for releases. There is no separate version file in the repo.
+
+## Features
+
+- Scans local command markdown files and skill directories
+- Provides a Blink source for `$command` and `$skill` completion
+- Auto-attaches only when the editor session is launched with `DOTAGENT_EDITOR_PROMPT=1`
+- Supports manual `:DotagentAttach` and `:DotagentDetach`
+- Includes `:DotagentRefresh`, `:DotagentBrowse`, and `:DotagentHealth`
+
+## Install
+
+Lazy example:
+
+```lua
+{
+  "0xble/dotagent.nvim",
+  config = function()
+    require("dotagent").setup({
+      sources = {
+        {
+          type = "commands",
+          path = vim.fn.expand("~/dotfiles/dot_agent/commands"),
+        },
+        {
+          type = "skills",
+          path = vim.fn.expand("~/dotfiles/dot_agent/skills"),
+        },
+      },
+    })
+  end,
+}
+```
+
+Blink setup:
+
+```lua
+{
+  "saghen/blink.cmp",
+  opts = function(_, opts)
+    opts.sources = opts.sources or {}
+    opts.sources.default = function()
+      local sources = { "lsp", "path", "snippets" }
+      if require("dotagent").is_buffer_enabled(0) then
+        table.insert(sources, 1, "dotagent")
+      elseif vim.bo.filetype ~= "" and vim.bo.filetype ~= "markdown" and vim.bo.filetype ~= "text" and vim.bo.filetype ~= "gitcommit" then
+        table.insert(sources, "buffer")
+      end
+      return sources
+    end
+
+    opts.sources.providers = opts.sources.providers or {}
+    opts.sources.providers.dotagent = require("dotagent.completion.blink").provider()
+  end,
+}
+```
+
+## Recommended Integration
+
+The best integration is an external-editor flow where Claude Code or a Codex launcher opens Neovim for prompt composition.
+
+Use one shared launcher for those flows:
+
+```sh
+#!/bin/sh
+export DOTAGENT_EDITOR_PROMPT=1
+exec nvim "$@"
+```
+
+Then point your agent surface at that launcher:
+
+- Claude Code: configure its external editor, then use `Ctrl+G`
+- Codex or an editor-backed wrapper like `ai`: set `EDITOR` to the same launcher
+
+When Neovim starts with `DOTAGENT_EDITOR_PROMPT=1`, `dotagent.nvim` attaches only to the initial prompt buffer. Additional buffers opened later in that session stay unaffected.
+
+## Default Behavior
+
+Without `DOTAGENT_EDITOR_PROMPT=1`, the plugin does not auto-attach in regular buffers.
+
+The fallback path is manual:
+
+- `:DotagentAttach`
+- `:DotagentDetach`
+
+That keeps `$` completion out of normal code editing by default.
+
+## Commands
+
+- `:DotagentAttach [bufnr]`
+- `:DotagentDetach [bufnr]`
+- `:DotagentRefresh`
+- `:DotagentBrowse`
+- `:DotagentHealth`
+
+## Configuration
+
+```lua
+require("dotagent").setup({
+  prefixes = { "$" },
+  activation = {
+    mode = "contextual",
+    env_var = "DOTAGENT_EDITOR_PROMPT",
+  },
+  sources = {
+    {
+      type = "commands",
+      path = vim.fn.expand("~/dotfiles/dot_agent/commands"),
+    },
+    {
+      type = "skills",
+      path = vim.fn.expand("~/dotfiles/dot_agent/skills"),
+    },
+    {
+      type = "items",
+      items = {
+        {
+          name = "ship",
+          kind = "command",
+          description = "Example Lua-defined item",
+        },
+      },
+    },
+  },
+})
+```
+
+`activation.mode` values:
+
+- `"contextual"`: attach only when launched with the editor prompt env marker
+- `"manual"`: never auto-attach
+- `"global"`: enable in every non-terminal buffer

doc/dotagent.txt

@@ -0,0 +1,88 @@
+*dotagent.nvim*  $-prefixed local agent completion
+
+INTRODUCTION                                                    *dotagent-intro*
+
+dotagent.nvim indexes local command markdown files and skill directories and
+exposes them as a Blink completion source.
+
+The plugin is conservative by default. It only auto-attaches when Neovim is
+started with DOTAGENT_EDITOR_PROMPT=1. Otherwise use |:DotagentAttach|.
+
+SETUP                                                           *dotagent-setup*
+
+>
+  require("dotagent").setup({
+    activation = {
+      mode = "contextual",
+      env_var = "DOTAGENT_EDITOR_PROMPT",
+    },
+    sources = {
+      {
+        type = "commands",
+        path = vim.fn.expand("~/dotfiles/dot_agent/commands"),
+      },
+      {
+        type = "skills",
+        path = vim.fn.expand("~/dotfiles/dot_agent/skills"),
+      },
+    },
+  })
+<
+
+Blink provider:
+
+>
+  opts.sources.providers.dotagent = require("dotagent.completion.blink").provider()
+<
+
+RECOMMENDED INTEGRATION                                 *dotagent-integration*
+
+Use one external-editor launcher for Claude Code, Codex wrappers, or any other
+editor-backed agent surface:
+
+>
+  #!/bin/sh
+  export DOTAGENT_EDITOR_PROMPT=1
+  exec nvim "$@"
+<
+
+Then point the agent tool at that launcher.
+
+Claude Code already has an external editor flow reachable with Ctrl+G.
+Editor-backed Codex launchers should use the same launcher through EDITOR.
+
+COMMANDS                                                       *dotagent-cmds*
+
+:DotagentAttach [bufnr]
+  Attach dotagent.nvim to the current buffer or the given buffer.
+
+:DotagentDetach [bufnr]
+  Detach dotagent.nvim from the current buffer or the given buffer.
+
+:DotagentRefresh
+  Rebuild the indexed command and skill list.
+
+:DotagentBrowse
+  Show indexed items with vim.ui.select and insert the chosen token.
+
+:DotagentHealth
+  Run |:checkhealth| for dotagent.nvim.
+
+CONFIGURATION                                                 *dotagent-config*
+
+prefixes~
+  List of valid command prefixes. Default: ["$"]
+
+activation.mode~
+  "contextual", "manual", or "global"
+
+activation.env_var~
+  Default: "DOTAGENT_EDITOR_PROMPT"
+
+sources~
+  List of source definitions:
+    - { type = "commands", path = "..." }
+    - { type = "skills", path = "..." }
+    - { type = "items", items = { ... } }
+
+vim:tw=78:ts=8:noet:ft=help:norl:

lua/dotagent/action/init.lua

@@ -0,0 +1 @@
+return {}