iru-explore
Explore this repository codebase, optionally grounded in a specific GitHub issue or Jira ticket used as the task to investigate, and detect the programming language(s) and framework(s) in play — inclu
SKILL.md.claude/skills/iru-explore/SKILL.md
GitHubExplore
Produce a grounded understanding of this repository codebase and, when available, of a specific GitHub issue or Jira ticket — without writing a plan or making code changes. This skill is read-only research: its output is a report, not a diff.
Step 1 — Resolve the ticket ID and its type
The skill may be invoked with a ticket ID as its argument (e.g. /iru-explore 42 or /iru-explore PROJ-123).
- Argument provided: detect which system it belongs to:
- Matches a Jira key pattern — one or more uppercase letters/digits starting with a letter, a hyphen, then
digits (e.g.
PROJ-123,ABC2-45) → Jira. - A bare number, optionally prefixed with
#(e.g.42,#42) → GitHub issue. - If it matches neither pattern clearly, ask the user (via
AskUserQuestion) whether it's a GitHub issue ID or a Jira key.
- Matches a Jira key pattern — one or more uppercase letters/digits starting with a letter, a hyphen, then
digits (e.g.
- No argument provided: ask the user (via
AskUserQuestion) for a ticket ID to focus the exploration on, making clear they can skip this and just have the codebase explored instead. Offer something like:- "Provide a GitHub issue ID or Jira key" (free text via "Other")
- "No ticket — just explore the codebase" (recommended default if they seem in a hurry)
- If they decline or give none, proceed directly to Step 4 (codebase-only exploration).
Step 2 — Detect the repository host and available tooling
Determine which platform hosts this repository, so later skills that operate on it (branch creation, pull/merge requests, commit history, CI status, etc.) know which CLI/API to use instead of assuming GitHub by default.
First, confirm the current working directory is actually inside a git repository at all
(git rev-parse --is-inside-work-tree, or check for a .git directory/file up the tree) — this skill must still
be useful when it isn't, e.g. run from a plain folder of docs, a fresh checkout-in-progress, or a directory that
was never git init'd:
- Not a git repository: tell the user plainly, once, that no repository was detected in the current working
directory — record
Repository host: none — not a git repositoryfor Step 7 and skip the rest of this step (there is no remote to inspect). This also means any git-dependent tooling later in this skill (ghinferring an owner/repo from the local remote,git logfor recent history in Step 4) will not work; note that explicitly too, as a warning, not a hard stop — continue exploring with whatever sources don't need a repository: a Jira ticket (Step 3) fetched via Jira MCP tools, a documentation MCP (Step 6), and any files actually present in the working directory (Step 4 — Antora docs,CLAUDE.md/README, source files, all work the same whether or not the directory happens to be a git repo). - Is a git repository: continue below as normal.
- Get the remote URL:
git remote get-url origin(fall back togit remote -v, or to whichever remote the current branch tracks, iforiginisn't the remote in use). - Match the URL against known host patterns:
github.com(or a GitHub Enterprise Server domain — look for a/api/v3/-style setup, or ask if uncertain) → GitHub. Tooling:ghCLI, or GitHub MCP tools (ToolSearch"github").bitbucket.org(cloud), or a self-hosted domain with a/scm/<project>/<repo>.gitpath (the Bitbucket Server/Data Center convention) → Bitbucket. Tooling: there's no ubiquitous CLI equivalent toghhere — search for Bitbucket MCP tools first (ToolSearch"bitbucket"), otherwise fall back to the Bitbucket REST API.dev.azure.comor<org>.visualstudio.com→ Azure DevOps (cloud). Tooling:az repos/az boards(the Azure CLI with theazure-devopsextension) if installed, or Azure DevOps MCP tools (ToolSearch"azure devops").- A self-hosted domain with a
/tfs/path segment, or_gitin the path without adev.azure.com/visualstudio.comdomain → Azure DevOps Server / Team Foundation Server (TFS). Same tooling family as Azure DevOps (az reposcan often target a collection URL directly), but confirm the collection URL and API version before assuming parity — older on-prem TFS versions expose a narrower REST API surface than cloud Azure DevOps. - If the URL doesn't clearly match any of these (e.g. a mirrored or internal git host), ask the user (via
AskUserQuestion) which platform it is rather than guessing — a wrong assumption here would misdirect every later git-platform operation.
- If there is no remote configured at all (a purely local repository), note that explicitly — later skills that need a hosted platform (PR/merge-request creation, etc.) won't have one to target.
- Record the detected host — and, for Azure DevOps/TFS or self-hosted Bitbucket, the base URL/collection — for
the report in Step 6. This detection is what later skills should key off instead of re-deriving it or
defaulting to GitHub-specific tooling (
gh, "Closes #N", etc.) unconditionally.
This is independent of Step 1: it detects where the code repository is hosted, not where the ticket lives — a Jira ticket can reference work in a GitHub, Bitbucket, or Azure DevOps repo, and vice versa.
Step 3 — Fetch the ticket
GitHub issue
Determine the repository (owner/name) from the git remote, e.g.:
gh repo view --json owner,name -q '.owner.login + "/" + .name'
- If Step 2 found no git repository at all (or a repository with no remote configured),
gh repo viewhas nothing to infer owner/repo from and will fail — this is expected, not a bug. Ask the user for the target repository explicitly (owner/repo), then fetch with--reposupplied directly:
If they don't know it or decline, warn them that the GitHub issue can't be fetched without a repository context, then continue with a codebase-only or Jira-only exploration (Step 4 onward) rather than stopping the whole skill — a missing repository should degrade this one lookup, not the rest of the exploration.gh issue view <issue-id> --repo <owner/repo> --json number,title,body,labels,comments,state,url
Otherwise, fetch the issue with the gh CLI directly:
gh issue view <issue-id> --json number,title,body,labels,comments,state,url
If gh is not installed/authenticated, search for GitHub MCP tools instead (ToolSearch with a query like
"github issue") and use those to fetch the same information — these may still work without a local repository if
the tool takes an explicit owner/repo parameter rather than inferring it from git remote. If neither is
available, tell the user and continue with a codebase-only exploration (Step 4), noting the issue could not be
retrieved.
Jira ticket
Search for connected Jira MCP tools (ToolSearch with a query like "jira issue" or "jira ticket"). If one or
more are found, use them to fetch the ticket by key: summary/title, description, issue type, status, labels/
components, comments, URL, and its issue links (issuelinks, plus the epic/parent relationship).
If no Jira MCP tool is available, tell the user plainly that this environment has no Jira connection, then ask
(via AskUserQuestion) whether to:
- paste the relevant ticket content (title/description/comments) directly so exploration can proceed grounded in it, or
- continue with a codebase-only exploration (Step 4), noting the ticket could not be retrieved.
Don't guess at Jira REST endpoints or attempt to WebFetch a Jira URL directly — Jira instances are normally
authenticated, and an unauthenticated fetch will just fail or return a login page.
Also fetch the epic and any linked tickets, one hop out, since a single ticket's own fields often omit context that lives on its epic or on tickets it references — a plan grounded only in the leaf ticket can miss a constraint the epic states once for all its children, or misunderstand what "blocks"/"relates to" actually means without reading the other side of that link:
- Epic: check whether the ticket belongs to an epic — the classic "Epic Link" field, or the
parentfield in team-managed/next-gen projects. If it does, fetch that epic ticket too (summary, description, status, and its own labels/components) — an epic frequently carries the overall goal, cross-cutting acceptance criteria, or links to design docs that no individual child ticket repeats. - Linked/related tickets: for each entry in the ticket's
issuelinks(e.g. "relates to", "blocks", "is blocked by", "duplicates", "clones") and any subtasks, fetch that linked ticket's summary, description, and status — enough to know concretely what the link means for this task, not just that it exists. Skip fetching its own comments unless the summary/description alone leaves the relationship unclear. - Keep this to one hop from the primary ticket — don't recursively follow the epic's or a linked ticket's own links.
- If fetching the epic or a linked ticket fails (no permission, deleted, not found), note that briefly and continue with what was retrieved rather than blocking the whole exploration on it.
Also check for attached implementation plans, on the ticket itself and on its epic/linked tickets fetched
above: list each ticket's attachments (via the same Jira MCP tool set — ToolSearch "jira attachment" if the
issue-fetch tool doesn't already return an attachment list) and look for any file named implementation_plan_*.md.
This is exactly the naming convention iru-code's own archiving step uses, and iru-issue attaches that archived
file back onto the ticket it resolved (per its own Step 7) — so a match here is a previously-completed
implementation plan for work the ticket-filer or a prior agent run judged similar or related, travelling with the
ticket itself rather than needing a local .archive/ in this checkout.
- Download and read each matched attachment in full — it's the same kind of precedent this skill's
.archive/check in Step 4 looks for locally, just sourced from the ticket instead of the current repository. - If more than one is attached (e.g. an epic with several resolved child tickets, each having attached its own plan), read all of them — they're typically small and each is a distinct, useful precedent.
- If the connected Jira MCP tool set has no way to list or download attachment content, note that explicitly and continue without it — this is a best-effort enrichment, not a blocker for the rest of exploration.
- If nothing matches
implementation_plan_*.mdon the ticket or its epic/linked tickets, note that briefly too rather than silently omitting the check.
Either way
Read the ticket's title, body/description, labels, and any comments that clarify scope or add constraints —
plus, for a Jira ticket, the epic's and any linked tickets' summaries/descriptions, and any downloaded
implementation_plan_*.md attachments, fetched above. Note explicitly: what behavior is requested/reported, any
acceptance criteria (including any stated only on the epic), and any files, classes, error messages, languages,
frameworks, or platforms mentioned — across the primary ticket, whatever epic/linked tickets were fetched, and
any attached implementation plans read.
Step 4 — Explore the codebase
This step must work generically on any repository — and equally on a working directory that per Step 2 isn't a
git repository at all — don't assume a language, framework, or prior familiarity with the project. Start from
first principles each time; every check below is file-based and works the same whether or not .git exists.
- Get the lay of the land first: check for a
CLAUDE.md,README, orAGENTS.md(use as a starting index, never as a substitute for reading the actual files, and treat it skeptically if it looks stale), list the top-level directories, and identify the language(s), build/package tooling, and entry points (main modules, services, public API surface). - Check whether Antora documentation exists and where: look for an
antora.yml(commonly underdocs/, but confirm the actual path rather than assuming) and, alongside it, anantora-playbook.ymland amodules/ROOT/pages(or other module) tree. Record the docs root path if found — later skills (e.g.iru-update-docs) need this location, and its content is itself a language/framework signal (see Step 5). - Check for a
.archive/directory at the repository root and give it special attention: theiru-codeskill archives every completedimplementation_plan.mdthere (typically asimplementation_plan_<ticket-or-timestamp-id>.md) once its task groups are done, so it's a library of previously resolved tasks. If it exists, list its contents (ls .archive) and skim each archived plan's title/summary for one whose topic, named files/classes, or task area overlaps with the current ticket (or, with no ticket, the general topic of this exploration) — matching on keywords rather than reading every file in full. Read the most relevant one or two in full: a matching archived plan shows how a similar task was previously scoped, broken into dependency-aware task groups, and what its "Current code state" notes captured — treat it as a concrete example to ground the current task's own plan against, not as a template to copy verbatim, since the current change is never identical. If.archive/doesn't exist, or nothing in it is relevant, note that explicitly rather than silently skipping the check. - Use the
Exploreagent (or directRead/grepfor small, targeted lookups) to build a picture of the most significant parts of the code structure: how the project is organized into modules/packages, the core abstractions and how they relate (inheritance, composition, key interfaces), where the main control flow or request/data path runs, and where tests live and how they map to source.
If a ticket was fetched, narrow the exploration to only the areas it implicates — do not do a full general tour. Concretely:
- Search for the classes/functions/files/error messages/behaviors named or described in the ticket.
- Read those files plus their closest structural neighbors (the base class/interface they implement, direct callers/callees) — only as much surrounding context as needed to understand how that area currently behaves.
- Check existing tests covering that area to learn current expected behavior and edge cases already handled.
- Skip unrelated parts of the codebase, even if they'd normally be worth a general orientation pass.
If there is no ticket (declined or unavailable), do a general orientation pass instead: map out the overall
architecture — the major components/modules, how they depend on each other, key abstractions and design
patterns in use, and, if Step 2 found this is actually a git repository, anything notable in recent git history
(git log --oneline -20) that suggests active areas of work. Skip the git-history check entirely (not a
failure, just nothing to check) if Step 2 found no git repository.
- Accessibility scan (UI projects only — skip when Step 5 finds no user interface): follow
reference/accessibility-detection.mdto look for existing assistive-technology support (ARIA/alt/labels,contentDescription,accessibilityLabel,AutomationProperties, a11y lint and audit tooling, any.ui-quality.yml), sample the coverage, and classify the resultpresent,partialorabsent. Read-only: report the evidence in Step 7, never change code.
Step 5 — Detect the technology stack
Identify the programming language(s) and framework(s) in play, both for the existing codebase and for whatever change is being requested. This is not a vague "looks like Java" impression — ground it in concrete evidence, and call out enough detail (per-module, if the repo has more than one stack) that later skills can act on it directly.
Codebase languages and frameworks
Use whichever of these signals are present — manifests/config are the most reliable, source-level signals are the fallback when manifests are absent or ambiguous:
- Build/package manifests are the primary signal:
pom.xml,build.gradle/build.gradle.kts→ Java/Kotlin; check dependencies forspring-boot-starter*(Spring/Spring Boot) — and among Spring Boot deps,hilla-spring-boot-starterand/orcom.vaadin:vaadin-spring-boot-starter→ Hilla (Spring Boot + Vaadin + Hilla), corroborated by a@vaadin/hilladependency in a co-locatedpackage.jsonand asrc/main/frontend/directory —micronaut-*,quarkus-*, or an Android Gradle plugin (com.android.application/com.android.library).- Build tool: record which one is in use — Maven (
pom.xml,mvnw), Gradle Kotlin DSL (build.gradle.kts/settings.gradle.kts), or Gradle Groovy (build.gradle/settings.gradle), plus whether a wrapper (mvnw/gradlew) is present — since the coding and gate skills run different commands for each. - Kotlin:
org.jetbrains.kotlin:kotlin-maven-plugininpom.xml, akotlin("jvm")/org.jetbrains.kotlin.jvmplugin (orkotlin("plugin.spring")/kotlin("plugin.jpa")) inbuild.gradle.kts, and/or asrc/main/kotlin/tree → Kotlin. Combined withspring-boot-starter*→ Kotlin Spring Boot (and Kotlin Spring Boot + Hilla when the Hilla markers above are also present). Asrc/main/java/tree alongsidesrc/main/kotlin/is a mixed Java/Kotlin module — record it as such and decide Java vs. Kotlin by where the bulk of production sources live. - Quarkus: the
io.quarkus:quarkus-maven-plugin(or Gradleid("io.quarkus")), an importedio.quarkus.platform:quarkus-bom/io.quarkus:quarkus-bom, and/orio.quarkus:quarkus-*dependencies → Quarkus; Java vs. Kotlin by the Kotlin signals above (aquarkus-kotlinextension corroborates Kotlin). - Architecture layout (Spring Boot / Quarkus backends): record whether the build is a hexagonal
multi-module reactor — sibling modules named (or suffixed)
domain,application,infrastructure(oradapters), andapi/rest/web, wired via<modules>in a parentpom.xmlorinclude(...)insettings.gradle*, with dependencies pointing inward towarddomain— vs. a layered/feature-based single-module (or loosely multi-module) layout. The coding skills apply hexagonal boundary rules only for the former, so state which one it is explicitly. - Android plugin id:
com.android.library→ Android library module,com.android.application→ Android application module — read it directly frombuild.gradle/build.gradle.kts, or, when the project centralizes versions/plugins ingradle/libs.versions.toml(itself a signal worth recording), from a plugin alias named e.g.android-library/android-applicationthere instead. Check for anandroidx.compose:compose-bom(or anotherandroidx.compose*) dependency → Jetpack Compose UI, vs. its absence → XML/View-based UI. A repository laid out as alib/module (library plugin) alongside anapp/module (application plugin) that depends on it (implementation(project(":lib"))) is this catalog's reference Android library shape — the app is the library's sample/demo, not a second deliverable — so record the library as the project type and the sample module as a sub-line, rather than treating them as two unrelated modules (see Step 7'sandroid-libraryrule). - Kotlin Multiplatform: a
kotlin("multiplatform")/org.jetbrains.kotlin.multiplatformplugin (directly or via akotlin-multiplatform/kotlinMultiplatformalias ingradle/libs.versions.toml), withsrc/commonMain/(+androidMain/,iosMain/) source sets, → a KMP module. An Android target (androidTarget(), thecom.android.kotlin.multiplatform.libraryplugin, orcom.android.libraryin the same module) plus iOS targets (iosArm64()/iosSimulatorArm64()/iosX64()) and aniosApp/Xcode (or XcodeGenproject.yml) host app → a KMP mobile app. Record the UI approach: the Compose Multiplatform plugin (org.jetbrains.compose+org.jetbrains.kotlin.plugin.compose) with composables incommonMain→compose(shared UI); shared logic only, with Jetpack Compose/Views in the Android app module and SwiftUI/UIKit iniosApp/→native. Record the module layout (shared/+androidApp/+iosApp/, or the JetBrains wizard's singlecomposeApp/module) and the test/coverage plugins (Kover, detekt, ktlint) on theBuild & layout:line. Acom.android.applicationmodule that only exists to host the KMPsharedmodule is part of the KMP app — never a separateandroid-app, and nevermultiple.
- Build tool: record which one is in use — Maven (
*.csproj/*.fsproj/*.sln/*.slnx→ C#/.NET (or F#); check forMicrosoft.AspNetCore.*(ASP.NET Core),*.Maui/Xamarin (cross-platform mobile), and Windows desktop project types:- A project with
<OutputType>WinExe</OutputType>(or anet*-windows*target framework) and<UseWPF>true,<UseWinUI>true(Windows App SDK / WinUI 3, usually with aPackage.appxmanifest) or<UseWindowsForms>true→ a Windows desktop app: record the UI stack (wpf/winui/winforms) and the architecture from the layout — a UI-freesrc/<App>.Coreproject withViewModels/(or MVVM ToolkitObservableObject/[ObservableProperty]usages) → MVVM;Controllers/plus view interfaces → MVC — on theBuild & layout:line, together with the test framework (MSTest/xUnit/NUnit), FlaUI UI tests and MSIX packaging (Package.appxmanifest,packaging/AppxManifest.xml,*.wapproj). A WPF/WinForms library (noWinExe) stays plaindotnet.
- A project with
package.json→ JavaScript/TypeScript; checkdependencies/devDependencies:vite+react(typically alongside avite.config.*file) → Vite + React web app.@angular/cliand/or@angular/core, corroborated by anangular.jsonat the project root → Angular CLI web app.@vaadin/hilla, alongside asrc/main/frontend/directory → the frontend half of a Hilla app (see thepom.xmlbullet above for its Spring Boot backend half).expoand/orreact-native→ React Native app. Record its toolchain:expoamong the dependencies →expo(Expo framework — corroborated byapp.json/app.config.*with anexpokey,eas.json,expo-router; committedios//android/directories in an Expo app arenpx expo prebuild/CNG output and don't change the answer);react-nativewithoutexpo→metro(bare React Native Community CLI project — corroborated bymetro.config.js,@react-native-community/cli*devDependencies,index.jscallingAppRegistry.registerComponent, and committed nativeandroid/(Gradle) andios/(Podfile,*.xcworkspace) projects). Expo also bundles with Metro, sometro.config.jsalone doesn't decide it — theexpodependency does. Also record the navigation library (expo-routervs.@react-navigation/*) and the e2e tool if any (.maestro/flows, a.detoxrc.js).@ionic/angularor@ionic/react→ Ionic, with which of the two deps is present telling you the underlying framework (Angular vs. React) Ionic is layered on;@capacitor/coreplus acapacitor.config.*and/orionic.config.jsoncorroborate it as an Ionic/Capacitor hybrid app rather than a plain Angular/React web app.@nestjs/core(usually with@nestjs/cli, anest-cli.json, andsrc/main.tscallingNestFactory.create) → NestJS backend. Also record: module format — ESM ("type": "module", relative imports ending in.js) vs. CommonJS (notypefield); test runner — Vitest (vitest.config*.ts) vs. Jest (jest.config.*,test/jest-e2e.json); and the persistence layer — TypeORM (@nestjs/typeorm), Prisma (prisma/@prisma/client,prisma/schema.prisma), or Mongoose (@nestjs/mongoose), if any.next(with anext.config.*) → Next.js web app. Also record: App Router (app/orsrc/app/with a rootlayout.tsx) vs. Pages Router (pages/orsrc/pages/) — or both, if they coexist; the installed Next major version (frompackage.json/the lockfile — caching and request-API semantics differ between 13/14, 15, and 16); and whethercacheComponents: trueis set innext.config.*(Cache Components model vs. the previous caching model).vue,express, etc. — other framework deps, as already covered.- No app-framework dependency present, but
main/exports/typesfields plus a co-locatedtsconfig.json→ a plain TypeScript/npm library (no framework), not an application.
composer.jsonand/or*.phpsources → PHP; record the PHP version constraint (require.php) and the test runner (Pest vs. PHPUnit), then tell the kind of project apart:laravel/frameworkincomposer.jsonplus anartisanfile at the root → Laravel application.- A PHP file at the plugin root whose header comment carries
Plugin Name:(typically<slug>/<slug>.php, often with areadme.txt) → WordPress plugin. - A
style.csswhose header comment carriesTheme Name:and/or atheme.json(block theme:templates/,parts/) → WordPress theme. - A main class that
extends Module(orPaymentModule/CarrierModule) in<module>/<module>.php, aconfig.xml, and/orprestashop/*dependencies incomposer.json→ PrestaShop module. - Any other
composer.jsonpackage (atypeoflibrary, or none, with PSR-4autoload) → plain PHP library/package.
requirements.txt,pyproject.toml,Pipfile,setup.py→ Python; recordrequires-pythonand the project/package manager (uv.lock→ uv,poetry.lock→ Poetry,pdm.lock→ PDM,Pipfile.lock→ Pipenv, otherwise pip/requirements*.txt) and the test runner (pytest, pytest-django, or Django'smanage.py test), then tell the kind of project apart:djangoamong the dependencies plus amanage.pyat the root (or the directory the module lives in) → Django project. Also record the settings module (DJANGO_SETTINGS_MODULEinmanage.py/pytest config, e.g.config.settings.local), the app layout (apps/<app>/vs. root-level apps), and the API layer:djangorestframework(DRF),django-ninja(Ninja), or neither.fastapiamong the dependencies (+ aFastAPI(app object, typicallyapp/main.pyorsrc/<pkg>/main.py) → FastAPI service. Also record the layout (app/layered,src/<pkg>/, or hexagonal ports/adapters), the persistence layer (SQLModel, SQLAlchemy 2.0 — sync or async —, or none) and whether Alembic is present.flask,pyramid,tornado, etc. — other Python web frameworks (no catalog key:other).- None of those, with a
[project]/[tool.poetry]table or asetup.py→ plain Python library/package.
Podfile,Package.swift,project.yml,Project.swift,*.xcodeproj/*.xcworkspace→ Swift and/or Objective-C:Package.swift(SwiftPM) — itsproducts:array tells library vs. executable (.library(...)vs..executable(...)), and itsplatforms:array (e.g..iOS(.v16),.macOS(.v13)) gives the target platforms directly.project.yml→ an XcodeGen-managed project;Project.swift→ a Tuist-managed project — either means the.xcodeprojitself is generated, so treat the generator file, not the generated project, as the source of truth for target/platform config, and read itsdeploymentTargetsetting for target platforms.- A hand-maintained
*.xcodeproj/*.xcworkspacewith no generator file present — read target platforms fromSUPPORTED_PLATFORMS/TARGETED_DEVICE_FAMILYin the.pbxprojor an.xcconfig. - Either way, check
import SwiftUIvs.import UIKitin source files for the UI framework in use, and.m/.mm/.hfile presence for Objective-C alongside.swift. - An app whose only platform is macOS (one
platform: macOSapp target /.macOS(...)deployment target, no iOS/watchOS/visionOS target) and the macOS desktop layout — anApp/UI layer plus a UI-free localPackages/Core, with no per-platformTargets/<Platform>/folders (those mean aniru-setup-apple-appscaffold, which staysapple-app (macos)), or a hand-maintained/other macOS-only project that has neither layout → a macOS desktop app: record the UI framework (swiftui— a SwiftUIApp;appkit— anNSApplicationDelegatewithNSWindowController/NSViewControllerand no SwiftUIApp) and the architecture from the layout (Packages/Core/Sources/Core/ViewModels/→ MVVM;…/Controllers/→ MVC), the App Sandbox/hardened-runtime entitlements, and the distribution files (ExportOptions-*.plist,scripts/make-dmg.sh) on theBuild & layout:line.
CMakeLists.txt,Makefile,*.vcxprojwith.c/.cpp/.h/.hppsources → C/C++.Cargo.toml→ Rust. Record whether it is a workspace ([workspace]members, anxtask/member), the edition andrust-version(MSRV),rust-toolchain.toml, and the lib/bin split (src/lib.rs,src/main.rs,[[bin]]entries). A binary target and aclapdependency (orratatui/crosstermfor a terminal UI) → a command-line tool: record the parser (clap derive vs. builder), the TUI library (ratatui+crossterm→ui: tui, elseui: none), the async runtime (tokio), the test crates (assert_cmd,predicates,snapbox/trycmd,insta), and the quality config ([lints],deny.toml,rustfmt.toml, cargo-llvm-cov / nextest config under.config/) on theBuild & layout:line. Any other crate is a plain Rust project.go.mod→ Go. Record the module path andgodirective, ago.workworkspace, and the layout (cmd/<name>/,internal/,pkg/). Apackage main(undercmd/<name>/or at the root) and a CLI framework —github.com/spf13/cobra,github.com/urfave/cli, orgithub.com/alecthomas/kong— or Bubble Tea (charm.land/bubbletea/v2,github.com/charmbracelet/bubbletea) → a command-line tool: record the framework, the TUI library (Bubble Tea →ui: tui), testscript e2e tests (testdata/script/*.txtar,github.com/rogpeppe/go-internal/testscript),.golangci.yml(v1 or v2 config) and.goreleaser.yamlon theBuild & layout:line. Any other module is a plain Go project.- Command-line tools in Swift and .NET — a
Package.swiftwhose.executableTargetdepends onArgumentParser(swift-argument-parser) → a Swift command-line tool (record the executable and library targets, e.g.<Bin>+<Bin>Kit, and the CLI e2e test target); a*.csprojwith<OutputType>Exe</OutputType>, none ofUseWPF/UseWinUI/UseWindowsForms, and aSystem.CommandLineorSpectre.Console.Clireference (or<PackAsTool>true) → a .NET command-line tool (record the Core project,PublishAot,PackAsTool, Spectre.Console / Terminal.Gui for a terminal UI). Both still use the existingswift/dotnetcoding keys. Gemfile→ Ruby.
- Source-level fallback: when manifests are absent, sparse, or ambiguous (e.g. a monorepo with multiple
stacks, or a manifest that doesn't disambiguate framework choice), sample actual source files — file
extensions,
import/using/#includestatements, and characteristic APIs — to confirm or fill the gap. - Antora documentation, if present (per Step 4): read
antora.yml(componentname/title) and the docs pages themselves — aninstallation.adoc/reference.adoc/getting-started.adocwill typically spell out the language and build tool explicitly (e.g. a Maven/Gradle/npm/NuGet dependency snippet, apodentry, animportexample). Treat this as a corroborating signal, not a substitute for the manifest/source checks above — but when manifests are ambiguous or a module lacks one of its own, the docs are often the clearest statement of intent, and are worth quoting directly rather than re-deriving from source alone. Note any mismatch between what the docs claim and what the manifests/source actually show (e.g. stale docs describing a since-migrated framework) instead of silently preferring one over the other. - Multiple stacks: if the repository contains more than one language/framework (e.g. a backend service plus a mobile client, or a monorepo of independent packages), record the stack per module/directory rather than flattening it into one list.
Languages/frameworks implicated by the requested change
If a ticket was fetched, read its title/description/comments for explicit or implicit tech signals — named languages, frameworks, or platforms (e.g. "iOS", "Android", "the web dashboard", "the API"), specific file/class names, or code snippets whose syntax identifies a language. Then cross-reference against the codebase stack just detected:
- If the ticket's signals match a part of the existing stack, note which module/language/framework the change targets.
- If the ticket names something not currently present in the codebase (e.g. a request to add a new mobile app to a backend-only repo, or to introduce a new framework), flag this explicitly as a new language/framework the work would introduce — don't silently assume it matches the existing stack.
- If nothing in the ticket indicates a specific target and the repo has a single stack, note that the change is presumed to apply to that stack. If the repo has multiple stacks and the ticket is genuinely ambiguous about which one it targets, say so rather than guessing.
If there is no ticket, this sub-step is just the codebase stack detected above — there is no requested change to cross-reference yet.
Step 6 — Check for a documentation MCP
Before reporting, check whether any documentation/knowledge-base MCP tools are connected in this session (e.g.
Confluence, Notion, or similar — search with ToolSearch using queries like "confluence", "notion",
"documentation", "wiki"). These are optional, environment-specific connectors, not something every repository or
user has configured.
If one or more are found, use them to search for pages relevant to:
- the ticket's title/keywords and any named components (if a ticket was fetched in Step 3), or
- the key components/domain areas identified in Step 4 (if there is no ticket).
Keep the search targeted — a handful of keyword queries against the ticket/codebase context, not a broad crawl of the whole space. Fetch and skim any clearly relevant pages (specs, design docs, architecture decision records, runbooks) that could sharpen a later implementation plan. Note what was found: page titles/links and a one-line summary of the relevant content, so it can be folded into Step 7's report.
If nothing relevant turns up even though a documentation MCP is connected, say so briefly rather than omitting the mention.
If no documentation MCP is connected, note that briefly and move on — this step is a best-effort enrichment and must never block exploration when no such tool exists.
Step 7 — Report findings
Summarize for the user in plain text (no file output unless asked):
Always include a Tech stack section, structured so later skills invoked in this same conversation (e.g.
iru-plan,iru-code, code review, branch/PR creation) can read it directly instead of re-detecting it themselves:## Tech stack - Languages (codebase): <e.g. Java, Kotlin> - Frameworks (codebase): <e.g. Spring Boot (backend/), Jetpack Compose (android/)> - Languages/frameworks (requested change): <e.g. Kotlin, Jetpack Compose — matches android/ module> - Project type: <one of: java-library, java-springboot, java-springboot-hilla, kotlin-springboot, kotlin-springboot-hilla, java-quarkus, kotlin-quarkus, typescript-library, react-web, angular-web, nestjs, nextjs, php-laravel, php-wordpress-plugin, php-wordpress-theme, php-prestashop-module, php-library, python-fastapi, python-django, python-library, android-library, android-app, swift-library, apple-app (ios, ipados, macos, watchos, visionos), macos-app (swiftui|appkit), react-native-app (expo|metro), ionic-app (angular|react), kmp-app (compose|native), windows-app (wpf|winui|winforms), cli-tool (rust|go|swift|dotnet), rust, go, dotnet, other, unknown> - Build & layout: <JVM backends: e.g. "Gradle (Kotlin DSL, wrapper), hexagonal reactor (domain/, application/, infrastructure/, api/)" or "Maven (wrapper), layered single-module"; NestJS: e.g. "ESM, Vitest, TypeORM"; Next.js: e.g. "Next 16, App Router, cacheComponents: true"; PHP: e.g. "PHP ^8.3, Pest"; Python: e.g. "Python >=3.12, uv, pytest, app/ layered, SQLModel async + Alembic" or "Python >=3.12, uv, pytest-django, DRF, config.settings"; React Native: e.g. "Expo SDK 57, Expo Router, EAS, Maestro" or "RN 0.8x CLI (Metro), React Navigation, CocoaPods"; KMP: e.g. "Gradle (Kotlin DSL, wrapper), shared/ + androidApp/ + iosApp/ (XcodeGen), Kover, detekt, ktlint"; command-line tools: e.g. "clap 4 + ratatui (ui: tui), xtask, nextest, cargo-llvm-cov" or "Cobra, cmd/mytool + internal/, testscript, golangci-lint v2, GoReleaser" or "swift-argument-parser, MyTool + MyToolKit" or "System.CommandLine, Native AOT, Spectre.Console, MyTool.Core" — omit for other stacks> - User interface: <"none" — or the UI stack(s) and where, e.g. "Jetpack Compose (app/), 14 screens, 31 components; .ui-quality.yml accessibility: enforce|report|off|none; Antora ui/ section: present (12 screen pages)" — or for a requested change that adds UI: the screens/components it introduces> - Accessibility: <present|partial|absent|not applicable (no UI)> — <evidence summary>; .ui-quality.yml: <value|missing> - Antora docs: <e.g. docs/ (antora.yml component "my-lib") — or "none found"> - Repository host: <e.g. GitHub (github.com/org/repo) — or Bitbucket / Azure DevOps / TFS, with base URL — or "no remote configured" — or "none — not a git repository">If Step 2 found the working directory isn't a git repository at all, use that last form and add a one-line warning restating what that disabled this run (git-remote-dependent tooling like unscoped
gh issue view, andgit log-based history in Step 4) versus what still ran normally (Jira, a documentation MCP, and any file-based checks in Step 4/5). If the repo has multiple modules/stacks, break the codebase lines out per module. If the requested change introduces something new (per Step 5), say so explicitly here rather than folding it silently into the existing list. The User interface line tellsiru-planto decompose the change into screens/components (with virtualized collections, UI tests, screenshots and accessibility checks — omitted when.ui-quality.ymlsaysaccessibility: none) andiru-update-docsto maintain the UI pages: name the UI framework(s), count screens (navigable destinations) and reusable components roughly, read.ui-quality.ymlif present (itsaccessibility:value may beenforce,report,offornone), and check whether the Antora module already has aui/section. Always state the Accessibility, Antora docs and Repository host lines, even when the answer is "none found"/"no remote", so later skills likeiru-update-docsor ones creating branches/PRs don't need to re-check.The
Project type:line is a normalized, single-token-per-module summary of the Step 5 signals — this exact vocabulary is a shared contract with theiru-setup-repositoryfront door, which reads this line verbatim to pre-select the right bootstrap flow, so never invent a value outside the list above. Derive it from Step 5's findings as follows:Project type Derived from (Step 5 signals) java-librarypom.xml/build.gradle*present, nospring-boot-starter*, no Quarkus, no Android pluginjava-springbootspring-boot-starter*dependency present, Java sources, no Hilla markersjava-springboot-hillahilla-spring-boot-starter/vaadin-spring-boot-starter(+@vaadin/hilla,src/main/frontend/)kotlin-springbootspring-boot-starter*+ Kotlin (kotlin-maven-plugin/kotlin("jvm")/kotlin("plugin.spring")/src/main/kotlin/), no Hilla markerskotlin-springboot-hillaKotlin Spring Boot (as above) + the Hilla markers java-quarkusio.quarkusplugin /quarkus-bom/io.quarkus:quarkus-*deps, Java sourceskotlin-quarkusQuarkus (as above) + Kotlin ( quarkus-kotlin, Kotlin plugin,src/main/kotlin/)typescript-librarypackage.jsonwithmain/exports/types+tsconfig.json, no app-framework depreact-webpackage.jsonwithvite+react(or another React web setup, not Native/Ionic)angular-web@angular/cli/@angular/core+angular.json, not layered under Ionicnestjs@nestjs/coredependency (+nest-cli.json,NestFactoryinsrc/main.ts)nextjsnextdependency (+next.config.*,app/and/orpages/)php-laravelcomposer.jsonwithlaravel/framework+ anartisanfilephp-wordpress-pluginMain PHP file with a Plugin Name:header commentphp-wordpress-themestyle.csswith aTheme Name:header and/ortheme.jsonphp-prestashop-moduleClass extends Module(+config.xml,prestashop/*deps)php-libraryAny other composer.jsonpackage (no Laravel/WordPress/PrestaShop markers)python-fastapifastapidependency (+ aFastAPI(app, e.g.app/main.py)python-djangodjangodependency + amanage.pypython-libraryAny other Python package ( pyproject.toml/setup.py, no Django/FastAPI/other web framework)android-libraryGradle com.android.libraryplugin (direct or vialibs.versions.tomlalias)android-appGradle com.android.applicationplugin (direct or vialibs.versions.tomlalias)swift-libraryPackage.swiftwith a.library(...)productapple-appAn Xcode/XcodeGen/Tuist app target (or a Package.swift.executable(...)product that isn't an ArgumentParser command-line tool)macos-appAn Xcode/XcodeGen/Tuist app whose only platform is macOS, not in the iru-setup-apple-appTargets/<Platform>/layoutreact-native-appexpo/react-nativedeps (+app.json/metro.config.js/eas.json,ios/+android/)kmp-appKotlin Multiplatform plugin with Android + iOS targets (+ iosApp/,commonMain/)ionic-app@ionic/angularor@ionic/react(+@capacitor/core,capacitor.config.*)windows-appA WinExe*.csprojwithUseWPF/UseWinUI/UseWindowsForms(Windows desktop app)cli-toolA command-line tool: Rust binary + clap(orratatui); Gopackage main+ Cobra/urfave/kong (or Bubble Tea); aPackage.swift.executableTargetonArgumentParser; anExe*.csproj(no WPF/WinUI/WinForms) withSystem.CommandLine/Spectre.Console.Cli/PackAsToolrustAny other Cargo.tomlcrate or workspace (library, service)goAny other go.modmodule (library, service)dotnetAny other *.csproj/*.fsproj/*.sln/*.slnx(library, ASP.NET Core, MAUI/Xamarin)otherA stack was detected but has no key above (e.g. Vue, Flutter, Micronaut, Flask, Ruby, C/C++, a KMP library with no app) unknownNothing in Step 5 matched any manifest or source-level signal apple-applists its detected target platforms in parentheses, using the platform keysios,ipados,macos,watchos,visionos(e.g.apple-app (ios, ipados)) — derived fromPackage.swift'splatforms:array,project.yml/Project.swift'sdeploymentTarget/platform, orSUPPORTED_PLATFORMS/TARGETED_DEVICE_FAMILY, as detected in Step 5. ItsBuild & layout:line also records the iOS target's UI framework (swiftui, oruikit— aUIApplicationDelegate+UIWindowSceneDelegatewith no SwiftUIApp) and the architecture fromPackages/Core/Sources/Core/ViewModels/(MVVM) vs…/Controllers/(MVC).ionic-applists its underlying framework in parentheses —ionic-app (angular)orionic-app (react)— from whichever of@ionic/angular/@ionic/reactwas found.react-native-applists its toolchain in parentheses —react-native-app (expo)orreact-native-app (metro)— per Step 5's rule (theexpodependency decides; committed native folders alone don't).macos-applists its UI framework in parentheses —macos-app (swiftui)ormacos-app (appkit). It takes precedence overapple-app (macos)except for aniru-setup-apple-appscaffold (Targets/macOS/…), which staysapple-app (macos)so it keeps its own setup chain; an app with macOS plus any other Apple platform staysapple-app.windows-applists its UI stack in parentheses —windows-app (wpf),windows-app (winui)orwindows-app (winforms). Itssrc/<App>.Coreclass library and test projects are part of the same value, never extradotnetentries ormultiple.cli-toollists its language in parentheses —cli-tool (rust),cli-tool (go),cli-tool (swift)orcli-tool (dotnet)— and itsBuild & layout:line names the argument parser, the terminal-UI library when there is one (ui: tui), and the e2e test setup. It takes precedence overrust/go/swift-library/apple-app/dotnetfor the same module: the library unit a CLI keeps its logic in (src/lib.rs,internal/,<Bin>Kit,src/<Tool>.Core) and a Rustxtask/workspace member are part of the same value, never extra entries ormultiple.kmp-applists its UI approach in parentheses —kmp-app (compose)(Compose Multiplatform shared UI) orkmp-app (native)(shared logic, platform-native UI). Its Android host module (androidApp/) andiosApp/are part of the same value, never extraandroid-app/apple-appentries ormultiple.- Java vs. Kotlin (Spring Boot / Quarkus): pick the
kotlin-*value when Kotlin is the build's primary language (Kotlin plugin applied and production sources mainly undersrc/main/kotlin/); a Java build with a few Kotlin files staysjava-*. A hexagonal multi-module reactor (domain/application/infrastructure/apimodules) is still a single project type — e.g.kotlin-springbootwith the layout on theBuild & layout:line — notmultiple. - PHP: Laravel, WordPress, and PrestaShop markers take precedence over
php-library(a Laravel app or a PrestaShop module also has acomposer.json). A WordPress plugin that ships blocks is stillphp-wordpress-plugin; a repository holding both a plugin and a theme ismultiple. - Python: Django and FastAPI markers take precedence over
python-library. A Django project that also mounts a FastAPI app (or the reverse) is classified by its primary entry point (manage.py→python-django); two independent services in one repository aremultiple. Flask/Pyramid/Tornado projects areother. - Hilla frontend vs. Next.js/NestJS: a
package.jsonunder a Spring Boot module'ssrc/main/frontend/is part of the*-springboot-hillavalue, never a separatenextjs/react-webmodule. - Examples:
- Project type: kotlin-quarkuswith- Build & layout: Gradle (Kotlin DSL, wrapper), layered single-module;- Project type: nextjswith- Build & layout: Next 16, App Router, cacheComponents: true;- Project type: php-wordpress-pluginwith- Build & layout: PHP >=8.1, PHPUnit. - Android library with a sample app: when every
com.android.applicationmodule depends on a siblingcom.android.librarymodule (implementation(project(":lib"))) — this catalog's reference library layout,lib/+ Composeapp/— the value isandroid-library, with the sample module recorded on an indented sub-line for information (- sample app: app/), notmultiple(reportingmultiplehere makes the front door ask which module to bootstrap for what is a single library project). - Multiple modules of different types: when the repository contains more than one module with a distinct
project type (e.g. a backend plus a mobile client, or two independent Android apps), the line's value is
multiple, followed by one<module-path>: <type>entry per module on indented sub-lines, e.g.:- Project type: multiple - backend/: java-springboot - android/: android-app - Say
unknownonly when nothing in Step 5 matched anything at all; sayotherwhen something clearly matched (a manifest and/or source-level signal was found) but that stack has no key in the table above.
If Step 6 found a connected documentation MCP, include a Related documentation section listing each relevant page found (title, link, one-line summary) — or a one-line note that none was relevant/connected. This is what a later
iru-planstep should draw on for additional context beyond the codebase and ticket.Include a Related past implementation plans section covering both the
.archive/check from Step 4 and, for a Jira ticket, the attached-plan check from Step 3: name any archived or downloaded plan(s) used as precedent (file name/source — local.archive/vs. downloaded from the ticket/epic/linked ticket — its original topic, and what carries over — task breakdown, granularity, or approach), or state explicitly that neither source had anything relevant (.archive/doesn't exist or nothing in it was relevant, and noimplementation_plan_*.mdattachment was found). This is what a lateriru-planstep should draw on to ground a new plan's structure in a proven prior one.If a ticket was explored: restate the task in your own words, list the specific files/classes/methods relevant to it, explain how the current code behaves in the area the ticket touches, and flag anything ambiguous or missing from the ticket that would block implementation. For a Jira ticket, also name its epic (if any) and any linked/related tickets fetched in Step 3, with a one-line summary of what each adds (a shared constraint from the epic, what a "blocks"/"relates to" link actually implies here) — or state plainly that the ticket has no epic and no links if that's the case.
If codebase-only: summarize the architecture areas covered and anything notable found (e.g. inconsistencies, undocumented behavior, missing test coverage) relevant to general orientation.
Do not propose an implementation plan or start editing code — if the user wants that next, they will ask for it (e.g. via planning mode) as a separate step.