DevPlaza Toolchain Setup Skill

This skill guides Team Admins and Company Admins through configuring the SDLC toolchain for a product — selecting tools per stage, providing credentials, validating connections, and verifying the setup is complete.

Scope

In scope:

• Browse tenant catalog (categories, tasks, tools)
• Create task-tool bindings for a product/project
• Update existing task-tool bindings
• Validate provider credentials before saving
• Confirm setup completeness by reading back mappings
• Create and update governance configuration for tools

Out of scope:

• Tenant catalog management (adding new tools/tasks to the catalog — Company Admin platform ops)
• Billing or subscription changes
• Run triggering or governance checks (handled by devplaza-process-guardian skill)

Roles

Both Team Admin and Company Admin can create and update task-tool bindings. No approval gate applies to SDLC setup (unlike product creation).

Operating principles

• Always verify tenant is active before setup operations. Use GET /api/v1/tenant/customer/:tenantId/status (alias: GET /api/v1/tenant/customer/tenantStatus/:tenantId on 404).
• Always validate provider credentials before creating a task-tool binding. Do not create a binding with unvalidated credentials.
• Never print credentials (apiToken, botToken, apiKey, appKey, token) in responses. Mask all credential values in output.
• If a task-tool binding already exists for the same category + task + tool + product + project, do not create a duplicate. Report the existing binding and offer to update it instead.
• Default to read-first behavior. If user intent is ambiguous between create and update, ask one clarifying question.
• Require explicit confirmation before any write operation (create or update).

Session config resolution

• Read .env first for BASE_URL, JWT, AUTH_EMAIL, AUTH_PASSWORD, TENANT_ID, PRODUCT_ID, PROJECT_ID.
• Only ask user for keys still missing after local file resolution.

Setup flow

For most setup requests, follow this sequence:

1. Verify tenant active status
2. Resolve product + project context
3. Browse tenant catalog to show available categories/tasks/tools
4. For each stage the user wants to configure: a. Confirm category (stage), task, and tool selection — apply disambiguation rules below b. Collect provider credentials c. Validate credentials against provider endpoint d. Confirm with user before creating binding e. Create task-tool binding via POST /api/v1/product/task-tools/
5. Read back mappings to confirm setup is complete

Input disambiguation

Users may specify setup intent in either direction. Handle both:

Key rule: never collect credentials or create a binding until both stage/task and tool are confirmed. If either is missing or ambiguous, ask one short clarifying question first.

Tenant catalog endpoints

• Categories (stages): GET /api/v1/tenant/categories
• Tasks: GET /api/v1/tenant/tasks
• Tools: GET /api/v1/tenant/tools

Present catalog results as: stage → tasks available → tools available per task.

Task-tool binding

Create

POST /api/v1/product/task-tools/

Required fields:

• tenantId, productId, projectIds (array of project ids — pass current projectId wrapped in array)
• categoryId, taskId, toolId
• categoryName, taskName, toolName
• owner — resolve from auth context (userId from JWT decode or login response)
• descriptiveName — human-readable label for this binding (e.g. "GitHub — Code stage")
• toolsConfig — provider credentials object (see per-provider shapes below)

Optional:

• governance
• envName — inherited from existing Build task-tool if not provided

Uniqueness: backend enforces no duplicate for same categoryId + taskId + toolId + productId + projectId. If duplicate detected, surface the existing binding and offer update instead.

Update

PUT /api/v1/product/task-tools/:id

Use for updating credentials or descriptive fields on an existing binding. Always validate new credentials against the provider endpoint before calling PUT — use the same validation endpoint as during create. Do not update a binding with unvalidated credentials. For providers with no validation endpoint (Jira, Confluence, Figma, Google Docs, Google Sheets), skip validation and note that credential confirmation is manual.

Update status

PUT /api/v1/product/task-tools/tool/:id/status

Use for marking a tool status change.

Delete

DELETE /api/v1/product/task-tools/:id

Use when a binding needs to be removed (e.g. replacing one tool with another). Always ask explicit confirmation with binding name + id before deleting. Permanent — cannot be undone.

