nullhack · nullhack · Apr 20, 2026 · Apr 20, 2026
diff --git a/.opencode/agents/designer.md b/.opencode/agents/designer.md
@@ -0,0 +1,48 @@
+---
+description: Designer responsible for visual identity — SVG assets, color systems, and WCAG-compliant branding
+mode: subagent
+temperature: 0.4
+tools:
+  write: true
+  edit: true
+  bash: false
+  read: true
+  grep: true
+  glob: true
+  task: true
+  skill: true
+---
+
+# Designer
+
+You create and maintain the visual identity of the project. Your outputs are SVG assets (`docs/assets/`) and the branding reference (`docs/branding.md`). You do not write application code or move `.feature` files.
+
+## Responsibilities
+
+- Create and update `docs/assets/logo.svg` and `docs/assets/banner.svg`
+- Write and maintain `docs/branding.md` — the single source of truth for project identity
+- Ensure all color choices meet WCAG 2.1 AA (4.5:1 contrast ratio for text on background)
+- Apply `docs/branding.md` colors and identity when generating any visual artifact
+
+## Session Start
+
+Load `skill run-session`. Read `docs/branding.md` before any visual work.
+
+## When Called
+
+You are invoked when the stakeholder requests:
+- A new or updated logo or banner
+- Color palette selection or update
+- Branding document initialization or revision
+
+Use `skill design-colors` for color selection, palette generation, and WCAG validation.
+Use `skill design-assets` for SVG asset creation and updates.
+
+## Ownership
+
+`docs/branding.md` and `docs/assets/` are owned exclusively by the designer. Other agents read these files but never write to them.
+
+Commit message format:
+- New asset: `design(assets): create <asset-name>`
+- Updated asset: `design(assets): update <asset-name>`
+- Branding update: `design(branding): <what changed>`
diff --git a/.opencode/agents/product-owner.md b/.opencode/agents/product-owner.md
@@ -19,13 +19,13 @@ You interview the human stakeholder to discover what to build, write Gherkin spe
 
 ## Session Start
 
-Load `skill session-workflow` first — it reads TODO.md, orients you to the current step and feature, and tells you what to do next.
+Load `skill run-session` first — it reads TODO.md, orients you to the current step and feature, and tells you what to do next.
 
 ## Step Routing
 
 | Step | Action |
 |---|---|
-| **Step 1 — SCOPE** | Load `skill scope` — contains Stage 1 (Discovery sessions) and Stage 2 (Stories + Criteria). At the end of Stage 2 Step B (criteria), write the `## Self-Declaration` block into `TODO.md` before committing — every DISAGREE is a hard blocker. |
+| **Step 1 — SCOPE** | Load `skill define-scope` — contains Stage 1 (Discovery sessions) and Stage 2 (Stories + Criteria). At the end of Stage 2 Step B (criteria), write the `## Self-Declaration` block into `TODO.md` before committing — every DISAGREE is a hard blocker. |
 | **Step 5 — ACCEPT** | See acceptance protocol below |
 
 ## Ownership Rules
@@ -66,6 +66,6 @@ When a defect is reported against any feature:
 
 ## Available Skills
 
-- `session-workflow` — session start/end protocol
-- `feature-selection` — when TODO.md is idle: score and select next backlog feature using WSJF
-- `scope` — Step 1: Stage 1 (Discovery sessions with stakeholder) and Stage 2 (Stories + Criteria, PO alone)
+- `run-session` — session start/end protocol
+- `select-feature` — when TODO.md is idle: score and select next backlog feature using WSJF
+- `define-scope` — Step 1: Stage 1 (Discovery sessions with stakeholder) and Stage 2 (Stories + Criteria, PO alone)
diff --git a/.opencode/agents/reviewer.md b/.opencode/agents/reviewer.md
@@ -31,7 +31,7 @@ You verify that work is done correctly by running commands and reading code. You
 
 ## Session Start
 
-Load `skill session-workflow` first. Then load `skill verify` for Step 4 verification.
+Load `skill run-session` first. Then load `skill verify` for Step 4 verification.
 
 ## Zero-Tolerance Rules
 

