opencode-gitlab-dap 1.5.0 → 1.6.0

package/README.md

@@ -73,23 +73,67 @@ 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.
 
-### 13 DAP Tools
-
-| 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                |
-| `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 |
+### Custom Agent Creation
+
+Create custom agents interactively:
+
+```
+Create an agent that responds to prompts in the form of poems
+```
+
+The plugin guides you through an interactive workflow:
+
+1. Discovers available built-in tools (`gitlab_list_builtin_tools`) and MCP servers (`gitlab_list_project_mcp_servers`)
+2. Asks for agent name, visibility, tool categories, and MCP servers via the question tool
+3. Generates a system prompt and shows the full configuration for approval
+4. Creates the agent via `gitlab_create_agent` (with `confirmed` gate to prevent accidental creation)
+5. Offers to enable the agent on the current project
+
+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.
+
+### Custom Flow Creation
+
+Design and create custom flows interactively:
+
+```
+Create a flow that fetches MR data, analyzes the changes, and posts a summary comment
+```
+
+The plugin provides a multi-round design workflow:
+
+1. `gitlab_design_flow` with `action="get_schema"` returns the flow YAML schema reference, two annotated examples, and step-by-step instructions
+2. The LLM asks the user about the flow's purpose, resource type, and steps
+3. The LLM proposes a component architecture for user approval
+4. The LLM generates the full YAML, validates it client-side against the `flow_v2` JSON schema via `gitlab_design_flow` with `action="validate"`
+5. After user confirmation, `gitlab_create_flow` with `confirmed=true` submits it to GitLab
+6. After creation, offers to enable the flow on the current project via `gitlab_enable_project_flow`
+
+The vendored `flow_v2.json` schema from GitLab Rails powers client-side validation using `ajv`, catching errors before hitting the API.
+
+### 20 DAP Tools
+
+| 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           |
 
 ### Dynamic Refresh
 
@@ -102,6 +146,9 @@ Foundational flow definitions (from `gitlab-org/modelops/applied-ml/code-suggest
 are vendored and embedded at build time. This provides flow input schemas for
 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`.
+
 ## Agent Types
 
 ### Foundational Agents
@@ -145,7 +192,7 @@ export GITLAB_INSTANCE_URL=https://your-instance.com
 
 ```bash
 npm install
-npm test          # Run tests (58 tests)
+npm test          # Run tests (69 tests)
 npm run build     # Build (auto-runs vendor:generate)
 npm run type-check
 ```
@@ -178,17 +225,17 @@ Plugin init
   │    └─ aiCatalogConfiguredItems       custom agents + flows (GraphQL)
   │         └─ aiCatalogAgentFlowConfig  flow config YAML (GraphQL)
   ├─ config hook                         injects agents (primary) + flows (subagent with prompt)
-  ├─ chat.message hook                   intercepts multi-@flow → combined dispatch
-  ├─ experimental.chat.system.transform  injects flow dispatch guidelines
-  └─ tool hook                           13 DAP tools
+  ├─ chat.message hook                   intercepts @flow → general subagent dispatch
+  ├─ experimental.chat.system.transform  injects flow dispatch + agent creation guidelines
+  └─ tool hook                           20 DAP tools
 
 Single flow execution (@FlowName goal):
-  ├─ Native subagent dispatch   opencode routes to registered subagent
-  ├─ Subagent Step 1            gitlab_get_flow_definition → parse context:goal mapping
-  ├─ Subagent Step 2            Resolve goal to exact value (MR IID, URL, etc.)
-  ├─ Subagent Step 3            Gather additional_context inputs via GitLab tools
-  ├─ Subagent Step 4            gitlab_execute_project_flow → POST to DWS
-  └─ Subagent Step 5            gitlab_get_workflow_status → report status + URL
+  ├─ chat.message hook          rewrites @mention → Task tool with general subagent
+  ├─ General subagent Step 1    gitlab_get_flow_definition → parse context:goal mapping
+  ├─ General subagent Step 2    Resolve goal to exact value (MR IID, URL, etc.)
+  ├─ General subagent Step 3    Gather additional_context inputs via GitLab tools
+  ├─ General subagent Step 4    gitlab_execute_project_flow → POST to DWS
+  └─ General subagent Step 5    gitlab_get_workflow_status → report status + URL
 
 Multi-flow execution (@Flow1 @Flow2 goal):
   ├─ chat.message hook          detects multiple @mentions → combined dispatch
@@ -199,6 +246,26 @@ Multi-flow execution (@Flow1 @Flow2 goal):
   ├─ General subagent           calls gitlab_get_workflow_status × N (concurrent)
   └─ General subagent           presents summary table
 
+Agent creation (interactive):
+  ├─ gitlab_create_agent        called without confirmed → returns instructions
+  ├─ gitlab_list_builtin_tools  discover available tools
+  ├─ gitlab_list_project_mcp_servers  discover MCP servers
+  ├─ question tool              ask user for name, visibility, tools, MCP servers
+  ├─ LLM generates              system prompt → user confirms
+  ├─ gitlab_create_agent        called with confirmed=true → creates agent
+  └─ gitlab_enable_project_agent  optionally enable on project
+
+Flow creation (interactive, multi-round):
+  ├─ gitlab_design_flow (get_schema)  returns schema reference + examples + instructions
+  ├─ gitlab_list_builtin_tools        discover available tool names for flow components
+  ├─ question tool                    ask user for name, visibility, purpose, steps
+  ├─ LLM proposes                    component architecture → user confirms
+  ├─ LLM generates                   flow YAML definition
+  ├─ gitlab_design_flow (validate)   client-side validation against flow_v2.json via ajv
+  ├─ User confirms                   the generated YAML
+  ├─ gitlab_create_flow              called with confirmed=true → creates flow
+  └─ gitlab_enable_project_flow      optionally enable on project
+
 Enable/disable:
   └─ refreshAgents()            clears cache, re-fetches, updates cfg.agent
 ```