@juicesharp/rpiv-pi 0.4.0

package/skills/annotate-inline/examples/root-nodejs-monorepo.md

@@ -0,0 +1,42 @@
+# CLAUDE.md
+
+Express API + React frontend in a Turborepo monorepo.
+
+## Project map
+
+- `apps/api/` - Express REST API
+- `apps/web/` - React SPA
+- `packages/db/` - Prisma schema and client
+- `packages/ui/` - Shared component library
+- `packages/config/` - Shared configuration
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `turbo build` | Build all packages |
+| `turbo test` | Run all tests |
+| `turbo lint` | Lint all packages |
+| `turbo dev` | Start dev server |
+| `turbo db:generate` | Regenerate Prisma client after schema changes |
+| `turbo db:migrate` | Run database migrations |
+
+<important if="you are adding or modifying API routes">
+- All routes go in `apps/api/src/routes/`
+- Use Zod for request validation — see `apps/api/src/routes/connections.ts` for the pattern
+- Error responses follow RFC 7807 format
+- Authentication via JWT middleware
+</important>
+
+<important if="you are writing or modifying tests">
+- API: Jest + Supertest, Frontend: Vitest + Testing Library
+- Test fixtures in `__fixtures__/` directories
+- Use `createTestClient()` helper for API integration tests
+- Mock database with `prismaMock` from `packages/db/test`
+</important>
+
+<important if="you are working with client-side state, stores, or data fetching">
+- Zustand for global client state
+- React Query for server state
+- URL state via `nuqs`
+</important>

package/skills/annotate-inline/examples/subfolder-database-layer.md

@@ -0,0 +1,81 @@
+# Database Layer Architecture
+
+## Responsibility
+SQLite persistence with better-sqlite3, repository pattern (plain types), QueryQueue concurrency, type transformations.
+
+## Dependencies
+- **better-sqlite3**: Native SQLite (requires rebuild for Electron)
+- **@redis-ui/core**: Domain types
+- **p-queue**: Query serialization
+
+## Consumers
+- **@redis-ui/services**: Repositories via RepositoryFactory
+- **Main process**: DatabaseManager initialization
+
+## Module Structure
+```
+src/
+├── DatabaseManager.ts, QueryQueue.ts   # Singleton, concurrency
+├── BaseRepository.ts, RepositoryFactory.ts
+├── schema.ts
+└── repositories/                        # One repo per entity
+```
+
+## Repository Boundary (CRITICAL: Plain Types, NOT Result<T>)
+
+```typescript
+export class ConnectionRepository extends BaseRepository<ConnectionDB, Connection, ConnectionId> {
+  protected toApplication(db: ConnectionDB): Connection {
+    return {
+      id: ConnectionId.create(db.id),
+      host: db.host,
+      port: db.port,
+      sslEnabled: Boolean(db.ssl_enabled),     // DB int → boolean
+      createdAt: new Date(db.created_at),      // timestamp → Date
+    };
+  }
+
+  async findById(id: ConnectionId): Promise<Connection | null> {
+    return this.queue.enqueueRead((db) => {
+      const row = db.prepare('SELECT * FROM connections WHERE id = ?').get(id);
+      return row ? this.toApplication(row) : null;
+    });
+  }
+}
+
+// Service: Wraps repository in Result<T>
+async createConnection(input: CreateInput): Promise<Result<Connection>> {
+  try {
+    const connection = await this.connectionRepo.create(input);
+    return Result.ok(connection);
+  } catch (error) {
+    return Result.fail(new InfrastructureError(error.message));
+  }
+}
+```
+
+## QueryQueue Pattern (Write Serialization)
+
+```typescript
+export class QueryQueue {
+  private writeQueue = new PQueue({ concurrency: 1 }) // Single writer
+  private readQueue = new PQueue({ concurrency: 5 })  // Multiple readers
+
+  async enqueueWrite<T>(op: (db: Database) => T): Promise<T> {
+    return this.writeQueue.add(() => op(this.db))
+  }
+}
+```
+
+## Architectural Boundaries
+- **NO Result<T> in repos**: Services wrap with Result
+- **NO unqueued DB ops**: Always use QueryQueue
+- **NO raw SQL in services**: Use repositories
+
+<important if="you are adding a new repository to this layer">
+## Adding a New Repository
+1. Create `XRepository.ts` extending `BaseRepository<XDB, X, XId>`
+2. Implement `toApplication()` and `toDatabase()` type mappers
+3. Register in `RepositoryFactory`
+4. Add table schema in `schema.ts`
+</important>

