[openspec]: feat Pipeline runner for automatic gate/hook execution

.gitignore

@@ -156,3 +156,7 @@ opencode.json
 
 # Codex
 .codex/
+.actrc
+
+# OpenSpec gate results (ephemeral execution state)
+**/.gates/

README.md

@@ -152,6 +152,284 @@ Run this inside each project to regenerate AI guidance and ensure the latest sla
 openspec update
 ```
 
+## Plugins
+
+OpenSpec supports a plugin system for extending lifecycle hooks, gate types, and schemas without modifying core.
+
+### Quick Start
+
+1. Create a plugin directory with a manifest:
+
+```
+openspec/plugins/my-plugin/
+  plugin.yaml
+  hooks/
+    my-hook.md
+```
+
+2. Define `plugin.yaml`:
+
+```yaml
+name: my-plugin
+version: 1.0.0
+description: My custom lifecycle hooks
+openspec: ">=1.2.0"
+
+hooks:
+  archive.post:
+    - id: notify
+      handler:
+        type: command
+        run: "echo 'Archived ${OPENSPEC_CHANGE_NAME}'"
+```
+
+3. Enable in `openspec/config.yaml`:
+
+```yaml
+schema: spec-driven
+plugins:
+  - my-plugin
+```
+
+4. Verify: `openspec plugin list`
+
+### Plugin Manifest (`plugin.yaml`)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Plugin name |
+| `version` | string | Yes | Semver version |
+| `description` | string | No | Brief description |
+| `openspec` | string | No | Compatible OpenSpec version range (e.g., `">=1.2.0"`) |
+| `schemas` | string[] | No | Schema names bundled in `schemas/` subdirectory |
+| `config` | object | No | Config schema (category → field → {type, required, default}) |
+| `hooks` | object | No | Lifecycle hooks by hook point |
+| `gates` | GateDefinition[] | No | Custom gate types for schema `apply.gates` |
+| `skill_overlays` | object | No | Content to inject into generated skills/commands per workflow |
+
+### Hook Points
+
+| Hook Point | When | Use Case |
+|------------|------|----------|
+| `propose.pre` | Before proposal creation | Pre-checks |
+| `propose.post` | After proposal creation | Notifications |
+| `apply.pre` | Before apply phase | Git branch creation, env setup |
+| `apply.post` | After all tasks complete | Cleanup, notifications |
+| `archive.pre` | Before archive operation | Validation, blocking checks |
+| `archive.post` | After archive completes | Obsidian sync, git cleanup |
+
+### Handler Types
+
+Hooks and gates support three handler types:
+
+- **`command`** — Execute a shell command. Exit code 0 = success.
+- **`prompt`** — Output a markdown prompt for the AI agent to execute.
+- **`both`** — Run a command first, then output a prompt with `{{command_output}}`.
+
+```yaml
+hooks:
+  archive.post:
+    # Shell command (deterministic)
+    - id: git-cleanup
+      handler:
+        type: command
+        run: "git branch -d feature/${OPENSPEC_CHANGE_NAME}"
+        ignore_failure: true
+
+    # AI prompt (judgment-based)
+    - id: obsidian-sync
+      handler:
+        type: prompt
+        file: hooks/obsidian-sync.md
+```
+
+### Environment Variables
+
+Command handlers receive these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `OPENSPEC_CHANGE_NAME` | Change name |
+| `OPENSPEC_CHANGE_DIR` | Absolute path to change directory |
+| `OPENSPEC_SCHEMA` | Schema name |
+| `OPENSPEC_PROJECT_ROOT` | Absolute path to project root |
+| `OPENSPEC_PHASE` | Current phase (propose, apply, archive) |
+| `OPENSPEC_HOOK_POINT` | Hook point (e.g., archive.post) |
+| `OPENSPEC_ARCHIVE_DIR` | Archive destination (archive.post only) |
+
+Plugin config values are available as `OPENSPEC_PLUGIN_CONFIG_{CATEGORY}_{FIELD}`.
+
+### Plugin Config
+
+Plugins can declare configuration requirements. Users provide values in `config.yaml`:
+
+```yaml
+# plugin.yaml
+config:
+  obsidian:
+    vault:
+      type: string
+      required: true
+    target_pattern:
+      type: string
+      default: "modules/{module}"
+
+# config.yaml
+plugins:
+  - my-plugin
+plugin_config:
+  my-plugin:
+    obsidian:
+      vault: "my-specs"
+```
+
+### Skill Overlays
+
+Plugins can inject content into generated skill and command files. When `openspec update` runs, overlay content is appended to the corresponding workflow's output.
+
+```yaml
+# plugin.yaml
+skill_overlays:
+  apply:
+    append: overlays/apply-orchestration.md
+  explore:
+    append: overlays/explore-research.md
+```
+
+Create the overlay files in your plugin directory:
+
+```
+my-plugin/
+  plugin.yaml
+  overlays/
+    apply-orchestration.md    # Appended to the apply skill/command
+    explore-research.md       # Appended to the explore skill/command
+```
+
+After `openspec update --force`, the generated skill files include the overlay content. Multiple plugins' overlays are appended in whitelist order. Missing overlay files produce a warning but don't block generation.
+
+Currently only `append` is supported. Future versions may add `prepend` and `replace_section`.
+
+### Plugin-Provided Schemas and Gates
+
+Plugins can bundle schemas in a `schemas/` subdirectory and custom gate types. See `openspec plugin info <name>` for details on any installed plugin.
+
+### Resolution Order
+
+Plugins resolve from three locations (highest priority first):
+
+1. **Project-local**: `openspec/plugins/<name>/`
+2. **User-global**: `~/.local/share/openspec/plugins/<name>/`
+3. **Package built-in**: `<openspec-package>/plugins/<name>/`
+
+Only plugins listed in `config.yaml`'s `plugins` array are loaded. Order in the array determines hook execution order.
+
+### CLI Commands
+
+```bash
+openspec plugin list          # Show all available plugins
+openspec plugin list --json   # Machine-readable output
+openspec plugin info <name>   # Detailed plugin information
+```
+
+## Orchestration
+
+OpenSpec supports parallel execution hints via `--subagents` and `--teams` flags. The CLI declares WHAT can be parallel; the AI harness decides HOW.
+
+### Flags
+
+```bash
+openspec instructions apply --change my-change --subagents --json
+openspec instructions apply --change my-change --teams --json
+```
+
+Flags are mutually exclusive and available on all `openspec instructions <phase>` commands.
+
+### Plugin Orchestration Declaration
+
+Plugins declare parallel capabilities on gates and hooks:
+
+```yaml
+# plugin.yaml
+gates:
+  - id: claude-review
+    handler:
+      type: prompt
+      file: gates/claude-review.md
+    orchestration:
+      parallel_with: ["codex-review"]   # Can run alongside codex-review
+      preferred_mode: teams              # Suggest teams mode
+
+  - id: codex-review
+    handler:
+      type: prompt
+      file: gates/codex-review.md
+    orchestration:
+      parallel_with: ["claude-review"]   # Bidirectional declaration required
+      preferred_mode: teams
+```
+
+Both sides must declare `parallel_with` (bidirectional). Unidirectional declarations emit a warning and default to sequential.
+
+### Schema Orchestration Override
+
+Schemas can override plugin declarations at the project level:
+
+```yaml
+# schema.yaml
+apply:
+  orchestration:
+    parallel_groups:
+      - gates: ["claude-review", "codex-review"]
+        parallel: true
+        mode: teams
+        synthesis: require-both-pass    # Both must pass
+```
+
+### Two-Layer Resolution
+
+```
+User flag (--teams)  →  mode only, doesn't force parallel grouping
+         ↓
+Schema orchestration →  final decision on parallel groups + synthesis
+         ↓
+Plugin declaration   →  default capabilities (parallel_with)
+         ↓
+Default              →  sequential execution
+```
+
+Schema always wins. Plugin is the default when schema is silent.
+
+### Task Group Parallelism
+
+Tasks in `tasks.md` are grouped by `## N.` section headers:
+
+- **Intra-group**: Tasks within a group run in parallel (`parallel: true`)
+- **Inter-group**: Sequential by default (group N depends on N-1)
+- **Explicit parallel**: Add `<!-- parallel-with: 1 -->` in a section header to override
+
+Domain tags `[domain: backend]` enable `--teams` assignment to specialized agents.
+
+### Gate Result Persistence
+
+Gate results are written to `.gates/` in the change directory (gitignored):
+
+```
+openspec/changes/my-change/
+└── .gates/
+    ├── claude-review.json
+    ├── codex-review.json
+    └── synthesis.json
+```
+
+### Synthesis Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `require-both-pass` | All gates in the group must pass |
+| `any-pass` | At least one gate must pass |
+| `majority` | More than half must pass |
+
 ## Usage Notes
 
 **Model selection**: OpenSpec works best with high-reasoning models. We recommend Opus 4.5 and GPT 5.2 for both planning and implementation.

openspec/changes/add-plugin-system/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-31