egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement new claude skills and workflow
All checks were successful
Deploy to Staging / Build Images (push) Successful in 23s
Details
Deploy to Staging / Deploy to Staging (push) Successful in 36s
Details
Deploy to Staging / Verify Staging (push) Successful in 6s
Details
Deploy to Staging / Notify Staging Ready (push) Successful in 6s
Details
Deploy to Staging / Notify Staging Failure (push) Has been skipped
Details

Browse Source
This commit is contained in:
Eric Gullickson
2026-01-03 11:02:30 -06:00
parent c443305007
commit 9f00797925
45 changed files with 10132 additions and 2174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
.claude/skills/doc-sync/README.md Normal file
View File

@@ -0,0 +1,46 @@
# Doc Sync
The CLAUDE.md/README.md hierarchy is central to context hygiene. CLAUDE.md files
are pure indexes -- tabular navigation with "What" and "When to read" columns
that help LLMs (and humans) find relevant files without loading everything.
README.md files capture invisible knowledge: architecture decisions, design
tradeoffs, and invariants that are not apparent from reading code.
The doc-sync skill audits and synchronizes this hierarchy across a repository.
## How It Works
The skill operates in five phases:
1. **Discovery** -- Maps all directories, identifies missing or outdated
CLAUDE.md files
2. **Audit** -- Checks for drift (files added/removed but not indexed),
misplaced content (architecture docs in CLAUDE.md instead of README.md)
3. **Migration** -- Moves architectural content from CLAUDE.md to README.md
4. **Update** -- Creates/updates indexes with proper tabular format
5. **Verification** -- Confirms complete coverage and correct structure
## When to Use
Use this skill for:
- **Bootstrapping** -- Adopting this workflow on an existing repository
- **After bulk changes** -- Major refactors, directory restructuring
- **Periodic audits** -- Checking for documentation drift
- **Onboarding** -- Before starting work on an unfamiliar codebase
If you use the planning workflow consistently, the technical writer agent
maintains documentation as part of execution. As such, doc-sync is primarily for
bootstrapping or recovery -- not routine use.
## Example Usage
```
Use your doc-sync skill to synchronize documentation across this repository
```
For targeted updates:
```
Use your doc-sync skill to update documentation in src/validators/
```

315
.claude/skills/doc-sync/SKILL.md Normal file
View File

