Main dev

.github/agents/sage-github.agent.md

@@ -1,307 +1,30 @@
 ---
-description: 'Expert assistant for managing SAGE project GitHub Issues using sage-github-manager CLI tool'
-tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'copilot-container-tools/*', 'pylance-mcp-server/*', 'todo', 'github.vscode-pull-request-github/copilotCodingAgent', 'github.vscode-pull-request-github/issue_fetch', 'github.vscode-pull-request-github/suggest-fix', 'github.vscode-pull-request-github/searchSyntax', 'github.vscode-pull-request-github/doSearch', 'github.vscode-pull-request-github/renderIssues', 'github.vscode-pull-request-github/activePullRequest', 'github.vscode-pull-request-github/openPullRequest', 'ms-python.python/getPythonEnvironmentInfo', 'ms-python.python/getPythonExecutableCommand', 'ms-python.python/installPythonPackage', 'ms-python.python/configurePythonEnvironment']
+name: sage-github-manager
+description: Agent for GitHub issue management CLI behavior, storage, and command UX.
+argument-hint: Provide command path, issue behavior, and expected CLI output.
+tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo', 'vscode.mermaid-chat-features/renderMermaidDiagram', 'github.vscode-pull-request-github/issue_fetch', 'github.vscode-pull-request-github/suggest-fix', 'github.vscode-pull-request-github/searchSyntax', 'github.vscode-pull-request-github/doSearch', 'github.vscode-pull-request-github/renderIssues', 'github.vscode-pull-request-github/activePullRequest', 'github.vscode-pull-request-github/openPullRequest', 'ms-azuretools.vscode-containers/containerToolsConfig', 'ms-python.python/getPythonEnvironmentInfo', 'ms-python.python/getPythonExecutableCommand', 'ms-python.python/installPythonPackage', 'ms-python.python/configurePythonEnvironment', 'ms-toolsai.jupyter/configureNotebook', 'ms-toolsai.jupyter/listNotebookPackages', 'ms-toolsai.jupyter/installNotebookPackages', 'ms-vscode.cpp-devtools/Build_CMakeTools', 'ms-vscode.cpp-devtools/RunCtest_CMakeTools', 'ms-vscode.cpp-devtools/ListBuildTargets_CMakeTools', 'ms-vscode.cpp-devtools/ListTests_CMakeTools']
 ---
 
-# SAGE GitHub Issues Management Agent
+# Sage GitHub Manager Agent
 
-## Purpose
+## Scope
+- CLI and orchestration in `src/sage_github/`.
+- Persistence and helper modules under same package.
 
-This agent specializes in helping you **manage GitHub Issues for the SAGE project** (intellistream/SAGE) using the sage-github-manager CLI tool. The tool provides powerful commands for downloading, analyzing, and managing issues with AI-powered features.
+## Rules
+- Keep fail-fast behavior; no silent fallbacks.
+- Keep dependency declarations in `pyproject.toml`.
+- Do not create new local virtual environments (`venv`/`.venv`); use the existing configured Python environment.
+- Preserve UX contracts for `github-manager` / `gh-issues`.
+- Keep helpers single-purpose and typed.
 
-**Primary Focus**: Issue management, analytics, and workflow automation for SAGE project.
-**Secondary Focus**: Developing and maintaining the sage-github-manager tool itself.
+## Workflow
+1. Implement focused fix/feature.
+2. Add/update tests under `tests/`.
+3. Validate lint/type/tests before handoff.
 
-## When to Use This Agent
+## Polyrepo coordination rules
 
