Two files, one repository

pr-pm/prpm ships 3 formats across 16 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ CLAUDE.md AGENTS.md ↔ Cursor rules CLAUDE.md ↔ Cursor rules

A · AGENTS.md · 4165 words B · CLAUDE.md · 2459 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	2	55	19	3%
Commands	0	9	0	0%
Section tags	6	10	0	38%

What each file covers

Sections

2 shared · 55 only in A · 19 only in B

− Individual package
− Mission
− Core Architecture
− Git Workflow - CRITICAL RULES
− Package Types
− Format Conversion System
− Collections System
− Collection Structure
− Installation Formats (Priority Order)
− Registry Resolution Logic
− CLI Resolution Logic
− Version Resolution
− Error Handling
− Quality & Ranking System
− Technical Stack
− Testing Standards
− Key Testing Patterns
− Development Workflow
− Package Manager: npm (NOT pnpm)
− Dependency Management Best Practices
− Environment Variable Management
− Security Standards
− Performance Considerations
− Deployment
− Webapp (S3 Static Export) ⚠️ CRITICAL
− Publishing PRPM to NPM
− CLI Command Structure
− Registry Route Structure
− Format Converter Structure
− Naming Conventions
− Documentation Standards
− Overview
− Reference Documentation
− Thoroughness
− Purpose
− When to Use
− Methodology
− Anti-Patterns to Avoid
− Quality Checkpoints
− Example Workflow
− Bad Approach (Shortcut-Driven)
− Good Approach (Thoroughness-Driven)
− Time Investment
− Success Metrics
− Mantras
− TypeScript Type Safety
− Type Safety Hierarchy
− Quick Reference
− Implementation
− Unknown Data Validation
− Module Augmentation
− Generic Constraints
− Type Alignment (Avoid Double Casts)
− Common Mistakes
− TSConfig Strict Settings
+ Using bv as an AI sidecar
+ MCP Agent Mail: coordination for multi-agent workflows
+ Integrating with Beads (dependency-aware task planning)
+ 🔎 cass — Search All Your Agent History
+ Check if index is healthy (exit 0=ok, 1=run index first)
+ Search across all agent histories
+ View a specific result (from search output)
+ Expand context around a line
+ Learn the full API
+ Agent Relay
+ Sending Messages
+ Communication Protocol
+ Receiving Messages
+ Channel Routing (Important!)
+ Correct - responds to #general channel
+ Wrong - sends as DM to sender instead of to the channel
+ Spawning Agents
+ Threads
+ Rules
Available Skills
Common Patterns

Commands

0 shared · 9 only in A · 0 only in B

− git checkout -b feature/your-feature-name
− git checkout -b fix/bug-description
− npm install
− npm install --workspace=@pr-pm/cli
− npm test
− npm run build
− npm run dev --workspace=prpm
− npm version patch --workspace=prpm --workspace=@prpm/registry-client
− npm version minor --workspace=prpm

Section tags

6 shared · 10 only in A · 0 only in B

− setup
− build
− lint-format
− architecture
− types
− testing-strategy
− security
− performance
− deployment
− docs
test
code-style
git-pr
api
do-not
agent-behaviour

Line diff

+343 added−1136 removed142 unchanged11.1% identical

pr-pm/prpm · AGENTS.md

@@ −1 @@

1

4

6<skills_system priority="1">

8## Available Skills

10

12<skills_system priority="1">

13<usage>

14When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.

16How to use skills (loaded into main context):

17- Use the <path> from the skill entry below

18- Invoke: Bash("cat <path>")

19- The skill content will load into your current context

20- Example: Bash("cat .openskills/backend-architect/SKILL.md")

22Usage notes:

23- Skills share your context window

24- Do not invoke a skill that is already loaded in your context

25</usage>

27<available_skills>

29<skill>

30<name>prpm-development</name>

31<description>Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base covering architecture, format conversion, package types, collections, quality standards, testing, and deployment</description>

32<path>.openskills/prpm-development/SKILL.md</path>

33</skill>

35<skill>

36<name>osgrep-skill</name>

37<description>Skill for using osgrep semantic code search - teaches how to effectively search codebases using natural language queries instead of exact string matching</description>

38<path>.openskills/osgrep-skill/SKILL.md</path>

39</skill>

41</available_skills>

42</skills_system>

44

46</skills_system>

50

52

53

54

56# Individual package

58Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base covering architecture, format conversion, package types, collections, quality standards, testing, and deployment

60## Mission

62Build the npm/cargo/pip equivalent for AI development artifacts. Enable developers to discover, install, share, and manage prompts across Cursor, Claude Code, Continue, Windsurf, and future AI editors.

64## Core Architecture

66### Git Workflow - CRITICAL RULES

68```bash

69git checkout -b feature/your-feature-name

70 # or

71 git checkout -b fix/bug-description

72```

74## Package Types

76- Knowledge and guidelines for AI assistants

78- `.claude/skills/`, `.cursor/rules/`

80- `@prpm/pulumi-troubleshooting`, `@typescript/best-practices`

82- Autonomous AI agents for multi-step tasks

84- `.claude/agents/`, `.cursor/agents/`

86- `@prpm/code-reviewer`, `@cursor/debugging-agent`

88- Specific instructions or constraints for AI behavior

90- `.cursor/rules/`, `.cursorrules`

92- `@cursor/react-conventions`, `@cursor/test-first`

94- Extensions that add functionality

96- `.cursor/plugins/`, `.claude/plugins/`

98- Reusable prompt templates

100- `.prompts/`, project-specific directories

101

102- Multi-step automation workflows

103

104- `.workflows/`, `.github/workflows/`

105

106- Executable utilities and scripts

107

108- `scripts/`, `tools/`, `.bin/`

109

110- Reusable file and project templates

111

112- `templates/`, project-specific directories

113

114- Model Context Protocol servers

115

116- `.mcp/servers/`

117

118## Format Conversion System

119

120- Cursor (.mdc)

121

122- MDC frontmatter with `ruleType`, `alwaysApply`, `description`

123

124- Markdown body

125

126- Simple, focused on coding rules

127

128- No structured tools/persona definitions

129

130- Claude (agent format)

131

132- YAML frontmatter: `name`, `description`

133

134- Optional: `tools` (comma-separated), `model` (sonnet/opus/haiku/inherit)

135

136- Markdown body

137

138- Supports persona, examples, instructions

139

140- Continue (JSON)

141

142- JSON configuration

143

144- Simple prompts, context rules

145

146- Limited metadata support

147

148- Windsurf

149

150- Similar to Cursor

151

152- Markdown-based

153

154- Basic structure

155

156- Missing tools: -10 points

157

158- Missing persona: -5 points

159

160- Missing examples: -5 points

161

162- Unsupported sections: -10 points each

163

164- Format-specific features lost: -5 points

165

166- **Canonical ↔ Claude**: Nearly lossless (95-100%)

167

168- **Canonical ↔ Cursor**: Lossy on tools/persona (70-85%)

169

170- **Canonical ↔ Continue**: Most lossy (60-75%)

171

172## Collections System

173

174### Collection Structure

175

176```json

177{

178 "id": "@collection/nextjs-pro",

179 "name": "Next.js Professional Setup",

180 "description": "Complete Next.js development setup",

181 "category": "frontend",

182 "packages": [

183 {

184 "packageId": "react-best-practices",

185 "required": true,

186 "reason": "Core React patterns"

187 },

188 {

189 "packageId": "typescript-strict",

190 "required": true,

191 "reason": "Type safety"

192 },

193 {

194 "packageId": "tailwind-helper",

195 "required": false,

196 "reason": "Styling utilities"

197 }

198 ]

199}

200```

201

202### Installation Formats (Priority Order)

203

204```bash

205prpm install collections/nextjs-pro

206prpm install collections/nextjs-pro@2.0.0

207```

208

209### Registry Resolution Logic

210

211```typescript

212// When scope is 'collection' (default from CLI for collections/* prefix):

213if (scope === 'collection') {

214 // Search across ALL scopes, prioritize by:

215 // 1. Official collections (official = true)

216 // 2. Verified authors (verified = true)

217 // 3. Most downloads

218 // 4. Most recent

219 SELECT * FROM collections

220 WHERE name_slug = $1

221 ORDER BY official DESC, verified DESC, downloads DESC, created_at DESC

222 LIMIT 1

223} else {

224 // Explicit scope: exact match only

225 SELECT * FROM collections

226 WHERE scope = $1 AND name_slug = $2

227 ORDER BY created_at DESC

228 LIMIT 1

229}

230```

231

232### CLI Resolution Logic

233

234```typescript

235// Parse collection spec:

236// - collections/nextjs-pro → scope='collection', name_slug='nextjs-pro'

237// - khaliqgant/nextjs-pro → scope='khaliqgant', name_slug='nextjs-pro'

238// - @khaliqgant/nextjs-pro → scope='khaliqgant', name_slug='nextjs-pro'

239// - nextjs-pro → scope='collection', name_slug='nextjs-pro'

240

241const matchWithScope = collectionSpec.match(/^@?([^/]+)\/([^/@]+)(?:@(.+))?$/);

242if (matchWithScope) {

243 [, scope, name_slug, version] = matchWithScope;

244} else {

245 // No scope: default to 'collection'

246 [, name_slug, version] = collectionSpec.match(/^([^/@]+)(?:@(.+))?$/);

247 scope = 'collection';

248}

249```

250

251### Version Resolution

252

253```bash

254prpm install collections/nextjs-pro

255

256prpm install collections/nextjs-pro@2.0.4

257

258prpm install khaliqgant/nextjs-pro@2.0.4

259```

260

261### Error Handling

262

263```bash

264prpm install collections/nonexistent

265```

266

267## Quality & Ranking System

268

269- (0-30 points):

270

271- Total downloads (weighted by recency)

272

273- Stars/favorites

274

275- Trending velocity

276

277- (0-30 points):

278

279- User ratings (1-5 stars)

280

281- Review sentiment

282

283- Documentation completeness

284

285- (0-20 points):

286

287- Verified author badge

288

289- Original creator vs fork

290

291- Publisher reputation

292

293- Security scan results

294

295- (0-10 points):

296

297- Last updated date (<30 days = 10 points)

298

299- Release frequency

300

301- Active maintenance

302

303- (0-10 points):

304

305- Has README

306

307- Has examples

308

309- Has tags

310

311- Complete metadata

312

313## Technical Stack

314

315- **Commander.js**: CLI framework

316

317- **Fastify Client**: HTTP client for registry

318

319- **Tar**: Package tarball creation/extraction

320

321- **Chalk**: Terminal colors

322

323- **Ora**: Spinners for async operations

324

325- **Fastify**: High-performance web framework

326

327- **PostgreSQL**: Primary database with GIN indexes

328

329- **Redis**: Caching layer for converted packages

330

331- **GitHub OAuth**: Authentication provider

332

333- **Docker**: Containerized deployment

334

335- **Vitest**: Unit and integration tests

336

337- **100% Coverage Goal**: Especially for format converters

338

339- **Round-Trip Tests**: Ensure conversion quality

340

341- **Fixtures**: Real-world package examples

342

343## Testing Standards

344

345### Key Testing Patterns

346

347```typescript

348// Format converter test

349describe('toCursor', () => {

350 it('preserves data in roundtrip', () => {

351 const result = toCursor(canonical);

352 const back = fromCursor(result.content);

353 expect(back).toEqual(canonical);

354 });

355});

356

357// CLI command test

358describe('install', () => {

359 it('downloads and installs package', async () => {

360 await handleInstall('test-pkg', { as: 'cursor' });

361 expect(fs.existsSync('.cursor/rules/test-pkg.md')).toBe(true);

362 });

363});

364```

365

366## Development Workflow

367

368### Package Manager: npm (NOT pnpm)

369

370```bash

371npm install

372

373npm install --workspace=@pr-pm/cli

374

375npm test

376

377npm run build

378

379npm run dev --workspace=prpm

380```

381

382### Dependency Management Best Practices

383

384```typescript

385// BAD - tar-stream is imported dynamically at runtime

386const tarStream = await import('tar-stream');

387```

388

389### Environment Variable Management

390

391```bash

392NEW_FEATURE_API_KEY=your-key-here

393```

394

395## Security Standards

396

397- **No Secrets in DB**: Never store GitHub tokens, use session IDs

398

399- **SQL Injection**: Parameterized queries only

400

401- **Rate Limiting**: Prevent abuse of registry API

402

403- **Content Security**: Validate package contents before publishing

404

405## Performance Considerations

406

407- **Batch Operations**: Use Promise.all for independent operations

408

409- **Database Indexes**: GIN for full-text, B-tree for lookups

410

411- **Caching Strategy**: Cache converted packages, not raw data

412

413- **Lazy Loading**: Don't load full package data until needed

414

415- **Connection Pooling**: Reuse PostgreSQL connections

416

417## Deployment

418

419### Webapp (S3 Static Export) ⚠️ CRITICAL

420

