Merge pull request '0.1.0' (#1) from 0.1.0 into main

Reviewed-on: #1

.github/ISSUE_TEMPLATE/01-define-value-stream-goals.md

@@ -0,0 +1,34 @@
+---
+name: "1. Define value stream goals"
+about: "First step for a new project — map the current process and set value stream goals."
+title: "Define value stream goals"
+labels: ["setup", "planning"]
+assignees: ""
+---
+
+## Task
+
+Produce the **current state** value stream map (and future state, if the target process is
+already known) for this project, using
+[`docs/value-stream-mapping/value_stream_map_template.odp`](../../docs/value-stream-mapping/value_stream_map_template.odp).
+
+## Steps
+
+- [ ] Identify the process boundaries: where does the value stream start and end?
+- [ ] Walk the current process step by step with the people who actually do the work
+- [ ] Fill in the current state map: process steps, cycle time, wait time, %C&A, inventory
+      between steps
+- [ ] Calculate total lead time and total cycle time
+- [ ] Identify bottlenecks, waste, and improvement opportunities
+- [ ] Draft the future state map reflecting the target process
+- [ ] Record improvement actions with an owner and a due date
+- [ ] Summarize headline metrics and actions on the
+      [Value Stream Mapping wiki page](../../wiki/Value-Stream-Mapping.md)
+- [ ] Share the map with stakeholders for feedback
+
+## Definition of done
+
+- [ ] Current (and, if applicable, future) state maps are complete in the `.odp` file
+- [ ] Metrics and action items are summarized on the wiki page
+- [ ] Stakeholders have reviewed the map
+- [ ] Findings feed into the [project specification issue](02-write-project-specification.md)

.github/ISSUE_TEMPLATE/02-write-project-specification.md

@@ -0,0 +1,38 @@
+---
+name: "2. Write project specification"
+about: "First step for a new project — complete and get approval on the project specification."
+title: "Write project specification"
+labels: ["setup", "planning"]
+assignees: ""
+---
+
+## Task
+
+Complete [`docs/PROJECT_SPECIFICATION.md`](../../docs/PROJECT_SPECIFICATION_TEMPLATE.md)
+(copied from the project specification template) for this project, and get it reviewed and
+approved by stakeholders.
+
+## Steps
+
+- [ ] Copy `docs/PROJECT_SPECIFICATION_TEMPLATE.md` to `docs/PROJECT_SPECIFICATION.md`
+- [ ] Write the summary and problem statement
+- [ ] List goals and — just as importantly — non-goals
+- [ ] Identify stakeholders and their roles
+- [ ] Define scope (in scope / out of scope)
+- [ ] Write functional and non-functional requirements
+- [ ] Sketch the architecture & design section (can stay high-level at this stage)
+- [ ] List constraints, assumptions, and risks
+- [ ] Draft milestones and a timeline
+- [ ] Define success metrics / acceptance criteria
+- [ ] Incorporate findings from the
+      [value stream mapping issue](01-define-value-stream-goals.md), if applicable
+- [ ] Circulate for review and log open questions in Section 15
+- [ ] Get sign-off from the stakeholders listed in Section 5 and set status to "Approved"
+
+## Definition of done
+
+- [ ] `docs/PROJECT_SPECIFICATION.md` exists and every section is filled in or deliberately
+      removed
+- [ ] Specification status is "Approved" and the revision history is up to date
+- [ ] Summary is copied onto the
+      [Project Specification wiki page](../../wiki/Project-Specification.md)

.github/ISSUE_TEMPLATE/03-set-up-project-wiki.md

@@ -0,0 +1,26 @@
+---
+name: "3. Set up project wiki"
+about: "First step for a new project — publish the wiki template pages."
+title: "Set up project wiki"
+labels: ["setup", "documentation"]
+assignees: ""
+---
+
+## Task
+
+Publish the pages from [`wiki/`](../../wiki/) to the repository's actual wiki (or your team's
+wiki tool), and fill each one in for this project.
+
+## Steps
+
+- [ ] Copy `wiki/Home.md`, `Getting-Started.md`, `Architecture.md`, `Project-Specification.md`,
+      `Value-Stream-Mapping.md`, and `FAQ.md` into the live wiki
+- [ ] Fill in Home with real links (repo, issue tracker, CI) and conventions
+- [ ] Fill in Getting Started with real install/run/test instructions
+- [ ] Link the approved project specification and value stream map from their wiki pages
+- [ ] Remove the "how to use this template" notes once pages are populated
+
+## Definition of done
+
+- [ ] Wiki is live and linked from the README
+- [ ] Getting Started page is accurate enough that a new contributor can follow it unaided

