@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/gdpr-compliant/references/data-rights.md

@@ -0,0 +1,177 @@
+# GDPR Reference — Data Rights, Accountability & Governance
+
+Load this file when you need implementation detail on:
+user rights endpoints, Data Subject Request (DSR) workflow,
+Record of Processing Activities (RoPA), consent management.
+
+---
+
+## User Rights Implementation (Articles 15–22)
+
+Every right MUST have a tested API endpoint or documented back-office process
+before the system goes live. Respond to verified requests within **30 calendar days**.
+
+| Right | Article | Engineering implementation |
+|---|---|---|
+| Right of access | 15 | `GET /api/v1/me/data-export` — all personal data, JSON or CSV |
+| Right to rectification | 16 | `PUT /api/v1/me/profile` — propagate to all downstream stores |
+| Right to erasure | 17 | `DELETE /api/v1/me` — scrub all stores per erasure checklist |
+| Right to restriction | 18 | `ProcessingRestricted` flag on user record; gate non-essential processing |
+| Right to portability | 20 | Same as access endpoint; structured, machine-readable (JSON) |
+| Right to object | 21 | Opt-out endpoint for legitimate-interest processing; honor immediately |
+| Automated decision-making | 22 | Expose a human review path + explanation of the logic |
+
+### Erasure Checklist — MUST cover all stores
+
+When `DELETE /api/v1/me` is called, the erasure pipeline MUST scrub:
+
+- Primary relational database (anonymize or delete rows)
+- Read replicas
+- Search index (Elasticsearch, Azure Cognitive Search, etc.)
+- In-memory cache (Redis, IMemoryCache)
+- Object storage (S3, Azure Blob — profile pictures, documents)
+- Email service logs (Brevo, SendGrid — delivery logs)
+- Analytics platform (Mixpanel, Amplitude, GA4 — user deletion API)
+- Audit logs (anonymize identifying fields — do not delete the event)
+- Backups (document the backup TTL; accept that backups expire naturally)
+- CDN edge cache (purge if personal data may be cached)
+- Third-party sub-processors (trigger their deletion API or document the manual step)
+
+### Data Export Format (`GET /api/v1/me/data-export`)
+
+```json
+{
+  "exportedAt": "2025-03-30T10:00:00Z",
+  "subject": {
+    "id": "uuid",
+    "email": "user@example.com",
+    "createdAt": "2024-01-15T08:30:00Z"
+  },
+  "profile": { ... },
+  "orders": [ ... ],
+  "consents": [ ... ],
+  "auditEvents": [ ... ]
+}
+```
+
+- MUST be machine-readable (JSON preferred, CSV acceptable).
+- MUST NOT be a PDF screenshot or HTML page.
+- MUST include all stores listed in the RoPA for this user.
+
+### DSR Tracker (back-office)
+
+Implement a **Data Subject Request tracker** with:
+- Incoming request date
+- Request type (access / rectification / erasure / portability / restriction / objection)
+- Verification status (identity confirmed y/n)
+- Deadline (received date + 30 days)
+- Assigned handler
+- Completion date and outcome
+- Notes
+
+Automate the primary store scrubbing; document manual steps for third-party stores.
+
+---
+
+## Record of Processing Activities (RoPA)
+
+Maintain as a living document (Markdown, YAML, or JSON) version-controlled in the repo.
+Update with **every** new feature that introduces a processing activity.
+
+### Minimum fields per processing activity
+
+```yaml
+- name: "User account management"
+  purpose: "Create and manage user accounts for service access"
+  legalBasis: "Contract (Art. 6(1)(b))"
+  dataSubjects: ["Registered users"]
+  personalDataCategories: ["Name", "Email", "Password hash", "IP address"]
+  recipients: ["Internal engineering team", "Brevo (email delivery)"]
+  retentionPeriod: "Account lifetime + 12 months"
+  transfers:
+    outside_eea: true
+    safeguard: "Brevo — Standard Contractual Clauses (SCCs)"
+  securityMeasures: ["TLS 1.3", "AES-256 at rest", "bcrypt password hashing"]
+  dpia_required: false
+```
+
+### Legal basis options (Art. 6)
+
+| Basis | When to use |
+|---|---|
+| `Contract (6(1)(b))` | Processing necessary to fulfill the service contract |
+| `Legitimate interest (6(1)(f))` | Fraud prevention, security, analytics (requires balancing test) |
+| `Consent (6(1)(a))` | Marketing, non-essential cookies, optional profiling |
+| `Legal obligation (6(1)(c))` | Tax records, anti-money-laundering |
+| `Vital interest (6(1)(d))` | Emergency situations only |
+| `Public task (6(1)(e))` | Public authorities |
+
+---
+
+## Consent Management
+
+### MUST
+
+- Store consent as an **immutable event log**, not a mutable boolean flag.
+- Record: what was consented to, when, which version of the privacy policy, the mechanism.
+- Load analytics / marketing SDKs **conditionally** — only after consent is granted.
+- Provide a consent withdrawal mechanism as easy to use as the consent grant.
+
+### Consent store schema (minimum)
+
+```sql
+CREATE TABLE ConsentRecords (
+    Id          UUID PRIMARY KEY,
+    UserId      UUID NOT NULL,
+    Purpose     VARCHAR(100) NOT NULL,   -- e.g. "marketing_emails", "analytics"
+    Granted     BOOLEAN NOT NULL,
+    PolicyVersion VARCHAR(20) NOT NULL,
+    ConsentedAt TIMESTAMPTZ NOT NULL,
+    IpAddressHash VARCHAR(64),           -- HMAC-SHA256 of anonymized IP
+    UserAgent   VARCHAR(500)
+);
+```
+
+### MUST NOT
+
+- MUST NOT pre-tick consent checkboxes.
+- MUST NOT bundle consent for marketing with consent for service delivery.
+- MUST NOT make service access conditional on marketing consent.
+- MUST NOT use dark patterns (e.g., "Accept all" prominent, "Reject" buried).
+
+---
+
+## Sub-processor Management
+
+Maintain a **sub-processor list** updated with every new SaaS tool or cloud service
+that touches personal data.
+
+Minimum fields per sub-processor:
+
+| Field | Example |
+|---|---|
+| Name | Brevo |
+| Service | Transactional email |
+| Data categories transferred | Email address, name, email content |
+| Processing location | EU (Paris) |
+| DPA signed |  2024-01-10 |
+| DPA URL / reference | [link] |
+| SCCs applicable | N/A (EU-based) |
+
+**MUST** review the sub-processor list annually and upon any change.
+**MUST NOT** allow data to flow to a new sub-processor before a DPA is signed.
+
+---
+
+## DPIA Triggers (Article 35)
+
+A DPIA is **mandatory** before processing that is likely to result in a high risk. Triggers include:
+
+- Systematic and extensive profiling with significant effects on individuals
+- Large-scale processing of special category data (health, biometric, racial origin, sexual orientation, religion)
+- Systematic monitoring of publicly accessible areas (CCTV, location tracking)
+- Processing of children's data at scale
+- Innovative technology with unknown privacy implications
+- Matching or combining datasets from multiple sources
+
+When in doubt: conduct the DPIA anyway. Document the outcome.

