Align JEP process with SpecKit standards and ADR conventions

kirkbrauer · claude · kirkbrauer · commit db7391e33d87 · 2026-04-09T23:05:14.000Z
- Add structured Design Decisions (DD-N) section to JEP template following the ADR pattern used in the project (e.g., ADR-0001 from PR #533) - Add Consequences section (positive/negative/risks) to JEP template - Mark all template sections as mandatory, optional, or conditional - Document the relationship between JEPs and ADRs in JEP-0000 - Add SpecKit and ADR references to Prior Art in JEP-0000 - Add agent instructions and document conventions to jeps/README.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/jeps/JEP-0000-jep-process.md b/jeps/JEP-0000-jep-process.md
@@ -70,6 +70,29 @@ Not every change needs a JEP. Use the following guidelines:
 When in doubt, ask in [Matrix](https://matrix.to/#/#jumpstarter:matrix.org) or
 open a GitHub issue to gauge whether your idea warrants a JEP.
 
+## JEPs and Architecture Decision Records (ADRs)
+
+The project uses both JEPs and Architecture Decision Records (ADRs). They serve
+different purposes and operate at different scopes:
+
+| Aspect        | JEP                                        | ADR                                               |
+|---------------|--------------------------------------------|----------------------------------------------------|
+| **Scope**     | Cross-cutting changes to the project       | Scoped to a single component or driver              |
+| **Process**   | Requires community review and maintainer approval | Included with the implementation PR                |
+| **When**      | Before implementation begins               | Alongside or within an implementation PR            |
+| **Location**  | `jeps/` directory                          | `python/docs/source/contributing/adr/` directory    |
+| **Example**   | New lease scheduling strategy              | Choice of telnet vs pyrenode3 for Renode driver     |
+
+**Use a JEP** when the change affects multiple components, changes public APIs or
+protocols, or requires community consensus. **Use an ADR** when you are making a
+significant technical decision within a self-contained piece of work (e.g., a new
+driver) that does not need project-wide review but should be documented for
+posterity.
+
+JEPs borrow the structured decision format from ADRs: each design decision in a
+JEP should document alternatives considered and rationale, following the `DD-N`
+pattern in the [JEP template](JEP-NNNN-template.md).
+
 ## JEP Types
 
 | Type               | Description                                                                                            |
@@ -209,6 +232,13 @@ This process draws inspiration from:
   test plan requirements, graduation criteria, production readiness.
 - [Rust RFCs](https://github.com/rust-lang/rfcs) — PR-based workflow, emphasis
   on motivation and teaching, prior art section.
+- [Architecture Decision Records (ADRs)](https://adr.github.io/) — structured
+  decision documentation with context, alternatives, and consequences. The JEP
+  template adopts the ADR pattern for individual design decisions.
+- [GitHub SpecKit](https://github.com/github/spec-kit) — spec-driven development
+  methodology with structured templates and agent-friendly document conventions.
+  The JEP template adopts SpecKit's practice of marking sections as mandatory or
+  optional and structuring documents for machine readability.
 
 ## Copyright
 
diff --git a/jeps/JEP-NNNN-template.md b/jeps/JEP-NNNN-template.md
@@ -10,6 +10,10 @@
   - Hardware-related proposals must address the Hardware Considerations section.
   - Protocol/API changes must include backward compatibility analysis.
   - Write as if teaching the feature to a new Jumpstarter contributor.
+  - Each design decision should document alternatives considered and rationale
+    (following the ADR pattern used in the project).
+  - Sections marked (mandatory) must be filled in. Sections marked (optional)
+    may be omitted if not applicable.
 -->
 
 | Field              | Value                                      |
@@ -28,14 +32,14 @@
 
 ---
 
-## Abstract
+## Abstract *(mandatory)*
 
 <!--
   One paragraph (3-5 sentences) summarizing the proposal. A reader should be
   able to decide whether this JEP is relevant to them from the abstract alone.
 -->
 
-## Motivation
+## Motivation *(mandatory)*
 
 <!--
   Why is this change needed? What problem does it solve? Who benefits?
@@ -48,7 +52,7 @@
   Do not describe the solution here — that belongs in the Proposal section.
 -->
 
-### User Stories (Optional)
+### User Stories *(optional)*
 
 <!--
   Describe 2-3 concrete scenarios from the perspective of a Jumpstarter user.
@@ -59,7 +63,7 @@
     specific device is offline.
 -->
 
-## Proposal
+## Proposal *(mandatory)*
 
 <!--
   Explain the proposal as if it were already implemented and you are teaching
@@ -76,7 +80,7 @@
   someone could begin implementation from it.
 -->
 
-### API / Protocol Changes (if applicable)
+### API / Protocol Changes *(if applicable)*
 
 <!--
   If this JEP modifies gRPC .proto definitions, operator CRDs, driver
@@ -87,7 +91,7 @@
   - For breaking changes, describe the migration path.
 -->
 
-### Hardware Considerations (if applicable)
+### Hardware Considerations *(if applicable)*
 
 <!--
   Jumpstarter operates at the hardware-software boundary. If this proposal
@@ -101,7 +105,38 @@
   - Are there power/thermal/physical safety implications?
 -->
 
-## Design Details
+## Design Decisions *(mandatory for Standards Track)*
+
+<!--
+  Document each significant design decision using the pattern below.
+  This follows the Architecture Decision Record (ADR) convention used
+  elsewhere in the project (see python/docs/source/contributing/adr/).
+
+  For each decision, state what was decided, what alternatives were
+  considered, and why the chosen approach was preferred. This section
+  is the most important part of the JEP for long-term project memory —
+  future contributors will refer to it to understand *why* things are
+  the way they are.
+-->
+
+### DD-1: *Decision title*
+
+**Alternatives considered:**
+
+1. **Option A** — Brief description.
+2. **Option B** — Brief description.
+
+**Decision:** Option A.
+
+**Rationale:** Explain why this option was chosen over the alternatives.
+Reference specific project constraints, prior art, or technical tradeoffs.
+
+<!--
+  Add more DD-N subsections as needed. Each decision should be
+  independently understandable.
+-->
+
+## Design Details *(mandatory for Standards Track)*
 
 <!--
   The technical heart of the JEP. Cover:
@@ -116,7 +151,7 @@
   interactions.
 -->
 
-## Test Plan
+## Test Plan *(mandatory for Standards Track)*
 
 <!--
   How will this feature be tested? Jumpstarter's HiL nature means pure unit
@@ -137,7 +172,7 @@
   the implementation?
 -->
 
-## Graduation Criteria (Optional)
+## Graduation Criteria *(optional)*
 
 <!--
   For features that should be introduced incrementally (e.g., behind a
@@ -152,7 +187,7 @@
   - How long should the feature be in experimental before promotion?
 -->
 
-## Backward Compatibility
+## Backward Compatibility *(mandatory for Standards Track)*
 
 <!--
   - Does this change break existing users, drivers, exporters, or deployments?
@@ -162,7 +197,31 @@
   - For protocol changes: is the wire format backward compatible?
 -->
 
-## Rejected Alternatives
+## Consequences *(mandatory)*
+
+<!--
+  Summarize the expected outcomes of this proposal, following ADR convention.
+-->
+
+### Positive
+
+<!--
+  What benefits does this proposal deliver? Be specific.
+-->
+
+### Negative
+
+<!--
+  What downsides or costs does this proposal introduce? Be honest.
+-->
+
+### Risks *(optional)*
+
+<!--
+  What could go wrong? What assumptions might prove incorrect?
+-->
+
+## Rejected Alternatives *(mandatory)*
 
 <!--
   What other designs were considered? Why were they not chosen?
@@ -171,9 +230,15 @@
   explored and helps future contributors understand why the chosen approach
   was preferred. Include brief descriptions of alternatives and the reasons
   they were rejected.
+
+  Note: If you used the Design Decisions section above with alternatives
+  for each decision, you may keep this section brief and refer back to
+  those decisions. Use this section for higher-level alternatives that
+  don't fit into individual design decisions (e.g., "we considered not
+  doing this at all").
 -->
 
-## Prior Art (Optional)
+## Prior Art *(optional)*
 
 <!--
   Are similar features present in other HiL frameworks, testing tools, or
@@ -186,15 +251,15 @@
   - Remote access solutions (if relevant)
 -->
 
-## Unresolved Questions
+## Unresolved Questions *(optional)*
 
 <!--
   What aspects of the design are still open? List specific questions that
   should be resolved during the JEP review process. Questions that can wait
   until implementation should be noted as such.
 -->
 
-## Future Possibilities (Optional)
+## Future Possibilities *(optional)*
 
 <!--
   What natural extensions or follow-up work does this proposal enable? This
diff --git a/jeps/README.md b/jeps/README.md
@@ -42,6 +42,14 @@ For the full process definition, see [JEP-0000](JEP-0000-jep-process.md).
 |------|-------|--------|-----------|
 | *none yet* | | | |
 
+## Related: Architecture Decision Records (ADRs)
+
+For technical decisions scoped to a single component or driver (e.g., choosing a
+control interface for a new driver), use an Architecture Decision Record instead
+of a JEP. ADRs live in `python/docs/source/contributing/adr/` and are submitted
+alongside the implementation PR. See [JEP-0000](JEP-0000-jep-process.md) for
+guidance on when to use a JEP vs an ADR.
+
 ## Status Key
 
 | Status         | Meaning                                              |
@@ -56,3 +64,50 @@ For the full process definition, see [JEP-0000](JEP-0000-jep-process.md).
 | Deferred       | Sound but not a current priority                     |
 | Withdrawn      | Author voluntarily withdrew                          |
 | Superseded     | Replaced by a newer JEP                             |
+
+## For AI Agents
+
+This section provides conventions for AI agents working with JEPs.
+
+### Document structure
+
+JEP files are Markdown documents with a metadata table at the top. The metadata
+table uses pipe-delimited rows with bold field names. Required fields:
+`JEP`, `Title`, `Author(s)`, `Status`, `Type`, `Created`.
+
+### Section markers
+
+Sections in the JEP template are marked `*(mandatory)*`, `*(optional)*`, or
+`*(mandatory for Standards Track)*`. When helping an author draft a JEP, ensure
+all mandatory sections are filled in. Optional sections may be omitted entirely.
+
+### Design Decisions format
+
+Each design decision uses a numbered `DD-N` subsection under `## Design Decisions`
+with the following structure:
+
+```text
+### DD-N: Decision title
+
+**Alternatives considered:**
+
+1. **Option A** — Description.
+2. **Option B** — Description.
+
+**Decision:** Chosen option.
+
+**Rationale:** Why this option was chosen.
+```
+
+This matches the ADR convention used elsewhere in the project (see
+`python/docs/source/contributing/adr/`).
+
+### File naming
+
+JEP files are named `JEP-NNNN-short-title.md` where `NNNN` is the PR number
+(zero-padded to 4 digits). The template file is `JEP-NNNN-template.md`.
+
+### JEP numbering
+
+The JEP number is the pull request number. JEP-0000 through JEP-0009 are
+reserved for process and meta-JEPs.
