claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/_payload/skills/unit-test/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: unit-test
+description: Write unit tests for frontend components and hooks. Follows testing best practices focusing on user behavior over implementation details. Adapts to the project's test runner and component framework.
+argument-hint: [component or hook name]
+disable-model-invocation: true
+---
+
+Write unit tests for: $ARGUMENTS.
+
+## Steps
+
+1. **Read the target code**: Read the component or hook file for `$ARGUMENTS` to understand its props, behavior, state, and edge cases.
+
+2. **Identify what to test**:
+
+   ### Always Test
+   - Component renders without crashing (smoke test)
+   - Props produce expected visible output
+   - User interactions trigger expected behavior (click, type, submit)
+   - Conditional rendering: loading state, empty state, error state, data state
+   - Accessibility: correct roles, labels, ARIA attributes
+
+   ### Never Test
+   - Implementation details (internal state values, private functions)
+   - Third-party library behavior (UI libraries, chart libraries, state management internals)
+   - Exact CSS classes or styling utilities
+   - Mock data structure (the type checker handles this)
+   - Snapshot tests (fragile, noisy diffs)
+
+3. **Write the test file**: Create the test file following the project's test file naming convention (e.g., `<ComponentName>.test.tsx`, `<ComponentName>.spec.tsx`, or `__tests__/<ComponentName>.test.tsx`).
+
+   ### Test File Template (Component Testing Library Pattern)
+   ```typescript
+   import { render, screen } from '@testing-library/react';
+   import userEvent from '@testing-library/user-event';
+   import { describe, it, expect, vi } from 'vitest';  // or jest
+   import { ComponentName } from './ComponentName';
+
+   // Wrap in providers if needed (router, state management, etc.)
+   function renderComponent(props: Partial<ComponentNameProps> = {}) {
+     const defaultProps: ComponentNameProps = {
+       // sensible defaults
+     };
+     return render(<ComponentName {...defaultProps} {...props} />);
+   }
+
+   describe('ComponentName', () => {
+     it('renders with default props', () => {
+       renderComponent();
+       expect(screen.getByRole('...')).toBeInTheDocument();
+     });
+
+     it('displays the provided title', () => {
+       renderComponent({ title: 'Test Title' });
+       expect(screen.getByText('Test Title')).toBeInTheDocument();
+     });
+
+     it('calls onClick when button is clicked', async () => {
+       const user = userEvent.setup();
+       const handleClick = vi.fn();
+       renderComponent({ onClick: handleClick });
+
+       await user.click(screen.getByRole('button', { name: /action/i }));
+       expect(handleClick).toHaveBeenCalledOnce();
+     });
+
+     it('shows empty state when no data', () => {
+       renderComponent({ data: [] });
+       expect(screen.getByText(/no.*found/i)).toBeInTheDocument();
+     });
+
+     it('shows loading spinner when loading', () => {
+       renderComponent({ isLoading: true });
+       expect(screen.getByRole('status')).toBeInTheDocument();
+     });
+   });
+   ```
+
+4. **Follow query priority** (from Testing Library best practices):
+
+   | Priority | Method | When to Use |
+   |----------|--------|-------------|
+   | 1 | `getByRole` | Accessible elements (buttons, headings, links) |
+   | 2 | `getByLabelText` | Form inputs |
+   | 3 | `getByText` | Non-interactive text content |
+   | 4 | `getByDisplayValue` | Current input values |
+   | 5 | `getByTestId` | Last resort — add `data-testid` to element |
+
+5. **Handle providers and wrappers**:
+
+   ### Router Context (React Router example)
+   ```typescript
+   import { MemoryRouter } from 'react-router-dom';
+
+   function renderWithRouter(ui: React.ReactElement, { route = '/' } = {}) {
+     return render(
+       <MemoryRouter initialEntries={[route]}>{ui}</MemoryRouter>
+     );
+   }
+   ```
+
+   ### State Store Mocking (example for a state management library)
+   ```typescript
+   import { useAppStore } from '@/hooks/useAppStore';
+
+   vi.mock('@/hooks/useAppStore');
+
+   beforeEach(() => {
+     vi.mocked(useAppStore).mockImplementation((selector) =>
+       selector({
+         currentUser: { id: '1', name: 'Test User' },
+         // ... other store values
+       })
+     );
+   });
+   ```
+
+6. **Test async behavior**:
+   ```typescript
+   it('loads and displays data', async () => {
+     renderComponent();
+     // Wait for async content
+     expect(await screen.findByText('Expected Content')).toBeInTheDocument();
+   });
+   ```
+
+7. **Test accessibility**:
+   ```typescript
+   it('has accessible button labels', () => {
+     renderComponent();
+     expect(screen.getByRole('button', { name: 'Close dialog' })).toBeInTheDocument();
+   });
+
+   it('supports keyboard navigation', async () => {
+     const user = userEvent.setup();
+     renderComponent();
+     await user.tab();
+     expect(screen.getByRole('button')).toHaveFocus();
+   });
+   ```
+
+8. **Run tests**: Execute the project's test command (check `package.json` scripts or the project's test runner docs).
+
+## Test Organization
+
+```
+src/
+  components/
+    ui/
+      Button.tsx
+      Button.test.tsx         # Co-located test
+    FeatureCard.tsx
+    FeatureCard.test.tsx      # Co-located test
+  hooks/
+    useAppStore.ts
+    useAppStore.test.ts       # Hook tests
+  pages/
+    DashboardPage.tsx
+    DashboardPage.test.tsx    # Page-level tests (lighter, focused on integration)
+```
+
+## Conventions
+
+### Naming
+- Test files: Follow project convention (e.g., `<Component>.test.tsx`, `<Component>.spec.tsx`, or `<hook>.test.ts`)
+- Describe blocks: component/hook name
+- Test names: describe behavior in plain English — `it('shows error message when form is invalid')`
+
+### Assertions
+- Prefer `toBeInTheDocument()` over `toBeTruthy()`
+- Prefer `toHaveTextContent()` over checking `.textContent`
+- Use `toHaveAttribute()` for ARIA and HTML attributes
+- Use `not.toBeInTheDocument()` to assert absence (with `queryBy*`)
+
+### Mocking
+- Mock external dependencies, not internal logic
+- Use the test runner's mock function (e.g., `vi.fn()`, `jest.fn()`) for callback props
+- Use module-level mocks for state stores and API calls
+- Reset mocks in `beforeEach` or use the test runner's clear/reset utilities
+
+### Coverage Targets
+| Metric | Target |
+|--------|--------|
+| Statements | 70% |
+| Branches | 65% |
+| Functions | 70% |
+| Lines | 70% |
+
+Focus coverage on business logic and user-facing behavior, not boilerplate.
+
+## Setup Requirements
+
+The project's test runner and assertion library should be configured. Common stacks:
+
+### Example: Vitest + React Testing Library
+```bash
+# Install test dependencies (if not already installed)
+npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom @vitest/coverage-v8
+```
+
+### Example: Jest + React Testing Library
+```bash
+npm install -D jest @testing-library/react @testing-library/jest-dom @testing-library/user-event jest-environment-jsdom
+```
+
+### Test Runner Config (Vitest example)
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: './src/test/setup.ts',
+    include: ['src/**/*.test.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html'],
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: ['src/**/*.test.*', 'src/data/**', 'src/test/**'],
+    },
+  },
+  resolve: {
+    alias: { '@': path.resolve(__dirname, './src') },
+  },
+});
+```
+
+### Test Setup File (Testing Library example)
+```typescript
+// src/test/setup.ts
+import '@testing-library/jest-dom/vitest';  // or '@testing-library/jest-dom' for Jest
+```

claude_kit/_payload/skills/using-agent-skills/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: using-agent-skills
+description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
+---
+
+# Using Agent Skills
+
+## Overview
+
+Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.
+
+## Skill Discovery
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Don't know what you want yet? ──────→ interview-me
+    ├── Have a rough concept, need variants? → idea-refine
+    ├── New project/feature/change? ──→ spec-driven-development
+    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
+    ├── Implementing code? ────────────→ incremental-implementation
+    │   ├── UI work? ─────────────────→ frontend-ui-engineering
+    │   ├── API work? ────────────────→ api-and-interface-design
+    │   ├── Need better context? ─────→ context-engineering
+    │   ├── Need doc-verified code? ───→ source-driven-development
+    │   └── Stakes high / unfamiliar code? ──→ doubt-driven-development
+    ├── Writing/running tests? ────────→ test-driven-development
+    │   └── Browser-based? ───────────→ browser-testing-with-devtools
+    ├── Something broke? ──────────────→ debugging-and-error-recovery
+    ├── Reviewing code? ───────────────→ code-review-and-quality
+    │   ├── Security concerns? ───────→ security-and-hardening
+    │   └── Performance concerns? ────→ performance-optimization
+    ├── Committing/branching? ─────────→ git-workflow-and-versioning
+    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
+    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
+    └── Deploying/launching? ─────────→ shipping-and-launch
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about requirements]
+2. [assumption about architecture]
+3. [assumption about scope]
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications:
+
+1. **STOP.** Do not proceed with a guess.
+2. Name the specific confusion.
+3. Present the tradeoff or ask the clarifying question.
+4. Wait for resolution before continuing.
+
+**Bad:** Silently picking one interpretation and hoping it's right.
+**Good:** "I see X in the spec but Y in the existing code. Which takes precedence?"
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems:
+
+- Point out the issue directly
+- Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
+- Propose an alternative
+- Accept the human's decision if they override with full information
+
+Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Actively resist it.
+
+Before finishing any implementation, ask:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+
+If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch.
+
+Do NOT:
+- Remove comments you don't understand
+- "Clean up" code orthogonal to the task
+- Refactor adjacent systems as a side effect
+- Delete code that seems unused without explicit approval
+- Add features not in the spec because they "seem useful"
+
+Your job is surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
+
+## Failure Modes to Avoid
+
+These are the subtle errors that look like productivity but create problems:
+
+1. Making wrong assumptions without checking
+2. Not managing your own confusion — plowing ahead when lost
+3. Not surfacing inconsistencies you notice
+4. Not presenting tradeoffs on non-obvious decisions
+5. Being sycophantic ("Of course!") to approaches with clear problems
+6. Overcomplicating code and APIs
+7. Modifying code or comments orthogonal to the task
+8. Removing things you don't fully understand
+9. Building without a spec because "it's obvious"
+10. Skipping verification because "it looks right"
+
+## Skill Rules
+
+1. **Check for an applicable skill before starting work.** Skills encode processes that prevent common mistakes.
+
+2. **Skills are workflows, not suggestions.** Follow the steps in order. Don't skip verification steps.
+
+3. **Multiple skills can apply.** A feature implementation might involve `idea-refine` → `spec-driven-development` → `planning-and-task-breakdown` → `incremental-implementation` → `test-driven-development` → `code-review-and-quality` → `shipping-and-launch` in sequence.
+
+4. **When in doubt, start with a spec.** If the task is non-trivial and there's no spec, begin with `spec-driven-development`.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+```
+1.  interview-me                → Extract what the user actually wants
+2.  idea-refine                 → Refine vague ideas
+3.  spec-driven-development     → Define what we're building
+4.  planning-and-task-breakdown → Break into verifiable chunks
+5.  context-engineering         → Load the right context
+6.  source-driven-development   → Verify against official docs
+7.  incremental-implementation  → Build slice by slice
+8.  doubt-driven-development    → Cross-examine non-trivial decisions in-flight
+9.  test-driven-development     → Prove each slice works
+10. code-review-and-quality     → Review before merge
+11. git-workflow-and-versioning → Clean commit history
+12. documentation-and-adrs      → Document decisions
+13. shipping-and-launch         → Deploy safely
+```
+
+Not every task needs every skill. A bug fix might only need: `debugging-and-error-recovery` → `test-driven-development` → `code-review-and-quality`.
+
+## Quick Reference
+
+| Phase | Skill | One-Line Summary |
+|-------|-------|-----------------|
+| Define | interview-me | Surface what the user actually wants before any plan, spec, or code exists |
+| Define | idea-refine | Refine ideas through structured divergent and convergent thinking |
+| Define | spec-driven-development | Requirements and acceptance criteria before code |
+| Plan | planning-and-task-breakdown | Decompose into small, verifiable tasks |
+| Build | incremental-implementation | Thin vertical slices, test each before expanding |
+| Build | source-driven-development | Verify against official docs before implementing |
+| Build | doubt-driven-development | Adversarial fresh-context review of every non-trivial decision |
+| Build | context-engineering | Right context at the right time |
+| Build | frontend-ui-engineering | Production-quality UI with accessibility |
+| Build | api-and-interface-design | Stable interfaces with clear contracts |
+| Verify | test-driven-development | Failing test first, then make it pass |
+| Verify | browser-testing-with-devtools | Chrome DevTools MCP for runtime verification |
+| Verify | debugging-and-error-recovery | Reproduce → localize → fix → guard |
+| Review | code-review-and-quality | Five-axis review with quality gates |
+| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
+| Review | performance-optimization | Measure first, optimize only what matters |
+| Ship | git-workflow-and-versioning | Atomic commits, clean history |
+| Ship | ci-cd-and-automation | Automated quality gates on every change |
+| Ship | documentation-and-adrs | Document the why, not just the what |
+| Ship | shipping-and-launch | Pre-launch checklist, monitoring, rollback plan |

claude_kit/_payload/templates/CLAUDE.md

@@ -0,0 +1,238 @@
+# Engineering Delivery Rules
+
+These rules are mandatory for all work in this repository. They define an autonomous,
+agent-driven software development lifecycle (SDLC): every change moves through spec →
+review → implementation → code review → testing → security → delivery, with quality
+gates between phases.
+
+> Installed by **claude-kit**. The full pipeline, agents, skills, and rule details live in
+> `.claude/rules/`, `.claude/agents/`, and `.claude/skills/`. This file is the entry point.
+
+---
+
+## Coding Behavior (applies to ALL implementation work)
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+### Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+### Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan with a verification check per step.
+
+Strong success criteria let you loop independently. Weak criteria ("make it work")
+require constant clarification.
+
+---
+
+## 1) Spec-first rule
+Do not write implementation code until a written spec exists.
+
+Before coding:
+- identify whether a relevant spec already exists
+- if not, draft one first
+- if the task changes, update the spec before continuing
+
+A task is not ready for implementation until the spec is explicit enough to review.
+
+## 2) Review workflow before implementation
+Before writing code, follow this workflow:
+
+1. **Spec & Doc Writer** writes specification + developer documentation in a single pass
+2. **UI Designer** (if UI work) — drafts and self-reviews the design spec
+3. Spec is reviewed by the appropriate **Senior Developer** (per work stream)
+4. Spec is reviewed by the **Technical Architect** — validates system design, scalability, integration
+5. Spec is reviewed by the **Engineering Manager** — final strategic and completeness check
+6. **Implementation** starts only after all reviews are complete
+
+At any stage, reviewers may request corrections. If anything is missing, update the spec
+and re-run the affected review.
+
+### Parallel execution for multi-stream work
+When a task spans two or more **independent work streams** (the canonical example is a
+backend lane and a frontend lane, but it applies to any split — service A vs. service B,
+API vs. client, data layer vs. UI):
+
+- Each stream's review chain (Senior Developer → Technical Architect → EM) runs **in parallel**.
+- After all review chains pass, a **Merge Reviewer** verifies cross-stream consistency
+  (shared contracts, data models, shared state).
+- Implementation then runs **in parallel**, one stream per isolated worktree, each with
+  its own **Code Reviewer**.
+- After all implementations pass code review and unit tests, the **Merge Reviewer** verifies
+  integration compatibility.
+- Only then does integration testing proceed.
+
+Independent work streams must never block each other. Merge-reviewer gates ensure
+consistency at join points.
+
+## 3) Design-first workflow for UI changes
+For any frontend, UI, UX, or interaction change:
+
+1. the **UI Designer** drafts a design spec (includes self-review against a quality checklist)
+2. the design spec describes: screen states, interactions, component behavior,
+   empty/loading/error states, responsive behavior, accessibility
+3. UI implementation begins only after the design spec is complete
+
+Do not start UI implementation from a vague request when a design spec is required.
+
+## 4) Required roles
+Each role maps to a dedicated agent in `.claude/agents/`:
+
+**Spec & Documentation:** Spec & Doc Writer · UI Designer
+**Review chain (per work stream):** Senior Developer · Technical Architect · Engineering Manager
+**Implementation & code review:** Developer · Code Reviewer
+**Testing:** Tester · Senior Tester · Unit Tester · E2E Tester
+**Security:** Security Reviewer + sub-scanners (Secret · Dependency · OWASP · Policy)
+**Review rigor:** Devil's Advocate (anti-sycophancy, on a unanimous PASS)
+**Integration:** Merge Reviewer
+**Delivery & operability:** DevOps Engineer · Observability Engineer · PR Raiser
+**Coordination:** Orchestrator (never writes code — only delegates and gates)
+
+State which role is being simulated at each stage when it helps clarity.
+
+## 5) Testing workflow
+After implementation, testing runs in parallel lanes for multi-stream work:
+
+- **Tester phase (parallel):** API/contract tester · UI tester · integration (end-to-end) tester
+- **Senior Tester phase (parallel, after testers):** each independently verifies a tester's
+  coverage and findings
+- **Test-coverage merge review:** the Merge Reviewer confirms every acceptance criterion is
+  covered across lanes, with no gaps and no contradictions
+
+For single-stream or small features, a single Tester + single Senior Tester is sufficient.
+Testing is not complete until senior verification AND the coverage merge review pass.
+
+## 6) Defect loop
+If any failure, defect, regression, or spec mismatch is found:
+
+1. document the issue clearly and classify it by work stream
+2. update the spec if expected behavior is unclear
+3. re-run **only the affected stream(s)** through their chain
+4. re-run the Merge Reviewer for cross-stream consistency
+5. then re-run Tester → Senior Tester for the affected lanes only
+
+Do not patch defects informally outside the process. Do not re-run unaffected lanes.
+
+## 7) Output expectations
+For each meaningful task, produce outputs in this order unless explicitly overridden:
+
+1. feature spec + developer documentation
+2. design spec (if UI work)
+3. review notes (senior developer → technical architect → EM, per stream)
+4. merge review (spec consistency) — multi-stream only
+5. implementation / code changes
+6. code review notes (per stream)
+7. merge review (code integration) — multi-stream only
+8. tester reports → senior tester verification → test-coverage merge review
+9. security review (Security Clear)
+10. DevOps (Pipeline Green) + Observability (Observability Ready) — for deployable/observable changes
+11. final summary with open issues, if any
+
+## 8) Quality bar
+Optimize for: simplicity, correctness, scalability, reliability, maintainability,
+observability, testability, security, and user experience.
+
+## 9) Documentation standard
+Every change must maintain or improve documentation. See `.claude/rules/documentation.md`.
+
+Mandatory for every change:
+- **Module/file docstring or header** in every new/modified source file
+- **Docstring on every public function** (arguments, return value, errors/exceptions raised)
+- **Full type annotations** where the language supports them — no untyped public signatures
+- **No bare/loose container types** — prefer named, typed structures over opaque maps
+- **README updated** when endpoints, env vars, project structure, or architecture change
+- **API metadata** (summary, response schema, status codes) on every endpoint, where applicable
+
+## 10) Guardrails
+Do not:
+- skip the spec + dev-doc stage
+- skip the design flow for UI work
+- skip the senior developer, technical architect, or EM review
+- skip the code review
+- mark work complete without tester validation
+- mark testing complete without senior tester verification
+- skip the merge reviewer at join points for multi-stream work
+- submit code with missing docstrings or type annotations
+- submit code without updating the README when endpoints or architecture changed
+
+If the user asks for speed, you may compress the process but must preserve the sequence
+and outputs.
+
+**Fast-track mode:** For bug fixes, typos, single-component changes, or config updates
+(< 5 files), skip the spec/design/review chain and go straight to:
+Developer → Code Reviewer → Tester → PR Raiser.
+
+See `.claude/rules/mandatory-workflow.md` for the full step-by-step pipeline with agent
+roles, gating rules, and the defect-loop protocol.
+
+---
+
+## 11) Working memory, self-check & quality gates
+
+- **Working memory:** read/write `.claude/CONTINUITY.md` every turn and at each stage
+  transition so work survives context compaction and new sessions. Distinct from
+  `.claude/agent-memory/` (durable learnings). See `.claude/rules/continuity.md`.
+- **RARV:** every agent runs Reason → Act → Reflect → Verify and shows a green Verify
+  before handoff. See `.claude/rules/rarv-cycle.md`.
+- **Severity model:** classify every finding Critical/High/Medium/Low/Cosmetic; a gate
+  passes only with zero Critical/High/Medium open. See `.claude/rules/quality-gates.md`.
+- **Blind review + Devil's Advocate:** parallel reviewers assess independently; a unanimous
+  PASS triggers the `devils-advocate` agent before the gate counts. See `.claude/rules/quality-gates.md`.
+- **Security review:** the `security-reviewer` dispatches `secret-scanner`,
+  `dependency-scanner`, `owasp-reviewer`, and `policy-validator`, and gates **Security Clear**
+  before delivery. See `.claude/rules/quality-gates.md`.
+- **DevOps & Observability:** for changes touching a deployable/observable surface, the
+  `devops-engineer` (Pipeline Green) and `observability-engineer` (Observability Ready)
+  gates run after testing and before the PR. See `.claude/rules/devops-observability.md`.
+
+---
+
+## Project-specific rules
+
+> Add your stack's conventions here (language style, framework patterns, naming, directory
+> layout, test commands). The pipeline is stack-agnostic; this section is where you make it
+> yours. Add matching rule files under `.claude/rules/` and reference them from the relevant
+> agents.