@complexthings/superpowers-agent 8.1.0

package/skills/problem-solving/simplification-cascades/skill.json

@@ -0,0 +1,9 @@
+{
+    "version": "1.1.0",
+    "name": "superpowers:problem-solving/simplification-cascades",
+    "title": "Simplification Cascades",
+    "aliases": [
+        "simplification-cascades",
+        "problem-solving/simplification-cascades"
+    ]
+}

package/skills/problem-solving/when-stuck/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: when-stuck
+description: Dispatch to the right problem-solving technique based on how you're stuck. Use this skill whenever you hit a wall — code behaving wrong, complexity spiraling, can't find a good approach, assumptions feel forced, unclear how it will scale, or you need to pick the right debugging technique before diving in. Use it proactively before major architecture decisions or when a solution feels like it's fighting you.
+metadata:
+  version: "2.0.0"
+---
+
+# When Stuck — Problem-Solving Dispatch
+
+## Core Principle
+
+Different stuck-types need different techniques. Picking the wrong technique wastes time. This skill helps you identify the right one in under a minute.
+
+**Match symptom → technique, then load and follow that skill.**
+
+## Stuck-Type → Technique
+
+| How You're Stuck | Technique to Use |
+|------------------|-----------------|
+| **Complexity spiraling** — Same thing implemented 5+ ways, growing special cases, each fix reveals a new problem | `simplification-cascades` |
+| **Need innovation** — Conventional solutions feel inadequate, stuck inside one way of thinking, need breakthrough | `collision-zone-thinking` |
+| **Recurring patterns** — Same issue across different domains, reinventing wheels, déjà vu in problem-solving | `meta-pattern-recognition` |
+| **Forced by assumptions** — "Must be done this way," solution fights the system, can't question the premise | `inversion-exercise` |
+| **Scale uncertainty** — Unsure it'll hold at production, edge cases unclear, architecture decisions without load data | `scale-game` |
+| **Code broken** — Wrong behavior, test failing, unexpected output, bug with unknown root cause | `systematic-debugging` |
+| **Symptom clear, cause hidden** — Error is deep in the call chain, fix locations but not the origin | `root-cause-tracing` |
+| **Multiple independent problems** — Separate failing tests, parallel research questions, independent subsystems | `dispatching-parallel-agents` |
+| **Starting fresh, scope unclear** — New feature, unclear requirements, don't know what to build | `brainstorming` |
+| **Have a plan, need execution** — Know what to build, complex multi-step implementation ahead | `writing-plans` |
+
+## How to Identify Your Stuck-Type
+
+If the symptom isn't obvious, ask these questions:
+
+1. **Is something broken?** → `systematic-debugging` (always start here for bugs)
+2. **Is there too much code doing similar things?** → `simplification-cascades`
+3. **Does the solution feel forced or fight the codebase?** → `inversion-exercise`
+4. **Does nothing in this domain work?** → `collision-zone-thinking` (leave the domain)
+5. **Have I seen this shape before in other contexts?** → `meta-pattern-recognition`
+6. **Do I not know if it'll hold under load?** → `scale-game`
+7. **Is the problem actually several independent things?** → `dispatching-parallel-agents`
+
+## Proactive Use (Not Just When Stuck)
+
+Some techniques should be used *before* you're stuck:
+
+- **Before major architecture decisions** → `inversion-exercise` (pre-mortem: "how would this fail?")
+- **Before implementing a complex feature** → `brainstorming` then `writing-plans`
+- **Before committing to a design at scale** → `scale-game`
+- **When a config file or handler list keeps growing** → `simplification-cascades`
+
+## Combining Techniques
+
+Some problems need more than one:
+
+| Combination | When to Use |
+|-------------|-------------|
+| `systematic-debugging` → `root-cause-tracing` | Bug found, but fix location is far from origin |
+| `simplification-cascades` + `meta-pattern-recognition` | Find the recurring pattern, then collapse all instances |
+| `collision-zone-thinking` + `inversion-exercise` | Force a new metaphor, then stress-test its assumptions |
+| `scale-game` + `simplification-cascades` | Extremes reveal what to eliminate |
+| `inversion-exercise` + `scale-game` | "How does this fail?" × "At what scale?" |
+
+## If Still Stuck After First Technique
+
+1. Try a different technique from the table — wrong diagnosis is common
+2. Combine two techniques (see above)
+3. If 3+ fixes have failed for a bug → this is an architectural problem, not a debugging problem. Use `inversion-exercise` to question the design.
+4. Step back: is the problem statement itself wrong? → `brainstorming`

package/skills/problem-solving/when-stuck/skill.json