package/skills/how/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: how
+description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation."
+disable-model-invocation: true
+---
+
+# How
+
+Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
+
+Each spawn below names a role line in the `pstack-models.mdc` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message.
+
+## Step 1. Assess Complexity
+
+If the scope is ambiguous, state your interpretation and explore. The user can redirect.
+
+- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. One explainer explores and explains in a single pass. Go to Step 2b.
+- **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): spawn parallel explorers first, then hand off to the explainer. Go to Step 2a.
+
+When in doubt, take the simple path.
+
+## Step 2a. Explore (complex questions only)
+
+Decompose the question into 2 to 4 exploration angles, each a distinct slice of the subsystem. Spawn all explorers in a single message:
+
+- `subagent_type`: `generalPurpose`
+- `model`: the `how explorer` line, default `grok-4.7-xhigh-fast`
+- `readonly`: `true`
+
+Each explorer gets the prompt in `references/explorer-prompt.md` with its angle filled in. Then go to Step 3.
+
+## Step 2b. Direct Explain (simple questions)
+
+Spawn one Task subagent that explores and explains in one pass:
+
+- `subagent_type`: `generalPurpose`
+- `model`: the `how explainer` line, default `claude-opus-5-5-max`
+- `readonly`: `true`
+
+Build its prompt from `references/explainer-prompt.md` without the explorer-findings section. Go to Step 4.
+
+## Step 3. Synthesize (complex questions only)
+
+Once all explorers have returned, spawn one Task subagent to synthesize their findings into one explanation:
+
+- `subagent_type`: `generalPurpose`
+- `model`: the `how explainer` line, default `claude-opus-5-5-max`
+- `readonly`: `true`
+
+Build its prompt from `references/explainer-prompt.md` with every explorer's findings filled in.
+
+## Step 4. Present
+
+Present the explainer's output to the user. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
+
+## Output Format
+
+The explanation uses the sections defined in `references/explainer-prompt.md`, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.

