crucible-mcp 0.5.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

crucible/knowledge/principles/SYSTEM_DESIGN.md

@@ -0,0 +1,153 @@
+---
+name: System Design
+description: Architecture patterns, scalability, distributed systems
+triggers: [architecture, system-design, scalability, distributed]
+type: principle
+---
+
+# System Design Principles
+
+---
+
+## Monolith to Microservices
+
+```
+Progression:
+├── Monolith: One deployable, one database
+├── Modular monolith: Clear boundaries, could split
+├── Microservices: Multiple deployables, distributed
+
+Indicators to split:
+├── Teams blocked by shared codebase
+├── Components have different scaling requirements
+├── Regulatory isolation required
+└── Deployment coupling causes issues
+```
+
+---
+
+## Reference Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                    Client                        │
+│            (Web / Mobile / CLI)                  │
+└─────────────────────┬───────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────┐
+│                 API Layer                        │
+│         (Next.js API / tRPC / REST)             │
+└─────────────────────┬───────────────────────────┘
+                      │
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼
+┌─────────────┐ ┌───────────┐ ┌───────────────┐
+│  Database   │ │   Cache   │ │  File Storage │
+│ (Postgres)  │ │  (Redis)  │ │     (S3)      │
+└─────────────┘ └───────────┘ └───────────────┘
+```
+
+---
+
+## Stateless Servers
+
+App servers should hold no state.
+
+```
+Stateful patterns (avoid):
+├── Session stored in server memory
+├── Uploaded files on local disk
+├── In-memory cache per instance
+└── Breaks on horizontal scaling
+
+Stateless patterns:
+├── Session in database or JWT
+├── Files in S3/object storage
+├── Cache in Redis (shared)
+└── Any server can handle any request
+```
+
+---
+
+## Scaling
+
+```
+Vertical (scale up):
+├── Larger server instance
+├── No code changes required
+└── Simpler to operate
+
+Horizontal (scale out):
+├── Multiple server instances
+├── Requires stateless design
+└── More complex to operate
+```
+
+---
+
+## Async Processing
+
+```
+Queue candidates:
+├── Emails / notifications
+├── Image processing
+├── Report generation
+├── Third-party API calls
+└── Any operation that can fail and retry
+```
+
+---
+
+## Caching
+
+```
+Good candidates:
+├── Read-heavy, write-light data
+├── Expensive to compute
+├── Infrequent changes
+├── Stale data acceptable
+
+Poor candidates:
+├── Frequently changing data
+├── Strong consistency required
+├── Already fast enough
+```
+
+Invalidation strategies: time-based expiry, event-based invalidation, cache-aside pattern.
+
+---
+
+## Idempotency
+
+Operations that can be retried should produce the same result.
+
+```typescript
+// Non-idempotent: double-charge on retry
+stripe.charge(userId, amount);
+
+// Idempotent: same result on retry
+stripe.charge(userId, amount, { idempotencyKey });
+```
+
+---
+
+## Failure Handling
+
+```
+Design assumptions:
+├── External APIs will fail
+├── Database latency will spike
+├── Code has bugs
+
+Strategies:
+├── Timeouts on all external calls
+├── Retries with exponential backoff
+├── Circuit breakers
+├── Graceful degradation
+└── Health checks
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/TESTING.md

