Handbook

Forge micro-agent

A micro-agent is a bounded local-LLM run for a single judgment task (for example one AI UX ruleset rule on a harness fixture). It uses a micro-pack (fixed prompt + manifest), not full Cursor .cursor/rules/, and does not…

Updated 2026-07-26

Definition

A micro-agent is a bounded local-LLM run for a single judgment task (for example one AI UX ruleset rule on a harness fixture). It uses a micro-pack (fixed prompt + manifest), not full Cursor .cursor/rules/, and does not use vector DB or MCP in MVP.

Architecture flow

Micro-agent local LLM path

How the UX harness invokes one bounded local-LLM judgment through workcells, LCDL, and a shared parse gate.

invoke-ai-ruleset-harness.shEntry script selecting --llm for the local workcell executor.
KS auditor glueUX auditor glue analyzes the fixture and assembles governed context.
ux-ai-rule-v1 packMicro-pack provides manifest, prompt.md, and context schema.
forge-workcells local_llm_workerPrivate runner executes one LCDL-backed workcell invocation.
forge-lcdlGoverned transport issues the chat call to the gateway profile.
LLM gateway (LLM_*)Configured gateway performs the inference for the pack prompt.
agent-output.txt --> parse-ai-agent-findings.mjs --> detection gateFindings parse and expect-ai-rule-detection gate complete the harness.

    invoke-ai-ruleset-harness.sh
              |
              | --llm
              v
    +-------------------+     +----------------------+
    | KS auditor glue   |     | ux-ai-rule-v1 pack   |
    | analyze + assemble|---->| manifest + prompt.md |
    +---------+---------+     +----------+-----------+
              | context.json            |
              v                           |
    +-------------------+                 |
    | forge-workcells   |<----------------+
    | local_llm_worker  |
    +---------+---------+
              |
              v
    +-------------------+     +----------------------+
    | forge-lcdl        |---->| LLM gateway (LLM_*)  |
    +-------------------+     +----------------------+
              |
              v
    agent-output.txt --> parse-ai-agent-findings.mjs --> detection gate

Illustrated version: Platform reference architecture §7 and SVG micro-agent-flow.svg.

Components

Piece	Owner	Role
Micro-pack	forgesdlc-kitchensink	`tools/forge-micro-agent/packs/<pack-id>/` — `manifest.yaml`, `prompt.md`, `context-schema.json`
Context assembly	KS `website-ux-auditor`	`ux-assemble-context.mjs` → `context.json` (audit slice + Playwright evidence)
Runner	forge-workcells (private)	Workcell `local_llm_worker` — LCDL chat, writes `micro-agent.log` + model output
Inference	forge-lcdl	`LLM_*` profile via `read_profile_from_env_file`
Contracts	forge-platform	`AgentRun`, `WorkcellRequest`, `WorkcellResult` (pattern); harness parses findings via existing JS

Context budget

Default 32K tokens per pack (max_context_tokens in manifest). Assemblers truncate audit JSON and cap screenshot/crop count.

Harness entry

# Cursor CLI (default when agent on PATH)
./invoke-ai-ruleset-harness.sh --only-rule AI.VISUAL.HIERARCHY

# Local LLM via forge-workcells
./invoke-ai-ruleset-harness.sh --only-rule AI.VISUAL.HIERARCHY \
  --llm --llm-env=/path/to/lcdl.env

Quota: gateway_probe_lcdl.py --env-file when --llm is set (not Cursor QUOTA_OK).

Cursor vs local LLM

Path	Trigger	Executor
Cursor	Default; `agent` on PATH	`run-design-ai-rule.sh` → Cursor CLI
Local LLM	`--llm` / `--llm-env=`	`forge-workcells run --workcell local_llm_worker`

Both paths feed parse-ai-agent-findings.mjs and expect-ai-rule-detection.sh.

Not a DecisionPack workflow

Micro-agent is a single workcell invocation (one pack, one primary LCDL call). Multi-step conditional graphs use forge-lcdl DecisionPack — see Governed workflows and rules.

Out of scope (MVP)

Full .mdc rule loader
Vector DB / RAG
MCP tool orchestration
Multi-rule local-LLM campaign (bootstrap stays --only-rule)
Replacing daily Cursor IDE use

Forge Platform