package/skills/annotate-inline/examples/subfolder-dotnet-application.md

@@ -0,0 +1,64 @@
+# Application Layer (CQRS + MediatR)
+
+## Responsibility
+Command/query handlers orchestrating domain logic via MediatR pipeline. Sits between API controllers and Domain layer.
+
+## Dependencies
+- **MediatR**: Command/query dispatch
+- **FluentValidation**: Request validation via pipeline behavior
+- **AutoMapper**: Domain ↔ DTO mapping
+
+## Consumers
+- **API Controllers**: Send commands/queries via `IMediator`
+- **Integration tests**: Direct handler invocation
+
+## Module Structure
+```
+Application/
+├── Common/
+│   ├── Behaviors/          # MediatR pipeline (validation, logging)
+│   └── Mappings/           # AutoMapper profiles
+├── Features/               # One folder per aggregate
+│   └── Orders/
+│       ├── Commands/       # CreateOrder/, UpdateOrder/ (handler + validator + DTO)
+│       └── Queries/        # GetOrder/, ListOrders/
+└── DependencyInjection.cs  # Service registration
+```
+
+## Handler Pattern (Command with Validation)
+
+```csharp
+public record CreateOrderCommand(string CustomerId, List<LineItemDto> Items)
+    : IRequest<Result<OrderDto>>;
+
+public class CreateOrderValidator : AbstractValidator<CreateOrderCommand> {
+    public CreateOrderValidator(IOrderRepository repo) {
+        RuleFor(x => x.CustomerId).NotEmpty();
+        RuleFor(x => x.Items).NotEmpty();
+    }
+}
+
+public class CreateOrderHandler : IRequestHandler<CreateOrderCommand, Result<OrderDto>> {
+    public async Task<Result<OrderDto>> Handle(
+        CreateOrderCommand request, CancellationToken ct) {
+        var order = Order.Create(request.CustomerId, request.Items); // Domain factory
+        await _repo.AddAsync(order, ct);
+        await _unitOfWork.SaveChangesAsync(ct);
+        return Result.Ok(_mapper.Map<OrderDto>(order));
+    }
+}
+```
+
+## Architectural Boundaries
+- **NO domain logic in handlers**: Handlers orchestrate, domain objects contain logic
+- **NO direct DbContext access**: Use repository abstractions
+- **NO cross-feature references**: Features are independent vertical slices
+
+<important if="you are adding a new feature or command/query handler">
+## Adding a New Feature
+1. Create folder under `Features/{Aggregate}/{Commands|Queries}/`
+2. Add `Command`/`Query` record implementing `IRequest<Result<TDto>>`
+3. Add `Validator` extending `AbstractValidator<TCommand>`
+4. Add `Handler` implementing `IRequestHandler<TCommand, Result<TDto>>`
+5. Add AutoMapper profile in `Common/Mappings/` if new DTO
+</important>

package/skills/annotate-inline/examples/subfolder-schemas-layer.md

@@ -0,0 +1,50 @@
+# Schemas Layer Architecture
+
+## Responsibility
+Zod validation schemas for dual-layer validation (preload UX + main security), type inference via z.infer<>.
+
+## Dependencies
+- **zod**: Runtime validation
+
+## Consumers
+- **@redis-ui/ipc**: Main process validation (security)
+- **Preload**: Fail-fast validation (UX)
+- **TypeScript**: Type inference
+
+## Module Structure
+```
+src/
+├── connection.ts, backup.ts    # Domain schemas
+└── __tests__/                  # Validation tests
+```
+
+## Complete Schema Pattern (Types + Validation + Composition)
+
+```typescript
+export const createConnectionSchema = z.object({
+  name: z.string().min(1).max(255),
+  host: z.string().min(1),
+  port: z.number().int().min(1).max(65535),
+  password: z.string().optional(),
+  database: z.number().int().min(0).max(15).default(0),
+})
+
+// Type inference
+export type CreateConnectionInput = z.infer<typeof createConnectionSchema>
+
+// Update schema (partial + ID required)
+export const updateConnectionSchema = createConnectionSchema.partial().extend({
+  id: z.string().min(1)
+})
+```
+
+## Dual-Validation Flow
+
+```
+Renderer input → Preload (Zod parse, fail fast) → IPC → Main (Zod parse again, security)
+```
+
+## Architectural Boundaries
+- **NO any types**: Use z.unknown()
+- **NO skipping validation**: Always validate at boundaries
+- **NO business logic**: Structure validation only

