lite-kits 0.1.0__py3-none-any.whl

lite_kits/kits/multiagent/README.md

@@ -0,0 +1,395 @@
+# Multiagent Kit
+
+**Status**: 📦 Optional (For Complex Projects)
+
+Multi-agent coordination structure for projects with multiple AI agents working in parallel. Includes collaboration directories, workflow guides, and coordination protocols.
+
+## What It Adds
+
+### Memory Guides
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| PR Workflow | How AI agents create pull requests | ✅ |
+| Git Worktrees Protocol | Parallel development with worktrees | ✅ |
+
+### Templates
+
+| Template | Description | Status |
+|----------|-------------|--------|
+| Collaboration structure | Active/archive/results directories | 🚧 |
+
+✅ = Implemented | 🚧 = Coming Soon
+
+## Dependencies
+
+⚠️ **multiagent-kit requires**:
+- **project-kit**: For `/review` command and best practices
+- **git-kit**: For `/commit`, `/pr` commands used in workflows
+
+**Recommended installation**:
+```bash
+lite-kits install -Recommended -Kit multiagent
+# Installs: project + git + multiagent
+```
+
+**Note**: Installer will automatically install dependencies if missing.
+
+## Installation
+
+### With dependencies (recommended):
+```bash
+lite-kits install -Recommended -Kit multiagent
+```
+
+### Individually (installs dependencies automatically):
+```bash
+lite-kits install -Kit multiagent
+```
+
+## What Gets Installed
+
+```
+your-project/
+├── .specify/memory/
+│   ├── pr-workflow-guide.md           # ✅ AI agent PR workflow
+│   └── git-worktrees-protocol.md      # ✅ Parallel development guide
+└── specs/
+    └── NNN-feature/
+        └── collaboration/             # 🚧 Created per-feature
+            ├── active/
+            │   ├── sessions/          # Work session logs
+            │   ├── decisions/         # Handoffs, proposals
+            │   └── README.md          # Current status
+            ├── archive/               # Historical (YYYY-MM/)
+            └── results/               # Completed deliverables
+                ├── validation/        # Test results, reviews
+                └── artifacts/         # Final outputs
+```
+
+**Note**: Collaboration directories are created automatically when you run `/specify` with multiagent-kit installed.
+
+## Memory Guides
+
+### PR Workflow Guide
+
+**File**: `.specify/memory/pr-workflow-guide.md`
+
+**What it covers**:
+- How AI agents should create pull requests
+- Commit attribution format (`via model @ interface`)
+- PR description templates for AI-generated code
+- Multi-agent coordination in PRs
+- Handoff procedures between agents
+- CI/CD integration for agent attribution
+
+**Example commit attribution**:
+```
+feat: Add user authentication
+
+Implements bcrypt password hashing and JWT tokens.
+
+via claude-sonnet-4.5 @ claude-code
+```
+
+**Use when**: Any AI agent is ready to create a PR
+
+---
+
+### Git Worktrees Protocol
+
+**File**: `.specify/memory/git-worktrees-protocol.md`
+
+**What it covers**:
+- Using git worktrees for parallel development
+- File territory definitions (avoid conflicts)
+- Synchronization strategies
+- When to use worktrees vs regular branches
+- Troubleshooting common issues
+
+**Example workflow**:
+```bash
+# Agent 1: Backend worktree
+git worktree add ../blog-backend 003-blog
+
+# Agent 2: Frontend worktree
+git worktree add ../blog-frontend 003-blog
+
+# Both agents work simultaneously, push to same branch
+# No merge conflicts because file territories are defined
+```
+
+**Use when**: Multiple agents working on same feature simultaneously
+
+---
+
+## Collaboration Directory Structure
+
+### Purpose
+
+Enable multiple AI agents to coordinate work on the same feature without stepping on each other's toes.
+
+### Structure
+
+```
+specs/003-blog-platform/collaboration/
+├── active/                           # Current work in progress
+│   ├── sessions/                     # Individual work sessions
+│   │   ├── 2025-10-06-claude-backend.md
+│   │   ├── 2025-10-06-copilot-frontend.md
+│   │   └── 2025-10-07-claude-integration.md
+│   ├── decisions/                    # Coordination documents
+│   │   ├── handoff-to-copilot.md    # Task delegation
+│   │   ├── worktree-coordination.md  # File territories
+│   │   └── agent-split.md            # Work division
+│   └── README.md                     # Current status summary
+├── archive/                          # Historical work
+│   ├── 2025-10/                      # Organized by month
+│   │   ├── sessions/
+│   │   └── decisions/
+│   └── 2025-11/
+└── results/                          # Completed deliverables
+    ├── validation/                   # Test results, reviews
+    │   ├── test-results.md
+    │   └── code-review.md
+    └── artifacts/                    # Final outputs
+        ├── completion-summary.md
+        └── performance-benchmarks.md
+```
+
+### Session Log Example
+
+```markdown
+# Backend Development Session
+
+**Agent**: Claude Code (claude-sonnet-4.5)
+**Worktree**: ../blog-backend
+**Date**: 2025-10-06
+**Duration**: 3 hours
+
+## Completed
+- Express app setup
+- Prisma schema design
+- Authentication middleware (JWT)
+- Integration tests (15/15 passing)
+
+## Commits
+- abc123: feat: Add Express app structure
+- def456: feat: Add Prisma database schema
+- ghi789: feat: Add JWT authentication
+
+## Synchronized
+- Pulled frontend changes at 14:00 (no conflicts)
+- Pushed backend at 16:30
+
+## Status
+✅ Backend ready for frontend integration
+
+## Next Steps
+- Frontend team: integrate with auth API
+- Add rate limiting (future iteration)
+```
+
+### Handoff Document Example
+
+```markdown
+# Handoff to GitHub Copilot
+
+**From**: Claude Code
+**To**: GitHub Copilot CLI
+**Date**: 2025-10-06
+
+## Context
+Backend authentication complete. Need frontend integration.
+
+## What's Done
+- Backend API endpoints (POST /login, POST /logout, GET /session)
+- JWT token generation and validation
+- Password hashing with bcrypt
+- Integration tests passing
+
+## What's Needed
+- React login form component
+- Auth context provider
+- Protected route wrapper
+- Session state management
+
+## Files to Create
+- src/components/LoginForm.tsx
+- src/hooks/useAuth.ts
+- src/components/ProtectedRoute.tsx
+
+## API Reference
+- See: specs/003-blog/contracts/auth-api.yaml
+- Backend: http://localhost:3000/api/auth
+
+## Testing
+- Use credentials: test@example.com / Test123!
+- Backend health check: GET /health
+```
+
+---
+
+## Multi-Agent Workflows
+
+### Scenario 1: Backend + Frontend Split
+
+**Agents**: Claude Code (backend) + Copilot CLI (frontend)
+
+**Workflow**:
+1. Claude runs `/specify` and `/plan` for full feature
+2. Claude creates handoff document defining split
+3. Both agents create worktrees for parallel work
+4. Each agent logs sessions in `collaboration/active/sessions/`
+5. Agents sync periodically with `git pull`
+6. Claude handles integration testing
+7. Either agent creates PR using `/pr` (from git-kit)
+
+**File territories** (avoid conflicts):
+- Backend worktree: `src/api/`, `src/models/`, `tests/api/`
+- Frontend worktree: `src/components/`, `src/hooks/`, `tests/components/`
+- Shared: Coordinate edits to `README.md`, `package.json`
+
+---
+
+### Scenario 2: Review + Implementation
+
+**Agents**: Claude (implementation) + Copilot (review)
+
+**Workflow**:
+1. Claude implements feature, commits work
+2. Claude creates handoff for review
+3. Copilot runs `/review` (from project-kit)
+4. Copilot logs review in `collaboration/active/decisions/`
+5. Claude addresses feedback
+6. Copilot approves and creates PR
+
+---
+
+### Scenario 3: Test + Fix Cycle
+
+**Agents**: Claude (testing) + Copilot (fixing)
+
+**Workflow**:
+1. Claude writes comprehensive tests (TDD)
+2. Tests fail (as expected)
+3. Claude creates handoff with failing test details
+4. Copilot implements code to pass tests
+5. Both agents log sessions
+6. Tests pass, feature complete
+
+---
+
+## When to Use Multiagent Kit
+
+### ✅ Use when:
+- Multiple AI agents working on same feature
+- Complex features requiring parallel work (backend + frontend)
+- Team handoffs between agents
+- Long-running features (>1 week)
+- Need coordination history for debugging
+
+### ❌ Don't use when:
+- Solo developer with single AI agent
+- Simple features (<1 day)
+- Proof of concepts or experiments
+- Scripts or small utilities
+
+**Rule of thumb**: If you're using git worktrees, you need multiagent-kit.
+
+---
+
+## Integration with Other Kits
+
+### With project-kit
+- Use `/orient` for each agent to understand their role
+- Use `/review` for agent-to-agent code review
+
+### With git-kit
+- Use `/commit` for agent-attributed commits
+- Use `/pr` to create PRs with multi-agent summary
+- Use `/sync` to visualize worktree status
+- Use `/cleanup` to remove stale worktrees
+
+---
+
+## Best Practices
+
+### Session Logging
+- Create session log at start of work
+- Update throughout session
+- Include commits, syncs, blockers
+- End with status and next steps
+
+### Handoff Documents
+- Clear context and background
+- Specific what's done vs what's needed
+- List files to create/modify
+- Include API references or contracts
+- Set clear expectations
+
+### File Territories
+- Define upfront in handoff document
+- Avoid editing shared files simultaneously
+- Communicate before editing shared files
+- Use git worktrees to enforce separation
+
+### Archive Regularly
+- Move completed sessions to `archive/YYYY-MM/`
+- Keep `active/` clean (current work only)
+- Document final results in `results/`
+
+---
+
+## Configuration
+
+No configuration needed - works out of the box.
+
+**Optional**: Customize collaboration templates in future versions.
+
+---
+
+## Compatibility
+
+- ✅ **Agents**: Claude Code, GitHub Copilot, Cursor
+- ✅ **Platforms**: Linux, macOS, Windows
+- ✅ **Shells**: Bash, PowerShell
+- ✅ **Vanilla safe**: Only adds new files, never modifies existing
+
+---
+
+## Uninstall
+
+```bash
+lite-kits remove -Kit multiagent
+```
+
+Removes:
+- `.specify/memory/pr-workflow-guide.md`
+- `.specify/memory/git-worktrees-protocol.md`
+
+**Note**: Existing `specs/*/collaboration/` directories are **preserved** (user data).
+
+---
+
+## Examples
+
+See working examples:
+- **blog-with-auth**: Full multi-agent workflow with worktrees
+  - Backend (Claude Code) + Frontend (Copilot CLI)
+  - Collaboration directories in action
+  - Handoff documents
+  - Integration testing
+
+---
+
+## Future Enhancements
+
+Considering for multiagent-kit:
+- Automated session logging (CLI helper)
+- Agent dashboard (show current work across agents)
+- Conflict detection (warn about file territory violations)
+- Collaboration metrics (contribution tracking)
+- Multi-agent CI workflows
+
+Suggest more in [GitHub Discussions](https://github.com/tmorgan181/spec-kit-multiagent-lite/discussions).

lite_kits/kits/multiagent/claude/commands/sync.md

@@ -0,0 +1,331 @@
+---
+description: Check multi-agent sync status with ASCII visualization
+---
+
+# Multi-Agent Sync Status
+
+**Purpose**: Visualize git sync status and multi-agent coordination state.
+
+## Execution Steps
+
+### 1. Check Git Status
+
+```bash
+# Current branch
+CURRENT_BRANCH=$(git branch --show-current)
+
+# Check if tracking remote
+REMOTE_BRANCH=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null)
+
+# Commits ahead/behind
+if [ -n "$REMOTE_BRANCH" ]; then
+  AHEAD=$(git rev-list --count $REMOTE_BRANCH..HEAD)
+  BEHIND=$(git rev-list --count HEAD..$REMOTE_BRANCH)
+else
+  AHEAD="N/A"
+  BEHIND="N/A"
+fi
+
+# Uncommitted changes
+MODIFIED=$(git status --short | wc -l)
+UNTRACKED=$(git ls-files --others --exclude-standard | wc -l)
+```
+
+### 2. Detect Multi-Agent Activity
+
+```bash
+# Check for recent commits by different agents
+git log --since="7 days ago" --format="%b" | grep "via.*@" | sort -u
+
+# Count commits by agent
+echo "Recent activity (last 7 days):"
+git log --since="7 days ago" --format="%b" | \
+  grep "via.*@" | \
+  sed 's/.*via \(.*\)/\1/' | \
+  sort | uniq -c | sort -rn
+```
+
+### 3. Check Collaboration Structure
+
+```bash
+# Find active collaboration directories
+if [ -d "specs" ]; then
+  # List active sessions
+  SESSION_COUNT=$(find specs/*/collaboration/active/sessions -name "*.md" 2>/dev/null | wc -l)
+
+  # List pending handoffs
+  HANDOFF_COUNT=$(find specs/*/collaboration/active/decisions -name "handoff-*.md" 2>/dev/null | wc -l)
+
+  # List active features
+  FEATURES=$(find specs -maxdepth 1 -type d -name "[0-9]*" | wc -l)
+else
+  SESSION_COUNT=0
+  HANDOFF_COUNT=0
+  FEATURES=0
+fi
+```
+
+### 4. Generate ASCII Visualization
+
+Create a visual representation of sync status:
+
+```
+===========================================================
+Multi-Agent Sync Status
+===========================================================
+
+Branch: dev/001-starter-kits
+Remote: origin/dev/001-starter-kits
+
+     Local                    Remote
+       ↓                         ↓
+    ┌─────┐                  ┌─────┐
+    │ ●●● │  ←──(2 behind)── │ ●●  │
+    │ ●●  │  ──(3 ahead)───→ │     │
+    └─────┘                  └─────┘
+
+    3 commits to push
+    2 commits to pull
+    5 uncommitted changes
+
+===========================================================
+Agent Activity (last 7 days):
+===========================================================
+
+claude-code         ████████████ 12 commits
+github-copilot-cli  ████████ 8 commits
+
+===========================================================
+Collaboration Status:
+===========================================================
+
+Active features:     3
+Active sessions:     2
+Pending handoffs:    1 ⚠
+
+===========================================================
+```
+
+### 5. Check for Conflicts
+
+```bash
+# Check if there are merge conflicts
+if git ls-files -u | wc -l | grep -q "^0$"; then
+  echo "✓ No merge conflicts"
+else
+  echo "⚠ Merge conflicts detected"
+  git diff --name-only --diff-filter=U
+fi
+```
+
+### 6. Provide Sync Recommendations
+
+Based on the status, suggest actions:
+
+**If commits to pull**:
+```
+⚠ You are behind the remote branch
+
+Recommended action:
+  git pull origin $CURRENT_BRANCH
+
+Or if you have local commits:
+  git pull --rebase origin $CURRENT_BRANCH
+```
+
+**If commits to push**:
+```
+✓ You have commits to push
+
+Recommended action:
+  git push origin $CURRENT_BRANCH
+```
+
+**If handoffs pending**:
+```
+⚠ Pending handoff detected
+
+Review handoff:
+  cat specs/*/collaboration/active/decisions/handoff-*.md
+
+Accept handoff:
+  1. Review the handoff document
+  2. Create session log for your work
+  3. Remove handoff file when complete
+```
+
+**If diverged (both ahead and behind)**:
+```
+⚠ Branches have diverged
+
+You have local commits AND remote has new commits.
+
+Recommended actions:
+  1. Review remote changes: git fetch && git log HEAD..origin/$CURRENT_BRANCH
+  2. Pull with rebase: git pull --rebase origin $CURRENT_BRANCH
+  3. Resolve conflicts if any
+  4. Push: git push origin $CURRENT_BRANCH
+```
+
+### 7. Session Log Status
+
+If multiagent-kit installed, check session logs:
+
+```bash
+# Find today's session log
+TODAY=$(date +%Y-%m-%d)
+AGENT="claude-code"  # or "github-copilot-cli"
+
+SESSION_LOG=$(find specs/*/collaboration/active/sessions -name "${TODAY}*${AGENT}*.md" 2>/dev/null | head -1)
+
+if [ -n "$SESSION_LOG" ]; then
+  echo "✓ Session log exists: $SESSION_LOG"
+else
+  echo "⚠ No session log for today"
+  echo "  Create one: specs/<feature>/collaboration/active/sessions/${TODAY}-${AGENT}.md"
+fi
+```
+
+## Output Examples
+
+### Example 1: Clean Sync
+
+```
+===========================================================
+Multi-Agent Sync Status
+===========================================================
+
+Branch: dev/001-starter-kits
+Remote: origin/dev/001-starter-kits
+
+     Local                    Remote
+       ↓                         ↓
+    ┌─────┐                  ┌─────┐
+    │ ●●● │ ===(in sync)===  │ ●●● │
+    └─────┘                  └─────┘
+
+    ✓ Up to date with remote
+    ✓ No uncommitted changes
+
+===========================================================
+Agent Activity (last 7 days):
+===========================================================
+
+claude-code         ████████████ 12 commits
+
+===========================================================
+Collaboration Status:
+===========================================================
+
+Active features:     1
+Active sessions:     1
+Pending handoffs:    0
+
+✓ All in sync, ready to work!
+===========================================================
+```
+
+### Example 2: Needs Sync
+
+```
+===========================================================
+Multi-Agent Sync Status
+===========================================================
+
+Branch: dev/002-blog-feature
+Remote: origin/dev/002-blog-feature
+
+     Local                    Remote
+       ↓                         ↓
+    ┌─────┐                  ┌─────┐
+    │ ●   │  ←──(1 behind)── │ ●●  │
+    │     │  ──(0 ahead)───→ │ ●   │
+    └─────┘                  └─────┘
+
+    ⚠ 1 commit to pull
+    2 uncommitted changes
+
+===========================================================
+Agent Activity (last 7 days):
+===========================================================
+
+github-copilot-cli  ████████ 5 commits (most recent)
+claude-code         ████ 3 commits
+
+===========================================================
+Collaboration Status:
+===========================================================
+
+Active features:     1
+Active sessions:     2
+Pending handoffs:    1 ⚠
+
+Handoff found:
+  specs/002-blog-feature/collaboration/active/decisions/handoff-to-claude.md
+
+===========================================================
+Recommended Actions:
+===========================================================
+
+1. Review handoff: cat specs/002-blog-feature/collaboration/active/decisions/handoff-to-claude.md
+2. Pull latest: git pull origin dev/002-blog-feature
+3. Review changes: git log -1 origin/dev/002-blog-feature
+4. Start work on handoff items
+
+===========================================================
+```
+
+## Advanced Features
+
+### Check Worktree Status
+
+If working with worktrees:
+
+```bash
+# List all worktrees
+git worktree list
+
+# Check which worktrees are active
+for worktree in $(git worktree list --porcelain | grep "worktree" | cut -d' ' -f2); do
+  echo "Worktree: $worktree"
+  cd "$worktree"
+  git status --short
+  cd - > /dev/null
+done
+```
+
+### Compare with Other Branches
+
+```bash
+# Compare with main
+git log main..HEAD --oneline --format="%h %s (via %b)" | grep "via"
+
+# Show what's new in main since you branched
+git log HEAD..main --oneline
+```
+
+### Check for Stale Branches
+
+```bash
+# List branches not updated in 30 days
+git for-each-ref --format='%(refname:short) %(committerdate:relative)' \
+  refs/heads/ | grep -E '(weeks|months|years) ago'
+```
+
+## Important Notes
+
+- **Read-only**: This command never modifies git state
+- **Fast**: Only checks status, doesn't fetch from remote
+- **Visual**: ASCII art helps quickly understand sync state
+- **Multi-agent aware**: Highlights collaboration indicators
+- **Actionable**: Provides specific next steps
+
+## Integration with /orient
+
+The `/sync` command complements `/orient`:
+- `/orient` - Initial orientation when starting work
+- `/sync` - Check status during work session
+- `/commit` - Save work with attribution
+- `/pr` - Create pull request when done
+
+Use `/sync` frequently during multi-agent sessions to stay coordinated!