@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 |

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 |

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 | | 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, 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