S19: consume versioned engineering resources and move landscape documentation

generated/skills/adr-brainstorm/ATTRIBUTION.md

@@ -0,0 +1,24 @@
+# License and attribution
+
+ADR brainstorm is maintained by Wanja Krah and is distributed under the MIT
+License. See [LICENSE.wanjakrah](LICENSE.wanjakrah) for the license covering
+Wanja Krah's original contributions.
+
+The design-tree approach and related interviewing guidance in `SKILL.md` were
+adapted from Matt Pocock's `grilling` skill, invoked by his `grill-me` skill.
+This includes tracking dependent decisions, settling prerequisites before
+asking dependent questions, investigating accessible facts, and leaving
+decisions with the user. The wording and workflow have been adapted for ADR
+brainstorming; this is not an unmodified copy of the upstream skill.
+
+Upstream source:
+- Repository: https://github.com/mattpocock/skills
+- Revision: `59db609eb1e18aaf59b63284d0e52255aff0c63c`
+- Paths: `skills/productivity/grilling` and `skills/productivity/grill-me`
+- License: MIT, copyright (c) 2026 Matt Pocock
+
+Matt Pocock's full copyright and license notice is preserved in
+[LICENSE.mattpocock](LICENSE.mattpocock) for the adapted material. Keep both
+license files with redistributed copies or substantial portions of this skill.
+The two notices preserve attribution under the same MIT terms; they do not
+introduce an additional license restriction or imply upstream endorsement.

generated/skills/adr-brainstorm/LICENSE.mattpocock

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

generated/skills/adr-brainstorm/LICENSE.wanjakrah

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wanja Krah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

