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 four a person actually runs most often — starting work on a ticket, filing a ticket before that work begins, bootstrapping a repository, 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. A question that cannot be put to the user (unattended run, declined, "decide later") is never guessed silently: it is persisted as a [NEEDS CLARIFICATION: <question> — options: <a> | <b>; recommended: <a>] marker on the task it blocks and in the Task summary’s Open clarifications: list, and planning continues around the recommended option

  • Writes an ## Acceptance criteria coverage table right after the Task summary, mapping every criterion (quoted from the ticket, or labelled derived when the ticket states none) to the tasks that cover it; a criterion with no task is a planning error that the skill fixes before finishing

  • 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

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.

For a larger or more demanding issue there is a detailed, spec-style path (GitHub only): iru-draft-github-issue interviews the user, writes a complete functional or documentation draft, runs iru-review-github-issue on it in a loop until no gaps remain, and offers iru-split-github-issue when the issue is too large (sub-issues ordered by dependency, tracked by a milestone). iru-create-github-issue stays the quick path. See Detailed, spec-style issues.

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 &lt;id&gt; or /iru-plan &lt;id&gt;\n(separate, later invocation)"]) X["/iru-draft-github-issue\n(detailed path)"] --> Y["iru-review-github-issue loop\n+ optional iru-split-github-issue"] Y --> G

Bootstrapping a repository

This workflow is for standing up a repository’s scaffold, docs, gitignore, CI/CD, changelog, and README in one pass, rather than writing each by hand or running five to six skills separately. iru-setup-repository is the front door for every stack this catalog supports — it works the same way whether the repository is brand new or already has code in it.

On a brand-new, empty repository

/iru-setup-repository finds nothing to detect, so it asks the project type itself, over up to six short AskUserQuestion rounds rather than one long list. Each round offers three options plus a "Something in the next group" escape hatch that moves on to the next round: JVM services & libraries (Java library, Spring Boot service, Quarkus service), Web & Node (TypeScript/npm library, web app, NestJS backend service), PHP (Laravel application, WordPress plugin or block theme, PrestaShop module), Python (FastAPI service, Django project), Mobile & Apple (Android, Apple, cross-platform mobile app), and Desktop & command line (macOS desktop app, Windows desktop app, command-line tool); the last round’s escape hatch is "None of these", which ends the run with a plain "no orchestrator for this stack" report. An option that bundles several types gets one short follow-up right away — web app → React / Next.js / Angular, WordPress → plugin / block theme, Android → library / app, Apple → Swift library / Apple app, cross-platform → React Native / Kotlin Multiplatform / Ionic, command-line tool → Rust / Go / Swift / C# .NET — while Spring Boot and Quarkus get none here: their language (Java or Kotlin), build tool (Maven or Gradle), Quarkus layout, and Hilla frontend are asked by their own orchestrators, and the desktop apps' UI framework and MVVM/MVC architecture are asked by iru-setup-macos-repository/iru-setup-windows-repository, and a command-line tool’s terminal UI and package channels by iru-setup-cli-repository. A plain .NET, Rust or Go library or service is recognised by iru-explore but never offered here, because the catalog has no bootstrap orchestrator for it (Windows desktop apps and command-line tools are the exceptions). Once the type is known, it announces that it is setting the repository up from scratch, then asks only the inputs the stacks genuinely share, exactly once: open-source; visibility (public/private/internal, detected with gh repo view when the repository already has a GitHub remote, otherwise asked); ci — whether to generate GitHub Actions workflows at all; sonar — whether SonarCloud/SonarQube receives CI analysis and coverage reports (+ its organization/project-key/host details); ci-tests — unit only or the full suite (integration / instrumentation / e2e); pages — whether docs are deployed to GitHub Pages; and publish (libraries) or distribution (apps) — plus the flavor-specific ones the chosen type needs (platforms for Swift/Apple, framework for Ionic, toolchain (expo or metro) and — for Expo only — native-builds for React Native). Kotlin Multiplatform’s UI approach (ui: compose for Compose Multiplatform shared UI, ui: native for Jetpack Compose + SwiftUI over shared logic) is asked by its own orchestrator. License and developer identity are never asked by the front door; each stack orchestrator asks its own.

