@slamb2k/mad-skills 2.0.7 → 2.0.9

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
-  "name": "slamb2k-plugins",
+  "name": "slamb2k",
   "description": "Claude Code plugins by Simon Lamb",
-  "version": "1.2.0",
+  "version": "2.0.9",
   "owner": {
     "name": "Simon Lamb",
     "url": "https://github.com/slamb2k"
@@ -10,7 +10,7 @@
     {
       "name": "mad-skills",
       "description": "AI-assisted planning, development and governance tools",
-      "version": "2.0.7",
+      "version": "2.0.9",
       "author": {
         "name": "slamb2k",
         "url": "https://github.com/slamb2k"
@@ -18,7 +18,13 @@
       "source": "./",
       "category": "development",
       "homepage": "https://github.com/slamb2k/mad-skills",
-      "tags": ["planning", "tdd", "architecture", "llm-review", "implementation"]
+      "tags": [
+        "planning",
+        "tdd",
+        "architecture",
+        "llm-review",
+        "implementation"
+      ]
     }
   ]
-}
+}

package/.claude-plugin/plugin.json

@@ -1,16 +1,18 @@
 {
   "name": "mad-skills",
   "description": "AI-assisted planning, development and governance tools",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "author": {
     "name": "slamb2k",
     "url": "https://github.com/slamb2k"
   },
   "repository": "https://github.com/slamb2k/mad-skills",
   "license": "MIT",
-  "keywords": ["planning", "tdd", "architecture", "llm-review", "implementation"],
-  "commands": ["./commands/"],
-  "agents": ["./agents/"],
-  "skills": ["./skills/"],
-  "hooks": "./hooks/"
-}
+  "keywords": [
+    "planning",
+    "tdd",
+    "architecture",
+    "llm-review",
+    "implementation"
+  ]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 ![Mad Skills](assets/mad-skills.png)
 
-An npm-based skill framework for Claude Code. Ships 7 skills covering the full development lifecycle — from project initialization to shipping PRs.
+A skill framework for Claude Code. Ships 8 skills covering the full development lifecycle — from project initialization to shipping PRs.
 
 ## Skills
 
@@ -14,33 +14,111 @@ An npm-based skill framework for Claude Code. Ships 7 skills covering the full d
 | **prime** | `/prime` | Load project context before feature work. Supports domain-specific context (security, routing, dashboard, etc.). |
 | **rig** | `/rig` | Bootstrap repos with lefthook hooks, commit templates, PR templates, and GitHub Actions workflows. Idempotent. |
 | **ship** | `/ship` | Full PR lifecycle — sync with main, create branch, commit, push, create PR, wait for CI, fix issues, squash merge, cleanup. |
+| **speccy** | `/speccy` | Interview-driven specification builder. Reviews code/docs, interviews through targeted questions, produces structured specs. |
 | **sync** | `/sync` | Sync local repo with origin/main. Stashes changes, pulls, restores stash, cleans up stale branches. |
 
 ## Installation
 
