Building a Reusable AI Workflow for Azure DevOps Work Items

Building a Reusable AI Workflow for Azure DevOps Work Items

AI is great at reasoning. It is terrible at remembering how your company likes to do Git.

Every week I implement dozens of Azure DevOps work items.

The process is always the same.

• Read the work item
• Understand the acceptance criteria
• Find the correct repository
• Create a branch
• Search the codebase
• Implement the change
• Validate it
• Commit
• Push
• Create a Pull Request

None of those steps are individually difficult.

They're just repetitive.

Naturally I thought:

"Why can't an AI agent do all of this?"

It turns out writing code is only about 20% of the workflow.

The remaining 80% is engineering discipline.

An AI agent can absolutely generate code.

But it doesn't automatically know:

• which repository contains the feature
• how your team names branches
• which projects require manual validation
• whether the working tree is already dirty
• if another Pull Request already exists
• how your product is organised

Those aren't intelligence problems.

They're workflow problems.

That's why I built Start Story.

Rather than creating another "AI coding assistant", I wanted to build something different:

A reusable workflow that safely takes an Azure DevOps work item all the way to a Pull Request while keeping a developer firmly in control.

The Goal

I had three design goals.

1. Remove repetitive work

I didn't want AI replacing developers.

I wanted it replacing ceremony.

If an agent can save me fifteen minutes on every ticket by handling Git operations and Azure DevOps plumbing, that's a meaningful productivity gain.

2. Make it reusable

The first version worked.

Unfortunately it only worked for my repositories.

Repository names were hardcoded.

Validation rules lived inside PowerShell.

Search guidance referenced my controllers.

It wasn't a reusable tool.

It was a diary entry that happened to execute.

I wanted something I could point at an entirely different product and have it work with minimal configuration.

3. Never sacrifice safety

Automation should reduce mistakes.

Not create new ones.

That meant every operation had to be deterministic.

No guessing.

No "probably".

No auto-merging.

No silently continuing after errors.

Human approval always remains the final step.

The Workflow

The finished workflow looks like this.

Azure DevOps Work Item
        │
        ▼
Read Story
        │
        ▼
Understand Acceptance Criteria
        │
        ▼
Detect Repository
        │
        ▼
Create or Reuse Branch
        │
        ▼
Agent Implements Change
        │
        ▼
Validate Repository
        │
        ▼
Developer Review
        │
        ▼
Commit
        │
        ▼
Push
        │
        ▼
Create Pull Request

Notice what isn't there.

Merge.

The workflow deliberately stops after creating the Pull Request.

Review is still performed by a human.

That decision alone removed a huge amount of risk.

The Biggest Design Mistake

Originally I thought this project was mostly about prompts.

It wasn't.

The biggest challenge was deciding what belongs where.

Everything had become mixed together.

PowerShell knew repository names.

Markdown knew folder structures.

Configuration files contained workflow logic.

Every change required editing multiple places.

Eventually I realised I wasn't building one system.

I was building three.

Three Layers Instead of One

The architecture eventually became surprisingly simple.

Each layer has exactly one responsibility.

That sounds obvious.

It wasn't obvious while building it.

Layer One — Scripts

Scripts perform work that should always behave identically.

Examples include:

• Git operations
• Azure DevOps REST calls
• Validation
• Pull Request creation
• Branch detection

A script should never need to "think".

It simply executes.

That makes scripts predictable and easy to test.

They become the safety rails around the AI.

Layer Two — Markdown

Markdown contains instructions for the coding agent.

Examples include:

• implementation workflow
• review checkpoints
• coding expectations
• reasoning guidance

Unlike scripts, markdown is expected to evolve.

As I discover better workflows, the instructions improve.

The scripts rarely change.

The prompts improve continuously.

That separation turned out to be incredibly valuable.

Layer Three — Repository Profiles

Every product has tribal knowledge.

Things like:

• "Search this controller first."
• "Business logic lives here."
• "Ignore generated files."
• "Don't modify this folder."

Originally those details lived inside prompts.

That meant every repository required editing the workflow.

Now they live inside repository profiles.

Changing products no longer requires changing the workflow.

Only the profile changes.

A Simple Rule

Eventually I settled on one design rule.

If it's deterministic, put it in a script.

If it requires judgement, put it in markdown.

If it's specific to one product, put it in a repository profile.

That single decision simplified almost every part of the project.