Common workflows

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Common workflows on the top-level page gives a one-diagram-each overview of how this catalog’s skills compose for a handful of recurring jobs. This page goes deeper on the three a person actually runs most often — starting work on a ticket, filing a ticket before that work begins, and cutting a release — with a fuller diagram and, for the first one, a breakdown of what each step in it actually does.

Typical development cycle, starting from a ticket

This is the main workflow for day-to-day work in this catalog. Whenever there’s a tracked ticket — a GitHub issue or a Jira ticket — to pick up, this is the path to reach for: /iru-issue <ticket-id> runs it end to end, from "just filed" to "pull request open for review." Each stage also works standalone (/iru-explore, /iru-plan, /iru-code, /iru-pr-description, /iru-pr-review), so the same flow applies whether one command drives all of it or a person runs each stage themselves.

flowchart LR A["Explore issue + codebase"] --> B["Prepare implementation plan"] B --> R1{{"User reviews the\nimplementation plan"}} R1 --> C["Code implementation"] C --> D["Create and review\nPull Request"] D --> R2{{"User reviews\nthe final result"}}

The two hexagons are manual gates, not automated steps: nothing moves past either one without the user’s own judgment call. Between "Prepare implementation plan" and "Code implementation," the user reads implementation_plan.md and either lets it proceed or asks for changes — this is the cheapest point to redirect the work, before any code is written. After "Create and review Pull Request," the user reviews the actual diff and the automated review comments before merging — the PR is always opened as a draft, so nothing ships without that final look.

Diagram block Skill(s) What happens

Explore issue + codebase

iru-explore

  • Fetches the ticket (GitHub issue or Jira ticket), auto-detecting which tracker it belongs to

  • Detects the codebase’s language(s)/framework(s), whether an Antora documentation module exists, and which platform hosts the repository

  • If a documentation MCP (e.g. Confluence, Notion) is connected, searches it for pages relevant to the ticket or codebase and folds anything relevant into the report as extra context

  • Builds a grounded, read-only understanding of the code relevant to the ticket — no files are changed

Prepare implementation plan

iru-plan

  • If implementation_plan.md already exists, assesses whether it matches the requested task and asks the user to skip planning (resume as-is), discard and regenerate, or update while preserving completed tasks

  • Reuses the exploration above rather than repeating it

  • Asks the user up to four focused questions only where something is genuinely ambiguous; otherwise picks a best-practice approach and states the rationale directly in the plan

  • Groups tasks into dependency-aware task groups, each marked whether its tasks can be implemented in parallel

  • Tags each task (and sub-task) with the language/framework key a later <key>-code-one-task-group skill should handle it with

  • Writes implementation_plan.md at the repository root, tasks/sub-tasks numbered Task N/Task N.M, one checkbox per task/sub-task

User reviews the implementation plan

— (manual gate)

  • The user reads implementation_plan.md and either confirms it, edits it, or asks for a different approach

  • Nothing is implemented until this review happens — /iru-issue explicitly asks whether to proceed automatically or stop here for manual review

Code implementation

iru-code

  • Captures a project-wide code-quality baseline (iru-java-code-quality/iru-dotnet-code-quality) and a security baseline (iru-check-security) before making any change

  • Works through implementation_plan.md one task group at a time, dispatching each to iru-code-one-task-group, which resolves each task’s language and delegates to iru-java-code-one-task-group, iru-dotnet-code-one-task-group, or (for database-tagged tasks) iru-database-code-one-task-group (or implements it directly if no matching skill applies), checking off boxes as it goes

  • Each task group’s tasks are implemented in parallel when the plan allows it (database task groups are always sequential instead), then paired with tests reaching at least 80% line coverage — verified against a real coverage report, not estimated — plus license headers and language-appropriate doc comments, all validated once per group rather than once per task

  • Re-checks the quality and security baselines at the end (a security regression is a hard stop, unlike a quality regression, which the user can accept or turn into follow-up tasks), runs a full local build, and updates the Antora documentation via iru-update-docs (which also proposes matching updates to a connected documentation MCP, if one exists, for the user to approve)

  • Archives implementation_plan.md to .archive/ on success and asks for a review — iru-code never commits, pushes, or opens a pull request itself

Create and review Pull Request

