conduit

README

Volon — Agentic Development System (v0.5)

This repository (volon-dev) is the private development workspace for Volon. Clean releases are exported via scripts/create-volon.sh and published at hollis-labs/volon. Use this repo for contributor work; use the Volon release repo in downstream projects.

A project-agnostic set of Claude Code plugins, skills, and workflow contracts for high-throughput, low-drift agentic development.

Volon automates the full development lifecycle: Ideation → Requirements → PRD → Spec → Plan → Tasks → Execute (PR/worktree) → QA/Docs → Investigate

Context Service Bootstrap Note

This repo is currently being used to scaffold initial planning artifacts for the Context Memory Service. Bootstrap deliverables are located at:

• docs/ARCHITECTURE.md
• docs/SCOPE.md
• docs/DEV.md
• docs/DECISIONS/
• docs/SPECS/
• outputs/

---

Agent entry points

Starting a Volon session (agents): See CLAUDE.md — contains the boot sequence and copy-paste Inception Run Prompt.

Authoritative boot doc: .agentrc/agent-boot.md — ground truth sources, core rules, reference map.

Current state: .agentrc/bootstrap.md — iteration, active tasks, next actions.

---

What's in this repo

• agentrc.yaml — system configuration
• plugins/ — Claude Code plugins (8 plugins, 22 skills)
• docs/ — system specs (config, PCC, workflow contracts, task model, orchestrator, inception)
• .agentrc/ — runtime state (bootstrap, PCC, tasks, logs, boot pack)
• examples/ — sample configs and workflow traces
• user-docs-mini-site/ — static user-facing documentation site

Key capabilities (v0.5 — all epics complete)

• Project Context Cache (PCC) — low-token, repo-local agent context
• Inception workflow (/workflow-inception) — canonical self-building loop
• Full workflow lifecycle — new-feature, docs-review, app-investigation, extension authoring
• Workflow authoring — create/edit/clone/deprecate workflows from within Volon
• Task + backlog management — file-based tasks, priority-ordered execution
• Git integration — worktrees, PR mode, commit-per-task or commit-per-iteration
• Pause/resume — deterministic state externalization; any session can restart cleanly
• Quality scans — correctness, security, dead code, performance smells
• Bootstrap boundaries — every iteration ends with a clean, restartable state file

Quick start (loading plugins)

Run the helper script (keeps this volon-dev repo up to date, then launches Claude with every plugin registered):

./scripts/volon-cli.sh --repo /path/to/target-repo

• Set FORGE_NO_SYNC=1 to skip the git fetch/pull step.
• Override the Claude binary with CLAUDE_BIN=/path/to/claude.
• The --repo flag is handled by the script (it cds into that path before launching). Pass additional Claude args after --, e.g. ./scripts/volon-cli.sh --repo /path -- --model claude-sonnet-4-6.

Manual invocation (equivalent, shown for reference):

claude \
  --plugin-dir /path/to/volon/plugins/core \
  --plugin-dir /path/to/volon/plugins/workflows \
  --plugin-dir /path/to/volon/plugins/git \
  --plugin-dir /path/to/volon/plugins/docsmith \
  --plugin-dir /path/to/volon/plugins/quality \
  --plugin-dir /path/to/volon/plugins/backlog \
  --plugin-dir /path/to/volon/plugins/workflow-author \
  --plugin-dir /path/to/volon/plugins/prompt-volon

Then in a target repo with agentrc.yaml (copy it from the Volon release repo):

/workflow-inception          # run the canonical self-building loop
/workflow-new-feature "..."  # full ideation → tasks pipeline
/workflow-docs-review        # PCC-grounded documentation scan
/quality-run                 # correctness / security / dead-code / perf scan

Docs

• docs/13_inception-workflow.md — the canonical loop
• docs/08_orchestrator.md — Orchestrator mode
• docs/volon-template.md — clean template/export + release steps
• docs/01_config.md — configuration reference
• docs/03_workflow-contracts.md — workflow execution contracts
• docs/04_task-model.md — task model
• docs/09_commands.md — all available commands
• docs/MCP_TOOLS.md — agent-facing MCP tool catalog (per-domain tools, scopes, playbooks)
• CHANGELOG.md — release history; consumers (Nanite et al.) watch this for new tools/routes
• docs/RELEASE.md — versioning + release-cut procedure /notes
• go build ./cmd/volon currently emits the CLI binary (prints “Volon” in usage/output). The path will move to cmd/volon once the module rename (TASK-20260224-010) lands.
• Use Go modules directly: go install github.com/hollis-labs/volon-dev/cmd/volon@latest (or @<tag>) to install the binary globally.
• When preparing a release, run scripts/create-volon.sh --target ~/Projects-apps/volon and push that clean repo to hollis-labs/volon (see docs/volon-template.md).

Repository layout

• volon-dev/ — private development repo (this project). Remote will move to github.com/hollis-labs/volon-dev after the rename (see docs/volon-dev.md).
• volon/ — clean release repo (exported via scripts/create-volon.sh and pushed to github.com/hollis-labs/volon).

Migrating from legacy Forge layout

If you cloned an older revision that still had forge.yaml and .forge/, run:

scripts/migrate-to-volon.sh

This renames the config/state to agentrc.yaml + .agentrc/. Then rerun scripts/volon-cli.sh /bootstrap-update to regenerate bootstrap state.

Documentation

Index

