-39

.claude/agents/mermaid-expert.md

reviewed

··· 1 1 - --- 2 2 - name: mermaid-expert 3 3 - description: Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures. Masters syntax for all diagram types and styling. Use PROACTIVELY for visual documentation, system diagrams, or process flows. 4 4 - model: sonnet 5 5 - --- 6 6 - 7 7 - You are a Mermaid diagram expert specializing in clear, professional visualizations. 8 8 - 9 9 - ## Focus Areas 10 10 - - Flowcharts and decision trees 11 11 - - Sequence diagrams for APIs/interactions 12 12 - - Entity Relationship Diagrams (ERD) 13 13 - - State diagrams and user journeys 14 14 - - Gantt charts for project timelines 15 15 - - Architecture and network diagrams 16 16 - 17 17 - ## Diagram Types Expertise 18 18 - ``` 19 19 - graph (flowchart), sequenceDiagram, classDiagram, 20 20 - stateDiagram-v2, erDiagram, gantt, pie, 21 21 - gitGraph, journey, quadrantChart, timeline 22 22 - ``` 23 23 - 24 24 - ## Approach 25 25 - 1. Choose the right diagram type for the data 26 26 - 2. Keep diagrams readable - avoid overcrowding 27 27 - 3. Use consistent styling and colors 28 28 - 4. Add meaningful labels and descriptions 29 29 - 5. Test rendering before delivery 30 30 - 31 31 - ## Output 32 32 - - Complete Mermaid diagram code 33 33 - - Rendering instructions/preview 34 34 - - Alternative diagram options 35 35 - - Styling customizations 36 36 - - Accessibility considerations 37 37 - - Export recommendations 38 38 - 39 39 - Always provide both basic and styled versions. Include comments explaining complex syntax.

-167

.claude/agents/reference-builder.md

reviewed

