12abdfe81d
Implements FED-010: Agent Spawn via Federation feature that enables spawning and managing Claude agents on remote federated Mosaic Stack instances via COMMAND message type. Features: - Federation agent command types (spawn, status, kill) - FederationAgentService for handling agent operations - Integration with orchestrator's agent spawner/lifecycle services - API endpoints for spawning, querying status, and killing agents - Full command routing through federation COMMAND infrastructure - Comprehensive test coverage (12/12 tests passing) Architecture: - Hub → Spoke: Spawn agents on remote instances - Command flow: FederationController → FederationAgentService → CommandService → Remote Orchestrator - Response handling: Remote orchestrator returns agent status/results - Security: Connection validation, signature verification Files created: - apps/api/src/federation/types/federation-agent.types.ts - apps/api/src/federation/federation-agent.service.ts - apps/api/src/federation/federation-agent.service.spec.ts Files modified: - apps/api/src/federation/command.service.ts (agent command routing) - apps/api/src/federation/federation.controller.ts (agent endpoints) - apps/api/src/federation/federation.module.ts (service registration) - apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint) - apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration) Testing: - 12/12 tests passing for FederationAgentService - All command service tests passing - TypeScript compilation successful - Linting passed Refs #93 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
283 lines
5.3 KiB
Markdown
283 lines
5.3 KiB
Markdown
# Branching Strategy
|
|
|
|
Git workflow and branching conventions for Mosaic Stack.
|
|
|
|
## Branch Types
|
|
|
|
### Main Branches
|
|
|
|
**`main`** — Production-ready code only
|
|
|
|
- Never commit directly
|
|
- Only merge from `develop` via release
|
|
- Tagged with version numbers
|
|
|
|
**`develop`** — Active development (default branch)
|
|
|
|
- All features merge here first
|
|
- Must always build and pass tests
|
|
- Protected branch
|
|
|
|
### Supporting Branches
|
|
|
|
**`feature/*`** — New features
|
|
|
|
```bash
|
|
# From: develop
|
|
# Merge to: develop
|
|
# Naming: feature/issue-number-description
|
|
|
|
git checkout develop
|
|
git pull --rebase
|
|
git checkout -b feature/6-frontend-auth
|
|
```
|
|
|
|
**`fix/*`** — Bug fixes
|
|
|
|
```bash
|
|
# From: develop (or main for hotfixes)
|
|
# Merge to: develop (or both main and develop)
|
|
# Naming: fix/issue-number-description
|
|
|
|
git checkout develop
|
|
git checkout -b fix/12-session-timeout
|
|
```
|
|
|
|
**`refactor/*`** — Code improvements
|
|
|
|
```bash
|
|
# From: develop
|
|
# Merge to: develop
|
|
# Naming: refactor/area-description
|
|
|
|
git checkout -b refactor/auth-service-cleanup
|
|
```
|
|
|
|
**`docs/*`** — Documentation updates
|
|
|
|
```bash
|
|
# From: develop
|
|
# Merge to: develop
|
|
# Naming: docs/topic
|
|
|
|
git checkout -b docs/api-reference
|
|
```
|
|
|
|
## Workflow
|
|
|
|
### 1. Start New Work
|
|
|
|
```bash
|
|
# Always start from latest develop
|
|
git checkout develop
|
|
git pull --rebase
|
|
|
|
# Create feature branch
|
|
git checkout -b feature/7-task-management
|
|
|
|
# Optional: Use git worktree for parallel work
|
|
git worktree add ../mosaic-stack_worktrees/7-task-management -b feature/7-task-management
|
|
```
|
|
|
|
### 2. Make Changes
|
|
|
|
```bash
|
|
# Make changes, write tests first (TDD)
|
|
# Build and test after each change
|
|
pnpm test
|
|
pnpm build
|
|
|
|
# Commit frequently with conventional format
|
|
git add .
|
|
git commit -m "feat(#7): Add task creation endpoint"
|
|
```
|
|
|
|
### 3. Stay Updated
|
|
|
|
```bash
|
|
# Regularly sync with develop
|
|
git checkout develop
|
|
git pull --rebase
|
|
git checkout feature/7-task-management
|
|
git rebase develop
|
|
|
|
# Resolve conflicts if any
|
|
```
|
|
|
|
### 4. Push Changes
|
|
|
|
```bash
|
|
# Push feature branch
|
|
git push -u origin feature/7-task-management
|
|
```
|
|
|
|
### 5. Create Pull Request
|
|
|
|
```bash
|
|
# Use git.mosaicstack.dev web UI or
|
|
pr-create.sh -t "Implement task management" \
|
|
-b "Adds full CRUD for tasks with tests" \
|
|
-i 7
|
|
|
|
# Or with gh CLI
|
|
gh pr create --title "feat(#7): Implement task management" \
|
|
--body "Full task management implementation..." \
|
|
--base develop \
|
|
--head feature/7-task-management
|
|
```
|
|
|
|
### 6. Code Review
|
|
|
|
- All PRs require review before merge
|
|
- Address review comments
|
|
- Keep commits clean (squash if messy)
|
|
|
|
### 7. Merge
|
|
|
|
```bash
|
|
# After approval, squash and merge
|
|
pr-merge.sh -n 7 -m squash -d
|
|
|
|
# Or via web UI: "Squash and Merge"
|
|
```
|
|
|
|
## Commit Message Format
|
|
|
|
```
|
|
<type>(#issue): Brief description
|
|
|
|
Detailed explanation if needed.
|
|
|
|
Fixes #123
|
|
```
|
|
|
|
### Types
|
|
|
|
- `feat` — New feature
|
|
- `fix` — Bug fix
|
|
- `docs` — Documentation
|
|
- `test` — Test additions/changes
|
|
- `refactor` — Code restructuring
|
|
- `chore` — Maintenance tasks
|
|
- `perf` — Performance improvements
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
feat(#7): Add task creation endpoint
|
|
|
|
Implements POST /api/tasks with validation and tests.
|
|
Includes database migration for task table.
|
|
|
|
Fixes #7
|
|
|
|
---
|
|
|
|
fix(#12): Resolve session timeout issue
|
|
|
|
Sessions were expiring prematurely due to incorrect JWT config.
|
|
Updated JWT_EXPIRATION to use proper time format.
|
|
|
|
Fixes #12
|
|
|
|
---
|
|
|
|
docs(#15): Add API authentication guide
|
|
|
|
Complete guide for auth endpoints with examples.
|
|
|
|
Refs #15
|
|
```
|
|
|
|
## Protected Branch Rules
|
|
|
|
### `main` Branch
|
|
|
|
- No direct commits
|
|
- Require PR approval
|
|
- Require passing tests
|
|
- Require up-to-date branch
|
|
|
|
### `develop` Branch
|
|
|
|
- No direct commits (use PRs)
|
|
- Require passing tests
|
|
- Auto-delete head branches after merge
|
|
|
|
## Git Worktrees
|
|
|
|
For working on multiple issues simultaneously:
|
|
|
|
```bash
|
|
# Structure: {project_name}_worktrees/{issue-name}/
|
|
mkdir ~/src/mosaic-stack_worktrees
|
|
|
|
# Create worktree for issue #7
|
|
cd ~/src/mosaic-stack
|
|
git worktree add ../mosaic-stack_worktrees/7-task-management -b feature/7-task-management
|
|
|
|
# Work in worktree
|
|
cd ../mosaic-stack_worktrees/7-task-management
|
|
# Make changes, commit, push
|
|
|
|
# List worktrees
|
|
git worktree list
|
|
|
|
# Remove after merge
|
|
git worktree remove ../mosaic-stack_worktrees/7-task-management
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Always start from `develop`**
|
|
2. **Keep branches short-lived** (max 1-2 weeks)
|
|
3. **Write tests first** (TDD approach)
|
|
4. **Commit frequently** with clear messages
|
|
5. **Rebase, don't merge** when syncing with develop
|
|
6. **Squash commits** before merging PR
|
|
7. **Delete branches** after merging
|
|
8. **Reference issues** in all commits
|
|
|
|
## Troubleshooting
|
|
|
|
### Conflicts During Rebase
|
|
|
|
```bash
|
|
# Start rebase
|
|
git rebase develop
|
|
|
|
# Conflicts occur
|
|
# Edit conflicting files
|
|
|
|
# Mark as resolved
|
|
git add <conflicted-files>
|
|
git rebase --continue
|
|
|
|
# Or abort and try later
|
|
git rebase --abort
|
|
```
|
|
|
|
### Accidentally Committed to `develop`
|
|
|
|
```bash
|
|
# Undo last commit (keep changes)
|
|
git reset --soft HEAD~1
|
|
|
|
# Create proper feature branch
|
|
git checkout -b feature/my-changes
|
|
|
|
# Commit again
|
|
git commit -m "feat: My changes"
|
|
|
|
# Force-push develop back to origin (if already pushed)
|
|
git checkout develop
|
|
git reset --hard origin/develop
|
|
git push --force
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- **Testing Requirements** — [Testing](2-testing.md)
|
|
- **Commit Guidelines** — [Committing](3-committing.md)
|
|
- **Database Migrations** — [Database](../2-database/2-migrations.md)
|