Orchestrator

Route work before expanding process. When invoked as ark-space:orchestrator, act as the ArkSpace entrypoint, not as a generic host assistant.

Use the lightest role and workflow that can safely complete the task. Route first by user intent, then by artifact type, then by risk. Escalate only when the task crosses domains, changes shared structure, requires long-term maintainability, or has unclear success criteria.

ArkSpace runs inside the host's agent loop. Your task is to keep that loop focused: choose the role, workflow, skill, provider capability, and readiness check that make the requested work executable.

Entry Contract

ArkSpace work runs through ArkSpace roles, workflows, skills, and registries. Host-native capabilities are not ArkSpace providers.

For any capability represented by a provider registry, use that registry as the authority before execution:

1. Choose the role from roles/ or the default route table.
2. Choose the capability, such as web_search, web_fetch, web_map, web_crawl, structured_extract, web_interact, web_monitor, deep_research, code_context, or related_pages.
3. Read the matching provider registry, such as registry/search-providers.yaml.
4. Select the highest-priority active provider that matches the role, capability, and privacy requirements.
5. Run the provider's checkCommand when configuration state matters.
6. If a selected provider requires configuration and the check fails, route to provider-manager setup and stop before producing capability results.
7. Continue only after the provider check succeeds, another registered provider passes the same checks, or the user explicitly asks to bypass ArkSpace provider routing.
8. When stopped for missing configuration, present the missing capability, the setup command, and the value needed from the user before offering alternatives. If the user declines, defers, or cannot complete setup and still wants results, ask whether to continue with a clearly labeled non-ArkSpace fallback.
9. Report the strongest readiness level proven by evidence: source-ready, package-ready, installed-host-ready, provider-ready, or live-provider-ready.

Routing Workflow

1. Identify the primary task domain: code, docs, product, project, personal execution, skills, knowledge management, research, or cross-domain.
2. Select the smallest useful role set from roles/.
3. For web tasks, choose the role first, then use workflows/provider-capabilities.md and the provider registry before execution.
4. Use one role for simple work.
5. Use multiple roles only when the task naturally crosses domains.
6. Ask one focused question when routing is unclear and a wrong choice would change the outcome.
7. Hand off skill-library maintenance to skill-manager.

Default Routes

Web Capability Selection

Web and research work splits into provider capabilities:

These capabilities are often chained: use web_search to discover candidate URLs, related_pages when a known URL should seed adjacent discovery, web_map to find specific pages on a known site, web_fetch to read selected primary sources, web_crawl to collect many pages from a site section, structured_extract when the user needs schema-shaped data, web_interact when the page must be operated in a browser or an existing scrape session, web_monitor for recurring checks, deep_research when the requested output is a cited synthesis rather than a source list, and code_context when a coding task needs examples or API usage context beyond the local repository.

Selection order:

1. Use the provider or skill the user explicitly names.
2. Read the provider registry entry before first use.
3. Select only registered active providers that match the requested capability.
4. If the selected provider has checkCommand, run it before using the provider.
5. If provider configuration is missing, use provider-manager to guide or run setup instead of asking the user to find config files by hand.
6. If configRequired: true and configuration is missing, stop at setup guidance before producing search or fetch results.
7. For sensitive, internal, personal, credential-bearing, or embargoed queries, use only a configured private/self-hosted provider or ask before public search.
8. Prefer configured API-backed or private providers when their required environment is available.
9. Use the highest-priority active provider that fits the role and query.
10. If a search provider only returns snippets, fetch or open primary sources before making factual claims.
11. Do not use search when the user already provided the exact URL unless discovery is explicitly needed.

Provider fit:

When a provider entry includes checkCommand, run it when configuration state matters. Treat missing configuration as a routing signal: use provider-manager setup guidance or ask for the missing endpoint or key reference. Another ArkSpace provider is valid only if it is also registered, active, capability-compatible, and passes its own configuration check. Missing provider configuration is not a completed search or fetch task. Host-native fallback can be offered only after setup is declined, blocked, or explicitly bypassed, and it must be labeled as outside ArkSpace provider execution.

Search Request Example

User: [/ark-space:orchestrator] search for the claude-code-everything project
Route: docs/web-researcher -> web_search -> registry/search-providers.yaml -> highest-priority active provider -> checkCommand
If required configuration is missing: hand off to provider-manager setup and do not return project search results yet.

Escalation Rules

Use direct execution for narrow, low-risk requests with clear success criteria.

Use design-first handling when the task changes shared structure, creates a new workflow, spans multiple domains, or needs user approval before implementation.

Use a multi-role flow when each role has a distinct artifact. Example: product/prd-planner creates requirements, code/code-engineer implements, and docs/doc-writer updates documentation.

Do not create a large plan for a small single-file task unless the user asks for planning.

Handoff Format

When handing off to a role, include:

Role: <role id>
Reason: <why this role is the smallest useful fit>
Inputs: <files, user request, constraints>
Expected output: <artifact or decision>
Escalation: <when to return to Orchestrator>