Add MiniSpec setup and CLAUDE.md

Initialize MiniSpec (falkenslab/minispec) with Claude integration and fill
.minispec/core/ with the project's architecture, stack, conventions and
glossary. CLAUDE.md keeps only build commands and the MiniSpec pointer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: fvarrui

.claude/skills/minispec-adr/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: minispec-adr
+description: Record an architectural decision as a new ADR under .minispec/decisions/ from the ADR template. Use when an important, hard-to-reverse decision is made.
+---
+
+# MiniSpec: new ADR
+
+Record a permanent architectural decision under `.minispec/decisions/`.
+
+## Steps
+
+1. Read `.minispec/README.md` for the standard.
+2. Read the template `.minispec/templates/adr.md`.
+3. Determine the next sequential number: list `.minispec/decisions/`, find the
+   highest `ADR-NNN-*` and add 1. Numbers are never reused or renumbered.
+4. Create `.minispec/decisions/ADR-NNN-<slug>.md` with `<slug>` in kebab-case.
+5. Fill the three sections:
+   - **Decision** — what was decided, one or two sentences.
+   - **Motivation** — why; what problem it solves, what was rejected.
+   - **Consequences** — what it commits us to; trade-offs, follow-ups.
+
+## Rules
+
+- One page. No more. Document the *why*, not the implementation.
+- Only record decisions that are important and worth not re-litigating. Don't
+  write an ADR for plain stack facts.
+- If the decision changes a rule, also update `.minispec/core/conventions.md`.

.claude/skills/minispec-bugfix/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: minispec-bugfix
+description: Document a bug and its fix as a MiniSpec bugfix note under .minispec/features/ from the bugfix template. Use when fixing a non-trivial bug worth recording.
+---
+
+# MiniSpec: new bugfix
+
+Document a bug and its fix using the bugfix format. It is temporal knowledge, so
+it lives under `.minispec/features/`.
+
+## Steps
+
+1. Read `.minispec/README.md` for the standard.
+2. Read the template `.minispec/templates/bugfix.md`.
+3. Create `.minispec/features/fix-<slug>.md` with `<slug>` in kebab-case.
+4. Fill the four sections:
+   - **Problem** — observable symptom.
+   - **Cause** — root cause.
+   - **Solution** — what was changed.
+   - **Verification** — how the fix was confirmed.
+
+## Rules
+
+- Max 100 lines. Short and factual. Base it on the real diff.
+- Temporal: once the fix is merged and verified, delete this file. If the fix
+  revealed a permanent lesson (a rule, a decision), promote it to `core/` or an
+  ADR first. Mention this; do not delete now.

.claude/skills/minispec-feature/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: minispec-feature
+description: Create a new MiniSpec feature document under .minispec/features/ from the feature template. Use when starting work on a feature, refactor, or migration that needs a short spec.
+---
+
+# MiniSpec: new feature
+
+Create a temporal feature document under `.minispec/features/`.
+
+## Steps
+
+1. Read `.minispec/README.md` to honor the standard (writing rules, formats).
+2. Read the template `.minispec/templates/feature.md`.
+3. Derive a kebab-case slug for the feature (e.g. `github-sync`). The file is
+   `.minispec/features/<slug>.md`. If it already exists, update it instead of
+   overwriting blindly.
+4. Fill the four sections (Goal / Context / Changes / Acceptance):
+   - **Goal** — one sentence.
+   - **Context** — current state: what exists, what's missing, why now.
+   - **Changes** — short bullet list of the work.
+   - **Acceptance** — observable done conditions.
+5. Base content on the real code and the user's description. Don't invent.
+
+## Rules
+
+- Max 100 lines. Short sentences and lists. No filler.
+- This is TEMPORAL knowledge: describe work in progress only.
+- Reminder for later: when the feature is done, promote anything permanent it
+  revealed (a decision → ADR, a rule → conventions, a term → glossary) and then
+  DELETE the feature file. Mention this to the user; do not delete now.

