gv-ai 1.0.0

package/.cursor/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "linear": {
+      "command": "bunx",
+      "args": [
+        "linear-mcp-server"
+      ]
+    }
+  }
+}

package/.gemini/settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "linear": {
+      "command": "bunx",
+      "args": [
+        "linear-mcp-server"
+      ]
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "linear": {
+      "command": "bunx",
+      "args": [
+        "linear-mcp-server"
+      ]
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+## Linear Ticket Enforcement
+
+**CRITICAL**: Before making ANY code changes (editing files, creating files, running commands that modify state), you MUST have a confirmed Linear ticket.
+
+### Pre-Implementation Gate
+
+When the user requests implementation work:
+
+1. **Ask what they're working on** (if not clear from context)
+2. **Search Linear for relevant tickets** using Linear MCP tools
+3. **Fetch all Linear projects** to show available options
+4. **Present a numbered list** to the user:
+
+   ```
+   Found potential matches:
+   1. [PROJ-123]: Ticket title here
+   2. [PROJ-456]: Another ticket title
+
+   Or create new ticket in:
+   3. Backend API (BACK)
+   4. Platform Infrastructure (PLAT)
+   5. Mobile App (MOB)
+
+   Which one? (enter number)
+   ```
+
+5. **Wait for user to select a number**
+6. **Confirm the selection** before proceeding with any implementation
+
+### Free Actions (No Ticket Required)
+
+You may freely help with:
+- Answering questions about code
+- Explaining how code works
+- Discussing approaches and solutions
+- Debugging and analysis (without making changes)
+- Code review and suggestions
+- General brainstorming
+
+### Gated Actions (Ticket Required)
+
+You MUST have a confirmed Linear ticket before:
+- Creating new files
+- Editing existing files
+- Running commands that modify state (git commits, npm install, etc.)
+- Creating branches or pull requests
+- Deploying or publishing
+
+### During Implementation
+
+Once a ticket is confirmed:
+- Update the Linear ticket with progress comments as you work
+- Set ticket status to "In Progress" when starting
+- Link commits and branches to the ticket
+- Keep the ticket updated with any blockers or decisions
+
+### PR Creation
+
+When creating a pull request:
+- Use Linear's branch naming convention (if available)
+- Automatically link the PR to the associated ticket
+- Update the ticket status to "In Review"
+- Add a comment to the ticket with the PR link
+
+### Multi-Ticket Sessions
+
+If work touches multiple features or areas:
+- Identify all relevant tickets at the start
+- Confirm with the user which tickets to track
+- Update each ticket appropriately as you work on related code
+- Keep tickets in sync with the work being done
+
+### Ad-hoc Tickets
+
+When creating a new ad-hoc ticket:
+- Ask the user which Linear project to create it in
+- Use the user's description as the ticket title
+- Automatically add an "ad-hoc" label
+- Assign the ticket to the current user (if possible)
+- Set the status to "In Progress"
+
+### Important Notes
+
+- **Always confirm** before associating work with a ticket
+- **Never guess** which ticket applies - always ask the user
+- **Show ticket details** (title, description preview) when asking for confirmation
+- **Handle errors gracefully** if Linear API is unavailable
+- **Be patient** - the user may need time to find the right ticket

package/README.md

@@ -0,0 +1,422 @@
+# GV AI - Linear Ticket Enforcement for AI Coding Tools
+
+Automate Linear ticket tracking across OpenCode, Claude Code, and Gemini CLI. Never forget to update tickets again!
+
+## Problem
+
+Backend developers often get so focused on building that they forget to:
+- Update Linear tasks with progress
+- Link PRs to tickets
+- Create tickets for ad-hoc work
+- Change ticket status
+
+This leads to out-of-sync project management and lost context.
+
+## Solution
+
+GV AI enforces a simple rule: **No code changes without a Linear ticket.**
+
+Your AI coding assistant will:
+1. Ask which Linear ticket you're working on before making changes
+2. Show you existing tickets or help create new ones
+3. Update the ticket automatically as you work
+4. Link commits and PRs to the ticket
+
+## Features
+
+- **Universal**: Works with OpenCode, Claude Code, and Gemini CLI
+- **Project-agnostic**: Works in any repository
+- **Simple setup**: One command to configure everything
+- **Non-intrusive**: Only gates implementation, not conversations
+- **Multi-ticket support**: Track multiple tickets in one session
+
+## Installation
+
+```bash
+bun install -g @gv-org/gv-ai
+```
+
+Or use with bunx:
+
+```bash
+bunx @gv-org/gv-ai project init
+```
+
+## Quick Start
+
+### 1. Initialize Your Project
+
+```bash
+cd your-project
+gv-ai project init
+```
+
+You'll be prompted to:
+1. Select which AI tools you use (OpenCode, Claude Code, Gemini CLI, VSCode, Cursor, Windsurf)
+
+That's it! The tool will:
+- Configure Linear's remote MCP server for selected tools
+- Create `AGENTS.md` with workflow instructions
+- Create symlinks (`CLAUDE.md`, `GEMINI.md`) if needed
+- Update `.gitignore` to exclude MCP configs
+
+### 2. Authenticate with Linear
+
+When you first use Linear in your AI tool, you'll be prompted to authenticate via OAuth. The MCP server will guide you through the process.
+
+### 3. Start Coding
+
+Restart your AI coding tool and start a session:
+
+```
+You: Fix the authentication bug in login.ts
+
+Agent: Let me search for relevant Linear tickets...
+
+Found potential matches:
+1. BACK-234: Token expiration issues
+2. BACK-189: Login endpoint returning 401
+
+Or create new ticket in:
+3. Backend API (BACK)
+4. Platform (PLAT)
+
+Which one? (enter number)
+
+You: 1
+
+Agent: ✓ Working on BACK-234: Token expiration issues
+       Let me fix the bug...
+```
+
+## How It Works
+
+### The Enforcement Gate
+
+The agent follows these rules (defined in `AGENTS.md`):
+
+**Free actions (no ticket needed):**
+- Answering questions
+- Explaining code
+- Discussing approaches
+- Code review
+
+**Gated actions (ticket required):**
+- Creating/editing files
+- Running commands that modify state
+- Creating branches/PRs
+
+### Runtime Flow
+
+1. **User asks to implement something**
+2. **Agent searches Linear** for relevant tickets using MCP
+3. **Agent presents options** as a numbered list:
+   - Existing tickets that match
+   - Options to create new tickets in different projects
+4. **User selects a number**
+5. **Agent proceeds** and updates the ticket as it works
+
+### Multi-Ticket Support
+
+If your work touches multiple features:
+
+```
+You: Refactor the authentication system
+
+Agent: This work touches multiple areas. I found:
+1. BACK-234: Token expiration (authentication logic)
+2. BACK-156: Session management (related)
+
+Should I track both tickets? Or just one?
+
+You: Both
+
+Agent: ✓ Tracking BACK-234 and BACK-156
+       [proceeds with implementation]
+```
+
+## Configuration
+
+### File Structure After Init
+
+```
+your-project/
+├── AGENTS.md                 # Main instruction file
+├── CLAUDE.md → AGENTS.md     # Symlink (if using Claude Code)
+├── GEMINI.md → AGENTS.md     # Symlink (if using Gemini CLI)
+├── .mcp.json                 # Claude Code MCP config
+├── .gemini/
+│   └── settings.json         # Gemini CLI MCP config
+└── opencode.json             # OpenCode MCP config
+```
+
+### MCP Configuration
+
+The tool configures the Linear MCP server for each selected tool:
+
+**OpenCode** (`opencode.json`):
+```json
+{
+  "mcp": {
+    "linear": {
+      "type": "local",
+      "command": ["npx", "-y", "mcp-remote", "https://mcp.linear.app/sse"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Claude Code** (`.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
+    }
+  }
+}
+```
+
+**Gemini CLI** (`.gemini/settings.json`):
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
+    }
+  }
+}
+```
+
+**VSCode** (`.vscode/mcp.json`):
+```json
+{
+  "servers": {
+    "linear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"],
+      "auth": {
+        "type": "oauth2"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
+    }
+  }
+}
+```
+
+**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
+    }
+  }
+}
+```
+
+### Customizing AGENTS.md
+
+The generated `AGENTS.md` contains the Linear workflow instructions. You can customize:
+
+- Which actions require tickets
+- Status transitions (Todo → In Progress → In Review)
+- Branch naming conventions
+- Ad-hoc ticket labels
+
+## Supported AI Tools
+
+| Tool | Status | Notes |
+|------|--------|-------|
+| **OpenCode** | ✅ Fully supported | Reads `AGENTS.md` directly |
+| **Claude Code** | ✅ Fully supported | Uses symlink to `CLAUDE.md` |
+| **Gemini CLI** | ✅ Fully supported | Uses symlink to `GEMINI.md` |
+| **VSCode** | ✅ Fully supported | Reads `AGENTS.md` directly |
+| **Cursor** | ✅ Fully supported | Reads `AGENTS.md` directly |
+| **Windsurf** | ✅ Fully supported | Reads `AGENTS.md` directly |
+
+## CLI Commands
+
+```bash
+# Initialize project
+gv-ai project init
+
+# Future commands (coming soon)
+gv-ai project status        # View current configuration
+gv-ai project add-tool      # Add another AI tool
+gv-ai config show           # Show current config
+```
+
+## Technical Details
+
+### Built With
+
+- **TypeScript** - Type-safe CLI development
+- **Commander** - CLI framework
+- **Inquirer** - Interactive prompts
+- **Chalk** - Terminal styling
+- **Ora** - Loading spinners
+- **Execa** - Process execution
+
+### Requirements
+
+- Node.js 20.0.0 or higher
+- npm or yarn
+- At least one AI coding tool installed (OpenCode, Claude Code, or Gemini CLI)
+- Linear API key
+
+### AGENTS.md Standard
+
+This tool follows the [AGENTS.md standard](https://agents.md/), an open format for guiding AI coding agents. AGENTS.md is supported by:
+
+- OpenCode
+- Claude Code (via symlink)
+- Gemini CLI (via symlink)
+- Cursor
+- GitHub Copilot
+- Devin
+- Factory
+- And 60,000+ open source projects
+
+### Linear MCP Server
+
+Uses the community-built [linear-mcp-server](https://www.npmjs.com/package/linear-mcp-server) which provides:
+
+- Issue search and filtering
+- Issue creation and updates
+- Comment management
+- Project and team listing
+- User assignment
+
+## Troubleshooting
+
+### "Tool not found" error
+
+Make sure the AI coding tool is installed and available in your PATH:
+
+```bash
+# Check if tools are installed
+opencode --version
+claude --version
+gemini --version
+```
+
+### MCP not working
+
+1. **Restart your AI tool** - MCP configs are loaded at startup
+2. **Check your Linear API key** - Test it at [linear.app/settings/api](https://linear.app/settings/api)
+3. **Verify MCP config files** - Make sure they were created in the right location
+
+### Agent not enforcing tickets
+
+1. **Check AGENTS.md exists** - The agent needs this file to know the rules
+2. **Verify symlinks** - Claude Code and Gemini CLI need `CLAUDE.md`/`GEMINI.md` symlinks
+3. **Restart your session** - Some tools need a fresh session to reload instructions
+
+## Examples
+
+### Example 1: Bug Fix
+
+```
+You: The user profile page is crashing when email is null
+
+Agent: Let me search Linear...
+
+Found: FRONT-89: Profile page crashes with null email
+
+Is this the ticket? (yes/no)
+
+You: yes
+
+Agent: ✓ Working on FRONT-89
+       [analyzes code, finds bug, implements fix]
+
+       I've fixed the null check in ProfilePage.tsx
+       Updated FRONT-89 with the solution
+```
+
+### Example 2: New Feature
+
+```
+You: Add dark mode toggle to settings
+
+Agent: No existing ticket found. Create new ticket in:
+1. Frontend (FRONT)
+2. Design System (DS)
+
+Which project? (enter number)
+
+You: 1
+
+Agent: ✓ Created FRONT-234: Add dark mode toggle to settings (ad-hoc)
+       ✓ Set status to "In Progress"
+
+       [proceeds with implementation]
+```
+
+### Example 3: Refactoring
+
+```
+You: Refactor the auth system to use JWT instead of sessions
+
+Agent: This affects multiple areas. Found:
+1. BACK-156: Migrate to JWT authentication
+2. BACK-189: Remove session storage
+
+Work on both tickets?
+
+You: yes
+
+Agent: ✓ Tracking BACK-156 and BACK-189
+       [proceeds with refactoring both areas]
+```
+
+## Roadmap
+
+- [ ] Support for GitHub integration
+- [ ] Automatic PR creation with ticket linking
+- [ ] Status auto-transitions based on git events
+- [ ] Team-wide configuration templates
+- [ ] Analytics dashboard for ticket tracking
+- [ ] Slack notifications for ticket updates
+
+## Contributing
+
+This is an internal tool for GV team. For issues or suggestions, reach out to the platform team.
+
+## License
+
+MIT
+
+## Credits
+
+Built with:
+- [AGENTS.md Standard](https://agents.md/) - Open format for AI agents
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Standard for connecting AI to data sources
+- [Linear MCP Server](https://www.npmjs.com/package/linear-mcp-server) - Community-built Linear integration
+- [Commander.js](https://github.com/tj/commander.js) - CLI framework
+- [Inquirer](https://github.com/SBoudrias/Inquirer.js) - Interactive prompts
+
+## Sources
+
+- [AGENTS.md GitHub Repository](https://github.com/agentsmd/agents.md)
+- [AGENTS.md Official Website](https://agents.md/)
+- [Linux Foundation - Agentic AI Foundation Announcement](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)
+- [Linear MCP Server npm package](https://www.npmjs.com/package/linear-mcp-server)
+- [Node.js CLI Best Practices](https://github.com/lirantal/nodejs-cli-apps-best-practices)