Templates & Checklists: merged checklists and templates

content/templates/adr.md

@@ -0,0 +1,65 @@
+---
+title: Architecture decision record
+---
+
+# Architecture decision record
+
+An architecture decision record (ADR) captures one significant decision: the problem, the options, the choice and what follows from it. Write one when a decision is hard to reverse, affects more than one component, or will puzzle someone who joins the project later. Michael Nygard [described the idea](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) in 2011, and most ADR formats, this one included, descend from his.
+
+- Keep each record short, usually one page, and about one decision.
+- Store records in the repository beside the code, for example in `docs/adr/`, numbered in order: `0007-use-cbor-for-telemetry.md`.
+- Never edit an accepted record to change the decision. Write a new one that supersedes it, and link the two.
+- When a decision needs wide discussion first, write a [request for comments](rfc.md), and record the outcome as an ADR.
+
+## Template
+
+```markdown
+---
+id: ADR-0000
+title: Short imperative title, for example "Use CBOR for telemetry payloads"
+status: proposed        # proposed | accepted | rejected | deprecated | superseded
+date: YYYY-MM-DD
+deciders: [names or roles]
+requirements: [REQ-...]
+principles: [AP-...]
+rfc:                    # RFC-0000, if one led to this decision
+supersedes:             # ADR-0000
+superseded-by:          # ADR-0000
+---
+
+# ADR-0000: Short imperative title
+
+## Context
+
+What is the problem, and why does it need a decision now? Describe the
+forces at work: technical, commercial, regulatory and schedule.
+
+## Decision drivers
+
+- The things that matter most in choosing, for example power budget,
+  team skills or time to market.
+
+## Options considered
+
+1. **Option A.** Summary. Pros. Cons.
+2. **Option B.** Summary. Pros. Cons.
+3. **Do nothing.** What happens if we do not decide.
+
+## Decision
+
+We will do X, because Y.
+
+## Consequences
+
+- Good: what becomes easier.
+- Bad: what becomes harder, and what we accept as a result.
+- Follow-up: actions, other decisions or documents to update.
+
+## Verification
+
+How we will know the decision is working, and when we will check.
+
+## Related
+
+Links to requirements, other ADRs, RFCs and designs.
+```

content/templates/agent-task-brief.md

@@ -0,0 +1,54 @@
+---
+title: Task brief for an AI agent
+---
+
+# Task brief for an AI agent
+
+An AI coding agent does better work with a short, specific brief than with a long conversation. The brief below gives it a goal, the boundaries, a definition of done and the points where it must stop and ask. It also says what to report, so a person can review the result quickly.
+
+Standing rules, such as build commands, folders it must not touch and coding conventions, belong in the repository's `AGENTS.md` (or the agent's own instruction file). The brief covers only this task.
+
+## Template
+
+```markdown
+# Task: short title
+
+## Goal
+
+One or two sentences: the outcome wanted, and why.
+
+## Requirement and context
+
+- Requirement IDs: REQ-...
+- Related ADRs: ADR-...
+- Files or areas in scope:
+
+## Constraints
+
+- Do not touch (as well as the boundaries in AGENTS.md):
+- Keep the change as small as it can be. Do not refactor beyond the task.
+- Prefer the simple solution. State any assumption rather than guess.
+
+## Definition of done
+
+- Build, tests and lint pass locally, using the commands in AGENTS.md.
+- Tests added or updated, and named after the requirement IDs.
+- Documentation updated.
+- Commits and pull request follow the conventions, with `Refs:` and
+  `Assisted-by:` trailers.
+
+## Ask first if
+
+- The change needs a new dependency, an interface change or an ADR.
+- A requirement is missing, unclear or contradicts another.
+- Anything touches a boundary listed in AGENTS.md.
+
+## Report back
+
+- What you did and why.
+- Assumptions you made.
+- Risks and anything left undone.
+- Evidence: test and analysis output.
+```
+
+Review the agent's work as you would a colleague's: against the [code review checklist](code-review-checklist.md), with the same bar for tests and evidence.

content/templates/architecture-canvases.md

