Setup Readme

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

Create or refresh a repository’s root README.md by exploring what actually exists — build files, CI workflows, quality-tool config, documentation, license, and source code — and composing only the sections that real material supports.

Purpose

iru-setup-readme never invents version numbers, badge URLs, dashboard links, or example code that don’t correspond to something actually present in the repository. It gathers project identity (repository/host, description, license, build tool, current and latest-released versions), taking the stack from iru-explore’s `Project type: line — reused from earlier in the conversation when available, otherwise obtained by invoking iru-explore itself, so the manifest to project-type table lives in exactly one place; only when iru-explore isn’t installed does it fall back to a minimal one-manifest check. Beyond the library and app stacks (Java/Maven, Gradle/Kotlin, Vite+React, Angular, Hilla, Expo, Ionic, Android, Swift, plain TypeScript), it tailors sections for macOS desktop apps (SwiftUI/AppKit), Windows desktop apps (WPF/WinUI 3/Windows Forms), Spring Boot (Java or Kotlin, Maven or Gradle KTS), Quarkus, Laravel, WordPress plugins and themes, PrestaShop modules, plain Composer packages, NestJS, Next.js, FastAPI, Django, plain Python packages, command-line tools (Rust clap/Ratatui, Go Cobra/Bubble Tea, Swift ArgumentParser, .NET System.CommandLine) and plain Rust crates and Go modules. Identity is read from the file that owns it for each stack: springboot-stack.yml/quarkus-stack.yml, gradle.properties, config/app.php (Laravel), the WordPress plugin/theme headers, the PrestaShop module class, pyproject.toml ([project].name/version, requires-python, with framework versions from uv.lock), project.yml/Project.swift (macOS apps, adding the deployment target, UI framework and App Sandbox status rows), Directory.Build.props and the app *.csproj/Package.appxmanifest (Windows apps: <Version>, target framework, UI stack, Windows App SDK version, MSIX identity), or git tags. For Rust and Go it reads Cargo.toml ([package], , rust-version, publish) or go.mod (module path, go and toolchain lines, cmd/<bin>/); Swift and .NET command-line tools use Package.swift and Directory.Build.props/global.json.

Command-line tools (cli-tool (rust|go|swift|dotnet)) get their own treatment: status-table rows for the toolchain floor, argument parser, terminal-UI library and release targets; crates.io/docs.rs, pkg.go.dev, NuGet and GitHub-release badges (each only after a live check); a link to the generated CLI reference page; and an install section listing only the channels the release workflow really wires (Homebrew tap, cargo install, go install, Scoop/WinGet, dotnet tool install -g, or the release archive with SHA256SUMS and gh attestation verify) plus build from source. Plain rust/go projects get only identity, badges, docs links and a cargo add/go get snippet.

Desktop apps (macos-app, windows-app) get no dependency snippet: when a release workflow exists the README gets an "Install" subsection matched to what it publishes (a notarized DMG or Mac App Store link; a Windows zip, MSIX/.appinstaller, winget install or Microsoft Store link — store URLs as placeholders), followed by "Build and run locally" steps (xcodegen/xcodebuild/swift test for macOS; dotnet build/dotnet run/dotnet test --filter "TestCategory!=UI" and the .NET 10 SDK prerequisite for Windows).

Badges are only emitted for resources that exist: CI status, SonarCloud/SonarQube, npm, Maven Central, Swift Package Index, Packagist, PyPI (Python libraries only) and WordPress.org (all only after a live check that the package or slug is published), static PHP/Python/WordPress/PrestaShop requirement badges (plus FastAPI/Django framework badges), and a GHCR container-image badge taken from the workflow’s actual images: value. The project status table grows extra rows (platforms, SDKs, Kotlin, PHP, Swift tools, Node engine, TypeScript, framework, Distribution) only for the stacks they apply to. Documentation links cover the Antora site, Maven/Gradle site report, Sonar dashboard, generated API docs (TypeDoc, Compodoc, Storybook, Dokka including Spring Boot’s /api/kdoc/, phpDocumentor, DocC (Swift/macOS apps, from the workflow’s api/ copy step), DocFX (.NET/Windows desktop apps, when docfx.json exists), Sphinx, generated REST/gRPC/AsyncAPI docs and OpenAPI schemas for FastAPI/Django), a static-export live site, registry/store pages and CHANGELOG.md.

Libraries get an Installation section (Maven, Gradle with an optional version-catalog form, npm plus pnpm/yarn when the lockfile shows it, SwiftPM, Python via uv add/pip install when live on PyPI, Composer). Services, web apps, plugins and modules get a Getting Started section instead, built only from commands the repository really defines: Spring Boot (bootRun/ spring-boot:run, the local profile, Actuator health, bootBuildImage), Quarkus (dev mode, Dev UI, packaged jar, native, container image), Laravel (composer run setup/dev, optional Sail), WordPress (WordPress.org, GitHub Release zip, WPackagist, wp-env), PrestaShop (module zip upload), NestJS, Next.js, FastAPI (uv sync, uv run fastapi dev, Swagger UI at /docs) and Django (manage.py migrate/runserver, admin, schema docs), plus a pull snippet for a released GHCR image. The "how it works" section for a service is a curl against a real route; it is omitted entirely when there is no meaningful source yet. A WordPress readme.txt is read for facts but never written.

The skill announces whether it is creating the README from scratch or updating an existing one. If README.md already exists, it warns the user, preserves any hand-written section it can’t regenerate (e.g. "Contributing"), flags where the file contradicts this run’s choices (stale Sonar badges under sonar: none, a github.io link under pages: no), and shows the proposed content as a diff before writing. A generator’s stock README (Laravel, create-next-app, nest new, quarkus create) is recognised as boilerplate, so Replace is recommended over Update. The user picks Update (merged draft, hand-written sections kept), Keep as is (file untouched; the report lists each mismatch), or Replace (only generated sections written). Under ci: no / pages: no it omits CI badges and never links a github.io site that nothing publishes, pointing at the docs/ sources and the local Antora build command instead.

Purpose group

Repository Bootstrap

Plugin

Shipped by the iru-core plugin of the ai-catalog marketplace (install with /plugin install iru-core@ai-catalog; see Plugins).

Invocation

/iru-setup-readme
/iru-setup-readme sonar: none
/iru-setup-readme
sonar: none
ci: no
pages: no
on-existing: update

Inputs

Argument Required Description Default

sonar

No

cloud, self-hosted, or none. Only none changes behaviour: it suppresses every SonarCloud/SonarQube badge and the dashboard link, even when a sonar {} block or sonar-project.properties is present on disk (a mode: existing repository may carry Sonar config the user has just chosen not to wire up). Passed by this catalog’s setup orchestrators with the value they already resolved, so the choice isn’t re-asked or re-detected here.

Detected from the repository’s own Sonar config.

ci

No

yes or no. Only no changes behaviour: every CI status badge and the CI row of the status table are skipped, even if stale .github/workflows/*.yml files exist. ci: no also implies pages: no.

Detected from the workflows present.

pages

No

yes or no. Only no changes behaviour: no https://<owner>.github.io/<repo>; link is emitted (Antora site, Maven site report, TypeDoc/Compodoc/Storybook/Dokka/phpDocumentor/DocC/Sphinx, or a static-export site), because CI only uploads the built docs as a workflow artifact. Readers are pointed at docs/ and the local cd docs && npx antora antora-playbook.yml build instead.

Detected from whether a workflow publishes to gh-pages.

on-existing

No

ask, keep, update, or replace — how Step 9 treats an existing README.md. keep stops after the warning and leaves the file untouched; update/replace are applied without asking (the diff is still shown). mode: existing alone does not mean "update silently".

ask

other key: value lines

No

Ignored (e.g. mode, visibility).

N/A

(all other inputs)

No

Everything else is derived by exploring the repository directly (pom.xml/build.gradle*/composer.json/package.json/pyproject.toml/uv.lock/Package.swift/WordPress plugin or theme headers/PrestaShop module class/Android Gradle modules/Xcode or Tuist project files, git remote, .github/workflows/*.yml, Sonar config, Antora docs, CHANGELOG.md, LICENSE, and source code), with the project type taken from iru-explore’s `Project type: line (reused from the conversation, or obtained by invoking iru-explore).