diff --git a/.opencode/agents/setup-project.md b/.opencode/agents/setup-project.md
@@ -121,12 +121,39 @@ uv sync --all-extras && uv run task test-fast
 
 Both must succeed. If `uv run task test-fast` fails and the failure is caused by a variable substitution that was missed (e.g. an import still referencing `app` instead of `<package_name>`), apply the same substitution pattern to fix it. If the failure has any other cause, report the error and stop — do not attempt to fix it.
 
-## Step 5 — Done
+## Step 5 — Branding
+
+Ask the following questions one at a time. All are optional — the user can skip any by pressing Enter. Only write fields the user answered.
+
+1. **Tagline** — one sentence describing the project for banners and README headers
+2. **Mission** — one sentence: what problem does this project solve?
+3. **Vision** — one sentence: what does success look like long-term?
+4. **Tone of voice** — how should docs and release notes sound? (e.g. "direct and technical", "friendly and approachable")
+5. **Primary color** — hex code for the main brand color; or describe a theme (e.g. "ocean", "forest") and colors will be suggested
+6. **Accent color** — hex code for highlights and links; suggested automatically if a theme was given
+7. **Release naming** — default is `adjective-animal`; provide a theme word to constrain it (e.g. "space", "mythology"), or leave blank for no constraint
+8. **Words to avoid** — comma-separated list (e.g. "easy, simple, just")
+9. **Words to prefer** — comma-separated list (e.g. "minimal, precise")
+
+**Color suggestion rule**: if the user provides a theme word but no hex codes, suggest a primary + accent palette:
+- Choose hue based on theme semantics (blue=trust/tech, green=growth/nature, orange=creativity/energy, purple=innovation/premium)
+- Use a complementary scheme: primary = muted/deep tone of chosen hue; accent = complementary pure hue
+- Verify WCAG 2.1 AA: white text on primary must achieve ≥ 4.5:1 contrast ratio using `(L1+0.05)/(L2+0.05)`
+- Show the user: hex codes + contrast ratio + one-line rationale before writing
+
+Write `docs/branding.md` with only the fields the user provided. Do not write placeholder text for skipped fields. Then commit:
+
+```bash
+git add docs/branding.md
+git commit -m "chore(branding): initialize branding.md"
+```
+
+## Step 6 — Done
 
 Tell the user which files were changed (list them). Then show next steps:
 
 ```bash
-# Commit the setup
+# Commit the setup (if not already committed per-step)
 git add -A && git commit -m "chore: initialize project from python-project-template"
 git push -u origin main
 

diff --git a/.opencode/agents/software-engineer.md b/.opencode/agents/software-engineer.md
@@ -31,15 +31,15 @@ You build everything: architecture, tests, code, and releases. You own technical
 
 ## Session Start
 
-Load `skill session-workflow` first — it reads TODO.md, orients you to the current step and feature, and tells you what to do next.
+Load `skill run-session` first — it reads TODO.md, orients you to the current step and feature, and tells you what to do next.
 
 ## Step Routing
 
 | Step | Action |
 |---|---|
-| **Step 2 — ARCH** | Load `skill implementation` — contains Step 2 architecture protocol |
-| **Step 3 — TDD LOOP** | Load `skill implementation` — contains Step 3 TDD Loop; load `skill refactor` when entering REFACTOR phase or doing preparatory refactoring |
-| **Step 5 — after PO accepts** | Load `skill pr-management` and `skill git-release` as needed |
+| **Step 2 — ARCH** | Load `skill implement` — contains Step 2 architecture protocol |
+| **Step 3 — TDD LOOP** | Load `skill implement` — contains Step 3 TDD Loop; load `skill refactor` when entering REFACTOR phase or doing preparatory refactoring |
+| **Step 5 — after PO accepts** | Load `skill create-pr` and `skill git-release` as needed |
 
 ## Ownership Rules
 
@@ -51,7 +51,7 @@ Load `skill session-workflow` first — it reads TODO.md, orients you to the cur
 
 If `docs/features/in-progress/` contains only `.gitkeep` (no `.feature` file):
 1. Do not pick a feature from backlog yourself.
-2. Update TODO.md: `Next: Run @product-owner — load skill feature-selection and pick the next BASELINED feature from backlog.`
+2. Update TODO.md: `Next: Run @product-owner — load skill select-feature and pick the next BASELINED feature from backlog.`
 3. Stop. The PO must move the chosen feature into `in-progress/` before you can begin Step 2.
 
 ## Spec Gaps
@@ -62,10 +62,10 @@ If during implementation you discover behavior not covered by existing acceptanc
 
 ## Available Skills
 
-- `session-workflow` — session start/end protocol
-- `implementation` — Steps 2-3: architecture + TDD loop
+- `run-session` — session start/end protocol
+- `implement` — Steps 2-3: architecture + TDD loop
 - `refactor` — REFACTOR phase and preparatory refactoring (load on-demand)
-- `design-patterns` — on-demand when smell detected during architecture or refactor
-- `pr-management` — Step 5: PRs with conventional commits
+- `apply-patterns` — on-demand when smell detected during architecture or refactor
+- `create-pr` — Step 5: PRs with conventional commits
 - `git-release` — Step 5: calver versioning and themed release naming
 - `create-skill` — meta: create new skills when needed
diff --git a/.opencode/skills/design-patterns/SKILL.md → .opencode/skills/apply-patterns/SKILL.md b/.opencode/skills/design-patterns/SKILL.md → .opencode/skills/apply-patterns/SKILL.md
@@ -1,7 +1,7 @@
 ---
-name: design-patterns
+name: apply-patterns
 description: GoF design pattern catalogue — smell triggers and Python before/after examples
-version: "2.0"
+version: "2.1"
 author: software-engineer
 audience: software-engineer
 workflow: feature-lifecycle
@@ -15,7 +15,11 @@ Sources: Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of Reusable
 
 ---
 
-## How to Use This Skill
+## When to Use
+
+Load this skill when the `refactor` skill's smell table points to a GoF pattern, or when the `implement` skill's Silent Pre-mortem detects a pattern smell in architecture stubs.
+
+## Step-by-Step
 
 1. **Identify the smell** from the refactor skill's lookup table
 2. **Find the smell category** below (Creational / Structural / Behavioral)

diff --git a/.opencode/skills/check-quality/SKILL.md b/.opencode/skills/check-quality/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: check-quality
+description: Enforce code quality using ruff, pytest coverage, and static type checking
+version: "2.1"
+author: software-engineer
+audience: software-engineer, reviewer
+workflow: feature-lifecycle
+---
+
+# Check Quality
+
+Quick reference for the software-engineer quality gate before handing off to the reviewer (Step 4).
+
+**For the full verification protocol used by the reviewer, load `skill verify`.**
+
+## When to Use
+
+Load this skill when completing Step 3 and preparing to hand off to the reviewer. Run all four commands; all must pass before signalling handoff.
+
+## Step-by-Step
+
+```bash
+uv run task lint                # ruff check + ruff format — must exit 0
+uv run task static-check        # pyright — must exit 0, 0 errors
+uv run task test                # pytest with coverage — must exit 0, 100% coverage
+timeout 10s uv run task run     # app starts — must exit non-124
+```
+
+All four must pass. Do not hand off broken work.
+
+## Checklist
+
+- [ ] `lint` exits 0 (ruff check + ruff format)
+- [ ] `static-check` exits 0, 0 pyright errors
+- [ ] `test` exits 0, 100% coverage
+- [ ] `run` exits non-124 (not hung)
+- [ ] No `noqa` or `type: ignore` — fix the underlying issue
diff --git a/.opencode/skills/code-quality/SKILL.md b/.opencode/skills/code-quality/SKILL.md
diff --git a/.opencode/skills/create-agent/SKILL.md b/.opencode/skills/create-agent/SKILL.md
@@ -65,7 +65,7 @@ steps: <step numbers this agent owns, e.g., "2, 3">
 
 | Skill | When to Load | Purpose |
 |---|---|---|
-| `session-workflow` | Every session | Session start/end protocol |
+| `run-session` | Every session | Session start/end protocol |
 | `<skill-name>` | When needed | <What the skill provides> |
 
 ## Instructions
@@ -152,7 +152,7 @@ steps: <owned steps, e.g., "2-3">
 
 ## Available Skills
 
-- `session-workflow` — always
+- `run-session` — always
 - `<skill>` — when <trigger>
 
 ## Instructions

diff --git a/.opencode/skills/pr-management/SKILL.md → .opencode/skills/create-pr/SKILL.md b/.opencode/skills/pr-management/SKILL.md → .opencode/skills/create-pr/SKILL.md
@@ -1,17 +1,21 @@
 ---
-name: pr-management
+name: create-pr
 description: Create pull requests with conventional commits, proper formatting, and branch workflow
 version: "1.0"
 author: software-engineer
 audience: software-engineer
 workflow: git-management
 ---
 
-# PR Management
+# Create PR
+
+## When to Use
+
+Load this skill after the reviewer approves the feature (Step 4 APPROVED) and the PO has accepted it (Step 5). Use it to create and merge the feature pull request.
 
-Create and manage pull requests after the reviewer approves the feature (Step 5).
+## Step-by-Step
 
-## Branch Naming
+### Branch Naming
 
 ```
 feature/<feature-stem>    # new feature

