From f74ec683fcb27240706ca9017a3d3c8dc308c7b3 Mon Sep 17 00:00:00 2001 From: nullhack Date: Mon, 20 Apr 2026 07:53:28 -0400 Subject: [PATCH] feat(branding): add designer agent, branding system, and rename skills to verb-noun convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move docs/images/ → docs/assets/ (logo.svg, banner.svg) - Add docs/branding.md with python-project-template example branding (Greek antiquity theme) - Add .opencode/agents/designer.md (owns docs/branding.md + docs/assets/) - Add .opencode/skills/design-colors/SKILL.md (color palette + WCAG 2.1 AA validation) - Add .opencode/skills/design-assets/SKILL.md (SVG asset creation guidance) - Update session-workflow → run-session: add Output Style section + Rule #8 (minimalist output) - Update git-release: Step 0 reads branding, optional release naming, fix stale {Adjective Animal} - Update living-docs → update-docs: Step 1 reads branding colors for Mermaid C4 theming - Update setup-project: add Step 6 Branding (questions + WCAG color suggestion + BRANDING.md) - Rename 8 skills to verb-noun: run-session, select-feature, define-scope, implement, apply-patterns, check-quality, create-pr, update-docs - Update all references in AGENTS.md, agent files, and skill files for new names - Fix skill content: add When to Use, Step-by-Step headings where missing --- .opencode/agents/designer.md | 48 +++++++++++ .opencode/agents/product-owner.md | 10 +-- .opencode/agents/reviewer.md | 2 +- .opencode/agents/setup-project.md | 31 ++++++- .opencode/agents/software-engineer.md | 18 ++--- .../SKILL.md | 10 ++- .opencode/skills/check-quality/SKILL.md | 37 +++++++++ .opencode/skills/code-quality/SKILL.md | 29 ------- .opencode/skills/create-agent/SKILL.md | 4 +- .../{pr-management => create-pr}/SKILL.md | 12 ++- .opencode/skills/create-skill/SKILL.md | 18 +++-- .../skills/{scope => define-scope}/SKILL.md | 4 +- .../discovery-template.md | 0 .opencode/skills/design-assets/SKILL.md | 79 ++++++++++++++++++ .opencode/skills/design-colors/SKILL.md | 80 +++++++++++++++++++ .opencode/skills/git-release/SKILL.md | 42 ++++++---- .../{implementation => implement}/SKILL.md | 16 ++-- .opencode/skills/refactor/SKILL.md | 6 +- .../SKILL.md | 24 ++++-- .../SKILL.md | 10 +-- .../{living-docs => update-docs}/SKILL.md | 19 ++--- .opencode/skills/verify/SKILL.md | 8 +- AGENTS.md | 39 +++++---- README.md | 2 +- docs/{images => assets}/banner.svg | 0 docs/{images => assets}/logo.svg | 0 docs/branding.md | 43 ++++++++++ 27 files changed, 461 insertions(+), 130 deletions(-) create mode 100644 .opencode/agents/designer.md rename .opencode/skills/{design-patterns => apply-patterns}/SKILL.md (98%) create mode 100644 .opencode/skills/check-quality/SKILL.md delete mode 100644 .opencode/skills/code-quality/SKILL.md rename .opencode/skills/{pr-management => create-pr}/SKILL.md (89%) rename .opencode/skills/{scope => define-scope}/SKILL.md (99%) rename .opencode/skills/{scope => define-scope}/discovery-template.md (100%) create mode 100644 .opencode/skills/design-assets/SKILL.md create mode 100644 .opencode/skills/design-colors/SKILL.md rename .opencode/skills/{implementation => implement}/SKILL.md (97%) rename .opencode/skills/{session-workflow => run-session}/SKILL.md (77%) rename .opencode/skills/{feature-selection => select-feature}/SKILL.md (93%) rename .opencode/skills/{living-docs => update-docs}/SKILL.md (91%) rename docs/{images => assets}/banner.svg (100%) rename docs/{images => assets}/logo.svg (100%) create mode 100644 docs/branding.md diff --git a/.opencode/agents/designer.md b/.opencode/agents/designer.md new file mode 100644 index 0000000..1e21b41 --- /dev/null +++ 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 ` +- Updated asset: `design(assets): update ` +- Branding update: `design(branding): ` diff --git a/.opencode/agents/product-owner.md b/.opencode/agents/product-owner.md index 403da3c..b9d3460 100644 --- 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 index 0f0b350..e38cdec 100644 --- 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 index a4a1d8f..ef3dc1a 100644 --- 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 ``), 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 index 10bdc5e..e6615dc 100644 --- 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 b/.opencode/skills/apply-patterns/SKILL.md similarity index 98% rename from .opencode/skills/design-patterns/SKILL.md rename to .opencode/skills/apply-patterns/SKILL.md index 7d1b4de..def03de 100644 --- a/.opencode/skills/design-patterns/SKILL.md +++ b/.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 new file mode 100644 index 0000000..673f202 --- /dev/null +++ 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 deleted file mode 100644 index 40f0294..0000000 --- a/.opencode/skills/code-quality/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: code-quality -description: Enforce code quality using ruff, pytest coverage, and static type checking -version: "2.0" -author: software-engineer -audience: software-engineer, reviewer -workflow: feature-lifecycle ---- - -# Code Quality - -Run these four commands before handing off to the reviewer (Step 4). All must pass. - -**This is a quick reference. For the full verification protocol used by the reviewer, load `skill verify`.** - -## Software-Engineer Self-Check - -Before handing off to reviewer: - -```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. - -**Golden rule: never use `noqa` or `type: ignore`.** Fix the underlying issue instead. diff --git a/.opencode/skills/create-agent/SKILL.md b/.opencode/skills/create-agent/SKILL.md index a482246..b1cc5e9 100644 --- a/.opencode/skills/create-agent/SKILL.md +++ b/.opencode/skills/create-agent/SKILL.md @@ -65,7 +65,7 @@ steps: | Skill | When to Load | Purpose | |---|---|---| -| `session-workflow` | Every session | Session start/end protocol | +| `run-session` | Every session | Session start/end protocol | | `` | When needed | | ## Instructions @@ -152,7 +152,7 @@ steps: ## Available Skills -- `session-workflow` — always +- `run-session` — always - `` — when ## Instructions diff --git a/.opencode/skills/pr-management/SKILL.md b/.opencode/skills/create-pr/SKILL.md similarity index 89% rename from .opencode/skills/pr-management/SKILL.md rename to .opencode/skills/create-pr/SKILL.md index 94af430..d4cb3e5 100644 --- a/.opencode/skills/pr-management/SKILL.md +++ b/.opencode/skills/create-pr/SKILL.md @@ -1,5 +1,5 @@ --- -name: pr-management +name: create-pr description: Create pull requests with conventional commits, proper formatting, and branch workflow version: "1.0" author: software-engineer @@ -7,11 +7,15 @@ 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/ # new feature diff --git a/.opencode/skills/create-skill/SKILL.md b/.opencode/skills/create-skill/SKILL.md index 39504b7..7774de3 100644 --- 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 | \ No newline at end of file diff --git a/.opencode/skills/scope/SKILL.md b/.opencode/skills/define-scope/SKILL.md similarity index 99% rename from .opencode/skills/scope/SKILL.md rename to .opencode/skills/define-scope/SKILL.md index cd02bd5..b8803a6 100644 --- a/.opencode/skills/scope/SKILL.md +++ b/.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. -/home/user/Documents/projects/python-project-template/.opencode/skills/scope/discovery-template.md +/home/user/Documents/projects/python-project-template/.opencode/skills/define-scope/discovery-template.md diff --git a/.opencode/skills/scope/discovery-template.md b/.opencode/skills/define-scope/discovery-template.md similarity index 100% rename from .opencode/skills/scope/discovery-template.md rename to .opencode/skills/define-scope/discovery-template.md diff --git a/.opencode/skills/design-assets/SKILL.md b/.opencode/skills/design-assets/SKILL.md new file mode 100644 index 0000000..108c245 --- /dev/null +++ b/.opencode/skills/design-assets/SKILL.md @@ -0,0 +1,79 @@ +--- +name: design-assets +description: Author and update SVG visual assets using project branding identity +version: "1.0" +author: designer +audience: designer +workflow: branding +--- + +# Design Assets + +Create or update `docs/assets/logo.svg` and `docs/assets/banner.svg` from the project's branding identity in `docs/branding.md`. + +## When to Use + +- Stakeholder requests a new or updated logo or banner +- `docs/assets/` is empty after project setup + +## Step-by-Step + +### 1. Read branding + +Read `docs/branding.md`. Extract: project name, tagline, primary/accent colors, tone of voice. If colors are absent, run `skill design-colors` first. + +### 2. Apply SVG structure rules + +All SVGs must follow these constraints (W3C SVG 2 spec — CSS properties take precedence over presentation attributes; inline ` + + + +``` + +### 6. Commit + +```bash +git add docs/assets/ +git commit -m "design(assets): " +``` + +## Checklist + +- [ ] `docs/branding.md` read before writing any SVG +- [ ] Colors sourced from `docs/branding.md`; `skill design-colors` run if absent +- [ ] `viewBox` set; no fixed `width`/`height` on `` root +- [ ] Colors use CSS custom properties with fallback hex +- [ ] System font stack; no external imports +- [ ] `role="img"` and `aria-label` present +- [ ] Banner readable at 400px wide; logo readable at 32px +- [ ] Files committed to `docs/assets/` diff --git a/.opencode/skills/design-colors/SKILL.md b/.opencode/skills/design-colors/SKILL.md new file mode 100644 index 0000000..f7ca8df --- /dev/null +++ b/.opencode/skills/design-colors/SKILL.md @@ -0,0 +1,80 @@ +--- +name: design-colors +description: Select and validate a project color palette with WCAG contrast compliance +version: "1.0" +author: designer +audience: designer +workflow: branding +--- + +# Design Colors + +Select a color palette for the project and validate it for accessibility. Write the result to `docs/branding.md`. + +## When to Use + +- Stakeholder provides a theme word or asks for a color palette +- `docs/branding.md` exists but has no colors yet +- Stakeholder requests a color change + +## Step-by-Step + +### 1. Read branding context + +Read `docs/branding.md`. If colors are already set and the stakeholder has not asked to change them, stop — do not overwrite. + +### 2. Select primary hue + +Map the project theme or mission to a hue. Hue carries meaning before any other element is read (Itten 1961 — hue semantics precede form perception): + +| Theme / Mission | Hue | Semantic | +|---|---|---| +| Technology, trust, precision | Blue | Calm, reliable | +| Growth, nature, sustainability | Green | Life, progress | +| Creativity, energy, community | Orange | Warmth, action | +| Innovation, premium, research | Purple | Depth, curiosity | +| Urgency, passion, power | Red | Use sparingly | +| Clarity, neutrality | Grey | Professional, recedes | + +### 3. Build the palette + +Use a complementary scheme by default — a muted primary plus a pure complementary accent. This produces the most reliably professional result without requiring design expertise (Albers 1963 — simultaneous contrast; complementary pairs read as distinct without competing): + +- **Primary** — muted/deep tone of chosen hue (lower saturation, lower value). Used for surfaces, backgrounds, headers. +- **Accent** — complementary hue (180° on color wheel), pure/saturated. Used for links, highlights, diagram lines only. + +Example for green: Primary `#2D6A4F` (deep forest), Accent `#D4A017` (golden amber). + +Use analogous, split-complementary, or triadic only when the stakeholder explicitly requests it. + +### 4. Validate WCAG 2.1 AA + +Any color used as a text background must achieve ≥ 4.5:1 contrast with white `#FFFFFF` (WCAG 2.1 SC 1.4.3 — derived from ISO 9241-3 baseline × 1.5 acuity loss factor): + +``` +sRGB → linear: c ≤ 0.04045 ? c/12.92 : ((c+0.055)/1.055)^2.4 +L = 0.2126·R + 0.7152·G + 0.0722·B +Contrast = (L_lighter + 0.05) / (L_darker + 0.05) +``` + +If contrast < 4.5:1, darken the primary until compliant. Accent colors on non-text surfaces are exempt. + +### 5. Write to branding + +Update `docs/branding.md` under `## Visual`: + +```markdown +- **Primary color:** `#XXXXXX` — () +- **Accent color:** `#XXXXXX` — () + +> Colors meet WCAG 2.1 AA (X.X:1 contrast) when white text is placed on the primary. +``` + +## Checklist + +- [ ] Existing colors checked before proceeding +- [ ] Hue chosen from theme/mission semantics +- [ ] Primary is muted/deep (not pure saturated) +- [ ] Accent is complementary or stakeholder-specified +- [ ] White-on-primary contrast ≥ 4.5:1 calculated and reported +- [ ] `docs/branding.md` updated with hex codes, rationale, and contrast note diff --git a/.opencode/skills/git-release/SKILL.md b/.opencode/skills/git-release/SKILL.md index fe85972..f8d66e4 100644 --- a/.opencode/skills/git-release/SKILL.md +++ b/.opencode/skills/git-release/SKILL.md @@ -1,7 +1,7 @@ --- name: git-release -description: Create releases with hybrid major.minor.calver versioning and AI-generated adjective-animal naming -version: "1.0" +description: Create releases with hybrid major.minor.calver versioning and optional custom release naming +version: "1.1" author: software-engineer audience: software-engineer workflow: release-management @@ -28,12 +28,9 @@ v1.2.20260415 → v1.3.20260415 (same-day second release) ## Release Naming -Each release gets a unique adjective-animal name. Analyze the commits and PRs since the last release, identify the theme, and choose a name that reflects it. +**Default**: no release name — the version tag alone is the release identifier. This is the industry-standard baseline (git tag, GitHub release title = version string). -Choose any adjective and any animal (use scientific name, not common name). The only constraints: - -1. **Thematic fit**: the name should reflect what this release does -2. **No repetition**: neither the adjective nor the animal may appear in a previous release +**Custom naming**: if `docs/branding.md` exists and `Release Naming > Convention` is set, apply it. The convention field specifies the pattern (e.g. `adjective-greek-figure`, `adjective-animal`, `codename`). Check previous names to avoid repetition: ```bash @@ -42,6 +39,15 @@ gh release list --limit 20 ## Release Process +### 0. Read branding + +Read `docs/branding.md` if it exists: + +- If `Release Naming > Convention` is set: use that convention for the release name. Analyze commits and PRs to choose a name that reflects the release theme. +- If `Release Naming > Theme` is set: constrain the name to that thematic domain. +- If `Release Naming > Excluded words` is set: omit those words. +- If the file is absent or `Release Naming > Convention` is blank: skip naming — use version string only. + ### 1. Analyze changes since last release ```bash @@ -68,9 +74,9 @@ Both must match: ### 4. Update CHANGELOG.md -Add at the top: +Add at the top. If a release name was generated in Step 0, include it; otherwise omit it: ```markdown -## [v{version}] - {Adjective Animal} - {YYYY-MM-DD} +## [v{version}] - {YYYY-MM-DD}[ - {Release Name}] ### Added - description (#PR-number) @@ -84,9 +90,9 @@ Add at the top: ### 5. Update living docs -Run the `living-docs` skill to reflect the newly accepted feature in C4 diagrams and the glossary. This step runs inline — do not commit separately. +Run the `update-docs` skill to reflect the newly accepted feature in C4 diagrams and the glossary. This step runs inline — do not commit separately. -Load and execute the full `living-docs` skill now: +Load and execute the full `update-docs` skill now: - Update `docs/c4/context.md` (C4 Level 1) - Update `docs/c4/container.md` (C4 Level 2, if multi-container) - Update `docs/glossary.md` (living glossary) @@ -101,7 +107,8 @@ After updating `pyproject.toml`, regenerate the lockfile — CI runs `uv sync -- uv lock git add pyproject.toml /__init__.py CHANGELOG.md uv.lock \ docs/c4/context.md docs/c4/container.md docs/glossary.md -git commit -m "chore(release): bump version to v{version} - {Adjective Animal}" +git commit -m "chore(release): bump version to v{version}[ - {Release Name}]" +# Include " - {Release Name}" only if a release name was generated in Step 0; omit otherwise. ``` ### 7. Create GitHub release @@ -111,10 +118,10 @@ Assign the SHA first so it expands correctly inside the notes string: ```bash SHA=$(git rev-parse --short HEAD) gh release create "v{version}" \ - --title "v{version} - {Adjective Animal}" \ - --notes "# v{version} - {Adjective Animal} + --title "v{version}[ - {Release Name}]" \ + --notes "# v{version}[ - {Release Name}] -> *\"{one-line tagline matching the release theme}\"* +> *\"{one-line tagline matching the release theme}\"* ← include only if a release name was generated ## Changelog @@ -129,10 +136,11 @@ gh release create "v{version}" \ ## Summary -2-3 sentences describing what this release accomplishes and why the name fits. +2-3 sentences describing what this release accomplishes[ and why the name fits — omit if no name]. --- **SHA**: \`${SHA}\`" +# Replace [ - {Release Name}] with the actual name, or omit the bracketed portion entirely if Step 0 produced no name. ``` ### 8. If a hotfix commit follows the release tag @@ -163,7 +171,7 @@ The release notes and title do not need to change — only the target commit mov - [ ] `uv lock` run after version bump — lockfile must be up to date - [ ] `/__version__` matches `pyproject.toml` version - [ ] CHANGELOG.md updated -- [ ] `living-docs` skill run — C4 diagrams and glossary reflect the new feature +- [ ] `update-docs` skill run — C4 diagrams and glossary reflect the new feature - [ ] Release name not used before - [ ] Release notes follow the template format - [ ] If a hotfix was pushed after the tag: tag reassigned to hotfix commit diff --git a/.opencode/skills/implementation/SKILL.md b/.opencode/skills/implement/SKILL.md similarity index 97% rename from .opencode/skills/implementation/SKILL.md rename to .opencode/skills/implement/SKILL.md index 61ada18..8e1aa37 100644 --- a/.opencode/skills/implementation/SKILL.md +++ b/.opencode/skills/implement/SKILL.md @@ -1,16 +1,20 @@ --- -name: implementation +name: implement description: Steps 2-3 — Architecture + TDD Loop, one @id at a time -version: "3.0" +version: "3.1" author: software-engineer audience: software-engineer workflow: feature-lifecycle --- -# Implementation +# Implement Steps 2 (Architecture) and 3 (TDD Loop) combined into a single skill. The software-engineer owns both. +## When to Use + +Load this skill when starting Step 2 (Architecture) after the PO has moved a BASELINED feature to `in-progress/`, or when continuing Step 3 (TDD Loop) for an in-progress feature. + ## Software-Engineer Quality Gate Priority Order During implementation, correctness priorities are (in order): @@ -72,7 +76,7 @@ For each external dep: For each noun: - Serving double duty across modules? → isolate -If pattern smell detected, load `skill design-patterns`. +If pattern smell detected, load `skill apply-patterns`. ### Write Stubs into Package @@ -153,7 +157,7 @@ Commit: `feat(): add architecture and test stubs` ### Prerequisites -- [ ] Exactly one .feature `in_progress`. If not present, Load `skill feature-selection` +- [ ] Exactly one .feature `in_progress`. If not present, load `skill select-feature` - [ ] Architecture stubs present in `/` (committed by Step 2) - [ ] Read `docs/architecture.md` — understand all architectural decisions before writing any test - [ ] Test stub files exist in `tests/features//_test.py` — generated by pytest-beehave at Step 2 end; if missing, re-run `uv run task test-fast` and commit the generated files before entering RED @@ -190,7 +194,7 @@ INNER LOOP │ (fix implementation only; do not advance to next @id) │ └── REFACTOR - ├── Load `skill refactor` — follow its protocol for this phase + ├── Load `skill refactor` — follow its Step-by-Step for this phase ├── uv run task test-fast after each individual change └── EXIT: test-fast passes; no smells remain diff --git a/.opencode/skills/refactor/SKILL.md b/.opencode/skills/refactor/SKILL.md index 208d12d..4f44369 100644 --- a/.opencode/skills/refactor/SKILL.md +++ b/.opencode/skills/refactor/SKILL.md @@ -42,7 +42,7 @@ Wear one hat at a time: --- -## When to Load This Skill +## When to Use ### 1. REFACTOR phase (opportunistic) @@ -60,7 +60,7 @@ Beck: *"For each desired change, make the change easy (warning: this may be hard --- -## Refactoring Protocol +## Step-by-Step ### Step 1 — Identify the smell @@ -81,7 +81,7 @@ Run the smell checklist from your Self-Declaration or from the Architecture Smel | Scattered notification or state transition | Observer / State | | Type-switching across callers | Strategy / Visitor | -If pattern smell detected: load `skill design-patterns` for before/after examples. +If pattern smell detected: load `skill apply-patterns` for before/after examples. ### Step 2 — Apply one catalogue entry at a time diff --git a/.opencode/skills/session-workflow/SKILL.md b/.opencode/skills/run-session/SKILL.md similarity index 77% rename from .opencode/skills/session-workflow/SKILL.md rename to .opencode/skills/run-session/SKILL.md index 0281f2c..469e864 100644 --- a/.opencode/skills/session-workflow/SKILL.md +++ b/.opencode/skills/run-session/SKILL.md @@ -1,5 +1,5 @@ --- -name: session-workflow +name: run-session description: Session start and end protocol — read TODO.md, continue from checkpoint, update and commit version: "3.0" author: software-engineer @@ -19,7 +19,7 @@ Every session starts by reading state. Every session ends by writing state. This # Current Work No feature in progress. - Next: Run @product-owner — load skill feature-selection and pick the next BASELINED feature from backlog. + Next: Run @product-owner — load skill select-feature and pick the next BASELINED feature from backlog. ``` 2. **If you are the PO** and Step 1 (SCOPE) is active: check `docs/discovery_journal.md` for the most recent session block. - If the most recent block has `Status: IN-PROGRESS` → the previous session was interrupted. Resume it before starting a new session: finish updating `.feature` files and `docs/discovery.md`, then mark the block `Status: COMPLETE`. @@ -31,8 +31,8 @@ Every session starts by reading state. Every session ends by writing state. This **If TODO.md says "No feature in progress":** -- **PO**: Load `skill feature-selection` — it guides you through scoring and selecting the next BASELINED backlog feature. You must verify the feature has `Status: BASELINED` before moving it to `in-progress/`. Only you may move it. -- **Software-engineer or reviewer**: Update TODO.md `Next:` line to `Run @product-owner — load skill feature-selection and pick the next BASELINED feature from backlog.` Then **stop**. Never self-select a feature. Never move a `.feature` file. +- **PO**: Load `skill select-feature` — it guides you through scoring and selecting the next BASELINED backlog feature. You must verify the feature has `Status: BASELINED` before moving it to `in-progress/`. Only you may move it. +- **Software-engineer or reviewer**: Update TODO.md `Next:` line to `Run @product-owner — load skill select-feature and pick the next BASELINED feature from backlog.` Then **stop**. Never self-select a feature. Never move a `.feature` file. ## Session End @@ -79,7 +79,7 @@ Run @ — **"Next" line format**: Always prefix with `Run @` so the human knows exactly which agent to invoke. Agent names are defined in `AGENTS.md` — use the name exactly as listed there. Examples: - `Run @ — implement @id:a1b2c3d4 (Step 3 RED)` -- `Run @ — load skill implementation and begin Step 2 (Architecture) for ` +- `Run @ — load skill implement and begin Step 2 (Architecture) for ` - `Run @ — verify feature at Step 4` - `Run @ — pick next BASELINED feature from backlog` - `Run @ — accept feature at Step 5` @@ -100,7 +100,7 @@ When no feature is active: # Current Work No feature in progress. -Next: Run @ — load skill feature-selection and pick the next BASELINED feature from backlog. +Next: Run @ — load skill select-feature and pick the next BASELINED feature from backlog. ``` ## Step 3 (TDD Loop) Cycle-Aware TODO Format @@ -142,3 +142,15 @@ Phase: RED | GREEN | REFACTOR 5. The "Next" line must be actionable enough that a fresh AI can execute it without asking questions 6. During Step 3, always update `## Cycle State` when transitioning between RED/GREEN/REFACTOR phases 7. When a step completes, update TODO.md and commit **before** any further work +8. Output is minimal-signal: findings, status, decisions, blockers, Next: line only. Use the fewest, least verbose tool calls necessary. Report results, not process. No redundant prose. + +## Output Style + +Use minimal output. Every message must contain only what the next agent or stakeholder needs to continue — findings, status, decisions, blockers, and the Next: line. + +- Use the fewest, least verbose tool calls necessary to achieve the step's goal +- Report results, not process ("3 files changed" not "I ran git status and it showed...") +- No narration before or after tool calls +- No restating tool output in prose +- No summaries of what was just done +- Always close with Next: diff --git a/.opencode/skills/feature-selection/SKILL.md b/.opencode/skills/select-feature/SKILL.md similarity index 93% rename from .opencode/skills/feature-selection/SKILL.md rename to .opencode/skills/select-feature/SKILL.md index a195b20..6e36630 100644 --- a/.opencode/skills/feature-selection/SKILL.md +++ b/.opencode/skills/select-feature/SKILL.md @@ -1,5 +1,5 @@ --- -name: feature-selection +name: select-feature description: Score and select the next backlog feature by value, effort, and dependencies version: "1.0" author: product-owner @@ -36,7 +36,7 @@ ls docs/features/in-progress/ Read each `.feature` file in `docs/features/backlog/`. Check its discovery section for `Status: BASELINED`. - Non-BASELINED features are not eligible — they need Step 1 (scope) first -- If no BASELINED features exist: inform the stakeholder; run `@product-owner` with `skill scope` to baseline the most promising backlog item first +- If no BASELINED features exist: inform the stakeholder; run `@product-owner` with `skill define-scope` to baseline the most promising backlog item first **IMPORTANT** @@ -99,9 +99,9 @@ Source: docs/features/in-progress/.feature Run @ — ``` -- If the feature has no `Rule:` blocks yet → Step 1 (SCOPE): `Run @product-owner — load skill scope and write stories` -- If the feature has `Rule:` blocks but no `@id` Examples → Step 1 Stage 2 Step B (Criteria): `Run @product-owner — load skill scope and write acceptance criteria` -- If the feature has `@id` Examples → Step 2 (ARCH): `Run @software-engineer — load skill implementation and write architecture stubs` +- If the feature has no `Rule:` blocks yet → Step 1 (SCOPE): `Run @product-owner — load skill define-scope and write stories` +- If the feature has `Rule:` blocks but no `@id` Examples → Step 1 Stage 2 Step B (Criteria): `Run @product-owner — load skill define-scope and write acceptance criteria` +- If the feature has `@id` Examples → Step 2 (ARCH): `Run @software-engineer — load skill implement and write architecture stubs` ### 6. Commit diff --git a/.opencode/skills/living-docs/SKILL.md b/.opencode/skills/update-docs/SKILL.md similarity index 91% rename from .opencode/skills/living-docs/SKILL.md rename to .opencode/skills/update-docs/SKILL.md index 8472547..2537243 100644 --- a/.opencode/skills/living-docs/SKILL.md +++ b/.opencode/skills/update-docs/SKILL.md @@ -1,5 +1,5 @@ --- -name: living-docs +name: update-docs description: Generate and update C4 architecture diagrams and the living glossary from existing project docs version: "1.0" author: product-owner @@ -22,9 +22,9 @@ The glossary is a secondary artifact derived from the code, the domain model, an | Document | Created/Updated by | Inputs read | |---|---|---| -| `docs/c4/context.md` | `living-docs` skill (PO) | `docs/discovery.md`, `docs/features/completed/` | -| `docs/c4/container.md` | `living-docs` skill (PO) | `docs/architecture.md`, `docs/features/completed/` | -| `docs/glossary.md` | `living-docs` skill (PO) | `docs/discovery.md`, `docs/glossary.md` (existing), `docs/architecture.md`, `docs/features/completed/` | +| `docs/c4/context.md` | `update-docs` skill (PO) | `docs/discovery.md`, `docs/features/completed/` | +| `docs/c4/container.md` | `update-docs` skill (PO) | `docs/architecture.md`, `docs/features/completed/` | +| `docs/glossary.md` | `update-docs` skill (PO) | `docs/discovery.md`, `docs/glossary.md` (existing), `docs/architecture.md`, `docs/features/completed/` | | `docs/architecture.md` | SE only (Step 2) | — | | `docs/discovery.md` | PO only (Step 1) | — | @@ -41,6 +41,7 @@ Read in this order: 3. `docs/architecture.md` — all architectural decisions (containers, modules, protocols, external deps) 4. `docs/c4/` — existing C4 diagrams if they exist (update, do not replace from scratch) 5. `docs/glossary.md` — existing glossary if it exists (extend, never remove existing entries) +6. `docs/branding.md` — if present, read `Visual > Primary color` and `Accent color`. Apply to C4 Mermaid diagrams via `%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '', 'lineColor': ''}}}%%`. If absent or fields blank, use Mermaid defaults. Identify from the read phase: @@ -142,7 +143,7 @@ The glossary answers: **what does each domain term mean in this project's contex ```markdown # Glossary — -> Living document. Updated after each completed feature by the `living-docs` skill. +> Living document. Updated after each completed feature by the `update-docs` skill. > Source: docs/discovery.md (Domain Model), docs/features/completed/, docs/architecture.md --- @@ -188,20 +189,20 @@ If `docs/glossary.md` already exists: **When run standalone** (stakeholder on demand): commit after all diagrams and glossary are updated: ``` -docs(living-docs): update C4 and glossary after +docs(update-docs): update C4 and glossary after ``` If triggered without a specific feature (general refresh): ``` -docs(living-docs): refresh C4 diagrams and glossary +docs(update-docs): refresh C4 diagrams and glossary ``` --- ## Checklist -- [ ] Read all five source files before writing anything +- [ ] Read all source files before writing anything (including `docs/branding.md` if present) - [ ] Context diagram reflects all actors from completed feature files - [ ] Context diagram reflects all external systems from `docs/architecture.md` - [ ] Container diagram present only if multi-container architecture confirmed in `docs/architecture.md` @@ -209,5 +210,5 @@ docs(living-docs): refresh C4 diagrams and glossary - [ ] No existing glossary entry removed - [ ] Every new term has a traceable source in completed feature files or `docs/architecture.md`; no term is invented - [ ] No edits made to `docs/architecture.md` or `docs/discovery.md` -- [ ] If standalone: committed with `docs(living-docs): ...` message +- [ ] If standalone: committed with `docs(update-docs): ...` message - [ ] If called from release: files staged but not committed (release process commits) diff --git a/.opencode/skills/verify/SKILL.md b/.opencode/skills/verify/SKILL.md index 3d5c449..5359d1c 100644 --- a/.opencode/skills/verify/SKILL.md +++ b/.opencode/skills/verify/SKILL.md @@ -19,6 +19,10 @@ This skill guides the reviewer through Step 4: independent verification that the The reviewer produces one written report (see template below) that includes: all gate results, the SE Self-Declaration Audit, the **Reviewer Stance Declaration**, and the final APPROVED/REJECTED verdict. Do not start until the software-engineer has committed all work and communicated the Self-Declaration verbally in the handoff message. +## When to Use + +Load this skill when the software-engineer signals Step 3 complete and hands off for review (Step 4). Do not load it earlier. + ## Step-by-Step ### 1. Read the Feature Docs @@ -60,7 +64,7 @@ Run before code review. If any row is FAIL, stop immediately with REJECTED. ### 5. Self-Declaration Audit -**Completeness check (hard gate — REJECT if failed)**: Count the numbered items in the SE's Self-Declaration. The template in `implementation/SKILL.md` has exactly 25 items numbered 1–25. If the count is not 25, or any number in the sequence 1–25 is missing, REJECT immediately — do not proceed to item-level audit. +**Completeness check (hard gate — REJECT if failed)**: Count the numbered items in the SE's Self-Declaration. The template in `implement/SKILL.md` has exactly 25 items numbered 1–25. If the count is not 25, or any number in the sequence 1–25 is missing, REJECT immediately — do not proceed to item-level audit. Read the software-engineer's Self-Declaration from the handoff message. @@ -110,7 +114,7 @@ Read the source files changed in this feature. **Do this before running lint/sta #### 6d. Object Calisthenics — any FAIL → REJECTED -Load `skill design-patterns` and apply the full OC checklist (9 rules). Record a PASS/FAIL with `file:line` evidence for each rule. Rules 1 and 7 (nesting and entity size) share thresholds with 6b above. +Load `skill apply-patterns` and apply the full OC checklist (9 rules). Record a PASS/FAIL with `file:line` evidence for each rule. Rules 1 and 7 (nesting and entity size) share thresholds with 6b above. #### 6e. Design Patterns — any FAIL → REJECTED diff --git a/AGENTS.md b/AGENTS.md index e483107..17d4278 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,27 +44,32 @@ STEP 5: ACCEPT (product-owner) → demo, validate, move .feature to com - **product-owner** — defines scope (Stage 1 Discovery + Stage 2 Specification), picks features, accepts deliveries - **software-engineer** — architecture, tests, code, git, releases (Steps 2-3 + release) - **reviewer** — runs commands and reviews code at Step 4, produces APPROVED/REJECTED report +- **designer** — creates and updates visual assets (SVG banners, logos) and maintains `docs/branding.md` - **setup-project** — one-time setup to initialize a new project from this template ## Skills | Skill | Used By | Step | |---|---|---| -| `session-workflow` | all agents | every session | -| `feature-selection` | product-owner | between features (idle state) | -| `scope` | product-owner | 1 | -| `implementation` | software-engineer | 2, 3 | -| `design-patterns` | software-engineer | 2, 3 (on-demand, when GoF pattern needed) | +| `run-session` | all agents | every session | +| `select-feature` | product-owner | between features (idle state) | +| `define-scope` | product-owner | 1 | +| `implement` | software-engineer | 2, 3 | +| `apply-patterns` | software-engineer | 2, 3 (on-demand, when GoF pattern needed) | | `refactor` | software-engineer | 3 (REFACTOR phase + preparatory refactoring) | | `verify` | reviewer | 4 | -| `code-quality` | software-engineer | pre-handoff (redirects to `verify`) | -| `pr-management` | software-engineer | 5 | -| `git-release` | software-engineer | 5 | -| `living-docs` | product-owner | 5 (after acceptance) + on stakeholder demand | +| `check-quality` | software-engineer | pre-handoff (redirects to `verify`) | +| `create-pr` | software-engineer | 5 | +| `git-release` | software-engineer | 5 (after acceptance) | +| `update-docs` | product-owner | 5 (after acceptance) + on stakeholder demand | +| `design-colors` | designer | branding, color, WCAG compliance | +| `design-assets` | designer | SVG asset creation and updates | | `create-skill` | software-engineer | meta | | `create-agent` | human-user | meta | -**Session protocol**: Every agent loads `skill session-workflow` at session start. Load additional skills as needed for the current step. +**Branding**: Agents that generate docs, diagrams, release names, or visual assets read `docs/branding.md` if present. Absent or blank fields fall back to defaults (adjective-animal release names, Mermaid default colors, no wording constraints). `docs/branding.md` and `docs/assets/` are owned by the designer agent. + +**Session protocol**: Every agent loads `skill run-session` at session start. Load additional skills as needed for the current step. ## Step 1 — SCOPE @@ -118,10 +123,12 @@ docs/ discovery_journal.md ← raw Q&A, PO appends after every session discovery.md ← synthesis changelog, PO appends after every session architecture.md ← all architectural decisions, SE appends after Step 2 - glossary.md ← living glossary, PO updates via living-docs skill + glossary.md ← living glossary, PO updates via update-docs skill + branding.md ← project identity, colors, release naming, wording (designer owns) + assets/ ← logo.svg, banner.svg, and other visual assets (designer owns) c4/ - context.md ← C4 Level 1 diagram, PO updates via living-docs skill - container.md ← C4 Level 2 diagram, PO updates via living-docs skill + context.md ← C4 Level 1 diagram, PO updates via update-docs skill + container.md ← C4 Level 2 diagram, PO updates via update-docs skill features/ backlog/.feature ← narrative + Rules + Examples in-progress/.feature @@ -229,15 +236,15 @@ Version format: `v{major}.{minor}.{YYYYMMDD}` - Minor bump for new features; major bump for breaking changes - Same-day second release: increment minor, keep same date -- Each release gets a unique adjective-animal name +- Release name: defined by `docs/branding.md > Release Naming > Convention`; absent or blank defaults to version string only (no name) Use `@software-engineer /skill git-release` for the full release process. When requested by the stakeholder ## Session Management -Every session: load `skill session-workflow`. Read `TODO.md` first, update it at the end. +Every session: load `skill run-session`. Read `TODO.md` first, update it at the end. -`TODO.md` is a session bookmark — not a project journal. See `.opencode/skills/session-workflow/SKILL.md` for the full structure including the Cycle State block used during Step 3. +`TODO.md` is a session bookmark — not a project journal. See `.opencode/skills/run-session/SKILL.md` for the full structure including the Cycle State block used during Step 3. ## Setup diff --git a/README.md b/README.md index a89bb28..90026c7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-Python Project Template +Python Project Template