Not applicable.

Outputs

  • README.md at the repository root — newly created, or updated or replaced after the user’s choice.

  • If README.md didn’t previously exist: it is written directly, no approval step needed.

  • If README.md already existed: the full proposed content (or diff) is shown first, together with the hand-written sections that were preserved and any contradiction with this run’s sonar/ci/pages choices. The file is only written on Update or Replace (from the user or on-existing); under Replace the preserved hand-written sections are dropped; under Keep as is it is left untouched. Any partial-apply request is handled by revising the draft in free text before writing.

  • A closing report that starts by restating the mode (created from scratch, or updated / kept as is / replaced and whether that came from the user or on-existing; under Keep as is, each mismatch with this run’s choices), naming which sections were included versus omitted and why (e.g. no Installation section because no build/package config was found), any fact that had to be inferred rather than confirmed, and a reminder to double-check the "How It Works"/example section specifically since it depends on this skill’s reading of the current API.

Execution flow

flowchart TD A[Start /iru-setup-readme] --> A0["Step 0: Resolve args\n(sonar, ci, pages, on-existing)"] A0 --> B{"Step 1: README.md already\nexists at root?"} B -- no --> B1["Announce: creating from scratch"] B1 --> D B -- yes --> B2["Announce: updating existing README;\nwarn that changes will be proposed\n(flag generator boilerplate)"] B2 -- on-existing is keep --> N B2 --> C["Read existing content"] C --> D C --> D["Step 2: Gather project identity\n(repo/host, description, license,\nmulti-stack detection, versions)"] D --> E["Step 3: Gather badge sources\n(CI unless ci: no, SonarCloud unless\nsonar: none, registry badges, PHP/WP/\nPrestaShop/Python requirements, PyPI, GHCR image)"] E --> F["Step 4: Build project status table\n(+ platform/SDK/Kotlin/PHP/Swift/\nNode/TS/Python/framework/Distribution rows;\nCLI: toolchain floor, parser, TUI, targets)"] F --> G["Step 5: Gather documentation links\n(+ generated API docs: TypeDoc,\nCompodoc, Storybook, Dokka, phpDoc, DocC, Sphinx,\nOpenAPI schema;\nno github.io links under pages: no)"] G --> H["Step 6: Compose Installation or\nGetting Started (dependency snippets,\nservice/plugin run commands,\nGHCR pull, store links)"] H --> I["Step 7: Write how-it-works\nsection with a real example\n(curl for services; via Explore agent)"] I --> J["Step 8: Compose remaining structural\nsections; preserve hand-written extras"] J --> K{"Did README.md\nalready exist?"} K -- no --> L["Write README.md directly"] K -- yes --> M["Step 9: Show diff and mismatches;\nask Update / Keep as is / Replace\n(or apply on-existing)"] M -- Update --> L M -- Replace --> M2["Drop preserved hand-written sections"] M2 --> L M -- Keep as is --> N["Leave existing README.md untouched"] L --> O["Step 11: Restate mode and option;\nreport"] N --> O

Dependencies

Invokes

  • Explore — Step 2, only when no iru-explore report with a Project type: line is already available in the conversation: invoked with no ticket argument to obtain the project type, build tool, and framework instead of re-deriving them from manifests. When iru-explore isn’t installed, a minimal one-manifest check stands in.

Invoked by

Related agents

  • Explore (see Agents) — used in Step 7 to locate the main source entry points before reading them directly, rather than reading the whole source tree — the same agent the iru-explore skill itself uses for this kind of broad structural search.

Source

SKILL.md on GitHub — the file this page was generated from.