diff --git a/.opencode/skills/create-skill/SKILL.md b/.opencode/skills/create-skill/SKILL.md
@@ -132,15 +132,17 @@ Add the skill name to the agent's "Available Skills" section so the agent knows
 
 | Skill | Used By | Purpose |
 |---|---|---|
-| `session-workflow` | all agents | Session start/end protocol |
-| `feature-selection` | product-owner | Score and select next backlog feature (WSJF) |
-| `scope` | product-owner | Step 1: define acceptance criteria |
-| `implementation` | software-engineer | Steps 2-3: architecture + TDD loop |
-| `design-patterns` | software-engineer | Steps 2, 3: refactor when smell detected |
+| `run-session` | all agents | Session start/end protocol |
+| `select-feature` | product-owner | Score and select next backlog feature (WSJF) |
+| `define-scope` | product-owner | Step 1: define acceptance criteria |
+| `implement` | software-engineer | Steps 2-3: architecture + TDD loop |
+| `apply-patterns` | software-engineer | Steps 2, 3: refactor when smell detected |
 | `verify` | reviewer | Step 4: adversarial verification |
-| `code-quality` | software-engineer | Quick reference — redirects to verify |
-| `pr-management` | software-engineer | Step 5: create PR with squash merge |
+| `check-quality` | software-engineer | Quick reference — redirects to verify |
+| `create-pr` | software-engineer | Step 5: create PR with squash merge |
 | `git-release` | software-engineer | Step 5: calver versioning and release |
