ai-playbook 1.0.0

package/roles/software-developer/frontend/testing/best-practices.md

@@ -0,0 +1,272 @@
+# Testing: Best Practices
+
+Testing is your safety net for confident refactoring and deployment. This guide covers how to write tests that catch real bugs while staying maintainable.
+
+## Test Behavior, Not Implementation
+
+Tests should verify what the component does, not how it does it. Implementation details change; behavior should remain stable.
+
+```javascript
+// BAD: Tests implementation (useState, specific function calls)
+function Counter() {
+  const [count, setCount] = useState(0);
+  return (
+    <div>
+      <div>{count}</div>
+      <button onClick={() => setCount(count + 1)}>Increment</button>
+    </div>
+  );
+}
+
+test('Counter uses useState', () => {
+  // Can't test useState directly - this is implementation detail
+  // This test breaks if we refactor to use a state manager
+});
+
+// GOOD: Test behavior (what user sees and can do)
+test('Counter increments when button clicked', () => {
+  render(<Counter />);
+  
+  expect(screen.getByText('0')).toBeInTheDocument();
+  
+  fireEvent.click(screen.getByRole('button', { name: /increment/i }));
+  
+  expect(screen.getByText('1')).toBeInTheDocument();
+});
+```
+
+## Arrange-Act-Assert Pattern
+
+Structure every test with three clear phases: setup, action, assertion.
+
+```javascript
+test('Form submits user data', () => {
+  // Arrange: Set up test conditions
+  const handleSubmit = jest.fn();
+  render(<UserForm onSubmit={handleSubmit} />);
+  
+  // Act: User action
+  fireEvent.change(screen.getByLabelText(/name/i), {
+    target: { value: 'Alice' }
+  });
+  fireEvent.change(screen.getByLabelText(/email/i), {
+    target: { value: 'alice@example.com' }
+  });
+  fireEvent.click(screen.getByRole('button', { name: /submit/i }));
+  
+  // Assert: Expected outcome
+  expect(handleSubmit).toHaveBeenCalledWith({
+    name: 'Alice',
+    email: 'alice@example.com'
+  });
+});
+```
+
+## Test Isolated Units
+
+Each test should focus on one component or function. Use mocking to isolate dependencies.
+
+```javascript
+// GOOD: Test one component in isolation
+function UserCard({ userId }) {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    fetchUser(userId).then(setUser);
+  }, [userId]);
+  
+  return user ? <div>{user.name}</div> : <div>Loading...</div>;
+}
+
+// Mock the external dependency
+jest.mock('./api', () => ({
+  fetchUser: jest.fn()
+}));
+
+test('UserCard displays user after loading', async () => {
+  fetchUser.mockResolvedValue({ name: 'Bob' });
+  
+  render(<UserCard userId={1} />);
+  
+  expect(screen.getByText('Loading...')).toBeInTheDocument();
+  
+  await waitFor(() => {
+    expect(screen.getByText('Bob')).toBeInTheDocument();
+  });
+});
+```
+
+## Mock Strategically
+
+Mock external dependencies (APIs, libraries) but test real component logic.
+
+```javascript
+// BAD: Over-mocking
+test('Button works', () => {
+  const mockClick = jest.fn();
+  // Mocking everything makes test useless
+  const Button = jest.fn(() => <button />);
+  
+  render(<Button onClick={mockClick} />);
+  // Not testing the real component anymore!
+});
+
+// GOOD: Mock external, test real logic
+function SubmitButton({ onSubmit }) {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  
+  const handleClick = async () => {
+    setLoading(true);
+    try {
+      await onSubmit();
+      setError(null);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+  
+  return (
+    <>
+      <button onClick={handleClick} disabled={loading}>
+        {loading ? 'Submitting...' : 'Submit'}
+      </button>
+      {error && <div role="alert">{error}</div>}
+    </>
+  );
+}
+
+test('SubmitButton shows loading and error states', async () => {
+  const mockSubmit = jest.fn().mockRejectedValue(
+    new Error('Network error')
+  );
+  
+  render(<SubmitButton onSubmit={mockSubmit} />);
+  
+  // Click button
+  fireEvent.click(screen.getByRole('button'));
+  
+  // Should show loading
+  expect(screen.getByRole('button')).toHaveTextContent('Submitting...');
+  expect(screen.getByRole('button')).toBeDisabled();
+  
+  // Should show error after submission fails
+  await waitFor(() => {
+    expect(screen.getByRole('alert')).toHaveTextContent('Network error');
+  });
+});
+```
+
+## Test Coverage Guidelines
+
+- Aim for 80%+ coverage on business logic
+- Coverage numbers matter less than meaningful tests
+- 100% coverage with bad tests is worse than 70% coverage with good tests
+
+```javascript
+// Test happy path, error path, and edge cases
+function parseUserInput(input) {
+  if (!input) throw new Error('Input required');
+  if (typeof input !== 'string') throw new Error('Must be string');
+  
+  const trimmed = input.trim();
+  if (trimmed.length === 0) throw new Error('Cannot be empty');
+  
+  return trimmed.toLowerCase();
+}
+
+test('parseUserInput: happy path', () => {
+  expect(parseUserInput('  Hello  ')).toBe('hello');
+});
+
+test('parseUserInput: null input', () => {
+  expect(() => parseUserInput(null)).toThrow('Input required');
+});
+
+test('parseUserInput: non-string input', () => {
+  expect(() => parseUserInput(123)).toThrow('Must be string');
+});
+
+test('parseUserInput: whitespace-only input', () => {
+  expect(() => parseUserInput('   ')).toThrow('Cannot be empty');
+});
+```
+
+## Async Testing
+
+Handle promises and timers carefully. Use async/await and waitFor.
+
+```javascript
+test('Async operation completes', async () => {
+  render(<DataLoader />);
+  
+  // Wait for async operation
+  const result = await screen.findByText('Data loaded');
+  
+  expect(result).toBeInTheDocument();
+});
+
+test('Handles delayed state updates', async () => {
+  jest.useFakeTimers();
+  
+  render(<Debounced />);
+  
+  fireEvent.change(screen.getByRole('textbox'), {
+    target: { value: 'search' }
+  });
+  
+  // Debounced function hasn't run yet
+  expect(mockFn).not.toHaveBeenCalled();
+  
+  // Fast-forward time
+  jest.advanceTimersByTime(500);
+  
+  // Now it should have run
+  expect(mockFn).toHaveBeenCalled();
+  
+  jest.useRealTimers();
+});
+```
+
+## Test Naming
+
+Write descriptive test names that explain what is being tested and expected outcome.
+
+```javascript
+// BAD: Unclear
+test('works', () => { ... });
+test('error', () => { ... });
+test('loading', () => { ... });
+
+// GOOD: Describes behavior
+test('UserForm displays validation error when email is invalid', () => { ... });
+test('API call retries after network timeout', () => { ... });
+test('Modal closes when escape key is pressed', () => { ... });
+
+// Pattern: "should [expected behavior] when [condition]"
+test('should disable submit button when form is invalid', () => { ... });
+test('should show error message when API fails', () => { ... });
+test('should redirect to home when not authenticated', () => { ... });
+```
+
+## Testing Best Practices Checklist
+
+- [ ] Tests verify behavior, not implementation
+- [ ] Each test follows Arrange-Act-Assert structure
+- [ ] Tests are independent and can run in any order
+- [ ] External dependencies are mocked appropriately
+- [ ] Happy path, error path, and edge cases covered
+- [ ] Async operations tested with waitFor or findBy
+- [ ] Test names clearly describe what is being tested
+- [ ] No tests for implementation details (internal state, specific function calls)
+- [ ] Tests run quickly (< 5 seconds per test)
+- [ ] Coverage is meaningful, not just high percentage
+
+## Related Guidance
+
+- `/components` — designing testable components  
+- `/code-quality` — code organization for testability  
+- `/debugging` — debugging failing tests  
+- `/tools-setup` — testing tools and configuration

