GatomIA (Agentic Spec-Driven Development Toolkit)

GatomIA is a VS Code extension that brings Agentic Spec-Driven Development to your workflow, leveraging SpecKit, OpenSpec, and GitHub Copilot.

It allows you to visually manage Specs, Steering documents (Constitution/AGENTS.md), and custom prompts, seamlessly integrating with GitHub Copilot Chat to generate high-quality documentation and code.

Current Project Status

This project is under continuous development. Some features may still exhibit unexpected behavior, contain bugs, or be only partially implemented.

Bug reports, suggestions, and general feedback are highly appreciated! They play a crucial role in helping us stabilize and improve the extension.

We are actively working on:

• Stabilizing all existing features
• Implementing the upcoming functionalities from our roadmap
• Improving overall reliability and user experience

You can follow our progress, open issues, or contribute directly through our official repository:

https://github.com/eitatech/gatomia-vscode/issues

Features

Spec Management

• Create Specs: Run GatomIA: Create New Spec (gatomia.spec.create) to open the creation dialog. Define your summary, product context, and constraints.
• Support for Multiple Systems: Choose between SpecKit (Recommended) or OpenSpec for your Spec-Driven Development workflow.
• Generate with Copilot: The extension compiles your input into an optimized prompt and sends it to GitHub Copilot Chat to generate the full specification.
• Manage Specs: Browse generated specs in the Specs view.
• Execute Tasks: Open tasks.md and use the "Start Task" CodeLens to send task context to GitHub Copilot Chat for implementation.

Prompt Management

• Custom Prompts: Manage Markdown prompts under .github/prompts (configurable) alongside instructions and agents to keep all project guidance in one place.
• Project Instructions & Agents: The Prompts explorer shows Project Instructions and Project Agents groups, surfacing .github/instructions and .github/agents files.
• Run Prompts: Execute prompts directly from the tree view, passing the context to GitHub Copilot Chat.
• Rename or Delete: Use the item context menu to rename or delete prompts.

Steering

• Instruction Rules: Create and manage instruction rules for GitHub Copilot at both project (.github/instructions/*.instructions.md) and user ($HOME/.github/instructions/*.instructions.md) levels.
  • Project Rules: Standardize team guidelines within the repository
  • User Rules: Define personal reusable guidance without committing to the repo
  • Constitution: Request Constitution document generation via Create Constitution button with AI-assisted drafting
• Constitution / Agents: Manage your project's "Constitution" (SpecKit) or "AGENTS.md" (OpenSpec) to steer Copilot's behavior.
• Global Instructions: Configure global instructions for Copilot across all your projects.

Migration

• Migrate to SpecKit: Easily migrate existing OpenSpec projects to the modern SpecKit structure using the GatomIA: Migrate to SpecKit command.

Hooks & Automation

• MCP Hooks Integration: Automate workflows by creating hooks that trigger MCP (Model Context Protocol) actions when agent operations complete.
• Browse MCP Servers: Discover available MCP servers and tools configured in your GitHub Copilot setup.
• Configure Actions: Set up hooks to execute MCP tools automatically (e.g., create GitHub issues, send Slack notifications) after operations like spec generation or task completion.
• Execution Tracking: View execution logs and monitor hook performance in real-time.
• Error Handling: Graceful degradation when MCP servers are unavailable, with automatic retry logic for transient failures.

Welcome Screen

• First-Time Setup: Interactive welcome screen appears on first activation to guide you through extension setup.
• Dependency Detection: Automatically checks for GitHub Copilot Chat, SpecKit CLI, and OpenSpec CLI installations.
• Quick Installation: One-click install buttons copy installation commands to your clipboard.
• Configuration Management: Edit key settings directly from the welcome screen with inline validation.
• Learning Resources: Browse documentation, examples, and tutorials organized by category.
• Feature Discovery: Explore all extension features with quick-access command buttons.
• System Health: Monitor extension status with real-time diagnostics and health indicators.
• Persistent Access: Re-open welcome screen anytime via GatomIA: Show Welcome Screen command.

Installation

Prerequisites

• Visual Studio Code 1.84.0 or newer.
• GitHub Copilot Chat extension must be installed.

SpecKit

1. Install the Specify CLI globally:

   uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
   

2. Initialize SpecKit in your project:

   specify init --here --ai copilot
   
   

OpenSpec

If you prefer OpenSpec:

1. Install the CLI globally:

   npm install -g @fission-ai/openspec@latest
   

2. Initialize in your project:

   openspec init
   

Marketplace

Search for "GatomIA" in the VS Code Marketplace and install the extension.

From Local VSIX

1. Build the package with npm run package (produces gatomia-<version>.vsix).
2. Install via code --install-extension gatomia-<version>.vsix.

Usage

1. Create a Spec

1. Open the Specs view in the Activity Bar.
2. Click Create New Spec.
3. Fill in the details (Product Context is required).
4. Click Create Spec. This will open GitHub Copilot Chat with a generated prompt.
5. Follow the chat instructions to generate the spec files.

2. Implement Tasks

1. Open a generated tasks.md file.
2. Click Start All Tasks above a checklist item.
3. GitHub Copilot Chat will open with the task context. Interact with it to implement the code.

3. Manage Instruction Rules

1. Open the Steering view in the Activity Bar.
2. Create Project Rule:
   • Click Create Project Rule button
   • Enter a name (e.g., "TypeScript Rules")
   • Edit the generated .github/instructions/<name>.instructions.md file
3. Create User Rule:
   • Click Create User Rule button
   • Enter a name for personal guidance
   • Edit the generated $HOME/.github/instructions/<name>.instructions.md file
4. Create Constitution:
   • Click Create Constitution button
   • Enter a brief description (e.g., "Python project with FastAPI")
   • Copilot Chat opens with /speckit.constitution prompt
   • The agent generates your constitution.md

4. Automate with Hooks

1. Open the Hooks view in the Activity Bar.
2. Click Create New Hook.
3. Configure the trigger (e.g., after "plan" operation in "speckit" agent).
4. Select an action type (MCP, Agent, Git, GitHub, or Custom).
5. For MCP actions:
   • Browse available MCP servers and tools
   • Map parameters using context variables or literal values
   • Save and enable the hook
6. Execute operations that match your trigger.
7. View execution logs in the Hooks view to monitor automation.

Configuration

All settings live under the gatomia namespace.

Workspace Layout

SpecKit Structure

.specify/
├── constitution.md         # Global steering rules
├── memory/                 # Project memory
├── templates/              # Spec templates
specs/                      # Feature specifications
├── 001-feature-name/
│   ├── spec.md
│   └── 001-task-name.md

OpenSpec Structure

openspec/
├── AGENTS.md               # Project-specific steering rules
├── project.md              # Project specification
├── specs/
│   ├── <spec>/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md

Development

1. Install dependencies:
   • npm run install:all
2. Build:
   • npm run build
3. Launch:
   • Press F5 inside VS Code.

License

MIT License. See LICENSE.

Credits

• SpecKit
• OpenSpec