@@ -0,0 +1,315 @@
---
name: doc-sync
description: Synchronizes CLAUDE.md navigation indexes and README.md architecture docs across a repository. Use when asked to "sync docs", "update CLAUDE.md files", "ensure documentation is in sync", "audit documentation", or when documentation maintenance is needed after code changes.
---
# Doc Sync
Maintains the CLAUDE.md navigation hierarchy and optional README.md architecture docs across a repository. This skill is self-contained and performs all documentation work directly.
## Scope Resolution
Determine scope FIRST:
| User Request | Scope |
| ------------------------------------------------------- | ----------------------------------------- |
| "sync docs" / "update documentation" / no specific path | REPOSITORY-WIDE |
| "sync docs in src/validator/" | DIRECTORY: src/validator/ and descendants |
| "update CLAUDE.md for parser.py" | FILE: single file's parent directory |
For REPOSITORY-WIDE scope, perform a full audit. For narrower scopes, operate only within the specified boundary.
## CLAUDE.md Format Specification
### Index Format
Use tabular format with What and When columns:
```markdown
## Files
| File | What | When to read |
| ----------- | ------------------------------ | ----------------------------------------- |
| `cache.rs` | LRU cache with O(1) operations | Implementing caching, debugging evictions |
| `errors.rs` | Error types and Result aliases | Adding error variants, handling failures |
## Subdirectories
| Directory | What | When to read |
| ----------- | ----------------------------- | ----------------------------------------- |
| `config/` | Runtime configuration loading | Adding config options, modifying defaults |
| `handlers/` | HTTP request handlers | Adding endpoints, modifying request flow |
```
### Column Guidelines
- **File/Directory**: Use backticks around names: `cache.rs`, `config/`
- **What**: Factual description of contents (nouns, not actions)
- **When to read**: Task-oriented triggers using action verbs (implementing, debugging, modifying, adding, understanding)
- At least one column must have content; empty cells use `-`
### Trigger Quality Test
Given task "add a new validation rule", can an LLM scan the "When to read" column and identify the right file?
### ROOT vs SUBDIRECTORY CLAUDE.md
**ROOT CLAUDE.md:**
```markdown
# [Project Name]
[One sentence: what this is]
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
## Build
[Copy-pasteable command]
## Test
[Copy-pasteable command]
## Development
[Setup instructions, environment requirements, workflow notes]
```
**SUBDIRECTORY CLAUDE.md:**
```markdown
# [directory-name]/
## Files
| File | What | When to read |
| ---- | ---- | ------------ |
## Subdirectories
| Directory | What | When to read |
| --------- | ---- | ------------ |
```
**Critical constraint:** Subdirectory CLAUDE.md files are PURE INDEX. No prose, no overview sections, no architectural explanations. Those belong in README.md.
## README.md Specification
### Creation Criteria (Invisible Knowledge Test)
Create README.md ONLY when the directory contains knowledge NOT visible from reading the code:
- Multiple components interact through non-obvious contracts or protocols
- Design tradeoffs were made that affect how code should be modified
- The directory's structure encodes domain knowledge (e.g., processing order matters)
- Failure modes or edge cases aren't apparent from reading individual files
- There are "rules" developers must follow that aren't enforced by the compiler/linter
**DO NOT create README.md when:**
- The directory is purely organizational (just groups related files)
- Code is self-explanatory with good function/module docs
- You'd be restating what CLAUDE.md index entries already convey
### Content Test
For each sentence in README.md, ask: "Could a developer learn this by reading the source files?"
- If YES: delete the sentence
- If NO: keep it
README.md earns its tokens by providing INVISIBLE knowledge: the reasoning behind the code, not descriptions of the code.
### README.md Structure
```markdown
# [Component Name]
## Overview
[One paragraph: what problem this solves, high-level approach]
## Architecture
[How sub-components interact; data flow; key abstractions]
## Design Decisions
[Tradeoffs made and why; alternatives considered]
## Invariants
[Rules that must be maintained; constraints not enforced by code]
```
## Workflow
### Phase 1: Discovery
Map directories requiring CLAUDE.md verification:
```bash
# Find all directories (excluding .git, node_modules, __pycache__, etc.)
find . -type d \( -name .git -o -name node_modules -o -name __pycache__ -o -name .venv -o -name target -o -name dist -o -name build \) -prune -o -type d -print
```
For each directory in scope, record:
1. Does CLAUDE.md exist?
2. If yes, does it have the required table-based index structure?
3. What files/subdirectories exist that need indexing?
### Phase 2: Audit
For each directory, check for drift and misplaced content:
```
<audit_check dir="[path]">
CLAUDE.md exists: [YES/NO]
Has table-based index: [YES/NO]
Files in directory: [list]
Files in index: [list]
Missing from index: [list]
Stale in index (file deleted): [list]
Triggers are task-oriented: [YES/NO/PARTIAL]
Contains misplaced content: [YES/NO] (architecture/design docs that belong in README.md)
README.md exists: [YES/NO]
README.md warranted: [YES/NO] (invisible knowledge present?)
</audit_check>
```
### Phase 3: Content Migration
**Critical:** If CLAUDE.md contains content that does NOT belong there, migrate it:
Content that MUST be moved from CLAUDE.md to README.md:
- Architecture explanations or diagrams
- Design decision documentation
- Component interaction descriptions
- Overview sections with prose (in subdirectory CLAUDE.md files)
- Invariants or rules documentation
- Any "why" explanations beyond simple triggers
Migration process:
1. Identify misplaced content in CLAUDE.md
2. Create or update README.md with the architectural content
3. Strip CLAUDE.md down to pure index format
4. Add README.md to the CLAUDE.md index table
### Phase 4: Index Updates
For each directory needing work:
**Creating/Updating CLAUDE.md:**
1. Use the appropriate template (ROOT or SUBDIRECTORY)
2. Populate tables with all files and subdirectories
3. Write "What" column: factual content description
4. Write "When to read" column: action-oriented triggers
5. If README.md exists, include it in the Files table
**Creating README.md (only when warranted):**
1. Verify invisible knowledge criteria are met
2. Document architecture, design decisions, invariants
3. Apply the content test: remove anything visible from code
4. Keep under ~500 tokens
### Phase 5: Verification
After all updates complete, verify:
1. Every directory in scope has CLAUDE.md
2. All CLAUDE.md files use table-based index format
3. No drift remains (files <-> index entries match)
4. No misplaced content in CLAUDE.md (architecture docs moved to README.md)
5. README.md files are indexed in their parent CLAUDE.md
6. Subdirectory CLAUDE.md files contain no prose/overview sections
## Output Format
```
## Doc Sync Report
### Scope: [REPOSITORY-WIDE | directory path]
### Changes Made
- CREATED: [list of new CLAUDE.md files]
- UPDATED: [list of modified CLAUDE.md files]
- MIGRATED: [list of content moved from CLAUDE.md to README.md]
- CREATED: [list of new README.md files]
- FLAGGED: [any issues requiring human decision]
### Verification
- Directories audited: [count]
- CLAUDE.md coverage: [count]/[total] (100%)
- Drift detected: [count] entries fixed
- Content migrations: [count] (architecture docs moved to README.md)
- README.md files: [count] (only where warranted)
```
## Exclusions
DO NOT index:
- Generated files (dist/, build/, _.generated._, compiled outputs)
- Vendored dependencies (node_modules/, vendor/, third_party/)
- Git internals (.git/)
- IDE/editor configs (.idea/, .vscode/ unless project-specific settings)
DO index:
- Hidden config files that affect development (.eslintrc, .env.example, .gitignore)
- Test files and test directories
- Documentation files (including README.md)
## Anti-Patterns
### Index Anti-Patterns
**Too vague (matches everything):**
```markdown
| `config/` | Configuration | Working with configuration |
```
**Content description instead of trigger:**
```markdown
| `cache.rs` | Contains the LRU cache implementation | - |
```
**Missing action verb:**
```markdown
| `parser.py` | Input parsing | Input parsing and format handling |
```
### Correct Examples
```markdown
| `cache.rs` | LRU cache with O(1) get/set | Implementing caching, debugging misses, tuning eviction |
| `config/` | YAML config parsing, env overrides | Adding config options, changing defaults, debugging config loading |
```
## When NOT to Use This Skill
- Single file documentation (inline comments, docstrings) - handle directly
- Code comments - handle directly
- Function/module docstrings - handle directly
- This skill is for CLAUDE.md/README.md synchronization specifically
## Reference
For additional trigger pattern examples, see `references/trigger-patterns.md`.