package/roles/software-developer/fullstack/README.md

@@ -0,0 +1,25 @@
+# Fullstack
+
+Use this packet when a change crosses frontend, backend, API, persistence, and
+deployment boundaries.
+
+## Scope
+
+- UI-to-API workflows, forms, dashboards, and end-to-end product features.
+- Contract changes that require coordinated frontend and backend updates.
+- Feature flags, staged rollouts, and backward compatibility.
+
+## Standards
+
+- Define the user workflow and API contract together.
+- Keep frontend and backend validation consistent without duplicating fragile logic.
+- Roll out breaking changes in compatible phases.
+- Verify the full path, not just isolated layers.
+
+## Related Files
+
+- `../frontend/`
+- `../api/`
+- `../backend/`
+- `../database/`
+- `../integration-tests/`

package/roles/software-developer/fullstack/checklists.md

@@ -0,0 +1,19 @@
+# Fullstack Checklists
+
+## Design
+
+- [ ] Define the user flow, API contract, data model, and rollout sequence.
+- [ ] Identify compatibility requirements for old clients and old servers.
+- [ ] Decide feature flag, migration, and fallback behavior.
+
+## Implementation
+
+- [ ] Update frontend states: loading, empty, error, success, and permission denied.
+- [ ] Update backend validation, authorization, persistence, and observability.
+- [ ] Keep contract fixtures or generated clients synchronized.
+
+## Verification
+
+- [ ] Add frontend behavior tests and backend contract tests.
+- [ ] Run an end-to-end or integration check for the complete workflow.
+- [ ] Verify rollout and rollback steps.