package/skills/annotate-inline/templates/root-claude-md.md

@@ -0,0 +1,46 @@
+```markdown
+# Project Overview
+[1-2 sentences: what it is, tech stack]
+
+# Architecture
+[monorepo structure tree + dependency flow diagram]
+[process architecture if applicable]
+
+# Commands
+[key commands table — always bare, never wrapped in <important if>]
+
+# Business Context
+[1-2 sentences if applicable]
+```
+
+The sections above (Overview, Architecture, Commands, Business Context) are foundational — they stay bare because they're relevant to virtually every task.
+
+Cross-cutting patterns and domain-specific conventions go in `<important if>` blocks with narrow, action-specific conditions. Do NOT group unrelated rules under a single broad condition like "you are writing or modifying code". Instead, shard by trigger.
+
+Root conditional blocks are for **cross-cutting conventions that don't belong to any single layer**. Layer-specific recipes (like "adding a new controller" or "adding a new repository") belong in the subfolder CLAUDE.md, not the root.
+
+**Deduplication rule:** If a layer has its own subfolder CLAUDE.md, do NOT add a root conditional block summarizing that layer's conventions. The subfolder file is the authoritative guide — the agent will see it when working in that directory. Root conditionals that mirror subfolder content waste attention budget and create staleness risk.
+
+Root MAY include cross-layer vertical-slice checklists (e.g., "adding a new domain entity end-to-end") that reference multiple subfolder CLAUDE.md files — but each step should point to the relevant subfolder for details, not inline them.
+
+Good root conditions — things that span multiple layers:
+
+```markdown
+<important if="you are writing or modifying tests">
+- Unit: xUnit + NSubstitute / Jest + Testing Library
+- Integration: WebApplicationFactory / Supertest
+- Test fixtures in `__fixtures__/` or `tests/Fixtures/`
+</important>
+
+<important if="you are adding or modifying database migrations">
+- Never modify existing migrations — always create new ones
+- Run `dotnet ef migrations add` / `turbo db:migrate` after schema changes
+</important>
+
+<important if="you are adding or modifying environment configuration">
+- All config via `IOptions<T>` pattern / environment variables
+- Secrets in user-secrets locally, Key Vault in production
+</important>
+```
+
+Each block should contain only rules that share the same trigger condition. If a codebase has 3 distinct convention areas, that's 3 blocks — not 1 block with a broad condition. Layer-specific checklists (adding a controller, adding a repository) go in the subfolder CLAUDE.md using `<important if="you are adding a new [entity] to this layer">`.

package/skills/annotate-inline/templates/subfolder-claude-md.md

