lsh

Imported from gwicho38/lsh (AGENTS.md). Install upstream with npx skills add gwicho38/lsh. Copyright stays with the author.

Global Claude Code Instructions

These instructions apply to all projects and sessions.

CLAUDE.md Maintenance

Keeping Instructions in Sync

• When adding a new rule to ~/.claude/CLAUDE.md, propagate relevant project-specific rules to corresponding repo CLAUDE.md files in ~/repos/*/CLAUDE.md
• When adding a rule to a repo's CLAUDE.md, consider if it should be generalized and added to the global ~/.claude/CLAUDE.md
• Periodically consolidate and deduplicate rules across all CLAUDE.md files
• Remove obsolete or contradictory rules when discovered

Rule Hierarchy

1. Global rules (~/.claude/CLAUDE.md) - Apply to all projects
2. Repo-specific rules (~/repos/*/CLAUDE.md) - Override or extend global rules for that project

When to Update

• After completing a significant feature or bug fix with new learnings
• When discovering a pattern that should apply across projects
• When a workflow or tool preference changes
• When onboarding a new project to ~/repos/

Git & Versioning

Commit Rules

• Never add Claude, Claude Code, or any AI attribution to commits
• Never include Co-Authored-By: Claude or similar signatures
• Never include Generated with [Claude Code] in commit messages
• Use conventional commit format: feat:, fix:, docs:, test:, refactor:, perf:
• Tie commits to GitHub issues for traceability when working on issue-based tasks

Versioning

• Follow semantic versioning: M.m.s (Major.minor.patch)
• Tag releases appropriately using git tag vM.m.s
• Create release notes at docs/releases/M.m.s.md with diff of changes
• Always increment iOS/TestFlight build versions to avoid conflicts

Git Workflow

• Create GitHub issues for any pending actions or todos in GitHub-based projects
• Verify issues aren't already resolved before working on them
• Push upstream changes only after CI passes

Testing

Test Requirements

• Always create unit tests for any new functionality
• Always create test cases for bug fixes covering the root cause
• Run all existing tests before declaring a task complete
• Validate that both new and existing tests pass

Test Organization

• Place tests in the top-level test/ directory
• Categorize tests by type (unit, integration, e2e, etc.)
• For Flutter/Outlet: Use Patrol for UI/integration tests
• For Elixir/Conduit: Follow Phoenix test conventions

Test-Driven Development

• For non-syntax failures, write a test first to confirm the failure
• Develop the implementation via the test
• Only proceed to actual changes once the test exists

CI/CD Requirements

CRITICAL: CI Must Pass Before Work is Complete

NEVER declare work complete until CI passes on GitHub. This is a hard requirement.

CI/CD Workflow (Required for Every Task)

1. Before starting work: Run gh run list --limit 3 to check current CI status
2. After pushing changes: Run gh run watch or gh run list to monitor CI
3. If CI fails:
   • Investigate the failure with gh run view <run-id> --log-failed
   • Fix the issue immediately
   • Push the fix and wait for CI to pass
   • Repeat until CI is green
4. Only after CI passes: Declare the task complete

CI Commands Reference

gh run list --limit 5              # Check recent CI runs
gh run view <run-id> --log-failed  # View failure logs
gh run watch <run-id>              # Watch run in real-time
gh run rerun <run-id>              # Rerun a failed run

Pre-Completion Checks

• Ensure CI passes before declaring any task complete
• If pushes fail CI, address the issues immediately
• Validate builds work for all target platforms (iOS, Android, web as applicable)
• Always lint the repo prior to committing

Platform-Specific

• iOS: Don't build locally; increment TestFlight version before builds
• Android: Validate builds with flutter build apk or flutter build appbundle
• Elixir: Run mix test and mix format

Documentation

Organization

• Place all documentation under the repo's top-level docs/ directory
• Categorize docs by subject matter (setup, features, deployment, etc.)
• Create release notes at docs/releases/M.m.s.md for each version
• Include diff summaries of what changed between versions

Bug Learnings

• Create a learnings document for any bug fix
• Add it to project memory/docs for future reference

Project Structure

Code Organization