• Variables
• func NewEmbedHandler(memStore *memory.Store, model string, logger func(string, ...any)) queue.Handler
• type Conduit
  • func Open(ctx context.Context, cfg Config, opts ...Option) (*Conduit, error)
  • func (c *Conduit) Close() error
  • func (c *Conduit) Embed(ctx context.Context, recordID string) error
  • func (c *Conduit) EmbedRevision(ctx context.Context, revisionID string) error
  • func (c *Conduit) GetCurrentRevision(ctx context.Context, namespace, key string) (memory.Revision, error)
  • func (c *Conduit) GetRevisionHistory(ctx context.Context, namespace, key string) ([]memory.Revision, error)
  • func (c *Conduit) MemoryStore() *memory.Store
  • func (c *Conduit) RecallMemory(ctx context.Context, in memory.RecallInput) ([]memory.RecallResult, error)
  • func (c *Conduit) Search(ctx context.Context, query string, opts SearchOptions) ([]embedding.SearchResult, error)
  • func (c *Conduit) Store() *contextstore.Store
  • func (c *Conduit) WriteMemory(ctx context.Context, in memory.WriteInput) (memory.Revision, error)
• type Config
• type Option
  • func WithDedupThreshold(t float64) Option
  • func WithEmbedder(e embedcontracts.Embedder) Option
  • func WithEmbeddingModel(model string) Option
  • func WithLogger(fn func(string, ...any)) Option
  • func WithQueue(q queue.Queue) Option
• type SearchOptions

Variables

var ErrEmbedderUnavailable = errors.New("embedder unavailable")

ErrEmbedderUnavailable is returned when an embedding operation is attempted but no embedder has been configured on the Conduit instance.

Functions

func NewEmbedHandler

func NewEmbedHandler(memStore *memory.Store, model string, logger func(string, ...any)) queue.Handler

NewEmbedHandler returns a queue.Handler that processes embed jobs. The handler decodes the revision ID from the job payload and calls EmbedRevision on the memory store to generate and persist the embedding.

Types

type Conduit

type Conduit struct {
	// contains filtered or unexported fields
}

Conduit is the top-level library handle. Create one via Open().

func Open

func Open(ctx context.Context, cfg Config, opts ...Option) (*Conduit, error)

Open creates a Conduit instance rooted at cfg.RootDir, initializing the SQLite store, memory subsystem, and decay goroutine.

func (*Conduit) Close

func (c *Conduit) Close() error

Close stops the decay goroutine and closes the underlying store.

func (*Conduit) Embed

func (c *Conduit) Embed(ctx context.Context, recordID string) error

Embed generates and stores a vector embedding for the record identified by recordID. It fetches the record from the store, extracts embeddable text, calls the configured embedder, and upserts the resulting vector.

func (*Conduit) EmbedRevision

func (c *Conduit) EmbedRevision(ctx context.Context, revisionID string) error

EmbedRevision generates and stores an embedding for a memory revision.

func (*Conduit) GetCurrentRevision

func (c *Conduit) GetCurrentRevision(ctx context.Context, namespace, key string) (memory.Revision, error)

GetCurrentRevision returns the current revision for a namespace/key pair.

func (*Conduit) GetRevisionHistory

func (c *Conduit) GetRevisionHistory(ctx context.Context, namespace, key string) ([]memory.Revision, error)

GetRevisionHistory returns all revisions for a namespace/key pair, newest first.

func (*Conduit) MemoryStore

func (c *Conduit) MemoryStore() *memory.Store

MemoryStore returns the underlying memory.Store.

func (*Conduit) RecallMemory

func (c *Conduit) RecallMemory(ctx context.Context, in memory.RecallInput) ([]memory.RecallResult, error)

RecallMemory retrieves memories by namespace, ranking, and filters.

func (*Conduit) Search

func (c *Conduit) Search(ctx context.Context, query string, opts SearchOptions) ([]embedding.SearchResult, error)

Search embeds the query string and returns the top matching records ranked by cosine similarity against all stored embeddings for the configured model.

func (*Conduit) Store

func (c *Conduit) Store() *contextstore.Store

Store returns the underlying contextstore.Store.

func (*Conduit) WriteMemory

func (c *Conduit) WriteMemory(ctx context.Context, in memory.WriteInput) (memory.Revision, error)

WriteMemory writes a new memory revision.

type Config

type Config struct {
	RootDir string
}

Config holds the top-level configuration for a Conduit instance.

type Option

type Option func(*options)

Option is a functional option for Open.

func WithDedupThreshold

func WithDedupThreshold(t float64) Option

WithDedupThreshold sets the similarity threshold for semantic dedup.

func WithEmbedder

func WithEmbedder(e embedcontracts.Embedder) Option

WithEmbedder sets the embedding provider used for vector indexing.

func WithEmbeddingModel

func WithEmbeddingModel(model string) Option

WithEmbeddingModel sets the model name passed to the embedder.

func WithLogger

func WithLogger(fn func(string, ...any)) Option

WithLogger sets a custom log function (defaults to log.Printf).

func WithQueue

func WithQueue(q queue.Queue) Option

WithQueue sets the background job queue used for async embedding. When set, a worker is started automatically and a QueueAdapter is used instead of the default NoopQueue.

type SearchOptions

type SearchOptions struct {
	Limit      int
	Threshold  float64
	Namespaces []string
	Types      []string
}

SearchOptions controls the behavior of a Search call.