Flowdex

This developer tool is called Flowdex, whenever "flowdex" is written it should be understood as the tool which is built from this codebase. This is different from tool-usage or external tools or just tools. Those refer to other tools, such as git, Azure Devops, shell commands, etc.

Code for a coding agent. The coding agents main function is to read a ticket (subject to a specific connector) and then work with the code in the current repository (working directory where the tool is run) and make changes to solve that ticket. Ticket may be called a task or item as well.

By default the project has two connectors:

Built-in connectors

• azure-devops – loads work items from Azure DevOps. It requires an AZURE_DEVOPS_TOKEN and optionally respects AZURE_DEVOPS_PROXY.
• openai – sends prompts to the OpenAI chat completion API. Configure it with OPENAI_API_KEY and optionally OPENAI_BASE_URL and OPENAI_MODEL.

The CLI automatically uses these connectors unless other modules are provided.

Main workflow

For detailed information about the main workflow, see docs/main-flow.md.

Configuration

Create a .env file with your personal access token. Optionally specify a proxy via AZURE_DEVOPS_PROXY:

AZURE_DEVOPS_TOKEN=<your pat>
#AZURE_DEVOPS_PROXY=http://proxy.example.com:8080

Connector plugins

Flowdex can load custom connectors at runtime. Set the environment variables WORKITEM_CONNECTOR and LLM_CONNECTOR to the module names of your own implementations. Each plugin should export a default factory function that receives an options object and returns a connector instance implementing the WorkItemConnector or LlmConnector interfaces from src/connectors. When not specified, the built in connectors described above are used. A pair of simple example plugins can be found in the plugins/ directory of this repository and the published package. Alongside the echo LLM and dummy work item examples, there is now a chatgpt.ts plugin which demonstrates how to call the OpenAI chat completion API.

Usage

npx @khayll/flowdex              # prints the detected project
npx @khayll/flowdex task <url>   # prints work item JSON
                                 # <url> can be a direct work item link or a backlog link
npx @khayll/flowdex run <url>    # generates a plan using the ticket
npx @khayll/flowdex prompt "<text>" # runs a free-form prompt against the codebase

Development

For detailed development practices and guidelines, see docs/development.md.

Publishing

To release a new patch version and publish it to npm:

npm version patch
npm publish --access public

The version command updates package.json and package-lock.json and triggers the bundle step via the prepare script. The published package now includes the prompts/ directory as well as the plugins/ examples.