linalab-io/lfg

OMO agent hierarchy parity for Grok Build — Full Real Port in Progress.

lfg is a Grok marketplace plugin that ports the complete, authentic production oh-my-openagent (OMO) agent hierarchy and orchestration engine into LFG / Grok Build.

The goal is not a lightweight command demo. The goal is a Grok-native agent operating system with real Sisyphus orchestration, Prometheus planning, Atlas checklist execution, Hephaestus deep work, Sisyphus-Junior category execution, Hyperplan adversarial teams, Boulder + Ralph "never stops" persistence, 5-tier defensive hooks, IntentGate ulw bootstrap, and full Team Mode — powered by Grok models and Grok-native sub-agent spawning.

The canonical implementation is now lfg-native under plugins/lfg/src/agents/, plugins/lfg/bin/, skills, hooks, MCP, and .lfg/ runtime state.

Every first-class agent is expected to use a Grok model. Grok Build native sub-agent spawning is the primary delegation path.

Product Scope

lfg provides an OMO-style runtime surface for Grok Build:

• Agent hierarchy: Sisyphus, Sisyphus-Junior, Prometheus, Hephaestus, Atlas, builtin-agents (plus the full 11 from real OMO)
• Orchestration: task delegation, category routing, dependency waves, hostile critique, lead synthesis, hyperplan 3-round adversarial
• Durable state: Boulder, continuation (Ralph-loop + TodoContinuationEnforcer), mailbox, shared tasklist, notepads, plans, team runtime
• Team execution: tmux-backed local observability plus Grok sub-agent spawning where available
• "Magic" entrypoints: ulw / ultrawork keyword + IntentGate + model-specific Grok preambles
• Quality gates: evidence strings (*=ok), critic review, tests, manual verification, release gates
• Integration surfaces: Grok skills, hooks (5-tier safeCreateHook), MCP tools, CLI wrappers, marketplace metadata

Install Through Grok Marketplace

The intended install path is inside Grok:

1. Open LFG / Grok Build.

2. Open the extensions modal with /plugins.

3. Add the LinaLab marketplace source URL:

   https://raw.githubusercontent.com/islee23520/lfg/main/.grok/plugins/marketplace.json
   

4. Install/add lfg from that marketplace.

5. Enable the plugin.

6. Verify it discovers agent definitions, skills, hooks, MCP server, and runtime helpers.

Marketplace/package identity:

Marketplace: linalab-io
Package:     linalab-io/lfg
Plugin id:   lfg
Repository:  https://github.com/islee23520/lfg
Marketplace source repo: https://github.com/islee23520/lfg.git
Reference:   oh-my-openagent agent hierarchy and orchestration model (full real port)
Current marketplace metadata reference retained for release compatibility: https://github.com/Yeachan-Heo/oh-my-codex

Developer smoke commands live in docs/SMOKE.md. Marketplace installation remains the product path.

Agent Hierarchy

Sisyphus

Main orchestrator. Owns user intent, dispatches specialists, tracks completion, enforces verification, and persists progress through Boulder state. The default lead for ulw.

Sisyphus-Junior

Focused executor spawned by category routing. It executes a bounded task, verifies its own changes, and does not become a second unconstrained orchestrator.

Prometheus

Strategic planner. Interviews, clarifies scope, reads context, and produces a verifiable plan before implementation starts. (Plan-only; hard-reject as team member per eligibility contract.)

Hephaestus

Autonomous deep worker. Receives goals, not recipes. It researches, implements, and verifies difficult work with strong evidence discipline. (Conditional teammate.)

Atlas

Todo-list orchestrator. Reads a plan, executes dependency waves, updates checkboxes, verifies every step, and continues until the checklist is complete.

builtin-agents

Factory and policy layer. Resolves model profile, category, skill availability, overrides, blocked tools, and registration conditions. Enforces the real AGENT_ELIGIBILITY_REGISTRY.

Full 11-Agent Catalog (Phase 2 Ported)

The lfg-native registry starts with Sisyphus, Atlas, Sisyphus-Junior, Hephaestus, Prometheus, and builtin-agents, with legacy named agents kept only for compatibility under plugins/lfg/src/agents/legacy/.

Grok Build Execution Model

lfg maps OMO-style delegation onto Grok Build:

Sisyphus receives request
  ├─ Prometheus plans if scope is non-trivial
  ├─ Atlas executes plan waves
  ├─ Sisyphus-Junior handles category tasks
  ├─ Hephaestus handles autonomous deep goals
  ├─ Hyperplan spawns hostile critics for adversarial planning
  └─ Sisyphus synthesizes, verifies, and advances Boulder

All agent entries resolve to Grok models. Category routing may map to different Grok reasoning levels, but not to non-Grok primary models.

The next integration focus is replacing fallback/manual-gated spawn evidence with verified Grok-native sub-agent spawning while keeping .lfg/ state and agent registry contracts stable.

Full Real OMO Port — Phase 2 Complete (Big Synthesis)

Official Ultragoal: omo-full-real-port-20260518 ("full real OMO as-is, ulw ulw with team mode on").

After a massive 14+ parallel ULW explorer swarm mapped the entire production OMO engine, the Huge Orchestration Team (ULW) executed Phase 2: shipping 7 core modules of portable, high-fidelity logic:

