swe-copilot-agents 0.1.0__tar.gz

swe_copilot_agents-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json

swe_copilot_agents-0.1.0/CLAUDE.md

@@ -0,0 +1,161 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Objective
+
+This repository generates GitHub Copilot agents from source materials. Agents are defined in `.agent.md` files with YAML frontmatter and custom instructions that define the agent's persona, tech stack, project structure, workflows, commands, and boundaries.
+
+### Workflow
+
+1. **Read source** from `copilot-agent-sources/` folder (contains source materials like blog posts, documentation)
+2. **Generate agents** and save to `agents/` folder
+3. **Human-in-the-loop**: Humans review and improve `agent.md` files based on real-world usage experience
+
+### Key Concepts from Source Material
+
+Effective agent.md files are **specific**, not vague. The best agents have:
+- **Clear persona**: "QA software engineer who writes tests" not "helpful assistant"
+- **Executable commands**: Put commands early with flags (`pytest -v`, `npm run build`)
+- **Code examples**: Show good output style, don't just describe it
+- **Clear boundaries**: What to always do, ask first, never do
+- **Specific stack**: "React 18, TypeScript, Vite, Tailwind" not "React project"
+
+### Agent File Structure
+
+GitHub Copilot agents use the `.agent.md` file extension with YAML frontmatter:
+
+```yaml
+---
+name: agent-name              # Optional: defaults to filename
+description: Required description of agent's purpose
+target: vscode | github-copilot  # Optional: defaults to both
+tools: ["read", "edit", "search"]  # Optional: omit for all tools
+disable-model-invocation: false   # Optional: manual selection only
+---
+```
+
+#### YAML Frontmatter Properties
+
+| Property | Type | Required | Purpose |
+|----------|------|----------|---------|
+| `name` | string | No | Display name (defaults to filename) |
+| `description` | string | **Yes** | Agent's purpose and capabilities |
+| `target` | string | No | `vscode` or `github-copilot` (both if omitted) |
+| `tools` | list | No | Tool names to enable (all if omitted) |
+| `disable-model-invocation` | boolean | No | Require manual selection if `true` |
+| `mcp-servers` | object | No | MCP server configs (org/enterprise only) |
+| `metadata` | object | No | Key-value annotation pairs |
+
+#### Tool Aliases
+
+| Primary | Compatible aliases | Purpose |
+|---------|-------------------|---------|
+| `execute` | `shell`, `Bash`, `powershell` | Run shell commands |
+| `read` | `Read`, `NotebookRead` | Read file contents |
+| `edit` | `Edit`, `MultiEdit`, `Write`, `NotebookEdit` | Edit files |
+| `search` | `Grep`, `Glob` | Search files/text |
+| `agent` | `custom-agent`, `Task` | Invoke other agents |
+| `web` | `WebSearch`, `WebFetch` | Web search/fetch |
+| `todo` | `TodoWrite` | Manage task lists |
+
+### Agent Naming
+
+- Filename (without `.agent.md`) used as default `name` if not specified
+- Only these characters allowed: `.`, `-`, `_`, `a-z`, `A-Z`, `0-9`
+- For org/enterprise: place in root `agents/` directory (not `.github/agents/`)
+
+### Agent Versioning
+
+- Based on Git commit SHAs of the agent profile file
+- Branches/tags can have different agent versions
+- PRs use consistent agent version throughout
+
+## Folder Structure
+
+```
+copilot-agent-sources/  # Source materials (blog posts, docs)
+  ├── github-blog.txt              # Original patterns source
+  ├── create-custom-agent.md       # How to create agents
+  └── custom-agents-configuration.md  # YAML configuration reference
+
+agents/                  # Generated .agent.md files
+  └── [agent-name].agent.md   # Individual agent definitions
+
+skills/                  # Additional tools (includes pdf-slides skill)
+```
+
+## Creating a New Agent
+
+When creating an agent from source materials:
+
+1. Read the relevant source file from `copilot-agent-sources/`
+2. Extract the agent persona, commands, and best practices
+3. Create a new agent file in `agents/[agent-name].agent.md` with this structure:
+
+```markdown
+---
+name: agent-name
+description: One-sentence description of agent's purpose and capabilities
+---
+
+You are an expert [role] for this project.
+
+## Persona
+- You specialize in [specific task]
+- Your output: [what you produce]
+
+## Project knowledge
+- **Tech Stack:** [technologies with versions]
+- **File Structure:**
+  - `src/` – [description]
+  - `tests/` – [description]
+
+## Tools you can use
+- **Build:** `command` (description)
+- **Test:** `command` (description)
+
+## Standards
+[Code style examples, naming conventions]
+
+## Boundaries
+- ✅ **Always:** [what to do]
+- ⚠️ **Ask first:** [what requires approval]
+- 🚫 **Never:** [what to avoid]
+```
+
+4. Have a human review and refine based on actual usage
+
+## Human-in-the-Loop Process
+
+After using an agent:
+1. Note what worked well and what didn't
+2. Update the agent.md file with:
+   - Missing commands that were needed
+   - New boundaries based on mistakes
+   - Better examples from successful interactions
+3. The agent.md file evolves through real-world iteration
+
+## Common Agent Types
+
+- **@docs-agent** - Writes documentation from code
+- **@test-agent** - Writes unit/integration/tests
+- **@lint-agent** - Fixes code style and formatting
+- **@api-agent** - Builds API endpoints
+- **@security-agent** - Analyzes code for security issues
+- **@deploy-agent** - Handles builds and deployments
+- **@planner-agent** - Creates implementation plans (read/search/edit only)
+
+## Skills: PDF Slides Generator
+
+The `skills/pdf-slides/` folder contains a separate skill for generating PDF slide decks from JSON outlines. This is independent of the agent generation workflow.
+
+```bash
+# Generate PDF from JSON outline
+python skills/pdf-slides/skill.py outline.json -o output.pdf
+```
+
+## Additional Resources
+
+- [awesome-copilot community collection](https://github.com/github/awesome-copilot/tree/main/agents)
+- [Custom agents tutorials](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

swe_copilot_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Awesome Copilot Agents Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swe_copilot_agents-0.1.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: swe-copilot-agents
+Version: 0.1.0
+Summary: GitHub Copilot custom agents for orchestrating the complete software development lifecycle
+Project-URL: Homepage, https://github.com/khaerulumam42/agent-generator
+Project-URL: Repository, https://github.com/khaerulumam42/agent-generator
+Project-URL: Issues, https://github.com/khaerulumam42/agent-generator/issues
+Author-email: Khaerul Umam <khaerul@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,copilot,development,github
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Awesome Skills - GitHub Copilot Agents
+
+A collection of specialized GitHub Copilot custom agents for orchestrating the complete software development lifecycle, from requirements gathering through implementation, testing, and review.
+
+## Overview
+
+This repository contains AI agents that follow the **"coordinator and worker" pattern**—where specialist agents perform focused work under the guidance of an orchestrator. Each agent has a strong persona, clear boundaries, and specific expertise.
+
+---
+
+## Agents
+
+### @dev-orchestrator
+
+**Role:** Meticulous technical lead who conducts specialist agents like an orchestra conductor
+
+**Persona:**
+- **Philosophy:** "Right agent, right time, right order"
+- **Traits:** Meticulous, patient, organized, clear
+- **Metaphor:** Orchestra conductor who doesn't play instruments but brings out the best performance from each soloist
+
+**Responsibilities:**
+- Coordinates the complete development lifecycle across 4 movements
+- Tracks state obsessively (which movement, which soloist, which outputs)
+- Manages review cycles with automatic fix loops (max 2 reviews)
+- Seeks human approval at each intermission
+
+**Orchestrated Agents:**
+- @brainstormer (Movement I - Planning)
+- @plan-executor (Movement II - Implementation)
+- @plan-reviewer (Movement III - Review)
+- @pytest-agent (Movement IV - Testing, optional)
+
+**Best Practices:** ✅ **EXCELLENT**
+- Strong, distinctive persona with musical terminology throughout
+- Clear YAML configuration with `agents` restriction
+- Visual workflow diagram (ASCII art)
+- Comprehensive error handling and human intervention pathways
+- Review cycle feedback loop with automatic fixes
+- Memorable tagline: *"A great conductor doesn't play every instrument—they know exactly when each section should perform."*
+
+---
+
+### @brainstormer
+
+**Role:** Curious planning agent who asks clarifying questions to crystallize requirements
+
+**Persona:**
+- **Philosophy:** Uncertainty triggers questions, not assumptions
+- **Traits:** Insatiably curious, thorough, multi-round questioner (1-10 rounds)
+- **Metaphor:** Exploratory researcher who never assumes
+
+**Responsibilities:**
+- Asks 1-10 rounds of clarifying questions before writing plans
+- Queries knowledge graph for impact analysis (downstream, cycles, bottlenecks, test seams)
+- Creates detailed markdown plan documents in `docs/plan/YYYY-MM-DD-*.md`
+- Integrates knowledge graph findings into every plan
+
+**Best Practices:** ✅ **EXCELLENT**
+- Strong persona ("insatiably curious")
+- Knowledge graph integration for impact analysis
+- Multi-round questioning framework with defined stages
+- Clear completion criteria (user confirmation before writing plan)
+- Comprehensive plan output template with KG analysis sections
+- Workflow summary diagram
+
+---
+
+### @plan-executor
+
+**Role:** Senior Python engineer who executes plans by blending seamlessly with existing codebases
+
+**Persona:**
+- **Philosophy:** "Consistency > Clean Code"
+- **Traits:** Chameleon-like, adaptive, pattern-matching
+- **Metaphor:** Code chameleon who becomes indistinguishable from existing code
+
+**Responsibilities:**
+- Reads 3-5 existing files to understand patterns before writing
+- Matches existing style exactly (naming, imports, error handling, formatting)
+- Implements requirements from plan documents
+- Never "fixes" existing code because it's ugly
+
+**Best Practices:** ✅ **EXCELLENT**
+- Strong persona with clear philosophy ("Consistency > Clean Code")
+- Concrete code examples showing good vs. bad matching
+- Specific matching table (naming, imports, errors, strings, formatting)
+- Clear boundaries (never "revamp" existing code)
+- Executable commands for studying patterns
+
+---
+
+### @plan-reviewer
+
+**Role:** Senior code reviewer and quality assurance engineer who rigorously audits implementation against plans
+
+**Persona:**
+- **Philosophy:** "Evidence over assumptions"
+- **Traits:** Ruthlessly thorough, evidence-driven, uncompromising
+- **Metaphor:** Auditor who proves everything through code inspection
+
+**Responsibilities:**
+- Extracts all requirements from plan documents
+- Searches codebase for concrete evidence of each requirement
+- Categorizes execution status (Fully/Partially/Not Executed)
+- Performs brittleness analysis via knowledge graph (high centrality, excessive dependencies, deep chains)
+- Provides prioritized remediation recommendations
+
+**Best Practices:** ✅ **EXCELLENT**
+- Strong persona ("ruthlessly thorough")
+- Clear execution status definitions with evidence gathering checklist
+- Knowledge graph brittleness analysis with risk levels
+- Comprehensive report output format
+- Priority assignment criteria (P0-P3)
+- Status determination rules with specific conditions
+
+---
+
+### @pytest-agent
+
+**Role:** Senior Python QA engineer specializing in pytest with expert-level mocking and patching
+
+**Persona:**
+- **Philosophy:** "Depth over breadth"
+- **Traits:** Exhaustive, comprehensive, edge-case obsessed
+- **Metaphor:** Test surgeon who operates at every code path
+
+**Responsibilities:**
+- Writes exhaustive test suites (happy path, edge cases, errors, state, integration)
+- Expert-level mocking and patching (Mock, MagicMock, patch, PropertyMock)
+- Targets >80% coverage for new code
+- Tests only newly implemented code (respects scope boundaries)
+
+**Best Practices:** ✅ **EXCELLENT**
+- Strong persona ("depth over breadth")
+- Comprehensive test coverage requirements table
+- Expert mocking examples with all patterns
+- Clarification protocol for ambiguous behavior
+- Clear scope boundaries (only test new code)
+- Code style examples (good vs. bad)
+
+---
+
+### @knowledge-graph-agent
+
+**Role:** Expert code analysis specialist who builds knowledge-base graphs from codebases
+
+**Persona:**
+- **Philosophy:** Static analysis reveals code architecture
+- **Traits:** Multi-lingual, systematic, incremental
+- **Metaphor:** Code cartographer who maps relationships
+
+**Responsibilities:**
+- Scans codebases and generates `knowledge-graph.yaml` in project root
+- Tracks relationships: files, functions, classes, imports, call chains, concerns
+- Supports incremental updates (only changed files)
+- Version tracking via git commit hashes
+- Multi-language support (Python, JS/TS, Go, Java, Rust)
+
+**Best Practices:** ✅ **EXCELLENT**
+- Clear startup behavior with git hash comparison
+- Incremental update mode to avoid full rescans
+- Comprehensive YAML output format specification
+- Complete analysis standards with good/bad examples
+- Web framework pattern recognition (Flask, FastAPI, Express, Gin)
+- Validation checklist before completion
+
+---
+
+## Best Practices Summary
+
+| Agent | Persona | Boundaries | Commands | Examples | Workflow Diagram | Overall |
+|-------|---------|------------|----------|----------|------------------|---------|
+| @dev-orchestrator | ✅ Strong | ✅ Clear | ✅ Complete | ✅ Musical | ✅ ASCII | **EXCELLENT** |
+| @brainstormer | ✅ Strong | ✅ Clear | ✅ Complete | ✅ Plan format | ✅ Flowchart | **EXCELLENT** |
+| @plan-executor | ✅ Strong | ✅ Clear | ✅ Complete | ✅ Code style | ❌ None | **EXCELLENT** |
+| @plan-reviewer | ✅ Strong | ✅ Clear | ✅ Complete | ✅ Report format | ❌ None | **EXCELLENT** |
+| @pytest-agent | ✅ Strong | ✅ Clear | ✅ Complete | ✅ Test style | ❌ None | **EXCELLENT** |
+| @knowledge-graph-agent | ✅ Strong | ✅ Clear | ✅ Complete | ✅ YAML format | ❌ None | **EXCELLENT** |
+
+**Overall Repository Quality:** ✅ **EXCELLENT** - All agents follow GitHub Copilot custom agent best practices with strong personas, clear boundaries, executable commands, and comprehensive examples.
+
+---
+
+## Workflow Orchestration
+
+### Complete Development Cycle
+
+```
+User Request
+      ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                    @dev-orchestrator (Conductor)                 │
+└─────────────────────────────────────────────────────────────────┘
+      │
+      ├─ Movement I: @brainstormer → Plan document
+      │     (1-10 rounds of questions)
+      │     ↓ Human Approval
+      │
+      ├─ Movement II: @plan-executor → Implementation
+      │     (Match existing code patterns)
+      │     ↓ Human Approval
+      │
+      ├─ Movement III: @plan-reviewer → Review #1
+      │     ↓ Major issues found?
+      │     ├─ YES → Movement IIb: @plan-executor (Fix)
+      │     │           ↓ Movement IIIb: @plan-reviewer (Re-review FINAL)
+      │     │                  ↓ Issues persist?
+      │     │                  └─ YES → Human Intervention
+      │     └─ NO → Continue
+      │     ↓ Human Approval
+      │
+      └─ Movement IV: @pytest-agent → Tests (Optional)
+            ↓
+         Finale
+```
+
+### Review Cycle Logic
+
+1. **Review #1** identifies issues → If major issues found, trigger fix cycle
+2. **Fix Cycle** (@plan-executor) implements recommendations
+3. **Review #2 (FINAL)** re-audits → If issues persist, human intervention required
+4. **Maximum 2 reviews** enforced
+
+---
+
+## Usage
+
+### Basic Agent Invocation
+
+```bash
+# In VS Code with GitHub Copilot Chat
+@dev-orchestrator
+I want to add a user authentication system with JWT tokens
+
+# Or invoke a specific agent directly
+@brainstormer
+I need to add a search feature to my application
+
+@plan-reviewer
+Review the implementation against docs/plan/2025-03-02-auth.md
+```
+
+### File Locations
+
+- **Agents:** `agents/*.agent.md`
+- **Plans:** `docs/plan/YYYY-MM-DD-*.md`
+- **Knowledge Graph:** `knowledge-graph.yaml` (project root)
+
+---
+
+## Agent File Structure
+
+All agents follow this structure:
+
+```yaml
+---
+name: agent-name
+description: Brief description of purpose
+tools: ["tool1", "tool2"]
+agents: ["agent1", "agent2"]  # For orchestrators only
+target: vscode | github-copilot
+---
+
+# Persona description
+## Core Philosophy
+## Your Role
+## [Specific sections per agent]
+## Boundaries (Always Do / Ask First / Never Do)
+## Commands
+```
+
+---
+
+## Contributing
+
+When adding new agents:
+
+1. **Follow the persona pattern** - Give each agent a distinctive personality
+2. **Define clear boundaries** - What they always do, ask first, never do
+3. **Include executable commands** - Concrete bash commands they can run
+4. **Provide examples** - Good vs. bad outputs
+5. **Add visual workflow** - ASCII diagrams for complex agents
+6. **Document best practices** - Mark if agent follows Copilot best practices
+
+---
+
+## License
+
+[Your License Here]
+
+---
+
+## Inspiration
+
+Based on patterns from:
+- [GitHub Custom Agents Documentation](https://docs.github.com/en/copilot/customizing-custom-agents)
+- [awesome-copilot community collection](https://github.com/github/awesome-copilot)
+- Subagent orchestration patterns in VS Code