lite-kits 0.1.0__py3-none-any.whl

lite_kits/kits/multiagent/memory/pr-workflow-guide.md

@@ -0,0 +1,281 @@
+# AI Agent Pull Request Workflow Guide
+
+**Version**: 1.0.0
+**Last Updated**: 2025-10-06
+
+## Purpose
+
+This guide defines the workflow for AI agents (Claude Code, GitHub Copilot, Cursor) when creating pull requests in spec-kit projects with multiagent coordination.
+
+## Core Principles
+
+1. **Commit your own work**: Each agent commits and pushes their own changes
+2. **Attribute properly**: Include model and interface information in commits
+3. **Coordinate via collaboration/**: Use feature collaboration directories for handoffs
+4. **Test before PR**: Run validation locally before creating pull request
+
+## Pull Request Workflow
+
+### Step 1: Complete Your Work
+
+```bash
+# Ensure all changes are committed
+git status
+
+# Run tests if available
+npm test || pytest || cargo test
+
+# Validate against constitution
+lite-kits validate
+```
+
+### Step 2: Update Collaboration Directory
+
+Create a session summary:
+```
+specs/NNN-feature/collaboration/active/sessions/YYYY-MM-DD-agent-summary.md
+
+## Session Summary
+**Agent**: Claude Code (claude-sonnet-4.5)
+**Date**: 2025-10-06
+**Duration**: 45 minutes
+
+### Completed
+- Implemented user authentication
+- Added password hashing with bcrypt
+- Created login/logout endpoints
+
+### Files Changed
+- src/auth.py (new)
+- src/models.py (modified)
+- tests/test_auth.py (new)
+
+### Tests
+- All tests passing (12/12)
+- Coverage: 94%
+
+### Next Steps
+- Review needed on password complexity requirements
+- Consider adding 2FA in future iteration
+```
+
+### Step 3: Create Pull Request
+
+**Preferred**: Use GitHub CLI (best for Copilot):
+```bash
+gh pr create --title "feat: Add user authentication" --body "$(cat <<'EOF'
+## Summary
+- Implemented bcrypt password hashing
+- Created login/logout API endpoints
+- Added comprehensive test coverage (94%)
+
+## Test Plan
+- [x] Unit tests passing (12/12)
+- [x] Manual testing of login flow
+- [x] Password validation tested
+- [ ] Security review needed
+
+## Related
+- Implements: specs/003-user-auth/spec.md
+- Session: specs/003-user-auth/collaboration/active/sessions/2025-10-06-claude-auth.md
+
+🤖 Generated with spec-kit-multiagent
+via claude-sonnet-4.5 @ claude-code
+EOF
+)"
+```
+
+**Alternative**: Manual PR creation via web interface
+
+### Step 4: Request Review
+
+Tag appropriate reviewers based on project conventions:
+- Human reviewers for architectural decisions
+- Other AI agents for code style/coverage checks
+- Automated CI for tests and linting
+
+## Commit Attribution Format
+
+**Required format** for AI agent commits:
+
+```
+<conventional-commit-message>
+
+<detailed description if needed>
+
+via <model> @ <interface>
+```
+
+**Examples**:
+```
+feat: Add user authentication with bcrypt
+
+Implements password hashing, login/logout endpoints,
+and session management.
+
+via claude-sonnet-4.5 @ claude-code
+```
+
+```
+fix: Resolve race condition in async handlers
+
+via gpt-4 @ github-copilot-cli
+```
+
+```
+docs: Update API documentation for auth endpoints
+
+via claude-opus-4 @ cursor
+```
+
+## Multi-Agent Coordination
+
+### When Multiple Agents Work on Same Feature
+
+**Use git worktrees** for parallel development:
+```bash
+# Agent 1: Work on authentication
+git worktree add ../feature-auth-backend 003-user-auth
+
+# Agent 2: Work on frontend
+git worktree add ../feature-auth-frontend 003-user-auth
+```
+
+See [git-worktrees-protocol.md](./git-worktrees-protocol.md) for details.
+
+### Handoff Between Agents
+
+Create handoff document in collaboration directory:
+```markdown
+# specs/003-user-auth/collaboration/active/decisions/handoff-to-copilot.md
+
+## Handoff to GitHub Copilot
+
+**From**: Claude Code
+**To**: GitHub Copilot CLI
+**Date**: 2025-10-06
+
+### Context
+I've implemented the backend authentication. Frontend integration needed.
+
+### What's Done
+- Backend API endpoints (POST /login, POST /logout, GET /session)
+- Password hashing with bcrypt
+- Session management with JWT
+- Comprehensive tests (94% coverage)
+
+### What's Needed
+- Frontend login form component
+- Session state management
+- Protected route wrapper
+- Logout button integration
+
+### Files to Create
+- src/components/LoginForm.tsx
+- src/hooks/useAuth.ts
+- src/components/ProtectedRoute.tsx
+
+### Reference
+- API docs: specs/003-user-auth/contracts/auth-api.yaml
+- Session log: collaboration/active/sessions/2025-10-06-claude-backend.md
+```
+
+## PR Checklist for AI Agents
+
+Before creating PR, ensure:
+
+- [ ] All tests passing locally
+- [ ] Code follows project conventions (see constitution.md)
+- [ ] Session summary created in collaboration/active/sessions/
+- [ ] Commit messages include agent attribution
+- [ ] No secrets or credentials committed
+- [ ] Documentation updated if needed
+- [ ] Handoff document created if needed
+
+## Special Cases
+
+### Emergency Fixes
+
+For critical bugs, streamlined process:
+```bash
+# Fix immediately on feature branch
+git commit -m "fix: Critical security patch for auth bypass
+
+via claude-sonnet-4.5 @ claude-code"
+
+# Push directly (skip PR if authorized)
+git push origin 003-user-auth
+```
+
+### Constitution Conflicts
+
+If your work conflicts with constitution:
+1. **STOP** - Do not proceed with PR
+2. Create issue describing conflict
+3. Tag human maintainers for decision
+4. Wait for constitution amendment or spec adjustment
+
+## CI/CD Integration
+
+**Automated checks** run on all PRs:
+- Test suite execution
+- Code coverage thresholds
+- Linting and formatting
+- Agent attribution detection (extracts model info)
+- Constitution compliance checks
+
+**Agent-specific checks**:
+- Verify commit attribution format
+- Check for collaboration directory updates
+- Validate session summaries exist
+
+## Review Process
+
+**For AI-generated PRs**:
+1. Automated CI checks (must pass)
+2. Human review for:
+   - Architectural decisions
+   - Security implications
+   - UX considerations
+3. Optional: Other AI agents for code quality
+
+**Merge criteria**:
+- All CI checks passing
+- At least one human approval (for non-trivial changes)
+- No unresolved conversations
+- Collaboration directory updated
+
+## Post-Merge
+
+After PR merged:
+```bash
+# Archive session
+mv specs/NNN-feature/collaboration/active/sessions/YYYY-MM-DD-*.md \
+   specs/NNN-feature/collaboration/archive/YYYY-MM/
+
+# Update status
+echo "✓ Feature complete and merged" >> \
+   specs/NNN-feature/collaboration/results/artifacts/completion-summary.md
+```
+
+## Troubleshooting
+
+**PR creation fails**:
+- Check branch is pushed to remote
+- Verify GitHub CLI authenticated
+- Ensure base branch exists
+
+**CI checks fail**:
+- Pull latest from base branch
+- Run tests locally
+- Check for merge conflicts
+
+**Attribution missing**:
+- Amend last commit to add attribution
+- Force push (if not yet reviewed)
+
+## Resources
+
+- GitHub CLI docs: https://cli.github.com/manual/
+- Git worktrees: [git-worktrees-protocol.md](./git-worktrees-protocol.md)
+- Constitution: [constitution.md](./constitution.md)

lite_kits/kits/multiagent/templates/collaboration-structure/README.md

@@ -0,0 +1,166 @@
+# Collaboration Directory Structure
+
+This directory is created automatically when multiagent-kit is installed and you create a new feature with `/specify`.
+
+## Purpose
+
+Coordinate work between multiple AI agents (Claude Code, GitHub Copilot, etc.) on the same feature.
+
+## Structure
+
+```
+specs/<feature-number>-<feature-name>/
+└── collaboration/
+    ├── active/              # Current work in progress
+    │   ├── sessions/        # Individual agent work sessions
+    │   ├── decisions/       # Coordination decisions and handoffs
+    │   └── README.md        # Quick reference (this file copied here)
+    │
+    ├── archive/             # Completed sessions and decisions
+    │   ├── sessions/
+    │   └── decisions/
+    │
+    └── results/             # Outcomes and artifacts
+        ├── validation/      # Test results, reviews
+        └── artifacts/       # Generated files, diagrams, etc.
+```
+
+## Workflows
+
+### Solo Agent Work
+
+If only one agent is working:
+1. Create session log in `active/sessions/`
+2. Document decisions in `active/decisions/`
+3. When feature complete, archive to `archive/`
+
+### Multi-Agent Coordination
+
+When multiple agents collaborate:
+
+1. **Starting Work**
+   - Run `/orient` to check for pending handoffs
+   - Create session log: `active/sessions/YYYY-MM-DD-<agent-name>.md`
+   - Review recent sessions from other agents
+
+2. **Making Decisions**
+   - Document in `active/decisions/<decision-name>.md`
+   - Include: what was decided, why, by whom
+   - Tag with agent attribution
+
+3. **Handoff to Another Agent**
+   - Create: `active/decisions/handoff-to-<agent>.md`
+   - Include: context, what's done, what's needed
+   - Other agent will see it in `/orient` output
+
+4. **Accepting Handoff**
+   - Read the handoff document
+   - Create your session log
+   - Move handoff to `archive/decisions/` when acknowledged
+
+5. **Completing Feature**
+   - Move all active sessions to `archive/sessions/`
+   - Move decisions to `archive/decisions/`
+   - Save artifacts in `results/artifacts/`
+
+## File Naming Conventions
+
+### Sessions
+
+```
+active/sessions/YYYY-MM-DD-<agent-name>.md
+active/sessions/YYYY-MM-DD-<agent-name>-<description>.md
+
+Examples:
+active/sessions/2025-10-06-claude-code.md
+active/sessions/2025-10-06-copilot-frontend-work.md
+```
+
+### Decisions
+
+```
+active/decisions/<decision-type>-<brief-name>.md
+
+Examples:
+active/decisions/handoff-to-copilot.md
+active/decisions/architecture-database-choice.md
+active/decisions/worktree-territory-split.md
+```
+
+### Artifacts
+
+```
+results/artifacts/<type>-<name>.<ext>
+
+Examples:
+results/artifacts/diagram-auth-flow.svg
+results/artifacts/benchmark-api-performance.csv
+```
+
+## Template Usage
+
+When creating documents, use the templates:
+- Session log: Copy from `../../templates/session-log.md`
+- Handoff: Copy from `../../templates/handoff.md`
+- Decision: Copy from `../../templates/decision.md`
+
+## Integration with Git
+
+- Session logs and decisions are **committed to git**
+- They become part of the feature's history
+- Future agents can review them to understand context
+- Helps with knowledge transfer and onboarding
+
+## Best Practices
+
+1. **Write for the next agent**: Assume someone else will read your session logs
+2. **Link to commits**: Reference git commits in session logs
+3. **Keep current**: Move old sessions to archive/ regularly
+4. **Be specific**: "Added auth" → "Implemented JWT token validation in auth middleware"
+5. **Update handoffs**: If you discover something while working, update the handoff
+6. **Time-stamp everything**: Helps understand sequence of events
+
+## Quick Commands
+
+```bash
+# Create session log
+touch active/sessions/$(date +%Y-%m-%d)-claude-code.md
+
+# Create handoff
+cat > active/decisions/handoff-to-copilot.md << EOF
+# Handoff to GitHub Copilot
+
+**From**: Claude Code
+**Date**: $(date +%Y-%m-%d)
+
+## Context
+[What you were working on]
+
+## Completed
+- [x] Task 1
+- [x] Task 2
+
+## Needed
+- [ ] Task 3
+- [ ] Task 4
+
+## Files
+- src/components/Auth.tsx (needs UI implementation)
+
+## Notes
+[Any gotchas or important context]
+EOF
+
+# Archive session
+mv active/sessions/2025-10-05-*.md archive/sessions/
+
+# List recent activity
+ls -lt active/sessions/ | head -5
+```
+
+## See Also
+
+- `/orient` - Check for pending handoffs
+- `/sync` - View collaboration status
+- `/commit` - Smart commits with agent attribution
+- Workflow guide: `.specify/memory/pr-workflow-guide.md`

lite_kits/kits/multiagent/templates/decision.md

@@ -0,0 +1,79 @@
+# Decision: [DECISION TITLE]
+
+**Date**: YYYY-MM-DD
+**Decided by**: [agent-name]
+**Status**: [proposed / accepted / implemented / superseded]
+
+## Context
+
+[What situation led to this decision? What problem are we solving?]
+
+## Decision
+
+[What was decided? Be specific and clear.]
+
+## Rationale
+
+[Why did we make this decision? What factors influenced it?]
+
+## Alternatives Considered
+
+### Option 1: [Alternative Name]
+- **Pros**:
+  - [Pro 1]
+  - [Pro 2]
+- **Cons**:
+  - [Con 1]
+  - [Con 2]
+- **Why not chosen**: [reason]
+
+### Option 2: [Alternative Name]
+- **Pros**:
+  - [Pro 1]
+- **Cons**:
+  - [Con 1]
+- **Why not chosen**: [reason]
+
+## Implications
+
+**Impact on**:
+- **Architecture**: [how this affects system design]
+- **Performance**: [performance implications if any]
+- **Maintenance**: [how this affects future work]
+- **Other features**: [what else is affected]
+
+## Implementation
+
+**Files affected**:
+- `path/to/file1.ext`
+- `path/to/file2.ext`
+
+**Commits implementing this**:
+- `abc1234` - [commit message]
+- `def5678` - [commit message]
+
+**Testing requirements**:
+- [ ] Test requirement 1
+- [ ] Test requirement 2
+
+## Reversibility
+
+**Can this be reversed?** [yes / no / partially]
+
+**If yes, how?**
+[Steps to reverse this decision if needed]
+
+**Cost of reversal**:
+[How much work to reverse it]
+
+## References
+
+- Related decisions: [link to other decision docs]
+- External docs: [relevant links]
+- Discussion: [where this was discussed]
+
+---
+
+**Decision ID**: [unique identifier if needed]
+**Reviewed by**: [other agent if applicable]
+**Last updated**: YYYY-MM-DD

lite_kits/kits/multiagent/templates/handoff.md

@@ -0,0 +1,95 @@
+# Handoff: [FROM-AGENT] → [TO-AGENT]
+
+**From**: [claude-code / github-copilot-cli]
+**To**: [claude-code / github-copilot-cli]
+**Date**: YYYY-MM-DD
+**Feature**: [feature number and name]
+
+## Summary
+
+[1-2 paragraph summary of what's been done and what's needed]
+
+## Context
+
+**Why this handoff?**
+[Reason for the handoff - different expertise, workload balance, etc.]
+
+**Current state**:
+[Where the feature is now - what works, what doesn't]
+
+## Completed Work
+
+- [x] Task 1 - [brief description]
+- [x] Task 2 - [brief description]
+- [x] Task 3 - [brief description]
+
+**Commits**:
+- `abc1234` - [commit message]
+- `def5678` - [commit message]
+
+**Key files**:
+- `path/to/file1.ext` - [what it does]
+- `path/to/file2.ext` - [what it does]
+
+## Needed Work
+
+- [ ] Task 1 - [description]
+  - Why: [rationale or context]
+  - Files: [which files to modify]
+
+- [ ] Task 2 - [description]
+  - Why: [rationale or context]
+  - Files: [which files to modify]
+
+## Important Notes
+
+**✓ What's working**:
+- [Feature A works correctly]
+- [Test B passes]
+
+**⚠ Known issues**:
+- [Issue 1 to be aware of]
+- [Issue 2 to handle]
+
+**🔍 Areas to focus on**:
+- [Priority area 1]
+- [Priority area 2]
+
+## Testing
+
+**Manual testing done**:
+- [x] Test scenario 1
+- [x] Test scenario 2
+- [ ] Test scenario 3 (needs completion)
+
+**Automated tests**:
+- [x] Unit tests pass
+- [ ] Integration tests (need to be written)
+
+## References
+
+- Related issue: #123
+- Design doc: [link or path]
+- API docs: [link]
+
+## Questions for Receiving Agent
+
+> Things to consider or decide:
+
+1. [Question 1]?
+2. [Question 2]?
+
+## Acceptance Criteria
+
+> When you can consider this handoff accepted:
+
+- [ ] Reviewed all committed code
+- [ ] Understand the needed work
+- [ ] No blocking questions
+- [ ] Session log created for your work
+
+---
+
+**Handoff Status**: pending
+**Acknowledged by**: _______
+**Acknowledged date**: _______

lite_kits/kits/multiagent/templates/session-log.md

@@ -0,0 +1,68 @@
+# Session Log: [AGENT-NAME]
+
+**Date**: YYYY-MM-DD
+**Agent**: [claude-code / github-copilot-cli]
+**Feature**: [feature number and name]
+**Duration**: [HH:MM or "ongoing"]
+
+## Session Goals
+
+- [ ] Goal 1
+- [ ] Goal 2
+- [ ] Goal 3
+
+## Work Completed
+
+### [Task/Area 1]
+- Implemented: [what was done]
+- Files changed:
+  - `path/to/file1.ext`
+  - `path/to/file2.ext`
+- Commits:
+  - `abc1234` - [commit message]
+
+### [Task/Area 2]
+- Implemented: [what was done]
+- Files changed:
+  - `path/to/file3.ext`
+- Commits:
+  - `def5678` - [commit message]
+
+## Decisions Made
+
+1. **[Decision Title]**
+   - What: [what was decided]
+   - Why: [rationale]
+   - Alternatives considered: [if any]
+   - Impact: [how this affects the feature]
+
+## Blockers / Issues
+
+- ⚠ [Issue 1 if any]
+- ⚠ [Issue 2 if any]
+
+## Handoff Items
+
+> If handing off to another agent, fill this out:
+
+- [ ] Task for next agent
+- [ ] Another task
+- [ ] Final task
+
+**Handoff notes**:
+[Any context the next agent needs]
+
+## Next Steps
+
+- [ ] Next action 1
+- [ ] Next action 2
+
+## Notes
+
+[Any additional context, learnings, gotchas, or references]
+
+---
+
+**Session Status**: [ongoing / completed / handed-off]
+**Commits this session**: [N commits]
+**Lines changed**: [+X -Y]