Read back (confirm setup)

GET /api/v1/product/task-tools/tenant/:tenantId/product/:productId/projectId/:projectId/allProductIds/:allProductIds

Use after creating bindings to confirm setup is complete. allProductIds must be URL-encoded JSON array (e.g. %5B%22id1%22%5D). Resolve from product context — use the productId as the single-item array if only one product is in scope.

Per-provider credential shapes and validation

GitHub

• Credentials: { link, apiToken }
• Validate: POST /api/v1/product/github/checkConfiguration with { link, apiToken, taskToolId: "" }
• Code/Dev stage: toolsConfig fields: { link, apiToken } — no further selection needed.
• Build stage (GitHub Actions): After credential validation, list branches via POST /api/v1/product/github/branches with { link, apiToken } — returns { isBranches: [...] }. User selects a branch. Then list YML workflow files via POST /api/v1/product/github/get/yml/files with { link, apiToken, branch } — returns { YMLFiles: [...] }. User selects the workflow file. toolsConfig fields: { link, apiToken, WORKFLOW_FILE_NAME: "<selected.yml>" }

GitLab

• Credentials: { link, apiToken }, optional pipelineTriggerToken
• Validate: POST /api/v1/product/gitlab/validate-env with { link, apiToken, pipelineTriggerToken? }
• Build stage: After credential validation, list branches via GET /api/v1/product/gitlab/branches?link=...&apiToken=.... User selects a branch. Then list YML pipeline files via GET /api/v1/product/gitlab/yml-files?projectId=...&branch=...&apiToken=...&link=.... User selects the pipeline file. toolsConfig fields: { link, apiToken, pipelineTriggerToken?, ymlFile: "<selected.yml>" }
• Code/Dev stage: toolsConfig fields: { link, apiToken, pipelineTriggerToken? } — no YML selection needed.

Jenkins

• Credentials: { link, apiToken, userName }
• Validate: POST /api/v1/product/task-tools/jenkins/config
• toolsConfig fields: { link, apiToken, userName }

SonarQube

• Credentials: { sonarUrl, token }
• Validate: POST /api/v1/product/sonarqube/authentication/validate with { sonarUrl, token }
• toolsConfig fields: { link: sonarUrl, apiToken: token, componentId }
• Note: componentId is required for runtime governance checks — collect it during setup.

Slack

• Credentials: { channelId, botToken, userToken }
• Validate: POST /api/v1/product/slack/checkconfiguration with { channelId, botToken, userToken }
• toolsConfig fields: { channelId, botToken, userToken }

Datadog

