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…

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

  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