@@ -0,0 +1,57 @@
+```markdown
+# [Layer/Component Name]
+
+## Responsibility
+[1-2 sentences: what this layer does, where it sits in architecture]
+
+## Dependencies
+[List only architectural dependencies — frameworks and libraries that shape how you write code in this layer.
+Do NOT list utility libraries discoverable from package.json/imports (e.g., lodash, moment, xlsx).
+A dependency is worth listing if it imposes patterns, constraints, or conventions on the code.]
+- **[dep]**: Why it's used
+
+## Consumers
+- **[consumer]**: How it uses this layer
+
+## Module Structure
+[Compact directory tree — aim for 4-7 top-level entries, not 15.
+Group related files on one line (e.g., "Service.ts, Handler.ts").
+Use architectural annotations for directories (e.g., "# One repo per entity", "# Domain schemas").
+DO NOT enumerate individual files inside directories — describe the convention.
+When a layer has many directories (10+), group related concerns on one line
+(e.g., "guards/, interceptors/, pipes/ — infrastructure plumbing") rather than listing each separately.
+The structure must stay valid when non-architectural files are added.]
+
+## [Pattern Name] ([Key Constraint or Characterization])
+[Each distinct pattern gets its own H2 section — NOT a generic "## Key Patterns" umbrella.
+Include a fenced code block with an idiomatic, generalized example showing:
+- Constructor / dependencies
+- Key method signatures and return types
+- Error handling / wrapping conventions
+- Inline comments for important conventions (e.g., "// throws on error — service wraps in Result")
+If a pattern spans a layer boundary, show both sides briefly.
+Multiple patterns = multiple H2 sections.]
+
+## [Additional Pattern Name]
+[Second pattern with code block if applicable]
+
+## Architectural Boundaries
+- **NO [X]**: [Why]
+- **NO [Y]**: [Why]
+
+<important if="you are adding a new [entity type] to this layer">
+## Adding a New [Entity Type]
+[Step-by-step checklist inferred from existing code:
+1. Create file following naming convention
+2. Extend/implement base class or interface
+3. Register in factory/container/index
+4. Add related artifacts (schema, test, migration)]
+</important>
+
+<important if="you are writing or modifying tests for this layer">
+## Testing Conventions
+[Test patterns, helpers, fixture locations, mocking approach — if detectable from code]
+</important>
+```
+
+Conditional sections are OPTIONAL — only include them if the pattern-finder skill detects testable patterns or clear "add new entity" workflows. Conditions must be narrow and action-specific. These sections contain checklists/recipes, not code examples (those stay in the unconditional pattern sections). Conditional sections do NOT count toward the 100-line budget for unconditional content.

