Phase 1 Goal: Production-ready MVP
Duration: 10 weeks (part-time) / 6 weeks (full-time)
Total Effort: ~240 hours
Team Size: 1-2 developers
✅ Core commands working: init, sync, status, list, validate
✅ Git-based versioning functional
✅ Auto-discovery implemented
✅ Schema validation working
✅ Namespace isolation working
✅ Tag-based filtering working
✅ 80%+ test coverage
✅ Documentation complete
✅ Beta release published
Owner: Dev Lead
Priority: P0 (Blocker)
Subtasks:
-
Create GitHub repository (1h)
- Initialize with .gitignore, LICENSE (MIT)
- Setup branch protection rules
- Configure issue templates
-
Setup package.json & TypeScript (2h)
- Configure tsconfig.json (strict mode)
- Setup build pipeline (tsup or esbuild)
- Configure ESLint + Prettier
-
Setup testing framework (2h)
- Install Vitest
- Configure test environment
- Setup coverage reporting
-
CI/CD Pipeline (1h)
- GitHub Actions for tests
- GitHub Actions for build
- Automated npm publishing workflow
Deliverables:
- ✅ Repository ready for development
- ✅ CI/CD passing
- ✅ Dev environment documented
Acceptance Criteria:
npm installworksnpm testruns (even if empty)npm run buildproduces dist/- CI passes on main branch
Owner: Dev 1
Priority: P0
Dependencies: Task 1.1
Subtasks:
-
Create directory structure (1h)
src/ ├── cli/ │ ├── commands/ │ ├── middleware/ │ └── index.ts ├── core/ │ ├── discovery/ │ ├── git/ │ ├── sync/ │ ├── validator/ │ └── namespace/ ├── schemas/ ├── types/ └── utils/ -
Define core TypeScript interfaces (4h)
- TeamConfig interface
- Lockfile interface
- ConfigEntry interface
- SyncResult interface
- ValidationResult interface
- ManifestSchema interface
- AgentConfig, SkillConfig, MCPConfig types
-
Setup error types hierarchy (2h)
- ValidationError
- SyncError
- GitError
- ConfigError
- Custom error classes with codes
-
Create constants & defaults (1h)
- File paths constants
- Default configurations
- Error codes enum
Deliverables:
- ✅ types/ folder with all interfaces
- ✅ Project structure in place
- ✅ Type exports working
Acceptance Criteria:
- All types compile without errors
- Type imports work across modules
- JSDoc documentation on all interfaces
Owner: Dev 1
Priority: P0
Dependencies: Task 1.2
Subtasks:
-
Setup Commander.js (2h)
- Install and configure
- Create base CLI structure
- Setup version, help commands
-
Create command base class (2h)
- Abstract base command
- Common flags (--verbose, --quiet, --debug)
- Error handling middleware
-
Setup logging system (2h)
- Install Winston or Pino
- Configure log levels
- File & console transports
- Debug mode support
Deliverables:
- ✅
oct --helpworks - ✅
oct --versionworks - ✅ Logging functional
Acceptance Criteria:
- CLI can be invoked
- Help text displays
- Logging writes to files when --debug
Owner: Dev 1
Priority: P0
Subtasks:
-
Install & configure simple-git (1h)
-
Implement GitManager class (5h)
class GitManager { clone(url: string, destination: string): Promise<void> fetch(repoPath: string): Promise<void> checkout(repoPath: string, ref: string): Promise<void> getCurrentCommit(repoPath: string): Promise<string> listTags(repoPath: string): Promise<string[]> listBranches(repoPath: string): Promise<string[]> hasUncommittedChanges(repoPath: string): Promise<boolean> }
-
Error handling for Git operations (1h)
- Network errors
- Authentication errors
- Repository not found
- Invalid ref
-
Unit tests (1h)
- Mock git operations
- Test error scenarios
Deliverables:
- ✅ GitManager class fully implemented
- ✅ 80%+ test coverage
Acceptance Criteria:
- Can clone a repository
- Can checkout tags/branches/commits
- Errors are properly caught and typed
- All tests pass
Owner: Dev 2 (or Dev 1)
Priority: P0
Subtasks:
-
Implement FileSystemManager (4h)
class FileSystemManager { ensureDir(path: string): Promise<void> copyFile(src: string, dest: string): Promise<void> removeFile(path: string): Promise<void> readFile(path: string): Promise<string> writeFile(path: string, content: string): Promise<void> listFiles(dir: string, pattern?: string): Promise<string[]> fileExists(path: string): Promise<boolean> getFileHash(path: string): Promise<string> }
-
Path resolution utilities (1h)
- getGlobalConfigPath()
- getProjectConfigPath()
- resolveTeamConfigPath()
- resolvePersonalConfigPath()
-
Unit tests (1h)
Deliverables:
- ✅ FileSystemManager implemented
- ✅ Path utilities working
- ✅ Tests passing
Acceptance Criteria:
- Can read/write files safely
- Path resolution works on Unix and Windows
- Errors handled gracefully
Owner: Dev 1
Priority: P1
Subtasks:
-
Install Zod (0.5h)
-
Define Zod schemas (3h)
- Agent schema (frontmatter validation)
- Skill schema (SKILL.md validation)
- Manifest schema (.opencode-team.yaml)
- Lockfile schema
-
Implement Validator classes (2h)
class AgentValidator { validate(content: string): ValidationResult validateFrontmatter(fm: unknown): ValidationResult } class SkillValidator { validate(path: string): ValidationResult validateName(name: string): boolean } class MCPValidator { validate(content: string): ValidationResult }
-
Unit tests (0.5h)
Deliverables:
- ✅ All validators implemented
- ✅ Zod schemas complete
- ✅ Tests passing
Acceptance Criteria:
- Valid configs pass validation
- Invalid configs return meaningful errors
- Error messages are actionable
Owner: Dev 1
Priority: P0
Dependencies: Tasks 2.1, 2.2
Subtasks:
-
Command interface & flags (2h)
oct init <repository-url> [options] Options: --ref <ref> Git ref (branch/tag/commit) --global Install globally --tags <tags> Initial tag filter
-
Init workflow implementation (8h)
- Parse & validate repository URL
- Determine scope (global vs project)
- Clone repository to temp location
- Checkout specified ref
- Discover configurations
- Validate configurations
- Create namespace directories (team/)
- Generate lockfile
- Perform initial sync
- Cleanup temp files
-
Error handling (1h)
- Invalid URL
- Repository not accessible
- Invalid ref
- Validation failures
- Disk space issues
-
Tests (1h)
Deliverables:
- ✅
oct initworking end-to-end - ✅ Lockfile generated correctly
- ✅ Tests passing
Acceptance Criteria:
- Can initialize from GitHub/GitLab URL
- Creates proper directory structure
- Generates valid lockfile
- Initial configs synced
- Errors are clear and actionable
Owner: Dev 1
Priority: P0
Dependencies: Task 3.1
Subtasks:
-
Lockfile interface implementation (4h)
class LockfileManager { read(path: string): Promise<Lockfile> write(path: string, lockfile: Lockfile): Promise<void> update(path: string, updates: Partial<Lockfile>): Promise<void> validate(lockfile: Lockfile): ValidationResult }
-
Lockfile schema (Zod) (2h)
-
Lockfile operations (1h)
- Create new lockfile
- Update existing
- Read and parse
- Validate integrity
-
Tests (1h)
Deliverables:
- ✅ LockfileManager working
- ✅ Schema validation working
- ✅ Tests passing
Acceptance Criteria:
- Can create/read/update lockfile
- Schema validation prevents corruption
- File format is human-readable YAML
Owner: Dev 1
Priority: P0
Dependencies: Tasks 2.1, 2.2, 2.3, 3.2
Subtasks:
-
SyncEngine class implementation (8h)
class SyncEngine { sync(options: SyncOptions): Promise<SyncResult> private discoverConfigs(): Promise<ConfigEntry[]> private filterByTags(configs: ConfigEntry[]): ConfigEntry[] private validateConfigs(configs: ConfigEntry[]): ValidationResult[] private detectChanges(local: ConfigEntry[], remote: ConfigEntry[]): Changes private applyChanges(changes: Changes): Promise<SyncResult> private handleConflicts(conflicts: Conflict[]): Promise<Resolution[]> }
-
Change detection algorithm (2h)
- Compare file hashes
- Detect added/updated/removed
- Detect conflicts (team vs personal)
-
Conflict resolution (1h)
- Namespace-based isolation
- Warnings for overrides
-
Tests (1h)
Deliverables:
- ✅ SyncEngine working
- ✅ Change detection accurate
- ✅ Tests passing
Acceptance Criteria:
- Correctly syncs configurations
- Detects all changes
- Handles conflicts per spec
- Provides detailed sync report
Owner: Dev 1
Priority: P0
Dependencies: Task 4.1
Subtasks:
-
Command interface & flags (2h)
oct sync [options] Options: --tags <tags> Filter by tags --exclude-tags <tags> Exclude tags --dry-run Preview changes --force-team Team configs override personal --no-validate Skip validation
-
Command implementation (4h)
- Read lockfile
- Fetch from Git (if needed)
- Run SyncEngine
- Display results
- Update lockfile
-
Output formatting (1h)
- Clear progress indicators
- Summary of changes
- Warnings and errors
-
Tests (1h)
Deliverables:
- ✅
oct syncworking - ✅ Dry-run mode working
- ✅ Tests passing
Acceptance Criteria:
- Syncs configurations correctly
- Dry-run shows accurate preview
- Output is clear and actionable
- Lockfile updated after sync
Owner: Dev 1
Priority: P1
Dependencies: Task 3.2
Subtasks:
-
Status checker implementation (3h)
class StatusChecker { checkStatus(): Promise<StatusInfo> checkForUpdates(): Promise<UpdateInfo> getLocalState(): Promise<LocalState> }
-
Command implementation (2h)
- Display current version
- Show last sync time
- Check for updates
- Display synced configs count
-
Tests (1h)
Deliverables:
- ✅
oct statusworking - ✅ Update detection working
Acceptance Criteria:
- Shows current state accurately
- Detects updates available
- Output is clean and readable
Owner: Dev 1
Priority: P1
Subtasks:
-
List functionality (3h)
- List all configs (team + personal)
- Filter by type (agent/skill)
- Filter by tags
- Sort options
-
Output formatting (2h)
- Table format
- Tree format
- JSON format (--json flag)
- Verbose mode
-
Tests (1h)
Deliverables:
- ✅
oct listworking - ✅ Multiple output formats
Acceptance Criteria:
- Lists all configurations correctly
- Filters work as expected
- Output is well-formatted
Owner: Dev 1
Priority: P1
Dependencies: Task 2.3
Subtasks:
-
Validation orchestrator (4h)
class ValidationOrchestrator { validateLocal(): Promise<ValidationReport> validateRemote(repoUrl: string): Promise<ValidationReport> validateSingle(path: string): Promise<ValidationResult> }
-
Command implementation (2h)
- Validate local team configs
- Validate remote before sync (--remote)
- Single file validation
-
Output formatting (1h)
- Clear error/warning messages
- Line numbers and context
- Suggestions for fixes
-
Tests (1h)
Deliverables:
- ✅
oct validateworking - ✅ Clear error messages
Acceptance Criteria:
- Validates all config types
- Error messages are actionable
- Can validate before sync
Owner: Dev 1
Priority: P2
Subtasks:
-
Remove command (4h)
oct remove <config-name> [options] Options: --type <type> Config type (agent/skill)
- Remove single config
- Update lockfile
- Confirmation prompt
-
Clean command (3h)
oct clean [options] Options: --force Skip confirmation
- Remove all team configs
- Keep personal configs
- Confirmation prompt
-
Tests (1h)
Deliverables:
- ✅ Both commands working
- ✅ Safety checks in place
Acceptance Criteria:
- Can remove single configs
- Can clean all team configs
- Personal configs untouched
- Confirmation required
Owner: Dev 1
Priority: P2
Subtasks:
-
System info collector (2h)
- OpenCode version
- oct version
- Repository info
- Config paths
- System info
-
Command implementation (1h)
-
Tests (1h)
Deliverables:
- ✅
oct infoworking
Acceptance Criteria:
- Shows all relevant info
- Useful for debugging
Owner: Dev 1
Priority: P1
Subtasks:
-
Update command (4h)
oct update [options] Options: --dry-run Preview changes
- Fetch latest from Git
- Compare versions
- Apply updates
- Update lockfile
-
Rollback command (3h)
oct rollback [options] Options: --to <ref> Rollback to specific version
- Read previous state
- Restore configurations
- Update lockfile
-
Tests (1h)
Deliverables:
- ✅ Update working
- ✅ Rollback working
Acceptance Criteria:
- Can update to latest
- Can rollback to previous
- Lockfile tracks history
Owner: Dev 1
Priority: P0
Subtasks:
-
DiscoveryEngine class (8h)
class DiscoveryEngine { discover(repoPath: string): Promise<ConfigEntry[]> private discoverAgents(path: string): Promise<ConfigEntry[]> private discoverSkills(path: string): Promise<ConfigEntry[]> private discoverMCP(path: string): Promise<ConfigEntry[]> private parseManifest(path: string): Promise<Manifest> private mergeManifestWithDiscovery(): ConfigEntry[] }
-
Pattern matching (2h)
- Glob patterns for each type
- Exclusion patterns
- Performance optimization
-
Manifest parser (1h)
- Parse .opencode-team.yaml
- Merge with auto-discovery
- Handle overrides
-
Tests (1h)
Deliverables:
- ✅ Discovery engine working
- ✅ Manifest support working
Acceptance Criteria:
- Discovers all config types
- Respects manifest overrides
- Fast even with large repos
Owner: Dev 1
Priority: P0
Subtasks:
-
Tag resolver (4h)
class TagResolver { filterByTags(configs: ConfigEntry[], tags: string[]): ConfigEntry[] excludeTags(configs: ConfigEntry[], tags: string[]): ConfigEntry[] matchTags(configTags: string[], filterTags: string[]): boolean }
-
Tag extraction from configs (2h)
- Parse tags from manifest
- Parse tags from frontmatter
- Merge global tags
-
Tag matching algorithm (1h)
- AND/OR logic
- Exclusion logic
-
Tests (1h)
Deliverables:
- ✅ Tag filtering working
- ✅ Complex queries supported
Acceptance Criteria:
- Can filter by single tag
- Can filter by multiple tags
- Can exclude tags
- Tag matching is accurate
Owner: Dev 1
Priority: P0
Subtasks:
-
NamespaceManager class (6h)
class NamespaceManager { resolveTeamPath(type: string, name: string): string resolvePersonalPath(type: string, name: string): string detectConflicts(): Promise<Conflict[]> resolvePrecedence(configName: string): 'team' | 'personal' ensureNamespaces(): Promise<void> }
-
Conflict detection (2h)
- Find duplicate names
- Determine precedence
- Generate warnings
-
Namespace isolation enforcement (1h)
- Team configs read-only
- Personal configs full-access
-
Tests (1h)
Deliverables:
- ✅ Namespace isolation working
- ✅ Conflicts detected correctly
Acceptance Criteria:
- Team configs in team/ directory
- Personal configs in personal/
- Conflicts reported with warnings
- Precedence rules enforced
Owner: Dev 1
Priority: P1
Subtasks:
-
Error class hierarchy (3h)
- Base OpenCodeTeamError
- Specific error types
- Error codes enum
- Error serialization
-
Error recovery mechanisms (3h)
- Retry logic for network
- Graceful degradation
- Transaction rollback
-
User-friendly error messages (2h)
- Error templates
- Contextual help
- Suggestions for fixes
-
Error logging (1h)
- Log to file
- Debug information
- Stack traces in debug mode
-
Tests (1h)
Deliverables:
- ✅ All error types defined
- ✅ Recovery mechanisms working
- ✅ Error messages clear
Acceptance Criteria:
- All errors properly typed
- Error messages actionable
- Recovery works where possible
- Logging captures all info
Owner: Dev 1 & Dev 2
Priority: P0
Subtasks:
-
Test repository setup (2h)
- Create test repo with configs
- Multiple branches/tags
- Various config types
-
End-to-end test scenarios (6h)
- Full init -> sync workflow
- Update workflow
- Rollback workflow
- Multi-project scenario
- Conflict resolution
- Error scenarios
- Tag filtering
- Namespace isolation
-
CI integration (1h)
- Run integration tests in CI
- Use test repository
-
Test documentation (1h)
Deliverables:
- ✅ Integration test suite passing
- ✅ 80%+ coverage overall
Acceptance Criteria:
- All critical paths tested
- Tests run in CI
- Tests are maintainable
Owner: Dev 1
Priority: P2
Subtasks:
-
Performance benchmarks (2h)
- Sync speed tests
- Memory usage tests
- Large repository tests
-
Performance optimization (2h)
- Profile bottlenecks
- Optimize hot paths
Deliverables:
- ✅ Performance benchmarks
Acceptance Criteria:
- Sync completes in < 5s for 50 configs
- Memory usage reasonable
Owner: Dev 1
Priority: P1
Subtasks:
- ESLint rules refinement (1h)
- Prettier formatting (1h)
- Type coverage check (1h)
- Security audit (1h)
- npm audit
- Check dependencies
- Code review & refactoring (2h)
Deliverables:
- ✅ Clean codebase
- ✅ No linting errors
- ✅ No security vulnerabilities
Owner: Dev 2 or Tech Writer
Priority: P0
Subtasks:
- Getting Started guide (2h)
- Command reference (2h)
- Configuration guide (1h)
- Troubleshooting guide (1h)
- FAQ (1h)
- Examples repository (1h)
Deliverables:
- ✅ Complete user docs
- ✅ Example repository
Acceptance Criteria:
- Docs cover all commands
- Examples are tested
- Clear and beginner-friendly
Owner: Dev 1
Priority: P1
Subtasks:
- Architecture documentation (2h)
- API reference (2h)
- Contributing guide (1h)
- Code comments audit (1h)
Deliverables:
- ✅ Developer docs complete
Owner: Dev 1
Priority: P0
Subtasks:
-
Versioning & changelog (1h)
- Prepare v1.0.0-beta.1
- Write changelog
-
npm package preparation (2h)
- Package.json finalization
- README for npm
- Keywords, description
-
Release automation (1h)
- GitHub release workflow
- npm publish workflow
-
Beta testing (1h)
- Internal testing
- Gather feedback
-
Launch (1h)
- Publish to npm
- GitHub release
- Announcement
Deliverables:
- ✅ v1.0.0-beta.1 released
- ✅ npm package published
- ✅ Documentation live
Acceptance Criteria:
- Package installable via npm
- All docs accessible
- Beta testers can use it
- ✅
oct init- Initialize team configs - ✅
oct sync- Sync configurations - ✅
oct status- Check status & updates - ✅
oct list- List configurations - ✅
oct validate- Validate configs - ✅
oct update- Update to latest - ✅
oct rollback- Rollback version - ✅
oct remove- Remove single config - ✅
oct clean- Clean all team configs - ✅
oct info- Show system info
- ✅ Git operations module
- ✅ File system operations
- ✅ Schema validation
- ✅ Auto-discovery engine
- ✅ Tag filtering system
- ✅ Namespace isolation
- ✅ Error handling
- ✅ Logging system
- ✅ Unit tests (80%+ coverage)
- ✅ Integration tests
- ✅ Performance benchmarks
- ✅ Security audit
- ✅ Code quality (linting, types)
- ✅ User documentation
- ✅ Developer documentation
- ✅ API reference
- ✅ Example repository
- ✅ Troubleshooting guide
- ✅ Beta release published
- ✅ npm package available
- ✅ GitHub repository public
-
Git authentication complexity
- Mitigation: Use standard Git credentials
- Fallback: Clear error messages
-
Namespace conflicts
- Mitigation: Clear precedence rules
- Testing: Extensive conflict scenarios
-
Performance with large repos
- Mitigation: Incremental sync
- Testing: Benchmark with large repos
-
Cross-platform compatibility
- Mitigation: Test on Windows, Mac, Linux
- CI: Multiple OS matrix
-
Validation edge cases
- Mitigation: Comprehensive test cases
- User feedback: Beta testing
- Gather beta user feedback
- Fix critical bugs
- Release v1.0.0 stable
- Start Phase 2 planning
- Multiple team config sources
- Interactive TUI mode
- Config templates
- Enhanced conflict resolution UI
- Plugin system foundation
- Week 1-2: Setup & Infrastructure (40h)
- Week 3-4: Core Commands Part 1 (40h)
- Week 5-6: Core Commands Part 2 (40h)
- Week 7-8: Advanced Features (40h)
- Week 9-10: Testing & Release (40h)
- Total: 200h development + 40h testing/docs = 240h
- 1 Developer Full-Time: 6 weeks (40h/week)
- 1 Developer Part-Time: 10 weeks (24h/week)
- 2 Developers Part-Time: 5-6 weeks (20h/week each)
- ✅ M1: Week 2 - Infrastructure complete
- ✅ M2: Week 4 - Core commands working
- ✅ M3: Week 6 - All commands implemented
- ✅ M4: Week 8 - Advanced features done
- ✅ M5: Week 10 - Beta release