@konductro/codex-plugin

Codex plugin for the Konductro platform. It enables technical analysis, story decomposition, ticket management, repository profiling, prototype delivery, and ticket-to-PR workflows directly from Codex.

Prerequisites

• Node.js 18+
• Codex
• A Konductro account with project access
• A personal CLI token from Konductro -> Settings -> CLI Access

Install the Plugin

The Konductro plugins are published to the public npm registry under the @konductro scope. No registry configuration or authentication is required.

For Codex:

npm install -g @konductro/codex-plugin

Generate a CLI Token

1. Open Konductro and navigate to your profile settings.
2. Under CLI Tokens, click Generate Token.
3. Give it a descriptive name, for example MacBook - Codex.
4. Copy the token. It is shown only once.

Configure the Plugin

Run the setup command with your Konductro platform URL and CLI token:

konductro-codex-setup --url https://platform.konductro.com --token <your-cli-token>

Replace <your-cli-token> with the token you copied in the previous step. If your organisation uses a self-hosted instance, replace the URL accordingly.

The setup command:

• Stores the connection configuration in ~/.codex/konductro.json
• Registers the plugin in ~/.agents/plugins/marketplace.json
• Enables the plugin in ~/.codex/config.toml
• Copies the plugin runtime to ~/plugins/konductro

Restart Codex after setup so the Konductro MCP tools and skills are discovered.

Verify the Connection

After setup, ask Codex to list your assigned Konductro tickets:

What Konductro tickets are assigned to me?

If Codex can call the Konductro tools and returns your assigned work, you are connected.

Skills

Skills are guided, multi-step workflows invoked by asking Codex naturally:

| Skill | Description | |---|---| | konductro-technical-analysis | Perform a full codebase analysis for a Konductro project phase | | konductro-decompose | Decompose a story into technical tasks by exploring the codebase | | konductro-prototype | Build, publish, and submit a UX prototype | | konductro-find-prototype | Find and download approved UX prototypes for the current project | | konductro-profile-repository | Scan the current repo and submit its profile to Konductro | | konductro-start-ticket | Pick up an assigned ticket and start work | | konductro-bug-enrich | Enrich a bug ticket with technical analysis — explores codebase and submits structured context | | konductro-demand-analysis | Size a demand against the real code and propose the phases the forum will commit to |

Tools

Tools are called automatically by Codex based on natural language. You do not invoke them directly.

Tickets and Delivery

| Tool | What it does | |---|---| | list_my_tickets | List tickets assigned to you with status, project, sprint, and branch info | | get_ticket_context | Load full ticket context: acceptance criteria, notes, parent story, repo, and artefacts | | start_work | Start work on a ticket: creates a branch, pushes the ticket spec, and sets in_progress | | create_pr | Create a pull request and move the 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. | | Konductro is not configured | A setup problem rather than a permissions one — run konductro-codex-setup, or your CLI token is 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 technical analysis task, plus the requester's context message when a refresh was asked for | | submit_tech_analysis | Submit your analysis document back to Konductro |

Demand Analysis

A demand sits above projects: a business request that has passed the demand forum and now needs sizing against the real code before the forum will commit to it. Unlike a phase's analysis, the repositories are not known in advance — deciding which projects the work lands in is part of the job.

| Tool | What it does | |---|---| | list_demand_analyses | List the demand analyses assigned to you | | get_demand_analysis_context | Load the pitch as the requester answered it, what the forum asked, and every repository in the workspace | | submit_demand_analysis | Submit the analysis, the repositories the change actually touches, and the phases you propose |

Story Decomposition

| Tool | What it does | |---|---| | list_decomposition_tasks | List your pending story decomposition assignments | | get_decomposition_context | Load story details, requirements, architecture, and repositories | | submit_decomposition_task | Submit one decomposed technical task | | complete_decomposition | Mark decomposition as complete after all tasks are submitted |

Prototype Delivery

| Tool | What it does | |---|---| | find_project_prototypes | Find published prototypes 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 preview HTML | | start_prototype_work | Mark a prototype task as in progress | | request_upload_credentials | Get temporary S3 credentials for prototype upload | | 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, and events | | get_bug_for_enrichment | Load a bug ticket and project context for enrichment | | submit_bug_enrichment | Submit structured technical enrichment for a bug ticket |

Updating

Update to the latest version the same way you installed:

npm install -g @konductro/codex-plugin@latest
konductro-codex-setup --url https://platform.konductro.com --token <your-cli-token>

Restart Codex after updating.

Troubleshooting

| Problem | Solution | |---|---| | EACCES permission error | Use sudo or fix npm global permissions | | Token rejected | Verify the token has not been revoked in Konductro settings | | Plugin not recognised by Codex | Restart Codex after setup | | Tools are not available | Confirm ~/.codex/config.toml contains konductro@local with enabled = true | | Connection timeout | Check that platform.konductro.com is reachable from your network |

Local Development

npm install
npm run check
npm pack --dry-run

To test setup from a local checkout:

npm run setup -- --url https://platform.konductro.com --token <your-cli-token>

Publish

For Konductro maintainers:

npm login
npm publish --access public