package/skills/code-review/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: code-review
+description: Conduct comprehensive code reviews by analyzing changes in parallel. Produces review documents in thoughts/shared/reviews/. Use when changes are ready for review.
+argument-hint: [scope]
+allowed-tools: Read, Bash(git *), Glob, Grep, Agent
+---
+
+# Code Review System
+
+You are tasked with conducting comprehensive code reviews by invoking parallel skills to analyze changes and synthesize their findings into actionable feedback.
+
+## Initial Setup:
+
+When this command is invoked, respond with:
+```
+I'm ready to perform a code review. Please specify what you'd like reviewed:
+- Latest commit(s)
+- Staged changes (git diff --cached)
+- Working directory changes (git diff)
+- Specific commit hash or range
+- Pull request (provide PR number or branch)
+
+You can also specify focus areas or review depth.
+```
+
+Then wait for the user's review request.
+
+## Steps to follow after receiving the review request:
+
+1. **Read the changes to review:**
+   - Determine what needs reviewing based on user input
+   - Use appropriate git commands to get the diff:
+     - Latest commit: `git diff HEAD~1 HEAD`
+     - Staged: `git diff --cached`
+     - Working: `git diff`
+   - **IMPORTANT**: Read the full diff output FIRST before invoking any skills
+   - Get list of changed files and understand the scope
+   - Note commit messages for context
+
+2. **Analyze and decompose the review:**
+   - Break down the changes into reviewable areas
+   - Take time to ultrathink about patterns, security implications, and architectural impacts
+   - Identify which components are affected
+   - Create a review plan using the `todo` tool to track all aspects
+   - Consider which existing patterns and historical decisions are relevant
+
+3. **Spawn parallel agents for comprehensive review:**
+   - Plan first then spawn multiple agents to review different aspects concurrently using the Agent tool. Those MUST be run simultaneously to boost efficiency.
+    **For codebase research:**
+   - Use the **codebase-locator** agent to find WHERE files and components live
+   - Use the **codebase-analyzer** agent to understand HOW specific code works
+   - Use the **codebase-pattern-finder** agent if you need examples of similar implementations
+
+   **For thoughts directory:**
+   - Use the **thoughts-locator** agent to discover what documents exist about the topic
+   - Use the **thoughts-analyzer** agent to extract key insights from specific documents
+
+   **For web research (only if user explicitly asks):**
+   - Use the **web-search-researcher** agent for external documentation and resources
+   - IF you use web-research agents, instruct them to return LINKS with their findings, and please INCLUDE those links in your final report
+
+   The key is to use these agents intelligently:
+   1. Start with locator agents to understand scope and find context
+   2. Then use analyzer agents on the most critical changes
+   - Run multiple agents in parallel when reviewing different aspects
+   - Each agent works in isolation — provide complete context in the prompt
+
+4. **Wait for all agents to complete and synthesize findings:**
+   - IMPORTANT: Wait for ALL agent invocations to complete before proceeding
+   - Compile all findings from agents
+   - Classify issues by severity:
+     - 🔴 Critical: Security vulnerabilities, data loss, crashes
+     - 🟡 Important: Bugs, performance issues, pattern violations
+     - 🔵 Suggestions: Style improvements, minor optimizations
+     - 💭 Discussion: Architecture decisions, trade-offs
+   - Cross-reference patterns found by agents with actual changes
+   - Check if historical decisions are being respected
+   - Verify test coverage based on existing patterns
+
+5. **Determine metadata and filename:**
+   - Filename format: `thoughts/shared/reviews/YYYY-MM-DD_HH-MM-SS_[scope].md`
+     - YYYY-MM-DD_HH-MM-SS: Current date and time (e.g., 2025-10-11_14-30-22)
+     - [scope]: Brief kebab-case description of what was reviewed
+   - Repository name: from git root basename, or current directory basename if not a git repo
+   - Use the git branch and commit from the git context injected at the start of the session (or run `git branch --show-current` / `git rev-parse --short HEAD` directly); falls back to "no-branch" / "no-commit" if not a git repo
+   - Reviewer: use the User from the git context injected at the start of the session (fallback: "unknown")
+   - If metadata unavailable: use "unknown" for commit/branch
+
+6. **Generate review document:**
+   - Use the metadata gathered in step 5
+   - Structure the document with YAML frontmatter followed by content:
+     ```markdown
+     ---
+     date: [Current date and time with timezone]
+     reviewer: [Reviewer name]
+     repository: [Repository name]
+     branch: [Current branch]
+     commit: [Commit hash]
+     review_type: [commit|pr|staged|working]
+     scope: "[What was reviewed]"
+     files_changed: [Number]
+     critical_issues: [Count]
+     important_issues: [Count]
+     suggestions: [Count]
+     status: [approved|needs_changes|requesting_changes]
+     tags: [code-review, relevant-components]
+     last_updated: [Current date in YYYY-MM-DD format]
+     last_updated_by: [Reviewer name]
+     ---
+
+     # Code Review: [Scope Description]
+
+     **Date**: [Current date and time]
+     **Reviewer**: [Reviewer name]
+     **Repository**: [Repository]
+     **Branch**: [Branch name]
+     **Commit**: [Commit hash]
+
+     ## Review Summary
+     [Overall assessment of the changes]
+
+     ## Issues Found
+
+     ### Critical Issues (Must Fix)
+     [None | List of critical issues with file:line references and suggested fixes]
+
+     ### Important Issues (Should Fix)
+     [List of important issues with evidence from skills]
+
+     ### Suggestions
+     [Minor improvements and optimizations]
+
+     ## Pattern Analysis
+     [How changes align with existing patterns found by pattern-finder]
+
+     ## Impact Assessment
+     [Files and tests affected based on locator findings]
+
+     ## Historical Context
+     [Relevant decisions and past issues from thoughts/]
+
+     ## Recommendation
+     [Clear verdict: Approved / Needs Changes / Requesting Changes]
+     ```
+
+7. **Present findings:**
+   - Present a concise summary to the user
+   - Include the most critical issues first
+   - Provide concrete examples from the codebase
+   - Ask if they need clarification on any findings
+
+8. **Handle follow-up questions:**
+   - If the user has follow-up questions, append to the same review document
+   - Update the frontmatter fields `last_updated` and `last_updated_by`
+   - Add a new section: `## Follow-up [timestamp]`
+   - Spawn new agents as needed for deeper investigation
+   - Continue updating the document and syncing
+
+## Important notes:
+- Always use parallel Agent tool calls to maximize efficiency
+- Always read the diff FULLY before spawning agents
+- Focus on finding concrete issues with evidence from agents
+- Review documents should be actionable with specific fixes
+- Each agent prompt should be focused on specific analysis
+- Consider patterns, security, performance, and maintainability
+- Include historical context when relevant
+- Keep the main agent focused on synthesis, not deep analysis
+- Encourage agents to find examples and patterns, not make judgments
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read diff first before spawning agents (step 1)
+  - ALWAYS wait for all agents to complete before synthesizing (step 4)
+  - ALWAYS gather metadata before writing the document (step 5 before step 6)
+- **Agent roles:**
+  - **codebase-locator**: WHERE code lives (find files)
+  - **codebase-analyzer**: HOW code works (implementation details)
+  - **codebase-pattern-finder**: Examples of similar code
+  - **thoughts-locator**: Find historical documentation
+  - **thoughts-analyzer**: Extract insights from documents
+  - **web-search-researcher**: External sources (sparingly)
+- **Severity classification**:
+  - Use evidence from agents to justify each issue's severity
+  - Provide specific file:line references for all issues
+  - Include examples of correct patterns when available
+  - Suggest concrete fixes, not vague improvements

