@jaggerxtrm/specialists 3.3.3 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.3.3",
+  "version": "3.4.0",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",

package/config/skills/specialists-usage-workspace/iteration-1/eval-bead-background/old_skill/outputs/result.md

@@ -1,105 +0,0 @@
-# Background Bug Hunt: Step-by-Step Commands
-
-## Scenario
-You have a beads issue `unitAI-xyz` assigned for deep bug investigation in the auth module.
-You want to run the `bug-hunt` specialist in the background.
-
----
-
-## Step 1: Verify the specialist exists
-
-```bash
-specialists list
-```
-
-Or filter if there are many:
-
-```bash
-specialists list --category analysis
-```
-
-Confirm `bug-hunt` appears in the output. If it does not, it is not installed in the project scope (`./specialists/*.specialist.yaml`).
-
----
-
-## Step 2: Start the specialist in the background
-
-```bash
-specialists run bug-hunt --bead unitAI-xyz --background
-```
-
-This returns immediately with a job ID, for example:
-
-```
-Job started: job_a1b2c3d4
-```
-
-The specialist will read the bead context from `unitAI-xyz` (title, description, linked files) and use it as its prompt. No `--prompt` flag is needed — `--bead` is the canonical input for tracked work.
-
----
-
-## Step 3: Monitor progress
-
-Follow all active jobs live (recommended):
-
-```bash
-specialists feed -f
-```
-
-Or follow only this job:
-
-```bash
-specialists feed job_a1b2c3d4 --follow
-```
-
-You will see event types as they arrive:
-- `text` — streamed output tokens
-- `thinking` — model reasoning
-- `tool` — specialist invoking a tool
-- `run_complete` — job finished
-
----
-
-## Step 4: Read the result when done
-
-```bash
-specialists result job_a1b2c3d4
-```
-
-Capture to a file if desired:
-
-```bash
-specialists result job_a1b2c3d4 > auth-bug-hunt.md
-```
-
----
-
-## Step 5: Close the bead
-
-Once you have reviewed the findings:
-
-```bash
-bd close unitAI-xyz --reason "Bug investigation complete, findings documented"
-```
-
----
-
-## Summary of all commands
-
-```bash
-specialists list
-specialists run bug-hunt --bead unitAI-xyz --background
-# → Job started: job_a1b2c3d4
-specialists feed -f
-specialists result job_a1b2c3d4
-bd close unitAI-xyz --reason "Bug investigation complete, findings documented"
-```
-
----
-
-## Notes
-
-- Do not use `--prompt` when passing `--bead` — the bead supplies the context.
-- Use `--context-depth 2` if the bead has upstream dependencies worth injecting (e.g., a parent issue describing broader scope).
-- If the job hangs, run `specialists stop job_a1b2c3d4` then check `specialists feed job_a1b2c3d4` for the last event.
-- If `bug-hunt` is not found, run `specialists doctor` to check for YAML errors or missing specialist files.

package/config/skills/specialists-usage-workspace/iteration-1/eval-bead-background/with_skill/outputs/result.md

@@ -1,93 +0,0 @@
-# Running bug-hunt Specialist in Background for unitAI-xyz
-
-You already have a beads issue `unitAI-xyz` assigned to you. Because this is a deep bug investigation (long-running, benefits from a dedicated expert), you should use the bead-first workflow with `--background`.
-
-## Exact Commands to Run
-
-### Step 1 — Verify the specialist exists
-
-```bash
-specialists list
-```
-
-Look for `bug-hunt` in the output. If it does not appear, only project-scoped specialists are searched (`./specialists/*.specialist.yaml`). Confirm the file exists in your project.
-
-### Step 2 — Start the specialist in the background, linked to your bead
-
-```bash
-specialists run bug-hunt --bead unitAI-xyz --background
-```
-
-This returns immediately with a job ID, for example:
-
-```
-Job started: job_a1b2c3d4
-```
-
-The specialist's system prompt will automatically have the context from bead `unitAI-xyz` injected (at the default depth of 1). If the auth module issue has related parent/child beads you want included, add `--context-depth 2` (or higher):
-
-```bash
-specialists run bug-hunt --bead unitAI-xyz --background --context-depth 2
-```
-
-### Step 3 — Monitor progress (live feed)
-
-```bash
-specialists feed job_a1b2c3d4 --follow
-```
-
-Or follow all active jobs at once:
-
-```bash
-specialists feed -f
-```
-
-Event types you will see:
-- `text` — streamed output tokens
-- `thinking` — model reasoning
-- `tool` — specialist calling a tool
-- `run_complete` — job finished
-
-### Step 4 — Read the final result once complete
-
-```bash
-specialists result job_a1b2c3d4
-```
-
-Capture to a file if you want to preserve it:
-
-```bash
-specialists result job_a1b2c3d4 > auth-bug-investigation.md
-```
-
-You will also see a completion banner injected into your next prompt:
-
-```
-[Specialist 'bug-hunt' completed (job job_a1b2c3d4, 42s). Run: specialists result job_a1b2c3d4]
-```
-
-### Step 5 — Close the bead when the investigation is done
-
-```bash
-bd close unitAI-xyz --reason "Bug investigation complete — findings in auth-bug-investigation.md"
-```
-
-### If you need to cancel
-
-```bash
-specialists stop job_a1b2c3d4
-```
-
----
-
-## Summary of the Full Command Sequence
-
-```bash
-specialists list                                               # confirm bug-hunt exists
-specialists run bug-hunt --bead unitAI-xyz --background       # start async job
-# → Job started: job_a1b2c3d4
-
-specialists feed job_a1b2c3d4 --follow                        # monitor live
-specialists result job_a1b2c3d4                               # read output when done
-bd close unitAI-xyz --reason "Investigation complete"         # close the bead
-```

