From 1d35410b8d29df6c4991a0b9aff24f8509d58a86 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sun, 4 Oct 2026 21:38:09 +0800 Subject: [PATCH] Add planning baseline: BC, SA, PP and two gateways Create the Business Case, Stakeholder Analysis (S01 course participant, S02 Udemy coursists, S03 GitHub viewers), Project Plan and the milestone documents MIL-001 (project setup, 6 tasks) and MIL-002 (game implementation, 8 tasks) for the console Blackjack game. Register PP and MIL in the artifact registry, set the PO language to en, and link the synced Gitea milestones in the Gateway Schedule. Refs #1 Refs #2 Refs #3 Refs #4 Refs #5 Refs #6 Refs #7 Refs #8 Refs #9 Refs #10 Refs #11 Refs #12 Refs #13 Refs #14 --- .agents/skills/.framework-skills | 3 + .agents/skills/artifact/SKILL.md | 113 +++++++ .agents/skills/artifact/references/ADR.md | 25 ++ .agents/skills/artifact/references/BC.md | 45 +++ .agents/skills/artifact/references/BMC.md | 21 ++ .agents/skills/artifact/references/BPMN.md | 22 ++ .agents/skills/artifact/references/DCD.md | 27 ++ .agents/skills/artifact/references/DICT.md | 25 ++ .agents/skills/artifact/references/DM.md | 26 ++ .agents/skills/artifact/references/ERD.md | 22 ++ .agents/skills/artifact/references/GOV.md | 16 + .agents/skills/artifact/references/KPI.md | 20 ++ .agents/skills/artifact/references/MIL.md | 48 +++ .agents/skills/artifact/references/OC.md | 27 ++ .agents/skills/artifact/references/PP.md | 64 ++++ .agents/skills/artifact/references/QC.md | 44 +++ .agents/skills/artifact/references/RC.md | 34 +++ .agents/skills/artifact/references/SA.md | 27 ++ .agents/skills/artifact/references/SD.md | 26 ++ .agents/skills/artifact/references/SSD.md | 21 ++ .agents/skills/artifact/references/TM.md | 15 + .agents/skills/artifact/references/TRN.md | 18 ++ .agents/skills/artifact/references/TRR.md | 21 ++ .agents/skills/artifact/references/UC.md | 35 +++ .agents/skills/artifact/references/UCD.md | 24 ++ .agents/skills/artifact/references/US.md | 22 ++ .agents/skills/artifact/templates/ADR.md | 42 +++ .agents/skills/artifact/templates/BC.md | 70 +++++ .agents/skills/artifact/templates/BMC.md | 113 +++++++ .agents/skills/artifact/templates/BPMN.md | 41 +++ .agents/skills/artifact/templates/DCD.md | 50 ++++ .agents/skills/artifact/templates/DICT.md | 35 +++ .agents/skills/artifact/templates/DM.md | 54 ++++ .agents/skills/artifact/templates/ERD.md | 53 ++++ .agents/skills/artifact/templates/GOV.md | 68 +++++ .agents/skills/artifact/templates/KPI.md | 35 +++ .agents/skills/artifact/templates/MIL.md | 58 ++++ .agents/skills/artifact/templates/OC.md | 41 +++ .agents/skills/artifact/templates/PP.md | 61 ++++ .agents/skills/artifact/templates/QC.md | 42 +++ .agents/skills/artifact/templates/RC.md | 39 +++ .agents/skills/artifact/templates/SA.md | 54 ++++ .agents/skills/artifact/templates/SD.md | 47 +++ .agents/skills/artifact/templates/SSD.md | 40 +++ .agents/skills/artifact/templates/TM.md | 30 ++ .agents/skills/artifact/templates/TRN.md | 60 ++++ .agents/skills/artifact/templates/TRR.md | 43 +++ .agents/skills/artifact/templates/UC.md | 55 ++++ .agents/skills/artifact/templates/UCD.md | 50 ++++ .agents/skills/artifact/templates/US.md | 36 +++ .agents/skills/coding-conventions/SKILL.md | 94 ++++++ .../skills/coding-conventions/references/c.md | 71 +++++ .../coding-conventions/references/cpp.md | 70 +++++ .../coding-conventions/references/csharp.md | 72 +++++ .../coding-conventions/references/python.md | 66 +++++ .../coding-conventions/references/shell.md | 62 ++++ .agents/skills/project-planning/SKILL.md | 278 ++++++++++++++++++ .claude/skills/.framework-skills | 3 + .claude/skills/artifact/SKILL.md | 113 +++++++ .claude/skills/artifact/references/ADR.md | 25 ++ .claude/skills/artifact/references/BC.md | 45 +++ .claude/skills/artifact/references/BMC.md | 21 ++ .claude/skills/artifact/references/BPMN.md | 22 ++ .claude/skills/artifact/references/DCD.md | 27 ++ .claude/skills/artifact/references/DICT.md | 25 ++ .claude/skills/artifact/references/DM.md | 26 ++ .claude/skills/artifact/references/ERD.md | 22 ++ .claude/skills/artifact/references/GOV.md | 16 + .claude/skills/artifact/references/KPI.md | 20 ++ .claude/skills/artifact/references/MIL.md | 48 +++ .claude/skills/artifact/references/OC.md | 27 ++ .claude/skills/artifact/references/PP.md | 64 ++++ .claude/skills/artifact/references/QC.md | 44 +++ .claude/skills/artifact/references/RC.md | 34 +++ .claude/skills/artifact/references/SA.md | 27 ++ .claude/skills/artifact/references/SD.md | 26 ++ .claude/skills/artifact/references/SSD.md | 21 ++ .claude/skills/artifact/references/TM.md | 15 + .claude/skills/artifact/references/TRN.md | 18 ++ .claude/skills/artifact/references/TRR.md | 21 ++ .claude/skills/artifact/references/UC.md | 35 +++ .claude/skills/artifact/references/UCD.md | 24 ++ .claude/skills/artifact/references/US.md | 22 ++ .claude/skills/artifact/templates/ADR.md | 42 +++ .claude/skills/artifact/templates/BC.md | 70 +++++ .claude/skills/artifact/templates/BMC.md | 113 +++++++ .claude/skills/artifact/templates/BPMN.md | 41 +++ .claude/skills/artifact/templates/DCD.md | 50 ++++ .claude/skills/artifact/templates/DICT.md | 35 +++ .claude/skills/artifact/templates/DM.md | 54 ++++ .claude/skills/artifact/templates/ERD.md | 53 ++++ .claude/skills/artifact/templates/GOV.md | 68 +++++ .claude/skills/artifact/templates/KPI.md | 35 +++ .claude/skills/artifact/templates/MIL.md | 58 ++++ .claude/skills/artifact/templates/OC.md | 41 +++ .claude/skills/artifact/templates/PP.md | 61 ++++ .claude/skills/artifact/templates/QC.md | 42 +++ .claude/skills/artifact/templates/RC.md | 39 +++ .claude/skills/artifact/templates/SA.md | 54 ++++ .claude/skills/artifact/templates/SD.md | 47 +++ .claude/skills/artifact/templates/SSD.md | 40 +++ .claude/skills/artifact/templates/TM.md | 30 ++ .claude/skills/artifact/templates/TRN.md | 60 ++++ .claude/skills/artifact/templates/TRR.md | 43 +++ .claude/skills/artifact/templates/UC.md | 55 ++++ .claude/skills/artifact/templates/UCD.md | 50 ++++ .claude/skills/artifact/templates/US.md | 36 +++ .claude/skills/coding-conventions/SKILL.md | 94 ++++++ .../skills/coding-conventions/references/c.md | 71 +++++ .../coding-conventions/references/cpp.md | 70 +++++ .../coding-conventions/references/csharp.md | 72 +++++ .../coding-conventions/references/python.md | 66 +++++ .../coding-conventions/references/shell.md | 62 ++++ .claude/skills/project-planning/SKILL.md | 278 ++++++++++++++++++ .gitmodules | 3 + AGENTS.md | 53 ++++ docs/artifact-registry.md | 43 +++ docs/business-case.md | 129 ++++++++ docs/milestones/mil-001-project-setup.md | 71 +++++ .../milestones/mil-002-game-implementation.md | 74 +++++ docs/project-plan.md | 83 ++++++ docs/stakeholder-analysis.md | 79 +++++ framework | 1 + 123 files changed, 5978 insertions(+) create mode 100644 .agents/skills/.framework-skills create mode 100644 .agents/skills/artifact/SKILL.md create mode 100644 .agents/skills/artifact/references/ADR.md create mode 100644 .agents/skills/artifact/references/BC.md create mode 100644 .agents/skills/artifact/references/BMC.md create mode 100644 .agents/skills/artifact/references/BPMN.md create mode 100644 .agents/skills/artifact/references/DCD.md create mode 100644 .agents/skills/artifact/references/DICT.md create mode 100644 .agents/skills/artifact/references/DM.md create mode 100644 .agents/skills/artifact/references/ERD.md create mode 100644 .agents/skills/artifact/references/GOV.md create mode 100644 .agents/skills/artifact/references/KPI.md create mode 100644 .agents/skills/artifact/references/MIL.md create mode 100644 .agents/skills/artifact/references/OC.md create mode 100644 .agents/skills/artifact/references/PP.md create mode 100644 .agents/skills/artifact/references/QC.md create mode 100644 .agents/skills/artifact/references/RC.md create mode 100644 .agents/skills/artifact/references/SA.md create mode 100644 .agents/skills/artifact/references/SD.md create mode 100644 .agents/skills/artifact/references/SSD.md create mode 100644 .agents/skills/artifact/references/TM.md create mode 100644 .agents/skills/artifact/references/TRN.md create mode 100644 .agents/skills/artifact/references/TRR.md create mode 100644 .agents/skills/artifact/references/UC.md create mode 100644 .agents/skills/artifact/references/UCD.md create mode 100644 .agents/skills/artifact/references/US.md create mode 100644 .agents/skills/artifact/templates/ADR.md create mode 100644 .agents/skills/artifact/templates/BC.md create mode 100644 .agents/skills/artifact/templates/BMC.md create mode 100644 .agents/skills/artifact/templates/BPMN.md create mode 100644 .agents/skills/artifact/templates/DCD.md create mode 100644 .agents/skills/artifact/templates/DICT.md create mode 100644 .agents/skills/artifact/templates/DM.md create mode 100644 .agents/skills/artifact/templates/ERD.md create mode 100644 .agents/skills/artifact/templates/GOV.md create mode 100644 .agents/skills/artifact/templates/KPI.md create mode 100644 .agents/skills/artifact/templates/MIL.md create mode 100644 .agents/skills/artifact/templates/OC.md create mode 100644 .agents/skills/artifact/templates/PP.md create mode 100644 .agents/skills/artifact/templates/QC.md create mode 100644 .agents/skills/artifact/templates/RC.md create mode 100644 .agents/skills/artifact/templates/SA.md create mode 100644 .agents/skills/artifact/templates/SD.md create mode 100644 .agents/skills/artifact/templates/SSD.md create mode 100644 .agents/skills/artifact/templates/TM.md create mode 100644 .agents/skills/artifact/templates/TRN.md create mode 100644 .agents/skills/artifact/templates/TRR.md create mode 100644 .agents/skills/artifact/templates/UC.md create mode 100644 .agents/skills/artifact/templates/UCD.md create mode 100644 .agents/skills/artifact/templates/US.md create mode 100644 .agents/skills/coding-conventions/SKILL.md create mode 100644 .agents/skills/coding-conventions/references/c.md create mode 100644 .agents/skills/coding-conventions/references/cpp.md create mode 100644 .agents/skills/coding-conventions/references/csharp.md create mode 100644 .agents/skills/coding-conventions/references/python.md create mode 100644 .agents/skills/coding-conventions/references/shell.md create mode 100644 .agents/skills/project-planning/SKILL.md create mode 100644 .claude/skills/.framework-skills create mode 100644 .claude/skills/artifact/SKILL.md create mode 100644 .claude/skills/artifact/references/ADR.md create mode 100644 .claude/skills/artifact/references/BC.md create mode 100644 .claude/skills/artifact/references/BMC.md create mode 100644 .claude/skills/artifact/references/BPMN.md create mode 100644 .claude/skills/artifact/references/DCD.md create mode 100644 .claude/skills/artifact/references/DICT.md create mode 100644 .claude/skills/artifact/references/DM.md create mode 100644 .claude/skills/artifact/references/ERD.md create mode 100644 .claude/skills/artifact/references/GOV.md create mode 100644 .claude/skills/artifact/references/KPI.md create mode 100644 .claude/skills/artifact/references/MIL.md create mode 100644 .claude/skills/artifact/references/OC.md create mode 100644 .claude/skills/artifact/references/PP.md create mode 100644 .claude/skills/artifact/references/QC.md create mode 100644 .claude/skills/artifact/references/RC.md create mode 100644 .claude/skills/artifact/references/SA.md create mode 100644 .claude/skills/artifact/references/SD.md create mode 100644 .claude/skills/artifact/references/SSD.md create mode 100644 .claude/skills/artifact/references/TM.md create mode 100644 .claude/skills/artifact/references/TRN.md create mode 100644 .claude/skills/artifact/references/TRR.md create mode 100644 .claude/skills/artifact/references/UC.md create mode 100644 .claude/skills/artifact/references/UCD.md create mode 100644 .claude/skills/artifact/references/US.md create mode 100644 .claude/skills/artifact/templates/ADR.md create mode 100644 .claude/skills/artifact/templates/BC.md create mode 100644 .claude/skills/artifact/templates/BMC.md create mode 100644 .claude/skills/artifact/templates/BPMN.md create mode 100644 .claude/skills/artifact/templates/DCD.md create mode 100644 .claude/skills/artifact/templates/DICT.md create mode 100644 .claude/skills/artifact/templates/DM.md create mode 100644 .claude/skills/artifact/templates/ERD.md create mode 100644 .claude/skills/artifact/templates/GOV.md create mode 100644 .claude/skills/artifact/templates/KPI.md create mode 100644 .claude/skills/artifact/templates/MIL.md create mode 100644 .claude/skills/artifact/templates/OC.md create mode 100644 .claude/skills/artifact/templates/PP.md create mode 100644 .claude/skills/artifact/templates/QC.md create mode 100644 .claude/skills/artifact/templates/RC.md create mode 100644 .claude/skills/artifact/templates/SA.md create mode 100644 .claude/skills/artifact/templates/SD.md create mode 100644 .claude/skills/artifact/templates/SSD.md create mode 100644 .claude/skills/artifact/templates/TM.md create mode 100644 .claude/skills/artifact/templates/TRN.md create mode 100644 .claude/skills/artifact/templates/TRR.md create mode 100644 .claude/skills/artifact/templates/UC.md create mode 100644 .claude/skills/artifact/templates/UCD.md create mode 100644 .claude/skills/artifact/templates/US.md create mode 100644 .claude/skills/coding-conventions/SKILL.md create mode 100644 .claude/skills/coding-conventions/references/c.md create mode 100644 .claude/skills/coding-conventions/references/cpp.md create mode 100644 .claude/skills/coding-conventions/references/csharp.md create mode 100644 .claude/skills/coding-conventions/references/python.md create mode 100644 .claude/skills/coding-conventions/references/shell.md create mode 100644 .claude/skills/project-planning/SKILL.md create mode 100644 .gitmodules create mode 100644 AGENTS.md create mode 100644 docs/artifact-registry.md create mode 100644 docs/business-case.md create mode 100644 docs/milestones/mil-001-project-setup.md create mode 100644 docs/milestones/mil-002-game-implementation.md create mode 100644 docs/project-plan.md create mode 100644 docs/stakeholder-analysis.md create mode 160000 framework diff --git a/.agents/skills/.framework-skills b/.agents/skills/.framework-skills new file mode 100644 index 0000000..5dad221 --- /dev/null +++ b/.agents/skills/.framework-skills @@ -0,0 +1,3 @@ +artifact +coding-conventions +project-planning diff --git a/.agents/skills/artifact/SKILL.md b/.agents/skills/artifact/SKILL.md new file mode 100644 index 0000000..9fb92f3 --- /dev/null +++ b/.agents/skills/artifact/SKILL.md @@ -0,0 +1,113 @@ +--- +name: artifact +description: Create, edit or review any project document artifact — Business Case, Stakeholder Analysis, KPI, Business Model Canvas, BPMN, milestones/gateways, use case diagram, user stories, use cases, domain model, SSD, operation contracts, sequence diagrams, DCD, ERD, ADRs, SQA review records, traceability matrix, governance, QC checklists. Scaffolds the file with the correct ID, CrossReference and links, then gives the required sections for that type. +--- + +# Artifact + +Every artifact is a markdown file with `## Metadata` and `## Version History` +tables, a registered short-name ID, and links only at the bottom. Types and +their related types are in `framework/registry/artifact-catalog.md`; this +project's file locations and next versions are in `docs/artifact-registry.md`. + +## Creating an artifact + +1. Find the type's short name (`BC`, `SA`, `MIL`, `DM`, `ADR`, `RC`, …) in + the catalog. If the type is new, add it to the catalog and the registry. +2. Scaffold — this sets the ID, `CrossReference` (only artifacts that exist), + the bottom link block and the registry version: + + ```bash + bash framework/scripts/new-artifact.sh [--file ] [--title ""] [--cite =]... + ``` + + `--file` is required for multi-document types (`MIL`, `UC`, `ADR`, `RC`, + `QC`); single-document types default to the registry's `Primary File`. + The script refuses to overwrite an existing file. +3. Read `framework/.agents/skills/artifact/references/.md` (cite-for + hints and required sections), then fill in the file. Keep the sections in + order and replace every ``. + +## Editing an artifact + +Append a row to `## Version History` on every change (a status change such as +`Proposed` → `Accepted`, or a content change). To re-check `CrossReference`, +run `bash framework/scripts/find-crossreferences.sh `. When the first +instance of a type is created, add it to the `CrossReference` of every +existing artifact that lists that type as a candidate (with a new Version +History row). + +### Version History rule + +The table keeps only the **two latest** changes; git holds the rest. Columns: + +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-01 | Accepted | Jane Doe | S02 | Added Risks section
Fixed scope wording | [a1b2c3d] | + +- **Status** — `Proposed`, `Accepted`, `Rejected` or `Deprecated` for every + artifact type (`ADR` also has `Superseded by ADR-NNNN`); `Approved` is not + used. A new row starts `Proposed`. When the review gives Go, that row + becomes `Accepted` and the row before it becomes `Deprecated`, so at most + one row is `Accepted`: the latest reviewed one. If the reviewer refuses the + change for good (not a No-Go that returns it for rework), the row becomes + `Rejected`; the earlier `Accepted` row stays `Accepted` and nothing is + deprecated. +- **Change** — a short summary of what this row changed; several lines are + separated with `
`. +- **Commit** — the commit that made the change, as a reference-style link + defined at the bottom of the file + (`[a1b2c3d]: https://///commit/`; Gitea and + GitHub use the same `/commit/` form). A row cannot contain its own commit + hash, so a new row says `pending` until the commit exists. Leave it + `pending` and do not commit: only when the user asks for a commit, then: + 1. commit the edited documents; + 2. run `bash framework/scripts/resolve-pending-commits.sh ...`, which + replaces `pending` with the link to that commit and adds the definition; + 3. commit the result as a follow-up commit, before opening the PR. Do not + amend: an amend changes the hash, so the link would point at a commit + that is never pushed. +- When adding a third row, delete the oldest row and its now-unused commit + link definition. Never rewrite the content of the two retained rows other + than resolving `pending` and setting Status to `Accepted` / `Deprecated` + after a Go review. +- Every document uses this format, including QC checklists. A file still in the + old four-column format is converted when next edited (old row kept as + `Initial version`, plus a new row for the conversion). + +## Reviewing an artifact + +1. Take the QC checklist named in the catalog (`framework/qc/qc-*.md`). +2. Create the review record: `new-artifact.sh RC …`, following + `references/RC.md`. +3. Add or update the instance's row in the Traceability Matrix. + +## Rules + +- **Links:** all links are reference-style, defined once at the bottom of the + file after a final `---`, labelled by the target's ID (`[SA-001]`), never + inline. No links → omit the block. +- **CrossReference:** cite only artifacts that exist now. Empty if none. +- **People:** use exact stakeholder IDs from the project's Stakeholder + Analysis (`S01`) for owners, reviewers and RACI. Never invent role names. +- **Diagrams** are PlantUML blocks; check them with + `bash framework/scripts/render-diagrams.sh --server ` (or set + `PLANTUML_URL`) before review. +- **QC checklists** are framework files: every criterion is tagged with an + ISO/IEC 25010:2023 characteristic, and they never mention real instances. +- **IDs:** `-`, 3 digits (`BC-001`); `ADR` uses 4 digits; + `RC` is sequential across all types; QC is `QC--`. +- **Language:** artifacts carry no `DomainLanguages` row. The PO language and + the register of each artifact type are in the `Languages` section of + `docs/artifact-registry.md` (registers: `IT Executive English` for + high-level, `IT Professional English` for technical). +- **Translations:** when the PO language is not English, each type the + registry marks "Also kept as a PO-language file" is also saved as + `..md` beside its English source (`business-case.da.md`). + A translation keeps the source's ID and sections, uses the PO terms from the + dictionary (`DICT`), and has a Version History row naming the source version + it follows. The English file is authoritative; update the translation in the + same change. If the PO language is English, no translations are made. +- **Dictionary:** the Domain Model uses the PO term; the Operation Contract, + Sequence Diagram, Design Class Diagram and ERD use the IT term. Every pair is + recorded in `docs/dictionary.md` (`DICT`). diff --git a/.agents/skills/artifact/references/ADR.md b/.agents/skills/artifact/references/ADR.md new file mode 100644 index 0000000..eb9e4c3 --- /dev/null +++ b/.agents/skills/artifact/references/ADR.md @@ -0,0 +1,25 @@ +# Architecture Decision Record (ADR) + +Files: `docs/adr/adr-NNNN-kebab-case-title.md`. `NNNN` is 4-digit and +sequential; the ID is `ADR-NNNN` and must match the filename number (an +intentional exception to the usual 3-digit IDs). Use +`new-artifact.sh ADR --file docs/adr/adr-NNNN-title.md`. + +Cite in `CrossReference` the artifacts this decision is about (pass each +with `--cite =`); ADR has no fixed candidate list. + +## Required sections (after Metadata / Version History) + +- **Context** — the problem, the options evaluated and the forces + (cost, risk, constraints). +- **Decision** — the outcome in one or two sentences, no hedging. +- **Consequences** — two bold labels, **Positive:** and **Negative:**, each + with a bullet list. +- **Affected Artifacts** — other artifacts impacted, as `[ID]` links, or a + single `-` if none. + +Allowed statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, +`Superseded by ADR-NNNN`; no others (an ADR is never `Approved`). Status +changes (`Proposed` → `Accepted` → `Deprecated` / `Superseded by ADR-NNNN`, or +`Proposed` → `Rejected`) are new rows in `## Version History` (only the two +latest are kept; earlier ones stay in git); never rewrite a retained row. diff --git a/.agents/skills/artifact/references/BC.md b/.agents/skills/artifact/references/BC.md new file mode 100644 index 0000000..f3f07da --- /dev/null +++ b/.agents/skills/artifact/references/BC.md @@ -0,0 +1,45 @@ +# Business Case (BC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Stakeholders section — cite S-IDs instead of re-describing roles +- **BMC** — Cost–Benefit Assessment must agree with its cost/revenue blocks +- **BPMN** — Forward: the process that realizes the objectives +- **KPI** — Success Criteria — each criterion is operationalized by a KPI +- **UCD** — Forward: scope expressed as actors and goals + +## Required sections (after Metadata / Version History) + +In this order: + +1. **Executive Summary** — one paragraph framing the problem and the + proposed solution. +2. **Methodological and Standards Foundation** — states the methodology + (e.g. Larman's *Applying UML and Patterns*) and quality standards (e.g. + ISO/IEC 25002/25010/25019) the rest of the document and downstream + artifacts are built on. +3. **Problem Statement** — the recurring problems that justify the project. +4. **Business Opportunity** — what becomes possible if the problem is + solved. +5. **Objectives** — concrete, verifiable statements of what the project + will achieve. +6. **Scope** — split into `## In Scope` and `## Out of Scope` subsections. +7. **Expected Benefits** — split into `### Tangible Benefits` and + `### Intangible Benefits`. +8. **Strategic Alignment** — how the project supports organizational goals. +9. **Success Criteria** — a table with explicit, measurable targets (not + aspirations). +10. **Risks** — a table with `Risk | Impact | Mitigation` columns; every + risk must have a mitigation. +11. **Assumptions** — bullet list, kept distinct from Constraints. +12. **Constraints** — bullet list, kept distinct from Assumptions. +13. **Cost–Benefit Assessment** — a table (`Costs | Benefits`); may be + qualitative if explicitly justified. +14. **Stakeholders** — a table referencing exact stakeholder IDs from the + project's Stakeholder Analysis (e.g. `S01`, `S07`) if `SA` exists per + the CrossReference check above. **Never re-describe stakeholder roles + inline instead of citing their IDs** — this is the single most common + defect found when reviewing Business Cases (see `QC-BC-001`'s Common + Defects). +15. **Recommendation** — a single, unambiguous "proceed" or "do not + proceed" statement. diff --git a/.agents/skills/artifact/references/BMC.md b/.agents/skills/artifact/references/BMC.md new file mode 100644 index 0000000..6fe740d --- /dev/null +++ b/.agents/skills/artifact/references/BMC.md @@ -0,0 +1,21 @@ +# Business Model Canvas (BMC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Objectives the canvas operationalizes; cost/revenue must agree with its Cost–Benefit Assessment +- **SA** — Value Propositions, Customer Segments, Channels — cite S-IDs +- **BPMN** — Key Activities — cite the process that realizes them +- **KPI** — Measures of value proposition / revenue — cite KPI IDs + +## Required sections (after Metadata / Version History) + +1. **Purpose / Scope** — one paragraph. +2. **Canvas** — all 9 building blocks populated, none empty: Key Partners, + Key Activities, Key Resources, Value Propositions, Customer + Relationships, Channels, Customer Segments, Cost Structure, Revenue + Streams. Must stay reviewable as a single, concise overview. +3. **Assumptions** — explicit and testable (how would we know it is wrong?). +4. **Consistency Check** — Revenue Streams vs Cost Structure agree; + Segments/Channels match stakeholder groups from `SA`. + +Cite Business Case objectives (`[BC-001]`) instead of restating them. diff --git a/.agents/skills/artifact/references/BPMN.md b/.agents/skills/artifact/references/BPMN.md new file mode 100644 index 0000000..6c8cda9 --- /dev/null +++ b/.agents/skills/artifact/references/BPMN.md @@ -0,0 +1,22 @@ +# BPMN Process Model (BPMN) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The stated business goal/objective the process serves +- **SA** — Participants / lanes — cite S-IDs +- **UCD** — Forward link: actors and goals derived from this process + +## Required sections (after Metadata / Version History) + +1. **Purpose and Business Goal** — the Business Case objective realized + (cite `[BC-001]`). +2. **Participants (Pools / Lanes)** — every participant, mapped to an `SA` + stakeholder ID where one exists. +3. **Process Diagram** — valid BPMN 2.0. Message flows cross pool + boundaries; sequence flows do not. Keep the diagram source next to the + document (BPMN has no native markdown form) so it stays diffable. +4. **Element Table** — `Element | Type | Lane | Description` for every + event, activity and gateway. Every gateway states its type (XOR/AND/OR) + and its matching join. +5. **Path Coverage** — every path runs from a start event to a defined end + event; no dead ends. diff --git a/.agents/skills/artifact/references/DCD.md b/.agents/skills/artifact/references/DCD.md new file mode 100644 index 0000000..c1df83b --- /dev/null +++ b/.agents/skills/artifact/references/DCD.md @@ -0,0 +1,27 @@ +# Design Class Diagram (DCD) (DCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DM** — Concepts each design class refines — names must stay consistent +- **SD** — Messages that become method signatures +- **ERD** — Forward: persistence of the classes' attributes + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML class diagram: visibility markers (`+` `-` `#`) + on every member; association vs aggregation vs composition vs dependency + used per true ownership/lifecycle; multiplicity and navigability on every + association. +3. **Class Table** — `Class | Refines (Domain Model concept) | + Responsibility (one sentence) | Attributes | Operations`. SOLID applied; + no god classes; names consistent with the Domain Model. +4. **Method Traceability** — `Method signature | Operation Contract / SD + message`; every method traces to one. +5. **Pattern Annotations** — `Pattern | Classes | Rationale`, explicit. +6. **Dependency Check** — note confirming no circular class/package + dependencies (or an explicit justification). + +## Terminology + +Class and attribute names are the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/DICT.md b/.agents/skills/artifact/references/DICT.md new file mode 100644 index 0000000..9cdd288 --- /dev/null +++ b/.agents/skills/artifact/references/DICT.md @@ -0,0 +1,25 @@ +# Domain Dictionary (DICT) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The business goals the vocabulary serves +- **SA** — The Product Owner (and other business stakeholders) whose terms are recorded +- **DM** — Concepts whose PO terms are recorded + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the PO language (from the registry's `Languages` + section) and what the dictionary covers. +2. **Dictionary** — one row per term: + `PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in`. + The definition is written in the PO language. "Used as PO term in" and + "Used as IT term in" list artifact types (for example `DM` and `OC, SD, + DCD, ERD`). +3. **Rules** — the register split (PO term in the Domain Model, use cases and + user stories; IT term in the Operation Contract, Sequence Diagram, Design + Class Diagram and ERD) and one IT term per PO term. + +Keep the dictionary in step with the Domain Model: a new concept gets a row +in the same change. When the PO language is English, the PO and IT columns can +still differ (a business word against a technical one); keep the file anyway +when the two registers use different words. diff --git a/.agents/skills/artifact/references/DM.md b/.agents/skills/artifact/references/DM.md new file mode 100644 index 0000000..de35ff6 --- /dev/null +++ b/.agents/skills/artifact/references/DM.md @@ -0,0 +1,26 @@ +# Domain Model (DM) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — Source of every concept (noun phrases) — cite each `UC-*` used +- **UCD** — Scope check: actors/goals the model must cover +- **SSD** — Forward: system operations that act on these concepts + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — which use cases the model covers. +2. **Diagram** — PlantUML class diagram (or linked source) showing + **concepts, attributes and associations only — no operations**. + Business language throughout ("Sale", not "SaleTable"/"SaleClass"). +3. **Concept Table** — `Concept | Definition | Attributes | Source (use + case noun phrase / glossary)`. Every concept traces to a noun in a use + case or glossary. Attributes are simple domain data, not foreign-key-like + references (model those as associations). +4. **Association Table** — `From | Association name (with reading + direction) | To | Multiplicity (both ends)`. All multiplicities present. +5. **Generalizations** — only true "is-a" relationships, never inheritance + for code reuse. + +## Terminology + +Concept names are the PO terms recorded in the dictionary (`DICT`); add a row there for each new concept. diff --git a/.agents/skills/artifact/references/ERD.md b/.agents/skills/artifact/references/ERD.md new file mode 100644 index 0000000..27a98ac --- /dev/null +++ b/.agents/skills/artifact/references/ERD.md @@ -0,0 +1,22 @@ +# Entity Relationship Diagram (ERD) (ERD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DCD** — **Required source**: classes/attributes each entity persists; data types must match + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML entity diagram with PK/FK marked on every entity and + cardinality (1:1, 1:N) on every relationship; N:M relationships resolved + through explicit junction entities. +3. **Entity Table** — per entity: `Attribute | Type | PK/FK | Nullable | + Source (DCD class.attribute)`. Types consistent with the DCD; consistent + naming, no implementation-specific abbreviations. +4. **Relationship Table** — `Entity | Cardinality | Entity | FK | Rule`. +5. **Normalization Notes** — 3NF confirmed; any denormalization documented + with its performance justification. + +## Terminology + +Entity and column names follow the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/GOV.md b/.agents/skills/artifact/references/GOV.md new file mode 100644 index 0000000..d441bc6 --- /dev/null +++ b/.agents/skills/artifact/references/GOV.md @@ -0,0 +1,16 @@ +# Governance / ARB Workflow (GOV) + +One per project: `docs/sqa/governance.md`. Sections: Purpose, ARB Review +Workflow (submission → QC review → `RC-*` record → Go/No-Go → sign-off → +Traceability update), RACI by Artifact Category, Escalation Rules, Cadence. +The template has the standard text; fill the RACI. + +**RACI cells use exact stakeholder IDs from the project's Stakeholder +Analysis (`S`), never role names.** + +Related singletons (edit the existing file, no scaffold needed): +- `PRC` — `framework/process/review-checklist-process.md`, the narrative + review procedure. Framework-level; do not add project data. +- `CSG` — `docs/sqa/coding-standards-governance.md`. Scope is *defining and + governing* (not enforcing) language standards and style guides, as set by + the project Business Case's scope. diff --git a/.agents/skills/artifact/references/KPI.md b/.agents/skills/artifact/references/KPI.md new file mode 100644 index 0000000..7e5b01c --- /dev/null +++ b/.agents/skills/artifact/references/KPI.md @@ -0,0 +1,20 @@ +# KPI Definitions (KPI) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The Success Criteria row each KPI is aligned to (`[BC-001]`) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — which Business Case success criteria this document + operationalizes. +2. **KPI Definitions** — one row per KPI: `KPI ID | Name | SMART statement | + Baseline | Target | Business Case Success Criterion | Owner | Frequency & + Method | Data Source`. +3. **Thresholds** — per KPI: acceptable / at-risk / failing bounds. +4. **Reporting** — where results are reported and to whom. + +Rules: every KPI is SMART (reject goals/activities like "improve quality"); +baseline *and* target are both present; `Owner` is a stakeholder ID from +the project's Stakeholder Analysis (e.g. `S07`), never free text; give KPIs stable IDs (`KPI-01`, …) so +Milestones can cite them. diff --git a/.agents/skills/artifact/references/MIL.md b/.agents/skills/artifact/references/MIL.md new file mode 100644 index 0000000..9a8e621 --- /dev/null +++ b/.agents/skills/artifact/references/MIL.md @@ -0,0 +1,48 @@ +# Milestone / Gateway (MIL) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The objective / constraint (e.g. project duration) the milestone traces to +- **KPI** — The KPI IDs evaluated at this gate +- **US** — Forward: the user stories (`US-.`) that deliver this gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what decision this gate supports. +2. **Deliverable** — the concrete, tangible output evaluated (never just a date). +3. **Go / No-Go Criteria** — objectively checkable, one per row. +4. **Dependencies** — other milestones that must precede this one. +5. **Traceability** — the Business Case objective and/or KPI ID(s) it maps to. +6. **Ownership** — owner and approving reviewer as `SA` stakeholder IDs. +7. **Target Date** — consistent with Business Case constraints. +8. **Tasks** — the implementation-level breakdown for this phase, one row + per task: `# | Task | Summary | Needs its own Use Case/User Story? | + Reference`. `Task` is a short title (becomes the Issue title on sync); + `Summary` is one to three sentences of real context — what the task + actually involves and why, grounded in this project's own documents, not + a restatement of the title — so someone reading the Issue on Gitea/GitHub + understands it without opening this file (becomes the Issue body). + +## Breaking a phase into tasks + +Not every task needs a use case — only model one when the task is something +a user, or another system, actually does: + +- **Needs a use case/user story** — "User resets password", "Admin exports + customer report", "Payment service processes refund". Set the column to + `Yes` and put the `US-…`/`UC-…` ID in Reference. +- **Plain task, no use case** — "Refactor authentication middleware", "Add + database index", "Upgrade React version", "Fix null-pointer bug", "Add + unit tests", "Configure CI pipeline", "Optimize SQL query". Set the column + to `No` and leave Reference blank, or point at the design artifact it + implements (`DCD-…`, `OC-…`). + +The hierarchy is: Business goal → Feature/requirement → Use case/user story +→ Tasks. The use case explains *why* a feature exists; tasks explain *how* +the team implements it — most tasks stay at that level. + +## Syncing to Gitea/GitHub + +Each `MIL-*` gateway becomes one Milestone on the git host; its `## Tasks` +row become Issues assigned to that milestone. Use the `project-planning` +skill and `framework/scripts/sync-project.sh` — do not create these by hand. diff --git a/.agents/skills/artifact/references/OC.md b/.agents/skills/artifact/references/OC.md new file mode 100644 index 0000000..3b74009 --- /dev/null +++ b/.agents/skills/artifact/references/OC.md @@ -0,0 +1,27 @@ +# Operation Contract (OC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SSD** — **Required source**: each contract traces to exactly one SSD message +- **DM** — Classes/associations named in pre/postconditions +- **SD** — Forward: the design realizing each contract's postconditions + +## Required sections (after Metadata / Version History) + +One block per system operation, each containing: + +1. **Operation** — complete signature: name, parameter types, return type + (must match the SSD message). +2. **Cross References** — the SSD message it traces to (one contract per + message) and the Domain Model concepts touched. +3. **Preconditions** — required state before execution, expressed in Domain + Model terms. +4. **Postconditions** — state changes only, in Larman's style: *instance + created / instance associated / attribute modified*. Declarative ("what"), + never algorithmic ("how"); avoid vague text like "system processes the + request". +5. **Exceptions** — error conditions, each with the failing precondition. + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/PP.md b/.agents/skills/artifact/references/PP.md new file mode 100644 index 0000000..80784fe --- /dev/null +++ b/.agents/skills/artifact/references/PP.md @@ -0,0 +1,64 @@ +# Project Plan (PP) + +One per project: `docs/project-plan.md`. Schedules the phases (`MIL-*` +gateways) over the Business Case's timeline/duration constraint. + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` +checks this for you): + +- **BC** — the duration/constraint and objectives the plan schedules against +- **SA** — the communication cadence (e.g. sync frequency) the phase length follows +- **MIL** — every phase gateway the plan schedules (add each as it is created) +- **US** — the gateway user stories, once they exist + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what the plan schedules and over what constraint. +2. **Planning Assumptions** — start date, phase length, any resolved + conflicts the phasing follows (cite `SA`/`BC` where relevant). +3. **Gateway Schedule** — one row per phase: `Gateway | Document | Window | + Decision date | Owner | Stories | Main deliverable | Milestone`. One row + per `MIL-*`. `Milestone` links to that phase's Gitea/GitHub Milestone once + `sync-project.sh` has created it (see "Phases, tasks and the git host" + below); leave it blank until then. +4. **Timeline diagram** — a PlantUML Gantt chart, one bar per phase plus a + milestone marker per Go/No-Go decision. +5. **Scope Coverage** — maps each Business Case scope item to the gateway + that delivers it. +6. **Dependencies** — the gateway order (usually a simple chain) and what a + No-Go does to later dates. +7. **Plan Risks** — risks specific to the plan (schedule slip, dependency + risk), separate from the Business Case's own Risks table. +8. **Open Issues** — anything unresolved (start date to confirm, ambiguous + targets, missing checklists needed by a later phase). + +## Phases, tasks and the git host + +Each phase is a `MIL-*` gateway document (see `references/MIL.md`), which +also holds that phase's task breakdown in its own `## Tasks` section. The +Project Plan does not repeat the tasks — it only lists the phases and their +schedule, plus a link to each phase's Milestone once synced (see above). Use +the `project-planning` skill to break a phase into tasks and sync phases (as +Milestones) and tasks (as Issues) to Gitea/GitHub: + +```bash +bash framework/scripts/sync-project.sh # dry run — prints the plan, no network calls +bash framework/scripts/sync-project.sh --apply # creates/updates Milestones and Issues +``` + +`--apply` needs a token: `GITEA_TOKEN` (Gitea, a personal access token — not +a deploy key) or `gh auth login` (GitHub). `GITEA_TOKEN` can come from a +`.env` file at the project root (copy `.env.example`, never commit it). If +`.env` is missing or has no token when a sync is needed, ask the user for +one and create `.env` from `.env.example` with it rather than skipping the +sync or inventing a value. + +After a real `--apply` run, copy each Milestone's URL into the Gateway +Schedule's `Milestone` column (a content update, not a status change — it +does not need a new `## Version History` row). + +## Validating + +`PP` has no QC checklist yet (open item) — validate a plan against the +Business Case constraint it schedules and against `## Go / No-Go Criteria` +in each `MIL-*` it lists, rather than a dedicated checklist. diff --git a/.agents/skills/artifact/references/QC.md b/.agents/skills/artifact/references/QC.md new file mode 100644 index 0000000..e62d8ac --- /dev/null +++ b/.agents/skills/artifact/references/QC.md @@ -0,0 +1,44 @@ +# Quality Criteria checklist (QC) + +A QC checklist is the reusable review checklist for one artifact **type**. +It lives in the framework (`framework/qc/qc-.md`), is +project-independent, and **must never name or link a real artifact +instance** (no `[BC-001]`, no `RC-*`, no stakeholder IDs). Refer to types +generically ("the Stakeholder Analysis"). + +- **ID:** `QC--` (e.g. `QC-BC-001`); the version starts + at `001` and only changes when the checklist itself is revised. +- **Create:** `new-artifact.sh QC --id QC-XX-001 --file framework/qc/qc-.md + --cite QC-=framework/qc/qc-.md ...` +- **CrossReference:** the QC checklists immediately backward and forward in + Larman's chain, in both directions: + +``` +QC-SA → QC-BC → { QC-BMC, QC-BPMN, QC-KPI } → QC-MIL +QC-BC, QC-SA → QC-UCD → { QC-US, QC-UC } +QC-UC → QC-DM → QC-SSD → QC-OC → QC-SD → QC-DCD → QC-ERD +QC-ADR ↔ QC-DCD, QC-ERD +QC-DCD, QC-ADR → { QC-PY, QC-CL, QC-CPP, QC-CS } (language code checklists) +``` + +## Version History statuses + +The statuses are `Proposed`, `Accepted`, `Rejected` and `Deprecated`, as for every +artifact type (rule in the `artifact` skill, "Version History rule"). + +## Required sections (after Metadata / Version History) + +- **Purpose** — why this type matters, what decision it supports. +- **Quality Criteria Checklist** — `# | Criterion | Level | ISO/IEC 25010 + Characteristic(s) | Notes`. `Level` is `Mandatory` (baseline every instance + must meet) or `Optional` (advanced, may be deferred); a checklist with an + extra column (e.g. `Format`) keeps `Level` right after `Criterion`. Every criterion is tagged with at least one of + the eight ISO/IEC 25010:2023 characteristics (Functional Suitability, + Performance Efficiency, Compatibility, Usability, Reliability, Security, + Maintainability, Portability). Never add an untagged criterion. +- **Common Defects** — anti-patterns a reviewer rejects on sight. +- **Traceability Rule** — Backward / Forward bullets with the same `[QC-*]` + labels as `CrossReference`. + +Also add an entry to `framework/CHANGELOG.md`. Reviews of real instances are +recorded in the project as `RC-*` records, not in the checklist. diff --git a/.agents/skills/artifact/references/RC.md b/.agents/skills/artifact/references/RC.md new file mode 100644 index 0000000..4a3fced --- /dev/null +++ b/.agents/skills/artifact/references/RC.md @@ -0,0 +1,34 @@ +# SQA Review Record (RC) + +One record per review of a specific artifact instance against its QC +checklist. Create one for **every** artifact instance in the project. + +- **File:** `docs/sqa/reviews/rc--.md` +- **ID:** `RC-NNN`, sequential across all artifact types (the registry's + Next Available Version for `RC`). +- **Create:** `new-artifact.sh RC --file docs/sqa/reviews/rc-NNN-.md + --cite = --cite QC--001=framework/qc/.md` + +## Required sections (after Metadata / Version History) + +- **Artifact Under Review** — links to the instance and to the QC checklist + used. +- **Checklist Results** — `# | Criterion | Status (Pass/Fail/N-A) | + Evidence/Notes`, one row per criterion copied from the QC checklist, in + the same order. +- **Overall Verdict** — Go / Go-with-conditions / No-Go, with rationale. +- **Action Items** — `Action | Owner | Due`. `Owner` is a stakeholder ID from + the project's Stakeholder Analysis, never a role name. Every `Fail` and + every condition gets an item. + +## After the review + +- The reviewer must not be the artifact's author (see governance). +- Add or update the instance's row in the Traceability Matrix, including + this `RC-*` in "Last Reviewed". +- On **Go**, set the reviewed artifact's latest `## Version History` row to + `Accepted` and the row before it to `Deprecated` (`Approved` is not a + status). On Go-with-conditions the status stays `Proposed` until the action + items are closed. If the change is refused for good, set the row to + `Rejected` (the earlier `Accepted` row stays). +- Step-by-step narrative: `framework/process/review-checklist-process.md`. diff --git a/.agents/skills/artifact/references/SA.md b/.agents/skills/artifact/references/SA.md new file mode 100644 index 0000000..a7307d4 --- /dev/null +++ b/.agents/skills/artifact/references/SA.md @@ -0,0 +1,27 @@ +# Stakeholder Analysis (SA) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Business Case objectives each stakeholder concern traces to (Business Goal Alignment section) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — why the analysis exists and the methodology it follows. +2. **Stakeholder Summary Table** — `ID | Name | Role/Title | Organization | + Power Level | Interest Level | Quadrant | Primary Concern (Business + Language)`. Every row fully filled; no unclassified stakeholder. +3. **Power/Interest Classification Rationale** — narrative per quadrant, + consistent with the table. +4. **Primary Concerns and FURPS+ Mapping** — each concern in business + language *and* mapped to a FURPS+ attribute. +5. **Communication Requirements** — channel, frequency, deliverable type, + tied to a project phase or milestone. +6. **Conflicting Interests and Mitigations** — every conflict has a + mitigation. +7. **Traceability Analysis** — stakeholder → actor/use case mapping, and + business-goal alignment citing Business Case (`[BC-001]`) objectives. +8. **Sign-Off**. + +Stakeholder IDs (`S01`, `S02`, …) are **stable: never renumbered or reused**. +Every other artifact cites them for RACI, ownership and review assignment +(`AGENTS.md` rule 3). Add new stakeholders with the next free `S`. diff --git a/.agents/skills/artifact/references/SD.md b/.agents/skills/artifact/references/SD.md new file mode 100644 index 0000000..a8b2476 --- /dev/null +++ b/.agents/skills/artifact/references/SD.md @@ -0,0 +1,26 @@ +# Sequence Diagram (Design) (SD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **OC** — **Required source**: the contract whose postconditions each diagram realizes +- **DCD** — Forward: classes/methods these messages become + +## Required sections (after Metadata / Version History) + +One block per realized Operation Contract: + +1. **Realizes** — the contract (`[OC-…]`) and its operation name. +2. **Diagram** — PlantUML sequence diagram: sync (solid filled arrow), + async (open arrow), returns (dashed); activations matching the call + nesting; `create` / `destroy` shown for transient objects; + `loop` / `alt` / `opt` fragments for conditional/repeated behavior. +3. **Pattern Annotations** — table `Pattern (GRASP/GoF) | Applied to | + Rationale`. Patterns are labelled, never implicit. +4. **Postcondition Coverage** — `Postcondition | Satisfied by message`; + every postcondition of the contract must be covered. +5. **Responsibility Check** — a short note showing no god-object receives + all messages (low coupling, high cohesion). + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.agents/skills/artifact/references/SSD.md b/.agents/skills/artifact/references/SSD.md new file mode 100644 index 0000000..16e8f94 --- /dev/null +++ b/.agents/skills/artifact/references/SSD.md @@ -0,0 +1,21 @@ +# System Sequence Diagram (SSD) (SSD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — **Required source** of every SSD: cite the use case (name and ID) it depicts +- **DM** — Concepts behind message parameters / returned values +- **OC** — Forward: contract per system operation shown + +## Required sections (after Metadata / Version History) + +1. **Source Use Case** — name and ID (`[UC-…]`) and the specific scenario. +2. **Diagram** — PlantUML sequence diagram with just the actor and + `:System`; **no internal objects**. Dashed return arrows for operations + that produce a result. One scenario per diagram — separate diagrams for + alternate/exception flows (or state them out of scope). +3. **System Operations Table** — `Step | Message (verb phrase) | Parameters + | Return | Use case step`. Messages match the use case's main success + scenario step-for-step; justify any deviation. Message names become the + Operation Contract names. +4. **Lifecycle Notes** — creation/destruction of the System instance where + relevant (session/transaction scope). diff --git a/.agents/skills/artifact/references/TM.md b/.agents/skills/artifact/references/TM.md new file mode 100644 index 0000000..a21dc38 --- /dev/null +++ b/.agents/skills/artifact/references/TM.md @@ -0,0 +1,15 @@ +# Traceability Matrix (TM) + +One matrix per project: `docs/sqa/traceability-matrix.md`. It makes the +Business Case's cross-artifact traceability target measurable. + +## Required sections (after Metadata / Version History) + +- **Purpose**. +- **Traceability Table** — one row per artifact instance: + `Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward + Link) | Last Reviewed (RC-ID)`. Add or update a row whenever an instance + is created or reviewed. +- **Coverage Notes** — which types have no instance yet, and how to read + `-`: in Upstream it means foundational; in Downstream it means nothing + is built on it yet; in Last Reviewed it means no `RC-*` exists yet. diff --git a/.agents/skills/artifact/references/TRN.md b/.agents/skills/artifact/references/TRN.md new file mode 100644 index 0000000..64b2b7d --- /dev/null +++ b/.agents/skills/artifact/references/TRN.md @@ -0,0 +1,18 @@ +# Reviewer Training (TRN) + +The reusable training material for reviewers. It mitigates the "resistance to +standardized reviews" risk of the Business Case. Framework-level, like `PRC`: +no project data, no stakeholder IDs, no links to project artifacts. The +*record* that a session happened (date, attendees, result) is a project +document, written after the session. + +- **File:** `framework/process/reviewer-training.md` (singleton, version `001`). +- **Create:** `new-artifact.sh TRN`. +- **CrossReference:** `PRC` (the procedure the training teaches). + +## Required sections (after Metadata / Version History) + +Purpose, Audience and Prerequisites, Learning Objectives, Agenda (modules with +minutes), Module Notes, Exercises (each with input and expected result), +Assessment (how and pass criteria), Session Record (what to capture). +Exercises use a seeded, generic example, not a real project artifact. diff --git a/.agents/skills/artifact/references/TRR.md b/.agents/skills/artifact/references/TRR.md new file mode 100644 index 0000000..d8173ca --- /dev/null +++ b/.agents/skills/artifact/references/TRR.md @@ -0,0 +1,21 @@ +# Reviewer Training Record (TRR) + +The project's record that a reviewer training session happened: the evidence +that mitigates the "resistance to standardized reviews" risk and satisfies a +"training delivered and recorded" gateway criterion. It records one session +of the framework's training material (`TRN`); it holds project data +(stakeholder IDs, dates), so it lives in the project, not in the framework. + +- **File:** `docs/sqa/reviewer-training-record.md` (one per project; add a new + row under `## Attendees and Assessment` and a Version History row for each + further session). +- **Create:** `new-artifact.sh TRR --file docs/sqa/reviewer-training-record.md + --cite TRN-001=framework/process/reviewer-training.md`. +- **CrossReference:** `TRN` (the material that was taught). + +## Required sections (after Metadata / Version History) + +Session (material, date, facilitator, format), Attendees and Assessment +(stakeholder IDs, attended, Pass or Not yet against the assessment in the +material), Feedback, Follow-ups (action, owner as a stakeholder ID, due). +Fill the record after the session; never before. diff --git a/.agents/skills/artifact/references/UC.md b/.agents/skills/artifact/references/UC.md new file mode 100644 index 0000000..fcb5da8 --- /dev/null +++ b/.agents/skills/artifact/references/UC.md @@ -0,0 +1,35 @@ +# Use Case (UC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — Actor and use-case names must match it exactly +- **US** — Stories this use case decomposes into +- **SA** — Stakeholders & Interests — cite S-IDs +- **DM** — Forward: concepts derived from this use case's nouns +- **SSD** — Forward: the SSD depicting this use case's main scenario + +## Location + +`docs/uc-NNN/uc.md`, one folder per use case (create with +`new-artifact.sh UC --file docs/uc-NNN/uc.md`). The artifacts this use case +affects are saved in the same folder; see the `project-planning` skill, "Use +cases get their own folder". + +## Required sections (after Metadata / Version History) + +Pick the format explicitly (`Format: Brief | Casual | Fully Dressed`) and +state the **scope/level** (summary, user-goal, subfunction). Always: primary +actor, pre/postconditions, goal-perspective wording with no UI or +implementation detail. + +- **Brief** — a single paragraph summarizing only the main success scenario. +- **Casual** — informal multi-paragraph narrative; may mention some + alternate flows. +- **Fully Dressed** — all sections, in order: Scope, Level, Primary Actor, + Stakeholders and Interests (cite `SA` S-IDs), Preconditions, + Postconditions (success guarantee), Main Success Scenario (numbered + steps), Extensions / Alternative Flows (reference `<>` / + `<>` use cases), Special Requirements / Business Rules (per step), + Open Issues. + +Title and actor names must match `UCD` and `US` exactly. diff --git a/.agents/skills/artifact/references/UCD.md b/.agents/skills/artifact/references/UCD.md new file mode 100644 index 0000000..c7ce5bd --- /dev/null +++ b/.agents/skills/artifact/references/UCD.md @@ -0,0 +1,24 @@ +# Use Case Diagram (UCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Each actor traces to a stakeholder need — cite S-IDs +- **BC** — Scope / objectives the boundary reflects +- **US** — Forward: stories whose role must match an actor here +- **UC** — Forward: the use cases detailing each goal shown + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the system boundary in words. +2. **Diagram** — actors with correct stereotypes (`<>`, + `<>`), a labelled system boundary, `<>` / `<>` + used per UML 2.5.1 (not as generic "uses"). Embed PlantUML or link the + diagram source; no UI or implementation detail. +3. **Actor Table** — `Actor | Stereotype | Stakeholder ID (SA) | Goals + (use cases)`. No orphan actors: every actor appears in at least one use + case. +4. **Use Case Table** — `Use Case | Actor(s) | Goal`, names as **verb + phrases describing actor goals** ("Place Order"), not system operations + ("Validate Input"). +5. **Relationships** — every `<>` / `<>` with a one-line + justification. diff --git a/.agents/skills/artifact/references/US.md b/.agents/skills/artifact/references/US.md new file mode 100644 index 0000000..554f93a --- /dev/null +++ b/.agents/skills/artifact/references/US.md @@ -0,0 +1,22 @@ +# User Story (US) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — The story's role must match an actor defined here +- **UC** — The use case each story traces to +- **BC** — Objective / epic the story ultimately supports +- **MIL** — The gateway (epic) each story delivers — one or more stories per gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the epic(s) covered. +2. **Story List** — each story with a stable ID `US-.` (e.g. + `US-001.01`, so it cannot be confused with the document ID `US-001`): + - Statement: **As a** ``, **I want** ``, **so that** + `` — one goal per story, no implementation detail. + - **Acceptance Criteria** — clear and testable (Given/When/Then works). + - **Traces to** — the use case (`UC-…`) or epic it comes from; a gateway + (`MIL-…`) is an epic. + - **Size** — fits a single iteration. +3. **INVEST Check** — one line confirming Independent, Negotiable, + Valuable, Estimable, Small, Testable (flag any exception with reason). diff --git a/.agents/skills/artifact/templates/ADR.md b/.agents/skills/artifact/templates/ADR.md new file mode 100644 index 0000000..0bcae97 --- /dev/null +++ b/.agents/skills/artifact/templates/ADR.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + + + +## Decision + + + +## Consequences + +**Positive:** + +- + +**Negative:** + +- + +## Affected Artifacts + +- [] — , or a single "-" if none + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/BC.md b/.agents/skills/artifact/templates/BC.md new file mode 100644 index 0000000..4d8e302 --- /dev/null +++ b/.agents/skills/artifact/templates/BC.md @@ -0,0 +1,70 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Executive Summary + +## Methodological and Standards Foundation + +## Problem Statement + +## Business Opportunity + +## Objectives + +## Scope + +### In Scope + +### Out of Scope + +## Expected Benefits + +### Tangible Benefits + +### Intangible Benefits + +## Strategic Alignment + +## Success Criteria + +| # | Criterion | Target | Measure | +| --- | --- | --- | --- | + +## Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Assumptions + +## Constraints + +## Cost–Benefit Assessment + +| Costs | Benefits | +| --- | --- | + +## Stakeholders + +| Stakeholder ID (SA) | Interest in this project | +| --- | --- | + +## Recommendation + + — + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/BMC.md b/.agents/skills/artifact/templates/BMC.md new file mode 100644 index 0000000..fedac6a --- /dev/null +++ b/.agents/skills/artifact/templates/BMC.md @@ -0,0 +1,113 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose / Scope + +Operationalizes: ([BC-]) + +## Canvas + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key PartnersKey ActivitiesValue PropositionsCustomer RelationshipsCustomer Segments
+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+
Key ResourcesChannels
+ +
    +
  • +
