ops-jrz1/docs/spec-kit-integration.md

# Spec-Kit Integration for ops-jrz1

**Purpose:** How to use the spec-kit framework for structured feature development

## What is Spec-Kit?

Spec-kit is a feature development framework that provides structured planning and execution. It's designed to:
- Force clear thinking before coding
- Document decisions and rationale
- Create actionable task lists
- Provide quality checklists
- Track progress systematically

## Current Spec-Kit Usage

**Existing Feature:**
- `specs/001-extract-matrix-platform/` - The feature that established this platform

**Structure:**
```
specs/001-extract-matrix-platform/
├── spec.md           # What we're building and why
├── plan.md           # How we'll build it
├── tasks.md          # Specific actionable tasks
├── analysis.md       # Technical analysis and decisions
├── research.md       # Background research
├── data-model.md     # Data structures and schemas
├── quickstart.md     # Quick reference guide
├── checklists/       # Validation checklists
└── contracts/        # Interface contracts
```

## Using Spec-Kit for New Features

### When to Create a Spec

**✅ Good candidates for spec-kit:**
- Complex features with multiple components (e.g., Slack bridge integration)
- Features that affect architecture or patterns
- Features requiring team coordination
- Features with unclear requirements

**❌ Not worth spec-kit overhead:**
- Bug fixes
- Minor config changes
- Documentation updates
- Quick experiments

### Workflow

1. **Create spec:** `/speckit.specify` - Describe what you want to build
2. **Plan implementation:** `/speckit.plan` - Break down into design steps
3. **Generate tasks:** `/speckit.tasks` - Create actionable task list
4. **Implement:** `/speckit.implement` - Execute tasks systematically
5. **Validate:** Use checklists to verify completion

## Recommended: Slack Bridge Feature Spec

Given our north star goal (Milestone 1: Working Slack Bridge), this is a **perfect candidate** for spec-kit.

### Why Use Spec-Kit for Slack Bridge?

**Complexity factors:**
- Requires external service integration (Slack API)
- Needs secrets management coordination
- Involves debugging unknown exit code 11
- Has architectural implications (bridge pattern for future features)
- Requires documentation for team onboarding

**Benefits:**
- Clear specification prevents scope creep
- Plan documents decision rationale
- Tasks provide clear progress tracking
- Checklists ensure quality (security, testing, docs)
- Future engineers can understand the design

### Proposed Feature: `002-slack-bridge-integration`

**Spec outline:**
```markdown
# Feature: Matrix-Slack Bridge Integration

## Goal
Enable bidirectional communication between Slack (chochacho workspace)
and Matrix homeserver to unify team communication.

## Background
- Team currently uses Slack as primary communication
- Matrix homeserver operational on clarun.xyz
- mautrix-slack module exists but exits with code 11
- Existing Slack bot needs reauthorization with updated scopes
- Need Socket Mode for reliable connection

## Success Criteria
- Send message in Slack → appears in Matrix
- Send message in Matrix → appears in Slack
- Bridge survives server restart
- Clear documentation for adding/removing channels
- Secrets properly managed via sops-nix

## Non-Goals
- WhatsApp bridge (future)
- Google Messages bridge (future)
- Multi-workspace support (future)
```

## Next Steps

1. **Start the spec process:**
   ```bash
   # Create new feature spec
   # Use /speckit.specify command or create directory manually
   mkdir -p specs/002-slack-bridge-integration
   ```

2. **Write initial spec.md:**
   - What: Slack bridge integration
   - Why: Team communication unification
   - Success criteria: Bidirectional messaging
   - Constraints: Socket Mode, sops-nix secrets

3. **Run planning:**
   ```bash
   # Generate implementation plan
   # Use /speckit.plan command
   ```

4. **Generate tasks:**
   ```bash
   # Create actionable task list
   # Use /speckit.tasks command
   ```

5. **Execute systematically:**
   - Work through tasks in order
   - Document blockers and decisions
   - Update worklog as you go

## Important Context: Existing Slack Bot

**Key Information from User:**
> "We have access to a bot, we need to have a manager reauthorize
> the bot because we need to change something or other, redo the
> scopes maybe, change it to socket based"

**Action Items:**
1. Identify existing Slack bot name/app
2. Document current scopes/permissions
3. Determine required scopes for mautrix-slack bridge
4. Request manager to reauthorize with new scopes
5. Enable Socket Mode in Slack app settings
6. Extract bot token and app token for sops-nix

**Socket Mode Benefits:**
- No public webhook URL needed
- More reliable than polling
- Better for localhost-based bridges
- Recommended by mautrix-slack documentation

## Coordination with Platform Vision

The Slack bridge spec should reference and align with:
- `docs/platform-vision.md` - Overall platform goals
- Milestone 1: Working Slack Bridge
- Architecture Principles → Communication Layer

## Checklist Template for Bridge Features

```markdown
# Bridge Integration Checklist

## Configuration
- [ ] External service credentials obtained
- [ ] Secrets added to sops-nix
- [ ] NixOS module configuration updated
- [ ] Database schema initialized

## Testing
- [ ] Service starts without errors
- [ ] Bidirectional messaging works
- [ ] Bridge survives restart
- [ ] Error handling tested

## Documentation
- [ ] Setup documented in worklog
- [ ] Credentials management documented
- [ ] Troubleshooting guide created
- [ ] Architecture diagram updated

## Security
- [ ] Secrets encrypted and committed
- [ ] Permissions scoped appropriately
- [ ] Network isolation verified
- [ ] Audit logging enabled
```

## Questions to Answer in Spec

When creating `002-slack-bridge-integration`, make sure to address:

1. **Scope:** Which channels to bridge? (all, specific list, on-demand)
2. **Identity:** How to map Slack users to Matrix users?
3. **Permissions:** Who can manage bridge? (admin-only vs engineer-accessible)
4. **Failure Modes:** What happens if Slack is down? Bridge crashes?
5. **Monitoring:** How to know if bridge is healthy?
6. **Scaling:** Future multi-workspace support?

## Integration with Worklogs

**Relationship:**
- Spec-kit specs are **planning documents** (what and how)
- Worklogs are **execution records** (what happened and why)

**Workflow:**
1. Create spec for the feature (e.g., `002-slack-bridge-integration`)
2. Work on implementation
3. Write worklogs documenting sessions (e.g., `2025-10-23-slack-bridge-setup.org`)
4. Update spec with learnings (if design changes)

**Cross-references:**
- Specs should link to worklogs for implementation details
- Worklogs should reference specs for context
- Platform vision should reference both

## Conclusion

For the Slack bridge work (Milestone 1 of our platform vision), I recommend:

**✅ Use spec-kit:** Create `specs/002-slack-bridge-integration/`
- Complex enough to warrant structured planning
- Clear bounded feature
- Important architectural precedent
- Needs team coordination

**Next Command:** `/speckit.specify` to start the spec process

This will ensure we build it right, document decisions, and make it easy for future engineers to understand and extend.