+Three methods are available. The table below shows what each delivers:
+
+| | Plugin | npx skills | npm package |
+|---|---|---|---|
+| Skills (slash commands) | ✅ all 8 | ✅ all 8 | — |
+| Agents (e.g. ship-analyzer) | ✅ | ❌ | — |
+| Session hooks (session-guard) | ✅ | ❌ | — |
+| Cross-agent (Cursor, Cline, etc.) | ❌ Claude Code only | ✅ | — |
+| Selective skill install | ❌ | ✅ | — |
+| Auto-updates | ✅ | ❌ | — |
+
+### Plugin (recommended)
+
+```
+/plugin install mad-skills@slamb2k
+```
+
+Installs skills, agents, and session hooks from the GitHub repo into `~/.claude/plugins/`. Updates automatically. Claude Code only.
+
+> **First time setup — add the marketplace (one-time):**
+>
+> **Option A** — CLI (outside Claude Code):
+> ```bash
+> claude plugin marketplace add slamb2k/mad-skills
+> ```
+>
+> **Option B** — Manual (add to `~/.claude/settings.json`):
+> ```json
+> "extraKnownMarketplaces": {
+>   "slamb2k": {
+>     "source": { "source": "github", "repo": "slamb2k/mad-skills" }
+>   }
+> }
+> ```
+>
+> Then install the plugin inside Claude Code with `/plugin install mad-skills@slamb2k`, or from the CLI with `claude plugin install mad-skills@slamb2k`.
+
+### npx skills
+
+```bash
+npx skills add slamb2k/mad-skills -g -y              # All skills, global
+npx skills add slamb2k/mad-skills --skill ship -g -y  # Specific skill
+```
+
+Installs skills into `~/.claude/skills/` (and `~/.agents/skills/` for other agents). **Does not install agents or hooks.** This means:
+
+- `/build` falls back to `general-purpose` agent for the ship stage instead of the optimised `ship-analyzer` agent
+- The session-guard hook (CLAUDE.md staleness detection, git validation) is not active
+
+Use this method when you need cross-agent compatibility (Cursor, Cline, Amp, etc.) or want to install individual skills.
+
+> **Note for dotfiles users:** If `~/.claude/skills/` is symlinked from a dotfiles repo, `npx skills` will create broken relative symlinks. Replace the skills directory symlink with a real directory before installing. See [dotfiles compatibility](#dotfiles-compatibility) below.
+
+### npm package
+
+The `@slamb2k/mad-skills` npm package is the **release artifact** — it is published on every merge to main and is used internally by the plugin system. It does not provide a CLI and cannot be used to install skills directly.
+
+### Invoke skills
+
+After installation, invoke skills with `/<skill-name>` (e.g., `/ship`, `/sync`).
+
+### Upgrading from the old CLI (`npx @slamb2k/mad-skills`)
+
+If you previously installed via the v2.0.x CLI, clean up stale artifacts first:
+
 ```bash
-# Install globally
-npm install -g @slamb2k/mad-skills
+# Remove old command stubs
+rm -f ~/.claude/commands/{brace,build,distil,prime,rig,ship,sync,speccy}.md
+
+# Remove installer manifest and stale skill files
+rm -f ~/.claude/.mad-skills-manifest.json
+rm -f ~/.claude/skills/*/instructions.md
+```
+
+Then install fresh using plugin or npx skills above.
+
+### Dotfiles compatibility
+
+If you manage `~/.claude` via a dotfiles repo with symlinked subdirectories, `npx skills` creates relative symlinks that break when `~/.claude/skills/` is not physically located at `~/.claude/skills/`.
 
-# Or run directly with npx
-npx @slamb2k/mad-skills --list             # List available skills
-npx @slamb2k/mad-skills                    # Install all skills
-npx @slamb2k/mad-skills --skill ship,sync  # Install specific skills
+**Fix:** ensure `~/.claude/skills/` is a real directory (not a symlink), and do not re-symlink it from dotfiles. For custom/local skills you want in dotfiles, use per-skill absolute symlinks in your install script:
+
+```bash
+ln -sfn "$DOTFILES_DIR/skills/my-skill" "$HOME/.claude/skills/my-skill"
 ```
 
-Skills are installed as slash commands in your Claude Code environment. After installation, invoke them with `/<skill-name>` (e.g., `/ship`, `/sync`).
+`npx skills` will leave entries it did not create untouched.
 
 ## Repository Structure
 
 ```
 mad-skills/
-├── skills/                  # Skill definitions (7 skills)
+├── skills/                  # Skill definitions (8 skills)
 │   ├── build/
 │   ├── brace/
 │   ├── distil/
 │   ├── prime/
 │   ├── rig/
 │   ├── ship/
+│   ├── speccy/
 │   └── sync/
 ├── scripts/                 # Build and CI tooling
 │   ├── validate-skills.js   # Structural validation
@@ -48,10 +126,7 @@ mad-skills/
 │   ├── run-evals.js         # Eval runner (Anthropic/OpenRouter)
 │   ├── build-manifests.js   # Generate skills/manifest.json
 │   └── package-skills.js    # Package .skill archives
-├── src/
-│   └── cli.js               # npx installer CLI
-├── commands/                # Slash command stubs
-├── hooks/                   # Session hooks (session-guard)
+├── hooks/                   # Session hooks + plugin hook config
 ├── agents/                  # Agent definitions (ship-analyzer)
 ├── tests/results/           # Eval output
 ├── archive/                 # Legacy skills (v1.x)
@@ -69,8 +144,7 @@ Each skill in `skills/<name>/` follows a standard layout:
 
 ```
 skills/<name>/
-├── SKILL.md              # Frontmatter (name, description) + banner
-├── instructions.md       # Execution logic (max 500 lines)
+├── SKILL.md              # Frontmatter + banner + execution logic (single file)
 ├── references/           # Extracted prompts, contracts, guides
 ├── assets/               # Static files (templates, components)
 └── tests/
@@ -109,20 +183,22 @@ npm test                         # validate + lint + eval
 - Detects which skills changed and posts eval results as PR comments
 
 **Release pipeline** (`.github/workflows/release.yml`):
-- Triggers on push to main
-- Validates, lints, runs evals, builds manifests
-- Creates version tag from package.json, publishes to npm with provenance
+- Phase 1: Triggers on push to main, validates, bumps patch version, creates auto-merge PR
+- Phase 2: When version bump merges, creates tag, publishes to npm with provenance
 - Builds `.skill` packages and creates a GitHub Release
-- Skips publish if the version tag already exists
 
 ## Archive
 
-Legacy skills from v1.x are preserved in `archive/` for reference:
-- play-tight (Browser Automation)
-- pixel-pusher (UI/UX Design)
-- cyberarian (Document Lifecycle Management)
-- start-right (Repository Scaffolding)
-- graphite-skill (Git/Graphite Workflows)
+The `archive/` folder contains **inactive** skills, agents, hooks, and other assets from previous versions. These are kept for historical reference only — they are **not part of the mad-skills release**, not published to npm, not installed by `npx skills`, and not supported.
+
+| Name | Description |
+|------|-------------|
+| play-tight | Browser Automation (v1.x) |
+| pixel-pusher | UI/UX Design (v1.x) |
+| cyberarian | Document Lifecycle Management (v1.x) |
+| start-right | Repository Scaffolding (v1.x) |
+| graphite-skill | Git/Graphite Workflows (v1.x) |
+| example-skill | Scaffold template for new skills |
 
 ## License
 

package/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/session-guard.sh",
+            "timeout": 30000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/session-guard-prompt.sh",
+            "timeout": 10000
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-guard-prompt.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# session-guard-prompt.sh — UserPromptSubmit companion hook for session-guard
+#
+# Checks if session-guard.sh left a pending context file from SessionStart.
+# If found, re-emits the context as additionalContext on the first user prompt,
+# then deletes the flag file so it only fires once.
+#
+# This works around the known limitation where SessionStart hook output is
+# silently injected and may not surface until after the first prompt is
+# already processed (see anthropics/claude-code#10808).
+#
+# Install globally in ~/.claude/settings.json:
+#   "command": "\"$HOME\"/.claude/hooks/session-guard-prompt.sh"
+#
+# Or per-project in .claude/settings.json:
+#   "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-guard-prompt.sh"
+
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PENDING_DIR="${TMPDIR:-/tmp}/claude-session-guard"
+GUARD_KEY=$(echo "$PROJECT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "default")
+PENDING_FILE="$PENDING_DIR/$GUARD_KEY.pending"
+
+# No pending file — fast exit
+if [[ ! -f "$PENDING_FILE" ]]; then
+  jq -n '{}'
+  exit 0
+fi
+
+CONTEXT=$(cat "$PENDING_FILE")
+rm -f "$PENDING_FILE"
+
+# Also clean up the dedup lock from session-guard.sh
+rm -f "$PENDING_DIR/$GUARD_KEY.lock"
+
+# Skip re-emit if session-guard found no issues (just the ✅ line, no warnings)
+if [[ $(echo "$CONTEXT" | grep -c '⚠️\|ℹ️') -eq 0 ]]; then
+  jq -n '{}'
+  exit 0
+fi
+
+WRAPPED=$(cat <<EOF
+[SESSION GUARD — FIRST PROMPT REMINDER]
+The following was detected at session start. Act on these items NOW using
+AskUserQuestion BEFORE proceeding with the user's request.
+
+$CONTEXT
+EOF
+)
+
+jq -n --arg ctx "$WRAPPED" '{
+  hookSpecificOutput: {
+    hookEventName: "UserPromptSubmit",
+    additionalContext: $ctx
+  }
+}'
+
+exit 0