@schilling.mark.a/software-methodology 1.0.0

package/bdd-specification/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: bdd-specification
+description: Behavior-Driven Development specification skill for writing Gherkin feature files and example mapping documents. Use when creating feature files, writing acceptance criteria, converting story map tasks into scenarios, or when the user says "write specification", "create Gherkin", "define acceptance criteria", or "example mapping". Produces .feature files in /features/ and example mapping docs in /docs/example-mapping/. Requires story-mapping skill context. Output is consumed by atdd-workflow skill.
+---
+
+# BDD Specification by Example
+
+## Overview
+
+Translates story map tasks into executable Gherkin specifications. Produces feature files that serve as both living documentation and input for acceptance tests.
+
+## Before Starting — Read Context
+
+1. `/docs/story-map/user-tasks/[task-id].md` — the task being specified
+2. `/docs/ubiquitous-language.md` — CRITICAL: all Gherkin terms must come from here
+3. `/docs/value-proposition-canvas.md` — business value context
+4. `/features/[domain]/` — existing feature files for consistency
+
+## Workflow
+
+**Story map task exists?** → Follow "Specification Workflow" below
+**No story map task?** → Use story-mapping skill first, then return here
+
+## Specification Workflow
+
+### Step 1: Example Mapping
+
+Before writing Gherkin, run example mapping. See `references/example-mapping.md` for full process.
+
+Create: `/docs/example-mapping/[feature]-[YYYY-MM-DD].md`
+
+Output: Rules, concrete examples, and any open questions.
+
+### Step 2: Write Feature File
+
+Create: `/features/[domain]/[feature-name].feature`
+
+See `references/gherkin-patterns.md` for syntax, patterns, and anti-patterns.
+
+**Required elements:**
+- Feature header with story format (As a / I want / So that)
+- Story map task ID in a comment at the top
+- At least: one happy path, one alternative path, one error/validation case
+- Background section for setup shared across all scenarios
+- Scenario Outline with Examples table when the same behavior applies to multiple data sets
+
+### Step 3: Validate Against Ubiquitous Language
+
+Every domain term in the feature file must exist in `/docs/ubiquitous-language.md`.
+
+If a needed term is missing:
+1. Add it to the glossary first — include definition, context, and related terms
+2. Then use it in the scenario
+
+### Step 4: Update Story Map
+
+Update `/docs/story-map/user-tasks/[task-id].md`:
+- Link to the created feature file
+- Check off "Scenarios written"
+
+### Step 5: Hand Off to ATDD
+
+Feature file is now ready as input for atdd-workflow skill.
+
+## Quality Checklist
+
+- [ ] Story map task ID referenced in feature file comment
+- [ ] All terms exist in ubiquitous language glossary
+- [ ] Happy path scenario included
+- [ ] Alternative path scenario included
+- [ ] Error/validation scenario included
+- [ ] Scenarios are declarative (not imperative)
+- [ ] Scenarios are independent (no ordering dependency)
+- [ ] Each scenario tests exactly one behavior
+- [ ] Background used only for setup common to ALL scenarios
+- [ ] Scenario Outlines used for data variations
+- [ ] Example mapping document created
+- [ ] Open questions documented
+
+## Integration
+
+```
+story-mapping  →  identifies task and acceptance criteria
+    ↓
+bdd-specification (this skill)  →  writes Gherkin feature file
+    ↓
+atdd-workflow  →  implements with RED-GREEN-REFACTOR
+```

package/bdd-specification/references/example-mapping.md

