specweave 0.16.2 → 0.16.5

package/plugins/specweave-github/agents/github-task-splitter/AGENT.md

@@ -0,0 +1,234 @@
+# GitHub Task Splitter Agent
+
+Expert agent for splitting SpecWeave tasks across multiple GitHub repositories based on architecture patterns.
+
+## 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
+# [INC-0015] Shopping Cart - Frontend Tasks
+
+Part of increment 0015-shopping-cart
+
+## 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

package/plugins/specweave-github/skills/github-multi-project/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: github-multi-project
+description: Expert at organizing specs and splitting tasks across multiple GitHub repositories. Handles monorepo, polyrepo, and parent repo architectures. Activates for multi-project GitHub setups, task splitting, spec organization, team allocation, cross-repo coordination.
+---
+
+# GitHub Multi-Project Management Skill
+
+Expert skill for managing SpecWeave projects across multiple GitHub repositories.
+
+## Core Capabilities
+
+### 1. Spec Organization
+- Organizes specs in `.specweave/docs/internal/projects/{project-id}/` structure
+- Maps increments to specific projects/repos
+- Maintains traceability across repositories
+- Handles cross-project dependencies
+
+### 2. Task Splitting
+When a SpecWeave increment spans multiple repositories:
+- Analyzes tasks in `tasks.md`
+- Identifies which tasks belong to which repo
+- Creates repo-specific task lists
+- Maintains cross-repo coordination
+
+### 3. Repository Architectures
+
+#### Single Repository
+```
+my-app/
+├── .specweave/
+│   └── docs/internal/projects/default/
+└── src/
+```
+
+#### Multi-Repository (Polyrepo)
+```
+my-app-frontend/
+├── .git
+└── src/
+
+my-app-backend/
+├── .git
+└── src/
+
+my-app-shared/
+├── .git
+└── src/
+```
+
+#### Parent Repository Approach (Recommended for Multi-Repo)
+```
+my-app-parent/              # Parent repo with .specweave
+├── .specweave/
+│   └── docs/internal/projects/
+│       ├── frontend/
+│       ├── backend/
+│       └── shared/
+└── services/               # Implementation repos
+    ├── frontend/
+    ├── backend/
+    └── shared/
+```
+
+#### Monorepo
+```
+my-app/
+├── .specweave/
+│   └── docs/internal/projects/
+│       ├── frontend/
+│       ├── backend/
+│       └── shared/
+└── packages/
+    ├── frontend/
+    ├── backend/
+    └── shared/
+```
+
+## Task Splitting Examples
+
+### Example 1: E-commerce Platform
+**Increment**: Add shopping cart functionality
+
+**Tasks split by repository**:
+
+**Frontend (my-app-frontend)**:
+- T-001: Create CartItem component
+- T-002: Implement cart state management
+- T-003: Add cart UI with add/remove buttons
+
+**Backend (my-app-backend)**:
+- T-004: Create cart database schema
+- T-005: Implement cart API endpoints
+- T-006: Add cart validation logic
+
+**Shared (my-app-shared)**:
+- T-007: Define cart TypeScript types
+- T-008: Create cart utility functions
+
+### Example 2: Microservices Architecture
+**Increment**: Implement user notifications
+
+**Tasks split by service**:
+
+**User Service**:
+- T-001: Add notification preferences to user profile
+- T-002: Create preference API endpoints
+
+**Notification Service**:
+- T-003: Implement notification queue
+- T-004: Create email sender
+- T-005: Create push notification sender
+
+**Gateway Service**:
+- T-006: Add notification routes
+- T-007: Implement rate limiting
+
+## Commands
+
+### Analyze Task Distribution
+```typescript
+// Analyze which tasks belong to which repository
+function analyzeTaskDistribution(tasks: Task[]): Map<string, Task[]> {
+  const distribution = new Map();
+
+  for (const task of tasks) {
+    const repo = detectRepository(task);
+    if (!distribution.has(repo)) {
+      distribution.set(repo, []);
+    }
+    distribution.get(repo).push(task);
+  }
+
+  return distribution;
+}
+```
+
+### Create Repository-Specific Issues
+```typescript
+// Create GitHub issues in each repository
+async function createRepoSpecificIssues(
+  increment: Increment,
+  distribution: Map<string, Task[]>
+) {
+  for (const [repo, tasks] of distribution) {
+    const issue = await createGitHubIssue({
+      repo,
+      title: `[${increment.id}] ${increment.name} - ${repo}`,
+      body: formatTasksAsChecklist(tasks),
+      labels: ['specweave', 'increment', repo]
+    });
+
+    console.log(`Created issue #${issue.number} in ${repo}`);
+  }
+}
+```
+
+## Best Practices
+
+### 1. Parent Repository Approach
+**Recommended for multi-repo projects**:
+- Central .specweave/ folder in parent repo
+- Living docs sync to parent (single source of truth)
+- Implementation repos stay clean
+- Better for enterprise/multi-team projects
+
+### 2. Task Naming Convention
+```
+T-{repo}-{number}: {description}
+T-FE-001: Create user profile component
+T-BE-001: Implement user API
+T-SHARED-001: Define user types
+```
+
+### 3. Cross-Repository Dependencies
+Mark dependencies clearly:
+```
+T-FE-002: Consume user API
+  Dependencies: T-BE-001 (must complete first)
+```
+
+### 4. Spec Organization
+```
+.specweave/docs/internal/projects/
+├── frontend/
+│   └── specs/
+│       ├── spec-001-user-interface.md
+│       └── spec-002-cart-ui.md
+├── backend/
+│   └── specs/
+│       ├── spec-001-api-design.md
+│       └── spec-002-database.md
+└── shared/
+    └── specs/
+        └── spec-001-types.md
+```
+
+## Integration with GitHub Projects
+
+### Multi-Repo GitHub Project
+Create a GitHub Project that spans multiple repositories:
+1. Create project at organization level
+2. Add issues from all repos
+3. Use project boards for cross-repo coordination
+4. Track overall increment progress
+
+### Repository-Specific Projects
+Each repository can have its own project:
+- Frontend Project: UI tasks
+- Backend Project: API tasks
+- Shared Project: Common tasks
+
+## Automation
+
+### GitHub Actions Integration
+```yaml
+# .github/workflows/specweave-sync.yml
+name: SpecWeave Multi-Repo Sync
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 */6 * * *' # Every 6 hours
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Sync to repositories
+        run: |
+          # Sync tasks to frontend repo
+          gh issue create --repo myorg/frontend ...
+
+          # Sync tasks to backend repo
+          gh issue create --repo myorg/backend ...
+```
+
+## Error Handling
+
+### Common Issues
+1. **Repository not found**: Ensure repos exist and token has access
+2. **Task ambiguity**: Use clear naming to indicate target repo
+3. **Cross-repo conflicts**: Use parent repo as single source of truth
+4. **Permission errors**: Token needs repo scope for all repositories
+
+## Related Skills
+- github-sync: Basic GitHub synchronization
+- github-issue-tracker: Task-level tracking
+- specweave:multi-project-spec-mapper: Intelligent spec splitting