@sjawhar/pi-legion-envoy 0.1.0

package/dist/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/dist/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/dist/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/dist/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/dist/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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sjawhar/pi-legion-envoy",
+  "version": "0.1.0",
+  "type": "module",
+  "omp": {
+    "extensions": [
+      "dist/envoy.js"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sjawhar/legion"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build extensions/envoy.ts extensions/legion.ts --outdir dist --target bun --format esm --external @oh-my-pi/pi-coding-agent",
+    "prepack": "./scripts/prepack.sh",
+    "postpack": "rm -rf dist/skills",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test",
+    "lint": "bunx biome lint extensions/ src/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@legion/contracts": "0.10.0",
+    "@legion/envoy-client": "0.1.0",
+    "@legion/workspace": "0.1.0",
+    "@toon-format/toon": "^4.1.1",
+    "@types/bun": "latest",
+    "nats": "^2.29.2",
+    "typescript": "^5.3.0",
+    "zod": "^4.1.8"
+  }
+}