@sjawhar/opencode-legion-envoy 0.6.1 → 0.8.0

package/skills/legion-worker/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: legion-worker
+description: Use when dispatched as an architect, plan, implement, test, or review phase worker in a Legion issue workspace.
+---
+
+# Legion Phase Worker
+
+You are one phase in a shared issue workspace, not a dispatcher or pipeline coordinator. The
+architect owns the tree; phases use the same jj workspace sequentially. Complete the phase
+assigned in the prompt, return its structured output to the architect, and leave the durable
+copy that the next phase can trust.
+
+## Identity, scope, and role
+
+The dispatch supplies the issue, phase, daemon-minted role token, workspace, and task
+`outputSchema`. At startup, claim that role with `envoy_role_set`; never construct a role
+token from an issue name. A claim survives parking, and a revived or re-created worker claims
+its own role again.
+
+Read the current issue and its acceptance criteria before changing the workspace. Work only
+on this phase's artifact. You may use ordinary scouts, reviewers, and oracle subagents for
+phase work; never spawn legion-role workers. Escalate a product, scope, cross-phase, or
+lifecycle decision to the owning architect through hub, with the verified facts and the
+decision needed. For a durable question that needs Sami directly, you may use the raw
+`dispatch` MCP tool yourself; replies return to your own session.
+
+## Workspace and handoff precedence
+
+The `workspace` attribute in your `<legion-spawn>` block is the authoritative issue
+workspace. Before reading repository files or handoffs, you **MUST** bind to that exact
+path with:
+
+```bash
+cd -- "<workspace>" && jj -R "<workspace>" status
+```
+
+Never rely on the inherited cwd. Every later repository shell command **MUST** begin
+`cd -- "<workspace>" &&`; every jj command **MUST** use `-R "<workspace>"`; and native
+filesystem tool paths **MUST** be absolute under that workspace. Do not create an isolated
+worktree, change the workspace topology, or mix another issue's work into it. Concurrent
+issues have disjoint workspaces; phases for this issue are sequential.
+
+On every start, and especially after revival or re-creation, read the issue and then the
+committed predecessor handoffs in lifecycle order from `<workspace>/.legion/`:
+
+1. `architect.json`
+2. `plan.json`
+3. `implement.json`
+4. `test.json`
+5. `review.json`
+
+Read only files that precede the assigned phase. The live path returns JSON matching the task
+`outputSchema` directly to the architect. The durable path uses the **same schema** in
+`<workspace>/.legion/<phase>.json`. If a committed handoff conflicts with memory or a prior
+transcript, the committed file wins: it is the copy that survived.
+
+## jj Safety Rules
+
+- **Always `jj -R "<workspace>" new` to create isolated commits.** Never
+  `jj -R "<workspace>" edit @-` to go back to a parent — this changes what `@` points to
+  and makes `jj abandon` dangerous.
+- **Never `jj -R "<workspace>" abandon`.** If a mistake would require abandoning work,
+  stop and send the owning architect the `jj -R "<workspace>" log` evidence.
+- **Before pushing, check ancestry:** `jj -R "<workspace>" log -r 'ancestors(@, 5)'` —
+  verify only your issue's commits are in the chain, not unrelated work.
+
+**Shared operation safety:** Never run `jj op restore` in a Legion workspace. It rewrites the
+shared operation log. If a mistake reaches that point, stop and send the owning architect the
+`jj -R "<workspace>" log` evidence; recover only through the approved, path-scoped workflow.
+
+## Phase work
+
+Follow the repository's normal engineering workflow and the assigned issue's acceptance criteria.
+The dispatch output schema defines the phase artifact and completion evidence. Do not replace
+architect-owned decomposition, gate discipline, scheduling, or human communication with labels
+or a local status model.
+
+Commit attribution is automatic: the Legion extension exports a `JJ_CONFIG` overlay at root
+bootstrap, so every jj commit made in the session family carries an `Omp-Session: <root-session-id>`
+trailer with no action from you. Do not add attribution trailers by hand.
+
+The jj configuration already supplies the phase worker's plus-addressed author and committer
+identity. Do not override Git identity configuration. The worker session receives the
+credential capability it needs; invoke GitHub through the credential helper:
+
+```bash
+legion gh -- <gh args…>
+```
+
+## GitHub comment attribution
+
+Append this exact structured footer to **every** GitHub issue comment, pull-request comment,
+and review that this phase posts. It preserves session provenance on the artifact itself so
+work stays attributable to the session that produced it:
+
+```html
+<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
+```
+
+For example:
+
+```bash
+legion gh -- issue comment <issue-number> \
+  --body $'Verification complete.\n\n<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->' \
+  --repo <owner>/<repo>
+```
+
+## Implementer push and pull request
+
+Only the implementer creates the issue bookmark, pushes it, and opens the pull request. After
+its implementation commit and verification, it uses this exact branch name and push procedure:
+
+```bash
+cd -- "<workspace>" && \
+  jj -R "<workspace>" bookmark set legion/issue-<n> && \
+  jj -R "<workspace>" git push --bookmark legion/issue-<n> --allow-new
+```
+
+The provisioned issue workspace configures `credential.helper` with the daemon's absolute
+credential command, so `jj -R "<workspace>" git push` authenticates transparently through the
+same session capability. Never handle a token.
+
+Then create the pull request with the `github` tool's `pr_create` operation. The credential
+helper and `legion gh` provide the GitHub identity; never export, fetch, or replace a token.
+Other phases advance the existing branch rather than creating a replacement bookmark or PR.
+
+## Completion gate: handoff write, verification, and persistence
+
+The durable handoff uses the phase-specific fields from the task's `outputSchema` only.
+`--data` must not include `schemaVersion`, `phase`, or `completed`: the CLI generates that
+envelope. Return the **full** schema through the task's structured output, including the
+generated envelope fields.
+
+Write the phase-specific handoff:
+
+```bash
+cd -- "<workspace>" && \
+  legion handoff write --phase <p> --data '<JSON object of phase-specific fields only>'
+```
+
+Then verify the durable artifact exists:
+
+```bash
+test -f "<workspace>/.legion/<phase>.json"
+```
+
+Then commit that exact handoff file onto the issue branch:
+
+```bash
+cd -- "<workspace>" && \
+  jj -R "<workspace>" split -m "<phase>: record handoff" .legion/<phase>.json
+```
+
+If the issue bookmark exists locally, advance it and push it with the provisioned credential
+helper. `--allow-new` also publishes the locally provisioned bookmark on its first push:
+
+```bash
+cd -- "<workspace>" && \
+  jj -R "<workspace>" bookmark set legion/issue-<n> && \
+  jj -R "<workspace>" git push --bookmark legion/issue-<n> --allow-new
+```
+
+Do not report phase completion until the write, existence check, and handoff commit succeed;
+when an issue branch exists, its push is also required. This is the committed copy the next
+phase reads after revival. The reviewer later removes `.legion/` as its final commit; phase
+workers do not remove it.
+
+## Completion and escalation
+
+Return the same schema as the durable handoff through the task's structured output. Do not add
+pipeline labels, run a controller loop, or notify a controller with an invented completion
+protocol. A direct worker delivery belongs to its role; overseers receive only derived
+verdicts.
+
+When blocked on lifecycle, scope, or cross-phase matters, send the owning architect a concise
+hub message: issue, phase, verified observation, what you tried, and the decision required.
+Reach for `dispatch` yourself only for a standalone human question outside that coordination.

