By name: bollydog-framework description: >- Design and build async microservice systems using the bollydog framework. Use when creating a new bollydog project, adding features, or auditing an existing system design.
Bollydog Framework
Async microservice framework built on mode. Commands as executable units, Hub as central dispatcher, Protocols as pluggable data layers.
How to Use This Skill
Two reference documents drive development. Do NOT read them in full — use the indexes below and read by line range (offset/limit).
| Document | Lines | Role |
|---|---|---|
| sop.md | 857 | 8-Phase workflow — what to do, in what order |
| spec.md | 619 | Architecture, API, constraints — how things work |
Rule: Every SOP step must comply with spec.md. Conflicts -> spec.md wins.
sop.md Index
| Section | Lines | Read When |
|---|---|---|
| Overview + Deliverable Map | 11-43 | Starting a project, understanding the flow |
| P0 Scenario Narrative | 44-70 | Writing user stories |
| P1 Domain Boundary | 71-109 | Partitioning bounded contexts |
| P2 Behavior Design | 110-154 | Designing Command/Event/Subscriber |
| P3 Service Responsibility | 155-220 | Protocol composition, lifecycle hooks |
| P4 End-to-End Tracing | 221-268 | Drawing sequence diagrams |
| P5 Interface Contract | 269-337 | Signatures, data models, serialization |
| P6 Behavior Verification (TDD) | 338-451 | Writing tests, test pyramid |
| P7 Walking Skeleton | 452-605 | Building skeleton, TOML config, stubs, run_execute |
| P8 Iterative Delivery | 606-803 | Issue protocol, registry, commit convention |
| Design Audit | 804-820 | Quality gate checklist |
| Test Pyramid | 821-844 | Layer 1-4 test structure |
| Quick Reference | 845-857 | Phase summary table |
spec.md Index
| Section | Lines | Read When |
|---|---|---|
| Architecture Overview | 10-36 | Understanding system structure (Bootstrap, Hub, ExecuteService) |
| Quick Start | 37-68 | First-time setup |
| Dispatch Pipeline | 69-103 | Two modes, CommandRunnerMixin, Hub vs ExecuteService |
| Command Patterns (4 types) | 105-174 | Designing commands |
| Globals (request-scoped) | 176-192 | Using hub/session/apps context vars |
| Destination & Topic | 193-200 | Naming conventions, _derive |
| Exchange (pub/sub) | 201-232 | Subscriber/fan-out design |
| Hooks (before/after) | 233-246 | Middleware hooks |
| Session | 247-261 | Session management (get/set/delete/history) |
| AppService Design | 262-286 | Service class design, apps registry |
| Protocol System | 287-374 | Base, ABC, implementations, composites |
| TOML Configuration | 375-471 | Config file structure, parse_config, build_services, Bootstrap |
| CLI | 472-490 | Command-line interface, fuzzy resolve, service vs execute |
| Environment Variables | 491-542 | Env var naming, all variables |
| Design Rules | 543-552 | Hard constraints |
| Testing Strategy | 553-611 | Four-layer model, fixtures, run_hub/run_execute |
| Troubleshooting | 612-619 | Common issues |
Workflow Summary
All development — including the initial build — is issue-driven.
1. Create docs/issues/YYYYMMDD-name/
2. Write stories + design (P0-P5) in issue directory
3. Read REGISTRY -> intersection analysis
4. Maintain Registry Delta in notes.md
5. Write tests (P6) + build skeleton (P7)
6. Update REGISTRY.md, commit with delta trailers
Commit Convention
Merge commits use Conventional Commits header + Git Trailers. REGISTRY.md is a pure current-state snapshot; traceability lives in git history only.
<type>(<scope>): <summary>
Issue: YYYYMMDD-name
Delta: + service FooService domain=x protocol=BarProtocol
Delta: ~ command DoThing dest=x.Foo.DoThing
+add /~modify /-remove- Entity types:
service/command/event/protocol/depends/config - Only on merge commit; search via
git log --grep="Delta.*EntityName"
Hard Constraints
- Command names: imperative verbs; Event names: past tense
destination: three-segmentdomain.ServiceAlias.CommandAlias- Command
__call__params/return: primitive types only - AppService must not dispatch — only Commands dispatch
- Protocol must be replaceable with MemoryProtocol for testing
moduleis a framework-reserved TOML key- Layer 1-3 tests: no Hub; Layer 4:
run_huborrun_executefixture - CLI command is
service(notserve); entrypoints toggled by env vars
Deliverables
docs/
├── REGISTRY.md <- Pure current-state snapshot (no history columns)
└── issues/
└── YYYYMMDD-name/
├── stories.md <- P0-P3
├── sequence.md <- P4
├── interfaces.md <- P5
└── notes.md <- intersection + decisions + registry delta
tests/
└── test_*.py <- P6: four-layer tests