package/config/skills/specialists-usage-workspace/iteration-1/eval-fresh-setup/old_skill/outputs/result.md

@@ -1,113 +0,0 @@
-# Fresh Setup: Specialists Walkthrough
-
-## Step 1 — Initialize Specialists in Your Project
-
-Run this once from your project root:
-
-```bash
-specialists init
-```
-
-This creates the `specialists/` and `.specialists/` directories and injects the workflow into `AGENTS.md`. Verify it worked:
-
-```bash
-specialists list
-```
-
-You should see the available specialists, including `code-review`.
-
----
-
-## Step 2 — Delegate the Code Review as a Background Job
-
-Since you want to keep working while the review runs, use `--background` mode.
-
-### Option A: Ad-hoc (no tracking bead)
-
-```bash
-specialists run code-review --prompt "Review src/api.ts for correctness, security, and style issues" --background
-```
-
-This returns immediately with a job ID, for example:
-
-```
-Job started: job_a1b2c3d4
-```
-
-### Option B: Tracked with a bead (recommended for real work)
-
-```bash
-# Create a bead to track the review
-bd create --title "Code review: src/api.ts" --type task --priority 2
-# → unitAI-abc
-
-# Run the specialist, linking it to the bead
-specialists run code-review --bead unitAI-abc --background
-# → Job started: job_a1b2c3d4
-```
-
----
-
-## Step 3 — Keep Working
-
-The specialist is now running asynchronously. You can continue with whatever else you need to do. The job runs in the background and does not block your session.
-
----
-
-## Step 4 — Monitor Progress (Optional)
-
-To tail live output from all active jobs:
-
-```bash
-specialists feed -f
-```
-
-To follow just this job:
-
-```bash
-specialists feed job_a1b2c3d4 --follow
-```
-
----
-
-## Step 5 — Read the Result When Done
-
-When the job completes, you will see a completion banner on your next prompt:
-
-```
-[Specialist 'code-review' completed (job job_a1b2c3d4, 42s). Run: specialists result job_a1b2c3d4]
-```
-
-Retrieve the full output:
-
-```bash
-specialists result job_a1b2c3d4
-```
-
-Capture it to a file:
-
-```bash
-specialists result job_a1b2c3d4 > review-api.md
-```
-
----
-
-## Step 6 — Close the Bead (If You Used One)
-
-```bash
-bd close unitAI-abc --reason "Review complete, addressed findings"
-```
-
----
-
-## Summary
-
-| Step | Command |
-|------|---------|
-| Initialize project | `specialists init` |
-| Verify specialists | `specialists list` |
-| Start background review | `specialists run code-review --prompt "..." --background` |
-| Monitor (optional) | `specialists feed -f` |
-| Read result | `specialists result <job-id>` |
-
-The key principle: use `--background` any time you want to keep working while a specialist runs. Use `--bead` to attach the run to a tracking issue for anything worth logging.

package/config/skills/specialists-usage-workspace/iteration-1/eval-fresh-setup/with_skill/outputs/result.md

