@schilling.mark.a/software-methodology 1.0.0

package/project-templates/test-strategy.md.template

@@ -0,0 +1,87 @@
+# Test Strategy
+
+## Overview
+This project uses ATDD with Red-Green-Refactor workflow. All test commands referenced by the atdd-workflow skill come from this file.
+
+## Testing Tools
+
+### Acceptance Testing
+- **Framework**: [TODO: e.g., Playwright, Cypress, Selenium, TestCafe]
+- **Purpose**: End-to-end testing through UI or API
+- **File pattern**: `tests/acceptance/**/*.[test|spec].[ext]`
+
+### Unit Testing
+- **Framework**: [TODO: e.g., Jest, Vitest, Mocha, pytest, JUnit]
+- **Purpose**: Test business logic in isolation
+- **File pattern**: `tests/unit/**/*.[test|spec].[ext]`
+
+### Test Doubles
+- **Library**: [TODO: e.g., Jest mocks, Sinon, Mockito, unittest.mock]
+- **Strategy**: Mock external dependencies (databases, APIs, file systems). Use real objects for domain logic.
+
+### Coverage
+- **Tool**: [TODO: e.g., Istanbul/c8, Coverage.py, JaCoCo]
+- **Minimum**: 90% line coverage
+- **Critical paths**: 100% coverage required
+
+## Test Commands
+
+**Claude Code uses these commands. Fill in all of them.**
+
+```bash
+# Run all tests
+[TODO]
+
+# Run acceptance tests only
+[TODO]
+
+# Run unit tests only
+[TODO]
+
+# Generate coverage report
+[TODO]
+
+# Watch mode (for TDD loop)
+[TODO]
+```
+
+## File Structure
+
+```
+tests/
+├── acceptance/[domain]/     ← End-to-end tests (from Gherkin scenarios)
+├── unit/[domain]/           ← Unit tests (one behavior per test)
+├── fixtures/                ← Shared test data
+└── helpers/                 ← Page objects, builders, test utilities
+```
+
+## Test Structure Pattern
+
+Follow Arrange-Act-Assert (AAA):
+```
+Arrange: Set up state and preconditions
+Act:     Execute the behavior under test
+Assert:  Verify the expected outcome
+```
+
+## Architecture (for test organization)
+[TODO: Describe your source code structure so tests mirror it]
+
+Example:
+- `/src/domain/` → `/tests/unit/domain/`
+- `/src/application/` → `/tests/unit/application/`
+
+## Mock/Stub Strategy
+
+### Mock these:
+- External APIs
+- Databases
+- File systems
+- Email/notification services
+- Time-dependent behavior
+
+### Do NOT mock these:
+- Domain objects
+- Value objects
+- Pure functions
+- Business logic calculations

