Related Pages

Related topics: Hecateq Orchestration Pipeline, Memory System and Context Injection

Overview and Plugin Architecture

Hecateq OpenAgent (v0.1.0-hecateq.1, beta) is a production-grade fork of oh-my-openagent designed to plug into the Hecateq agentic workflow engine that runs inside OpenCode. The repository is organized as a TypeScript monorepo: a top-level plugin/CLI binary plus a collection of internal packages that each own a single concern (LSP tooling, rules, model resolution, state, web UI). The release notes advertise task-graph orchestration, self-healing memory management, and validation safeguards as headline features, all of which are layered on top of the same plugin surface the upstream project exposes.

Monorepo Layout and Public Surface

The root package.json declares the public entry points for downstream consumers, published under the beta npm tag (Source: package.json:1-50):

The root build pipeline stitches together the ast-grep-mcp package, the main Bun entry (src/index.ts), a Node require shim, and the JSON schema generator, then runs tsc --emitDeclarationOnly to produce .d.ts files (Source: package.json:51-90). A separate build:lsp-tools-mcp script delegates into the packages/lsp-tools-mcp workspace so the LSP runtime is rebuilt in lockstep with the plugin (Source: package.json:91-130).

Internal packages share a common shape (packages/*):

• packages/lsp-tools-mcp — standalone LSP-over-MCP server (see below).
• packages/model-core — canonical model identifiers, fallback chains, capability resolution.
• packages/rules-engine — discovery and priority resolution for project/user rule files.
• packages/ast-grep-mcp, packages/comment-checker-core, packages/hashline-core, packages/boulder-state, packages/agents-md-core, packages/utils — supporting libraries, each gated behind its own tsconfig.json and typechecked individually by the root typecheck script (Source: package.json:131-180).
• packages/web — Next.js 15 / React 19 dashboard deployed to Cloudflare via opennextjs-cloudflare (Source: packages/web/package.json:1-60).

LSP Tools MCP Subsystem

packages/lsp-tools-mcp is the upstream source of truth for two downstream plugins (codex-lsp and oh-my-openagent), both of which consume it as a git submodule rather than forking the runtime (Source: packages/lsp-tools-mcp/README.md:1-30). The package ships as a stdio MCP server with the binary name lsp-tools-mcp pointing at ./dist/cli.js (Source: packages/lsp-tools-mcp/package.json:1-40).

The runtime exposes tools such as lsp_diagnostics, lsp_goto_definition, lsp_find_references, lsp_symbols, lsp_prepare_rename, lsp_rename, and lsp_status (Source: packages/lsp-tools-mcp/README.md:31-60). Internally, file extensions are normalized to LSP language IDs through a hand-maintained table covering common ecosystems (TypeScript, Python, Rust, Go, Ruby, Zig, etc.) (Source: packages/lsp-tools-mcp/src/lsp/language-mappings.ts:1-60). Strongly-typed LSP wire types — Diagnostic, TextEdit, WorkspaceEdit, PrepareRenameResult, and the SeverityFilter union — live alongside the runtime so refactors stay type-safe end-to-end (Source: packages/lsp-tools-mcp/src/lsp/types.ts:1-60).

flowchart LR
  Agent[OpenCode Agent] -- "stdio MCP" --> Server[lsp-tools-mcp]
  Server -- "LSP wire protocol" --> Backend[Language Servers]
  Backend -- "diagnostics / symbols / edits" --> Server
  Server -- "typed JSON" --> Agent

Model Resolution and Capability Layer

The model-core package owns the policy that decides which provider/model pair an agent actually uses at runtime. It re-exports everything needed by callers: resolveModel, resolveModelWithFallback, normalizeFallbackModels, flattenToFallbackModelStrings, capability heuristics, alias maps, sanitizers, and error classifiers (Source: packages/model-core/src/index.ts:1-50).

Three contracts sit at the center of the layer:

1. DelegatedModelConfig captures the per-call knob set (provider, model, variant, reasoning effort, temperature, top_p, maxTokens, thinking) (Source: packages/model-core/src/model-resolution-types.ts:1-40).
2. ModelResolutionRequest carries intent, constraints.availableModels, and an optional policy.fallbackChain plus systemDefaultModel (Source: packages/model-core/src/model-resolution-types.ts:41-70).
3. ModelResolutionResult returns the chosen model plus a provenance tag ("override" | "category-default" | "provider-fallback" | "system-default") and an attempted trail for diagnostics (Source: packages/model-core/src/model-resolution-types.ts:71-90).

Fallback chains are expressed as ordered FallbackEntry lists of { providers, model, variant } triples. For example, the unspecified-low category tries Anthropic Claude Sonnet 4.6 first, then gpt-5.3-codex, then Kimi K2.6, Gemini 3 Flash, and a MiniMax fallback (Source: packages/model-core/src/model-requirements.ts:1-60). Recognized variant tokens are centralized in KNOWN_VARIANTS (low, medium, high, xhigh, max, minimal, none, auto, thinking) so parsers and flatten helpers agree on what counts as an effort suffix (Source: packages/model-core/src/known-variants.ts:1-12).

getModelCapabilities produces a ModelCapabilitiesDiagnostics block that tags every field with its resolution source — "runtime", "override", "heuristic", "snapshot", or "none" — making it possible to debug why a particular model ends up reasoning-capable or not (Source: packages/model-core/src/model-capabilities/get-model-capabilities.ts:1-90).

Rules Engine and Project Discovery

The rules-engine package supplies the discovery layer that locates rule files in a project and ranks them by provenance. Constants cover:

• Project markers used to detect repository roots: .git, pyproject.toml, package.json, Cargo.toml, go.mod, .venv (Source: packages/rules-engine/src/constants.ts:1-15).
• Rule subdirectories consulted in order — .omo/rules, .claude/rules, .cursor/rules, .github/instructions, .sisyphus/rules — plus the standalone .github/copilot-instructions.md file (Source: packages/rules-engine/src/constants.ts:16-40).
• User-level rule directories under the home folder, mirroring the project set with priority offsets (Source: packages/rules-engine/src/constants.ts:41-60).
• SOURCE_PRIORITY as a ReadonlyMap<RuleSource, number> that gives project-local rules priority 0–5 and user-level rules priority 100–103 (Source: packages/rules-engine/src/constants.ts:61-90).
• EXCLUDED_DIRS (node_modules, .git, dist, build, .turbo, .next, coverage) and the canonical AGENTS.md filename (Source: packages/rules-engine/src/constants.ts:91-110).

Extension Points for Downstream

Two patterns make the architecture extendable without forking the runtime:

• Git submodule consumption for the LSP runtime — fixes or features land upstream in code-yeongyu/lsp-tools-mcp and are pulled in via a submodule pointer bump (Source: packages/lsp-tools-mcp/README.md:1-20).
• Schema-tagged configuration — the root package exports both the upstream oh-my-opencode.schema.json and a Hecateq-specific hecateq-openagent.schema.json, letting forks carry their own config keys without colliding with upstream (Source: package.json:20-50).

Together, these choices keep the plugin surface narrow (one entry, two schema variants, one LSP binary) while letting internal packages evolve independently behind their own tsconfig.json boundaries.

See Also

• LSP Tools MCP runtime: packages/lsp-tools-mcp/README.md
• Model requirements and fallback chains: packages/model-core/src/model-requirements.ts
• Rules engine discovery constants: packages/rules-engine/src/constants.ts
• Model resolution pipeline: packages/model-core/src/model-resolution-types.ts
• Build and typecheck pipeline: package.json

Related Pages

Related topics: Overview and Plugin Architecture, Memory System and Context Injection, CLI Commands and Doctor Diagnostics

Hecateq Orchestration Pipeline

Overview and Purpose

The Hecateq Orchestration Pipeline is the coordinating layer that turns a user request submitted to OpenCode into a routed, capability-aware, and rule-governed multi-model execution. It is the defining addition in the Hecateq fork of oh-my-openagent, packaged and distributed as @hecateq/hecateq-openagent (entry point ./dist/index.js, registered as the OpenCode plugin through @opencode-ai/plugin).

Source: package.json

The pipeline is implemented as a set of cooperating workspaces rather than a single monolith. The workspaces field in package.json declares nine internal packages (rules-engine, ast-grep-core, ast-grep-mcp, utils, model-core, comment-checker-core, hashline-core, boulder-state, agents-md-core) that together provide the capabilities required to plan, route, and supervise an agent run. Cross-cutting policy is enforced through a single overrides block for hono, express-rate-limit, fast-uri, and path-to-regexp, indicating the plugin runs alongside an HTTP layer.

Source: package.json

Architecture

flowchart LR
    User[User Request in OpenCode] --> Plugin[hecateq-openagent Plugin Entry]
    Plugin --> Rules[Rules Engine<br/>project + user rules]
    Plugin --> Resolver[Model Resolution Pipeline<br/>model-core]
    Rules --> Planner[Task Categorization]
    Resolver --> Planner
    Planner --> Fallback[Fallback Chain<br/>per category]
    Fallback --> LSP[LSP Tools MCP<br/>diagnostics/rename/symbols]
    Fallback --> AST[ast-grep MCP<br/>pattern match/replace]
    Fallback --> Mem[Boulder State<br/>self-healing memory]
    Fallback --> Result[Structured Output]

The entry point exposes both a default export and a ./server export, while ./schema.json is bundled for configuration validation. The CLI is shipped under three alias names — hecateq-openagent, oh-my-opencode, and oh-my-openagent — all pointing at bin/oh-my-opencode.js, with platform-specific binaries provided as optional dependencies (linux-x64, linux-x64-baseline, windows-x64, windows-x64-baseline).

Source: package.json

Model Resolution and Capability Routing

At the heart of the pipeline is model-core, which exports the resolution surface used to pick the right model for each agent category. The barrel file in packages/model-core/src/index.ts re-exports model-requirements, model-resolver, model-capabilities, model-capability-heuristics, context-limit-resolver, and related helpers such as resolveModel, resolveModelWithFallback, normalizeFallbackModels, and flattenToFallbackModelStrings.

Each agent role — including the Hecateq-specific hecateq-planner — has a ModelRequirement with a fallbackChain. The planner first tries gpt-5.4 across openai/github-copilot/opencode/vercel, then claude-sonnet-4-6 across anthropic/github-copilot/opencode/vercel, then qwen3.7-plus via opencode-go, kimi-k2.6 via opencode-go/vercel, and finally big-pickle on opencode. Category-level requirements such as visual-engineering add a variant qualifier (gemini-3.1-pro with variant: "high", claude-opus-4-7 with variant: "max"), letting the pipeline tune reasoning effort per task type.

Source: packages/model-core/src/model-requirements.ts

When a model is invoked, get-model-capabilities.ts resolves its real capabilities through a layered lookup: runtime metadata first, then ModelCapabilityOverride, then the heuristic family registry, and finally the bundled snapshot. Every field is tagged with a diagnostic source ("runtime" | "override" | "heuristic" | "snapshot" | "none"), which is critical for the pipeline's self-healing posture — when a value comes from "heuristic" or "unknown", downstream stages can flag uncertainty.

Source: packages/model-core/src/model-capabilities/get-model-capabilities.ts

The heuristic registry encodes which reasoning controls apply to which model family without requiring a live snapshot. claude-opus advertises variants low|medium|high|max with supportsThinking: true; openai-reasoning covers o1/o3/o4 style identifiers with the standard reasoning-effort ladder; gpt-5 adds xhigh and max efforts; and a gpt-legacy family captures everything else under the gpt prefix. This lets the orchestrator pick the correct variant argument for ModelRequirement lookups even when the provider's snapshot is missing.

Source: packages/model-core/src/model-capability-heuristics.ts

The capability record itself (ModelCapabilities) is the contract between the resolver and the executor. It carries family, variants, reasoningEfforts, reasoning, supportsThinking, supportsTemperature, supportsTopP, maxOutputTokens, toolCall, and modalities, together with a diagnostics block that traces the origin of every field. Inputs to the resolver are providerID, modelID, an optional runtimeModel, an optional runtimeSnapshot, a bundledSnapshot, and an optional providerCache.

Source: packages/model-core/src/model-capabilities/types.ts

Rules Engine and Tool Surface

The orchestration pipeline binds model selection to project context via the rules-engine. Rule sources are ordered by an explicit SOURCE_PRIORITY map: .omo/rules (0) wins over .claude/rules (1), .cursor/rules (2), .github/instructions (3), .github/copilot-instructions.md (4), and .sisyphus/rules (5). User-level directories are pushed to 100+ (~/.omo/rules → 100, ~/.opencode/rules → 101, ~/.claude/rules → 102), preventing global rules from silently overriding project policy. The loader walks project markers (pyproject.toml, Cargo.toml, go.mod, .venv, …), respects EXCLUDED_DIRS (node_modules, .git, dist, build, .turbo, .next, coverage), and recognizes filenames AGENTS.md plus .instructions.md patterns.

Source: packages/rules-engine/src/constants.ts

The orchestrator surfaces two MCP tool tiers to its agents. Tier 1, supplied by lsp-tools-mcp, exposes lsp_diagnostics, lsp_goto_definition, lsp_find_references, lsp_symbols, lsp_prepare_rename, lsp_rename, and lsp_status. The package's own README documents that downstream plugins (codex-lsp, oh-my-openagent) consume it as a git submodule so the runtime stays in one place. Language identification is driven by the extension table in language-mappings.ts, which maps .ts/.tsx to TypeScript, .py/.pyi to Python, .rs to Rust, and so on, with makefile (no extension) and Rakefile-style entries handled separately.

Source: packages/lsp-tools-mcp/README.md Source: packages/lsp-tools-mcp/src/lsp/language-mappings.ts

Tier 2, supplied by ast-grep-mcp, exposes pattern-aware code search and rewrite. The MCP handler advertises find and replace tools with strict JSON Schema inputs (pattern, lang, optional paths/globs/context, and rewrite + dryRun for replace). Invalid requests are rejected with JSON-RPC error -32600 Invalid Request, ensuring the orchestrator cannot pass malformed tool calls into the agent loop.

Source: packages/ast-grep-mcp/src/mcp.ts

Operational Notes and Common Failure Modes

Source: package.json Source: packages/model-core/src/model-capabilities/get-model-capabilities.ts

The pipeline's "self-healing memory management" mentioned in the v0.1.0-hecateq.1 release notes is realized through boulder-state's deterministic state model combined with the capability diagnostics block, which lets the orchestrator downgrade gracefully when a heuristic is used in place of a confirmed snapshot. "Robust validation safeguards" correspond to the strict JSON Schema on MCP tools and the Zod-backed configuration schema exported as ./schema.json.

See Also

• package.json — workspaces, dependencies, and CLI aliases.
• packages/model-core/src/index.ts — barrel exports for the resolution pipeline.
• packages/rules-engine/src/constants.ts — rule source priorities and project markers.
• packages/lsp-tools-mcp/README.md — Tier-1 LSP tool inventory and downstream usage.

Related Pages

Related topics: Hecateq Orchestration Pipeline, CLI Commands and Doctor Diagnostics

Memory System and Context Injection

Overview

Hecateq OpenAgent is a customized fork of oh-my-openagent designed to operate inside the Hecateq agentic workflow engine within OpenCode. The v0.1.0-hecateq.1 release introduces "self-healing memory management" together with advanced task graph orchestration, but the repository exposes the supporting context-injection substrate through several distinct, well-bounded subsystems rather than a single monolithic memory module.

Three subsystems visible in the source tree contribute directly to how context is discovered, shaped, and routed into agent invocations:

Each subsystem is independently consumable, and together they form the practical "memory" layer that agents query at runtime.

Rules Engine: Project and User Rule Discovery

The rules engine is the closest analogue to a memory bootstrap step because it walks the filesystem to discover what context an agent should inherit before any reasoning begins. Project markers, rule subdirectories, and source priorities are all defined as readonly constants so that every consumer agrees on ordering.

Source: packages/rules-engine/src/constants.ts:3-5

• PROJECT_MARKERS enumerates the directory markers that identify a project root, including .git, pyproject.toml, package.json, Cargo.toml, go.mod, and .venv.

Source: packages/rules-engine/src/constants.ts:7-13

• PROJECT_RULE_SUBDIRS lists the well-known subdirectories searched for rule files: .omo/rules, .claude/rules, .cursor/rules, .github/instructions, and .sisyphus/rules.
• PROJECT_RULE_FILES registers .github/copilot-instructions.md as a single-file rule source.
• OPENCODE_USER_RULE_DIRS adds .omo/rules, .opencode/rules, and .sisyphus/rules for user-scope rules.
• RULE_EXTENSIONS constrains loader behaviour to .md and .mdc.

Source: packages/rules-engine/src/constants.ts:23-31

• SOURCE_PRIORITY assigns numeric precedence to each rule source. Project-scope sources occupy priorities 0–5, while user-scope sources occupy 100–103, ensuring that explicit project rules win ties over ambient user rules.

Excluded directories (node_modules, .git, dist, build, .turbo, .next, coverage) are pruned from traversal so that the rules walk does not waste I/O on build output. Source: packages/rules-engine/src/constants.ts:17

Model Core: Capability and Variant Context

While the rules engine decides *what text* enters the prompt, the model core decides *which model* consumes that prompt and which capability flags travel with the request. The package re-exports a single barrel that downstream agents import. Source: packages/model-core/src/index.ts:1-50

flowchart LR
  A[Agent Request] --> B[Model Resolution Pipeline]
  B --> C{Available Models?}
  C -- yes --> D[Match Provider/Model]
  C -- no --> E[Apply Fallback Chain]
  D --> F[Apply Heuristic Capabilities]
  E --> F
  F --> G[DelegatedModelConfig]
  G --> H[Provider Call]

The core data contract is DelegatedModelConfig, which carries the resolved providerID, modelID, optional variant, reasoningEffort, temperature, top_p, maxTokens, and a thinking toggle. Source: packages/model-core/src/model-resolution-types.ts:3-12

ModelResolutionRequest distinguishes three intent inputs — uiSelectedModel, userModel, and categoryDefaultModel — alongside an availableModels set constraint, while ModelResolutionResult tags the answer with a provenance of "override" | "category-default" | "provider-fallback" | "system-default". This provenance acts as a small memory trace explaining *why* a particular model was chosen. Source: packages/model-core/src/model-resolution-types.ts:14-39

When no override is available, heuristic families fill the capability gap. The registry encodes per-family patterns and aliases: for example, gpt-5 declares variants low, medium, high, xhigh and reasoning efforts none, minimal, low, medium, high, xhigh, max. Source: packages/model-core/src/model-capability-heuristics.ts:5-21

Canonical variant tokens are kept in a single readonly set so that the parser, fallback flattener, and capability resolver all agree on what counts as a known effort level. Source: packages/model-core/src/known-variants.ts:1-13

export const KNOWN_VARIANTS = new Set([
  "low", "medium", "high", "xhigh", "max",
  "minimal", "none", "auto", "thinking",
])

LSP Tools MCP: Live Language Context

The LSP tools package is registered as a Tier-1 stdio MCP server and exposes language-server queries as agent-callable tools, supplying the *dynamic* half of context injection (fresh editor state rather than static rules). Source: packages/lsp-tools-mcp/README.md:1-15

The tool surface, defined through the LspMcpTool interface, standardizes execution, schema, and structured error reporting. Source: packages/lsp-tools-mcp/src/tools.ts:11-19

Diagnostic results carry severity, mode (file or directory), totalDiagnostics, and a truncated flag, plus a structured errorKind so an agent can decide whether to fall back to a different context provider. Source: packages/lsp-tools-mcp/src/tools.ts:21-29

Integration: Composing the Context Layer

At runtime, an agent turn in OpenCode typically composes context as follows:

1. The rules engine injects static markdown rules discovered under the priority ladder.
2. The model resolver picks a model and capability flags, recording provenance in the result.
3. The agent optionally invokes lsp_* tools to enrich the prompt with fresh diagnostics and symbol maps.

This decomposition keeps each concern testable in isolation — packages/model-core/src/model-requirements.test.ts validates fallback-chain ordering, while the LSP package ships its own vitest suite — and means that "self-healing memory" surfaced in the release notes can rely on a deterministic, contract-driven substrate rather than implicit globals.

See Also

• Rules Engine
• Model Resolution Pipeline
• LSP Tools MCP
• Task Graph Orchestration

Related Pages

Related topics: Hecateq Orchestration Pipeline, Memory System and Context Injection

CLI Commands and Doctor Diagnostics

Overview

Hecateq OpenAgent exposes its functionality through a layered set of command-line entry points and built-in diagnostic machinery. The root package.json declares an ESM-only CLI whose default export targets the OpenAgent plugin runtime, and it also wires up auxiliary build targets for a TypeScript Language Server Protocol (LSP) MCP server and a JSON Schema artifact (hecateq-openagent.schema.json). Source: package.json.

The CLI surface area is intentionally minimal at the top level: the package ships a bin entry for the LSP MCP runtime (a standalone lsp-tools-mcp binary) and exposes both the plugin entry (./dist/index.js) and a server entry (./server) for embedding. The scripts field defines a deterministic build pipeline that compiles the plugin, the LSP runtime, and the schema in a single command (bun run build). Source: package.json.

LSP Tools MCP Command

The lsp-tools-mcp package is the user-facing CLI for LSP-backed code intelligence. It is published as a separate npm package (@code-yeongyu/lsp-tools-mcp) and is consumed by downstream plugins such as oh-my-openagent via a git submodule. Source: packages/lsp-tools-mcp/README.md.

The CLI is a stdio-based Model Context Protocol (MCP) server. Its only supported subcommand is mcp, which starts the server and waits for JSON-RPC messages on stdin. Source: packages/lsp-tools-mcp/README.md. The package's bin field maps the lsp-tools-mcp command to ./dist/cli.js, and the files whitelist keeps the distribution minimal (only dist/, LICENSE, NOTICE, README.md, and CHANGELOG.md). Source: packages/lsp-tools-mcp/package.json.

flowchart LR
    A[User Agent] -->|stdio JSON-RPC| B[lsp-tools-mcp CLI]
    B --> C[tools.ts handlers]
    C --> D[src/lsp runtime]
    D -->|spawn| E[Language Server]
    E --> D --> C --> A

The runtime maps a wide range of file extensions to canonical LSP language identifiers (e.g. .ts → typescript, .py → python, .rs → rust, .tf → terraform) via getLanguageId, ensuring the correct server is selected per document. Source: packages/lsp-tools-mcp/src/lsp/language-mappings.ts.

Exposed MCP Tools

The MCP server registers a fixed set of tool handlers, each with both a canonical name and an lsp_* alias for compatibility with downstream plugins. Source: packages/lsp-tools-mcp/src/tools.ts. The diagnostic-relevant tool is lsp_diagnostics (alias of diagnostics), which surfaces LSP Diagnostic records — range, optional severity, code, source, and message — as defined in the runtime type definitions. Source: packages/lsp-tools-mcp/src/lsp/types.ts.

Source: packages/lsp-tools-mcp/src/tools.ts.

Configuration and Path Overrides

By default the LSP client reads .codex/lsp-client.json for project-level configuration and ~/.codex/lsp-client.json for user-level configuration. Two environment variables allow downstream consumers to redirect these paths — LSP_TOOLS_MCP_PROJECT_CONFIG and LSP_TOOLS_MCP_USER_CONFIG. The README documents that oh-my-openagent uses LSP_TOOLS_MCP_PROJECT_CONFIG=.opencode/lsp.json to integrate with OpenCode. Source: packages/lsp-tools-mcp/README.md.

A minimal configuration file declares one LSP entry per language:

{
  "lsp": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx", ".js", ".jsx"]
    }
  }
}

Source: packages/lsp-tools-mcp/README.md.

Model Capabilities as a Doctor-Style Diagnostic

Hecateq OpenAgent treats model capability resolution as a transparent, multi-source diagnostic process. The getModelCapabilities function returns a ModelCapabilities record that, alongside each field, includes a diagnostics block enumerating the source of every resolved value — runtime, override, heuristic, snapshot, or none. Source: packages/model-core/src/model-capabilities/get-model-capabilities.ts.

This design lets a "doctor" command or operator inspect why a given model behaved a certain way. For example, variants.source reports whether the list of supported variants came from runtime metadata, an explicit override, a heuristic family match, or was unavailable. The same applies to reasoningEfforts, supportsThinking, supportsTemperature, supportsTopP, and maxOutputTokens. Source: packages/model-core/src/model-capabilities/get-model-capabilities.ts.

The shape of the override is fixed via ModelCapabilityOverride, allowing operators to pin variants, reasoningEfforts, supportsThinking, supportsTemperature, or supportsTopP to known-good values when the runtime is uncertain. Source: packages/model-core/src/model-capabilities/types.ts.

The set of canonical variant tokens that the resolver recognises is intentionally small and is shared between the parser and the flattener to keep agent-to-model mapping consistent. Source: packages/model-core/src/known-variants.ts.

Rule Discovery Constants

The rules-engine package encodes the search order and source priority for project rules, which is useful for diagnostic commands that want to report "which rules were loaded and from where". SOURCE_PRIORITY assigns a numeric weight to each rule source, with ~/.opencode/rules ranking at priority 101 and ~/.claude/rules at 102, ensuring deterministic precedence when multiple sources define the same rule. Source: packages/rules-engine/src/constants.ts.

PROJECT_MARKERS lists the files whose presence signals a project root (.git, pyproject.toml, package.json, Cargo.toml, go.mod, .venv), and EXCLUDED_DIRS enumerates directories that should never be traversed during rule discovery (node_modules, .git, dist, build, .turbo, .next, coverage). A doctor command can reuse these constants to explain why a particular rules file was or was not picked up. Source: packages/rules-engine/src/constants.ts.

See Also

• Hecateq OpenAgent README and schema
• LSP Tools MCP upstream
• oh-my-openagent — downstream consumer of the LSP runtime
• Model capabilities resolution
• Rules engine constants

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/hecateq/hecateq-openagent

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/hecateq/hecateq-openagent

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/hecateq/hecateq-openagent

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/hecateq/hecateq-openagent

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/hecateq/hecateq-openagent

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/hecateq/hecateq-openagent

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/hecateq/hecateq-openagent

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using hecateq-openagent with real data or production workflows.

• Configuration risk requires verification - GitHub / issue