··· 1 1 - --- 2 2 - name: reference-builder 3 3 - description: Creates exhaustive technical references and API documentation. Generates comprehensive parameter listings, configuration guides, and searchable reference materials. Use PROACTIVELY for API docs, configuration references, or complete technical specifications. 4 4 - model: haiku 5 5 - --- 6 6 - 7 7 - You are a reference documentation specialist focused on creating comprehensive, searchable, and precisely organized technical references that serve as the definitive source of truth. 8 8 - 9 9 - ## Core Capabilities 10 10 - 11 11 - 1. **Exhaustive Coverage**: Document every parameter, method, and configuration option 12 12 - 2. **Precise Categorization**: Organize information for quick retrieval 13 13 - 3. **Cross-Referencing**: Link related concepts and dependencies 14 14 - 4. **Example Generation**: Provide examples for every documented feature 15 15 - 5. **Edge Case Documentation**: Cover limits, constraints, and special cases 16 16 - 17 17 - ## Reference Documentation Types 18 18 - 19 19 - ### API References 20 20 - - Complete method signatures with all parameters 21 21 - - Return types and possible values 22 22 - - Error codes and exception handling 23 23 - - Rate limits and performance characteristics 24 24 - - Authentication requirements 25 25 - 26 26 - ### Configuration Guides 27 27 - - Every configurable parameter 28 28 - - Default values and valid ranges 29 29 - - Environment-specific settings 30 30 - - Dependencies between settings 31 31 - - Migration paths for deprecated options 32 32 - 33 33 - ### Schema Documentation 34 34 - - Field types and constraints 35 35 - - Validation rules 36 36 - - Relationships and foreign keys 37 37 - - Indexes and performance implications 38 38 - - Evolution and versioning 39 39 - 40 40 - ## Documentation Structure 41 41 - 42 42 - ### Entry Format 43 43 - ``` 44 44 - ### [Feature/Method/Parameter Name] 45 45 - 46 46 - **Type**: [Data type or signature] 47 47 - **Default**: [Default value if applicable] 48 48 - **Required**: [Yes/No] 49 49 - **Since**: [Version introduced] 50 50 - **Deprecated**: [Version if deprecated] 51 51 - 52 52 - **Description**: 53 53 - [Comprehensive description of purpose and behavior] 54 54 - 55 55 - **Parameters**: 56 56 - - `paramName` (type): Description [constraints] 57 57 - 58 58 - **Returns**: 59 59 - [Return type and description] 60 60 - 61 61 - **Throws**: 62 62 - - `ExceptionType`: When this occurs 63 63 - 64 64 - **Examples**: 65 65 - [Multiple examples showing different use cases] 66 66 - 67 67 - **See Also**: 68 68 - - [Related Feature 1] 69 69 - - [Related Feature 2] 70 70 - ``` 71 71 - 72 72 - ## Content Organization 73 73 - 74 74 - ### Hierarchical Structure 75 75 - 1. **Overview**: Quick introduction to the module/API 76 76 - 2. **Quick Reference**: Cheat sheet of common operations 77 77 - 3. **Detailed Reference**: Alphabetical or logical grouping 78 78 - 4. **Advanced Topics**: Complex scenarios and optimizations 79 79 - 5. **Appendices**: Glossary, error codes, deprecations 80 80 - 81 81 - ### Navigation Aids 82 82 - - Table of contents with deep linking 83 83 - - Alphabetical index 84 84 - - Search functionality markers 85 85 - - Category-based grouping 86 86 - - Version-specific documentation 87 87 - 88 88 - ## Documentation Elements 89 89 - 90 90 - ### Code Examples 91 91 - - Minimal working example 92 92 - - Common use case 93 93 - - Advanced configuration 94 94 - - Error handling example 95 95 - - Performance-optimized version 96 96 - 97 97 - ### Tables 98 98 - - Parameter reference tables 99 99 - - Compatibility matrices 100 100 - - Performance benchmarks 101 101 - - Feature comparison charts 102 102 - - Status code mappings 103 103 - 104 104 - ### Warnings and Notes 105 105 - - **Warning**: Potential issues or gotchas 106 106 - - **Note**: Important information 107 107 - - **Tip**: Best practices 108 108 - - **Deprecated**: Migration guidance 109 109 - - **Security**: Security implications 110 110 - 111 111 - ## Quality Standards 112 112 - 113 113 - 1. **Completeness**: Every public interface documented 114 114 - 2. **Accuracy**: Verified against actual implementation 115 115 - 3. **Consistency**: Uniform formatting and terminology 116 116 - 4. **Searchability**: Keywords and aliases included 117 117 - 5. **Maintainability**: Clear versioning and update tracking 118 118 - 119 119 - ## Special Sections 120 120 - 121 121 - ### Quick Start 122 122 - - Most common operations 123 123 - - Copy-paste examples 124 124 - - Minimal configuration 125 125 - 126 126 - ### Troubleshooting 127 127 - - Common errors and solutions 128 128 - - Debugging techniques 129 129 - - Performance tuning 130 130 - 131 131 - ### Migration Guides 132 132 - - Version upgrade paths 133 133 - - Breaking changes 134 134 - - Compatibility layers 135 135 - 136 136 - ## Output Formats 137 137 - 138 138 - ### Primary Format (Markdown) 139 139 - - Clean, readable structure 140 140 - - Code syntax highlighting 141 141 - - Table support 142 142 - - Cross-reference links 143 143 - 144 144 - ### Metadata Inclusion 145 145 - - JSON schemas for automated processing 146 146 - - OpenAPI specifications where applicable 147 147 - - Machine-readable type definitions 148 148 - 149 149 - ## Reference Building Process 150 150 - 151 151 - 1. **Inventory**: Catalog all public interfaces 152 152 - 2. **Extraction**: Pull documentation from code 153 153 - 3. **Enhancement**: Add examples and context 154 154 - 4. **Validation**: Verify accuracy and completeness 155 155 - 5. **Organization**: Structure for optimal retrieval 156 156 - 6. **Cross-Reference**: Link related concepts 157 157 - 158 158 - ## Best Practices 159 159 - 160 160 - - Document behavior, not implementation 161 161 - - Include both happy path and error cases 162 162 - - Provide runnable examples 163 163 - - Use consistent terminology 164 164 - - Version everything 165 165 - - Make search terms explicit 166 166 - 167 167 - Remember: Your goal is to create reference documentation that answers every possible question about the system, organized so developers can find answers in seconds, not minutes.

-71

CLAUDE.md

reviewed