Visibility matters because the CI choices cost differently (per GitHub’s current pricing — double-check your plan): standard Actions runners and SonarCloud are free for public repositories, while a private repository spends its plan’s included Actions minutes (2,000/month on GitHub Free, with macOS minutes counting roughly 10×), needs a paid SonarCloud plan, and can only use GitHub Pages on Pro/Team/Enterprise Cloud — where the published site is still public unless the organization is on Enterprise Cloud with private Pages access control. So for a public repository the front door recommends ci: yes, ci-tests: full, and defaults pages: yes; for a private one it recommends ci-tests: unit and pages: no (the docs are still built and uploaded as a workflow artifact), and recommends sonar: cloud only for a public, open-source repository. ci: no skips the workflows step entirely — including the shared Dependabot/dependency-review/CodeQL/OSV-Scanner/gitleaks security block — and the stack’s -github-workflows skill can be re-run later to add them. It then delegates to that stack’s own orchestrator (e.g. Setup TypeScript Repository, Setup Android Repository) via the iru-isolated-skill-executor agent, so its full multi-step transcript stays out of the front door’s own context.

A -repository orchestrator runs its fixed six-step chain (scaffold → Antora → gitignore → CI/CD workflows → changelog → README), while iru-setup-java-springboot runs its own manifest-driven chain (interview → springboot-stack.yml → the iru-setup-java-springboot- sub-skills → iru-update-java-springboot-documentation → gitignore/README/changelog). Either way it returns a single consolidated report, including one combined required-secrets table covering every workflow it generated (Sonar tokens, publishing credentials, signing secrets, …) instead of a separate table per sub-skill. What to do next is manual and outside any skill’s reach: create those secrets in the repository’s settings, set up the SonarCloud/self-hosted SonarQube project and any package-registry account the publish/ distribution choice implies, review the generated files, and commit.

On an existing repository

/iru-setup-repository runs iru-explore first and reads back its Project type: line, so the type question is pre-selected instead of asked — a repository already recognizable as, say, android-library skips straight to the shared inputs. Before asking them, it announces that it is updating an existing repository and prints an inventory of the prior setup it found — build manifest, sources, Antora docs, .gitignore, each workflow file, Dependabot, Sonar config, CHANGELOG.md, README.md, LICENSE — each marked absent, present, or partial. It then forces mode: existing on the delegation, so no sub-skill assumes a brand-new repo, but mode: existing never means "update silently": every component skill that finds an artifact it owns warns and asks what to do with it, explaining the consequence of each choice —

  • Update (usually recommended) — merge: add what’s missing and correct outdated parts using the skill’s template, keeping everything the skill doesn’t own (custom steps, entries, pages, sections). You review a diff.

  • Keep as is — leave the file untouched; the final report lists every way it disagrees with this run’s choices (e.g. a workflow that still runs a Sonar step after sonar: none, or still deploys to Pages after pages: no).

  • Replace — regenerate from the template; every customization in that file is lost (recoverable only from git history).

Some components keep their additive nature inside that shape: iru-setup-antora's Update only fills gaps and never overwrites a page, and iru-setup-changelog's Update only appends releases missing from CHANGELOG.md. For scripted runs, on-existing: keep|update|replace in args answers every one of these questions up front. The final report repeats the mode and, per component, the action actually taken — created, updated, replaced, kept as is, or skipped (ci: no).

Invoking a stack orchestrator directly

