Project and system tools

Discover projects, read their methodology and state, and ask the server about teams, agents and capabilities. This group has 8 tools.

Tool	Edition	Summary
agent_health	Open core	Per-agent health snapshot: LLM call/cost counters vs.
capabilities	Open core	Read-only capability discovery.
get_project_info	Open core	Get full methodology + statistics for any project without loading it.
is_run_active	Open core	Check if spec-editor run is currently executing in the project.
list_projects	Open core	List all discovered spec-editor projects with methodology summaries.
pipeline_status	Open core	Light pipeline status for the header indicator: engine_running, per-role working/stopped, pool_parked, roles_without_account, stand_stale.
registry_get	Open core	Get the agent/team registry: teams, agents (skills, aspects, resolved llm route, budget, memory, delegation, gates, paused, source, role_ref, and the…
spec_editor_system	Open core	Teams, agents, tasks, questions, chat, capture, convert, pause toggles, and the pipeline runner.

agent_health

Per-agent health snapshot: LLM call/cost counters vs. budget (calls_ratio, cost_ratio), cache_hit_ratio, task/delegation outcomes, staleness (last_seen_ts > 30min AND no recent heartbeat AND no in-server worker running), suspended LLM-profile routes, and an overall ok/warn/error health level. Read-only; folded from the agent_stats journal projection and llm/profile-decision events.

Parameters

Parameter	Type	Required	Description
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)

capabilities

Read-only capability discovery. Returns {core: {version}, plugins: [{name, version, features, ui: {manifest_url}, services: [status,…], vscode}]} — core version plus every installed plugin’s declared capabilities, frontend manifest URL (if any), its running services’ status, and VS Code contribution path (if any). Stateless — no project_path needed.

Parameters

This tool takes no parameters.

get_project_info

Get full methodology + statistics for any project without loading it. Stateless — works across multiple projects. Returns methodology name, version, description, all aspects with element_types and relationship_types, plus element count.

Parameters

Parameter	Type	Required	Description
project_path	string	yes	Path to spec-editor project directory

is_run_active

Check if spec-editor run is currently executing in the project. Returns active status and PID of the running process. Requires project_path.

Parameters

Parameter	Type	Required	Description
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)

list_projects

List all discovered spec-editor projects with methodology summaries. Searches for directories containing methodology.yaml. Returns path, name, methodology name, version, aspects count, element count.

Parameters

Parameter	Type	Required	Description
base_dir	string	no	Base directory to search (optional)

pipeline_status

Light pipeline status for the header indicator: engine_running, per-role working/stopped, pool_parked, roles_without_account, stand_stale. Read-only; answers from the shared projections, none of agent_health/pool_records_get/economy_get.

Parameters

Parameter	Type	Required	Description
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)

registry_get

Get the agent/team registry: teams, agents (skills, aspects, resolved llm route, budget, memory, delegation, gates, paused, source, role_ref, and the composed-agent provenance composed/source_role/task), llm_profiles (fallback chain + suspension policy), roles (name, title, skills, aspects, analysis, source — union of methodology/plugin/agents.yaml role sources), and delegation_edges (every agent’s may_delegate_to glob patterns expanded against all agent keys). Read-only; falls back to the hardcoded defaults when the project has no agents.yaml.

Parameters

Parameter	Type	Required	Description
project_path	string	yes	Path to spec-editor project (directory with methodology.yaml)

spec_editor_system

Teams, agents, tasks, questions, chat, capture, convert, pause toggles, and the pipeline runner. Use command to select the operation. Commands: list_teams, list_agents, get_agent, list_tasks, queue_list, task_log, list_questions, chat, capture_requirement, convert_source_file, set_agent_paused, set_task_paused, list_composed_roles, set_composed_role_state, read_composed_journal, read_selection_records, assign_task_validator, remote_control_session_url, code_index_status, pipeline_status, pipeline_advance, report_bug, worker_status, worker_start, worker_stop, enqueue_task, run_agent. Installed plugins may add further commands (see SpecEditorPlugin.register_system_commands) — unknown commands return {status: error}.