-| `living-docs` | product-owner | Step 5 (after acceptance) + on stakeholder demand: C4 diagrams + glossary |
+| `update-docs` | product-owner | Step 5 (after acceptance) + on stakeholder demand: C4 diagrams + glossary |
+| `design-colors` | designer | Color palette selection and WCAG validation |
+| `design-assets` | designer | SVG visual asset creation and updates |
 | `create-skill` | software-engineer | Create new skills |
 | `create-agent` | human-user | Create new agents with research-backed design |
diff --git a/.opencode/skills/scope/SKILL.md → .opencode/skills/define-scope/SKILL.md b/.opencode/skills/scope/SKILL.md → .opencode/skills/define-scope/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: scope
+name: define-scope
 description: Step 1 — discover requirements through stakeholder interviews and write Gherkin acceptance criteria
 version: "5.0"
 author: product-owner
@@ -471,5 +471,5 @@ Relative paths in this skill (e.g., scripts/, reference/) are relative to this b
 Note: file list is sampled.
 
 <skill_files>
-<file>/home/user/Documents/projects/python-project-template/.opencode/skills/scope/discovery-template.md</file>
+<file>/home/user/Documents/projects/python-project-template/.opencode/skills/define-scope/discovery-template.md</file>
 </skill_files>
diff --git a/.opencode/skills/scope/discovery-template.md → ...skills/define-scope/discovery-template.md b/.opencode/skills/scope/discovery-template.md → ...skills/define-scope/discovery-template.md