1. Eligibility Contracts (contracts/eligibility.json + team/eligibility.py) — verbatim AGENT_ELIGIBILITY_REGISTRY + hyperplan roster (eligibility-contract-shipped=ok)
2. Agents Catalog (agents/) — all 11 real agents with identities and prompt loading (agent-catalog-impl=ok)
3. Ultrawork IntentGate (ultrawork/) — keyword detection + Grok-4-3 harness preambles + bootstrap (ultrawork-intentgate-impl=ok)
4. BackgroundManager + Tmux Viz (background/) — parallel delegation engine + live visibility (background-manager-impl=ok)
5. 5-Tier Hooks (hooks/) — safeCreateHook + defensive validators (hooks-5tier-impl=ok)
6. Team Runtime (team/) — Hyperplan executor (exact 3-round adversarial + handoff), Mailbox, Tasklist (team-runtime-hyperplan-impl=ok)
7. Config / Doctor / Named Teams (config/) — 3-layer loading, discovery, self-diagnostics, team create hyperplan (doctor-named-teams-impl=ok)

Plus cross-cutting Persistence (persistence/) — Boulder + Ralph-loop + TodoContinuationEnforcer + SYSTEM DIRECTIVE ("never stops until done") — persistence-boulder-ralph-impl=ok

All modules are dependency-light Python, directly portable into ~/.grok/plugins/grok-build/omo/, and exercised with live evidence strings.

"The boulder is moving. The real OMO engine is here."

Runtime Commands

The current CLI is a transition surface while the OMO parity runtime lands. The expected product commands are:

plugins/lfg/bin/lfg status
plugins/lfg/bin/lfg doctor
plugins/lfg/bin/lfg agents list
plugins/lfg/bin/lfg agents inspect sisyphus
plugins/lfg/bin/lfg spawn sisyphus-junior --category quick --task "fix failing smoke"
plugins/lfg/bin/lfg prometheus plan "ship OMO registry"
plugins/lfg/bin/lfg atlas run .lfg/plans/<plan>.md
plugins/lfg/bin/lfg hephaestus goal "port Boulder state"
plugins/lfg/bin/lfg hyperplan "design Grok spawn adapter"
plugins/lfg/bin/lfg team create 3:executor "verify release gates"
plugins/lfg/bin/lfg ulw "build the ultimate autonomous agent swarm"

Existing commands remain useful for development until their semantics are migrated to the OMO runtime paths.

Runtime state is stored under:

.lfg/

Target state layout:

.lfg/
  agents/
  boulder/
  plans/
  teams/
  hyperplan/
  notepads/
  mailbox/
  tasklists/

Team Mode

Team Mode is the durable multi-agent execution surface. It combines OMO mailbox/tasklist semantics with local tmux observability and Grok sub-agent spawning.

Target flow:

/team providers
/team preflight
/team 3:executor "fix the failing tests with verification"
/team status <team-name>
/team resume <team-name>
/team shutdown <team-name>

Equivalent local runtime:

plugins/lfg/bin/lfg team providers
plugins/lfg/bin/lfg team preflight
plugins/lfg/bin/lfg team create 3:executor "fix the failing tests with verification"
plugins/lfg/bin/lfg team status <team-name>
plugins/lfg/bin/lfg team resume <team-name>
plugins/lfg/bin/lfg team shutdown <team-name>

The smoke-safe provider remains noop for dependency-free tests and preflight examples.

Verify

Run dependency-free smoke tests:

Run plugin self-test:

plugins/lfg/bin/self-test.sh

Run real local Grok install/discovery smoke when ~/.grok/bin/grok is available:

plugins/lfg/bin/grok-install-smoke.sh

Run full local release readiness when preparing release:

scripts/verify-release-readiness-local.sh

Run the full local + remote release readiness wrapper before tagging a release; success emits release-readiness-all=ok:

scripts/verify-release-readiness-all.sh

See docs/SMOKE.md, docs/RELEASE_CHECKLIST.md, and docs/TEST_RULES.md for the exact evidence contracts.

Layout

.grok/plugins/marketplace.json           # Grok marketplace metadata
.agents/plugins/marketplace.json         # Agents-compatible marketplace metadata
plugins/lfg/
  .grok-plugin/plugin.json               # Grok plugin manifest
  .claude-plugin/plugin.json             # compatibility manifest
  .mcp.json                              # MCP server config
  src/agents/harness.toml    # agent harness metadata (canonical)
  bin/lfg.py                             # runtime, state, Grok spawn adapter
  bin/lfg                                # default runtime wrapper
  bin/ulw                                # ultrawork launcher wrapper
  bin/lfg-mcp.py                         # stdio JSON-RPC MCP server
  bin/self-test.sh                       # local smoke test
  hooks/hooks.json                       # hook registration
  hooks/scripts/lfg-audit-hook.sh        # fail-open audit hook
  skills/*/SKILL.md                      # Grok slash surfaces backed by OMO semantics

Roadmap

See ROADMAP.md for the M0-M13 OMO parity plan.
See the Full Real OMO Port ultragoal (.lfg/ultragoal/omo-full-real-port-20260518/) and Phase 2 artifacts for the accelerated "as-is" track.
See docs/ARCHITECTURE.md for the agent hierarchy, current runtime implementation ("How LFG actually works with OMO right now"), Grok spawn adapter status, and verification commands.
See docs/AGENTS.md for documentation and evidence rules.

Attribution

Built with oh-my-openagent as the architectural reference for agent hierarchy, orchestration discipline, Boulder/continuation, Team Mode, Hyperplan, Prometheus planning, Atlas checklist execution, and Sisyphus-style persistence. lfg is a separate Grok Build implementation adapted to Grok marketplace, Grok models, skills, hooks, MCP, and .lfg/ state conventions.

ulw ulw with team mode on.