@jaggerxtrm/specialists 3.15.4 → 3.17.0

package/README.md

@@ -144,6 +144,9 @@ sp ps
 sp feed <job-id> --follow
 sp result <job-id>
 
+# Human-in-the-loop alternative: launch with a live TUI
+sp chat debugger --bead <id>          # feed-style timeline + status + final result + input
+
 # After implementation and reviewer PASS
 sp merge <chain-root-bead>          # standalone chain
 sp epic status <epic-id>            # multi-chain publication check
@@ -167,8 +170,11 @@ Useful commands:
 ```bash
 sp ps                         # actionable dashboard
 sp ps -f                      # TTY dashboard follow; pipes emit ANSI-free snapshots
-sp feed <job-id>              # full DB-backed event replay
+sp feed <job-id>              # compact DB-backed event replay
 sp feed -f                    # follow all active jobs
+sp log <job-id>               # lean runtime/control/error log; from a parent dir aggregates child repo DBs
+sp log --specialist reviewer -f
+sp chat explorer --bead <id>    # launch interactive TUI; input auto-steers/resumes
 sp result <job-id> --wait
 sp steer <job-id> "focus only on X"
 sp resume <job-id> "continue with these findings"
@@ -177,6 +183,8 @@ sp clean --reap-orphans --dry-run
 sp clean --ps                 # hide terminal dashboard history without deleting DB audit rows
 ```
 
+`sp chat` is for launching a new interactive specialist session. It renders the same normalized feed style as `sp feed -f`, shows startup/payload context and the final result, and maps typed input to `steer` while running or `resume` while waiting. `/quit` and Ctrl+C detach the TUI without stopping the job; use `/stop` when you intend to stop it. Current `sp attach <job-id>` remains the legacy tmux attach path; chat-style attach to an existing job is tracked separately.
+
 ## Script and service specialists
 
 Use `sp run` for interactive agent orchestration. Use the script/service surfaces when you need a synchronous, READ_ONLY, one-shot generation path:

package/config/mandatory-rules/research-tool-routing.md

@@ -7,6 +7,10 @@ Pick the right source before invoking research. Default to the project knowledge
 - `find-docs` / context7 — library, framework, SDK, CLI, or cloud-service docs (API syntax, config, migration).
 - `deepwiki` — public GitHub repo internals (architecture, conventions, code paths).
 - `github-search` (ghgrep) — real-world code patterns and API usage examples.
+- `ddgs` — general web search, no API key (`ddgs text -q "<query>" -m 8`). Discover authoritative URLs for vendor docs, blogs, papers, or proprietary products the above don't cover.
+- `agent-browser` — read/interact with any URL, including JS-rendered pages (`agent-browser open <url>` → `get text body`; close with `agent-browser close --all`).
 - `last30days` — recent web/social signals (Reddit, X, HN, YouTube). Early-warning only, never authoritative.
 
+General web (not a library/repo/social topic): use `ddgs` to discover URLs, then `agent-browser` to read them. Never point `agent-browser` at a search engine — headless Chrome gets CAPTCHA-blocked; search with `ddgs` instead. If `ddgs`/`agent-browser` aren't installed, report the gap (`uv tool install ddgs`; `npm i -g agent-browser && agent-browser install`) rather than answering from memory.
+
 Invoke skills on demand, not by default. Cite the source for every external claim.

package/config/mandatory-rules/test-runner-execution-scope.md

@@ -2,4 +2,4 @@
 name: test-runner-execution-scope
 kind: mandatory-rule
 ---
-Run only requested tests. Report failures with root cause and fix hints; do not expand scope.
+Run only requested tests. Exact command input wins over manifest fallback. If fallback is used, label it clearly as fallback. Report failures with root cause, owner classification, and next-recipient hints; do not expand scope.

package/config/skills/specialists-creator/SKILL.md

@@ -5,8 +5,8 @@ description: >
   agent through writing a valid `.specialist.json`, choosing supported models,
   validating against the schema, and avoiding common specialist authoring
   mistakes.
-version: 1.2
-synced_at: 236ca5e6
+version: 1.3
+synced_at: 78a7883e
 ---
 
 # Specialist Author Guide