@@ -1,131 +0,0 @@
-# Fresh Setup + Background Code Review Walkthrough
-
-## Step 1: Initialize specialists for your project
-
-Run this once in your project root:
-
-```bash
-specialists init
-```
-
-This creates the `specialists/` and `.specialists/` directories, wires up hooks, and injects the AGENTS.md workflow context. After it completes, verify discovery works:
-
-```bash
-specialists list
-```
-
-You should see the available specialists. For code review work, this project has `parallel-review` (covers architecture, security, performance, quality).
-
-> Note: There is no `code-review` specialist in this project. The closest equivalent is `parallel-review`, which runs concurrent analysis across multiple backends and synthesizes findings into a prioritized report.
-
----
-
-## Step 2: Create a tracking bead
-
-The canonical pattern for any real work is bead-first. Create a bead to track the review:
-
-```bash
-bd create --title "Code review: src/api.ts" --type task --priority 2
-# Returns something like: unitAI-abc
-```
-
----
-
-## Step 3: Start the review in the background
-
-Because code review takes more than 30 seconds and you want to keep working, use `--background`:
-
-```bash
-specialists run parallel-review --bead unitAI-abc --background
-# → Job started: job_a1b2c3d4
-```
-
-Or, if you want to scope the prompt explicitly:
-
-```bash
-echo "Review src/api.ts for architecture, security, performance, and quality issues." | specialists run parallel-review --bead unitAI-abc --background
-# → Job started: job_a1b2c3d4
-```
-
-The command returns immediately with a job ID. The specialist runs async while you continue your other work.
-
----
-
-## Step 4: Keep working
-
-Go work on whatever you were doing. The specialist runs independently in the background.
-
----
-
-## Step 5: Monitor progress (optional)
-
-If you want to check in:
-
-```bash
-specialists feed -f                        # follow all active jobs live
-specialists feed job_a1b2c3d4 --follow     # follow just this job
-```
-
-When the job completes, the next prompt you send will show a completion banner:
-
-```
-[Specialist 'parallel-review' completed (job job_a1b2c3d4, 42s). Run: specialists result job_a1b2c3d4]
-```
-
----
-
-## Step 6: Read the result
-
-```bash
-specialists result job_a1b2c3d4
-# or capture to file:
-specialists result job_a1b2c3d4 > review-api.md
-```
-
----
-
-## Step 7: Close the bead
-
-```bash
-bd close unitAI-abc --reason "Review complete, issues triaged"
-```
-
----
-
-## Summary of all commands
-
-```bash
-# One-time setup
-specialists init
-specialists list
-
-# Create tracking issue
-bd create --title "Code review: src/api.ts" --type task --priority 2
-# → unitAI-abc
-
-# Delegate to specialist, return immediately
-specialists run parallel-review --bead unitAI-abc --background
-# → Job started: job_a1b2c3d4
-
-# ... keep working ...
-
-# Check status
-specialists feed job_a1b2c3d4 --follow
-
-# Read result
-specialists result job_a1b2c3d4
-
-# Close the bead
-bd close unitAI-abc --reason "Review complete"
-```
-
----
-
-## Key points from the skill
-
-- `specialists init` is the one-time project setup command. `specialists install` and `specialists setup` are deprecated aliases that redirect to it.
-- Always use `--bead` for tracked work. `--prompt` is for quick, untracked, exploratory runs only.
-- Use `--background` whenever the task takes >30 seconds or you want to keep working in parallel.
-- `specialists doctor` runs detailed health checks (hooks, MCP wiring, zombie jobs) if anything seems wrong.
-- `specialists list` only searches project scope (`./specialists/*.specialist.yaml`). User-scope (`~/.specialists/`) is deprecated.
-- This project has `parallel-review` (not `code-review`) as the code review specialist — it covers all four focus areas: architecture, security, performance, and quality.

package/config/skills/specialists-usage-workspace/iteration-1/eval-yaml-debug/old_skill/outputs/result.md