iru-pr-description + iru-pr-review

  • The branch is pushed and a pull request opened as a draft against the base branch

  • iru-pr-description drafts the PR body from the real diff

  • iru-pr-review re-runs iru-explore grounded in the linked ticket, then leaves review comments — delegating correctness/reuse/efficiency analysis to the external code-review skill when it’s available in the session, and focusing its own pass on whether the change matches the ticket’s intent and this codebase’s conventions

User reviews the final result

— (manual gate)

  • The user reads the PR diff and the automated review comments before merging

  • Because the PR is opened as a draft, nothing merges automatically — this is the last checkpoint before the change ships

Filing a ticket before work begins

The cycle above needs a ticket (or at least a free-form description) to start from. That ticket doesn’t have to be written by hand: iru-create-github-issue and iru-create-jira-ticket let AI assist in producing one, so it’s ready to feed straight into the typical development cycle above.

Either skill runs iru-explore first — a previous analysis of the current codebase — then asks the user the same handful of questions every time: what the purpose of the task is, what additional context exists (linked URLs, attached files, related tickets, and — Jira only — an optional epic), and the task’s due date and importance. From that, it classifies the ticket (bug vs. feature/enhancement, or the matching Jira issue type), drafts a structured title and body — including an agent-assessed estimated difficulty — and matches it against the repository’s actual label set or Jira project configuration rather than inventing one. The draft is always shown for confirmation before anything is filed. See Creating GitHub issues and Jira tickets for the full breakdown of what’s asked, how the draft is structured, and every skill involved.

Tickets can still be created manually — directly in GitHub or Jira, with no AI involvement at all — and nothing in the typical development cycle requires going through these skills first; /iru-issue and /iru-plan work the same way against a hand-written ticket, or even no ticket at all. What AI assist adds is consistency and grounding: every draft is checked against the real codebase and asks for the same structured information, rather than depending on whoever’s filing it to remember what a well-formed ticket needs.

flowchart LR A["/iru-create-github-issue\nor /iru-create-jira-ticket"] --> B["iru-explore\n(analyze current codebase)"] B --> C["Ask purpose + additional context\n(+ due date, importance)"] C --> D["Classify bug vs. feature;\ndraft title + structured body"] D --> E{"User confirms?"} E -- edits --> D E -- declines --> F["Stop: draft kept,\nnothing filed"] E -- confirmed --> G["File via gh issue create\nor Jira MCP tools"] G --> H(["/iru-issue <id> or /iru-plan <id>\n(separate, later invocation)"])

Generating a release

This workflow is used once a batch of tasks has already been completed, reviewed, and tested — not mid-feature. iru-release converts the repository’s current development SNAPSHOT into a final, tagged release: it must be run from develop (this catalog follows gitflow) and stops immediately if it isn’t.

flowchart TD A["/iru-release"] --> B{"Current branch is develop?"} B -- no --> Z["Stop: checkout develop\nand retry"] B -- yes --> C["Gather state: SNAPSHOT version,\nlatest tag, base branch, clean tree"] C --> D["Ask user: release version\n(3 computed candidates + free text)"] D --> E["Ask user: next SNAPSHOT version\n(3 computed candidates + free text)"] E --> F["Create release_x.y.z\nbranch off develop"] F --> G["Update pom.xml, README.md\n(via iru-setup-readme), docs/antora.yml,\nAntora version snippets"] G --> H["Write whats-new.adoc +\nCHANGELOG.md sections"] H --> I["Commit changes on the release branch"] I --> J{"User confirms\npush + PR?"} J -- no --> K["Stop: nothing pushed"] J -- yes --> L["Push branch;\nopen PR against main/master"] L --> M["iru-pr-description\n(fill in the release PR body)"] M --> N(["Merging the release PR\ntriggers the Sync workflow's\nautomatic snapshot bump into develop"])

Every file that echoes the version number — pom.xml, README.md, docs/antora.yml, and any Antora page with a dependency snippet — is updated in the same pass, so nothing is left pointing at the previous release once the PR merges.

See also

  • Common workflows on the top-level page — the shorter, one-diagram version of these same three workflows, alongside the catalog’s other supported flows (bootstrapping a new repository, updating an existing one after unrelated changes).

  • Creating GitHub issues and Jira tickets — a full breakdown of the "Filing a ticket" workflow above: every piece of information asked for, how the drafted ticket is structured, and every skill involved.

  • Issue-to-PR Development Cycle and Ticket Intake — the purpose groups these workflows draw their skills from.

  • Issue, Plan, Code — detail pages for the typical development cycle’s own skills.

  • Release — detail page for the release workflow.