Merge pull request 'adr' (#17) from adr into main

Reviewed-on: #17

adr/README.md

@@ -0,0 +1,33 @@
+
+The adr-folder contains Architecture Decision Records.
+An Architecture Decision Record is a file that contains a decision that should be applied to all new and altered code and systems.
+ADR's can only be added or altered on specific request by the user. Agents should never add or modify ADR's without explicit request to do so. 
+ADR's are immutable in essence. This means that the only modifications allowed are in its state, or when it applies to typo's, adding clarifications, or removing ambiguity. 
+An ADR MUST have the following properties:
+
+- ID
+- Title
+- Supersedes
+- Status (NEW, REFINED, APPROVED, REJECTED, EXPIRED)
+- Expiration date
+- Context
+- Decisions
+- Options considered with pro's and cons
+- Consequences.
+An _ID_ MUST be a unique number, prefixed with ADR (e.g. ADR1, ADR2, ADR3, etc.). This makes it easy to reference an ADR.
+A _title_ is a short, unique description of the ADR. It should make it easy to know in a glance what the ADR is about. 
+The name of the file SHOULD contain the ID and the title, or a short variant of the title, of the ADR.
+_Supersedes_ is an optional property that MAY reference another, expired ADR that it supersedes.
+When _supersedes_ references another ADR, it MUST do so by referencing its ID. 
+When _supersedes_ references another ADR, the status of that other ADR MUST equal to EXPIRED.
+_Status_ contains the state of the ADR. In the readme, when we mention state, we mean the value of this status-property. ADR's are always in a subfolder of the adr-folder, with the same name as the state, but in lowercase ('adr/new' for ADR's with state NEW, 'adr/refined' for ADR's with state REFINED, etc.). 
+Each created ADR will start with the state NEW. Apart from the ID and the state, each property can still be modified. Nothing that is in an ADR with state NEW, should be considered when writing or evaluating anything within the software landscape. 
+An RFD will get the state REFINED, when it is fully worked out. Only RFD's with the state NEW can be changed to REFINED. This means an effort has been made to get to a final version of the RFD. Getting an RFD from NEW to REFINED can be done with or without the help of an agent. However, an agent should always verify mutual understanding of the content with the human owner, before changing the state from NEW to REFINED. 
+An ADR with the state REFINED can be moved to either APPROVED or REJECTED. This step must be done manually, not by any agent. APPROVED means the decision in the ADR applies to all code and/or software added or altered as far as the content of the ADR applies to the situation. Exceptions are possible with explicit accord. Such an accord should be given by a person. REJECTED means that the ADR should not be considered anywhere when writing or evaluating anything within the software landscape.
+An ADR with the state EXPIRED is no longer valid. It should no longer be considered anywhere when writing or evaluating anything within the software landscape, even though it had been the case previously. It MAY have been superseded by a new ADR, but that is not necessary.
+An _expiration date_ indicated from when an ADR should be notified for reevaluation. Reaching the _expiration date_ does not mean the ADR is expired. It only means the ADR should be reevaluated by a person, with or without the help of an agent. As a result of the reevaluation, this ADR may get EXPIRED - only after explicit agreement of a person - and it MAY be superseded by a new one. Another option is that only the expiration date itself gets updated to a new expiration date. This also only after explicit agreement of a person.
+_Context_ should explain the context of the problem where a decision had to be made for. 
+The _decision_ describes the decision. This is what all code MUST apply to, unless an explicit exception is approved by a person.
+The _options_ describes the various alternatives that were considered, all with its pro's and con's, and why the chosen decision whas chosen. 
+_Consequences_ describes the consequences to the current state of the application landscape at the time of writing. This could be about a migration timeline, a new process, different tooling, or a change in the stack, or something else.
+

adr/refined/ADR1_application-size.md

@@ -0,0 +1,215 @@
+**ID:** ADR1 \
+**Title:** Application size \
+**Supersedes:** - \
+**Status:** REFINED \
+**Expiration Date:** Six months after approval; record the calendar date upon manual approval.
+
+## Context
+
+Agile Dancers currently keeps its frontend, backend, CI pipeline, skills,
+specifications, ADRs, and other documentation in one repository. As the application
+grows, humans and agents need more context to understand individual tasks.
+Functional dependencies can become entangled, making changes and reuse harder.
+
+The primary goal is to reduce the context required for a task. Supporting goals
+are preventing uncontrolled coupling and enabling reuse and replacement of
+capabilities. Repository organization, module boundaries, and deployment
+boundaries are separate architectural choices.
+
+Business capabilities stand on their own, while an application system may support
+multiple capabilities. Loosely coupled capability boundaries allow implementations
+to change between custom software, libraries, and externally supplied components.
+Scheduling and school administration are candidate areas to examine; their exact
+system boundaries have not yet been decided.
+
+Code-level modularity alone is insufficient when shared tables, materialized
+views, SQL scripts, or other database access bypass module boundaries. Separate
+services would have the same weakness without enforced data ownership.
+
+Systems can initially run on the same physical server. Independent workload
+placement is nevertheless useful: computational work, such as runners and future
+scheduling calculations, may run on a mini-PC rather than the Synology. Independent
+scaling and release cycles are future possibilities rather than universal current
+requirements. Colocation reduces network exposure but process restarts, timeouts,
+and resource contention still require defined failure behavior.
+
+Reusable engineering resources should also support other projects. Specifications
+can affect several projects, and ADRs apply across the application landscape.
+
+## Decisions
+
+### Capabilities and systems
+
+Organize the landscape into independently deployable systems. Group capabilities
+into systems according to cohesion, data ownership, replacement needs, and
+operational requirements, including workload placement. Capability size alone does
+not justify a separate system.
+
+Each system has its own repository and independent deployment lifecycle. Within a
+system, use modules to keep its capabilities loosely coupled. A capability does
+not automatically require its own service or deployment. Compute workers may be
+deployed separately from the business system that delegates work to them.
+
+Capability contracts should allow implementations to be replaced by custom code,
+libraries, or external products, using adapters where necessary.
+
+### Data ownership
+
+Each system exclusively owns its data. Other systems access that data through
+explicit contracts, never through direct access to its storage. This restriction
+also applies to reporting queries, views, migrations, and maintenance scripts.
+Cross-system reporting requires explicit contracts or a separately owned
+projection.
+
+PostgreSQL-backed systems initially share one PostgreSQL server/container, with
+separate databases or schemas and separate credentials whose permissions enforce
+ownership. Sharing physical infrastructure does not permit sharing storage access.
+Systems may choose other storage technologies when justified. This permits future
+CQRS designs without adopting CQRS through this ADR.
+
+### Contracts and communication
+
+Systems communicate through explicit, versioned contracts. Internal domain models
+and persistence entities remain private to their owning system and are not shared
+through common libraries. Contract definitions and generated clients may be shared.
+
+Choose synchronous APIs or asynchronous messaging for each interaction according
+to its needs. Define failure behavior for each interaction. This ADR mandates
+neither a landscape-wide communication mechanism nor a message broker.
+
+### Landscape and engineering resources
+
+Maintain a landscape repository containing ADRs, specifications, and the capability
+and system map. Specifications identify the projects they affect and may span
+multiple systems. ADRs govern the application landscape according to their scope.
+Each system retains a README describing its implementation and operation.
+
+Maintain reusable engineering resources, including pipeline components, skills,
+and general engineering documentation, separately from the landscape repository
+and individual systems. Group these resources according to maintenance and release
+needs; a separate repository per resource type is not required. Version shared
+resources so consuming projects can adopt updates deliberately.
+
+### Adoption and review
+
+Use this ADR as guidance and the starting point for follow-up specifications.
+Detailed system boundaries, contracts, and migration designs are follow-up work.
+Migrate incrementally, keeping the application working after each extraction.
+
+Perform an initial review six months after approval. Review earlier if contract
+coordination, operational overhead, or persistent cross-system coupling becomes a
+significant burden. The expiration date triggers reevaluation and does not
+automatically invalidate the decision.
+
+## Options considered
+
+### 1. Improve navigation within the current structure
+
+Keep the existing projects and deployment structure, improving focused
+documentation, task guidance, and file organization.
+
+Pros:
+
+- Requires little disruption or migration work.
+- Makes relevant context easier to find.
+- Retains simple local development and coordinated changes.
+
+Cons:
+
+- Offers limited protection against functional entanglement.
+- Does not enforce data ownership or support independent workload placement.
+- Leaves reuse and replacement dependent on existing application boundaries.
+
+Not chosen because navigation improvements alone do not establish the ownership
+and replacement boundaries needed as the landscape grows.
+
+### 2. Modular monolith in one repository
+
+Organize capabilities into modules with explicit interfaces and dependency rules,
+while retaining coordinated deployment and one repository.
+
+Pros:
+
+- Reduces the code area needed to understand a capability.
+- Enables dependency checks and straightforward changes across modules.
+- Keeps deployment and in-process communication simple.
+
+Cons:
+
+- Shared database access can bypass code-level boundaries through tables, views,
+  and scripts unless storage ownership is separately enforced.
+- Workload placement and deployment remain coupled.
+- Independent replacement and reuse may require later extraction.
+
+Not chosen as the landscape-wide approach because independently enforced ownership
+and deployment boundaries are desired. Modular design remains part of the chosen
+approach inside each system.
+
+### 3. Separate projects and repositories with coordinated deployment
+
+Extract capabilities into separately built libraries or applications with
+versioned contracts, while retaining a coordinated deployment lifecycle.
+
+Pros:
+
+- Separates source and build context.
+- Gives reusable components their own versioned releases.
+- Retains a coordinated operational release process.
+
+Cons:
+
+- Changes spanning repositories require dependency release coordination.
+- Deployment remains coupled despite repository separation.
+- Repository separation alone does not enforce storage ownership or runtime
+  independence.
+
+Not chosen because it incurs repository coordination costs while retaining a
+deployment constraint that would limit workload placement and replacement.
+
+### 4. Independently deployable systems with internal capability modules — chosen
+
+Give systems their own repositories, deployment lifecycles, contracts, and enforced
+data ownership. Keep capabilities loosely coupled through modules within a system.
+Place compute workers independently where useful.
+
+Pros:
+
+- Supports focused development context and independent system evolution.
+- Enforces data ownership beyond code dependency rules through storage permissions.
+- Allows workloads to move between the Synology and mini-PC.
+- Supports capability replacement and reuse through explicit contracts.
+- Allows storage technology choices per system.
+
+Cons:
+
+- Requires contract compatibility and coordination for changes spanning systems.
+- Adds deployment, configuration, and operational maintenance for multiple processes.
+- Requires explicit failure handling and cross-system consistency decisions.
+- Sharing one server or PostgreSQL instance retains common infrastructure failure
+  points despite logical isolation.
+
+Chosen because ownership, replaceability, focused context, and independent workload
+placement outweigh the additional operational and contract coordination work.
+
+## Consequences
+
+- Write follow-up specifications to map capabilities and dependencies, choose
+  initial system boundaries, define contracts and data ownership, and plan
+  extraction. This ADR does not itself settle those boundaries or implement them.
+- Establish the landscape repository and the repositories and versioning needed
+  for reusable engineering resources. Preserve links between specifications and
+  affected projects, and between system READMEs and landscape guidance.
+- Extract systems one at a time, establishing contracts and enforcing storage
+  ownership as part of each extraction. Moving tables into separate schemas is
+  insufficient while cross-system SQL access remains possible.
+- Adapt build and deployment pipelines to release systems independently and
+  consume versioned shared engineering resources.
+- Add appropriate checks for module dependencies, contract compatibility, and
+  storage isolation. Include views and scripts in boundary enforcement.
+- Specify how systems exchange information, handle failed interactions, and keep
+  derived information consistent. These choices belong to the relevant follow-up
+  specifications rather than a universal messaging requirement.
+- Keep one PostgreSQL container initially. Detailed backup and failover design is
+  future work; logical data separation does not provide infrastructure failover.
+- Record the calendar review date when a maintainer manually approves this ADR.
+  REFINED records the agreed proposal; approval remains a separate manual step.

adr/refined/ADR2_http-api-contracts-and-tooling.md

@@ -0,0 +1,176 @@
+**ID:** ADR2 \
+**Title:** HTTP API contracts and tooling \
+**Supersedes:** - \
+**Status:** REFINED \
+**Expiration Date:** Six months after approval; record the calendar date upon manual approval.
+
+## Context
+
+Agile Dancers currently uses REST without an explicit architectural decision.
+The landscape needs agreed defaults for communication across system boundaries,
+contract documentation, client generation, compatibility, and error handling.
+
+Interactions include frontend access, requests between business systems,
+delegation of long-running calculations to workers, change notifications, and
+external consumers. Most clients and servers are developed by the same maintainer.
+Consumers must nevertheless be able to upgrade independently. The independently
+deployable systems proposed in ADR1 are relevant context; ADR1 remains REFINED
+and is not approved through this decision.
+
+The current frontend uses Angular, but future clients may use other frameworks
+or languages. Contracts and tooling should support that flexibility.
+
+For now, interactions use a defined alternative path when another system is
+offline. Durable queued delivery is not a current requirement. More specialized
+communication mechanisms may become appropriate for particular interactions.
+
+## Decisions
+
+### Scope and communication style
+
+Use HTTP APIs with JSON payloads as the default across system boundaries.
+Use resource-oriented endpoints where natural and action-oriented endpoints
+where they express business intent more clearly. Do not force business actions
+into CRUD operations. For example:
+
+```text
+GET  /api/v1/schedules/{id}
+POST /api/v1/schedules/{id}/calculate
+```
+
+Action endpoints still follow HTTP method and status semantics. For long-running
+work, use an explicit job or operation resource with a status endpoint when the
+caller needs to track progress. A notification can initially use a direct HTTP
+request with documented failure behavior; this does not promise durable delivery.
+
+These are landscape defaults. Document justified exceptions alongside the
+relevant interface, including the reason and the alternative contract and failure
+behavior. This ADR does not mandate GraphQL, RPC, or messaging infrastructure.
+
+### Contracts and documentation
+
+Describe HTTP APIs using OpenAPI. Normally generate the description from server
+code, adding explicit descriptions and annotations where needed. Review the
+resulting contract as a public interface; generation alone does not ensure
+completeness or backward compatibility.
+
+Use self-hosted Scalar API Reference as the default interactive documentation UI.
+Keep the OpenAPI document independently available so consumers and tooling do not
+depend on the UI. Publish a contract artifact for each supported major version.
+
+Choose an OpenAPI specification version supported by the server tooling, Scalar,
+and the selected client generators. Do not automatically adopt the latest version
+without checking that compatibility.
+
+### Client generation
+
+Generate client transport code and contract types from OpenAPI by default, using
+OpenAPI Generator. Select the generator appropriate to the consuming technology;
+use `typescript-angular` for Angular clients. This choice does not require future
+frontends to use Angular.
+
+Pin generator versions and configuration for reproducible generation. Generate
+against a selected contract artifact rather than requiring a running server during
+the client build. Keep generated code separate from handwritten application logic
+and do not manually edit generated files. Generated static types do not by
+themselves provide runtime response validation.
+
+### Versioning and compatibility
+
+Put the major contract version in the URL, such as `/api/v1/schedules`.
+Keep backward-compatible changes within that major version. Introduce a new
+major version for breaking changes. Software release and generated client package
+versions may advance independently of the major contract version.
+
+Allow consumers to upgrade independently. Normally support one contract version;
+during transitions, aim to support two. This is a guideline rather than a hard
+cap: additional versions may coexist when justified. Document supported versions,
+deprecation, and the transition plan, coordinating retirement with affected
+consumers. Check compatibility before releasing contract changes.
+
+### Errors and offline behavior
+
+Standardize API error bodies on RFC 9457 Problem Details using
+`application/problem+json` and appropriate HTTP status codes. Use stable problem
+`type` identifiers for programmatic handling and readable explanations for humans.
+Clients must not depend on parsing human-readable messages. Document expected
+errors in OpenAPI, including validation details where applicable. Do not expose
+internal exception details or sensitive information in error responses.
+
+Define timeouts and the offline alternative path for each interaction. A network
+failure may produce no HTTP response, so consumers must handle that separately
+from a Problem Details response. Avoid automatic retries of actions unless
+repeating them is safe. Do not assume durable delivery or eventual replay.
+
+### Adoption and review
+
+Adopt incrementally for new interfaces and interfaces being substantially changed.
+Migrate existing interfaces through planned work while preserving compatibility
+for existing consumers. No immediate landscape-wide rewrite is required.
+
+Review six months after approval, or earlier if integration needs expose
+limitations. The review date triggers reevaluation rather than automatic expiry.
+
+## Options considered
+
+### Communication approach
+
+| Option | Pros | Cons | Outcome |
+| --- | --- | --- | --- |
+| Resource-oriented HTTP/JSON with action endpoints | Readable resources and business actions; supports different client technologies; retains HTTP semantics. | Requires consistent endpoint conventions and explicit handling of long-running work and failures. | Chosen as the default. |
+| GraphQL | Flexible data selection; typed schema; supports different consumer views of related data. | Adds query authorization and performance concerns; requires additional conventions for work delegation and notifications. | Not chosen: current needs and common client/server ownership do not justify the added complexity. |
+| RPC, including JSON-RPC and gRPC | Explicit operation contracts; JSON-RPC is lightweight; gRPC supports strongly typed generated clients. | Operation-oriented contracts require careful evolution; gRPC adds browser integration requirements. | Not chosen as the default: resource-oriented HTTP with optional actions better matches the desired interface flexibility. RPC remains a possible justified exception. |
+
+### Contract description and authoring
+
+| Option | Pros | Cons | Outcome |
+| --- | --- | --- | --- |
+| OpenAPI, normally generated from server code | Language-independent HTTP contracts; supports documentation and client generation; avoids separately maintaining a design language. | Needs annotations, review, and compatibility checks; generated output can be incomplete. | Chosen. |
+| TypeSpec generating OpenAPI | Dedicated contract authoring language; can generate descriptions and other artifacts. | Adds a language and compiler to maintain. | Not chosen: no current benefit sufficient to justify the additional tooling. |
+| RAML | API description language with reusable modeling constructs. | Its specification repository is archived, creating a maintenance concern for a new standard. | Not chosen. |
+
+### Interactive documentation
+
+| Option | Pros | Cons | Outcome |
+| --- | --- | --- | --- |
+| Scalar API Reference | Readable interactive documentation; integrated request testing; self-hosting and configuration options. | Requires integration and maintenance alongside the server framework. | Chosen: readability and testability are the primary purposes of the UI. |
+| Swagger UI | Interactive requests and authentication support; direct integration with Quarkus OpenAPI tooling. | Its expandable operation layout is less aligned with the preferred reading experience. | Not chosen as the landscape default. |
+
+### Client generation
+
+| Option | Pros | Cons | Outcome |
+| --- | --- | --- | --- |
+| OpenAPI Generator | Supports Angular and other client technologies in one tool family; configurable generation. | Generator-specific options and upgrades need management. | Chosen to support future technology changes. |
+| ng-openapi-gen | Angular-focused generation; npm-based tooling. | Other client technologies require another generator. | Not chosen as the landscape default. |
+| Handwritten clients | Direct control over client code and application integration. | Duplicates contract types and request details; increases drift risk. | Not chosen as the default. |
+
+## Consequences
+
+- Apply the defaults to new and substantially changed interfaces. Plan migration
+  of existing interfaces incrementally, preserving consumer compatibility.
+- Generate and publish versioned OpenAPI artifacts. Add Scalar to provide
+  interactive documentation and request testing for supported contracts.
+- Establish pinned OpenAPI Generator configurations for client technologies,
+  initially Angular. Keep generated code separate from application logic.
+- Add contract validation and compatibility checks to release workflows. Verify
+  generated clients against the actual contract before adopting generator upgrades.
+- Introduce URL major versions and coordinate deprecation with consumers. Normally
+  maintain one version and temporarily two, documenting justified deviations.
+- Align API error responses with Problem Details and document expected failures.
+  Define timeout and offline behavior per interaction, including safe retry rules.
+- Record justified exceptions alongside their interfaces rather than imposing an
+  unsuitable communication mechanism on every interaction.
+- Record the calendar review date upon manual approval. REFINED captures the
+  agreed proposal; approval remains a separate manual step.
+
+### References
+
+- [OpenAPI specification](https://spec.openapis.org/oas/)
+- [Scalar API Reference configuration](https://scalar.com/products/api-references/configuration)
+- [OpenAPI Generator: TypeScript Angular](https://openapi-generator.tech/docs/generators/typescript-angular/)
+- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html)
+- [Swagger UI configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)
+- [TypeSpec overview](https://learn.microsoft.com/en-us/azure/developer/typespec/overview/)
+- [RAML specification repository](https://github.com/raml-org/raml-spec)
+- [JSON-RPC specification](https://www.jsonrpc.org/specification)
+- [ng-openapi-gen](https://github.com/cyclosproject/ng-openapi-gen)

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

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>

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"

skills/code-review/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.

skills/grill-me/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.

skills/grilling/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.