@schilling.mark.a/software-methodology 1.0.0

package/docs/SKILLS.md

@@ -0,0 +1,296 @@
+# Software Methodology Skills Index
+
+This document provides quick access to all skills in the methodology. Each skill has a SKILL.md entry point and detailed reference files.
+
+**See also**: [Quick Start](QUICKSTART.md) | [Sharing Guide](SHARING.md) | [Main README](../README.md)
+
+## Quick Navigation
+
+Jump to: [Product](#product-strategy) | [Research](#ux-research) | [Planning](#story-mapping) | [Specification](#bdd-specification) | [Design](#design-skills) | [Development](#development-skills) | [Operations](#cicd-pipeline) | [Improvement](#continuous-improvement)
+
+---
+
+## Product Strategy
+
+**Location**: [`product-strategy/SKILL.md`](../product-strategy/SKILL.md)
+
+**Purpose**: Create and maintain the Business Model Canvas and Value Proposition Canvas — the foundation documents that all other skills depend on.
+
+**When to use**:
+- Starting a new product
+- Entering a new market or user segment
+- After research reveals strategy changes needed
+
+**Key references**:
+- [Business Model Canvas](../product-strategy/references/business-model-canvas.md)
+- [Value Proposition Canvas](../product-strategy/references/value-proposition-canvas.md)
+- [Canvas Alignment](../product-strategy/references/canvas-alignment.md)
+
+**Outputs**: `/docs/business-model-canvas.md`, `/docs/value-proposition-canvas.md`
+
+---
+
+## UX Research
+
+**Location**: [`ux-research/SKILL.md`](../ux-research/SKILL.md)
+
+**Purpose**: Create personas, mental models, and user journey maps to understand customer needs deeply.
+
+**When to use**:
+- After creating the Value Proposition Canvas
+- Before designing features
+- When user feedback reveals gaps in understanding
+
+**Key references**:
+- Check the skill for persona templates and mental model formats
+
+**Outputs**: `/docs/personas/`, `/docs/mental-models/`, `/docs/user-journey-maps/`
+
+---
+
+## Story Mapping
+
+**Location**: [`story-mapping/SKILL.md`](../story-mapping/SKILL.md)
+
+**Purpose**: Organize user activities into a backbone and sequence features into releases.
+
+**When to use**:
+- After personas and journey maps exist
+- Planning a new release
+- Reorganizing the product backlog
+
+**Key references**:
+- [Backbone Structure](../story-mapping/references/backbone.md)
+- [Walking Skeleton](../story-mapping/references/walking-skeleton.md)
+- [Release Planning](../story-mapping/references/release-planning.md)
+- [Task Template](../story-mapping/references/task-template.md)
+
+**Outputs**: `/docs/story-map/backbone.md`, `/docs/story-map/releases/*.md`
+
+---
+
+## BDD Specification
+
+**Location**: [`bdd-specification/SKILL.md`](../bdd-specification/SKILL.md)
+
+**Purpose**: Write Gherkin feature files using example mapping to discover scenarios and rules.
+
+**When to use**:
+- After selecting tasks for a release
+- Before implementation begins
+- Clarifying feature acceptance criteria
+
+**Outputs**: `/features/*.feature`
+
+---
+
+## Design Skills
+
+### UX Design
+
+**Location**: [`ux-design/SKILL.md`](../ux-design/SKILL.md)
+
+**Purpose**: Design information architecture, interaction patterns, usability flows, and onboarding.
+
+**When to use**:
+- After feature specifications exist
+- Designing new user flows
+- Improving existing interactions
+
+**Key references**:
+- [Information Architecture](../ux-design/references/information-architecture.md)
+- [Interaction Patterns](../ux-design/references/interaction-patterns.md)
+- [Usability Evaluation](../ux-design/references/usability-evaluation.md)
+- [Onboarding](../ux-design/references/onboarding.md)
+
+**Outputs**: Design documents in `/docs/`
+
+### UI Design Workflow
+
+**Location**: [`ui-design-workflow/SKILL.md`](../ui-design-workflow/SKILL.md)
+
+**Purpose**: Create screen flows, select components, and set acceptance targets for UI implementation.
+
+**When to use**:
+- After UX design is complete
+- Before implementation
+- Defining UI acceptance criteria
+
+**Outputs**: `/docs/screen-flows/`, component selections, acceptance targets
+
+### UI Design System
+
+**Location**: [`ui-design-system/SKILL.md`](../ui-design-system/SKILL.md)
+
+**Type**: Reference skill (consulted during UI design workflow)
+
+**Purpose**: Define design tokens, typography, layout, components, and accessibility standards.
+
+**When to use**:
+- Referenced during `ui-design-workflow`
+- Setting up a new design system
+- Ensuring UI consistency
+
+**Outputs**: Design system documentation
+
+---
+
+## Development Skills
+
+### ATDD Workflow
+
+**Location**: [`atdd-workflow/SKILL.md`](../atdd-workflow/SKILL.md)
+
+**Purpose**: Implement features using RED-GREEN-REFACTOR test-driven development cycle.
+
+**When to use**:
+- Implementing any feature
+- Writing production code
+- Every development task
+
+**Workflow**: RED (write failing test) → GREEN (make it pass) → REFACTOR (improve design)
+
+**Outputs**: Implementation code and tests
+
+### Green Implementation
+
+**Location**: [`green-implementation/SKILL.md`](../green-implementation/SKILL.md)
+
+**Purpose**: Detailed patterns for Angular/TypeScript/Playwright implementation during the GREEN phase.
+
+**When to use**:
+- During GREEN phase of ATDD workflow
+- Implementing Angular components
+- Writing Playwright tests
+
+**Key references**:
+- [Angular Patterns](../green-implementation/references/angular-patterns.md)
+- [RxJS Patterns](../green-implementation/references/rxjs-patterns.md)
+- [Playwright Patterns](../green-implementation/references/playwright-patterns.md)
+- [Common Rejections](../green-implementation/references/common-rejections.md)
+
+### Clean Code
+
+**Location**: [`clean-code/SKILL.md`](../clean-code/SKILL.md)
+
+**Type**: Reference skill (consulted during GREEN and REFACTOR phases)
+
+**Purpose**: Apply SOLID principles and design patterns to create maintainable code.
+
+**When to use**:
+- During GREEN phase (choosing patterns)
+- During REFACTOR phase (improving design)
+- Code reviews
+
+**Key references**:
+- [SOLID Principles](../clean-code/references/solid.md)
+- [Structural Patterns](../clean-code/references/structural-patterns.md)
+- [Behavioral Patterns](../clean-code/references/behavioral-patterns.md)
+- [Creational Patterns](../clean-code/references/creational-patterns.md)
+
+---
+
+## CI/CD Pipeline
+
+**Location**: [`cicd-pipeline/SKILL.md`](../cicd-pipeline/SKILL.md)
+
+**Purpose**: Set up pipeline stages, environment promotion, deployment, and rollback procedures.
+
+**When to use**:
+- Setting up a new project
+- Adding deployment environments
+- Configuring CI/CD automation
+
+**Outputs**: Pipeline configuration, deployment scripts
+
+---
+
+## Continuous Improvement
+
+**Location**: [`continuous-improvement/SKILL.md`](../continuous-improvement/SKILL.md)
+
+**Purpose**: Measure post-release outcomes, perform root cause analysis, and feed improvements back into the methodology.
+
+**When to use**:
+- After each release
+- When production issues occur
+- Regular improvement cycles
+
+**Outputs**: Measurement reports, process improvements (feeds back to any upstream skill)
+
+---
+
+## The Methodology Flow
+
+```
+┌─────────────────────┐
+│ product-strategy    │  Business Model Canvas + Value Proposition Canvas
+└──────────┬──────────┘
+           │
+           ▼
+┌─────────────────────┐
+│ ux-research         │  Personas + Mental Models + Journey Maps
+└──────────┬──────────┘
+           │
+           ▼
+┌─────────────────────┐
+│ story-mapping       │  Backbone + Release Plans
+└──────────┬──────────┘
+           │
+           ▼
+┌─────────────────────┐
+│ bdd-specification   │  Feature Files (Gherkin)
+└──────────┬──────────┘
+           │
+           ▼
+┌─────────────────────┐
+│ ux-design           │  Information Architecture + Interaction Patterns
+└──────────┬──────────┘
+           │
+           ▼
+┌─────────────────────┐
+│ ui-design-workflow  │◄─────┐ ui-design-system (reference)
+└──────────┬──────────┘      │
+           │                  │
+           ▼                  │
+┌─────────────────────┐      │
+│ atdd-workflow       │◄─────┤
+│ (RED-GREEN-REFACTOR)│      │ clean-code (reference)
+└──────────┬──────────┘      │
+           │                  │
+           ▼                  │
+┌─────────────────────┐      │
+│ cicd-pipeline       │      │
+└──────────┬──────────┘      │
+           │                  │
+           ▼                  │
+┌─────────────────────┐      │
+│ continuous-         │──────┘
+│ improvement         │  Feeds improvements back upstream
+└─────────────────────┘
+```
+
+## Using Skills with Different Tools
+
+### With Claude Code
+
+Deploy `.skill` files from `dist/` directory to `/mnt/skills/user/`. See main [README.md](../README.md) for details.
+
+### With GitHub Copilot
+
+Copilot reads `.github/copilot-instructions.md` and can reference these skill files directly. Ask Copilot about methodology questions and it will guide you to the right skill.
+
+### With VS Code
+
+Open this repository in VS Code. All skills are in markdown format and easily navigable. Use the VS Code workspace settings in `.vscode/settings.json` for optimized navigation.
+
+---
+
+## Project Templates
+
+When starting a new project, use the templates in [`project-templates/`](../project-templates/):
+
+- **context.md.template** — Project context file for Claude Code
+- **test-strategy.md.template** — Testing approach and commands
+
+Copy these to your project's `/docs/` directory and fill in the project-specific details.

package/green-implementation/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: green-implementation
+description: >
+  Angular/TypeScript/Playwright implementation patterns for making tests green
+  while meeting team coding standards. Use during the GREEN and REFACTOR phases
+  of the ATDD workflow — when writing production code to pass failing tests.
+  Activates when: implementing features, making tests pass, writing Angular
+  components or services, creating Playwright page objects, fixing PR feedback,
+  or when the user says "make it green", "implement", "write the code",
+  "fix the PR comments". Works alongside atdd-workflow (which governs the
+  RED-GREEN-REFACTOR discipline) and clean-code (which governs design
+  principles). This skill governs the team-specific conventions that prevent
+  PR rejections. Reads acceptance criteria from the active feature context.
+  Produces code that passes both automated tests and peer review.
+---
+
+# GREEN Implementation — Angular / TypeScript / Playwright
+
+## Purpose
+
+atdd-workflow tells the agent *how to work* (RED→GREEN→REFACTOR).
+clean-code tells the agent *how to design* (SOLID, patterns).
+This skill tells the agent *what the team will accept* — the conventions
+that prevent PR rejections and rework.
+
+Only codify patterns here where the wrong choice causes rework. If both
+approaches are acceptable on the team, don't specify one.
+
+## Before Writing Code
+
+1. Read the failing test — understand EXACTLY what it asserts
+2. Read the AC from the active feature context
+3. Read `/docs/test-strategy.md` for test commands
+4. Read `/docs/ubiquitous-language.md` for naming
+
+## Architecture Rules
+
+These are non-negotiable. Violations block PRs.
+
+### Services Own HTTP — Components Never Touch HttpClient
+
+```typescript
+// ✅
+@Component({ ... })
+export class UserListComponent {
+  users$ = this.userService.getUsers();
+  constructor(private userService: UserService) {}
+}
+
+// ❌ PR REJECTED
+@Component({ ... })
+export class UserListComponent {
+  constructor(private http: HttpClient) {}
+}
+```
+
+### Business Logic in Services, Not Components
+
+Components: template binding + user interaction.
+Services: data transformation, validation, API calls, state.
+
+### Barrel Exports for Public APIs
+
+Every feature module exposes its public API through `index.ts`.
+
+For full architecture patterns: see `references/angular-patterns.md`
+
+## Naming Conventions
+
+| Rule | Good | Bad |
+|---|---|---|
+| No Hungarian notation | `userName` | `strUserName` |
+| Observable$ suffix | `users$` | `users: Observable<T>` |
+| No I prefix on interfaces | `UserProfile` | `IUserProfile` |
+| Named constants | `MAX_PAGE_SIZE = 20` | `if (x >= 20)` |
+| Descriptive test names | `'should show error when invalid'` | `'test error'` |
+
+## Error Handling
+
+| Rule | Pattern |
+|---|---|
+| No empty catch blocks | Always log and handle: `catch (error: unknown) { this.logger.error(...) }` |
+| Typed errors | `catch (error: unknown)` then narrow with `instanceof` |
+| No console.log | Use the team's `LoggerService` |
+| switchMap needs catchError | Every `switchMap` must have a `catchError` inside the inner observable |
+
+For full error handling patterns: see `references/angular-patterns.md`
+
+## RxJS Patterns
+
+| Rule | Preferred | Avoid |
+|---|---|---|
+| Async style | `async/await` | `.then()` chains |
+| Cleanup | `takeUntilDestroyed()` or `async` pipe | Bare `.subscribe()` without cleanup |
+| Error in switchMap | `switchMap(x => obs.pipe(catchError(...)))` | `switchMap(x => obs)` without error handling |
+
+For full reactive patterns: see `references/rxjs-patterns.md`
+
+## Playwright Test Patterns
+
+| Rule | Pattern |
+|---|---|
+| Page Object required | All selectors in PO classes, never raw selectors in test files |
+| Web-first assertions | `await expect(locator).toBeVisible()` — no `waitForTimeout` |
+| User-facing locators | `getByRole`, `getByLabel`, `getByText` preferred over CSS |
+| Test data from fixtures | `TestDataBuilder.createUser()` — no hard-coded credentials |
+
+For full Playwright and Page Object patterns: see `references/playwright-patterns.md`
+
+## Security
+
+- **No `innerHTML`** — use Angular template binding `[innerHTML]` with `DomSanitizer`
+- **No `console.log`** — use LoggerService
+- **No hard-coded secrets** — use environment config
+
+## GREEN Phase Discipline
+
+While applying the patterns above, remember:
+
+1. Write ONLY enough code to make the current failing test pass
+2. If you need a service, create a minimal one — just the method the test requires
+3. Hard-coding is acceptable if it makes the test pass
+4. Do NOT add methods no test calls
+5. Do NOT implement edge cases no test covers
+6. Do NOT optimize — REFACTOR handles that
+7. After each green: run ALL tests to check for side effects
+8. Commit: `🟢 GREEN: Make [test name] pass with minimal code`
+
+## Integration
+
+```
+atdd-workflow    →  governs the RED-GREEN-REFACTOR cycle
+                     ↓ (during GREEN and REFACTOR)
+green-implementation (this skill)  →  team conventions and patterns
+                     ↓ (during REFACTOR)
+clean-code       →  SOLID principles and design patterns
+```
+
+During GREEN: follow this skill's patterns. Consult clean-code only if
+a SOLID violation blocks the next test cycle.
+
+During REFACTOR: use clean-code's decision tree for design improvements.
+Keep this skill's conventions intact — refactoring should not introduce
+pattern violations.
+
+## Keeping This Skill Current
+
+After every PR rejection:
+1. Record feedback in the MCP server (`record_pr_feedback`)
+2. Add automated rule if possible (`add_rule` in team-standards.json)
+3. Add the same pattern here with ✅/❌ examples
+4. If a violation type appears 3+ times, the section isn't clear — strengthen it
+
+This skill and `team-standards.json` stay in sync. Every rule in the JSON
+has a corresponding pattern here. The skill prevents; the MCP server catches.

package/green-implementation/references/angular-patterns.md

@@ -0,0 +1,239 @@
+# Angular Implementation Patterns
+
+## Component Architecture
+
+### Smart vs Presentational Components
+
+**Smart (container) components:**
+- Inject services
+- Manage state and side effects
+- Pass data down via `@Input()`
+- React to events via `@Output()`
+
+**Presentational (dumb) components:**
+- Receive data via `@Input()` only
+- Emit events via `@Output()` only
+- No injected services (except simple utilities)
+- Pure rendering — given the same inputs, same output
+
+```typescript
+// ✅ Smart component — owns the data
+@Component({
+  selector: 'app-user-list-container',
+  template: `<app-user-list [users]="users$ | async" (select)="onSelect($event)" />`,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserListContainerComponent {
+  users$ = this.userService.getUsers();
+  constructor(private userService: UserService) {}
+  onSelect(user: User) { this.router.navigate(['/users', user.id]); }
+}
+
+// ✅ Presentational component — renders what it's given
+@Component({
+  selector: 'app-user-list',
+  template: `
+    <ul>
+      <li *ngFor="let user of users; trackBy: trackById" (click)="select.emit(user)">
+        {{ user.name }}
+      </li>
+    </ul>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserListComponent {
+  @Input() users: User[] = [];
+  @Output() select = new EventEmitter<User>();
+  trackById = (_: number, user: User) => user.id;
+}
+```
+
+### Service Layer Pattern
+
+Services own all business logic and HTTP communication.
+Components never import `HttpClient`.
+
+```typescript
+// ✅ Service — owns HTTP and business logic
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private readonly apiUrl = '/api/users';
+
+  constructor(
+    private http: HttpClient,
+    private logger: LoggerService
+  ) {}
+
+  getUsers(): Observable<User[]> {
+    return this.http.get<User[]>(this.apiUrl).pipe(
+      catchError(error => {
+        this.logger.error('Failed to load users', { error });
+        return of([]);
+      })
+    );
+  }
+
+  getUserById(id: string): Observable<User> {
+    return this.http.get<User>(`${this.apiUrl}/${id}`).pipe(
+      catchError(error => {
+        this.logger.error('Failed to load user', { id, error });
+        throw error;
+      })
+    );
+  }
+}
+```
+
+### Barrel Exports
+
+Every feature directory has an `index.ts` that exports the public API.
+Internal implementation files are not exported.
+
+```typescript
+// src/app/users/index.ts
+export { UserListContainerComponent } from './user-list-container.component';
+export { UserService } from './user.service';
+export { User, UserRole, CreateUserRequest } from './user.model';
+// Do NOT export internal components, helpers, or private types
+```
+
+## Error Handling Patterns
+
+### HTTP Error Handling in Services
+
+```typescript
+// ✅ Typed error handling with logging
+saveUser(user: CreateUserRequest): Observable<User> {
+  return this.http.post<User>(this.apiUrl, user).pipe(
+    catchError((error: unknown) => {
+      if (error instanceof HttpErrorResponse) {
+        switch (error.status) {
+          case 409:
+            this.logger.warn('User already exists', { email: user.email });
+            throw new UserAlreadyExistsError(user.email);
+          case 422:
+            this.logger.warn('Validation failed', { errors: error.error });
+            throw new ValidationError(error.error.errors);
+          default:
+            this.logger.error('Unexpected error saving user', { error });
+            throw new UnexpectedError('Failed to save user');
+        }
+      }
+      throw error;
+    })
+  );
+}
+```
+
+### Component Error Display
+
+```typescript
+// ✅ Component handles error state from service
+@Component({
+  template: `
+    <app-error-banner *ngIf="error" [message]="error" />
+    <app-user-list *ngIf="users$ | async as users" [users]="users" />
+    <app-loading-spinner *ngIf="loading$ | async" />
+  `,
+})
+export class UserListContainerComponent {
+  error: string | null = null;
+
+  users$ = this.userService.getUsers().pipe(
+    catchError(error => {
+      this.error = error.message;
+      return of([]);
+    })
+  );
+}
+```
+
+### Custom Error Types
+
+```typescript
+// ✅ Domain-specific error classes
+export class UserAlreadyExistsError extends Error {
+  constructor(public email: string) {
+    super(`User with email ${email} already exists`);
+    this.name = 'UserAlreadyExistsError';
+  }
+}
+
+export class ValidationError extends Error {
+  constructor(public errors: Record<string, string[]>) {
+    super('Validation failed');
+    this.name = 'ValidationError';
+  }
+}
+```
+
+## Subscription Management
+
+### Preferred: async Pipe
+
+```typescript
+// ✅ Best — Angular handles subscription lifecycle
+@Component({
+  template: `
+    <div *ngIf="user$ | async as user">
+      <h1>{{ user.name }}</h1>
+    </div>
+  `,
+})
+export class UserDetailComponent {
+  user$ = this.route.params.pipe(
+    switchMap(params => this.userService.getUserById(params['id']))
+  );
+}
+```
+
+### When You Need the Value in Code: takeUntilDestroyed
+
+```typescript
+// ✅ Angular 16+ — automatic cleanup
+@Component({ ... })
+export class DashboardComponent implements OnInit {
+  private destroyRef = inject(DestroyRef);
+  metrics: DashboardMetrics | null = null;
+
+  ngOnInit() {
+    this.metricsService.getMetrics().pipe(
+      takeUntilDestroyed(this.destroyRef)
+    ).subscribe(metrics => {
+      this.metrics = metrics;
+      this.updateChart(metrics);
+    });
+  }
+}
+```
+
+### Never: Bare subscribe Without Cleanup
+
+```typescript
+// ❌ Memory leak — no cleanup mechanism
+ngOnInit() {
+  this.userService.getUsers().subscribe(users => this.users = users);
+}
+```
+
+## File Organization
+
+```
+src/app/
+├── users/                        # Feature directory
+│   ├── index.ts                  # Barrel exports (public API)
+│   ├── user-list-container.component.ts  # Smart component
+│   ├── user-list.component.ts    # Presentational component
+│   ├── user-detail.component.ts
+│   ├── user.service.ts           # HTTP + business logic
+│   ├── user.model.ts             # Interfaces, types, enums
+│   └── user.errors.ts            # Domain error classes
+├── shared/                       # Cross-feature utilities
+│   ├── index.ts
+│   ├── logger.service.ts
+│   └── error-banner.component.ts
+└── core/                         # App-wide singletons
+    ├── index.ts
+    ├── auth.service.ts
+    └── http-error.interceptor.ts
+```