+ 		+ +
    +
  • +
+
Cost StructureRevenue Streams
+ +
    +
  • +
+ 		+ +
    +
  • +
+
+ + +## Assumptions + +| # | Assumption | How it can be tested | +| --- | --- | --- | + +## Consistency Check + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/BPMN.md b/.agents/skills/artifact/templates/BPMN.md new file mode 100644 index 0000000..4744780 --- /dev/null +++ b/.agents/skills/artifact/templates/BPMN.md @@ -0,0 +1,41 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Business Goal + +Realizes: ([BC-]) + +## Participants + +| Pool / Lane | Participant | Stakeholder ID (SA) | +| --- | --- | --- | + +## Process Diagram + + + +## Element Table + +| Element | Type (event / activity / gateway) | Lane | Description | +| --- | --- | --- | --- | + +## Path Coverage + +| Path | Start event | End event | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/DCD.md b/.agents/skills/artifact/templates/DCD.md new file mode 100644 index 0000000..057cf8f --- /dev/null +++ b/.agents/skills/artifact/templates/DCD.md @@ -0,0 +1,50 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +class Controller { + -repo : Repository + +operationName(param : Type) : ReturnType +} +class Entity +Controller --> Entity : uses +@enduml +``` + +## Class Table + +| Class | Refines (Domain Model concept) | Responsibility | Attributes | Operations | +| --- | --- | --- | --- | --- | + +## Method Traceability + +| Method signature | Operation Contract / SD message | +| --- | --- | + +## Pattern Annotations + +| Pattern | Classes | Rationale | +| --- | --- | --- | + +## Dependency Check + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/DICT.md b/.agents/skills/artifact/templates/DICT.md new file mode 100644 index 0000000..44bf5bb --- /dev/null +++ b/.agents/skills/artifact/templates/DICT.md @@ -0,0 +1,35 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Maps each Product Owner (PO) term to its professional IT term. PO language: +. + +## Dictionary + +| PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in | +| --- | --- | --- | --- | --- | --- | +| | | | | DM | OC, SD, DCD, ERD | + +## Rules + +- The Domain Model, use cases and user stories use the PO term; the Operation + Contract, Sequence Diagram, Design Class Diagram and ERD use the IT term. +- One IT term per PO term and one PO term per IT term; no synonyms. + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/DM.md b/.agents/skills/artifact/templates/DM.md new file mode 100644 index 0000000..dfbf337 --- /dev/null +++ b/.agents/skills/artifact/templates/DM.md @@ -0,0 +1,54 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Covers: + +## Diagram + +Concepts, attributes and associations only — no operations. + +```plantuml +@startuml +class Order { + date + status +} +class Customer { + name +} +Customer "1" --> "0..*" Order : places +@enduml +``` + +## Concept Table + +| Concept | Definition | Attributes | Source (use case / glossary) | +| --- | --- | --- | --- | + +## Association Table + +| From | Association (reading direction) | To | Multiplicity | +| --- | --- | --- | --- | + +## Generalizations + +| General | Specializations | Is-a justification | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/ERD.md b/.agents/skills/artifact/templates/ERD.md new file mode 100644 index 0000000..25c0656 --- /dev/null +++ b/.agents/skills/artifact/templates/ERD.md @@ -0,0 +1,53 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +hide circle +entity CUSTOMER { + * id : int <> + -- + name : string +} +entity ORDER { + * id : int <> + -- + * customer_id : int <> +} +CUSTOMER ||--o{ ORDER : places +@enduml +``` + +## Entity Table + +### + +| Attribute | Type | PK/FK | Nullable | Source (DCD class.attribute) | +| --- | --- | --- | --- | --- | + +## Relationship Table + +| Entity | Cardinality | Entity | FK | Rule | +| --- | --- | --- | --- | --- | + +## Normalization Notes + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/GOV.md b/.agents/skills/artifact/templates/GOV.md new file mode 100644 index 0000000..a1bda5c --- /dev/null +++ b/.agents/skills/artifact/templates/GOV.md @@ -0,0 +1,68 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Defines how this project applies Quality Criteria (QC) checklists to real +artifact instances, producing SQA Review Records and Go/No-Go decisions. + +## ARB Review Workflow + +1. **Submission** — the artifact owner submits an instance for review, + identifying its type's QC checklist (`framework/qc/qc-*.md`). +2. **QC Checklist Review** — the assigned reviewer (see RACI) applies the + checklist criterion by criterion. +3. **Review Record** — the reviewer documents the outcome as an SQA Review + Record (`RC-*` under `docs/sqa/reviews/`). +4. **Go/No-Go Decision** — the Accountable role for the artifact category + decides; contested or cross-cutting cases escalate to the ARB Chair. +5. **Sign-off** — on **Go**, the artifact's `## Version History` gets an + `Accepted` row (the previous row becomes `Deprecated`). On **Go-with-conditions**, status stays `Proposed` until + the Action Items are closed. On **No-Go**, the artifact returns to its + owner. +6. **Traceability Update** — the Traceability Matrix is updated with the + instance and its `RC-*` reference. + +## RACI by Artifact Category + +Fill every cell with stakeholder IDs from the Stakeholder Analysis (`S`), +never role names. + +| Artifact Category | Responsible (runs the review) | Accountable (Go/No-Go owner) | Consulted | Informed | +| --- | --- | --- | --- | --- | +| Strategic (Stakeholder Analysis, Business Case, BMC) | S | S | S | S | +| Process/Business (BPMN, KPI, Milestones/Gateways) | S | S | S | S | +| Requirements (Use Case Diagram, User Story, Use Case) | S | S | S | S | +| Modeling/Design (Domain Model, SSD, Operation Contract, Sequence Diagram, DCD, ERD) | S | S | S | S | + +Cross-cutting escalations and disputed verdicts are Accountable to the ARB +Chair (`S`), overriding the category-level Accountable role. + +## Escalation Rules + +- A **No-Go** verdict, or any disagreement between the Responsible reviewer + and the category's Accountable owner, escalates to the ARB Chair. +- A reviewer may not review an instance they authored. +- Repeated No-Go verdicts (2 or more) on the same artifact type trigger a + review of the corresponding `QC-*` checklist itself. + +## Cadence + +- Reviews are triggered per artifact instance as it is produced or revised. +- QC checklists are reviewed annually. + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/KPI.md b/.agents/skills/artifact/templates/KPI.md new file mode 100644 index 0000000..3a8a89f --- /dev/null +++ b/.agents/skills/artifact/templates/KPI.md @@ -0,0 +1,35 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## KPI Definitions + +| KPI ID | Name | SMART statement | Baseline | Target | Business Case success criterion | Owner (S-ID) | Frequency & method | Data source | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| KPI-01 | | | | | | | | | + +## Thresholds + +| KPI ID | Acceptable | At risk | Failing | +| --- | --- | --- | --- | + +## Reporting + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/MIL.md b/.agents/skills/artifact/templates/MIL.md new file mode 100644 index 0000000..66f844b --- /dev/null +++ b/.agents/skills/artifact/templates/MIL.md @@ -0,0 +1,58 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Deliverable + + + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | + +## Dependencies + +| Depends on | Reason | +| --- | --- | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | | +| Approving reviewer | | + +## Target Date + +YYYY-MM-DD — + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | | | No | | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/OC.md b/.agents/skills/artifact/templates/OC.md new file mode 100644 index 0000000..f3c7622 --- /dev/null +++ b/.agents/skills/artifact/templates/OC.md @@ -0,0 +1,41 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Contract: + +| Item | Value | +| --- | --- | +| Operation | `operationName(param: Type): ReturnType` | +| Traces to | in [SSD-] | +| Domain Model concepts | ([DM-]) | + +**Preconditions** + +- + +**Postconditions** + +- A instance was created. +- was associated with . +- . was set to . + +**Exceptions** + +| Condition (failing precondition) | Outcome | +| --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/PP.md b/.agents/skills/artifact/templates/PP.md new file mode 100644 index 0000000..1ed287f --- /dev/null +++ b/.agents/skills/artifact/templates/PP.md @@ -0,0 +1,61 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Planning Assumptions + +- Week 1 starts ; the plan ends by , per the Business Case constraint. +- Phase length: . + +## Gateway Schedule + +| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | [MIL-] | | | | | | | + +```plantuml +@startgantt +Project starts +[Phase 1] starts and ends +[Phase 1 Go/No-Go] happens +@endgantt +``` + +## Scope Coverage + +| Business Case scope item | Gateway | +| --- | --- | + +## Dependencies + +``` + → → ... +``` + +## Plan Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Open Issues + +- + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/QC.md b/.agents/skills/artifact/templates/QC.md new file mode 100644 index 0000000..4c98f24 --- /dev/null +++ b/.agents/skills/artifact/templates/QC.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`. The latest reviewed row is `Accepted`; the row before it is `Deprecated`. + +--- + +## Purpose + + + +## Quality Criteria Checklist + +Level: **Mandatory** criteria are the baseline every instance must meet; **Optional** criteria are advanced and may be deferred. + +| # | Criterion | Level | ISO/IEC 25010 Characteristic(s) | Notes | +| --- | --- | --- | --- | --- | +| 1 | | Mandatory | | | + +## Common Defects + +- +- + +## Traceability Rule + +- Backward: ([QC--]) +- Forward: ([QC--]) + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/RC.md b/.agents/skills/artifact/templates/RC.md new file mode 100644 index 0000000..fd5f173 --- /dev/null +++ b/.agents/skills/artifact/templates/RC.md @@ -0,0 +1,39 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [] +- Checklist used: [] (`QC--`, e.g. `QC-BC-001`) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | | Pass/Fail/N-A | | + +## Overall Verdict + + — + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/SA.md b/.agents/skills/artifact/templates/SA.md new file mode 100644 index 0000000..0be8093 --- /dev/null +++ b/.agents/skills/artifact/templates/SA.md @@ -0,0 +1,54 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Stakeholder Summary Table + +| ID | Name | Role/Title | Organization | Power Level | Interest Level | Quadrant | Primary Concern (Business Language) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| S01 | | | | HIGH / MEDIUM / LOW | HIGH / MEDIUM / LOW | Manage Closely / Keep Satisfied / Keep Informed / Monitor | | + +## Power/Interest Classification Rationale + +## Primary Concerns and FURPS+ Mapping + +| ID | Concern | FURPS+ attribute | +| --- | --- | --- | + +## Communication Requirements + +| ID | Channel | Frequency | Deliverable | Phase / Milestone | +| --- | --- | --- | --- | --- | + +## Conflicting Interests and Mitigations + +| Conflict | Stakeholders | Mitigation | +| --- | --- | --- | + +## Traceability Analysis + +### Business Goal Alignment + +| Stakeholder | Concern | Business Case objective | +| --- | --- | --- | + +## Sign-Off + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/SD.md b/.agents/skills/artifact/templates/SD.md new file mode 100644 index 0000000..1df4e54 --- /dev/null +++ b/.agents/skills/artifact/templates/SD.md @@ -0,0 +1,47 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Sequence: + +**Realizes:** `operationName` in [OC-] + +### Diagram + +```plantuml +@startuml +participant ":Controller" as C +participant ":Collaborator" as X +C -> X : message(args) +activate X +X --> C : result +deactivate X +@enduml +``` + +### Pattern Annotations + +| Pattern (GRASP / GoF) | Applied to | Rationale | +| --- | --- | --- | + +### Postcondition Coverage + +| Postcondition (from contract) | Satisfied by message | +| --- | --- | + +### Responsibility Check + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/SSD.md b/.agents/skills/artifact/templates/SSD.md new file mode 100644 index 0000000..82ed747 --- /dev/null +++ b/.agents/skills/artifact/templates/SSD.md @@ -0,0 +1,40 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Source Use Case + + ([UC-]) — scenario:
+ +## Diagram + +```plantuml +@startuml +actor Actor as A +participant ":System" as S +A -> S : verbPhrase(param) +S --> A : result +@enduml +``` + +## System Operations + +| Step | Message | Parameters | Return | Use case step | +| --- | --- | --- | --- | --- | + +## Lifecycle Notes + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/TM.md b/.agents/skills/artifact/templates/TM.md new file mode 100644 index 0000000..7e5c810 --- /dev/null +++ b/.agents/skills/artifact/templates/TM.md @@ -0,0 +1,30 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Tracks backward/forward links between artifact instances so that the Business Case's +cross-artifact traceability success criterion is measurable. A row is added or +updated whenever an artifact instance is created or reviewed. + +## Traceability Table + +| Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | +| --- | --- | --- | --- | --- | +| [] | | [] | [] | [] | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/TRN.md b/.agents/skills/artifact/templates/TRN.md new file mode 100644 index 0000000..43ed3b4 --- /dev/null +++ b/.agents/skills/artifact/templates/TRN.md @@ -0,0 +1,60 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Audience and Prerequisites + + + +## Learning Objectives + +By the end, a participant can: + +- + +## Agenda + +| Module | Topic | Minutes | +| --- | --- | --- | +| 1 | | | + +## Module Notes + +### Module 1: + + + +## Exercises + +### Exercise 1: + + + +## Assessment + + + +## Session Record + +What is recorded after each session, in the project (never in the framework): +date, facilitator, attendees, result against the assessment, feedback and +follow-ups. + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/TRR.md b/.agents/skills/artifact/templates/TRR.md new file mode 100644 index 0000000..59b5771 --- /dev/null +++ b/.agents/skills/artifact/templates/TRR.md @@ -0,0 +1,43 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Session + +| Item | Value | +| --- | --- | +| Training material | [] | +| Date | | +| Facilitator | | +| Format and place | | + +## Attendees and Assessment + +| Stakeholder ID (SA) | Attended | Assessment (Pass / Not yet) | Notes | +| --- | --- | --- | --- | +| | | | | + +## Feedback + + + +## Follow-ups + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/UC.md b/.agents/skills/artifact/templates/UC.md new file mode 100644 index 0000000..90b9359 --- /dev/null +++ b/.agents/skills/artifact/templates/UC.md @@ -0,0 +1,55 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +**Format:** Brief | Casual | Fully Dressed (delete the unused sections below) + +## Brief + + + +## Casual + + + +## Fully Dressed + +- **Scope:** +- **Level:** summary | user-goal | subfunction +- **Primary Actor:** ]> +- **Stakeholders and Interests:** + - — +- **Preconditions:** +- **Postconditions (success guarantee):** + +### Main Success Scenario + +1. +2. + +### Extensions (Alternative / Exception Flows) + +- 2a. : + 1. (`<>` / `<>` ) + +### Special Requirements / Business Rules + +| Step | Rule | +| --- | --- | + +### Open Issues + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/UCD.md b/.agents/skills/artifact/templates/UCD.md new file mode 100644 index 0000000..bab5bfa --- /dev/null +++ b/.agents/skills/artifact/templates/UCD.md @@ -0,0 +1,50 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + + + +## Diagram + +```plantuml +@startuml +left to right direction +actor "Name" as A1 +rectangle "System Name" { + usecase "Verb-phrase goal" as UC1 +} +A1 --> UC1 +@enduml +``` + +## Actor Table + +| Actor | Stereotype | Stakeholder ID (SA) | Goals (use cases) | +| --- | --- | --- | --- | + +## Use Case Table + +| Use Case | Actor(s) | Goal | +| --- | --- | --- | + +## Relationships + +| From | Relationship (`<>` / `<>`) | To | Justification | +| --- | --- | --- | --- | + +--- + +@LINKS@ diff --git a/.agents/skills/artifact/templates/US.md b/.agents/skills/artifact/templates/US.md new file mode 100644 index 0000000..83ee098 --- /dev/null +++ b/.agents/skills/artifact/templates/US.md @@ -0,0 +1,36 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Story List + +### @ID@.01 — + +**As a** ]>, **I want** , **so that** . + +**Acceptance Criteria** + +- Given , when , then . + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-] or [MIL-] | fits one iteration | none | + +## INVEST Check + +--- + +@LINKS@ diff --git a/.agents/skills/coding-conventions/SKILL.md b/.agents/skills/coding-conventions/SKILL.md new file mode 100644 index 0000000..3e199bf --- /dev/null +++ b/.agents/skills/coding-conventions/SKILL.md @@ -0,0 +1,94 @@ +--- +name: coding-conventions +description: Programming conventions for writing or reviewing source code — naming, layout, formatting and language idioms — for Python, C, C++, C# and Shell (bash). Use when writing, editing, reviewing or refactoring code in one of those languages, choosing names, setting up a formatter/linter config, or adding conventions for another language. Holds the rules shared by every language and points to a per-language sub-skill. +--- + +# Coding Conventions + +One skill for all languages. This file holds what is true in every language; +everything specific to one language is in a sub-skill that is read only when +that language is in hand: + +| Language | Sub-skill | QC checklist | +| --- | --- | --- | +| Python | `references/python.md` | `framework/qc/qc-programming-python.md` (`QC-PY-001`) | +| C | `references/c.md` | `framework/qc/qc-programming-c.md` (`QC-CL-001`) | +| C++ | `references/cpp.md` | `framework/qc/qc-programming-cpp.md` (`QC-CPP-001`) | +| C# | `references/csharp.md` | `framework/qc/qc-programming-csharp.md` (`QC-CS-001`) | +| Shell (bash) | `references/shell.md` | `framework/qc/qc-programming-shell.md` (`QC-SH-001`) | + +Read the sub-skill for the language you are working in, then write or review +the code. To review, use the language's QC checklist and record the result as +an `RC-*` (see the `artifact` skill). + +## Precondition: a planned task + +Before writing or editing code under `src/` or `tests/`, name the task row +(`MIL-NNN`, task N) or the synced issue, and the use case or design artifact +it implements, or say it is a plain technical task. If you cannot, refuse and +use the `project-planning` skill instead (rule: `framework/process/plan-first-gate.md`). +Reviewing code needs no task. + +## Rules for every language + +1. **The existing code wins.** In a file or project that already has a + convention, follow it, even if the sub-skill says otherwise. Do not mix + styles within a file; do not reformat code you are not changing. +2. **Naming follows the language, not your habits.** Casing differs per + language (table below). Never carry one language's casing into another. +3. **A name says what, not how.** Name by purpose in the domain's language + (IT Professional English, as the registry's `Languages` section says), not by + type or implementation (`customer_list`, not `arr2`). +4. **Length follows scope.** Short names (`i`, `n`) only for tiny scopes; + wider scope, longer name. No abbreviations except ones the whole domain + uses (`id`, `url`, `http`). +5. **Booleans read as a question:** `is_valid`, `has_items`, `can_retry` + (cased per language). No negated names (`is_not_ready`). +6. **Functions are verbs, types are nouns.** A function that returns a value + without side effects may be a noun (`total`, `Total`) where the language + community does so. +7. **Formatting is done by the formatter,** not by hand and not in review + comments. Each sub-skill names the formatter and linter; commit its + configuration file with the code. +8. **Comments say why,** never what the code already says. Public APIs get + the language's documentation-comment form. +9. **No dead or commented-out code, no unexplained magic numbers.** Name the + constant. +10. **Errors are handled or propagated, never swallowed.** Each sub-skill says + how its language does this. + +## Casing at a glance + +| Element | Python | C | C++ | C# | +| --- | --- | --- | --- | --- | +| Type / class | `PascalCase` | `snake_case_t` | `PascalCase` | `PascalCase` | +| Function / method | `snake_case` | `snake_case` | `snake_case` | `PascalCase` | +| Variable / parameter | `snake_case` | `snake_case` | `snake_case` | `camelCase` | +| Constant | `UPPER_SNAKE` | `UPPER_SNAKE` | `kPascalCase` | `PascalCase` | +| Private member | `_leading` | file-scope `static` | `trailing_` | `_camelCase` | +| Namespace / module | `snake_case` module | `mod_` prefix | `snake_case` | `PascalCase` | +| File | `snake_case.py` | `snake_case.c/.h` | `snake_case.cpp/.h` | `PascalCase.cs` | + +The table is a summary; the sub-skill is authoritative. Shell (bash) is not in +the table: functions and variables are `snake_case`, constants and environment +variables `UPPER_SNAKE`, files `kebab-case.sh`. + +## Governance boundary + +Conventions are **defined and governed** here but **not enforced** by this +framework: writing a linter or CI job that enforces them is outside the +framework's scope. The formatter and linter names in each sub-skill are the +recommended tools, not a pipeline. A new or changed convention follows the +process in the project's Coding Standards Governance document and is recorded +in `framework/CHANGELOG.md`. No project data belongs in this skill. + +## Adding a language + +1. Add `references/.md` with these sections: Standard base, Naming, + Formatting, Language rules, Errors, Tests, Tooling. +2. Add `framework/qc/qc-.md` (`QC--001`) using the `QC` type + of the `artifact` skill, tagging every criterion with an ISO/IEC 25010:2023 + characteristic and a Level. +3. Add the row to the table above, the casing table, and a row for the + language in `framework/registry/artifact-catalog.md`; note it in + `framework/CHANGELOG.md`; run `bash framework/scripts/install-skills.sh`. diff --git a/.agents/skills/coding-conventions/references/c.md b/.agents/skills/coding-conventions/references/c.md new file mode 100644 index 0000000..14375ca --- /dev/null +++ b/.agents/skills/coding-conventions/references/c.md @@ -0,0 +1,71 @@ +# C conventions + +C has no single official style guide. This sub-skill fixes one consistent +style built on common practice; MISRA C and SEI CERT C are the references for +safety-critical or security-sensitive code. + +## Standard base + +ISO C11 or C17 as set by the project's compiler flag (`-std=c11`). Compile +with warnings on (`-Wall -Wextra -Wpedantic`); treat warnings as errors in +release builds. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Function, variable, parameter | `snake_case` | `parse_header`, `byte_count` | +| Public symbol | module prefix plus `snake_case` (C has no namespaces) | `stay_reader_open()` | +| File-local function / variable | `static`, no prefix needed | `static int next_token(...)` | +| Type (`struct`, `enum`, `typedef`) | `snake_case_t`, module prefix for public types | `stay_reader_t` | +| Enum constant, macro, constant | `UPPER_SNAKE` with the module prefix | `STAY_READER_OK` | +| Header / source file | `snake_case.h` / `snake_case.c`, same base name | `stay_reader.h` | +| Header guard | `MODULE_FILE_H` (or `#pragma once` if the project allows) | `STAY_READER_H` | + +- Do not use reserved identifiers: a leading underscore followed by an + uppercase letter, any double underscore, or a leading underscore at file + scope. +- POSIX reserves the `_t` suffix; keep the module prefix on public types so + they cannot collide. +- Macros are a last resort; prefer `static inline` functions and `enum` or + `const` values. + +## Formatting + +- One formatter configuration for the project (`clang-format`); 4 spaces (or + the project's setting), no tabs mixed in. +- Braces on every `if`, `else`, `for`, `while`, even for one statement. +- One declaration per line; declare variables at first use, initialised. +- Headers: include what you use, only what you use; public headers are + self-contained; add `extern "C"` guards when C++ code consumes them. + +## Language rules + +- Check every return value that can fail; check every allocation. +- Every `malloc`/`open`/`lock` has one clear owner and one matching release; + release on every exit path (single exit or `goto cleanup`). +- Use `size_t` for sizes and indices, fixed-width types (``) for + data layout, `const` wherever data is not modified, `restrict` only with + care. +- Bounds are explicit: pass a length with every buffer; use `snprintf`, + never `sprintf`, `strcpy` or `gets`. +- No undefined behaviour: no signed overflow, no out-of-range shifts, no use + after free, no uninitialised reads. +- Avoid global mutable state; if unavoidable, `static` and documented. + +## Errors + +Return a status code (an `enum`) or `-1`/`NULL` plus an error out-parameter; +document which in the header. Never ignore a failing call. Read `errno` +immediately after the failing call. + +## Tests + +A unit-test framework (for example Unity or CMocka); run under sanitizers +(`-fsanitize=address,undefined`) in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` or `cppcheck`, compiler warnings, sanitizers. + +Review with `QC-CL-001`. diff --git a/.agents/skills/coding-conventions/references/cpp.md b/.agents/skills/coding-conventions/references/cpp.md new file mode 100644 index 0000000..8e164ab --- /dev/null +++ b/.agents/skills/coding-conventions/references/cpp.md @@ -0,0 +1,70 @@ +# C++ conventions + +## Standard base + +ISO C++17 or later as set by the project (`-std=c++20`); the C++ Core +Guidelines are the rule source. C++ has no official naming style, so the +style below is used unless the project already has another (rule 1 of the +overall skill). + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Class, struct, enum, concept, type alias | `PascalCase` | `StayReader`, `Stay` | +| Function, method, variable, parameter | `snake_case` | `read_stays()`, `byte_count` | +| Data member (private) | `snake_case` with trailing underscore | `buffer_` | +| Struct public data member | `snake_case`, no underscore | `check_in` | +| Constant (`constexpr`, namespace-scope `const`) | `kPascalCase` | `kMaxRetries` | +| Enum class value | `PascalCase` | `Status::NotFound` | +| Namespace | short `snake_case`; no `using namespace` in headers | `billing` | +| Template parameter | `PascalCase` | `typename ItemT` | +| Macro | `UPPER_SNAKE` with project prefix; avoid macros | `BILLING_ASSERT` | +| Header / source file | `snake_case.h` / `snake_case.cpp`, same base name | `stay_reader.h` | +| Header guard | `#pragma once` (or `PROJECT_PATH_FILE_H`) | | + +## Formatting + +- `clang-format` with one checked-in config; 4 spaces (or the project's + setting); braces on every control-flow body. +- Include order: matching header, project headers, third party, standard + library; each group sorted. +- One declaration per line; declare at first use, initialise with `{}`. + +## Language rules + +- **Ownership:** RAII everywhere. No owning raw pointers, no naked + `new`/`delete`; use `std::unique_ptr` by default, `std::shared_ptr` only for + real shared ownership, created with `std::make_unique`/`make_shared`. +- Follow the rule of zero; if you define one of destructor, copy or move, + define or delete all five. +- Pass by `const&` (large, read-only) or by value (small or sink); use + `std::span` and `std::string_view` for non-owning views, `std::optional` for + "maybe", `std::variant` for alternatives. +- `const` and `constexpr` by default; mark single-argument constructors + `explicit`; mark `override`/`final`; `[[nodiscard]]` on results that must + be used. +- Prefer algorithms and range-for over hand-written loops; `enum class` over + plain `enum`; `nullptr` over `NULL` or `0`; `using` over `typedef`. +- No C-style casts; use `static_cast` and friends. No mutable global state. +- Headers are self-contained and contain declarations, templates and + `inline` definitions only. + +## Errors + +Use exceptions for exceptional failures, or `std::expected` and error codes +where the project forbids exceptions; one choice per project. Destructors +never throw. Catch by `const&`; never `catch (...)` without rethrowing or +logging. + +## Tests + +GoogleTest, Catch2 or doctest; run under sanitizers (`address`, `undefined`) +in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` with the Core Guidelines checks, compiler +warnings (`-Wall -Wextra -Wpedantic`), sanitizers. + +Review with `QC-CPP-001`. diff --git a/.agents/skills/coding-conventions/references/csharp.md b/.agents/skills/coding-conventions/references/csharp.md new file mode 100644 index 0000000..88abb3b --- /dev/null +++ b/.agents/skills/coding-conventions/references/csharp.md @@ -0,0 +1,72 @@ +# C# conventions + +## Standard base + +Microsoft's C# coding conventions and .NET Framework Design Guidelines, with +the analyzers that ship in the SDK. Target the language version of the +project's `LangVersion` / target framework. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Namespace | `PascalCase`, matches folder path | `Billing.Stays` | +| Class, struct, record, enum, delegate | `PascalCase` (nouns) | `StayReader` | +| Interface | `I` + `PascalCase` | `IStayReader` | +| Method, property, event, public field | `PascalCase` | `ReadStays()`, `CheckIn` | +| Constant, `static readonly` | `PascalCase` | `MaxRetries` | +| Enum value | `PascalCase`; `[Flags]` enums are plural | `Status.NotFound` | +| Parameter, local variable | `camelCase` | `byteCount` | +| Private / internal field | `_camelCase` | `_buffer` | +| Generic type parameter | `T` or `T` + `PascalCase` | `T`, `TKey` | +| Async method | ends in `Async` | `ReadStaysAsync()` | +| Exception, attribute | end in `Exception` / `Attribute` | `InvalidDateException` | +| Boolean | `Is`, `Has`, `Can` prefix | `IsActive` | +| File | the type's name, one top-level type per file | `StayReader.cs` | + +- Two-letter acronyms are upper case (`IO`); longer ones are `PascalCase` + (`Xml`, `Http`). + +## Formatting + +- `.editorconfig` checked in; `dotnet format` applies it. 4 spaces, Allman + braces, braces on every control-flow body. +- File-scoped namespaces (`namespace X;`); `using` directives outside the + namespace, `System` first. +- `var` when the type is obvious from the right-hand side, explicit type + otherwise. + +## Language rules + +- Enable nullable reference types (`enable`) and treat + nullable warnings as errors; do not suppress with `!` without a comment. +- `IDisposable` owners use `using`; implement the dispose pattern only when + needed. +- `async`/`await` all the way; no `.Result` or `.Wait()`; no `async void` + except event handlers; pass `CancellationToken` through public async APIs. +- Prefer properties over public fields, `readonly` and `init` for + immutability, `record` for value-like data, pattern matching and switch + expressions over long `if` chains. +- LINQ for queries, loops for side effects; do not enumerate a sequence twice. +- String interpolation over concatenation; `StringBuilder` in loops; + `DateTimeOffset` over `DateTime` for points in time; `decimal` for money. +- XML documentation comments (`///`) on public types and members. + +## Errors + +Throw specific exceptions (`ArgumentNullException`, custom types); validate +arguments at the public boundary (`ArgumentNullException.ThrowIfNull`). Catch +the narrowest type; `throw;` (not `throw ex;`) to rethrow. Never an empty +`catch`. + +## Tests + +xUnit, NUnit or MSTest; names like `Method_Condition_Expected`; one behaviour +per test; no dependence on order, time or the network. + +## Tooling + +`dotnet format`, the .NET analyzers (`AnalysisLevel`, `EnforceCodeStyleInBuild`) +and optionally StyleCop.Analyzers, configured in `.editorconfig`. + +Review with `QC-CS-001`. diff --git a/.agents/skills/coding-conventions/references/python.md b/.agents/skills/coding-conventions/references/python.md new file mode 100644 index 0000000..e262961 --- /dev/null +++ b/.agents/skills/coding-conventions/references/python.md @@ -0,0 +1,66 @@ +# Python conventions + +## Standard base + +PEP 8 (style), PEP 257 (docstrings), PEP 484 and later (type hints). Target +the Python version declared in `pyproject.toml`. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Package / module | short `snake_case` | `billing`, `stay_reader.py` | +| Class, exception | `PascalCase`; exceptions end in `Error` | `StayReader`, `InvalidDateError` | +| Function, method, variable, parameter | `snake_case` | `total_price`, `read_stays()` | +| Constant (module level) | `UPPER_SNAKE` | `MAX_RETRIES` | +| Internal (not public API) | one leading underscore | `_parse_row` | +| Type variable | short `PascalCase`; `_co` / `_contra` for variance | `T`, `KeyT`, `ItemT_co` | +| Boolean | `is_`, `has_`, `can_` prefix | `is_active` | +| Test file / function | `test_.py` / `test__` | `test_total_when_empty` | + +- Avoid name mangling (`__name`) unless you need it to prevent a subclass clash. +- Never use `l`, `O` or `I` as single-letter names. +- Do not shadow builtins (`list`, `id`, `type`); add a trailing underscore + (`type_`) only as a last resort. + +## Formatting + +- 4 spaces, no tabs. Maximum line length set once in the formatter config + (88 with `ruff format`; 79 if the project follows PEP 8 strictly). +- Imports at the top, grouped standard library / third party / local, one + blank line between groups, no wildcard imports. +- Double quotes for strings unless the formatter says otherwise. +- Trailing commas in multi-line literals and calls. + +## Language rules + +- Annotate every function signature (parameters and return, `-> None` too). + Modern syntax: `X | None`, `list[str]`. Avoid `Any` without a comment. +- `pathlib` over `os.path`; f-strings over `%` or `.format`; `enum` over + magic strings; `dataclass` (frozen where possible) over ad-hoc dicts. +- No mutable default arguments; no bare `except:`; no `print` for logging + (use `logging`). +- Use context managers (`with`) for files, locks and connections. +- Prefer comprehensions over `map`/`filter` with lambdas; keep them simple. +- Docstrings (PEP 257) on public modules, classes and functions; say what, + not how. + +## Errors + +Raise specific exceptions; catch the narrowest type; re-raise with +`raise ... from err` to keep the cause. Do not use exceptions for normal +control flow. + +## Tests + +`pytest`; one behaviour per test; `tmp_path` for files; fakes over mocks where +a simple fake is possible; tests do not depend on order or on the network. + +## Tooling + +`ruff` (lint and format) and `mypy --strict` (types), configured in +`pyproject.toml`. Architecture rules (layers, ports, dataframes) are in +`.agents/rules/python.md` and the `python-developer` agent; this sub-skill +covers naming and style only. + +Review with `QC-PY-001`. diff --git a/.agents/skills/coding-conventions/references/shell.md b/.agents/skills/coding-conventions/references/shell.md new file mode 100644 index 0000000..aa8a728 --- /dev/null +++ b/.agents/skills/coding-conventions/references/shell.md @@ -0,0 +1,62 @@ +# Shell conventions (bash) + +## Standard base + +Bash 4 or later, POSIX `test` semantics through `[[ ]]`. Start every script +with `#!/usr/bin/env bash` and `set -euo pipefail`. State the bash version and +the external tools it needs in the header comment. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Script file | `kebab-case.sh`, executable | `check-plan.sh`, `new-artifact.sh` | +| Function | `snake_case`, a verb | `read_registry`, `die` | +| Local variable, parameter | `snake_case`, declared with `local` | `msgfile`, `changed` | +| Constant, environment variable | `UPPER_SNAKE` | `PLAN_GATE`, `PROJECT_ROOT` | +| Boolean | `is_` / `has_` prefix, value `0` or `1` | `is_enabled=1` | + +- Name a script and its functions by what they do, not how. +- Do not shadow a command with a function of the same name. + +## Formatting + +- 2 spaces, no tabs. One command per line; `then` and `do` on the same line as + `if` and `for`. Keep lines near 80 characters; break long pipelines at `|`. +- Format with `shfmt -i 2 -ci`; lint with `shellcheck`. Commit the project's + `.editorconfig` or `.shellcheckrc` with the code. + +## Language rules + +- **Quote every expansion** (`"$var"`, `"${arr[@]}"`); use arrays, not + space-separated strings, for lists. Use `[[ ]]`, not `[ ]`, and `$(...)`, + not backticks. +- Declare function variables `local`; no globals except constants. +- Parse options with `case` and `shift`, check required arguments with + `"${1:?usage: ...}"`, and print a usage line on bad input. +- Read input with `read -r`; iterate files with globs or `find -print0`, never + by parsing `ls`. +- Use `mktemp` for temporary files and remove them with `trap ... EXIT`; never + a fixed `/tmp` name. + +## Errors and exit codes + +- Errors go to standard error, start with `error:`, say what is wrong and what + to do, and end the script with a non-zero exit code (`die` helper). +- `0` is success, `1` a failed check or bad input, `2` a usage error; document + any other code in the header. +- Never swallow a failure with `|| true` without a comment that says why. + +## Safety + +- A script that changes state outside its own directory defaults to a dry run + or asks for an explicit flag (`--apply`, `--force`); say so in the header. +- Never echo a token or password, put one on a command line, or commit one; + read secrets from the environment or a gitignored file. +- Do not `eval` input; do not build a command from unvalidated text. + +## Tools + +Formatter `shfmt`, linter `shellcheck`, syntax check `bash -n`. These are the +recommended tools, not a pipeline: enforcing them in CI is outside this +framework's scope. diff --git a/.agents/skills/project-planning/SKILL.md b/.agents/skills/project-planning/SKILL.md new file mode 100644 index 0000000..d1c429d --- /dev/null +++ b/.agents/skills/project-planning/SKILL.md @@ -0,0 +1,278 @@ +--- +name: project-planning +description: Plan a project (or a new phase of one) in phases with tasks, and sync those phases and tasks to Gitea or GitHub as Milestones and Issues. Use when starting a new project, adding or updating a phase/gateway, breaking a phase down into tasks, deciding whether a task needs its own use case or user story, or asked to create/update project milestones or issues on the git host. +--- + +# Project Planning + +Plans a project as phases (gateways), each phase as a set of tasks, and +keeps those phases and tasks in sync with the git host's own project +management (Milestones and Issues). It builds on the `artifact` skill's +`PP` (Project Plan) and `MIL` (Milestone/Gateway) types. + +## Domain language first + +Before planning, find the Product Owner's (PO's) domain language. Take it from +the first of these that states it: + +1. the user's prompt; +2. a file the user included or that the project already has (the `Languages` + section of `docs/artifact-registry.md`). + +If none states it, **ask the user for it** and stop planning until it is +answered; never assume one. Record the answer in the registry's `Languages` +section. If it differs from the project's working language, the high-level +artifacts are also kept in it (see the registry's translation list). + +## Start here + +Before planning or building anything, check that the baseline exists (the +`docs/artifact-registry.md` rows and files): the Business Case (`BC`), the +Stakeholder Analysis (`SA`), the Project Plan (`PP`) and at least one +milestone (`MIL`). If one is missing, create it first, in that order, with +`new-artifact.sh` (it refuses when a type in the catalog's `Requires` column +is missing). + +A "build X" request is planning-first. Produce the phases, tasks and issues, +show the dry run of `sync-project.sh`, and ask for a go-ahead before any code +is written; running `--apply` is the user's decision. Only the user can waive +the plan, in chat, for that request; the waiver does not carry over. The rule +is defined in `framework/process/plan-first-gate.md`. + +## The hierarchy + +``` +Business goal → Feature/requirement → Use case/user story → Tasks +``` + +The use case/user story explains **why** a feature exists; tasks explain +**how** the team implements it. Not every task needs a use case: + +- **Needs a use case/user story** — the task is something a user, or + another system, actually does: "User resets password", "Admin exports + customer report", "Payment service processes refund". +- **Plain task, no use case** — purely technical/implementation work: + "Refactor authentication middleware", "Add database index", "Upgrade + React version", "Fix null-pointer bug", "Add unit tests", "Configure CI + pipeline", "Optimize SQL query". + +When in doubt, ask: does this row describe a goal an actor is pursuing, or +a step the team takes to build something? Goals get a use case; steps stay +a plain task. + +## Use cases get their own folder + +Each use case lives in `docs/uc-NNN/` (`UC-001` → `docs/uc-001/`), together +with the artifacts that belong to it. Nothing about a use case goes in a +shared `docs/use-cases/` folder. + +1. **Create the folder and the use case:** + `bash framework/scripts/new-artifact.sh UC --file docs/uc-001/uc.md`. +2. **Create only the artifacts this use case affects,** in this order, each in + the same folder with a fixed file name. Skip any it does not touch (no + `erd.md` if nothing is stored; no `dm.md` if it adds no concept). + + | Order | Type | File | Create when the use case… | + | --- | --- | --- | --- | + | 1 | `SSD` | `ssd.md` | has system interaction to show (almost always) | + | 2 | `DM` | `dm.md` | introduces or changes domain concepts | + | 3 | `OC` | `oc.md` | has system operations that change state | + | 4 | `SD` | `sd.md` | needs a collaboration design for an operation | + | 5 | `DCD` | `dcd.md` | adds or changes design classes | + | 6 | `ERD` | `erd.md` | adds or changes persisted data | + + ```bash + bash framework/scripts/new-artifact.sh SSD --file docs/uc-001/ssd.md + bash framework/scripts/new-artifact.sh DM --file docs/uc-001/dm.md --cite UC-001=docs/uc-001/uc.md + ``` + + `new-artifact.sh` cites only the artifacts in the same use-case folder + (and project-level ones); for `DM`, `DCD` and `ERD`, add the use case and + sibling artifacts by hand with `--cite`. Each gets its own ID (the next + version in the registry, e.g. `DM-002`) and its own `RC-*` review. +3. **Reconcile with the project models.** The use-case artifacts are a scoped + view; the project-level `docs/domain-model.md`, `docs/dcd.md` and + `docs/erd.md` are the consolidated truth. When the use case's `DM`, `DCD` + or `ERD` are done, compare each with its project-level document: + - add the new concepts, classes, attributes and entities; change the ones + the use case modified; + - keep names identical to the existing ones, and resolve any conflict + with another use case's model instead of duplicating the element; + - give each project-level document a new `## Version History` row (Change: + which use case caused it), and create it from the first use case's + document if it does not exist yet; + - if nothing needs to change, say so in the use case's task and PR + description ("project DM/DCD/ERD unchanged: "). + +## Planning a project (or a new phase) + +1. **Phases are gateways.** Each phase is a `MIL-*` document (the `artifact` + skill's `MIL` type): purpose, deliverable, Go/No-Go criteria, dependencies, + ownership, target date. Create one with + `bash framework/scripts/new-artifact.sh MIL --file docs/milestones/mil--.md`. +2. **The plan schedules the phases.** `docs/project-plan.md` (the `artifact` + skill's `PP` type) lists every phase with its window and owner, and holds + the overall timeline diagram. Create it once with + `bash framework/scripts/new-artifact.sh PP`. +3. **Break each phase into tasks.** In the phase's `## Tasks` section, add + one row per task using the hierarchy rule above. Tasks that need a use + case or user story get one created first (`UC`/`US` types; a use case + follows "Use cases get their own folder" below), then are referenced from + the Tasks row; plain tasks just describe the work. +4. **Sync to the git host.** Run the sync tool (below) to create or update + the corresponding Milestones and Issues. Do this whenever a phase or its + tasks change — the tool is idempotent (matches by title, never creates a + duplicate). + +## Syncing to Gitea/GitHub + +```bash +bash framework/scripts/sync-project.sh # prints the plan only — no network calls +bash framework/scripts/sync-project.sh --milestone MIL-002 # limit to one phase +bash framework/scripts/sync-project.sh --apply # actually create/update on the git host +``` + +- **Default is a dry run**: it parses `docs/milestones/mil-*.md` and prints + what would be created or updated. Nothing is sent anywhere. +- **`--apply`** performs the real requests. It needs: + - **Gitea** (default — detected from `origin`'s hostname): `GITEA_TOKEN` + env var, a personal access token. This is an HTTP API call (milestones, + issues) — a deploy key cannot be used, since deploy keys only + authenticate SSH git transport (clone/fetch/push), not the REST API. + Scope the token to issues only if your Gitea version supports scoped + tokens, rather than a full-account one. + - **GitHub** (detected when `origin` is on github.com, or pass + `--host github`): the `gh` CLI, already logged in (`gh auth login`). +- **`--with-project`** additionally tries to create/attach a Kanban Project + board. This is best-effort: some Gitea versions (confirmed on 1.27.3) show + Projects/Kanban only in the web UI and expose **no REST API for it at + all**, so this always fails there — check your server's own + `https:///swagger.v1.json` for any `project` path if unsure. GitHub + Projects (v2) needs `gh` with the `project` scope. Either way the script + warns and continues; Milestones and Issues are unaffected. Where there's + no API, create the board by hand at `https://///projects`. +- Read the script's header comment for the full flag list, including + `--owner`, `--repo`, `--api-base` to override auto-detection. + +`--apply` is an outward-facing, hard-to-reverse action (it creates real +Milestones/Issues on the git host) — run it yourself once you're ready, or +ask explicitly for it to be run. + +## Branching before commits + +**Never commit, push or open a PR unless the user asks.** The user reviews +the working-tree changes first; finish the edits, summarise them and stop. +Everything below (branching, closing keywords, resolving commit links, the +PR) describes how to do those steps once the user has asked for them; it is +not permission to start them. + +Never commit directly on `main`. This is enforced locally by a pre-commit +hook (`framework/githooks/pre-commit`) once +`bash framework/scripts/install-git-hooks.sh` has been run in this clone — +run it once per clone; it points `core.hooksPath` at the versioned +`framework/githooks/` instead of the per-clone, untracked `.git/hooks/`. +The hook refuses the commit with a pointer back to this section; a rare, +deliberate exception can bypass it with `ALLOW_MAIN_COMMIT=1 git commit`. + +Before the first commit of a piece of work, create and switch to a new +branch, then commit there: + +```bash +git checkout -b +# ... commits ... +git push -u origin +``` + +- Name the branch for the gateway/task it covers, kebab-case, e.g. + `g2-kpi-bmc-bpmn` or `mil-002-kpi-baseline` — short enough to read in a + PR list, specific enough to say what it's for. +- Open a PR (`gh pr create` on GitHub, or the Gitea equivalent) instead of + merging straight to `main`; this project's own history is a merged PR + per phase (e.g. "Merge pull request 'Close G1 inception baseline...'"), + so keep following that pattern. +- This applies to every commit, not just gateway/task work — if in doubt + whether the current branch is `main`, check (`git branch --show-current`) + before committing. + +## Closing tasks from commits + +When a commit finishes the work for a task that `sync-project.sh` has +already synced as an Issue, reference that Issue number in the commit +message so Gitea/GitHub auto-closes it once that commit lands on the +default branch (`main`) — via the PR merge required by "Branching before +commits" above, not by pushing the closing keyword to a feature branch. +Use `Refs #N` instead when the commit only touches the task without +finishing it — that links the commit without closing. + +- **One issue per commit:** use `Closes #5`. +- **Several issues closed by the same commit:** put one `Closes #N` per + line, not a comma-separated list (`Closes #5, #6, #7` only closed `#5` on + a confirmed live Gitea instance — the comma form is not reliably parsed): + + ``` + Closes #5 + Closes #6 + Closes #7 + ``` +- Get each issue number either from the most recent `sync-project.sh` / + `sync-project.sh --apply` output (it prints `updated issue #N` / + `created issue #N` per task) or, if that's not at hand, from the git + host's issue list for the milestone. +- Match commits to issues by the task row they implement — one task row in + a `MIL-*` document's `## Tasks` section is one Issue, so a commit that + completes that row's work closes that Issue. +- Don't guess an issue number; if it isn't known from a recent sync or a + lookup, ask rather than omit or fabricate one. +- **After pushing a multi-issue closing commit, verify** each issue's state + came back `closed` (e.g. `GET /repos///issues/` with + `GITEA_TOKEN`) rather than assuming the whole list closed; close any that + didn't with a direct `PATCH .../issues/` `{"state":"closed"}` call. + +## Pull requests close the issues they complete + +Every PR must close the Issues its work finishes, so the board matches +reality once it merges. Before opening (or updating) a PR: + +1. **List the issues the branch completes.** Go through the task rows the + branch implements (`git log main..HEAD`, plus the `## Tasks` of the + `MIL-*` it belongs to) and get each Issue number as described in "Closing + tasks from commits". +2. **Put one closing line per issue in the PR description**, one per line, + never comma-separated: + + ``` + Closes #5 + Closes #6 + ``` + + Use `Refs #N` for an issue the PR only touches. A PR that finishes no + issue says so explicitly ("No issue closed: ") instead of saying + nothing. +3. **Ask, don't guess.** If an issue number is unknown or a task is only + partly done, ask rather than omit or invent one. Leave a partly done task + open and note what remains. +4. **After the merge, verify** that each issue is `closed` (the check in + "Closing tasks from commits") and close any stragglers by hand. Also make + sure the finished task rows are reflected in the `MIL-*` document and, when + every task of a phase is closed, that the Milestone is closed too. + +5. **Resolve pending commit links before the PR** (see "Version History rule" + in the `artifact` skill): commit, run + `bash framework/scripts/resolve-pending-commits.sh `, then + commit the result as a follow-up commit. +6. **Never ask for, offer or perform the merge.** A PR needs a reviewer: ask + the user to open the PR / request a review, and stop there. Merging, + enabling auto-merge and "shall I merge?" are not yours to do. + +Closing keywords in the PR description and in commit messages both count on +Gitea and GitHub; they only take effect when the PR merges into the default +branch. + +## Files this skill touches + +- `docs/project-plan.md` — `PP`, via the `artifact` skill. +- `docs/milestones/mil-*.md` — `MIL`, via the `artifact` skill, each with a + `## Tasks` section. +- `docs/uc-NNN/*.md` (the use case and its `SSD`, `DM`, `OC`, `SD`, `DCD`, `ERD`), `docs/user-stories.md` — only for tasks that need one; plus `docs/domain-model.md`, `docs/dcd.md`, `docs/erd.md` when reconciling. +- `framework/scripts/sync-project.sh` — never edited per project; propose + changes upstream in the framework. diff --git a/.claude/skills/.framework-skills b/.claude/skills/.framework-skills new file mode 100644 index 0000000..5dad221 --- /dev/null +++ b/.claude/skills/.framework-skills @@ -0,0 +1,3 @@ +artifact +coding-conventions +project-planning diff --git a/.claude/skills/artifact/SKILL.md b/.claude/skills/artifact/SKILL.md new file mode 100644 index 0000000..9fb92f3 --- /dev/null +++ b/.claude/skills/artifact/SKILL.md @@ -0,0 +1,113 @@ +--- +name: artifact +description: Create, edit or review any project document artifact — Business Case, Stakeholder Analysis, KPI, Business Model Canvas, BPMN, milestones/gateways, use case diagram, user stories, use cases, domain model, SSD, operation contracts, sequence diagrams, DCD, ERD, ADRs, SQA review records, traceability matrix, governance, QC checklists. Scaffolds the file with the correct ID, CrossReference and links, then gives the required sections for that type. +--- + +# Artifact + +Every artifact is a markdown file with `## Metadata` and `## Version History` +tables, a registered short-name ID, and links only at the bottom. Types and +their related types are in `framework/registry/artifact-catalog.md`; this +project's file locations and next versions are in `docs/artifact-registry.md`. + +## Creating an artifact + +1. Find the type's short name (`BC`, `SA`, `MIL`, `DM`, `ADR`, `RC`, …) in + the catalog. If the type is new, add it to the catalog and the registry. +2. Scaffold — this sets the ID, `CrossReference` (only artifacts that exist), + the bottom link block and the registry version: + + ```bash + bash framework/scripts/new-artifact.sh [--file ] [--title ""] [--cite =]... + ``` + + `--file` is required for multi-document types (`MIL`, `UC`, `ADR`, `RC`, + `QC`); single-document types default to the registry's `Primary File`. + The script refuses to overwrite an existing file. +3. Read `framework/.agents/skills/artifact/references/.md` (cite-for + hints and required sections), then fill in the file. Keep the sections in + order and replace every ``. + +## Editing an artifact + +Append a row to `## Version History` on every change (a status change such as +`Proposed` → `Accepted`, or a content change). To re-check `CrossReference`, +run `bash framework/scripts/find-crossreferences.sh `. When the first +instance of a type is created, add it to the `CrossReference` of every +existing artifact that lists that type as a candidate (with a new Version +History row). + +### Version History rule + +The table keeps only the **two latest** changes; git holds the rest. Columns: + +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-01 | Accepted | Jane Doe | S02 | Added Risks section
Fixed scope wording | [a1b2c3d] | + +- **Status** — `Proposed`, `Accepted`, `Rejected` or `Deprecated` for every + artifact type (`ADR` also has `Superseded by ADR-NNNN`); `Approved` is not + used. A new row starts `Proposed`. When the review gives Go, that row + becomes `Accepted` and the row before it becomes `Deprecated`, so at most + one row is `Accepted`: the latest reviewed one. If the reviewer refuses the + change for good (not a No-Go that returns it for rework), the row becomes + `Rejected`; the earlier `Accepted` row stays `Accepted` and nothing is + deprecated. +- **Change** — a short summary of what this row changed; several lines are + separated with `
`. +- **Commit** — the commit that made the change, as a reference-style link + defined at the bottom of the file + (`[a1b2c3d]: https://///commit/`; Gitea and + GitHub use the same `/commit/` form). A row cannot contain its own commit + hash, so a new row says `pending` until the commit exists. Leave it + `pending` and do not commit: only when the user asks for a commit, then: + 1. commit the edited documents; + 2. run `bash framework/scripts/resolve-pending-commits.sh ...`, which + replaces `pending` with the link to that commit and adds the definition; + 3. commit the result as a follow-up commit, before opening the PR. Do not + amend: an amend changes the hash, so the link would point at a commit + that is never pushed. +- When adding a third row, delete the oldest row and its now-unused commit + link definition. Never rewrite the content of the two retained rows other + than resolving `pending` and setting Status to `Accepted` / `Deprecated` + after a Go review. +- Every document uses this format, including QC checklists. A file still in the + old four-column format is converted when next edited (old row kept as + `Initial version`, plus a new row for the conversion). + +## Reviewing an artifact + +1. Take the QC checklist named in the catalog (`framework/qc/qc-*.md`). +2. Create the review record: `new-artifact.sh RC …`, following + `references/RC.md`. +3. Add or update the instance's row in the Traceability Matrix. + +## Rules + +- **Links:** all links are reference-style, defined once at the bottom of the + file after a final `---`, labelled by the target's ID (`[SA-001]`), never + inline. No links → omit the block. +- **CrossReference:** cite only artifacts that exist now. Empty if none. +- **People:** use exact stakeholder IDs from the project's Stakeholder + Analysis (`S01`) for owners, reviewers and RACI. Never invent role names. +- **Diagrams** are PlantUML blocks; check them with + `bash framework/scripts/render-diagrams.sh --server ` (or set + `PLANTUML_URL`) before review. +- **QC checklists** are framework files: every criterion is tagged with an + ISO/IEC 25010:2023 characteristic, and they never mention real instances. +- **IDs:** `-`, 3 digits (`BC-001`); `ADR` uses 4 digits; + `RC` is sequential across all types; QC is `QC--`. +- **Language:** artifacts carry no `DomainLanguages` row. The PO language and + the register of each artifact type are in the `Languages` section of + `docs/artifact-registry.md` (registers: `IT Executive English` for + high-level, `IT Professional English` for technical). +- **Translations:** when the PO language is not English, each type the + registry marks "Also kept as a PO-language file" is also saved as + `..md` beside its English source (`business-case.da.md`). + A translation keeps the source's ID and sections, uses the PO terms from the + dictionary (`DICT`), and has a Version History row naming the source version + it follows. The English file is authoritative; update the translation in the + same change. If the PO language is English, no translations are made. +- **Dictionary:** the Domain Model uses the PO term; the Operation Contract, + Sequence Diagram, Design Class Diagram and ERD use the IT term. Every pair is + recorded in `docs/dictionary.md` (`DICT`). diff --git a/.claude/skills/artifact/references/ADR.md b/.claude/skills/artifact/references/ADR.md new file mode 100644 index 0000000..eb9e4c3 --- /dev/null +++ b/.claude/skills/artifact/references/ADR.md @@ -0,0 +1,25 @@ +# Architecture Decision Record (ADR) + +Files: `docs/adr/adr-NNNN-kebab-case-title.md`. `NNNN` is 4-digit and +sequential; the ID is `ADR-NNNN` and must match the filename number (an +intentional exception to the usual 3-digit IDs). Use +`new-artifact.sh ADR --file docs/adr/adr-NNNN-title.md`. + +Cite in `CrossReference` the artifacts this decision is about (pass each +with `--cite =`); ADR has no fixed candidate list. + +## Required sections (after Metadata / Version History) + +- **Context** — the problem, the options evaluated and the forces + (cost, risk, constraints). +- **Decision** — the outcome in one or two sentences, no hedging. +- **Consequences** — two bold labels, **Positive:** and **Negative:**, each + with a bullet list. +- **Affected Artifacts** — other artifacts impacted, as `[ID]` links, or a + single `-` if none. + +Allowed statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, +`Superseded by ADR-NNNN`; no others (an ADR is never `Approved`). Status +changes (`Proposed` → `Accepted` → `Deprecated` / `Superseded by ADR-NNNN`, or +`Proposed` → `Rejected`) are new rows in `## Version History` (only the two +latest are kept; earlier ones stay in git); never rewrite a retained row. diff --git a/.claude/skills/artifact/references/BC.md b/.claude/skills/artifact/references/BC.md new file mode 100644 index 0000000..f3f07da --- /dev/null +++ b/.claude/skills/artifact/references/BC.md @@ -0,0 +1,45 @@ +# Business Case (BC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Stakeholders section — cite S-IDs instead of re-describing roles +- **BMC** — Cost–Benefit Assessment must agree with its cost/revenue blocks +- **BPMN** — Forward: the process that realizes the objectives +- **KPI** — Success Criteria — each criterion is operationalized by a KPI +- **UCD** — Forward: scope expressed as actors and goals + +## Required sections (after Metadata / Version History) + +In this order: + +1. **Executive Summary** — one paragraph framing the problem and the + proposed solution. +2. **Methodological and Standards Foundation** — states the methodology + (e.g. Larman's *Applying UML and Patterns*) and quality standards (e.g. + ISO/IEC 25002/25010/25019) the rest of the document and downstream + artifacts are built on. +3. **Problem Statement** — the recurring problems that justify the project. +4. **Business Opportunity** — what becomes possible if the problem is + solved. +5. **Objectives** — concrete, verifiable statements of what the project + will achieve. +6. **Scope** — split into `## In Scope` and `## Out of Scope` subsections. +7. **Expected Benefits** — split into `### Tangible Benefits` and + `### Intangible Benefits`. +8. **Strategic Alignment** — how the project supports organizational goals. +9. **Success Criteria** — a table with explicit, measurable targets (not + aspirations). +10. **Risks** — a table with `Risk | Impact | Mitigation` columns; every + risk must have a mitigation. +11. **Assumptions** — bullet list, kept distinct from Constraints. +12. **Constraints** — bullet list, kept distinct from Assumptions. +13. **Cost–Benefit Assessment** — a table (`Costs | Benefits`); may be + qualitative if explicitly justified. +14. **Stakeholders** — a table referencing exact stakeholder IDs from the + project's Stakeholder Analysis (e.g. `S01`, `S07`) if `SA` exists per + the CrossReference check above. **Never re-describe stakeholder roles + inline instead of citing their IDs** — this is the single most common + defect found when reviewing Business Cases (see `QC-BC-001`'s Common + Defects). +15. **Recommendation** — a single, unambiguous "proceed" or "do not + proceed" statement. diff --git a/.claude/skills/artifact/references/BMC.md b/.claude/skills/artifact/references/BMC.md new file mode 100644 index 0000000..6fe740d --- /dev/null +++ b/.claude/skills/artifact/references/BMC.md @@ -0,0 +1,21 @@ +# Business Model Canvas (BMC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Objectives the canvas operationalizes; cost/revenue must agree with its Cost–Benefit Assessment +- **SA** — Value Propositions, Customer Segments, Channels — cite S-IDs +- **BPMN** — Key Activities — cite the process that realizes them +- **KPI** — Measures of value proposition / revenue — cite KPI IDs + +## Required sections (after Metadata / Version History) + +1. **Purpose / Scope** — one paragraph. +2. **Canvas** — all 9 building blocks populated, none empty: Key Partners, + Key Activities, Key Resources, Value Propositions, Customer + Relationships, Channels, Customer Segments, Cost Structure, Revenue + Streams. Must stay reviewable as a single, concise overview. +3. **Assumptions** — explicit and testable (how would we know it is wrong?). +4. **Consistency Check** — Revenue Streams vs Cost Structure agree; + Segments/Channels match stakeholder groups from `SA`. + +Cite Business Case objectives (`[BC-001]`) instead of restating them. diff --git a/.claude/skills/artifact/references/BPMN.md b/.claude/skills/artifact/references/BPMN.md new file mode 100644 index 0000000..6c8cda9 --- /dev/null +++ b/.claude/skills/artifact/references/BPMN.md @@ -0,0 +1,22 @@ +# BPMN Process Model (BPMN) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The stated business goal/objective the process serves +- **SA** — Participants / lanes — cite S-IDs +- **UCD** — Forward link: actors and goals derived from this process + +## Required sections (after Metadata / Version History) + +1. **Purpose and Business Goal** — the Business Case objective realized + (cite `[BC-001]`). +2. **Participants (Pools / Lanes)** — every participant, mapped to an `SA` + stakeholder ID where one exists. +3. **Process Diagram** — valid BPMN 2.0. Message flows cross pool + boundaries; sequence flows do not. Keep the diagram source next to the + document (BPMN has no native markdown form) so it stays diffable. +4. **Element Table** — `Element | Type | Lane | Description` for every + event, activity and gateway. Every gateway states its type (XOR/AND/OR) + and its matching join. +5. **Path Coverage** — every path runs from a start event to a defined end + event; no dead ends. diff --git a/.claude/skills/artifact/references/DCD.md b/.claude/skills/artifact/references/DCD.md new file mode 100644 index 0000000..c1df83b --- /dev/null +++ b/.claude/skills/artifact/references/DCD.md @@ -0,0 +1,27 @@ +# Design Class Diagram (DCD) (DCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DM** — Concepts each design class refines — names must stay consistent +- **SD** — Messages that become method signatures +- **ERD** — Forward: persistence of the classes' attributes + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML class diagram: visibility markers (`+` `-` `#`) + on every member; association vs aggregation vs composition vs dependency + used per true ownership/lifecycle; multiplicity and navigability on every + association. +3. **Class Table** — `Class | Refines (Domain Model concept) | + Responsibility (one sentence) | Attributes | Operations`. SOLID applied; + no god classes; names consistent with the Domain Model. +4. **Method Traceability** — `Method signature | Operation Contract / SD + message`; every method traces to one. +5. **Pattern Annotations** — `Pattern | Classes | Rationale`, explicit. +6. **Dependency Check** — note confirming no circular class/package + dependencies (or an explicit justification). + +## Terminology + +Class and attribute names are the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/DICT.md b/.claude/skills/artifact/references/DICT.md new file mode 100644 index 0000000..9cdd288 --- /dev/null +++ b/.claude/skills/artifact/references/DICT.md @@ -0,0 +1,25 @@ +# Domain Dictionary (DICT) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The business goals the vocabulary serves +- **SA** — The Product Owner (and other business stakeholders) whose terms are recorded +- **DM** — Concepts whose PO terms are recorded + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the PO language (from the registry's `Languages` + section) and what the dictionary covers. +2. **Dictionary** — one row per term: + `PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in`. + The definition is written in the PO language. "Used as PO term in" and + "Used as IT term in" list artifact types (for example `DM` and `OC, SD, + DCD, ERD`). +3. **Rules** — the register split (PO term in the Domain Model, use cases and + user stories; IT term in the Operation Contract, Sequence Diagram, Design + Class Diagram and ERD) and one IT term per PO term. + +Keep the dictionary in step with the Domain Model: a new concept gets a row +in the same change. When the PO language is English, the PO and IT columns can +still differ (a business word against a technical one); keep the file anyway +when the two registers use different words. diff --git a/.claude/skills/artifact/references/DM.md b/.claude/skills/artifact/references/DM.md new file mode 100644 index 0000000..de35ff6 --- /dev/null +++ b/.claude/skills/artifact/references/DM.md @@ -0,0 +1,26 @@ +# Domain Model (DM) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — Source of every concept (noun phrases) — cite each `UC-*` used +- **UCD** — Scope check: actors/goals the model must cover +- **SSD** — Forward: system operations that act on these concepts + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — which use cases the model covers. +2. **Diagram** — PlantUML class diagram (or linked source) showing + **concepts, attributes and associations only — no operations**. + Business language throughout ("Sale", not "SaleTable"/"SaleClass"). +3. **Concept Table** — `Concept | Definition | Attributes | Source (use + case noun phrase / glossary)`. Every concept traces to a noun in a use + case or glossary. Attributes are simple domain data, not foreign-key-like + references (model those as associations). +4. **Association Table** — `From | Association name (with reading + direction) | To | Multiplicity (both ends)`. All multiplicities present. +5. **Generalizations** — only true "is-a" relationships, never inheritance + for code reuse. + +## Terminology + +Concept names are the PO terms recorded in the dictionary (`DICT`); add a row there for each new concept. diff --git a/.claude/skills/artifact/references/ERD.md b/.claude/skills/artifact/references/ERD.md new file mode 100644 index 0000000..27a98ac --- /dev/null +++ b/.claude/skills/artifact/references/ERD.md @@ -0,0 +1,22 @@ +# Entity Relationship Diagram (ERD) (ERD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **DCD** — **Required source**: classes/attributes each entity persists; data types must match + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope**. +2. **Diagram** — PlantUML entity diagram with PK/FK marked on every entity and + cardinality (1:1, 1:N) on every relationship; N:M relationships resolved + through explicit junction entities. +3. **Entity Table** — per entity: `Attribute | Type | PK/FK | Nullable | + Source (DCD class.attribute)`. Types consistent with the DCD; consistent + naming, no implementation-specific abbreviations. +4. **Relationship Table** — `Entity | Cardinality | Entity | FK | Rule`. +5. **Normalization Notes** — 3NF confirmed; any denormalization documented + with its performance justification. + +## Terminology + +Entity and column names follow the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/GOV.md b/.claude/skills/artifact/references/GOV.md new file mode 100644 index 0000000..d441bc6 --- /dev/null +++ b/.claude/skills/artifact/references/GOV.md @@ -0,0 +1,16 @@ +# Governance / ARB Workflow (GOV) + +One per project: `docs/sqa/governance.md`. Sections: Purpose, ARB Review +Workflow (submission → QC review → `RC-*` record → Go/No-Go → sign-off → +Traceability update), RACI by Artifact Category, Escalation Rules, Cadence. +The template has the standard text; fill the RACI. + +**RACI cells use exact stakeholder IDs from the project's Stakeholder +Analysis (`S`), never role names.** + +Related singletons (edit the existing file, no scaffold needed): +- `PRC` — `framework/process/review-checklist-process.md`, the narrative + review procedure. Framework-level; do not add project data. +- `CSG` — `docs/sqa/coding-standards-governance.md`. Scope is *defining and + governing* (not enforcing) language standards and style guides, as set by + the project Business Case's scope. diff --git a/.claude/skills/artifact/references/KPI.md b/.claude/skills/artifact/references/KPI.md new file mode 100644 index 0000000..7e5b01c --- /dev/null +++ b/.claude/skills/artifact/references/KPI.md @@ -0,0 +1,20 @@ +# KPI Definitions (KPI) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The Success Criteria row each KPI is aligned to (`[BC-001]`) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — which Business Case success criteria this document + operationalizes. +2. **KPI Definitions** — one row per KPI: `KPI ID | Name | SMART statement | + Baseline | Target | Business Case Success Criterion | Owner | Frequency & + Method | Data Source`. +3. **Thresholds** — per KPI: acceptable / at-risk / failing bounds. +4. **Reporting** — where results are reported and to whom. + +Rules: every KPI is SMART (reject goals/activities like "improve quality"); +baseline *and* target are both present; `Owner` is a stakeholder ID from +the project's Stakeholder Analysis (e.g. `S07`), never free text; give KPIs stable IDs (`KPI-01`, …) so +Milestones can cite them. diff --git a/.claude/skills/artifact/references/MIL.md b/.claude/skills/artifact/references/MIL.md new file mode 100644 index 0000000..9a8e621 --- /dev/null +++ b/.claude/skills/artifact/references/MIL.md @@ -0,0 +1,48 @@ +# Milestone / Gateway (MIL) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — The objective / constraint (e.g. project duration) the milestone traces to +- **KPI** — The KPI IDs evaluated at this gate +- **US** — Forward: the user stories (`US-.`) that deliver this gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what decision this gate supports. +2. **Deliverable** — the concrete, tangible output evaluated (never just a date). +3. **Go / No-Go Criteria** — objectively checkable, one per row. +4. **Dependencies** — other milestones that must precede this one. +5. **Traceability** — the Business Case objective and/or KPI ID(s) it maps to. +6. **Ownership** — owner and approving reviewer as `SA` stakeholder IDs. +7. **Target Date** — consistent with Business Case constraints. +8. **Tasks** — the implementation-level breakdown for this phase, one row + per task: `# | Task | Summary | Needs its own Use Case/User Story? | + Reference`. `Task` is a short title (becomes the Issue title on sync); + `Summary` is one to three sentences of real context — what the task + actually involves and why, grounded in this project's own documents, not + a restatement of the title — so someone reading the Issue on Gitea/GitHub + understands it without opening this file (becomes the Issue body). + +## Breaking a phase into tasks + +Not every task needs a use case — only model one when the task is something +a user, or another system, actually does: + +- **Needs a use case/user story** — "User resets password", "Admin exports + customer report", "Payment service processes refund". Set the column to + `Yes` and put the `US-…`/`UC-…` ID in Reference. +- **Plain task, no use case** — "Refactor authentication middleware", "Add + database index", "Upgrade React version", "Fix null-pointer bug", "Add + unit tests", "Configure CI pipeline", "Optimize SQL query". Set the column + to `No` and leave Reference blank, or point at the design artifact it + implements (`DCD-…`, `OC-…`). + +The hierarchy is: Business goal → Feature/requirement → Use case/user story +→ Tasks. The use case explains *why* a feature exists; tasks explain *how* +the team implements it — most tasks stay at that level. + +## Syncing to Gitea/GitHub + +Each `MIL-*` gateway becomes one Milestone on the git host; its `## Tasks` +row become Issues assigned to that milestone. Use the `project-planning` +skill and `framework/scripts/sync-project.sh` — do not create these by hand. diff --git a/.claude/skills/artifact/references/OC.md b/.claude/skills/artifact/references/OC.md new file mode 100644 index 0000000..3b74009 --- /dev/null +++ b/.claude/skills/artifact/references/OC.md @@ -0,0 +1,27 @@ +# Operation Contract (OC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SSD** — **Required source**: each contract traces to exactly one SSD message +- **DM** — Classes/associations named in pre/postconditions +- **SD** — Forward: the design realizing each contract's postconditions + +## Required sections (after Metadata / Version History) + +One block per system operation, each containing: + +1. **Operation** — complete signature: name, parameter types, return type + (must match the SSD message). +2. **Cross References** — the SSD message it traces to (one contract per + message) and the Domain Model concepts touched. +3. **Preconditions** — required state before execution, expressed in Domain + Model terms. +4. **Postconditions** — state changes only, in Larman's style: *instance + created / instance associated / attribute modified*. Declarative ("what"), + never algorithmic ("how"); avoid vague text like "system processes the + request". +5. **Exceptions** — error conditions, each with the failing precondition. + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/PP.md b/.claude/skills/artifact/references/PP.md new file mode 100644 index 0000000..80784fe --- /dev/null +++ b/.claude/skills/artifact/references/PP.md @@ -0,0 +1,64 @@ +# Project Plan (PP) + +One per project: `docs/project-plan.md`. Schedules the phases (`MIL-*` +gateways) over the Business Case's timeline/duration constraint. + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` +checks this for you): + +- **BC** — the duration/constraint and objectives the plan schedules against +- **SA** — the communication cadence (e.g. sync frequency) the phase length follows +- **MIL** — every phase gateway the plan schedules (add each as it is created) +- **US** — the gateway user stories, once they exist + +## Required sections (after Metadata / Version History) + +1. **Purpose** — what the plan schedules and over what constraint. +2. **Planning Assumptions** — start date, phase length, any resolved + conflicts the phasing follows (cite `SA`/`BC` where relevant). +3. **Gateway Schedule** — one row per phase: `Gateway | Document | Window | + Decision date | Owner | Stories | Main deliverable | Milestone`. One row + per `MIL-*`. `Milestone` links to that phase's Gitea/GitHub Milestone once + `sync-project.sh` has created it (see "Phases, tasks and the git host" + below); leave it blank until then. +4. **Timeline diagram** — a PlantUML Gantt chart, one bar per phase plus a + milestone marker per Go/No-Go decision. +5. **Scope Coverage** — maps each Business Case scope item to the gateway + that delivers it. +6. **Dependencies** — the gateway order (usually a simple chain) and what a + No-Go does to later dates. +7. **Plan Risks** — risks specific to the plan (schedule slip, dependency + risk), separate from the Business Case's own Risks table. +8. **Open Issues** — anything unresolved (start date to confirm, ambiguous + targets, missing checklists needed by a later phase). + +## Phases, tasks and the git host + +Each phase is a `MIL-*` gateway document (see `references/MIL.md`), which +also holds that phase's task breakdown in its own `## Tasks` section. The +Project Plan does not repeat the tasks — it only lists the phases and their +schedule, plus a link to each phase's Milestone once synced (see above). Use +the `project-planning` skill to break a phase into tasks and sync phases (as +Milestones) and tasks (as Issues) to Gitea/GitHub: + +```bash +bash framework/scripts/sync-project.sh # dry run — prints the plan, no network calls +bash framework/scripts/sync-project.sh --apply # creates/updates Milestones and Issues +``` + +`--apply` needs a token: `GITEA_TOKEN` (Gitea, a personal access token — not +a deploy key) or `gh auth login` (GitHub). `GITEA_TOKEN` can come from a +`.env` file at the project root (copy `.env.example`, never commit it). If +`.env` is missing or has no token when a sync is needed, ask the user for +one and create `.env` from `.env.example` with it rather than skipping the +sync or inventing a value. + +After a real `--apply` run, copy each Milestone's URL into the Gateway +Schedule's `Milestone` column (a content update, not a status change — it +does not need a new `## Version History` row). + +## Validating + +`PP` has no QC checklist yet (open item) — validate a plan against the +Business Case constraint it schedules and against `## Go / No-Go Criteria` +in each `MIL-*` it lists, rather than a dedicated checklist. diff --git a/.claude/skills/artifact/references/QC.md b/.claude/skills/artifact/references/QC.md new file mode 100644 index 0000000..e62d8ac --- /dev/null +++ b/.claude/skills/artifact/references/QC.md @@ -0,0 +1,44 @@ +# Quality Criteria checklist (QC) + +A QC checklist is the reusable review checklist for one artifact **type**. +It lives in the framework (`framework/qc/qc-.md`), is +project-independent, and **must never name or link a real artifact +instance** (no `[BC-001]`, no `RC-*`, no stakeholder IDs). Refer to types +generically ("the Stakeholder Analysis"). + +- **ID:** `QC--` (e.g. `QC-BC-001`); the version starts + at `001` and only changes when the checklist itself is revised. +- **Create:** `new-artifact.sh QC --id QC-XX-001 --file framework/qc/qc-.md + --cite QC-=framework/qc/qc-.md ...` +- **CrossReference:** the QC checklists immediately backward and forward in + Larman's chain, in both directions: + +``` +QC-SA → QC-BC → { QC-BMC, QC-BPMN, QC-KPI } → QC-MIL +QC-BC, QC-SA → QC-UCD → { QC-US, QC-UC } +QC-UC → QC-DM → QC-SSD → QC-OC → QC-SD → QC-DCD → QC-ERD +QC-ADR ↔ QC-DCD, QC-ERD +QC-DCD, QC-ADR → { QC-PY, QC-CL, QC-CPP, QC-CS } (language code checklists) +``` + +## Version History statuses + +The statuses are `Proposed`, `Accepted`, `Rejected` and `Deprecated`, as for every +artifact type (rule in the `artifact` skill, "Version History rule"). + +## Required sections (after Metadata / Version History) + +- **Purpose** — why this type matters, what decision it supports. +- **Quality Criteria Checklist** — `# | Criterion | Level | ISO/IEC 25010 + Characteristic(s) | Notes`. `Level` is `Mandatory` (baseline every instance + must meet) or `Optional` (advanced, may be deferred); a checklist with an + extra column (e.g. `Format`) keeps `Level` right after `Criterion`. Every criterion is tagged with at least one of + the eight ISO/IEC 25010:2023 characteristics (Functional Suitability, + Performance Efficiency, Compatibility, Usability, Reliability, Security, + Maintainability, Portability). Never add an untagged criterion. +- **Common Defects** — anti-patterns a reviewer rejects on sight. +- **Traceability Rule** — Backward / Forward bullets with the same `[QC-*]` + labels as `CrossReference`. + +Also add an entry to `framework/CHANGELOG.md`. Reviews of real instances are +recorded in the project as `RC-*` records, not in the checklist. diff --git a/.claude/skills/artifact/references/RC.md b/.claude/skills/artifact/references/RC.md new file mode 100644 index 0000000..4a3fced --- /dev/null +++ b/.claude/skills/artifact/references/RC.md @@ -0,0 +1,34 @@ +# SQA Review Record (RC) + +One record per review of a specific artifact instance against its QC +checklist. Create one for **every** artifact instance in the project. + +- **File:** `docs/sqa/reviews/rc--.md` +- **ID:** `RC-NNN`, sequential across all artifact types (the registry's + Next Available Version for `RC`). +- **Create:** `new-artifact.sh RC --file docs/sqa/reviews/rc-NNN-.md + --cite = --cite QC--001=framework/qc/.md` + +## Required sections (after Metadata / Version History) + +- **Artifact Under Review** — links to the instance and to the QC checklist + used. +- **Checklist Results** — `# | Criterion | Status (Pass/Fail/N-A) | + Evidence/Notes`, one row per criterion copied from the QC checklist, in + the same order. +- **Overall Verdict** — Go / Go-with-conditions / No-Go, with rationale. +- **Action Items** — `Action | Owner | Due`. `Owner` is a stakeholder ID from + the project's Stakeholder Analysis, never a role name. Every `Fail` and + every condition gets an item. + +## After the review + +- The reviewer must not be the artifact's author (see governance). +- Add or update the instance's row in the Traceability Matrix, including + this `RC-*` in "Last Reviewed". +- On **Go**, set the reviewed artifact's latest `## Version History` row to + `Accepted` and the row before it to `Deprecated` (`Approved` is not a + status). On Go-with-conditions the status stays `Proposed` until the action + items are closed. If the change is refused for good, set the row to + `Rejected` (the earlier `Accepted` row stays). +- Step-by-step narrative: `framework/process/review-checklist-process.md`. diff --git a/.claude/skills/artifact/references/SA.md b/.claude/skills/artifact/references/SA.md new file mode 100644 index 0000000..a7307d4 --- /dev/null +++ b/.claude/skills/artifact/references/SA.md @@ -0,0 +1,27 @@ +# Stakeholder Analysis (SA) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **BC** — Business Case objectives each stakeholder concern traces to (Business Goal Alignment section) + +## Required sections (after Metadata / Version History) + +1. **Purpose** — why the analysis exists and the methodology it follows. +2. **Stakeholder Summary Table** — `ID | Name | Role/Title | Organization | + Power Level | Interest Level | Quadrant | Primary Concern (Business + Language)`. Every row fully filled; no unclassified stakeholder. +3. **Power/Interest Classification Rationale** — narrative per quadrant, + consistent with the table. +4. **Primary Concerns and FURPS+ Mapping** — each concern in business + language *and* mapped to a FURPS+ attribute. +5. **Communication Requirements** — channel, frequency, deliverable type, + tied to a project phase or milestone. +6. **Conflicting Interests and Mitigations** — every conflict has a + mitigation. +7. **Traceability Analysis** — stakeholder → actor/use case mapping, and + business-goal alignment citing Business Case (`[BC-001]`) objectives. +8. **Sign-Off**. + +Stakeholder IDs (`S01`, `S02`, …) are **stable: never renumbered or reused**. +Every other artifact cites them for RACI, ownership and review assignment +(`AGENTS.md` rule 3). Add new stakeholders with the next free `S`. diff --git a/.claude/skills/artifact/references/SD.md b/.claude/skills/artifact/references/SD.md new file mode 100644 index 0000000..a8b2476 --- /dev/null +++ b/.claude/skills/artifact/references/SD.md @@ -0,0 +1,26 @@ +# Sequence Diagram (Design) (SD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **OC** — **Required source**: the contract whose postconditions each diagram realizes +- **DCD** — Forward: classes/methods these messages become + +## Required sections (after Metadata / Version History) + +One block per realized Operation Contract: + +1. **Realizes** — the contract (`[OC-…]`) and its operation name. +2. **Diagram** — PlantUML sequence diagram: sync (solid filled arrow), + async (open arrow), returns (dashed); activations matching the call + nesting; `create` / `destroy` shown for transient objects; + `loop` / `alt` / `opt` fragments for conditional/repeated behavior. +3. **Pattern Annotations** — table `Pattern (GRASP/GoF) | Applied to | + Rationale`. Patterns are labelled, never implicit. +4. **Postcondition Coverage** — `Postcondition | Satisfied by message`; + every postcondition of the contract must be covered. +5. **Responsibility Check** — a short note showing no god-object receives + all messages (low coupling, high cohesion). + +## Terminology + +Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses. diff --git a/.claude/skills/artifact/references/SSD.md b/.claude/skills/artifact/references/SSD.md new file mode 100644 index 0000000..16e8f94 --- /dev/null +++ b/.claude/skills/artifact/references/SSD.md @@ -0,0 +1,21 @@ +# System Sequence Diagram (SSD) (SSD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UC** — **Required source** of every SSD: cite the use case (name and ID) it depicts +- **DM** — Concepts behind message parameters / returned values +- **OC** — Forward: contract per system operation shown + +## Required sections (after Metadata / Version History) + +1. **Source Use Case** — name and ID (`[UC-…]`) and the specific scenario. +2. **Diagram** — PlantUML sequence diagram with just the actor and + `:System`; **no internal objects**. Dashed return arrows for operations + that produce a result. One scenario per diagram — separate diagrams for + alternate/exception flows (or state them out of scope). +3. **System Operations Table** — `Step | Message (verb phrase) | Parameters + | Return | Use case step`. Messages match the use case's main success + scenario step-for-step; justify any deviation. Message names become the + Operation Contract names. +4. **Lifecycle Notes** — creation/destruction of the System instance where + relevant (session/transaction scope). diff --git a/.claude/skills/artifact/references/TM.md b/.claude/skills/artifact/references/TM.md new file mode 100644 index 0000000..a21dc38 --- /dev/null +++ b/.claude/skills/artifact/references/TM.md @@ -0,0 +1,15 @@ +# Traceability Matrix (TM) + +One matrix per project: `docs/sqa/traceability-matrix.md`. It makes the +Business Case's cross-artifact traceability target measurable. + +## Required sections (after Metadata / Version History) + +- **Purpose**. +- **Traceability Table** — one row per artifact instance: + `Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward + Link) | Last Reviewed (RC-ID)`. Add or update a row whenever an instance + is created or reviewed. +- **Coverage Notes** — which types have no instance yet, and how to read + `-`: in Upstream it means foundational; in Downstream it means nothing + is built on it yet; in Last Reviewed it means no `RC-*` exists yet. diff --git a/.claude/skills/artifact/references/TRN.md b/.claude/skills/artifact/references/TRN.md new file mode 100644 index 0000000..64b2b7d --- /dev/null +++ b/.claude/skills/artifact/references/TRN.md @@ -0,0 +1,18 @@ +# Reviewer Training (TRN) + +The reusable training material for reviewers. It mitigates the "resistance to +standardized reviews" risk of the Business Case. Framework-level, like `PRC`: +no project data, no stakeholder IDs, no links to project artifacts. The +*record* that a session happened (date, attendees, result) is a project +document, written after the session. + +- **File:** `framework/process/reviewer-training.md` (singleton, version `001`). +- **Create:** `new-artifact.sh TRN`. +- **CrossReference:** `PRC` (the procedure the training teaches). + +## Required sections (after Metadata / Version History) + +Purpose, Audience and Prerequisites, Learning Objectives, Agenda (modules with +minutes), Module Notes, Exercises (each with input and expected result), +Assessment (how and pass criteria), Session Record (what to capture). +Exercises use a seeded, generic example, not a real project artifact. diff --git a/.claude/skills/artifact/references/TRR.md b/.claude/skills/artifact/references/TRR.md new file mode 100644 index 0000000..d8173ca --- /dev/null +++ b/.claude/skills/artifact/references/TRR.md @@ -0,0 +1,21 @@ +# Reviewer Training Record (TRR) + +The project's record that a reviewer training session happened: the evidence +that mitigates the "resistance to standardized reviews" risk and satisfies a +"training delivered and recorded" gateway criterion. It records one session +of the framework's training material (`TRN`); it holds project data +(stakeholder IDs, dates), so it lives in the project, not in the framework. + +- **File:** `docs/sqa/reviewer-training-record.md` (one per project; add a new + row under `## Attendees and Assessment` and a Version History row for each + further session). +- **Create:** `new-artifact.sh TRR --file docs/sqa/reviewer-training-record.md + --cite TRN-001=framework/process/reviewer-training.md`. +- **CrossReference:** `TRN` (the material that was taught). + +## Required sections (after Metadata / Version History) + +Session (material, date, facilitator, format), Attendees and Assessment +(stakeholder IDs, attended, Pass or Not yet against the assessment in the +material), Feedback, Follow-ups (action, owner as a stakeholder ID, due). +Fill the record after the session; never before. diff --git a/.claude/skills/artifact/references/UC.md b/.claude/skills/artifact/references/UC.md new file mode 100644 index 0000000..fcb5da8 --- /dev/null +++ b/.claude/skills/artifact/references/UC.md @@ -0,0 +1,35 @@ +# Use Case (UC) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — Actor and use-case names must match it exactly +- **US** — Stories this use case decomposes into +- **SA** — Stakeholders & Interests — cite S-IDs +- **DM** — Forward: concepts derived from this use case's nouns +- **SSD** — Forward: the SSD depicting this use case's main scenario + +## Location + +`docs/uc-NNN/uc.md`, one folder per use case (create with +`new-artifact.sh UC --file docs/uc-NNN/uc.md`). The artifacts this use case +affects are saved in the same folder; see the `project-planning` skill, "Use +cases get their own folder". + +## Required sections (after Metadata / Version History) + +Pick the format explicitly (`Format: Brief | Casual | Fully Dressed`) and +state the **scope/level** (summary, user-goal, subfunction). Always: primary +actor, pre/postconditions, goal-perspective wording with no UI or +implementation detail. + +- **Brief** — a single paragraph summarizing only the main success scenario. +- **Casual** — informal multi-paragraph narrative; may mention some + alternate flows. +- **Fully Dressed** — all sections, in order: Scope, Level, Primary Actor, + Stakeholders and Interests (cite `SA` S-IDs), Preconditions, + Postconditions (success guarantee), Main Success Scenario (numbered + steps), Extensions / Alternative Flows (reference `<>` / + `<>` use cases), Special Requirements / Business Rules (per step), + Open Issues. + +Title and actor names must match `UCD` and `US` exactly. diff --git a/.claude/skills/artifact/references/UCD.md b/.claude/skills/artifact/references/UCD.md new file mode 100644 index 0000000..c7ce5bd --- /dev/null +++ b/.claude/skills/artifact/references/UCD.md @@ -0,0 +1,24 @@ +# Use Case Diagram (UCD) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **SA** — Each actor traces to a stakeholder need — cite S-IDs +- **BC** — Scope / objectives the boundary reflects +- **US** — Forward: stories whose role must match an actor here +- **UC** — Forward: the use cases detailing each goal shown + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the system boundary in words. +2. **Diagram** — actors with correct stereotypes (`<>`, + `<>`), a labelled system boundary, `<>` / `<>` + used per UML 2.5.1 (not as generic "uses"). Embed PlantUML or link the + diagram source; no UI or implementation detail. +3. **Actor Table** — `Actor | Stereotype | Stakeholder ID (SA) | Goals + (use cases)`. No orphan actors: every actor appears in at least one use + case. +4. **Use Case Table** — `Use Case | Actor(s) | Goal`, names as **verb + phrases describing actor goals** ("Place Order"), not system operations + ("Validate Input"). +5. **Relationships** — every `<>` / `<>` with a one-line + justification. diff --git a/.claude/skills/artifact/references/US.md b/.claude/skills/artifact/references/US.md new file mode 100644 index 0000000..554f93a --- /dev/null +++ b/.claude/skills/artifact/references/US.md @@ -0,0 +1,22 @@ +# User Story (US) + +Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you): + +- **UCD** — The story's role must match an actor defined here +- **UC** — The use case each story traces to +- **BC** — Objective / epic the story ultimately supports +- **MIL** — The gateway (epic) each story delivers — one or more stories per gateway + +## Required sections (after Metadata / Version History) + +1. **Purpose and Scope** — the epic(s) covered. +2. **Story List** — each story with a stable ID `US-.` (e.g. + `US-001.01`, so it cannot be confused with the document ID `US-001`): + - Statement: **As a** ``, **I want** ``, **so that** + `` — one goal per story, no implementation detail. + - **Acceptance Criteria** — clear and testable (Given/When/Then works). + - **Traces to** — the use case (`UC-…`) or epic it comes from; a gateway + (`MIL-…`) is an epic. + - **Size** — fits a single iteration. +3. **INVEST Check** — one line confirming Independent, Negotiable, + Valuable, Estimable, Small, Testable (flag any exception with reason). diff --git a/.claude/skills/artifact/templates/ADR.md b/.claude/skills/artifact/templates/ADR.md new file mode 100644 index 0000000..0bcae97 --- /dev/null +++ b/.claude/skills/artifact/templates/ADR.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + + + +## Decision + + + +## Consequences + +**Positive:** + +- + +**Negative:** + +- + +## Affected Artifacts + +- [] — , or a single "-" if none + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/BC.md b/.claude/skills/artifact/templates/BC.md new file mode 100644 index 0000000..4d8e302 --- /dev/null +++ b/.claude/skills/artifact/templates/BC.md @@ -0,0 +1,70 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Executive Summary + +## Methodological and Standards Foundation + +## Problem Statement + +## Business Opportunity + +## Objectives + +## Scope + +### In Scope + +### Out of Scope + +## Expected Benefits + +### Tangible Benefits + +### Intangible Benefits + +## Strategic Alignment + +## Success Criteria + +| # | Criterion | Target | Measure | +| --- | --- | --- | --- | + +## Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Assumptions + +## Constraints + +## Cost–Benefit Assessment + +| Costs | Benefits | +| --- | --- | + +## Stakeholders + +| Stakeholder ID (SA) | Interest in this project | +| --- | --- | + +## Recommendation + + — + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/BMC.md b/.claude/skills/artifact/templates/BMC.md new file mode 100644 index 0000000..fedac6a --- /dev/null +++ b/.claude/skills/artifact/templates/BMC.md @@ -0,0 +1,113 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose / Scope + +Operationalizes: ([BC-]) + +## Canvas + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key PartnersKey ActivitiesValue PropositionsCustomer RelationshipsCustomer Segments
+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+ 		+ +
    +
  • +
