@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

package/pipeline/skills/figma-common/figma-commit/COMMON_REBASE.md

@@ -1,206 +0,0 @@
-# Common Submodule  -  Rebase, Resolve, Validate & Push
-
-Handles `{project.slug}-common` branch creation, conflict resolution, regeneration, validation, and PR flow.
-
-Called from `/figma-commit` SKILL.md after code review passes.
-
----
-
-## Inputs (from parent skill)
-
-| Variable | Source |
-|----------|--------|
-| `REPO_ROOT` | git repo root |
-| `COMMON_PATH` | `${REPO_ROOT}/{repos.common.path}` |
-| `BRANCH_NAME` | `feature/${JIRA_ISSUE}-${COMPONENT_KEBAB}-implementation` |
-| `JIRA_ISSUE` | Jira ticket |
-| `COMPONENT_PASCAL` | Component name |
-
----
-
-## STEP 1  -  Stash
-
-```bash
-cd "${COMMON_PATH}"
-git stash push -u -m "figma-commit: ${COMPONENT_PASCAL} pre-branch stash"
-```
-
-Skip if `git status --porcelain` is empty.
-
-## STEP 2  -  Fetch & Branch from develop
-
-```bash
-cd "${COMMON_PATH}"
-git fetch origin develop
-git checkout develop
-git pull origin develop
-git checkout -b "${BRANCH_NAME}"
-```
-
-If branch already exists → append `-v2`, `-v3`, etc.
-
-## STEP 3  -  Pop Stash
-
-```bash
-cd "${COMMON_PATH}"
-git stash pop
-```
-
-If pop succeeds cleanly → skip to STEP 5.
-If pop fails with conflicts → proceed to STEP 4.
-
-## STEP 4  -  Conflict Resolution
-
-### 4A  -  Classify conflicted files
-
-| File Pattern | Strategy |
-|-------------|----------|
-| `iOS/Sources/*/Generated/*` | Accept either side (will regenerate) |
-| `Shared/Figma/Generated/*` | Accept either side (gitignored, will regenerate) |
-| `iOS/Sources/LocalizationAssets/Resources/*.xcstrings` | Accept either side (will regenerate) |
-| `iOS/Sources/AccessibilityAssets/Resources/*.xcstrings` | Accept either side (will regenerate) |
-| `Shared/Localization/*/Metadata/*` | Accept either side (gitignored, will regenerate) |
-| `Shared/UITestingIdentifiers/Metadata/*` | Accept either side (gitignored, will regenerate) |
-| `Sources/Suggested/*.json` | Our version wins (per-key files, we created them) |
-| Source JSONs (see below) | **Union merge** |
-| `Shared/Figma/Components/*.json` | Our version wins (we created/modified it) |
-
-### 4B  -  Union merge for source JSONs
-
-For each conflicted source JSON:
-
-```
-a. Accept OURS (develop) version: git checkout --ours <file> && git add <file>
-b. Manually insert only the NEW keys from the branch (use Edit tool, match existing format exactly)
-c. NEVER use Python json.dump or any JSON serializer  -  it reformats the entire file
-d. After manual edits, normalize with the Swift tool:
-   .build/debug/UITestingIdentifierTool format
-e. Verify: key count >= develop's count  -  no key lost
-```
-
-**Source files requiring union merge:**
-
-| File | Resolution | Format Tool |
-|------|-----------|-------------|
-| `Shared/UITestingIdentifiers/ui-testing-identifiers.json` | Accept ours + insert new keys | `UITestingIdentifierTool format` |
-| `Shared/UIAssets/Colors/*.json` | Accept ours + insert new entries | (manual  -  match existing format) |
-
-**Files that NO LONGER need union merge** (per-key files or gitignored):
-- `*-data-suggested.json` → replaced by `Sources/Suggested/*.json` (per-key files, never conflict)
-- `*-data-merged.json` → gitignored (derived artifact, regenerated in section5)
-- `*-metadata.json` → gitignored (derived artifact, regenerated in section5)
-- `Metadata/identifier-keys.json` → gitignored (derived artifact, regenerated in section5)
-
-### 4C  -  Text file union merge
-
-**No longer needed.** `localization-keys.txt` and `accessibility-keys.txt` are gitignored (regenerated in section5).
-
-### 4D  -  Verify no conflict markers remain
-
-```bash
-grep -r "<<<<<<" . --include="*.json" --include="*.swift" --include="*.txt" | head -5
-```
-
-## STEP 5  -  Rebuild Derived Artifacts
-
-All derived artifacts (merged data, metadata, keys.txt, registries, catalogs) are gitignored. Always rebuild them after conflict resolution to guarantee fresh data.
-
-```bash
-bash "${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh"
-```
-
-This script rebuilds everything: merge translations from per-key `Sources/Suggested/` files, regenerate metadata, keys indexes, UI assets, token registries, and Figma catalogs.
-
-If the script fails → source JSON likely has invalid syntax from merge. Fix and retry.
-
-## STEP 6  -  Validate Integrity
-
-Always fetch develop first so the non-destruction check compares against the latest:
-
-```bash
-cd "${COMMON_PATH}"
-git fetch origin develop
-
-python3 "${REPO_ROOT}/.instructions/figma/figma-commit/validate-localization-sync.py" \
-    --common-path "${COMMON_PATH}"
-```
-
-**Must exit 0.** Validates:
-1. Suggested covers merged  -  every merged key has a corresponding per-key file in `Sources/Suggested/`
-2. All 8 languages present per key  -  no missing translations
-3. No empty suggested values
-4. keys.txt and metadata in sync with merged
-5. Key count non-decreasing vs develop
-6. Non-destruction  -  no key removed vs develop
-7. Testing identifiers JSON ↔ keys JSON match
-
-If validation fails → fix before committing. Common fixes:
-- **Keys in merged not in suggested**: Add missing per-key file via `TranslationManagerTool add`
-- **Key count decreased**: Key lost during merge  -  find and restore the per-key file
-- **Empty values**: Translation added without content  -  provide it
-- **Non-destruction violation**: Intentional rename → re-add old key as alias
-
-## STEP 7  -  Commit
-
-```bash
-cd "${COMMON_PATH}"
-git add -A
-git commit -m "$(cat <<'EOF'
-feat(common): [${JIRA_ISSUE}] add ${COMPONENT_PASCAL} tokens and keys
-
-- Add testing identifiers, localization, and accessibility keys
-- Add design tokens and component registry entry
-- Regenerate all platform code and catalogs
-
-Refs: ${JIRA_ISSUE}
-EOF
-)"
-```
-
-## STEP 8  -  Push
-
-```bash
-cd "${COMMON_PATH}"
-git push -u origin "${BRANCH_NAME}"
-```
-
-## STEP 9  -  Create PR (do NOT merge)
-
-```bash
-cd "${COMMON_PATH}"
-gh pr create --base develop \
-    --title "feat(common): [${JIRA_ISSUE}] add ${COMPONENT_PASCAL} tokens" \
-    --body "$(cat <<'EOF'
-## Summary
-- Add testing identifiers, localization, and accessibility keys
-- Add design tokens and component registry entry
-- Regenerate all platform code and catalogs
-
-## Visual Reference
-- **Figma:** ${FIGMA_URL}
-- **Confluence iOS:** ${CONFLUENCE_IOS_URL}
-
-## Validation
-- [ ] validate-localization-sync.py passes
-- [ ] No key count decrease vs develop
-- [ ] All 8 languages present
-
-Refs: ${JIRA_ISSUE}
-EOF
-)"
-```
-
-**Do NOT merge**  -  PR is created for review. Merging is a separate manual action.
-
----
-
-## Error Handling
-
-- **Stash conflict on pop**: Follow section4 conflict resolution
-- **Branch already exists**: Append `-v2`, `-v3`
-- **Push rejected**: Report error, do NOT force-push
-- **Not on develop**: Warn user, ask confirmation
-- **Rebuild script fails**: Source JSON likely invalid from merge  -  fix and retry
-- **Validation fails**: Fix before committing  -  NEVER skip validation
-- **Key count decreased**: STOP  -  per-key file was lost, check `Sources/Suggested/` for missing files
-- **Same-key conflict in union merge**: Ask user which version to keep  -  do NOT silently overwrite (only applies to UIAssets Colors and UITestingIdentifiers now)

