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 |