package/skills/commit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: commit
+description: Create structured git commits. Groups related changes logically with clear, descriptive messages. Use when code changes are ready to commit.
+argument-hint: [message]
+allowed-tools: Bash(git *), Read, Glob, Grep
+---
+
+# Commit Changes
+
+You are tasked with creating git commits for repository changes.
+
+## Commit hint
+
+If the user has already provided a specific commit hint or message, use it as guidance. Otherwise the user may have provided no hint — their input will appear as a follow-up paragraph after this skill body if they did.
+
+## Context:
+- **In-session**: If there's conversation history, use it to understand what was built/changed
+- **Standalone**: If no context available, rely entirely on git state and file inspection
+
+## Process:
+
+0. **Check git availability:**
+   - Run `git status --short` to determine whether the current directory is a git repository
+   - If not a git repo, tell the user: "This directory is not a git repository. Run `git init` to initialize one."
+   - Stop — do not proceed with commit.
+
+1. **Think about what changed:**
+   - **If in-session**: Review the conversation history to understand what was accomplished
+   - **Always**: Run `git diff` to understand the modifications in detail
+   - If needed, inspect file contents to understand purpose and scope
+   - Consider whether changes should be one commit or multiple logical commits
+
+2. **Plan your commit(s):**
+   - Identify which files belong together
+   - Draft clear, descriptive commit messages
+   - Use imperative mood in commit messages
+   - Focus on why the changes were made, not just what
+   - Check for sensitive information (API keys, credentials) before committing
+
+3. **Present your plan to the user:**
+   - List the files you plan to add for each commit
+   - Show the commit message(s) you'll use
+   - Use the `ask_user_question` tool to confirm the commit plan. Question: "[N] commit(s) with [M] files. Proceed?". Header: "Commit". Options: "Commit (Recommended)" (Create the commit(s) as planned); "Adjust" (Change the grouping or commit messages); "Review files" (Show me the full diff before committing).
+
+4. **Execute upon confirmation:**
+   - Use `git add` with specific files (never use `-A` or `.`)
+   - Create commits with your planned messages
+   - Show the result with `git log --oneline -n X` (where X = number of commits you just created)
+
+## Important:
+
+- **NEVER add co-author information or Claude attribution**
+- Commits should be authored solely by the user
+- Do not include any "Generated with Claude" messages
+- Do not add "Co-Authored-By" lines
+- Write commit messages as if the user wrote them
+
+## Remember:
+
+- Adapt your approach: use conversation context if available, otherwise infer from git state
+- In-session: you have full context of what was done; Standalone: infer from git analysis
+- Group related changes by purpose (feature, fix, refactor, docs)
+- Keep commits atomic: one logical change per commit
+- Split into multiple commits if: different features, mixing bugs with features, or unrelated concerns
+- The user trusts your judgment - they asked you to commit