Architectural Decisions
This folder contains the Architectural Decision Records (ADRs) for DevWorkWire. An ADR captures a significant architectural decision, the context that led to it, and the consequences.
Decision Log
One row per ADR. Use sequential IDs (
ADR-001,ADR-002, …) and file namesadr-XXX-short-slug.md. Statuses follow the lifecycle:Proposed → Accepted → (Superseded by ADR-xxx | Deprecated).
| ADR ID | Title | Status |
|---|---|---|
| ADR-001 | Hexagonal Architecture with Vertical Feature Slices | Proposed |
| ADR-002 | Python 3.11+ Runtime, Typer CLI, and Supported Platforms | Proposed |
| ADR-003 | Jira Access via Direct REST v3 over httpx | Proposed |
| ADR-004 | MCP Server on stdio with a Preview-Handle Confirm Gate | Superseded by ADR-011 |
| ADR-005 | Local SQLite State Store as a Rebuildable Cache | Deferred |
| ADR-006 | Per-Project YAML Config with an Environment-Variable Secret | Proposed |
| ADR-007 | Hatchling Packaging with PyPI/pipx/Homebrew Distribution and Trusted Publishing | Proposed |
| ADR-008 | Quality and Security Toolchain on GitHub Actions | Proposed |
| ADR-009 | No Telemetry — Local Diagnosability Only | Proposed |
| ADR-010 | Two-Branch Fork-Based Workflow with CI as the Merge Gate | Proposed |
| ADR-011 | CLI-First AI Agent Integration | Accepted |
ADR-011 is the active AI integration decision. ADR-004 is superseded and ADR-005 is deferred. The remaining earlier ADRs are proposals; their implementation status must be checked against the current CLI before treating them as shipped.
Recommended Decision Areas
Not every project needs all of these, but significant choices in these areas should each get an ADR. Use as a checklist during Phase 0 / early MVP:
- High-level architecture pattern (monolith, modular monolith, microservices) — ADR-001
- Backend framework and language — ADR-002
- Frontend framework and language — not applicable, no browser UI
- Database choice — ADR-005
- Authentication and authorization strategy — ADR-006 (outbound credentials), ADR-011 (agent task approval)
- Deployment platform — ADR-007 (distribution, not hosting)
- ORM / data access choice — not applicable, stdlib
sqlite3with no ORM (ADR-005) - Build tooling — ADR-007
- Monitoring and observability — ADR-009
- Testing framework strategy — ADR-008
- Secrets management — ADR-006
- Containerization strategy — not applicable, no containers
- Infrastructure as Code strategy — not applicable, no infrastructure to provision
- Environment strategy (local / CI / dev / staging / prod) — ADR-007 (local, CI, TestPyPI, PyPI)
- Code quality tooling (linters, formatters, type checkers) — ADR-008
- Git workflow and branch strategy — ADR-010
- Database migration strategy — ADR-005
Every applicable area is covered. The four marked not applicable reflect that DevWorkWire is a locally installed CLI with no browser UI, no server database, no containers, and no infrastructure — see Deployment Architecture.
Open Items Inside Accepted Decisions
These are decisions recorded as made, with a specific value or tension still unresolved. They are tracked here so they are not lost inside the ADR bodies.
| Item | ADR | Needs |
|---|---|---|
Local .devworkwire-import.json contains issue keys and source hashes | ADR-011 | Keep the current resume-file behavior documented and review privacy requirements against it |
| Raise branch protection to 1/2 approvals | ADR-010 | Trigger: a second maintainer joins |
| Mocked adapter tests cannot catch a Jira API contract change | ADR-008 | Manual live-Jira pass on the release checklist |
Creating a New ADR
Use the ADR Template for all new decisions. Continue numbering from
ADR-012.
Related Documents
Last Updated: 2026-09-02