@@ -0,0 +1,27 @@
+---
+title: Architecture canvases
+---
+
+# Architecture canvases
+
+A canvas fits the essentials of an architecture on one page, to fill in together at a whiteboard or on a shared screen. It is not a replacement for the [architecture document](architecture-document.md). It is a quick way to start one, or to explain a system in a meeting.
+
+Both canvases here come from the [arc42 canvas project](https://canvas.arc42.org/). They are licensed under [Creative Commons Attribution-ShareAlike 4.0](https://creativecommons.org/licenses/by-sa/4.0/), and the files keep their authors' names and licence. If you change them and share the result, keep the attribution and the same licence.
+
+## Architecture Inception Canvas
+
+Use it at the start of a project, before there is much to document. The team fills it in together to agree what they are building, for whom, and what will shape the architecture. Its boxes cover the business case and context, a functional overview and the top three quality goals. Others hold the organisational and technical constraints, the known challenges and risks, and the architectural hypotheses that follow. Gaps that show up on the canvas are the questions to answer next.
+
+Downloads: [draw.io](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-inception-canvas.drawio) · [PowerPoint](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-inception-canvas.pptx)
+
+## Architecture Communication Canvas
+
+Use it to explain an existing system to someone new, such as a new team member, a stakeholder or a reviewer. On one page it gives the system's value, its key stakeholders, its core functions and its business context. It also shows the main components and technologies, the quality requirements, the decisions that shaped the system, and its risks and missing information.
+
+Downloads: [draw.io](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-communication-canvas.drawio) · [PowerPoint](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/architecture-communication-canvas.pptx)
+
+## Tips
+
+- Fill it in with the team, not alone. The conversation is worth more than the finished page.
+- Use sticky notes or short phrases. If a box needs a paragraph, it needs a section in the architecture document.
+- Date the canvas, and redo it when the architecture changes rather than patching the old one.

content/templates/architecture-document.md

@@ -0,0 +1,131 @@
+---
+title: Architecture document
+---
+
+# Architecture document
+
+An architecture document explains how a system is built and why. It is for the people who will build, test, operate and change the system, so it should answer their questions and stop. Start small: a context diagram, the quality goals and the main decisions are worth more than a hundred pages nobody reads.
+
+## Outline
+
+The outline below follows [arc42](https://arc42.org/), a free template for architecture documentation by Gernot Starke and Peter Hruschka. Its twelve sections are a checklist of what a reader might need. Leave out a section that has nothing to say, but keep the numbering, so readers always know where to look. The [arc42 documentation](https://docs.arc42.org/) explains each section, with examples. The official templates, in many formats and languages, are on the arc42 site.
+
+[[CAPTION:Table]] The twelve sections of an architecture document.
+
+| Section | What it answers |
+|---------|-----------------|
+| 1 Introduction and goals | What the system is for, its main features, the top three to five quality goals, and who the stakeholders are |
+| 2 Constraints | What the team must work within: technical, organisational, regulatory and conventions |
+| 3 Context and scope | What is inside the system and what is outside, and every external interface, both in business terms and in technical terms |
+| 4 Solution strategy | The handful of fundamental decisions that shape everything else, and how they meet the quality goals |
+| 5 Building block view | How the system is split into parts, level by level, and what each part is responsible for |
+| 6 Runtime view | How the parts work together in the important scenarios, including start-up and failure |
+| 7 Deployment view | Which hardware, networks and environments the parts run on |
+| 8 Cross-cutting concepts | Rules that apply across many parts: security, logging, error handling, persistence, configuration |
+| 9 Architecture decisions | The significant decisions, usually as links to [architecture decision records](adr.md) |
+| 10 Quality requirements | The quality goals made measurable, as [quality scenarios](requirements.md#quality-scenario) |
+| 11 Risks and technical debt | What could go wrong, and what we already know needs fixing |
+| 12 Glossary | The domain and technical terms, so everyone uses the same words |
+
+Review the document with the [architecture review checklist](architecture-review-checklist.md).
+
+## C4 diagrams
+
+The [C4 model](https://c4model.com/), by Simon Brown, draws a system at four levels of zoom: system context, containers, components and code. Sections 3, 5 and 7 of the outline map onto its context, container and deployment diagrams. Most systems need only the first two levels.
+
+### C4 in PlantUML
+
+[C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML) adds C4 shapes to PlantUML. Its standard library ships with PlantUML, so `!include <C4/C4_Context>` needs no download. Copy this starter and replace the names.
+
+[[CAPTION:Figure]]
+```plantuml caption="A system context diagram drawn with C4-PlantUML"
+@startuml
+!include <C4/C4_Context>
+title System context: sensor platform
+
+Person(installer, "Installer", "Fits and commissions sensors")
+System(platform, "Sensor platform", "Collects readings and manages devices")
+System_Ext(network, "Mobile network", "NB-IoT and LTE-M")
+System_Ext(erp, "Customer ERP", "Bills customers from readings")
+
+Rel(installer, platform, "Commissions devices with", "mobile app")
+Rel(platform, network, "Sends readings over")
+Rel(platform, erp, "Sends daily readings to", "HTTPS")
+@enduml
+```
+
+[[CAPTION:Figure]]
+```plantuml caption="A container diagram drawn with C4-PlantUML"
+@startuml
+!include <C4/C4_Container>
+title Containers: sensor platform
+
+Person(installer, "Installer")
+System_Boundary(platform, "Sensor platform") {
+    Container(device, "Sensor firmware", "C, Zephyr", "Measures and reports")
+    Container(ingest, "Ingest service", "Go", "Receives and decodes readings")
+    ContainerDb(store, "Time-series store", "PostgreSQL", "Holds readings")
+    Container(app, "Installer app", "Kotlin", "Commissions devices")
+}
+System_Ext(erp, "Customer ERP")
+
+Rel(device, ingest, "Sends readings", "CoAP, CBOR")
+Rel(ingest, store, "Writes")
+Rel(installer, app, "Uses")
+Rel(app, ingest, "Registers devices", "HTTPS")
+Rel(ingest, erp, "Sends daily readings", "HTTPS")
+@enduml
+```
+
+The other levels use `<C4/C4_Component>`, `<C4/C4_Deployment>` and `<C4/C4_Dynamic>` in the same way.
+
+### C4 in Structurizr
+
+For anything bigger than a few diagrams, keep one model and draw every view from it. Then a name changed in the model changes in every diagram. [Structurizr](https://structurizr.com/) does this with a model written in its own domain-specific language (DSL), and py-doc can turn a Structurizr workspace into chapters and pictures. This starter describes the same system as the diagrams above. Download [`c4-workspace.dsl`](https://github.com/markbac/markbac.github.io/raw/main/content/templates/files/c4-workspace.dsl).
+
+[[CAPTION:Figure]] A starter Structurizr workspace.
+
+```text
+workspace "Sensor platform" "Starter C4 model" {
+
+    model {
+        installer = person "Installer" "Fits and commissions sensors."
+        erp = softwareSystem "Customer ERP" "Bills customers from readings." "External"
+
+        platform = softwareSystem "Sensor platform" "Collects readings and manages devices." {
+            device = container "Sensor firmware" "Measures and reports." "C, Zephyr"
+            ingest = container "Ingest service" "Receives and decodes readings." "Go"
+            store = container "Time-series store" "Holds readings." "PostgreSQL" "Database"
+            app = container "Installer app" "Commissions devices." "Kotlin"
+        }
+
+        installer -> app "Uses"
+        app -> ingest "Registers devices with" "HTTPS"
+        device -> ingest "Sends readings to" "CoAP, CBOR"
+        ingest -> store "Writes readings to"
+        ingest -> erp "Sends daily readings to" "HTTPS"
+    }
+
+    views {
+        systemContext platform "Context" {
+            include *
+            autoLayout
+        }
+        container platform "Containers" {
+            include *
+            autoLayout
+        }
+        styles {
+            element "Person" {
+                shape Person
+            }
+            element "Database" {
+                shape Cylinder
+            }
+            element "External" {
+                background #999999
+            }
+        }
+    }
+}
+```