opencode-gitlab-dap 1.16.5 → 1.16.6

package/README.md

@@ -1,4 +1,4 @@
-# opencode-gitlab-dap
+# OpenCode GitLab Duo Agent Platform Plugin
 
 An [opencode](https://opencode.ai) plugin for the [GitLab Duo Agent Platform (DAP)](https://docs.gitlab.com/user/duo_agent_platform/).
 Discovers agents and flows from the GitLab AI Catalog, injects them into opencode,
@@ -39,6 +39,12 @@ On startup, the plugin discovers all agents and flows enabled for your project:
 - Agents appear in `/agents` dialog and Tab agent picker
 - Flows appear in the `@` mention menu as subagents
 
+**Use cases:**
+
+- **Switch to a specialized agent mid-conversation** — press Tab or open `/agents` to pick a Data Analyst, Security Analyst, or any custom agent enabled for your project
+- **Discover what automation is available** — browse the `@` menu to see all flows your project has access to, including both foundational and custom flows
+- **Use foundational agents for specialized tasks** — switch to the Planner agent for project planning, or the Security Analyst for vulnerability assessment, without any setup
+
 ### Flow Execution via `@` Menu
 
 Type `@Flow Name` followed by your goal to execute a flow:
@@ -56,6 +62,14 @@ The plugin:
 5. Executes the flow via `POST /api/v4/ai/duo_workflows/workflows`
 6. Monitors workflow status and reports the workflow URL for tracking in GitLab UI
 
+**Use cases:**
+
+- **Trigger a code review** — `@Code Review 🦊 review MR !42` to get automated code review feedback on a specific merge request
+- **Fix a broken pipeline** — `@Fix CI/CD Pipeline diagnose and fix the failing pipeline on branch feature/auth` to get automated pipeline diagnosis
+- **Resolve a security vulnerability** — `@Security Vulnerability Fix fix vulnerability #123` to get an automated fix generated and pushed as an MR
+- **Generate test coverage** — `@Auto Fix generate tests for the UserService class` to get unit tests created automatically
+- **Natural language goal resolution** — describe what you want in plain English and the plugin resolves it to the exact parameter the flow needs (e.g., "MR !12" → IID `12`)
+
 ### Parallel Multi-Flow Dispatch
 
 Mention multiple flows in a single message to execute them simultaneously:
@@ -73,6 +87,13 @@ When multiple flows are mentioned:
 
 The `experimental.chat.system.transform` hook injects system prompt guidelines that instruct the main agent on how to handle multi-flow and batch dispatch scenarios.
 
+**Use cases:**
+
+- **Run security and code review simultaneously** — `@AppSec Security MR Reviewer @Code Review 🦊 review MR !42` to get both security analysis and code quality feedback in parallel
+- **Batch review all open MRs** — `@Code Review 🦊 review all open MRs` to dispatch one flow execution per open MR, all running concurrently
+- **Multi-flow batch operations** — combine multiple flows with "for each" semantics: the plugin lists all matching resources, then dispatches N flows × M resources in parallel
+- **Reduce wait time with concurrency** — instead of running flows one by one, mention them all at once for simultaneous execution with a single summary at the end
+
 ### Custom Agent Creation
 
 Create custom agents interactively:
@@ -91,6 +112,14 @@ The plugin guides you through an interactive workflow:
 
 The `confirmed` parameter on `gitlab_create_agent` enforces the interactive workflow — the tool returns instructions instead of creating the agent when called without explicit confirmation.
 
+**Use cases:**
+
+- **Build a domain-specific assistant** — create an agent with a system prompt tuned to your team's domain (e.g., payments, infrastructure, data pipelines) and the relevant tools
+- **Create a creative writing agent** — build an agent that responds in a specific format (poems, haiku, bullet points) for fun or specialized output needs
+- **Set up a security-focused reviewer** — create an agent with security scanning tools and a system prompt that emphasizes OWASP, CVE checks, and secure coding practices
+- **Connect an agent to external services** — assign MCP servers to an agent so it can interact with third-party APIs and services during conversations
+- **Share agents across your organization** — create a public agent in the AI Catalog that any project in your GitLab instance can enable and use
+
 ### Custom Flow Creation
 
 Design and create custom flows interactively:
@@ -110,40 +139,91 @@ The plugin provides a multi-round design workflow:
 
 The vendored `flow_v2.json` schema from GitLab Rails powers client-side validation using `ajv`, catching errors before hitting the API.
 
+**Use cases:**
+
+- **Automate MR summarization** — create a flow that fetches MR diffs, analyzes the changes, and posts a summary comment with key observations
+- **Build a deployment checklist flow** — design a multi-step flow that verifies prerequisites, runs pre-deployment checks, and triggers deployment
+- **Create a release notes generator** — build a flow that collects commits since the last tag, categorizes changes, and generates formatted release notes
+- **Design a conditional flow with routing** — create a flow with branching logic (e.g., different review steps based on file types changed in the MR)
+- **Validate flow definitions before submission** — catch YAML schema errors locally before hitting the GitLab API, reducing back-and-forth during flow development
+- **Iterate on flow design interactively** — use the multi-round design workflow to refine component architecture and step definitions with guided assistance
+
 ### 35 Tools
 
 #### DAP Tools (20)
 
+##### Flow Execution
+
+| Tool                          | Description                                |
+| ----------------------------- | ------------------------------------------ |
+| `gitlab_execute_project_flow` | Execute a flow via DWS REST API            |
+| `gitlab_get_flow_definition`  | Get flow YAML config (inputs, components)  |
+| `gitlab_get_workflow_status`  | Monitor workflow execution status and logs |
+
+**Use cases:**
+
+- **Run a code review flow on a merge request** — trigger the "Code Review" flow for a specific MR to get automated review feedback posted as comments
+- **Fix a failing CI/CD pipeline** — execute the "Fix CI/CD Pipeline" flow with the pipeline URL to get automated diagnosis and fix suggestions
+- **Batch-execute flows across multiple MRs** — run a security review flow on all open MRs simultaneously by listing resources first, then dispatching N flows in parallel
+- **Inspect flow requirements before execution** — use `gitlab_get_flow_definition` to check what inputs a flow expects (e.g., `merge_request_iid`, `pipeline_url`, `vulnerability_id`) before triggering it
+- **Monitor long-running workflows** — poll `gitlab_get_workflow_status` to track progress, retrieve the agent conversation log, and get the GitLab UI URL for the workflow session
+- **Debug flow execution failures** — check workflow status messages to understand where a flow failed and what the agent attempted
+
+##### Catalog CRUD
+
 | Tool                              | Description                                             |
 | --------------------------------- | ------------------------------------------------------- |
-| `gitlab_list_agents`              | Search agents in the global AI Catalog                  |
-| `gitlab_get_agent`                | Get agent details by ID                                 |
-| `gitlab_list_project_agents`      | List agents enabled for a project                       |
-| `gitlab_enable_project_agent`     | Enable an agent in a project                            |
-| `gitlab_disable_project_agent`    | Disable an agent in a project                           |
 | `gitlab_create_agent`             | Create a custom agent (interactive, confirmation-gated) |
 | `gitlab_update_agent`             | Update an existing custom agent                         |
 | `gitlab_list_builtin_tools`       | List available built-in tools for agent/flow config     |
 | `gitlab_design_flow`              | Interactive flow design + YAML validation               |
 | `gitlab_create_flow`              | Create a custom flow (confirmation-gated)               |
 | `gitlab_update_flow`              | Update an existing custom flow                          |
-| `gitlab_list_flows`               | Search flows in the global AI Catalog                   |
-| `gitlab_get_flow`                 | Get flow details by ID                                  |
-| `gitlab_list_project_flows`       | List flows enabled for a project                        |
-| `gitlab_enable_project_flow`      | Enable a flow in a project                              |
-| `gitlab_disable_project_flow`     | Disable a flow in a project                             |
-| `gitlab_execute_project_flow`     | Execute a flow via DWS REST API                         |
-| `gitlab_get_flow_definition`      | Get flow YAML config (inputs, components)               |
-| `gitlab_get_workflow_status`      | Monitor workflow execution status and logs              |
 | `gitlab_list_project_mcp_servers` | List MCP servers available for project agents           |
 
-#### Project Knowledge Tools (11)
+**Use cases:**
+
+- **Create a project-specific code reviewer agent** — interactively define a custom agent with a tailored system prompt, assign it the MR and code search tools, and connect it to your project's MCP servers
+- **Build a team-specific incident responder agent** — create an agent with security scanning tools and a system prompt tuned to your team's runbooks and escalation procedures
+- **Design a custom flow from scratch** — use `gitlab_design_flow` to get the YAML schema reference and examples, propose a component architecture, validate the YAML client-side, and submit it
+- **Create a vulnerability triage flow** — design a multi-step flow that fetches vulnerability details, evaluates severity, and posts remediation guidance
+- **Iterate on an agent's system prompt** — use `gitlab_update_agent` to refine the prompt after testing, bump the version, and release
+- **Add MCP servers to an existing agent** — discover available MCP servers with `gitlab_list_project_mcp_servers`, then update the agent to include them
+- **Validate flow YAML before submission** — catch schema errors locally with `gitlab_design_flow(action="validate")` before hitting the API
+- **Discover available tools for agent configuration** — use `gitlab_list_builtin_tools` to see all tool categories (search, issues, MRs, epics, files, git, CI/CD, security, audit, planning, wiki)
+
+##### Catalog Item Management
+
+| Tool                           | Description                            |
+| ------------------------------ | -------------------------------------- |
+| `gitlab_list_agents`           | Search agents in the global AI Catalog |
+| `gitlab_get_agent`             | Get agent details by ID                |
+| `gitlab_list_project_agents`   | List agents enabled for a project      |
+| `gitlab_enable_project_agent`  | Enable an agent in a project           |
+| `gitlab_disable_project_agent` | Disable an agent in a project          |
+| `gitlab_list_flows`            | Search flows in the global AI Catalog  |
+| `gitlab_get_flow`              | Get flow details by ID                 |
+| `gitlab_list_project_flows`    | List flows enabled for a project       |
+| `gitlab_enable_project_flow`   | Enable a flow in a project             |
+| `gitlab_disable_project_flow`  | Disable a flow in a project            |
+
+**Use cases:**
+
+- **Browse the AI Catalog for useful agents** — search the global catalog by name or description to discover agents built by other teams or the community
+- **Set up a new project with standard agents** — enable your organization's standard set of agents and flows on a newly created project
+- **Audit which agents are enabled** — list all agents and flows enabled for a project to verify compliance with team standards or security policies
+- **Enable a flow after creation** — after creating a custom flow, enable it on your project so it appears in the `@` mention menu
+- **Disable a misbehaving flow** — temporarily disable a flow that is producing incorrect results while you debug and update its definition
+- **Inspect agent details before enabling** — check an agent's creator, version, description, and permissions before adding it to your project
+- **Find the consumer ID for flow execution** — list project flows to retrieve the consumer ID required by `gitlab_execute_project_flow`
+
+#### Project Knowledge Tools (15)
 
 Persistent project memory and reusable skills. Knowledge is stored in GitLab project/group wikis but tools abstract the storage — the agent works with facts, decisions, patterns, and skills.
 
 Say **"bootstrap project memory"** to automatically inspect a project and build its knowledge base. If memory already exists, it does a smart refresh — updating stale facts and archiving outdated entries.
 
-##### Memory Tools
+##### Memory Tools (7)
 
 | Tool                        | Description                                                     |
 | --------------------------- | --------------------------------------------------------------- |
@@ -155,7 +235,24 @@ Say **"bootstrap project memory"** to automatically inspect a project and build
 | `gitlab_memory_recall`      | Search project knowledge for relevant information               |
 | `gitlab_memory_log_session` | Log a session summary with learnings                            |
 
-##### Skill Tools
+**Use cases:**
+
+- **Bootstrap project knowledge from scratch** — run "bootstrap project memory" to inspect README, issues, MRs, pipelines, and team members, then record everything as structured facts, architecture, conventions, and people entries
+- **Preserve context across sessions** — record facts about tech stack, dependencies, and deployment targets so future sessions start with full context instead of re-exploring
+- **Document architectural decisions with reasoning** — record why the team chose PostgreSQL over MySQL, or React over Vue, with full rationale for future reference
+- **Track recurring patterns** — record observations like "CI pipelines fail on Mondays due to cache expiry" or "test suite is flaky on the `payments` module" so they aren't rediscovered each time
+- **Maintain a living architecture document** — record and update system design, module structure, data flow, and key abstractions as the codebase evolves
+- **Codify coding conventions** — record naming patterns, commit message formats, review processes, and coding standards so the agent follows them consistently
+- **Document known issues and workarounds** — record troubleshooting steps for common errors so the agent can suggest solutions without investigation
+- **Track team roles and ownership** — record who owns which modules, who to contact for specific subsystems, and team members' areas of expertise
+- **Record implementation plans** — document feature designs, task breakdowns, and roadmap items that persist across sessions
+- **Refresh stale knowledge** — use `gitlab_memory_update` to correct outdated facts (e.g., updated issue counts, new team members, changed dependencies)
+- **Archive superseded decisions** — when a decision is reversed or a fact becomes obsolete, archive it with a reason so there's a historical record
+- **Periodic memory housekeeping** — use `gitlab_memory_consolidate` to identify stale, duplicate, or contradictory records and clean them up
+- **Search before investigating** — use `gitlab_memory_recall` to check if something is already known about a topic before spending time exploring the codebase
+- **Log session summaries** — at the end of a significant work session, record what was accomplished, what was learned, and suggestions for next steps
+
+##### Skill Tools (8)
 
 | Tool                    | Description                                                   |
 | ----------------------- | ------------------------------------------------------------- |
@@ -168,17 +265,30 @@ Say **"bootstrap project memory"** to automatically inspect a project and build
 | `gitlab_skill_setup`    | Extract skill to `.agents/skills/<name>/` for local execution |
 | `gitlab_skill_delete`   | Delete skill (wiki pages + snippet + index entry)             |
 
-**Hybrid storage:** SKILL.md and markdown references are stored in the wiki. Executable files
-(`.py`, `.js`, `.sh`) are stored as a multi-file project snippet with extensions preserved.
-Use `gitlab_skill_setup` to extract everything to `.agents/skills/<name>/` for local execution.
-Skills are indexed in `agents/skills/index` for fast discovery.
-All tools support project scope (default) and group scope (`scope="groups"`).
+**Use cases:**
+
+- **Create a reusable incident retrospective procedure** — save a step-by-step skill that guides the agent through conducting incident retros with checklists and templates
+- **Share skills across projects via group wiki** — save a skill at the group level so all projects in the group can discover and install it
+- **Discover team-shared skills** — search the group wiki and skills.sh registry to find skills other teams have built (e.g., Helm rollback procedures, database migration checklists)
+- **Install a skill from the community** — install a skill from skills.sh into your project wiki with one command, bringing in both documentation and executable scripts
+- **Draft and iterate on a skill before publishing** — save a skill as a draft, test it in practice, refine the instructions, then promote it to published when ready
+- **Bundle executable scripts with a skill** — save Python, JavaScript, or Shell scripts alongside skill instructions using hybrid storage (wiki for markdown, project snippet for executables)
+- **Extract skills for local execution** — use `gitlab_skill_setup` to download a skill's scripts to `.agents/skills/<name>/` so opencode auto-discovers and uses them locally
+- **Maintain a skill index for fast discovery** — the index at `agents/skills/index` is auto-rebuilt on every `gitlab_skill_list` call, keeping it in sync with actual skill pages
+- **Promote a proven draft skill** — after validating a draft skill works well, promote it to published to make it available to all users of the project
+- **Remove an obsolete skill** — delete a skill and its associated snippet, automatically cleaning up the index entry
+- **Audit available skills** — list all published and draft skills with their descriptions to understand what automation is available for the project
 
 ### Dynamic Refresh
 
 After enabling or disabling an agent/flow, the plugin automatically refreshes the
 agent list. Restart opencode to update the `@` menu.
 
+**Use cases:**
+
+- **Enable an agent and use it immediately** — after enabling a new agent or flow, the plugin refreshes the catalog cache so tools immediately reflect the change without restarting
+- **Disable a broken flow mid-session** — disable a flow that is misbehaving and the agent list updates in real time for subsequent tool calls
+
 ### Vendored Foundational Flow Configs
 
 Foundational flow definitions (from `gitlab-org/modelops/applied-ml/code-suggestions/ai-assist`)
@@ -188,6 +298,12 @@ foundational flows whose configs are not available via the GitLab API.
 The `flow_v2.json` JSON schema is also vendored from GitLab Rails and bundled
 inline for client-side YAML validation via `ajv`.
 
+**Use cases:**
+
+- **Execute foundational flows without API calls** — flow input schemas for built-in flows are bundled in the plugin, enabling instant flow definition lookup without network requests
+- **Validate custom flow YAML offline** — the vendored `flow_v2.json` schema enables client-side validation via `ajv` without requiring a GitLab API connection
+- **Stay up to date with new flow versions** — run `npm run vendor` to pull the latest foundational flow definitions when DWS releases updates
+
 ## Agent Types
 
 ### Foundational Agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-gitlab-dap",
-  "version": "1.16.5",
+  "version": "1.16.6",
   "description": "OpenCode plugin that injects GitLab AI Catalog agents as native opencode agents",
   "license": "MIT",
   "type": "module",