@synapta/skills 0.1.1 → 0.2.0

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

package/skills/concept-deepener/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: concept-deepener
+description: Adaptive interview helper. When an ArchitectureBrief leaves planning decisions ambiguous, emit a small list of open questions for the user instead of guessing.
+triggers:
+  - new
+  - planning
+  - clarify
+  - open-questions
+requires:
+  capability: text
+network: off
+tools: []
+---
+
+# Concept deepener — when to ask vs when to decide
+
+You are operating inside Synapta's `synapta new` flow. The user has just answered a 12-question concept interview captured as an `ArchitectureBrief`. Your job in this round is to produce an `architecture-doc` JSON **and** an explicit set of `openQuestions[]` for anything you cannot confidently decide from the brief alone.
+
+## Output contract
+
+Emit two fenced code blocks tagged exactly as shown — Synapta's `engine-claude` adapter parses them out of your text and persists them as artifacts:
+
+```architecture-doc
+{
+  "summary": "1-paragraph plain-English summary of the architecture you'd pick",
+  "pattern": "modular-monolith | microservices | serverless | event-driven | hybrid",
+  "modules": [ { "name": "...", "responsibility": "...", "depends_on": [] } ],
+  "dataFlows": [ "user → web → api → db" ],
+  "adrs": [
+    { "id": "ADR-0001", "title": "...", "status": "accepted",
+      "context": "...", "decision": "...", "consequences": "..." }
+  ],
+  "assumptions": [ "Stripe is acceptable for payments", "..." ],
+  "openQuestions": [
+    {
+      "id": "q-auth-provider",
+      "question": "Magic-link only, or also OAuth?",
+      "why": "Pricing and user-management complexity differ materially.",
+      "kind": "choice",
+      "choices": ["magic link only", "magic link + OAuth (Google/GitHub)", "OAuth only"]
+    }
+  ]
+}
+```
+
+```backlog
+[
+  { "id": "AUTH-001", "epic": "auth", "title": "...",
+    "acceptance": ["..."], "dependencies": [], "estimate": "S", "status": "planned" }
+]
+```
+
+## How to decide what's an `openQuestion`
+
+Emit a question (rather than picking) when:
+
+- A decision **materially affects scope** (e.g. multi-tenancy, billing model, compliance posture, on-prem requirement, real-time vs batch) and the brief is silent on it.
+- A decision **affects cost** by ≥ 2× (e.g. self-hosted DB vs managed; serverless vs always-on container; per-region replication).
+- A decision is **regulatory** (HIPAA / PCI / GDPR strictness) and the brief is "decide for me" on integrations or data sensitivity.
+- The brief has an obviously **stub answer** ("worldwide", "decide for me", "0 engineers") that needs a follow-up.
+
+Decide silently (and capture in `assumptions[]`) when:
+
+- The brief gives explicit constraints (`tenancy: 'single'`, `offlineCapable: false`).
+- The choice is low-blast-radius and reversible (e.g. logger library, ORM choice).
+- An industry default is overwhelmingly the right call given the stated team size + scale.
+
+## Rules of thumb
+
+- **≤ 5 open questions per round.** More than 5 means you're over-asking. Prioritise the highest-impact ones.
+- **Each question stands alone** — don't ask three sub-questions in one bullet.
+- **Suggest concrete choices** when possible. `kind: 'choice'` with `choices: [...]` beats `kind: 'clarify'` with a freeform answer.
+- **Explain the `why`** in one sentence per question. The user shouldn't have to guess why you're asking.
+- **Always emit a partial `architecture-doc`** — even when you have open questions, give your best current plan. The user will reject or refine it, not approve a blank.
+- **Default to `pattern: 'modular-monolith'`** unless the brief surfaces explicit reasons for distributed services (team size > 8, multi-region active-active, > 10k QPS at year 1, etc.).
+- **Default to Twelve-Factor practices** for any chosen stack.
+
+## Re-running on a refined brief
+
+If you receive an updated brief with the user's answers folded in (Synapta will mark it with `(round 2)` or `(round 3)` in the prompt), keep the same `architecture-doc` shape but:
+
+- Move answered questions out of `openQuestions[]` and into `assumptions[]`.
+- Tighten the `modules` and `dataFlows` based on what you now know.
+- Only emit new `openQuestions[]` for things the previous round revealed (don't repeat).
+
+Stop emitting questions once you have enough to ship a complete plan. Round 3 should ideally have an empty `openQuestions[]`.