@slamb2k/mad-skills 2.0.7 → 2.0.9

package/skills/ship/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: ship
-description: >
-  Ship changes through the full PR lifecycle. Use after completing feature work
-  to commit, push, create PR, wait for checks, and merge. Handles the entire
-  workflow: syncs with main, creates feature branch if needed, groups commits
-  logically with semantic messages, creates detailed PR, monitors CI, fixes
-  issues, squash merges, and cleans up. Invoke when work is ready to ship.
+description: "Ship changes through the full PR lifecycle. Use after completing feature work to commit, push, create PR, wait for checks, and merge. Handles the entire workflow: syncs with main, creates feature branch if needed, groups commits logically with semantic messages, creates detailed PR, monitors CI, fixes issues, squash merges, and cleans up. Invoke when work is ready to ship."
+argument-hint: --pr-only, --no-squash, --keep-branch (optional flags)
+allowed-tools: Bash, Read, Glob, Grep, Skill
 ---
 
 # Ship - Full PR Lifecycle
@@ -35,21 +32,195 @@ Taglines:
 - 📬 Another one for the merge queue!
 - 🟢 LGTM — Let's Get This Merged!
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Ship changes through the complete PR lifecycle. Every stage runs in a subagent
+to isolate context from the primary conversation. Prompts for each stage are
+in `references/stage-prompts.md`.
+
+## Flags
+
+Parse optional flags from the request:
+- `--pr-only`: Stop after creating the PR
+- `--no-squash`: Use regular merge instead of squash
+- `--keep-branch`: Don't delete the source branch after merge
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| git | cli | `git --version` | yes | stop | Install from https://git-scm.com |
+| gh | cli | `gh --version` | yes | url | https://cli.github.com |
+| ship-analyzer | agent | `~/.claude/agents/ship-analyzer.md` | no | fallback | Uses general-purpose agent |
+
+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
+
+Read `default_branch` and `remote` from Stage 1's SYNC_REPORT. These are
+substituted into all stage prompts as `{REMOTE}` and `{DEFAULT_BRANCH}`.
+
+### Platform Detection
+
+After sync, detect the hosting platform from the remote URL:
+
+```bash
+REMOTE_URL=$(git remote get-url {REMOTE} 2>/dev/null)
+if echo "$REMOTE_URL" | grep -qiE 'dev\.azure\.com|visualstudio\.com'; then
+  PLATFORM="azdo"
+elif echo "$REMOTE_URL" | grep -qi 'github\.com'; then
+  PLATFORM="github"
+else
+  PLATFORM="github"   # default fallback
+fi
+```
+
+Pass `{PLATFORM}` into all stage prompts. Each stage uses the appropriate
+CLI tool: `gh` for GitHub, `az repos`/`az pipelines` for Azure DevOps.
+
+> **Azure DevOps prerequisite:** The `az devops` extension must be installed
+> and configured (`az devops configure --defaults organization=... project=...`).
+> If `az repos` commands fail, report the setup requirement to the user.
+
+---
+
+## Stage 1: Sync
+
+Launch **Bash subagent** (haiku — simple git commands):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Sync with default branch",
+  prompt: "Follow ~/.claude/skills/sync/SKILL.md subagent prompt. Return SYNC_REPORT."
+)
+```
+
+Parse SYNC_REPORT. Extract `remote` and `default_branch`. Abort if sync failed.
+
+---
+
+## Stage 2: Commit, Push & Create PR
+
+This stage needs to **read and understand code** to write good commit messages
+and PR descriptions. Use a code-aware subagent.
+
+Launch **ship-analyzer subagent** (reads diffs + source files):
+
+```
+Task(
+  subagent_type: "ship-analyzer",
+  description: "Analyze, commit, push, and create PR",
+  prompt: <read from references/stage-prompts.md#stage-2>
+)
+```
+
+> **Fallback:** If `ship-analyzer` is not available, use `subagent_type: "general-purpose"`.
+
+Substitute `{USER_INTENT}`, `{FILES_TO_INCLUDE}`, `{FILES_TO_EXCLUDE}`,
+`{REMOTE}`, `{DEFAULT_BRANCH}`, `{PLATFORM}` into the prompt.
+
+Parse SHIP_REPORT. Abort if failed.
+
+**Rollback:** If push succeeds but PR creation fails, report the error and
+suggest the manual PR creation command. Do NOT revert the push.
+- GitHub: `gh pr create --head {branch}`
+- Azure DevOps: `az repos pr create --source-branch {branch} --target-branch {DEFAULT_BRANCH}`
 
-## Subagent Architecture
+**If `--pr-only` flag: Stop here and report PR URL to user.**
 
-All work runs in subagents to keep the primary conversation context clean:
+---
+
+## Stage 3: Wait for CI
+
+Launch **Bash subagent** in the **background** (haiku — just polling):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  run_in_background: true,
+  description: "Monitor CI checks",
+  prompt: <read from references/stage-prompts.md#stage-3>
+)
+```
+
+Substitute `{PR_NUMBER}` into the prompt.
+
+While CI runs in the background, briefly inform the user:
+```
+CI running for PR #{pr_number}... waiting for checks.
+```
+
+When the background task completes, read the output file and parse CHECKS_REPORT.
+
+---
+
+## Stage 4: Fix Failing Checks (if needed)
+
+If CHECKS_REPORT shows failures, launch **general-purpose subagent**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Fix CI failures",
+  prompt: <read from references/stage-prompts.md#stage-4>
+)
+```
+
+Substitute `{PR_NUMBER}`, `{BRANCH}`, `{FAILING_CHECKS}` into the prompt.
 
-| Stage | Agent Type | Model | Purpose |
-|-------|-----------|-------|---------|
-| Sync | Bash | haiku | Git sync (cheap, fast) |
-| Ship | ship-analyzer | sonnet | Analyze code, commit, push, create PR |
-| CI | Bash (background) | haiku | Poll checks without blocking |
-| Fix CI | general-purpose | default | Read code, fix failures |
-| Land | Bash | haiku | Merge + final sync |
+If fixed, return to Stage 3 (run CI watch again).
+If unable to fix after 2 attempts, report to user and stop.
 
-The `ship-analyzer` custom agent (`~/.claude/agents/ship-analyzer.md`) reads
-source files to write meaningful commit messages and PR descriptions.
-Falls back to `general-purpose` if not installed.
+---
+
+## Stage 5: Merge & Final Sync
+
+Launch **Bash subagent** (haiku — simple git + platform CLI commands):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Merge PR and sync",
+  prompt: <read from references/stage-prompts.md#stage-5>
+)
+```
+
+Substitute `{PR_NUMBER}`, `{REMOTE}`, `{DEFAULT_BRANCH}`, merge/branch flags.
+
+Parse LAND_REPORT.
+
+---
+
+## Final Report to User
+
+Compile all stage reports into a summary:
+
+```
+Ship complete
+
+  Branch:  {branch}
+  PR:      {pr_url}
+  Merged:  {merge_commit} ({merge_type})
+
+  Commits:
+  {list of commit messages, indented}
+
+  Files:   {count} files changed ({diff_summary})
+```
 
