@antoneeo/agentic-sdlc-skill 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -1,19 +1,40 @@
 # Changelog - Agentic SDLC Skill
 
-Tutte le modifiche significative a questa skill saranno documentate in questo file.
-
-## [1.2.2] - 2026-05-10
-### Changed
-- README convertito in inglese per la pubblicazione npm.
-- Versione allineata a `1.2.2` in `package.json` e `gemini-extension.json`.
-
-## [1.2.1] - 2026-05-10
-### Fixed
-- `postinstall` ora registra la skill anche per Codex copiandola in `$CODEX_HOME/skills/agentic-sdlc/` oppure `~/.codex/skills/agentic-sdlc/`.
-- `preuninstall` rimuove anche la copia Codex della skill.
-- `agentic-sdlc-init` ora crea `AGENTS.md` per Codex invece di `.codex/hooks.json`, che Codex non carica come istruzioni di progetto.
-
-## [1.2.0] - 2026-05-10
+Tutte le modifiche significative a questa skill saranno documentate in questo file.
+
+## [1.3.1] - 2026-05-14
+### Fixed
+- Correzione documentazione (README + CHANGELOG) della sintassi per invocare il bin `agentic-sdlc-install-skill`. La forma `npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` documentata in 1.3.0 **non funziona** perché npx non riesce a disambiguare il bin quando il pacchetto ne espone più di uno (errore: `could not determine executable to run`). Sintassi corretta: lanciare `agentic-sdlc-install-skill` direttamente dopo `npm install -g`, oppure usare `npx -p @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` con `-p` esplicito.
+- Nessuna modifica al codice della skill: il bin di 1.3.0 funziona correttamente, era solo la doc a indicare la sintassi sbagliata.
+
+## [1.3.0] - 2026-05-14
+### Added
+- Nuovo comando esplicito `agentic-sdlc-install-skill` (registrato come `bin`): installa la skill in `~/.claude/skills/agentic-sdlc/` e `~/.codex/skills/agentic-sdlc/` **senza dipendere dal `postinstall` hook**. Risolve i casi in cui `npm` salta gli script (configurazioni `ignore-scripts=true`, policy IT aziendali, alcuni installer Node) e l'auto-install fallisce silenziosamente.
+- Sezione "Troubleshooting" nel README con istruzioni per il caso in cui la skill non venga rilevata da Claude Code dopo `npm install -g`.
+
+### Usage
+```bash
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+agentic-sdlc-install-skill
+```
+
+## [1.2.4] - 2026-05-14
+### Fixed
+- `postinstall` ora rileva Claude Code anche quando il CLI `claude` non è nel PATH (es. Claude Desktop con Claude Code integrato): la presenza di `~/.claude/` o della variabile `CLAUDE_CONFIG_DIR` è sufficiente per attivare l'installazione della skill in `~/.claude/skills/agentic-sdlc/`. Stesso pattern già usato per Codex.
+- `preuninstall` rispetta `CLAUDE_CONFIG_DIR` per rimuovere la skill dalla directory di configurazione corretta.
+
+## [1.2.2] - 2026-05-10
+### Changed
+- README convertito in inglese per la pubblicazione npm.
+- Versione allineata a `1.2.2` in `package.json` e `gemini-extension.json`.
+
+## [1.2.1] - 2026-05-10
+### Fixed
+- `postinstall` ora registra la skill anche per Codex copiandola in `$CODEX_HOME/skills/agentic-sdlc/` oppure `~/.codex/skills/agentic-sdlc/`.
+- `preuninstall` rimuove anche la copia Codex della skill.
+- `agentic-sdlc-init` ora crea `AGENTS.md` per Codex invece di `.codex/hooks.json`, che Codex non carica come istruzioni di progetto.
+
+## [1.2.0] - 2026-05-10
 ### Added
 - **Auto-installazione skill nativa Claude Code**: il `postinstall` ora copia `skills/agentic-sdlc-skill/` in `~/.claude/skills/agentic-sdlc/` quando rileva il CLI `claude`. La skill diventa disponibile come `agentic-sdlc` nel tool `Skill` di Claude Code dopo riavvio.
 - Nuovo script `preuninstall.js` che rimuove la skill da `~/.claude/skills/agentic-sdlc/` durante `npm uninstall`.