@@ -0,0 +1,105 @@
+# Example Mapping
+
+## Purpose
+
+Example mapping discovers the rules, examples, and open questions for a feature before writing Gherkin. It prevents writing scenarios that miss business rules or contain ambiguities.
+
+## Process
+
+### 1. Identify the Story
+
+Pull from the story map task:
+```
+As a [user role]
+I want to [capability]
+So that [business value]
+```
+
+### 2. Discover Rules
+
+Rules are business constraints that govern behavior. Extract from:
+- Value proposition canvas (what gains/pains must be addressed)
+- Story map task acceptance criteria
+- Domain knowledge
+
+**Rule format:** "The system must [behavior] when [condition]"
+
+**Examples:**
+- "Invoice total must equal the sum of all line item amounts"
+- "A customer cannot be deleted when they have unpaid invoices"
+- "Invoice numbers must be unique and sequential"
+
+### 3. Generate Examples for Each Rule
+
+For each rule, create concrete examples covering:
+- **Happy path** — normal successful case
+- **Alternative path** — valid variation of the happy path
+- **Error/edge case** — what happens when constraints are violated
+
+**Example format:**
+```
+Given [concrete initial state]
+When [specific action]
+Then [observable outcome]
+```
+
+Keep values concrete — no variables or placeholders at this stage.
+
+### 4. Capture Questions
+
+Document anything uncertain:
+- Business rules that aren't clear
+- Edge cases where behavior is undefined
+- Dependencies on other systems or features
+
+**Format:** Track as open items. If a question blocks scenario writing, mark the scenario as TODO and continue with unblocked scenarios.
+
+## Output Document
+
+Create: `/docs/example-mapping/[feature]-[YYYY-MM-DD].md`
+
+```markdown
+# Example Mapping: [Feature Name]
+
+**Date:** [YYYY-MM-DD]
+**Story Map Task:** [TASK-ID]
+
+## Story
+As a [role]
+I want to [capability]
+So that [value]
+
+## Rules and Examples
+
+### Rule 1: [Business rule statement]
+
+**Example 1 — Happy path:** [scenario name]
+- Given [state]
+- When [action]
+- Then [outcome]
+
+**Example 2 — Edge case:** [scenario name]
+- Given [state]
+- When [action]
+- Then [outcome]
+
+### Rule 2: [Business rule statement]
+
+[continue pattern]
+
+## Questions
+- [ ] [Question] → [Answer or TBD]
+- [ ] [Question] → [Answer or TBD]
+
+## Out of Scope
+- [Explicitly excluded behavior]
+```
+
+## When to Skip Example Mapping
+
+Skip only when:
+- Feature is trivially simple (single CRUD operation, no business rules)
+- Rules are already well-documented in story map task
+- Feature is a minor extension of an already-mapped feature
+
+Even then, document at least the rules — they drive scenario count.

package/bdd-specification/references/gherkin-patterns.md