Each stack’s orchestrator also runs standalone, useful when the front door’s project-type rounds are unnecessary because the stack is already known:

  • TypeScript/web — /iru-setup-typescript-repository covers seven flavors from one orchestrator; pass flavor to skip the question (library, react, angular, react-native, ionic, nestjs, nextjs), e.g. /iru-setup-typescript-repository with args: flavor: react for a Vite+React web app, or flavor: ionic (plus framework: angular or framework: react for Ionic’s own underlying choice). flavor: nestjs scaffolds a NestJS API via iru-setup-nestjs-app (orm/database pick an optional persistence layer, distribution: internal adds a container image to GHCR); flavor: nextjs scaffolds a Next.js web app via iru-setup-nextjs-web (router: app|pages, output: server|static, e2e: playwright|none).

  • Quarkus — /iru-setup-quarkus-repository with args: language: java|kotlin, build-tool: maven|gradle (Gradle uses the Kotlin DSL), and layout: single|hexagonal (a single-module service, or a multi-module hexagonal reactor mirroring the Spring Boot module table); iru-setup-quarkus-service writes a quarkus-stack.yml manifest, scaffolds with the Quarkus Maven plugin using extensions validated against code.quarkus.io, and post-processes quality tooling, JaCoCo, and sample tests at each Quarkus test level.

  • PHP — /iru-setup-php-repository with args: flavor: laravel (Pest, Pint, Larastan), flavor: wordpress-plugin or flavor: wordpress-theme (block theme; WPCS, PHPStan WordPress, Brain Monkey unit tests plus wp-env integration tests), or flavor: prestashop-module (PrestaShop 8.x/9.x, prestashop/php-dev-tools); php-version sets the supported floor and distribution decides whether a WordPress.org/PrestaShop Addons package or a Laravel container image is produced.

  • Python — /iru-setup-python-repository with args: flavor: fastapi (iru-setup-python-fastapi; database/orm pick an optional SQLModel/SQLAlchemy persistence layer with Alembic) or flavor: django (iru-setup-python-django; api picks DRF or Django Ninja), both with pytest, Ruff, and mypy; python-version sets the supported floor and distribution decides whether a container image is pushed to GHCR. A plain Python package (no FastAPI/Django) has no scaffold, but the iru-python-* gate skills still apply to it.

  • Android — /iru-setup-android-repository with args: flavor: library (a lib/ module plus a Compose app/ sample, following the Android reference-repository conventions) or flavor: app (a single app/ module).

  • Kotlin Multiplatform — /iru-setup-kmp-repository (scaffold via iru-setup-kmp-app): a shared/ KMP module (Android + iOS targets), an androidApp/ host and an XcodeGen-generated SwiftUI iosApp/, with ui: compose or ui: native, detekt/ktlint/Android Lint/SwiftLint, Kover coverage on the JVM/Android side, Dokka, and CI that splits Linux (shared + Android) from macOS (iOS) jobs.

  • React Native — /iru-setup-typescript-repository with args: flavor: react-native and toolchain: expo (Expo framework: Expo Router, EAS or local prebuild builds) or toolchain: metro (bare React Native CLI: committed android//ios/ projects, CocoaPods, Gradle/Xcode CI jobs and store release).

  • Swift/Apple — /iru-setup-swift-repository with args: flavor: library for a SwiftPM package, or flavor: app for an XcodeGen/Tuist-generated native iOS/iPadOS/macOS/watchOS/visionOS app — SwiftUI or, for the iOS/iPadOS target, programmatic UIKit (ui), with architecture: mvvm|mvc over a UI-free Packages/Core (add platforms to scope the targets when app).

  • macOS desktop — /iru-setup-macos-repository (scaffold via iru-setup-macos-app): a macOS-only XcodeGen project with ui: swiftui (scenes, Settings, menu commands) or ui: appkit (programmatic NSWindowController/NSViewController), architecture: mvvm (SwiftUI, or AppKit with Observation tracking) or mvc (AppKit), a UI-free Packages/Core package carrying the 80% coverage bar, the App Sandbox and hardened runtime, and CI/CD that tests on a macOS runner and releases a Developer ID–signed, notarized, stapled DMG (distribution: internal) or an App Store Connect upload (distribution: store).

  • Windows desktop — /iru-setup-windows-repository (scaffold via iru-setup-windows-app): a .NET 10 solution with ui: wpf, winui (WinUI 3 / Windows App SDK) or winforms, architecture: mvvm (CommunityToolkit.Mvvm; the only option for WPF/WinUI) or mvc (Windows Forms), a UI-free net10.0 Core project carrying the 80% coverage bar (testable on Linux/macOS too), MSTest + coverlet, StyleCop + .NET analyzers, DocFX, optional FlaUI UI tests, and CI/CD that keeps Core tests on Linux, builds/packages on a Windows runner, and releases zips + a signed MSIX
    .appinstaller (optionally WinGet) or a Microsoft Store submission.

  • Command-line tool — /iru-setup-cli-repository (scaffold via iru-setup-rust-cli, iru-setup-go-cli, iru-setup-swift-cli or iru-setup-dotnet-cli, workflows via iru-setup-cli-github-workflows): one native binary in language: rust (clap), go (Cobra), swift (swift-argument-parser) or dotnet (System.CommandLine, Native AOT), with ui: tui adding a TTY-gated full-screen browse command (Ratatui, Bubble Tea, or a .NET terminal UI — not offered for Swift). Every scaffold follows the agent-friendly contract of the author’s Building CLIs for AI Agents guide: data on stdout and messages on stderr, exit codes 0–7 plus 130/143, --format text|json|jsonl with a JSON error envelope, colour only on a terminal (NO_COLOR), no prompts without one (--no-input, --yes), --dry-run for mutations, and generated completion, schema, man page and CLI reference. Logic lives in a library unit carrying the 80% coverage bar, next to end-to-end tests of the real binary; CI runs on Linux with macOS/Windows legs on the cross-os-ci schedule, and releases ship per-target archives with SHA256SUMS and build-provenance attestations (distribution: internal), plus crates.io / Homebrew / Scoop / WinGet / NuGet-tool channels (store).

  • Spring Boot + Hilla — /iru-setup-java-springboot itself already asks whether the service has a frontend; pass args: frontend: hilla to skip that question and have iru-setup-java-springboot-hilla scaffold the Vaadin/Hilla React frontend into the boot module right after the API layer is generated.

  • Kotlin Spring Boot — the same /iru-setup-java-springboot chain with args: language: kotlin (and optionally build-tool: gradle for a Kotlin DSL build with a version catalog and build-logic/ convention plugins; Maven remains the default): the module tree is unchanged, while detekt/ktlint and Dokka replace Checkstyle/PMD/SpotBugs and Javadoc. Java services stay Maven-only.

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 pre-release version into a final, tagged release: it must be run from develop (this catalog follows gitflow) and stops immediately if it isn’t. It is not Maven-only — the version-bump step itself is delegated to whichever iru-<key>-bump-version skill (guides/extending-the-catalog.adoc#_release_generation_for_other_ecosystems covers the registry) matches the project’s detected ecosystem (java — Java or Kotlin, Maven or Gradle —, typescript, react-native, android, kmp, swift, php, python, dotnet, rust, go today), so the same /iru-release flow applies whether the version lives in pom.xml, a Gradle build or gradle.properties, package.json (plus a React Native app’s app.json or native versionName/MARKETING_VERSION, or a KMP app’s iosApp xcconfig), a Gradle version catalog, a Swift package manifest, or a PHP project’s own version location (Laravel config/app.php, a WordPress plugin/theme header, a PrestaShop module class), a Python project’s pyproject.toml (PEP 440 .devN pre-releases), a .NET Directory.Build.props <Version> (-dev pre-releases, mirrored into a Windows app’s four-part MSIX version), a Rust Cargo.toml version, a Go tool’s internal/version/version.go literal, or a Swift command-line tool’s Version.swift (all -dev pre-releases).

flowchart TD A["/iru-release"] --> B{"Current branch is develop?"} B -- no --> Z["Stop: checkout develop\nand retry"] B -- yes --> C["Gather state: current version,\nlatest tag, base branch, clean tree"] C --> D["Ask user: release version\n(3 computed candidates + free text)"] D --> E["Ask user: next pre-release version\n(3 computed candidates + free text)"] E --> F["Create release_x.y.z\nbranch off develop"] F --> G["Delegate the version edit to\niru-<key>-bump-version;\nupdate README.md (via iru-setup-readme),\ndocs/antora.yml, Antora 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 version bump into develop"])

Every file that echoes the version number — the ecosystem’s own version file (via iru-<key>-bump-version), 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 workflows, alongside the catalog’s other supported flows (updating an existing repository 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.

  • Extending the skills and agents catalog — how the repository-bootstrap and release-generation pipelines used above are built to be extended with a new stack or ecosystem.

  • 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.

  • Setup Repository — detail page for the repository-bootstrap front door.

  • Rolling deployments — staged blue/green, canary and linear deployments for generated Spring Boot services, and the promote.yml workflow that advances them.

  • Release — detail page for the release workflow.