Workflow Conventions

This page documents the cross-cutting conventions that all devops-plugin agents follow. Understanding these conventions makes it easier to trace a YouTrack issue through the pipeline, interpret git history, and diagnose failures.

Branch naming

Feature branches follow the convention:

<type>/<issue-id>-<short-slug>

Examples:

Branch	Type	When to use
`feat/COR-42-login-flow`	`feat`	New feature
`fix/COR-87-duplicate-webhook`	`fix`	Bug fix
`chore/COR-99-bump-deps`	`chore`	Maintenance
`docs/COR-1071-restructure-docs`	`docs`	Documentation-only

Branches are created off main and deleted after merge.

Commit message format

All commits follow Conventional Commits:

<type>(<scope>): <subject>

<body — what changed and why>

Resolves COR-<N>
Co-Authored-By: Claude <noreply@anthropic.com>

The Co-Authored-By trailer is required on all AI-generated commits.

PR label flow

Labels drive handoffs between agents:

flowchart LR
    %% PR label state machine
    Open([PR opened])
    Ready[Label: Ready]
    NeedChanges[Label: Need Changes]
    Merged([Merged])

    Open -->|issue-resolver applies| Ready
    Ready -->|pr-reviewer approves| Merged
    Ready -->|pr-reviewer requests changes| NeedChanges
    NeedChanges -->|pr-resolver fixes| Ready

Label	Applied by	Means
`Ready`	`issue-resolver`, `pr-resolver`	PR is ready for review
`Need Changes`	`pr-reviewer`	Reviewer has requested changes

Issue routing

issue-resolver determines which specialist agent (if any) implements the change by walking a four-level priority chain:

Lane field (deterministic): frontend → blazor-frontend-coder, backend → csharp-backend-coder, designer → ui-designer, docs → doc-writer.
Git Repo map (fallback when Lane is unset): doc → doc-writer; dev-software-plugin, officialsite, manifest → self-implement.
Keyword sniff (last resort): if issue summary/description contains mock, wireframe, or visual design → ui-designer.
Self-implement (default): resolver implements the change directly.

Monorepo guard: repos listed in KNOWN_MONOREPOS trigger a hard stop — the resolver posts a comment asking the planner to split the work into per-lane sub-issues.

YouTrack custom fields

Field	Values	Purpose
`Stage`	`To Do`, `In Progress`, `Done`	Pipeline progress
`Assignee`	`Claude_Code` or a human user	Signal for auto-pickup; unset when work begins
`Git Repo`	repo name (e.g. `doc`, `shop`)	Which repository the issue targets
`Lane`	`frontend`, `backend`, `designer`, `docs`	Forces routing to a specific specialist

Open Questions guard

If an issue description contains an ## Open Questions section with at least one non-empty bullet, issue-resolver blocks and exits without implementing anything. The convention is:

Run issue-clarifier (manually invoked by the operator) to resolve questions via Discord.
issue-clarifier folds answers back into the description and removes the section when all questions are resolved.
Re-dispatch the issue.

Heartbeat notifications

All pipeline agents send Discord notifications at key milestones using the notify-discord skill:

Start: blue embed, status processing, elapsed 0s.
Periodic: one heartbeat per ~60s of wall-clock work; skipped if less than 60s since last one.
Completion: green embed (done) on success; red embed (failure) on error or block.

A failed notification must never block the workflow — agents log the error and continue.

Credential and authentication rules

Agents must never create scripts or commands to extract, read, or construct auth tokens (e.g. git credential fill, reading .gitconfig, parsing credential stores). For git operations, rely on the configured credential helper. For API operations, use MCP tools. If auth fails, stop and report the error.

Table of Contents