android-ai-skills 0.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+# [1.2.0](https://github.com/noloman/Android-AI-skills/compare/v1.1.0...v1.2.0) (2026-02-12)
+
+
+### Bug Fixes
+
+* **ci:** fix trusted publishing — upgrade npm and add repository field ([cc93884](https://github.com/noloman/Android-AI-skills/commit/cc938841c51b3c22633e66030d84ddeb3982a744))
+* **ci:** remove registry-url that interferes with OIDC token exchange ([eed08b9](https://github.com/noloman/Android-AI-skills/commit/eed08b9f7f0343d4b3081861df7aa1eb6ea1dd4b))
+* **ci:** switch to npm trusted publishing via OIDC ([f74d8ce](https://github.com/noloman/Android-AI-skills/commit/f74d8ce182ddb1e16439dc1a5e4dbf9aba4a4654))
+
+
+### Features
+
+* add kotlin-coroutines-best-practices skill ([6e002e9](https://github.com/noloman/Android-AI-skills/commit/6e002e917c4b88b77fc749a5abd87ab6300526a7))
+
+# [1.1.0](https://github.com/noloman/Android-AI-skills/compare/v1.0.0...v1.1.0) (2026-02-12)
+
+
+### Features
+
+* add universal AI coding assistant support (9 tools) ([44bd7b5](https://github.com/noloman/Android-AI-skills/commit/44bd7b51dc5ce081bf6d3f37673093aa5caae1d8))
+
+# 1.0.0 (2026-02-12)
+
+
+### Bug Fixes
+
+* **ci:** remove registry-url to avoid NPM_TOKEN conflict ([b749728](https://github.com/noloman/Android-AI-skills/commit/b74972832cd2367562d895dfd2df2b3e07b69bab))
+* **ci:** upgrade Node.js to 22 for semantic-release compatibility ([5805e8d](https://github.com/noloman/Android-AI-skills/commit/5805e8d1c7e449841aaf55b73145d3047772805c))
+
 # Changelog
 
 All notable changes to this project will be documented in this file.

package/README.md

@@ -1,18 +1,43 @@
-[![CI](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/release.yml?branch=main)](https://github.com/OWNER/REPO/actions)
+[![CI](https://img.shields.io/github/actions/workflow/status/noloman/android-ai-skills/release.yml?branch=main)](https://github.com/noloman/android-ai-skills/actions)
 [![npm](https://img.shields.io/npm/v/android-ai-skills.svg)](https://www.npmjs.com/package/android-ai-skills)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-# 🚀 Android AI Architecture Skills
+# Android AI Architecture Skills
 
 Opinionated, production-grade AI skills for Android, Kotlin Multiplatform (KMP),
 and Compose Multiplatform projects.
 
-This repository provides structured **AI governance layers** that enforce
-architecture, performance, and scalability best practices automatically.
+Works with **Codex, Claude Code, GitHub Copilot, Cursor, Windsurf, Cline,
+JetBrains AI, Amazon Q & Aider**.
 
 ---
 
-# 🎯 Why This Exists
+## Supported AI Tools
+
+### Global install (home directory)
+
+| Tool | Path | Format |
+|------|------|--------|
+| Codex | `~/.codex/skills/<name>/SKILL.md` | Directory copy |
+| Claude Code | `~/.claude/rules/<name>.md` | Flattened markdown |
+
+### Project-level (`init` command)
+
+| Tool | Path | Format |
+|------|------|--------|
+| Codex | `AGENTS.md` | Single markdown file |
+| Claude Code | `CLAUDE.md` | Single markdown file |
+| GitHub Copilot | `.github/copilot-instructions.md` | Single markdown file |
+| Cursor | `.cursor/rules/<name>.mdc` | MDC per skill |
+| Windsurf | `.windsurfrules` | Single markdown file |
+| Cline | `.clinerules/<name>.md` | Markdown per skill |
+| JetBrains AI | `.aiassistant/rules/<name>.md` | Markdown per skill |
+| Amazon Q | `.amazonq/rules/<name>.md` | Markdown per skill |
+| Aider | `CONVENTIONS.md` + `.aider.conf.yml` | Single markdown + YAML |
+
+---
+
+## Why This Exists
 
 Modern Android & KMP projects grow complex quickly.
 
@@ -27,7 +52,7 @@ These AI skills:
 
 ---
 
-# 🧠 Skill Ecosystem
+## Skill Ecosystem
 
 ```mermaid
 flowchart LR
@@ -45,19 +70,24 @@ flowchart LR
 
     E --> J[Shared UI Discipline]
     E --> K[Platform-owned Navigation]
+
+    L[kotlin-coroutines-best-practices]
+    C --- L
+    D --- L
+    E --- L
+    L --> M[Structured Concurrency & Flow]
 ```
 
 ---
 
-# 📦 Included Skills
+## Included Skills
 
-## 1️⃣ compose-best-practices
+### 1. compose-best-practices
 
 For Android-only Jetpack Compose apps.
 
-### Enforces
-
-- Material3-only (🚫 no M2 mixing)
+**Enforces:**
+- Material3-only (no M2 mixing)
 - Stateless composables + UDF
 - StateFlow + SharedFlow patterns
 - Lifecycle-aware collection
@@ -67,12 +97,11 @@ For Android-only Jetpack Compose apps.
 
 ---
 
-## 2️⃣ kmp-architecture-best-practices
+### 2. kmp-architecture-best-practices
 
 For shared business logic in Kotlin Multiplatform.
 
-### Enforces
-
+**Enforces:**
 - No Android leakage into commonMain
 - No java.time in shared code
 - Proper expect/actual boundaries
@@ -82,12 +111,11 @@ For shared business logic in Kotlin Multiplatform.
 
 ---
 
-## 3️⃣ compose-multiplatform-best-practices
+### 3. compose-multiplatform-best-practices
 
 For shared UI in commonMain using Compose Multiplatform.
 
-### Enforces
-
+**Enforces:**
 - No Android ViewModel in shared UI
 - Platform-owned navigation
 - Shared state holder model
@@ -96,7 +124,22 @@ For shared UI in commonMain using Compose Multiplatform.
 
 ---
 
-# 🔥 Enterprise Mode (Auto-Detection)
+### 4. kotlin-coroutines-best-practices
+
+Cross-cutting skill that always activates alongside the project-type-specific skill.
+
+**Enforces:**
+- No GlobalScope — scoped coroutines only
+- Structured concurrency with parent-child job hierarchies
+- Cooperative cancellation (isActive, ensureActive)
+- Never catch CancellationException
+- Dispatcher injection — no hardcoded Dispatchers.Main in shared code
+- StateFlow for UI state, SharedFlow for events
+- Test coroutines with TestDispatcher + runTest
+
+---
+
+## Enterprise Mode (Auto-Detection)
 
 Enterprise Mode activates automatically if the repository contains:
 
@@ -130,7 +173,117 @@ flowchart TD
 
 ---
 
-# ⚡ Performance Governance
+## Install via npx
+
+### Global install (default: Codex + Claude Code)
+
+```bash
+npx android-ai-skills@latest
+```
+
+### Install only one skill
+
+```bash
+npx android-ai-skills@latest --android-only
+npx android-ai-skills@latest --kmp-only
+npx android-ai-skills@latest --compose-mp-only
+```
+
+### Install only for one target
+
+```bash
+npx android-ai-skills@latest --target codex
+npx android-ai-skills@latest --target claude
+```
+
+### Dry run
+
+```bash
+npx android-ai-skills@latest --dry-run
+```
+
+### Uninstall
+
+```bash
+npx android-ai-skills@latest uninstall
+npx android-ai-skills@latest uninstall --target codex
+```
+
+---
+
+## Project-level init (all 9 tools)
+
+Generate project-level instruction files for all supported AI tools:
+
+```bash
+npx android-ai-skills@latest init
+```
+
+### Select specific tools
+
+```bash
+npx android-ai-skills@latest init --tools cursor,copilot
+npx android-ai-skills@latest init --tools claude,codex
+```
+
+### Exclude tools
+
+```bash
+npx android-ai-skills@latest init --exclude aider
+```
+
+### Smaller output (skip reference docs)
+
+```bash
+npx android-ai-skills@latest init --no-references
+```
+
+### Overwrite existing files
+
+```bash
+npx android-ai-skills@latest init --force
+```
+
+### Generated files
+
+Running `init` with defaults creates:
+
+```
+AGENTS.md                                    # Codex
+CLAUDE.md                                    # Claude Code
+.github/copilot-instructions.md              # GitHub Copilot
+.cursor/rules/compose-best-practices.mdc     # Cursor (per skill)
+.cursor/rules/kmp-architecture-best-practices.mdc
+.cursor/rules/compose-multiplatform-best-practices.mdc
+.cursor/rules/kotlin-coroutines-best-practices.mdc
+.windsurfrules                               # Windsurf
+.clinerules/compose-best-practices.md        # Cline (per skill)
+.clinerules/kmp-architecture-best-practices.md
+.clinerules/compose-multiplatform-best-practices.md
+.clinerules/kotlin-coroutines-best-practices.md
+.aiassistant/rules/compose-best-practices.md # JetBrains AI (per skill)
+.aiassistant/rules/kmp-architecture-best-practices.md
+.aiassistant/rules/compose-multiplatform-best-practices.md
+.aiassistant/rules/kotlin-coroutines-best-practices.md
+.amazonq/rules/compose-best-practices.md     # Amazon Q (per skill)
+.amazonq/rules/kmp-architecture-best-practices.md
+.amazonq/rules/compose-multiplatform-best-practices.md
+.amazonq/rules/kotlin-coroutines-best-practices.md
+CONVENTIONS.md                               # Aider
+.aider.conf.yml
+```
+
+---
+
+## Print resolved paths
+
+```bash
+npx android-ai-skills@latest print-paths
+```
+
+---
+
+## Performance Governance
 
 Performance is treated as a first-class citizen.
 
@@ -144,7 +297,7 @@ Performance is treated as a first-class citizen.
 
 ---
 
-# 🏗 Architecture Governance
+## Architecture Governance
 
 ```mermaid
 flowchart TB
@@ -168,7 +321,7 @@ Principles:
 
 ---
 
-# 🧪 Stability & Compose Compiler Alignment
+## Stability & Compose Compiler Alignment
 
 The skills encourage:
 
@@ -182,112 +335,18 @@ This ensures Compose can skip recomposition effectively.
 
 ---
 
-# 📂 Repository Structure
+## Repository Structure
 
 ```
 compose-best-practices/
 kmp-architecture-best-practices/
 compose-multiplatform-best-practices/
+kotlin-coroutines-best-practices/
 README.md
 ```
 
 ---
 
-# 📖 How To Use
-
-1. Place the skills inside:
-   - ~/.codex/skills/
-   - ~/.claude/skills/
-   - or project-level .codex/skills/
-
-2. Add AGENTS.md to your project root (optional but recommended).
-
-3. The correct skill activates automatically based on project structure.
-
----
-
-# 🎉 Result
-
-You now have:
-
-- Predictable AI code reviews
-- Performance-aware AI refactors
-- Architecture enforcement across Android + KMP
-- Enterprise-ready governance without overengineering
+## License
 
----
-
-# 🛡 License
-
-MIT – Use freely in personal, startup, or enterprise projects.
----
-
-# 🧰 Install via npx
-
-You can install the skills globally into the standard locations for **Codex** and **Claude**:
-
-- `~/.codex/skills/`
-- `~/.claude/skills/`
-
-## Install (default: both)
-
-```bash
-npx android-ai-skills@latest
-```
-
-## Install only one skill
-
-```bash
-npx android-ai-skills@latest --android-only
-npx android-ai-skills@latest --kmp-only
-npx android-ai-skills@latest --compose-mp-only
-```
-
-## Install only for one target
-
-```bash
-npx android-ai-skills@latest --target codex
-npx android-ai-skills@latest --target claude
-```
-
-## Dry run
-
-```bash
-npx android-ai-skills@latest --dry-run
-```
-
-## Uninstall
-
-```bash
-npx android-ai-skills@latest uninstall
-npx android-ai-skills@latest uninstall --target codex
-```
-
----
-
-# 🧾 Auto-detect Enterprise Mode (Tooling-aware)
-
-Enterprise Mode activates automatically **only if tooling is detected** in the project root:
-
-- `detekt.yml` / `detekt.yaml`
-- `lint.xml`
-- ktlint config
-- spotless config
-
-If tooling is not detected, the skills remain tool-agnostic and **do not** enforce lint/detekt specifics.
-
-### Generate an AGENTS.md in your repo
-
-```bash
-npx android-ai-skills@latest init
-# or write it somewhere else:
-npx android-ai-skills@latest init --path .
-```
-
-### Print where skills will be installed
-
-```bash
-npx android-ai-skills@latest print-paths
-# or include paths during install:
-npx android-ai-skills@latest --print-paths
-```
+MIT -- Use freely in personal, startup, or enterprise projects.

package/bin/android-ai-skills.js

@@ -11,46 +11,169 @@ const ALL_SKILLS = [
   "compose-best-practices",
   "kmp-architecture-best-practices",
   "compose-multiplatform-best-practices",
+  "kotlin-coroutines-best-practices",
 ];
 
+// ── Tool registry for project-level init ──────────────────────────────
+
+const INIT_TOOLS = {
+  codex:     { file: "AGENTS.md",                                  type: "single" },
+  claude:    { file: "CLAUDE.md",                                  type: "single" },
+  copilot:   { dir: ".github", file: "copilot-instructions.md",   type: "single" },
+  cursor:    { dir: ".cursor/rules",                               type: "per-skill", ext: ".mdc" },
+  windsurf:  { file: ".windsurfrules",                             type: "single" },
+  cline:     { dir: ".clinerules",                                 type: "per-skill", ext: ".md" },
+  jetbrains: { dir: ".aiassistant/rules",                          type: "per-skill", ext: ".md" },
+  amazonq:   { dir: ".amazonq/rules",                              type: "per-skill", ext: ".md" },
+  aider:     { file: "CONVENTIONS.md",                             type: "single", extra: ".aider.conf.yml" },
+};
+
+const INIT_TOOL_NAMES = Object.keys(INIT_TOOLS);
+
+// ── Content pipeline ──────────────────────────────────────────────────
+
+function parseYamlFrontmatter(text) {
+  const match = text.match(/^[\s]*---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: text.trim() };
+  const raw = match[1];
+  const meta = {};
+  for (const line of raw.split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx > 0) meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+  return { meta, body: match[2].trim() };
+}
+
+function readSkillContent(skillName) {
+  const skillDir = path.join(projectRoot, skillName);
+  const skillMd = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8");
+  const { meta, body } = parseYamlFrontmatter(skillMd);
+
+  const references = [];
+  const refsDir = path.join(skillDir, "references");
+  if (fs.existsSync(refsDir)) {
+    for (const f of fs.readdirSync(refsDir).sort()) {
+      if (!f.endsWith(".md")) continue;
+      references.push({
+        name: f.replace(/\.md$/, ""),
+        content: fs.readFileSync(path.join(refsDir, f), "utf8").trim(),
+      });
+    }
+  }
+
+  return { name: skillName, meta, body, references };
+}
+
+function activationMatrix() {
+  return `## Skill activation matrix
+
+If the project contains \`commonMain\` (KMP):
+
+- If shared UI composables exist in \`commonMain\`:
+  - Use **compose-multiplatform-best-practices**
+- Else (shared business logic only):
+  - Use **kmp-architecture-best-practices**
+
+If the project is Android-only:
+
+- Use **compose-best-practices**
+
+**Always activate:** **kotlin-coroutines-best-practices** (cross-cutting concern — applies to all project types).
+
+## Enterprise Mode auto-detection (optional)
+
+Enterprise Mode turns on automatically when tooling is detected in the repo root:
+- detekt.yml / detekt.yaml
+- lint.xml
+- ktlint/spotless config
+
+If not detected, tool-specific enforcement is disabled (tool-agnostic guidance only).`;
+}
+
+function generateMarkdown(skill, { includeRefs = true } = {}) {
+  let out = skill.body;
+  if (includeRefs && skill.references.length) {
+    for (const ref of skill.references) {
+      out += `\n\n---\n\n${ref.content}`;
+    }
+  }
+  return out + "\n";
+}
+
+function generateMdc(skill, { includeRefs = true } = {}) {
+  const desc = skill.meta.description || skill.name;
+  const body = generateMarkdown(skill, { includeRefs });
+  return `---
+description: ${desc}
+globs: "**/*.kt,**/*.kts"
+alwaysApply: false
+---
+
+${body}`;
+}
+
+function flattenSkillForClaude(skill) {
+  return generateMarkdown(skill, { includeRefs: true });
+}
+
+function generateSingleFile(skills, { includeRefs = true } = {}) {
+  let out = `# Android AI Skills\n\n${activationMatrix()}\n`;
+  for (const skill of skills) {
+    out += `\n---\n\n${generateMarkdown(skill, { includeRefs })}`;
+  }
+  return out;
+}
+
+// ── CLI helpers ───────────────────────────────────────────────────────
+
 function help() {
   console.log(`
-android-ai-skills — install Claude + Codex skills
+android-ai-skills — install AI governance skills for Android, KMP & Compose
+
+Supported tools: Codex, Claude Code, GitHub Copilot, Cursor, Windsurf,
+                 Cline, JetBrains AI, Amazon Q, Aider.
 
 Usage:
-  npx android-ai-skills@latest [options]
-  npx android-ai-skills@latest uninstall [options]
-  npx android-ai-skills@latest init [options]
+  npx android-ai-skills@latest [options]            Global install (Codex + Claude)
+  npx android-ai-skills@latest uninstall [options]   Remove global install
+  npx android-ai-skills@latest init [options]        Project-level files (all 9 tools)
   npx android-ai-skills@latest print-paths [options]
 
-Install options:
+Skill selection:
   --android-only          Install only compose-best-practices
   --kmp-only              Install only kmp-architecture-best-practices
   --compose-mp-only       Install only compose-multiplatform-best-practices
 
-Target options:
-  --target <both|codex|claude>  Default: both
+Global install targets:
+  --target <all|codex|claude>  Default: all
   --codex-only            Same as --target codex
   --claude-only           Same as --target claude
 
+Init options:
+  --path <dir>            Where to write files (default: current directory)
+  --tools <tool,...>      Only generate for these tools (comma-separated)
+  --exclude <tool,...>    Skip these tools (comma-separated)
+  --no-references         Omit reference docs for smaller output
+
+  Available tool names: ${INIT_TOOL_NAMES.join(", ")}
+
 Advanced:
   --dest <path>           Override destination base folder (advanced)
   --dry-run               Print actions without writing files
-  --force                 Overwrite existing skill folders
-  --print-paths           Print resolved install paths and exit (or include in output)
+  --force                 Overwrite existing files
+  --print-paths           Print resolved install paths and exit
   --help                  Show this help
 
-init options:
-  --path <dir>            Where to write AGENTS.md (default: current directory)
-  --force                 Overwrite existing AGENTS.md
-
 Examples:
   npx android-ai-skills@latest
   npx android-ai-skills@latest --android-only
   npx android-ai-skills@latest --target codex
   npx android-ai-skills@latest --dry-run
-  npx android-ai-skills@latest uninstall --target both
+  npx android-ai-skills@latest uninstall --target all
   npx android-ai-skills@latest init
+  npx android-ai-skills@latest init --tools cursor,copilot
+  npx android-ai-skills@latest init --exclude aider --force
+  npx android-ai-skills@latest init --no-references
   npx android-ai-skills@latest print-paths
 `);
 }
@@ -62,7 +185,12 @@ function parse(argv) {
     if (!s.startsWith("--")) { a._.push(s); continue; }
     const k = s.slice(2);
     const n = argv[i + 1];
-    const booleanKeys = new Set(["android-only","kmp-only","compose-mp-only","codex-only","claude-only","dry-run","force","help","print-paths"]);
+    const booleanKeys = new Set([
+      "android-only", "kmp-only", "compose-mp-only",
+      "codex-only", "claude-only",
+      "dry-run", "force", "help", "print-paths",
+      "no-references",
+    ]);
     if (!booleanKeys.has(k) && n && !n.startsWith("--")) { a[k] = n; i++; }
     else a[k] = true;
   }
@@ -91,6 +219,12 @@ function removeDir(dest, { dryRun }) {
   fs.rmSync(dest, { recursive: true, force: true });
 }
 
+function removeFile(dest, { dryRun }) {
+  if (!fs.existsSync(dest)) return;
+  if (dryRun) return;
+  fs.unlinkSync(dest);
+}
+
 function resolveSkills(args) {
   const selected = new Set();
   if (args["android-only"] || args["kmp-only"] || args["compose-mp-only"]) {
@@ -102,63 +236,146 @@ function resolveSkills(args) {
   return [...ALL_SKILLS];
 }
 
-function resolveTargets(args) {
-  const home = os.homedir();
-  let target = (args.target || "both").toLowerCase();
+// ── Global install targets ────────────────────────────────────────────
+
+function resolveGlobalTargets(args) {
+  let target = (args.target || "all").toLowerCase();
   if (args["codex-only"]) target = "codex";
   if (args["claude-only"]) target = "claude";
+  if (target === "both") target = "all";
 
-  if (args.dest) return [path.resolve(process.cwd(), args.dest)];
+  if (args.dest) {
+    return [{ type: "codex", base: path.resolve(process.cwd(), args.dest) }];
+  }
 
-  if (target === "both") return [path.join(home, ".codex", "skills"), path.join(home, ".claude", "skills")];
-  if (target === "codex") return [path.join(home, ".codex", "skills")];
-  if (target === "claude") return [path.join(home, ".claude", "skills")];
-  throw new Error(`Unknown --target ${args.target}. Use both|codex|claude.`);
+  const home = os.homedir();
+  const targets = [];
+  if (target === "all" || target === "codex") {
+    targets.push({ type: "codex", base: path.join(home, ".codex", "skills") });
+  }
+  if (target === "all" || target === "claude") {
+    targets.push({ type: "claude", base: path.join(home, ".claude", "rules") });
+  }
+  if (!targets.length) throw new Error(`Unknown --target ${args.target}. Use all|codex|claude.`);
+  return targets;
+}
+
+function checkClaudeMigration(skills) {
+  const oldBase = path.join(os.homedir(), ".claude", "skills");
+  if (!fs.existsSync(oldBase)) return;
+  const found = skills.filter(s => fs.existsSync(path.join(oldBase, s)));
+  if (found.length) {
+    console.log(`⚠️  Found old Claude skills in ~/.claude/skills/`);
+    console.log(`   Claude Code reads from ~/.claude/rules/ instead.`);
+    console.log(`   You can remove the old directory: rm -rf ~/.claude/skills/`);
+    console.log("");
+  }
 }
 
 function printResolvedPaths(args) {
   const skills = resolveSkills(args);
-  const targets = resolveTargets(args);
+  const targets = resolveGlobalTargets(args);
   console.log("Resolved install paths:");
   for (const t of targets) {
-    console.log(`- ${t}`);
-    for (const s of skills) console.log(`  - ${path.join(t, s)}`);
+    console.log(`- ${t.base} (${t.type})`);
+    for (const s of skills) {
+      if (t.type === "claude") {
+        console.log(`  - ${path.join(t.base, s + ".md")}`);
+      } else {
+        console.log(`  - ${path.join(t.base, s)}/`);
+      }
+    }
   }
 }
 
-function writeAgentsMd(outDir, force) {
-  const p = path.join(outDir, "AGENTS.md");
-  if (fs.existsSync(p) && !force) {
-    throw new Error(`AGENTS.md already exists at ${p}. Use --force to overwrite.`);
-  }
-  const content = `# AGENTS.md
+// ── Init command ──────────────────────────────────────────────────────
 
-## Skill activation matrix
-
-If the project contains \`commonMain\` (KMP):
+function resolveInitTargets(args) {
+  let tools = [...INIT_TOOL_NAMES];
+  if (args.tools) {
+    tools = args.tools.split(",").map(t => t.trim().toLowerCase());
+    for (const t of tools) {
+      if (!INIT_TOOLS[t]) throw new Error(`Unknown tool: ${t}. Available: ${INIT_TOOL_NAMES.join(", ")}`);
+    }
+  }
+  if (args.exclude) {
+    const excl = new Set(args.exclude.split(",").map(t => t.trim().toLowerCase()));
+    tools = tools.filter(t => !excl.has(t));
+  }
+  return tools;
+}
 
-- If shared UI composables exist in \`commonMain\`:
-  - Use **compose-multiplatform-best-practices**
-- Else (shared business logic only):
-  - Use **kmp-architecture-best-practices**
+function writeProjectFiles(outDir, skills, tools, { dryRun, force, includeRefs }) {
+  const skillContents = skills.map(s => readSkillContent(s));
+  const written = [];
 
-If the project is Android-only:
+  for (const toolName of tools) {
+    const cfg = INIT_TOOLS[toolName];
 
-- Use **compose-best-practices**
+    if (cfg.type === "single") {
+      const filePath = cfg.dir
+        ? path.join(outDir, cfg.dir, cfg.file)
+        : path.join(outDir, cfg.file);
 
-## Enterprise Mode auto-detection (optional)
+      if (fs.existsSync(filePath) && !force) {
+        console.log(`⏭️  Skipped ${path.relative(outDir, filePath)} (exists, use --force)`);
+        continue;
+      }
 
-Enterprise Mode turns on automatically when tooling is detected in the repo root:
-- detekt.yml / detekt.yaml
-- lint.xml
-- ktlint/spotless config
+      const content = generateSingleFile(skillContents, { includeRefs });
+      if (!dryRun) {
+        ensureDir(path.dirname(filePath), false);
+        fs.writeFileSync(filePath, content, "utf8");
+      }
+      console.log(`${dryRun ? "🧪" : "✅"} ${toolName} → ${path.relative(outDir, filePath)}`);
+      written.push(filePath);
+
+      // Aider extra: .aider.conf.yml
+      if (cfg.extra) {
+        const extraPath = path.join(outDir, cfg.extra);
+        if (!fs.existsSync(extraPath)) {
+          const yaml = `read:\n  - ${cfg.file}\n`;
+          if (!dryRun) fs.writeFileSync(extraPath, yaml, "utf8");
+          console.log(`${dryRun ? "🧪" : "✅"} ${toolName} → ${path.relative(outDir, extraPath)}`);
+          written.push(extraPath);
+        } else {
+          console.log(`⏭️  Skipped ${path.relative(outDir, extraPath)} (exists)`);
+        }
+      }
+    } else {
+      // per-skill
+      const dir = path.join(outDir, cfg.dir);
+      for (const skill of skillContents) {
+        const fileName = skill.name + cfg.ext;
+        const filePath = path.join(dir, fileName);
+
+        if (fs.existsSync(filePath) && !force) {
+          console.log(`⏭️  Skipped ${path.relative(outDir, filePath)} (exists, use --force)`);
+          continue;
+        }
+
+        let content;
+        if (toolName === "cursor") {
+          content = generateMdc(skill, { includeRefs });
+        } else {
+          content = generateMarkdown(skill, { includeRefs });
+        }
+
+        if (!dryRun) {
+          ensureDir(dir, false);
+          fs.writeFileSync(filePath, content, "utf8");
+        }
+        console.log(`${dryRun ? "🧪" : "✅"} ${toolName} → ${path.relative(outDir, filePath)}`);
+        written.push(filePath);
+      }
+    }
+  }
 
-If not detected, tool-specific enforcement is disabled (tool-agnostic guidance only).
-`;
-  fs.writeFileSync(p, content, "utf8");
-  return p;
+  return written;
 }
 
+// ── Main ──────────────────────────────────────────────────────────────
+
 function main() {
   const args = parse(process.argv.slice(2));
   const sub = (args._[0] || "").toLowerCase();
@@ -172,9 +389,20 @@ function main() {
 
   if (sub === "init") {
     const outDir = path.resolve(process.cwd(), args.path || ".");
-    ensureDir(outDir, false);
-    const p = writeAgentsMd(outDir, !!args.force);
-    console.log(`✅ Wrote ${p}`);
+    const dryRun = !!args["dry-run"];
+    const force = !!args.force;
+    const includeRefs = !args["no-references"];
+    const skills = resolveSkills(args);
+    const tools = resolveInitTargets(args);
+
+    console.log(`🚀 Initializing project-level AI skill files`);
+    if (dryRun) console.log("🧪 Dry-run (no files will be written)");
+    console.log(`   Tools: ${tools.join(", ")}`);
+    console.log(`   Skills: ${skills.join(", ")}`);
+    console.log("");
+
+    writeProjectFiles(outDir, skills, tools, { dryRun, force, includeRefs });
+    console.log("\n🎉 Done.");
     return;
   }
 
@@ -184,27 +412,50 @@ function main() {
 
   if (args["print-paths"]) {
     printResolvedPaths(args);
-    if (!uninstall) console.log("");
+    console.log("");
   }
 
   const skills = resolveSkills(args);
-  const targets = resolveTargets(args);
+  const targets = resolveGlobalTargets(args);
+
+  if (!uninstall) checkClaudeMigration(skills);
 
   console.log(`🚀 ${uninstall ? "Uninstalling" : "Installing"} android-ai-skills`);
   if (dryRun) console.log("🧪 Dry-run (no files will be written)");
   console.log("");
 
-  for (const baseDest of targets) {
-    ensureDir(baseDest, dryRun);
-    for (const skill of skills) {
-      const src = path.join(projectRoot, skill);
-      const dest = path.join(baseDest, skill);
-      if (uninstall) {
-        console.log(`🗑️  ${skill} → ${dest}`);
-        removeDir(dest, { dryRun });
-      } else {
-        console.log(`✅ ${skill} → ${dest}`);
-        copyDir(src, dest, { dryRun, force });
+  for (const target of targets) {
+    ensureDir(target.base, dryRun);
+
+    if (target.type === "codex") {
+      for (const skill of skills) {
+        const src = path.join(projectRoot, skill);
+        const dest = path.join(target.base, skill);
+        if (uninstall) {
+          console.log(`🗑️  ${skill} → ${dest}`);
+          removeDir(dest, { dryRun });
+        } else {
+          console.log(`✅ ${skill} → ${dest}`);
+          copyDir(src, dest, { dryRun, force });
+        }
+      }
+    } else if (target.type === "claude") {
+      for (const skill of skills) {
+        const dest = path.join(target.base, skill + ".md");
+        if (uninstall) {
+          console.log(`🗑️  ${skill} → ${dest}`);
+          removeFile(dest, { dryRun });
+        } else {
+          if (fs.existsSync(dest) && !force) {
+            throw new Error(`Destination exists: ${dest}. Use --force.`);
+          }
+          const content = flattenSkillForClaude(readSkillContent(skill));
+          if (!dryRun) {
+            ensureDir(target.base, false);
+            fs.writeFileSync(dest, content, "utf8");
+          }
+          console.log(`✅ ${skill} → ${dest}`);
+        }
       }
     }
   }

package/kotlin-coroutines-best-practices/SKILL.md

@@ -0,0 +1,39 @@
+
+---
+name: kotlin-coroutines-best-practices
+description: Kotlin Coroutines & Flow best practices for Android and KMP projects.
+---
+
+# Kotlin Coroutines & Flow Best Practices
+
+Cross-cutting skill — always activates alongside the project-type-specific skill.
+
+## Hard Rules
+- No GlobalScope — use scoped coroutines (viewModelScope, lifecycleScope, custom CoroutineScope).
+- No blocking calls on Dispatchers.Main.
+- Structured concurrency — maintain parent-child job hierarchies.
+- Cooperative cancellation — check isActive in long-running loops.
+- Never catch CancellationException.
+- Never swallow exceptions silently.
+- Inject dispatchers — no hardcoded Dispatchers.Main in shared code.
+- Prefer Flow over callbacks.
+- Test coroutines with TestDispatcher + runTest.
+
+## Core Patterns
+- StateFlow for UI state, SharedFlow for events.
+- stateIn with WhileSubscribed(5_000) for cold-to-hot conversion.
+- withContext for dispatcher switching.
+- supervisorScope for isolated failure handling.
+- flowOn to change upstream dispatcher.
+- catch operator for upstream flow errors.
+- Prefer callbackFlow over raw Channel for callback interop.
+
+## References
+- references/structured_concurrency.md
+- references/error_handling.md
+- references/testing.md
+- references/dispatchers.md
+- references/flow_types.md
+- references/flow_operators.md
+- references/channels.md
+- references/anti_patterns.md

package/kotlin-coroutines-best-practices/references/anti_patterns.md

@@ -0,0 +1,30 @@
+# Coroutine Anti-Patterns
+
+## Scope & Lifecycle
+- GlobalScope: leaks coroutines — no structured cancellation. Use scoped coroutines.
+- launch without a scope: fire-and-forget with no lifecycle management.
+- Ignoring the Job returned by launch: cannot cancel or track completion.
+
+## Cancellation
+- Catching CancellationException: breaks cancellation propagation. If catching Exception, rethrow CancellationException.
+- Infinite while(true) without isActive check: coroutine never cooperatively cancels.
+- runBlocking in production Android code: blocks the calling thread, risk of ANR on Main.
+
+## Threading
+- Blocking calls on Dispatchers.Main: Thread.sleep, synchronous I/O, heavy computation — causes ANR.
+- Hardcoded Dispatchers.Main in commonMain (KMP): Main is Android-specific, crashes on other platforms.
+
+## Flows
+- Collecting flows in composable body (outside LaunchedEffect): triggers new collection on every recomposition.
+- SharingStarted.Eagerly without justification: wastes resources when no collectors are active.
+- withContext inside flow {} builder: use flowOn instead.
+
+## Error Handling
+- Swallowing exceptions silently: catch {} with no logging or propagation hides bugs.
+- CoroutineExceptionHandler on child coroutine: ignored — install on root scope only.
+- runCatching on suspend functions without rethrowing CancellationException.
+
+## Over-engineering
+- Mutex when limitedParallelism(1) suffices.
+- Raw Channel when SharedFlow or callbackFlow fits.
+- Custom CoroutineScope when viewModelScope/lifecycleScope already matches lifecycle.

package/kotlin-coroutines-best-practices/references/channels.md

@@ -0,0 +1,23 @@
+# Channels
+
+- Hot communication primitive — elements are consumed once (not broadcast).
+- Prefer Flow for most use cases — channels are lower-level.
+
+## Channel Types
+- Channel.UNLIMITED: unlimited buffer, sender never suspends.
+- Channel.BUFFERED: default buffer size (64), sender suspends when full.
+- Channel.RENDEZVOUS: zero buffer, sender suspends until receiver is ready.
+- Channel.CONFLATED: buffer of 1, new values overwrite unread value.
+
+## Patterns
+- produce {} builder: returns ReceiveChannel, auto-closes on completion.
+- Fan-out: multiple coroutines receiving from one channel (load balancing).
+- Fan-in: multiple coroutines sending to one channel (aggregation).
+- close() when done — signals no more elements.
+- consumeEach {} for safe consumption with automatic cancellation.
+
+## When to Use
+- Prefer callbackFlow over raw Channel for bridging callback APIs.
+- Use Channel for worker pool / fan-out patterns.
+- Use Channel for single-consumer event queues when SharedFlow doesn't fit.
+- Avoid Channel for state — use StateFlow instead.

package/kotlin-coroutines-best-practices/references/dispatchers.md

@@ -0,0 +1,24 @@
+# Dispatchers
+
+## Built-in Dispatchers
+- Dispatchers.Main: UI thread only — use for UI updates, state emissions.
+- Dispatchers.IO: blocking I/O (network, disk, database) — backed by ~64 threads.
+- Dispatchers.Default: CPU-intensive work (sorting, parsing, serialization) — thread count = CPU cores.
+- Dispatchers.Unconfined: avoid — runs in caller's thread until first suspension, then resumes in whatever thread.
+
+## Switching
+- withContext(Dispatchers.IO) { ... } — switch dispatcher for a block, return result.
+- Never nest withContext with the same dispatcher — no-op overhead.
+- flowOn(Dispatchers.IO) — changes upstream flow dispatcher.
+
+## Injection
+- Accept CoroutineDispatcher as constructor parameter.
+- Provide via DI (Hilt @Qualifier annotations: @IoDispatcher, @DefaultDispatcher, @MainDispatcher).
+- Never hardcode Dispatchers.Main in commonMain (KMP) — Main is Android-specific.
+- In KMP shared code, inject all dispatchers.
+
+## Advanced
+- limitedParallelism(n): create a view limiting concurrent coroutines.
+- Use limitedParallelism(1) for single-threaded access (replaces Mutex in some cases).
+- IO.limitedParallelism(4) for rate-limiting external API calls.
+- Default.limitedParallelism(2) for CPU-bound tasks that shouldn't starve others.

package/kotlin-coroutines-best-practices/references/error_handling.md

@@ -0,0 +1,25 @@
+# Error Handling
+
+## Suspend Functions
+- Use try-catch inside suspend functions for recoverable errors.
+- Return Result<T> or sealed class for expected failures (network, parsing).
+- runCatching {} wraps in Result<T> — but catches CancellationException; re-throw it.
+
+## Coroutine Scopes
+- CoroutineExceptionHandler: install on root scope only (launch, not async).
+- Child exceptions propagate to parent — handler on child is ignored.
+- supervisorScope: isolates child failures — one child crash doesn't cancel siblings.
+- Use supervisorScope when launching independent parallel work.
+
+## Flows
+- catch {} operator: catches upstream errors only.
+- Place catch before terminal operators (collect, stateIn).
+- Use onCompletion {} to detect both success and failure.
+- retryWhen { cause, attempt -> } for transient failures with backoff.
+- Exponential backoff: delay(minOf(2.0.pow(attempt).toLong() * 1000, 30_000)).
+
+## Anti-patterns
+- Never swallow exceptions silently — at minimum log them.
+- Never catch CancellationException — breaks structured concurrency.
+- Don't use CoroutineExceptionHandler as a substitute for proper error handling.
+- Avoid runCatching on suspend functions without re-throwing CancellationException.

package/kotlin-coroutines-best-practices/references/flow_operators.md

@@ -0,0 +1,41 @@
+# Flow Operators
+
+## Transform
+- map { } — transform each element.
+- filter { } — keep elements matching predicate.
+- mapNotNull { } — map + filter nulls in one step.
+- transform { } — emit zero or more values per upstream element.
+
+## Flattening
+- flatMapLatest { } — cancel previous inner flow when new value arrives (use for search-as-you-type).
+- flatMapConcat { } — process inner flows sequentially.
+- flatMapMerge { } — process inner flows concurrently (configurable concurrency).
+
+## Combining
+- combine(flow1, flow2) { a, b -> } — emit on any change, using latest from each.
+- zip(flow1, flow2) { a, b -> } — 1:1 pairing, completes when either flow completes.
+- merge(flow1, flow2) — interleave emissions from multiple flows.
+
+## Rate Limiting
+- debounce(timeoutMillis) — emit after silence period (search input).
+- sample(periodMillis) — emit latest value at fixed intervals.
+- distinctUntilChanged() — skip consecutive duplicates.
+
+## Buffering
+- buffer() — run collector and emitter concurrently (back-pressure relief).
+- conflate() — skip intermediate values when collector is slow.
+- buffer(Channel.CONFLATED) — equivalent to conflate().
+
+## Error Handling
+- catch { } — catch upstream exceptions, can emit fallback values.
+- retryWhen { cause, attempt -> } — retry upstream on transient failures.
+- onCompletion { cause -> } — runs after flow completes (success or failure).
+
+## Side Effects
+- onEach { } — perform action on each element without transforming.
+- onStart { } — runs before first element is emitted.
+- onCompletion { } — runs after terminal event.
+
+## Context
+- flowOn(dispatcher) — change upstream dispatcher. Does NOT affect downstream.
+- Never use withContext inside flow {} builder — use flowOn instead.

package/kotlin-coroutines-best-practices/references/flow_types.md

@@ -0,0 +1,33 @@
+# Flow Types
+
+## Cold Flow
+- flow {} builder: executes on each collector independently.
+- Emissions are sequential within a single flow.
+- Completes when the builder block finishes.
+- Use for one-shot or on-demand data streams.
+
+## StateFlow
+- Hot flow — always has a current value (.value).
+- Conflated: collectors always get the latest value, may skip intermediate.
+- Requires initial value at creation.
+- MutableStateFlow(initialValue) for read-write, expose as StateFlow for read-only.
+- Equality-based deduplication: same value emitted twice is ignored.
+- Use for UI state in ViewModels.
+
+## SharedFlow
+- Hot flow — event stream, no initial value required.
+- Configurable replay (number of past values for new collectors) and extraBufferCapacity.
+- MutableSharedFlow for read-write, expose as SharedFlow.
+- replay = 0: new collectors miss past events (use for one-off events).
+- Use for navigation events, snackbar triggers, analytics.
+
+## Conversions
+- stateIn(scope, started, initialValue): cold flow -> StateFlow.
+- shareIn(scope, started, replay): cold flow -> SharedFlow.
+- SharingStarted.WhileSubscribed(5_000): stops upstream 5s after last collector leaves — balance between freshness and resource savings.
+- SharingStarted.Eagerly: starts immediately, never stops — use sparingly.
+- SharingStarted.Lazily: starts on first collector, never stops.
+
+## Special Builders
+- callbackFlow {}: bridge callback APIs to Flow — use awaitClose {} for cleanup.
+- channelFlow {}: concurrent emissions from multiple coroutines.

package/kotlin-coroutines-best-practices/references/structured_concurrency.md

@@ -0,0 +1,19 @@
+# Structured Concurrency
+
+- Every coroutine must have a parent scope — no orphan launches.
+- CoroutineScope ties coroutine lifetime to a component (ViewModel, Activity, Service).
+- Parent cancellation cascades to all children automatically.
+- Child failure cancels siblings and parent (default Job behavior).
+- SupervisorJob: child failure does NOT cancel siblings or parent.
+- coroutineScope {} — creates child scope, waits for all children, propagates failure.
+- supervisorScope {} — creates child scope, waits for all children, isolates failures.
+- viewModelScope: auto-cancelled on ViewModel.onCleared().
+- lifecycleScope: auto-cancelled on Lifecycle.DESTROYED.
+- Custom scopes: create with CoroutineScope(SupervisorJob() + dispatcher), cancel explicitly.
+
+## Cooperative Cancellation
+- Check isActive in CPU-bound loops.
+- Use ensureActive() for an automatic check + throw.
+- yield() checks cancellation and yields to other coroutines.
+- Never catch CancellationException — breaks cancellation propagation.
+- If you must catch Exception, rethrow CancellationException.

package/kotlin-coroutines-best-practices/references/testing.md

@@ -0,0 +1,28 @@
+# Testing Coroutines
+
+## Core Setup
+- Use runTest {} (replaces deprecated runBlockingTest).
+- runTest auto-advances virtual time for delay-based code.
+- Inject TestDispatcher into classes under test.
+
+## Test Dispatchers
+- StandardTestDispatcher: does not auto-dispatch — control time with advanceTimeBy(), advanceUntilIdle().
+- UnconfinedTestDispatcher: eager dispatch — coroutines run immediately.
+- Use StandardTestDispatcher for precise timing tests.
+- Use UnconfinedTestDispatcher when timing doesn't matter.
+
+## Testing StateFlow
+- Assert against .value directly after triggering actions.
+- Use advanceUntilIdle() to flush pending coroutines.
+- Set Dispatchers.Main via Dispatchers.setMain(testDispatcher) in @Before.
+- Reset via Dispatchers.resetMain() in @After.
+
+## Testing SharedFlow / Events
+- Use Turbine library: flow.test { awaitItem(), expectNoEvents(), cancelAndIgnoreRemainingEvents() }.
+- Turbine provides timeout-based assertions — no manual job juggling.
+- awaitItem() suspends until next emission.
+- expectNoEvents() asserts no emissions within timeout.
+
+## Testing Cancellation
+- Launch in a separate job, cancel it, verify cleanup ran.
+- Use advanceTimeBy() to simulate timeout-based cancellation.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "android-ai-skills",
-  "version": "0.1.0",
-  "description": "AI governance skills for Android, Kotlin Multiplatform (KMP), and Compose Multiplatform (Claude + Codex).",
+  "version": "1.2.0",
+  "description": "AI governance skills for Android, KMP & Compose — works with Codex, Claude, Copilot, Cursor, Windsurf, Cline, JetBrains AI, Amazon Q & Aider.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noloman/Android-AI-skills.git"
+  },
   "type": "module",
   "bin": {
     "android-ai-skills": "bin/android-ai-skills.js"
@@ -12,6 +16,7 @@
     "compose-best-practices/",
     "kmp-architecture-best-practices/",
     "compose-multiplatform-best-practices/",
+    "kotlin-coroutines-best-practices/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",