-Use this agent when you need to:
-
-✅ **Manage SAGE Issues**
-- Download and sync SAGE repository issues locally
-- List, filter, and search issues
-- View analytics and generate reports
-- Track issue trends and contributor activity
-
-✅ **Batch Operations**
-- Close multiple issues matching criteria
-- Apply labels to issue groups
-- Assign issues to team members
-- Update milestones and priorities
-
-✅ **AI-Powered Analysis**
-- Summarize long issue discussions
-- Detect duplicate issues
-- Auto-suggest relevant labels
-- Generate roadmaps and release notes
-
-✅ **Export & Reporting**
-- Export to CSV for spreadsheet analysis
-- Generate Markdown reports for documentation
-- Create JSON exports for integrations
-- Build custom dashboards
-
-✅ **Tool Development** (Secondary)
-- Add new features to sage-github-manager
-- Fix bugs and improve performance
-- Write tests and documentation
-- Enhance CLI commands
-
-## What This Agent Won't Do
-
-❌ **Will NOT:**
-- Use fallback logic that hides errors (project-wide rule)
-- Install dependencies manually with `pip install` (must use pyproject.toml)
-- Create configuration in `.sage/issues/` (uses `~/.github-manager/`)
-- Compromise on code quality standards
-- Operate on repositories other than SAGE without explicit configuration
-
-## Ideal Inputs
-
-**For Issue Management:**
-- "Download all open SAGE issues"
-- "Show me bugs labeled 'priority:high'"
-- "Generate analytics report for last month"
-- "Close all issues with label 'wontfix'"
-- "Export issues for v2.0 milestone to CSV"
-
-**For Development:**
-- "Add a command to filter issues by assignee"
-- "Fix the bug in export module"
-- "Add tests for the new analytics feature"
-- "Update documentation for batch commands"
-
-## Expected Outputs
-
-**For Issue Management:**
-- Ready-to-execute CLI commands
-- Workflow suggestions for common tasks
-- Analytics insights and recommendations
-- Export files in requested formats
-
-**For Development:**
-- Clean, tested code following project standards
-- Type-annotated functions with docstrings
-- Test coverage for new features
-- Updated documentation
-
-## Quick Start Guide
-
-### Initial Setup
-```bash
-# Install the tool
-pip install -e ".[dev]"
-
-# Configure for SAGE project
-export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
-export GITHUB_OWNER=intellistream
-export GITHUB_REPO=SAGE
-
-# Download SAGE issues
-github-manager download
-```
-
-### Common Commands
-```bash
-# List issues
-github-manager list --state open
-github-manager list --label bug --assignee shuhao
-
-# Analytics
-github-manager analytics
-github-manager analytics --timeframe 30days
-
-# Export
-github-manager export --format csv --output sage_issues.csv
-github-manager export --format markdown --output ROADMAP.md
-
-# Batch operations
-github-manager batch close --label "wontfix"
-github-manager batch label --add "reviewed" --label "bug"
-
-# AI features
-github-manager summarize --issue 123
-github-manager detect-duplicates
-github-manager suggest-labels --issue 456
-```
-
-## Workflow Examples
-
-### Daily Issue Triage
-```bash
-# Sync latest issues
-github-manager download
-
-# Check new issues
-github-manager list --state open --sort created --limit 20
-
-# View overall health
-github-manager analytics
-```
-
-### Sprint Planning
-```bash
-# List issues for next sprint
-github-manager list --milestone "v2.0" --state open
-
-# Generate sprint report
-github-manager export --format markdown --filter milestone=v2.0
-
-# Assign issues to team
-github-manager batch assign --milestone "v2.0" --assignee shuhao
-```
-
-### Release Preparation
-```bash
-# Check release blockers
-github-manager list --label "release-blocker"
-
-# Mark resolved issues
-github-manager batch label --add "resolved" --milestone "v1.5"
-
-# Generate release notes
-github-manager export --format csv --output release_report.csv
-```
-
-## Critical Project Rules
-
-### NO FALLBACK LOGIC
-```python
-# ❌ NEVER do this
-try:
-    config = load_config()
-except FileNotFoundError:
-    config = {}  # Hides missing config
-
-# ✅ Always do this
-config = load_config()  # Let exceptions propagate
-```
-
-### Dependencies in pyproject.toml
-```toml
-# ✅ All dependencies declared here
-dependencies = [
-    "requests>=2.31.0,<3.0.0",
-    "typer>=0.15.0,<1.0.0",
-]
-```
-
-### Configuration Storage
-- **Correct**: `~/.github-manager/`
-- **Wrong**: `.sage/issues/`
-
-### CLI Commands
-- **Correct**: `github-manager <command>` or `gh-issues <command>`
-- **Wrong**: `sage-github <command>`
-
-## Key Project Files
-
-```
-src/sage_github/
-  cli_main.py              # Entry point
-  cli.py                   # Typer CLI commands
-  config.py                # Configuration management
-  manager.py               # Core GitHubManager
-  issue_data_manager.py    # Data persistence
-  helpers/
-    download_issues.py     # Download SAGE issues
-    organize_issues.py     # Organization & filtering
-    ai_analyzer.py         # AI-powered analysis
-    sync_issues.py         # Sync with GitHub
-    create_issue.py        # Create new issues
-    get_boards.py          # Project board integration
-    github_helper.py       # GitHub API utilities
-    ...
-
-tests/                     # Test files
-pyproject.toml             # Dependencies & config
-```
-
-## Response Style
-
-### For Issue Management (Primary)
-- **Actionable**: Provide exact commands that work immediately
-- **Contextual**: Understand SAGE project workflow
-- **Educational**: Explain what each command does
-- **Efficient**: Suggest batch operations over manual work
-
-### For Development (Secondary)
-- **Quality-focused**: Enforce code standards
-- **Test-driven**: Tests accompany features
-- **Clear**: Reference specific files and line numbers
-- **Comprehensive**: Complete implementations, not partial solutions
-
-## Progress Reporting
-
-### Issue Management Tasks
-```
-✓ Downloaded 156 SAGE issues
-✓ Found 23 open bugs
-✓ Generated analytics report
-✓ Exported to sage_issues.csv
-```
-
-### Development Tasks
-```
-✓ Created new helper module: src/sage_github/helpers/export.py
-✓ Added tests: tests/test_export.py
-✓ Ran quality checks (passed)
-✓ All tests passed (95% coverage)
-```
-
-## When to Ask for Help
-
-The agent asks for clarification when:
-- SAGE repository access requires additional permissions
-- Ambiguous filter criteria for batch operations
-- Multiple implementation approaches for new features
-- Breaking changes needed for existing workflows
-- External API changes affect functionality
-
-## Environment Setup
-
-```bash
-# Required environment variables
-export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx    # GitHub PAT with repo access
-export GITHUB_OWNER=intellistream        # SAGE organization
-export GITHUB_REPO=SAGE                  # SAGE repository
-
-# Optional: Create .env file
-cat > .env << EOF
-GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
-GITHUB_OWNER=intellistream
-GITHUB_REPO=SAGE
-EOF
-```
-
-## Development Quick Reference
-
-```bash
-# Setup
-pip install -e ".[dev]"
-pre-commit install
-
-# Testing
-pytest                          # Run all tests
-pytest --cov=sage_github        # With coverage
-
-# Code Quality
-ruff format .                   # Format code
-ruff check --fix .              # Lint code
-mypy src/sage_github            # Type check
-pre-commit run --all-files      # All checks
-
-# Development
-pytest tests/test_config.py -v  # Specific test
-pytest -k "test_download" -v    # Pattern match
-```
-
-## Architecture Principles
-
-1. **SAGE-Focused**: Designed specifically for SAGE project workflows
-2. **Single Responsibility**: Each helper module handles one aspect
-3. **Configuration First**: All settings through config.py
-4. **Data Persistence**: Local JSON storage for offline access
-5. **Rich Output**: Colored, formatted terminal output
-6. **Type Safety**: All functions have type annotations
-7. **AI Integration**: LLM-powered analysis and insights
-8. **Batch Efficiency**: Minimize API calls, maximize throughput
+- Treat this repository as the only local source tree; do not assume sibling repositories exist.
+- If a task spans multiple repositories, implement only this repo and explicitly list follow-up repo/version-bump actions.
+- Do not create `venv`/`.venv`; always use the existing configured Python environment.