package/story-mapping/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: story-mapping
+description: User story mapping for organizing user activities into a navigable map that connects business value to implementable tasks. Use when creating or updating a story map, planning releases, breaking down epics, organizing user tasks, or when the user says "story map", "user journey", "plan release", or "break down epic". Produces backbone.md, walking-skeleton.md, release plans, and individual task files in /docs/story-map/. Output tasks are consumed by bdd-specification skill.
+---
+
+# User Story Mapping
+
+## Overview
+
+Organizes user activities and tasks into a structured map that connects value propositions to implementable work. Provides the backbone that BDD specification and ATDD implementation build upon.
+
+## Before Starting — Read Context
+
+1. `/docs/business-model-canvas.md` — business model
+2. `/docs/value-proposition-canvas.md` — customer jobs, pains, gains (primary source for activities)
+3. `/docs/ubiquitous-language.md` — domain terminology
+4. `/docs/story-map/backbone.md` — existing backbone (if updating)
+
+## Workflow Decision
+
+**No story map exists?** → Follow "Create Story Map" below
+**Story map exists, adding features?** → Follow "Update Story Map" below
+**Planning a release?** → Follow "Release Planning" below
+
+## Create Story Map
+
+### Step 1: Identify User Activities (Backbone)
+
+Source: Value Proposition Canvas — Customer Jobs
+
+Each customer job maps to one user activity. Activities are the horizontal spine of the map, ordered by typical user flow.
+
+See `references/backbone.md` for structure and file format.
+
+Create: `/docs/story-map/backbone.md`
+
+### Step 2: Define Walking Skeleton
+
+The thinnest possible path through the system that delivers end-to-end value. One task per activity, minimum viable behavior.
+
+See `references/walking-skeleton.md` for structure.
+
+Create: `/docs/story-map/walking-skeleton.md`
+
+### Step 3: Break Activities into Tasks
+
+For each activity, identify the specific things users do. Each task becomes an individual file.
+
+See `references/task-template.md` for file structure.
+
+Create: `/docs/story-map/user-tasks/[ACT-ID]-[task-NNN].md`
+
+### Step 4: Plan Release 1
+
+Slice vertically — each release delivers end-to-end value across activities. Start with the walking skeleton.
+
+See `references/release-planning.md` for approach.
+
+Create: `/docs/story-map/releases/r1-mvp.md`
+
+## Update Story Map
+
+When adding new features:
+1. Determine which activity the new task belongs to
+2. Create task file following the template
+3. Update backbone.md if a new activity is needed
+4. Update the relevant release plan
+5. Update traceability matrix
+
+## Release Planning
+
+See `references/release-planning.md` for full guidance on vertical slicing, prioritization, and release scope definition.
+
+## File Structure
+
+```
+docs/story-map/
+├── backbone.md                      ← User activities (horizontal spine)
+├── walking-skeleton.md              ← Minimum viable journey
+├── releases/
+│   ├── r1-mvp.md                   ← Release 1 scope
+│   └── r2-[name].md               ← Release 2 scope
+└── user-tasks/
+    ├── ACT-001-task-001.md         ← Individual task
+    ├── ACT-001-task-002.md
+    └── ACT-002-task-001.md
+```
+
+## Task ID Convention
+
+```
+ACT-[activity number]-task-[task number]
+Example: ACT-001-task-003
+```
+
+## Integration
+
+```
+story-mapping (this skill)  →  identifies tasks and acceptance criteria
+    ↓
+bdd-specification  →  writes Gherkin feature file for each task
+    ↓
+atdd-workflow  →  implements with RED-GREEN-REFACTOR
+```

package/story-mapping/references/backbone.md

@@ -0,0 +1,66 @@
+# Backbone — User Activities
+
+## What is the Backbone?
+
+The horizontal spine of the story map. Each entry is a high-level user activity — a goal the user wants to accomplish. Activities are ordered left-to-right by the typical user flow through the system.
+
+## Deriving Activities from Value Proposition Canvas
+
+Each Customer Job in the Value Proposition Canvas maps to one User Activity.
+
+**Mapping process:**
+1. Read `/docs/value-proposition-canvas.md`
+2. List each Customer Job
+3. Reframe each job as a user activity (present tense, action-oriented)
+4. Order by typical usage sequence — what does a user do first, second, third?
+
+**Example mapping:**
+```
+Customer Job: "Send invoices to customers quickly"
+→ Activity: Invoice Management
+
+Customer Job: "Track who owes me money"
+→ Activity: Payment Tracking
+
+Customer Job: "Understand my business financial health"
+→ Activity: Financial Reporting
+```
+
+## Sequencing Rules
+
+Order activities by **typical user flow**, not by:
+- Technical complexity
+- Implementation priority
+- What's easiest to build
+
+If activities are independent (user can do them in any order), sequence by frequency — most frequent first.
+
+## File Format
+
+Create: `/docs/story-map/backbone.md`
+
+```markdown
+# Story Map Backbone
+
+## User Activities
+
+### ACT-001: [Activity Name]
+**User Goal:** [What the user wants to accomplish]
+
+**Value Proposition Link:**
+- Pain relieved: [from VPC]
+- Gain created: [from VPC]
+
+**Tasks:** [List task IDs once created]
+
+---
+
+### ACT-002: [Activity Name]
+[same structure]
+```
+
+## Sizing Guidelines
+
+- **Too few activities (1-2):** The system probably has more distinct user goals. Break down further.
+- **Right range (3-7):** Most systems fall here.
+- **Too many activities (8+):** Some activities might belong together. Consider grouping.