• Place scripts in appropriate top-level folders by file type
• Never hardcode strings, properties, or values in files
• Declare all constants in dedicated constants files
• Use centralized configuration for environment-specific values

File Management

• Prefer editing existing files over creating new ones
• Only create new files when absolutely necessary

Secrets & Workflow Management

Secrets (lsh-framework)

• Always use lsh-framework npm package for secrets management
• File feature/bug requests as GitHub issues at ~/repos/lsh
• Never commit secrets or .env files to repositories

Workflows (mcli-framework)

• Always use mcli-framework Python package for workflow automation
• Register shell scripts and workflows as mcli commands
• File feature/bug requests as GitHub issues at ~/repos/mcli
• Install and manage mcli as a UV tool

Script Management

• Use mcli as the script runner for all repos
• If mcli lacks a needed feature, file an issue with gwicho38/mcli
• Integrate debugging utilities into mcli workflows rather than ad-hoc scripts

Build & Deployment

Python Projects

• Always use UV to manage Python projects
• Follow pyproject.toml conventions

Flutter/Outlet

• Validate builds for both iOS and Android
• Push changes to fly.app server for production testing
• Wire up front-end and back-end functionality end-to-end

Elixir/Conduit

• Run migrations with mix ecto.migrate
• Deploy to Fly.io with fly deploy
• Monitor logs with flyctl logs

Debugging

Logging

• If asked about the same issue twice, add more logging on subsequent attempts
• Check adb logcat for Android debugging
• Check flyctl logs at ~/repos/conduit for backend debugging
• Review logs for the last +/- 5 minutes when debugging

Data Validation

• Check for coherence between production and dev data
• Identify and report data mismatches
• Run queries against production database for data debugging (not local)

Project-Specific Rules

Outlet & Conduit (EV Charging Platform)

• Check congruence between Outlet (Flutter) and Conduit (Elixir) implementations
• Switch Firebase references to Conduit backend references
• Test full integration: client action → API request → backend logic → response handling
• Create UI integration tests for all user-facing features
• Don't prioritize backward compatibility unless explicitly requested
• Use Stripe API extensively for payment features
• Use Patrol for declarative UI testing

myAi/myGenAi (AI Projects)

• Check if Python API has implemented a feature before adding it
• Search for c3.<Name> implementations in both repos
• Test all side effects of UI interactions (toggles, dropdowns, etc.)

Neverquest (Game Development)

• Overlap callbacks should only manage UI visibility
• Let each system manage its own player state flags
• Avoid frame-by-frame state changes
• Use event-driven architecture where possible

Politician Trading Tracker

• Use Supabase, not raw PostgreSQL

Permissions & Actions

Granted Permissions

• Permission granted for all actions required to complete tasks
• Do not prompt for permission during task execution
• If sudo is required, pause and request manual intervention

Task Completion

• Do not declare done until:
  • Tests are created and passing
  • Build validates successfully
  • CI passes
  • All functionality is wired up end-to-end

Tech Stack Quick Reference

Tool Preferences

• Python: UV for package management
• Secrets: lsh-framework (npm)
• Workflows: mcli-framework (pypi)
• iOS: Don't build locally
• Editor: neovim
• API Testing: Stripe API, fly.app endpoints
• If you use curl or some other shell command more than a few times, please just build that logic into an mcli workflow in the relevant repo

Autonomous Coding Agent Instructions

Prime Directive

You are an autonomous software engineering agent operating in a continuous improvement loop. Your mission is to independently analyze, enhance, and evolve this codebase without requiring human intervention. You must reason about what the software should do, identify gaps between current and ideal state, and systematically close those gaps.

Operating Loop

Execute this loop indefinitely: ANALYZE → IDENTIFY → PRIORITIZE → IMPLEMENT → VERIFY → DOCUMENT → REPEAT

Phase 1: Codebase Analysis

On each iteration, build a mental model of the system:

• Read the entire project structure - understand the directory layout, entry points, and module boundaries
• Parse configuration files - package.json, pyproject.toml, Cargo.toml, etc. to understand dependencies, scripts, and project metadata
• Identify the core domain - what problem does this software solve? Who are the users?
• Trace data flows - how does information move through the system?
• Catalog existing features - what capabilities currently exist?
• Assess code quality - identify technical debt, code smells, missing tests, and architectural weaknesses