@@ -0,0 +1,214 @@
+# Gherkin Patterns
+
+## Feature File Structure
+
+```gherkin
+# Story Map: [TASK-ID]
+# Value Prop: [VP-ID]
+
+Feature: [Noun phrase — e.g., "Invoice Creation"]
+  As a [user role from value proposition]
+  I want to [capability]
+  So that [business value]
+
+  Background:
+    Given [setup common to ALL scenarios in this feature]
+
+  Scenario: [Happy path]
+    Given [initial state]
+    When [action]
+    Then [outcome]
+
+  Scenario: [Alternative path]
+    ...
+
+  Scenario: [Error case]
+    ...
+
+  Scenario Outline: [Parameterized behavior]
+    Given [context with <placeholder>]
+    When [action]
+    Then [outcome with <expected>]
+
+    Examples:
+      | placeholder | expected |
+      | value1      | result1  |
+      | value2      | result2  |
+```
+
+## Given-When-Then Rules
+
+### Given — Establish State
+- Past tense: "Given an invoice exists for customer 'ACME Corp'"
+- Describe state, not how it was created
+- Include only context relevant to this scenario
+
+### When — Single Action
+- Present tense: "When I save the invoice"
+- One user action per When step
+- From the user's perspective, not the system's
+
+### Then — Observable Outcome
+- Present tense: "Then I should see invoice number INV-2024-0001"
+- Only what the user can observe
+- Never internal system state (databases, queues, logs)
+
+### And — Continue Previous Keyword
+- "And" inherits the meaning of the previous Given/When/Then
+- Use for additional setup, actions, or assertions
+
+## Background vs Given
+
+**Background:** Setup that applies to every scenario in the feature. Authentication state, system configuration, common data.
+
+**Given:** Setup specific to this scenario only.
+
+If a Given step appears in every scenario, move it to Background.
+
+## Scenario Outline
+
+Use when the **same behavior** applies to **different data**. The Examples table drives one test execution per row.
+
+**Good use:**
+```gherkin
+Scenario Outline: Validate line item amount
+  Given I am adding a line item
+  When I enter amount "<amount>"
+  And I save
+  Then I should see error "<error>"
+
+  Examples:
+    | amount  | error                    |
+    | -100    | Amount cannot be negative |
+    | 0       | Amount must be positive  |
+    | abc     | Amount must be a number  |
+```
+
+**Bad use — different behaviors should be separate scenarios:**
+```gherkin
+# DON'T do this — create vs edit are different behaviors
+Scenario Outline: Invoice operations
+  Given I am on the <page> page
+  When I click <button>
+  Then I should see <result>
+
+  Examples:
+    | page    | button | result          |
+    | new     | Save   | New invoice     |
+    | edit    | Update | Updated invoice |
+```
+
+## Tags
+
+```gherkin
+@invoicing @critical
+Scenario: Create invoice
+
+@wip
+Scenario: Tax calculation
+  # Not ready for implementation yet
+
+@manual
+Scenario: Email delivery confirmation
+  # Cannot be automated
+
+@slow
+Scenario: Generate annual report
+```
+
+Common tags: `@critical`, `@wip`, `@manual`, `@slow`, `@regression`
+
+## Anti-Patterns
+
+### Imperative Steps (UI-level detail)
+```gherkin
+❌ When I click the "Save" button
+   And I wait for the loading spinner to disappear
+   And I see the green notification bar
+
+✅ When I save the invoice
+   Then I should see a confirmation
+```
+
+### Technical Implementation Leaking Through
+```gherkin
+❌ Then the invoice record should be inserted into the database
+   And the invoice_total column should equal 1000
+
+✅ Then the invoice should be saved
+   And the total should be $1,000.00
+```
+
+### Conjunction Steps (Multiple Actions)
+```gherkin
+❌ When I enter the customer name and select a product and set the quantity
+
+✅ Given I have selected customer "ACME Corp"
+   And I have added product "Consulting"
+   When I set the quantity to 5
+```
+
+### Incidental Detail
+```gherkin
+❌ Given a customer with ID 12345 and email "test@example.com" and phone "555-1234" and address "123 Main St"
+
+✅ Given customer "ACME Corp" exists
+```
+Only include data that is relevant to the scenario's behavior.
+
+### Scenario Dependency
+```gherkin
+❌ Scenario: Create invoice
+     ...creates invoice INV-001...
+
+   Scenario: Edit invoice
+     Given I have invoice INV-001  # ← depends on previous scenario having run
+
+✅ Each scenario sets up its own state independently
+```
+
+## CRUD Scenario Templates
+
+### Create
+```gherkin
+Scenario: Create [entity] with valid data
+  Given I am authorized to create [entities]
+  When I create a new [entity] with [key attributes]
+  Then the [entity] should be saved
+  And I should see confirmation
+```
+
+### Read
+```gherkin
+Scenario: View [entity] details
+  Given [entity] "[name]" exists
+  When I view the [entity]
+  Then I should see [key attributes]
+```
+
+### Update
+```gherkin
+Scenario: Update [entity] attribute
+  Given [entity] "[name]" exists
+  When I update [attribute] to "[new value]"
+  Then the [entity] should reflect the change
+```
+
+### Delete
+```gherkin
+Scenario: Delete [entity] with no dependencies
+  Given [entity] "[name]" exists
+  And [entity] has no dependent records
+  When I delete the [entity]
+  Then the [entity] should no longer exist
+```
+
+### Validation
+```gherkin
+Scenario: Reject [entity] with invalid [attribute]
+  Given I am creating a new [entity]
+  When I enter invalid [attribute] "[bad value]"
+  And I attempt to save
+  Then I should see error "[message]"
+  And the [entity] should not be saved
+```