package/story-mapping/references/release-planning.md

@@ -0,0 +1,92 @@
+# Release Planning
+
+## Vertical Slicing
+
+Each release must deliver end-to-end value. Slice across activities, not down them.
+
+**Anti-pattern — horizontal slicing:**
+```
+❌ Release 1: All of Invoice Management (complete)
+❌ Release 2: All of Payment Tracking (complete)
+❌ Release 3: All of Financial Reporting (complete)
+
+Problem: Release 1 delivers invoicing but user can't track payments.
+         No end-to-end value until Release 2.
+```
+
+**Correct — vertical slicing:**
+```
+✅ Release 1: Basic invoice creation + basic payment tracking
+✅ Release 2: Advanced invoice features + payment details + basic reporting
+✅ Release 3: Full reporting + analytics + integrations
+
+Each release: user can create invoices AND track payments (end-to-end value)
+```
+
+## Prioritization — MoSCoW
+
+**Must Have:** Release fails without it. Core value proposition. Walking skeleton tasks.
+
+**Should Have:** Important but a workaround exists. Significant value. Can slip to next release if needed.
+
+**Could Have:** Nice to have. Minor improvement. Easy to defer.
+
+**Won't Have (this release):** Explicitly out of scope. Document why — prevents scope creep.
+
+## Priority Matrix
+
+When choosing what goes into a release, consider both axes:
+
+| | Low Risk/Complexity | High Risk/Complexity |
+|---|---|---|
+| **High Value** | Do early — quick wins | De-risk early — learn fast |
+| **Low Value** | Do late or defer | Question if needed at all |
+
+## Release File Format
+
+Create: `/docs/story-map/releases/r[N]-[name].md`
+
+```markdown
+# Release [N] — [Name]
+
+## Goal
+[What end-to-end capability this release delivers]
+
+## Target Date
+[Date]
+
+## Value Proposition
+- Job to be done: [from VPC]
+- Pain relieved: [from VPC]
+- Gain created: [from VPC]
+
+## Included Tasks
+
+### [Activity Name]
+- ✅ [TASK-ID]: [Task name] — [MoSCoW]
+- ✅ [TASK-ID]: [Task name] — [MoSCoW]
+- ❌ [TASK-ID]: [Task name] — deferred to R[N+1]
+
+### [Activity Name]
+[same pattern]
+
+## Success Metrics
+- [How we know this release succeeded]
+- [Measurable user outcome]
+
+## Risks
+- [Risk] — mitigated by [mitigation]
+
+## Dependencies
+- [What must be ready before this release can ship]
+```
+
+## Release Sequencing
+
+Release 1 always starts with the walking skeleton. Each subsequent release adds depth to existing activities before adding new activities.
+
+**Decision:** "Should this go in the current release or next?"
+- Does it block end-to-end value? → Current release
+- Does a workaround exist? → Next release
+- Is it high value + low risk? → Current release
+- Is it high risk? → De-risk now (spike/prototype), implement when understood

package/story-mapping/references/task-template.md