@@ -358,16 +358,35 @@ Typical use cases:
 - `gitnexus: false` for specialists that should not receive GitNexus graph tooling
 - set both `false` for constrained runs that need clean extension surface
 
+### Bare specialists
+
+Use `execution.bare: true` for non-coding LLM transforms that need a fresh canvas: research synthesis, document analysis, summarization, extraction, translation, or other tasks where specialist runtime framing adds noise instead of help.
+
+Bare mode disables all package-runner prompt injection beyond rendered `prompt.system` and `prompt.task_template`: Specialist Run Context, Output Style, GitNexus mandate, `STATIC_WORKFLOW_RULES_BLOCK`, memory injection, GitNexus pre-query snapshot, reviewer patch retrieval, output contract, and task-side mandatory rules / reviewer diff context.
+
+`execution.bare` is orthogonal to `prompt.system_prompt_mode`. Set `bare: true` without `system_prompt_mode: "replace"` when you want to keep pi's coding-agent base prompt but skip specialist runtime injections.
+
+Copy bare template from installed npm package, not repo clone:
+
+```bash
+cp "$(node -p \"require.resolve('@jaggerxtrm/specialists/package.json').replace(/package\\.json$/, '')\")config/specialists/bare.specialist.json" ".specialists/user/<your-name>.specialist.json"
+```
+
+Warning: bare mode bypasses `mandatory_rules` completely — template sets, inline rules, and global disables all skip runtime injection in bare runs.
+
 ### `specialist.prompt` (required)
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `task_template` | string | yes | Template string with `$variable` substitution |
 | `system` | string | no | System prompt / agents.md content |