421```typescript

422// ❌ Dynamic route (doesn't work with 'use client')

423 // /app/shared/[token]/page.tsx

424 const params = useParams();

425 const token = params.token;

426

427 // ✅ Query string with Suspense (works with 'use client')

428 // /app/shared/page.tsx

429 import { Suspense } from 'react';

430

431 function Content() {

432 const searchParams = useSearchParams();

433 const token = searchParams.get('token');

434 // ... component logic

435 }

436

437 export default function Page() {

438 return (

439 <Suspense fallback={<div>Loading...</div>}>

440 <Content />

441 </Suspense>

442 );

443 }

444```

445

446### Publishing PRPM to NPM

447

448```bash

449npm version patch --workspace=prpm --workspace=@prpm/registry-client

450

451npm version minor --workspace=prpm

452```

453

454## Common Patterns

455

456### CLI Command Structure

457

458```typescript

459export async function handleCommand(args: Args, options: Options) {

460 const startTime = Date.now();

461 try {

462 const config = await loadUserConfig();

463 const client = getRegistryClient(config);

464 const result = await client.fetchData();

465 console.log('✅ Success');

466 await telemetry.track({ command: 'name', success: true });

467 } catch (error) {

468 console.error('❌ Failed:', error.message);

469 await telemetry.track({ command: 'name', success: false });

470 process.exit(1);

471 }

472}

473```

474

475### Registry Route Structure

476

477```typescript

478server.get('/:id', {

479 schema: { /* OpenAPI schema */ },

480}, async (request, reply) => {

481 const { id } = request.params;

482 if (!id) return reply.code(400).send({ error: 'Missing ID' });

483 const result = await server.pg.query('SELECT...');

484 return result.rows[0];

485});

486```

487

488### Format Converter Structure

489

490```typescript

491export function toFormat(pkg: CanonicalPackage): ConversionResult {

492 const warnings: string[] = [];

493 let qualityScore = 100;

494 const content = convertSections(pkg.content.sections, warnings);

495 const lossyConversion = warnings.some(w => w.includes('not supported'));

496 if (lossyConversion) qualityScore -= 10;

497 return { content, format: 'target', warnings, qualityScore, lossyConversion };

498}

499```

500

501## Naming Conventions

502

503- **Files**: kebab-case (`registry-client.ts`, `to-cursor.ts`)

504

505- **Types**: PascalCase (`CanonicalPackage`, `ConversionResult`)

506

507- **Functions**: camelCase (`getPackage`, `convertToFormat`)

508

509- **Constants**: UPPER_SNAKE_CASE (`DEFAULT_REGISTRY_URL`)

510

511- **Database**: snake_case (`package_id`, `created_at`)

512

513- **API Requests/Responses**: snake_case (`package_id`, `session_id`, `created_at`)

514

515- **Important**: All API request and response fields use snake_case to match PostgreSQL database conventions

516

517- Internal service methods may use camelCase, but must convert to snake_case at API boundaries

518

519- TypeScript interfaces for API types should use snake_case fields

520

521- Examples: `PlaygroundRunRequest.package_id`, `CreditBalance.reset_at`

522

523## Documentation Standards

524

525- **Inline Comments**: Explain WHY, not WHAT

526

527- **JSDoc**: Required for public APIs

528

529- **README**: Keep examples up-to-date

530

531- **Markdown Docs**: Use code blocks with language tags

532

533- **Changelog**: Follow Keep a Changelog format

534

535- **Continuous Accuracy**: Documentation must be continuously updated and tended to for accuracy

536

537- When adding features, update relevant docs immediately

538

539- When fixing bugs, check if docs need corrections

540

541- When refactoring, verify examples still work

542

543- Review docs quarterly for outdated information

544

545- Keep CLI docs, README, and Mintlify docs in sync

546

547## Overview

548

549Complete knowledge base for developing PRPM - the universal package manager for AI prompts, agents, and rules.

550

551## Reference Documentation

552

553- `format-conversion.md` - Complete format conversion specs

554

555- `package-types.md` - All package types with examples

556

557- `collections.md` - Collections system and examples

558

559- `quality-ranking.md` - Quality and ranking algorithms

560

561- `testing-guide.md` - Testing patterns and standards

562

563- `deployment.md` - Deployment procedures

564

565

566

567

568

569

570

571

572

573# Thoroughness

574

575Use when implementing complex multi-step tasks, fixing critical bugs, or when quality and completeness matter more than speed - ensures comprehensive implementation without shortcuts through systematic analysis, implementation, and verification phases

576

577## Purpose

578

579This skill ensures comprehensive, complete implementation of complex tasks without shortcuts. Use this when quality and completeness matter more than speed.

580

581## When to Use

582

583- Fixing critical bugs or compilation errors

584

585- Implementing complex multi-step features

586

587- Debugging test failures

588

589- Refactoring large codebases

590

591- Production deployments

592

593- Any task where shortcuts could cause future problems

594

595## Methodology

596

597- **Identify All Issues**

598

599- List every error, warning, and failing test

600

601- Group related issues together

602

603- Prioritize by dependency order

604

605- Create issue hierarchy (what blocks what)

606

607- **Root Cause Analysis**

608

609- Don't fix symptoms, find root causes

610

611- Trace errors to their source

612

613- Identify patterns in failures

614

615- Document assumptions that were wrong

616

617- **Create Detailed Plan**

618

619- Break down into atomic steps

620

621- Estimate time for each step

622

623- Identify dependencies between steps

624

625- Plan verification for each step

626

627- Schedule breaks/checkpoints

628

629- **Fix Issues in Dependency Order**

630

631- Start with foundational issues

632

633- Fix one thing completely before moving on

634

635- Test after each fix

636

637- Document what was changed and why

638

639- **Verify Each Fix**

640

641- Write/run tests for the specific fix

642

643- Check for side effects

644

645- Verify related functionality still works

646

647- Document test results

648

649- **Track Progress**

650

651- Mark issues as completed

652

653- Update plan with new discoveries

654

655- Adjust time estimates

656

657- Note any blockers immediately

658

659- **Run All Tests**

660

661- Unit tests

662

663- Integration tests

664

665- E2E tests

666

667- Manual verification

668

669- **Cross-Check Everything**

670

671- Review all changed files

672

673- Verify compilation succeeds

674

675- Check for console errors/warnings

676

677- Test edge cases

678

679- **Documentation**

680

681- Update relevant docs

682

683- Add inline comments for complex fixes

684

685- Document known limitations

686

687- Create issues for future work

688

689## Anti-Patterns to Avoid

690

691- ❌ Fixing multiple unrelated issues at once

692

693- ❌ Moving on before verifying a fix works

694

695- ❌ Assuming similar errors have the same cause

696

697- ❌ Skipping test writing "to save time"

698

699- ❌ Copy-pasting solutions without understanding

700

701- ❌ Ignoring warnings "because it compiles"

702

703- ❌ Making changes without reading existing code first

704

705## Quality Checkpoints

706

707- [ ] Can I explain why this fix works?

708

709- [ ] Have I tested this specific change?

710

711- [ ] Are there any side effects?

712

713- [ ] Is this the root cause or a symptom?

714

715- [ ] Will this prevent similar issues in the future?

716

717- [ ] Is the code readable and maintainable?

718

719- [ ] Have I documented non-obvious decisions?

720

721## Example Workflow

722

723### Bad Approach (Shortcut-Driven)

724

725*Bad example*

726

727```

7281. See 24 TypeScript errors

7292. Add @ts-ignore to all of them

7303. Hope tests pass

7314. Move on

732```

733

734### Good Approach (Thoroughness-Driven)

735

736*Good example*

737

738```

7391. List all 24 errors systematically

7402. Group by error type (7 missing types, 10 unknown casts, 7 property access)

7413. Find root causes:

742 - Missing @types/tar package

743 - No type assertions on fetch responses

744 - Implicit any types in callbacks

7454. Fix by category:

746 - Install @types/tar (fixes 7 errors)

747 - Add proper type assertions to registry-client.ts (fixes 10 errors)

748 - Add explicit parameter types (fixes 7 errors)

7495. Test after each category

7506. Run full test suite

7517. Document what was learned

752```

753

754## Time Investment

755

756- Initial: 2-3x slower than shortcuts

757

758- Long-term: 10x faster (no debugging later, no rework)

759

760- Quality: Near-perfect first time

761

762- Maintenance: Minimal

763

764## Success Metrics

765

766- ✅ 100% of tests passing

767

768- ✅ Zero warnings in production build

769

770- ✅ All code has test coverage

771

772- ✅ Documentation is complete and accurate

773

774- ✅ No known issues or TODOs left behind

775

776- ✅ Future developers can understand the code

777

778## Mantras

779

780- "Slow is smooth, smooth is fast"

781

782- "Do it right the first time"

783

784- "Test everything, assume nothing"

785

786- "Document for your future self"

787

788- "Root causes, not symptoms"

789

790

791

792

793

794

795

796

797

798# TypeScript Type Safety

799

800Use when encountering TypeScript any types, type errors, or lax type checking - eliminates type holes and enforces strict type safety through proper interfaces, type guards, and module augmentation

801

802## Overview

803

804**Zero tolerance for `any` types.** Every `any` is a runtime bug waiting to happen.

805

806Replace `any` with proper types using interfaces, `unknown` with type guards, or generic constraints. Use `@ts-expect-error` with explanation only when absolutely necessary.

807

808## When to Use

809

810- Use when you see:

811

812- `: any` in function parameters or return types

813

814- `as any` type assertions

815

816- TypeScript errors you're tempted to ignore

817

818- External libraries without proper types

819

820- Catch blocks with implicit `any`

821

822- Don't use for:

823

824- Already properly typed code

825

826- Third-party `.d.ts` files (contribute upstream instead)

827

828## Type Safety Hierarchy

829

830**Prefer in this order:**

8311. Explicit interface/type definition

8322. Generic type parameters with constraints

8333. Union types

8344. `unknown` (with type guards)

8355. `never` (for impossible states)

836

837**Never use:** `any`

838

839## Quick Reference

840

841| Pattern | Bad | Good |

842|---------|-----|------|

843| **Error handling** | `catch (error: any)` | `catch (error) { if (error instanceof Error) ... }` |

844| **Unknown data** | `JSON.parse(str) as any` | `const data = JSON.parse(str); if (isValid(data)) ...` |

845| **Type assertions** | `(request as any).user` | `(request as AuthRequest).user` |

846| **Double casting** | `return data as unknown as Type` | Align interfaces instead: make types compatible |

847| **External libs** | `const server = fastify() as any` | `declare module 'fastify' { ... }` |

848| **Generics** | `function process(data: any)` | `function process<T extends Record<string, unknown>>(data: T)` |

849

850## Implementation

851

852### Error Handling

853

854```typescript

855// ❌ BAD

856try {

857 await operation();

858} catch (error: any) {

859 console.error(error.message);

860}

861

862// ✅ GOOD - Use unknown and type guard

863try {

864 await operation();

865} catch (error) {

866 if (error instanceof Error) {

867 console.error(error.message);

868 } else {

869 console.error('Unknown error:', String(error));

870 }

871}

872

873// ✅ BETTER - Helper function

874function toError(error: unknown): Error {

875 if (error instanceof Error) return error;

876 return new Error(String(error));

877}

878

879try {

880 await operation();

881} catch (error) {

882 const err = toError(error);

883 console.error(err.message);

884}

885```

886

887### Unknown Data Validation

888

889```typescript

890// ❌ BAD

891const data = await response.json() as any;

892console.log(data.user.name);

893

894// ✅ GOOD - Type guard

895interface UserResponse {

896 user: {

897 name: string;

898 email: string;

899 };

900}

901

902function isUserResponse(data: unknown): data is UserResponse {

903 return (

904 typeof data === 'object' &&

905 data !== null &&

906 'user' in data &&

907 typeof data.user === 'object' &&

908 data.user !== null &&

909 'name' in data.user &&

910 typeof data.user.name === 'string'

911 );

912}

913

914const data = await response.json();

915if (isUserResponse(data)) {

916 console.log(data.user.name); // Type-safe

917}

918```

919

920### Module Augmentation

921

922```typescript

923// ❌ BAD

924const user = (request as any).user;

925const db = (server as any).pg;

926

927// ✅ GOOD - Augment third-party types

928import { FastifyRequest, FastifyInstance } from 'fastify';

929

930interface AuthUser {

931 user_id: string;

932 username: string;

933 email: string;

934}

935

936declare module 'fastify' {

937 interface FastifyRequest {

938 user?: AuthUser;

939 }

940

941 interface FastifyInstance {

942 pg: PostgresPlugin;

943 }

944}

945

946// Now type-safe everywhere

947const user = request.user; // AuthUser | undefined

948const db = server.pg; // PostgresPlugin

949```

950

951### Generic Constraints

952

953```typescript

954// ❌ BAD

955function merge(a: any, b: any): any {

956 return { ...a, ...b };

957}

958

959// ✅ GOOD - Constrained generic

960function merge<

961 T extends Record<string, unknown>,

962 U extends Record<string, unknown>

963>(a: T, b: U): T & U {

964 return { ...a, ...b };

965}

966```

967

968### Type Alignment (Avoid Double Casts)

969