package/README.md

@@ -1,61 +1,84 @@
-# Agentic SDLC Skill for Claude Code, Gemini CLI & Codex
-
-A "Documentation-First" SDLC protocol designed to manage the software development lifecycle rigorously. It natively supports **Claude Code** (skill auto-installed in `~/.claude/skills/`), **Gemini CLI** (extension), and **Codex AI** (skill auto-installed in `~/.codex/skills/`).
-
-## Key Features
-- **Documentation-First**: Requires documentation (`docs/`) to be created or updated before writing code.
-- **Automatic Audit**: Analyzes the existing architecture and features.
-- **Traceable Workflow**: Tracks feature status in `features_history.md`.
-- **Built-In Quality**: Native integration of analysis, development, and testing.
-
-## Installation
-
-### Via npm (recommended - installs for all detected CLIs)
-
-```bash
-npm install -g @antoneeo/agentic-sdlc-skill
-```
-
-The `postinstall` script automatically detects installed CLIs and configures each one:
-
-- **Claude Code**: copies the skill to `~/.claude/skills/agentic-sdlc/`. Restart Claude Code; invoke it through the `Skill` tool as `agentic-sdlc`, or let it trigger automatically from SDLC/audit prompts.
-- **Gemini CLI**: suggests `gemini extensions install` (see below).
-- **Codex AI**: copies the skill to `$CODEX_HOME/skills/agentic-sdlc/` or `~/.codex/skills/agentic-sdlc/`. Restart Codex to load it.
-
-`npm uninstall -g @antoneeo/agentic-sdlc-skill` also removes the skills from `~/.claude/skills/agentic-sdlc/` and `~/.codex/skills/agentic-sdlc/`.
-
-### Via Gemini CLI (local alternative)
-
-> **Tip:** Before installing, copy this folder from the USB drive to your computer's hard drive (for example, `C:\tools\agentic-sdlc-skill`). This keeps the skill available even after the USB drive is removed.
-
-To install this extension, open a terminal in the folder that contains this README and run:
-
-```bash
-gemini extensions install .
-```
-
-*Note: If you are in a different folder, replace `.` with the full path to the skill folder.*
-
-## Global Availability
-Once installation is complete, the skill is **globally available**. You can close this folder and move to **any other project** on your PC: Gemini CLI will automatically recognize the commands and workflow of the `agentic-sdlc` skill.
-
-## Getting Started
-
-After installation, start Gemini CLI and verify that the skill is available:
-
-1. **List available skills:**
-   ```bash
-   /skills list all
-   ```
-2. **Activate the skill:**
-   The skill activates automatically when it detects requests related to development, audits, or feature management. You can also invoke it explicitly:
-   > "Use the agentic-sdlc skill to analyze this project"
-
-## Project Structure
-- `skills/`: Contains the skill logic (`SKILL.md`).
-- `references/`: Markdown templates for architecture, analysis, and feature history.
-- `gemini-extension.json`: Extension manifest.
-
----
-Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo))
-(c) 2026 Antonio Pinto. All rights reserved.
+# Agentic SDLC Skill for Claude Code, Gemini CLI & Codex
+
+A "Documentation-First" SDLC protocol designed to manage the software development lifecycle rigorously. It natively supports **Claude Code** (skill auto-installed in `~/.claude/skills/`), **Gemini CLI** (extension), and **Codex AI** (skill auto-installed in `~/.codex/skills/`).
+
+## Key Features
+- **Documentation-First**: Requires documentation (`docs/`) to be created or updated before writing code.
+- **Automatic Audit**: Analyzes the existing architecture and features.
+- **Traceable Workflow**: Tracks feature status in `features_history.md`.
+- **Built-In Quality**: Native integration of analysis, development, and testing.
+
+## Installation
+
+### Via npm (recommended - installs for all detected CLIs)
+
+```bash
+npm install -g @antoneeo/agentic-sdlc-skill
+```
+
+The `postinstall` script automatically detects installed CLIs and configures each one:
+
+- **Claude Code**: copies the skill to `~/.claude/skills/agentic-sdlc/`. Restart Claude Code; invoke it through the `Skill` tool as `agentic-sdlc`, or let it trigger automatically from SDLC/audit prompts.
+- **Gemini CLI**: suggests `gemini extensions install` (see below).
+- **Codex AI**: copies the skill to `$CODEX_HOME/skills/agentic-sdlc/` or `~/.codex/skills/agentic-sdlc/`. Restart Codex to load it.
+
+`npm uninstall -g @antoneeo/agentic-sdlc-skill` also removes the skills from `~/.claude/skills/agentic-sdlc/` and `~/.codex/skills/agentic-sdlc/`.
+
+#### Troubleshooting — skill not visible in Claude Code after install
+
+If after `npm install -g` you do **not** see the line `--- Agentic SDLC Skill Discovery ---` in the npm output, and `~/.claude/skills/agentic-sdlc/` does not exist, the `postinstall` hook was skipped by npm. The most common cause is `ignore-scripts=true` in your npm config (set by some Node installers, corporate IT policies, or security tools).
+
+The package ships an explicit `agentic-sdlc-install-skill` command that does the same work but does **not** depend on the `postinstall` hook. After `npm install -g`, the bin shim is created regardless of `ignore-scripts`, so you can simply run:
+
+```bash
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+agentic-sdlc-install-skill
+```
+
+You should see the `--- Agentic SDLC Skill Discovery ---` banner and `📦 Installed Claude Code skill at: ...`. Then restart Claude Code (or Codex) and the skill will be available.
+
+> **Note on `npx`**: because the package exposes two bin commands, the shorthand `npx @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill` does not work — npx cannot disambiguate. If you prefer npx, use the explicit `-p` form: `npx -p @antoneeo/agentic-sdlc-skill agentic-sdlc-install-skill`.
+
+Alternatively, fix the npm config and reinstall (the `postinstall` hook will then run automatically):
+
+```bash
+npm config set ignore-scripts false
+npm uninstall -g @antoneeo/agentic-sdlc-skill
+npm install -g @antoneeo/agentic-sdlc-skill@latest
+```
+
+### Via Gemini CLI (local alternative)
+
+> **Tip:** Before installing, copy this folder from the USB drive to your computer's hard drive (for example, `C:\tools\agentic-sdlc-skill`). This keeps the skill available even after the USB drive is removed.
+
+To install this extension, open a terminal in the folder that contains this README and run:
+
+```bash
+gemini extensions install .
+```
+
+*Note: If you are in a different folder, replace `.` with the full path to the skill folder.*
+
+## Global Availability
+Once installation is complete, the skill is **globally available**. You can close this folder and move to **any other project** on your PC: Gemini CLI will automatically recognize the commands and workflow of the `agentic-sdlc` skill.
+
+## Getting Started
+
+After installation, start Gemini CLI and verify that the skill is available:
+
+1. **List available skills:**
+   ```bash
+   /skills list all
+   ```
+2. **Activate the skill:**
+   The skill activates automatically when it detects requests related to development, audits, or feature management. You can also invoke it explicitly:
+   > "Use the agentic-sdlc skill to analyze this project"
+
+## Project Structure
+- `skills/`: Contains the skill logic (`SKILL.md`).
+- `references/`: Markdown templates for architecture, analysis, and feature history.
+- `gemini-extension.json`: Extension manifest.
+
+---
+Created by **Antonio Pinto** ([GitHub](https://github.com/Antoneeo))
+(c) 2026 Antonio Pinto. All rights reserved.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "Protocollo SDLC Documentation-First per Gemini CLI.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "Protocollo SDLC Documentation-First per Claude Code, Gemini CLI e Codex. Auto-installa le skill native in ~/.claude/skills/ e ~/.codex/skills/. Gestisce audit, analisi, sviluppo e chiusura feature con documentazione sincronizzata.",
   "keywords": [
     "claude-code",
@@ -17,7 +17,8 @@
     "access": "public"
   },
   "bin": {
-    "agentic-sdlc-init": "scripts/init.js"
+    "agentic-sdlc-init": "scripts/init.js",
+    "agentic-sdlc-install-skill": "scripts/postinstall.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",

package/scripts/init.js

@@ -18,23 +18,23 @@ function checkCommand(cmd) {
 
 // 1. Path definitions
 const directories = [
-  path.join(cwd, 'ai_docs'),
-  path.join(cwd, 'ai_docs', 'strategic'),
-  path.join(cwd, 'ai_docs', 'audit'),
-  path.join(cwd, 'ai_docs', 'solutions')
-];
+  path.join(cwd, 'ai_docs'),
+  path.join(cwd, 'ai_docs', 'strategic'),
+  path.join(cwd, 'ai_docs', 'audit'),
+  path.join(cwd, 'ai_docs', 'solutions')
+];
 
 const files = {
   architecture: path.join(cwd, 'ai_docs', 'strategic', 'architecture.md'),
   existingFeatures: path.join(cwd, 'ai_docs', 'strategic', 'existing_features.md'),
   featuresHistory: path.join(cwd, 'ai_docs', 'strategic', 'features_history.md'),
   auditPlan: path.join(cwd, 'ai_docs', 'audit', 'audit_plan.md'),
-  handoff: path.join(cwd, 'ai_docs', 'audit', 'handoff.md'),
-  claudeConfig: path.join(cwd, 'CLAUDE.md'),
-  geminiConfig: path.join(cwd, 'GEMINI.md'),
-  codexAgents: path.join(cwd, 'AGENTS.md'),
-  cursorRules: path.join(cwd, '.cursorrules')
-};
+  handoff: path.join(cwd, 'ai_docs', 'audit', 'handoff.md'),
+  claudeConfig: path.join(cwd, 'CLAUDE.md'),
+  geminiConfig: path.join(cwd, 'GEMINI.md'),
+  codexAgents: path.join(cwd, 'AGENTS.md'),
+  cursorRules: path.join(cwd, '.cursorrules')
+};
 
 // 2. Operational Protocol (System Prompt)
 const protocolContent = `# "Agentic SDLC" Operational Protocol
@@ -68,7 +68,7 @@ Upon feature completion:
 - Update \`ai_docs/strategic/features_history.md\` setting status to \`[COMPLETED]\`.
 `;
 
-const historyBoilerplate = `# Feature History
+const historyBoilerplate = `# Feature History
 
 | ID | Feature Name | Status | Start Date | End Date | Analysis Doc | Notes |
 |:---|:---|:---|:---|:---|:---|:---|
@@ -115,17 +115,17 @@ if (checkCommand('gemini')) {
   writeIfNotExists(files.geminiConfig, protocolContent, 'Gemini Configuration');
 }
 
-if (checkCommand('codex')) {
-  console.log('✅ Codex AI detected.');
-  writeIfNotExists(files.codexAgents, protocolContent, 'Codex AGENTS.md');
-}
+if (checkCommand('codex')) {
+  console.log('✅ Codex AI detected.');
+  writeIfNotExists(files.codexAgents, protocolContent, 'Codex AGENTS.md');
+}
 
 // Cursor/Windsurf (always recommended)
 writeIfNotExists(files.cursorRules, protocolContent, 'Cursor/Windsurf Rules');
 
 console.log('\n✅ Setup completed successfully!');
 console.log('💡 Next steps:');
-console.log('   1. If using Claude Code, start it: it will read CLAUDE.md.');
-console.log('   2. If using Gemini CLI, commands will use GEMINI.md.');
-console.log('   3. If using Codex, restart/open the project so it reads AGENTS.md.');
-console.log('   4. Start analyzing the codebase following ai_docs/audit/audit_plan.md.');
+console.log('   1. If using Claude Code, start it: it will read CLAUDE.md.');
+console.log('   2. If using Gemini CLI, commands will use GEMINI.md.');
+console.log('   3. If using Codex, restart/open the project so it reads AGENTS.md.');
+console.log('   4. Start analyzing the codebase following ai_docs/audit/audit_plan.md.');

package/scripts/postinstall.js

@@ -5,13 +5,14 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'agentic-sdlc-skill');
-const CLAUDE_SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills');
-const CLAUDE_SKILL_TARGET = path.join(CLAUDE_SKILLS_DIR, 'agentic-sdlc');
-const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-const CODEX_SKILLS_DIR = path.join(CODEX_HOME, 'skills');
-const CODEX_SKILL_TARGET = path.join(CODEX_SKILLS_DIR, 'agentic-sdlc');
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const SKILL_SOURCE = path.join(PACKAGE_ROOT, 'skills', 'agentic-sdlc-skill');
+const CLAUDE_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+const CLAUDE_SKILLS_DIR = path.join(CLAUDE_HOME, 'skills');
+const CLAUDE_SKILL_TARGET = path.join(CLAUDE_SKILLS_DIR, 'agentic-sdlc');
+const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+const CODEX_SKILLS_DIR = path.join(CODEX_HOME, 'skills');
+const CODEX_SKILL_TARGET = path.join(CODEX_SKILLS_DIR, 'agentic-sdlc');
 
 function checkCommand(cmd) {
   try {
@@ -37,7 +38,7 @@ function copyRecursive(src, dest) {
   }
 }
 
-function installClaudeSkill() {
+function installClaudeSkill() {
   if (!fs.existsSync(SKILL_SOURCE)) {
     console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping Claude Code install.`);
     return false;
@@ -52,54 +53,57 @@ function installClaudeSkill() {
     console.log(`⚠️  Failed to install Claude Code skill: ${err.message}`);
     console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${CLAUDE_SKILL_TARGET}".`);
     return false;
-  }
-}
-
-function installCodexSkill() {
-  if (!fs.existsSync(SKILL_SOURCE)) {
-    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping Codex install.`);
-    return false;
-  }
-  try {
-    fs.mkdirSync(CODEX_SKILLS_DIR, { recursive: true });
-    copyRecursive(SKILL_SOURCE, CODEX_SKILL_TARGET);
-    console.log(`📦 Installed Codex skill at: ${CODEX_SKILL_TARGET}`);
-    console.log('   Restart Codex to load it. Invoke it as "$agentic-sdlc" or by asking for Agentic SDLC.');
-    return true;
-  } catch (err) {
-    console.log(`⚠️  Failed to install Codex skill: ${err.message}`);
-    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${CODEX_SKILL_TARGET}".`);
-    return false;
-  }
-}
-
-function hasCodexHome() {
-  return Boolean(process.env.CODEX_HOME) || fs.existsSync(CODEX_HOME);
-}
-
-console.log('\n--- Agentic SDLC Skill Discovery ---');
+  }
+}
 
