@runecraft/grimoire 1.0.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@runecraft/grimoire",
+  "version": "1.0.0",
+  "description": "Interactive catalog and installer for agent skills",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "grimoire": "dist/grimoire.js"
+  },
+  "files": [
+    "skills/",
+    "references/",
+    "dist/",
+    "catalog.json"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --target=node --format=esm --outfile dist/grimoire.js && chmod +x dist/grimoire.js",
+    "dev": "bun run src/index.ts",
+    "lint": "bun run typecheck",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepack": "bun run build",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "grimoire",
+    "agent",
+    "skills",
+    "prompts",
+    "ai",
+    "coding-agent",
+    "claude",
+    "codex",
+    "opencode",
+    "copilot",
+    "installer",
+    "cli"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  }
+}

package/references/definition-of-done.md

@@ -0,0 +1,67 @@
+# Definition of Done
+
+A standing, project-wide bar that every change must clear before it counts as done. Unlike acceptance criteria, which vary per task and answer "did we build the right thing?", the Definition of Done is the same every time and answers "is this finished to our standard?". Use it as the final gate in `spec-driven` and `shipping-and-launch`.
+
+## Definition of Done vs. Acceptance Criteria
+
+| | Acceptance Criteria | Definition of Done |
+|---|---|---|
+| Scope | Specific to one task or spec | Applies to every increment |
+| Changes | Different for each item | Fixed and reused |
+| Answers | "Did we build *this thing*?" | "Is it *ready*?" |
+| Owner | Defined when planning the task | Defined once for the project |
+| Example | "User can reset password via email link" | "Tests pass, no regressions, docs updated" |
+
+The two are complementary. A task is done only when **its** acceptance criteria are met **and** the standing Definition of Done is satisfied. Skipping either leaves work that looks finished but is not.
+
+## The Standing Checklist
+
+Apply this to every change before declaring it done.
+
+### Correctness
+- [ ] All acceptance criteria for the task are met
+- [ ] Code runs and behaves as intended, verified at runtime, not just compiled or typechecked
+- [ ] New behavior is covered by tests that fail without the change and pass with it
+- [ ] Existing tests still pass; no regressions introduced
+- [ ] Edge cases and error paths are handled, not just the happy path
+
+### Quality
+- [ ] Code reveals intent through naming and structure; no comments needed to explain *what* it does
+- [ ] No duplicated business logic
+- [ ] No dead code, debug output, or commented-out blocks left behind
+- [ ] Changes are scoped to the task; no unrelated refactors snuck in
+- [ ] Linting and formatting pass
+
+The depth behind these items lives in `code-review-and-quality` (the five-axis review) and `code-simplification` (reducing complexity without changing behavior).
+
+### Integration
+- [ ] Change works with the rest of the system, not just in isolation
+- [ ] Database migrations, config changes, and feature flags are accounted for
+- [ ] Backward compatibility considered for any public interface or API change
+
+### Documentation
+- [ ] Public interfaces, APIs, and user-facing behavior are documented
+- [ ] Architectural decisions worth preserving are recorded
+- [ ] Documentation describes the current state in timeless language, not the change history
+
+### Ship-readiness
+- [ ] Security implications reviewed for any untrusted input, auth, or data handling (see `security-and-hardening`)
+- [ ] Observability in place for new critical paths (logs, metrics, traces)
+- [ ] Rollback path exists for anything risky (see `shipping-and-launch`)
+- [ ] The human has reviewed and approved before merge or deploy
+
+## How to Apply
+
+- **Per task**: confirm the Correctness and Quality sections before checking the task off.
+- **Per feature**: confirm Integration and Documentation before considering the feature complete.
+- **Per release**: the full checklist is the floor; `shipping-and-launch` adds the deploy-specific gates on top.
+
+Tailor the list to the project once, then reuse it unchanged. A Definition of Done that is renegotiated every sprint is not a Definition of Done.
+
+## Red Flags
+
+- "It's done, I just haven't run it yet": unverified work is not done.
+- "Tests pass" used as a synonym for done while docs, regressions, or runtime verification are skipped.
+- A different bar applied depending on deadline pressure.
+- Acceptance criteria treated as the whole bar, with no standing quality floor.
+- "Done" declared before human review on changes that need it.

package/references/testing-patterns.md

