@synapta/skills 0.1.0 → 0.1.2

package/skills/architecture-selector/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: architecture-selector
+description: Choose the simplest architecture that satisfies a captured ArchitectureBrief. Default to a modular monolith with Twelve-Factor practices; justify distributed services only when the brief surfaces concrete constraints (tenancy isolation, geo latency, independent deploy cadence, regulatory).
+triggers: [synapta architecture, architecture selection, monolith vs microservices, stack architecture, system design]
+network: off
+tools: [Read, Write, Glob]
+source:
+  origin: authored-by-synapta
+  reason: "No community SKILL.md found that acts as a true multi-axis architecture selector (existing skills are framework advocates, not selectors)."
+  citation_patterns:
+    - "Twelve-Factor App (https://12factor.net)"
+    - "AWS Well-Architected (https://aws.amazon.com/architecture/well-architected/)"
+    - "Monolith First — Martin Fowler (https://martinfowler.com/bliki/MonolithFirst.html)"
+    - "Choose Boring Technology — Dan McKinley (https://boringtechnology.club)"
+---
+
+# Architecture Selector
+
+Read the `ArchitectureBrief` artifact and produce an `ArchitectureDoc` + ADRs. Pick the simplest architecture that satisfies the brief's hard constraints. Be ruthless about ruling out complexity.
+
+## Default architecture
+
+**Modular monolith + Twelve-Factor**, deployed to a single platform target (Vercel / Fly / Railway / Cloudflare / Docker / K8s / SSH — see deployment adapters).
+
+This is the default unless the brief surfaces ≥1 of:
+- **Tenancy isolation requirement** (regulated multi-tenant data; hardware isolation needed)
+- **Geo latency budget** below ~150ms p95 to multiple regions simultaneously
+- **Independent deploy cadence** across teams that can't share a release train
+- **Regulatory boundary** that requires physical separation (e.g. FedRAMP High zones, HIPAA isolation)
+- **Scale break**: existing component throughput is >1 OOM beyond what a monolith can serve, *measured*, not projected
+
+If none of the above appear in the brief, the answer is the modular monolith.
+
+## Process
+
+1. **Read the brief**. Extract scale (concurrent users, peak load, growth curve), latency targets, tenancy, compliance, data sensitivity, integrations, offline, team size, release cadence, uptime target, geo.
+2. **Run the decision matrix**:
+
+   | Axis | Monolith | Distributed |
+   |---|---|---|
+   | Team size | ≤ ~15 engineers | independent teams that must deploy without coordination |
+   | Tenancy | single + multi shared-DB | hard isolation / per-tenant infra |
+   | Geo | one region or CDN-edge for read | multi-region writes |
+   | Compliance | most SOC2 / PCI / GDPR | FedRAMP High, HIPAA isolation, data sovereignty across regions |
+   | Scale | up to multi-million users with vertical + horizontal slicing | proven bottleneck beyond monolith ceiling |
+
+3. **Pick the simplest** that satisfies every hard constraint.
+4. **Write one ADR per decision** under `docs/architecture/`. Each ADR has **Context**, **Decision**, **Consequences**.
+5. **Output**: `ArchitectureDoc` (overview + module boundaries + data flow) plus ADR set.
+
+## Decision quality bar
+
+An ADR is acceptable when:
+- The Decision references a concrete constraint from the brief, not aspiration
+- The Consequences include the operational cost (people, dollars, complexity) of the chosen approach
+- The rejected alternative is named, with the reason it was ruled out
+
+## Anti-patterns to refuse without explicit justification
+
+- Microservices for <10 engineers
+- Event-sourcing for CRUD apps
+- Custom auth instead of an IdP
+- Eventual consistency where strong was sufficient
+- Bleeding-edge framework major versions in production