@@ -0,0 +1,9 @@
+{
+    "version": "1.1.0",
+    "name": "superpowers:problem-solving/when-stuck",
+    "title": "When Stuck - Problem-Solving Dispatch",
+    "aliases": [
+        "when-stuck",
+        "problem-solving/when-stuck"
+    ]
+}

package/skills/research/ABOUT.md

@@ -0,0 +1,20 @@
+# Research Skills - Attribution
+
+This skill was derived from agent patterns in the [Amplifier](https://github.com/microsoft/amplifier) project.
+
+**Source Repository:**
+- Name: Amplifier
+- URL: https://github.com/microsoft/amplifier
+- Commit: 2adb63f858e7d760e188197c8e8d4c1ef721e2a6
+- Date: 2025-10-10
+
+## Skills Derived from Amplifier Agents
+
+**From knowledge-archaeologist agent:**
+- tracing-knowledge-lineages - Understanding how ideas evolved over time to find old solutions for new problems and avoid repeating past failures
+
+## What Was Adapted
+
+The knowledge-archaeologist agent excels at temporal analysis of knowledge evolution, paradigm shift documentation, and preserving the "fossil record" of ideas. This skill extracts the core research techniques for understanding why current approaches exist before proposing changes.
+
+Adapted with practical search strategies (decision records, git archaeology, conversation history) and scoped for mature codebases (explicitly notes to skip for greenfield projects).

package/skills/research/tracing-knowledge-lineages/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: tracing-knowledge-lineages
+description: "Trace the historical lineage of technical ideas, patterns, and architectures to rediscover proven solutions, understand WHY current approaches exist, and avoid repeating failures. Use when you encounter 'why do we do it this way?', 'is this a new problem?', 'what has been tried before?', 'has this pattern emerged before?', or when designing systems that resemble something from the past."
+metadata:
+  category: research
+  version: 1.2.0
+---
+
+# Tracing Knowledge Lineages
+
+## Why This Matters
+
+Every technical decision carries invisible weight from the past. When you skip lineage tracing:
+
+- You reinvent failed approaches because you don't know they failed
+- You miss proven patterns that already solved your exact problem
+- You don't understand WHY the current approach exists, so you can't safely deviate from it
+- You create architecture that repeats historical mistakes your predecessors already paid for
+
+The goal isn't to be constrained by history — it's to be *informed* by it. Knowing the lineage lets you deviate deliberately rather than ignorantly.
+
+## When to Trace Lineages
+
+**Always trace when:**
+- You're designing something and someone says "isn't this like X?"
+- You're questioning why something is done a certain way
+- You're proposing to remove or replace an established pattern
+- You're encountering a problem that "feels old"
+- You're evaluating a technology that claims to be new
+
+**Quick trace (5 minutes):** Is this pattern familiar? → Search for historical names → Find 2–3 examples → Note outcomes
+
+**Deep trace (30+ minutes):** Before architectural decisions, major refactors, or when the quick trace surfaces surprising history
+
+---
+
+## The Four Core Techniques
+
+### 1. Decision Archaeology
+
+Excavate the reasoning behind existing choices — not just what was decided, but why, and what alternatives were rejected.
+
+**Sources to mine:**
+- `git log --all --grep="why\|decision\|chose\|considered\|rejected"` — look for commit messages explaining reasoning
+- Architecture Decision Records (ADRs), RFCs, and design docs in `/docs`, `/adr`, `/rfcs`
+- Ticket trackers (JIRA, Linear, GitHub Issues) — search for the feature name + "alternative" or "rejected"
+- Team Slack/Discord history — search around the dates of significant commits
+- PR descriptions and review comments: `git log --merges --format="%H %s" | head -50`, then check PRs
+
+**What to capture:**
+- The alternatives that were *considered but rejected* — these are as valuable as what was chosen
+- The constraints that shaped the decision (team size, deadline, scale, tooling available then)
+- Whether those constraints still apply today
+
+**Probe questions:**
+> "What problem was this solving when it was introduced?"
+> "What was the runner-up solution, and why was it rejected?"
+> "What has changed since this decision was made?"
+
+---
+
+### 2. Failed Attempt Analysis
+
+Failures are the most valuable and most hidden part of technical history. They rarely get documented, but they repeat.
+
+**Finding hidden failures:**
+- Reverted commits: `git log --all --diff-filter=R` or search for "revert" in commit history
+- Short-lived branches: `git branch -r | xargs -I{} git log --oneline -1 {}` — branches that were created and abandoned
+- Half-migrated code: look for dual implementations (old + new living side by side)
+- "TODO: remove this once X" comments that were never removed
+- Changelog entries that disappeared in later versions
+
+**The failure taxonomy:**
+| Type | Signal | What to learn |
+|------|--------|---------------|
+| Performance failure | Reverted optimization, "too slow" in commits | What the scale thresholds were |
+| Complexity failure | "Simplified", "removed abstraction" | Where the abstraction broke down |
+| Adoption failure | Feature removed, flag disabled | What made it hard to use |
+| Timing failure | "Premature", "not ready" | What prerequisites were missing |
+
+---
+
+### 3. Revival Detection
+
+Old patterns resurface under new names. Recognizing revivals lets you access 30+ years of operational experience immediately.
+
+**Technically accurate revival lineages:**
+
+| Modern Pattern | Historical Ancestor | What the revival added |
+|---------------|--------------------|-----------------------|
+| Serverless Functions | Time-sharing systems (1960s) + Unix daemons | Elastic billing, managed infra |
+| GraphQL | SGML/XQL query languages + SOAP/WSDL | Typed schema, client-driven queries |
+| NoSQL Document Stores | IMS hierarchical DB + CODASYL network DBs (1970s) | Horizontal scale, flexible schema |
+| Microservices | CORBA/SOA (1990s–2000s) | Lightweight protocols, containers |
+| Edge Computing | CDN + Akamai ESI (early 2000s) | Full compute, not just caching |
+| Server Components (React) | Server-side rendering + JSP/PHP | Component model + streaming |
+| Event Sourcing | Append-only ledgers + audit logs | Projections, temporal queries |
+| Infrastructure as Code | LISP machine system images + Puppet/Chef | Declarative, version-controlled |
+
+**Revival research steps:**
+1. Name the modern pattern precisely
+2. Ask: "what did this replace, and what did the replacement itself replace?"
+3. Search: `[pattern name] history site:lobste.rs OR site:news.ycombinator.com`
+4. Look for talks titled "X considered harmful" or "the return of Y"
+
+---
+
+### 4. Paradigm Shift Mapping
+
+Understand what changed — constraints, tooling, scale, understanding — that made old approaches viable again or newly obsolete.
+
+**The shift template:**
+```
+Old constraint: [what made X unworkable before]
+New condition: [what changed]
+Therefore: [why X is viable/necessary now]
+```
+
+**Example:**
+```
+Old constraint: RAM was expensive; storing state in memory meant high cost
+New condition: RAM is effectively free at the scale most apps run
+Therefore: In-memory state machines (XState, Zustand) beat complex DB state management
+```
+
+**Constraint categories to check:**
+- **Cost**: storage, compute, bandwidth costs have changed dramatically
+- **Speed**: network latency, CPU speed, disk I/O profiles
+- **Scale**: how many users, requests, data volume
+- **Tooling**: what primitives are now available (containers, managed databases, type systems)
+- **Team**: what skills are now common vs. rare
+
+---
+
+## Search Strategy
+
+### Code & Version Control
+```bash
+# Commits explaining reasoning
+git log --all --grep="because\|reason\|trade-off\|instead of\|considered"
+
+# Reverted changes (hidden failures)
+git log --all --grep="[Rr]evert" --oneline
+
+# Find old implementations
+git log --all --full-history -- "**/old-*" "**/deprecated-*" "**/legacy-*"
+
+# When was this pattern introduced?
+git log -S "pattern_name" --oneline
+```
+
+### Documentation & Issues
+- GitHub/GitLab: search `repo:org/name "why" OR "reason" OR "considered"`  
+- JIRA/Linear: filter by date range around when the pattern was introduced  
+- Confluence/Notion: search for the component name + "decision" or "RFC"
+
+### Web Archaeology
+- `site:news.ycombinator.com "[technology name]"` — HN discussions often contain expert history
+- `site:lobste.rs "[technology name]"` — deeper technical discussions
+- ACM Digital Library / IEEE Xplore for academic lineage
+- The Wayback Machine for documentation of dead projects
+- Wikipedia revision history for contested technical decisions
+
+---
+
+## Recognizing Lineage Signals
+
+**In code:**
+- Comments starting with "NB:", "NOTE:", "FIXME:", "HACK:", "WARNING:" — often explain constraints
+- Unusually defensive code in an otherwise simple module
+- Abstraction layers that wrap a single thing
+- Feature flags that have been "temporary" for years
+
+**In conversations:**
+- "We tried that before" — ALWAYS follow up: "What happened?"
+- "That won't work here" — ask for the specific failure scenario
+- "We have reasons" — that phrase usually means there's archaeology to do
+
+**In architecture:**
+- Two implementations of the same thing existing simultaneously
+- Naming like `*_v2`, `*_new`, `*_refactored`
+- Explicit "Do Not Use" warnings pointing to another implementation
+
+---
+
+## Synthesizing Your Findings
+
+A lineage trace is only valuable if it produces actionable insight. Structure your output:
+
+```markdown
+## Lineage: [Pattern/Decision Name]
+
+**What it is now:** [one sentence]
+
+**Historical origin:** [oldest known ancestor + approximate era]
+
+**Key evolution steps:**
+1. [era] — [what existed and what problem it solved]
+2. [era] — [what changed and why]
+3. [current] — [how we got here]
+
+**Failed attempts along the way:**
+- [attempt] failed because [reason] — still relevant because [implication]
+
+**What the history tells us:**
+- The core problem being solved is [X], not [Y]
+- This approach works when [conditions]; breaks when [other conditions]
+- The constraint that shaped this was [Z] — that constraint [still applies / no longer applies]
+
+**Implication for current work:**
+[One concrete decision or caution derived from the lineage]
+```
+
+---
+
+## Informed Deviation: Using History to Break from It
+
+Knowing the lineage doesn't mean being constrained by it — it means you can break from it *deliberately*. Before deviating from an established pattern:
+
+1. **Name the constraint that shaped the original decision**
+   - "This was built when we had X constraint"
+2. **Verify whether that constraint still applies**
+   - "That constraint no longer applies because Y"
+3. **Check if the deviation was tried before**
+   - "This exact deviation was tried in [branch/ticket/year] and failed because Z"
+4. **State your deviation explicitly**
+   - "We are intentionally deviating from the historical pattern because [conditions changed]"
+
+The trap to avoid: "We don't need to do it that way anymore" without knowing *why* it was done that way in the first place.
+
+---
+
+## Anti-Patterns
+
+| Anti-pattern | What it looks like | The fix |
+|---|---|---|
+| **Present bias** | "That's old, we don't need to learn from it" | Old failures are especially relevant — same problems, different names |
+| **Success bias** | Only tracing the winning path | Failed attempts teach more than successes |
+| **Shallow attribution** | "This is like X" without understanding WHY | Trace through to first principles |
+| **Archive paralysis** | Spending days on lineage for a one-day task | Time-box: quick trace = 5 min, deep trace = 30 min |
+| **Context stripping** | "They tried X and it failed" without the why | Always capture the conditions under which it failed |

package/skills/research/tracing-knowledge-lineages/skill.json

@@ -0,0 +1,9 @@
+{
+    "version": "1.1.0",
+    "name": "superpowers:research/tracing-knowledge-lineages",
+    "title": "Tracing Knowledge Lineages",
+    "aliases": [
+        "tracing-knowledge-lineages",
+        "research/tracing-knowledge-lineages"
+    ]
+}

package/skills/setup-skills/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: setup-skills
+description: Run superpowers-agent setup-skills to initialize the skills infrastructure for a project. Use whenever starting a new project with AI agents, when skills symlinks are missing, when AGENTS.md lacks skills configuration, when a user asks to "set up skills", "install skills", "bootstrap skills", or "initialize superpowers". Also use when skills aren't being discovered or when you're about to create project-specific skills and the infrastructure doesn't exist yet. If there's any chance the project hasn't been set up for skills yet, run this skill.
+---
+
+# Setup Skills
+
+This skill does one thing: run `superpowers-agent setup-skills` and follow the output it gives you exactly.
+
+The command sets up the full skills infrastructure for a project — creating `.agents/`, symlinks for each AI platform, and updating `AGENTS.md` — and its output tells you everything that happened and what to do next.
+
+## Run the Command
+
+From the project root:
+
+```bash
+superpowers-agent setup-skills
+```
+
+## Follow the Output Exactly
+
+The command output is authoritative. Read it, act on it, and do not skip any steps it prescribes. It adapts to the platforms detected in your project and tells you precisely what was created, updated, or skipped.
+
+If the command prints follow-up instructions, complete them before continuing with your task.
+
+## If superpowers-agent Is Not Found
+
+Install it first, then rerun:
+
+```bash
+@npm install -g @complexthings/superpowers-agent
+superpowers-agent setup-skills
+```
+
+## After Setup
+
+Project-specific skills belong in `.agents/skills/`. All AI agents working in the project discover them automatically via the symlinks the command created.
+
+To verify:
+```bash
+superpowers-agent find-skills
+```
+
+## Related Skills
+
+- **finding-skills** — Discover available skills after setup
+- **using-superpowers** — How the full skills system works