@konductro/q-plugin

Amazon Q Developer plugin for the Konductro platform. Enables technical analysis, story decomposition, ticket management, prototype delivery, and ticket-to-PR workflows directly from Amazon Q Developer (CLI, VS Code, JetBrains).

Prerequisites

• Node.js 18+
• Konductro CLI token (generated in Konductro → Settings → CLI Access)

Install

1. Install the plugin globally

npm install -g @konductro/q-plugin

2. Configure for Amazon Q Developer

konductro-q-setup --url https://platform.konductro.com --token YOUR_CLI_TOKEN

Get your CLI token from Konductro → Settings → CLI Access.

Agents

Agents are guided, multi-step workflows. In Q Developer CLI, start them with @konductro:

| Agent | Description | |---|---| | technical-analysis | Perform a full codebase analysis for a Konductro project phase | | decompose | Decompose a story into technical tasks by exploring the codebase | | prototype | Build a UX prototype: load design system, generate HTML, publish to S3, submit | | find-prototype | Find and download the approved UX prototype for the current project | | profile-repository | Scan the current repo and submit its profile to Konductro | | start-ticket | Pick up an assigned ticket — creates branch, pushes ticket spec, sets status | | bug-enrich | Enrich a bug ticket with technical analysis — explores codebase and submits structured context |

Tools

Tools are called automatically by Q based on natural language. You don't invoke them directly — just ask.

Tickets and delivery

| Tool | What it does | |---|---| | list_my_tickets | List all tickets assigned to you with status, project, sprint info | | get_ticket_context | Load full context for a ticket — AC, architectural notes, parent story, repo | | start_work | Start work on a ticket — creates branch via ADO, pushes spec file, sets in_progress | | create_pr | Create a pull request for a ticket — auto-assigns reviewer, moves ticket to pr_open |

Work items

| Tool | What it does | |---|---| | create_work_item | Create a story, task or bug in the project this repo belongs to | | update_work_item | Change the title, description or acceptance criteria of a work item you own | | delete_work_item | Delete a task or bug that has not been started |

The project is resolved from the repository's git remote, so you are never asked for a project identifier.

Everything created lands in Draft and still needs an SDM's approval before it can be worked on.

update_work_item can change three fields and no others. Status, sprint, assignee and everything else are deliberately not on the schema — change those in Konductro. Sending acceptanceCriteria replaces the whole list rather than appending to it. The changed list it reports back is the fields that were written, not the ones that turned out to differ, so re-sending a value unchanged still shows up in it.

A task is created in the repository you are standing in. Its parent story is the only thing you need to name. Set repositoryId yourself only for a task that will be built in a different repository on the same project.

Only a task may have a parent. A story or a bug sent with a parentKey is refused and nothing is created, rather than being filed top-level as though it had worked. A bug is always standalone here — Konductro parents one to a story only when QA files it against a failed test criterion — so name the story in the description instead. A story is top-level by definition: the hierarchy is story → task, and work that belongs under a story is a task.

create_work_item returns the new item's id. Use it for the follow-up call. Ticket keys are prefix plus number and the prefix is not returned, so a guessed key resolves to a different project's item of the same number instead of failing.

Who can create and change stories

Each project has a story access setting, which an SDM controls under Settings → General:

| Setting | What a developer can do | |---|---| | Planning roles only | Cannot create or change stories. Filing bugs and editing tasks are unaffected. | | Developers can, with review | Changes apply straight away, then wait for an SDM to approve or reject. | | Developers can, no review | Creates and changes apply with nothing held for approval. |

A new project starts on planning roles only.

Under with review, a change to a story is applied and then held: the story will not move to Ready for QA until an SDM resolves it, even once every task is done. If it is rejected, the previous values are restored and you are notified.

What a refusal means

These are answers, not errors — none of them is worth retrying as-is.

| You will see | What to do | |---|---| | The project's story access is set to planning roles only | A project setting. Ask an SDM to make the change, or to open story access for developers. | | You can only change work items assigned to you, that you are the developer on, or that you created | Ask whoever owns it, or ask an SDM. | | Stories cannot be deleted from the CLI | Deleting a story removes its tasks with it. Archive it in Konductro instead. | | QA filed this bug against a failed test criterion | It is QA's record of a failure, not yours to remove. | | Only a task can be created under a parent | Nothing was created. For a bug, re-run without parentKey and name the story in the description. For a story, you probably wanted kind: "task". | | Work has already started on this item | It has a branch, or has moved past sprint planning. Only items still in draft, approved or in_sprint can be deleted. | | Your seat is a viewer seat | Read-only across the whole platform, not a project setting. Ask an admin for a contributor seat. | | Your role on this project is read-only | Ask an SDM for a writing role on the project. | | You are not a member of this project | Ask an SDM to add you to the project team. | | Not authenticated | A setup problem rather than a permissions one — your KONDUCTRO_CLI_TOKEN is missing, expired or revoked. Create a new one in Konductro under your profile. |

Technical analysis

| Tool | What it does | |---|---| | list_tech_analysis_tasks | List your pending technical analysis assignments | | get_task_context | Load requirements and project context for a tech analysis task, plus the requester's context message when a refresh was asked for | | submit_tech_analysis | Submit your analysis document back to Konductro |

Story decomposition

| Tool | What it does | |---|---| | list_decomposition_tasks | List your pending story decomposition assignments | | get_decomposition_context | Load story details, requirements, and repo context for decomposition | | submit_decomposition_task | Submit a single decomposed task | | complete_decomposition | Mark decomposition as complete after all tasks submitted |

Prototype delivery

| Tool | What it does | |---|---| | find_project_prototypes | Find published prototypes for a project by matching the git remote URL | | list_prototype_tasks | List your pending prototype build assignments | | get_prototype_context | Load engagement details, design system, approved docs, and S3 config | | start_prototype_work | Mark a prototype task as in progress | | request_upload_credentials | Get temporary S3 credentials to upload prototype files | | submit_prototype | Submit the published prototype back to Konductro |

Repository profiling

| Tool | What it does | |---|---| | profile_repository | Submit a repository profile (tech stack, APIs, dependencies) | | get_bug_for_enrichment | Load a bug ticket and project context for enrichment | | submit_bug_enrichment | Submit structured technical enrichment for a bug ticket |

Examples

"What tickets are assigned to me?"          → list_my_tickets
"Show me the context for MRB-15"            → get_ticket_context
"I want to start work on MRB-15"            → start-ticket agent (guided flow)
"Run a technical analysis"                  → technical-analysis agent (guided flow)
"Build the prototype for this engagement"   → prototype agent (guided flow)
"Open a PR for MRB-15"                      → create_pr

In VS Code / JetBrains

The tools and agents appear in the Amazon Q panel and can be invoked through the chat interface.

Update

npm update -g @konductro/q-plugin

To update your CLI token:

konductro-q-setup --url https://platform.konductro.com --token NEW_TOKEN