@@ -0,0 +1,78 @@
+# Task Template
+
+## File Location
+
+`/docs/story-map/user-tasks/[ACT-ID]-task-[NNN].md`
+
+Example: `/docs/story-map/user-tasks/ACT-001-task-003.md`
+
+## Template
+
+```markdown
+# [ACT-ID]-task-[NNN]: [Task Name]
+
+## Activity
+[ACT-ID]: [Activity Name]
+
+## User Task
+As a [user role]
+I want to [capability]
+So that [business value]
+
+## Value Proposition Link
+- Pain relieved: [from VPC]
+- Gain created: [from VPC]
+
+## Acceptance Criteria
+- [Observable behavior 1]
+- [Observable behavior 2]
+- [Observable behavior 3]
+
+## Priority
+- **MoSCoW:** Must Have | Should Have | Could Have | Won't Have
+- **Business Value:** High | Medium | Low
+- **Complexity:** High | Medium | Low
+
+## Release
+[Release name — e.g., "Release 1 - MVP"]
+
+## Dependencies
+- [What must exist before this task can be implemented]
+
+## Feature File
+[Path to .feature file — filled in after bdd-specification runs]
+
+## Status
+- [ ] Acceptance criteria defined
+- [ ] Example mapping complete
+- [ ] Scenarios written
+- [ ] Acceptance tests created
+- [ ] Implementation complete
+- [ ] Deployed
+
+## Notes
+[Additional context]
+```
+
+## Task Sizing
+
+**Right size:** Completable in 1-3 days, produces 1 feature file with 2-5 scenarios.
+
+**Too large — split by:**
+- CRUD operations (create / read / update / delete as separate tasks)
+- Data complexity (basic first, then edge cases)
+- User roles (different users, different tasks)
+- Happy vs error paths (core behavior first, validation second)
+- Incremental complexity (simple version first, advanced version later)
+
+**Too small — combine when:**
+- Task has no standalone user value
+- Task is a single step inside a larger behavior
+- Completing it alone doesn't change what the user can do
+
+## Characteristics of a Good Task
+
+- **User-centric:** Written from the user's perspective, not the system's
+- **Valuable:** Completing it delivers observable value to the user
+- **Testable:** Success can be verified with concrete acceptance criteria
+- **Independent:** Can be implemented without depending on other unbuilt tasks (where possible)

package/story-mapping/references/walking-skeleton.md

@@ -0,0 +1,63 @@
+# Walking Skeleton
+
+## What is the Walking Skeleton?
+
+The thinnest possible slice through the entire system that delivers end-to-end value. One task per activity, minimum viable behavior per task. It proves the architecture works and delivers real value before adding depth.
+
+## Rules
+
+- Must touch every activity in the backbone (end-to-end)
+- Each included task is reduced to its absolute minimum behavior
+- Explicitly lists what is NOT included and why
+- Becomes the core of Release 1
+
+## Determining Minimum Behavior
+
+For each activity, ask: "What is the single simplest version of this that still delivers value?"
+
+**Example — Invoice Management activity:**
+- Full behavior: Multi-line items, tax calculation, drafts, editing, voiding, PDF export
+- Walking skeleton: Single line item, no tax, save as final only, no editing
+
+**Example — Payment Tracking activity:**
+- Full behavior: Partial payments, multiple payment methods, payment history, reminders
+- Walking skeleton: Mark invoice as paid or unpaid. Nothing else.
+
+## File Format
+
+Create: `/docs/story-map/walking-skeleton.md`
+
+```markdown
+# Walking Skeleton — Minimum Viable Journey
+
+## Goal
+[What end-to-end value this delivers]
+
+## User Journey
+
+### 1. [Activity Name] — Simplified
+- ✅ [Task ID]: [Task name]
+  - Included: [What's in]
+  - Excluded: [What's cut and why]
+
+### 2. [Activity Name] — Simplified
+[same pattern]
+
+### 3. [Activity Name] — Deferred
+- ❌ [Reason — e.g., "Not needed for core value loop"]
+
+## What's NOT in the Walking Skeleton
+- [Feature] — deferred to R2
+- [Feature] — deferred to R2
+- [Feature] — not needed for minimum value delivery
+
+## Success Criteria
+User can:
+1. [End-to-end action 1]
+2. [End-to-end action 2]
+3. [Verify value was delivered]
+```
+
+## Common Mistake
+
+Including too much. The walking skeleton should feel uncomfortably thin. If it feels complete, cut more. Depth comes in subsequent releases.