+
Key ResourcesChannels
+ +
    +
  • +
+ 		+ +
    +
  • +
+
Cost StructureRevenue Streams
+ +
    +
  • +
+ 		+ +
    +
  • +
+
+ + +## Assumptions + +| # | Assumption | How it can be tested | +| --- | --- | --- | + +## Consistency Check + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/BPMN.md b/.claude/skills/artifact/templates/BPMN.md new file mode 100644 index 0000000..4744780 --- /dev/null +++ b/.claude/skills/artifact/templates/BPMN.md @@ -0,0 +1,41 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Business Goal + +Realizes: ([BC-]) + +## Participants + +| Pool / Lane | Participant | Stakeholder ID (SA) | +| --- | --- | --- | + +## Process Diagram + + + +## Element Table + +| Element | Type (event / activity / gateway) | Lane | Description | +| --- | --- | --- | --- | + +## Path Coverage + +| Path | Start event | End event | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/DCD.md b/.claude/skills/artifact/templates/DCD.md new file mode 100644 index 0000000..057cf8f --- /dev/null +++ b/.claude/skills/artifact/templates/DCD.md @@ -0,0 +1,50 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +class Controller { + -repo : Repository + +operationName(param : Type) : ReturnType +} +class Entity +Controller --> Entity : uses +@enduml +``` + +## Class Table + +| Class | Refines (Domain Model concept) | Responsibility | Attributes | Operations | +| --- | --- | --- | --- | --- | + +## Method Traceability + +| Method signature | Operation Contract / SD message | +| --- | --- | + +## Pattern Annotations + +| Pattern | Classes | Rationale | +| --- | --- | --- | + +## Dependency Check + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/DICT.md b/.claude/skills/artifact/templates/DICT.md new file mode 100644 index 0000000..44bf5bb --- /dev/null +++ b/.claude/skills/artifact/templates/DICT.md @@ -0,0 +1,35 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Maps each Product Owner (PO) term to its professional IT term. PO language: +. + +## Dictionary + +| PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in | +| --- | --- | --- | --- | --- | --- | +| | | | | DM | OC, SD, DCD, ERD | + +## Rules + +- The Domain Model, use cases and user stories use the PO term; the Operation + Contract, Sequence Diagram, Design Class Diagram and ERD use the IT term. +- One IT term per PO term and one PO term per IT term; no synonyms. + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/DM.md b/.claude/skills/artifact/templates/DM.md new file mode 100644 index 0000000..dfbf337 --- /dev/null +++ b/.claude/skills/artifact/templates/DM.md @@ -0,0 +1,54 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +Covers: + +## Diagram + +Concepts, attributes and associations only — no operations. + +```plantuml +@startuml +class Order { + date + status +} +class Customer { + name +} +Customer "1" --> "0..*" Order : places +@enduml +``` + +## Concept Table + +| Concept | Definition | Attributes | Source (use case / glossary) | +| --- | --- | --- | --- | + +## Association Table + +| From | Association (reading direction) | To | Multiplicity | +| --- | --- | --- | --- | + +## Generalizations + +| General | Specializations | Is-a justification | +| --- | --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/ERD.md b/.claude/skills/artifact/templates/ERD.md new file mode 100644 index 0000000..25c0656 --- /dev/null +++ b/.claude/skills/artifact/templates/ERD.md @@ -0,0 +1,53 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Diagram + +```plantuml +@startuml +hide circle +entity CUSTOMER { + * id : int <> + -- + name : string +} +entity ORDER { + * id : int <> + -- + * customer_id : int <> +} +CUSTOMER ||--o{ ORDER : places +@enduml +``` + +## Entity Table + +### + +| Attribute | Type | PK/FK | Nullable | Source (DCD class.attribute) | +| --- | --- | --- | --- | --- | + +## Relationship Table + +| Entity | Cardinality | Entity | FK | Rule | +| --- | --- | --- | --- | --- | + +## Normalization Notes + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/GOV.md b/.claude/skills/artifact/templates/GOV.md new file mode 100644 index 0000000..a1bda5c --- /dev/null +++ b/.claude/skills/artifact/templates/GOV.md @@ -0,0 +1,68 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Defines how this project applies Quality Criteria (QC) checklists to real +artifact instances, producing SQA Review Records and Go/No-Go decisions. + +## ARB Review Workflow + +1. **Submission** — the artifact owner submits an instance for review, + identifying its type's QC checklist (`framework/qc/qc-*.md`). +2. **QC Checklist Review** — the assigned reviewer (see RACI) applies the + checklist criterion by criterion. +3. **Review Record** — the reviewer documents the outcome as an SQA Review + Record (`RC-*` under `docs/sqa/reviews/`). +4. **Go/No-Go Decision** — the Accountable role for the artifact category + decides; contested or cross-cutting cases escalate to the ARB Chair. +5. **Sign-off** — on **Go**, the artifact's `## Version History` gets an + `Accepted` row (the previous row becomes `Deprecated`). On **Go-with-conditions**, status stays `Proposed` until + the Action Items are closed. On **No-Go**, the artifact returns to its + owner. +6. **Traceability Update** — the Traceability Matrix is updated with the + instance and its `RC-*` reference. + +## RACI by Artifact Category + +Fill every cell with stakeholder IDs from the Stakeholder Analysis (`S`), +never role names. + +| Artifact Category | Responsible (runs the review) | Accountable (Go/No-Go owner) | Consulted | Informed | +| --- | --- | --- | --- | --- | +| Strategic (Stakeholder Analysis, Business Case, BMC) | S | S | S | S | +| Process/Business (BPMN, KPI, Milestones/Gateways) | S | S | S | S | +| Requirements (Use Case Diagram, User Story, Use Case) | S | S | S | S | +| Modeling/Design (Domain Model, SSD, Operation Contract, Sequence Diagram, DCD, ERD) | S | S | S | S | + +Cross-cutting escalations and disputed verdicts are Accountable to the ARB +Chair (`S`), overriding the category-level Accountable role. + +## Escalation Rules + +- A **No-Go** verdict, or any disagreement between the Responsible reviewer + and the category's Accountable owner, escalates to the ARB Chair. +- A reviewer may not review an instance they authored. +- Repeated No-Go verdicts (2 or more) on the same artifact type trigger a + review of the corresponding `QC-*` checklist itself. + +## Cadence + +- Reviews are triggered per artifact instance as it is produced or revised. +- QC checklists are reviewed annually. + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/KPI.md b/.claude/skills/artifact/templates/KPI.md new file mode 100644 index 0000000..3a8a89f --- /dev/null +++ b/.claude/skills/artifact/templates/KPI.md @@ -0,0 +1,35 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## KPI Definitions + +| KPI ID | Name | SMART statement | Baseline | Target | Business Case success criterion | Owner (S-ID) | Frequency & method | Data source | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| KPI-01 | | | | | | | | | + +## Thresholds + +| KPI ID | Acceptable | At risk | Failing | +| --- | --- | --- | --- | + +## Reporting + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/MIL.md b/.claude/skills/artifact/templates/MIL.md new file mode 100644 index 0000000..66f844b --- /dev/null +++ b/.claude/skills/artifact/templates/MIL.md @@ -0,0 +1,58 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Deliverable + + + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | + +## Dependencies + +| Depends on | Reason | +| --- | --- | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | | +| Approving reviewer | | + +## Target Date + +YYYY-MM-DD — + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | | | No | | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/OC.md b/.claude/skills/artifact/templates/OC.md new file mode 100644 index 0000000..f3c7622 --- /dev/null +++ b/.claude/skills/artifact/templates/OC.md @@ -0,0 +1,41 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Contract: + +| Item | Value | +| --- | --- | +| Operation | `operationName(param: Type): ReturnType` | +| Traces to | in [SSD-] | +| Domain Model concepts | ([DM-]) | + +**Preconditions** + +- + +**Postconditions** + +- A instance was created. +- was associated with . +- . was set to . + +**Exceptions** + +| Condition (failing precondition) | Outcome | +| --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/PP.md b/.claude/skills/artifact/templates/PP.md new file mode 100644 index 0000000..1ed287f --- /dev/null +++ b/.claude/skills/artifact/templates/PP.md @@ -0,0 +1,61 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Planning Assumptions + +- Week 1 starts ; the plan ends by , per the Business Case constraint. +- Phase length: . + +## Gateway Schedule + +| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | [MIL-] | | | | | | | + +```plantuml +@startgantt +Project starts +[Phase 1] starts and ends +[Phase 1 Go/No-Go] happens +@endgantt +``` + +## Scope Coverage + +| Business Case scope item | Gateway | +| --- | --- | + +## Dependencies + +``` + → → ... +``` + +## Plan Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | + +## Open Issues + +- + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/QC.md b/.claude/skills/artifact/templates/QC.md new file mode 100644 index 0000000..4c98f24 --- /dev/null +++ b/.claude/skills/artifact/templates/QC.md @@ -0,0 +1,42 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`. The latest reviewed row is `Accepted`; the row before it is `Deprecated`. + +--- + +## Purpose + + + +## Quality Criteria Checklist + +Level: **Mandatory** criteria are the baseline every instance must meet; **Optional** criteria are advanced and may be deferred. + +| # | Criterion | Level | ISO/IEC 25010 Characteristic(s) | Notes | +| --- | --- | --- | --- | --- | +| 1 | | Mandatory | | | + +## Common Defects + +- +- + +## Traceability Rule + +- Backward: ([QC--]) +- Forward: ([QC--]) + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/RC.md b/.claude/skills/artifact/templates/RC.md new file mode 100644 index 0000000..fd5f173 --- /dev/null +++ b/.claude/skills/artifact/templates/RC.md @@ -0,0 +1,39 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [] +- Checklist used: [] (`QC--`, e.g. `QC-BC-001`) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | | Pass/Fail/N-A | | + +## Overall Verdict + + — + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/SA.md b/.claude/skills/artifact/templates/SA.md new file mode 100644 index 0000000..0be8093 --- /dev/null +++ b/.claude/skills/artifact/templates/SA.md @@ -0,0 +1,54 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Stakeholder Summary Table + +| ID | Name | Role/Title | Organization | Power Level | Interest Level | Quadrant | Primary Concern (Business Language) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| S01 | | | | HIGH / MEDIUM / LOW | HIGH / MEDIUM / LOW | Manage Closely / Keep Satisfied / Keep Informed / Monitor | | + +## Power/Interest Classification Rationale + +## Primary Concerns and FURPS+ Mapping + +| ID | Concern | FURPS+ attribute | +| --- | --- | --- | + +## Communication Requirements + +| ID | Channel | Frequency | Deliverable | Phase / Milestone | +| --- | --- | --- | --- | --- | + +## Conflicting Interests and Mitigations + +| Conflict | Stakeholders | Mitigation | +| --- | --- | --- | + +## Traceability Analysis + +### Business Goal Alignment + +| Stakeholder | Concern | Business Case objective | +| --- | --- | --- | + +## Sign-Off + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/SD.md b/.claude/skills/artifact/templates/SD.md new file mode 100644 index 0000000..1df4e54 --- /dev/null +++ b/.claude/skills/artifact/templates/SD.md @@ -0,0 +1,47 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Sequence: + +**Realizes:** `operationName` in [OC-] + +### Diagram + +```plantuml +@startuml +participant ":Controller" as C +participant ":Collaborator" as X +C -> X : message(args) +activate X +X --> C : result +deactivate X +@enduml +``` + +### Pattern Annotations + +| Pattern (GRASP / GoF) | Applied to | Rationale | +| --- | --- | --- | + +### Postcondition Coverage + +| Postcondition (from contract) | Satisfied by message | +| --- | --- | + +### Responsibility Check + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/SSD.md b/.claude/skills/artifact/templates/SSD.md new file mode 100644 index 0000000..82ed747 --- /dev/null +++ b/.claude/skills/artifact/templates/SSD.md @@ -0,0 +1,40 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Source Use Case + + ([UC-]) — scenario:
+ +## Diagram + +```plantuml +@startuml +actor Actor as A +participant ":System" as S +A -> S : verbPhrase(param) +S --> A : result +@enduml +``` + +## System Operations + +| Step | Message | Parameters | Return | Use case step | +| --- | --- | --- | --- | --- | + +## Lifecycle Notes + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/TM.md b/.claude/skills/artifact/templates/TM.md new file mode 100644 index 0000000..7e5c810 --- /dev/null +++ b/.claude/skills/artifact/templates/TM.md @@ -0,0 +1,30 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + +Tracks backward/forward links between artifact instances so that the Business Case's +cross-artifact traceability success criterion is measurable. A row is added or +updated whenever an artifact instance is created or reviewed. + +## Traceability Table + +| Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | +| --- | --- | --- | --- | --- | +| [] | | [] | [] | [] | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/TRN.md b/.claude/skills/artifact/templates/TRN.md new file mode 100644 index 0000000..43ed3b4 --- /dev/null +++ b/.claude/skills/artifact/templates/TRN.md @@ -0,0 +1,60 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose + + + +## Audience and Prerequisites + + + +## Learning Objectives + +By the end, a participant can: + +- + +## Agenda + +| Module | Topic | Minutes | +| --- | --- | --- | +| 1 | | | + +## Module Notes + +### Module 1: + + + +## Exercises + +### Exercise 1: + + + +## Assessment + + + +## Session Record + +What is recorded after each session, in the project (never in the framework): +date, facilitator, attendees, result against the assessment, feedback and +follow-ups. + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/TRR.md b/.claude/skills/artifact/templates/TRR.md new file mode 100644 index 0000000..59b5771 --- /dev/null +++ b/.claude/skills/artifact/templates/TRR.md @@ -0,0 +1,43 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Session + +| Item | Value | +| --- | --- | +| Training material | [] | +| Date | | +| Facilitator | | +| Format and place | | + +## Attendees and Assessment + +| Stakeholder ID (SA) | Attended | Assessment (Pass / Not yet) | Notes | +| --- | --- | --- | --- | +| | | | | + +## Feedback + + + +## Follow-ups + +| Action | Owner | Due | +| --- | --- | --- | +| | | | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/UC.md b/.claude/skills/artifact/templates/UC.md new file mode 100644 index 0000000..90b9359 --- /dev/null +++ b/.claude/skills/artifact/templates/UC.md @@ -0,0 +1,55 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +**Format:** Brief | Casual | Fully Dressed (delete the unused sections below) + +## Brief + + + +## Casual + + + +## Fully Dressed + +- **Scope:** +- **Level:** summary | user-goal | subfunction +- **Primary Actor:** ]> +- **Stakeholders and Interests:** + - — +- **Preconditions:** +- **Postconditions (success guarantee):** + +### Main Success Scenario + +1. +2. + +### Extensions (Alternative / Exception Flows) + +- 2a. : + 1. (`<>` / `<>` ) + +### Special Requirements / Business Rules + +| Step | Rule | +| --- | --- | + +### Open Issues + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/UCD.md b/.claude/skills/artifact/templates/UCD.md new file mode 100644 index 0000000..bab5bfa --- /dev/null +++ b/.claude/skills/artifact/templates/UCD.md @@ -0,0 +1,50 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + + + +## Diagram + +```plantuml +@startuml +left to right direction +actor "Name" as A1 +rectangle "System Name" { + usecase "Verb-phrase goal" as UC1 +} +A1 --> UC1 +@enduml +``` + +## Actor Table + +| Actor | Stereotype | Stakeholder ID (SA) | Goals (use cases) | +| --- | --- | --- | --- | + +## Use Case Table + +| Use Case | Actor(s) | Goal | +| --- | --- | --- | + +## Relationships + +| From | Relationship (`<>` / `<>`) | To | Justification | +| --- | --- | --- | --- | + +--- + +@LINKS@ diff --git a/.claude/skills/artifact/templates/US.md b/.claude/skills/artifact/templates/US.md new file mode 100644 index 0000000..83ee098 --- /dev/null +++ b/.claude/skills/artifact/templates/US.md @@ -0,0 +1,36 @@ +# @TITLE@ + +## Metadata +| Key | Value | +| --- | --- | +| ID | @ID@ | +| CrossReference | @CROSSREF@ | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| @DATE@ | Accepted | @AUTHOR@ | | Initial version | pending | + +--- + +## Purpose and Scope + +## Story List + +### @ID@.01 — + +**As a** ]>, **I want** , **so that** . + +**Acceptance Criteria** + +- Given , when , then . + +| Traces to | Size | INVEST exceptions | +| --- | --- | --- | +| [UC-] or [MIL-] | fits one iteration | none | + +## INVEST Check + +--- + +@LINKS@ diff --git a/.claude/skills/coding-conventions/SKILL.md b/.claude/skills/coding-conventions/SKILL.md new file mode 100644 index 0000000..3e199bf --- /dev/null +++ b/.claude/skills/coding-conventions/SKILL.md @@ -0,0 +1,94 @@ +--- +name: coding-conventions +description: Programming conventions for writing or reviewing source code — naming, layout, formatting and language idioms — for Python, C, C++, C# and Shell (bash). Use when writing, editing, reviewing or refactoring code in one of those languages, choosing names, setting up a formatter/linter config, or adding conventions for another language. Holds the rules shared by every language and points to a per-language sub-skill. +--- + +# Coding Conventions + +One skill for all languages. This file holds what is true in every language; +everything specific to one language is in a sub-skill that is read only when +that language is in hand: + +| Language | Sub-skill | QC checklist | +| --- | --- | --- | +| Python | `references/python.md` | `framework/qc/qc-programming-python.md` (`QC-PY-001`) | +| C | `references/c.md` | `framework/qc/qc-programming-c.md` (`QC-CL-001`) | +| C++ | `references/cpp.md` | `framework/qc/qc-programming-cpp.md` (`QC-CPP-001`) | +| C# | `references/csharp.md` | `framework/qc/qc-programming-csharp.md` (`QC-CS-001`) | +| Shell (bash) | `references/shell.md` | `framework/qc/qc-programming-shell.md` (`QC-SH-001`) | + +Read the sub-skill for the language you are working in, then write or review +the code. To review, use the language's QC checklist and record the result as +an `RC-*` (see the `artifact` skill). + +## Precondition: a planned task + +Before writing or editing code under `src/` or `tests/`, name the task row +(`MIL-NNN`, task N) or the synced issue, and the use case or design artifact +it implements, or say it is a plain technical task. If you cannot, refuse and +use the `project-planning` skill instead (rule: `framework/process/plan-first-gate.md`). +Reviewing code needs no task. + +## Rules for every language + +1. **The existing code wins.** In a file or project that already has a + convention, follow it, even if the sub-skill says otherwise. Do not mix + styles within a file; do not reformat code you are not changing. +2. **Naming follows the language, not your habits.** Casing differs per + language (table below). Never carry one language's casing into another. +3. **A name says what, not how.** Name by purpose in the domain's language + (IT Professional English, as the registry's `Languages` section says), not by + type or implementation (`customer_list`, not `arr2`). +4. **Length follows scope.** Short names (`i`, `n`) only for tiny scopes; + wider scope, longer name. No abbreviations except ones the whole domain + uses (`id`, `url`, `http`). +5. **Booleans read as a question:** `is_valid`, `has_items`, `can_retry` + (cased per language). No negated names (`is_not_ready`). +6. **Functions are verbs, types are nouns.** A function that returns a value + without side effects may be a noun (`total`, `Total`) where the language + community does so. +7. **Formatting is done by the formatter,** not by hand and not in review + comments. Each sub-skill names the formatter and linter; commit its + configuration file with the code. +8. **Comments say why,** never what the code already says. Public APIs get + the language's documentation-comment form. +9. **No dead or commented-out code, no unexplained magic numbers.** Name the + constant. +10. **Errors are handled or propagated, never swallowed.** Each sub-skill says + how its language does this. + +## Casing at a glance + +| Element | Python | C | C++ | C# | +| --- | --- | --- | --- | --- | +| Type / class | `PascalCase` | `snake_case_t` | `PascalCase` | `PascalCase` | +| Function / method | `snake_case` | `snake_case` | `snake_case` | `PascalCase` | +| Variable / parameter | `snake_case` | `snake_case` | `snake_case` | `camelCase` | +| Constant | `UPPER_SNAKE` | `UPPER_SNAKE` | `kPascalCase` | `PascalCase` | +| Private member | `_leading` | file-scope `static` | `trailing_` | `_camelCase` | +| Namespace / module | `snake_case` module | `mod_` prefix | `snake_case` | `PascalCase` | +| File | `snake_case.py` | `snake_case.c/.h` | `snake_case.cpp/.h` | `PascalCase.cs` | + +The table is a summary; the sub-skill is authoritative. Shell (bash) is not in +the table: functions and variables are `snake_case`, constants and environment +variables `UPPER_SNAKE`, files `kebab-case.sh`. + +## Governance boundary + +Conventions are **defined and governed** here but **not enforced** by this +framework: writing a linter or CI job that enforces them is outside the +framework's scope. The formatter and linter names in each sub-skill are the +recommended tools, not a pipeline. A new or changed convention follows the +process in the project's Coding Standards Governance document and is recorded +in `framework/CHANGELOG.md`. No project data belongs in this skill. + +## Adding a language + +1. Add `references/.md` with these sections: Standard base, Naming, + Formatting, Language rules, Errors, Tests, Tooling. +2. Add `framework/qc/qc-.md` (`QC--001`) using the `QC` type + of the `artifact` skill, tagging every criterion with an ISO/IEC 25010:2023 + characteristic and a Level. +3. Add the row to the table above, the casing table, and a row for the + language in `framework/registry/artifact-catalog.md`; note it in + `framework/CHANGELOG.md`; run `bash framework/scripts/install-skills.sh`. diff --git a/.claude/skills/coding-conventions/references/c.md b/.claude/skills/coding-conventions/references/c.md new file mode 100644 index 0000000..14375ca --- /dev/null +++ b/.claude/skills/coding-conventions/references/c.md @@ -0,0 +1,71 @@ +# C conventions + +C has no single official style guide. This sub-skill fixes one consistent +style built on common practice; MISRA C and SEI CERT C are the references for +safety-critical or security-sensitive code. + +## Standard base + +ISO C11 or C17 as set by the project's compiler flag (`-std=c11`). Compile +with warnings on (`-Wall -Wextra -Wpedantic`); treat warnings as errors in +release builds. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Function, variable, parameter | `snake_case` | `parse_header`, `byte_count` | +| Public symbol | module prefix plus `snake_case` (C has no namespaces) | `stay_reader_open()` | +| File-local function / variable | `static`, no prefix needed | `static int next_token(...)` | +| Type (`struct`, `enum`, `typedef`) | `snake_case_t`, module prefix for public types | `stay_reader_t` | +| Enum constant, macro, constant | `UPPER_SNAKE` with the module prefix | `STAY_READER_OK` | +| Header / source file | `snake_case.h` / `snake_case.c`, same base name | `stay_reader.h` | +| Header guard | `MODULE_FILE_H` (or `#pragma once` if the project allows) | `STAY_READER_H` | + +- Do not use reserved identifiers: a leading underscore followed by an + uppercase letter, any double underscore, or a leading underscore at file + scope. +- POSIX reserves the `_t` suffix; keep the module prefix on public types so + they cannot collide. +- Macros are a last resort; prefer `static inline` functions and `enum` or + `const` values. + +## Formatting + +- One formatter configuration for the project (`clang-format`); 4 spaces (or + the project's setting), no tabs mixed in. +- Braces on every `if`, `else`, `for`, `while`, even for one statement. +- One declaration per line; declare variables at first use, initialised. +- Headers: include what you use, only what you use; public headers are + self-contained; add `extern "C"` guards when C++ code consumes them. + +## Language rules + +- Check every return value that can fail; check every allocation. +- Every `malloc`/`open`/`lock` has one clear owner and one matching release; + release on every exit path (single exit or `goto cleanup`). +- Use `size_t` for sizes and indices, fixed-width types (``) for + data layout, `const` wherever data is not modified, `restrict` only with + care. +- Bounds are explicit: pass a length with every buffer; use `snprintf`, + never `sprintf`, `strcpy` or `gets`. +- No undefined behaviour: no signed overflow, no out-of-range shifts, no use + after free, no uninitialised reads. +- Avoid global mutable state; if unavoidable, `static` and documented. + +## Errors + +Return a status code (an `enum`) or `-1`/`NULL` plus an error out-parameter; +document which in the header. Never ignore a failing call. Read `errno` +immediately after the failing call. + +## Tests + +A unit-test framework (for example Unity or CMocka); run under sanitizers +(`-fsanitize=address,undefined`) in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` or `cppcheck`, compiler warnings, sanitizers. + +Review with `QC-CL-001`. diff --git a/.claude/skills/coding-conventions/references/cpp.md b/.claude/skills/coding-conventions/references/cpp.md new file mode 100644 index 0000000..8e164ab --- /dev/null +++ b/.claude/skills/coding-conventions/references/cpp.md @@ -0,0 +1,70 @@ +# C++ conventions + +## Standard base + +ISO C++17 or later as set by the project (`-std=c++20`); the C++ Core +Guidelines are the rule source. C++ has no official naming style, so the +style below is used unless the project already has another (rule 1 of the +overall skill). + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Class, struct, enum, concept, type alias | `PascalCase` | `StayReader`, `Stay` | +| Function, method, variable, parameter | `snake_case` | `read_stays()`, `byte_count` | +| Data member (private) | `snake_case` with trailing underscore | `buffer_` | +| Struct public data member | `snake_case`, no underscore | `check_in` | +| Constant (`constexpr`, namespace-scope `const`) | `kPascalCase` | `kMaxRetries` | +| Enum class value | `PascalCase` | `Status::NotFound` | +| Namespace | short `snake_case`; no `using namespace` in headers | `billing` | +| Template parameter | `PascalCase` | `typename ItemT` | +| Macro | `UPPER_SNAKE` with project prefix; avoid macros | `BILLING_ASSERT` | +| Header / source file | `snake_case.h` / `snake_case.cpp`, same base name | `stay_reader.h` | +| Header guard | `#pragma once` (or `PROJECT_PATH_FILE_H`) | | + +## Formatting + +- `clang-format` with one checked-in config; 4 spaces (or the project's + setting); braces on every control-flow body. +- Include order: matching header, project headers, third party, standard + library; each group sorted. +- One declaration per line; declare at first use, initialise with `{}`. + +## Language rules + +- **Ownership:** RAII everywhere. No owning raw pointers, no naked + `new`/`delete`; use `std::unique_ptr` by default, `std::shared_ptr` only for + real shared ownership, created with `std::make_unique`/`make_shared`. +- Follow the rule of zero; if you define one of destructor, copy or move, + define or delete all five. +- Pass by `const&` (large, read-only) or by value (small or sink); use + `std::span` and `std::string_view` for non-owning views, `std::optional` for + "maybe", `std::variant` for alternatives. +- `const` and `constexpr` by default; mark single-argument constructors + `explicit`; mark `override`/`final`; `[[nodiscard]]` on results that must + be used. +- Prefer algorithms and range-for over hand-written loops; `enum class` over + plain `enum`; `nullptr` over `NULL` or `0`; `using` over `typedef`. +- No C-style casts; use `static_cast` and friends. No mutable global state. +- Headers are self-contained and contain declarations, templates and + `inline` definitions only. + +## Errors + +Use exceptions for exceptional failures, or `std::expected` and error codes +where the project forbids exceptions; one choice per project. Destructors +never throw. Catch by `const&`; never `catch (...)` without rethrowing or +logging. + +## Tests + +GoogleTest, Catch2 or doctest; run under sanitizers (`address`, `undefined`) +in at least one build. + +## Tooling + +`clang-format`, `clang-tidy` with the Core Guidelines checks, compiler +warnings (`-Wall -Wextra -Wpedantic`), sanitizers. + +Review with `QC-CPP-001`. diff --git a/.claude/skills/coding-conventions/references/csharp.md b/.claude/skills/coding-conventions/references/csharp.md new file mode 100644 index 0000000..88abb3b --- /dev/null +++ b/.claude/skills/coding-conventions/references/csharp.md @@ -0,0 +1,72 @@ +# C# conventions + +## Standard base + +Microsoft's C# coding conventions and .NET Framework Design Guidelines, with +the analyzers that ship in the SDK. Target the language version of the +project's `LangVersion` / target framework. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Namespace | `PascalCase`, matches folder path | `Billing.Stays` | +| Class, struct, record, enum, delegate | `PascalCase` (nouns) | `StayReader` | +| Interface | `I` + `PascalCase` | `IStayReader` | +| Method, property, event, public field | `PascalCase` | `ReadStays()`, `CheckIn` | +| Constant, `static readonly` | `PascalCase` | `MaxRetries` | +| Enum value | `PascalCase`; `[Flags]` enums are plural | `Status.NotFound` | +| Parameter, local variable | `camelCase` | `byteCount` | +| Private / internal field | `_camelCase` | `_buffer` | +| Generic type parameter | `T` or `T` + `PascalCase` | `T`, `TKey` | +| Async method | ends in `Async` | `ReadStaysAsync()` | +| Exception, attribute | end in `Exception` / `Attribute` | `InvalidDateException` | +| Boolean | `Is`, `Has`, `Can` prefix | `IsActive` | +| File | the type's name, one top-level type per file | `StayReader.cs` | + +- Two-letter acronyms are upper case (`IO`); longer ones are `PascalCase` + (`Xml`, `Http`). + +## Formatting + +- `.editorconfig` checked in; `dotnet format` applies it. 4 spaces, Allman + braces, braces on every control-flow body. +- File-scoped namespaces (`namespace X;`); `using` directives outside the + namespace, `System` first. +- `var` when the type is obvious from the right-hand side, explicit type + otherwise. + +## Language rules + +- Enable nullable reference types (`enable`) and treat + nullable warnings as errors; do not suppress with `!` without a comment. +- `IDisposable` owners use `using`; implement the dispose pattern only when + needed. +- `async`/`await` all the way; no `.Result` or `.Wait()`; no `async void` + except event handlers; pass `CancellationToken` through public async APIs. +- Prefer properties over public fields, `readonly` and `init` for + immutability, `record` for value-like data, pattern matching and switch + expressions over long `if` chains. +- LINQ for queries, loops for side effects; do not enumerate a sequence twice. +- String interpolation over concatenation; `StringBuilder` in loops; + `DateTimeOffset` over `DateTime` for points in time; `decimal` for money. +- XML documentation comments (`///`) on public types and members. + +## Errors + +Throw specific exceptions (`ArgumentNullException`, custom types); validate +arguments at the public boundary (`ArgumentNullException.ThrowIfNull`). Catch +the narrowest type; `throw;` (not `throw ex;`) to rethrow. Never an empty +`catch`. + +## Tests + +xUnit, NUnit or MSTest; names like `Method_Condition_Expected`; one behaviour +per test; no dependence on order, time or the network. + +## Tooling + +`dotnet format`, the .NET analyzers (`AnalysisLevel`, `EnforceCodeStyleInBuild`) +and optionally StyleCop.Analyzers, configured in `.editorconfig`. + +Review with `QC-CS-001`. diff --git a/.claude/skills/coding-conventions/references/python.md b/.claude/skills/coding-conventions/references/python.md new file mode 100644 index 0000000..e262961 --- /dev/null +++ b/.claude/skills/coding-conventions/references/python.md @@ -0,0 +1,66 @@ +# Python conventions + +## Standard base + +PEP 8 (style), PEP 257 (docstrings), PEP 484 and later (type hints). Target +the Python version declared in `pyproject.toml`. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Package / module | short `snake_case` | `billing`, `stay_reader.py` | +| Class, exception | `PascalCase`; exceptions end in `Error` | `StayReader`, `InvalidDateError` | +| Function, method, variable, parameter | `snake_case` | `total_price`, `read_stays()` | +| Constant (module level) | `UPPER_SNAKE` | `MAX_RETRIES` | +| Internal (not public API) | one leading underscore | `_parse_row` | +| Type variable | short `PascalCase`; `_co` / `_contra` for variance | `T`, `KeyT`, `ItemT_co` | +| Boolean | `is_`, `has_`, `can_` prefix | `is_active` | +| Test file / function | `test_.py` / `test__` | `test_total_when_empty` | + +- Avoid name mangling (`__name`) unless you need it to prevent a subclass clash. +- Never use `l`, `O` or `I` as single-letter names. +- Do not shadow builtins (`list`, `id`, `type`); add a trailing underscore + (`type_`) only as a last resort. + +## Formatting + +- 4 spaces, no tabs. Maximum line length set once in the formatter config + (88 with `ruff format`; 79 if the project follows PEP 8 strictly). +- Imports at the top, grouped standard library / third party / local, one + blank line between groups, no wildcard imports. +- Double quotes for strings unless the formatter says otherwise. +- Trailing commas in multi-line literals and calls. + +## Language rules + +- Annotate every function signature (parameters and return, `-> None` too). + Modern syntax: `X | None`, `list[str]`. Avoid `Any` without a comment. +- `pathlib` over `os.path`; f-strings over `%` or `.format`; `enum` over + magic strings; `dataclass` (frozen where possible) over ad-hoc dicts. +- No mutable default arguments; no bare `except:`; no `print` for logging + (use `logging`). +- Use context managers (`with`) for files, locks and connections. +- Prefer comprehensions over `map`/`filter` with lambdas; keep them simple. +- Docstrings (PEP 257) on public modules, classes and functions; say what, + not how. + +## Errors + +Raise specific exceptions; catch the narrowest type; re-raise with +`raise ... from err` to keep the cause. Do not use exceptions for normal +control flow. + +## Tests + +`pytest`; one behaviour per test; `tmp_path` for files; fakes over mocks where +a simple fake is possible; tests do not depend on order or on the network. + +## Tooling + +`ruff` (lint and format) and `mypy --strict` (types), configured in +`pyproject.toml`. Architecture rules (layers, ports, dataframes) are in +`.agents/rules/python.md` and the `python-developer` agent; this sub-skill +covers naming and style only. + +Review with `QC-PY-001`. diff --git a/.claude/skills/coding-conventions/references/shell.md b/.claude/skills/coding-conventions/references/shell.md new file mode 100644 index 0000000..aa8a728 --- /dev/null +++ b/.claude/skills/coding-conventions/references/shell.md @@ -0,0 +1,62 @@ +# Shell conventions (bash) + +## Standard base + +Bash 4 or later, POSIX `test` semantics through `[[ ]]`. Start every script +with `#!/usr/bin/env bash` and `set -euo pipefail`. State the bash version and +the external tools it needs in the header comment. + +## Naming + +| Element | Convention | Example | +| --- | --- | --- | +| Script file | `kebab-case.sh`, executable | `check-plan.sh`, `new-artifact.sh` | +| Function | `snake_case`, a verb | `read_registry`, `die` | +| Local variable, parameter | `snake_case`, declared with `local` | `msgfile`, `changed` | +| Constant, environment variable | `UPPER_SNAKE` | `PLAN_GATE`, `PROJECT_ROOT` | +| Boolean | `is_` / `has_` prefix, value `0` or `1` | `is_enabled=1` | + +- Name a script and its functions by what they do, not how. +- Do not shadow a command with a function of the same name. + +## Formatting + +- 2 spaces, no tabs. One command per line; `then` and `do` on the same line as + `if` and `for`. Keep lines near 80 characters; break long pipelines at `|`. +- Format with `shfmt -i 2 -ci`; lint with `shellcheck`. Commit the project's + `.editorconfig` or `.shellcheckrc` with the code. + +## Language rules + +- **Quote every expansion** (`"$var"`, `"${arr[@]}"`); use arrays, not + space-separated strings, for lists. Use `[[ ]]`, not `[ ]`, and `$(...)`, + not backticks. +- Declare function variables `local`; no globals except constants. +- Parse options with `case` and `shift`, check required arguments with + `"${1:?usage: ...}"`, and print a usage line on bad input. +- Read input with `read -r`; iterate files with globs or `find -print0`, never + by parsing `ls`. +- Use `mktemp` for temporary files and remove them with `trap ... EXIT`; never + a fixed `/tmp` name. + +## Errors and exit codes + +- Errors go to standard error, start with `error:`, say what is wrong and what + to do, and end the script with a non-zero exit code (`die` helper). +- `0` is success, `1` a failed check or bad input, `2` a usage error; document + any other code in the header. +- Never swallow a failure with `|| true` without a comment that says why. + +## Safety + +- A script that changes state outside its own directory defaults to a dry run + or asks for an explicit flag (`--apply`, `--force`); say so in the header. +- Never echo a token or password, put one on a command line, or commit one; + read secrets from the environment or a gitignored file. +- Do not `eval` input; do not build a command from unvalidated text. + +## Tools + +Formatter `shfmt`, linter `shellcheck`, syntax check `bash -n`. These are the +recommended tools, not a pipeline: enforcing them in CI is outside this +framework's scope. diff --git a/.claude/skills/project-planning/SKILL.md b/.claude/skills/project-planning/SKILL.md new file mode 100644 index 0000000..d1c429d --- /dev/null +++ b/.claude/skills/project-planning/SKILL.md @@ -0,0 +1,278 @@ +--- +name: project-planning +description: Plan a project (or a new phase of one) in phases with tasks, and sync those phases and tasks to Gitea or GitHub as Milestones and Issues. Use when starting a new project, adding or updating a phase/gateway, breaking a phase down into tasks, deciding whether a task needs its own use case or user story, or asked to create/update project milestones or issues on the git host. +--- + +# Project Planning + +Plans a project as phases (gateways), each phase as a set of tasks, and +keeps those phases and tasks in sync with the git host's own project +management (Milestones and Issues). It builds on the `artifact` skill's +`PP` (Project Plan) and `MIL` (Milestone/Gateway) types. + +## Domain language first + +Before planning, find the Product Owner's (PO's) domain language. Take it from +the first of these that states it: + +1. the user's prompt; +2. a file the user included or that the project already has (the `Languages` + section of `docs/artifact-registry.md`). + +If none states it, **ask the user for it** and stop planning until it is +answered; never assume one. Record the answer in the registry's `Languages` +section. If it differs from the project's working language, the high-level +artifacts are also kept in it (see the registry's translation list). + +## Start here + +Before planning or building anything, check that the baseline exists (the +`docs/artifact-registry.md` rows and files): the Business Case (`BC`), the +Stakeholder Analysis (`SA`), the Project Plan (`PP`) and at least one +milestone (`MIL`). If one is missing, create it first, in that order, with +`new-artifact.sh` (it refuses when a type in the catalog's `Requires` column +is missing). + +A "build X" request is planning-first. Produce the phases, tasks and issues, +show the dry run of `sync-project.sh`, and ask for a go-ahead before any code +is written; running `--apply` is the user's decision. Only the user can waive +the plan, in chat, for that request; the waiver does not carry over. The rule +is defined in `framework/process/plan-first-gate.md`. + +## The hierarchy + +``` +Business goal → Feature/requirement → Use case/user story → Tasks +``` + +The use case/user story explains **why** a feature exists; tasks explain +**how** the team implements it. Not every task needs a use case: + +- **Needs a use case/user story** — the task is something a user, or + another system, actually does: "User resets password", "Admin exports + customer report", "Payment service processes refund". +- **Plain task, no use case** — purely technical/implementation work: + "Refactor authentication middleware", "Add database index", "Upgrade + React version", "Fix null-pointer bug", "Add unit tests", "Configure CI + pipeline", "Optimize SQL query". + +When in doubt, ask: does this row describe a goal an actor is pursuing, or +a step the team takes to build something? Goals get a use case; steps stay +a plain task. + +## Use cases get their own folder + +Each use case lives in `docs/uc-NNN/` (`UC-001` → `docs/uc-001/`), together +with the artifacts that belong to it. Nothing about a use case goes in a +shared `docs/use-cases/` folder. + +1. **Create the folder and the use case:** + `bash framework/scripts/new-artifact.sh UC --file docs/uc-001/uc.md`. +2. **Create only the artifacts this use case affects,** in this order, each in + the same folder with a fixed file name. Skip any it does not touch (no + `erd.md` if nothing is stored; no `dm.md` if it adds no concept). + + | Order | Type | File | Create when the use case… | + | --- | --- | --- | --- | + | 1 | `SSD` | `ssd.md` | has system interaction to show (almost always) | + | 2 | `DM` | `dm.md` | introduces or changes domain concepts | + | 3 | `OC` | `oc.md` | has system operations that change state | + | 4 | `SD` | `sd.md` | needs a collaboration design for an operation | + | 5 | `DCD` | `dcd.md` | adds or changes design classes | + | 6 | `ERD` | `erd.md` | adds or changes persisted data | + + ```bash + bash framework/scripts/new-artifact.sh SSD --file docs/uc-001/ssd.md + bash framework/scripts/new-artifact.sh DM --file docs/uc-001/dm.md --cite UC-001=docs/uc-001/uc.md + ``` + + `new-artifact.sh` cites only the artifacts in the same use-case folder + (and project-level ones); for `DM`, `DCD` and `ERD`, add the use case and + sibling artifacts by hand with `--cite`. Each gets its own ID (the next + version in the registry, e.g. `DM-002`) and its own `RC-*` review. +3. **Reconcile with the project models.** The use-case artifacts are a scoped + view; the project-level `docs/domain-model.md`, `docs/dcd.md` and + `docs/erd.md` are the consolidated truth. When the use case's `DM`, `DCD` + or `ERD` are done, compare each with its project-level document: + - add the new concepts, classes, attributes and entities; change the ones + the use case modified; + - keep names identical to the existing ones, and resolve any conflict + with another use case's model instead of duplicating the element; + - give each project-level document a new `## Version History` row (Change: + which use case caused it), and create it from the first use case's + document if it does not exist yet; + - if nothing needs to change, say so in the use case's task and PR + description ("project DM/DCD/ERD unchanged: "). + +## Planning a project (or a new phase) + +1. **Phases are gateways.** Each phase is a `MIL-*` document (the `artifact` + skill's `MIL` type): purpose, deliverable, Go/No-Go criteria, dependencies, + ownership, target date. Create one with + `bash framework/scripts/new-artifact.sh MIL --file docs/milestones/mil--.md`. +2. **The plan schedules the phases.** `docs/project-plan.md` (the `artifact` + skill's `PP` type) lists every phase with its window and owner, and holds + the overall timeline diagram. Create it once with + `bash framework/scripts/new-artifact.sh PP`. +3. **Break each phase into tasks.** In the phase's `## Tasks` section, add + one row per task using the hierarchy rule above. Tasks that need a use + case or user story get one created first (`UC`/`US` types; a use case + follows "Use cases get their own folder" below), then are referenced from + the Tasks row; plain tasks just describe the work. +4. **Sync to the git host.** Run the sync tool (below) to create or update + the corresponding Milestones and Issues. Do this whenever a phase or its + tasks change — the tool is idempotent (matches by title, never creates a + duplicate). + +## Syncing to Gitea/GitHub + +```bash +bash framework/scripts/sync-project.sh # prints the plan only — no network calls +bash framework/scripts/sync-project.sh --milestone MIL-002 # limit to one phase +bash framework/scripts/sync-project.sh --apply # actually create/update on the git host +``` + +- **Default is a dry run**: it parses `docs/milestones/mil-*.md` and prints + what would be created or updated. Nothing is sent anywhere. +- **`--apply`** performs the real requests. It needs: + - **Gitea** (default — detected from `origin`'s hostname): `GITEA_TOKEN` + env var, a personal access token. This is an HTTP API call (milestones, + issues) — a deploy key cannot be used, since deploy keys only + authenticate SSH git transport (clone/fetch/push), not the REST API. + Scope the token to issues only if your Gitea version supports scoped + tokens, rather than a full-account one. + - **GitHub** (detected when `origin` is on github.com, or pass + `--host github`): the `gh` CLI, already logged in (`gh auth login`). +- **`--with-project`** additionally tries to create/attach a Kanban Project + board. This is best-effort: some Gitea versions (confirmed on 1.27.3) show + Projects/Kanban only in the web UI and expose **no REST API for it at + all**, so this always fails there — check your server's own + `https:///swagger.v1.json` for any `project` path if unsure. GitHub + Projects (v2) needs `gh` with the `project` scope. Either way the script + warns and continues; Milestones and Issues are unaffected. Where there's + no API, create the board by hand at `https://///projects`. +- Read the script's header comment for the full flag list, including + `--owner`, `--repo`, `--api-base` to override auto-detection. + +`--apply` is an outward-facing, hard-to-reverse action (it creates real +Milestones/Issues on the git host) — run it yourself once you're ready, or +ask explicitly for it to be run. + +## Branching before commits + +**Never commit, push or open a PR unless the user asks.** The user reviews +the working-tree changes first; finish the edits, summarise them and stop. +Everything below (branching, closing keywords, resolving commit links, the +PR) describes how to do those steps once the user has asked for them; it is +not permission to start them. + +Never commit directly on `main`. This is enforced locally by a pre-commit +hook (`framework/githooks/pre-commit`) once +`bash framework/scripts/install-git-hooks.sh` has been run in this clone — +run it once per clone; it points `core.hooksPath` at the versioned +`framework/githooks/` instead of the per-clone, untracked `.git/hooks/`. +The hook refuses the commit with a pointer back to this section; a rare, +deliberate exception can bypass it with `ALLOW_MAIN_COMMIT=1 git commit`. + +Before the first commit of a piece of work, create and switch to a new +branch, then commit there: + +```bash +git checkout -b +# ... commits ... +git push -u origin +``` + +- Name the branch for the gateway/task it covers, kebab-case, e.g. + `g2-kpi-bmc-bpmn` or `mil-002-kpi-baseline` — short enough to read in a + PR list, specific enough to say what it's for. +- Open a PR (`gh pr create` on GitHub, or the Gitea equivalent) instead of + merging straight to `main`; this project's own history is a merged PR + per phase (e.g. "Merge pull request 'Close G1 inception baseline...'"), + so keep following that pattern. +- This applies to every commit, not just gateway/task work — if in doubt + whether the current branch is `main`, check (`git branch --show-current`) + before committing. + +## Closing tasks from commits + +When a commit finishes the work for a task that `sync-project.sh` has +already synced as an Issue, reference that Issue number in the commit +message so Gitea/GitHub auto-closes it once that commit lands on the +default branch (`main`) — via the PR merge required by "Branching before +commits" above, not by pushing the closing keyword to a feature branch. +Use `Refs #N` instead when the commit only touches the task without +finishing it — that links the commit without closing. + +- **One issue per commit:** use `Closes #5`. +- **Several issues closed by the same commit:** put one `Closes #N` per + line, not a comma-separated list (`Closes #5, #6, #7` only closed `#5` on + a confirmed live Gitea instance — the comma form is not reliably parsed): + + ``` + Closes #5 + Closes #6 + Closes #7 + ``` +- Get each issue number either from the most recent `sync-project.sh` / + `sync-project.sh --apply` output (it prints `updated issue #N` / + `created issue #N` per task) or, if that's not at hand, from the git + host's issue list for the milestone. +- Match commits to issues by the task row they implement — one task row in + a `MIL-*` document's `## Tasks` section is one Issue, so a commit that + completes that row's work closes that Issue. +- Don't guess an issue number; if it isn't known from a recent sync or a + lookup, ask rather than omit or fabricate one. +- **After pushing a multi-issue closing commit, verify** each issue's state + came back `closed` (e.g. `GET /repos///issues/` with + `GITEA_TOKEN`) rather than assuming the whole list closed; close any that + didn't with a direct `PATCH .../issues/` `{"state":"closed"}` call. + +## Pull requests close the issues they complete + +Every PR must close the Issues its work finishes, so the board matches +reality once it merges. Before opening (or updating) a PR: + +1. **List the issues the branch completes.** Go through the task rows the + branch implements (`git log main..HEAD`, plus the `## Tasks` of the + `MIL-*` it belongs to) and get each Issue number as described in "Closing + tasks from commits". +2. **Put one closing line per issue in the PR description**, one per line, + never comma-separated: + + ``` + Closes #5 + Closes #6 + ``` + + Use `Refs #N` for an issue the PR only touches. A PR that finishes no + issue says so explicitly ("No issue closed: ") instead of saying + nothing. +3. **Ask, don't guess.** If an issue number is unknown or a task is only + partly done, ask rather than omit or invent one. Leave a partly done task + open and note what remains. +4. **After the merge, verify** that each issue is `closed` (the check in + "Closing tasks from commits") and close any stragglers by hand. Also make + sure the finished task rows are reflected in the `MIL-*` document and, when + every task of a phase is closed, that the Milestone is closed too. + +5. **Resolve pending commit links before the PR** (see "Version History rule" + in the `artifact` skill): commit, run + `bash framework/scripts/resolve-pending-commits.sh `, then + commit the result as a follow-up commit. +6. **Never ask for, offer or perform the merge.** A PR needs a reviewer: ask + the user to open the PR / request a review, and stop there. Merging, + enabling auto-merge and "shall I merge?" are not yours to do. + +Closing keywords in the PR description and in commit messages both count on +Gitea and GitHub; they only take effect when the PR merges into the default +branch. + +## Files this skill touches + +- `docs/project-plan.md` — `PP`, via the `artifact` skill. +- `docs/milestones/mil-*.md` — `MIL`, via the `artifact` skill, each with a + `## Tasks` section. +- `docs/uc-NNN/*.md` (the use case and its `SSD`, `DM`, `OC`, `SD`, `DCD`, `ERD`), `docs/user-stories.md` — only for tasks that need one; plus `docs/domain-model.md`, `docs/dcd.md`, `docs/erd.md` when reconciling. +- `framework/scripts/sync-project.sh` — never edited per project; propose + changes upstream in the framework. diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..a759dc9 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "framework"] + path = framework + url = ssh://git@git.tirsystem.com:10022/TirSystem/SQA-QC-Framework.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..aaa1f03 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,53 @@ +# AGENTS.md + +This project uses the SQA and QC framework mounted at `framework/`. + +For any document under `docs/` (create, edit or review) use the `artifact` +skill. For planning a project or a phase into tasks, and syncing phases and +tasks to Gitea/GitHub as Milestones and Issues, use the `project-planning` +skill. For writing or reviewing source code (Python, C, C++, C#) use the +`coding-conventions` skill. Skills are read from `.agents/skills/` (this harness and Codex CLI) +and `.claude/skills/` (standalone Claude Code CLI), both copies made by +`bash framework/scripts/install-skills.sh` — re-run it after updating the +framework. + +**Never commit, push or open a PR unless asked.** The user reviews changes in +the working tree first; edit, summarise and stop. The commit/PR rules below +apply once a commit has been asked for. + +## Workflow order + +Business Case, Stakeholder Analysis, Project Plan, milestones, tasks synced as +issues, then code. Nothing goes under `src/` or `tests/` unless a milestone +document (`MIL-*`) is accepted and the task is a row in it (ideally a synced +issue). If those are missing, plan with the `project-planning` skill, show the +dry-run output of `bash framework/scripts/sync-project.sh`, and stop. The rule +is defined once in `framework/process/plan-first-gate.md`. + +A "build X" request is planning-first: produce the plan and issues, then ask +for a go-ahead. Only the user can waive the plan, in chat, for that request. +Before planning, find the Product Owner's language (the prompt, or the +`Languages` section of `docs/artifact-registry.md`); if neither states it, ask. + +To enforce the gate at commit time, run +`bash framework/scripts/install-git-hooks.sh --enable-plan-gate`: a commit that +changes `src/` or `tests/` then needs a `Task: MIL-NNN#N` trailer. + +Rules that apply to every document: + +1. Get the short name from `framework/registry/artifact-catalog.md` and the + next version from `docs/artifact-registry.md`. Create files with + `bash framework/scripts/new-artifact.sh `. +2. Owners, reviewers and RACI use stakeholder IDs from the project's + Stakeholder Analysis, never invented role names. +3. Every QC criterion is tagged with an ISO/IEC 25010:2023 characteristic. +4. Every reviewed instance gets an `RC-*` record in `docs/sqa/reviews/`. +5. Do not edit `framework/` from this project; propose changes upstream. +6. Every PR description closes the issues its work completes, one + `Closes #N` per line (`Refs #N` for partial work); see the + `project-planning` skill. +7. Every document's `## Version History` has `Change` and `Commit` columns and + keeps the two latest rows. After committing, run + `framework/scripts/resolve-pending-commits.sh` and commit the result before + opening the PR (no amend). Never ask for or perform the merge: a reviewer + merges. diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md new file mode 100644 index 0000000..f14b5f5 --- /dev/null +++ b/docs/artifact-registry.md @@ -0,0 +1,43 @@ +# Artifact Registry + +This project's artifact state. Types, short names and `CrossReference +Candidates` come from the framework catalog +(`framework/registry/artifact-catalog.md`); this file only records where +each document lives in *this* project and the next version to use. + +Delete rows for types you don't use. Add a row the first time you create a +document of a type. `Primary File` may contain a glob (e.g. +`docs/uc-*/uc.md`); `framework/scripts/find-crossreferences.sh` reads it. + +| Short Name | Artifact Type | Primary File | Next Available Version | +| --- | --- | --- | --- | +| BC | Business Case | docs/business-case.md | 002 | +| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | +| PP | Project Plan | docs/project-plan.md | 002 | +| MIL | Milestone / Gateway | docs/milestones/mil-*.md | 003 | + +## Languages + +Set the PO language when the project starts; `project-planning` asks for it +if it is missing. A translated artifact is named `..md` +(for example `business-case.da.md`); the English file stays the source. + +| Setting | Value | +| --- | --- | +| PO language | en | +| High-level register | IT Executive English | +| Technical register | IT Professional English | + +| Artifact types | Register | Also kept as a PO-language file | +| --- | --- | --- | +| BC, KPI, PP, MIL | IT Executive English | Yes | +| SA, BMC, BPMN, UCD, US, UC, SSD, DM, RA, GOV, DICT | IT Professional English | Yes | +| OC, SD, DCD, ERD, ADR, TM, RC, QC, source code | IT Professional English | No | + +## Notes + +- "Next Available Version" is the zero-padded (3-digit) version to use the + *next* time a new document of that type is created. Increment it only when + a brand-new document is created, not when an existing document's + `## Version History` gets a row. +- `ADR` uses 4 digits (`0001`); `RC` is sequential across all artifact types. diff --git a/docs/business-case.md b/docs/business-case.md new file mode 100644 index 0000000..7136759 --- /dev/null +++ b/docs/business-case.md @@ -0,0 +1,129 @@ +# Business Case + +## Metadata +| Key | Value | +| --- | --- | +| ID | BC-001 | +| CrossReference | [SA-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-04 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Executive Summary + +This project delivers a console Blackjack game written in Python as the first capstone of the Udemy course *100 Days of Code: The Complete Python Pro Bootcamp* (day 11). The player plays against a computer dealer under simple house rules, using emoji playing cards. The project doubles as a worked example of the SQA/QC framework: a small, fully planned, tested and documented Python 3.13+ code base that is easy to review. + +## Methodological and Standards Foundation + +The work follows the project's SQA and QC framework (artifact-first, plan-first gate, review records per artifact). Quality criteria are tagged with ISO/IEC 25010:2023 characteristics. Source code follows the framework's Python coding conventions and is documented with Doxygen comments. + +## Problem Statement + +The course assignment asks for a complete program that combines functions, lists, loops, conditionals and user input. Without a plan, the work is easily done as one unstructured script that is hard to test, review or reuse, and that loses the course's learning value. + +## Business Opportunity + +A small, well-structured game shows the full delivery chain (plan, tracked issues, branches and pull requests, tests, generated documentation) on a problem that is simple enough to finish quickly. The result can be reused as a template for the remaining capstone projects. + +## Objectives + +1. Implement Blackjack for one player against a computer dealer following the house rules below. +2. Render cards as emoji and show the course's ASCII logo at the start of every game. +3. Separate game rules (pure functions) from console input/output so the rules can be unit-tested. +4. Provide a reproducible local setup (venv, `pyproject.toml`) and run/test instructions. +5. Document the source with Doxygen comments and ship a `Doxyfile`. +6. Track every step as a milestone, issue and pull request on the project's git host. + +House rules: unlimited deck, no jokers, Jack/Queen/King count 10, Ace counts 11 or 1, drawn cards are not removed, the computer is the dealer and draws while its score is below 17, a two-card Ace + 10 hand is a blackjack. + +## Scope + +### In Scope + +- Game logic: `deal_card`, `calculate_score`, `compare`, dealer play, game loop and restart prompt. +- Emoji card rendering and the logo from the assignment. +- Project scaffolding: `src/`, `tests/`, `docs/`, `pyproject.toml`, `constants.py`, Python `.gitignore`, `Doxyfile`, `README.md`. +- Unit tests for the rules and the console flow (with scripted input). +- Git host housekeeping: repository description and topics. + +### Out of Scope + +- Splitting, doubling down, insurance, betting and multi-player. +- Graphical or web user interface; network play. +- Packaging for PyPI or any deployment. +- Runtime third-party dependencies. + +## Expected Benefits + +### Tangible Benefits + +- A working, tested console game that matches the assignment's behaviour. +- A reusable project skeleton and documentation set. + +### Intangible Benefits + +- Practice of planning-first delivery with traceable issues and pull requests. +- Confidence in the Python tooling chain (venv, pyproject, tests, Doxygen). + +## Strategic Alignment + +The project supports the owner's goal of completing the 100 Days of Code course while building a public portfolio of repositories that follow one consistent, reviewable quality process, shared with fellow coursists and useful as an idea source for GitHub visitors. + +## Success Criteria + +| # | Criterion | Target | Measure | +| --- | --- | --- | --- | +| 1 | Functional suitability: the house rules behave as specified | 100 % of rule unit tests pass | `python -m unittest` exit code 0 | +| 2 | Maintainability: rules are testable without console I/O | `calculate_score`, `compare` and `deal_card` contain no `input()`/`print()` calls | Code review | +| 3 | Portability: runs on Python 3.13+ with no runtime dependencies | `pyproject.toml` lists zero runtime dependencies | Inspection of `pyproject.toml` | +| 4 | Usability: documentation lets a new user run and test the game | Setup to first game in under 5 minutes following the README only | Walkthrough on a clean clone | +| 5 | Maintainability: source documentation is generated | `doxygen Doxyfile` completes without warnings | Doxygen log | + +## Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | +| Emoji cards render badly in some Windows terminals | Cards unreadable, poor usability | Document a UTF-8 capable terminal; keep the card symbols in `constants.py` so they are easy to change | +| Randomness makes tests flaky | Unreliable tests | Patch `random.choice` or inject the card source in tests | +| Scope creep (betting, splitting) | Late delivery | Out of Scope list; changes need a new milestone | +| Secrets in `.env` leak into the repository | Credential exposure | `.env` is git-ignored and is never imported or tested by the project | + +## Assumptions + +- The Product Owner and sole developer is stakeholder `S01`. +- The repository is public, so coursists (`S02`) and viewers (`S03`) can read it. +- The git host is `git.tirsystem.com`, organisation `Tirsvad-Udemy-100_days_of_code`. +- Python 3.13 or newer is installed locally. + +## Constraints + +- Python 3.13+ and a venv-based workflow; `pyproject.toml` for configuration. +- Constants live in `constants.py`; layout is `src/`, `tests/`, `docs/`. +- No runtime dependencies unless needed. +- Nothing is committed, pushed or merged without the owner's request; work is done on branches and pull requests. + +## Cost–Benefit Assessment + +| Costs | Benefits | +| --- | --- | +| About two evenings of developer time (qualitative: learning project, no budget) | Completed capstone, reusable skeleton, practised process | + +## Stakeholders + +| Stakeholder ID (SA) | Interest in this project | +| --- | --- | +| S01 | Owns scope and acceptance; takes the course, builds and reviews the game | +| S02 | Fellow coursists who share code and compare solutions | +| S03 | GitHub viewers who browse the repository for ideas | + +## Recommendation + +Proceed - the scope is small, the rules are fully specified by the assignment and the risks are cheap to mitigate. + +--- + +[SA-001]: ./stakeholder-analysis.md diff --git a/docs/milestones/mil-001-project-setup.md b/docs/milestones/mil-001-project-setup.md new file mode 100644 index 0000000..21ef739 --- /dev/null +++ b/docs/milestones/mil-001-project-setup.md @@ -0,0 +1,71 @@ +# Gateway 1 - Project Setup + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-001 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-04 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Decide whether the project foundation (repository metadata, layout, tooling, documentation skeleton) is ready so that game code can be added on top of it. + +## Deliverable + +A repository with `src/`, `tests/`, `docs/`, a `pyproject.toml` (Python 3.13+, no runtime dependencies), `constants.py`, a Python `.gitignore`, a `Doxyfile`, a `README.md` that documents the local `.venv` and the pip upgrade, and a repository description with topics on the git host. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | `pip install -e .` works in a fresh `.venv` on Python 3.13+ | Succeeds | Fails | +| 2 | `python -m unittest` runs (with at least one smoke test) | Exit code 0 | Non-zero | +| 3 | `doxygen Doxyfile` runs | No errors | Errors | +| 4 | README documents venv creation, `python -m pip install --upgrade pip`, run and test | All present | Any missing | +| 5 | Repository has a description and topics | Visible on the git host | Missing | +| 6 | `.env` is git-ignored and not referenced by any file under `src/` or `tests/` | True | False | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| None | First gateway | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| Objectives 4, 5 and 6 | [BC-001] | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S01 | +| Approving reviewer | S01 | + +## Target Date + +2026-10-06 - within the two-evening effort assumed in the Business Case. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Add repository description and topics | Set a one-line description and topics (python, blackjack, udemy, 100-days-of-code, cli-game) on the git host repository through its API, using the token from the local `.env`. The `.env` file is for personal use only and is never imported, tested or committed. | No | | +| 2 | Create project layout and pyproject.toml | Create `src/`, `tests/` and a `pyproject.toml` that requires Python 3.13 or newer, defines the package under `src/`, has no runtime dependencies and configures the unittest entry. Verify the existing Python `.gitignore` covers `.venv/` and `.env`. | No | | +| 3 | Add constants module | Create `constants.py` with the deck list `[11, 2, 3, 4, 5, 6, 7, 8, 9, 10, 10, 10, 10]`, the blackjack target 21, the dealer stand threshold 17, the ace values and the emoji card faces, so no magic numbers appear in game code. | No | | +| 4 | Add Doxyfile | Add a `Doxyfile` that reads `src/`, writes to `docs/doxygen/`, and extracts Python documentation from Doxygen-style comments. | No | | +| 5 | Write README with venv and run/test instructions | Write `README.md` (standard layout) with description, requirements, creating and activating a local `.venv`, `python -m pip install --upgrade pip`, installing the project, running the game, running the tests and generating Doxygen documentation. | No | | +| 6 | Add smoke test for package import | Add one unittest that imports the package, so the test command is proven to work before any game logic exists. | No | | + +--- + +[BC-001]: ../business-case.md diff --git a/docs/milestones/mil-002-game-implementation.md b/docs/milestones/mil-002-game-implementation.md new file mode 100644 index 0000000..a29a3b2 --- /dev/null +++ b/docs/milestones/mil-002-game-implementation.md @@ -0,0 +1,74 @@ +# Gateway 2 - Game Implementation + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-002 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-04 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Decide whether the Blackjack game is complete, correct under the house rules and ready to be played from the console. + +## Deliverable + +A runnable console game (`python -m blackjack` from the activated venv) with emoji cards and the course logo, a unit-test suite covering the rules, and Doxygen comments on all public functions. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | Unit tests for `deal_card`, `calculate_score` and `compare` cover every house rule | All pass | Any fail | +| 2 | An Ace + 10 two-card hand scores 0 (blackjack); an Ace is demoted from 11 to 1 when the hand exceeds 21 | Verified by test | Not verified | +| 3 | The dealer draws while its score is below 17 | Verified by test | Not verified | +| 4 | A scripted full game (hit, stand, restart answer) runs to the end without error | Passes | Fails | +| 5 | Rule functions contain no `input()` or `print()` calls | True | False | +| 6 | `doxygen Doxyfile` documents every public function | No warnings | Warnings | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| [MIL-001] | Needs the layout, constants, tooling and test runner | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| Objectives 1, 2, 3 and 5 | [BC-001] | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S01 | +| Approving reviewer | S01 | + +## Target Date + +2026-10-11 - five days after the setup gateway, within the Business Case effort estimate. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Implement deal_card | Return a random card from the deck constant using `random.choice`. The deck is unlimited and cards are never removed, so each draw is independent. Add a Doxygen comment and unit tests with `random.choice` patched. | No | | +| 2 | Implement calculate_score | Sum a list of cards, return 0 for a two-card Ace + 10 blackjack, and replace an 11 with 1 while the total exceeds 21. Pure function without console I/O; unit-tested for blackjack, bust, multiple aces and normal totals. | No | | +| 3 | Implement compare | Take user and computer scores and return the outcome: draw on equal scores, user loses on dealer blackjack or user bust, user wins on user blackjack or dealer bust, otherwise the higher score wins. Check order follows the assignment's hint 13. | No | | +| 4 | Render emoji cards and logo | Convert card values to emoji faces (suit emoji with the card rank) from the constants, and print the course logo from `art.py` at the start of each game. Keep rendering separate from the rules. | No | | +| 5 | Implement dealer play and game loop | Deal two cards each, show hands, let the user hit or stand until bust, blackjack or stand, then let the dealer draw while below 17, compare and print the result. Console input and output sit in one module that calls the pure rule functions. | No | | +| 6 | Implement restart prompt and console clear | After each game ask whether to play again; on yes clear the console and start a new game, on no exit cleanly. Handle invalid answers by asking again. | No | | +| 7 | Add scripted end-to-end test | Run a full game with `input` and `random.choice` patched, covering hit, stand, bust, blackjack and restart, and assert the printed outcome. | No | | +| 8 | Add Doxygen comments and generate docs | Ensure every public module, function and constant has a Doxygen comment, run `doxygen Doxyfile` and fix any warnings. | No | | + +--- + +[BC-001]: ../business-case.md +[MIL-001]: ./mil-001-project-setup.md diff --git a/docs/project-plan.md b/docs/project-plan.md new file mode 100644 index 0000000..7a6cbed --- /dev/null +++ b/docs/project-plan.md @@ -0,0 +1,83 @@ +# Project Plan + +## Metadata +| Key | Value | +| --- | --- | +| ID | PP-001 | +| CrossReference | [BC-001], [SA-001], [MIL-001], [MIL-002] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-04 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Schedule the two gateways that deliver the Blackjack game within the Business Case's two-evening effort constraint ([BC-001]). + +## Planning Assumptions + +- Week 1 starts 2026-10-04; the plan ends by 2026-10-11. +- Phase length: setup 2 days, implementation 5 days (part-time). +- Communication follows [SA-001]: one pull request review by S01 per gateway; S02 and S03 are served by the published repository. +- PO language is English; no translated copies are kept. + +## Gateway Schedule + +| Gateway | Document | Window | Decision date | Owner | Stories | Main deliverable | Milestone | +| --- | --- | --- | --- | --- | --- | --- | --- | +| Gateway 1 - Project Setup | [MIL-001] | 2026-10-04 to 2026-10-06 | 2026-10-06 | S01 | none | Layout, pyproject, constants, Doxyfile, README | [Milestone-34] | +| Gateway 2 - Game Implementation | [MIL-002] | 2026-10-07 to 2026-10-11 | 2026-10-11 | S01 | none | Playable, tested, documented game | [Milestone-35] | + +```plantuml +@startgantt +Project starts 2026-10-04 +[Gateway 1 - Project Setup] starts 2026-10-04 and ends 2026-10-06 +[Gateway 1 Go/No-Go] happens 2026-10-06 +[Gateway 2 - Game Implementation] starts 2026-10-07 and ends 2026-10-11 +[Gateway 2 Go/No-Go] happens 2026-10-11 +@endgantt +``` + +## Scope Coverage + +| Business Case scope item | Gateway | +| --- | --- | +| Project scaffolding and README | [MIL-001] | +| Git host description and topics | [MIL-001] | +| Game logic, emoji cards, logo, restart | [MIL-002] | +| Unit tests | [MIL-002] (smoke test in [MIL-001]) | +| Doxygen documentation | [MIL-001] (Doxyfile), [MIL-002] (comments) | + +## Dependencies + +``` +Gateway 1 - Project Setup -> Gateway 2 - Game Implementation +``` + +A No-Go on Gateway 1 moves every Gateway 2 date by the same number of days. + +## Plan Risks + +| Risk | Impact | Mitigation | +| --- | --- | --- | +| Part-time availability | Dates slip | Dates are targets; a slip is recorded here, scope is not cut | +| Git host API token lacks permission to edit repository metadata | Task 1 of Gateway 1 blocked | Set description and topics by hand in the web UI | + +## Open Issues + +- No use cases or user stories are modelled: all tasks are plain technical tasks because the assignment is a small single-actor console program. Say if a use case (for example "Play a game of Blackjack") should be added first. +- The reviewer for every artifact is S01 (sole stakeholder); an independent reviewer would need a new stakeholder ID. +- No README template was supplied, so a standard layout is used. +- The Python `.gitignore` already exists in the repository and is verified in [MIL-001] task 2. + +--- + +[BC-001]: ./business-case.md +[SA-001]: ./stakeholder-analysis.md +[MIL-001]: ./milestones/mil-001-project-setup.md +[MIL-002]: ./milestones/mil-002-game-implementation.md +[Milestone-34]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/011-black-jack/milestone/34 +[Milestone-35]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/011-black-jack/milestone/35 diff --git a/docs/stakeholder-analysis.md b/docs/stakeholder-analysis.md new file mode 100644 index 0000000..5abe13a --- /dev/null +++ b/docs/stakeholder-analysis.md @@ -0,0 +1,79 @@ +# Stakeholder Analysis + +## Metadata +| Key | Value | +| --- | --- | +| ID | SA-001 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-04 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +--- + +## Purpose + +Identify who has an interest in the Blackjack project and what they need, using the power/interest grid. IDs are stable and are cited by all other artifacts. + +## Stakeholder Summary Table + +| ID | Name | Role/Title | Organization | Power Level | Interest Level | Quadrant | Primary Concern (Business Language) | +| --- | --- | --- | --- | --- | --- | --- | --- | +| S01 | Jens Tirsvad Nielsen | Course participant, Product Owner, developer, reviewer | Tirsvad | HIGH | HIGH | Manage Closely | Complete the course assignment with a correct game, built and tracked with the planning process | +| S02 | Udemy coursists | Fellow participants of the course who share code | Udemy course community | LOW | MEDIUM | Keep Informed | Readable, runnable code they can compare with their own solution | +| S03 | GitHub viewers | Visitors who browse the repository for ideas | Public | LOW | LOW | Monitor | A clear README and a clean structure that gives them ideas to reuse | + +## Power/Interest Classification Rationale + +- **Manage Closely (S01):** decides scope, accepts every milestone, writes and reviews the work. +- **Keep Informed (S02):** share and compare solutions; they do not decide anything but benefit from readable code and clear instructions. +- **Monitor (S03):** browse occasionally; no direct communication, they are served by the README and the repository description and topics. + +## Primary Concerns and FURPS+ Mapping + +| ID | Concern | FURPS+ attribute | +| --- | --- | --- | +| S01 | Game behaves per the assignment's house rules | Functionality | +| S01 | Easy to run on a clean machine | Usability / Implementation | +| S01 | Rules can be tested and reviewed | Supportability | +| S02 | Code is readable and follows the assignment's function names | Supportability | +| S02 | Can run the game and tests from the README | Usability | +| S03 | Finds the idea quickly: description, topics, README | Usability | +| S03 | No setup surprises: no runtime dependencies | Implementation | + +## Communication Requirements + +| ID | Channel | Frequency | Deliverable | Phase / Milestone | +| --- | --- | --- | --- | --- | +| S01 | Pull request review on the git host | Once per milestone | Reviewed milestone deliverable | MIL-001, MIL-002 | +| S02 | Repository, README, source comments | On publication | Runnable game with documented code | MIL-002 | +| S03 | Repository description, topics and README | On publication | Discoverable, understandable repository | MIL-001 | + +## Conflicting Interests and Mitigations + +| Conflict | Stakeholders | Mitigation | +| --- | --- | --- | +| Course hints suggest one flat script; the framework asks for testable, documented modules | S01, S02 | Keep the hint function names (`deal_card`, `calculate_score`, `compare`) but place them in importable modules | +| Coursists want a simple read-through; viewers want a polished project | S02, S03 | Keep modules small with Doxygen comments, and put the overview in the README | + +## Traceability Analysis + +### Business Goal Alignment + +| Stakeholder | Concern | Business Case objective | +| --- | --- | --- | +| S01 | Correct game | [BC-001] objective 1 | +| S01 | Reviewable, tracked steps | [BC-001] objective 6 | +| S02 | Readable, testable code | [BC-001] objectives 3 and 5 | +| S02, S03 | Run and test instructions | [BC-001] objective 4 | +| S03 | Discoverable repository | [BC-001] objective 4 | + +## Sign-Off + +Pending review by S01. + +--- + +[BC-001]: ./business-case.md diff --git a/framework b/framework new file mode 160000 index 0000000..14d221e --- /dev/null +++ b/framework @@ -0,0 +1 @@ +Subproject commit 14d221ec1cfd3966611a3eff6a607ef1964526c2 -- 2.54.0