@slamb2k/mad-skills 2.0.6 → 2.0.8

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"
+      }
+    ]
+  }
+]

package/skills/sync/SKILL.md

@@ -1,28 +1,25 @@
 ---
 name: sync
-description: >
-  Sync local repository with origin/main. Use before starting new work, after
-  completing a PR, or when needing latest upstream changes. Safely stashes
-  uncommitted changes, fetches and pulls origin/main, restores stash, and cleans
-  up stale local branches (merged or with deleted remotes). Invoke when switching
-  contexts or preparing for new feature work.
+description: Sync local repository with origin/main. Use before starting new work, after completing a PR, or when needing latest upstream changes. Safely stashes uncommitted changes, fetches and pulls origin/main, restores stash, and cleans up stale local branches (merged or with deleted remotes). Invoke when switching contexts or preparing for new feature work.
+argument-hint: --no-stash, --no-cleanup, --no-rebase (optional flags)
+allowed-tools: Bash
 ---
 
 # Sync - Repository Synchronization
 
 When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
-Pick ONE tagline at random — vary your choice each time:
+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:
@@ -35,20 +32,181 @@ Taglines:
 - 🔁 Rebase, merge, rinse, repeat!
 - 🎬 Previously on main...
 
-Follow instructions in: [instructions.md](instructions.md)
-
-## Subagent Architecture
+---
 
-Single **Bash** subagent with **haiku** model. Pure git commands — no code
-analysis needed, so the cheapest/fastest model is used. All git output stays
-in the subagent context; the primary agent only sees the structured SYNC_REPORT.
+Synchronize local repository with the remote default branch using a single
+Bash subagent to isolate all git operations from the primary conversation.
 
 ## Flags
 
-- `--no-stash` — Skip auto-stashing uncommitted changes
-- `--no-cleanup` — Skip deleting stale local branches
-- `--no-rebase` — Use merge instead of rebase on feature branches
+Parse optional flags from the request:
+- `--no-stash`: Don't auto-stash uncommitted changes
+- `--no-cleanup`: Don't delete stale local branches
+- `--no-rebase`: Use merge instead of rebase when on a feature branch
+
+---
+
+## 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 |
+
+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
+
+---
+
+## Pre-flight Detection
+
+Before launching the subagent, detect the remote and default branch:
+
+```
+REMOTE=$(git remote | head -1)   # usually "origin"
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/$REMOTE/HEAD 2>/dev/null | sed 's|.*/||')
+```
+
+Fallback chain if `symbolic-ref` fails:
+1. Check `git show-ref --verify refs/heads/main` → use `main`
+2. Check `git show-ref --verify refs/heads/master` → use `master`
+3. If neither exists, report error and stop
+
+Pass `{REMOTE}` and `{DEFAULT_BRANCH}` into the subagent prompt.
+
+---
+
+## Execution
+
+Launch a **Bash subagent** (haiku — pure git commands, no code analysis needed):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Sync repo with {DEFAULT_BRANCH}",
+  prompt: <see prompt below>
+)
+```
+
+### Subagent Prompt
 
-## Safety
+```
+Synchronize this git repository with {REMOTE}/{DEFAULT_BRANCH}. Execute the
+following steps in order and report results.
+
+Limit SYNC_REPORT to 15 lines maximum.
+
+FLAGS: {flags from request, or "none"}
+
+## Steps
+
+1. **Check state**
+   BRANCH=$(git branch --show-current 2>/dev/null || echo "DETACHED")
+   CHANGES=$(git status --porcelain | head -20)
+   Record: current_branch=$BRANCH, has_changes=(non-empty CHANGES)
+
+   If BRANCH == "DETACHED":
+     Record error: "Detached HEAD — cannot sync. Checkout a branch first."
+     Skip to Output.
+
+2. **Stash changes** (skip if --no-stash or no changes)
+   If has_changes and not --no-stash:
+     git stash push -m "sync-auto-stash-$(date +%Y%m%d-%H%M%S)"
+     Record: stash_created=true
+
+3. **Sync {DEFAULT_BRANCH}**
+   git fetch {REMOTE}
+   If BRANCH != "{DEFAULT_BRANCH}":
+     git checkout {DEFAULT_BRANCH}
+   git pull {REMOTE} {DEFAULT_BRANCH} --ff-only
+   If pull fails (diverged):
+     git pull {REMOTE} {DEFAULT_BRANCH} --rebase
+   Record: main_commit=$(git rev-parse --short HEAD)
+   Record: main_message=$(git log -1 --format=%s)
+
+4. **Return to branch and update** (skip if already on {DEFAULT_BRANCH})
+   If current_branch != "{DEFAULT_BRANCH}":
+     git checkout $BRANCH
+     If --no-rebase:
+       git merge {DEFAULT_BRANCH} --no-edit
+     Else:
+       git rebase {DEFAULT_BRANCH}
+       If rebase fails:
+         git rebase --abort
+         Record: rebase_status="conflict — aborted, branch unchanged"
+
+5. **Restore stash** (if created in step 2)
+   If stash_created:
+     git stash pop
+     If pop fails (conflict):
+       Record: stash="conflict — run 'git stash show' to inspect"
+     Else:
+       Record: stash="restored"
+
+6. **Cleanup branches** (skip if --no-cleanup)
+   git fetch --prune
+
+   # Delete branches whose remote is gone
+   for branch in $(git branch -vv | grep ': gone]' | awk '{print $1}'); do
+     if [ "$branch" != "$BRANCH" ]; then
+       git branch -d "$branch" 2>/dev/null && echo "Deleted: $branch"
+     fi
+   done
+
+   # Delete branches fully merged into {DEFAULT_BRANCH} (except current)
+   for branch in $(git branch --merged {DEFAULT_BRANCH} | grep -v '^\*' | grep -v '{DEFAULT_BRANCH}'); do
+     branch=$(echo "$branch" | xargs)
+     if [ "$branch" != "$BRANCH" ] && [ -n "$branch" ]; then
+       git branch -d "$branch" 2>/dev/null && echo "Deleted: $branch"
+     fi
+   done
+
+   Record: branches_cleaned={list of deleted branches, or "none"}
+
+7. **Final state**
+   echo "Branch: $(git branch --show-current)"
+   echo "HEAD: $(git log -1 --format='%h %s')"
+   echo "Status: $(git status --short | wc -l) modified files"
+
+## Output Format
+
+SYNC_REPORT:
+- status: success|failed
+- remote: {REMOTE}
+- default_branch: {DEFAULT_BRANCH}
+- main_updated_to: {commit} - {message}
+- current_branch: {branch}
+- stash: restored|none|conflict
+- rebase: success|conflict|skipped
+- branches_cleaned: {list or "none"}
+- errors: {any errors encountered}
+```
+
+---
+
+## Report to User
+
+Parse the subagent's SYNC_REPORT and present a clean summary:
+
+```
+Sync complete
+  Main:    {commit} - {message}
+  Branch:  {current_branch}
+  Stash:   {status}
+  Cleaned: {branches or "none"}
+```
 
-Safe by default: detached HEAD, rebase conflicts, and stash conflicts are detected and reported without destructive action.
+If errors occurred, report them clearly with suggested resolution:
+- Detached HEAD → suggest `git checkout <branch>`
+- Rebase conflict → suggest `git rebase {DEFAULT_BRANCH}` manually and resolve
+- Stash conflict → suggest `git stash show` and `git stash pop` manually