obra · lockie · Jun 4, 2026
diff --git a/.eca-plugin/marketplace.json b/.eca-plugin/marketplace.json
@@ -0,0 +1,14 @@
+{
+  "plugins": [
+    {
+      "name": "superpowers",
+      "description": "Agentic development methodology: spec-driven brainstorming, structured planning, subagent-driven development, TDD, and systematic debugging",
+      "source": ".eca-plugin/superpowers",
+      "category": "Workflow",
+      "tags": ["methodology", "skill", "planning", "tdd", "debugging", "subagent", "workflow"],
+      "author": "obra",
+      "icon": "⚡",
+      "featured": true
+    }
+  ]
+}
diff --git a/.eca-plugin/superpowers/eca.json b/.eca-plugin/superpowers/eca.json
@@ -0,0 +1,5 @@
+{
+  "skills": [
+    {"path": "skills"}
+  ]
+}
diff --git a/.eca-plugin/superpowers/hooks/hooks.json b/.eca-plugin/superpowers/hooks/hooks.json
@@ -0,0 +1,12 @@
+{
+  "superpowers-bootstrap": {
+    "type": "chatStart",
+    "visible": false,
+    "actions": [
+      {
+        "type": "shell",
+        "file": "${plugin:root}/hooks/session-start"
+      }
+    ]
+  }
+}
diff --git a/.eca-plugin/superpowers/hooks/session-start b/.eca-plugin/superpowers/hooks/session-start
@@ -0,0 +1 @@
+../../../hooks/session-start
diff --git a/.eca-plugin/superpowers/skills b/.eca-plugin/superpowers/skills
@@ -0,0 +1 @@
+../../skills
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ Superpowers is a complete software development methodology for your coding agent
 
 ## Quickstart
 
-Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).
+Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [ECA](#eca), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).
 
 ## How it works
 
@@ -107,6 +107,24 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
 
 - Or search for "superpowers" in the plugin marketplace.
 
+### ECA
+
+- Add Superpowers as a plugin source in `~/.config/eca/config.json` (or `.eca/config.json` for project-local):
+
+  ```json
+  {
+    "plugins": {
+      "superpowers-source": {
+        "source": "https://github.com/obra/superpowers.git"
+      },
+      "install": ["superpowers"]
+    }
+  }
+  ```
+
+- Restart ECA.
+- Detailed docs: [docs/README.eca.md](docs/README.eca.md)
+
 ### Factory Droid
 
 - Register the marketplace:

diff --git a/docs/README.eca.md b/docs/README.eca.md
@@ -0,0 +1,109 @@
+# Superpowers for ECA (Editor Code Assistant)
+
+Complete guide for using Superpowers with [ECA](https://eca.dev).
+
+## Installation
+
+Add Superpowers as a plugin source in your ECA config:
+
+**Global config** (`~/.config/eca/config.json`):
+
+```json
+{
+  "plugins": {
+    "superpowers-source": {
+      "source": "https://github.com/obra/superpowers.git"
+    },
+    "install": ["superpowers"]
+  }
+}
+```
+
+**Project-local config** (`.eca/config.json`):
+
+```json
+{
+  "plugins": {
+    "superpowers-source": {
+      "source": "https://github.com/obra/superpowers.git"
+    },
+    "install": ["superpowers"]
+  }
+}
+```
+
+ECA's runtime plugin loader matches install entries against marketplace entries by exact name. The plugin marketplace entry is named `superpowers`, so the install list must say `"superpowers"` — not `"superpowers@source-name"`. The `@source` suffix is only parsed by the `/plugin-install` command, not by the loader that resolves plugins on session start.
+
+Restart ECA for the plugin to take effect.
+
+Verify by sending:
+
+> Tell me about your superpowers
+
+### Updating
+
+ECA re-resolves plugin sources on startup and periodically (approximately hourly). To force an update, restart ECA or clear the plugin cache at `~/.eca/cache/plugins/`.
+
+To pin a specific version, use a branch or tag in the source URL:
+
+```json
+{
+  "plugins": {
+    "superpowers-source": {
+      "source": "https://github.com/obra/superpowers.git#v5.1.0"
+    },
+    "install": ["superpowers"]
+  }
+}
+```
+
+## How It Works
+
+The plugin provides three things:
+
+1. **Skills** — All Superpowers skills are registered under the `superpowers:` namespace. ECA discovers them via the plugin's `skills/` directory (symlinked to the project's `skills/` root).
+2. **Bootstrap injection** — A `chatStart` hook runs the `session-start` script, which injects the `using-superpowers` skill content as additional context at the start of every chat.
+3. **Tool mapping** — The `using-superpowers` skill references `references/eca-tools.md` for ECA-specific tool name equivalents.
+
+### Skill Namespacing
+
+ECA plugins expose skills under a `<plugin-name>:<name>` namespace. Superpowers skills are accessed as:
+
+- `superpowers:brainstorming`
+- `superpowers:test-driven-development`
+- `superpowers:systematic-debugging`
+- `superpowers:using-superpowers`
+- etc.
+
+When the plugin name matches the skill name (e.g., `superpowers:superpowers`), the prefix is dropped — so `superpowers:superpowers` is just `/superpowers`.
+
+## Usage
+
+Skills auto-trigger based on context — the bootstrap injection teaches the agent to check for relevant skills before every response. You don't need to do anything special.
+
+To manually invoke a skill:
+
+```
+Load the superpowers:brainstorming skill
+```
+
+## Troubleshooting
+
+### Plugin not loading
+
+1. Check that your `config.json` has the correct `source` URL
+2. Verify the git repo is accessible: `git ls-remote https://github.com/obra/superpowers.git`
+3. Check ECA logs for plugin resolution errors
+
+### Skills not found
+
+1. Use `/plugins` to verify `superpowers` appears in the installed list
+2. Check that the plugin's `skills/` symlink resolves correctly
+3. Each skill needs a `SKILL.md` file with valid YAML frontmatter (`name` and `description`)
+
+### Bootstrap not appearing
+
+1. Verify the `chatStart` hook is registered: check `.eca-plugin/superpowers/hooks/hooks.json`
+2. The hook script uses `${plugin:root}` to resolve its path — this is ECA's dynamic interpolation that expands to the absolute plugin directory at load time
+3. The hook runs `hooks/session-start` which must be executable
+4. Check ECA logs for hook execution errors
diff --git a/hooks/session-start b/hooks/session-start
@@ -42,7 +42,7 @@ elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
   # Claude Code sets CLAUDE_PLUGIN_ROOT without COPILOT_CLI
   printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$session_context" | cat
 else
-  # Copilot CLI (sets COPILOT_CLI=1) or unknown platform — SDK standard format
+  # Copilot CLI (sets COPILOT_CLI=1), ECA (no harness env vars), or unknown platform — SDK standard format
   printf '{\n  "additionalContext": "%s"\n}\n' "$session_context" | cat
 fi
 

diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md
@@ -37,11 +37,13 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
 
 **In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
 
+**In ECA:** Use the `eca__skill` tool. ECA discovers skills from installed plugins and presents name+description metadata. Invoke `eca__skill` with the skill name to load the full content.
+
 **In other environments:** Check your platform's documentation for how skills are loaded.
 
 ## Platform Adaptation
 
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [eca-tools.md](references/eca-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
 
 # Using Skills
 

diff --git a/skills/using-superpowers/references/eca-tools.md b/skills/using-superpowers/references/eca-tools.md
@@ -0,0 +1,38 @@
+# ECA Tool Mapping
+
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
+
+| Skill references | ECA equivalent |
+|-----------------|----------------|
+| `Read` (file reading) | `eca__read_file` |
+| `Write` (file creation) | `eca__write_file` |
+| `Edit` (file editing) | `eca__edit_file` |
+| `Bash` (run commands) | `eca__shell_command` |
+| `Grep` (search file content) | `eca__grep` |
+| `Glob` / `LS` (list directory) | `eca__directory_tree` |
+| `TodoWrite` (task tracking) | `eca__task` |
+| `Skill` tool (invoke a skill) | `eca__skill` |
+| `Task` tool (dispatch subagent) | `eca__spawn_agent` |
+
+## Subagent support
+
+ECA supports subagents via the `eca__spawn_agent` tool. The `code` agent is the primary implementation agent, `explorer` is for codebase exploration, and `general` handles complex multi-step tasks.
+
+When a skill says to dispatch a named agent type, use `eca__spawn_agent` with the appropriate agent and a detailed task prompt:
+
+| Skill instruction | ECA equivalent |
+|-------------------|----------------|
+| `Task tool (superpowers:implementer)` | `eca__spawn_agent(agent: "code", task: "<filled implementer-prompt.md>")` |
+| `Task tool (superpowers:spec-reviewer)` | `eca__spawn_agent(agent: "general", task: "<filled spec-reviewer-prompt.md>")` |
+| `Task tool (superpowers:code-reviewer)` | `eca__spawn_agent(agent: "general", task: "<filled code-reviewer.md>")` |
+| `Task tool (superpowers:code-quality-reviewer)` | `eca__spawn_agent(agent: "general", task: "<filled code-quality-reviewer-prompt.md>")` |
+| `Task tool (general-purpose)` with inline prompt | `eca__spawn_agent(agent: "general", task: "<inline prompt>")` |
+| `Task tool (explorer)` | `eca__spawn_agent(agent: "explorer", task: "<exploration task>")` |
+
+### Prompt filling
+
+Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders and pass the complete prompt as the task to `eca__spawn_agent`.
+
+### Parallel dispatch
+
+ECA supports parallel subagent dispatch. When a skill asks you to dispatch multiple independent subagent tasks in parallel, spawn all of them together. Keep dependent tasks sequential, but do not serialize independent subagent tasks.