@slamb2k/mad-skills 2.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MAD Skills Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# MAD Skills
+
+![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.
+
+## Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| **build** | `/build` | Context-isolated feature development pipeline. Takes a design/plan and executes explore, question, architect, implement, review, ship inside subagents. |
+| **brace** | `/brace` | Initialize projects with the GOTCHA/BRACE framework. Creates 6-layer structure, BRACE build methodology, and project CLAUDE.md. |
+| **distil** | `/distil` | Generate multiple unique web design variations. Creates a Vite + React + TypeScript + Tailwind project with N designs at /1, /2, /3. |
+| **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. |
+| **sync** | `/sync` | Sync local repo with origin/main. Stashes changes, pulls, restores stash, cleans up stale branches. |
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @slamb2k/mad-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
+```
+
+Skills are installed as slash commands in your Claude Code environment. After installation, invoke them with `/<skill-name>` (e.g., `/ship`, `/sync`).
+
+## Repository Structure
+
+```
+mad-skills/
+├── skills/                  # Skill definitions (7 skills)
+│   ├── build/
+│   ├── brace/
+│   ├── distil/
+│   ├── prime/
+│   ├── rig/
+│   ├── ship/
+│   └── sync/
+├── scripts/                 # Build and CI tooling
+│   ├── validate-skills.js   # Structural validation
+│   ├── lint-skills.js       # SKILL.md linting
+│   ├── 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)
+├── agents/                  # Agent definitions (ship-analyzer)
+├── tests/results/           # Eval output
+├── archive/                 # Legacy skills (v1.x)
+├── .claude-plugin/          # Plugin metadata
+│   ├── marketplace.json
+│   └── plugin.json
+└── .github/workflows/
+    ├── ci.yml               # PR validation + evals
+    └── release.yml          # Tagged release → npm + GitHub
+```
+
+### Skill Structure
+
+Each skill in `skills/<name>/` follows a standard layout:
+
+```
+skills/<name>/
+├── SKILL.md              # Frontmatter (name, description) + banner
+├── instructions.md       # Execution logic (max 500 lines)
+├── references/           # Extracted prompts, contracts, guides
+├── assets/               # Static files (templates, components)
+└── tests/
+    └── evals.json        # Eval cases for the skill
+```
+
+## Development
+
+```bash
+# Validate all skill structures
+npm run validate
+
+# Lint SKILL.md files
+npm run lint
+
+# Run evals (requires ANTHROPIC_API_KEY or OPENROUTER_API_KEY)
+npm run eval
+npm run eval -- --verbose
+npm run eval:update              # Update eval snapshots
+
+# Build
+npm run build:manifests          # Generate skills/manifest.json
+npm run build:skills             # Package .skill archives
+npm run build                    # Both
+
+# Full test suite
+npm test                         # validate + lint + eval
+```
+
+## CI/CD
+
+**PR pipeline** (`.github/workflows/ci.yml`):
+- Triggers on all pull requests (required status check)
+- Runs validate and lint
+- Runs evals when API key is available (skipped for external PRs)
+- 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
+- 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)
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@slamb2k/mad-skills",
+  "version": "2.0.6",
+  "description": "Claude Code skills collection with CI/CD and npx installer",
+  "type": "module",
+  "bin": {
+    "claude-skills": "./src/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/slamb2k/mad-skills"
+  },
+  "files": [
+    "src/",
+    "skills/"
+  ],
+  "scripts": {
+    "validate": "node scripts/validate-skills.js",
+    "lint": "node scripts/lint-skills.js",
+    "eval": "node scripts/run-evals.js",
+    "eval:update": "node scripts/run-evals.js --update-snapshots",
+    "build:manifests": "node scripts/build-manifests.js",
+    "build:skills": "node scripts/package-skills.js",
+    "build": "npm run build:manifests && npm run build:skills",
+    "prepublishOnly": "npm run validate && npm run build:manifests",
+    "test": "npm run validate && npm run lint && npm run eval"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "mcp",
+    "ai"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0"
+  }
+}

package/skills/brace/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: brace
+description: >
+  Initialize any project directory with the GOTCHA/BRACE framework for agentic
+  AI systems. Creates the 6-layer structure (Goals, Orchestration, Tools,
+  Context, Hard prompts, Args), BRACE build methodology, and a project
+  CLAUDE.md. Recommends claude-mem for persistent memory. Idempotent — safe
+  to run on existing projects. Triggers: "init gotcha", "setup brace", "brace",
+  "initialize framework", "bootstrap gotcha".
+argument-hint: [--no-brace] [--force]
+---
+
+# Brace - GOTCHA/BRACE Framework Bootstrap
+
+When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
+Pick ONE tagline at random — vary your choice each time:
+
+```
+{tagline}
+
+    ██╗██████╗ ██████╗  █████╗  ██████╗███████╗
+   ██╔╝██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔════╝
+  ██╔╝ ██████╔╝██████╔╝███████║██║     █████╗
+ ██╔╝  ██╔══██╗██╔══██╗██╔══██║██║     ██╔══╝
+██╔╝   ██████╔╝██║  ██║██║  ██║╚██████╗███████╗
+╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝
+
+```
+
+Taglines:
+- Bracing the structure...
+- Reinforcing before load!
+- Locking in the framework!
+- Preparing for heavy lifting!
+- Cross-bracing the foundation!
+- Tightening the load path!
+- Structural integrity confirmed!
+- Brace for impact!
+
+Follow instructions in: [instructions.md](instructions.md)
+
+## Subagent Architecture
+
+- Phase 1 (scan): **Bash** subagent, **haiku** model
+- Phase 4 (scaffold): **general-purpose** subagent (content generation)
+- Phase 5 (verify): **Bash** subagent, **haiku** model
+
+## Flags
+
+- `--no-brace` — Skip BRACE build methodology
+- `--force` — Overwrite existing files without prompting

package/skills/brace/assets/gitignore-template

@@ -0,0 +1,28 @@
+# Credentials & secrets
+.env
+.env.*
+*.pem
+*.key
+credentials.json
+token.json
+
+# Data & databases
+data/
+*.db
+*.sqlite
+*.sqlite3
+
+# Temp & scratch
+.tmp/
+
+# Memory embeddings cache
+memory/*.npy
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# OS files
+.DS_Store
+Thumbs.db

package/skills/brace/assets/global-preferences-template.md

@@ -0,0 +1,53 @@
+# Global Preferences & Universal Principles
+
+Template appended to `~/.claude/CLAUDE.md` by brace when the user
+selects "global" or "both" installation level. The Phase 4 agent inserts
+this content before the "## Current Skills" section.
+
+---
+
+BEGIN TEMPLATE
+
+## Global Preferences
+
+These defaults apply to all projects. Override in a project-level CLAUDE.md.
+
+### Tooling
+- **Python**: Use `uv` for virtual environments and dependency management
+- **JavaScript/TypeScript**: Use `bun` over `node`/`npm`/`yarn`
+- **Git**: Use conventional commits with scope — `feat(scope): message`
+
+### Code Quality
+- Prefer editing existing files over creating new ones
+- Do not create documentation files (README, CHANGELOG) unless asked
+- Do not add comments, docstrings, or type annotations to code you didn't change
+- Prefer simple, readable code over clever abstractions
+
+### Security
+- Never commit `.env`, credentials, or API keys
+- Check `git diff --staged` for secrets before committing
+
+### Python
+- Use `pathlib` over `os.path`
+- Use f-strings over `.format()` or `%`
+- Type hints on function signatures, not internal variables
+
+### Testing
+- Always run tests after making changes unless told to skip
+
+## Universal Operating Principles
+
+### Question & Assumption Accountability
+- When making an assumption, state it explicitly and record it
+- When a question can't be answered immediately, log it as an open item
+- When deferring a fix or skipping an edge case, document why
+- At the end of each task, review all assumptions and open questions
+- Never close a task with unacknowledged open questions
+- Present unresolved items to the user with context and suggested actions
+
+### Communication
+- When stuck, explain what's missing — don't guess or invent capabilities
+- When a workflow fails mid-execution, preserve intermediate outputs
+- Verify output format before chaining into another tool or step
+
+END TEMPLATE

package/skills/brace/instructions.md

@@ -0,0 +1,229 @@
+# Brace Instructions
+
+Initialize any project directory with the GOTCHA/BRACE framework. Idempotent —
+safe to re-run on existing projects. Content templates and subagent prompts
+are in `references/`.
+
+**Key principle:** Scan first, present plan, get approval, then act.
+
+Phase prompts: `references/phase-prompts.md`
+Scaffold manifest: `references/scaffold-manifest.md`
+Report format: `references/report-template.md`
+
+---
+
+## Flags
+
+Parse optional flags from the request:
+- `--no-brace` — Skip BRACE build methodology (goals/build_app.md)
+- `--force` — Overwrite existing files without prompting
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| claude-mem | plugin | — | no | ask | `claude plugin install claude-mem` |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+1. Capture **FLAGS** from the user's request
+2. Create a task list tracking all 5 phases
+
+---
+
+## Phase 1: Directory Scan
+
+Launch **Bash** subagent (**haiku**):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Scan directory for existing GOTCHA structure",
+  prompt: <read from references/phase-prompts.md#phase-1>
+)
+```
+
+Parse SCAN_REPORT. Extract:
+- `directory_name` (used as default project name)
+- `existing_dirs` / `missing_dirs`
+- `existing_files` / `missing_files`
+- `has_claude_md` / `has_gitignore`
+- `has_atlas` (legacy ATLAS naming detected)
+- `has_forge` (legacy FORGE naming detected)
+
+---
+
+## Phase 1b: Legacy Upgrade Detection
+
+**Skip if neither `has_atlas` nor `has_forge` is true.**
+
+If SCAN_REPORT shows `has_atlas: true` or `has_forge: true`, ask the user via AskUserQuestion:
+
+   Question: "Legacy naming detected. Upgrade to BRACE?"
+   Options:
+   - "Yes, upgrade to BRACE" — Replace legacy references with BRACE equivalents
+   - "No, leave as-is" — Keep existing naming
+
+Store result as `upgrade_legacy: true|false` in USER_CONFIG.
+
+---
+
+## Phase 2: Project Inquiry
+
+**Runs on primary thread** (user interaction required).
+
+1. Derive default project name from SCAN_REPORT `directory_name`
+2. Present via AskUserQuestion:
+
+   Question: "What to include in GOTCHA setup?"
+   Options:
+   - "Full GOTCHA + BRACE (Recommended)"
+   - "GOTCHA structure only (no BRACE methodology)"
+   - "Cancel"
+
+3. If not cancelled, ask for project description (one sentence) via
+   AskUserQuestion with free text.
+
+4. Ask installation level via AskUserQuestion:
+
+   Question: "Where should global preferences and universal principles go?"
+   Options:
+   - "Both — global + project (Recommended)" → portable AND global coverage
+   - "Global (~/.claude/CLAUDE.md) only" → applies to all projects
+   - "Project level only" → self-contained, portable
+
+5. Store as USER_CONFIG:
+   - project_name: from directory name or user override
+   - description: from user input
+   - include_brace: true/false (based on selection and `--no-brace`)
+   - install_level: "both" | "global" | "project"
+
+**If cancelled, stop here.**
+
+---
+
+## Phase 3: Present Plan & Approve
+
+Build the ACTION_PLAN from SCAN_REPORT + USER_CONFIG + FLAGS.
+
+For each item in `references/scaffold-manifest.md`:
+- If component not selected in USER_CONFIG → status: "not selected"
+- If item already exists (from SCAN_REPORT) and no `--force` → status: "skip"
+- If item exists and `--force` → status: "overwrite"
+- If CLAUDE.md exists → status: "merge" (append GOTCHA section)
+- If .gitignore exists → status: "merge" (append missing entries)
+- Otherwise → status: "create"
+
+If `upgrade_legacy` is true in USER_CONFIG, set status "upgrade" for:
+- CLAUDE.md (replaces "merge" or "skip" — upgrade takes priority)
+- goals/build_app.md (replaces "skip")
+- goals/manifest.md (replaces "skip")
+
+Present plan summary to user via AskUserQuestion:
+
+```
+GOTCHA Framework Setup for: {project_name}
+
+Will create:  {list of items with status "create"}
+Will merge:   {list of items with status "merge"}
+Will upgrade: {list of items with status "upgrade" — legacy → BRACE}
+Will skip:    {count} existing items
+Not selected: {count} items
+Global config: {install_level description}
+
+Proceed?
+```
+
+Options: "Yes, proceed" / "Cancel"
+
+**If cancelled, stop here.**
+
+---
+
+## Phase 4: Scaffold Structure
+
+Launch **general-purpose** subagent:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Create GOTCHA framework structure",
+  prompt: <read from references/phase-prompts.md#phase-4>
+)
+```
+
+Before sending the prompt, substitute these variables:
+- `{ACTION_PLAN}` — the action plan from Phase 3
+- `{PROJECT_NAME}` — from USER_CONFIG
+- `{PROJECT_DESCRIPTION}` — from USER_CONFIG
+- `{INSTALL_LEVEL}` — from USER_CONFIG ("both", "global", or "project")
+- `{CLAUDE_MD_TEMPLATE}` — read from `references/claude-md-template.md`
+  (the section between BEGIN TEMPLATE and END TEMPLATE)
+- `{GITIGNORE_CONTENT}` — read from `assets/gitignore-template`
+- `{GOALS_MANIFEST}` — read from `references/scaffold-manifest.md`
+  (the goals/manifest.md content block)
+- `{TOOLS_MANIFEST}` — read from `references/scaffold-manifest.md`
+  (the tools/manifest.md content block)
+- `{BRACE_WORKFLOW}` — read from `references/brace-workflow.md`
+  (the section after the header, used for goals/build_app.md)
+- `{GLOBAL_PREFERENCES_CONTENT}` — read from `assets/global-preferences-template.md`
+  (the section between BEGIN TEMPLATE and END TEMPLATE)
+
+Parse SCAFFOLD_REPORT. If status is "failed", report to user and stop.
+
+---
+
+## Phase 5: Verification & Report
+
+Launch **Bash** subagent (**haiku**):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Verify GOTCHA structure",
+  prompt: <read from references/phase-prompts.md#phase-5>
+)
+```
+
+Parse VERIFY_REPORT. Present the final summary using the format in
+`references/report-template.md`.
+
+---
+
+## Idempotency Rules
+
+- **Skip** directories and files that already exist (unless `--force`)
+- **Merge** CLAUDE.md: append GOTCHA section if file exists but lacks it
+- **Merge** .gitignore: append missing entries only
+- **Never delete** user content
+- **Never overwrite** without `--force` or explicit user approval
+
+---
+
+## Error Handling
+
+Standard escalation pattern:
+1. If retryable (permission issue after mkdir): retry once
+2. If persistent: report to user with specific error
+3. Offer: skip and continue / abort
+4. Never silently swallow errors
+
+Common issues:
+- Permission denied → report, suggest checking directory permissions
+- CLAUDE.md merge conflict → show both versions, let user choose
+- Directory is read-only → abort with clear message