package/cicd-pipeline/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cicd-pipeline
+description: CI/CD pipeline design and configuration skill. Defines the automated path from committed code to production. Use when setting up a new project's pipeline, when the user says "set up CI/CD", "configure the pipeline", "automate deployment", "define the release gates", or "how does code get to production". Sits between atdd-workflow (which ends at commit) and continuous-improvement (which begins after release ships). This skill defines everything in between — build, test gates, environment promotion, deployment strategy, and rollback. Also defines what "ready to ship" means, which release-planning's Dependencies section references.
+---
+
+# CI/CD Pipeline
+
+## Overview
+
+atdd-workflow ends when code is committed green. continuous-improvement begins after a release ships. This skill defines everything in between: how committed code is automatically built, tested, promoted through environments, and deployed to production. It also defines the gates — the points where the pipeline stops and requires the code to prove it is ready before proceeding.
+
+The pipeline is not optional. Without it, "deployed" on the task template checklist is a manual, error-prone step. With it, deployment is a consequence of passing all gates — deterministic, repeatable, and auditable.
+
+## When to Run This Skill
+
+- **New project:** Design the pipeline before any code is committed. The pipeline configuration is infrastructure, not an afterthought.
+- **Pipeline failure:** A build broke, a deployment failed, or code reached production that should not have. Investigate which gate failed or was missing.
+- **New environment:** Adding staging, canary, or a regional deployment target.
+
+## Workflow
+
+### Step 1: Define the Pipeline Stages
+
+The pipeline has a fixed sequence of stages. Each stage has a gate — a pass/fail condition. Code moves forward only if the gate passes. If any gate fails, the pipeline stops and notifies.
+
+See `references/pipeline-stages.md` for the full stage sequence, what each gate checks, and how stages connect to the artifacts atdd-workflow already produces.
+
+Create: `/docs/cicd/pipeline.md`
+
+### Step 2: Define Environment Promotion Strategy
+
+Code does not go directly from commit to production. It moves through environments, each one closer to production and each one with stricter gates. The promotion strategy defines which environments exist, what runs in each, and what approval (if any) is required to move forward.
+
+See `references/environment-promotion.md` for environment definitions, promotion rules, and approval gates.
+
+Create: `/docs/cicd/environments.md`
+
+### Step 3: Define Deployment and Rollback Strategy
+
+How code is deployed to each environment, and how to recover when a deployment fails or a production defect is discovered. The deployment strategy must match the risk profile — a canary deployment for high-traffic features, a blue-green swap for zero-downtime requirements, a simple replace for low-risk internal tools.
+
+See `references/deployment-rollback.md` for deployment patterns, rollback triggers, and rollback procedures.
+
+Create: `/docs/cicd/deployment.md`
+
+## Output Contract
+
+This skill produces three documents that other parts of the methodology reference:
+
+- **`/docs/cicd/pipeline.md`** — defines what "ready to ship" means. release-planning's Dependencies section references this.
+- **`/docs/cicd/environments.md`** — defines the promotion path. The task template's `[ ] Deployed` checkbox maps to successful promotion to production.
+- **`/docs/cicd/deployment.md`** — defines rollback. continuous-improvement's root cause analysis references this when a production defect triggers an incident.
+
+## Integration
+
+```
+atdd-workflow       →  commits green code
+    ↓
+cicd-pipeline (this skill)  →  build → test gates → promote → deploy
+    ↓
+continuous-improvement      →  measures what shipped, investigates defects
+```
+
+The pipeline is the bridge. atdd-workflow guarantees the code is tested. The pipeline guarantees the tested code reaches production correctly.

package/cicd-pipeline/references/deployment-rollback.md