-const agents = [
-  { name: 'Claude Code', cmd: 'claude', onDetect: installClaudeSkill },
-  { name: 'Gemini CLI', cmd: 'gemini' }
-];
+function installCodexSkill() {
+  if (!fs.existsSync(SKILL_SOURCE)) {
+    console.log(`⚠️  Skill source not found at ${SKILL_SOURCE}; skipping Codex install.`);
+    return false;
+  }
+  try {
+    fs.mkdirSync(CODEX_SKILLS_DIR, { recursive: true });
+    copyRecursive(SKILL_SOURCE, CODEX_SKILL_TARGET);
+    console.log(`📦 Installed Codex skill at: ${CODEX_SKILL_TARGET}`);
+    console.log('   Restart Codex to load it. Invoke it as "$agentic-sdlc" or by asking for Agentic SDLC.');
+    return true;
+  } catch (err) {
+    console.log(`⚠️  Failed to install Codex skill: ${err.message}`);
+    console.log(`   Manual install: copy "${SKILL_SOURCE}" to "${CODEX_SKILL_TARGET}".`);
+    return false;
+  }
+}
+
+function hasCodexHome() {
+  return Boolean(process.env.CODEX_HOME) || fs.existsSync(CODEX_HOME);
+}
+
+function hasClaudeHome() {
+  return Boolean(process.env.CLAUDE_CONFIG_DIR) || fs.existsSync(CLAUDE_HOME);
+}
+
+console.log('\n--- Agentic SDLC Skill Discovery ---');
 
 let detected = false;