.github/ISSUE_TEMPLATE/04-complete-new-project-checklist.md

@@ -0,0 +1,29 @@
+---
+name: "4. Complete new project checklist"
+about: "First step for a new project — work through the full repo/project setup checklist."
+title: "Complete new project checklist"
+labels: ["setup"]
+assignees: ""
+---
+
+## Task
+
+Work through [`docs/NEW_PROJECT_CHECKLIST.md`](../../docs/NEW_PROJECT_CHECKLIST.md) end to
+end. This issue is the tracking wrapper for that checklist — paste its sections in below (or
+just check them off in the file itself and link to the commit).
+
+## Checklist
+
+- [ ] Repository setup complete
+- [ ] Value stream map complete (see [issue 1](01-define-value-stream-goals.md))
+- [ ] Project specification approved (see [issue 2](02-write-project-specification.md))
+- [ ] Planning complete: milestones set, setup issues created, board in place
+- [ ] Environment & tooling configured (Python version, linting, tests, CI)
+- [ ] Documentation complete: README, wiki (see [issue 3](03-set-up-project-wiki.md))
+- [ ] Kickoff held with stakeholders
+
+## Definition of done
+
+- [ ] Every item in `docs/NEW_PROJECT_CHECKLIST.md` is checked or explicitly marked N/A with
+      a reason
+- [ ] The project is ready for regular development work to begin

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

README.md