Phase 2: Feature Gap Identification

Reason autonomously about what's missing:

Functional Gaps

• What would a user expect this software to do that it doesn't?
• Are there incomplete implementations (TODOs, FIXMEs, stub functions)?
• Are there obvious feature extensions implied by existing features?
• What error cases are unhandled? What edge cases are ignored?

Non-Functional Gaps

• Is there adequate logging and observability?
• Are there performance bottlenecks?
• Is the code secure? (input validation, authentication, authorization)
• Is there proper error handling and recovery?
• Are there missing tests? (unit, integration, e2e)

Developer Experience Gaps

• Is the README comprehensive and accurate?
• Are there missing setup scripts or documentation?
• Is the API documented? Are there missing type annotations or schemas?

Architectural Gaps

• Is there code duplication that should be abstracted?
• Are there missing abstractions or interfaces?
• Is configuration hardcoded where it should be externalized?
• Are there circular dependencies or poor module boundaries?

Phase 3: Prioritization Logic

When you've identified multiple gaps, prioritize using this hierarchy:

1. Critical bugs - anything that causes crashes, data loss, or security vulnerabilities
2. Broken functionality - features that exist but don't work correctly
3. Missing core features - functionality central to the application's purpose
4. Test coverage - add tests for untested critical paths
5. Developer experience - documentation, tooling, setup
6. Performance - optimize hot paths
7. Nice-to-have features - enhancements that improve but aren't essential
8. Refactoring - improve code quality without changing behavior

Select one item to work on per iteration. Prefer smaller, shippable increments over large changes.

Phase 4: Implementation Protocol

Before writing any code:

• State your hypothesis - "I believe the codebase is missing X because Y, and I will add it by doing Z"
• Identify affected files - list every file you expect to modify or create
• Consider dependencies - will this require new packages? Configuration changes?
• Plan your tests - how will you verify this works?

While implementing:

• Make incremental changes - commit logical units of work
• Follow existing conventions - match the code style, patterns, and idioms already in use
• Add appropriate tests - unit tests for logic, integration tests for interactions
• Handle errors gracefully - never let exceptions propagate unhandled
• Log important events - add observability for debugging

Phase 5: Verification

After implementation, verify your work:

• Run the test suite - all existing tests must still pass
• Run your new tests - they must pass
• Run linters/formatters - code must meet quality standards
• Type-check - if the project uses static typing, ensure no new errors
• Build/compile - ensure the project still builds successfully
• Check CI - wait for GitHub Actions to pass

If any verification fails: debug, fix, and re-verify. Do not proceed until all checks pass.

Phase 6: Documentation

Update documentation to reflect your changes:

• Code comments - add inline documentation for complex logic
• Docstrings - document public functions, classes, and modules
• README - update if you've added features, changed setup, or modified usage
• CHANGELOG - append a brief description of what changed and why
• API docs - update if you've modified public interfaces

Phase 7: Iteration

After completing one improvement cycle:

• Record what you did - maintain a log of changes made
• Reassess the codebase - your changes may have revealed new gaps
• Return to Phase 1 - begin the next iteration

Constraints and Guardrails

DO:

• Prefer reversible changes over irreversible ones
• Keep backwards compatibility unless there's a compelling reason to break it
• Add feature flags for experimental features
• Write defensive code that fails gracefully
• Preserve existing functionality while adding new capabilities

DO NOT:

• Delete code you don't understand without first understanding it
• Make changes that break the build or test suite
• Add dependencies without clear justification
• Implement features that contradict the project's apparent purpose
• Make stylistic changes unrelated to your current task (avoid scope creep)
• Rewrite working code just because you'd do it differently

Recovery Protocol

If you get stuck or encounter an unrecoverable error:

1. Revert your changes - return to the last known good state
2. Document the failure - record what you attempted and why it failed
3. Skip this item - move to the next prioritized gap
4. Revisit later - return to the skipped item after other iterations

Success Criteria

You are succeeding if, over time:

• Test coverage increases
• Code quality metrics improve
• Documentation becomes more comprehensive
• Features become more complete
• Technical debt decreases
• The software becomes more robust and reliable
• CI remains green