package/roles/software-developer/fullstack/examples.md

@@ -0,0 +1,14 @@
+# Fullstack Examples
+
+## Coordinated Contract Change
+
+```text
+Goal: Add "display_name" to user profile editing.
+
+1. Add nullable database column.
+2. Add API response field while accepting old clients.
+3. Update frontend form and validation.
+4. Add integration test for save-and-render flow.
+5. Backfill display names.
+6. Make field required only after clients are deployed.
+```

package/roles/software-developer/graphql/README.md

@@ -0,0 +1,24 @@
+# GraphQL
+
+Use this packet for GraphQL schemas, resolvers, mutations, subscriptions, and
+client contracts.
+
+## Scope
+
+- Schema design, field naming, input types, mutations, pagination, and errors.
+- Resolver behavior, batching, data loading, authorization, and complexity limits.
+- Schema evolution, deprecation, compatibility, and generated clients.
+
+## Standards
+
+- Treat the schema as a public contract.
+- Keep resolvers thin and delegate business behavior to services.
+- Add authorization checks at resolver or service boundaries.
+- Prevent N+1 queries with batching or data loaders.
+- Use deprecation before removal.
+
+## Related Files
+
+- `../api/` for contract principles.
+- `../authorization/` for field and object access.
+- `../performance/` for query cost and N+1 concerns.

package/roles/software-developer/graphql/checklists.md

@@ -0,0 +1,20 @@
+# GraphQL Checklists
+
+## Design
+
+- [ ] Define schema changes, nullability, pagination, and deprecation impact.
+- [ ] Identify resolver data sources and authorization rules.
+- [ ] Define query complexity, depth, and rate limits.
+
+## Implementation
+
+- [ ] Keep resolver code small and call service-layer functions.
+- [ ] Use data loaders or batching for repeated entity lookups.
+- [ ] Return typed domain errors instead of leaking internal exceptions.
+- [ ] Update generated client types or schema artifacts.
+
+## Verification
+
+- [ ] Add resolver tests for allowed, denied, missing, and invalid inputs.
+- [ ] Test query complexity limits and N+1-sensitive paths.
+- [ ] Verify schema compatibility for existing clients.

package/roles/software-developer/graphql/examples.md

@@ -0,0 +1,24 @@
+# GraphQL Examples
+
+## Resolver Shape
+
+```typescript
+const resolvers = {
+  Query: {
+    project: async (_parent, args, context) => {
+      const project = await context.projectService.getProject(args.id);
+      context.authz.requireProjectAccess(context.principal, project, 'read');
+      return project;
+    },
+  },
+};
+```
+
+## Deprecation
+
+```graphql
+type User {
+  name: String @deprecated(reason: "Use displayName.")
+  displayName: String!
+}
+```

package/roles/software-developer/integration-tests/README.md

@@ -0,0 +1,25 @@
+# Integration Tests
+
+Use this packet when testing multiple components together: service plus database,
+API plus worker, frontend plus API, or external dependency contracts.
+
+## Scope
+
+- Contract tests, service integration tests, database-backed tests, and workflow tests.
+- Test containers, fixtures, seeded data, mocks, fakes, and sandbox services.
+- Boundary verification across modules, processes, or infrastructure.
+
+## Standards
+
+- Test behavior at real boundaries when unit tests cannot catch integration risk.
+- Keep fixtures explicit and isolated.
+- Prefer deterministic fakes over brittle live third-party calls.
+- Clean up data and resources after tests.
+- Keep integration tests slower than unit tests but still reliable.
+
+## Related Files
+
+- `../testing/`
+- `../unit-tests/`
+- `../api/`
+- `../database/`

package/roles/software-developer/integration-tests/checklists.md

@@ -0,0 +1,20 @@
+# Integration Test Checklists
+
+## Design
+
+- [ ] Identify the boundary that must be verified.
+- [ ] Decide which dependencies are real, fake, mocked, or containerized.
+- [ ] Define seed data, cleanup strategy, and isolation model.
+
+## Implementation
+
+- [ ] Use stable fixtures and explicit setup.
+- [ ] Avoid depending on test order.
+- [ ] Use realistic serialization, persistence, and auth behavior.
+- [ ] Capture logs or diagnostics for failure triage.
+
+## Verification
+
+- [ ] Run the test alone and with the full suite.
+- [ ] Confirm failures are deterministic and actionable.
+- [ ] Confirm cleanup leaves no shared state behind.

package/roles/software-developer/integration-tests/examples.md