diff --git a/docs/images/banner.svg b/docs/assets/banner.svg similarity index 100% rename from docs/images/banner.svg rename to docs/assets/banner.svg diff --git a/docs/images/logo.svg b/docs/assets/logo.svg similarity index 100% rename from docs/images/logo.svg rename to docs/assets/logo.svg diff --git a/docs/branding.md b/docs/branding.md new file mode 100644 index 0000000..f3b83a9 --- /dev/null +++ b/docs/branding.md @@ -0,0 +1,43 @@ +# Branding + +All fields are optional. Blank or absent fields fall back to defaults (adjective-animal release names, Mermaid default colors, no wording constraints). Agents read this file before generating release names, C4 diagrams, README banners, or any document with visual or copy identity. + +--- + +## Identity + +- **Project name:** Python Project Template +- **Tagline:** Production-ready Python, from zero to workflow in minutes. +- **Mission:** Eliminate boilerplate so engineers ship features, not setup. +- **Vision:** The standard starting point for any serious Python project. +- **Tone of voice:** Direct, precise, minimal. No fluff. + +## Visual + +- **Background/parchment:** `#faf7f2` → `#ede8e0` — warm off-white marble (primary surface) +- **Primary text:** `#5c3d1e` → `#3b2410` — deep warm brown (body text, headings) +- **Accent/gold:** `#c9a84c` → `#e8c96a` — antique gold (borders, highlights, lines) +- **Secondary/blue:** `#7baabf` → `#4a7a96` — muted steel blue (labels, secondary text) +- **Stone/marble:** `#f0ece4` → `#c8c0b8` — structural marble tone (temple columns, shapes) +- **Logo:** `docs/assets/logo.svg` +- **Banner:** `docs/assets/banner.svg` + +> Color system derived from the SVG assets (classical Greek temple aesthetic — marble, parchment, antique gold). Deep brown `#3b2410` on parchment `#faf7f2` achieves > 10:1 contrast (WCAG AAA). Gold accent used for decorative lines and borders only, not body text. + +## Release Naming + +- **Convention:** `adjective-greek-figure` +- **Theme:** Greek antiquity — philosophers, heroes, gods, mythological figures (e.g. "Nimble Socrates", "Resolute Athena", "Precise Pythagoras") +- **Excluded words:** *(none)* + +## Wording + +- **Avoid:** `easy`, `simple`, `just`, `quick` — these undermine engineer credibility +- **Prefer:** `minimal`, `precise`, `production-ready`, `zero-boilerplate` + +## Project Summary + +A Python project template with a production-ready AI-assisted delivery workflow. +Ships with quality tooling (ruff, pyright, pytest, hypothesis), Gherkin-driven +acceptance criteria, and four specialized AI agents covering scope through release. +Use this summary in banners, release notes, and document headers.