@martinffx/atelier 1.2.1 → 1.3.0

package/skills/oracle-grillme/SKILL.md

@@ -1,160 +0,0 @@
----
-name: oracle-grillme
-description: >
-  Socratic interrogation of plans against the project's domain model and documented decisions.
-  Use when the user wants to stress-test a plan, clarify terminology, or validate assumptions
-  against existing domain language. Updates CONTEXT.md and ADRs inline as decisions crystallise.
-user-invocable: true
----
-
-# Grill Me
-
-Relentless questioning of your plan against the project's domain model, sharpening terminology and updating documentation (CONTEXT.md, ADRs) inline as decisions crystallise.
-
-## When to Use
-
-- **Stress-testing a plan** — "I want to add a refund flow to the Order service"
-- **Clarifying fuzzy language** — "We're calling it 'account' but is that a Customer or a User?"
-- **Onboarding to a domain** — "Walk me through how the Billing context relates to Ordering"
-- **Before writing specs** — Ensuring the domain language is solid before `spec-research` begins
-- **After code review** — "The PR introduces 'cancellation' but our glossary says..."
-
-## When NOT to Use
-
-- **Simple implementation questions** — Use `oracle-challenge` or `oracle-architect` instead
-- **Debugging** — Use `code-debug`
-- **Testing strategy** — Use `oracle-testing`
-- **Already in spec workflow** — Use `spec-research` + `oracle-architect` for domain discovery during the spec process
-
----
-
-## How It Works
-
-<interview-loop>
-
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
-
-Ask the questions one at a time, waiting for feedback on each question before continuing.
-
-If a question can be answered by exploring the codebase, explore the codebase instead.
-
-</interview-loop>
-
----
-
-## Domain Awareness
-
-### Discovering Context
-
-Most repos have a single context:
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
-
-### During the Session
-
-#### Challenge Against the Glossary
-
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately.
-
-> "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
-
-#### Sharpen Fuzzy Language
-
-When the user uses vague or overloaded terms, propose a precise canonical term.
-
-> "You're saying 'account' — do you mean the Customer or the User? Those are different things."
-
-#### Discuss Concrete Scenarios
-
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
-
-#### Cross-Reference With Code
-
-When the user states how something works, check whether the code agrees. If you find a contradiction, surface it:
-
-> "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
-
-#### Update CONTEXT.md Inline
-
-When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [references/CONTEXT-FORMAT.md](./references/CONTEXT-FORMAT.md).
-
-`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
-
-#### Offer ADRs Sparingly
-
-Only offer to create an ADR when all three are true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
-3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
-
-If any of the three is missing, skip the ADR. Use the format in [references/ADR-FORMAT.md](./references/ADR-FORMAT.md).
-
----
-
-## Usage Examples
-
-### Stress-Test a New Feature
-```
-/grillme "I want to add a refund flow to the Order service"
-```
-> "Before we go further — your glossary defines 'Order' as a completed purchase. A refund implies the Order is no longer complete. Is 'refund' a state on Order, or a new concept entirely?"
-
-### Clarify Ambiguous Terms
-```
-/grillme "We need to handle 'account' deletions"
-```
-> "You said 'account' — your CONTEXT.md has both Customer and User. Which one are we deleting, and what happens to their Orders?"
-
-### Validate Against Existing Decisions
-```
-/grillme "I'm switching the write model from Postgres to DynamoDB"
-```
-> "ADR-0002 says we chose Postgres for the write model because of ACID requirements. Have those requirements changed, or is this a new trade-off?"
-
-### Onboard to a Domain
-```
-/grillme "Explain how Billing relates to Ordering"
-```
-> "Ordering emits OrderPlaced events. Billing consumes them to create Invoices. But your CONTEXT.md says Invoice is a request for payment — who decides when payment is actually processed?"
-
----
-
-## Relationship to Other Skills
-
-| Skill | Use When |
-|-------|----------|
-| **oracle-grillme** | Questioning domain assumptions, sharpening terminology, updating docs inline |
-| **oracle-challenge** | Critically evaluating a technical approach or decision |
-| **oracle-architect** | Designing components, data models, API contracts during spec-research |
-| **spec-research** | Structured discovery + architecture → spec.md (use grillme before this to solidify language) |
-
-**Key distinction:**
-- `oracle-challenge` = "Is this approach valid?" (critical evaluation)
-- `oracle-grillme` = "What do we mean by these words?" (domain interrogation)

package/skills/oracle-security/SKILL.md

@@ -1,225 +0,0 @@
----
-name: oracle-security
-description: Security architecture and threat modeling knowledge. Auto-invokes when designing features that handle untrusted data, authentication, authorization, external integrations, file uploads, or sensitive data. Provides risk assessment frameworks, trust boundary analysis, and security design principles — not implementation code.
-user-invocable: false
----
-
-# oracle-security: Security Architecture & Threat Modeling
-
-## When to Use
-
-Auto-invokes when context contains:
-- Authentication, authorization, session management
-- User input, validation, untrusted data
-- External integrations, webhooks, third-party APIs
-- File uploads, data processing
-- Encryption, hashing, secrets, sensitive data
-- Security concerns, vulnerabilities, threats
-
-## The Security Mindset
-
-### Core Principles
-
-1. **Validate at Boundaries** — Every entry point is a trust boundary. Assume everything that crosses it is hostile until proven otherwise.
-
-2. **Never Trust the Client** — Client-side validation, hidden fields, and browser headers are UX conveniences, not security controls. The server is the only security boundary that matters.
-
-3. **Fail Closed** — Deny by default. When in doubt, reject. When validation fails, stop. When auth is uncertain, deny. "Fail open" is an accidental backdoor.
-
-4. **Defense in Depth** — No single control should be the only thing preventing compromise. Layer them so that bypassing one still leaves others.
-
-5. **Least Privilege** — Every component should have the minimum access necessary to do its job, and only for the minimum time required.
-
-6. **Compartmentalize** — A breach in one area should not automatically grant access to everything else. Isolate by function, data sensitivity, and trust level.
-
-### The Trust Boundary Model
-
-```
-External World  →  [Trust Boundary]  →  Internal System
-       ↑                                    ↑
-   Validate here                        Enforce here
-   Sanitize here                         Audit here
-   Authenticate here                     Authorize here
-```
-
-Trust boundaries exist at every system edge where data or control crosses from a less-trusted to a more-trusted zone:
-
-- **API routes / controllers** — Where external requests enter
-- **Event consumers** — Where external events are processed
-- **File processors** — Where external files are handled
-- **External service callbacks** — Where third-party responses enter
-- **Database writes** — When data from external sources persists
-
-**Key insight**: Security enforcement should happen as close to the trust boundary as possible. Don't let untrusted data travel deep into your system before validation.
-
-## Threat Modeling Quick-Start
-
-### Simplified STRIDE
-
-For every feature, ask these six questions:
-
-| Threat | Question | Example Concern |
-|--------|----------|----------------|
-| **S**poofing | Who could pretend to be someone else? | Fake user IDs, stolen tokens, forged requests |
-| **T**ampering | What could be modified in transit or at rest? | Request payload alteration, data corruption |
-| **R**epudiation | Can actions be denied after the fact? | Missing audit logs, unaccountable changes |
-| **I**nformation Disclosure | What sensitive data could leak? | Error messages, logs, API responses |
-| **D**enial of Service | How could this be overwhelmed or broken? | No rate limits, expensive queries, resource exhaustion |
-| **E**levation of Privilege | Who could gain more access than intended? | Missing authorization checks, parameter tampering |
-
-### Attack Tree Thinking
-
-For critical features, build a simple attack tree:
-
-1. **Goal**: What does the attacker want? (data, access, disruption)
-2. **Paths**: How could they achieve it? (multiple entry points, chained vulnerabilities)
-3. **Barriers**: What stops each path? (validation, auth, rate limits, encryption)
-4. **Gaps**: Where are there no barriers? (missing checks, implicit trust)
-
-**Usage**: You don't need a formal diagram. A bullet list of "to steal X, attacker could Y which is blocked by Z, unless they find W" is sufficient for most design reviews.
-
-## Risk Proportionality
-
-### Assessment Dimensions
-
-Consider two factors:
-
-- **Impact**: What happens if this is exploited? (reputational damage, financial loss, legal consequences, user harm)
-- **Likelihood**: How easy is exploitation? (public internet access, authenticated only, internal network, physical access required)
-
-### Flexible Guidance
-
-| Context | Typical Posture |
-|---------|-----------------|
-| Public-facing, unauthenticated | Maximum validation, rate limiting, minimal data exposure, aggressive fail-closed |
-| Authenticated user operations | Standard validation, authorization checks, audit logging, session management |
-| Internal admin tools | Authentication essential, authorization by role, audit everything, additional monitoring |
-| Background processing | Input validation still required, fail-safe defaults, logging for debugging |
-
-**Adjust based on your threat model.** A public search box and an internal admin panel have different risks. Don't apply maximum security everywhere — apply *proportional* security everywhere.
-
-## Security Architecture Patterns
-
-### Defense in Depth
-
-Don't rely on a single control. Layer them:
-
-```
-Input → [Validation] → [Authentication] → [Authorization] → [Audit]
-         ↑              ↑                 ↑                ↑
-      Reject bad     Verify who         Check can-do       Log did-do
-      data           they are           they have          they did
-```
-
-If any layer fails, the others still provide protection. A validation bypass shouldn't automatically mean unauthorized access.
-
-### Least Privilege
-
-- Services should have minimum database permissions (read-only where possible, never admin by default)
-- API tokens should have scoped access (not blanket permissions)
-- User sessions should timeout (not indefinite, not excessively long)
-- Background jobs should run with restricted credentials (not application-level access)
-
-**Corollary**: When a component needs elevated access temporarily, that access should be explicitly granted and automatically revoked.
-
-### Fail-Safe Defaults
-
-- Permission denied unless explicitly granted (not granted unless explicitly denied)
-- Reject input that doesn't match expected format (don't try to fix or coerce)
-- Lock account after repeated failures (don't allow infinite attempts)
-- Default to most restrictive CORS, CSP, and network policies (open up explicitly)
-
-**Key question**: "If this component fails or is misconfigured, what's the safest default state?"
-
-### Compartmentalization
-
-- Separate sensitive data from operational data (different stores, different access levels)
-- Use different credentials for different services (one breach doesn't cascade)
-- Isolate file processing from application logic (sandbox, validate before processing)
-- Don't mix admin and user operations in the same endpoints or components
-
-## Design Review Questions
-
-Ask before implementing:
-
-### Data Handling
-- [ ] What data enters the system? Where does it come from? How is it validated?
-- [ ] What data exits the system? Who can see it? Is it filtered appropriately?
-- [ ] What happens to data at rest? Is sensitive data protected?
-- [ ] Are there retention/deletion requirements? How are they enforced?
-
-### Access Control
-- [ ] Who can access this feature? How is that authenticated and enforced?
-- [ ] Can users access other users' data? How is that prevented?
-- [ ] Are there different permission levels? How are they checked?
-- [ ] What happens when permissions change (revocation, role change)?
-
-### Threat Surface
-- [ ] What new entry points does this feature create?
-- [ ] What existing trust boundaries does this cross?
-- [ ] What external systems does this depend on? What's their security posture?
-- [ ] What happens if those systems are compromised or unavailable?
-
-### Failure Modes
-- [ ] What happens when validation fails? (Should fail closed)
-- [ ] What happens when authentication fails? (Should not reveal user existence)
-- [ ] What happens when dependencies fail? (Should degrade safely)
-- [ ] Are errors informative for debugging without being revealing for attackers?
-
-## Red Flags & Anti-Patterns
-
-### Architectural Smells
-
-- **Trusting external input without validation** — Browser headers, webhook payloads, file contents, third-party API responses. All are untrusted until validated.
-
-- **Single authorization check at entry** — Checking auth at the route level but not verifying resource ownership on each operation. Every action on a resource needs its own authorization check.
-
-- **Errors revealing system internals** — Stack traces, database schemas, file paths, internal IDs in error messages. Debug information belongs in logs, not responses.
-
-- **No audit trail for sensitive operations** — If you can't reconstruct who did what after an incident, you can't investigate or recover.
-
-- **Broad permissions by default** — Service accounts with admin access, tokens with blanket permissions, users with more roles than they need.
-
-- **Security logic in client code** — "The frontend will validate" or "the mobile app won't send that." The client is not a security boundary.
-
-### Process Smells
-
-- "We'll add security later" — Security retrofitting is 10x harder and 10x more expensive than designing it in.
-- "This is just internal" — Internal tools are prime targets. Attackers specifically look for weak internal systems.
-- "No one would try to exploit this" — Automated attacks are indiscriminate. You don't need to be a target to be compromised.
-- "The framework handles security" — Frameworks provide primitives and tools. You must compose them correctly.
-- "Security slows development" — Insecure code slows you more when you have to stop everything to respond to a breach.
-
-## Common Rationalizations
-
-| Rationalization | Reality |
-|-----------------|---------|
-| "It's just a prototype" | Prototypes become production. Security habits from day one prevent day-one-hundred emergencies. |
-| "This is an internal tool" | Internal tools are targets. Attackers look for the weakest link, and internal systems are often it. |
-| "We'll add security later" | Later rarely comes. Retrofitting is expensive, error-prone, and usually incomplete. |
-| "The framework handles security" | Frameworks provide primitives. You compose them correctly. They don't secure your application by default. |
-| "No one would target us" | Automated attacks are indiscriminate. Scanners don't care who you are. |
-| "Security slows development" | Insecure code costs more: incident response, legal exposure, user trust loss. |
-
-## Verification
-
-After designing security-relevant features:
-
-- [ ] Threat model documented (even if brief — STRIDE questions answered)
-- [ ] Trust boundaries identified and validation points specified
-- [ ] Input validation strategy defined (where, what, how strict)
-- [ ] Authentication requirements specified (who, how, session management)
-- [ ] Authorization rules documented (who can do what to what)
-- [ ] Failure modes specified (fail closed, not open)
-- [ ] Audit requirements identified (what to log, where)
-- [ ] External dependencies' security posture considered
-- [ ] No secrets or sensitive data in design documents (future attack surface)
-
-## See Also
-
-- `references/threat-modeling-guide.md` — Extended threat modeling approaches
-- `references/security-patterns.md` — Catalog of security design patterns
-
----
-
-*Security is not a feature you add. It's a property of the system you design.*

package/skills/oracle-security/references/security-patterns.md

@@ -1,236 +0,0 @@
-# Security Design Patterns
-
-Catalog of architectural patterns for building secure systems.
-
-## Input Validation Patterns
-
-### Whitelist Validation
-Define what's allowed, reject everything else. More secure than blacklist (define what's blocked, allow everything else).
-
-- Specify allowed types, formats, lengths, ranges
-- Reject input that doesn't match exactly
-- Don't try to "fix" invalid input — reject it
-
-### Schema Validation
-Define expected structure and enforce it at the boundary.
-
-- Types, required fields, field constraints
-- Nested object validation
-- Array item validation
-
-### Sanitization vs. Validation
-
-| Approach | When to Use | Risk |
-|----------|-------------|------|
-| **Validation** | Reject invalid input entirely | Low — no invalid data enters system |
-| **Sanitization** | Clean input for safe use | Medium — subtle bugs in sanitization logic |
-| **Encoding** | Escape for specific context | Context-dependent — wrong encoding for wrong context |
-
-**Rule**: Validate first. Only sanitize if you understand exactly what the destination context requires.
-
-## Authentication Patterns
-
-### Session-Based Authentication
-- Server-side session storage
-- Session ID in httpOnly, secure, sameSite cookie
-- Server validates session on every request
-
-### Token-Based Authentication
-- Signed token (JWT, Paseto) containing claims
-- Token sent in Authorization header
-- Server validates signature and expiry
-
-### Multi-Factor Authentication
-- Something you know (password)
-- Something you have (device, token)
-- Something you are (biometric)
-
-**Key Decision**: Session vs. Token depends on state requirements, scale, and revocation needs.
-
-## Authorization Patterns
-
-### Role-Based Access Control (RBAC)
-- Users assigned to roles
-- Roles granted permissions
-- Simple to understand and audit
-
-### Attribute-Based Access Control (ABAC)
-- Policies based on user attributes, resource attributes, environment
-- More flexible but more complex
-- Better for fine-grained, dynamic access control
-
-### Resource-Level Authorization
-Every operation checks: "Does this user have permission to perform this action on this specific resource?"
-
-- Don't check once at login and assume it's valid for all subsequent actions
-- Re-verify on every request that touches a resource
-- Consider resource ownership, sharing, delegation
-
-## Output Protection Patterns
-
-### Response Filtering
-Remove sensitive fields from API responses based on caller's authorization level.
-
-- Never return internal IDs, passwords, tokens, or secrets
-- Filter differently for different user types
-- Consider field-level access control
-
-### Error Message Safety
-- Return generic errors to users
-- Log detailed errors internally
-- Never expose: stack traces, database schemas, file paths, internal IPs, system versions
-
-## Audit and Logging Patterns
-
-### Security Event Logging
-Log events that matter for security investigations:
-
-- Authentication attempts (success and failure)
-- Authorization failures
-- Sensitive data access
-- Configuration changes
-- Privilege escalations
-
-### Audit Trail Requirements
-- **Who**: Which user or service performed the action
-- **What**: What action was performed
-- **When**: Timestamp (UTC)
-- **Where**: Source IP, endpoint, service
-- **Result**: Success or failure
-- **Context**: Relevant IDs, parameters (sanitized)
-
-### Log Protection
-- Logs should be tamper-evident (append-only, signed)
-- Separate log access from application access
-- Retain according to compliance requirements
-- Don't log secrets, tokens, or sensitive personal data
-
-## Secrets Management Patterns
-
-### Environment-Based Configuration
-- Secrets in environment variables, never in code
-- Separate config per environment (dev, staging, prod)
-- Use secret management services in production (Vault, AWS Secrets Manager, etc.)
-
-### Secret Rotation
-- Rotate credentials regularly
-- Support emergency rotation
-- Don't hardcode secret references
-
-### Least-Exposure Principle
-- Services should only know the secrets they absolutely need
-- Don't use one API key for everything
-- Separate credentials by function and scope
-
-## Resilience Patterns
-
-### Circuit Breaker
-When a dependency fails repeatedly, stop calling it temporarily to prevent cascading failures.
-
-- Detect failure threshold
-- Open circuit (fail fast) for a period
-- Half-open (test with limited traffic) before fully closing
-
-### Rate Limiting
-Prevent abuse by limiting requests per time window per client.
-
-- Different limits for different endpoints (auth vs. data)
-- Different limits for different user types (anonymous vs. authenticated)
-- Consider burst allowances and graceful degradation
-
-### Timeout and Backoff
-- All external calls should have timeouts
-- Retry with exponential backoff for transient failures
-- Don't retry authentication failures (could be brute force)
-
-## Data Protection Patterns
-
-### Encryption at Rest
-- Sensitive data encrypted in database
-- Key management separate from data access
-- Consider performance impact on queries
-
-### Encryption in Transit
-- TLS for all external communication
-- Consider mTLS for service-to-service
-- Don't disable certificate verification
-
-### Tokenization
-Replace sensitive data with non-sensitive equivalents.
-
-- Actual data stored in secure vault
-- Token used in application logic
-- Reduces exposure surface
-
-## Secure Defaults Patterns
-
-### Deny by Default
-- All access denied unless explicitly granted
-- All features disabled unless explicitly enabled
-- All connections rejected unless explicitly allowed
-
-### Minimal Surface Area
-- Don't expose features you don't need
-- Disable unused endpoints, services, protocols
-- Remove default accounts and sample data
-
-### Secure Configuration
-- Framework defaults should be hardened
-- Don't rely on "out of the box" security
-- Explicitly configure security settings
-
-## Defense in Depth Patterns
-
-### Layered Controls
-Multiple independent controls for the same threat:
-
-```
-Threat: SQL Injection
-├── Layer 1: Input validation (reject non-matching input)
-├── Layer 2: Parameterized queries (prevent interpretation as SQL)
-├── Layer 3: Least privilege database user (limit damage if bypassed)
-└── Layer 4: Monitoring (detect and alert on suspicious patterns)
-```
-
-### Compartmentalization
-- Separate sensitive operations from general operations
-- Isolate user data by tenant or scope
-- Use different credentials for different functions
-
-### Fail-Safe States
-- When validation fails: reject
-- When auth fails: deny
-- When encryption fails: don't send
-- When logging fails: fail closed (don't proceed silently)
-
-## Anti-Patterns to Avoid
-
-### God Object Security
-Putting all security logic in one place (e.g., a single middleware) instead of at each layer.
-
-**Problem**: Bypass the middleware, bypass all security.
-**Fix**: Security at every relevant layer.
-
-### Client-Side Security
-Relying on browser validation, hidden fields, or client logic for security.
-
-**Problem**: Clients are completely under attacker control.
-**Fix**: Server-side validation is the only validation that matters.
-
-### Security Through Obscurity
-Relying on secrecy of design or implementation for security.
-
-**Problem**: Once discovered (and it will be), there's no protection.
-**Fix**: Assume attackers know your design. Security should work even when public.
-
-### Trusting the Network
-Assuming internal network traffic is safe.
-
-**Problem**: Lateral movement after initial compromise is common.
-**Fix**: Authenticate and validate internal traffic too.
-
-### Hardcoded Secrets
-Embedding credentials, keys, or tokens in source code.
-
-**Problem**: Committed to version control, visible to anyone with code access.
-**Fix**: Environment variables, secret managers, runtime injection.