• Credentials: { apiKey, appKey, baseUrl }
• Validate: POST /api/v1/product/datadog/validate with { apiKey, appKey, baseUrl }
• toolsConfig fields: { apiKey, appKey, baseUrl }
• baseUrl is region-specific (e.g. https://api.us5.datadoghq.com)

Testkube

• Credentials: { link, orgId, apiToken }
• Validate: POST /api/v1/product/testkube/workflows/check/config with { orgId, apiToken, link }
• After validation: list available workflows per environment via POST /api/v1/product/testkube/env/workflows with { link, orgId, envId, apiToken } — returns { envId, workFlows: string[] }. Ask user to confirm envId and select workflow(s). Ask for an environment name label (e.g. "dev", "staging") to key the template.
• toolsConfig fields: { orgId, apiToken, link, testkubeTemplates: { [envName]: { envId, workFlows: ["wf1", "wf2"] } } }
• Note: testkubeTemplates is a map keyed by environment label. Each entry has the envId and an array of selected workflow names. Multiple environments can be added to the same binding.

Jira

• Credentials: { url, host, username, apiToken }
• Validate: no dedicated auth validation endpoint. Create binding with provided credentials.
• Note in output: validation not supported for Jira — user should confirm credentials manually.
• toolsConfig fields: { url, host, username, apiToken }

Confluence / Figma / Google Docs / Google Sheets (Plan stage tools)

• No integration validation endpoint available. Create binding with provided credentials.
• Note in output: validation not supported for this provider — user should confirm credentials manually.

Endpoint alias fallback (tenant mismatches)

Apply exactly one fallback retry rule:

• Try contract path first.
• If 404 and a known alias path exists, retry once with alias path.
• No multi-hop retries.

Error policy

• 401/403 from DevPlaza endpoints: session or permission issue — ask user to refresh DevPlaza JWT or check role scope.
• 401/403 from provider validation endpoints (GitHub, SonarQube, Slack, Datadog, etc.): credentials invalid — do NOT suggest refreshing DevPlaza JWT. Report as "invalid credentials" and ask user to check the provider token.
• 404: not found — apply alias fallback once if configured.
• 409/422: validation/conflict — list exact missing/invalid fields.
• 5xx/timeout: transient platform issue — suggest retry.
• Duplicate task-tool (backend throws): surface existing binding, offer update.

Output style

Prefer this structure:

• Current state
• Blocking issues (or None)
• Next safe action

For each task-tool binding created or updated, always confirm:

• provider
• stage (category) + task
• binding id
• validation status (credentials confirmed / not validated)

Never print credential values in output. Use [masked] for all token/key fields.

Governance configuration

Team Admins can configure governance rules for tools — defining eligibility criteria and thresholds per tool binding.

Endpoints (tenant-mgmt):

• Create: POST /api/v1/tenant/governance
• Update: PUT /api/v1/tenant/governance/:id
• Read one: GET /api/v1/tenant/governance/:id
• Read all: GET /api/v1/tenant/governance (supports page, pageSize, searchTerm)
• Delete: DELETE /api/v1/tenant/governance/:id

Required fields for create

• toolId — UUID of the tool this governance applies to (resolve from tenant catalog if user provides a tool name)
• governanceData — JSON object containing the governance thresholds and criteria (structure is flexible — collect from user or apply sensible defaults)

Governance flow

When a user wants to set or update governance for a tool:

1. Confirm which tool they want to govern — resolve toolId from the tenant catalog if not already known.
2. If no existing governance record exists for that tool, create one. If one exists, offer to update it.
3. Collect governanceData from the user (e.g. pass threshold, coverage percentage, eligibility criteria). If the user wants defaults, use { "eligibilityCriteria": "standard", "isActive": true } and note that they can update later.
4. Require explicit confirmation before POST or PUT.
5. Read back the saved record to confirm.

To check if governance already exists for a tool: GET /api/v1/tenant/governance with searchTerm matching the tool name, or list all and filter by toolId.

Do not delete governance records without explicit user confirmation including the governance id and associated tool name.

Post-setup handoff

After all bindings are confirmed and the setup summary is presented, always close with:

"Setup is complete. To run governance checks and verify integration readiness before your first build or deploy, switch to the Process Guardian skill."

Do not attempt to trigger runs from the toolchain setup skill. That is the guardian skill's responsibility.

Replication across projects

A Team Admin may want to replicate an existing project's toolchain setup to a new project under the same product.

When a user requests this (e.g. "set up project X the same as project Y"):

1. Read back task-tool bindings for the source project using the read-back endpoint.
2. Present the list to the user and confirm they want to replicate all bindings (or ask if any should be excluded).
3. For each binding to replicate: create a new task-tool binding via POST /api/v1/product/task-tools/ with the same categoryId, taskId, toolId, toolsConfig, and descriptiveName, but with the target projectId in projectIds.
4. Do NOT re-run provider credential validation during replication — credentials are already validated in the source binding.
5. Require explicit confirmation before creating each binding (or once before batch creation if user has pre-approved all).
6. Read back the new project's bindings after creation to confirm replication is complete.

Uniqueness rule still applies: if a binding for the same categoryId + taskId + toolId + productId + projectId already exists on the target project, surface it and skip — do not duplicate.

Guardrails

• No credential leakage in responses.
• Validate before create — do not skip the provider validation step.
• Require explicit confirmation before any write operation.
• If multiple products or projects match context, ask one short disambiguation question before acting.
• For Plan stage tools with no validation endpoint, warn user that credential confirmation is manual.