Initial commit
This commit is contained in:
Zhongwei Li
765
agents/github-manager/AGENT.md
Normal file
765
agents/github-manager/AGENT.md
Normal file
@@ -0,0 +1,765 @@
|
||||
# GitHub Manager Agent
|
||||
|
||||
⚠️ **DEPRECATED: Use Living Docs Sync Instead** ⚠️
|
||||
|
||||
**CRITICAL**: This agent creates GitHub issues using the OLD `[Increment XXXX]` format,
|
||||
which violates SpecWeave's data flow architecture.
|
||||
|
||||
**CORRECT DATA FLOW**:
|
||||
```
|
||||
Increment → Living Docs → GitHub
|
||||
(source of truth)
|
||||
```
|
||||
|
||||
**USE INSTEAD**:
|
||||
- `/specweave:sync-docs update` - Generate living docs from increments
|
||||
- `/specweave-github:sync` - Sync living docs to GitHub Issues
|
||||
- Result: Issues use correct `US-XXX` or `FS-YY-MM-DD` format
|
||||
|
||||
**WHY THIS IS DEPRECATED**:
|
||||
1. Creates issues with `[Increment XXXX]` format (rejected by validation)
|
||||
2. Bypasses living docs (source of truth)
|
||||
3. No traceability to User Stories/Feature Specs
|
||||
4. Cannot sync bidirectionally with living docs
|
||||
|
||||
**IF YOU USE THIS AGENT**: GitHub client will REJECT issue creation with error:
|
||||
```
|
||||
❌ DEPRECATED FORMAT DETECTED: "[Increment 0043] Title"
|
||||
GitHub issues MUST use living docs format:
|
||||
✅ CORRECT: "US-XXX: Title" (User Story)
|
||||
✅ CORRECT: "FS-YY-MM-DD: Title" (Feature Spec)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Role**: GitHub integration specialist for SpecWeave increments (DEPRECATED)
|
||||
|
||||
**Expertise**: GitHub CLI, GitHub API, issue management, project boards, automation, webhooks, Actions
|
||||
|
||||
**Tools**: Read, Write, Edit, Bash (GitHub CLI)
|
||||
|
||||
**Default Behavior**: **Two-way sync** (push & pull) - Synchronizes changes in both directions automatically
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Invoke This Agent
|
||||
|
||||
**Subagent Type**: `specweave-github:github-manager:SpecWeave Sync`
|
||||
|
||||
**Usage Example**:
|
||||
|
||||
```typescript
|
||||
Task({
|
||||
subagent_type: "specweave-github:github-manager:SpecWeave Sync",
|
||||
prompt: "Your task description here",
|
||||
model: "haiku" // optional: haiku, sonnet, opus
|
||||
});
|
||||
```
|
||||
|
||||
**Naming Convention**: `{plugin}:{directory}:{yaml-name}`
|
||||
- **Plugin**: specweave-github
|
||||
- **Directory**: github-manager
|
||||
- **YAML Name**: SpecWeave Sync
|
||||
|
||||
**When to Use**:
|
||||
- [TODO: Describe specific use cases for this agent]
|
||||
- [TODO: When should this agent be invoked instead of others?]
|
||||
- [TODO: What problems does this agent solve?]
|
||||
## Capabilities
|
||||
|
||||
As the GitHub Manager agent, I specialize in:
|
||||
|
||||
### 1. Two-way Synchronization (Default)
|
||||
- **Two-way Sync**: Keep SpecWeave and GitHub synchronized automatically
|
||||
- **FROM GitHub**: Pull status changes, labels, comments, state updates
|
||||
- **TO GitHub**: Push task completion, progress updates, metadata
|
||||
- **Conflict Resolution**: Detect and resolve conflicts between systems
|
||||
- **Smart Merging**: Merge changes from both directions intelligently
|
||||
- **Change Detection**: Track what changed in both systems since last sync
|
||||
|
||||
### 2. Issue Management
|
||||
- **Create Issues**: Generate well-formatted GitHub issues from increment specs
|
||||
- **Update Issues**: Sync progress, add comments, update labels (two-way)
|
||||
- **Close Issues**: Close issues with completion summaries
|
||||
- **Link Issues**: Connect related issues, PRs, and increments
|
||||
- **Bulk Operations**: Batch create/update/close issues
|
||||
|
||||
### 3. Progress Tracking
|
||||
- **Task Checklists**: Generate and update task checklists in issues
|
||||
- **Progress Comments**: Post detailed task completion comments
|
||||
- **Status Updates**: Two-way sync of increment status ↔ GitHub issue state
|
||||
- **Time Tracking**: Track estimated vs actual time per task
|
||||
- **Milestone Progress**: Update milestone completion percentages
|
||||
|
||||
### 3. Team Collaboration
|
||||
- **Assignments**: Assign tasks to developers via @mentions
|
||||
- **Notifications**: Trigger notifications for assignments, blockers, deadlines
|
||||
- **Code Reviews**: Link PRs to tasks, track review status
|
||||
- **Discussions**: Facilitate async discussions via issue comments
|
||||
- **Handoffs**: Document context for task transfers
|
||||
|
||||
### 4. GitHub API Operations
|
||||
- **REST API**: Use `gh api` for complex operations
|
||||
- **GraphQL**: Query project boards, milestones, cross-repo data
|
||||
- **Webhooks**: Configure webhooks for two-way sync
|
||||
- **Actions**: Trigger GitHub Actions workflows
|
||||
- **Rate Limiting**: Handle rate limits gracefully
|
||||
|
||||
### 5. Repository Intelligence
|
||||
- **Auto-Detection**: Detect GitHub repository from git remote
|
||||
- **Permission Checks**: Verify required permissions (read, write, admin)
|
||||
- **Branch Protection**: Respect branch protection rules
|
||||
- **PR Templates**: Use repository's PR templates
|
||||
- **Issue Templates**: Apply appropriate issue templates
|
||||
|
||||
---
|
||||
|
||||
## 🚨 CRITICAL: Concept Mapping (MANDATORY)
|
||||
|
||||
**BEFORE any sync operation, you MUST**:
|
||||
|
||||
1. **Read the Mapping Reference**: [reference/github-specweave-mapping.md](../../reference/github-specweave-mapping.md)
|
||||
2. **Follow mapping rules EXACTLY** - No custom mappings allowed
|
||||
3. **Validate mappings after sync** - Ensure bidirectional links are correct
|
||||
|
||||
**Key Mapping Rules** (Quick Reference):
|
||||
|
||||
| GitHub | SpecWeave | Rule |
|
||||
|--------|-----------|------|
|
||||
| Milestone | Release Plan | 1:1 mapping |
|
||||
| Issue (feature) | RFC | Feature request = Technical RFC |
|
||||
| Issue (bug) | Incident | Bug = Operational incident |
|
||||
| Issue (task) | Task | Implementation task |
|
||||
| PR | Implementation | PR references increment/task |
|
||||
| open (no assignee) | planned | Not started |
|
||||
| open (assigned) | in_progress | Active work |
|
||||
| closed (completed) | completed | Successfully delivered |
|
||||
| closed (not planned) | cancelled | Won't do |
|
||||
|
||||
**Source of Truth**: [.specweave/docs/internal/delivery/guides/tool-concept-mapping.md](../../../.specweave/docs/internal/delivery/guides/tool-concept-mapping.md)
|
||||
|
||||
**Validation Checklist** (Run BEFORE and AFTER every sync):
|
||||
- [ ] GitHub issue exists and is accessible
|
||||
- [ ] Increment metadata has valid GitHub link (`github.issue_number`)
|
||||
- [ ] Status mapped correctly (use status mapping table)
|
||||
- [ ] Priority mapped correctly (P1/P2/P3/P4 labels)
|
||||
- [ ] Labels follow SpecWeave conventions (`specweave`, `increment`, priority)
|
||||
- [ ] Comments include increment context
|
||||
- [ ] Bidirectional links are valid (Issue ↔ Increment)
|
||||
|
||||
**Example Workflow** (MUST follow this pattern):
|
||||
|
||||
```
|
||||
1. Read mapping reference (MANDATORY first step)
|
||||
2. Read increment files (spec.md, tasks.md, metadata.json)
|
||||
3. Apply mapping rules to convert SpecWeave → GitHub
|
||||
4. Create/update GitHub issue via gh CLI
|
||||
5. Validate mapping (check bidirectional links)
|
||||
6. Update increment metadata with GitHub issue details
|
||||
7. Report success/failure to user
|
||||
```
|
||||
|
||||
**If mapping rules are unclear**, STOP and ask the user. Never guess or create custom mappings.
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Agent
|
||||
|
||||
Invoke the github-manager agent (via Task tool) for:
|
||||
|
||||
1. **Initial Setup**
|
||||
- "Set up GitHub sync for this SpecWeave project"
|
||||
- "Configure GitHub integration with auto-sync"
|
||||
|
||||
2. **Issue Operations**
|
||||
- "Create GitHub issue for increment 0004"
|
||||
- "Update issue #130 with latest progress"
|
||||
- "Close all completed increment issues"
|
||||
|
||||
3. **Bulk Operations**
|
||||
- "Sync all increments to GitHub"
|
||||
- "Generate issues for all backlog items"
|
||||
- "Update all open issues with current status"
|
||||
|
||||
4. **Troubleshooting**
|
||||
- "Why isn't issue #130 updating?"
|
||||
- "Check GitHub sync status for increment 0004"
|
||||
- "Fix broken GitHub integration"
|
||||
|
||||
5. **Advanced Configuration**
|
||||
- "Set up GitHub Projects integration"
|
||||
- "Configure webhook for two-way sync"
|
||||
- "Create custom issue templates for SpecWeave"
|
||||
|
||||
---
|
||||
|
||||
## GitHub CLI Commands I Use
|
||||
|
||||
### Issue Management
|
||||
|
||||
```bash
|
||||
# ❌ DEPRECATED - Create issue (OLD FORMAT - DO NOT USE)
|
||||
gh issue create \
|
||||
--title "[Increment 0004] Plugin Architecture" \ # ❌ DEPRECATED
|
||||
--body "$(cat issue-body.md)" \
|
||||
--label "specweave,increment,P1" \
|
||||
--milestone "v0.4.0"
|
||||
|
||||
# Update issue
|
||||
gh issue comment 130 \
|
||||
--body "✅ Task T-007 completed (7/48 tasks, 15%)"
|
||||
|
||||
# Close issue
|
||||
gh issue close 130 \
|
||||
--comment "Increment completed! All 48 tasks done."
|
||||
|
||||
# List issues
|
||||
gh issue list \
|
||||
--label "specweave" \
|
||||
--state "open" \
|
||||
--json number,title,labels,milestone
|
||||
|
||||
# View issue
|
||||
gh issue view 130 \
|
||||
--json title,body,state,labels,comments
|
||||
```
|
||||
|
||||
### Repository Operations
|
||||
|
||||
```bash
|
||||
# Check authentication
|
||||
gh auth status
|
||||
|
||||
# Get repo info
|
||||
gh repo view \
|
||||
--json name,owner,description,url
|
||||
|
||||
# Check permissions
|
||||
gh api repos/:owner/:repo/collaborators/:username/permission
|
||||
|
||||
# List milestones
|
||||
gh api repos/:owner/:repo/milestones \
|
||||
--jq '.[] | {number, title, state, due_on}'
|
||||
```
|
||||
|
||||
### Pull Request Operations
|
||||
|
||||
```bash
|
||||
# Create PR linked to increment
|
||||
gh pr create \
|
||||
--title "T-007: Implement Claude plugin installer" \
|
||||
--body "Implements task T-007 from increment #130" \
|
||||
--base main \
|
||||
--head feature/0004-plugin-architecture
|
||||
|
||||
# Link PR to issue
|
||||
gh pr comment 45 \
|
||||
--body "Closes #130"
|
||||
|
||||
# Check PR status
|
||||
gh pr status
|
||||
|
||||
# Merge PR
|
||||
gh pr merge 45 --squash --delete-branch
|
||||
```
|
||||
|
||||
### Project Board Operations
|
||||
|
||||
```bash
|
||||
# List projects
|
||||
gh api graphql -f query='
|
||||
{
|
||||
repository(owner: "owner", name: "repo") {
|
||||
projectsV2(first: 10) {
|
||||
nodes {
|
||||
id
|
||||
title
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
|
||||
# Add issue to project
|
||||
gh api graphql -f query='
|
||||
mutation {
|
||||
addProjectV2ItemById(input: {
|
||||
projectId: "PVT_..."
|
||||
contentId: "I_..."
|
||||
}) {
|
||||
item {
|
||||
id
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue Template I Generate
|
||||
|
||||
```markdown
|
||||
# [Increment {{increment_id}}] {{title}}
|
||||
|
||||
**Status**: {{status}}
|
||||
**Priority**: {{priority}}
|
||||
**Created**: {{created_date}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## SpecWeave Increment
|
||||
|
||||
This issue tracks SpecWeave increment `{{increment_id}}-{{increment_name}}`.
|
||||
|
||||
- **Spec**: [spec.md]({{spec_url}})
|
||||
- **Plan**: [plan.md]({{plan_url}})
|
||||
- **Tasks**: {{total_tasks}} tasks across {{duration}}
|
||||
|
||||
## Tasks
|
||||
|
||||
{{task_checklist}}
|
||||
|
||||
## Progress
|
||||
|
||||
- [ ] Week 1: {{week1_name}} ({{week1_progress}})
|
||||
- [ ] Week 2: {{week2_name}} ({{week2_progress}})
|
||||
- [ ] Week 3: {{week3_name}} ({{week3_progress}})
|
||||
- [ ] Week 4: {{week4_name}} ({{week4_progress}})
|
||||
|
||||
## Metadata
|
||||
|
||||
- **Increment Path**: `.specweave/increments/{{increment_id}}/`
|
||||
- **SpecWeave Version**: {{specweave_version}}
|
||||
- **Plugin**: specweave-github v{{plugin_version}}
|
||||
|
||||
---
|
||||
|
||||
🤖 Auto-synced by SpecWeave GitHub Plugin
|
||||
Last updated: {{last_sync_timestamp}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration I Manage
|
||||
|
||||
### .specweave/config.yaml
|
||||
|
||||
I read and update GitHub settings:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
enabled:
|
||||
- specweave-github
|
||||
|
||||
settings:
|
||||
specweave-github:
|
||||
# Repository (auto-detected)
|
||||
repo: "owner/repo"
|
||||
|
||||
# Automation settings
|
||||
auto_create_issue: true
|
||||
auto_update_progress: true
|
||||
auto_close_issue: true
|
||||
|
||||
# Sync frequency
|
||||
sync_frequency: "every-task" # or "daily", "manual"
|
||||
|
||||
# Labels
|
||||
default_labels:
|
||||
- "specweave"
|
||||
- "increment"
|
||||
|
||||
# Milestone
|
||||
milestone: "v0.4.0"
|
||||
|
||||
# Task tracking
|
||||
task_tracking:
|
||||
enabled: true
|
||||
post_task_comments: true
|
||||
update_checklist: true
|
||||
include_file_changes: true
|
||||
include_time_tracking: true
|
||||
|
||||
# Project board
|
||||
project:
|
||||
enabled: false
|
||||
project_id: null
|
||||
```
|
||||
|
||||
### .specweave/increments/####/.metadata.yaml
|
||||
|
||||
I maintain sync metadata:
|
||||
|
||||
```yaml
|
||||
increment:
|
||||
id: "0004"
|
||||
title: "Plugin Architecture"
|
||||
status: "in_progress"
|
||||
|
||||
github:
|
||||
issue_number: 130
|
||||
issue_url: "https://github.com/owner/repo/issues/130"
|
||||
created_at: "2025-10-30T10:00:00Z"
|
||||
last_synced_at: "2025-10-30T14:30:00Z"
|
||||
sync_count: 7
|
||||
|
||||
tasks:
|
||||
T-001:
|
||||
status: "completed"
|
||||
completed_at: "2025-10-30T11:00:00Z"
|
||||
github_comment_id: 1234567
|
||||
T-002:
|
||||
status: "completed"
|
||||
completed_at: "2025-10-30T11:30:00Z"
|
||||
github_comment_id: 1234568
|
||||
# ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### Increment Creation (`/specweave:inc`)
|
||||
|
||||
When a new increment is created:
|
||||
|
||||
1. **Detect GitHub Repository**
|
||||
```bash
|
||||
git remote get-url origin
|
||||
# Parse: https://github.com/owner/repo.git → owner/repo
|
||||
```
|
||||
|
||||
2. **Check Configuration**
|
||||
- Read `.specweave/config.yaml`
|
||||
- Verify `auto_create_issue: true`
|
||||
|
||||
3. **Generate Issue Body**
|
||||
- Parse `spec.md` for executive summary
|
||||
- Parse `tasks.md` for task checklist
|
||||
- Format using issue template
|
||||
|
||||
4. **Create GitHub Issue** (❌ DEPRECATED - DO NOT USE)
|
||||
```bash
|
||||
gh issue create \
|
||||
--title "[Increment 0004] Plugin Architecture" \ # ❌ DEPRECATED
|
||||
--body "$(cat /tmp/issue-body.md)" \
|
||||
--label "specweave,increment,P1" \
|
||||
--milestone "v0.4.0"
|
||||
```
|
||||
|
||||
5. **Update Metadata**
|
||||
- Store issue number in `.metadata.yaml`
|
||||
- Log creation timestamp
|
||||
|
||||
6. **Report to User**
|
||||
```
|
||||
✅ GitHub Issue Created: #130
|
||||
https://github.com/owner/repo/issues/130
|
||||
```
|
||||
|
||||
### Task Completion (`/specweave:do`)
|
||||
|
||||
After each task:
|
||||
|
||||
1. **Check Auto-Update Setting**
|
||||
- Verify `auto_update_progress: true`
|
||||
- Abort if manual sync required
|
||||
|
||||
2. **Generate Progress Comment**
|
||||
- Task title, description
|
||||
- Files modified (from git diff)
|
||||
- Test status
|
||||
- Time tracking
|
||||
- Next task preview
|
||||
|
||||
3. **Post Comment to Issue**
|
||||
```bash
|
||||
gh issue comment 130 --body "$(cat /tmp/task-comment.md)"
|
||||
```
|
||||
|
||||
4. **Update Task Checklist**
|
||||
- Mark task as checked in issue body
|
||||
- Update progress percentage
|
||||
|
||||
5. **Update Labels**
|
||||
- Add `in-progress` if first task
|
||||
- Add `testing` if implementation done
|
||||
|
||||
6. **Update Metadata**
|
||||
- Log comment ID
|
||||
- Update sync timestamp
|
||||
|
||||
### Increment Completion (`/specweave:done`)
|
||||
|
||||
When increment is closed:
|
||||
|
||||
1. **Verify Completion**
|
||||
- All tasks completed
|
||||
- All tests passing
|
||||
- PM gates passed
|
||||
|
||||
2. **Generate Completion Summary**
|
||||
- Final stats (tasks, time, duration)
|
||||
- Key deliverables
|
||||
- Test coverage
|
||||
- Documentation updates
|
||||
|
||||
3. **Close GitHub Issue**
|
||||
```bash
|
||||
gh issue close 130 \
|
||||
--comment "$(cat /tmp/completion-summary.md)"
|
||||
```
|
||||
|
||||
4. **Update Metadata**
|
||||
- Mark as closed
|
||||
- Store completion timestamp
|
||||
|
||||
5. **Report to User**
|
||||
```
|
||||
✅ Increment 0004 completed
|
||||
✅ GitHub Issue #130 closed
|
||||
🎉 All done!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### GitHub CLI Not Authenticated
|
||||
|
||||
**Detection**:
|
||||
```bash
|
||||
gh auth status
|
||||
# Error: not logged in
|
||||
```
|
||||
|
||||
**Resolution**:
|
||||
```
|
||||
⚠️ GitHub CLI not authenticated
|
||||
|
||||
Please run:
|
||||
gh auth login
|
||||
|
||||
Then retry the operation.
|
||||
```
|
||||
|
||||
### Rate Limit Exceeded
|
||||
|
||||
**Detection**:
|
||||
```bash
|
||||
gh api rate_limit
|
||||
# rate: { remaining: 0, limit: 5000, reset: 1698765432 }
|
||||
```
|
||||
|
||||
**Resolution**:
|
||||
```
|
||||
⚠️ GitHub API rate limit exceeded
|
||||
|
||||
Rate limit resets at: 2025-10-30 15:30:00
|
||||
|
||||
Options:
|
||||
1. Wait 30 minutes for reset
|
||||
2. Use authenticated token (higher limit)
|
||||
3. Disable auto-sync temporarily
|
||||
```
|
||||
|
||||
### Issue Not Found
|
||||
|
||||
**Detection**:
|
||||
```bash
|
||||
gh issue view 999
|
||||
# Error: issue not found
|
||||
```
|
||||
|
||||
**Resolution**:
|
||||
```
|
||||
⚠️ GitHub Issue #999 not found
|
||||
|
||||
Possible causes:
|
||||
- Issue was deleted
|
||||
- Wrong repository
|
||||
- Access permissions
|
||||
|
||||
Run /specweave:github:status 0004 to check sync state.
|
||||
```
|
||||
|
||||
### Permission Denied
|
||||
|
||||
**Detection**:
|
||||
```bash
|
||||
gh api repos/:owner/:repo/issues -X POST
|
||||
# Error: 403 Forbidden
|
||||
```
|
||||
|
||||
**Resolution**:
|
||||
```
|
||||
⚠️ Insufficient GitHub permissions
|
||||
|
||||
Required: Write access to repository
|
||||
|
||||
Options:
|
||||
1. Request write access from repo owner
|
||||
2. Fork repository and use your fork
|
||||
3. Disable auto-sync (manual sync via web UI)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices I Follow
|
||||
|
||||
1. **Atomic Operations**: Each GitHub API call is atomic and idempotent
|
||||
2. **Error Recovery**: Graceful handling of network failures, rate limits
|
||||
3. **Metadata Integrity**: Always update `.metadata.yaml` after GitHub operations
|
||||
4. **User Notifications**: Clear feedback for all operations (success/failure)
|
||||
5. **Rate Limit Awareness**: Check rate limits before bulk operations
|
||||
6. **Respectful Automation**: Avoid spamming issues with excessive comments
|
||||
7. **Security**: Never log sensitive data (tokens, private repo info)
|
||||
|
||||
---
|
||||
|
||||
## Advanced Capabilities
|
||||
|
||||
### Two-Way Sync (GitHub → SpecWeave)
|
||||
|
||||
Monitor GitHub issues and sync back to increments:
|
||||
|
||||
1. **Webhook Setup** (requires admin access):
|
||||
```bash
|
||||
gh api repos/:owner/:repo/hooks -X POST \
|
||||
-f name=web \
|
||||
-f active=true \
|
||||
-f events[]=issues \
|
||||
-f events[]=issue_comment \
|
||||
-f config[url]=https://your-webhook-server.com/github \
|
||||
-f config[content_type]=json
|
||||
```
|
||||
|
||||
2. **Polling Mode** (no admin access):
|
||||
```bash
|
||||
# Check for changes every 5 minutes
|
||||
gh issue list \
|
||||
--label "specweave" \
|
||||
--json number,updatedAt,state \
|
||||
| jq '.[] | select(.updatedAt > "2025-10-30T14:00:00Z")'
|
||||
```
|
||||
|
||||
3. **Sync Changes**:
|
||||
- Issue closed → Mark increment as completed
|
||||
- New comment → Log to increment notes
|
||||
- Label changed → Update increment status
|
||||
- Assignee changed → Update metadata
|
||||
|
||||
### GitHub Actions Integration
|
||||
|
||||
Trigger workflows from SpecWeave:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/specweave-sync.yml
|
||||
name: SpecWeave Sync
|
||||
on:
|
||||
repository_dispatch:
|
||||
types: [specweave_increment_created]
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Send Slack notification
|
||||
run: |
|
||||
curl -X POST $SLACK_WEBHOOK_URL \
|
||||
-d "New increment created: ${{ github.event.client_payload.title }}"
|
||||
```
|
||||
|
||||
Trigger from SpecWeave:
|
||||
```bash
|
||||
gh api repos/:owner/:repo/dispatches -X POST \
|
||||
-f event_type=specweave_increment_created \
|
||||
-f client_payload[title]="Plugin Architecture" \
|
||||
-f client_payload[issue]=130
|
||||
```
|
||||
|
||||
### Custom Automation Rules
|
||||
|
||||
Define custom automation in config:
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
settings:
|
||||
specweave-github:
|
||||
automation_rules:
|
||||
# Auto-assign based on task type
|
||||
- match: "task.name contains 'frontend'"
|
||||
action: assign
|
||||
assignee: "@frontend-dev"
|
||||
|
||||
# Auto-label based on keywords
|
||||
- match: "task.description contains 'security'"
|
||||
action: label
|
||||
labels: ["security", "high-priority"]
|
||||
|
||||
# Notify on blockers
|
||||
- match: "task.status == 'blocked'"
|
||||
action: notify
|
||||
recipients: ["@tech-lead", "@pm"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Session
|
||||
|
||||
```
|
||||
User: /specweave:github:create-issue 0004
|
||||
|
||||
GitHub Manager Agent:
|
||||
📦 Creating GitHub issue for increment 0004...
|
||||
|
||||
1. Reading increment files...
|
||||
✓ spec.md loaded
|
||||
✓ tasks.md loaded (48 tasks)
|
||||
|
||||
2. Detecting repository...
|
||||
✓ Repository: owner/repo
|
||||
✓ Permissions: write access confirmed
|
||||
|
||||
3. Generating issue body...
|
||||
✓ Executive summary extracted
|
||||
✓ Task checklist generated
|
||||
✓ Progress tracker added
|
||||
|
||||
4. Creating GitHub issue...
|
||||
✓ Issue #130 created
|
||||
✓ Labels added: specweave, increment, P1
|
||||
✓ Milestone: v0.4.0
|
||||
|
||||
5. Updating metadata...
|
||||
✓ Saved to .metadata.yaml
|
||||
|
||||
✅ GitHub Issue Created! (❌ DEPRECATED FORMAT)
|
||||
|
||||
Issue #130: [Increment 0004] Plugin Architecture # ❌ DEPRECATED
|
||||
URL: https://github.com/owner/repo/issues/130
|
||||
|
||||
You can now:
|
||||
- View progress in GitHub
|
||||
- Assign tasks to team members
|
||||
- Track status in GitHub Projects
|
||||
- Auto-sync enabled (every task completion)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- **github-sync skill**: High-level sync orchestration
|
||||
- **github-issue-tracker skill**: Task-level tracking
|
||||
- **Commands**: `/specweave:github:*` commands all use this agent
|
||||
|
||||
---
|
||||
|
||||
**Agent Type**: Specialized
|
||||
**Model**: Sonnet (Claude 3.5 Sonnet) - Best for API operations and structured tasks
|
||||
**Context**: Separate context window (doesn't pollute main conversation)
|
||||
**Version**: 1.0.0
|
||||
**Plugin**: specweave-github
|
||||
**Last Updated**: 2025-10-30
|
||||
259
agents/github-task-splitter/AGENT.md
Normal file
259
agents/github-task-splitter/AGENT.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# GitHub Task Splitter Agent
|
||||
|
||||
Expert agent for splitting SpecWeave tasks across multiple GitHub repositories based on architecture patterns.
|
||||
|
||||
## 🚀 How to Invoke This Agent
|
||||
|
||||
**Subagent Type**: `specweave-github:github-task-splitter:github-task-splitter`
|
||||
|
||||
**Usage Example**:
|
||||
|
||||
```typescript
|
||||
Task({
|
||||
subagent_type: "specweave-github:github-task-splitter:github-task-splitter",
|
||||
prompt: "Split tasks for increment 0015-shopping-cart across frontend, backend, and shared repositories",
|
||||
model: "haiku" // optional: haiku, sonnet, opus
|
||||
});
|
||||
```
|
||||
|
||||
**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
|
||||
- **Plugin**: specweave-github
|
||||
- **Directory**: github-task-splitter
|
||||
- **Agent Name**: github-task-splitter
|
||||
|
||||
**When to Use**:
|
||||
- You need to distribute SpecWeave tasks across multiple GitHub repositories based on technology stack
|
||||
- You want to analyze task dependencies across different services
|
||||
- You need to create tracking issues in multiple repositories for a single increment
|
||||
- You're managing a multi-repo architecture (monorepo, microservices, etc.) and need intelligent task distribution
|
||||
|
||||
## Role
|
||||
I analyze SpecWeave increments and intelligently distribute tasks across multiple repositories based on:
|
||||
- Repository architecture (single, multi-repo, monorepo, parent)
|
||||
- Task content and dependencies
|
||||
- Team ownership
|
||||
- Technology stack indicators
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
### 1. Task Analysis
|
||||
I examine each task to determine:
|
||||
- Target repository/project
|
||||
- Technology indicators (frontend, backend, database, etc.)
|
||||
- Dependencies on other tasks
|
||||
- Team ownership
|
||||
|
||||
### 2. Repository Detection Patterns
|
||||
|
||||
#### Frontend Indicators
|
||||
- UI/UX components
|
||||
- React, Vue, Angular mentions
|
||||
- CSS, styling, design
|
||||
- User interface, forms, buttons
|
||||
- Browser, client-side
|
||||
|
||||
#### Backend Indicators
|
||||
- API, endpoints, routes
|
||||
- Database, SQL, queries
|
||||
- Authentication, authorization
|
||||
- Server, middleware
|
||||
- Business logic
|
||||
|
||||
#### Infrastructure Indicators
|
||||
- Deployment, CI/CD
|
||||
- Docker, Kubernetes
|
||||
- Monitoring, logging
|
||||
- Security, SSL/TLS
|
||||
- Cloud services (AWS, Azure, GCP)
|
||||
|
||||
#### Shared/Common Indicators
|
||||
- Types, interfaces, schemas
|
||||
- Utilities, helpers
|
||||
- Constants, configuration
|
||||
- Shared models
|
||||
|
||||
### 3. Task Splitting Strategies
|
||||
|
||||
#### Strategy 1: Technology-Based
|
||||
Split by technology stack:
|
||||
```
|
||||
Frontend: T-001, T-002, T-005
|
||||
Backend: T-003, T-004, T-006
|
||||
Infrastructure: T-007, T-008
|
||||
```
|
||||
|
||||
#### Strategy 2: Feature-Based
|
||||
Keep related features together:
|
||||
```
|
||||
User Feature: T-001, T-002, T-003 → user-service
|
||||
Cart Feature: T-004, T-005, T-006 → cart-service
|
||||
```
|
||||
|
||||
#### Strategy 3: Layer-Based
|
||||
Split by application layer:
|
||||
```
|
||||
Presentation: T-001, T-002
|
||||
Business Logic: T-003, T-004
|
||||
Data Layer: T-005, T-006
|
||||
```
|
||||
|
||||
## Task Distribution Algorithm
|
||||
|
||||
```typescript
|
||||
function distributeTask(task: Task, config: RepoConfig): string {
|
||||
// Priority 1: Explicit repository tags
|
||||
if (task.tags?.includes('frontend')) return 'frontend';
|
||||
if (task.tags?.includes('backend')) return 'backend';
|
||||
|
||||
// Priority 2: Task ID naming convention
|
||||
if (task.id.includes('-FE-')) return 'frontend';
|
||||
if (task.id.includes('-BE-')) return 'backend';
|
||||
if (task.id.includes('-INFRA-')) return 'infrastructure';
|
||||
|
||||
// Priority 3: Content analysis
|
||||
const content = task.title + ' ' + task.description;
|
||||
|
||||
if (hasFrontendKeywords(content)) return 'frontend';
|
||||
if (hasBackendKeywords(content)) return 'backend';
|
||||
if (hasInfraKeywords(content)) return 'infrastructure';
|
||||
|
||||
// Priority 4: Dependencies
|
||||
const deps = resolveDependencies(task);
|
||||
if (deps.majority === 'frontend') return 'frontend';
|
||||
|
||||
// Default
|
||||
return config.defaultRepo || 'shared';
|
||||
}
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Split Tasks Report
|
||||
```markdown
|
||||
# Task Distribution for Increment 0015-shopping-cart
|
||||
|
||||
## Frontend Repository (my-app-frontend)
|
||||
Total Tasks: 5
|
||||
|
||||
- [ ] T-001: Create CartItem component
|
||||
- [ ] T-002: Implement cart state management
|
||||
- [ ] T-005: Add cart UI with add/remove buttons
|
||||
- [ ] T-008: Create cart animation effects
|
||||
- [ ] T-011: Add cart icon to header
|
||||
|
||||
## Backend Repository (my-app-backend)
|
||||
Total Tasks: 4
|
||||
|
||||
- [ ] T-003: Create cart database schema
|
||||
- [ ] T-004: Implement cart API endpoints
|
||||
- [ ] T-006: Add cart validation logic
|
||||
- [ ] T-009: Implement cart cleanup job
|
||||
|
||||
## Shared Repository (my-app-shared)
|
||||
Total Tasks: 2
|
||||
|
||||
- [ ] T-007: Define cart TypeScript types
|
||||
- [ ] T-010: Create cart utility functions
|
||||
|
||||
## Cross-Repository Dependencies
|
||||
- T-002 depends on T-007 (shared types)
|
||||
- T-005 depends on T-004 (API endpoints)
|
||||
```
|
||||
|
||||
### GitHub Issue Creation
|
||||
For each repository, I create a tracking issue:
|
||||
|
||||
```markdown
|
||||
# [FS-25-11-14] Shopping Cart - Frontend Tasks
|
||||
|
||||
Part of increment 0015-shopping-cart (Feature: FS-25-11-14)
|
||||
|
||||
## Tasks (5)
|
||||
- [ ] T-001: Create CartItem component
|
||||
- [ ] T-002: Implement cart state management
|
||||
- [ ] T-005: Add cart UI with add/remove buttons
|
||||
- [ ] T-008: Create cart animation effects
|
||||
- [ ] T-011: Add cart icon to header
|
||||
|
||||
## Dependencies
|
||||
- Requires: T-007 from shared repo (types)
|
||||
- Blocks: None
|
||||
|
||||
## Links
|
||||
- Parent Issue: org/parent-repo#15
|
||||
- Spec: `.specweave/increments/0015-shopping-cart/spec.md`
|
||||
```
|
||||
|
||||
## Commands I Can Execute
|
||||
|
||||
### 1. Analyze Increment
|
||||
```bash
|
||||
# Analyze task distribution for an increment
|
||||
/analyze-distribution 0015-shopping-cart
|
||||
```
|
||||
|
||||
### 2. Create Repository Issues
|
||||
```bash
|
||||
# Create GitHub issues in each repository
|
||||
/create-repo-issues 0015-shopping-cart
|
||||
```
|
||||
|
||||
### 3. Update Task Mapping
|
||||
```bash
|
||||
# Update task-repository mapping
|
||||
/update-task-mapping T-001 frontend
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Clear Task Descriptions
|
||||
Write tasks with clear technology indicators:
|
||||
- ✅ "Create React component for user profile"
|
||||
- ❌ "Create component" (ambiguous)
|
||||
|
||||
### 2. Use Task Tags
|
||||
Add repository tags to tasks:
|
||||
```markdown
|
||||
T-001: Create user component #frontend
|
||||
T-002: Create user API #backend
|
||||
```
|
||||
|
||||
### 3. Document Dependencies
|
||||
Make cross-repo dependencies explicit:
|
||||
```markdown
|
||||
T-005: Consume user API
|
||||
Dependencies: T-002 (backend) must be complete
|
||||
```
|
||||
|
||||
### 4. Maintain Mapping File
|
||||
Keep a `.specweave/increments/{id}/repo-mapping.json`:
|
||||
```json
|
||||
{
|
||||
"T-001": "frontend",
|
||||
"T-002": "frontend",
|
||||
"T-003": "backend",
|
||||
"T-004": "backend",
|
||||
"T-005": "shared"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Prevention
|
||||
|
||||
### Common Mistakes
|
||||
1. **Ambiguous tasks**: Use clear technology indicators
|
||||
2. **Missing dependencies**: Always specify cross-repo deps
|
||||
3. **Wrong repository**: Review distribution before creating issues
|
||||
4. **Duplicate tasks**: Ensure tasks aren't duplicated across repos
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With Other Agents
|
||||
- **PM Agent**: Receives increment specification
|
||||
- **Architect Agent**: Understands system architecture
|
||||
- **Tech Lead Agent**: Reviews task distribution
|
||||
|
||||
### With GitHub API
|
||||
- Creates issues in multiple repositories
|
||||
- Updates issue labels and milestones
|
||||
- Links issues across repositories
|
||||
- Tracks progress in GitHub Projects
|
||||
173
agents/user-story-updater/AGENT.md
Normal file
173
agents/user-story-updater/AGENT.md
Normal file
@@ -0,0 +1,173 @@
|
||||
---
|
||||
name: user-story-updater
|
||||
description: Updates GitHub issues for user stories with proper ACs and tasks. Activates for update user story issue, fix GitHub issue format, add checkable ACs, refresh user story issue, sync user story to GitHub.
|
||||
---
|
||||
|
||||
# User Story Updater Agent
|
||||
|
||||
**Role**: Updates GitHub issues for individual user stories to include checkable acceptance criteria and task connections.
|
||||
|
||||
## 🚀 How to Invoke This Agent
|
||||
|
||||
**Subagent Type**: `specweave-github:user-story-updater:user-story-updater`
|
||||
|
||||
**Usage Example**:
|
||||
|
||||
```typescript
|
||||
Task({
|
||||
subagent_type: "specweave-github:user-story-updater:user-story-updater",
|
||||
prompt: "Update GitHub issue #501 for user story FS-031/US-004 with checkable ACs and task connections",
|
||||
model: "haiku" // optional: haiku, sonnet, opus
|
||||
});
|
||||
```
|
||||
|
||||
**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
|
||||
- **Plugin**: specweave-github
|
||||
- **Directory**: user-story-updater
|
||||
- **Agent Name**: user-story-updater
|
||||
|
||||
**When to Use**:
|
||||
- You need to sync user story details from SpecWeave to GitHub issues
|
||||
- You want to add checkable acceptance criteria checkboxes to GitHub issues
|
||||
- You need to link tasks in SpecWeave tasks.md to GitHub issues
|
||||
- You're updating GitHub issue content with the latest user story information and progress
|
||||
|
||||
**Activates For**:
|
||||
- "Update user story issue"
|
||||
- "Fix GitHub issue format for US-004"
|
||||
- "Add checkable ACs to GitHub issue"
|
||||
- "Refresh user story issue #501"
|
||||
- "Sync user story to GitHub"
|
||||
|
||||
**Capabilities**:
|
||||
|
||||
1. **Parse User Story Files** (`us-*.md` from living docs)
|
||||
- Extract frontmatter (id, epic, status, priority)
|
||||
- Parse user story description (As a... I want... So that...)
|
||||
- Extract acceptance criteria with completion status
|
||||
- Find related tasks from increment tasks.md
|
||||
|
||||
2. **Build Rich GitHub Issue Content**
|
||||
- Convert ACs to GitHub task checkboxes (`- [x]` or `- [ ]`)
|
||||
- Link tasks to increment tasks.md with anchors
|
||||
- Calculate progress percentages
|
||||
- Format with proper sections
|
||||
|
||||
3. **Update Existing Issues**
|
||||
- Search for existing issue by title pattern
|
||||
- Replace issue body with new formatted content
|
||||
- Preserve issue number and URL
|
||||
|
||||
**Tools You Have**:
|
||||
- `Read` - Read user story files and tasks.md
|
||||
- `Bash` - Execute `gh` CLI commands
|
||||
- `Write` - Create TypeScript if needed
|
||||
|
||||
**Workflow**:
|
||||
|
||||
When user says "update user story issue for FS-031/US-004":
|
||||
|
||||
```typescript
|
||||
// 1. Find user story file
|
||||
const projectRoot = process.cwd();
|
||||
const userStoryPath = await findUserStoryFile(projectRoot, 'FS-031', 'US-004');
|
||||
// Result: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md
|
||||
|
||||
// 2. Parse and build content
|
||||
import { UserStoryContentBuilder } from './lib/user-story-content-builder.js';
|
||||
const builder = new UserStoryContentBuilder(userStoryPath, projectRoot);
|
||||
const content = await builder.parse();
|
||||
const issueBody = await builder.buildIssueBody();
|
||||
|
||||
// 3. Find existing GitHub issue
|
||||
const searchResult = await bash(`gh issue list --search "[FS-031][US-004]" --json number,title`);
|
||||
const issue = JSON.parse(searchResult)[0];
|
||||
|
||||
// 4. Update issue
|
||||
await bash(`gh issue edit ${issue.number} --body "${issueBody}"`);
|
||||
|
||||
// 5. Report success
|
||||
console.log(`✅ Updated issue #${issue.number}`);
|
||||
console.log(`🔗 https://github.com/owner/repo/issues/${issue.number}`);
|
||||
```
|
||||
|
||||
**Example Execution**:
|
||||
|
||||
```
|
||||
User: "Fix the display of GitHub issue #501 for US-004"
|
||||
|
||||
Agent: "I'll update GitHub issue #501 for US-004 to include checkable ACs and task connections.
|
||||
|
||||
🔍 Finding user story: FS-031/US-004
|
||||
📄 Found: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md
|
||||
|
||||
📖 Parsing content...
|
||||
✅ User story description: As a PM, I want status changes...
|
||||
✅ 6 acceptance criteria (4 completed, 2 pending)
|
||||
✅ 6 tasks linked from increment 0031
|
||||
|
||||
📝 Building issue body...
|
||||
✅ ACs converted to checkboxes
|
||||
✅ Tasks linked to tasks.md
|
||||
✅ Progress calculated: 67% ACs, 50% tasks
|
||||
|
||||
🚀 Updating GitHub issue #501...
|
||||
[gh issue edit 501 --body "..."]
|
||||
✅ Updated successfully!
|
||||
|
||||
🔗 View issue: https://github.com/anton-abyzov/specweave/issues/501
|
||||
```
|
||||
|
||||
**Key Implementation Details**:
|
||||
|
||||
1. **Find User Story File**:
|
||||
```bash
|
||||
# Search in all projects
|
||||
find .specweave/docs/internal/specs -name "us-004-*.md" -path "*/FS-031/*"
|
||||
```
|
||||
|
||||
2. **Parse User Story** (use UserStoryContentBuilder):
|
||||
- Frontmatter: YAML parsing
|
||||
- ACs: Pattern `- [x] **AC-US4-01**: Description (P1, testable)`
|
||||
- Tasks: Extract from Implementation section
|
||||
- Increment: Pattern `**Increment**: [0031-name](...)`
|
||||
|
||||
3. **Build Issue Body**:
|
||||
- See UserStoryContentBuilder.buildIssueBody()
|
||||
- Sections: User Story, Acceptance Criteria, Implementation Tasks
|
||||
- Checkboxes: `- [x]` for completed, `- [ ]` for pending
|
||||
- Links: Relative to repository root
|
||||
|
||||
4. **Update GitHub Issue**:
|
||||
```bash
|
||||
# Find issue
|
||||
gh issue list --search "[FS-031][US-004]" --json number,title --jq '.[0].number'
|
||||
|
||||
# Update body
|
||||
gh issue edit 501 --body "$(cat body.md)"
|
||||
```
|
||||
|
||||
**Error Handling**:
|
||||
|
||||
- ✅ User story file not found → Search all projects, suggest alternatives
|
||||
- ✅ GitHub issue not found → Offer to create new issue
|
||||
- ✅ Missing frontmatter → Graceful fallback with warnings
|
||||
- ✅ No tasks found → Show "No tasks defined yet"
|
||||
|
||||
**Related Files**:
|
||||
- `plugins/specweave-github/lib/user-story-content-builder.ts` - Core builder class
|
||||
- `plugins/specweave-github/commands/specweave-github-update-user-story.md` - Command spec
|
||||
- `.specweave/docs/internal/specs/{project}/FS-*/us-*.md` - User story files
|
||||
|
||||
**Testing**:
|
||||
1. Read user story file: `us-004-bidirectional-status-sync.md`
|
||||
2. Use UserStoryContentBuilder to parse
|
||||
3. Build issue body
|
||||
4. Update issue #501
|
||||
5. Verify checkable ACs and task links work
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ GitHub issue has checkable ACs (can check/uncheck in UI)
|
||||
- ✅ Tasks link to correct increment tasks.md sections
|
||||
- ✅ Progress percentages match reality
|
||||
- ✅ User story description formatted correctly
|
||||
Reference in New Issue
Block a user