Luna Foundry Multiagent

An AI-first development companion that embodies the eternal Sherpa ethos — wise, calm, patient guidance for building business solutions with xAI Grok. Luna orchestrates the MacroFlow ritual through a single fluid Workforce agent that flows across all phases as one continuous conversation.

Release v1.0.26134-preview.26 (ADR-031, ADR-032, ADR-033: Workforce-Only MacroFlow, Agentic Realm, xAI Skills Integration). The extension integrates xAI Grok native APIs with voice-first NAB capture, SIGNALS-driven feedback, and fluid Workforce execution.

🚀 30-Second Elevator Pitch

Luna Foundry is an AI-first development companion that turns nebulous requirements into shipped code through a single fluid conversation. You open VS Code, invoke Luna by guided voice or local commands, and one xAI Grok-powered agent — Workforce — walks you up the mountain under Luna's oversight: Constitution (foundations), Clarify (requirements with Zero to One checklists), and Workforce (execution with internal solutioning, tasking, and code delivery). Voice input arrives as Natural Agentic Briefs (NABs) — discrete, self-contained units of intent. SIGNALS (phase transitions, NAB captures, agentic attention, progression cues, errors) provide multi-modal feedback. Every transition emits a RealmEvent so the same conversation can resume later on another device, in the cloud, or inside a CI pipeline. No agent hand-off friction. No lost context. Just one calm guide, three disciplined phases, xAI Grok native, and integrated RealmEvent persistence.

What's New in v1.0.26134-preview.26

• Workforce-Only Fluid Model: Single agent executes the Workforce ritual under Luna oversight across Constitution, Clarify, and Workforce with internal state management; no explicit sub-agent handoffs
• Natural Agentic Brief (NAB): Voice and text input captured as discrete, atomic units of intent (ADR-001)
• SIGNALS-Driven Feedback: Phase Transitions, NAB Capture, Agentic Attention, Progression, and Error/Clarification signals guide interactions
• RealmEvent Persistence: All transitions emit RealmEvents for full conversation traceability and cross-device resumption
• xAI Grok Native: Direct integration with xAI APIs: Voice API (STT/TTS), Imagine API, Collections API, Agent Tools API, Grok Code Fast 1
• Guarded Back-Navigation: Workforce includes analysis model + Constitution reaffirmation before stepping backward
• Cross-Platform Continuity: Conversations persist and resume across VS Code, CLI, cloud pipelines, and background agents

The Workforce-Based Ritual

Luna Foundry uses a Workforce-based, xAI-first ritual where Luna oversees three working phases: Constitution, Clarify, and Workforce. A single Workforce agent stays active end-to-end, preserving full context across phases and emitting RealmEvents for traceability and resumption.

Key Distinction: The Workforce-based model exposes 3 external phases under Luna oversight. Within the Workforce phase, the agent internally performs Solutioning, Tasks creation, and delivery work (no separate user-facing phases). This keeps the ritual lean and the conversation unified. Back-stepping is guarded: the agent requires analysis approval + Constitution reaffirmation before rewinding.

Agents

Model: Luna is the constant guide who never changes. Workforce is the execution engine. When you select Workforce, you get direct, lean execution. When you select Luna, you get Luna's voice + Workforce underneath. Both paths emit identical RealmEvents and flow through Constitution, Clarify, and Workforce. The only difference is the narrative tone and orchestrator presence.

xAI Skills Integration

Luna Foundry integrates xAI's latest Skills APIs for enhanced development capabilities:

Core Skills

• Voice API: Speech-to-text and text-to-speech with multiple voice options
• Imagine API: AI-powered diagram and visualization generation
• Collections API: RAG-based knowledge retrieval and context management
• Agent Tools API: Advanced tool-calling for development workflows
• Grok Code Fast 1: Accelerated coding with reasoning models

Voice & NAB (Natural Agentic Brief) Capture

Voice input is captured as Natural Agentic Briefs — discrete, atomic units of intent:

• NAB Capture (Shift+Space by default): Transcribe voice intent → NAB classification → route to appropriate phase
• SIGNALS Feedback: Phase Transition signals, NAB Capture confirmations, Agentic Attention pings, Progression cues, Error/Clarification prompts

Skills Commands

• luna.startMacroFlow: Invoke the full Workforce ritual
• luna.voiceQuery: Hands-free voice input (NAB capture)
• luna.generateVoice: Text-to-speech output
• luna.processVoice: Transcribe voice content
• luna.generateImage: Create AI-generated diagrams and visualizations
• luna.generateDiagram: Automated Mermaid diagram generation

Architecture

Key Runtime Components

• Extension Core — src/core/extension.ts registers commands, wires agent selection, and drives phase transitions.
• Configuration Manager — src/configuration/configurationManager.ts reads lunaFoundry.* settings and validates the xAI runtime.
• Workforce Runtime — src/workforce/ orchestrates the Workforce ritual (Constitution, Clarify, Workforce) with internal state via RealmEvents:
  • workforceRouter.ts: resolveMacroFlowMode(agentId), internal phase navigation, evaluateBackNavigationGuard, buildRealmEvent.
  • workforceOrchestrator.ts: runWorkforceTransition(request) executes all phases, manages state, emits RealmEvents.
• Voice & NAB Layer — src/services/voiceManager.ts captures voice input as NABs, routes to Workforce, emits SIGNALS feedback.
• Skills Integration — Direct xAI API clients for Voice API (STT/TTS), Imagine, Collections, Agent Tools.
• Agent Manager — src/agents/agentManager.ts delegates to Workforce router; Luna is a narrative wrapper.

Entry Surfaces

The Agentic Realm event contract (ADR-031) is emitted today; the Event Hubs / persistence infrastructure is intentionally deferred.

Configuration

Configure the extension under Settings → Extensions → Luna Foundry Multiagent or in your settings.json:

{
  // Active agent for Luna Foundry
  "lunaFoundry.agent": "workforce", // workforce | luna (both use Workforce internally)

  // xAI runtime (xAI Grok native, enforced)
  "lunaFoundry.provider": "xai",
  "lunaFoundry.apiBaseUrl": "https://api.x.ai/v1",
  "lunaFoundry.model": "grok-4.3", // grok-4.3 (recommended), grok-4.3-reasoning, grok-build-0.1

  // xAI Skills toggles
  "lunaFoundry.voiceEnabled": true,
  "lunaFoundry.imagineEnabled": true,
  "lunaFoundry.collectionsEnabled": true,
  "lunaFoundry.agentToolsEnabled": true,

  // NAB & SIGNALS
  "lunaFoundry.nabCaptureKeybind": "shift+space",
  "lunaFoundry.signalsFeedback": true,

  // Multimodal & Dev
  "lunaFoundry.videoEnabled": true,
  "lunaFoundry.buildEnabled": true,
  "lunaFoundry.debugRealmEvents": false // Enable to watch RealmEvent stream in Output
}

API keys are stored in VS Code's secrets store; never commit them.

Install

From VSIX (current delivery path)

A VSIX is produced for every tagged release in the repo root:

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

Or via VS Code UI: Ctrl+Shift+P → Extensions: Install from VSIX… → select the .vsix → reload.

From Source

git clone https://github.com/acornsoft/luna-foundry-multiagent.git
cd luna-foundry-multiagent
npm install
npm run compile
npm test          # expect updated test count
npx vsce package --no-dependencies
code --install-extension .\luna-foundry-multiagent-1.0.26133.26.vsix --force

Prerequisites

• VS Code 1.85+ (Insiders recommended for voice)
• Node.js 18+
• xAI API key (get one at console.x.ai)
• Azure CLI + Azure DevOps CLI extension (for work item integration)
• GitHub CLI (for PR and issue flows)
• Mermaid CLI (@mermaid-js/mermaid-cli) for regenerating diagrams

Regenerating Diagrams