@@ -1,159 +0,0 @@
-# Debugging: Specialist YAML Not Showing in `specialists list`
-
-## How Discovery Works
-
-`specialists list` uses `SpecialistLoader` which scans these directories in order:
-
-1. `<project-root>/specialists/`
-2. `<project-root>/.claude/specialists/`
-3. `<project-root>/.agent-forge/specialists/`
-4. `~/.agents/specialists/` (user scope)
-
-Only directories that physically exist are scanned. Within each directory, only files ending in `.specialist.yaml` are loaded.
-
----
-
-## Checklist: Why Your File Is Not Appearing
-
-Work through these checks in order.
-
-### 1. File is in the wrong location
-
-The file must be in one of the scanned directories listed above. The most common location is `<project-root>/specialists/`.
-
-Check:
-```bash
-ls specialists/*.specialist.yaml
-```
-
-If your file is somewhere else (e.g., `./my-specialist.yaml`, `./config/specialists/foo.yaml`), move it:
-```bash
-mv my-specialist.yaml specialists/my-specialist.yaml
-```
-
-### 2. File name does not end in `.specialist.yaml`
-
-The loader filters for the exact suffix `.specialist.yaml`. A file named `foo.yaml` or `foo.specialist.yml` will be silently ignored.
-
-Rename if needed:
-```bash
-mv specialists/foo.yaml specialists/foo.specialist.yaml
-```
-
-### 3. YAML parse or schema validation error (most common cause)
-
-When a file fails to parse or fails Zod schema validation, it is **silently skipped** with a warning printed to stderr only. You will not see it in normal `specialists list` output.
-
-Run this to surface the warning:
-```bash
-specialists list 2>&1 | grep skipping
-```
-
-Or redirect stderr directly:
-```bash
-specialists list 2>/tmp/spec-errors.txt; cat /tmp/spec-errors.txt
-```
-
-#### Required schema fields
-
-Every `.specialist.yaml` must have this top-level structure:
-
-```yaml
-specialist:
-  metadata:
-    name: my-specialist        # kebab-case: lowercase letters, digits, hyphens only
-    version: 1.0.0             # semver: X.Y.Z
-    description: "..."
-    category: "..."
-
-  execution:
-    model: anthropic/claude-sonnet-4-6   # required
-    # mode defaults to 'auto', timeout_ms defaults to 120000
-
-  prompt:
-    task_template: |           # required
-      $prompt
-```
-
-Common schema violations that cause silent skips:
-
-| Problem | Error message contains |
-|---------|----------------------|
-| `name` not kebab-case (e.g. `My Specialist`, `mySpecialist`) | `Must be kebab-case` |
-| `version` not semver (e.g. `1.0`, `v1.0.0`) | `Must be semver` |
-| Missing `execution.model` | `Required` |
-| Missing `prompt.task_template` | `Required` |
-| Top-level key is not `specialist:` | `Required` |
-| YAML syntax error (bad indentation, unquoted special chars) | YAML parse error |
-
-### 4. A duplicate name already exists in a higher-priority scope
-
-The loader uses a "first wins" strategy. If a specialist with the same `metadata.name` already exists in a directory scanned earlier (e.g., `specialists/` before `.claude/specialists/`), the duplicate is silently dropped.
-
-Check for name collisions:
-```bash
-specialists list --json | grep '"name"'
-grep -r "^    name:" specialists/ .claude/specialists/ 2>/dev/null
-```
-
-### 5. The `specialists/` directory does not exist yet
-
-If no `.specialist.yaml` files have been added before, the `specialists/` directory may not exist. The loader skips non-existent directories without error.
-
-Fix:
-```bash
-specialists init    # creates specialists/ and bootstraps the project
-```
-
-### 6. Running `specialists list` from the wrong working directory
-
-`SpecialistLoader` resolves project directories relative to `process.cwd()`. If you run `specialists list` from a subdirectory, it will not find files in the project root's `specialists/` folder.
-
-Always run from the project root:
-```bash
-cd /path/to/your/project
-specialists list
-```
-
----
-
-## Quick Diagnostic Commands
-
-```bash
-# 1. Show all stderr warnings (skipped files with reasons)
-specialists list 2>&1 >/dev/null
-
-# 2. Show full output including errors
-specialists list 2>&1
-
-# 3. Verify the file exists with correct suffix
-ls -la specialists/*.specialist.yaml
-
-# 4. Validate YAML syntax manually
-node -e "require('yaml').parse(require('fs').readFileSync('specialists/my-specialist.yaml','utf8'))"
-
-# 5. Run doctor for broader environment checks
-specialists doctor
-```
-
----
-
-## Example: Minimal Valid Specialist YAML
-
-```yaml
-specialist:
-  metadata:
-    name: my-specialist
-    version: 1.0.0
-    description: "Does something useful."
-    category: analysis
-
-  execution:
-    model: anthropic/claude-sonnet-4-6
-
-  prompt:
-    task_template: |
-      $prompt
-```
-
-Save as `specialists/my-specialist.specialist.yaml` in your project root, then run `specialists list` — it should appear immediately.