.claude/skills/minispec-implement/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: minispec-implement
+description: List pending MiniSpec features (.minispec/features/) and implement the chosen one following the MiniSpec reading contract. Use when the user wants to turn a feature spec into code. Accepts an optional feature slug as argument.
+---
+
+# MiniSpec: implement a feature
+
+Turn a MiniSpec feature spec into code. MiniSpec is not a codegen pipeline: this
+skill just loads the right context and implements the feature like any task.
+
+## Steps
+
+### 1. Pick the feature
+
+- The files in `.minispec/features/` are the **pending / in-progress** work
+  (MiniSpec's temporal knowledge). Each `*.md` is a candidate; `fix-*.md` are
+  bugfix notes.
+- If the user named a feature (argument or message), use that one. Match by slug
+  (filename without `.md`); if ambiguous or not found, list and ask.
+- If no feature was named, **list the features** with a one-line summary of each
+  (read each file's `# title` and `Goal`) and **ask the user which to
+  implement**. Do not guess.
+- If `.minispec/features/` is empty, tell the user there's nothing pending and
+  offer to create one with `/minispec-feature`.
+
+### 2. Load context (reading contract)
+
+Read `.minispec/README.md`, then follow its reading contract:
+
+- Always: `core/project.md`, `core/conventions.md`, `core/principles.md`.
+- The chosen `features/<slug>.md`.
+- On demand only: `core/architecture.md`, `core/stack.md`, `core/glossary.md`,
+  and any `decisions/ADR-*.md` the feature touches.
+
+Do not read the whole `.minispec/` — only what the task needs.
+
+### 3. Implement
+
+- Write code that satisfies the feature's **Changes**, respecting
+  `conventions.md` and `principles.md`.
+- Stay within scope: no refactors outside the feature (a principle).
+
+### 4. Verify
+
+- Check the result against the feature's **Acceptance** section, point by point.
+- Report what passes and what doesn't.
+
+### 5. Close the feature (remind, don't auto-delete)
+
+When the feature is done and verified, MiniSpec says to:
+
+1. Promote anything **permanent** it revealed — a decision → ADR
+   (`/minispec-adr`), a rule → `core/conventions.md`, a term → `core/glossary.md`.
+2. Then **delete** `features/<slug>.md`.
+
+Tell the user this and offer to do it. Do not delete without confirmation.
+
+## Rules
+
+- Don't invent requirements not in the spec; if the spec is thin, ask before
+  coding.
+- This skill chooses and implements; it does not rewrite the spec.

.minispec/README.md

@@ -0,0 +1,73 @@
+# MiniSpec v1.0
+
+A lightweight specification standard for AI-assisted software development.
+
+MiniSpec separates **permanent knowledge** (what the project *is*) from
+**temporal knowledge** (what is *being worked on*). The goal is to give an AI
+agent the minimum context it needs — and nothing more.
+
+## Reading contract (for the agent)
+
+**Always read first:**
+
+- `core/project.md`
+- `core/conventions.md`
+- `core/principles.md`
+
+**Read on demand:**
+
+- Touching architecture → `core/architecture.md`
+- Unsure about the stack → `core/stack.md`
+- Domain terms → `core/glossary.md`
+- Working on a feature → the matching `features/*.md`
+- Structural decision → the relevant `decisions/ADR-*.md`
+
+**Negative rule:** do not read anything you don't need for the task.
+
+## Structure
+
+```
+.minispec/
+├── README.md          this file — the reading contract
+├── core/              PERMANENT knowledge (rarely changes)
+├── decisions/         ADRs — important decisions (permanent)
+├── features/          TEMPORAL knowledge — work in progress only
+└── templates/         templates for new documents
+```
+
+## Writing rules
+
+1. **Hard limit: 100 lines per document.** `project.md` ≤ 50, `principles.md` ≤ 20.
+2. Short sentences and lists. No filler prose.
+3. One document = one topic. Never mix permanent and temporal knowledge.
+4. Don't explain general technologies or concepts — only what is specific to
+   this project.
+5. Don't duplicate what the code already says. Document the *why*, not the *how*.
+
+## Document formats
+
+- **Feature** — `Goal / Context / Changes / Acceptance`
+- **ADR** — `Decision / Motivation / Consequences`
+- **Bugfix** — `Problem / Cause / Solution / Verification`
+
+## Naming
+
+- Core: fixed names (`project.md`, `architecture.md`, `stack.md`,
+  `conventions.md`, `glossary.md`, `principles.md`).
+- ADR: `ADR-NNN-slug.md`, sequential, never renumbered.
+- Feature / Bugfix: `slug.md` (kebab-case).
+
+## Feature lifecycle
+
+A feature file describes **work in progress only**. When a feature is done:
+
+1. Promote anything **permanent** it revealed (a decision → ADR, a rule →
+   `conventions.md`, a term → `glossary.md`).
+2. **Delete** the feature file.
+
+If `features/` is empty, nothing is in flight.
+
+## Maintenance
+
+- Changing any rule in this standard bumps the version declared at the top.
+- Keep documents small. When in doubt, cut.

.minispec/core/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+## Flow
+
+```
+PackageMojo (Maven) | PackagePlugin + PackageTask (Gradle)
+  → Context.setContext(MavenContext | GradleContext)
+  → PackagerFactory.createPackager(platform) + fluent settings
+  → packager.createApp() → packager.generateInstallers() → packager.createBundles()
+```
+
+## Key pieces
+
+- `packagers/Context` — static singleton hiding the build tool. Declares tool-specific operations (runnable JAR, copy dependencies, tarball, zipball, license, Launch4j EXE) and registers installer generators per platform.
+- `maven/MavenContext` — implements them by running other Maven plugins through `mojo-executor` (`maven/*` classes).
+- `gradle/GradleContext` — implements them with Gradle tasks (`gradle/*` classes with the same names).
+- `PackagerSettings` — every configuration property, with fluent setters. Also the base of the Gradle extension `PackagePluginExtension`.
+- `Packager` — shared pipeline: init, resolve resources/icons/license, app folder structure, bundle JRE, run installer generators. Subclasses `WindowsPackager`, `MacPackager`, `LinuxPackager` implement `doInit`, `doCreateAppStructure`, `doCreateApp`.
+- `ArtifactGenerator<T>` — unit of work: `skip(packager)` decides, `doApply(packager)` produces a `File`. Installers (`GenerateDeb`, `GenerateDmg`, `GenerateMsi`, ...), `BundleJre` and the Windows EXE creators are generators.
+- `utils/VelocityUtils` — renders `.vtl` templates, first from the user's `assetsDir`, then from the classpath. The packager is exposed as `$info` (plus `$StringUtils`, `$GUID`, `$features`).
+- `utils/CommandUtils` — runs external tools (`jlink`, `jdeps`, `iscc`, `candle`/`light`, `hdiutil`, `pkgbuild`, `codesign`, `rcedit`).
+- `utils/Logger` — wraps the Maven or Gradle logger, with indentation helpers.
+- `net/jsign/WindowsSigner` — Windows code signing on top of `jsign-core`.
+
+## Windows launcher
+
+`WindowsConfig.exeCreationTool` picks how the EXE is built: `launch4j` (via the context), `winrun4j` (`CreateWindowsExeWinRun4j`) or `why` (`CreateWindowsExeWhy`).
+
+## WiX version
+
+`GenerateMsm` detects the WiX major version (`wix -version`, falling back to `candle`/`light` as v3) and stores it in the packager. `GenerateMsi` relies on that, so MSM must stay registered before MSI in `Context`. v3 uses `candle` + `light`; v4+ uses `wix build`.
+
+## Folder map
+
+- `src/main/java/.../javapackager/maven/` — Maven mojo and Maven-based operations.
+- `src/main/java/.../javapackager/gradle/` — Gradle plugin, task, extension and Gradle-based operations.
+- `src/main/java/.../javapackager/packagers/` — build-tool-independent pipeline and generators.
+- `src/main/java/.../javapackager/model/` — configuration model (`WindowsConfig`, `MacConfig`, `LinuxConfig`, `FileAssociation`, ...).
+- `src/main/java/.../javapackager/utils/` — helpers (files, commands, Velocity, JDK, icons, XML).
+- `src/main/resources/{linux,mac,windows}/` — Velocity templates, default icons and bundled native binaries (WinRun4J, `JavaLauncher.exe`, `rcedit-x64.exe`, `nativeJavaApplicationStub*`, `universalJavaApplicationStub.sh`).
+- `docs/` — user documentation for platform-specific properties and samples.

.minispec/core/conventions.md

@@ -0,0 +1,14 @@
+# Conventions
+
+- Keep Java 8 compatibility: no APIs or syntax newer than Java 8.
+- Indent Java with tabs.
+- Build with the wrapper: `./gradlew build`. Test changes with `./gradlew publishToMavenLocal` and a real sample project; there are no unit tests.
+- Any change must keep working in both Maven and Gradle. Build-tool-specific code goes only in `maven/` or `gradle/`, behind `Context`.
+- A new configuration property is wired in: `PackagerSettings` (field + fluent setter + getter), `PackageMojo` (`@Parameter` + fluent call in `execute()`), `PackageTask` (annotated field + fluent call in `createPackager()` with `defaultIfNull(taskValue, extension.getX())`), and documented in `README.md` or `docs/*-specific-properties.md`.
+- Platform-specific options go in `WindowsConfig`, `MacConfig` or `LinuxConfig`, not in `PackagerSettings`.
+- New artifacts are `ArtifactGenerator` subclasses. Platform and external-tool checks go in `skip()`, not in `doApply()`.
+- Template names and the variables they use are public API: users override them from `assetsDir`. Renaming a template or changing its variables is a breaking change.
+- Log through `utils/Logger`, never `System.out`.
+- Run external tools through `utils/CommandUtils`.
+- Bundled native binaries in `src/main/resources` are not edited by hand. `updateWhyJavaLauncher` refreshes `JavaLauncher.exe`; `updateUniversalJavaApplicationStub` only matters for `universalJavaApplicationStub.sh`.
+- A fix is verified by packaging on the affected OS; record how in the bugfix note.

.minispec/core/glossary.md

@@ -0,0 +1,53 @@
+# Glossary
+
+## App folder
+
+The generated directory `${outputDirectory}/${name}` with the native app: launcher, JAR, `libs`, JRE and resources. Installers and bundles are built from it.
+
+## Assets dir
+
+`assetsDir` (default `assets/` in the project). Holds user icons and templates organized by platform (`linux/`, `mac/`, `windows/`) that replace the plugin defaults with the same name.
+
+## Bootstrap script
+
+Optional user script (`scripts.bootstrap`) run by the startup script before launching the app.
+
+## Bundle
+
+Zipball or tarball of the app folder (`createZipball`, `createTarball`).
+
+## Context
+
+The build-tool abstraction (`MavenContext` or `GradleContext`), held statically in `Context`.
+
+## Customized JRE
+
+JRE generated with `jlink`, containing only the modules found by `jdeps` or listed in `modules`.
+
+## EXE creation tool
+
+How the Windows launcher is built: `launch4j`, `winrun4j` or `why`.
+
+## Generator
+
+An `ArtifactGenerator`: a step that may be skipped and produces one file (installer, JRE, EXE).
+
+## Installer
+
+A platform package built from the app folder: DEB, RPM, AppImage, DMG, PKG, Inno Setup EXE (setup), MSI, MSM.
+
+## Packager
+
+The platform-specific orchestrator (`WindowsPackager`, `MacPackager`, `LinuxPackager`).
+
+## Platform
+
+Target OS: `auto`, `linux`, `mac` or `windows`. May differ from the OS running the build.
+
+## Runnable JAR
+
+The app JAR with a manifest pointing to `mainClass`, created by the plugin unless `runnableJar` is given.
+
+## Mac startup
+
+macOS launcher type (`macStartup`): `UNIVERSAL`, `X86_64`, `ARM64` (bundled `nativeJavaApplicationStub` binaries) or `SCRIPT` (`universalJavaApplicationStub.sh`). The launcher is always copied into the app as `Contents/MacOS/universalJavaApplicationStub`.

.minispec/core/principles.md

@@ -0,0 +1,13 @@
+# Engineering principles
+
+Consult **before** writing code.
+
+- Solve first, optimize later.
+- Readable code over clever code.
+- One responsibility per class or component.
+- Prefer composition over inheritance.
+- Avoid premature abstractions.
+- Preserve existing behavior: users' existing Maven/Gradle configurations and custom templates must keep working.
+- Don't refactor outside the task's scope.
+- If a choice adds a lot of complexity, propose a simpler alternative first.
+- Document decisions, not implementation.

.minispec/core/project.md

@@ -0,0 +1,22 @@
+# Project
+
+## What
+
+JavaPackager is a hybrid Maven/Gradle plugin, published as a single artifact (`io.github.fvarrui:javapackager`), that packages Java applications as native Windows, macOS or GNU/Linux apps and generates installers for them.
+
+## What it does
+
+- Builds a native app folder: runnable JAR, dependencies, launcher executable or startup script, icons and optional bundled JRE.
+- Generates a customized JRE with `jdeps` + `jlink`, or bundles an existing one.
+- Generates installers: DEB, RPM and AppImage (Linux); DMG and PKG (macOS); Inno Setup EXE, MSI and MSM (Windows).
+- Creates zipball/tarball bundles of the app folder.
+- Lets users override any icon or Velocity template from their own `assetsDir`.
+
+## For whom
+
+- Java developers who want to distribute desktop apps without chaining several plugins.
+- Users configure it through `pom.xml` (goal `package`) or a Gradle `PackageTask`; see `README.md` and `docs/`.
+
+## Goal
+
+One plugin to rule them all: package and distribute a Java app natively from a single build configuration.