Diagram sources live in ../../../docs/Analysis/diagrams/*.mmd. Rebuild the full rendered set into ../../../docs/Analysis/images/ with the canonical renderer:

pwsh -NoProfile -ExecutionPolicy Bypass -File ../../../lib/scripts/Render-Analysis-Diagrams.ps1

This renders every Mermaid source in docs/Analysis/diagrams so each .mmd has a corresponding .png in docs/Analysis/images. mmdc (Mermaid CLI) downloads its own headless Chromium on first run.

Commands

Usage

Luna Foundry is designed to feel like one continuous conversation with a wise guide, not a menu of tools. This section walks through the most common flows end-to-end.

1. First-Time Setup

1. Install the VSIX (see Install).
2. Open the Command Palette (Ctrl+Shift+P) and run Luna: Set API Key — paste your xAI key from console.x.ai. It is stored in VS Code's secret store, never in settings.json.
3. Confirm defaults in Settings → Extensions → Luna Foundry Multiagent:
   • lunaFoundry.agent: workforce (recommended)
   • lunaFoundry.model: grok-4-1-fast-reasoning
4. Reload the window. Luna is ready.

2. Daily Driver — Start MacroFlow

This is the flow you'll use 95% of the time.

1. Open the workspace you want to work in.
2. Ctrl+Shift+P → Luna: Start MacroFlow.
3. Workforce opens a chat panel and begins Phase 1 — Constitution, loading your project's manifesto, patterns, and guardrails. She confirms context with you in first person.
4. Answer Clarify questions. Be terse; Workforce will probe if she needs more. Voice input is captured as NABs and marked with SIGNALS feedback.
5. When requirements are clear, Workforce internally transitions to Solutioning (no phase change visible to you): she proposes specs, architecture, trade-offs, and (optionally) an ADR draft. Approve, refine, or redirect.
6. She internally creates Tasks (vertical slices, user stories) and continues execution within Workforce: code, tests, scaffolding, and delivery artifacts are generated directly into your workspace. Review diffs in Source Control.

One agent, full context, three external phases under Luna oversight. Workforce handles Constitution, Clarify, and Workforce (internal solutioning + tasks + delivery) as a seamless flow. RealmEvents are emitted on every transition for cross-device resumption.

3. Going Backward (Guarded)

If mid-Workforce execution you realize the solution is wrong:

1. Ask Luna: "Let's step back — I think Solutioning missed X."
2. She runs the back-navigation guard: she requires you to (a) approve her analysis of what to revisit, and (b) reaffirm the Constitution for the new direction.
3. Once both are confirmed, she rewinds to the earlier phase cleanly — no context loss, no ghost state.

This is the single most important discipline in MacroFlow. It prevents thrashing.

4. Voice Mode & NAB Capture

VS Code Insiders + microphone required.

1. Ctrl+Shift+P → Luna: Voice Query or press Shift+Space (default NAB capture keybind).
2. Speak your intent naturally: "Luna, let's spec a new sync endpoint for the cross-app bridge." — your voice is transcribed and captured as a Natural Agentic Brief (NAB).
3. Workforce transcribes via xAI Voice API (STT), classifies the NAB intent, routes it to the appropriate phase, and responds in text (and optionally voice via Luna: Generate Voice using xAI TTS). SIGNALS provide multi-modal feedback: visual phase transitions, audio cues, progress pings.

5. Multi-Perspective Brainstorming

When you need diverse viewpoints before committing to an approach:

1. Ctrl+Shift+P → Luna: Ask the Team.
2. Luna spawns parallel Research / Logician / Designer sub-prompts against Grok, then synthesizes a single recommendation.
3. Use the output as input to the next Clarify or Solutioning turn.

6. Multimodal Workflows

• Video — Luna: Process Video feeds a local or remote video to Grok for analysis (e.g., reviewing UX walkthroughs, extracting specs from whiteboard recordings).
• Cross-device sync — Luna: Sync with grok.com pushes the current RealmEvent stream to your grok.com account so the conversation resumes on phone or web.

7. CLI & Background Agents (Contracts Ready, Driver Planned)

The Workforce runtime already accepts CLI and cloud/background invocations via runWorkforceTransition({ agentId, ... }). The dedicated CLI binary ships in a follow-up release; the contract is locked today so your pipelines can wire against it.

8. Inspecting the Realm Stream

Every transition emits a RealmEvent (PhaseHandOff, VoiceInput, AgentOutput, RealmUpdate). Today these are surfaced through telemetry and the extension output channel. When Event Hubs persistence lands, the same events become your durable audit trail and resumption log.

To watch events live right now: open Output → Luna Foundry Multiagent in VS Code during a session.

Typical Session (End-to-End Example)

You : Luna: Start MacroFlow

[SIGNAL: Phase Transition → Constitution]
Workforce: [Constitution] Loaded manifesto, 3 ADRs, MacroFlow v1.0.26133.26. Confirm project = luna-foundry-multiagent?
You : Yes. I need to add a heartbeat endpoint for the background agent.

[SIGNAL: NAB Captured]
Workforce: [Clarify] Is "heartbeat" a liveness probe, a progress beacon, or both?
You : Liveness only. Every 30s. POST /agent/heartbeat with agentId + timestamp.

[SIGNAL: Phase Transition → Workforce (internal solutioning + tasks)]
Workforce: Proposing minimal API endpoint in src/api/heartbeat.ts, stored in-memory for now,
           telemetry to App Insights. Trade-off: skipping persistence keeps PR small. Proceed? [y/N]
You : Yes.

[SIGNAL: Phase Transition → Workforce Execution]
Workforce: Generated src/api/heartbeat.ts, tests/heartbeat.test.ts, wired router.
           Tests: 74/74 passing. Review diffs in Source Control.
You : Looks good. Merging now.

[RealmEvent emitted for all transitions; conversation resumable on CLI, cloud, or next session]

One conversation. Luna oversight plus three external phases. One agent. Internal state via RealmEvents. That's MacroFlow v1.0.26133.26.

Development

npm run compile     # tsc build
npm test            # Mocha suite (73 tests)
npm run package     # Produce VSIX

Source layout:

src/
  core/              Extension activation, command registration, AGENTS array
  configuration/     VSCodeConfigurationManager + xAI runtime validation
  agents/            Agent shape, XaiApiClient, Grok420ApiClient
  workforce/         Router, orchestrator, guards, RealmEvent builder
  services/          Webview + enhanced voice manager
tests/suite/
  extension.test.ts            Command registration and activation
  integration.test.ts          Configuration, runtime guardrails, migration skeletons
  workforce.artifacts.test.ts  Router, orchestrator, CLI/Cloud/Background handoff

Key ADRs (canonical monorepo paths: ../../../docs/Analysis/Macroflow-Research/ADR/ and ../../../docs/Analysis/Voice-Agent-Research/ADR/):

• ADR-001 — Natural Agentic Brief (NAB) definition, voice interaction patterns, Zero to One ideas
• ADR-031 — Persistent Agentic Realm (RealmEvent contract), Event Hubs persistence, voice-first bridge
• ADR-032 — Evolve MacroFlow to Workforce-only fluid agent (no explicit sub-agent handoffs)
• ADR-033 — Release readiness summary for MacroFlow v1.0.26133.26

Roadmap

• Now (v1.0.26133.26) — Workforce fluid mode locked, RealmEvent emission, CLI / cloud / background contracts, xAI Grok native, NAB capture, SIGNALS feedback.
• Next (v1.1) — Dedicated CLI driver shipped, Realm persistence (Event Hubs + store), expanded xAI Skills surface.
• Later — Enterprise observability dashboard on the Realm stream, multi-project skill federation, cross-org Workforce delegation.

Built with ❤️ by Acornsoft / Luna Foundry · Powered by xAI Grok · Inspired by the Sherpa ethos

For issues and contributions: github.com/acornsoft/luna-foundry-multiagent/issues