package/skills/legion-worker/references/config.md

@@ -0,0 +1,259 @@
+# Repository Configuration (.legion/config.yml)
+
+Workers load repository-specific configuration from `.legion/config.yml` at the workspace root. This file allows teams to customize Legion behavior per repository without modifying workflows.
+
+## Schema Overview
+
+The config file is YAML with the following top-level sections:
+
+```yaml
+merge:
+  require_smoke_test: boolean
+  require_reporter_approval: boolean
+  auto_merge_allowed: boolean
+
+testing:
+  require_specific_task: boolean
+  require_taiga_evidence: boolean
+
+notifications:
+  slack_channel: string
+  ping_reporter_on_pr: boolean
+
+skills:
+  required:
+    - skill_name_1
+    - skill_name_2
+
+phases:
+  architect:
+    # Phase-specific overrides (same keys as top-level)
+  plan:
+    # Phase-specific overrides
+  implement:
+    # Phase-specific overrides
+  test:
+    # Phase-specific overrides
+  review:
+    # Phase-specific overrides
+```
+
+## Field Reference
+
+### merge
+
+Controls merge behavior and approval gates.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `require_smoke_test` | boolean | `false` | If `true`, merge workflow requires evidence of smoke testing before auto-merge |
+| `require_reporter_approval` | boolean | `false` | If `true`, merge workflow requires explicit reporter approval before merging |
+| `auto_merge_allowed` | boolean | `false` | If `true`, merge workflow may auto-merge PRs that pass all gates |
+
+### testing
+
+Controls test requirements and evidence gates.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `require_specific_task` | boolean | `false` | If `true`, test workflow requires evidence of specific task testing (not just unit tests) |
+| `require_taiga_evidence` | boolean | `false` | If `true`, test workflow requires Taiga evidence (e.g., screenshots, logs) attached to the issue |
+
+### notifications
+
+Controls notifications and pings.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `slack_channel` | string | `null` | Slack channel ID (e.g., `#eng-legion`) where implementation status updates are posted. If set and `slack-bot` skill is available, implement workflow posts PR URL and CI state |
+| `ping_reporter_on_pr` | boolean | `false` | If `true`, notify the issue reporter when a PR is created |
+
+### skills
+
+Specifies skills that should be invoked for all phases.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `required` | string[] | `[]` | List of skill names to invoke in addition to plan handoff `requiredSkills` and independently discovered skills. Additive with other skill sources |
+
+### phases
+
+Phase-specific overrides. Each phase (`architect`, `plan`, `implement`, `test`, `review`) can override any top-level key.
+
+**Merge behavior:** Phase-specific values override top-level values. For example:
+
+```yaml
+merge:
+  require_reporter_approval: false
+
+phases:
+  implement:
+    merge:
+      require_reporter_approval: true  # Override for implement phase only
+```
+
+## Recognized Keys
+
+Workers recognize the following keys (case-sensitive):
+
+- `merge.require_smoke_test`
+- `merge.require_reporter_approval`
+- `merge.auto_merge_allowed`
+- `testing.require_specific_task`
+- `testing.require_taiga_evidence`
+- `notifications.slack_channel`
+- `notifications.ping_reporter_on_pr`
+- `skills.required`
+- `phases.<mode>.*` (any of the above keys under a phase)
+
+Unknown keys are silently ignored. Malformed YAML causes the config to be skipped (fallback to defaults).
+
+## Worker Behavior
+
+### Loading
+
+Each workflow loads config at startup:
+
+```bash
+if [ -f .legion/config.yml ]; then cat .legion/config.yml; fi
+```
+
+If the file is missing or malformed, workers proceed with defaults (no error).
+
+### Parsing
+
+Workers parse recognized keys and echo them for auditability:
+
+```
+Repo config constraints from .legion/config.yml:
+- merge.require_reporter_approval: true
+- testing.require_specific_task: true
+- skills.required: [test-driven-development, verification-before-completion]
+```
+
+### Application
+
+Config values are applied to shape workflow behavior:
+
+- **Plan phase:** Config constraints inform the plan preamble (e.g., "reporter approval required before merge")
+- **Implement phase:** Config-required skills are invoked additively with plan handoff skills
+- **Test phase:** Config gates (e.g., `require_specific_task`) are enforced
+- **Review phase:** Config-required skills are invoked additively
+- **Merge phase:** Config gates (e.g., `require_reporter_approval`) are enforced
+
+## Example Configuration
+
+### Minimal (all defaults)
+
+```yaml
+# Empty file or omitted entirely
+# All defaults apply
+```
+
+### Strict Testing
+
+```yaml
+testing:
+  require_specific_task: true
+  require_taiga_evidence: true
+
+skills:
+  required:
+    - test-driven-development
+    - verification-before-completion
+```
+
+### Slack Notifications + Approval Gate
+
+```yaml
+notifications:
+  slack_channel: "#eng-legion"
+  ping_reporter_on_pr: true
+
+merge:
+  require_reporter_approval: true
+  require_smoke_test: true
+```
+
+### Phase-Specific Overrides
+
+```yaml
+# Default: no approval required
+merge:
+  require_reporter_approval: false
+
+# But for implement phase, require approval
+phases:
+  implement:
+    merge:
+      require_reporter_approval: true
+
+# And require specific task testing only in test phase
+phases:
+  test:
+    testing:
+      require_specific_task: true
+```
+
+### Full Example
+
+```yaml
+merge:
+  require_smoke_test: true
+  require_reporter_approval: false
+  auto_merge_allowed: false
+
+testing:
+  require_specific_task: true
+  require_taiga_evidence: false
+
+notifications:
+  slack_channel: "#eng-legion"
+  ping_reporter_on_pr: true
+
+skills:
+  required:
+    - test-driven-development
+    - verification-before-completion
+
+phases:
+  plan:
+    skills:
+      required:
+        - brainstorming
+  implement:
+    merge:
+      require_reporter_approval: true
+  test:
+    testing:
+      require_taiga_evidence: true
+```
+
+## Defaults
+
+If a key is not specified in `.legion/config.yml`, the following defaults apply:
+
+```yaml
+merge:
+  require_smoke_test: false
+  require_reporter_approval: false
+  auto_merge_allowed: false
+
+testing:
+  require_specific_task: false
+  require_taiga_evidence: false
+
+notifications:
+  slack_channel: null
+  ping_reporter_on_pr: false
+
+skills:
+  required: []
+```
+
+## Notes
+
+- **Additive skills:** Config-required skills are additive with plan handoff `requiredSkills` and independently discovered skills. All sources are combined.
+- **Phase overrides:** Phase-specific values completely override top-level values for that phase. Partial overrides are not merged.
+- **Missing file:** If `.legion/config.yml` is missing or malformed, workers proceed with defaults (no error).
+- **Auditability:** Workers echo recognized keys and effective values at the start of each phase for transparency.

