feat: Project Polaris - Phased Workflow Engine & Architect Agents

[SuccessSoham]

Project Polaris: Phased Workflow Engine & Specialized Agents

This PR introduces Project Polaris, a significant architectural enhancement to Gemini CLI designed to handle complex software engineering tasks through a structured, multi-agent workflow.

Closes #18537

🚀 Key Features

1. Phased Workflow Engine (packages/core/src/workflow/engine.ts)

   • Implements a deterministic 7-phase state machine: Discovery -> Exploration -> Clarification -> Architecture -> Implementation -> Quality Review -> Summary.
   • Orchestrates specialized agents to handle distinct phases of the development lifecycle.

2. Specialized Built-in Agents

   • Architect Agent: Dedicated to codebase analysis and plan generation. Features a strict whitelist of native read-only tools (read_file, grep_search, glob, lsp_find_references, lsp_go_to_definition) to ensure safe and focused exploration without MCP conflicts.
   • Reviewer Agent: specialized in auditing code changes against project conventions and task requirements, returning structured confidence scores and issue lists.
   • Both agents are now registered as first-class built-ins in AgentRegistry.

3. New /polaris Slash Command

   • Added packages/cli/src/ui/commands/polarisCommand.ts.
   • Allows users to directly invoke the high-level workflow engine (e.g., /polaris \"Refactor the auth system\"), bypassing the chat model's tool selection loop for a more reliable kickoff.
   • Provides real-time UI feedback for internal agent activities (tool calls, thoughts).

4. Enhanced LocalAgentExecutor

   • Added support for onActivity callbacks to stream granular agent events to the UI.
   • Implemented robust fallback logic for model alias resolution, ensuring agents can recover and run even if specific model aliases (like architect-config) aren't perfectly resolved in the environment.

🌟 Phase 2 Update: Semantic Intelligence (LSP)

This PR now includes deep semantic analysis capabilities:

• LSP Client Service: A new core service (packages/core/src/services/lspService.ts) that orchestrates language servers via JSON-RPC.
• Semantic Tools: Added lsp_find_references and lsp_go_to_definition tools, allowing agents to understand code structure rather than just matching text.
• Zero-Config: Automatically uses npx to run language servers (e.g., typescript-language-server) without requiring global installation.

🛠️ Compatibility & Runtime Fixes

• Windows Support: Addressed bundling issues by introducing a react-shim.ts and patching shellExecutionService.ts to correctly handle @xterm/headless imports.
• Build Scripts: Updated scripts/build.js to be resilient against non-essential workspace build failures (like vscode-companion), ensuring the CLI bundle is always generated.
• Rate Limit Safeguard: A temporary 15-second delay has been added to the agent loop to support testing with free-tier API keys (to be removed or flagged in production).

🧪 Verification

This workflow has been tested locally on Windows.

1. Run npm run bundle
2. Start CLI: node bundle/gemini.js
3. Command: /polaris \"Analyze the codebase...\" -> Successfully spawns Architect, explores files, and generates a plan.

Future Work (Phase 3)

• Implementation Agent: An executor agent that consumes the plan and writes code.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @SuccessSoham, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces Project Polaris, a major architectural enhancement to the Gemini CLI that establishes a new phased workflow engine. This engine orchestrates specialized AI agents through a structured development lifecycle, aiming to improve the handling of complex software engineering tasks by providing a more deterministic and observable process. The changes also include critical compatibility fixes for Windows and improvements to build stability.

Highlights

• Project Polaris Introduction: Introduces 'Project Polaris', a significant architectural enhancement to the Gemini CLI, designed to handle complex software engineering tasks through a structured, multi-agent workflow.
• Phased Workflow Engine: Implements a deterministic 7-phase state machine (Discovery -> Exploration -> Clarification -> Architecture -> Implementation -> Quality Review -> Summary) to orchestrate specialized agents.
• Specialized Built-in Agents: Adds an 'Architect Agent' for codebase analysis and plan generation with whitelisted read-only tools, and a 'Reviewer Agent' for auditing code changes, both registered as first-class built-ins.
• New /polaris Slash Command: Introduces a new /polaris command to directly invoke the high-level workflow engine, providing real-time UI feedback on internal agent activities.
• LocalAgentExecutor Enhancements: Adds support for onActivity callbacks to stream granular agent events to the UI and implements robust fallback logic for model alias resolution.
• Windows Compatibility & Build Resilience: Addresses bundling issues with a react-shim.ts and patches shellExecutionService.ts for @xterm/headless imports. Updates build scripts to be resilient against non-essential workspace build failures.

Changelog

• packages/cli/src/patches/react-shim.ts
  • Added a React shim to resolve bundling issues, particularly for Windows environments.
• packages/cli/src/services/BuiltinCommandLoader.ts
  • Integrated the new /polaris command into the CLI's built-in command loader, making it accessible to users.
• packages/cli/src/ui/commands/polarisCommand.ts
  • Introduced the /polaris slash command, enabling direct invocation of the Polaris workflow engine.
  • Implemented real-time UI feedback for agent activities (tool calls, thoughts) during workflow execution.
• packages/core/src/agents/architect-agent.ts
  • Added the ArchitectAgent, a new specialized agent designed for codebase analysis and generating detailed implementation plans.
  • Configured the ArchitectAgent to use a strict whitelist of native read-only tools for safe and focused exploration.
• packages/core/src/agents/local-executor.ts
  • Implemented improved fallback logic for model alias resolution within the LocalAgentExecutor, ensuring agents can function even if specific model aliases are not perfectly configured.
• packages/core/src/agents/registry.ts
  • Registered the newly created ArchitectAgent and ReviewerAgent as core built-in agents within the system.
• packages/core/src/agents/reviewer-agent.ts
  • Introduced the ReviewerAgent, a specialized agent for auditing code changes, providing structured confidence scores and issue lists based on project conventions and task requirements.
• packages/core/src/agents/types.ts
  • Expanded agent type definitions to include workflowMode for LocalAgentDefinition.
  • Introduced new Zod schemas for PlanStepSchema, PlanProposalSchema, ReviewIssueSchema, ReviewScoreSchema, and TaskContextSchema to support structured agent outputs.
• packages/core/src/agents/utils.ts
  • Refactored the templateString utility for broader applicability.
  • Added new utility functions (calculateConsensusScore, filterHighConfidenceIssues) to process and aggregate review scores.
• packages/core/src/index.ts
  • Updated the core export file to include new utility modules and the WorkflowEngine for broader accessibility within the project.
• packages/core/src/services/shellExecutionService.ts
  • Corrected the import statement for @xterm/headless to resolve bundling issues and improve Windows compatibility.
• packages/core/src/telemetry/index.ts
  • Expanded telemetry logging capabilities by adding new loggers and event types for various system activities, including extension management and model commands.
• packages/core/src/utils/shell-utils.ts
  • Adjusted the import path for web-tree-sitter.wasm to ensure correct bundling and loading of WASM binaries.
• packages/core/src/workflow/engine.ts
  • Implemented the WorkflowEngine, which orchestrates a multi-phase development process, currently focusing on the Architecture phase using the ArchitectAgent.
• scripts/build.js
  • Enhanced the build script with a try-catch block around workspace builds, making it more robust against failures in non-essential packages and ensuring the CLI bundle is still generated.

Activity

• The pull request introduces a major new feature, Project Polaris, which includes a phased workflow engine and new specialized agents.
• It addresses several compatibility and build issues, notably for Windows environments, ensuring broader usability.
• The author, SuccessSoham, has provided detailed explanations of the new architecture and verification steps in the PR description, including local testing on Windows.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant architectural enhancement, Project Polaris, which includes a phased workflow engine and specialized agents. The changes are extensive and well-structured. My review focuses on improving robustness, security, and correctness in several key areas. I've identified a few critical and high-severity issues related to prompt templating, agent output validation, command cancellation, and tool security. Addressing these, with reference to established rules, will make the new architecture more resilient and reliable.

[SuccessSoham]

Hi team,

I have addressed all the feedback provided by the gemini-code-assist bot. Specifically:

1. Robust Templating: Restored validation in templateString to ensure all required placeholders are present before sending prompts to the model.
2. Schema Reliability: Made agentId optional in ReviewScoreSchema to prevent unnecessary validation failures during agent completion.
3. Cancellation Support: Updated the /polaris command to utilize context.signal, enabling proper user-initiated cancellation (Ctrl+C).
4. Security Consistency: Implemented strict tool whitelisting for the Reviewer agent, using the same robust pattern as the Architect agent to prevent unintended tool access.
5. Data Integrity: Enhanced the WorkflowEngine to perform runtime Zod validation on plan proposals.

Project Polaris is now more resilient and secure. Looking forward to your final review and merge!

Best regards,
Soham