package/ui-design-system/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: ui-design-system
+description: Design system reference for consistent UI implementation. Use when implementing any UI component or screen, when choosing colors, spacing, typography, or layout, when the user says "style this", "what color should I use", or "follow the design system". Provides design tokens, layout grid rules, typography scale, component specifications, and accessibility standards. Read before writing any presentation layer code. Output of this skill populates /docs/ui-design/design-system.md in each project.
+---
+
+# UI Design System
+
+## Overview
+
+Single source of truth for visual and interactive consistency. Every screen, component, and layout decision references this system. Consistency is not optional — it is what makes a product feel professional and usable.
+
+## How to Use This Skill
+
+**Starting a new project?** Read `references/design-tokens.md` first — tokens are the foundation everything else builds on. Then populate `/docs/ui-design/design-system.md` in your project with your chosen token values.
+
+**Implementing a screen?** Read `references/layout.md` for grid and spacing, `references/typography.md` for text hierarchy, then `references/components.md` for the components you need.
+
+**Choosing a color?** Read `references/design-tokens.md` — never use raw color values. Always reference a semantic token.
+
+**Checking accessibility?** Read `references/accessibility.md` before shipping any screen.
+
+## Decision Tree — Which Reference to Load
+
+### "I need to choose colors or spacing"
+→ Read `references/design-tokens.md`
+
+### "I need to lay out a page or section"
+→ Read `references/layout.md`
+
+### "I need to style text or choose a heading level"
+→ Read `references/typography.md`
+
+### "I need to implement a button, input, table, or other UI element"
+→ Read `references/components.md`
+
+### "I need to check if my UI is accessible"
+→ Read `references/accessibility.md`
+
+## Project Setup
+
+When starting a new project, create `/docs/ui-design/design-system.md` by populating the token values from `references/design-tokens.md` with your project's actual values. This file becomes the project-specific design system that ui-design-workflow reads.
+
+## Constraints
+
+- **Never use raw values.** No hardcoded hex colors, no magic pixel numbers. Everything references a token.
+- **Semantic naming.** Tokens are named for their purpose, not their value. `color.error` not `color.red`.
+- **Accessibility first.** Every color combination must meet WCAG AA. Every interactive element must be keyboard-navigable. Read `references/accessibility.md` before any screen ships.
+- **Consistency over preference.** If a component exists in the system, use it. Do not create a one-off variant because you personally prefer a different look.

package/ui-design-system/references/accessibility.md