+| `system_prompt_mode` | enum | no | `append` \| `replace` — see [System Prompt Mode](#system-prompt-mode) |
 | `skill_inherit` | string | no | Single skill folder/file injected via `pi --skill` (Agent Forge compat) |
 | `output_schema` | object | no | JSON schema for structured output — injected into system prompt by runner; post-run validation is warn-only |
 | `examples` | array | no | Few-shot examples |
 
+> **Replace mode warning:** `replace` removes pi's coding-agent base prompt. Teach every command, tool, convention, output format, and behavior explicitly in `prompt.system`; nothing implicit remains.
+
 **Output contract precedence (runner-injected):** `response_format` → `output_type` → `output_schema`.
 
 **`response_format` behavior**
@@ -397,6 +416,24 @@ Typical use cases:
 
 **Mandatory markdown+schema rule:** if `response_format: markdown` and `output_schema` is present, the output must include `## Machine-readable block` containing exactly one JSON object in a single ` ```json ` fenced block. That JSON object is canonical and must match the schema.
 
+### System Prompt Mode
+
+`prompt.system_prompt_mode` controls whether `prompt.system` replaces or appends to pi's base prompt.
+
+| Runner | Default when field absent | `append` sees | `replace` sees |
+|--------|---------------------------|---------------|----------------|
+| Package-class (`sp run` → `runner.ts` → `session.ts`) | `append` | pi coding-agent base prompt + specialist `agentsMd` | only specialist `agentsMd` |
+| Script-class (`sp script` / `sp serve` → `script-runner.ts`) | `replace` | only specialist `prompt.system` | only specialist `prompt.system` |
+
+| Combination | Agent sees |
+|-------------|------------|
+| Package × append | pi coding-agent base prompt + specialist `agentsMd` |
+| Package × replace | only specialist `agentsMd` |
+| Script × append | pi coding-agent base prompt + specialist `prompt.system` |
+| Script × replace | only specialist `prompt.system` |
+
+> **Replace mode warning:** use `replace` only when you intend to author full prompt surface yourself. No coding-agent defaults survive; teach commands, tools, conventions, output contract, and behavior explicitly. Best fit: non-coding transforms where base prompt adds noise.
+
 Standard schemas by specialist type (shown as the `output_schema` object value):
 
 executor — change manifest:
@@ -441,6 +478,48 @@ planner — epic result:
 }
 ```
 
+### `specialist.mandatory_rules` (optional)
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `template_sets` | string[] | `[]` | Adds rule-set ids from `config/mandatory-rules/index.json` and local overlays |
+| `disable_default_globals` | boolean | `false` | Suppresses only inline `STATIC_WORKFLOW_RULES_BLOCK` (`Beads Workflow Quick Rules`) |
+| `inline_rules` | `MandatoryRule[]` | `[]` | Inline rules appended without file lookup |
+
+Runtime layering:
+
+1. `config/mandatory-rules/index.json.required_template_sets` — always loaded
+2. `config/mandatory-rules/index.json.default_template_sets` — also always loaded today; current quirk, not suppressed by `disable_default_globals`
+3. `specialist.mandatory_rules.template_sets`
+4. `specialist.mandatory_rules.inline_rules`
+
+`disable_default_globals` only removes the inline `STATIC_WORKFLOW_RULES_BLOCK`. It does **not** suppress index-driven sets. True user-rules-only runs need both `disable_default_globals: true` and a user overlay index in `.specialists/user/mandatory-rules/index.json` that clears required/default sets.
+
+Canonical set ids in `config/mandatory-rules/*.md`:
+`bead-id-verbatim`, `changelog-conventions`, `changelog-keeper-scope`, `code-quality-defaults`, `core-session-boundary`, `diagnose-loop`, `executor-delivery`, `explorer-readonly`, `git-workflow-safe`, `gitnexus-required`, `overthinker-4phase`, `per-turn-handoff-schema`, `research-tool-routing`, `researcher-source-discipline`, `reviewer-verdict-format`, `security-review-defaults`, `serena-cheatsheet`, `sync-docs-scope-discipline`, `test-runner-execution-scope`.
+
+Minimal user-rules-only spec:
+
+```json
+{
+  "specialist": {
+    "mandatory_rules": {
+      "disable_default_globals": true,
+      "inline_rules": [
+        { "id": "user-rule-1", "level": "error", "text": "Use local policy only." },
+        { "id": "user-rule-2", "level": "warn", "text": "Prefer repo overlay index.", "when": "overlay exists" }
+      ]
+    }
+  }
+}
+```
+
+Inline rule shape:
+
+```json
+{ "id": "rule-id", "level": "error", "text": "Rule text", "when": "optional condition" }
+```
+
 ### `specialist.skills` (optional)
 
 ```json
@@ -496,7 +575,34 @@ Informational declarations used by pre-run validation and future tooling (e.g. `
 }
 ```
 
-Writes the final session output to this file path after the session completes. Relative to the working directory.
+When set, the specialist writes its **handoff block** to this file on every substantive turn — foreground and `--background`. The content is identical to what is appended to the input bead notes and shown by `sp result`: a markdown heading, the verbatim specialist output, and an italic metadata footer.
+
+- **No env flag required.** `output_file` is honored whenever it is set (since unitAI-f58ma). It does NOT require `SPECIALISTS_JOB_FILE_OUTPUT` — that flag now only gates the debug file-mirrors (events.jsonl / status.json / result.txt).
+- **Single writer.** In a supervised run (`sp run`) the supervisor owns the file and the runner's own write is suppressed, so the file is never double-written. (In script/serve runs there is no supervisor; the runner writes the raw output instead of the enveloped block.)
+- **Format is the rendered handoff block, not bare output.** A downstream specialist that consumes this file as input will see the header/footer envelope around the body.
+- **Append vs overwrite is controlled by `notes_mode`** (see below): `full-trail` appends each turn; `final-only` overwrites with just the final `[FINAL · DONE]` block.
+- **Gitignore the path** if you don't want it committed — specs with `output_file` always write, so add the path (e.g. `.specialists/*-result.md`) to `.gitignore`.
+
+Relative paths resolve from the working directory.
+
+### `specialist.notes_mode`
+
+Controls how per-turn handoff output is persisted to BOTH the input bead notes and `output_file`.
+
+| Value | Behavior |
+|---|---|
+| `"full-trail"` (default) | Append every substantive turn. Bead notes / `output_file` accumulate `### … [turn N · WAITING]` blocks, ending with a final `## … [FINAL · DONE]` block. Best for keep-alive specialists where the operator wants the full trail. |
+| `"final-only"` | Persist only the single canonical `## … [FINAL · DONE]` block; intermediate turns are skipped and `output_file` is OVERWRITTEN (not appended). Best for non-coding / chained pipelines where the next specialist reads the previous specialist's bead note or `output_file` as its input and only wants the final result. |
+
+Empty turns are never persisted. The handoff block is markdown-native (heading + verbatim body + one italic metadata footer); the model string is normalized (provider prefix stripped, e.g. `nano-gpt/moonshotai/kimi-k2.5` renders as `kimi-k2.5`).
+
+```json
+{ "notes_mode": "final-only" }
+```
+
+### Handoff / pipeline output recipe
+
+For a non-coding pipeline where each specialist reads the previous one's result, set `output_file` to a known path AND `notes_mode: "final-only"` so the file (and the bead note) holds exactly the final result, overwritten each run — clean for the next specialist to consume. For a human-monitored keep-alive specialist, leave `notes_mode: "full-trail"` (default) so the operator sees every turn accumulate. `output_file` needs no env flag; just gitignore its path.
 
 ### `specialist.validation` (optional)
 
@@ -794,3 +900,41 @@ specialists run my-specialist --prompt "ping" --no-beads
 ```
 
 If you need the underlying implementation, read `config/skills/specialists-creator/scripts/validate-specialist.ts`. It is a thin Bun/TypeScript wrapper over `parseSpecialist()` from `src/specialist/schema.ts`, which keeps the helper cross-platform for Windows, macOS, and Linux.
+
+---
+
+## Script-Class vs Package-Class Runtime
+
+Two runtime classes exist:
+
+- **Package-class**: `sp run` → `runner.ts` → `session.ts`
+- **Script-class**: `sp script` / `sp serve` → `script-runner.ts`
+
+| Runner | Injected into system prompt |
+|--------|----------------------------|
+| Package-class | `prompt.system` + Specialist Run Context + caveman output style + GitNexus mandate (if `.gitnexus` exists) + `STATIC_WORKFLOW_RULES_BLOCK` + memory injection + mandatory rules + skills inheritance + output contract + reviewer patch retrieval (reviewer reuse only) |
+| Script-class | `prompt.system` only |
+
+Pi flags:
+
+| Runner | Pi flags |
+|--------|----------|
+| Package-class | `--no-extensions`, then re-enable quality-gates/service-skills/caveman/gitnexus/serena |
+| Script-class | `--no-extensions --no-tools --offline --no-context-files --no-prompt-templates --no-themes` and `--no-skills` when `skills.paths` is empty |
+
+Settings that silently do nothing on script-class:
+
+- `mandatory_rules` (all fields)
+- beads injection
+- GitNexus mandate
+- memory injection
+- output contract auto-generation
+
+Per-runner default for `prompt.system_prompt_mode`:
+
+- Package-class: `append`
+- Script-class: `replace`
+
+> **Script-class warning:** `mandatory_rules` never reaches script-class. If spec must rely on rule sets, it must run package-class.
+
+---

package/config/skills/using-specialists-auto/SKILL.md

@@ -39,7 +39,7 @@ read bead → write 7-section contract (child impl bead) → bd dep add parent
   → sleep 10 && sp ps                              # confirm started, not stuck queued
   → sleep <role-typical from v3> & sp ps          # check (see v3 Monitoring section)
   → sp result <exec-job>                           # consume immediately on transition to waiting
-  → optional advisory passes per v3 (code-sanity if smelly, security-auditor if risk surface)
+  → optional advisory passes per v3 (seconder if smelly, security-auditor if risk surface)
   → write reviewer bead contract → sp run reviewer --bead <review> --job <exec-job> --background
   → sleep 90 & sp ps
   → sp result <reviewer-job>

package/config/skills/using-specialists-v2/SKILL.md

@@ -215,7 +215,7 @@ Run `specialists list` if you need the live registry. Choose by task, not by hab
 | Design/tradeoffs | `overthinker` | The approach is risky, ambiguous, or needs critique. |
 | Implementation | `executor` | The contract is clear enough to write code or docs. |
 | Compliance/code review | `reviewer` | An executor/debugger produced changes that need the final PASS/PARTIAL/FAIL verdict. |
-| Implementation sanity | `code-sanity` | You want a cheap READ_ONLY smell pass for simplicity, type safety, dead code, brittle async/error handling, or maintainability before reviewer. |
+| Implementation sanity | `seconder` | You want a cheap READ_ONLY smell pass for simplicity, type safety, dead code, brittle async/error handling, or maintainability before reviewer. |
 | Security/dependency audit | `security-auditor` | You need threat modeling, secure-code review, package advisory triage, or agent/config security scanning. LOW: scan/read/recommend only. |
 | Multiple review perspectives | `parallel-review` | A critical diff needs independent review passes. |
 | Test execution | `test-runner` | You need suites run and failures interpreted. |
@@ -247,7 +247,7 @@ specialists doctor --check-drift                 # inspect stale .specialists/de
 sp prune-stale-defaults --dry-run                # preview redundant default snapshots
 specialists run <name> --bead <id> --background
 specialists run executor --bead <impl-bead> --background       # worktree auto-provisioned
-specialists run code-sanity --bead <sanity-bead> --job <exec-job> --keep-alive --background
+specialists run seconder --bead <sanity-bead> --job <exec-job> --keep-alive --background
 specialists run security-auditor --bead <security-bead> --job <exec-job> --keep-alive --background
 specialists run reviewer --bead <review-bead> --job <exec-job> --keep-alive --background
 specialists ps
@@ -343,7 +343,7 @@ specialists run executor --worktree --bead <impl> --context-depth 3 --background
 specialists result <exec-job>
 ```
 
-Optional code-sanity pass for implementation smell checks (use when the diff is non-trivial or likely to accumulate agent-code complexity):
+Optional seconder pass for implementation smell checks (use when the diff is non-trivial or likely to accumulate agent-code complexity):
 
 ```bash
 bd create --title "Code sanity check token refresh retry" --type task --priority 3 \
@@ -355,11 +355,11 @@ CONSTRAINTS: At most 5 concrete findings; cite files/symbols/lines where possibl
 VALIDATION: Findings are suitable to paste into specialists resume <exec-job>.
 OUTPUT: OK/FINDINGS/BLOCKED with handoff."
 bd dep add <sanity> <impl>
-specialists run code-sanity --bead <sanity> --job <exec-job> --context-depth 3 --keep-alive --background
+specialists run seconder --bead <sanity> --job <exec-job> --context-depth 3 --keep-alive --background
 specialists result <sanity-job>
 ```
 
-If code-sanity returns `FINDINGS`, resume executor with those concrete instructions, then rerun code-sanity only if the fixes were substantive. Do not treat code-sanity `OK` as reviewer PASS.
+If seconder returns `FINDINGS`, resume executor with those concrete instructions, then rerun seconder only if the fixes were substantive. Do not treat seconder `OK` as reviewer PASS.
 
 Optional security pass when the task touches auth, secrets, input handling, dependency updates, package advisories, agent config, hooks, or exposed endpoints:
 
@@ -492,7 +492,7 @@ Standard loop:
 ```text
 executor --worktree --bead impl
   -> waiting after turn
-optional code-sanity --bead sanity --job exec-job
+optional seconder --bead sanity --job exec-job
   -> OK: continue
   -> FINDINGS: resume executor with exact sanity findings
 optional security-auditor --bead security --job exec-job
@@ -506,7 +506,7 @@ reviewer --bead review --job exec-job
 
 Prefer `sp resume <exec-job>` over a new fix executor when the original job is waiting and context is healthy. Use a new fix bead with `--job <exec-job>` only when the original executor is dead, context exhausted, or a separate audit trail is required.
 
-Code-sanity and security-auditor outputs are advisory inputs to the chain; reviewer output must still be consumed before publishing. Do not treat job completion, code-sanity OK, or security no-findings as equivalent to reviewer acceptance.
+Seconder and security-auditor outputs are advisory inputs to the chain; reviewer output must still be consumed before publishing. Do not treat job completion, seconder OK, or security no-findings as equivalent to reviewer acceptance.
 
 ## Dependency Mapping