970```typescript

971// ❌ BAD - Double cast indicates misaligned types

972interface SearchPackage {

973 id: string;

974 type: string; // Too loose

975}

976

977interface RegistryPackage {

978 id: string;

979 type: PackageType; // Specific enum

980}

981

982return data.packages as unknown as RegistryPackage[]; // Hiding incompatibility

983

984// ✅ GOOD - Align types from the source

985interface SearchPackage {

986 id: string;

987 type: PackageType; // Use same specific type

988}

989

990interface RegistryPackage {

991 id: string;

992 type: PackageType; // Now compatible

993}

994

995return data.packages; // No cast needed - types match

996```

997

998## Common Mistakes

999

1000| Mistake | Why It Fails | Fix |

1001|---------|--------------|-----|

1002| Using `any` for third-party libs | Loses all type safety | Use module augmentation or `@types/*` package |

1003| `as any` for complex types | Hides real type errors | Create proper interface or use `unknown` |

1004| `as unknown as Type` double casts | Misaligned interfaces | Align types at source - same enums/unions |

1005| Skipping catch block types | Unsafe error access | Use `unknown` with type guards or toError helper |

1006| Generic functions without constraints | Allows invalid operations | Add `extends` constraint |

1007| Ignoring `ts-ignore` accumulation | Tech debt compounds | Fix root cause, use `@ts-expect-error` with comment |

1008

1009## TSConfig Strict Settings

1010

1011### Enable all strict options for maximum type safety:

1012

1013```json

1014{

1015 "compilerOptions": {

1016 "strict": true,

1017 "noImplicitAny": true,

1018 "strictNullChecks": true,

1019 "strictFunctionTypes": true,

1020 "strictBindCallApply": true,

1021 "strictPropertyInitialization": true,

1022 "noImplicitThis": true,

1023 "noUnusedLocals": true,

1024 "noUnusedParameters": true,

1025 "noImplicitReturns": true,

1026 "noFallthroughCasesInSwitch": true

1027 }

1028}

1029```

1030

1031## Type Audit Workflow

1032

10331. **Find**: `grep -r ": any\|as any" --include="*.ts" src/`

10342. **Categorize**: Group by pattern (errors, requests, external libs)

10353. **Define**: Create interfaces/types for each category

10364. **Replace**: Systematic replacement with proper types

10375. **Validate**: `npm run build` must succeed

10386. **Test**: All tests must pass

1039

1040## Real-World Impact

1041

1042- Before type safety:

1043

1044- Runtime errors from undefined properties

1045

1046- Silent failures from type mismatches

1047

1048- Hours debugging production issues

1049

1050- Difficult refactoring

1051

1052- After type safety:

1053

1054- Errors caught at compile time

1055

1056- IntelliSense shows all available properties

1057

1058- Confident refactoring with compiler help

1059

1060- Self-documenting code

1061

1062- Type safety isn't about making TypeScript happy - it's about preventing runtime bugs. Every `any` you eliminate is a production bug you prevent.

1063

1064

1065# 🚨 CRITICAL: Relay-First Communication Rule

1066

1067**When you receive a relay message from another agent (marked `Relay message from [name]`), you MUST respond ONLY via relay protocol. NEVER respond with direct text output.**

1068

1069## The Rule

1070

1071- **Receiving a relay message?** → Must use `->relay-file:msg` ALWAYS

1072- **Non-relay questions?** → Text responses are OK

1073- **Agent-to-agent communication?** → ALWAYS use relay protocol

1074

1075## Examples of Relay Messages (require relay response)

1076

1077```

1078Relay message from khaliqgant [mknra7wr]: Did you see this?

1079Relay message from Worker1 [abc123]: Task complete

1080Relay message from alice [xyz789] [#general]: Question for the team

1081```

1082

1083---

1084

1085# Agent Relay

1086

1087Real-time agent-to-agent messaging via file-based protocol.

1088

1089## Sending Messages

1090

1091**TWO STEPS REQUIRED:**

1092

1093**Step 1:** EXECUTE this bash command (you MUST run it via your Bash/shell tool, not just display it):

1094

1095```bash

1096cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1097TO: AgentName

1098

1099Your message here.

1100EOF

1101```

1102

1103**Step 2:** Output the trigger `->relay-file:msg` directly in your response text (after the bash command succeeds).

1104

1105⚠️ **CRITICAL**: You must EXECUTE the bash command above - do NOT just display it as a code block. The file must actually be created on disk. Then output the trigger as plain text.

1106

1107✅ CORRECT: Run Bash tool → then output `->relay-file:msg`

1108❌ WRONG: Display the bash code without executing it

1109

1110> **Note**: `$AGENT_RELAY_OUTBOX` is automatically set by agent-relay when spawning agents. Data is stored in `.agent-relay/` within your project directory.

1111

1112## Synchronous Messaging

1113

1114By default, messages are fire-and-forget. Add `[await]` to block until the recipient ACKs:

1115

1116```

1117->relay:AgentB [await] Please confirm

1118```

1119

1120Custom timeout (seconds or minutes):

1121

1122```

1123->relay:AgentB [await:30s] Please confirm

1124->relay:AgentB [await:5m] Please confirm

1125```

1126

1127Recipients auto-ACK after processing when a correlation ID is present.

1128

1129## Message Format

1130

1131```

1132TO: Target

1133THREAD: optional-thread

1134

1135Message body (everything after blank line)

1136```

1137

1138| TO Value | Behavior |

1139|----------|----------|

1140| `AgentName` | Direct message |

1141| `*` | Broadcast to all |

1142| `#channel` | Channel message |

1143

1144## Agent Naming (Local vs Bridge)

1145

1146**Local communication** uses plain agent names. The `project:` prefix is **ONLY** for cross-project bridge mode.

1147

1148| Context | Correct | Incorrect |

1149|---------|---------|-----------|

1150| Local (same project) | `TO: Lead` | `TO: project:lead` |

1151| Local (same project) | `TO: Worker1` | `TO: myproject:Worker1` |

1152| Bridge (cross-project) | `TO: frontend:Designer` | N/A |

1153| Bridge (to another lead) | `TO: otherproject:lead` | N/A |

1154

1155**Common mistake**: Using `project:lead` when communicating locally. This will fail because the relay looks for an agent literally named "project:lead".

1156

1157```bash

1158# CORRECT - local communication to Lead agent

1159cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1160TO: Lead

1161

1162Status update here.

1163EOF

1164```

1165

1166```bash

1167# WRONG - project: prefix is only for bridge mode

1168cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1169TO: project:lead

1170

1171This will fail locally!

1172EOF

1173```

1174

1175## Spawning & Releasing

1176

1177**IMPORTANT**: The filename is always `spawn` (not `spawn-agentname`) and the trigger is always `->relay-file:spawn`. Spawn agents one at a time sequentially.

1178

1179### CLI Options

1180

1181The `CLI` header specifies which AI CLI to use. Valid values:

1182

1183| CLI Value | Description |

1184|-----------|-------------|

1185| `claude` | Claude Code (Anthropic) |

1186| `codex` | Codex CLI (OpenAI) |

1187| `gemini` | Gemini CLI (Google) |

1188| `aider` | Aider coding assistant |

1189| `goose` | Goose AI assistant |

1190

1191**Step 1:** EXECUTE this bash command (run it, don't just display it):

1192```bash

1193# Spawn a Claude agent

1194cat > $AGENT_RELAY_OUTBOX/spawn << 'EOF'

1195KIND: spawn

1196NAME: WorkerName

1197CLI: claude

1198

1199Task description here.

1200EOF

1201```

1202**Step 2:** Output: `->relay-file:spawn`

1203

1204```bash

1205# Spawn a Codex agent

1206cat > $AGENT_RELAY_OUTBOX/spawn << 'EOF'

1207KIND: spawn

1208NAME: CodexWorker

1209CLI: codex

1210

1211Task description here.

1212EOF

1213```

1214

1215**Step 1:** EXECUTE this bash command (run it, don't just display it):

1216```bash

1217# Release

1218cat > $AGENT_RELAY_OUTBOX/release << 'EOF'

1219KIND: release

1220NAME: WorkerName

1221EOF

1222```

1223**Step 2:** Output: `->relay-file:release`

1224

1225## When You Are Spawned

1226

1227If you were spawned by another agent:

1228

12291. **Check who spawned you**: `echo $AGENT_RELAY_SPAWNER`

12302. **Your first message** is your task from your spawner - reply to THEM, not "spawner"

12313. **Report status** to your spawner (your lead), not broadcast

1232

1233```bash

1234# Check your spawner

1235echo "I was spawned by: $AGENT_RELAY_SPAWNER"

1236```

1237

1238**Step 1:** EXECUTE this bash command:

1239```bash

1240# Reply to your spawner

1241cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1242TO: $AGENT_RELAY_SPAWNER

1243

1244ACK: Starting on the task.

1245EOF

1246```

1247**Step 2:** Output: `->relay-file:msg`

1248

1249## Receiving Messages

1250

1251Messages appear as:

1252```

1253Relay message from Alice [abc123]: Content here

1254```

1255

1256Channel messages include `[#channel]`:

1257```

1258Relay message from Alice [abc123] [#general]: Hello!

1259```

1260Reply to the channel shown, not the sender.

1261

1262## Protocol

1263

1264- **ACK** when you receive a task: `ACK: Brief description`

1265- **DONE** when complete: `DONE: What was accomplished`

1266- Send status to your **lead** (the agent in `$AGENT_RELAY_SPAWNER`), not broadcast

1267

1268## Headers Reference

1269

1270| Header | Required | Description |

1271|--------|----------|-------------|

1272| TO | Yes (messages) | Target agent/channel |

1273| KIND | No | `message` (default), `spawn`, `release` |

1274| NAME | Yes (spawn/release) | Agent name |

1275| CLI | Yes (spawn) | CLI to use: `claude`, `codex`, `gemini`, `aider`, `goose` |

1276| THREAD | No | Thread identifier |

1277

1278

pr-pm/prpm · CLAUDE.md

@@ +1 @@

1* Use the `bd` tool instead of markdown to coordinate all work and tasks.

2* NEVER commit changes unless the user explicitly asks you to.

4# Using bv as an AI sidecar

6bv is a fast terminal UI for Beads projects (.beads/beads.jsonl). It renders lists/details and precomputes dependency metrics (PageRank, critical path, cycles, etc.) so you instantly see blockers and execution order. For agents, it’s a graph sidecar: instead of parsing JSONL or risking hallucinated traversal, call the robot flags to get deterministic, dependency-aware outputs.

8*IMPORTANT: As an agent, you must ONLY use bv with the robot flags, otherwise you'll get stuck in the interactive TUI that's intended for human usage only!*

10- bv --robot-help — shows all AI-facing commands.

11- bv --robot-insights — JSON graph metrics (PageRank, betweenness, HITS, critical path, cycles) with top-N summaries for quick triage.

12- bv --robot-plan — JSON execution plan: parallel tracks, items per track, and unblocks lists showing what each item frees up.

13- bv --robot-priority — JSON priority recommendations with reasoning and confidence.

14- bv --robot-recipes — list recipes (default, actionable, blocked, etc.); apply via bv --recipe <name> to pre-filter/sort before other flags.

15- bv --robot-diff --diff-since <commit|date> — JSON diff of issue changes, new/closed items, and cycles introduced/resolved.

17Use these commands instead of hand-rolling graph logic; bv already computes the hard parts so agents can act safely and quickly.

19## MCP Agent Mail: coordination for multi-agent workflows

21What it is

22- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.

23- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.

25Why it's useful

26- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.

27- Keeps communication out of your token budget by storing messages in a per-project archive.

28- Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.

30How to use effectively

311) Same repository

32 - Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.

33 - Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.

34 - Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.

35 - Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20` or `resource://thread/{id}?project=<abs-path>&include_bodies=true`.

36 - Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.

382) Across different repos in one project (e.g., Next.js frontend + FastAPI backend)

39 - Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).

40 - Option B (separate projects): each repo has its own `project_key`; use `macro_contact_handshake` or `request_contact`/`respond_contact` to link agents, then message directly. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.

42Macros vs granular tools

43- Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.

44- Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.

46Common pitfalls

47- "from_agent not registered": always `register_agent` in the correct `project_key` first.

48- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.

49- Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.

52## Integrating with Beads (dependency-aware task planning)

54Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: [steveyegge/beads](https://github.com/steveyegge/beads)

56Recommended conventions

57- **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).

58- **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.

59- **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.

61Typical flow (agents)

621) **Pick ready work** (Beads)

63 - `bd ready --json` → choose one item (highest priority, no blockers)

642) **Reserve edit surface** (Mail)

65 - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`

663) **Announce start** (Mail)

67 - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`

684) **Work and update**

69 - Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id

705) **Complete and release**

71 - `bd close bd-123 --reason "Completed"` (Beads is status authority)

72 - `release_file_reservations(project_key, agent_name, paths=["src/**"])`

73 - Final Mail reply: `[bd-123] Completed` with summary and links

75Mapping cheat-sheet

76- **Mail `thread_id`** ↔ `bd-###`

77- **Mail subject**: `[bd-###] …`

78- **File reservation `reason`**: `bd-###`

79- **Commit messages (optional)**: include `bd-###` for traceability