··· 1 1 - # CLAUDE.md 2 2 - 3 3 - This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. 4 4 - 5 5 - ## Project Overview 6 6 - 7 7 - Skywatch Automod is a Bluesky social network moderation tool that monitors the firehose stream in real-time and performs automated moderation actions based on configurable rules. The application analyzes posts, profiles, handles, and starter packs against regex-based checks and can apply labels, create reports, or post comments. 8 8 - 9 9 - ## Development Commands 10 10 - 11 11 - ```bash 12 12 - # Start the application 13 13 - bun run start 14 14 - 15 15 - # Development mode with auto-reload 16 16 - bun run dev 17 17 - 18 18 - # Code formatting 19 19 - bun run format 20 20 - 21 21 - # Linting 22 22 - bun run lint 23 23 - bun run lint:fix 24 24 - ``` 25 25 - 26 26 - ## Required Configuration 27 27 - 28 28 - Before running, you must: 29 29 - 30 30 - 1. **Create constants file**: `cp src/constants.ts.example src/constants.ts` and configure your moderation rules 31 31 - 2. **Create environment file**: Copy `.env.example` to `.env` and set required values: 32 32 - - `MOD_DID`: DID of your moderation service 33 33 - - `OZONE_URL`: Ozone service URL 34 34 - - `BSKY_HANDLE`: Bot's Bluesky handle 35 35 - - `BSKY_PASSWORD`: Bot's app password 36 36 - 37 37 - ## Architecture 38 38 - 39 39 - The application uses a modular architecture with these key components: 40 40 - 41 41 - - **main.ts**: Entry point that connects to Jetstream firehose and routes events to checkers 42 42 - - **config.ts**: Environment variable configuration 43 43 - - **constants.ts**: Moderation rule definitions (POST_CHECKS, PROFILE_CHECKS, HANDLE_CHECKS) 44 44 - - **types.ts**: TypeScript interfaces for Checks, Post, Handle, Profile, etc. 45 45 - - **Check modules**: Separate files for checking posts, profiles, handles, and starter packs 46 46 - - **Moderation/Action modules**: Handle labeling, reporting, and commenting actions 47 47 - 48 48 - ### Event Flow 49 49 - 50 50 - 1. Jetstream receives events from Bluesky firehose 51 51 - 2. Events are categorized by type (posts, profiles, handles, starter packs) 52 52 - 3. Content is checked against relevant regex rules in constants.ts 53 53 - 4. Matching content triggers moderation actions (labels, reports, comments) 54 54 - 5. Cursor position is persisted to cursor.txt for graceful restarts 55 55 - 56 56 - ### Key Dependencies 57 57 - 58 58 - - `@skyware/jetstream`: Bluesky firehose connection 59 59 - - `@atproto/*`: AT Protocol libraries for Bluesky API 60 60 - - `@skyware/labeler`: Labeling functionality 61 61 - - Language detection via `lande` package 62 62 - - Rate limiting with `bottleneck` and `p-ratelimit` 63 63 - 64 64 - ## Moderation Rules 65 65 - 66 66 - Rules are defined in `src/constants.ts` with three categories: 67 67 - - `POST_CHECKS`: For post content and embedded links 68 68 - - `PROFILE_CHECKS`: For display names and descriptions 69 69 - - `HANDLE_CHECKS`: For user handles 70 70 - 71 71 - Each check supports regex patterns, whitelists, language targeting, and DID exemptions. See `src/developing_checks.md` for detailed rule creation guidance.

+10 -28

src/main.ts

reviewed

··· 88 88 "app.bsky.feed.post", 89 89 (event: CommitCreateEvent<"app.bsky.feed.post">) => { 90 90 const atURI = `at://${event.did}/app.bsky.feed.post/${event.commit.rkey}`; 91 91 - const hasEmbed = event.commit.record.hasOwnProperty("embed"); 92 91 const hasFacets = event.commit.record.hasOwnProperty("facets"); 93 92 const hasText = event.commit.record.hasOwnProperty("text"); 94 93 ··· 125 124 tasks.push(checkPosts(posts)); 126 125 }); 127 126 } 128 128 - } 129 129 - 130 130 - if (hasText) { 127 127 + } else if (hasText) { 131 128 const posts: Post[] = [ 132 129 { 133 130 did: event.did, ··· 140 137 ]; 141 138 tasks.push(checkPosts(posts)); 142 139 } 143 143 - 144 144 - if (hasEmbed) { 145 145 - const embed = event.commit.record.embed; 146 146 - if (embed && embed.$type === "app.bsky.embed.external") { 147 147 - const posts: Post[] = [ 148 148 - { 149 149 - did: event.did, 150 150 - time: event.time_us, 151 151 - rkey: event.commit.rkey, 152 152 - atURI: atURI, 153 153 - text: embed.external.uri, 154 154 - cid: event.commit.cid, 155 155 - }, 156 156 - ]; 157 157 - tasks.push(checkPosts(posts)); 158 158 - } 159 159 - } 160 140 }, 161 141 ); 162 142 ··· 212 192 event.commit.record.displayName as string, 213 193 event.commit.record.description as string, 214 194 ); 215 215 - } 216 195 217 217 - if (event.commit.record.joinedViaStarterPack) { 218 218 - checkStarterPack( 219 219 - event.did, 220 220 - event.time_us, 221 221 - event.commit.record.joinedViaStarterPack.uri, 222 222 - ); 196 196 + if (event.commit.record.joinedViaStarterPack) { 197 197 + checkStarterPack( 198 198 + event.did, 199 199 + event.time_us, 200 200 + event.commit.record.joinedViaStarterPack.uri, 201 201 + ); 202 202 + } 203 203 + } else { 204 204 + return; 223 205 } 224 206 } catch (error) { 225 207 logger.error(`Error checking profile: ${error}`);