125
.claude/skills/doc-sync/references/trigger-patterns.md Normal file
View File

@@ -0,0 +1,125 @@
# Trigger Patterns Reference
Examples of well-formed triggers for CLAUDE.md index table entries.
## Column Formula
| File | What | When to read |
| ------------ | -------------------------------- | ------------------------------------- |
| `[filename]` | [noun-based content description] | [action verb] [specific context/task] |
## Action Verbs by Category
### Implementation Tasks
implementing, adding, creating, building, writing, extending
### Modification Tasks
modifying, updating, changing, refactoring, migrating
### Debugging Tasks
debugging, troubleshooting, investigating, diagnosing, fixing
### Understanding Tasks
understanding, learning, reviewing, analyzing, exploring
## Examples by File Type
### Source Code Files
| File | What | When to read |
| -------------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
| `cache.rs` | LRU cache with O(1) operations | Implementing caching, debugging cache misses, modifying eviction policy |
| `auth.rs` | JWT validation, session management | Implementing login/logout, modifying token validation, debugging auth failures |
| `parser.py` | Input parsing, format detection | Modifying input parsing, adding new input formats, debugging parse errors |
| `validator.py` | Validation rules, constraint checks | Adding validation rules, modifying validation logic, understanding validation flow |
### Configuration Files
| File | What | When to read |
| -------------- | -------------------------------- | ----------------------------------------------------------------------------- |
| `config.toml` | Runtime config options, defaults | Adding new config options, modifying defaults, debugging configuration issues |
| `.env.example` | Environment variable template | Setting up development environment, adding new environment variables |
| `Cargo.toml` | Rust dependencies, build config | Adding dependencies, modifying build configuration, debugging build issues |
### Test Files
| File | What | When to read |
| -------------------- | --------------------------- | -------------------------------------------------------------------------------- |
| `test_cache.py` | Cache unit tests | Adding cache tests, debugging test failures, understanding cache behavior |
| `integration_tests/` | Cross-component test suites | Adding integration tests, debugging cross-component issues, validating workflows |
### Documentation Files
| File | What | When to read |
| ----------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| `README.md` | Architecture, design decisions | Understanding architecture, design decisions, component relationships |
| `ARCHITECTURE.md` | System design, component boundaries | Understanding system design, component boundaries, data flow |
| `API.md` | Endpoint specs, request/response formats | Implementing API endpoints, understanding request/response formats, debugging API issues |
### Index Files (cross-cutting concerns)
| File | What | When to read |
| ------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- |
| `error-handling-index.md` | Error handling patterns reference | Understanding error handling patterns, failure modes, error recovery strategies |
| `performance-index.md` | Performance optimization reference | Optimizing latency, throughput, resource usage, understanding cost models |
| `security-index.md` | Security patterns reference | Implementing authentication, encryption, threat mitigation, compliance features |
## Examples by Directory Type
### Feature Directories
| Directory | What | When to read |
| ---------- | --------------------------------------- | ------------------------------------------------------------------------------------- |
| `auth/` | Authentication, authorization, sessions | Implementing authentication, authorization, session management, debugging auth issues |
| `api/` | HTTP endpoints, request handling | Implementing endpoints, modifying request handling, debugging API responses |
| `storage/` | Persistence, data access layer | Implementing persistence, modifying data access, debugging storage issues |
### Layer Directories
| Directory | What | When to read |
| ----------- | ----------------------------- | -------------------------------------------------------------------------------- |
| `handlers/` | Request handlers, routing | Implementing request handlers, modifying routing, debugging request processing |
| `models/` | Data models, schemas | Adding data models, modifying schemas, understanding data structures |
| `services/` | Business logic, service layer | Implementing business logic, modifying service interactions, debugging workflows |
### Utility Directories
| Directory | What | When to read |
| ---------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| `utils/` | Helper functions, common patterns | Needing helper functions, implementing common patterns, debugging utility behavior |
| `scripts/` | Maintenance tasks, automation | Running maintenance tasks, automating workflows, debugging script execution |
| `tools/` | Development tools, CLI utilities | Using development tools, implementing tooling, debugging tool behavior |
## Anti-Patterns
### Too Vague (matches everything)
| File | What | When to read |
| ---------- | ------------- | -------------------------- |
| `config/` | Configuration | Working with configuration |
| `utils.py` | Utilities | When you need utilities |
### Content Description Only (no trigger)
| File | What | When to read |
| ---------- | --------------------------------------------- | ------------ |
| `cache.rs` | Contains the LRU cache implementation | - |
| `auth.rs` | Authentication logic including JWT validation | - |
### Missing Action Verb
| File | What | When to read |
| -------------- | ---------------- | --------------------------------- |
| `parser.py` | Input parsing | Input parsing and format handling |
| `validator.py` | Validation rules | Validation rules and constraints |
## Trigger Guidelines
- Combine 2-4 triggers per entry using commas or "or"
- Use action verbs: implementing, debugging, modifying, adding, understanding
- Be specific: "debugging cache misses" not "debugging"
- If more than 4 triggers needed, the file may be doing too much