81Event mirroring (optional automation)

82- On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.

83- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.

85Pitfalls to avoid

86- Don't create or manage tasks in Mail; treat Beads as the single task queue.

87- Always include `bd-###` in message `thread_id` to avoid ID drift across tools.

89# 🔎 cass — Search All Your Agent History

91What: cass indexes conversations from Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, and more into a unified, searchable index. Before solving a problem from scratch, check if any agent already solved something similar.

93⚠️ NEVER run bare cass — it launches an interactive TUI. Always use --robot or --json.

95Quick Start

97# Check if index is healthy (exit 0=ok, 1=run index first)

98cass health

100# Search across all agent histories

101cass search "authentication error" --robot --limit 5

102

103# View a specific result (from search output)

104cass view /path/to/session.jsonl -n 42 --json

105

106# Expand context around a line

107cass expand /path/to/session.jsonl -n 42 -C 3 --json

108

109# Learn the full API

110cass capabilities --json # Feature discovery

111cass robot-docs guide # LLM-optimized docs

112

113Why Use It

114

115- Cross-agent knowledge: Find solutions from Codex when using Claude, or vice versa

116- Forgiving syntax: Typos and wrong flags are auto-corrected with teaching notes

117- Token-efficient: --fields minimal returns only essential data

118

119Key Flags

120

121| Flag | Purpose |

122|------------------|--------------------------------------------------------|

123| --robot / --json | Machine-readable JSON output (required!) |

124| --fields minimal | Reduce payload: source_path, line_number, agent only |

125| --limit N | Cap result count |

126| --agent NAME | Filter to specific agent (claude, codex, cursor, etc.) |

127| --days N | Limit to recent N days |

128

129stdout = data only, stderr = diagnostics. Exit 0 = success.

130

131<skills_system priority="1">

132

133## Available Skills

134

135

136<usage>

137When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.

138

139How to use skills:

140- Invoke: Bash("npx openskills read <skill-name>")

141- The skill content will load with detailed instructions on how to complete the task

142- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)

143

144Usage notes:

145- Only use skills listed in <available_skills> below

146- Do not invoke a skill that is already loaded in your context

147- Each skill invocation is stateless

148</usage>

149

150<available_skills>

151

152<skill>

153<name>agent-builder</name>

154<description>Use when creating, improving, or troubleshooting Claude Code subagents. Expert guidance on agent design, system prompts, tool access, model selection, and best practices for building specialized AI assistants.</description>

155<location>project</location>

156</skill>

157

158<skill>

159<name>aws-beanstalk-expert</name>

160<description>Expert knowledge for deploying, managing, and troubleshooting AWS Elastic Beanstalk applications with production best practices</description>

161<location>project</location>

162</skill>

163

164<skill>

165<name>beanstalk-deploy</name>

166<description>"Robust deployment patterns for Elastic Beanstalk with GitHub Actions, Pulumi, and edge case handling"</description>

167<location>project</location>

168</skill>

169

170<skill>

171<name>claude-hook-writer</name>

172<description>Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls</description>

173<location>project</location>

174</skill>

175

176<skill>

177<name>creating-agents-md</name>

178<description>Use when creating agents.md files - provides plain markdown format with NO frontmatter, free-form structure, and project context guidelines for AI coding assistants</description>

179<location>project</location>

180</skill>

181

182<skill>

183<name>creating-claude-agents</name>

184<description>Use when creating or improving Claude Code agents. Expert guidance on agent file structure, frontmatter, persona definition, tool access, model selection, and validation against schema.</description>

185<location>project</location>

186</skill>

187

188<skill>

189<name>creating-claude-commands</name>

190<description>Expert guidance for creating Claude Code slash commands with correct frontmatter, structure, and best practices</description>

191<location>project</location>

192</skill>

193

194<skill>

195<name>creating-claude-hooks</name>

196<description>Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure</description>

197<location>project</location>

198</skill>

199

200<skill>

201<name>creating-continue-packages</name>

202<description>Use when creating Continue rules - provides required name field, alwaysApply semantics, glob/regex patterns, and markdown format with optional frontmatter</description>

203<location>project</location>

204</skill>

205

206<skill>

207<name>creating-copilot-packages</name>

208<description>Use when creating GitHub Copilot instructions - provides repository-wide and path-specific formats, applyTo patterns, excludeAgent options, and natural language markdown style</description>

209<location>project</location>

210</skill>

211

212<skill>

213<name>creating-cursor-commands</name>

214<description>Expert guidance for creating effective Cursor slash commands with best practices, format requirements, and schema validation</description>

215<location>project</location>

216</skill>

217

218<skill>

219<name>creating-cursor-rules-skill</name>

220<description>Expert guidance for creating effective Cursor IDE rules with best practices, patterns, and examples</description>

221<location>project</location>

222</skill>

223

224<skill>

225<name>creating-kiro-agents</name>

226<description>Use when building custom Kiro AI agents or when user asks for agent configurations - provides JSON structure, tool configuration, prompt patterns, and security best practices for specialized development assistants</description>

227<location>project</location>

228</skill>

229

230<skill>

231<name>creating-kiro-packages</name>

232<description>Use when creating Kiro steering files or hooks - provides inclusion modes (always/fileMatch/manual), foundational files (product.md/tech.md/structure.md), and JSON hook configuration with event triggers</description>

233<location>project</location>

234</skill>

235

236<skill>

237<name>creating-skills</name>

238<description>Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples</description>

239<location>project</location>

240</skill>

241

242<skill>

243<name>creating-windsurf-packages</name>

244<description>Use when creating Windsurf rules - provides plain markdown format with NO frontmatter, 12,000 character limit, and single-file structure requirements</description>

245<location>project</location>

246</skill>

247

248<skill>

249<name>documentation-standards</name>

250<description>Standards and guidelines for organizing, structuring, and maintaining documentation in the PRPM repository - ensures consistency across user docs, development docs, and internal references</description>

251<location>project</location>

252</skill>

253

254<skill>

255<name>elastic-beanstalk-deployment</name>

256<description>Use when deploying Node.js applications to AWS Elastic Beanstalk or troubleshooting deployment issues - provides dependency installation strategies, monorepo handling, and deployment best practices</description>

257<location>project</location>

258</skill>

259

260<skill>

261<name>github-actions-testing</name>

262<description>Expert guidance for testing and validating GitHub Actions workflows before deployment - catches cache errors, path issues, monorepo dependencies, and service container problems that local testing misses</description>

263<location>project</location>

264</skill>

265

266<skill>

267<name>human-writing</name>

268<description>Write content that sounds natural, conversational, and authentically human - avoiding AI-generated patterns, corporate speak, and generic phrasing</description>

269<location>project</location>

270</skill>

271

272<skill>

273<name>integrating-stripe-webhooks</name>

274<description>Use when implementing Stripe webhook endpoints and getting 'Raw body not available' or signature verification errors - provides raw body parsing solutions and subscription period field fixes across frameworks</description>

275<location>project</location>

276</skill>

277

278<skill>

279<name>karen-repo-reviewer</name>

280<description>Use when the user requests a repository review, code assessment, or honest evaluation of their codebase. Provides brutally honest AI-powered reviews with market-aware Karen Scores (0-100) analyzing over-engineering, completion honesty, and practical value. Available as GitHub Action or IDE tool.</description>

281<location>project</location>

282</skill>

283

284<skill>

285<name>postgres-migrations</name>

286<description>Comprehensive guide to PostgreSQL migrations - common errors, generated columns, full-text search, indexes, idempotent migrations, and best practices for database schema changes</description>

287<location>project</location>

288</skill>

289

290<skill>

291<name>prpm-development</name>

292<description>Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base covering architecture, format conversion, package types, collections, quality standards, testing, and deployment</description>

293<location>project</location>

294</skill>

295

296<skill>

297<name>prpm-json-best-practices</name>

298<description>Best practices for structuring prpm.json package manifests with required fields, tags, organization, multi-package management, enhanced file format, and conversion hints</description>

299<location>project</location>

300</skill>

301

302<skill>

303<name>pulumi-troubleshooting</name>

304<description>Comprehensive guide to troubleshooting Pulumi TypeScript errors, infrastructure issues, and best practices - covers common errors, Outputs handling, AWS Beanstalk deployment, and cost optimization</description>

305<location>project</location>

306</skill>

307

308<skill>

309<name>self-improving</name>

310<description>Use when starting infrastructure, testing, deployment, or framework-specific tasks - automatically searches PRPM registry for relevant expertise packages and suggests installation to enhance capabilities for the current task</description>

311<location>project</location>

312</skill>

313

314<skill>

315<name>slash-command-builder</name>

316<description>Use when creating, improving, or troubleshooting Claude Code slash commands. Expert guidance on command structure, arguments, frontmatter, tool permissions, and best practices for building effective custom commands.</description>

317<location>project</location>

318</skill>

319

320<skill>

321<name>thoroughness</name>

322<description>Use when implementing complex multi-step tasks, fixing critical bugs, or when quality and completeness matter more than speed - ensures comprehensive implementation without shortcuts through systematic analysis, implementation, and verification phases</description>

323<location>project</location>

324</skill>

325

326<skill>

327<name>typescript-hook-writer</name>

328<description>Expert guidance for developing Claude Code hooks in TypeScript with shared utilities, esbuild compilation, and Vitest testing - distributes compiled JS while maintaining TypeScript development experience</description>

329<location>project</location>

330</skill>

331

332<skill>

333<name>typescript-type-safety</name>

334<description>Use when encountering TypeScript any types, type errors, or lax type checking - eliminates type holes and enforces strict type safety through proper interfaces, type guards, and module augmentation</description>

335<location>project</location>

336</skill>

337

338</available_skills>

339

340

341</skills_system>

342

343

344# Agent Relay

345

346Real-time agent-to-agent messaging. Output `->relay:` patterns to communicate.

347

348## Sending Messages

349

350**Always use the fenced format** for reliable message delivery:

351

352```

353->relay:AgentName <<<

354Your message here.>>>

355```

356

357```

358->relay:* <<<

359Broadcast to all agents.>>>

360```

361

362**CRITICAL:** Always close multi-line messages with `>>>` on its own line!

363

364## Communication Protocol

365

366**ACK immediately** - When you receive a task, acknowledge it before starting work:

367

368```

369->relay:Sender <<<

370ACK: Brief description of task received>>>

371```

372

373Then proceed with your work. This confirms message delivery and lets the sender know you're on it.

374

375**Report completion** - When done, send a completion message:

376

377```

378->relay:Sender <<<

379DONE: Brief summary of what was completed>>>

380```

381

382## Receiving Messages

383

384Messages appear as:

385```

386Relay message from Alice [abc123]: Message content here

387```

388

389### Channel Routing (Important!)

390

391Messages from #general (broadcast channel) include a `[#general]` indicator:

392```

393Relay message from Alice [abc123] [#general]: Hello everyone!

394```

395

396**When you see `[#general]`**: Reply to `*` (broadcast), NOT to the sender directly.

397

398```

399# Correct - responds to #general channel

400->relay:* <<<

401Response to the group message.>>>

402

403# Wrong - sends as DM to sender instead of to the channel

404->relay:Alice <<<

405Response to the group message.>>>

406```

407

408This ensures your response appears in the same channel as the original message.

409

410If truncated, read full message:

411```bash

412agent-relay read abc123

413```

414

415## Spawning Agents

416

417Spawn workers to delegate tasks:

418

419```

420->relay:spawn WorkerName claude "task description"

421->relay:release WorkerName

422```

423

424## Threads

425

426Use threads to group related messages together. Thread syntax:

427

428```

429->relay:AgentName [thread:topic-name] <<<

430Your message here.>>>

431```

432

433**When to use threads:**

434- Working on a specific issue (e.g., `[thread:agent-relay-299]`)

435- Back-and-forth discussions with another agent

436- Code review conversations

437- Any multi-message topic you want grouped

438

439**Examples:**

440

441```

442->relay:Protocol [thread:auth-feature] <<<

443How should we handle token refresh?>>>

444

445->relay:Frontend [thread:auth-feature] <<<

446Use a 401 interceptor that auto-refreshes.>>>

447

448->relay:Reviewer [thread:pr-123] <<<

449Please review src/auth/*.ts>>>

450

451->relay:Developer [thread:pr-123] <<<

452LGTM, approved!>>>

453```

454

455Thread messages appear grouped in the dashboard with reply counts.

456

457## Common Patterns

458

459```

460->relay:Lead <<<

461ACK: Starting /api/register implementation>>>

462

463->relay:* <<<

464STATUS: Working on auth module>>>

465

466->relay:Lead <<<

467DONE: Auth module complete>>>

468

469->relay:Developer <<<

470TASK: Implement /api/register>>>

471

472->relay:Reviewer [thread:code-review-auth] <<<

473REVIEW: Please check src/auth/*.ts>>>

474

475->relay:Architect <<<

476QUESTION: JWT or sessions?>>>

477```

478

479## Rules

480

481- Pattern must be at line start (whitespace OK)

482- Escape with `\->relay:` to output literally

483- Check daemon status: `agent-relay status`

484

485

@@ −1 +1 @@

