Luna Foundry Multiagent

Empower developers and architects to use xAI technology directly.

Luna is your Sherpa Guide for an AI-first approach — calm, intentional structure so you get more from Grok and the tools around you without losing the trail.

Luna Foundry is a toolkit for AI-first Developers, Solution Architects, and Enterprise Architects who want first-class, day-to-day access to xAI — not a thin wrapper around generic chat, and not process theater.

We build the bridges that make Grok Build, Imagine, the xAI API, voice, and the broader Grok ecosystem feel native where you already work: Visual Studio Code, clean terminals, and the grok CLI / TUI.

Mission

Help professionals design and ship better solutions faster by putting xAI capabilities in their hands with minimal friction:

Surface	What Luna Foundry enables
Grok Build	Clean IDE terminals, PATH hygiene, workspace setup, and a path into the official TUI
xAI API	Secure API key handling, model selection, optional base URL for local/dev proxies
Imagine	Multimodal creation hooks as xAI expands image generation in the stack
Voice	Voice-first sessions when you want hands-free orchestration
Grok plugin	Full SoT pack (same agents/skills as Setup) anywhere the `grok` CLI runs

Luna (your Sherpa Guide) keeps sessions structured (MacroFlow™: Constitution → Clarify → Workforce) so you drive home to a delivered product — clean guardrails first, then ship with proof.

Azure DevOps / enterprise mode is Acornsoft-internal for now and not part of the first public release. We fine-tune it in-house; it ships later only if it proves value and works with any ADO instance—not just ours. Public MacroFlow stays product mode: guardrails → deliver.

Waypoint Check (Luna language)

Luna’s brief collect → check → recover → move forward stop is a Waypoint Check — position on the MacroFlow route, kit readiness, gap recovery, then the next leg. Use at phase handoffs, after verification, when stuck, and before claiming done. Keep it short.

Duality (one pack, two runtimes)

Path	Brain / billing	What you get
GitHub Copilot Chat	Included Copilot models (no Grok required)	Same Luna agents & skills via workspace SoT deploy (`.github/`)
Grok Build + xAI	xAI (CLI / API key / product)	Same pack as a native plugin — plus the meat: Grok Build, Imagine, Voice, API

SoT = Source of Truth. Canonical content lives in luna-foundry-config and is deployed by this extension (Copilot/Cursor) or installed as the Grok plugin (TUI). v1.0.26193+: full skill/agent parity — no curated subset on Grok.

What You Get

One command to put xAI tools in your VS Code workspace:

Luna: Setup Workspace — Deploys Luna skills/agents and prepares focused Grok terminals.
Grok Build (pwsh) — Clean native shell profile optimized for Grok Build and MacroFlow.
Grok (wsl) — Clean WSL profile for Linux-native tooling when you need it.
Grok plugin helper — Install the bundled luna-foundry plugin for native TUI sessions.
MacroFlow skills — Environment checks (ensure-*), content creation, forensic analysis, and ritual orchestration — usable with Copilot and native Grok.

The goal: highest-leverage xAI work feels natural inside the IDE and shell you already use.

Core Commands

Command	Description
`Luna: Setup Unified Workspace`	Primary. Deploy Luna + MacroFlow (`.github/` + `.cursorrules`); clean terminals.
`Luna: Create Grok Build (pwsh / bash / wsl)`	Focused shells that auto-start Grok Build.
`Luna: Install / Verify Grok CLI`	Ensure `grok` is on PATH.
`Luna: Install Luna Plugin for Grok`	Same SoT pack for native Grok TUI.

MacroFlow itself runs in Copilot Chat (agents/skills) or Grok Build TUI — not a separate dead extension webview.

Small command surface — the product is access to xAI, not a wall of menus.

Getting Started

Install the extension (Marketplace or VSIX).
Run Luna: Setup Workspace.
Open a Grok Build (pwsh) or Grok (wsl) terminal.
Start with /constitution, or say “Start MacroFlow with Luna.”
Use Grok Build, /goal, skills, and (where configured) Imagine / voice as first-class tools — not side quests.

Grok CLI / plugin (any shell)

Local install (recommended while pre-releasing) — use the SoT layout, pure x.y.z version in plugin.json:

# From monorepo root (adjust path if needed)
PLUGIN="src/apps/luna-foundry-config/live/grok-plugin/luna-foundry"
grok plugin validate "$PLUGIN"
grok plugin uninstall luna-foundry 2>/dev/null || true
grok plugin install "$(cd "$(dirname "$PLUGIN")" && pwd)/luna-foundry" --trust
# or absolute:
# grok plugin install "/path/to/luna-foundry-config/live/grok-plugin/luna-foundry" --trust
grok plugin details luna-foundry   # expect version 1.0.26193 (not …-preview.N)

Do not put -preview.N in plugin.json version. Prefer pure x.y.z (same rule as the VS Code VSIX). Rebuild with npm run build:grok-plugin in luna-foundry-config after version bumps.

Marketplace (when published):

grok plugin marketplace add "https://github.com/acornsoft/luna-foundry-multiagent"
grok plugin install luna-foundry --trust

Then in the TUI: /plugins (or /marketplace), /macroflow, /constitution, /goal. Reload plugins with r on the Plugins tab if needed.

The extension’s Install Luna Plugin for Grok command installs the layout bundled with the installed extension. After a version fix, reinstall the 1.0.26193 VSIX (not …-preview.1) so the bundled plugin is not stale.

Configuration

Key settings under lunaFoundry.*:

Setting	Purpose
`model`	e.g. `grok-4.3`, `grok-4.3-reasoning`
`apiKey`	Stored via VS Code Secrets
`apiBaseUrl`	Default `https://api.x.ai/v1`; override for local OpenAI-compatible proxies if needed
`voiceEnabled` / `videoEnabled`	Multimodal toggles
`agent`	`workforce` (recommended) or `luna`

Full schema: package.json → contributes.configuration.

Cost-aware use: Prefer focused terminals, early /constitution checks, and sparingly scheduled /loop jobs. Point apiBaseUrl at a local proxy for cheap iteration when full Grok fidelity is not required.

Architecture (short)

Luna — Sherpa Guide for AI-first work (MacroFlow ritual + agent handoffs + Waypoint Check).
SoT (Source of Truth) — luna-foundry-config: skills, agents, instructions, Grok plugin layout.
Extension — Delivery layer: workspace setup, terminal hygiene, CLI/plugin helpers.
Dual delivery — Copilot Chat (included models + same pack) and Grok Build / xAI (native plugin + full xAI stack).

This extension bundles a built copy of the SoT for distribution.

Current pre-release: 1.0.26193 (YYDDD day-of-year + prerelease). See CHANGELOG.md.

Installation

Marketplace

Search for Luna Foundry Multiagent in the Extensions view.

VSIX

code --install-extension .\luna-foundry-multiagent-*.vsix --force

Development / pre-release package

cd src/apps/luna-foundry-multiagent
npm run package:pre   # bundle SoT + compile + VSIX (pre-release)
# or: npm run package

Artifact: luna-foundry-multiagent-1.0.26193.vsix (version from package.json / VersionHistory.txt).

Reload the extension host after changes. Run Luna: Setup Unified Workspace to redeploy the pack.

Design Principles

Luna is your Sherpa Guide — AI-first navigation, not a bag of unconnected prompts.
One SoT — Source of Truth for agents/skills is luna-foundry-config; surfaces only adapt it.
Direct access to xAI — Grok Build, Imagine, API, voice, and CLI/TUI are the meat of the stack.
Copilot without Grok is valid — Same pack on included Copilot models; xAI key optional until you want Grok/xAI runtime.
Multi-modal by design — Text today; voice and richer channels as they mature.

Roadmap (product, not backlog admin)

Deeper native Grok Build feel inside VS Code and every shell.
Richer Imagine / multimodal paths as xAI ships them.
Seamless Copilot ↔ Grok TUI handoff with one ritual and one skill set.
Multi-session synthesis so fragmented Grok sessions become durable understanding.

Luna Foundry — Your Sherpa Guide for AI-first work, with tools that put xAI in the hands of developers and architects.

Maintained by Acornsoft · Powered by xAI Grok

Issues: github.com/acornsoft/luna-foundry-multiagent/issues