zammad/.dev/agent_docs/development_workflow.md

Development Workflow

Issue Tracking & Code Hosting

• Issues (bugs, stories, epics) are tracked on GitHub — in zammad/zammad (public) and private repositories (e.g. zammad/coordination-desktop-view).
• Code is developed on a self-hosted GitLab instance.
• GitHub hosts a read-only mirror — synced automatically when public branches like develop or stable are updated.
• Branches prefixed with private/ are never synced to GitHub.

All branches must start with private/ to prevent unintended syncing.

Tools

• GitHub MCP server — for reading issues, labels, and comments.
• glab CLI — for pushing branches, creating merge requests, and other GitLab operations. Authenticated against the self-hosted GitLab instance.

Lifecycle

1. Understand

Read the GitHub issue thoroughly before writing any code. Clarify scope, acceptance criteria, and edge cases. If the issue is ambiguous, ask the user for clarification rather than guessing.

Determine the mode. If the user supplied --parent <github_issue_url>, this is attach mode: the task is part of a larger story whose branch and MR already exist. Otherwise, this is standalone mode: the task gets its own branch and MR. The parent may live in a different repository — parse owner + repo + number from the URL, do not assume same-repo.

In attach mode, also:

• Read the parent issue via the GitHub MCP server (it provides context the task issue alone doesn't have).
• List the parent's sub-issues. Note which are already closed, which are in progress, and who is assigned — this prevents stepping on a colleague's work.
• Confirm the existing branch is already checked out in the current workspace (Conductor creates the workspace from a branch; the branch is on disk before the workflow starts). If it is not — abort and ask the user.

Then determine which parts of the codebase the issue affects:

• Check labels and comments for scope hints (when available).
• Otherwise, search the codebase for keywords from the issue title and body to locate the relevant component(s).
• Identify which stack is affected: CoffeeScript frontend, Vue 3 frontend (desktop or mobile), REST backend, GraphQL layer, services, etc.
• State your conclusion explicitly before moving on, e.g. "This issue affects the CoffeeScript frontend (KB answers component) and the REST controller behind it. I will NOT investigate Vue 3, GraphQL, or unrelated services unless something during research requires it."

This explicit scoping prevents broad codebase exploration in areas the issue does not touch.

2. Research

Investigate only the parts of the codebase identified in the Understand phase. Delegate broad research to separate agents to keep your main context clean. Understand the existing patterns before introducing new ones.

If during research you discover the scope was wrong (e.g. the data turns out to come from a service you hadn't considered), update the scope explicitly and tell the user before continuing.

3. Plan

Identify affected files and outline the approach. For non-trivial changes, present the plan to the user before implementing. Consider side effects on other parts of the system.

4. Branch

Standalone mode: Use the /prepare-issue-branch skill to create the branch and prepare the commit message. It handles naming conventions, public vs. private issue detection, and commit message formatting automatically.

Attach mode: Do not invoke /prepare-issue-branch. The story branch is already checked out (confirmed in step 1). Instead:

• Run git fetch origin && git pull --rebase to align with what colleagues have pushed since you started.
• If git pull --rebase produces conflicts, stop and ask the user to resolve them before continuing.
• Do not prepare a commit message yet — it will be written in step 8 based on what was actually changed.

5. Implement

Write the code following the patterns described in the relevant agent reference docs (graphql_patterns, frontend_patterns, service_patterns, etc.). Read the relevant doc before starting implementation — do not read them all upfront.

6. Test

Run the specific tests affected by your changes. Write new tests for new behavior. Never run the full test suite — CI handles comprehensive testing.

7. Review

Before committing, delegate the review to the code-reviewer sub-agent. The sub-agent has its own context window and reviews the uncommitted diff without bias from the implementation history.

The sub-agent will report findings grouped by severity (P0/P1/P2). If findings are reported, return to step 5 (Implement) to address them, then test again before re-running the review.

If the sub-agent reports no findings, proceed to commit.

8. Commit

Pre-commit hooks run linting and validation automatically. If you changed the GraphQL schema or settings, the regenerate hook runs the appropriate generators automatically.

Standalone mode: Use the prepared commit message from step 4 (/prepare-issue-branch wrote it to .git/COMMIT_EDITMSG).

Attach mode: Write a commit message that describes what this commit changed — no issue reference, no Closes/Fixes keywords. The parent story's MR carries the issue context; individual commits within it only need to describe their own change. Keep it short and conventional, e.g. Add validation for empty subject on ticket form.

9. Merge Request

Standalone mode: Use the /create-mr skill to push the branch and create a Merge Request on GitLab. It selects the correct MR template, fills in the sections, and targets the appropriate branch automatically.

Attach mode: Do not invoke /create-mr — the MR for the parent story already exists.

Don't push automatically. After committing, stop and wait. Tell the user what you committed and ask before pushing — every time. Pushing sends your commit to the team's MR and runs CI, so the user decides when that happens.

Push only after the user confirms.

CI runs automatically on MR creation (standalone) or push (attach). A human review is required before merging.

10. Cherry-pick

If the fix also applies to stable, use the /cherry-pick-to-stable skill after the MR is merged to develop.

Rules

• Never push directly to develop or stable.
• Never reference private issue numbers in public commits.
• Never run the full test suite — always target specific files.