@@ -0,0 +1,260 @@
+# Testing Patterns Reference
+
+Quick reference for common testing patterns across the stack. Use alongside the `test-driven-development` skill.
+
+## Test Pyramid (80/15/5)
+
+Target distribution for a healthy suite:
+
+```
+        /\
+       /  \         E2E        ~5%   (slow, brittle, high signal)
+      /----\
+     /      \       Integration ~15%  (contract-level, balanced)
+    /--------\
+   /          \     Unit        ~80%  (fast, focused, cheap)
+  /------------\
+```
+
+- **80% unit** — pure functions, single behavior, milliseconds
+- **15% integration** — module boundaries, contracts between collaborators
+- **5% E2E** — critical user journeys only; every E2E test is expensive
+
+## Beyonce Rule
+
+> "If you liked it then you should've put a test on it."
+
+Every shipped behavior needs a regression test. "We'll add tests later" is a known failure mode — the gap is rarely closed, and the next change touches untested code. New behavior without a test is unfinished work, not done work.
+
+## Table of Contents
+
+- [Test Structure (Arrange-Act-Assert)](#test-structure-arrange-act-assert)
+- [Test Naming Conventions](#test-naming-conventions)
+- [Common Assertions](#common-assertions)
+- [Mocking Patterns](#mocking-patterns)
+- [React/Component Testing](#reactcomponent-testing)
+- [API / Integration Testing](#api--integration-testing)
+- [E2E Testing (Playwright)](#e2e-testing-playwright)
+- [Test Anti-Patterns](#test-anti-patterns)
+
+## Test Structure (Arrange-Act-Assert)
+
+```typescript
+it('describes expected behavior', () => {
+  // Arrange: Set up test data and preconditions
+  const input = { title: 'Test Task', priority: 'high' };
+
+  // Act: Perform the action being tested
+  const result = createTask(input);
+
+  // Assert: Verify the outcome
+  expect(result.title).toBe('Test Task');
+  expect(result.priority).toBe('high');
+  expect(result.status).toBe('pending');
+});
+```
+
+## Test Naming Conventions
+
+```typescript
+// Pattern: [unit] [expected behavior] [condition]
+describe('TaskService.createTask', () => {
+  it('creates a task with default pending status', () => {});
+  it('throws ValidationError when title is empty', () => {});
+  it('trims whitespace from title', () => {});
+  it('generates a unique ID for each task', () => {});
+});
+```
+
+## Common Assertions
+
+```typescript
+// Equality
+expect(result).toBe(expected);           // Strict equality (===)
+expect(result).toEqual(expected);        // Deep equality (objects/arrays)
+expect(result).toStrictEqual(expected);  // Deep equality + type matching
+
+// Truthiness
+expect(result).toBeTruthy();
+expect(result).toBeFalsy();
+expect(result).toBeNull();
+expect(result).toBeDefined();
+expect(result).toBeUndefined();
+
+// Numbers
+expect(result).toBeGreaterThan(5);
+expect(result).toBeLessThanOrEqual(10);
+expect(result).toBeCloseTo(0.3, 5);      // Floating point
+
+// Strings
+expect(result).toMatch(/pattern/);
+expect(result).toContain('substring');
+
+// Arrays / Objects
+expect(array).toContain(item);
+expect(array).toHaveLength(3);
+expect(object).toHaveProperty('key', 'value');
+
+// Errors
+expect(() => fn()).toThrow();
+expect(() => fn()).toThrow(ValidationError);
+expect(() => fn()).toThrow('specific message');
+
+// Async
+await expect(asyncFn()).resolves.toBe(value);
+await expect(asyncFn()).rejects.toThrow(Error);
+```
+
+## Mocking Patterns
+
+### Mock Functions
+
+```typescript
+const mockFn = jest.fn();
+mockFn.mockReturnValue(42);
+mockFn.mockResolvedValue({ data: 'test' });
+mockFn.mockImplementation((x) => x * 2);
+
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+expect(mockFn).toHaveBeenCalledTimes(3);
+```
+
+### Mock Modules
+
+```typescript
+// Mock an entire module
+jest.mock('./database', () => ({
+  query: jest.fn().mockResolvedValue([{ id: 1, title: 'Test' }]),
+}));
+
+// Mock specific exports
+jest.mock('./utils', () => ({
+  ...jest.requireActual('./utils'),
+  generateId: jest.fn().mockReturnValue('test-id'),
+}));
+```
+
+### Mock at Boundaries Only
+
+```
+Mock these:                    Don't mock these:
+├── Database calls             ├── Internal utility functions
+├── HTTP requests              ├── Business logic
+├── File system operations     ├── Data transformations
+├── External API calls         ├── Validation functions
+└── Time/Date (when needed)    └── Pure functions
+```
+
+## React/Component Testing
+
+```tsx
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+
+describe('TaskForm', () => {
+  it('submits the form with entered data', async () => {
+    const onSubmit = jest.fn();
+    render(<TaskForm onSubmit={onSubmit} />);
+
+    // Find elements by accessible role/label (not test IDs)
+    await screen.findByRole('textbox', { name: /title/i });
+    fireEvent.change(screen.getByRole('textbox', { name: /title/i }), {
+      target: { value: 'New Task' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({ title: 'New Task' });
+    });
+  });
+
+  it('shows validation error for empty title', async () => {
+    render(<TaskForm onSubmit={jest.fn()} />);
+
+    fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+    expect(await screen.findByText(/title is required/i)).toBeInTheDocument();
+  });
+});
+```
+
+## API / Integration Testing
+
+```typescript
+import request from 'supertest';
+import { app } from '../src/app';
+
+describe('POST /api/tasks', () => {
+  it('creates a task and returns 201', async () => {
+    const response = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'Test Task' })
+      .set('Authorization', `Bearer ${testToken}`)
+      .expect(201);
+
+    expect(response.body).toMatchObject({
+      id: expect.any(String),
+      title: 'Test Task',
+      status: 'pending',
+    });
+  });
+
+  it('returns 422 for invalid input', async () => {
+    const response = await request(app)
+      .post('/api/tasks')
+      .send({ title: '' })
+      .set('Authorization', `Bearer ${testToken}`)
+      .expect(422);
+
+    expect(response.body.error.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('returns 401 without authentication', async () => {
+    await request(app)
+      .post('/api/tasks')
+      .send({ title: 'Test' })
+      .expect(401);
+  });
+});
+```
+
+## E2E Testing (Playwright)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('user can create and complete a task', async ({ page }) => {
+  // Navigate and authenticate
+  await page.goto('/');
+  await page.fill('[name="email"]', 'test@example.com');
+  await page.fill('[name="password"]', 'testpass123');
+  await page.click('button:has-text("Log in")');
+
+  // Create a task
+  await page.click('button:has-text("New Task")');
+  await page.fill('[name="title"]', 'Buy groceries');
+  await page.click('button:has-text("Create")');
+
+  // Verify task appears
+  await expect(page.locator('text=Buy groceries')).toBeVisible();
+
+  // Complete the task
+  await page.click('[aria-label="Complete Buy groceries"]');
+  await expect(page.locator('text=Buy groceries')).toHaveCSS(
+    'text-decoration-line', 'line-through'
+  );
+});
+```
+
+## Test Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|---|---|---|
+| Testing implementation details | Breaks on refactor | Test inputs/outputs |
+| Snapshot everything | No one reviews snapshot diffs | Assert specific values |
+| Shared mutable state | Tests pollute each other | Setup/teardown per test |
+| Testing third-party code | Wastes time, not your bug | Mock the boundary |
+| Skipping tests to pass CI | Hides real bugs | Fix or delete the test |
+| Using `test.skip` permanently | Dead code | Remove or fix it |
+| Overly broad assertions | Doesn't catch regressions | Be specific |
+| No async error handling | Swallowed errors, false passes | Always `await` async tests |

package/skills/code-review-and-quality/README.md

@@ -0,0 +1,13 @@
+# code-review-and-quality
+
+Multi-axis code review (correctness, readability, architecture, security, performance) with severity labels (Blocker, Required, Optional, Nit, FYI).
+
+| Field | Value |
+|-------|-------|
+| Version | 1.0.0 |
+| Trigger | `/review`, "code review", "PR review", "merge gate", "five-axis review" |
+| PT trigger | `/revisar`, "revisão de código", "revisão de PR" |
+
+**Do not use for** in-flight decisions on non-trivial work (that's `/harden`), single-line typo fixes, or when the user explicitly skips review.
+
+See [SKILL.md](SKILL.md) for the full process.