1−

1+* Use the `bd` tool instead of markdown to coordinate all work and tasks.

2+* NEVER commit changes unless the user explicitly asks you to.

4+# Using bv as an AI sidecar

4−

6+bv is a fast terminal UI for Beads projects (.beads/beads.jsonl). It renders lists/details and precomputes dependency metrics (PageRank, critical path, cycles, etc.) so you instantly see blockers and execution order. For agents, it’s a graph sidecar: instead of parsing JSONL or risking hallucinated traversal, call the robot flags to get deterministic, dependency-aware outputs.

6−<skills_system priority="1">

8+*IMPORTANT: As an agent, you must ONLY use bv with the robot flags, otherwise you'll get stuck in the interactive TUI that's intended for human usage only!*

8−## Available Skills

10+- bv --robot-help — shows all AI-facing commands.

11+- bv --robot-insights — JSON graph metrics (PageRank, betweenness, HITS, critical path, cycles) with top-N summaries for quick triage.

12+- bv --robot-plan — JSON execution plan: parallel tracks, items per track, and unblocks lists showing what each item frees up.

13+- bv --robot-priority — JSON priority recommendations with reasoning and confidence.

14+- bv --robot-recipes — list recipes (default, actionable, blocked, etc.); apply via bv --recipe <name> to pre-filter/sort before other flags.

15+- bv --robot-diff --diff-since <commit|date> — JSON diff of issue changes, new/closed items, and cycles introduced/resolved.

916

10−

17+Use these commands instead of hand-rolling graph logic; bv already computes the hard parts so agents can act safely and quickly.

1118

12−<skills_system priority="1">

13−<usage>

14−When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.

19+## MCP Agent Mail: coordination for multi-agent workflows

1520

16−How to use skills (loaded into main context):

17−- Use the <path> from the skill entry below

18−- Invoke: Bash("cat <path>")

19−- The skill content will load into your current context

20−- Example: Bash("cat .openskills/backend-architect/SKILL.md")

21+What it is

22+- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.

23+- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.

2124

22−Usage notes:

23−- Skills share your context window

24−- Do not invoke a skill that is already loaded in your context

25−</usage>

25+Why it's useful

26+- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.

27+- Keeps communication out of your token budget by storing messages in a per-project archive.

28+- Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.

2629

27−<available_skills>

30+How to use effectively

31+1) Same repository

32+ - Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.

33+ - Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.

34+ - Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.

35+ - Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20` or `resource://thread/{id}?project=<abs-path>&include_bodies=true`.

36+ - Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.

2837

29−<skill>

30−<name>prpm-development</name>

31−<description>Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base covering architecture, format conversion, package types, collections, quality standards, testing, and deployment</description>

32−<path>.openskills/prpm-development/SKILL.md</path>

33−</skill>

38+2) Across different repos in one project (e.g., Next.js frontend + FastAPI backend)

39+ - Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).

40+ - Option B (separate projects): each repo has its own `project_key`; use `macro_contact_handshake` or `request_contact`/`respond_contact` to link agents, then message directly. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.

3441

35−<skill>

36−<name>osgrep-skill</name>

37−<description>Skill for using osgrep semantic code search - teaches how to effectively search codebases using natural language queries instead of exact string matching</description>

38−<path>.openskills/osgrep-skill/SKILL.md</path>

39−</skill>

42+Macros vs granular tools

43+- Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.

44+- Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.

4045

41−</available_skills>

42−</skills_system>

46+Common pitfalls

47+- "from_agent not registered": always `register_agent` in the correct `project_key` first.

48+- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.

49+- Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.

4350

44−

4551

46−</skills_system>

52+## Integrating with Beads (dependency-aware task planning)

4753

54+Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: [steveyegge/beads](https://github.com/steveyegge/beads)

4855

56+Recommended conventions

57+- **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).

58+- **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.

59+- **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.

4960

50−

61+Typical flow (agents)

62+1) **Pick ready work** (Beads)

63+ - `bd ready --json` → choose one item (highest priority, no blockers)

64+2) **Reserve edit surface** (Mail)

65+ - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`

66+3) **Announce start** (Mail)

67+ - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`

68+4) **Work and update**

69+ - Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id

70+5) **Complete and release**

71+ - `bd close bd-123 --reason "Completed"` (Beads is status authority)

72+ - `release_file_reservations(project_key, agent_name, paths=["src/**"])`

73+ - Final Mail reply: `[bd-123] Completed` with summary and links

5174

52−

53−

54−

75+Mapping cheat-sheet

76+- **Mail `thread_id`** ↔ `bd-###`

77+- **Mail subject**: `[bd-###] …`

78+- **File reservation `reason`**: `bd-###`

79+- **Commit messages (optional)**: include `bd-###` for traceability

5580

56−# Individual package

81+Event mirroring (optional automation)

82+- On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.

83+- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.

5784

58−Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base covering architecture, format conversion, package types, collections, quality standards, testing, and deployment

85+Pitfalls to avoid

86+- Don't create or manage tasks in Mail; treat Beads as the single task queue.

87+- Always include `bd-###` in message `thread_id` to avoid ID drift across tools.

5988

60−## Mission

89+# 🔎 cass — Search All Your Agent History

6190

62−Build the npm/cargo/pip equivalent for AI development artifacts. Enable developers to discover, install, share, and manage prompts across Cursor, Claude Code, Continue, Windsurf, and future AI editors.

91+What: cass indexes conversations from Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, and more into a unified, searchable index. Before solving a problem from scratch, check if any agent already solved something similar.

6392

64−## Core Architecture

93+⚠️ NEVER run bare cass — it launches an interactive TUI. Always use --robot or --json.

6594

66−### Git Workflow - CRITICAL RULES

95+Quick Start

6796

68−```bash

69−git checkout -b feature/your-feature-name

70− # or

71− git checkout -b fix/bug-description

72−```

97+# Check if index is healthy (exit 0=ok, 1=run index first)

98+cass health

7399

74−## Package Types

100+# Search across all agent histories

101+cass search "authentication error" --robot --limit 5

75102

76−- Knowledge and guidelines for AI assistants

103+# View a specific result (from search output)

104+cass view /path/to/session.jsonl -n 42 --json

77105

78−- `.claude/skills/`, `.cursor/rules/`

106+# Expand context around a line

107+cass expand /path/to/session.jsonl -n 42 -C 3 --json

79108

80−- `@prpm/pulumi-troubleshooting`, `@typescript/best-practices`

109+# Learn the full API

110+cass capabilities --json # Feature discovery

111+cass robot-docs guide # LLM-optimized docs

81112

82−- Autonomous AI agents for multi-step tasks

113+Why Use It

83114

84−- `.claude/agents/`, `.cursor/agents/`

115+- Cross-agent knowledge: Find solutions from Codex when using Claude, or vice versa

116+- Forgiving syntax: Typos and wrong flags are auto-corrected with teaching notes

117+- Token-efficient: --fields minimal returns only essential data

85118

86−- `@prpm/code-reviewer`, `@cursor/debugging-agent`

119+Key Flags

87120

88−- Specific instructions or constraints for AI behavior

121+| Flag | Purpose |

122+|------------------|--------------------------------------------------------|

123+| --robot / --json | Machine-readable JSON output (required!) |

124+| --fields minimal | Reduce payload: source_path, line_number, agent only |

125+| --limit N | Cap result count |

126+| --agent NAME | Filter to specific agent (claude, codex, cursor, etc.) |

127+| --days N | Limit to recent N days |

89128

90−- `.cursor/rules/`, `.cursorrules`

129+stdout = data only, stderr = diagnostics. Exit 0 = success.

91130

92−- `@cursor/react-conventions`, `@cursor/test-first`

131+<skills_system priority="1">

93132

94−- Extensions that add functionality

133+## Available Skills

95134

96−- `.cursor/plugins/`, `.claude/plugins/`

135+

136+<usage>

137+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.

97138

98−- Reusable prompt templates

139+How to use skills:

140+- Invoke: Bash("npx openskills read <skill-name>")

141+- The skill content will load with detailed instructions on how to complete the task

142+- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)

99143

100−- `.prompts/`, project-specific directories

144+Usage notes:

145+- Only use skills listed in <available_skills> below

146+- Do not invoke a skill that is already loaded in your context

147+- Each skill invocation is stateless

148+</usage>

101149

102−- Multi-step automation workflows

150+<available_skills>

103151

104−- `.workflows/`, `.github/workflows/`

152+<skill>

153+<name>agent-builder</name>

154+<description>Use when creating, improving, or troubleshooting Claude Code subagents. Expert guidance on agent design, system prompts, tool access, model selection, and best practices for building specialized AI assistants.</description>

155+<location>project</location>

156+</skill>

105157

106−- Executable utilities and scripts

158+<skill>

159+<name>aws-beanstalk-expert</name>

160+<description>Expert knowledge for deploying, managing, and troubleshooting AWS Elastic Beanstalk applications with production best practices</description>

161+<location>project</location>

162+</skill>

107163

108−- `scripts/`, `tools/`, `.bin/`

164+<skill>

165+<name>beanstalk-deploy</name>

166+<description>"Robust deployment patterns for Elastic Beanstalk with GitHub Actions, Pulumi, and edge case handling"</description>

167+<location>project</location>

168+</skill>

109169

110−- Reusable file and project templates

170+<skill>

171+<name>claude-hook-writer</name>

172+<description>Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls</description>

173+<location>project</location>

174+</skill>

111175

112−- `templates/`, project-specific directories

176+<skill>

177+<name>creating-agents-md</name>

178+<description>Use when creating agents.md files - provides plain markdown format with NO frontmatter, free-form structure, and project context guidelines for AI coding assistants</description>

179+<location>project</location>

180+</skill>

113181

114−- Model Context Protocol servers

182+<skill>

183+<name>creating-claude-agents</name>

184+<description>Use when creating or improving Claude Code agents. Expert guidance on agent file structure, frontmatter, persona definition, tool access, model selection, and validation against schema.</description>

185+<location>project</location>

186+</skill>

115187

116−- `.mcp/servers/`

188+<skill>

189+<name>creating-claude-commands</name>

190+<description>Expert guidance for creating Claude Code slash commands with correct frontmatter, structure, and best practices</description>

191+<location>project</location>

192+</skill>

117193

118−## Format Conversion System

194+<skill>

195+<name>creating-claude-hooks</name>

196+<description>Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure</description>

197+<location>project</location>

198+</skill>

119199

120−- Cursor (.mdc)

200+<skill>

201+<name>creating-continue-packages</name>

202+<description>Use when creating Continue rules - provides required name field, alwaysApply semantics, glob/regex patterns, and markdown format with optional frontmatter</description>

203+<location>project</location>

204+</skill>

121205

122−- MDC frontmatter with `ruleType`, `alwaysApply`, `description`

206+<skill>

207+<name>creating-copilot-packages</name>

208+<description>Use when creating GitHub Copilot instructions - provides repository-wide and path-specific formats, applyTo patterns, excludeAgent options, and natural language markdown style</description>

209+<location>project</location>

210+</skill>

123211

124−- Markdown body

212+<skill>

213+<name>creating-cursor-commands</name>

214+<description>Expert guidance for creating effective Cursor slash commands with best practices, format requirements, and schema validation</description>

215+<location>project</location>

216+</skill>

125217

126−- Simple, focused on coding rules

218+<skill>

219+<name>creating-cursor-rules-skill</name>

220+<description>Expert guidance for creating effective Cursor IDE rules with best practices, patterns, and examples</description>

221+<location>project</location>

222+</skill>

127223

128−- No structured tools/persona definitions

224+<skill>

225+<name>creating-kiro-agents</name>

226+<description>Use when building custom Kiro AI agents or when user asks for agent configurations - provides JSON structure, tool configuration, prompt patterns, and security best practices for specialized development assistants</description>

227+<location>project</location>

228+</skill>

129229

130−- Claude (agent format)

230+<skill>

231+<name>creating-kiro-packages</name>

232+<description>Use when creating Kiro steering files or hooks - provides inclusion modes (always/fileMatch/manual), foundational files (product.md/tech.md/structure.md), and JSON hook configuration with event triggers</description>

233+<location>project</location>

234+</skill>

131235

132−- YAML frontmatter: `name`, `description`

236+<skill>

237+<name>creating-skills</name>

238+<description>Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples</description>

239+<location>project</location>

240+</skill>

133241

134−- Optional: `tools` (comma-separated), `model` (sonnet/opus/haiku/inherit)

242+<skill>

243+<name>creating-windsurf-packages</name>

244+<description>Use when creating Windsurf rules - provides plain markdown format with NO frontmatter, 12,000 character limit, and single-file structure requirements</description>

245+<location>project</location>

246+</skill>

135247

136−- Markdown body

248+<skill>

249+<name>documentation-standards</name>

250+<description>Standards and guidelines for organizing, structuring, and maintaining documentation in the PRPM repository - ensures consistency across user docs, development docs, and internal references</description>

251+<location>project</location>

252+</skill>

137253

138−- Supports persona, examples, instructions

254+<skill>

255+<name>elastic-beanstalk-deployment</name>

