@mc1global/opencode-jarvis 0.14.0 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +779 -319
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,157 +1,155 @@
1
1
  # @mc1global/opencode-jarvis
2
2
 
3
- > **v0.15.0** — SRP enforcement: 9 oversized files split, enum-values facade across all 13 bounded contexts, composition root extracted. See [CHANGELOG.md](CHANGELOG.md)
3
+ > **v0.14.0** — LLM comment intent processing, SRP enforcement, typed port interfaces, Azure sync bug fixes. See [CHANGELOG.md](CHANGELOG.md)
4
4
 
5
- A native [OpenCode](https://opencode.ai) plugin providing multi-agent development infrastructure: session memory, kanban project management, governance guardrails, automatic token-per-card cost tracking with budget alerts, RAG semantic search, Obsidian vault management, domain map analysis, workspace registry, environment management, CI/CD pipelines, Azure DevOps sync, and structured data tools.
5
+ A native [OpenCode](https://opencode.ai) plugin that brings **multi-agent development infrastructure** to any project: session memory, kanban project management, governance guardrails, token cost tracking, RAG semantic search, Obsidian vault documentation, domain-map analysis, Azure DevOps synchronization, CI/CD pipelines, and more.
6
6
 
7
- Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
7
+ Built entirely in **TypeScript** with Domain-Driven Design, SOLID principles, and strict type safety. No Python. No Bun. Runs on Node.js.
8
8
 
9
9
  ---
10
10
 
11
- ## Prerequisites
12
-
13
- - **[OpenCode](https://opencode.ai) CLI** — Host runtime for the plugin (**required**)
14
- - **[Bun](https://bun.sh) >= 1.0** — Production runtime for bun:sqlite (**required**)
15
- - **[Ollama](https://ollama.ai)** + `embeddinggemma` model — Local embeddings for RAG semantic search (**required for RAG**)
16
- - **Node.js >= 20** — Test runner only (dev)
17
- - **[Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** — Azure DevOps board sync (optional)
18
- - **[Dagger CLI](https://docs.dagger.io/install)** — Container CI/CD gate execution (optional)
11
+ ## Table of Contents
12
+
13
+ 1. [Prerequisites](#prerequisites)
14
+ 2. [Install OpenCode CLI](#install-opencode-cli)
15
+ 3. [Install the Plugin](#install-the-plugin)
16
+ 4. [Configure the Plugin](#configure-the-plugin)
17
+ 5. [First Launch](#first-launch)
18
+ 6. [Verify Setup](#verify-setup)
19
+ 7. [Quick Guide — JARVIS Methodology](#quick-guide--jarvis-methodology)
20
+ 8. [Azure DevOps Integration](#azure-devops-integration)
21
+ 9. [File Locations Reference](#file-locations-reference)
22
+ 10. [Local Development](#local-development)
23
+ 11. [Troubleshooting](#troubleshooting)
24
+ 12. [Configuration Reference](#configuration-reference)
25
+ 13. [Dependencies](#dependencies)
26
+ 14. [License](#license)
19
27
 
20
28
  ---
21
29
 
22
- ## Quick Start
30
+ ## Prerequisites
23
31
 
24
- ### Step 1 — Install prerequisites
32
+ | Requirement | Purpose | Install |
33
+ |---|---|---|
34
+ | **Node.js >= 20** | Plugin runtime and test runner | [nodejs.org](https://nodejs.org) |
35
+ | **OpenCode CLI** | Host that loads and runs the plugin | See below |
36
+ | **Ollama** + `embeddinggemma` | Local embeddings for RAG semantic search | [ollama.ai](https://ollama.ai) |
37
+ | **Ollama** + `llama3.2` | LLM for Azure comment intent classification | Same Ollama install |
38
+ | **Azure CLI** _(optional)_ | Azure DevOps board sync authentication | [learn.microsoft.com/cli/azure](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) |
39
+ | **Dagger CLI** _(optional)_ | CI/CD gate execution via containers | [docs.dagger.io/install](https://docs.dagger.io/install) |
40
+
41
+ ---
25
42
 
26
- Choose your operating system below. Each section includes both **manual commands** and a link to an **automated setup script** that handles everything.
43
+ ## Install OpenCode CLI
27
44
 
28
- #### macOS
45
+ Full documentation: [opencode.ai/docs](https://opencode.ai/docs)
29
46
 
30
- **Automated** (recommended):
47
+ ### macOS
31
48
 
32
49
  ```bash
33
- curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-macos.sh | bash
34
- ```
50
+ # Via install script (recommended)
51
+ curl -fsSL https://opencode.ai/install | bash
35
52
 
36
- Or download `scripts/setup/setup-macos.sh` from the repository and run it locally.
53
+ # Or via Homebrew
54
+ brew install anomalyco/tap/opencode
55
+ ```
37
56
 
38
- **Manual:**
57
+ ### Linux (Ubuntu / Debian / Fedora / Arch)
39
58
 
40
59
  ```bash
41
- # Bun (required — SQLite runtime)
42
- curl -fsSL https://bun.sh/install | bash
60
+ # Via install script
61
+ curl -fsSL https://opencode.ai/install | bash
62
+
63
+ # Arch Linux
64
+ sudo pacman -S opencode # Stable
65
+ paru -S opencode-bin # Latest (AUR)
66
+ ```
43
67
 
44
- # Ollama + embedding model (required for RAG)
45
- brew install ollama
46
- ollama serve # start the server (keep running)
47
- ollama pull embeddinggemma # download the embedding model
68
+ ### Windows
48
69
 
49
- # Optional: Azure DevOps sync
50
- brew install azure-cli && az login
70
+ > **Recommendation:** Use [Windows Subsystem for Linux (WSL)](https://opencode.ai/docs/windows-wsl) for the best experience. The JARVIS plugin requires WSL — it does not run in native Windows PowerShell or cmd.
71
+
72
+ **Step 1 — Install WSL** (PowerShell as Administrator):
51
73
 
52
- # Optional: CI/CD pipeline execution
53
- brew install dagger/tap/dagger
74
+ ```powershell
75
+ wsl --install
54
76
  ```
55
77
 
56
- #### Linux (Ubuntu/Debian/Fedora/Arch)
78
+ Restart, then open the Ubuntu terminal.
57
79
 
58
- **Automated** (recommended):
80
+ **Step 2 — Install OpenCode inside WSL:**
59
81
 
60
82
  ```bash
61
- curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-linux.sh | bash
83
+ curl -fsSL https://opencode.ai/install | bash
62
84
  ```
63
85
 
64
- Or download `scripts/setup/setup-linux.sh` from the repository and run it locally.
86
+ If you prefer to use OpenCode natively on Windows (without WSL), the CLI itself supports Chocolatey and Scoop — but the JARVIS plugin must still run inside WSL:
65
87
 
66
- **Manual:**
88
+ ```powershell
89
+ choco install opencode # or: scoop install opencode
90
+ ```
67
91
 
68
- ```bash
69
- # Bun (required)
70
- curl -fsSL https://bun.sh/install | bash
92
+ ### Configure an LLM provider
71
93
 
72
- # Ollama + embedding model (required for RAG)
73
- curl -fsSL https://ollama.ai/install.sh | sh
74
- ollama serve # start the server (keep running)
75
- ollama pull embeddinggemma # download the embedding model
94
+ After installing OpenCode, connect a provider:
76
95
 
77
- # Optional: Azure CLI (Debian/Ubuntu)
78
- curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
79
-
80
- # Optional: Dagger CLI
81
- curl -fsSL https://dl.dagger.io/dagger/install.sh | sh
96
+ ```
97
+ /connect
82
98
  ```
83
99
 
84
- #### Windows (WSL)
100
+ Select your provider and paste your API key. See [opencode.ai/docs/providers](https://opencode.ai/docs/providers) for the full list of supported providers.
85
101
 
86
- > OpenCode recommends Windows Subsystem for Linux (WSL) for the best experience.
87
- > See the [OpenCode WSL guide](https://opencode.ai/docs/windows-wsl) for details.
102
+ ---
88
103
 
89
- **Step 0 — Install WSL** (if you haven't already):
104
+ ## Install the Plugin
90
105
 
91
- Open **PowerShell as Administrator** and run:
106
+ ### Option A — From npm (recommended)
92
107
 
93
- ```powershell
94
- wsl --install
95
- ```
108
+ OpenCode installs npm plugins automatically. You only need to reference the package in your `opencode.json` (see [Configure the Plugin](#configure-the-plugin)).
96
109
 
97
- Restart your computer, then open the **Ubuntu** terminal app.
110
+ Requires access to the `@mc1global` scope on npm. If you have access, OpenCode installs it automatically on first launch — no manual `npm install` needed.
98
111
 
99
- **Step 1 — Run the setup script inside WSL:**
112
+ ### Option B — From Azure DevOps repository (private access)
100
113
 
101
114
  ```bash
102
- # From your WSL terminal (Ubuntu):
103
- curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-wsl.sh | bash
115
+ # Clone the repository
116
+ git clone https://dev.azure.com/MC1Innovation/IA/_git/AgenticCoding jarvis-plugin
117
+ cd jarvis-plugin
118
+
119
+ # Install dependencies and build
120
+ npm install
121
+ npm run build
122
+
123
+ # Link as a local OpenCode plugin (creates symlink to dist/index.js)
124
+ npm run link:local
104
125
  ```
105
126
 
106
- Or download `scripts/setup/setup-wsl.sh` from the repository and run it inside WSL.
127
+ After `link:local`, the plugin is active globally — no `opencode.json` change needed. Any OpenCode project on this machine will load it.
107
128
 
108
- **Manual (inside WSL terminal):**
129
+ To update after pulling changes:
109
130
 
110
131
  ```bash
111
- # OpenCode CLI
112
- curl -fsSL https://opencode.ai/install | bash
113
-
114
- # Bun (required)
115
- curl -fsSL https://bun.sh/install | bash
132
+ git pull
133
+ npm run build # the symlink stays valid, just rebuild
134
+ ```
116
135
 
117
- # Ollama + embedding model (required for RAG)
118
- curl -fsSL https://ollama.ai/install.sh | sh
119
- ollama serve # start the server (keep running in a separate terminal)
120
- ollama pull embeddinggemma # download the embedding model
136
+ To remove the local link:
121
137
 
122
- # Optional: Azure CLI
123
- curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
138
+ ```bash
139
+ npm run unlink:local
124
140
  ```
125
141
 
126
- > **WSL performance tip:** For best results, keep your project files in the WSL
127
- > filesystem (`~/code/my-project`) rather than on `/mnt/c/`. See
128
- > [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl) for more.
129
-
130
142
  ---
131
143
 
132
- ### Step 2 — Add the plugin to your project
144
+ ## Configure the Plugin
133
145
 
134
- Create an `opencode.json` file **in your project root directory**:
135
-
136
- ```
137
- your-project/ <-- your project root
138
- opencode.json <-- CREATE THIS FILE HERE
139
- package.json
140
- src/
141
- ...
142
- ```
143
-
144
- Content of `opencode.json`:
146
+ Create an `opencode.json` file in your **project root** (or at `~/.config/opencode/opencode.json` to enable globally):
145
147
 
146
148
  ```json
147
149
  {
148
150
  "$schema": "https://opencode.ai/config.json",
149
151
  "plugin": ["@mc1global/opencode-jarvis"],
150
152
  "command": {
151
- "config": {
152
- "template": "Use JARVIS config tools to view and modify configuration. Run config-read to show current settings, then config-write to apply changes. $ARGUMENTS",
153
- "description": "View or modify JARVIS configuration"
154
- },
155
153
  "healthcheck": {
156
154
  "template": "Run the JARVIS healthcheck diagnostic and provide actionable guidance for any issues found. $ARGUMENTS",
157
155
  "description": "Run JARVIS environment diagnostics"
@@ -163,84 +161,70 @@ Content of `opencode.json`:
163
161
  "start-card": {
164
162
  "template": "Start working on a JARVIS kanban card. Handle the full lifecycle: check status, assign agent and sprint, move to doing, and start a context session. $ARGUMENTS",
165
163
  "description": "Start working on a kanban card"
164
+ },
165
+ "config": {
166
+ "template": "Use JARVIS config tools to view and modify configuration. Run config-read to show current settings, then config-write to apply changes. $ARGUMENTS",
167
+ "description": "View or modify JARVIS configuration"
166
168
  }
167
169
  }
168
170
  }
169
171
  ```
170
172
 
171
- The `"command"` block registers JARVIS slash commands (`/config`, `/healthcheck`, `/sync-azure`, `/start-card`) so OpenCode shows them in the command list. The plugin's `command.execute.before` hook enriches the prompt with detailed JARVIS-specific instructions when executed.
172
-
173
- OpenCode installs npm plugins automatically at startup. Requires access to the `@mc1global` org on npm.
174
-
175
- #### Where exactly does `opencode.json` go?
176
-
177
- OpenCode supports config files at **two levels**. Choose one (or both — they merge):
178
-
179
- **Project-level** (recommended for teams):
180
-
181
- ```
182
- /home/you/code/my-project/opencode.json # Linux/WSL
183
- /Users/you/code/my-project/opencode.json # macOS
184
- ```
185
-
186
- This is committed to git so your whole team gets the plugin. OpenCode looks for this file in the current directory or traverses up to the nearest git root.
187
-
188
- **Global-level** (applies to ALL your projects):
189
-
190
- ```
191
- ~/.config/opencode/opencode.json # Linux/macOS/WSL
192
- ```
173
+ **Where does `opencode.json` go?**
193
174
 
194
- Use this if you want JARVIS active on every project without adding `opencode.json` to each one.
175
+ | Location | Effect |
176
+ |---|---|
177
+ | `your-project/opencode.json` | Plugin active only in this project — commit to git for team sharing |
178
+ | `~/.config/opencode/opencode.json` | Plugin active in **all** your projects on this machine |
195
179
 
196
- > **Precedence:** Project config overrides global config for conflicting keys.
197
- > Non-conflicting settings from both are merged. See the
198
- > [OpenCode config docs](https://opencode.ai/docs/config#locations) for details.
180
+ Both files can coexist. Project config overrides global config for conflicting keys; non-conflicting settings merge. See [opencode.ai/docs/config](https://opencode.ai/docs/config) for details.
199
181
 
200
182
  ---
201
183
 
202
- ### Step 3 — First launch (automatic)
184
+ ## First Launch
203
185
 
204
- Run `opencode` in your project directory. JARVIS initializes everything:
186
+ Run OpenCode in your project directory:
205
187
 
206
188
  ```bash
207
- cd /path/to/your/project # must contain opencode.json (or have one globally)
189
+ cd /path/to/your/project
208
190
  opencode
209
191
  ```
210
192
 
211
- On first load, JARVIS creates these files and directories automatically:
193
+ On first load, JARVIS automatically creates:
212
194
 
213
195
  ```
214
196
  your-project/
215
- .jarvis/ SQLite database + RAG indexes (local, gitignored)
216
- config/jarvis.yaml Default configuration (commit this)
217
- obsidian-vault/ Documentation skeleton (commit this)
218
- AGENTS.md Agent operational guide (commit this)
197
+ AGENTS.md Agent operational guide — commit this
198
+ config/jarvis.yaml Default configuration — commit this
199
+ obsidian-vault/ Documentation vault skeleton — commit this
200
+ .jarvis/ SQLite database + RAG indexes — add to .gitignore
219
201
 
220
202
  ~/.config/opencode/commands/jarvis-agents-md-file.md (once per machine)
203
+ ~/.jarvis/registry.db Workspace registry
221
204
  ```
222
205
 
223
- The global command `~/.config/opencode/commands/jarvis-agents-md-file.md` is written **once per machine** on first plugin load. It registers the `/jarvis-agents-md-file` slash command globally, available in every OpenCode project without any per-project configuration.
206
+ The global command `jarvis-agents-md-file` is installed once per machine, making the `/jarvis-agents-md-file` slash command available in every OpenCode project without any per-project configuration.
224
207
 
225
- On the **first session**, the agent receives automatic guidance via system prompt injection to run initial diagnostics.
208
+ **First session — run these in order:**
226
209
 
227
- ### Step 4 — First session recommended steps
228
-
229
- The agent should run these on first use (JARVIS prompts automatically):
210
+ ```
211
+ /healthcheck Verify all subsystems and get fix guidance
212
+ rag-index Index the codebase for semantic search
213
+ rag-oracle-index Index the JARVIS documentation (dir="obsidian-vault")
214
+ kanban-board-view See the kanban board
215
+ ```
230
216
 
231
- 1. **`/healthcheck`** — Verify all subsystems
232
- 2. **`rag-index`** tool — Index the codebase for semantic search
233
- 3. **`rag-oracle-index`** tool with `directory="obsidian-vault"` — Index documentation
234
- 4. **`kanban-board-view`** tool — See the kanban board
217
+ ---
235
218
 
236
- ### Step 5 — Verify your setup
219
+ ## Verify Setup
237
220
 
238
- The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix commands**:
221
+ The `/healthcheck` command shows all dependencies with copy-paste fix commands:
239
222
 
240
223
  ```
241
- [PASS] Bun Runtime: Bun is available (v1.1.38)
224
+ [PASS] Node.js Runtime: Node.js v20.x is available
242
225
  [PASS] Ollama Connectivity: Ollama is reachable at http://localhost:11434
243
226
  [PASS] Embedding Model: Model "embeddinggemma" is available
227
+ [PASS] LLM Model: Model "llama3.2" is available
244
228
  [PASS] SQLite Database: Database file exists
245
229
  [PASS] Configuration: config/jarvis.yaml exists
246
230
  [PASS] RAG Index: RAG index contains 42006 documents
@@ -249,210 +233,642 @@ The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix comma
249
233
  [WARN] Azure CLI (optional): Azure CLI is not installed
250
234
  FIX: brew install azure-cli && az login
251
235
 
252
- Summary: 6 pass, 2 warn, 0 fail (8 total)
236
+ Summary: 7 pass, 2 warn, 0 fail (9 total)
253
237
  Status: HEALTHY
254
238
  ```
255
239
 
256
240
  ---
257
241
 
258
- ## File Locations Reference
242
+ ## Quick Guide — JARVIS Methodology
259
243
 
260
- ### In your project (committed to git, shared with team)
244
+ ### What is the JARVIS methodology?
245
+
246
+ JARVIS enforces a structured development methodology on top of OpenCode. It is not a code generator — it is a **governance and project management layer** that ensures AI agents follow the same standards a senior engineer would enforce in code review.
247
+
248
+ The methodology is built on four pillars:
249
+
250
+ **1. Domain-Driven Design (DDD)**
251
+ Code is organized into 13 bounded contexts. Each context owns its domain logic, use cases, infrastructure adapters, and tools. No direct imports between contexts — cross-context communication uses port interfaces wired at the composition root.
252
+
253
+ **2. SOLID principles**
254
+ Every class and module must satisfy all five SOLID principles. The Single Responsibility Principle is enforced at the file level with a hard limit of **500 lines per file**. Files approaching this limit must be split by responsibility.
255
+
256
+ **3. Kanban lifecycle**
257
+ All non-trivial work (estimated > 15 minutes) follows a mandatory pipeline:
261
258
 
262
259
  ```
263
- your-project/
264
- opencode.json Plugin declaration (Step 2 above)
265
- config/jarvis.yaml Configuration (auto-created, then customized)
266
- AGENTS.md Agent operational guide (auto-generated)
267
- obsidian-vault/ Documentation vault
260
+ backlog → grooming → ready → doing → review → tested → done
268
261
  ```
269
262
 
270
- ### Local per machine (NOT committed — add to .gitignore)
263
+ Skipping stages is a governance violation. Each stage has gate tasks that must be met with evidence before promotion.
264
+
265
+ **4. Context memory**
266
+ Every work session is tracked. The agent records decisions, discoveries, and blockers. When the context window compacts, JARVIS injects the active session state back — the agent never loses track of what it was doing.
267
+
268
+ ---
269
+
270
+ ### Guardrails
271
+
272
+ Guardrails are runtime policies enforced on **every tool invocation** via the `tool.execute.before` hook. Violations with `error` severity throw immediately and abort the call — the agent cannot bypass them.
273
+
274
+ **File access guardrails:**
275
+
276
+ | Forbidden action | Correct alternative |
277
+ |---|---|
278
+ | Read `.csv` files directly | `data-csv-query` tool |
279
+ | Read `.yaml` / `.yml` files directly | `data-yaml-get` or `config-read` |
280
+ | Read `.env`, `.pem`, `.key`, `credentials.*` | Blocked — never allowed |
281
+ | Read `.aws/credentials`, `.npmrc`, `.kube/config` | Blocked — never allowed |
282
+
283
+ **Shell safety guardrails:**
284
+
285
+ | Forbidden command | Reason |
286
+ |---|---|
287
+ | `git push --force` | History rewriting on shared branches |
288
+ | `sqlite3 ...` | Bypasses repository abstraction and domain invariants |
289
+ | `env`, `printenv`, `echo $SECRET` | Leaks secrets into AI provider context |
290
+ | `cat .env`, `source .env` | Same as above via shell |
291
+
292
+ **Kanban guardrails:**
293
+ - Gate tasks must be met before promoting a card to `review`, `tested`, or `done`
294
+ - Minimum 30 seconds between status transitions (configurable)
295
+ - All grooming requirements must be satisfied before moving to `ready`
296
+
297
+ Pre-check any operation before executing:
271
298
 
272
299
  ```
273
- your-project/
274
- .jarvis/jarvis.db SQLite: kanban, sessions, metrics, sync mappings
275
- .jarvis/rag/ Vectra vector store (RAG embeddings)
300
+ governance-validate tool_name="bash" tool_args={"command": "git push --force origin main"}
301
+ governance-policies # list all 13 active policies
276
302
  ```
277
303
 
278
- ### Global (shared across all your projects)
304
+ ---
305
+
306
+ ### Obsidian Vault — Documentation
307
+
308
+ JARVIS creates and maintains an [Obsidian](https://obsidian.md)-compatible vault in `obsidian-vault/`. This vault serves two purposes:
309
+
310
+ **1. Project documentation** (managed by the agent, committed to git):
311
+
312
+ | Folder | Contents |
313
+ |---|---|
314
+ | `09-Dashboards/` | Project status dashboard — version, active card, test counts |
315
+ | `11-Domain-Reference/` | Per-context architecture docs — one file per bounded context |
316
+ | `12-Scope-Docs/` | Grooming scope documents — one file per kanban card (`CD-NNN-title.md`) |
317
+
318
+ **2. ORACLE documentation** (indexed for semantic search):
319
+
320
+ | Folder | Contents |
321
+ |---|---|
322
+ | `governance/` | Policy rules and security guidelines |
323
+ | `workflows/` | Step-by-step workflow guides (kanban, Azure sync, pipelines) |
324
+ | `patterns/` | Architecture patterns (DDD, hooks, RAG, config system) |
325
+ | `quick_reference/` | Tool reference, guardrails checklist, setup guide |
326
+
327
+ The ORACLE is the agent's reference library. It is indexed separately from the codebase using `rag-oracle-index` and queried with `rag-oracle-search`. Before starting an unfamiliar workflow, the agent searches ORACLE first.
328
+
329
+ **Vault tools:**
279
330
 
280
331
  ```
281
- ~/.config/opencode/opencode.json Global OpenCode config (optional)
282
- ~/.config/opencode/commands/jarvis-agents-md-file.md /jarvis-agents-md-file command (auto-installed)
283
- ~/.config/opencode/plugins/jarvis.js Symlink — local dev only (see below)
284
- ~/.jarvis/registry.db Workspace registry (cross-project)
285
- ~/.cache/opencode/node_modules/ Plugin npm cache (managed by OpenCode)
332
+ vault-inspect Overview of vault structure
333
+ vault-manage path="..." operation="read/write" Read or write sections
334
+ vault-create-document path="..." Create a new document
335
+ vault-search query="..." Full-text search across vault
286
336
  ```
287
337
 
288
338
  ---
289
339
 
290
- ## Setup Scripts
340
+ ### RAG Index — Why It Matters
291
341
 
292
- Automated setup scripts are available in the `scripts/setup/` directory of this repository:
342
+ The RAG index is a local vector database of your codebase and documentation. It enables the agent to find relevant code semantically — "find the function that validates card transitions" — without reading every file.
293
343
 
294
- - **`scripts/setup/setup-macos.sh`** — macOS with Homebrew — installs Bun, Ollama, embeddinggemma, optionally Azure CLI and Dagger
295
- - **`scripts/setup/setup-linux.sh`** — Ubuntu, Debian, Fedora, Arch Linux
296
- - **`scripts/setup/setup-wsl.sh`** — Windows Subsystem for Linux (includes OpenCode CLI install + WSL detection)
297
- - **`scripts/setup/link-local.js`** — Local development helper (see [Local Development](#local-development))
344
+ **Without the RAG index**, the agent falls back to file search and grep: slower, less accurate, and heavier on context window.
298
345
 
299
- Each OS script is interactive, checks for existing installations, and clearly reports what it does.
346
+ **With the RAG index**, the agent can:
347
+ - Find relevant code by meaning with `rag-search query="..."`
348
+ - Get code snippets with surrounding context with `rag-snippet query="..."`
349
+ - Search ORACLE documentation with `rag-oracle-search query="..." domain="workflows"`
350
+
351
+ **When to reindex:**
352
+
353
+ | Situation | Action |
354
+ |---|---|
355
+ | First setup | `rag-index` (full index) |
356
+ | After large refactor or many new files | `rag-index clear=true` (full reindex) |
357
+ | After modifying a single file | `rag-update file_path="src/..."` |
358
+ | After deleting a file | `rag-delete file_path="src/..."` |
359
+ | After updating vault docs | `rag-oracle-index directory="obsidian-vault"` |
360
+
361
+ Check index status:
362
+
363
+ ```
364
+ rag-status workspace="WORKSPACE" include_oracle=true
365
+ ```
300
366
 
301
367
  ---
302
368
 
303
- ## Available Commands
369
+ ### Migrating a Legacy Project to JARVIS Standards
370
+
371
+ If your project does not follow SOLID, DDD, or the 500-line limit, use JARVIS to plan and execute the migration incrementally — one bounded context at a time.
372
+
373
+ **Step 1 — Analyze the current state**
304
374
 
305
- Commands are available in any OpenCode session:
375
+ ```
376
+ domain-map-analyze directory="src"
377
+ domain-map-view directory="src"
378
+ ```
306
379
 
307
- - **`/jarvis-agents-md-file`** — Regenerate AGENTS.md with the canonical JARVIS template (global, auto-installed)
308
- - **`/healthcheck`** — Run diagnostics with actionable fix guidance
309
- - **`/sync-azure`** — Execute Azure DevOps sync workflow
310
- - **`/start-card CD-XXX`** — Start working on a kanban card (full lifecycle)
311
- - **`/config`** — Agent-guided configuration wizard
380
+ This produces a DDD structure report: detected bounded contexts, entity relationships, SRP violations (files over 500 lines), and cross-context coupling issues.
381
+
382
+ **Step 2 — Index the codebase**
383
+
384
+ ```
385
+ rag-index workspace="WORKSPACE" data_dir="src"
386
+ ```
312
387
 
313
- ## Available Skills (loaded on demand via `skill()` tool)
388
+ After indexing, all subsequent work uses semantic search to find relevant code before modifying it.
314
389
 
315
- - **`jarvis-kanban`** — Card lifecycle, grooming, sprints, gate tasks
316
- - **`jarvis-azure-sync`** — Azure DevOps push/pull/sync, PR creation
317
- - **`jarvis-onboarding`** — Setup, healthcheck, RAG indexing, tool reference
390
+ **Step 3 — Create an epic and sprint for the migration**
391
+
392
+ ```
393
+ kanban-epic-create title="Legacy Migration — DDD + SOLID + 500-line enforcement"
394
+ kanban-sprint-create name="SP-001" goal="Migration phase 1"
395
+ kanban-sprint-activate sprint_id="SP-001"
396
+ ```
397
+
398
+ **Step 4 — Create one card per bounded context or violation cluster**
399
+
400
+ For each area of work:
401
+
402
+ ```
403
+ kanban-card-create title="Extract UserAuth bounded context" priority="high"
404
+ kanban-card-move card_id="CD-001" status="grooming"
405
+ kanban-card-assign-epic card_id="CD-001" epic_id="EP-001"
406
+ vault-create-document path="obsidian-vault/12-Scope-Docs/CD-001-user-auth-extraction.md"
407
+ kanban-card-scope-doc card_id="CD-001" path="12-Scope-Docs/CD-001-user-auth-extraction.md"
408
+ kanban-card-criteria card_id="CD-001" description="All files in the UserAuth context are under 500 lines"
409
+ kanban-card-criteria card_id="CD-001" description="No direct imports from UserAuth to OrderProcessing context"
410
+ kanban-card-estimate card_id="CD-001" points=5
411
+ kanban-grooming-validate card_id="CD-001"
412
+ kanban-card-move card_id="CD-001" status="ready"
413
+ ```
414
+
415
+ **Step 5 — Work the card**
416
+
417
+ ```
418
+ kanban-card-assign card_id="CD-001" agent="opencode"
419
+ kanban-card-assign-sprint card_id="CD-001" sprint_id="SP-001"
420
+ kanban-card-move card_id="CD-001" status="doing"
421
+ context-session-start purpose="CD-001: Extract UserAuth bounded context"
422
+ ```
423
+
424
+ Before modifying any file, always search first:
425
+
426
+ ```
427
+ rag-search query="user authentication logic"
428
+ rag-snippet query="login validation"
429
+ rag-oracle-search query="DDD bounded context extraction" domain="patterns"
430
+ ```
431
+
432
+ **Step 6 — Meet gate tasks and promote**
433
+
434
+ ```
435
+ kanban-gate-list card_id="CD-001"
436
+ kanban-gate-meet card_id="CD-001" gate_index=0 evidence="commit abc123 — zero tsc errors"
437
+ kanban-card-move card_id="CD-001" status="review"
438
+ ```
439
+
440
+ Repeat for each area of the codebase. Use `domain-map-analyze` again after each phase to track remaining violations.
318
441
 
319
442
  ---
320
443
 
321
- ## Features
322
-
323
- ### 108 Tools across 15 categories
324
-
325
- - **Context Memory** (8) — `context-session-*`, `context-todo-*`, `context-note-*`, `context-search`
326
- - **Kanban Cards** (12) — `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief`
327
- - **Kanban Sprint/Epic** (9) — `kanban-sprint-create/get/list/activate/close/cancel`, `kanban-epic-create/list/update`
328
- - **Kanban Board & Grooming** (4) — `kanban-board-view/stats/wip`, `kanban-grooming-validate`
329
- - **Kanban Gates** (2) — `kanban-gate-list`, `kanban-gate-meet`
330
- - **Governance** (2) — `governance-validate`, `governance-policies`
331
- - **Token Metrics** (6) — `token-record/history/agent-report/card-report/sprint-report/summary`
332
- - **RAG** (8) — `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index`
333
- - **Data** (3) — `data-yaml-get`, `data-json-get`, `data-csv-query`
334
- - **Vault** (12) — `vault-manage`, `vault-inspect`, `vault-read/write-section`, `vault-read/write-frontmatter`, `vault-create-document`, `vault-list-documents`, `vault-search`, `vault-read/add/update-table`
335
- - **Agent** (7) — `agent-register/profile/list/spawn`, `agent-send/handoff/status`
336
- - **Domain Map** (2) — `domain-map-analyze`, `domain-map-view`
337
- - **Workspace** (4) — `workspace-info/list/update/link`
338
- - **Environment** (5) — `env-init/create/list/status/merge`
339
- - **Pipeline** (9) — `pipeline-init/activate/cancel/retry/query`, `gate-run/pass/fail/skip`
340
- - **Azure Sync** (12) — `azure-discover/push/pull/sync/status/pr-create/pr-list/comment`, `azure-poll-start/stop/status`, `azure-events-list`
341
- - **Bootstrap & Config** (5) — `bootstrap`, `healthcheck`, `terminal-commands`, `config-read`, `config-write`
342
-
343
- ### 8 Hooks
344
-
345
- - **Context Compacting** — Injects session context when context window compacts
346
- - **First-Run Guide** — Injects setup instructions on first session
347
- - **Shell Environment** — Injects JARVIS env vars into shell sessions
348
- - **Guardrails** — Governance policy enforcement on tool invocations
349
- - **Event Handlers** — Token usage tracking and cross-context event handling
350
- - **Execution Journal** — Crash recovery via tool execution state tracking
351
- - **Slash Commands** — `/healthcheck`, `/sync-azure`, `/start-card`, `/config`
352
- - **Config Command** — Agent-guided configuration editing
353
-
354
- ### 13 Governance Policies
355
-
356
- Runtime-enforced via `tool.execute.before` hook. Covers: CSV/YAML/env file access, force push protection, SQLite CLI blocking, destructive shell ops, credential file protection, and more.
444
+ ### All 121 Tools — Reference
445
+
446
+ #### Context Memory (8)
447
+
448
+ | Tool | Description |
449
+ |---|---|
450
+ | `context-session-start` | Start a tracked work session for a card or task |
451
+ | `context-session-finish` | Close session with a summary |
452
+ | `context-session-list` | List all sessions for the workspace |
453
+ | `context-todo-add` | Add a TODO item to track a task |
454
+ | `context-todo-list` | List TODOs, optionally filtered by status |
455
+ | `context-todo-complete` | Mark a TODO as completed |
456
+ | `context-note-add` | Record a decision, discovery, or blocker |
457
+ | `context-search` | Full-text semantic search across all context memory |
458
+
459
+ #### Kanban — Cards (14)
460
+
461
+ | Tool | Description |
462
+ |---|---|
463
+ | `kanban-card-create` | Create a new card in backlog |
464
+ | `kanban-card-update` | Update card description or priority |
465
+ | `kanban-card-move` | Move card to a new status (enforces state machine + WIP limits) |
466
+ | `kanban-card-assign` | Assign an agent to a card |
467
+ | `kanban-card-assign-sprint` | Assign card to an active sprint |
468
+ | `kanban-card-assign-epic` | Assign card to an epic |
469
+ | `kanban-card-estimate` | Set story points (Fibonacci: 1,2,3,5,8,13,21) |
470
+ | `kanban-card-criteria` | Add an acceptance criterion |
471
+ | `kanban-card-criteria-meet` | Mark an acceptance criterion as met |
472
+ | `kanban-card-scope-doc` | Link a vault scope document to a card |
473
+ | `kanban-card-depends-on` | Add or remove a depends-on relationship |
474
+ | `kanban-card-blocked-by` | Add or remove a blocked-by relationship |
475
+ | `kanban-card-unblock` | Unblock a card (moves back to doing or backlog) |
476
+ | `kanban-card-delete` | Delete a card (only backlog or done status) |
477
+
478
+ #### Kanban — Query (3)
479
+
480
+ | Tool | Description |
481
+ |---|---|
482
+ | `kanban-card-list` | List cards, optionally filtered by status |
483
+ | `kanban-card-get` | Get detailed card information |
484
+ | `kanban-card-brief` | Generate a full context briefing for handoff to another agent |
485
+
486
+ #### Kanban — Sprints & Epics (11)
487
+
488
+ | Tool | Description |
489
+ |---|---|
490
+ | `kanban-sprint-create` | Create a sprint in planning status |
491
+ | `kanban-sprint-get` | Get sprint details |
492
+ | `kanban-sprint-list` | List all sprints |
493
+ | `kanban-sprint-activate` | Activate a sprint (required before cards can move to doing) |
494
+ | `kanban-sprint-close` | Close a sprint with actual velocity |
495
+ | `kanban-sprint-cancel` | Cancel an active sprint |
496
+ | `kanban-epic-create` | Create an epic |
497
+ | `kanban-epic-list` | List all epics |
498
+ | `kanban-epic-update` | Update epic description, owner, or priority |
499
+ | `kanban-epic-start` | Mark epic as in-progress |
500
+ | `kanban-epic-complete` | Mark epic as completed |
501
+
502
+ #### Kanban — Board, Grooming & Gates (6)
503
+
504
+ | Tool | Description |
505
+ |---|---|
506
+ | `kanban-board-view` | Full board view with all columns and cards |
507
+ | `kanban-board-stats` | Card count per status column |
508
+ | `kanban-board-wip` | Check WIP limit violations |
509
+ | `kanban-grooming-validate` | Validate all grooming requirements for a card |
510
+ | `kanban-gate-list` | List all gate tasks for a card with evidence |
511
+ | `kanban-gate-meet` | Mark a gate task as met with evidence |
512
+
513
+ #### Governance (2)
514
+
515
+ | Tool | Description |
516
+ |---|---|
517
+ | `governance-validate` | Pre-check if an operation is allowed before executing |
518
+ | `governance-policies` | List all 13 active governance policies |
519
+
520
+ #### Token Metrics (6)
521
+
522
+ | Tool | Description |
523
+ |---|---|
524
+ | `token-record` | Record a token usage event |
525
+ | `token-history` | Get usage history with optional filters |
526
+ | `token-agent-report` | Report by agent — total tokens, cost, operation breakdown |
527
+ | `token-card-report` | Report by card — cost attribution per feature |
528
+ | `token-sprint-report` | Report by sprint — budget vs actual with alerts |
529
+ | `token-summary` | High-level workspace cost summary |
530
+
531
+ #### RAG — Semantic Search (8)
532
+
533
+ | Tool | Description |
534
+ |---|---|
535
+ | `rag-index` | Index workspace files into the local vector store |
536
+ | `rag-search` | Semantic search by meaning across indexed files |
537
+ | `rag-snippet` | Search with surrounding code context and line numbers |
538
+ | `rag-update` | Re-index a single file after modification |
539
+ | `rag-delete` | Remove a file from the index |
540
+ | `rag-status` | Show index status — document count, model, store info |
541
+ | `rag-oracle-index` | Index ORACLE governance documentation |
542
+ | `rag-oracle-search` | Semantic search across ORACLE docs, with domain filter |
543
+
544
+ #### Data (5)
545
+
546
+ | Tool | Description |
547
+ |---|---|
548
+ | `data-yaml-get` | Read a value from a YAML file using dot-notation path |
549
+ | `data-yaml-set` | Write a value to a YAML file |
550
+ | `data-json-get` | Read a value from a JSON file using dot-notation path |
551
+ | `data-json-set` | Write a value to a JSON file |
552
+ | `data-csv-query` | Query rows from a CSV file with filter expressions |
553
+
554
+ #### Vault — Obsidian Docs (12)
555
+
556
+ | Tool | Description |
557
+ |---|---|
558
+ | `vault-inspect` | Smart inspection — overview of vault or specific document |
559
+ | `vault-manage` | High-level read/write with intelligent defaults |
560
+ | `vault-read-section` | Read a specific section by heading path |
561
+ | `vault-write-section` | Write or update a section (replace or append) |
562
+ | `vault-read-frontmatter` | Read YAML frontmatter from a document |
563
+ | `vault-write-frontmatter` | Update YAML frontmatter |
564
+ | `vault-create-document` | Create a new vault document |
565
+ | `vault-list-documents` | List documents in a vault folder |
566
+ | `vault-search` | Full-text search across vault documents |
567
+ | `vault-read-table` | Read a markdown table from a document |
568
+ | `vault-add-table-row` | Append a row to a markdown table |
569
+ | `vault-update-table-row` | Update a table row by matching a column value |
570
+
571
+ #### Agent Registry (7)
572
+
573
+ | Tool | Description |
574
+ |---|---|
575
+ | `agent-register` | Register an agent profile with role, system prompt, and tool access |
576
+ | `agent-profile` | Get detailed information about a registered agent |
577
+ | `agent-list` | List all registered agent profiles |
578
+ | `agent-spawn` | Spawn a new OpenCode session configured with an agent's profile |
579
+ | `agent-send` | Send a message or task to another agent session |
580
+ | `agent-handoff` | Hand off a work item to another agent |
581
+ | `agent-status` | Check status of work items assigned to or by this agent |
582
+
583
+ #### Domain Map (2)
584
+
585
+ | Tool | Description |
586
+ |---|---|
587
+ | `domain-map-analyze` | Analyze a directory for DDD structure, SRP violations, and recommendations |
588
+ | `domain-map-view` | View the cached domain map from the most recent analysis |
589
+
590
+ #### Workspace Registry (4)
591
+
592
+ | Tool | Description |
593
+ |---|---|
594
+ | `workspace-info` | Get workspace metadata, tech stack, and dependencies |
595
+ | `workspace-list` | List all registered workspaces |
596
+ | `workspace-update` | Update workspace metadata, status, or tech stack |
597
+ | `workspace-link` | Manage dependency links between workspaces |
598
+
599
+ #### Environment (6)
600
+
601
+ | Tool | Description |
602
+ |---|---|
603
+ | `env-init` | Analyze a project directory and suggest environment config |
604
+ | `env-create` | Create an isolated development environment |
605
+ | `env-list` | List environments for the workspace |
606
+ | `env-status` | Get or update environment status |
607
+ | `env-merge` | Merge environment changes back to the main branch |
608
+ | `env-delete` | Delete an environment |
609
+
610
+ #### Pipeline — CI/CD (9)
611
+
612
+ | Tool | Description |
613
+ |---|---|
614
+ | `pipeline-init` | Create a pipeline from a stack template (`typescript-app`, `python-lib`, etc.) |
615
+ | `pipeline-activate` | Activate a draft pipeline |
616
+ | `pipeline-cancel` | Cancel a draft or active pipeline |
617
+ | `pipeline-retry` | Retry a failed pipeline |
618
+ | `pipeline-query` | Query pipelines or list available templates |
619
+ | `gate-run` | Execute a gate via Dagger |
620
+ | `gate-pass` | Manually pass a gate with evidence |
621
+ | `gate-fail` | Manually fail a gate |
622
+ | `gate-skip` | Skip a gate with a reason |
623
+
624
+ #### Azure DevOps Sync (13)
625
+
626
+ | Tool | Description |
627
+ |---|---|
628
+ | `azure-discover` | Discover Azure project config — process template, work item types, iterations |
629
+ | `azure-push` | Push local cards/epics/sprints to Azure (create or update work items) |
630
+ | `azure-pull` | Pull Azure work items into local kanban |
631
+ | `azure-sync` | Bidirectional sync (push then pull) |
632
+ | `azure-status` | Show sync mapping status — mapped, unmapped, sync timestamps |
633
+ | `azure-pr-create` | Create a Pull Request in Azure Repos |
634
+ | `azure-pr-list` | List Pull Requests or get a single PR |
635
+ | `azure-comment` | Add a structured comment to an Azure work item |
636
+ | `azure-poll-start` | Start background polling for Azure changes |
637
+ | `azure-poll-stop` | Stop background polling |
638
+ | `azure-poll-status` | Check polling service status |
639
+ | `azure-events-list` | List detected sync events (field changes, state transitions, comments) |
640
+ | `azure-process-comment` | Process a comment via LLM — classify intent, execute action, post reply |
641
+
642
+ #### Bootstrap & Config (6)
643
+
644
+ | Tool | Description |
645
+ |---|---|
646
+ | `bootstrap` | Initialize JARVIS project structure (AGENTS.md + directories) |
647
+ | `healthcheck` | Diagnose environment readiness with copy-paste fix guidance |
648
+ | `terminal-commands` | Get terminal commands for long-running operations (RAG index, etc.) |
649
+ | `config-read` | Read current JARVIS configuration (any section or all) |
650
+ | `config-write` | Update configuration values for a section |
651
+ | `config-reset` | Reset a section back to built-in defaults |
357
652
 
358
653
  ---
359
654
 
360
- ## Configuration
655
+ ### ORACLE — Searching the Documentation
361
656
 
362
- All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults:
657
+ The ORACLE is the semantic search index over the `obsidian-vault/` documentation. It covers workflows, governance, patterns, and quick reference guides.
363
658
 
364
- ```yaml
365
- # RAG embedding settings
366
- rag:
367
- ollama:
368
- url: "http://localhost:11434"
369
- model: "embeddinggemma"
370
- dimensions: 768
371
- markdownSplitByHeaders: true
659
+ **Index the ORACLE** (required on first setup, repeat after vault updates):
372
660
 
373
- # Azure DevOps integration
661
+ ```
662
+ rag-oracle-index directory="obsidian-vault"
663
+ ```
664
+
665
+ **Search the ORACLE** before starting any unfamiliar workflow:
666
+
667
+ ```
668
+ rag-oracle-search query="how to groom a card" domain="workflows"
669
+ rag-oracle-search query="DDD bounded context" domain="patterns"
670
+ rag-oracle-search query="azure sync setup" domain="workflows"
671
+ rag-oracle-search query="governance policies" domain="governance"
672
+ rag-oracle-search query="first time setup" domain="quick_reference"
673
+ ```
674
+
675
+ Supported `domain` values: `workflows`, `patterns`, `governance`, `quick_reference`. Omit `domain` for cross-domain search.
676
+
677
+ ---
678
+
679
+ ## Azure DevOps Integration
680
+
681
+ JARVIS can synchronize the local kanban board with **Azure DevOps Boards** bi-directionally. Cards become work items, sprints become iterations, epics become Azure Epics, and acceptance criteria become child Task items.
682
+
683
+ Additionally, when the background poll service is active, Azure work item **comments are detected in real-time** and can be classified by an LLM (`llama3.2` via Ollama) to trigger JARVIS actions automatically.
684
+
685
+ ### Prerequisites
686
+
687
+ **1. Install and authenticate Azure CLI:**
688
+
689
+ ```bash
690
+ # macOS
691
+ brew install azure-cli && az login
692
+
693
+ # Linux (Debian / Ubuntu)
694
+ curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
695
+
696
+ # Windows (inside WSL)
697
+ curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
698
+ ```
699
+
700
+ **2. Configure your Azure project:**
701
+
702
+ ```
703
+ config-write section="azure-sync" values={"organization": "MyOrg", "project": "MyProject", "repository": "MyRepo", "authMethod": "az-cli"}
704
+ ```
705
+
706
+ Or edit `config/jarvis.yaml` directly:
707
+
708
+ ```yaml
374
709
  azure-sync:
375
- organization: "" # Set to enable Azure sync
376
- project: ""
377
- repository: ""
378
- authMethod: "az-cli"
379
- pollEnabled: false
380
- pollIntervalSecs: 60
710
+ organization: "MyOrg"
711
+ project: "MyProject"
712
+ repository: "MyRepo"
713
+ authMethod: "az-cli" # or "pat" — requires AZURE_DEVOPS_PAT env var
714
+ ```
381
715
 
382
- # Kanban workflow enforcement
383
- kanban:
384
- minTransitionIntervalSecs: 30
385
- gateTasks: # Per-phase gate definitions
716
+ **3. Pull Ollama model for comment intent processing** (optional):
386
717
 
387
- # Token metrics & cost tracking
388
- token-metrics:
389
- sprintBudgetUsd: null # Set a USD budget per sprint (e.g. 50.0)
390
- budgetAlertThreshold: 0.8 # Alert when utilization exceeds 80%
718
+ ```bash
719
+ ollama pull llama3.2
720
+ ```
391
721
 
392
- # MCP server settings
393
- mcp-server:
394
- transport: "stdio"
395
- enabledTools: null # null = all tools
722
+ ---
723
+
724
+ ### Step 1 — Discover the Azure project
396
725
 
397
- # Pipeline CI/CD
398
- pipeline:
399
- defaultTimeoutMs: 300000
726
+ ```
727
+ azure-discover org="MyOrg" project="MyProject"
400
728
  ```
401
729
 
402
- Never read YAML files directly — use `data-yaml-get` tool or `ConfigService` getters.
730
+ Returns: process template (Scrum / Agile / CMMI), existing work item types, and current iterations. JARVIS uses this to automatically map local entities to the correct Azure work item types.
403
731
 
404
732
  ---
405
733
 
406
- ## MCP Server Mode
734
+ ### Step 2 — Push the local kanban to Azure
407
735
 
408
- JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
736
+ Push in this order — sprints (iterations) must exist before cards can reference them:
409
737
 
410
- ```bash
411
- bun run src/mcp-server.ts --directory /path/to/project
738
+ ```
739
+ azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="sprint"
740
+ azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="epic"
741
+ azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="card"
742
+ ```
743
+
744
+ Or push all at once:
745
+
746
+ ```
747
+ azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="all"
412
748
  ```
413
749
 
414
- Configure tool filtering in `config/jarvis.yaml` under `mcp-server`.
750
+ Preview without committing:
751
+
752
+ ```
753
+ azure-push workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="all" dry_run=true
754
+ ```
415
755
 
416
756
  ---
417
757
 
418
- ## Architecture
758
+ ### Step 3 — Check sync status
759
+
760
+ ```
761
+ azure-status workspace="WORKSPACE" org="MyOrg" project="MyProject"
762
+ ```
763
+
764
+ Shows which local entities are mapped to Azure work items, which are unmapped on either side, and sync timestamps.
765
+
766
+ ---
767
+
768
+ ### Step 4 — Pull changes from Azure
769
+
770
+ When team members update work items directly in Azure Boards:
771
+
772
+ ```
773
+ azure-pull workspace="WORKSPACE" org="MyOrg" project="MyProject" entity_type="card"
774
+ ```
775
+
776
+ Or run a full bidirectional sync:
419
777
 
420
778
  ```
421
- jarvis-plugin/
422
- src/
423
- domain/ Pure business logic, zero external deps (11 bounded contexts)
424
- application/ Use cases with DTOs
425
- infrastructure/ SQLite repos, Vectra, Ollama, FS adapters
426
- tools/ 21 tool modules (108 tools total)
427
- hooks/ 8 hooks
428
- tests/ 2,670+ tests across 93 test suites
429
- scripts/setup/ Per-OS automated setup scripts
430
- obsidian-vault/ Structured documentation
431
- config/ jarvis.yaml configuration
432
- templates/ AGENTS.md template + global OpenCode command templates
779
+ azure-sync workspace="WORKSPACE" org="MyOrg" project="MyProject"
433
780
  ```
434
781
 
435
- **Key constraints:**
782
+ ---
783
+
784
+ ### Background Polling — Real-time Change Detection
785
+
786
+ Enable polling in `config/jarvis.yaml` to detect Azure changes automatically:
787
+
788
+ ```yaml
789
+ azure-sync:
790
+ pollEnabled: true
791
+ pollIntervalSecs: 60 # minimum 30
792
+ ```
436
793
 
437
- - Max 500 lines per file (no exceptions)
438
- - Domain layer has zero external dependencies
439
- - ESM modules (`"type": "module"`)
440
- - `exactOptionalPropertyTypes: true` + `verbatimModuleSyntax: true`
441
- - 11 bounded contexts with strict DDD boundaries
442
- - Production runtime: Bun (`bun:sqlite`); Tests: Node.js + Jest
794
+ Control polling manually:
795
+
796
+ ```
797
+ azure-poll-start
798
+ azure-poll-status # check if running and last poll time
799
+ azure-events-list workspace="WORKSPACE" # view detected events
800
+ azure-poll-stop
801
+ ```
443
802
 
444
803
  ---
445
804
 
446
- ## Storage
805
+ ### Comment Intent Processing
806
+
807
+ When polling is active and a new comment is posted to an Azure work item, JARVIS stores it as a `comment_added` `SyncEvent`. Process it on demand:
808
+
809
+ ```
810
+ azure-process-comment event_id="EVT-NNN"
811
+ ```
447
812
 
448
- All data is stored locally:
813
+ This pipeline:
814
+ 1. Loads the comment text from the stored event
815
+ 2. Sends it to `llama3.2` via Ollama with a structured JSON schema prompt
816
+ 3. Classifies the intent: `create-card`, `move-card`, `add-ac`, `add-note`, or `unknown`
817
+ 4. Executes the resolved action against the local kanban
818
+ 5. Posts a `[JARVIS] ...` reply comment back to the Azure work item
449
819
 
450
- - `.jarvis/jarvis.db` — SQLite database (sessions, todos, notes, kanban, metrics, environments, pipelines)
451
- - `.jarvis/rag/<workspace>/` — Vectra vector stores (RAG indexes)
452
- - `.jarvis/rag/<workspace>/index-manifest.json` — File index registry (incremental indexing)
453
- - `~/.jarvis/registry.db` — Central workspace registry (cross-project)
820
+ **Example intents:**
454
821
 
455
- The `JARVIS_HOME` environment variable overrides the `~/.jarvis/` default.
822
+ | Comment posted in Azure | Intent detected | Action taken |
823
+ |---|---|---|
824
+ | `"Create a card to fix the login timeout"` | `create-card` | New kanban card created |
825
+ | `"Move this to in review"` | `move-card` | Card status updated |
826
+ | `"Add AC: login must complete in under 2s"` | `add-ac` | Acceptance criterion added |
827
+ | `"Note: we decided to use JWT tokens"` | `add-note` | Context memory note recorded |
828
+ | Anything unrecognised | `unknown` | LLM generates a helpful reply |
829
+
830
+ ---
831
+
832
+ ### Creating Pull Requests from JARVIS
833
+
834
+ ```
835
+ azure-pr-create org="MyOrg" project="MyProject" repository="MyRepo"
836
+ title="CD-005: Add LLM comment processing"
837
+ description="Implements on-demand comment classification..."
838
+ source_branch="cd-005-feature"
839
+ target_branch="main"
840
+ work_item_ids=[42]
841
+ ```
842
+
843
+ ---
844
+
845
+ ## File Locations Reference
846
+
847
+ ### In your project (commit to git — shared with team)
848
+
849
+ ```
850
+ your-project/
851
+ opencode.json Plugin declaration
852
+ config/jarvis.yaml Configuration (auto-created, then customized)
853
+ AGENTS.md Agent operational guide (auto-generated)
854
+ obsidian-vault/ Documentation vault
855
+ ```
856
+
857
+ ### Local per machine (do NOT commit — add to .gitignore)
858
+
859
+ ```
860
+ your-project/
861
+ .jarvis/jarvis.db SQLite: kanban, sessions, metrics, sync mappings
862
+ .jarvis/rag/ Vectra vector store (RAG embeddings)
863
+ ```
864
+
865
+ ### Global (shared across all your projects on this machine)
866
+
867
+ ```
868
+ ~/.config/opencode/opencode.json Global OpenCode config (optional)
869
+ ~/.config/opencode/commands/jarvis-agents-md-file.md Auto-installed global command
870
+ ~/.jarvis/registry.db Workspace registry (cross-project)
871
+ ```
456
872
 
457
873
  ---
458
874
 
@@ -460,7 +876,7 @@ The `JARVIS_HOME` environment variable overrides the `~/.jarvis/` default.
460
876
 
461
877
  ```bash
462
878
  # Clone
463
- git clone <repo-url> jarvis-plugin
879
+ git clone https://dev.azure.com/MC1Innovation/IA/_git/AgenticCoding jarvis-plugin
464
880
  cd jarvis-plugin
465
881
 
466
882
  # Install dependencies
@@ -472,90 +888,134 @@ npm run build
472
888
  # Run all tests
473
889
  npm test
474
890
 
475
- # Type check (zero errors required)
891
+ # Type check only (zero errors required)
476
892
  npm run lint
477
893
 
478
- # Single test file
479
- node --experimental-vm-modules node_modules/.bin/jest src/tests/application/healthcheck.test.ts --no-coverage
480
-
481
894
  # Watch mode
482
895
  npm run dev
483
896
  ```
484
897
 
485
- ### Testing the plugin locally (before publishing to npm)
486
-
487
- JARVIS loads as a global plugin via a symlink in `~/.config/opencode/plugins/`. No changes to any `opencode.json` are needed.
898
+ ### Test the plugin locally before publishing
488
899
 
489
900
  ```bash
490
- # Build + create symlink (once)
901
+ # Build + create symlink to ~/.config/opencode/plugins/jarvis.js
491
902
  npm run link:local
492
903
 
493
- # After each code change — the symlink stays valid, just rebuild
904
+ # After each code change — symlink stays valid, just rebuild
494
905
  npm run build
495
906
 
496
907
  # Remove the symlink when done
497
908
  npm run unlink:local
498
909
  ```
499
910
 
500
- `npm run link:local` runs `npm run build` first, then creates:
501
-
502
- ```
503
- ~/.config/opencode/plugins/jarvis.js → dist/index.js
504
- ```
505
-
506
- When Bun follows the symlink it resolves relative imports from `dist/` and finds external dependencies (`vectra`, `js-yaml`, etc.) in this repository's `node_modules/` — no additional configuration required.
507
-
508
- Restart OpenCode in any project to pick up the plugin or any new build.
911
+ Restart OpenCode in any project to pick up the new build.
509
912
 
510
913
  ---
511
914
 
512
915
  ## Troubleshooting
513
916
 
514
917
  **Ollama connection refused**
515
- - Ensure Ollama is running: `ollama serve`
516
- - Check URL in `config/jarvis.yaml` under `rag.ollama.url` (default: `http://localhost:11434`)
918
+ - Start Ollama: `ollama serve`
919
+ - Check the URL in `config/jarvis.yaml` under `rag.ollama.url` (default: `http://localhost:11434`)
517
920
 
518
921
  **Embedding model not found**
519
922
  - Pull the model: `ollama pull embeddinggemma`
520
923
  - Verify: `ollama list` should show `embeddinggemma`
521
924
 
925
+ **llama3.2 not found** (comment intent processing)
926
+ - Pull the model: `ollama pull llama3.2`
927
+
522
928
  **RAG index empty after rag-index**
523
- - Run `jarvis-healthcheck` to verify Ollama connectivity
524
- - Try full reindex: use `rag-index` tool with `clear: true`
929
+ - Run `/healthcheck` to verify Ollama connectivity
930
+ - Try full reindex: use `rag-index` with `clear=true`
525
931
 
526
932
  **Plugin not loading in OpenCode**
527
- - Verify `opencode.json` exists in your project root (or globally at `~/.config/opencode/opencode.json`)
528
- - Verify it contains `"plugin": ["@mc1global/opencode-jarvis"]`
933
+ - Verify `opencode.json` exists and contains `"plugin": ["@mc1global/opencode-jarvis"]`
529
934
  - Check `~/.cache/opencode/node_modules/` for the installed package
530
- - Ensure Bun is installed (required for production runtime)
935
+ - Run OpenCode with `--verbose` to see plugin load errors
531
936
 
532
937
  **Windows: Plugin not loading**
533
- - JARVIS must run inside WSL, not native Windows PowerShell/cmd
534
- - Install prerequisites inside WSL using `setup-wsl.sh`
938
+ - JARVIS must run inside WSL — it does not run in native Windows PowerShell or cmd
939
+ - Install prerequisites inside WSL
535
940
  - Run `opencode` from your WSL terminal
536
- - See [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl)
537
-
538
- **MCP server fails to start**
539
- - Ensure Bun is installed: `bun --version`
540
- - Run manually: `bun run src/mcp-server.ts --directory .`
941
+ - Keep project files in the WSL filesystem (`~/code/`) for best performance
942
+ - See [OpenCode Windows docs](https://opencode.ai/docs/windows-wsl)
541
943
 
542
- **Azure sync not working**
543
- - Set `organization` and `project` in `config/jarvis.yaml` under `azure-sync`
944
+ **Azure sync: authentication error**
544
945
  - Ensure Azure CLI is authenticated: `az login`
545
- - Test connectivity: use `azure-sync-config` tool
946
+ - Test connectivity: `azure-discover org="MyOrg" project="MyProject"`
947
+ - If using PAT auth: set the `AZURE_DEVOPS_PAT` environment variable
948
+
949
+ **Kanban card won't move to done**
950
+ - Check gate tasks: `kanban-gate-list card_id="CD-XXX"`
951
+ - All required gates must be met with evidence before promotion
952
+
953
+ ---
954
+
955
+ ## Configuration Reference
956
+
957
+ All settings live in `config/jarvis.yaml`. Values are deep-merged over built-in defaults — only overrides need to be present:
958
+
959
+ ```yaml
960
+ # RAG embedding settings
961
+ rag:
962
+ ollama:
963
+ url: "http://localhost:11434"
964
+ model: "embeddinggemma"
965
+ dimensions: 768
966
+ markdownSplitByHeaders: true
967
+
968
+ # Azure DevOps integration
969
+ azure-sync:
970
+ organization: ""
971
+ project: ""
972
+ repository: ""
973
+ authMethod: "az-cli" # or "pat"
974
+ pollEnabled: false
975
+ pollIntervalSecs: 60
976
+
977
+ # Kanban workflow enforcement
978
+ kanban:
979
+ minTransitionIntervalSecs: 30
980
+
981
+ # Token metrics and cost tracking
982
+ token-metrics:
983
+ sprintBudgetUsd: null # e.g. 50.0 — alerts when budget exceeded
984
+ budgetAlertThreshold: 0.8 # alert at 80% utilization
985
+
986
+ # Pipeline CI/CD
987
+ pipeline:
988
+ defaultTimeoutMs: 300000
989
+ ```
990
+
991
+ Read current config:
992
+
993
+ ```
994
+ config-read section="azure-sync"
995
+ config-read # all sections
996
+ ```
997
+
998
+ Update config:
999
+
1000
+ ```
1001
+ config-write section="azure-sync" values={"organization": "MyOrg", "project": "MyProject"}
1002
+ config-write section="token-metrics" values={"sprintBudgetUsd": 50.0}
1003
+ ```
546
1004
 
547
1005
  ---
548
1006
 
549
1007
  ## Dependencies
550
1008
 
551
- - `bun:sqlite` — Local SQLite database (Bun production runtime)
552
- - `better-sqlite3` — SQLite runtime (Node.js — tests and npm-installed production)
553
- - `js-yaml` — YAML file parsing
554
- - `vectra` — Local vector store for RAG
555
- - `ollama` — Embedding generation via local Ollama
556
- - `@langchain/textsplitters` — Code-aware text chunking for RAG
557
- - `@opencode-ai/plugin` — OpenCode plugin SDK (peer dependency)
558
- - `@modelcontextprotocol/sdk` — MCP server protocol (optional)
1009
+ | Package | Purpose |
1010
+ |---|---|
1011
+ | `better-sqlite3` | SQLite database — kanban, sessions, metrics, sync mappings |
1012
+ | `js-yaml` | YAML parsing for config and vault files |
1013
+ | `vectra` | Local vector store for RAG semantic search |
1014
+ | `ollama` | Embedding generation and LLM classification via local Ollama |
1015
+ | `@langchain/textsplitters` | Code-aware text chunking for RAG indexing |
1016
+ | `@clack/prompts` | Interactive terminal prompts |
1017
+ | `@modelcontextprotocol/sdk` | MCP protocol implementation |
1018
+ | `@opencode-ai/plugin` | OpenCode plugin SDK (peer dependency) |
559
1019
 
560
1020
  ---
561
1021