SLT.V1.001 – Design extension/plugin system #85
Description
[SLT.V1.001] Design extension/plugin system
Overview
Define a first-class plugin architecture that allows controlled pre/post processing of Shiplog commands while preserving security and upgrade guarantees.
References & Assets
- Figma / Design: N/A
- Product Spec (Notion / Confluence): N/A
- Related Issues / PRs: SLT.V1.002 – Integrate secrets scrubber #86
- Feature Flags / Experiments: N/A
- Other Assets: N/A
User Story
As a platform engineer,
I want a documented extension system for Shiplog hooks,
so that teams can add custom behavior without forking core scripts.
Acceptance Criteria
- Documented plugin lifecycle with clear hook points
- Security and sandboxing guidance published
- Reference implementation demonstrating pre/post mutation
- Tests ensuring plugins cannot escape allowed boundaries
Definition of Done
Plugin system contract documented, reference plugin shipped, and CI coverage added for lifecycle and security guards.
Scope
In-Scope
- Define plugin API and lifecycle events
- Security posture and sandbox contract
- Example plugin + tests
Out-of-Scope
- UI for plugin management
- Remote plugin distribution marketplace
Deliverables
- Est. Lines of Code: ~250
- Est. Blast Radius:
lib/plugins.sh, docs/plugins.md, tests
Implementation Details
High-Level Approach
Introduce plugin loader that discovers scripts in .shiplog/plugins/, enforce contract via helper functions, and document event triggers.
Affected Areas
- lib/plugins.sh
- docs/plugins.md
- tests/helpers
Implementation Steps
- Draft plugin lifecycle diagram and review
- Implement loader with sandbox checks
- Provide sample plugin and tests
- Update docs with contract and guidance
- Wire plugin execution into core commands
Test Plan
Happy Path
- Plugins execute in configured order during run/write flows
Edge Cases
- Plugin failure aborts safely with clear error
- Missing plugin directory is handled gracefully
Failure Cases
- Plugins attempting forbidden operations are rejected
Monitoring & Success Metrics
- CLI logs include plugin execution summary per run
QA Sign-off Matrix
| Environment | Surface (browser / device / API) | Owner | Status | Notes |
|---|---|---|---|---|
| Local Docker | CLI | TBD | Pending | Covered via make test |
Requirements
Hard Requirements
- Plugin scripts must honor sandbox restrictions and documented contract
Soft Requirements
- Provide scaffolding helper for plugin authors
Runtime Requirements
- Works with POSIX shell tooling without additional dependencies
Dependencies & Approvals
- Security review of plugin sandbox
- Documentation review
Production Notes
Priority: 3 / 5
Important foundation for follow-on features and blockers (P2 roadmap item).
Complexity: 4 / 5
Requires careful contract design and security review.
Estimate: 24 - 36 hours
Covers design, implementation, docs, and validation.
Risk & Rollback
- Primary Risks: Plugin API drift; security escape hatches
- Mitigations: Strict contract, automated tests
- Rollback / Kill Switch: Config flag to disable plugin loading
Additional Notes
Unblocks SLT.V1.002 and several Alpha/Beta plugin safety tasks.