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:

# 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:

   # 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:

   # Generate implementation plan
   # Use /speckit.plan command
   

4. Generate tasks:

   # 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

# 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.