@@ -0,0 +1,18 @@
+# Integration Test Examples
+
+## API Plus Database
+
+```python
+async def test_create_user_persists_and_returns_contract(api_client, db):
+    response = await api_client.post(
+        "/v1/users",
+        json={"email": "ada@example.com", "display_name": "Ada"},
+    )
+
+    assert response.status_code == 201
+    body = response.json()
+    assert body["email"] == "ada@example.com"
+
+    row = await db.fetch_one("select email from users where id = :id", {"id": body["id"]})
+    assert row["email"] == "ada@example.com"
+```

package/roles/software-developer/java/README.md

@@ -0,0 +1,24 @@
+# Java
+
+Use this packet for Java application code, libraries, services, tests, and build
+configuration.
+
+## Scope
+
+- Java language features, collections, concurrency, streams, exceptions, and generics.
+- JVM service code, dependency injection, persistence, and API integration.
+- Maven or Gradle builds, static analysis, and test suites.
+
+## Standards
+
+- Favor clear object boundaries and immutable value objects.
+- Use checked and unchecked exceptions intentionally.
+- Keep concurrency explicit and bounded.
+- Use dependency injection for external collaborators.
+- Add unit and integration tests for public behavior.
+
+## Related Files
+
+- `../springboot/` for Spring Boot-specific guidance.
+- `../backend/` for service design.
+- `../testing/` and `../unit-tests/` for verification.

package/roles/software-developer/java/checklists.md

@@ -0,0 +1,16 @@
+# Java Checklists
+
+## Implementation
+
+- [ ] Use project formatting, static analysis, and build conventions.
+- [ ] Keep public APIs typed and documented when reused across modules.
+- [ ] Prefer constructor injection for required dependencies.
+- [ ] Handle nullability explicitly with validation, annotations, or Optional where appropriate.
+- [ ] Avoid blocking calls in async or reactive flows unless isolated.
+
+## Verification
+
+- [ ] Add unit tests for business rules.
+- [ ] Add integration tests for persistence, messaging, or HTTP clients when touched.
+- [ ] Run the relevant Maven or Gradle test target.
+- [ ] Check logs for noisy stack traces or swallowed exceptions.

package/roles/software-developer/java/examples.md

@@ -0,0 +1,22 @@
+# Java Examples
+
+## Service Shape
+
+```java
+public final class InvoiceService {
+    private final InvoiceRepository invoices;
+    private final PaymentGateway payments;
+
+    public InvoiceService(InvoiceRepository invoices, PaymentGateway payments) {
+        this.invoices = invoices;
+        this.payments = payments;
+    }
+
+    public Invoice capture(String invoiceId, Principal principal) {
+        Invoice invoice = invoices.getForUpdate(invoiceId);
+        invoice.requirePermission(principal, "capture");
+        payments.capture(invoice.paymentId(), invoice.id());
+        return invoices.save(invoice.markCaptured());
+    }
+}
+```

package/roles/software-developer/javascript/README.md

@@ -0,0 +1,24 @@
+# JavaScript
+
+Use this packet for JavaScript application code across browser, server, scripts,
+tests, and tooling.
+
+## Scope
+
+- Language behavior, modules, async flows, error handling, and runtime APIs.
+- Browser and Node.js code when TypeScript is not used.
+- Build tooling, package scripts, linting, and test setup.
+
+## Standards
+
+- Prefer explicit data shapes and runtime validation for external inputs.
+- Use `async` and `await` consistently for promise flows.
+- Avoid global mutable state unless the lifecycle is clear.
+- Keep side effects isolated and testable.
+- Use linting and formatting to catch common mistakes.
+
+## Related Files
+
+- `../typescript/` for typed JavaScript guidance.
+- `../node/` for Node.js runtime concerns.
+- `../frontend/` for browser UI code.

package/roles/software-developer/javascript/checklists.md

@@ -0,0 +1,15 @@
+# JavaScript Checklists
+
+## Implementation
+
+- [ ] Validate external data before use.
+- [ ] Handle promise rejection and cancellation paths.
+- [ ] Keep modules small and exports intentional.
+- [ ] Avoid mutating inputs unless explicitly documented.
+- [ ] Remove development-only console output before production.
+
+## Verification
+
+- [ ] Add tests for success, failure, and edge cases.
+- [ ] Run lint, format, and test scripts.
+- [ ] Check bundle or runtime impact when adding dependencies.

package/roles/software-developer/javascript/examples.md

@@ -0,0 +1,18 @@
+# JavaScript Examples
+
+## Safe Async Function
+
+```javascript
+export async function loadUser(apiClient, userId) {
+  if (!userId) {
+    throw new Error('userId is required');
+  }
+
+  const response = await apiClient.get(`/users/${encodeURIComponent(userId)}`);
+  if (!response.ok) {
+    throw new Error(`Failed to load user: ${response.status}`);
+  }
+
+  return response.json();
+}
+```