@@ -28,3 +28,19 @@ See the wiki for usage and examples.
 
 Visitors since repo creation.</br>
 ![Visitor Badge](https://visitor-badge.laobi.icu/badge?page_id=Lerking.python-repo-template)
+
+## Using this as a project template
+
+Beyond the bare Python repo scaffold (`main.py`, `LICENCE`, `.gitignore`), this template
+includes everything needed to kick off a new project properly:
+
+| What | Where |
+|---|---|
+| Project specification template | [`docs/PROJECT_SPECIFICATION_TEMPLATE.md`](docs/PROJECT_SPECIFICATION_TEMPLATE.md) |
+| Value stream mapping template (OpenDocument Presentation) | [`docs/value-stream-mapping/value_stream_map_template.odp`](docs/value-stream-mapping/value_stream_map_template.odp) |
+| New project setup checklist | [`docs/NEW_PROJECT_CHECKLIST.md`](docs/NEW_PROJECT_CHECKLIST.md) |
+| Wiki template (copy into your repo's actual wiki) | [`wiki/`](wiki/) |
+| Standard first-step issues (value stream goals, specification, wiki setup, checklist) | [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/) |
+
+Start with the checklist — it walks through repository setup, defining the project (value
+stream map + specification), planning, tooling, documentation, and kickoff, in order.

docs/NEW_PROJECT_CHECKLIST.md

@@ -0,0 +1,64 @@
+# New Project Checklist
+
+Work through this checklist when setting up a new project from this template. It's ordered
+roughly in the sequence you'd actually do the work, but feel free to skip items that don't
+apply and add project-specific ones at the bottom.
+
+## 1. Repository setup
+
+- [ ] Create the repository from this template
+- [ ] Rename the project (repo name, `main.py` header, README title)
+- [ ] Update `LICENCE` copyright holder and year
+- [ ] Review `.gitignore` for anything project-specific to add (env files, build artefacts, data dumps)
+- [ ] Set repository visibility (public/private) and default branch protections
+- [ ] Add collaborators / team access
+- [ ] Update README badges (or remove the ones that don't apply)
+- [ ] Enable the wiki and publish the [wiki template](../wiki/Home.md) pages
+
+## 2. Define the project
+
+- [ ] Create the [Value Stream Map](value-stream-mapping/value_stream_map_template.odp) —
+      current state at minimum, future state if the target process is already known
+- [ ] Open the **"Define value stream goals"** issue (from the issue templates) and fill it in
+- [ ] Open the **"Write project specification"** issue and complete the
+      [project specification template](PROJECT_SPECIFICATION_TEMPLATE.md)
+- [ ] Get the specification reviewed and approved by stakeholders
+- [ ] Identify and record non-goals explicitly — don't skip this
+
+## 3. Planning
+
+- [ ] Break the specification down into milestones
+- [ ] Create the standard setup issues (see `.github/ISSUE_TEMPLATE/`) in the issue tracker
+- [ ] Set up a project board / backlog and add the initial issues to it
+- [ ] Agree on a definition of "done" for issues and for the project as a whole
+- [ ] Identify risks and mitigations (Section 12 of the specification)
+
+## 4. Environment & tooling
+
+- [ ] Choose and pin the Python version (`.python-version` / `pyproject.toml`)
+- [ ] Set up the virtual environment / dependency manager
+- [ ] Add linting and formatting tools and their configuration
+- [ ] Add a test framework and a first smoke test
+- [ ] Set up CI (lint, test, build) on push/PR
+- [ ] Configure branch protection to require CI + review before merge
+
+## 5. Documentation
+
+- [ ] Fill in the README with an actual project description, setup, and usage instructions
+- [ ] Link the project specification and value stream map from the README
+- [ ] Set up the wiki structure (see `wiki/`) with at least a Home page and a
+      Getting Started page
+- [ ] Document how to run, test, and deploy the project
+
+## 6. Kickoff
+
+- [ ] Walk stakeholders through the approved specification and value stream map
+- [ ] Confirm milestones and timeline with everyone involved
+- [ ] Close out the setup issues once each is genuinely complete — don't just close them to
+      clear the board
+- [ ] Schedule the first review checkpoint (e.g. after MVP / first milestone)
+
+## Project-specific additions
+
+- [ ]
+- [ ]

docs/PROJECT_SPECIFICATION_TEMPLATE.md

@@ -0,0 +1,155 @@
+# Project Specification: <Project Name>
+
+> **How to use this template:** Copy this file to `docs/PROJECT_SPECIFICATION.md` in your new
+> project, then work through it top to bottom. Every `<placeholder>` should be replaced or
+> removed. Sections marked *(optional)* can be deleted if they genuinely don't apply — don't
+> delete them just because they're hard to answer. Keep this document updated as the project
+> evolves; it is the single source of truth for what the project is and why.
+
+| | |
+|---|---|
+| **Status** | Draft / In Review / Approved |
+| **Owner** | <name> |
+| **Created** | <yyyy-mm-dd> |
+| **Last updated** | <yyyy-mm-dd> |
+| **Version** | 0.1 |
+
+---
+
+## 1. Summary
+
+A short (3–5 sentence) description of the project, written so that someone outside the
+project can understand what it is and why it exists without reading further.
+
+## 2. Problem Statement
+
+- What problem are we solving?
+- Who has this problem, and how do they experience it today?
+- What happens if we do nothing?
+
+## 3. Goals
+
+Concrete, testable statements of what success looks like. Prefer measurable outcomes over
+vague aspirations.
+
+- [ ] Goal 1
+- [ ] Goal 2
+- [ ] Goal 3
+
+## 4. Non-Goals
+
+Explicitly out of scope. This section prevents scope creep and mismatched expectations —
+it is as important as the goals section.
+
+- Non-goal 1
+- Non-goal 2
+
+## 5. Stakeholders
+
+| Role | Name | Interest / Responsibility |
+|---|---|---|
+| Sponsor | | |
+| Product owner | | |
+| Tech lead | | |
+| End users | | |
+| Other | | |
+
+## 6. Background & Context *(optional)*
+
+Relevant history, prior attempts, related systems, or decisions that shape this project.
+Link to the [Value Stream Map](../docs/value-stream-mapping/) if one has been produced —
+it often surfaces the problem this project addresses.
+
+## 7. Scope
+
+### 7.1 In Scope
+- Item 1
+- Item 2
+
+### 7.2 Out of Scope
+- Item 1
+- Item 2
+
+## 8. Requirements
+
+### 8.1 Functional Requirements
+
+| ID | Requirement | Priority (Must/Should/Could/Won't) |
+|---|---|---|
+| FR-1 | | Must |
+| FR-2 | | Should |
+
+### 8.2 Non-Functional Requirements
+
+Consider at least: performance, scalability, security, privacy, accessibility,
+reliability/availability, maintainability, observability, compliance.
+
+| ID | Requirement | Notes |
+|---|---|---|
+| NFR-1 | | |
+| NFR-2 | | |
+
+## 9. Users & Use Cases *(optional)*
+
+Describe the primary user(s)/persona(s) and the key use cases or user stories.
+
+- As a `<user type>`, I want to `<action>`, so that `<benefit>`.
+
+## 10. Architecture & Design
+
+- High-level architecture (diagram, or link to one).
+- Key components and their responsibilities.
+- Technology choices and why they were made.
+- Data model / schema, if applicable.
+- External interfaces / APIs / integrations.
+
+## 11. Constraints & Assumptions
+
+| Type | Description |
+|---|---|
+| Constraint | e.g. must run on existing infrastructure, fixed deadline, budget cap |
+| Assumption | e.g. third-party API will remain stable, expected data volume |
+
+## 12. Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| | Low/Med/High | Low/Med/High | |
+
+## 13. Milestones & Timeline
+
+| Milestone | Target date | Notes |
+|---|---|---|
+| Project kickoff | | |
+| Specification approved | | |
+| MVP / first working version | | |
+| Release | | |
+
+## 14. Success Metrics / Acceptance Criteria
+
+How will we know the project succeeded? Prefer measurable, falsifiable criteria over
+"it works."
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## 15. Open Questions
+
+Track unresolved questions here so they don't get lost. Move resolved items to a decision
+log or into the relevant section above.
+
+| Question | Owner | Status |
+|---|---|---|
+| | | Open |
+
+## 16. Glossary *(optional)*
+
+| Term | Definition |
+|---|---|
+| | |
+
+## 17. Revision History
+
+| Version | Date | Author | Summary of changes |
+|---|---|---|---|
+| 0.1 | <yyyy-mm-dd> | | Initial draft |

wiki/Architecture.md

@@ -0,0 +1,35 @@
+# Architecture
+
+> Keep this page in sync with the "Architecture & Design" section of the project
+> specification. The specification captures the *decision*; this page captures the
+> *current, evolving state* of the system for people working in the codebase day to day.
+
+## Overview
+
+One paragraph: what the major pieces are and how they fit together. Include or link a
+diagram.
+
+## Components
+
+| Component | Responsibility | Depends on |
+|---|---|---|
+| | | |
+
+## Data flow
+
+Describe how data moves through the system, from input to output.
+
+## External dependencies
+
+| Dependency | Purpose | Notes |
+|---|---|---|
+| | | |
+
+## Key design decisions
+
+A short log of significant decisions and the reasoning behind them (an ADR-style list is
+fine here if you don't have a separate `docs/adr/` folder).
+
+| Decision | Date | Reasoning |
+|---|---|---|
+| | | |

wiki/FAQ.md

@@ -0,0 +1,10 @@
+# FAQ
+
+> A running list of questions that came up more than once. If you find yourself answering
+> the same question in an issue or chat, add it here.
+
+**Q: `<question>`**
+A: `<answer>`
+
+**Q: `<question>`**
+A: `<answer>`

wiki/Getting-Started.md

@@ -0,0 +1,37 @@
+# Getting Started
+
+## Prerequisites
+
+- Python `<version>`
+- `<other tools: e.g. Docker, make, poetry>`
+
+## Installation
+
+```bash
+git clone <repo-url>
+cd <project>
+<install command, e.g. pip install -r requirements.txt>
+```
+
+## Configuration
+
+- Environment variables / config file(s) needed, and where to get their values
+- Any secrets or credentials required, and how to obtain them safely (never commit them)
+
+## Running the project
+
+```bash
+<run command>
+```
+
+## Running the tests
+
+```bash
+<test command>
+```
+
+## Common issues
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| | | |

wiki/Home.md

@@ -0,0 +1,33 @@
+# <Project Name> Wiki
+
+> Copy the pages in this `wiki/` folder into your repository's actual GitHub Wiki (or your
+> wiki tool of choice), then fill them in. File names map to page titles, so keep them as-is
+> unless you're renaming the page. Delete this note once the wiki is populated.
+
+Welcome. This wiki is the living documentation for the project — the specification and value
+stream map describe what we set out to build and why; this wiki describes how the project
+actually works and how to use it, day to day.
+
+## Pages
+
+- **[[Getting Started]]** — install, configure, and run the project locally
+- **[[Architecture]]** — how the system is put together and why
+- **[[Project Specification]]** — link/summary of the approved specification
+- **[[Value Stream Mapping]]** — link/summary of the current & future state maps
+- **[[FAQ]]** — common questions and troubleshooting
+
+## Quick links
+
+| | |
+|---|---|
+| Repository | `<link>` |
+| Issue tracker | `<link>` |
+| Project specification | [docs/PROJECT_SPECIFICATION.md](../docs/PROJECT_SPECIFICATION_TEMPLATE.md) |
+| Value stream map | [docs/value-stream-mapping/](../docs/value-stream-mapping/) |
+| CI / build status | `<link>` |
+
+## Conventions
+
+- Branching model: `<e.g. trunk-based, git-flow>`
+- Commit message style: `<e.g. Conventional Commits>`
+- Where decisions get recorded: `<e.g. ADRs in docs/adr/, this wiki, issue comments>`

wiki/Project-Specification.md

@@ -0,0 +1,28 @@
+# Project Specification
+
+The authoritative project specification lives in
+[`docs/PROJECT_SPECIFICATION.md`](../docs/PROJECT_SPECIFICATION_TEMPLATE.md) (based on the
+[project specification template](../docs/PROJECT_SPECIFICATION_TEMPLATE.md)), not on this
+wiki page — it needs version control and review history that the wiki doesn't give you.
+
+This page exists so the specification is easy to find. Keep it updated with:
+
+- **Current version:** `<version>`
+- **Status:** Draft / In Review / Approved
+- **Last approved:** `<date>`
+
+## Summary
+
+Paste the 3–5 sentence summary from Section 1 of the specification here, so readers get the
+gist without leaving the wiki.
+
+## Key goals
+
+- Goal 1
+- Goal 2
+- Goal 3
+
+## Notable non-goals
+
+- Non-goal 1
+- Non-goal 2

wiki/Value-Stream-Mapping.md

@@ -0,0 +1,37 @@
+# Value Stream Mapping
+
+The current and future state value stream maps live in
+[`docs/value-stream-mapping/`](../docs/value-stream-mapping/) as an OpenDocument
+Presentation (`.odp`), editable in LibreOffice Impress, OpenOffice Impress, or (with
+conversion) PowerPoint/Google Slides.
+
+## Current state summary
+
+Briefly describe the current process, its main bottlenecks, and the headline metrics
+(total lead time, total cycle time, %C&A) once the current state map is complete.
+
+| Metric | Value |
+|---|---|
+| Total lead time | |
+| Total cycle time (value-added time) | |
+| Process cycle efficiency | |
+
+## Future state summary
+
+Briefly describe the target process and what changes once the future state map is
+complete.
+
+| Metric | Value |
+|---|---|
+| Target lead time | |
+| Target cycle time | |
+| Target process cycle efficiency | |
+
+## Improvement actions
+
+Pulled from the action plan slide in the map — kept here for visibility, updated from the
+`.odp` file when it changes.
+
+| Action | Owner | Due | Status |
+|---|---|---|---|
+| | | | |