+If any stage failed, report the failure point and suggested resolution.

package/skills/speccy/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: speccy
+description: Deep-dive interview skill for creating comprehensive specifications. Reviews existing code and docs, then interviews the user through multiple rounds of targeted questions covering technical implementation, UI/UX, concerns, and tradeoffs. Produces a structured spec via create-specification. Use when starting a new feature, system, or major change that needs a spec.
+argument-hint: Goal, feature, or high-level description to specify
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# Speccy - Interview-Driven Specification Builder
+
+When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character. The first line of the art has 4 leading spaces — you MUST preserve them.
+
+```
+{tagline}
+
+⠀   ██╗███████╗██████╗ ███████╗ ██████╗ ██████╗██╗   ██╗
+   ██╔╝██╔════╝██╔══██╗██╔════╝██╔════╝██╔════╝╚██╗ ██╔╝
+  ██╔╝ ███████╗██████╔╝█████╗  ██║     ██║      ╚████╔╝
+ ██╔╝  ╚════██║██╔═══╝ ██╔══╝  ██║     ██║       ╚██╔╝
+██╔╝   ███████║██║     ███████╗╚██████╗╚██████╗   ██║
+╚═╝    ╚══════╝╚═╝     ╚══════╝ ╚═════╝ ╚═════╝   ╚═╝
+```
+
+Taglines:
+- 🔍 Tell me everything...
+- 🧠 Let's think this through!
+- 📋 Spec it before you wreck it!
+- 🎤 Interview mode: ACTIVATED
+- 💡 Great specs start with great questions!
+- 🏗️ Measure twice, code once!
+- 📝 No assumption left behind!
+- 🎯 Precision engineering starts here!
+
+---
+
+Interview the user through multiple rounds of targeted questions to build
+a comprehensive specification. Then hand off to the `create-specification`
+skill to produce the final structured spec document.
+
+Interview prompts and question guidelines: `references/interview-guide.md`
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| create-specification | skill | `~/.claude/skills/create-specification/SKILL.md` or `~/.agents/skills/create-specification/SKILL.md` | yes | ask | This skill is needed to format the final spec. Install with: `npx skills add slamb2k/mad-skills --skill create-specification` |
+
+For each row, in order:
+1. Test file existence (check both paths for symlinked skills)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **ask**: Notify user the skill is missing, offer to install it. If they
+     decline, halt execution — the final spec cannot be produced without it.
+4. After all checks: proceed to context gathering
+
+---
+
+## Stage 1: Context Gathering
+
+Before asking any questions, build a thorough understanding of the project:
+
+1. **Capture GOAL** — the user's argument describing what needs to be specified
+2. **Scan the project**:
+   - Read `CLAUDE.md` if present (project conventions, structure, domain)
+   - Read goal/spec manifests: `goals/manifest.md`, `spec/` directory
+   - Scan existing specs and design docs for context
+   - Read relevant source code that relates to the GOAL
+   - Check memory for prior decisions or open questions related to the GOAL
+3. **Identify knowledge gaps** — what must you learn from the user to write
+   a complete, unambiguous specification?
+
+Group gaps into interview categories:
+- **Architecture & Technical Design** — stack, patterns, data flow, integrations
+- **Requirements & Scope** — what's in, what's out, must-haves vs nice-to-haves
+- **UI & UX** — user flows, interaction patterns, accessibility, responsive
+- **Security & Auth** — authentication, authorization, data protection
+- **Infrastructure & Deployment** — hosting, CI/CD, environments, IaC
+- **Data & Storage** — schemas, persistence, migrations, caching
+- **Testing & Quality** — test strategy, coverage, acceptance criteria
+- **Concerns & Tradeoffs** — known risks, alternatives considered, constraints
+
+---
+
+## Stage 2: Interview Rounds
+
+Conduct multiple rounds of questions using `AskUserQuestion`. Continue until
+all knowledge gaps are resolved.
+
+### Question Rules
+
+1. **4 questions per round maximum** (AskUserQuestion limit)
+2. **Non-obvious questions only** — don't ask things you can determine from
+   reading the code or docs. The user's time is valuable.
+3. **Recommendations** — where you have an informed opinion based on the
+   codebase, project conventions, or industry best practice, mark one option
+   as recommended by listing it first and appending `(Recommended)` to its label.
+   At least one question per round should have a recommendation where possible.
+4. **Concise options** — 2-4 options per question, each with a clear
+   description of implications and tradeoffs
+5. **Progressive depth** — start with high-level architecture and scope,
+   then drill into implementation details in later rounds
+6. **Build on answers** — use previous round answers to inform next questions.
+   Don't re-ask decided topics.
+7. **Track decisions** — maintain a running list of all decisions made.
+   Present this list at the start of each round so the user can see progress.
+
+### Round Structure
+
+Each round follows this pattern:
+
+1. **Progress update** — brief summary of decisions made so far (after round 1)
+2. **Category label** — which interview category this round covers
+3. **Questions** — 3-4 targeted questions via AskUserQuestion
+4. **Evaluate** — after answers, determine if more questions are needed
+
+### Completion Criteria
+
+Stop interviewing when ALL of the following are true:
+- All identified knowledge gaps have been addressed
+- No answer has raised new unresolved questions
+- You have enough information to write every section of the spec template
+- The user has confirmed scope boundaries (what's in and what's out)
+
+When complete, briefly present a **Decision Summary** — a numbered list of
+all decisions made across all rounds — and confirm with the user before
+proceeding to spec generation.
+
+---
+
+## Stage 3: Generate Specification
+
+Once the interview is complete and decisions are confirmed:
+
+1. **Invoke the `create-specification` skill** using the Skill tool:
+   ```
+   Skill(skill: "create-specification")
+   ```
+
+2. **Provide the full context** to the skill as input:
+   - The original GOAL
+   - All decisions from the interview rounds
+   - Any relevant code/architecture context discovered in Stage 1
+   - The spec purpose should match the GOAL description
+
+3. The `create-specification` skill will handle formatting, naming, and
+   saving the spec file according to its own template and conventions.
+
+---
+
+## Output
+
+After the spec is created, report to the user:
+
+```
+Spec complete!
+
+  File:       {spec file path}
+  Sections:   {count of sections written}
+  Decisions:  {count of interview decisions captured}
+  Rounds:     {count of interview rounds conducted}
+  Questions:  {total questions asked}
+```