package/skills/backlog-planner/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: backlog-planner
+synapta_original_name: breakdown-epic-pm
+description: 'Prompt for creating an Epic Product Requirements Document (PRD) for a new epic. This PRD will be used as input for generating a technical architecture specification.'
+triggers: [synapta backlog, epic breakdown, PRD, INVEST stories, acceptance criteria]
+network: off
+source:
+  origin: https://github.com/github/awesome-copilot
+  path: plugins/project-planning/skills/breakdown-epic-pm
+  commit: 4e4b34c48d3f
+  license: MIT (GitHub, Inc.)
+  adapted: light-touch
+  related: "Sibling skills in awesome-copilot/plugins/project-planning: breakdown-feature-prd, breakdown-feature-implementation, breakdown-epic-arch, create-implementation-plan, update-implementation-plan, create-technical-spike. Consider as a project-planning sub-pack in v0.1+."
+---
+
+# Epic Product Requirements Document (PRD) Prompt
+
+## Goal
+
+Act as an expert Product Manager for a large-scale SaaS platform. Your primary responsibility is to translate high-level ideas into detailed Epic-level Product Requirements Documents (PRDs). These PRDs will serve as the single source of truth for the engineering team and will be used to generate a comprehensive technical architecture specification for the epic.
+
+Review the user's request for a new epic and generate a thorough PRD. If you don't have enough information, ask clarifying questions to ensure all aspects of the epic are well-defined.
+
+## Output Format
+
+The output should be a complete Epic PRD in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/epic.md`.
+
+### PRD Structure
+
+#### 1. Epic Name
+
+- A clear, concise, and descriptive name for the epic.
+
+#### 2. Goal
+
+- **Problem:** Describe the user problem or business need this epic addresses (3-5 sentences).
+- **Solution:** Explain how this epic solves the problem at a high level.
+- **Impact:** What are the expected outcomes or metrics to be improved (e.g., user engagement, conversion rate, revenue)?
+
+#### 3. User Personas
+
+- Describe the target user(s) for this epic.
+
+#### 4. High-Level User Journeys
+
+- Describe the key user journeys and workflows enabled by this epic.
+
+#### 5. Business Requirements
+
+- **Functional Requirements:** A detailed, bulleted list of what the epic must deliver from a business perspective.
+- **Non-Functional Requirements:** A bulleted list of constraints and quality attributes (e.g., performance, security, accessibility, data privacy).
+
+#### 6. Success Metrics
+
+- Key Performance Indicators (KPIs) to measure the success of the epic.
+
+#### 7. Out of Scope
+
+- Clearly list what is _not_ included in this epic to avoid scope creep.
+
+#### 8. Business Value
+
+- Estimate the business value (e.g., High, Medium, Low) with a brief justification.
+
+## Context Template
+
+- **Epic Idea:** [A high-level description of the epic from the user]
+- **Target Users:** [Optional: Any initial thoughts on who this is for]

package/skills/carplay-entitlement-checker/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: carplay-entitlement-checker
+description: Verify CarPlay entitlement at build + runtime. If Apple has not granted the entitlement, disable Track B (native CarPlay) cleanly; Track A (companion app + widgets + Live Activities) continues unchanged.
+triggers: [synapta carplay check, CarPlay entitlement, Track B gate]
+network: off
+tools: [Read, Bash]
+source:
+  origin: authored-by-synapta
+  reason: "Synapta-specific gate for CarPlay entitlement risk (Apple denies most third-party CarPlay apps)."
+  citation_patterns:
+    - "Apple CarPlay Programming Guide"
+    - "Apple Developer — Requesting CarPlay entitlements"
+---
+
+# CarPlay Entitlement Checker
+
+Apple controls CarPlay entitlements tightly. Most third-party apps are denied. Synapta assumes denial and builds Track A as the real product; Track B (native CarPlay) is a compile-gated bonus.
+
+## Build-time check
+
+`scripts/check-carplay-entitlement.sh` (run by `ios.yml` CI workflow):
+
+```sh
+#!/usr/bin/env bash
+set -euo pipefail
+ENTITLEMENTS_FILE="apps/ios-synapta-drive/Synapta.entitlements"
+EXPECTED_KEY="com.apple.developer.carplay-charging"  # or whichever category Synapta requests
+if grep -q "$EXPECTED_KEY" "$ENTITLEMENTS_FILE"; then
+  echo "CarPlay entitlement present in $ENTITLEMENTS_FILE"
+  echo "carplay=enabled" >> "$GITHUB_OUTPUT"
+else
+  echo "CarPlay entitlement NOT present — Track B disabled"
+  echo "carplay=disabled" >> "$GITHUB_OUTPUT"
+fi
+```
+
+When disabled, the xcodebuild step uses the default scheme that excludes the CarPlay target.
+
+## Compile-time gate
+
+All CarPlay code lives behind `#if SYNAPTA_CARPLAY`:
+
+```swift
+#if SYNAPTA_CARPLAY
+import CarPlay
+
+class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDelegate {
+  // ...
+}
+#endif
+```
+
+The build flag is set only when the entitlement check passes AND the scheme is the CarPlay-enabled variant.
+
+## Runtime check
+
+Even when compiled in, verify the entitlement at runtime before activating CarPlay UI:
+
+```swift
+func hasCarPlayEntitlement() -> Bool {
+  guard let entitlements = Bundle.main.object(forInfoDictionaryKey: "com.apple.developer.carplay-charging") else {
+    return false
+  }
+  return entitlements is Bool ? (entitlements as! Bool) : true
+}
+```
+
+If false at runtime, the app behaves as if Track A only: no CarPlay scene delegate registered.
+
+## Submission guidance
+
+When submitting to App Review with CarPlay:
+1. Choose the correct **category** (`charging`, `navigation`, `parking`, etc.). Synapta is uncategorized in Apple's list, so submission may require an exception request.
+2. Document Track A as the default user experience.
+3. Disclose the audit log + signed-approval architecture.
+4. Expect entitlement denial. Plan submission with Track A only as the safe baseline.
+
+## Anti-patterns
+
+- Shipping a non-entitled binary that contains CarPlay symbols — risks rejection for unused entitlements
+- Hardcoding `hasCarPlayEntitlement = true` for testing — leave the runtime gate intact
+- Marketing the app as "CarPlay app" before entitlement is granted