generated/skills/adr-brainstorm/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: adr-brainstorm
+description: "Brainstorm with the user about a new ADR. Use when the user wants to stress-test their thinking, or uses any combination of 'adr' and 'brainstorm' in their trigger phrase."
+---
+
+An ADR is an Architecture Decision Record. Such a record contains a decision on the architecture or design for the application landscape the user is maintaining.
+If an ADR-folder exists, read the README.md of that folder to get a full understanding of any specific rules and properties of how the user works with ADR's that might not be listed in this Skill. 
+
+The goal of the ADR is to provide an architectural solution or a design solution for a given context. Therefor, two to four different approaches must be worked out with their pro's and con's, from which the user should select one as their preferred solution. 
+
+Below, the brainstorm session is mapped out in multiple steps. Each step must be completed succesfully, before continuing to the next step. Success means reaching a shared understanding and whatever the step entitles as its success criteria. 
+
+If the user, or the relevant ADR, indicates that an ADR is to supersede another ADR, read that ADR first.
+
+## Explore decisions with the user
+
+### Follow a design tree
+
+Map the architectural question as a design tree: each decision may
+introduce dependent decisions. Track which decisions are agreed,
+open, awaiting factual investigation, or explicitly deferred.
+
+Ask dependent questions only after their prerequisites are settled.
+Revisit earlier decisions when new evidence changes their assumptions,
+and explain which dependent decisions need reconsideration.
+
+Keep the tree within the ADR's agreed scope. Suggest follow-up work
+for independent topics rather than continually expanding the ADR.
+A deferred topic must have a clear boundary and must not leave the
+main decision ambiguous.
+
+Finish when the user has agreed on the architectural decision and its material tradeoffs. Identify remaining implementation questions as follow-up work. Do not leave questions open that could materially change the chosen approach.
+
+### Establish facts before asking for decisions
+
+Finding accessible facts is the agent's responsibility. Inspect relevant
+code, configuration, specifications, ADRs, and authoritative documentation
+before asking the user questions those sources can answer.
+
+Distinguish observed facts, assumptions, recommendations, and decisions.
+Cite sources for material factual claims and explain uncertainty where
+evidence is unavailable or conflicting. Ask the user for requirements,
+priorities, constraints, and knowledge unavailable from accessible sources.
+
+Evaluate alternatives against the agreed requirements. Present credible
+alternatives fairly, including drawbacks of the recommended approach.
+Do not infer that an option is unsuitable merely because the current
+implementation uses something else.
+
+### Keep the conversation collaborative
+
+Use short rounds, usually one main question or a few closely related
+questions. Number questions when asking more than one. Do not ask every
+available question at once if that would hinder discussion.
+
+For decision questions, normally provide a recommended answer and its
+reason. Where natural, phrase the question so "yes" clearly accepts that
+recommendation. Make its scope explicit; avoid combining independent
+decisions into one yes/no question.
+
+Use open questions when discovering requirements or when a recommendation
+would prematurely narrow the discussion. Allow disagreement, alternatives,
+and back-and-forth exploration before seeking a decision.
+
+### Leave architectural decisions with the user
+
+The agent investigates, explains tradeoffs, challenges assumptions, and
+recommends. The user selects the architectural approach and accepts its
+material tradeoffs.
+
+Do not treat silence, a factual answer, or agreement on one decision as
+approval of other decisions. Preserve earlier agreements without repeatedly
+requesting confirmation unless their meaning or supporting facts change.
+
+At meaningful milestones, summarize the agreed decisions and remaining
+questions. Before finalizing the ADR, confirm shared understanding of the
+complete proposal. Keep recommendations and unresolved assumptions out of
+the Decisions section until the user accepts them.
+
+### Guide the process through steps
+
+Coöperate with the user via the following steps. Communicate each step in which step you are, and what the step entails. Use the template adr-template.md as a template for the final ADR. 
+
+The _first step_ is to get to a shared understanding of the probived context and the problem area the user is in need for a decision. Success for step one means you can describe the context in one to fifty sentences.
+
+The _second step_ is to get to two to four different architectural solutions or design solutions for the described context. Every solution needs a short description of one to fifty sentences and a list of one to ten pro's and one to ten con's. allow discussion of consequences when they affect the choice. Record them formally in _step four_, but don’t postpone discovering migration costs or operational burdens until after selecting an option.
+Success for step two means there are more than one credible solutions with a set of relevant pro's and con's by which a user is able to choose, or not choose that solution for the next step.
+
+The _third step_ is to pick the best solution. Ths user must decide what solution he prefers. The choosen solution will be presented as the ADR decision. A decision may branch into a small tree of related decisions, small meaning one to five levels deep. Make the architectural decision, its scope, and its material tradeoffs unambiguous; record remaining implementation questions as follow-up work. Success of step three means there is a shared understanding of the choosen solution and what it entails.
+
+The _fourth step_ is to make clear what the consequences will be for the application landscape. Success of step four means there is a clear understanding of the changes that should be made to software landscape and the way futurue work should be implemented. 
+
+The _fifth step_ is fill out the other properties of the ADR that is required by the template. Succes of step five means the ID of the ADR is unique, the title is short and comprehandible, and gives the user an overall idea of what the ADR is about. If the ADR supersedes another ADR, that is listed as well.
+Set the Expiration Date of when the ADR should be reviewd. This should be a relative date, to be made absolute by the user as soon as the user moves the ADR to APPROVED.
+Finally, set the status to REFINED. It's up to the user to set the Status to either APPROVED - meaning the ADR is accepted and to be applied for all future work - or REJECTED - meaning the ADR is not accepted and should not be taken in consideration. 
+
+When updating the ADR with the result of the brainstorm, make it both easy to glanse through, as to read in full, meaning:
+- stick to the template
+- keep to the formatting as is custom for markdown-files
+- high use of headers and sub-headers
+- high use of bullit points, lists, and tables where applicable
+- keep sentences short and precise where possible
+- create images with ASCII-art where possible

generated/skills/adr-brainstorm/adr-template.md

@@ -0,0 +1,20 @@
+**ID:** <insert ADR followed by a unique number> \
+**Title:** <insert short and descriptive title> \
+**Supersedes:** - \
+**Status:** NEW \
+**Expiration Date:** to be determined 
+
+## Context
+To be determined
+
+## Decisions
+To be determined
+
+## Options considered
+To be determined
+
+## Consequences
+To be determined
+
+## References
+<insert a list of references consulted, along with a timestamp of when it was consulted>

generated/skills/adr-brainstorm/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "ADR Brainstorm"
+  short_description: "Brainstorm with the user on an ADR to get it from NEW to REFINED"