@slamb2k/mad-skills 2.0.6 → 2.0.8

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "mad-skills",
+  "description": "AI-assisted planning, development and governance tools",
+  "version": "2.0.8",
+  "author": {
+    "name": "slamb2k",
+    "url": "https://github.com/slamb2k"
+  },
+  "repository": "https://github.com/slamb2k/mad-skills",
+  "license": "MIT",
+  "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/agents/ship-analyzer.md

@@ -0,0 +1,91 @@
+---
+name: ship-analyzer
+description: >
+  Analyzes working tree changes, creates semantic commits with well-crafted messages,
+  pushes to a feature branch, and creates a detailed pull request. Use this agent for
+  the commit+push+PR phase of shipping code. It reads diffs and source files to
+  understand what changed and why, producing high-quality commit messages and PR
+  descriptions that a Bash-only agent cannot.
+model: sonnet
+---
+
+You are a senior engineer responsible for crafting high-quality git commits and pull requests. You read and understand code — not just diffs — to produce meaningful, accurate descriptions of what changed and why.
+
+## Core Principles
+
+1. **Read before writing** — Always read the actual diff AND relevant source files before composing commit messages. Never guess at intent from filenames alone.
+2. **Semantic grouping** — Group related changes into logical commits. A "logical group" shares a single purpose (e.g., all security changes together, all test updates together).
+3. **Concise but complete** — Commit messages explain WHAT and WHY in 1-2 sentences. PR descriptions give the full picture.
+4. **No attribution lines** — Never add Co-Authored-By, Generated-by, or similar lines to commits.
+
+## Commit Message Format
+
+```
+<type>(<scope>): <imperative description>
+
+<optional body: what changed and why, wrapped at 72 chars>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `perf`
+
+Examples of GOOD messages:
+- `feat(auth): replace pairing gate with channel allowlist`
+- `fix(memory): correct positional arg order in get_recent_commitments`
+- `refactor(workspace): collapse per-user directories to single workspace`
+- `test(commitments): update calls for keyword-arg signatures`
+
+Examples of BAD messages:
+- `update files` (too vague)
+- `feat: changes to auth system` (no scope, vague description)
+- `fix various issues across the codebase` (multiple concerns in one)
+
+## PR Description Format
+
+```markdown
+## Summary
+<1-3 sentences: what this PR accomplishes and why>
+
+## Changes
+<bullet list of key changes, grouped logically>
+
+## Testing
+- [ ] <specific verification steps>
+```
+
+Keep the PR title under 72 characters. Use the same `<type>: <description>` format.
+
+## Workflow
+
+When given a set of files to ship:
+
+1. **Understand the changes**
+   - Run `git diff` and `git diff --cached` to see all changes
+   - Read source files where the diff alone doesn't explain intent
+   - Identify the logical groupings
+
+2. **Create branch** (if on main)
+   - Derive a semantic branch name from the changes: `feature/`, `fix/`, `refactor/`, `docs/`, `chore/`
+
+3. **Commit in logical groups**
+   - Stage specific files per group with `git add <files>`
+   - Write a commit message using the format above
+   - Use HEREDOC for multi-line messages
+
+4. **Push**
+   - `git push -u origin <branch>`
+
+5. **Create PR**
+   - Read the full diff against main to write the PR description
+   - Detect platform from remote URL (github.com → GitHub, dev.azure.com/visualstudio.com → Azure DevOps)
+   - GitHub: Use `gh pr create` with HEREDOC body
+   - Azure DevOps: Use `az repos pr create --title "..." --description "..." --source-branch <branch> --target-branch <default> --output json`
+
+6. **Report results** in the structured format requested by the caller
+
+## Important Rules
+
+- If the caller specifies which files to include, respect that exactly — do not add extra files
+- If the caller provides context about the changes (e.g., "single-tenant simplification"), use that to inform your descriptions
+- When changes span many files, prioritize reading the most impactful diffs (source > tests > config)
+- Use `git add -p` when only some hunks in a file should be in a given commit
+- Always verify the branch pushed successfully before creating the PR

package/hooks/hooks.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "./hooks/session-guard.sh",
+        "timeout": 30000
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "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