package/skills/legion-worker/references/knowledge-injection.md

@@ -0,0 +1,98 @@
+# Knowledge Injection Algorithm
+
+Canonical algorithm for injecting relevant learnings from `docs/solutions/` before phase-specific work begins. All worker workflows reference this file for the injection procedure; each workflow specifies its own keyword sources.
+
+## Overview
+
+Before starting main work, each phase checks the learnings index for applicable prior knowledge. This surfaces patterns, pitfalls, and institutional knowledge that previous workers documented.
+
+**Injection must never block work.** If any step fails (missing index, invalid JSON, missing files, empty handoff data), skip silently and proceed with the phase's main work.
+
+## Algorithm
+
+### 1. Read the Index
+
+Assemble the index by reading all per-entry JSON files in `docs/solutions/.index/`:
+
+```bash
+# Read and merge all entry files in .index/ directory
+for f in docs/solutions/.index/*.json; do
+  [ -f "$f" ] && cat "$f"
+done
+```
+
+Each file has the format `{ "version": 1, "entries": { "key": ["learning-path", ...] } }`. Merge all `entries` maps together, deduplicating learning paths per key.
+
+If the `.index/` directory doesn't exist or contains no valid JSON files, skip injection entirely — proceed to the phase's main work.
+
+### 2. Extract Keywords
+
+Collect keywords from the phase-specific sources (defined in each workflow file). The extraction algorithm:
+
+1. **Collect raw text** from the specified keyword sources (see the calling workflow's keyword source table)
+2. **Tokenize**: split on whitespace, `/`, `-`, `_`, and camelCase boundaries
+3. **Normalize**: lowercase all tokens
+4. **Filter**: remove tokens < 3 chars and common stopwords (the, and, for, with, this, that, from, into, when, will, should, would, could, also, been, have, each, etc.)
+5. **Deduplicate** tokens
+6. **Extract full path segments**: e.g., `packages/daemon/src/state` — keep as-is for path matching in addition to individual tokens
+
+Also look for references to:
+- Source path segments (e.g., `packages/daemon/src/state/`, `serve-manager`)
+- Module names (e.g., "daemon", "controller", "worker", "state")
+- Component names (e.g., "serve-manager", "decision", "fetch")
+- Feature areas (e.g., "skills", "linear", "github", "review", "retro")
+- Integration concerns (e.g., "PR", "labels", "MCP")
+- Domain concepts and error keywords from the context
+
+### 3. Match Keywords Against Index
+
+Use two matching modes against the keys in `.index`:
+
+- **Path matching**: For each key that does NOT start with `tag:`, check if any extracted keyword appears as a substring of the key (case-insensitive). Collect all matched learning file paths.
+- **Tag matching**: For each key that starts with `tag:`, extract the tag name (e.g., `tag:race-condition` → `race-condition`). Check if any extracted keyword matches the tag name (case-insensitive). Collect matched learning file paths.
+
+### 4. Deduplicate and Rank
+
+- Remove duplicates (same file matched via multiple keys)
+- **Status filter**: For each candidate, read its YAML front matter `status` field. Exclude any file with `status: superseded`. If the file doesn't exist or has no front matter, include it (graceful degradation).
+- **Primary rank: tag overlap** — For each remaining candidate, read its `tags` front matter field. Count how many of its tags appear in the extracted keywords (case-insensitive). Higher overlap = higher rank.
+- **Secondary rank: key specificity** — Learnings matched via longer/more-specific keys rank higher (e.g., a match on `packages/daemon/src/state` outranks a match on `packages/daemon`)
+- **Tertiary rank: match count** — Number of distinct key matches (more matches = more relevant)
+- **Cap at 3 learnings maximum**
+
+### 5. Read Matched Learnings
+
+For each matched learning file (from `docs/solutions/<path>`):
+
+1. Read YAML front matter: extract `title` and `tags` fields
+2. Skip past front matter (`---` blocks) and headings, take the first paragraph of prose (typically the Problem or Overview section)
+3. Prepend structured header: `[{title} | tags: {comma-separated tags}]`
+4. Truncate entire output (header + prose) to **350 characters**
+
+**If a matched file doesn't exist on disk:** Skip that entry silently (stale index entry from a file rename). Do not error.
+
+### 6. Output Injected Learnings
+
+Output the injected learnings visibly in the session before proceeding with the phase's main work:
+
+```
+## Relevant Learnings (from docs/solutions/)
+
+1. [docs/solutions/<path>]: [{title} | tags: {tag1}, {tag2}] <prose excerpt> (350 chars max total)
+2. [docs/solutions/<path>]: [{title} | tags: {tag1}, {tag2}] <prose excerpt>
+3. [docs/solutions/<path>]: [{title} | tags: {tag1}, {tag2}] <prose excerpt>
+
+(Review these for patterns and pitfalls relevant to this phase's work.)
+```
+
+**If no matches found:** Output "No relevant learnings found." and proceed. Do NOT add an empty section.
+
+**Canonical identifiers:** All references to learnings use their `docs/solutions/` relative file path (e.g., `daemon/controller-lifecycle-separation.md`). These paths are the stable IDs used for injection, handoff tracking, and future aggregation. Never use titles or truncated text as identifiers.
+
+## Fallback Behavior
+
+When a keyword source is unavailable (missing handoff data, empty fields, missing phase data), silently fall back to the next available source as defined in the calling workflow's fallback rules. Never error on missing data.
+
+## Integration with Handoffs
+
+If the phase writes handoff data, include a `learningsInjected` field listing the `docs/solutions/` relative paths of all injected learnings. This enables downstream phases to see what knowledge was available and supports future aggregation.

package/skills/legion-worker/resources/strategies/cleanup-deletion.md

@@ -0,0 +1,22 @@
+# Strategy: Cleanup & Deletion PRs
+
+When deleting deprecated code, stale docs, or consolidating references.
+
+## When deleting a CLI command, check all four:
+
+1. Implementation file(s)
+2. `package.json` / `pyproject.toml` script entry
+3. All project documentation references (AGENTS.md or equivalent — check command tables AND section headings)
+4. Wrapper scripts or CI jobs that invoke it
+
+## project doc headings are documentation too
+
+When updating a command reference, grep for the section heading and update it in the same commit. Headings that reference specific paths (`## Foo (meta/bar/)`) go stale when paths change.
+
+## Deletion PRs should be almost entirely deletions
+
+Resist opportunistic refactors. If the diff has significant additions, the scope has crept. The value of a cleanup PR is its tight, reviewable scope.
+
+## Complete the deletion chain
+
+If a feature has implementation + CLI wrapper + package.json entry + docs, remove all of them together. Partial deletion leaves broken references.

package/skills/legion-worker/resources/strategies/systematic-rename.md

@@ -0,0 +1,19 @@
+# Strategy: Systematic Rename
+
+When a repo, package, or URL is renamed across a codebase.
+
+## Checklist
+
+1. **Scope by file type** — grep all text-bearing extensions, not just the obvious ones:
+   - Source code (`.ts`, `.js`, `.py`, `.sh`) — functional, must update
+   - CI/CD configs (`.yml`, `.yaml`) — functional, must update
+   - Documentation (`.md`) — correctness, should update
+   - Config files (`.json`, `.toml`) — check but may be immutable
+
+2. **Classify matches as mutable vs immutable** — historical records (transcripts, test snapshots, progress logs) must NOT be modified. Changing them falsifies history.
+
+3. **Check comments for semantic context** — a comment mentioning the old name may still be correct in intent. Update the name but preserve the reasoning.
+
+4. **Verify with grep before AND after** — capture pre-edit state as a baseline for comparison.
+
+5. **Use `jj diff --git`** for verification — plain `jj diff` without color concatenates old/new text confusingly (e.g., `old-nameNEW-name` without color codes).

package/skills/linear/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: linear
+description: Manage Linear issues. Use when working with tasks, tickets, bugs, or Linear.
+mcp:
+  linear:
+    command: npx
+    args: ["-y", "github:obra/streamlinear"]
+    env:
+      LINEAR_API_TOKEN: ${LINEAR_API_TOKEN}
+---
+
+# Linear (Stream Linear)
+
+Single-tool MCP with action dispatch. All operations go through `linear_linear`.
+
+## Actions
+
+### Search Issues
+
+```
+linear_linear(action="search")                          # Your active issues
+linear_linear(action="search", query="auth bug")        # Text search
+linear_linear(action="search", query={state: "In Progress"})  # Filter
+linear_linear(action="search", query={team: "ENG", assignee: "me"})
+```
+
+### Get Issue Details
+
+```
+linear_linear(action="get", id="ABC-123")               # By short ID
+linear_linear(action="get", id="https://linear.app/...")  # By URL
+```
+
+Returns: title, description, status, labels, comments, attachments.
+
+### Update Issue
+
+```
+linear_linear(action="update", id="ABC-123", state="Done")
+linear_linear(action="update", id="ABC-123", priority=1)
+linear_linear(action="update", id="ABC-123", assignee="me")
+linear_linear(action="update", id="ABC-123", labels=["legion-backlog", "existing-label"])
+```
+
+**Labels array replaces all labels.** Fetch current labels first, then append.
+
+### Comment on Issue
+
+```
+linear_linear(action="comment", id="ABC-123", body="Fixed in commit abc123")
+```
+
+### Create Issue
+
+```
+linear_linear(action="create", title="Bug: Login fails", team="ENG")
+linear_linear(action="create", title="Bug", team="ENG", body="Details", priority=2)
+```
+
+### Raw GraphQL
+
+```
+linear_linear(action="graphql", graphql="query { viewer { name } }")
+```
+
+### Help
+
+```
+linear_linear(action="help")
+```
+
+## Reference
+
+- Priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low
+- State matching is fuzzy: "done" → "Done", "in prog" → "In Progress"
+- IDs accept: `ABC-123`, Linear URLs, or UUIDs