package/skills/brace/references/brace-workflow.md

@@ -0,0 +1,109 @@
+# BRACE Build Methodology
+
+Content for `goals/build_app.md`. Copied during brace Phase 4.
+
+---
+
+## Goal
+
+Build full-stack applications using AI assistance within the GOTCHA framework.
+BRACE is a 5-step process that ensures apps are production-ready.
+
+| Step | Phase | What You Do |
+|------|-------|-------------|
+| **B** | Brief | Define problem, users, success metrics |
+| **R** | Research | Data schema, integrations map, stack proposal |
+| **A** | Architect | Design structure, validate all connections |
+| **C** | Construct | Build with layered architecture |
+| **E** | Evaluate | Test functionality, error handling |
+
+---
+
+## B — Brief
+
+**Purpose:** Know exactly what you are building before touching code.
+
+1. **What problem does this solve?** — One sentence.
+2. **Who is this for?** — Specific user, not "everyone".
+3. **What does success look like?** — Measurable outcome.
+4. **What are the constraints?** — Budget, time, technical limits.
+
+**Output:** App Brief (problem, user, success criteria, constraints)
+
+---
+
+## R — Research
+
+**Purpose:** Design before building. Define the source of truth.
+
+1. **Data schema** — Tables, fields, relationships
+2. **Integrations map** — External services, auth types, API availability
+3. **Technology stack proposal** — Database, backend, frontend (user approves)
+4. **Edge cases** — Rate limits, auth expiry, timeouts, invalid input
+
+**Output:** Schema, approved stack, integrations checklist, edge cases
+
+---
+
+## A — Architect
+
+**Purpose:** Design structure and validate all connections BEFORE building.
+
+Checklist:
+- [ ] Database connection tested
+- [ ] All API keys verified
+- [ ] OAuth flows working
+- [ ] Environment variables set
+- [ ] Rate limits understood
+
+**Output:** All green. Fix anything that fails before proceeding.
+
+---
+
+## C — Construct
+
+**Purpose:** Build with proper architecture.
+
+Build order:
+1. Database schema first
+2. Backend API routes second
+3. Frontend UI last
+
+Follow GOTCHA separation: frontend (display), backend (logic), database (truth).
+
+**Output:** Working application with functional DB, API, and UI.
+
+---
+
+## E — Evaluate
+
+**Purpose:** Test before shipping.
+
+- **Functional:** All buttons work, data saves/retrieves, navigation works
+- **Integration:** API calls succeed, auth persists, rate limits respected
+- **Edge cases:** Invalid input handled, empty states display, errors show feedback
+- **User acceptance:** Solves the original problem, no major friction
+
+**Output:** Test report (passed, failed, needs fixing)
+
+---
+
+## Anti-Patterns
+
+1. Building before designing — rewrites everything
+2. Skipping connection validation — hours wasted on broken integrations
+3. No data modeling — schema changes cascade into UI rewrites
+4. No testing — ship broken code, lose trust
+5. Hardcoding everything — no flexibility for changes
+
+---
+
+## GOTCHA Layer Mapping
+
+| BRACE Step | GOTCHA Layer |
+|------------|--------------|
+| Brief | Goals (define the process) |
+| Research | Context (reference patterns) |
+| Architect | Args (environment setup) |
+| Construct | Tools (execution) |
+| Evaluate | Orchestration (AI validates) |