package/pipeline/skills/figma-common/figma-commit/REVIEW.md

@@ -1,337 +0,0 @@
-# Figma Component Code Review
-
-Pre-commit review checklist for components implemented via the `/figma` workflow.
-Run this review after all phases complete, before committing.
-
-**Input:** Component name and source location from `IMPLEMENTATION_HISTORY.md`.
-
----
-
-## How To Use
-
-```
-Review the {ComponentName} component at {componentLocation} using the checklist in .instructions/figma/figma-commit/REVIEW.md
-```
-
----
-
-## 1. File Completeness
-
-Verify all expected files exist at `{componentLocation}/`:
-
-| File | Required | Condition |
-|------|----------|-----------|
-| `{ComponentName}.swift` | Always | Main View |
-| `{ComponentName}Configuration.swift` | COMPLEX only | Configuration struct |
-| `{ComponentName}+Modifiers.swift` | COMPLEX only | View-level chain modifiers |
-| `{ComponentName}.figma.swift` | Always | Code Connect |
-| `FIGMA.md` | Always | Component documentation |
-
-Verify test files exist:
-
-| File | Required | Location |
-|------|----------|----------|
-| `{ComponentName}ViewInspectorTests.swift` | Always | `Tests/UIComponentsTests/ViewInspector/Components/.../` |
-| `{ComponentName}SnapshotTests.swift` | Always | `Tests/UIComponentsTests/Snapshot/Components/.../` |
-| Snapshot reference images | Never committed | `__Snapshots__/` is gitignored  -  generated on-demand via `record: .missing` |
-
-**FAIL if:** ViewInspector or Snapshot test file is missing. **FAIL if:** `__Snapshots__/` directory is tracked by git (should be gitignored).
-
----
-
-## 2. No Magic Numbers
-
-Scan ALL production Swift files (NOT test files) for hardcoded values.
-
-### 2.1 Dimensions  -  Must Use Tokens or Named Constants
-
-Every numeric `CGFloat` in production code must come from a design token OR a named constant in a `private enum Constants`. Component-specific sizes that don't map to an existing design token (e.g., icon sizes from Figma specs) are valid in `Constants`:
-
-| Bad (magic number) | Good (token) |
-|--------------------|--------------|
-| `frame(height: 56)` | `frame(minHeight: .Size.size56)` |
-| `padding(20)` | `padding(.horizontal, .Spacing.spacing20)` |
-| `cornerRadius(8)` | `cornerRadius: .Radius.radius8` |
-| `lineWidth: 1` | `lineWidth: .BorderWidth.borderWidth1` |
-| `spacing: 4` | `spacing: .Spacing.spacing4` |
-| `width: 24, height: 24` | `width: .Size.size24, height: .Size.size24` |
-
-**How to check:**
-```
-Grep for raw numeric CGFloat values in {ComponentName}.swift and {ComponentName}+Modifiers.swift:
-- Pattern: \b\d+\.?\d*\b in frame/padding/spacing/cornerRadius/lineWidth/width/height contexts
-- Exclude: 0, 1 (only if used as multiplier/boolean, NOT as dimension)
-- Exclude: .infinity (SwiftUI constant)
-- Exclude: Values referenced via Constants.propertyName (named constants are NOT magic numbers)
-```
-
-**FAIL if:** Any raw inline dimension value found (e.g., `frame(height: 56)`). Named constants in `Constants` enum are PASS.
-
-### 2.2 Colors  -  Must Use Semantic Tokens
-
-Prefer design tokens. No `Color(red:green:blue:)`, no `UIColor` literals, no SwiftUI named colors (`.red`, `.white`).
-
-| Bad | Good |
-|-----|------|
-| `Color(red: 0.9, green: 0, blue: 0)` | `Color.Primary.primary` |
-| `Color.red` | `Color.Primary.primary` |
-| `Color.white` | `Color.Text.textWhite` or `Color.Button.buttonPrimaryWhite` |
-| `Color.clear` | `Color.clear` is ALLOWED (SwiftUI built-in, not a design token gap) |
-
-When a color has no matching design token and must be hardcoded in `Constants`, use the `Color(hex:)` initializer from UIExtensions (NOT `Color(red:green:blue:)`):
-
-| Bad (raw RGB) | Good (hex constant) |
-|---------------|---------------------|
-| `Color(red: 0.9, green: 0, blue: 0)` | `Color(hex: "#E50914")` |
-| `Color(.sRGB, red: 0.15, green: 0.68, blue: 0.38)` | `Color(hex: "#25AD61")` |
-
-**FAIL if:** `Color(red:green:blue:)`, `Color(.sRGB, ...)`, or SwiftUI named colors (`.red`, `.blue`, `.white`, etc.) found in production code.
-
-### 2.3 Typography  -  Must Use TypographyStyle
-
-No raw `.font()` calls. All text styling via `.typographyStyle()`.
-
-| Bad | Good |
-|-----|------|
-| `.font(.system(size: 18, weight: .bold))` | `.typographyStyle(.h6)` |
-| `.font(.headline)` | `.typographyStyle(.bodyBold)` |
-
-**FAIL if:** Any `.font()` call found in production code.
-
-### 2.4 Allowed Exceptions
-
-These raw values are acceptable and should NOT be flagged:
-
-- `0` as zero padding/offset
-- `.infinity` in `frame(maxWidth: .infinity)`
-- Named constants in `private enum Constants`  -  these are NOT magic numbers
-- Numeric values in test files (snapshot frame sizes, assertion values)
-- Numeric values in `#Preview` section labels (e.g., section divider count)
-- Opacity values (`0.0` to `1.0`)  -  no token system for opacity
-- `lineLimit(1)`  -  SwiftUI view modifier, not a dimension
-
----
-
-## 3. Configuration Purity (COMPLEX only)
-
-Read `{ComponentName}Configuration.swift` and verify:
-
-| Rule | Check |
-|------|-------|
-| No closures | No `() -> Void`, `(T) -> Void`, `@escaping` in Configuration properties |
-| No bindings | No `Binding<T>`, `@Binding` in Configuration properties |
-| No state | No `@State`, `@ObservedObject`, `@StateObject`, `@EnvironmentObject` |
-| No view builders | No `AnyView`, `@ViewBuilder`, `some View` as properties |
-| Value types only | All properties should be `let` with value/enum/optional types |
-| `@GenerateChainModifiers` | Macro is applied to the struct |
-| `Sendable` conformance | Struct conforms to `Sendable` |
-
-**FAIL if:** Any non-value-type property found in Configuration.
-
----
-
-## 4. +Modifiers Correctness (COMPLEX only)
-
-Read `{ComponentName}+Modifiers.swift` and verify:
-
-| Rule | Check |
-|------|-------|
-| One method per Configuration property | Count matches (excluding `@IgnoreChainModifier` properties) |
-| Localized overloads for String props | `func title(localized value: LocalizationStringKey)` exists for each String property |
-| Delegates to `configured { }` | Every method body is `configured { $0.propertyName(value) }` |
-| Return type is concrete | Returns `{ComponentName}`, not `Self` or `some View` |
-| Correct nested type paths | Enum parameters use `{ComponentName}Configuration.EnumType` |
-| `import CoreLocalization` | Present if any localized overload exists |
-
-**FAIL if:** Method count mismatch or incorrect delegation pattern.
-
----
-
-## 5. Accessibility
-
-Read `{ComponentName}.swift` and verify:
-
-| Rule | Check |
-|------|-------|
-| Interactive elements have identifiers | `.accessibilityIdentifier(.{ComponentName}.elementName)` on buttons, taps |
-| Uses type-safe keys | `.accessibilityIdentifier(.ComponentName.key)` NOT `.accessibilityIdentifier("raw_string")` |
-| Container combining | `.accessibilityElement(children: .combine)` on composite interactive elements |
-| Icons are decorative | `.accessibilityHidden(true)` on decorative icons within labeled buttons |
-| No redundant labels | Don't add `.accessibilityLabel` if SwiftUI `Button` + `Text` already provides it |
-
-**FAIL if:** Interactive elements lack identifiers, or raw strings used instead of type-safe keys.
-
----
-
-## 6. Analytics
-
-Read `{ComponentName}.swift` and verify:
-
-| Rule | Check |
-|------|-------|
-| Tappable elements tracked | `.analyticsButton(id:label:type:)` on buttons |
-| ID uses testing identifier | `id: UITestingIdentifierKey.{ComponentName}.element.identifier` |
-| Type mapping correct | Style/variant maps to correct `ButtonType` (primary/secondary/ghost/tertiary) |
-| No duplicate tracking | One analytics modifier per user action, not per sub-view |
-
-**WARN if:** Missing analytics on tappable elements. Not always a hard fail (some components are purely presentational).
-
----
-
-## 7. Testing Identifiers
-
-Verify the identifier pipeline is complete:
-
-| Step | Check |
-|------|-------|
-| Registered | `UITestingIdentifierTool check --key '{ComponentName}.element'` returns `✅ Key exists` for all identifiers |
-| Generated keys | `UITestingIdentifierKeys.swift` has `enum {ComponentName}` with static keys |
-| View usage | `{ComponentName}.swift` uses `.accessibilityIdentifier(.{ComponentName}.key)` |
-| Test assertions | ViewInspector tests assert identifier presence |
-
-**FAIL if:** Any step in the pipeline is missing or inconsistent.
-
----
-
-## 8. Preview Quality
-
-Read the Preview section at the bottom of `{ComponentName}.swift`:
-
-| Rule | Check |
-|------|-------|
-| LTR preview exists | `{ComponentName}Preview: View` struct + `#Preview` |
-| RTL preview exists | `{ComponentName}RTLPreview: View` struct + `#Preview("RTL")` |
-| +Modifiers style | Uses `{ComponentName} { }.prop(val)` NOT `{ config in config.prop(val) }` |
-| All variants shown | Every enum `allCases` iterated via `ForEach` |
-| RTL has Arabic text | Localized text props use Arabic placeholders |
-| RTL environment set | `.environment(\.layoutDirection, .rightToLeft)` + `.environment(\.locale, Locale(identifier: "ar"))` |
-| Preview structs are plain | No macros on preview structs (workaround for `#Preview` + macro conflict) |
-| Disabled state shown | If component supports disabled, shown with `.disabled(true)` |
-
-**FAIL if:** Missing LTR or RTL preview, or using old configure-closure style.
-
----
-
-## 9. Code Connect
-
-Read `{ComponentName}.figma.swift`:
-
-| Rule | Check |
-|------|-------|
-| `import Figma` | Present |
-| Correct `figmaNodeUrl` | Contains correct fileKey and nodeId |
-| +Modifiers style | Body uses `.prop(val)` chain, NOT `{ config in ... }` |
-| All variant groups covered | Separate `FigmaConnect` struct per variant group |
-| `@FigmaEnum` uses shorthand | `.enumCase` NOT `Type.enumCase` |
-| `#Preview` at bottom | At least one preview for compile validation |
-
-**FAIL if:** Wrong node URL, missing variant coverage, or old closure style.
-
----
-
-## 10. View Implementation Quality
-
-Read `{ComponentName}.swift` (the View, excluding Preview section):
-
-| Rule | Check |
-|------|-------|
-| `@GenerateConfiguredInit` | Applied to the View struct |
-| `public struct` | View is public |
-| `public let configuration` | Configuration property is public let |
-| `@Environment(\.isEnabled)` | Used for disabled state (NOT a config boolean) |
-| No force unwraps | No `!` on optionals in production code |
-| No `print`/`debugPrint` | No debug logging in production code |
-| Correct MARK sections | `// MARK: - Properties`, `// MARK: - Body`, `// MARK: - Subviews`, `// MARK: - Computed Properties` |
-| `@ViewBuilder` on conditional views | Optional subviews use `@ViewBuilder` |
-| No unused imports | Every `import` is actually used |
-
-**FAIL if:** Missing macro annotation, force unwraps, or debug logging.
-
----
-
-## 11. FIGMA.md Documentation
-
-Read `{componentLocation}/FIGMA.md`:
-
-| Rule | Check |
-|------|-------|
-| Figma link present | Contains `https://www.figma.com/design/{fileKey}/?node-id={nodeId}` |
-| Variant mapping table | Maps Figma property values to Swift enum cases |
-| Usage example | Shows basic instantiation |
-| Code Connect section | Lists strategy and property mappings |
-
-**FAIL if:** Missing Figma link or variant mapping table.
-
----
-
-## 12. Build Verification
-
-```bash
-xcodebuild build -project {build.xcodeproj} -scheme {build.scheme} \
-    -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO -quiet
-```
-
-**FAIL if:** Build errors. Warnings on component files should be investigated.
-
----
-
-## 13. Test Verification
-
-```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
-bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" --filter "{ComponentName}ViewInspectorTests"
-bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" --filter "{ComponentName}SnapshotTests"
-```
-
-**FAIL if:** Any test fails or test count is zero.
-
----
-
-## Review Output Format
-
-```
-## Code Review: {ComponentName}
-
-### Status: PASS / FAIL / WARN
-
-### Checklist
-
-| # | Check | Status | Notes |
-|---|-------|--------|-------|
-| 1 | File completeness | PASS/FAIL | {missing files if any} |
-| 2 | No magic numbers | PASS/FAIL | {violations if any} |
-| 3 | Configuration purity | PASS/FAIL/N/A | {violations if any} |
-| 4 | +Modifiers correctness | PASS/FAIL/N/A | {violations if any} |
-| 5 | Accessibility | PASS/FAIL | {missing identifiers if any} |
-| 6 | Analytics | PASS/WARN | {missing tracking if any} |
-| 7 | Testing identifiers | PASS/FAIL | {pipeline gaps if any} |
-| 8 | Preview quality | PASS/FAIL | {issues if any} |
-| 9 | Code Connect | PASS/FAIL | {issues if any} |
-| 10 | View implementation | PASS/FAIL | {issues if any} |
-| 11 | FIGMA.md docs | PASS/FAIL | {issues if any} |
-| 12 | Build | PASS/FAIL | {errors if any} |
-| 13 | Tests | PASS/FAIL | {failures if any} |
-
-### Violations (if any)
-
-{Detailed list of each violation with file:line, what's wrong, and suggested fix}
-
-### Summary
-
-{One paragraph: overall assessment, blocking issues, suggestions}
-```
-
----
-
-## Severity Levels
-
-| Level | Meaning | Action |
-|-------|---------|--------|
-| **FAIL** | Blocking  -  must fix before commit | Fix all FAIL items |
-| **WARN** | Non-blocking  -  should fix but can commit | Document in PR description |
-| **PASS** | Compliant | No action needed |
-| **N/A** | Not applicable | SIMPLE components skip Configuration/+Modifiers checks |
-
-**Overall status:**
-- Any FAIL → overall FAIL (do not commit)
-- All PASS/WARN/N/A → overall PASS (safe to commit)