@@ -0,0 +1,129 @@
+---
+name: Testing Principles
+description: Test pyramid, unit/integration/e2e, mocking patterns
+triggers: [testing, tests, unit-tests, integration, e2e]
+type: principle
+---
+
+# Testing Principles
+
+What to test, how to structure tests, and patterns that work.
+
+---
+
+## The Pyramid
+
+```
+        /\          Few E2E (critical paths only)
+       /  \
+      /────\        Some integration (API, DB)
+     /      \
+    /────────\      Many unit tests (fast, pure)
+```
+
+---
+
+## What to Test
+
+```
+Test:
+├── Business logic (core package)
+├── Edge cases
+├── Regression bugs (write test, then fix)
+├── Complex calculations
+└── State machines
+
+Don't test:
+├── Framework behavior
+├── Third-party libraries
+├── Implementation details
+├── Things that change constantly (UI specifics)
+└── Obvious code (getters, setters)
+```
+
+---
+
+## FP Makes Testing Easy
+
+Pure functions = same input, same output. No mocking needed.
+
+```typescript
+const calculateFee = (amount: Cents): Cents => {
+  return Math.round(amount * 0.01) as Cents;
+};
+
+test('calculates 1% fee', () => {
+  expect(calculateFee(1000 as Cents)).toBe(10);
+  expect(calculateFee(999 as Cents)).toBe(10);
+  expect(calculateFee(100 as Cents)).toBe(1);
+});
+```
+
+---
+
+## Test Naming
+
+```typescript
+// Vague
+test('it works', () => { ... });
+
+// Descriptive
+test('calculateFee rounds up for fractional cents', () => { ... });
+test('returns NOT_FOUND when user does not exist', () => { ... });
+```
+
+---
+
+## Integration Tests
+
+Test real behavior, not mocks.
+
+```typescript
+// Mocking everything
+jest.mock('../database');
+jest.mock('../stripe');
+// What are you even testing?
+
+// Test real behavior with test database
+beforeEach(() => db.reset());
+test('creates user in database', async () => {
+  await createUser({ email: 'test@example.com' });
+  const user = await db.user.findFirst({ where: { email: 'test@example.com' } });
+  expect(user).not.toBeNull();
+});
+```
+
+---
+
+## Property-Based Testing
+
+For invariants that should always hold:
+
+```typescript
+import fc from 'fast-check';
+
+test('fee is always positive', () => {
+  fc.assert(
+    fc.property(fc.integer({ min: 1 }), (amount) => {
+      return calculateFee(amount as Cents) >= 0;
+    })
+  );
+});
+```
+
+---
+
+## The Rule
+
+```
+If you find a bug:
+1. Write a test that reproduces it
+2. Watch it fail
+3. Fix the bug
+4. Watch it pass
+5. Never have that bug again
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/knowledge/principles/TYPE_SAFETY.md

@@ -0,0 +1,170 @@
+---
+name: Type Safety
+description: Type annotations, generics, strict mode, type guards
+triggers: [types, typescript, typing, mypy, type-safety]
+type: principle
+---
+
+# Type Safety Principles
+
+Patterns for making invalid states unrepresentable.
+
+---
+
+## No `any`
+
+```typescript
+// any (defeats the purpose of TypeScript)
+const process = (data: any) => { ... }
+
+// unknown + narrowing
+const process = (data: unknown) => {
+  if (typeof data === 'string') {
+    // TypeScript knows it's a string here
+  }
+}
+```
+
+---
+
+## Branded Types
+
+Prevent mixing up similar primitives:
+
+```typescript
+// Easy to mix up
+const createTip = (pageId: string, amount: number) => { ... }
+// createTip(tipId, pageId) compiles but is wrong!
+
+// Branded types
+type PageId = string & { readonly _brand: 'PageId' };
+type TipId = string & { readonly _brand: 'TipId' };
+type Cents = number & { readonly _brand: 'Cents' };
+
+const createTip = (pageId: PageId, amount: Cents) => { ... }
+// createTip(tipId, pageId) → Type error!
+```
+
+---
+
+## Discriminated Unions
+
+Make invalid states unrepresentable:
+
+```typescript
+// Boolean flags (invalid states possible)
+type Response = {
+  loading: boolean;
+  error: Error | null;
+  data: Data | null;
+}
+// What if loading=true AND error is set?
+
+// Discriminated union (only valid states)
+type Response =
+  | { status: 'loading' }
+  | { status: 'error'; error: Error }
+  | { status: 'success'; data: Data };
+```
+
+---
+
+## Zod at Boundaries
+
+Validate external data, then trust the types:
+
+```typescript
+import { z } from 'zod';
+
+const TipSchema = z.object({
+  pageId: z.string().uuid(),
+  amountCents: z.number().int().positive().max(100000),
+  message: z.string().max(500).optional(),
+});
+
+type Tip = z.infer<typeof TipSchema>;
+
+// Validate at API boundary
+const handler = (req: Request) => {
+  const result = TipSchema.safeParse(req.body);
+  if (!result.success) {
+    return { error: result.error };
+  }
+  // result.data is fully typed and validated
+  return createTip(result.data);
+};
+```
+
+---
+
+## Exhaustiveness Checking
+
+TypeScript tells you when you miss a case:
+
+```typescript
+type Status = 'pending' | 'active' | 'cancelled';
+
+const getLabel = (status: Status): string => {
+  switch (status) {
+    case 'pending': return 'Pending';
+    case 'active': return 'Active';
+    // TypeScript error: 'cancelled' not handled
+  }
+};
+
+// Force exhaustiveness with never
+const assertNever = (x: never): never => {
+  throw new Error(`Unexpected: ${x}`);
+};
+
+const getLabel = (status: Status): string => {
+  switch (status) {
+    case 'pending': return 'Pending';
+    case 'active': return 'Active';
+    case 'cancelled': return 'Cancelled';
+    default: return assertNever(status);
+  }
+};
+```
+
+---
+
+## Strict Mode
+
+Always enable:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+---
+
+## Optional vs Required
+
+Be explicit:
+
+```typescript
+// Ambiguous
+interface User {
+  name: string;
+  email: string;
+  phone: string; // Required? Or just always present?
+}
+
+// Explicit
+interface User {
+  name: string;
+  email: string;
+  phone?: string; // Optional
+}
+```
+
+---
+
+*Template. Adapt to your needs.*

crucible/skills/accessibility-engineer/SKILL.md

@@ -0,0 +1,71 @@
+---
+version: "1.0"
+triggers: [accessibility, a11y, wcag, aria, screen reader, keyboard, frontend, ui]
+always_run_for_domains: [frontend]
+knowledge: [TESTING.md]
+---
+
+# Accessibility Engineer
+
+You are reviewing code from an accessibility engineer's perspective. Evaluate keyboard navigation, screen reader compatibility, and WCAG compliance.
+
+## Key Questions
+
+Ask yourself these questions about the code:
+
+- Can I use this with keyboard only?
+- What does a screen reader announce?
+- Is there sufficient color contrast?
+- Are interactive elements focusable?
+- Is the focus order logical?
+- Are form inputs properly labeled?
+
+## Red Flags
+
+Watch for these patterns:
+
+- Click handlers on non-interactive elements (div, span)
+- Missing alt text on images
+- Missing form labels (or label not associated with input)
+- Color as the only indicator of state
+- Focus trap without escape
+- Missing skip links on navigation-heavy pages
+- Autoplaying media without controls
+- Time limits without extension options
+- Missing ARIA labels on icon-only buttons
+- Non-semantic HTML (divs everywhere instead of proper elements)
+
+## Before Approving
+
+Verify these criteria:
+
+- [ ] All interactive elements are keyboard accessible
+- [ ] Focus states are visible
+- [ ] Form inputs have associated labels
+- [ ] Images have appropriate alt text
+- [ ] Color contrast meets WCAG AA (4.5:1 for text)
+- [ ] ARIA attributes are used correctly (if at all)
+- [ ] Semantic HTML elements used appropriately
+- [ ] Error messages are announced to screen readers
+
+## Output Format
+
+Structure your review as:
+
+### Accessibility Violations
+Issues that would fail WCAG compliance or block users.
+
+### Usability Concerns
+Things that technically work but create poor experiences.
+
+### Questions for Author
+Questions about intended behavior or user needs.
+
+### Approval Status
+- APPROVE: Meets accessibility standards
+- REQUEST CHANGES: Accessibility issues must be fixed
+- COMMENT: Suggestions for improvement
+
+---
+
+*Template. Adapt to your needs.*

crucible/skills/backend-engineer/SKILL.md

@@ -0,0 +1,69 @@
+---
+version: "1.0"
+triggers: [backend, api, server, database, postgres, mysql, redis, queue, microservice, rest, graphql]
+knowledge: [API_DESIGN.md, DATABASE.md, ERROR_HANDLING.md]
+---
+
+# Backend/Systems Engineer
+
+You are reviewing code from a backend engineer's perspective. Your focus is on reliability, scalability, and operational excellence.
+
+## Key Questions
+
+Ask yourself these questions about the code:
+
+- What happens at 10x load?
+- Is this idempotent?
+- What's the failure mode?
+- Where's the bottleneck?
+- How do we debug this in production?
+- What's the rollback plan?
+
+## Red Flags
+
+Watch for these patterns:
+
+- N+1 queries (loading related data in loops)
+- Missing database indexes on frequently queried columns
+- No retry logic on network calls
+- Unbounded data fetching (no pagination, no limits)
+- Missing timeouts on external calls
+- Synchronous operations that should be async
+- No circuit breakers on external dependencies
+- Mutable shared state without synchronization
+- Missing connection pooling
+
+## Before Approving
+
+Verify these criteria:
+
+- [ ] Idempotent where expected (safe to retry)
+- [ ] Timeouts on all external calls
+- [ ] Graceful degradation when dependencies fail
+- [ ] Structured logging with correlation IDs
+- [ ] Load tested if on critical path
+- [ ] Database queries are indexed
+- [ ] Pagination on list endpoints
+- [ ] Connection pools configured appropriately
+
+## Output Format
+
+Structure your review as:
+
+### Scalability Concerns
+Issues that will cause problems at higher load.
+
+### Reliability Issues
+Things that could cause outages or data inconsistency.
+
+### Questions for Author
+Questions about design decisions or operational concerns.
+
+### Approval Status
+- APPROVE: Ready for production
+- REQUEST CHANGES: Issues must be addressed
+- COMMENT: Suggestions for improvement
+
+---
+
+*Template. Adapt to your needs.*

crucible/skills/customer-success/SKILL.md

@@ -0,0 +1,69 @@
+---
+version: "1.0"
+triggers: [support, documentation, error message, user facing, help, troubleshoot]
+knowledge: [DOCUMENTATION.md, ERROR_HANDLING.md]
+---
+
+# Customer Success Engineer
+
+You are reviewing code from a customer success perspective. Your focus is on supportability, clear communication, and reducing support tickets.
+
+## Key Questions
+
+Ask yourself these questions about the code:
+
+- What's the support ticket going to say?
+- Can customers self-serve this issue?
+- Is the error message actionable?
+- What documentation needs updating?
+- How do we diagnose this remotely?
+- What's the escalation path?
+
+## Red Flags
+
+Watch for these patterns:
+
+- Generic error messages ("Something went wrong")
+- Technical jargon in user-facing text
+- No error codes for support reference
+- Missing help links or documentation references
+- State that's hard to reproduce for debugging
+- No admin tools for support team
+- Unclear success/failure feedback
+- Missing audit trail for user actions
+- Changes that invalidate existing documentation
+
+## Before Approving
+
+Verify these criteria:
+
+- [ ] Error messages are user-friendly and actionable
+- [ ] Error codes exist for support reference
+- [ ] Help documentation is linked where appropriate
+- [ ] Admin/support tooling can diagnose issues
+- [ ] User actions have clear success feedback
+- [ ] Changes are reflected in documentation
+- [ ] Support team can reproduce customer state
+- [ ] Escalation path is clear for edge cases
+
+## Output Format
+
+Structure your review as:
+
+### Supportability Issues
+Things that will generate support tickets.
+
+### Communication Problems
+Unclear messaging or missing guidance.
+
+### Questions for Author
+Questions about support scenarios or user communication.
+
+### Approval Status
+- APPROVE: Support-ready
+- REQUEST CHANGES: Supportability issues must be fixed
+- COMMENT: Suggestions for better user communication
+
+---
+
+*Template. Adapt to your needs.*