@@ -0,0 +1,134 @@
+# Accessibility
+
+## Standard: WCAG AA
+
+All UI must meet WCAG 2.1 AA. This is not optional. Every screen, every component, every interaction.
+
+---
+
+## Color Contrast
+
+### Minimum Ratios (WCAG AA)
+
+| Text type | Minimum ratio |
+|---|---|
+| Normal text (< 18px or < 14px bold) | 4.5:1 |
+| Large text (≥ 18px or ≥ 14px bold) | 3:1 |
+| UI components and graphical objects | 3:1 |
+
+### Rules
+- Never convey meaning through color alone. Always pair with text, icon, or pattern.
+- Error states: red background/border AND an error icon AND error message text. Not just red.
+- Success states: green background/border AND a checkmark icon AND success message text.
+- Disabled elements are exempt from contrast requirements — but don't use "disabled" as an excuse to make things invisible.
+
+### Token Compliance
+
+When choosing token values for your project's design-system.md, verify every foreground/background combination meets the ratios above before committing.
+
+---
+
+## Keyboard Navigation
+
+Every interactive element must be reachable and operable via keyboard alone.
+
+### Tab Order
+- Follows the visual reading order (left to right, top to bottom)
+- Never use `tabindex` values other than 0 or -1
+- `tabindex="0"` — include in natural tab order
+- `tabindex="-1"` — focusable programmatically, but not via Tab
+
+### Focus Visibility
+- Every focused element shows a visible focus ring
+- Focus ring: border.width.medium, border.color.focus, offset 2px
+- Never remove the default focus outline without providing a replacement
+
+### Keyboard Interactions by Component
+
+**Buttons:** Enter or Space activates
+**Links:** Enter activates
+**Inputs:** Tab moves between fields. Enter submits form (single-input forms only)
+**Select:** Space opens dropdown. Arrow keys navigate options. Enter selects.
+**Modal:** Tab cycles within modal only (focus trap). Escape closes.
+**Tabs:** Arrow keys move between tabs. Enter/Space activates.
+**Table:** Arrow keys navigate cells. Enter activates cell action.
+**Accordion:** Enter/Space toggles panel. Arrow keys move between panels.
+
+---
+
+## Screen Reader Support
+
+### Semantic HTML First
+
+Use native HTML elements before ARIA. A `<button>` is better than a `<div role="button">`. A `<nav>` is better than a `<div aria-label="Navigation">`.
+
+### Required ARIA Patterns
+
+**Forms:**
+- Every input has an associated `<label>` (via `for`/`id` or wrapping)
+- Helper text linked via `aria-describedby`
+- Error messages linked via `aria-describedby` AND `aria-invalid="true"` on the input
+
+**Alerts:**
+- Use `role="alert"` for error messages that appear dynamically
+- Use `aria-live="polite"` for success/info messages that don't need immediate attention
+
+**Buttons with icons only (no text label):**
+- Must have `aria-label` describing the action
+- Example: close button → `aria-label="Close modal"`
+
+**Images:**
+- Decorative images: `alt=""`
+- Meaningful images: `alt="[description of what the image conveys]"`
+- Never put the filename in alt text
+
+**Tables:**
+- Use `<th>` for headers with `scope="col"` or `scope="row"`
+- Use `<caption>` or `aria-label` on the `<table>` to describe its purpose
+
+**Navigation:**
+- Wrap in `<nav>` element
+- If multiple nav elements exist, use `aria-label` to distinguish them
+- Active page/item: `aria-current="page"` or `aria-current="true"`
+
+**Modals:**
+- `role="dialog"` and `aria-modal="true"`
+- `aria-labelledby` pointing to the modal title
+- Focus moves to the modal on open. Returns to the trigger on close.
+
+### Loading States
+- Announce loading with `aria-live="polite"` — "Loading results..."
+- Announce completion — "Results loaded. Showing 12 invoices."
+- Never use a spinner alone without text. Screen readers can't see it.
+
+---
+
+## Reduced Motion
+
+Respect `prefers-reduced-motion: reduce`:
+- Disable or minimize animations
+- Replace motion-based transitions with instant state changes
+- Keep functional animations (loading spinner) but simplify them
+
+---
+
+## Pre-Ship Accessibility Checklist
+
+Run this before any screen ships:
+
+- [ ] All text meets contrast ratios against its background
+- [ ] Color is not the sole indicator of meaning (status, errors, required fields)
+- [ ] All interactive elements are reachable via keyboard in logical order
+- [ ] Focus is always visible
+- [ ] All form inputs have visible labels
+- [ ] All error messages are associated with their inputs
+- [ ] All images have appropriate alt text
+- [ ] Dynamic content changes are announced via aria-live
+- [ ] Modals trap focus and are dismissible via Escape
+- [ ] Page has exactly one h1
+- [ ] Heading levels are sequential (no skips)
+- [ ] Tables use proper header structure
+- [ ] Navigation landmarks are labeled
+- [ ] Loading and empty states are announced to screen readers
+- [ ] Animations respect prefers-reduced-motion
+- [ ] Touch targets are at least 44×44px on mobile