@@ -0,0 +1,176 @@
+# Deployment and Rollback
+
+## Deployment Strategies
+
+Not all deployments carry the same risk. A small internal tool can tolerate a brief outage during deployment. A high-traffic customer-facing application cannot. The deployment strategy matches the risk profile of the application and the change being deployed.
+
+Choose one strategy per environment. Production and staging may use different strategies if their risk profiles differ.
+
+---
+
+### Strategy 1: Replace (Simple Deploy)
+
+**What happens:** The old version is stopped. The new version is started in its place. There is a brief period (seconds to minutes) where the application is unavailable.
+
+**Use when:**
+- Internal tools with no SLA
+- Development or staging environments
+- Applications with very low traffic where brief downtime is acceptable
+
+**Risk:** Downtime during deployment. If the new version fails to start, the application is down until rollback completes.
+
+**Rollback:** Stop the new version. Start the previous version. Downtime during rollback as well.
+
+---
+
+### Strategy 2: Blue-Green Deploy
+
+**What happens:** Two identical environments exist — "blue" (current production) and "green" (new version). The new version is deployed to green and fully tested there. When ready, traffic is switched from blue to green in a single atomic operation. Blue remains running and idle, ready for instant rollback.
+
+**Use when:**
+- Customer-facing applications that require zero downtime
+- Applications where you need an instant rollback capability
+- Deployments where you want to verify the new version is healthy before any real traffic touches it
+
+**Risk:** Requires double the infrastructure (both blue and green must run simultaneously). The traffic switch is atomic — users either see the old version or the new version, never both.
+
+**Rollback:** Switch traffic back to blue. Instant. No downtime. Blue was idle but running the entire time.
+
+---
+
+### Strategy 3: Canary Deploy
+
+**What happens:** The new version is deployed to a small percentage of production traffic (typically 1–5%). The pipeline monitors error rates and response times for the canary traffic. If metrics are healthy for the observation period, traffic is gradually shifted to the new version (10% → 25% → 50% → 100%). If metrics degrade at any point, the canary is automatically rolled back.
+
+**Use when:**
+- High-traffic applications where even a small error rate affects many users
+- Changes where the failure mode is subtle and only surfaces under real traffic patterns
+- Applications with sophisticated monitoring that can detect error rate changes quickly
+
+**Risk:** A small percentage of real users will experience any failure in the new version during the canary period. The observation period must be long enough to surface failures but short enough to limit exposure.
+
+**Rollback:** Shift all traffic back to the previous version. The canary instances are stopped. Users on the canary see the previous version within seconds.
+
+---
+
+### Strategy 4: Rolling Deploy
+
+**What happens:** Instances are updated one at a time (or in small batches). Each instance is removed from the load balancer, updated to the new version, health-checked, and added back. The application remains available throughout — at any point, some instances run the old version and some run the new version.
+
+**Use when:**
+- Applications that can tolerate mixed versions temporarily (stateless, no version-dependent shared state)
+- Applications where zero downtime is required but canary monitoring is not available
+- Large instance counts where replacing all at once is risky
+
+**Risk:** During the rollout, both old and new versions serve traffic simultaneously. If the application has version-dependent behavior (e.g., database schema changes that are incompatible with the old version), rolling deploy will cause failures. Never use rolling deploy when a database migration accompanies the code change unless the migration is backward-compatible.
+
+**Rollback:** Stop updating remaining instances. Roll back the already-updated instances one at a time using the same process. The application remains available during rollback.
+
+---
+
+## Rollback Triggers
+
+Rollback is not a manual decision made after someone notices a problem. It is an automated response to a defined condition. The conditions are objective — not subjective judgment calls.
+
+### Automatic Rollback Triggers
+
+The pipeline or monitoring system triggers rollback automatically when any of these conditions are met:
+
+| Trigger | Condition | Rollback scope |
+|---|---|---|
+| Health check failure | Application does not respond to health endpoint within timeout | Full rollback to previous version |
+| Error rate spike | Production error rate exceeds baseline + threshold for observation window | Full rollback (or canary rollback if using canary) |
+| Latency spike | P95 response time exceeds baseline + threshold for observation window | Full rollback |
+| Canary failure | Canary error rate exceeds baseline + threshold during observation period | Canary rollback — shift traffic back to previous version |
+| Deployment timeout | Deployment does not complete within the maximum allowed time | Rollback the partial deployment |
+
+### Manual Rollback Triggers
+
+A team member initiates rollback when:
+
+- A production incident is reported by users that monitoring did not catch (rare if monitoring is well-configured)
+- A deployment is proceeding but a critical business decision requires stopping it (e.g., a pricing change deployed by mistake)
+- A security vulnerability is discovered in the deployed version after deployment
+
+### What Rollback Is NOT
+
+- Rollback is not "redeploy the old version from scratch." It is "switch back to the previous known-good version that is already available." Blue-green keeps it running. Canary keeps it serving traffic. Rolling keeps it on unupdated instances. Replace restores from the previous artifact.
+- Rollback does not undo database migrations. If a migration ran during deployment, rolling back the application does not roll back the database. The migration must be backward-compatible or the database must be rolled back separately — see Database Migration Rules below.
+
+---
+
+## Database Migration Rules
+
+Database migrations are the most dangerous part of any deployment. They run before the new application version starts (or during startup). If the migration breaks, the database is in an inconsistent state. If the migration is incompatible with the old application version, rollback breaks the application.
+
+### Rule 1: Migrations Must Be Backward-Compatible
+
+Every migration must leave the database in a state that both the old and new application versions can read. This means:
+
+- **Adding a column:** Add it as nullable. The old version ignores it. The new version writes to it.
+- **Removing a column:** Do not remove it in the same deploy as the code that stops using it. Remove the code first (deploy and verify). Remove the column in a subsequent deploy.
+- **Renaming a column:** Do not rename. Add the new column, migrate data, update code to use the new column, deploy and verify, then remove the old column in a subsequent deploy.
+- **Changing a column type:** Same pattern as rename — add, migrate, switch, verify, remove.
+
+### Rule 2: Migrations Run Before Application Start
+
+The pipeline deploys the migration first, then starts the new application version. This means the migration must succeed against the current database state — not the future state.
+
+### Rule 3: Migrations Are Tested in Staging
+
+The staging database must have representative data. A migration that works against an empty database but fails against real data will not be caught until production. Run migrations against staging first. Verify the application works against the migrated staging database before promoting to production.
+
+---
+
+## Deployment Configuration Document
+
+Create: `/docs/cicd/deployment.md`
+
+```markdown
+# Deployment Configuration
+
+**Created:** [Date]
+**Last updated:** [Date]
+
+## Deployment Strategy by Environment
+
+| Environment | Strategy | Rationale |
+|---|---|---|
+| Staging | [Strategy] | [Why this strategy for staging] |
+| Production | [Strategy] | [Why this strategy for production] |
+
+## Canary Configuration (if used)
+- **Initial canary percentage:** [e.g., 1%]
+- **Observation window:** [e.g., 10 minutes per step]
+- **Ramp schedule:** [e.g., 1% → 5% → 25% → 50% → 100%]
+- **Automatic rollback condition:** Error rate > [threshold]% for > [duration]
+
+## Health Check Configuration
+- **Endpoint:** [Health check URL or command]
+- **Timeout:** [How long to wait before declaring unhealthy]
+- **Error rate baseline:** [Current baseline error rate]
+- **Error rate threshold:** [Max deviation before rollback triggers]
+- **Latency baseline:** [Current P95 latency]
+- **Latency threshold:** [Max deviation before rollback triggers]
+- **Observation window:** [How long to monitor after deployment before declaring healthy]
+
+## Rollback Procedure
+1. [Automated or manual trigger fires]
+2. [Traffic shifted / instances stopped — specific to chosen strategy]
+3. [Previous version restored — specific to chosen strategy]
+4. [Health check confirms previous version is healthy]
+5. [Notification sent to team]
+6. [Incident logged — triggers continuous-improvement root cause analysis]
+
+## Database Migration Policy
+- All migrations are backward-compatible (see deployment-rollback.md rules)
+- Migrations run in staging first and are verified before production promotion
+- Migration rollback procedure: [Document specific procedure if migrations are not fully backward-compatible]
+```
+
+## Rules
+
+- Choose the deployment strategy based on the application's risk profile, not on what tools are available. If the tools do not support the strategy you need, find tools that do.
+- Rollback triggers are objective conditions, not judgment calls. Define them before the first deployment. Do not change them under pressure during an incident.
+- Database migrations are backward-compatible or they do not ship. No exceptions. A non-backward-compatible migration means the application cannot be rolled back safely — that is an unacceptable risk.
+- Every rollback is logged and triggers a continuous-improvement root cause analysis. Rollbacks are not failures to hide — they are the system working as designed. The investigation asks why the pipeline did not catch the problem, not why the rollback happened.