Parameters

Parameter	Type	Required	Description
action	string or array	no	Journal action(s) to read: created, reused, updated, disabled, archived, restored, merged, escalated (a filter for read_composed_journal — all of them by default).
agent	string	no	Agent key (for get_agent, chat, set_agent_paused; for task_log without task_id — that agent’s LLM runs).
agent_key	string	no	Registry agent key, e.g. ‘coding_agent’ (for run_agent).
archived	boolean	no	Archive a composed role (hidden from the Agents tree unless its filter asks for it) or bring it back (for set_composed_role_state — the project owner only).
command	string	yes	Operation to perform (see tool description).
description	string	no	Bug description (for report_bug).
element_id	string	no	Element id (for pipeline_advance).
element_ids	array of string	no	Related element ids this bug is about (for report_bug, optional).
enabled	boolean	no	The owner’s switch over a composed role: false takes it out of the delegate skill’s select step without deleting it (for set_composed_role_state — the project owner only).
file_path	string	no	File path (for convert_source_file).
history	array	no	Optional chat history: [{role: user|assistant, content:…}].
include_archived	boolean	no	List archived composed roles too — the Agents tree’s own filter, off by default (for list_composed_roles); for read_composed_journal, read the records rotation moved into the archive as well.
justification	string	no	Why the composed role is switched off, archived or brought back — recorded in the team/composed journal with the role and its skills (for set_composed_role_state). Optional: the action’s default reason is written when it is left out.
limit	integer	no	Max number of tasks to return (for list_tasks), or of records the page holds, newest first — 0 asks for every match (for read_composed_journal, read_selection_records).
message	string	no	Chat message (for chat).
offset	integer	no	How many matching records to skip before the page (for read_composed_journal, read_selection_records).
params	object	no	Task params for run_agent: {goal, element_id?, acceptance?} for a coding-role agent; {code_dir?, deep?, phases?} for reengineer; {goal} for any other role. start_worker: true starts the role’s worker even when pipeline.workers.auto_start is false.
paused	boolean	no	Pause state (for set_agent_paused / set_task_paused).
payload	object	no	Arbitrary task payload, passed through verbatim to the queue (for enqueue_task).
performer	string	no	Composed role that did the work (for assign_task_validator).
project_path	string	no	Path to the spec-editor project (optional for list_teams/list_agents — without it they answer from the built-in defaults, with it from the project’s agents.yaml plus its composed agents).
role	string	no	Queue role, e.g. ‘coding’ — a filter for list_tasks, the queue to list for queue_list (required there), or the target role for worker_start/worker_stop/enqueue_task.
role_name	string	no	Composed role name, e.g. ‘physics_modeller’ (for set_composed_role_state; a filter for read_composed_journal and read_selection_records; for list_composed_roles a read by direct identifier, which reaches an archived role whatever the archive filter says).
run_id	string	no	LLM run id (for task_log with agent and role — that run’s attempts as llm_attempts).
screen	string	no	Screen route/title where the bug was seen (for report_bug, optional).
severity	string, one of low, medium, high	no	Bug severity, default ‘medium’ (for report_bug).
stage	string	no	Force this stage — trace|formulate|plan|implement|verify (for pipeline_advance, optional — omit to auto-detect the next applicable stage).
status	string	no	Filter by task status: queued|running|done|failed (for list_tasks).
task	string	no	The task statement the verifier is being assigned to (for assign_task_validator), or the task whose records are wanted — matched canonically, so any wording of it finds them (for read_composed_journal, read_selection_records).
task_id	string	no	Task ID (for set_task_paused, task_log).
text	string	no	Requirement text (for capture_requirement).
title	string	no	Short title (for capture_requirement, optional).
validator	string	no	Composed role proposed to verify it (for assign_task_validator). Refused with code validator_too_close or validator_shares_soul_and_model when it is not independent enough of the performer.