package/skills/speccy/references/interview-guide.md

@@ -0,0 +1,96 @@
+# Interview Guide
+
+Reference material for conducting effective specification interviews.
+
+---
+
+## Question Categories & Example Topics
+
+### Architecture & Technical Design
+- Compute model (serverless vs hosted vs edge)
+- Frontend framework and rendering strategy
+- API design (REST vs GraphQL, versioning)
+- State management approach
+- Caching strategy
+- Real-time requirements (WebSockets, SSE, polling)
+- Monorepo vs multi-repo structure
+
+### Requirements & Scope
+- Core user stories and acceptance criteria
+- Feature phasing (MVP vs full implementation)
+- Must-have vs nice-to-have features
+- Known limitations or explicit non-goals
+- Backward compatibility requirements
+
+### UI & UX
+- Navigation model (wizard, tabs, SPA routing)
+- Theme and visual design (light/dark, brand)
+- Component library choice
+- Responsive and mobile requirements
+- Accessibility standards (WCAG level)
+- Loading states and error presentation
+- Dashboard and data visualisation approach
+
+### Security & Auth
+- Authentication method (SSO, OAuth, API keys)
+- Authorization model (RBAC, ABAC, per-resource)
+- Data sensitivity and encryption requirements
+- Audit logging needs
+- Session management
+
+### Infrastructure & Deployment
+- Hosting platform (Azure, AWS, GCP, self-hosted)
+- IaC tooling (Bicep, Terraform, Pulumi)
+- CI/CD pipeline design
+- Environment strategy (dev, staging, prod)
+- Monitoring and alerting
+- Cost constraints
+
+### Data & Storage
+- Primary data store (SQL, NoSQL, blob, file)
+- Data retention and lifecycle policies
+- Migration strategy
+- Caching layers
+- Data import/export formats
+
+### Testing & Quality
+- Test framework and tooling
+- Coverage targets
+- Integration and E2E test approach
+- Performance testing requirements
+- Linting and formatting standards
+
+### Concerns & Tradeoffs
+- Known technical risks
+- Alternatives considered and why rejected
+- Performance vs complexity tradeoffs
+- Build vs buy decisions
+- Technical debt acceptance
+
+---
+
+## Anti-Patterns to Avoid
+
+- **Don't ask what you can read** — if the codebase already answers it, don't ask
+- **Don't ask leading questions** — present options neutrally (except recommendations)
+- **Don't ask compound questions** — one decision per question
+- **Don't ask about implementation details too early** — architecture first
+- **Don't assume technology** — let the user confirm even if it seems obvious
+- **Don't skip the "why"** — understanding rationale prevents spec rot
+
+---
+
+## Recommendation Guidelines
+
+When marking an option as `(Recommended)`:
+
+1. **Base it on evidence** — codebase patterns, project conventions, or the
+   specific constraints you've discovered
+2. **Explain why in the description** — the recommendation reason should be
+   clear from the option's description text
+3. **Don't force it** — if you genuinely don't have a strong opinion, don't
+   recommend. Quality over quantity.
+4. **Respect existing choices** — if the project already uses a technology
+   or pattern, recommending consistency is usually right
+5. **Consider the user's context** — team size, timeline, and expertise
+   matter more than theoretical best practice

package/skills/speccy/tests/evals.json

@@ -0,0 +1,34 @@
+[
+  {
+    "name": "speccy-invocation-banner",
+    "prompt": "Run the speccy skill with no arguments",
+    "assertions": [
+      {
+        "type": "contains",
+        "value": "SPECCY"
+      },
+      {
+        "type": "contains",
+        "value": "██"
+      }
+    ]
+  },
+  {
+    "name": "speccy-interview-categories",
+    "prompt": "What question categories does the speccy skill use?",
+    "assertions": [
+      {
+        "type": "contains",
+        "value": "Architecture"
+      },
+      {
+        "type": "contains",
+        "value": "Requirements"
+      },
+      {
+        "type": "contains",
+        "value": "Security"
+      }
+    ]
+  }
+]