package/skills/how/references/explainer-prompt.md

@@ -0,0 +1,55 @@
+# Explainer Prompt Template
+
+Build the explainer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+You are writing an architectural explanation for a senior engineer. Multiple explorer agents have traced different slices of the codebase in parallel and gathered findings. Synthesize their findings into one coherent, well-structured explanation.
+
+## Original Question
+
+> {QUESTION}
+
+## Explorer Findings
+
+{EXPLORER_FINDINGS_ALL}
+
+## Instructions
+
+The explorers each investigated a different angle of the same subsystem. Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and combine the separate slices into a unified picture.
+
+Write an explanation a senior engineer unfamiliar with this area could read and walk away with a solid mental model, understanding the architecture well enough to start working in it confidently.
+
+You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use Read, Grep, and Glob as needed. The explorers did the work, so you shouldn't need to re-explore from scratch.
+
+## Output Format
+
+Use this structure, adapted to what makes sense for the question. Not every section is needed for every question.
+
+### Overview
+1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read just this and decide whether to keep reading.
+
+### Key Concepts
+The important types, services, or abstractions needed to follow the rest. Brief definitions, not exhaustive.
+
+### How It Works
+The core of the explanation, and the longest section. Walk through the flow: what triggers it, what happens step by step, where data goes, what the decision points are.
+
+Use prose, not pseudocode. Reference specific files and functions so the reader knows where to look, but don't dump large code blocks unless a snippet is essential to a point.
+
+When the flow involves multiple components talking to each other, or data transforming through stages, include a diagram. Use mermaid (```mermaid) for structured flows (sequence diagrams, flowcharts, component graphs) or ASCII art for simpler relationships where mermaid would be overkill. Use your judgment. A diagram should clarify, not decorate. If prose covers the flow, skip the diagram.
+
+### Where Things Live
+A brief file/directory map. Just the ones someone would need to start working here.
+
+### Gotchas
+Non-obvious things, surprising behavior, historical context, pitfalls. Skip this section if there's nothing worth calling out.
+
+## Communication Style
+
+- Use concrete language, not abstractions-about-abstractions
+- Say "the `UserService` calls `AuthClient.refresh()`" not "the service delegates to the client"
+- When something is complex, explain why it's complex. Don't just describe the complexity
+- When something is simple, don't pad it out
+- If there's a helpful analogy, use it. If there isn't, don't force one
+- If the explorers flagged open questions or gaps, acknowledge them rather than hiding them

package/skills/how/references/explorer-prompt.md

@@ -0,0 +1,52 @@
+# Explorer Prompt Template
+
+Build each explorer subagent's prompt from this template. Fill in the placeholders.
+
+---
+
+You are exploring a codebase to understand how something works. Gather facts. Trace code paths, read implementations, map components. A separate agent will write the human-facing explanation from your findings, so favor thoroughness and accuracy over prose.
+
+Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep.
+
+## Question
+
+> {QUESTION}
+
+## Your Exploration Angle
+
+{EXPLORATION_ANGLE}
+
+## Exploration Instructions
+
+Start by finding the relevant code. Use Glob to find directories and files, Grep to find key symbols, Read to understand the actual implementation. Don't guess from names. Read the code.
+
+Follow this pattern:
+1. **Find the entry point.** What triggers this behavior? A user action, an API call, a scheduled job? Find where it starts.
+2. **Trace the flow.** Follow the call chain from the entry point. Read each function. Understand what data flows through and how it transforms.
+3. **Map the key abstractions.** What types, interfaces, services, or classes are central? Read their definitions. Understand what they represent and why they exist.
+4. **Find the boundaries.** Where does this subsystem interface with others? What goes in, what comes out?
+5. **Look for the non-obvious.** Anything surprising? Anything that looks like a historical artifact? Anything a newcomer would misunderstand?
+
+Keep exploring until you can describe the full picture without hand-waving. If you hit a part you can't trace, say so explicitly. "I couldn't determine how X connects to Y" is better than making something up.
+
+## Output
+
+Return your findings in this structure. Be factual and specific. Reference exact file paths, function names, type names, and line numbers where relevant.
+
+### Components Found
+The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does.
+
+### Flow
+The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps.
+
+### Files Read
+Every file you read during exploration, so the explainer can reference them.
+
+### Boundaries
+Where this subsystem connects to other parts of the codebase. The inputs and outputs.
+
+### Non-Obvious Things
+Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but work another.
+
+### Open Questions
+Anything you couldn't fully trace or understand. Be honest about gaps.