-agents.forEach(agent => {
-  if (checkCommand(agent.cmd)) {
-    console.log(`✅ Detected: ${agent.name}`);
-    detected = true;
-    if (typeof agent.onDetect === 'function') agent.onDetect();
-  }
-});
-
-if (checkCommand('codex') || hasCodexHome()) {
-  console.log(`✅ Detected: Codex AI`);
-  detected = true;
-  installCodexSkill();
-}
-
-if (!detected) {
+
+if (checkCommand('claude') || hasClaudeHome()) {
+  console.log(`✅ Detected: Claude Code`);
+  detected = true;
+  installClaudeSkill();
+}
+
+if (checkCommand('gemini')) {
+  console.log(`✅ Detected: Gemini CLI`);
+  detected = true;
+}
+
+if (checkCommand('codex') || hasCodexHome()) {
+  console.log(`✅ Detected: Codex AI`);
+  detected = true;
+  installCodexSkill();
+}
+
+if (!detected) {
   console.log('ℹ️  No specific AI CLI detected globally, but you can still use the skill.');
 }
 

package/scripts/preuninstall.js

@@ -2,21 +2,22 @@
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
-
-const CLAUDE_SKILL_TARGET = path.join(os.homedir(), '.claude', 'skills', 'agentic-sdlc');
-const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-const CODEX_SKILL_TARGET = path.join(CODEX_HOME, 'skills', 'agentic-sdlc');
-
-function removeSkill(target, label) {
-  if (!fs.existsSync(target)) return;
-  try {
-    fs.rmSync(target, { recursive: true, force: true });
-    console.log(`🧹 Removed ${label} skill at: ${target}`);
-  } catch (err) {
-    console.log(`⚠️  Could not remove ${target}: ${err.message}`);
-  }
-}
-
-removeSkill(CLAUDE_SKILL_TARGET, 'Claude Code');
-removeSkill(CODEX_SKILL_TARGET, 'Codex');
+const os = require('os');
+
+const CLAUDE_HOME = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+const CLAUDE_SKILL_TARGET = path.join(CLAUDE_HOME, 'skills', 'agentic-sdlc');
+const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+const CODEX_SKILL_TARGET = path.join(CODEX_HOME, 'skills', 'agentic-sdlc');
+
+function removeSkill(target, label) {
+  if (!fs.existsSync(target)) return;
+  try {
+    fs.rmSync(target, { recursive: true, force: true });
+    console.log(`🧹 Removed ${label} skill at: ${target}`);
+  } catch (err) {
+    console.log(`⚠️  Could not remove ${target}: ${err.message}`);
+  }
+}
+
+removeSkill(CLAUDE_SKILL_TARGET, 'Claude Code');
+removeSkill(CODEX_SKILL_TARGET, 'Codex');