From dd8f0ce186886b041b5fd625483636b042b1024f Mon Sep 17 00:00:00 2001 From: Wanja Krah Date: Tue, 10 Nov 2026 09:09:44 +0100 Subject: [PATCH] S19: own shared agent workflows and document multi-project runner onboarding --- AGENTS.md | 11 ++- README.md | 4 +- S19-classification.md | 38 +++++---- SOURCE.md | 4 + onboarding.md | 16 +++- skills/README.md | 36 ++++++++ skills/adr-brainstorm/ATTRIBUTION.md | 24 ++++++ skills/adr-brainstorm/LICENSE.mattpocock | 21 +++++ skills/adr-brainstorm/LICENSE.wanjakrah | 21 +++++ skills/adr-brainstorm/SKILL.md | 103 +++++++++++++++++++++++ skills/adr-brainstorm/adr-template.md | 20 +++++ skills/adr-brainstorm/agents/openai.yaml | 3 + skills/code-review/LICENSE.mattpocock | 21 +++++ skills/code-review/SKILL.md | 89 ++++++++++++++++++++ skills/code-review/agents/openai.yaml | 3 + skills/grill-me/LICENSE.mattpocock | 21 +++++ skills/grill-me/SKILL.md | 7 ++ skills/grill-me/agents/openai.yaml | 5 ++ skills/grilling/LICENSE.mattpocock | 21 +++++ skills/grilling/SKILL.md | 30 +++++++ skills/grilling/agents/openai.yaml | 3 + skills/upstream.json | 14 +++ specs/S19-validation.md | 14 +++ specs/S19.md | 3 +- specs/in_review/S19_multi-project | 19 ++++- systems.md | 14 ++- 26 files changed, 536 insertions(+), 29 deletions(-) create mode 100644 skills/README.md create mode 100644 skills/adr-brainstorm/ATTRIBUTION.md create mode 100644 skills/adr-brainstorm/LICENSE.mattpocock create mode 100644 skills/adr-brainstorm/LICENSE.wanjakrah create mode 100644 skills/adr-brainstorm/SKILL.md create mode 100644 skills/adr-brainstorm/adr-template.md create mode 100644 skills/adr-brainstorm/agents/openai.yaml create mode 100644 skills/code-review/LICENSE.mattpocock create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/code-review/agents/openai.yaml create mode 100644 skills/grill-me/LICENSE.mattpocock create mode 100644 skills/grill-me/SKILL.md create mode 100644 skills/grill-me/agents/openai.yaml create mode 100644 skills/grilling/LICENSE.mattpocock create mode 100644 skills/grilling/SKILL.md create mode 100644 skills/grilling/agents/openai.yaml create mode 100644 skills/upstream.json diff --git a/AGENTS.md b/AGENTS.md index 3c42977..cc9e14c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,12 @@ - Each specification identifies affected repositories; maintain systems.md when responsibilities or ownership boundaries change. - Implementation, runtime configuration and validation evidence belong to their - application repositories. Reusable engineering resources belong to engineering. -- Engineering skills are available in the engineering repository under - resources/skills, or in a consuming project's pinned generated/skills. + application repositories. Reusable build resources belong to engineering. +- Shared agent workflows live in this repository under skills/. Read the requested + skill's SKILL.md before using it. For code reviews use skills/code-review/SKILL.md + with the consuming project's backend-review companion and coding standards. +- Use grill-me only when explicitly requested; read skills/grill-me/SKILL.md and + its dependency skills/grilling/SKILL.md. Installing a skill starts no interview. +- Keep upstream skill files unchanged; preserve skills/upstream.json, attribution + and licenses. Consumers use these landscape workflows across all projects. - Do not infer permission for production deployment from documentation changes. diff --git a/README.md b/README.md index 7dd2a25..7d69b28 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,11 @@ system map for projects maintained under this landscape. - [Specifications](specs/README.md); each identifies affected repositories. - [Capability and system map](systems.md). - [Start a project](onboarding.md). +- [Shared agent skills](skills/README.md). - [S19 resource inventory](S19-classification.md). -Reusable mechanisms, templates, skills and general coding standards belong to +Shared agent skills belong to this repository. Reusable build mechanisms, templates +and general coding standards belong to [engineering](http://192.168.2.28:3000/wanjakrah/engineering), which releases them as versioned packages. Application implementations, deployment configuration, secrets, operational runbooks and validation evidence belong to their own diff --git a/S19-classification.md b/S19-classification.md index cc3e913..08d5de1 100644 --- a/S19-classification.md +++ b/S19-classification.md @@ -1,7 +1,9 @@ # S19 resource classification All source paths are relative to the initial Agile Dancers snapshot recorded in SOURCE.md. -Shared resources also have a generated copy in each consumer. +Shared executable engineering resources have generated copies in consumers. +Shared agent skills moved to landscape/skills/ on 2026-11-10 by maintainer request; +these workflows are referenced directly rather than generated into each application. | Source | Destination | Reason | | --- | --- | --- | @@ -42,23 +44,23 @@ Shared resources also have a generated copy in each consumer. | `docs/s2-validation.md` | `agiledancers/docs/s2-validation.md` | Application configuration, operational instructions, validation evidence or benchmark. | | `docs/s4-validation.md` | `agiledancers/docs/s4-validation.md` | Application configuration, operational instructions, validation evidence or benchmark. | | `docs/s6-validation.md` | `agiledancers/docs/s6-validation.md` | Application configuration, operational instructions, validation evidence or benchmark. | -| `skills/README.md` | `engineering/resources/skills/README.md` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/adr-brainstorm/ATTRIBUTION.md` | `engineering/resources/skills/adr-brainstorm/ATTRIBUTION.md` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/adr-brainstorm/LICENSE.mattpocock` | `engineering/resources/skills/adr-brainstorm/LICENSE.mattpocock` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/adr-brainstorm/LICENSE.wanjakrah` | `engineering/resources/skills/adr-brainstorm/LICENSE.wanjakrah` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/adr-brainstorm/SKILL.md` | `engineering/resources/skills/adr-brainstorm/SKILL.md` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/adr-brainstorm/adr-template.md` | `engineering/resources/skills/adr-brainstorm/adr-template.md` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/adr-brainstorm/agents/openai.yaml` | `engineering/resources/skills/adr-brainstorm/agents/openai.yaml` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/code-review/LICENSE.mattpocock` | `engineering/resources/skills/code-review/LICENSE.mattpocock` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/code-review/SKILL.md` | `engineering/resources/skills/code-review/SKILL.md` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/code-review/agents/openai.yaml` | `engineering/resources/skills/code-review/agents/openai.yaml` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/grill-me/LICENSE.mattpocock` | `engineering/resources/skills/grill-me/LICENSE.mattpocock` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/grill-me/SKILL.md` | `engineering/resources/skills/grill-me/SKILL.md` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/grill-me/agents/openai.yaml` | `engineering/resources/skills/grill-me/agents/openai.yaml` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/grilling/LICENSE.mattpocock` | `engineering/resources/skills/grilling/LICENSE.mattpocock` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/grilling/SKILL.md` | `engineering/resources/skills/grilling/SKILL.md` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/grilling/agents/openai.yaml` | `engineering/resources/skills/grilling/agents/openai.yaml` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | -| `skills/upstream.json` | `engineering/resources/skills/upstream.json` | Reusable mechanism or skill; consumed from pinned generated/ snapshot. | +| `skills/README.md` | `landscape/skills/README.md` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/adr-brainstorm/ATTRIBUTION.md` | `landscape/skills/adr-brainstorm/ATTRIBUTION.md` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/adr-brainstorm/LICENSE.mattpocock` | `landscape/skills/adr-brainstorm/LICENSE.mattpocock` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/adr-brainstorm/LICENSE.wanjakrah` | `landscape/skills/adr-brainstorm/LICENSE.wanjakrah` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/adr-brainstorm/SKILL.md` | `landscape/skills/adr-brainstorm/SKILL.md` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/adr-brainstorm/adr-template.md` | `landscape/skills/adr-brainstorm/adr-template.md` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/adr-brainstorm/agents/openai.yaml` | `landscape/skills/adr-brainstorm/agents/openai.yaml` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/code-review/LICENSE.mattpocock` | `landscape/skills/code-review/LICENSE.mattpocock` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/code-review/SKILL.md` | `landscape/skills/code-review/SKILL.md` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/code-review/agents/openai.yaml` | `landscape/skills/code-review/agents/openai.yaml` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/grill-me/LICENSE.mattpocock` | `landscape/skills/grill-me/LICENSE.mattpocock` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/grill-me/SKILL.md` | `landscape/skills/grill-me/SKILL.md` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/grill-me/agents/openai.yaml` | `landscape/skills/grill-me/agents/openai.yaml` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/grilling/LICENSE.mattpocock` | `landscape/skills/grilling/LICENSE.mattpocock` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/grilling/SKILL.md` | `landscape/skills/grilling/SKILL.md` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/grilling/agents/openai.yaml` | `landscape/skills/grilling/agents/openai.yaml` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | +| `skills/upstream.json` | `landscape/skills/upstream.json` | Shared agent workflow in landscape; upstream attribution and licenses preserved. | | `specs/README.md` | `landscape/specs/README.md` | Requirements and agreed specifications. | | `specs/S10_allow-group-exclusion-for-show` | `landscape/specs/S10_allow-group-exclusion-for-show` | Requirements and agreed specifications. | | `specs/S11_add-season-context-to-groups-and-shows` | `landscape/specs/S11_add-season-context-to-groups-and-shows` | Requirements and agreed specifications. | diff --git a/SOURCE.md b/SOURCE.md index 7e5875d..8d37f3e 100644 --- a/SOURCE.md +++ b/SOURCE.md @@ -6,3 +6,7 @@ Source commit: `bd898e92d22f6c412e671908770f4d89c8ae12bc`. Original history rema Project-specific extraction and generalization are recorded in S19. Upstream licenses and revision records accompany the resources they cover. + +Shared skills moved from engineering/resources/skills at engineering commit +`c25ce11a1bb8bf97f24d5e2b12d98680a9c573ca` on 2026-11-10 by maintainer request. +Upstream SKILL.md files, licenses and revision records are preserved in skills/. diff --git a/onboarding.md b/onboarding.md index 8b0c8d2..1ac1e1a 100644 --- a/onboarding.md +++ b/onboarding.md @@ -4,11 +4,14 @@ its responsibilities to systems.md; identify affected repositories in its specifications. Decide data ownership and deployment boundaries explicitly. 2. Create a Gitea repository under the appropriate owner. Choose visibility - deliberately. Configure Actions and an available host runner with JDK 25, + deliberately. Enable Actions and use the shared host runner labelled `mini-pc`, + registered at user scope for `wanjakrah`, so new repositories of that owner + inherit access without a project-specific runner registration. It needs JDK 25, Maven, Git, Python 3, Docker/Compose and Node/npm when a frontend is selected. 3. Clone [engineering](http://192.168.2.28:3000/wanjakrah/engineering) and check out a released version. Follow its README to run create-project.py with a project - name, destination, backend/frontend/both selection, release tag and runner label. + name, destination, backend/frontend/both selection and release tag. The default + runner label is `mini-pc`; override it only when using another shared runner. 4. Review generated project-owned files, module paths, Compose project and image namespace. Configure deployment targets, readiness and any required dependency services. Keep secrets outside Git. Follow engineering's Gitea setup and @@ -16,12 +19,19 @@ 5. Verify the engineering lock records both tag and full commit. Commit generated/ with the local bootstrap and Maven profile. Confirm a fresh checkout builds and that the bootstrap can reconstruct an absent generated/ directory. -6. Initialize and push the application repository, run its build workflow, and +6. Before the first push, check that `mini-pc` is online and available in the new + repository's Actions settings. Follow engineering's runner verification command; + changing a workflow label alone does not change runner scope. Configure the + project's registry secrets and target platform separately. + Initialize and push the application repository, run its build workflow, and inspect diagnostics. Validate deployment/rollback in an isolated environment before a separate manual production deployment. 7. Keep implementation and operational instructions in the application's README. Link README and AGENTS to this landscape and pinned local engineering guidance. Keep executable tests, fixtures and implementation validation evidence there. +8. Verify that systems.md includes the new repository, responsibilities, data + ownership and deployment state. Record frontend technology deviations explicitly, + such as Waterpolo Coaching's Three.js and Vite instead of Angular. For engineering upgrades, choose a released tag, record its commit, follow that release's UPGRADING.md, regenerate and review the diff before committing. Only diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..79c19e5 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,36 @@ +# Landscape skills + +Shared agent workflows for all projects in this landscape. Invoke them explicitly in the +conversation, for example: + +> Gebruik grill-me om de JSON-import en -export met mij uit te werken. + +## Installed skills + +| Skill | Purpose | +| --- | --- | +| [code-review](code-review/SKILL.md) | Review changes against documented coding standards and the originating spec. | +| [grill-me](grill-me/SKILL.md) | Entry point for reviewing a plan or design through questions. | +| [grilling](grilling/SKILL.md) | Interview instructions required by `grill-me`. | +| [adr-brainstorm](adr-brainstorm/SKILL.md) | Develop an architecture decision with the maintainer. | + +The skills are copied from [Matt Pocock's skills.sh listing](https://skills.sh/mattpocock/skills/grill-me) +and its [upstream repository](https://github.com/mattpocock/skills). +The exact upstream revisions and paths are recorded in [upstream.json](upstream.json). +The upstream [MIT license](grill-me/LICENSE.mattpocock) is included with each skill. + +These project-local files are available to the agent from the next conversation +turn through this repository's root `AGENTS.md`. Application and engineering +AGENTS.md files link here and combine these workflows with their own coding +standards and review companions. Skills are not application-specific and are not +installed globally or distributed as generated engineering resources anymore. + +Read the requested SKILL.md before applying it. When working outside this +checkout, use the landscape repository link in the project's AGENTS.md; a sibling +landscape checkout is convenient but is not required. Keep upstream SKILL.md files +unchanged and retain their attribution, licenses and upstream.json when updating. +Use grill-me only when explicitly requested and read its grilling dependency. + +The skills moved unchanged from engineering/resources/skills at commit +`c25ce11a1bb8bf97f24d5e2b12d98680a9c573ca`. Historical engineering releases retain +their original copies; new releases and consumers refer to this source. diff --git a/skills/adr-brainstorm/ATTRIBUTION.md b/skills/adr-brainstorm/ATTRIBUTION.md new file mode 100644 index 0000000..1ebe60f --- /dev/null +++ b/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. diff --git a/skills/adr-brainstorm/LICENSE.mattpocock b/skills/adr-brainstorm/LICENSE.mattpocock new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/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. diff --git a/skills/adr-brainstorm/LICENSE.wanjakrah b/skills/adr-brainstorm/LICENSE.wanjakrah new file mode 100644 index 0000000..73f2e1d --- /dev/null +++ b/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. diff --git a/skills/adr-brainstorm/SKILL.md b/skills/adr-brainstorm/SKILL.md new file mode 100644 index 0000000..6ef44da --- /dev/null +++ b/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 \ No newline at end of file diff --git a/skills/adr-brainstorm/adr-template.md b/skills/adr-brainstorm/adr-template.md new file mode 100644 index 0000000..7afb962 --- /dev/null +++ b/skills/adr-brainstorm/adr-template.md @@ -0,0 +1,20 @@ +**ID:** \ +**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 + \ No newline at end of file diff --git a/skills/adr-brainstorm/agents/openai.yaml b/skills/adr-brainstorm/agents/openai.yaml new file mode 100644 index 0000000..9dae6f3 --- /dev/null +++ b/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" diff --git a/skills/code-review/LICENSE.mattpocock b/skills/code-review/LICENSE.mattpocock new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/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. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..83183e0 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,89 @@ +--- +name: code-review +description: "Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to \"review since X\"." +--- + +Two-axis review of the diff between `HEAD` and a fixed point the user supplies: + +- **Standards**: does the code conform to this repo's documented coding standards? +- **Spec**: does the code faithfully implement the originating issue / spec? + +Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. Start every sub-agent with a fresh context window. + +The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. + +## Process + +### 1. Pin the fixed point + +Whatever the user said is the fixed point (a commit SHA, branch name, tag, `main`, `HEAD~5`, etc.). If they didn't specify one, ask for it. + +Capture the diff command once: `git diff ...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log ..HEAD --oneline`. + +Before going further, confirm the fixed point resolves (`git rev-parse `) and the diff is non-empty. A bad ref or empty diff should fail here, not inside two parallel sub-agents. + +### 2. Identify the spec source + +Look for the originating spec, in this order: + +1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.), fetched via the workflow in the tracker doc. +2. A path the user passed as an argument. +3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature. +4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available". + +### 3. Identify the standards sources + +Search the repo for every file that documents how code should be written. When `CODING_STANDARDS.md` or `CONTRIBUTING.md` exists, it must be on the list. + +On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below: a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it: + +- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell. +- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation. Like any standard here, skip anything tooling already enforces. + +Each smell reads *what it is* → *how to fix*; match it against the diff: + +- **Mysterious Name**: a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky. +- **Duplicated Code**: the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both. +- **Feature Envy**: a method that reaches into another object's data more than its own. → move the method onto the data it envies. +- **Data Clumps**: the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that. +- **Primitive Obsession**: a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type. +- **Repeated Switches**: the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share. +- **Shotgun Surgery**: one logical change forces scattered edits across many files in the diff. → gather what changes together into one module. +- **Divergent Change**: one file or module is edited for several unrelated reasons. → split so each module changes for one reason. +- **Speculative Generality**: abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows. +- **Message Chains**: long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object. +- **Middle Man**: a class or function that mostly just delegates onward. → cut it, call the real target direct. +- **Refused Bequest**: a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition. + +### 4. Spawn both sub-agents in parallel + +Issue both sub-agent calls together, in the foreground, and aggregate the reports they return. + +**Standards sub-agent prompt** should include: + +- The full diff command and commit list. +- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full (the sub-agent has no other access to it). +- The brief: "Report, per file/hunk where relevant, (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls: documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words." + +**Spec sub-agent prompt** should include: + +- The diff command and commit list. +- The path or fetched contents of the spec. +- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words." + +If the spec is missing, skip the Spec sub-agent and note this in the final report. + +### 5. Aggregate + +Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings, because the two axes are deliberately separate (see _Why two axes_). + +End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes: that's the reranking the separation exists to prevent. + +## Why two axes + +A change can pass one axis and fail the other: + +- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.** +- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.** + +Reporting them separately stops one axis from masking the other. diff --git a/skills/code-review/agents/openai.yaml b/skills/code-review/agents/openai.yaml new file mode 100644 index 0000000..9076774 --- /dev/null +++ b/skills/code-review/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Code Review" + short_description: "Review a diff on standards and spec" diff --git a/skills/grill-me/LICENSE.mattpocock b/skills/grill-me/LICENSE.mattpocock new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/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. diff --git a/skills/grill-me/SKILL.md b/skills/grill-me/SKILL.md new file mode 100644 index 0000000..3947ff9 --- /dev/null +++ b/skills/grill-me/SKILL.md @@ -0,0 +1,7 @@ +--- +name: grill-me +description: A relentless interview to sharpen a plan or design. +disable-model-invocation: true +--- + +Call the Skill tool with "grilling". diff --git a/skills/grill-me/agents/openai.yaml b/skills/grill-me/agents/openai.yaml new file mode 100644 index 0000000..4d6fb0c --- /dev/null +++ b/skills/grill-me/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Grill Me" + short_description: "Sharpen a plan through interview" +policy: + allow_implicit_invocation: false diff --git a/skills/grilling/LICENSE.mattpocock b/skills/grilling/LICENSE.mattpocock new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/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. diff --git a/skills/grilling/SKILL.md b/skills/grilling/SKILL.md new file mode 100644 index 0000000..df69d99 --- /dev/null +++ b/skills/grilling/SKILL.md @@ -0,0 +1,30 @@ +--- +name: grilling +description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases. +--- + +Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it. + +Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round. + +Format a round like so: + +``` +❓ **Q1** - ****: + +➡️ + +--- + +❓ **Q2** - ****: + +➡️ +``` + +Word each question so "yes" accepts your recommended answer. + +Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one. + +Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait. + +The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding. diff --git a/skills/grilling/agents/openai.yaml b/skills/grilling/agents/openai.yaml new file mode 100644 index 0000000..ddbdb96 --- /dev/null +++ b/skills/grilling/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "Grilling" + short_description: "Stress-test thinking a round of questions at a time" diff --git a/skills/upstream.json b/skills/upstream.json new file mode 100644 index 0000000..67230b0 --- /dev/null +++ b/skills/upstream.json @@ -0,0 +1,14 @@ +{ + "repository": "https://github.com/mattpocock/skills", + "commit": "59db609eb1e18aaf59b63284d0e52255aff0c63c", + "source": "https://skills.sh/mattpocock/skills/grill-me", + "skills": { + "grill-me": "skills/productivity/grill-me", + "grilling": "skills/productivity/grilling", + "code-review": { + "path": "skills/engineering/code-review", + "commit": "a496f5513d4a4cf889bc48e189e579f4b0bdf6aa", + "source": "https://www.skills.sh/mattpocock/skills/code-review" + } + } +} diff --git a/specs/S19-validation.md b/specs/S19-validation.md index 8e888b0..99d5eb0 100644 --- a/specs/S19-validation.md +++ b/specs/S19-validation.md @@ -33,3 +33,17 @@ credentials and rollback of pre-S19 retained releases remain explicit operationa validation limits. The release-state schema, existing Compose project and database volume remain compatible; review legacy health-hook compatibility before production rollback. Business-system extraction is outside S19. + +## Review follow-up — 2026-11-10 + +Engineering v2.0.0 (`46df72f008113d0ed683a6c7344b1d7309564d84`) moves shared +agent workflows to landscape/skills/ and supplies a shared user-scoped mini-pc +runner setup. Upstream skill contents, attribution and licenses were preserved. +A newly generated project completed its build on the default mini-pc runner +without a project-specific registration, after the documented platform setup. + +Consumer changes and validation remain application-owned: +[Agile Dancers PR](http://192.168.2.28:3000/wanjakrah/agiledancers/pulls/21) and +[Waterpolo Coaching PR](http://192.168.2.28:3000/wanjakrah/waterpolo-coaching/pulls/1). +The review's independent-image-name limitation remains recorded in the specification. +No production deployment is included in this follow-up. diff --git a/specs/S19.md b/specs/S19.md index 38fdf96..9c63753 100644 --- a/specs/S19.md +++ b/specs/S19.md @@ -1,6 +1,7 @@ # S19 — Multi-project engineering setup -Affected repositories: `agiledancers`, `landscape`, `engineering`. +Affected repositories: `agiledancers`, `landscape`, `engineering`; review follow-up +also affects the new `waterpolo-coaching` consumer. This stable reference follows the specification through its lifecycle. diff --git a/specs/in_review/S19_multi-project b/specs/in_review/S19_multi-project index 2fd2883..fcf6117 100644 --- a/specs/in_review/S19_multi-project +++ b/specs/in_review/S19_multi-project @@ -39,10 +39,15 @@ technical usage instructions rather than maintaining duplicate instructions. ### Engineering -Move reusable skills, general engineering documentation, coding standards, +Move general engineering documentation, coding standards, tooling, and generalized pipeline and deployment mechanisms to `engineering`. Include templates and a project generator for new consumers. +Maintainer clarification (2026-11-10): reusable agent skills belong in +`landscape/skills/`, as shared workflows for all projects. Engineering and application +agent instructions reference those skills and retain project-specific review +companions. Historical published engineering versions remain immutable. + Generalize the existing CI, deployment, formatting, standards, and coverage helpers as needed. This includes helpers such as `ci/Pipeline.java`; substantial generalization is part of S19 rather than deferred merely because it requires @@ -175,3 +180,15 @@ Application commit: `c6a495a93c31bef86080915d7c939f642861a97a`. Engineering rele [Gitea build](http://192.168.2.28:3000/wanjakrah/agiledancers/actions/runs/64) completed successfully. Production deployment remains a separate action. + +## Review follow-up — 2026-11-10 + +Affected repositories additionally include `waterpolo-coaching`, a new consumer. +Use the physical mini-pc as a shared Gitea user-scoped runner for `wanjakrah`, +labelled `mini-pc`, available to existing and future projects of that owner. +New generated projects default to that label and reuse its one-time registration. +Record Waterpolo Coaching and its Three.js/Vite frontend deviation in systems.md. + +The review found that image names are derived from `-backend/frontend`. +Neither current consumer needs independently configurable image repositories. +This follow-up does not implement that outstanding part of the original requirement. diff --git a/systems.md b/systems.md index 88ad357..3209b20 100644 --- a/systems.md +++ b/systems.md @@ -3,11 +3,21 @@ | System / repository | Responsibilities | Data ownership | Deployment | | --- | --- | --- | --- | | [Agile Dancers](http://192.168.2.28:3000/wanjakrah/agiledancers) | Current school administration, import/export, scheduling and show planning | Owns its application PostgreSQL data | Existing frontend/backend application deployment; project-owned Compose configuration | -| landscape | ADRs, specifications, capability/system map, onboarding | Owns landscape documentation | Documentation repository; no application runtime | -| [engineering](http://192.168.2.28:3000/wanjakrah/engineering) | Shared engineering mechanisms, standards, skills, templates and generator | Owns versioned engineering source | Immutable versioned releases consumed by applications | +| [Waterpolo Coaching](http://192.168.2.28:3000/wanjakrah/waterpolo-coaching) | Interactive visualization of waterpolo training and player positions | Owns its application state; no production data store documented yet | Local frontend/backend development; no production deployment configured | +| landscape | ADRs, specifications, capability/system map, onboarding and shared agent skills | Owns landscape documentation and agent workflows | Documentation repository; no application runtime | +| [engineering](http://192.168.2.28:3000/wanjakrah/engineering) | Shared build mechanisms, standards, templates and generator; shared runner setup | Owns versioned engineering source | Immutable versioned releases consumed by applications | S19 separates engineering and governance repositories. It does not extract a business capability or change runtime/data boundaries. Scheduling and school administration remain candidates for future examination under ADR1. Any later system extraction must specify contracts, enforced data ownership and failure behavior before migration. + +Waterpolo Coaching uses Three.js (https://threejs.org/) with TypeScript and Vite +instead of the Angular frontend used by Agile Dancers. Its npm lint, test, build +and container contracts still follow the common engineering recipe. + +The physical mini-pc provides the shared host runner labelled `mini-pc`, registered +at Gitea user scope for `wanjakrah`. Existing and new repositories of that owner +use the same runner. Builds share one execution slot; deployment settings and +registry credentials remain project-owned.