Proposal: Rule-Driven, Modular Chain Mode

[0x01d]

Overview

Introduce a fully modular execution mode in avante.nvim, where users can orchestrate a pipeline using:

• avanterules: prompt templating, task directives, behavior rules.
• avantechain: declarative chain execution logic (e.g. run this step → conditionally continue).

This mode would allow anyone to define powerful, project-specific assistants using just simple configuration and Lua glue — no hardcoding of prompts, agents, models, or flows.

Design Philosophy

• Not all nodes are agents: some steps are just simple inference, while others are minimal Lua functions or wrappers around model calls.
• No built-in agents required: users define their own context-fetchers, editors, or tools based on their needs.
• Minimal Lua exposure: users only write small utility functions when needed — all orchestration handled via .avantechain.
• Composable, rule-driven: workflows follow explicit rules defined in .avanterules — fully deterministic, no surprises.
• Chain branching: next steps can depend on model output or Lua function results, allowing conditional logic in workflows.

Example Use Case

A user wants to:

• Extend behavior from shared .avanterules templates.
• Run a custom Lua function that fetches internal docs based on the prompt.
• Feed the result + prompt into an expensive reasoning model.
• If the model suggests a refactor, apply code- using a cheaper model. Otherwise, do nothing.

This use case:

• Has no built-in “agent”
• Uses minimal Lua glue
• Is fully declarative
• Can be reused or shared across teams by changing .avantechain + .avanterules

Benefits

• Zero hardcoded flows: Everything is opt-in and user-defined.
• Fits large projects: Teams can tailor .avantechain to their internal tooling, docs, and coding style.
• Fast iteration: Swapping chains or templates doesn’t require plugin modification.
• Token-efficient: Prompt steps are reused across chains, minimizing API calls.
• Supports parallel or conditional chains: e.g. run doc and code search in parallel, then route based on combined output.

Key Concepts

• Multiple step types (prompt, agent, code, tool, router, noop)
• Parallel execution where possible
• Dynamic branching based on output of previous steps
• Declarative, minimal-programming user experience
• Tight integration with .avanterules for consistent behavior and persona

---

Concept	Description
Step	A single unit in the chain; can be a prompt, agent, code, tool, router, noop
Chain	A DAG of steps with defined dependencies and data flows
Rules	Behavioral logic in .avanterules files used by prompt and agent steps
Router	Step that dynamically selects next step based on output
Group	Executes multiple steps in parallel

---

Supported Step Types

Type	Description
prompt	Render a prompt using .avanterules blocks and send to LLM
agent	Multi-turn agent behavior controlled by .avanterules
code	Run shell or Lua code with input, return output
builtin-tool	Execute built-in Avante tools (e.g., file replace)
router	Dynamically pick next step based on previous output
noop	Terminal step, does nothing
group	Run multiple steps concurrently

---

Example: docs-and-code-lookup.avantechain

version: "1.0.0"

imports:
  rules:
    - "shared/avanterules/general.avanterules"
  lua:
    - "lua/utils/doc_search.lua"
    - "lua/utils/repo_search.lua"
  chains:
    - "common/generate-terms.avantechain"

chains:

  # ----------------------------------------------------------------
  # Main chain: fetch docs & code, then decide on refactor/apply
  # ----------------------------------------------------------------
  docs-and-code-lookup:
    description: >
      1) In parallel: generate search terms and fetch docs & code.
      2) Merge results, ask LLM if refactor is needed.
      3) If LLM returns a code block, parse and apply patch.
    params:
      user_prompt: string
    entry: parallel-fetch
    steps:

      # 1) run two sub-chains + lookups in parallel
      parallel-fetch:
        type: group
        parallel:
          - fetch-docs
          - fetch-code
        next: merge

      fetch-docs:
        type: run
        chain: generate-terms
        args:
          prompt: "{{user_prompt}}"
        next: docs-search

      docs-search:
        type: run
        cmd: "lua utils.doc_search({{fetch-docs.output}})"
        next: noop

      fetch-code:
        type: run
        chain: generate-terms
        args:
          prompt: "{{user_prompt}}"
        next: code-search

      code-search:
        type: run
        cmd: "lua utils.repo_search({{fetch-code.output}})"
        next: noop

      # 2) merge outputs, ask for refactor suggestion
      merge:
        type: prompt
        rule: merge.sources
        model: gpt-4
        inputs:
          docs: "{{docs-search.output}}"
          code: "{{code-search.output}}"
        next: decide

      decide:
        type: prompt
        rule: refactor.suggestion
        model: gpt-4
        inputs:
          combined: "{{merge.output}}"
        next: parse-route

      # 3) route on presence of a code block fence
      parse-route:
        type: router
        cases:
          - when: contains(decide.output, "```")
            next: extract-code
        default: end

      extract-code:
        type: run
        cmd: "lua utils.parse_code_block({{decide.output}})"
        next: apply-patch

      apply-patch:
        type: run
        cmd: "apply.patch --patch '{{extract-code.output}}'"
        next: end

      end:
        type: noop

Key points in this example:

• Everything is declarative—no ad-hoc Lua or multi-field step definitions.
• You call sub-chains via run.chain instead of retyping prompts.
• Mustache is the only interpolation you learn.
• Router is a tiny, readable DSL for content checks.
• Parallelism is explicit and obvious.

Thanks for reading my idea. Let me know if you are interested in building this out. I think it would be awesome.