256+<description>Use when deploying Node.js applications to AWS Elastic Beanstalk or troubleshooting deployment issues - provides dependency installation strategies, monorepo handling, and deployment best practices</description>

257+<location>project</location>

258+</skill>

139259

140−- Continue (JSON)

260+<skill>

261+<name>github-actions-testing</name>

262+<description>Expert guidance for testing and validating GitHub Actions workflows before deployment - catches cache errors, path issues, monorepo dependencies, and service container problems that local testing misses</description>

263+<location>project</location>

264+</skill>

141265

142−- JSON configuration

266+<skill>

267+<name>human-writing</name>

268+<description>Write content that sounds natural, conversational, and authentically human - avoiding AI-generated patterns, corporate speak, and generic phrasing</description>

269+<location>project</location>

270+</skill>

143271

144−- Simple prompts, context rules

272+<skill>

273+<name>integrating-stripe-webhooks</name>

274+<description>Use when implementing Stripe webhook endpoints and getting 'Raw body not available' or signature verification errors - provides raw body parsing solutions and subscription period field fixes across frameworks</description>

275+<location>project</location>

276+</skill>

145277

146−- Limited metadata support

278+<skill>

279+<name>karen-repo-reviewer</name>

280+<description>Use when the user requests a repository review, code assessment, or honest evaluation of their codebase. Provides brutally honest AI-powered reviews with market-aware Karen Scores (0-100) analyzing over-engineering, completion honesty, and practical value. Available as GitHub Action or IDE tool.</description>

281+<location>project</location>

282+</skill>

147283

148−- Windsurf

284+<skill>

285+<name>postgres-migrations</name>

286+<description>Comprehensive guide to PostgreSQL migrations - common errors, generated columns, full-text search, indexes, idempotent migrations, and best practices for database schema changes</description>

287+<location>project</location>

288+</skill>

149289

150−- Similar to Cursor

290+<skill>

291+<name>prpm-development</name>

292+<description>Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base covering architecture, format conversion, package types, collections, quality standards, testing, and deployment</description>

293+<location>project</location>

294+</skill>

151295

152−- Markdown-based

296+<skill>

297+<name>prpm-json-best-practices</name>

298+<description>Best practices for structuring prpm.json package manifests with required fields, tags, organization, multi-package management, enhanced file format, and conversion hints</description>

299+<location>project</location>

300+</skill>

153301

154−- Basic structure

302+<skill>

303+<name>pulumi-troubleshooting</name>

304+<description>Comprehensive guide to troubleshooting Pulumi TypeScript errors, infrastructure issues, and best practices - covers common errors, Outputs handling, AWS Beanstalk deployment, and cost optimization</description>

305+<location>project</location>

306+</skill>

155307

156−- Missing tools: -10 points

308+<skill>

309+<name>self-improving</name>

310+<description>Use when starting infrastructure, testing, deployment, or framework-specific tasks - automatically searches PRPM registry for relevant expertise packages and suggests installation to enhance capabilities for the current task</description>

311+<location>project</location>

312+</skill>

157313

158−- Missing persona: -5 points

314+<skill>

315+<name>slash-command-builder</name>

316+<description>Use when creating, improving, or troubleshooting Claude Code slash commands. Expert guidance on command structure, arguments, frontmatter, tool permissions, and best practices for building effective custom commands.</description>

317+<location>project</location>

318+</skill>

159319

160−- Missing examples: -5 points

320+<skill>

321+<name>thoroughness</name>

322+<description>Use when implementing complex multi-step tasks, fixing critical bugs, or when quality and completeness matter more than speed - ensures comprehensive implementation without shortcuts through systematic analysis, implementation, and verification phases</description>

323+<location>project</location>

324+</skill>

161325

162−- Unsupported sections: -10 points each

326+<skill>

327+<name>typescript-hook-writer</name>

328+<description>Expert guidance for developing Claude Code hooks in TypeScript with shared utilities, esbuild compilation, and Vitest testing - distributes compiled JS while maintaining TypeScript development experience</description>

329+<location>project</location>

330+</skill>

163331

164−- Format-specific features lost: -5 points

332+<skill>

333+<name>typescript-type-safety</name>

334+<description>Use when encountering TypeScript any types, type errors, or lax type checking - eliminates type holes and enforces strict type safety through proper interfaces, type guards, and module augmentation</description>

335+<location>project</location>

336+</skill>

165337

166−- **Canonical ↔ Claude**: Nearly lossless (95-100%)

338+</available_skills>

339+

167340

168−- **Canonical ↔ Cursor**: Lossy on tools/persona (70-85%)

341+</skills_system>

169342

170−- **Canonical ↔ Continue**: Most lossy (60-75%)

343+

344+# Agent Relay

171345

172−## Collections System

346+Real-time agent-to-agent messaging. Output `->relay:` patterns to communicate.

173347

174−### Collection Structure

348+## Sending Messages

175349

176−```json

177−{

178− "id": "@collection/nextjs-pro",

179− "name": "Next.js Professional Setup",

180− "description": "Complete Next.js development setup",

181− "category": "frontend",

182− "packages": [

183− {

184− "packageId": "react-best-practices",

185− "required": true,

186− "reason": "Core React patterns"

187− },

188− {

189− "packageId": "typescript-strict",

190− "required": true,

191− "reason": "Type safety"

192− },

193− {

194− "packageId": "tailwind-helper",

195− "required": false,

196− "reason": "Styling utilities"

197− }

198− ]

199−}

200−```

350+**Always use the fenced format** for reliable message delivery:

201351

202−### Installation Formats (Priority Order)

203−

204−```bash

205−prpm install collections/nextjs-pro

206−prpm install collections/nextjs-pro@2.0.0

207352 ```

208−

209−### Registry Resolution Logic

210−

211−```typescript

212−// When scope is 'collection' (default from CLI for collections/* prefix):

213−if (scope === 'collection') {

214− // Search across ALL scopes, prioritize by:

215− // 1. Official collections (official = true)

216− // 2. Verified authors (verified = true)

217− // 3. Most downloads

218− // 4. Most recent

219− SELECT * FROM collections

220− WHERE name_slug = $1

221− ORDER BY official DESC, verified DESC, downloads DESC, created_at DESC

222− LIMIT 1

223−} else {

224− // Explicit scope: exact match only

225− SELECT * FROM collections

226− WHERE scope = $1 AND name_slug = $2

227− ORDER BY created_at DESC

228− LIMIT 1

229−}

353+->relay:AgentName <<<

354+Your message here.>>>

230355 ```

231356

232−### CLI Resolution Logic

233−

234−```typescript

235−// Parse collection spec:

236−// - collections/nextjs-pro → scope='collection', name_slug='nextjs-pro'

237−// - khaliqgant/nextjs-pro → scope='khaliqgant', name_slug='nextjs-pro'

238−// - @khaliqgant/nextjs-pro → scope='khaliqgant', name_slug='nextjs-pro'

239−// - nextjs-pro → scope='collection', name_slug='nextjs-pro'

240−

241−const matchWithScope = collectionSpec.match(/^@?([^/]+)\/([^/@]+)(?:@(.+))?$/);

242−if (matchWithScope) {

243− [, scope, name_slug, version] = matchWithScope;

244−} else {

245− // No scope: default to 'collection'

246− [, name_slug, version] = collectionSpec.match(/^([^/@]+)(?:@(.+))?$/);

247− scope = 'collection';

248−}

249357 ```

250−

251−### Version Resolution

252−

253−```bash

254−prpm install collections/nextjs-pro

255−

256−prpm install collections/nextjs-pro@2.0.4

257−

258−prpm install khaliqgant/nextjs-pro@2.0.4

358+->relay:* <<<

359+Broadcast to all agents.>>>

259360 ```

260361

261−### Error Handling

362+**CRITICAL:** Always close multi-line messages with `>>>` on its own line!

262363

263−```bash

264−prpm install collections/nonexistent

265−```

364+## Communication Protocol

266365

267−## Quality & Ranking System

366+**ACK immediately** - When you receive a task, acknowledge it before starting work:

268367

269−- (0-30 points):

270−

271−- Total downloads (weighted by recency)

272−

273−- Stars/favorites

274−

275−- Trending velocity

276−

277−- (0-30 points):

278−

279−- User ratings (1-5 stars)

280−

281−- Review sentiment

282−

283−- Documentation completeness

284−

285−- (0-20 points):

286−

287−- Verified author badge

288−

289−- Original creator vs fork

290−

291−- Publisher reputation

292−

293−- Security scan results

294−

295−- (0-10 points):

296−

297−- Last updated date (<30 days = 10 points)

298−

299−- Release frequency

300−

301−- Active maintenance

302−

303−- (0-10 points):

304−

305−- Has README

306−

307−- Has examples

308−

309−- Has tags

310−

311−- Complete metadata

312−

313−## Technical Stack

314−

315−- **Commander.js**: CLI framework

316−

317−- **Fastify Client**: HTTP client for registry

318−

319−- **Tar**: Package tarball creation/extraction

320−

321−- **Chalk**: Terminal colors

322−

323−- **Ora**: Spinners for async operations

324−

325−- **Fastify**: High-performance web framework

326−

327−- **PostgreSQL**: Primary database with GIN indexes

328−

329−- **Redis**: Caching layer for converted packages

330−

331−- **GitHub OAuth**: Authentication provider

332−

333−- **Docker**: Containerized deployment

334−

335−- **Vitest**: Unit and integration tests

336−

337−- **100% Coverage Goal**: Especially for format converters

338−

339−- **Round-Trip Tests**: Ensure conversion quality

340−

341−- **Fixtures**: Real-world package examples

342−

343−## Testing Standards

344−

345−### Key Testing Patterns

346−

347−```typescript

348−// Format converter test

349−describe('toCursor', () => {

350− it('preserves data in roundtrip', () => {

351− const result = toCursor(canonical);

352− const back = fromCursor(result.content);

353− expect(back).toEqual(canonical);

354− });

355−});

356−

357−// CLI command test

358−describe('install', () => {

359− it('downloads and installs package', async () => {

360− await handleInstall('test-pkg', { as: 'cursor' });

361− expect(fs.existsSync('.cursor/rules/test-pkg.md')).toBe(true);

362− });

363−});

364368 ```

365−

366−## Development Workflow

367−

368−### Package Manager: npm (NOT pnpm)

369−

370−```bash

371−npm install

372−

373−npm install --workspace=@pr-pm/cli

374−

375−npm test

376−

377−npm run build

378−

379−npm run dev --workspace=prpm

369+->relay:Sender <<<

370+ACK: Brief description of task received>>>

380371 ```

381372

382−### Dependency Management Best Practices

373+Then proceed with your work. This confirms message delivery and lets the sender know you're on it.

383374

384−```typescript

385−// BAD - tar-stream is imported dynamically at runtime

386−const tarStream = await import('tar-stream');

387−```

375+**Report completion** - When done, send a completion message:

388376

389−### Environment Variable Management

390−

391−```bash

392−NEW_FEATURE_API_KEY=your-key-here

393377 ```

394−

395−## Security Standards

396−

397−- **No Secrets in DB**: Never store GitHub tokens, use session IDs

398−

399−- **SQL Injection**: Parameterized queries only

400−

401−- **Rate Limiting**: Prevent abuse of registry API

402−

403−- **Content Security**: Validate package contents before publishing

404−

405−## Performance Considerations

406−

407−- **Batch Operations**: Use Promise.all for independent operations

408−

409−- **Database Indexes**: GIN for full-text, B-tree for lookups

410−

411−- **Caching Strategy**: Cache converted packages, not raw data

412−

413−- **Lazy Loading**: Don't load full package data until needed

414−

415−- **Connection Pooling**: Reuse PostgreSQL connections

416−

417−## Deployment

418−

419−### Webapp (S3 Static Export) ⚠️ CRITICAL

420−

421−```typescript

422−// ❌ Dynamic route (doesn't work with 'use client')

423− // /app/shared/[token]/page.tsx

424− const params = useParams();

425− const token = params.token;

426−

427− // ✅ Query string with Suspense (works with 'use client')

428− // /app/shared/page.tsx

429− import { Suspense } from 'react';

430−

431− function Content() {

432− const searchParams = useSearchParams();

433− const token = searchParams.get('token');

434− // ... component logic

435− }

436−

437− export default function Page() {

438− return (

439− <Suspense fallback={<div>Loading...</div>}>

440− <Content />

441− </Suspense>

442− );

443− }

378+->relay:Sender <<<

379+DONE: Brief summary of what was completed>>>

444380 ```

445381

446−### Publishing PRPM to NPM

382+## Receiving Messages

447383

448−```bash

449−npm version patch --workspace=prpm --workspace=@prpm/registry-client

450−

451−npm version minor --workspace=prpm

384+Messages appear as:

452385 ```

453−

454−## Common Patterns

455−

456−### CLI Command Structure

457−

458−```typescript

459−export async function handleCommand(args: Args, options: Options) {

460− const startTime = Date.now();

461− try {

462− const config = await loadUserConfig();

463− const client = getRegistryClient(config);

464− const result = await client.fetchData();

465− console.log('✅ Success');

466− await telemetry.track({ command: 'name', success: true });

467− } catch (error) {

468− console.error('❌ Failed:', error.message);

469− await telemetry.track({ command: 'name', success: false });

470− process.exit(1);

471− }

472−}

386+Relay message from Alice [abc123]: Message content here

473387 ```

