@mc1global/opencode-jarvis 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @mc1global/opencode-jarvis
 
-A native [OpenCode](https://opencode.ai) plugin providing multi-agent development infrastructure: session memory, kanban project management, governance guardrails, token metrics tracking, RAG semantic search, Obsidian vault management, domain map analysis, workspace registry, environment management, CI/CD pipelines, Azure DevOps sync, and structured data tools.
+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.
 
 Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
 
@@ -188,13 +188,14 @@ mcp-server:
 
 ## Features
 
-### 112 Tools across 13 categories
+### 113 Tools across 14 categories
 
 | Category | Count | Key Tools |
 |---|---|---|
 | **Context Memory** | 8 | `context-session-*`, `context-todo-*`, `context-note-*`, `context-search` |
 | **Kanban Cards** | 12 | `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief` |
 | **Kanban Board** | 15 | `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check` |
+| **Kanban Grooming** | 4 | `kanban-grooming-validate`, `kanban-card-scope-doc/criteria/estimate`, `kanban-card-gate` |
 | **Governance** | 2 | `governance-validate`, `governance-policies` |
 | **Token Metrics** | 7 | `metrics-record/history/agent-report/card-report/sprint-report/summary/estimate` |
 | **RAG** | 8 | `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index` |
@@ -204,9 +205,9 @@ mcp-server:
 | **Domain Map** | 2 | `domain-map-analyze`, `domain-map-view` |
 | **Workspace** | 4 | `workspace-info/list/update/link` |
 | **Environment** | 6 | `env-init/create/list/status/merge/delete` |
-| **Pipeline** | 12 | `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold` |
+| **Pipeline** | 10 | `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold` |
 | **Azure Sync** | 10 | `azure-sync-*`, `azure-pr-*` |
-| **Bootstrap** | 2 | `jarvis-bootstrap`, `jarvis-healthcheck` |
+| **Bootstrap** | 3 | `jarvis-bootstrap`, `jarvis-healthcheck`, `jarvis-terminal-commands` |
 
 ### 5 Hooks
 
@@ -249,6 +250,11 @@ kanban:
   minTransitionIntervalSecs: 30
   gateTasks:              # Per-phase gate definitions
 
+# Token metrics & cost tracking
+token-metrics:
+  sprintBudgetUsd: null         # Set a USD budget per sprint (e.g. 50.0)
+  budgetAlertThreshold: 0.8     # Alert when utilization exceeds 80%
+
 # MCP server settings
 mcp-server:
   transport: "stdio"
@@ -271,7 +277,7 @@ jarvis-plugin/
       context-memory/        # Session, Todo, Note entities + services
       kanban/                # Card state machine, Sprint, Epic, Grooming
       governance/            # 13 policy rules, validation service
-      token-metrics/         # Token usage tracking entities
+      token-metrics/         # Token usage tracking, cost-per-card/sprint, budget alerts
       rag/                   # RAG value objects, domain services
       vault/                 # Vault document, section, table entities
       domain-map/            # Bounded context detection, domain analysis
@@ -282,9 +288,9 @@ jarvis-plugin/
       config/                # Configuration value objects + defaults
     application/             # Use cases with DTOs (11 bounded contexts)
     infrastructure/          # SQLite repos, Vectra, Ollama, FS adapters
-    tools/                   # 15 tool modules (112 tools total)
+    tools/                   # 20 tool modules (113 tools total)
     hooks/                   # 5 hooks (guardrails, compacting, first-run, events, shell-env)
-    tests/                   # 2435+ tests across 80 test suites
+    tests/                   # 2,520+ tests across 85 test suites
   obsidian-vault/            # Structured documentation
   config/                    # jarvis.yaml configuration
 ```
@@ -379,7 +385,7 @@ npx tsx scripts/rag-index.ts --clear
 
 ## Test Coverage
 
-- **2,435+ tests** across 80 test suites
+- **2,520+ tests** across 85 test suites
 - Domain, application, infrastructure, and tools layers tested
 - In-memory SQLite for fast, isolated integration tests
 - `tsc --noEmit` zero errors with all strict flags

package/dist/application/bootstrap/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Re-exports the bootstrap use cases, healthcheck, types, and template generator.
  */
-export { BootstrapUseCases, generateAgentsMd, } from "./use-cases.js";
+export { BootstrapUseCases, generateAgentsMd, processConditionalBlocks, replacePlaceholders, } from "./use-cases.js";
 export type { BootstrapConfig, BootstrapResult, } from "./use-cases.js";
 export { HealthcheckUseCases } from "./healthcheck-use-cases.js";
 export type { CheckStatus, CheckResult, HealthcheckResponse, HealthcheckDeps, } from "./healthcheck-use-cases.js";

package/dist/application/bootstrap/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/bootstrap/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,YAAY,EACV,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/bootstrap/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,eAAe,EACf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,YAAY,EACV,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,kCAAkC,CAAC"}

package/dist/application/bootstrap/index.js

@@ -3,7 +3,7 @@
  *
  * Re-exports the bootstrap use cases, healthcheck, types, and template generator.
  */
-export { BootstrapUseCases, generateAgentsMd, } from "./use-cases.js";
+export { BootstrapUseCases, generateAgentsMd, processConditionalBlocks, replacePlaceholders, } from "./use-cases.js";
 export { HealthcheckUseCases } from "./healthcheck-use-cases.js";
 export { TerminalCommandsUseCases } from "./terminal-commands-use-cases.js";
 //# sourceMappingURL=index.js.map

package/dist/application/bootstrap/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/bootstrap/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AASjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/bootstrap/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AASjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/application/bootstrap/use-cases.d.ts

@@ -48,8 +48,22 @@ export declare class BootstrapUseCases {
     buildConfig(azureSyncConfig?: AzureSyncConfig): BootstrapConfig;
 }
 /**
- * Generate config-adaptive AGENTS.md content.
- * Sections for Azure DevOps, Dagger, and container-use only appear when enabled.
+ * Process conditional blocks in a template string.
+ *
+ * Syntax: `{{#IF NAME}}...content...{{/IF NAME}}`
+ * If `conditions[NAME]` is truthy, the content is kept; otherwise removed.
+ * Supports nested conditions.
+ */
+export declare function processConditionalBlocks(template: string, conditions: Record<string, boolean>): string;
+/**
+ * Replace `{{PLACEHOLDER}}` tokens with values from a variables map.
+ */
+export declare function replacePlaceholders(template: string, variables: Record<string, string>): string;
+/**
+ * Generate config-adaptive AGENTS.md content from external template.
+ *
+ * Reads `templates/agents-md.template.md`, processes conditional blocks
+ * based on config flags, and replaces placeholders with config values.
  */
 export declare function generateAgentsMd(config: BootstrapConfig): string;
 //# sourceMappingURL=use-cases.d.ts.map

package/dist/application/bootstrap/use-cases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cases.d.ts","sourceRoot":"","sources":["../../../src/application/bootstrap/use-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAI5E,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AA8DD;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;OAOG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,UAAQ,GAAG,eAAe;IAiDrF;;OAEG;IACH,WAAW,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,eAAe;CAUhE;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA4BhE"}
+{"version":3,"file":"use-cases.d.ts","sourceRoot":"","sources":["../../../src/application/bootstrap/use-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAI5E,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AA8DD;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;OAOG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,UAAQ,GAAG,eAAe;IAiDrF;;OAEG;IACH,WAAW,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,eAAe;CAUhE;AAiCD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBhE"}

package/dist/application/bootstrap/use-cases.js

@@ -8,8 +8,9 @@
  * SOLID: OCP — new sections can be added without modifying existing ones
  * SOLID: DIP — depends on ConfigService abstraction for config reading
  */
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 // ── Vault Skeleton Folders ────────────────────────────────────────────────────
 const VAULT_SKELETON_DIRS = [
     "obsidian-vault",
@@ -133,223 +134,73 @@ export class BootstrapUseCases {
         };
     }
 }
-// ── AGENTS.md Template Generator ──────────────────────────────────────────────
+// ── AGENTS.md Template Engine ─────────────────────────────────────────────────
 /**
- * Generate config-adaptive AGENTS.md content.
- * Sections for Azure DevOps, Dagger, and container-use only appear when enabled.
+ * Resolve the path to the external AGENTS.md template file.
+ *
+ * Checks three locations in order:
+ * 1. `templates/` relative to package root (npm published layout)
+ * 2. `../../templates/` relative to compiled dist/ (development via dist/)
+ * 3. `templates/` relative to CWD (fallback for local dev)
  */
-export function generateAgentsMd(config) {
-    const sections = [];
-    sections.push(SECTION_HEADER);
-    sections.push(SECTION_KANBAN_LIFECYCLE);
-    sections.push(SECTION_GUARDRAILS);
-    sections.push(SECTION_GOVERNANCE);
-    if (config.containerUseEnabled) {
-        sections.push(SECTION_CONTAINER_USE);
+function resolveTemplatePath() {
+    // Use import.meta.url to find package root relative to this compiled file.
+    // In dist: dist/application/bootstrap/use-cases.js → ../../.. = package root
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const packageRoot = join(thisDir, "..", "..", "..");
+    const candidates = [
+        join(packageRoot, "templates", "agents-md.template.md"),
+        join(thisDir, "..", "..", "..", "templates", "agents-md.template.md"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
     }
-    if (config.azureSyncEnabled) {
-        sections.push(generateAzureSyncSection(config));
-    }
-    if (config.pipelineEnabled) {
-        sections.push(SECTION_PIPELINE_DAGGER);
+    // Should never happen in a correctly installed package
+    throw new Error(`AGENTS.md template not found. Searched: ${candidates.join(", ")}`);
+}
+/**
+ * Process conditional blocks in a template string.
+ *
+ * Syntax: `{{#IF NAME}}...content...{{/IF NAME}}`
+ * If `conditions[NAME]` is truthy, the content is kept; otherwise removed.
+ * Supports nested conditions.
+ */
+export function processConditionalBlocks(template, conditions) {
+    // Process from innermost to outermost by iterating until stable.
+    let result = template;
+    let previous = "";
+    while (result !== previous) {
+        previous = result;
+        result = result.replace(/\{\{#IF (\w+)\}\}\n?([\s\S]*?)\{\{\/IF \1\}\}\n?/g, (_match, name, content) => conditions[name] ? content : "");
     }
-    sections.push(SECTION_VAULT);
-    sections.push(SECTION_GIT_STRATEGY);
-    sections.push(SECTION_CONFIG_SYSTEM);
-    sections.push(SECTION_TOOL_QUICK_REFERENCE);
-    sections.push(SECTION_SKILLS_AND_COMMANDS);
-    sections.push(SECTION_RAG_ORACLE);
-    return sections.join("\n\n") + "\n";
+    return result;
 }
-// ── Static Sections ───────────────────────────────────────────────────────────
-const SECTION_HEADER = `# AGENTS.md — JARVIS Plugin Operational Guide
-
-This file instructs agentic coding agents operating in this repository.
-JARVIS is an OpenCode plugin implementing a multi-agent development framework
-with kanban governance, context memory, and CI/CD pipeline support.`;
-const SECTION_KANBAN_LIFECYCLE = `## Mandatory Workflow — Kanban Lifecycle
-
-ALL non-trivial work (>15 minutes) MUST follow the full kanban pipeline.
-Do NOT skip steps. Do NOT commit directly to \`main\`.
-
-\`\`\`
-backlog -> grooming -> ready -> doing -> review -> tested -> done
-\`\`\`
-
-### Before coding anything:
-
-1. **Create or pick a card** — \`kanban-card-create\`, assign to epic and sprint
-2. **Groom it** — Write a scope doc in \`obsidian-vault/12-Scope-Docs/\`, define
-   acceptance criteria (min 2), estimate story points (Fibonacci), assign epic
-3. **Move to ready** — Card cannot leave grooming without: scope doc, AC, points, epic
-4. **Assign agent + sprint** — Then move to \`doing\`
-5. **Start a session** — \`context-session-start\` before any card work
-
-### Grooming rules — CRITICAL:
-
-Grooming defines **problem, value, and boundaries**. It does NOT prescribe
-implementation details (no class names, method signatures, field names, code
-snippets). The implementing agent decides those during the \`doing\` phase.
-
-### After coding:
-
-6. **Run tests + linter** — All must pass, zero errors
-7. **Commit** — Imperative mood, reference card: \`Add X (CD-XXX)\` or \`Fix Y (CD-XXX)\`
-8. **Move card** — \`doing -> review -> tested -> done\`, meet all AC and gate tasks first
-9. **Update vault** — Dashboard + domain reference doc at end of every phase`;
-const SECTION_GUARDRAILS = `## Guardrails — Hard Rules
-
-### NEVER:
-- Use fallback/mock behavior to mask errors — errors must throw with proper handling
-- Use a "simpler approach" to bypass the real solution
-- Read \`.csv\` directly — use \`data-csv-query\` tool
-- Read \`.yaml/.yml\` directly — use \`data-yaml-get\` tool
-- Read \`.env\`, \`.pem\`, \`.key\`, credentials files — blocked by governance
-- Run \`git push --force\` on main/master
-- Run \`sqlite3\` CLI — use repository methods
-- Create \`TODO.md\`, \`PLAN.md\`, or \`ROADMAP.md\` — use kanban tools
-- Bypass the kanban pipeline for trackable work
-- Push to git without explicit user approval
-- Start the app from the agent session — ask the user to do it in another terminal
-
-### ALWAYS:
-- Search RAG (\`rag-search\` / \`rag-snippet\`) before creating or modifying files
-- Use specialized tools instead of raw file operations
-- Get full codebase context before making changes — ask if unclear
-- Validate card status transitions through the kanban domain
-- Track context with sessions, TODOs, and notes`;
-const SECTION_GOVERNANCE = `## Governance Policies (Runtime Enforced)
-
-Governance policies are evaluated by the \`tool.execute.before\` hook on every
-tool invocation. Violations with \`error\` severity throw and block execution.
-These cover: CSV/YAML/env file access, force push, direct SQLite CLI,
-destructive shell ops, credential file reads.
-
-Use \`governance-validate\` to pre-check if an operation is allowed.
-Use \`governance-policies\` to list all active policies.`;
-const SECTION_CONTAINER_USE = `## Container-Use Environments
-
-Container-use environments are isolated containers with their own git worktree
-branches. Use them for all file, code, and shell operations.
-
-Workflow:
-1. \`env-init\` — Detect project stack
-2. \`env-create\` — Spin up container from git ref
-3. Work inside container via \`container-use_environment_*\` tools
-4. \`env-merge\` — Merge branch back to main
-5. \`env-delete\` — Clean up container + worktree
-
-IMPORTANT: Always inform the user how to view your work using
-\`container-use log <env_id>\` and \`container-use checkout <env_id>\`.
-
-Do NOT install or use the git CLI with \`environment_run_cmd\`. All environment
-tools handle git operations automatically.`;
-const SECTION_PIPELINE_DAGGER = `## CI/CD Pipelines (Dagger)
-
-Pipeline BC uses Dagger for CI/CD gate execution. Pipelines are created from
-stack templates (typescript-lib, python-app, etc.) and run gates in containers.
-
-Workflow:
-1. \`pipeline-init\` — Create pipeline from stack template
-2. \`pipeline-activate\` — Make pipeline runnable
-3. \`pipeline-run\` — Execute gates via Dagger
-4. \`pipeline-gate\` — Manual pass/fail/skip/retry for gates
-5. \`pipeline-status\` — View pipeline state and gate results
-
-Templates available via \`pipeline-template\` tool.
-Scaffold Dagger modules via \`pipeline-scaffold\` tool.`;
-const SECTION_VAULT = `## Obsidian Vault
-
-Documentation lives in \`obsidian-vault/\`. Use structured lists, NOT markdown
-tables (token efficiency). Update at end of every phase:
-
-- \`09-Dashboards/\` — Project dashboards and metrics
-- \`11-Domain-Reference/\` — Per-context architecture docs
-- \`12-Scope-Docs/CD-XXX-*.md\` — Grooming scope documents
-
-Use \`vault-manage\` tool for smart vault operations (inspect, read, write, create,
-search, table-read, table-update).`;
-const SECTION_GIT_STRATEGY = `## Git Strategy
-
-- Work on feature branches (never commit directly to \`main\`)
-- Commit messages: imperative verb + summary + card reference
-  - \`Add feature X (CD-001)\`
-  - \`Fix bug Y (CD-015)\`
-- Merge via PR or controlled merge
-- Never amend pushed commits without explicit request
-- Never push without explicit user approval`;
-const SECTION_CONFIG_SYSTEM = `## Configuration System
-
-\`config/jarvis.yaml\` holds tunable settings per bounded context. The ConfigService
-deep-merges YAML overrides over hardcoded defaults. Access config via the
-appropriate getter methods — never read YAML files directly.`;
-const SECTION_TOOL_QUICK_REFERENCE = `## Tool Quick Reference (112 tools)
-
-JARVIS provides 112 tools across 11 bounded contexts. Key tool groups:
-
-- **Context Memory** (8): \`context-session-start\`, \`context-session-finish\`, \`context-todo-add\`, \`context-note-add\`, \`context-search\`...
-- **Kanban** (31): \`kanban-card-create\`, \`kanban-card-move\`, \`kanban-board-view\`, \`kanban-sprint-create\`, \`kanban-epic-create\`...
-- **Governance** (2): \`governance-validate\`, \`governance-policies\`
-- **Token Metrics** (7): \`metrics-summary\`, \`metrics-agent-report\`, \`metrics-card-report\`...
-- **Vault** (11): \`vault-manage\` (smart facade), \`vault-doc-create\`, \`vault-doc-search\`...
-- **RAG** (8): \`rag-search\`, \`rag-snippet\`, \`rag-index\`, \`rag-oracle-search\`, \`rag-oracle-index\`...
-- **Data** (3): \`data-yaml-get\`, \`data-json-get\`, \`data-csv-query\`
-- **Agent** (8): \`agent-sessions\`, \`agent-send\`, \`agent-spawn\`, \`agent-dispatch\`...
-- **Pipeline** (10): \`pipeline-init\`, \`pipeline-run\`, \`pipeline-status\`...
-- **Environment** (6): \`env-create\`, \`env-status\`, \`env-merge\`, \`env-delete\`...
-- **Workspace** (4): \`workspace-info\`, \`workspace-list\`, \`workspace-update\`, \`workspace-link\`
-- **Bootstrap** (2): \`jarvis-bootstrap\`, \`jarvis-healthcheck\`
-
-For detailed workflows, load the appropriate skill (see below).`;
-const SECTION_SKILLS_AND_COMMANDS = `## Available Skills
-
-Load skills via the \`skill()\` tool to get detailed workflow instructions:
-
-- **\`jarvis-kanban\`** — Full kanban lifecycle: card creation, grooming, sprint management, gate tasks
-- **\`jarvis-azure-sync\`** — Azure DevOps sync: push/pull/bidi-sync, PR creation, poll events
-- **\`jarvis-onboarding\`** — Setup, healthcheck, RAG indexing, tool group reference
-
-### Available Commands
-
-Use these slash commands for common operations:
-
-- **\`/healthcheck\`** — Run diagnostics and get actionable fix guidance
-- **\`/sync-azure\`** — Execute Azure DevOps sync workflow
-- **\`/start-card CD-XXX\`** — Start working on a specific card (handles full lifecycle)
-
-When you encounter an unfamiliar workflow, ALWAYS load the relevant skill first.`;
-const SECTION_RAG_ORACLE = `## Knowledge Search — RAG & ORACLE
-
-Before creating or modifying code, ALWAYS search first:
-
-- **\`rag-search\`** / **\`rag-snippet\`** — Search the codebase semantically
-- **\`rag-oracle-search\`** — Search curated framework documentation (governance, workflows, patterns)
-
-When you don't know how to do something, search ORACLE:
-\`\`\`
-rag-oracle-search  query="how to sync azure devops"
-rag-oracle-search  query="kanban grooming requirements"  domain="workflows"
-\`\`\`
-
-ORACLE domains: \`governance\`, \`workflows\`, \`patterns\`, \`quick_reference\`.`;
-// ── Dynamic Sections ──────────────────────────────────────────────────────────
-function generateAzureSyncSection(config) {
-    return `## Azure DevOps Integration
-
-This project is connected to Azure DevOps (${config.azureOrg}/${config.azureProject}).
-
-Available tools:
-- \`azure-sync-discover\` — Detect project template, list work items + iterations
-- \`azure-sync-push\` — Push cards/epics/sprints to Azure DevOps
-- \`azure-sync-pull\` — Pull work items from Azure DevOps
-- \`azure-sync-sync\` — Bidirectional sync (push then pull)
-- \`azure-sync-status\` — Show sync status between local and Azure
-- \`azure-sync-config\` — Show configuration + test connectivity
-- \`azure-sync-events\` — List/acknowledge/dismiss detected change events
-- \`azure-pr-create\` — Create Pull Request in Azure Repos
-- \`azure-pr-list\` — List Pull Requests
-
-Poll service can be enabled in \`config/jarvis.yaml\` under \`azure-sync.pollEnabled\`
-to automatically detect changes made by team members in Azure DevOps.`;
+/**
+ * Replace `{{PLACEHOLDER}}` tokens with values from a variables map.
+ */
+export function replacePlaceholders(template, variables) {
+    return template.replace(/\{\{([A-Z_]+)\}\}/g, (_match, name) => variables[name] ?? `{{${name}}}`);
+}
+/**
+ * Generate config-adaptive AGENTS.md content from external template.
+ *
+ * Reads `templates/agents-md.template.md`, processes conditional blocks
+ * based on config flags, and replaces placeholders with config values.
+ */
+export function generateAgentsMd(config) {
+    const templatePath = resolveTemplatePath();
+    const raw = readFileSync(templatePath, "utf-8");
+    const conditions = {
+        AZURE_SYNC: config.azureSyncEnabled,
+        PIPELINE: config.pipelineEnabled,
+        CONTAINER_USE: config.containerUseEnabled,
+    };
+    const variables = {
+        AZURE_ORG: config.azureOrg,
+        AZURE_PROJECT: config.azureProject,
+    };
+    const afterConditions = processConditionalBlocks(raw, conditions);
+    return replacePlaceholders(afterConditions, variables);
 }
 //# sourceMappingURL=use-cases.js.map

package/dist/application/bootstrap/use-cases.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-cases.js","sourceRoot":"","sources":["../../../src/application/bootstrap/use-cases.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-cases.js","sourceRoot":"","sources":["../../../src/application/bootstrap/use-cases.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mc1global/opencode-jarvis",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "JARVIS Framework - OpenCode native plugin for multi-agent development with DDD architecture",
   "author": "Julio Fabio de O. Chagas <julio.fabio@mc1global.com>",
   "license": "SEE LICENSE IN LICENSE",
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist/",
+    "templates/",
     "LICENSE",
     "README.md",
     "QUICK-GUIDE.md"

package/templates/agents-md.template.md

@@ -0,0 +1,232 @@
+# AGENTS.md — JARVIS Plugin Operational Guide
+
+This file instructs agentic coding agents operating in this repository.
+JARVIS is an OpenCode plugin implementing a multi-agent development framework
+with kanban governance, context memory, automatic cost tracking, and CI/CD
+pipeline support.
+
+## Architecture Constraints — Inviolable
+
+- **SOLID Principles** — Every class/module must strictly respect all 5 principles
+- **Domain-Driven Design** — Domain layer has ZERO external dependencies. Repository
+  interfaces in domain, implementations in infrastructure
+- **Max 500 lines per file** — No exceptions. Split by responsibility if approaching limit
+- **ESM modules** — `"type": "module"` required by `@opencode-ai/plugin`
+- **Strict TypeScript** — `exactOptionalPropertyTypes`, `verbatimModuleSyntax`,
+  `noUncheckedIndexedAccess` all enabled
+- **13 bounded contexts** with strict DDD boundaries — no direct imports between contexts
+- **Cross-context communication** via ports/callbacks wired at composition root
+
+## Mandatory Workflow — Kanban Lifecycle
+
+ALL non-trivial work (>15 minutes) MUST follow the full kanban pipeline.
+Do NOT skip steps. Do NOT commit directly to `main`.
+
+```
+backlog -> grooming -> ready -> doing -> review -> tested -> done
+```
+
+### Before coding anything:
+
+1. **Create or pick a card** — `kanban-card-create`, assign to epic and sprint
+2. **Groom it** — Write a scope doc in `obsidian-vault/12-Scope-Docs/`, define
+   acceptance criteria (min 2), estimate story points (Fibonacci), assign epic
+3. **Move to ready** — Card cannot leave grooming without: scope doc, AC, points, epic
+4. **Assign agent + sprint** — Then move to `doing`
+5. **Start a session** — `context-session-start` before any card work
+
+### Grooming rules — CRITICAL:
+
+Grooming defines **problem, value, and boundaries**. It does NOT prescribe
+implementation details (no class names, method signatures, field names, code
+snippets). The implementing agent decides those during the `doing` phase.
+
+### After coding:
+
+6. **Run tests + linter** — All must pass, zero errors
+7. **Commit** — Imperative mood, reference card: `Add X (CD-XXX)` or `Fix Y (CD-XXX)`
+8. **Move card** — `doing -> review -> tested -> done`, meet all AC and gate tasks first
+9. **Update vault** — Dashboard + domain reference doc at end of every phase
+
+## Guardrails — Hard Rules
+
+### NEVER:
+- Use fallback/mock behavior to mask errors — errors must throw with proper handling
+- Use a "simpler approach" to bypass the real solution
+- Read `.csv` directly — use `data-csv-query` tool
+- Read `.yaml/.yml` directly — use `data-yaml-get` tool
+- Read `.env`, `.pem`, `.key`, credentials files — blocked by governance
+- Run `git push --force` on main/master
+- Run `sqlite3` CLI — use repository methods
+- Create `TODO.md`, `PLAN.md`, or `ROADMAP.md` — use kanban tools
+- Bypass the kanban pipeline for trackable work
+- Push to git without explicit user approval
+- Start the app from the agent session — ask the user to do it in another terminal
+- Skip grooming requirements or gate tasks for cards
+- Import directly between bounded contexts — use ports/callbacks
+
+### ALWAYS:
+- Search RAG (`rag-search` / `rag-snippet`) before creating or modifying files
+- Use specialized tools instead of raw file operations
+- Get full codebase context before making changes — ask if unclear
+- Validate card status transitions through the kanban domain
+- Track context with sessions, TODOs, and notes
+- Meet all gate tasks before moving cards through review/tested/done
+
+## Governance Policies (13 Runtime Enforced)
+
+Governance policies are evaluated by the `tool.execute.before` hook on every
+tool invocation. Violations with `error` severity throw and block execution.
+
+Policy groups:
+- **File access** — Block direct CSV, YAML, env file reads (use specialized tools)
+- **Shell safety** — Block force push, direct SQLite CLI, warn on destructive ops
+- **Security** — Block env dump, sensitive file reads, credential file access
+- **Pipeline** — Warn when running pipeline without linked card
+- **Kanban** — Require gate tasks before status transitions, warn on rapid transitions
+
+Use `governance-validate` to pre-check if an operation is allowed.
+Use `governance-policies` to list all active policies.
+
+{{#IF CONTAINER_USE}}
+## Container-Use Environments
+
+Container-use environments are isolated containers with their own git worktree
+branches. Use them for all file, code, and shell operations.
+
+Workflow:
+1. `env-init` — Detect project stack
+2. `env-create` — Spin up container from git ref
+3. Work inside container via `container-use_environment_*` tools
+4. `env-merge` — Merge branch back to main
+5. `env-delete` — Clean up container + worktree
+
+IMPORTANT: Always inform the user how to view your work using
+`container-use log <env_id>` and `container-use checkout <env_id>`.
+
+Do NOT install or use the git CLI with `environment_run_cmd`. All environment
+tools handle git operations automatically.
+{{/IF CONTAINER_USE}}
+
+{{#IF AZURE_SYNC}}
+## Azure DevOps Integration
+
+This project is connected to Azure DevOps ({{AZURE_ORG}}/{{AZURE_PROJECT}}).
+
+Available tools:
+- `azure-sync-discover` — Detect project template, list work items + iterations
+- `azure-sync-push` — Push cards/epics/sprints to Azure DevOps
+- `azure-sync-pull` — Pull work items from Azure DevOps
+- `azure-sync-sync` — Bidirectional sync (push then pull)
+- `azure-sync-status` — Show sync status between local and Azure
+- `azure-sync-config` — Show configuration + test connectivity
+- `azure-sync-events` — List/acknowledge/dismiss detected change events
+- `azure-sync-poll-status` — Show background poll service status
+- `azure-pr-create` — Create Pull Request in Azure Repos
+- `azure-pr-list` — List Pull Requests
+
+Poll service can be enabled in `config/jarvis.yaml` under `azure-sync.pollEnabled`
+to automatically detect changes made by team members in Azure DevOps.
+{{/IF AZURE_SYNC}}
+
+{{#IF PIPELINE}}
+## CI/CD Pipelines (Dagger)
+
+Pipeline BC uses Dagger for CI/CD gate execution. Pipelines are created from
+stack templates (typescript-lib, python-app, etc.) and run gates in containers.
+
+Workflow:
+1. `pipeline-init` — Create pipeline from stack template
+2. `pipeline-activate` — Make pipeline runnable
+3. `pipeline-run` — Execute gates via Dagger
+4. `pipeline-gate` — Manual pass/fail/skip/retry for gates
+5. `pipeline-status` — View pipeline state and gate results
+
+Templates available via `pipeline-template` tool.
+Scaffold Dagger modules via `pipeline-scaffold` tool.
+{{/IF PIPELINE}}
+
+## Obsidian Vault
+
+Documentation lives in `obsidian-vault/`. Use structured lists, NOT markdown
+tables (token efficiency). Update at end of every phase:
+
+- `09-Dashboards/` — Project dashboards and metrics
+- `11-Domain-Reference/` — Per-context architecture docs
+- `12-Scope-Docs/CD-XXX-*.md` — Grooming scope documents
+
+Use `vault-manage` tool for smart vault operations (inspect, read, write, create,
+search, table-read, table-update).
+
+## Git Strategy
+
+- Work on feature branches (never commit directly to `main`)
+- Commit messages: imperative verb + summary + card reference
+  - `Add feature X (CD-001)`
+  - `Fix bug Y (CD-015)`
+- Merge via PR or controlled merge
+- Never amend pushed commits without explicit request
+- Never push without explicit user approval
+
+## Configuration System
+
+`config/jarvis.yaml` holds tunable settings per bounded context. The ConfigService
+deep-merges YAML overrides over hardcoded defaults. Access config via the
+appropriate getter methods — never read YAML files directly.
+
+Available config sections: `rag`, `azure-sync`, `kanban`, `mcp-server`,
+`pipeline`, `token-metrics` (with `sprintBudgetUsd` and `budgetAlertThreshold`).
+
+## Tool Quick Reference (113 tools)
+
+JARVIS provides 113 tools across 13 bounded contexts. Key tool groups:
+
+- **Context Memory** (8): `context-session-start`, `context-session-finish`, `context-todo-add`, `context-note-add`, `context-search`...
+- **Kanban** (31): `kanban-card-create`, `kanban-card-move`, `kanban-board-view`, `kanban-sprint-create`, `kanban-epic-create`, `kanban-grooming-validate`, `kanban-card-gate`...
+- **Governance** (2): `governance-validate`, `governance-policies`
+- **Token Metrics** (7): `metrics-summary`, `metrics-agent-report`, `metrics-card-report`, `metrics-sprint-report`, `metrics-estimate`... (auto-tracks cost per card/sprint)
+- **Vault** (11): `vault-manage` (smart facade), `vault-doc-create`, `vault-doc-search`...
+- **RAG** (8): `rag-search`, `rag-snippet`, `rag-index`, `rag-oracle-search`, `rag-oracle-index`...
+- **Data** (3): `data-yaml-get`, `data-json-get`, `data-csv-query`
+- **Agent** (8): `agent-sessions`, `agent-send`, `agent-spawn`, `agent-dispatch`, `agent-register`, `agent-profile`...
+- **Pipeline** (10): `pipeline-init`, `pipeline-run`, `pipeline-status`, `pipeline-template`, `pipeline-scaffold`...
+- **Environment** (6): `env-init`, `env-create`, `env-list`, `env-status`, `env-merge`, `env-delete`
+- **Workspace** (4): `workspace-info`, `workspace-list`, `workspace-update`, `workspace-link`
+- **Azure Sync** (10): `azure-sync-discover`, `azure-sync-push`, `azure-sync-pull`, `azure-sync-sync`, `azure-pr-create`...
+- **Bootstrap** (3): `jarvis-bootstrap`, `jarvis-healthcheck`, `jarvis-terminal-commands`
+- **Domain Map** (2): `domain-map-analyze`, `domain-map-view`
+
+For detailed workflows, load the appropriate skill (see below).
+
+## Available Skills
+
+Load skills via the `skill()` tool to get detailed workflow instructions:
+
+- **`jarvis-kanban`** — Full kanban lifecycle: card creation, grooming, sprint management, gate tasks
+- **`jarvis-azure-sync`** — Azure DevOps sync: push/pull/bidi-sync, PR creation, poll events
+- **`jarvis-onboarding`** — Setup, healthcheck, RAG indexing, tool group reference
+
+### Available Commands
+
+Use these slash commands for common operations:
+
+- **`/healthcheck`** — Run diagnostics and get actionable fix guidance
+- **`/sync-azure`** — Execute Azure DevOps sync workflow
+- **`/start-card CD-XXX`** — Start working on a specific card (handles full lifecycle)
+
+When you encounter an unfamiliar workflow, ALWAYS load the relevant skill first.
+
+## Knowledge Search — RAG & ORACLE
+
+Before creating or modifying code, ALWAYS search first:
+
+- **`rag-search`** / **`rag-snippet`** — Search the codebase semantically
+- **`rag-oracle-search`** — Search curated framework documentation (governance, workflows, patterns)
+
+When you don't know how to do something, search ORACLE:
+```
+rag-oracle-search  query="how to sync azure devops"
+rag-oracle-search  query="kanban grooming requirements"  domain="workflows"
+```
+
+ORACLE domains: `governance`, `workflows`, `patterns`, `quick_reference`.