474388

475−### Registry Route Structure

389+### Channel Routing (Important!)

476390

477−```typescript

478−server.get('/:id', {

479− schema: { /* OpenAPI schema */ },

480−}, async (request, reply) => {

481− const { id } = request.params;

482− if (!id) return reply.code(400).send({ error: 'Missing ID' });

483− const result = await server.pg.query('SELECT...');

484− return result.rows[0];

485−});

391+Messages from #general (broadcast channel) include a `[#general]` indicator:

486392 ```

487−

488−### Format Converter Structure

489−

490−```typescript

491−export function toFormat(pkg: CanonicalPackage): ConversionResult {

492− const warnings: string[] = [];

493− let qualityScore = 100;

494− const content = convertSections(pkg.content.sections, warnings);

495− const lossyConversion = warnings.some(w => w.includes('not supported'));

496− if (lossyConversion) qualityScore -= 10;

497− return { content, format: 'target', warnings, qualityScore, lossyConversion };

498−}

393+Relay message from Alice [abc123] [#general]: Hello everyone!

499394 ```

500395

501−## Naming Conventions

396+**When you see `[#general]`**: Reply to `*` (broadcast), NOT to the sender directly.

502397

503−- **Files**: kebab-case (`registry-client.ts`, `to-cursor.ts`)

504−

505−- **Types**: PascalCase (`CanonicalPackage`, `ConversionResult`)

506−

507−- **Functions**: camelCase (`getPackage`, `convertToFormat`)

508−

509−- **Constants**: UPPER_SNAKE_CASE (`DEFAULT_REGISTRY_URL`)

510−

511−- **Database**: snake_case (`package_id`, `created_at`)

512−

513−- **API Requests/Responses**: snake_case (`package_id`, `session_id`, `created_at`)

514−

515−- **Important**: All API request and response fields use snake_case to match PostgreSQL database conventions

516−

517−- Internal service methods may use camelCase, but must convert to snake_case at API boundaries

518−

519−- TypeScript interfaces for API types should use snake_case fields

520−

521−- Examples: `PlaygroundRunRequest.package_id`, `CreditBalance.reset_at`

522−

523−## Documentation Standards

524−

525−- **Inline Comments**: Explain WHY, not WHAT

526−

527−- **JSDoc**: Required for public APIs

528−

529−- **README**: Keep examples up-to-date

530−

531−- **Markdown Docs**: Use code blocks with language tags

532−

533−- **Changelog**: Follow Keep a Changelog format

534−

535−- **Continuous Accuracy**: Documentation must be continuously updated and tended to for accuracy

536−

537−- When adding features, update relevant docs immediately

538−

539−- When fixing bugs, check if docs need corrections

540−

541−- When refactoring, verify examples still work

542−

543−- Review docs quarterly for outdated information

544−

545−- Keep CLI docs, README, and Mintlify docs in sync

546−

547−## Overview

548−

549−Complete knowledge base for developing PRPM - the universal package manager for AI prompts, agents, and rules.

550−

551−## Reference Documentation

552−

553−- `format-conversion.md` - Complete format conversion specs

554−

555−- `package-types.md` - All package types with examples

556−

557−- `collections.md` - Collections system and examples

558−

559−- `quality-ranking.md` - Quality and ranking algorithms

560−

561−- `testing-guide.md` - Testing patterns and standards

562−

563−- `deployment.md` - Deployment procedures

564−

565−

566−

567−

568−

569−

570−

571−

572−

573−# Thoroughness

574−

575−Use when implementing complex multi-step tasks, fixing critical bugs, or when quality and completeness matter more than speed - ensures comprehensive implementation without shortcuts through systematic analysis, implementation, and verification phases

576−

577−## Purpose

578−

579−This skill ensures comprehensive, complete implementation of complex tasks without shortcuts. Use this when quality and completeness matter more than speed.

580−

581−## When to Use

582−

583−- Fixing critical bugs or compilation errors

584−

585−- Implementing complex multi-step features

586−

587−- Debugging test failures

588−

589−- Refactoring large codebases

590−

591−- Production deployments

592−

593−- Any task where shortcuts could cause future problems

594−

595−## Methodology

596−

597−- **Identify All Issues**

598−

599−- List every error, warning, and failing test

600−

601−- Group related issues together

602−

603−- Prioritize by dependency order

604−

605−- Create issue hierarchy (what blocks what)

606−

607−- **Root Cause Analysis**

608−

609−- Don't fix symptoms, find root causes

610−

611−- Trace errors to their source

612−

613−- Identify patterns in failures

614−

615−- Document assumptions that were wrong

616−

617−- **Create Detailed Plan**

618−

619−- Break down into atomic steps

620−

621−- Estimate time for each step

622−

623−- Identify dependencies between steps

624−

625−- Plan verification for each step

626−

627−- Schedule breaks/checkpoints

628−

629−- **Fix Issues in Dependency Order**

630−

631−- Start with foundational issues

632−

633−- Fix one thing completely before moving on

634−

635−- Test after each fix

636−

637−- Document what was changed and why

638−

639−- **Verify Each Fix**

640−

641−- Write/run tests for the specific fix

642−

643−- Check for side effects

644−

645−- Verify related functionality still works

646−

647−- Document test results

648−

649−- **Track Progress**

650−

651−- Mark issues as completed

652−

653−- Update plan with new discoveries

654−

655−- Adjust time estimates

656−

657−- Note any blockers immediately

658−

659−- **Run All Tests**

660−

661−- Unit tests

662−

663−- Integration tests

664−

665−- E2E tests

666−

667−- Manual verification

668−

669−- **Cross-Check Everything**

670−

671−- Review all changed files

672−

673−- Verify compilation succeeds

674−

675−- Check for console errors/warnings

676−

677−- Test edge cases

678−

679−- **Documentation**

680−

681−- Update relevant docs

682−

683−- Add inline comments for complex fixes

684−

685−- Document known limitations

686−

687−- Create issues for future work

688−

689−## Anti-Patterns to Avoid

690−

691−- ❌ Fixing multiple unrelated issues at once

692−

693−- ❌ Moving on before verifying a fix works

694−

695−- ❌ Assuming similar errors have the same cause

696−

697−- ❌ Skipping test writing "to save time"

698−

699−- ❌ Copy-pasting solutions without understanding

700−

701−- ❌ Ignoring warnings "because it compiles"

702−

703−- ❌ Making changes without reading existing code first

704−

705−## Quality Checkpoints

706−

707−- [ ] Can I explain why this fix works?

708−

709−- [ ] Have I tested this specific change?

710−

711−- [ ] Are there any side effects?

712−

713−- [ ] Is this the root cause or a symptom?

714−

715−- [ ] Will this prevent similar issues in the future?

716−

717−- [ ] Is the code readable and maintainable?

718−

719−- [ ] Have I documented non-obvious decisions?

720−

721−## Example Workflow

722−

723−### Bad Approach (Shortcut-Driven)

724−

725−*Bad example*

726−

727398 ```

728−1. See 24 TypeScript errors

729−2. Add @ts-ignore to all of them

730−3. Hope tests pass

731−4. Move on

732−```

399+# Correct - responds to #general channel

400+->relay:* <<<

401+Response to the group message.>>>

733402

734−### Good Approach (Thoroughness-Driven)

735−

736−*Good example*

737−

403+# Wrong - sends as DM to sender instead of to the channel

404+->relay:Alice <<<

405+Response to the group message.>>>

738406 ```

739−1. List all 24 errors systematically

740−2. Group by error type (7 missing types, 10 unknown casts, 7 property access)

741−3. Find root causes:

742− - Missing @types/tar package

743− - No type assertions on fetch responses

744− - Implicit any types in callbacks

745−4. Fix by category:

746− - Install @types/tar (fixes 7 errors)

747− - Add proper type assertions to registry-client.ts (fixes 10 errors)

748− - Add explicit parameter types (fixes 7 errors)

749−5. Test after each category

750−6. Run full test suite

751−7. Document what was learned

752−```

753407

754−## Time Investment

408+This ensures your response appears in the same channel as the original message.

755409

756−- Initial: 2-3x slower than shortcuts

757−

758−- Long-term: 10x faster (no debugging later, no rework)

759−

760−- Quality: Near-perfect first time

761−

762−- Maintenance: Minimal

763−

764−## Success Metrics

765−

766−- ✅ 100% of tests passing

767−

768−- ✅ Zero warnings in production build

769−

770−- ✅ All code has test coverage

771−

772−- ✅ Documentation is complete and accurate

773−

774−- ✅ No known issues or TODOs left behind

775−

776−- ✅ Future developers can understand the code

777−

778−## Mantras

779−

780−- "Slow is smooth, smooth is fast"

781−

782−- "Do it right the first time"

783−

784−- "Test everything, assume nothing"

785−

786−- "Document for your future self"

787−

788−- "Root causes, not symptoms"

789−

790−

791−

792−

793−

794−

795−

796−

797−

798−# TypeScript Type Safety

799−

800−Use when encountering TypeScript any types, type errors, or lax type checking - eliminates type holes and enforces strict type safety through proper interfaces, type guards, and module augmentation

801−

802−## Overview

803−

804−**Zero tolerance for `any` types.** Every `any` is a runtime bug waiting to happen.

805−

806−Replace `any` with proper types using interfaces, `unknown` with type guards, or generic constraints. Use `@ts-expect-error` with explanation only when absolutely necessary.

807−

808−## When to Use

809−

810−- Use when you see:

811−

812−- `: any` in function parameters or return types

813−

814−- `as any` type assertions

815−

816−- TypeScript errors you're tempted to ignore

817−

818−- External libraries without proper types

819−

820−- Catch blocks with implicit `any`

821−

822−- Don't use for:

823−

824−- Already properly typed code

825−

826−- Third-party `.d.ts` files (contribute upstream instead)

827−

828−## Type Safety Hierarchy

829−

830−**Prefer in this order:**

831−1. Explicit interface/type definition

832−2. Generic type parameters with constraints

833−3. Union types

834−4. `unknown` (with type guards)

835−5. `never` (for impossible states)

836−

837−**Never use:** `any`

838−

839−## Quick Reference

840−

841−| Pattern | Bad | Good |

842−|---------|-----|------|

843−| **Error handling** | `catch (error: any)` | `catch (error) { if (error instanceof Error) ... }` |

844−| **Unknown data** | `JSON.parse(str) as any` | `const data = JSON.parse(str); if (isValid(data)) ...` |

845−| **Type assertions** | `(request as any).user` | `(request as AuthRequest).user` |

846−| **Double casting** | `return data as unknown as Type` | Align interfaces instead: make types compatible |

847−| **External libs** | `const server = fastify() as any` | `declare module 'fastify' { ... }` |

848−| **Generics** | `function process(data: any)` | `function process<T extends Record<string, unknown>>(data: T)` |

849−

850−## Implementation

851−

852−### Error Handling

853−

854−```typescript

855−// ❌ BAD

856−try {

857− await operation();

858−} catch (error: any) {

859− console.error(error.message);

860−}

861−

862−// ✅ GOOD - Use unknown and type guard

863−try {

864− await operation();

865−} catch (error) {

866− if (error instanceof Error) {

867− console.error(error.message);

868− } else {

869− console.error('Unknown error:', String(error));

870− }

871−}

872−

873−// ✅ BETTER - Helper function

874−function toError(error: unknown): Error {

875− if (error instanceof Error) return error;

876− return new Error(String(error));

877−}

878−

879−try {

880− await operation();

881−} catch (error) {

882− const err = toError(error);

883− console.error(err.message);

884−}

885−```

886−

887−### Unknown Data Validation

888−

889−```typescript

890−// ❌ BAD

891−const data = await response.json() as any;

892−console.log(data.user.name);

893−

894−// ✅ GOOD - Type guard

895−interface UserResponse {

896− user: {

897− name: string;

898− email: string;

899− };

900−}

901−

902−function isUserResponse(data: unknown): data is UserResponse {

903− return (

904− typeof data === 'object' &&

905− data !== null &&

906− 'user' in data &&

907− typeof data.user === 'object' &&

908− data.user !== null &&

909− 'name' in data.user &&

910− typeof data.user.name === 'string'

911− );

912−}

913−

914−const data = await response.json();

915−if (isUserResponse(data)) {

916− console.log(data.user.name); // Type-safe

917−}

918−```

919−

920−### Module Augmentation

921−

922−```typescript

923−// ❌ BAD

924−const user = (request as any).user;

925−const db = (server as any).pg;

926−

927−// ✅ GOOD - Augment third-party types

928−import { FastifyRequest, FastifyInstance } from 'fastify';

929−

930−interface AuthUser {

931− user_id: string;

932− username: string;

933− email: string;

934−}

935−

936−declare module 'fastify' {

937− interface FastifyRequest {

938− user?: AuthUser;

939− }

940−

941− interface FastifyInstance {

942− pg: PostgresPlugin;

943− }

944−}

945−

946−// Now type-safe everywhere

947−const user = request.user; // AuthUser | undefined

948−const db = server.pg; // PostgresPlugin

949−```

950−

951−### Generic Constraints

952−

953−```typescript

954−// ❌ BAD

955−function merge(a: any, b: any): any {

956− return { ...a, ...b };

957−}

958−

959−// ✅ GOOD - Constrained generic

960−function merge<

961− T extends Record<string, unknown>,

962− U extends Record<string, unknown>

963−>(a: T, b: U): T & U {

964− return { ...a, ...b };

965−}

966−```

967−

968−### Type Alignment (Avoid Double Casts)

969−

970−```typescript

971−// ❌ BAD - Double cast indicates misaligned types

972−interface SearchPackage {

973− id: string;

974− type: string; // Too loose

975−}

976−

977−interface RegistryPackage {

978− id: string;

979− type: PackageType; // Specific enum

980−}

981−

982−return data.packages as unknown as RegistryPackage[]; // Hiding incompatibility

983−

984−// ✅ GOOD - Align types from the source

985−interface SearchPackage {

986− id: string;

987− type: PackageType; // Use same specific type

988−}

989−

990−interface RegistryPackage {

991− id: string;

992− type: PackageType; // Now compatible

993−}

994−

995−return data.packages; // No cast needed - types match

996−```

997−

998−## Common Mistakes

999−

1000−| Mistake | Why It Fails | Fix |

1001−|---------|--------------|-----|

1002−| Using `any` for third-party libs | Loses all type safety | Use module augmentation or `@types/*` package |

1003−| `as any` for complex types | Hides real type errors | Create proper interface or use `unknown` |

1004−| `as unknown as Type` double casts | Misaligned interfaces | Align types at source - same enums/unions |

1005−| Skipping catch block types | Unsafe error access | Use `unknown` with type guards or toError helper |

1006−| Generic functions without constraints | Allows invalid operations | Add `extends` constraint |

1007−| Ignoring `ts-ignore` accumulation | Tech debt compounds | Fix root cause, use `@ts-expect-error` with comment |

1008−

1009−## TSConfig Strict Settings

1010−

1011−### Enable all strict options for maximum type safety:

1012−

1013−```json

1014−{

1015− "compilerOptions": {

1016− "strict": true,

1017− "noImplicitAny": true,

1018− "strictNullChecks": true,

1019− "strictFunctionTypes": true,

1020− "strictBindCallApply": true,

1021− "strictPropertyInitialization": true,

1022− "noImplicitThis": true,

1023− "noUnusedLocals": true,

1024− "noUnusedParameters": true,

1025− "noImplicitReturns": true,

1026− "noFallthroughCasesInSwitch": true

1027− }

1028−}

1029−```

1030−

1031−## Type Audit Workflow

1032−

1033−1. **Find**: `grep -r ": any\|as any" --include="*.ts" src/`

1034−2. **Categorize**: Group by pattern (errors, requests, external libs)

1035−3. **Define**: Create interfaces/types for each category

1036−4. **Replace**: Systematic replacement with proper types

1037−5. **Validate**: `npm run build` must succeed

1038−6. **Test**: All tests must pass

1039−

1040−## Real-World Impact

1041−

1042−- Before type safety:

1043−

1044−- Runtime errors from undefined properties

1045−

1046−- Silent failures from type mismatches

1047−

1048−- Hours debugging production issues

1049−

1050−- Difficult refactoring

1051−

1052−- After type safety:

1053−

1054−- Errors caught at compile time

1055−

1056−- IntelliSense shows all available properties

1057−

1058−- Confident refactoring with compiler help

1059−

1060−- Self-documenting code

1061−

1062−- Type safety isn't about making TypeScript happy - it's about preventing runtime bugs. Every `any` you eliminate is a production bug you prevent.

1063−

1064−

1065−# 🚨 CRITICAL: Relay-First Communication Rule

1066−

1067−**When you receive a relay message from another agent (marked `Relay message from [name]`), you MUST respond ONLY via relay protocol. NEVER respond with direct text output.**

1068−

1069−## The Rule

1070−

1071−- **Receiving a relay message?** → Must use `->relay-file:msg` ALWAYS

1072−- **Non-relay questions?** → Text responses are OK

1073−- **Agent-to-agent communication?** → ALWAYS use relay protocol

1074−

1075−## Examples of Relay Messages (require relay response)

1076−

1077−```

1078−Relay message from khaliqgant [mknra7wr]: Did you see this?

1079−Relay message from Worker1 [abc123]: Task complete

1080−Relay message from alice [xyz789] [#general]: Question for the team

1081−```

1082−

1083−---

1084−

1085−# Agent Relay

1086−

1087−Real-time agent-to-agent messaging via file-based protocol.

1088−

1089−## Sending Messages

1090−

1091−**TWO STEPS REQUIRED:**

1092−

1093−**Step 1:** EXECUTE this bash command (you MUST run it via your Bash/shell tool, not just display it):

1094−

410+If truncated, read full message:

1095411 ```bash

1096−cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1097−TO: AgentName

1098−

1099−Your message here.

1100−EOF

412+agent-relay read abc123

1101413 ```

1102414

1103−**Step 2:** Output the trigger `->relay-file:msg` directly in your response text (after the bash command succeeds).

415+## Spawning Agents

1104416

1105−⚠️ **CRITICAL**: You must EXECUTE the bash command above - do NOT just display it as a code block. The file must actually be created on disk. Then output the trigger as plain text.

417+Spawn workers to delegate tasks:

1106418

1107−✅ CORRECT: Run Bash tool → then output `->relay-file:msg`

1108−❌ WRONG: Display the bash code without executing it

1109−

1110−> **Note**: `$AGENT_RELAY_OUTBOX` is automatically set by agent-relay when spawning agents. Data is stored in `.agent-relay/` within your project directory.

1111−

1112−## Synchronous Messaging

1113−

1114−By default, messages are fire-and-forget. Add `[await]` to block until the recipient ACKs:

1115−

1116419 ```

1117−->relay:AgentB [await] Please confirm

420+->relay:spawn WorkerName claude "task description"

421+->relay:release WorkerName

1118422 ```

1119423

1120−Custom timeout (seconds or minutes):

424+## Threads

1121425

1122−```

1123−->relay:AgentB [await:30s] Please confirm

1124−->relay:AgentB [await:5m] Please confirm

1125−```

426+Use threads to group related messages together. Thread syntax:

1126427

1127−Recipients auto-ACK after processing when a correlation ID is present.

1128−

1129−## Message Format

1130−

1131428 ```

1132−TO: Target

1133−THREAD: optional-thread

1134−

1135−Message body (everything after blank line)

429+->relay:AgentName [thread:topic-name] <<<

430+Your message here.>>>

1136431 ```

1137432

1138−| TO Value | Behavior |

1139−|----------|----------|

1140−| `AgentName` | Direct message |

1141−| `*` | Broadcast to all |

1142−| `#channel` | Channel message |

433+**When to use threads:**

434+- Working on a specific issue (e.g., `[thread:agent-relay-299]`)

435+- Back-and-forth discussions with another agent

436+- Code review conversations

437+- Any multi-message topic you want grouped

1143438

1144−## Agent Naming (Local vs Bridge)

439+**Examples:**

1145440

1146−**Local communication** uses plain agent names. The `project:` prefix is **ONLY** for cross-project bridge mode.

1147−

1148−| Context | Correct | Incorrect |

1149−|---------|---------|-----------|

1150−| Local (same project) | `TO: Lead` | `TO: project:lead` |

1151−| Local (same project) | `TO: Worker1` | `TO: myproject:Worker1` |

1152−| Bridge (cross-project) | `TO: frontend:Designer` | N/A |

1153−| Bridge (to another lead) | `TO: otherproject:lead` | N/A |

1154−

1155−**Common mistake**: Using `project:lead` when communicating locally. This will fail because the relay looks for an agent literally named "project:lead".

1156−

1157−```bash

1158−# CORRECT - local communication to Lead agent

1159−cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1160−TO: Lead

1161−

1162−Status update here.

1163−EOF

1164441 ```

442+->relay:Protocol [thread:auth-feature] <<<

443+How should we handle token refresh?>>>

1165444

1166−```bash

1167−# WRONG - project: prefix is only for bridge mode

1168−cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1169−TO: project:lead

445+->relay:Frontend [thread:auth-feature] <<<

446+Use a 401 interceptor that auto-refreshes.>>>

1170447

1171−This will fail locally!

1172−EOF

1173−```

448+->relay:Reviewer [thread:pr-123] <<<

449+Please review src/auth/*.ts>>>

1174450

1175−## Spawning & Releasing

1176−

1177−**IMPORTANT**: The filename is always `spawn` (not `spawn-agentname`) and the trigger is always `->relay-file:spawn`. Spawn agents one at a time sequentially.

1178−

1179−### CLI Options

1180−

1181−The `CLI` header specifies which AI CLI to use. Valid values:

1182−

1183−| CLI Value | Description |

1184−|-----------|-------------|

1185−| `claude` | Claude Code (Anthropic) |

1186−| `codex` | Codex CLI (OpenAI) |

1187−| `gemini` | Gemini CLI (Google) |

1188−| `aider` | Aider coding assistant |

1189−| `goose` | Goose AI assistant |

1190−

1191−**Step 1:** EXECUTE this bash command (run it, don't just display it):

1192−```bash

1193−# Spawn a Claude agent

1194−cat > $AGENT_RELAY_OUTBOX/spawn << 'EOF'

1195−KIND: spawn

1196−NAME: WorkerName

1197−CLI: claude

1198−

1199−Task description here.

1200−EOF

451+->relay:Developer [thread:pr-123] <<<

452+LGTM, approved!>>>

1201453 ```

1202−**Step 2:** Output: `->relay-file:spawn`

1203454

1204−```bash

1205−# Spawn a Codex agent

1206−cat > $AGENT_RELAY_OUTBOX/spawn << 'EOF'

1207−KIND: spawn

1208−NAME: CodexWorker

1209−CLI: codex

455+Thread messages appear grouped in the dashboard with reply counts.

1210456

1211−Task description here.

1212−EOF

1213−```

457+## Common Patterns

1214458

1215−**Step 1:** EXECUTE this bash command (run it, don't just display it):

1216−```bash

1217−# Release

1218−cat > $AGENT_RELAY_OUTBOX/release << 'EOF'

1219−KIND: release

1220−NAME: WorkerName

1221−EOF

1222459 ```

1223−**Step 2:** Output: `->relay-file:release`

460+->relay:Lead <<<

461+ACK: Starting /api/register implementation>>>

1224462

1225−## When You Are Spawned

463+->relay:* <<<

464+STATUS: Working on auth module>>>

1226465

1227−If you were spawned by another agent:

466+->relay:Lead <<<

467+DONE: Auth module complete>>>

1228468

1229−1. **Check who spawned you**: `echo $AGENT_RELAY_SPAWNER`

1230−2. **Your first message** is your task from your spawner - reply to THEM, not "spawner"

1231−3. **Report status** to your spawner (your lead), not broadcast

469+->relay:Developer <<<

470+TASK: Implement /api/register>>>

1232471

1233−```bash

1234−# Check your spawner

1235−echo "I was spawned by: $AGENT_RELAY_SPAWNER"

1236−```

472+->relay:Reviewer [thread:code-review-auth] <<<

473+REVIEW: Please check src/auth/*.ts>>>

1237474

1238−**Step 1:** EXECUTE this bash command:

1239−```bash

1240−# Reply to your spawner

1241−cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'

1242−TO: $AGENT_RELAY_SPAWNER

1243−

1244−ACK: Starting on the task.

1245−EOF

475+->relay:Architect <<<

476+QUESTION: JWT or sessions?>>>

1246477 ```

1247−**Step 2:** Output: `->relay-file:msg`

1248478

1249−## Receiving Messages

479+## Rules

1250480

1251−Messages appear as:

1252−```

1253−Relay message from Alice [abc123]: Content here

1254−```

1255−

1256−Channel messages include `[#channel]`:

1257−```

1258−Relay message from Alice [abc123] [#general]: Hello!

1259−```

1260−Reply to the channel shown, not the sender.

1261−

1262−## Protocol

1263−

1264−- **ACK** when you receive a task: `ACK: Brief description`

1265−- **DONE** when complete: `DONE: What was accomplished`

1266−- Send status to your **lead** (the agent in `$AGENT_RELAY_SPAWNER`), not broadcast

1267−

1268−## Headers Reference

1269−

1270−| Header | Required | Description |

1271−|--------|----------|-------------|

1272−| TO | Yes (messages) | Target agent/channel |

1273−| KIND | No | `message` (default), `spawn`, `release` |

1274−| NAME | Yes (spawn/release) | Agent name |

1275−| CLI | Yes (spawn) | CLI to use: `claude`, `codex`, `gemini`, `aider`, `goose` |

1276−| THREAD | No | Thread identifier |

1277−

481+- Pattern must be at line start (whitespace OK)

482+- Escape with `\->relay:` to output literally

483+- Check daemon status: `agent-relay status`

484+

1278485