Claude GitHub Copilot opencode Skill

finfocus-dev

FinFocus Core development workflow guide for contributors. Use when implementing features, fixing bugs, writing tests, running CI checks, or following project conventions in the finfocus Go codebase. Triggers on: adding CLI commands, writing Go tests, running make targets, debugg

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download rshade-finfocus-.claude_skills_finfocus-dev_finfocus-dev-835e5f9.zip · 5 KB

Install

skills CLI npx skills add https://github.com/rshade/finfocus/tree/main/.claude/skills/finfocus-dev/finfocus-dev
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rshade-finfocus@llmmart
Git git clone https://github.com/rshade/finfocus.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rshade/finfocus collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

FinFocus Development Workflow

Quick Reference

make build          # Build binary to bin/finfocus
make test           # Unit tests (fast, default)
make lint           # golangci-lint + markdownlint (5+ min, use extended timeout)
make validate       # go mod tidy + go vet
make test-race      # Race detector
make test-integration  # Cross-component tests (10min timeout)
make build-all      # Build binary + all plugins

Critical rules: Always run make lint and make test before claiming success. Never run git commit (user commits manually). Never modify .golangci.yml.

Adding a CLI Command

  1. Create internal/cli/your_command.go
  2. Follow constructor pattern:
func NewYourCmd() *cobra.Command {
    var flagVar string
    cmd := &cobra.Command{
        Use:   "your-command",
        Short: "Description",
        RunE: func(cmd *cobra.Command, args []string) error {
            // Use cmd.Printf() not fmt.Printf()
            return nil
        },
    }
    cmd.Flags().StringVar(&flagVar, "flag", "", "description")
    return cmd
}
  1. Register in parent command (e.g., root.go or cost.go)
  2. Use RunE (not Run) for error handling
  3. Defer cleanup immediately: defer cleanup()

Resource Processing Pipeline

All cost commands follow:

ingest.LoadPulumiPlan(path) -> ingest.MapResources() -> registry.Open(ctx, adapter)
  -> engine.GetProjectedCost/GetActualCost() -> engine.RenderResults(format, results)

Testing Standards

  • Use testify/assert and testify/require exclusively (never manual if/t.Errorf)
  • require.* for setup that must succeed; assert.* for value checks
  • Table-driven tests for variations
  • Package suffix _test for black-box testing
  • t.TempDir() for temporary files (auto-cleanup)
  • Capture output: cmd.SetOut(&buf) and cmd.SetErr(&buf)
  • Target 80% coverage minimum, 95% for critical paths

See references/testing-patterns.md for detailed test patterns and examples.

Project Structure

See references/project-structure.md for the complete package map and key file locations.

Error Handling

  • Wrap errors: fmt.Errorf("context: %w", err)
  • Return early on errors
  • Plugin failures don't stop processing (graceful degradation)
  • Validation prefix: "VALIDATION: %v", plugin error prefix: "ERROR:"

Logging (zerolog)

log := logging.FromContext(ctx)
log.Debug().Ctx(ctx).Str("component", "engine").Msg("message")

Standard fields: trace_id, component, operation, duration_ms. Enable debug: --debug flag or FINFOCUS_LOG_LEVEL=debug.

Date Handling

Support both "2006-01-02" and RFC3339. Default --to to time.Now(). Validate ranges (to must be after from).

Output Formats

Three formats via --output flag: table (default), json, ndjson. Always use cmd.Printf() for testability.

Files (finfocus)
  • references
    • project-structure.md 5 KB
      Loading…
    • testing-patterns.md 4.5 KB
      Loading…
  • SKILL.md 3.3 KB
    ---
    name: finfocus-dev
    description: >
      FinFocus Core development workflow guide for contributors. Use when implementing features,
      fixing bugs, writing tests, running CI checks, or following project conventions in the
      finfocus Go codebase. Triggers on: adding CLI commands, writing Go tests, running make
      targets, debugging CI failures, understanding project structure, or any Go development
      task within finfocus-core.
    ---
    
    # FinFocus Development Workflow
    
    ## Quick Reference
    
    ```bash
    make build          # Build binary to bin/finfocus
    make test           # Unit tests (fast, default)
    make lint           # golangci-lint + markdownlint (5+ min, use extended timeout)
    make validate       # go mod tidy + go vet
    make test-race      # Race detector
    make test-integration  # Cross-component tests (10min timeout)
    make build-all      # Build binary + all plugins
    ```
    
    **Critical rules**: Always run `make lint` and `make test` before claiming success.
    Never run `git commit` (user commits manually). Never modify `.golangci.yml`.
    
    ## Adding a CLI Command
    
    1. Create `internal/cli/your_command.go`
    1. Follow constructor pattern:
    
    ```go
    func NewYourCmd() *cobra.Command {
        var flagVar string
        cmd := &cobra.Command{
            Use:   "your-command",
            Short: "Description",
            RunE: func(cmd *cobra.Command, args []string) error {
                // Use cmd.Printf() not fmt.Printf()
                return nil
            },
        }
        cmd.Flags().StringVar(&flagVar, "flag", "", "description")
        return cmd
    }
    ```
    
    1. Register in parent command (e.g., `root.go` or `cost.go`)
    1. Use `RunE` (not `Run`) for error handling
    1. Defer cleanup immediately: `defer cleanup()`
    
    ## Resource Processing Pipeline
    
    All cost commands follow:
    
    ```text
    ingest.LoadPulumiPlan(path) -> ingest.MapResources() -> registry.Open(ctx, adapter)
      -> engine.GetProjectedCost/GetActualCost() -> engine.RenderResults(format, results)
    ```
    
    ## Testing Standards
    
    - Use `testify/assert` and `testify/require` exclusively (never manual `if/t.Errorf`)
    - `require.*` for setup that must succeed; `assert.*` for value checks
    - Table-driven tests for variations
    - Package suffix `_test` for black-box testing
    - `t.TempDir()` for temporary files (auto-cleanup)
    - Capture output: `cmd.SetOut(&buf)` and `cmd.SetErr(&buf)`
    - Target 80% coverage minimum, 95% for critical paths
    
    See [references/testing-patterns.md](references/testing-patterns.md) for detailed
    test patterns and examples.
    
    ## Project Structure
    
    See [references/project-structure.md](references/project-structure.md) for the
    complete package map and key file locations.
    
    ## Error Handling
    
    - Wrap errors: `fmt.Errorf("context: %w", err)`
    - Return early on errors
    - Plugin failures don't stop processing (graceful degradation)
    - Validation prefix: `"VALIDATION: %v"`, plugin error prefix: `"ERROR:"`
    
    ## Logging (zerolog)
    
    ```go
    log := logging.FromContext(ctx)
    log.Debug().Ctx(ctx).Str("component", "engine").Msg("message")
    ```
    
    Standard fields: `trace_id`, `component`, `operation`, `duration_ms`.
    Enable debug: `--debug` flag or `FINFOCUS_LOG_LEVEL=debug`.
    
    ## Date Handling
    
    Support both `"2006-01-02"` and RFC3339. Default `--to` to `time.Now()`.
    Validate ranges (to must be after from).
    
    ## Output Formats
    
    Three formats via `--output` flag: `table` (default), `json`, `ndjson`.
    Always use `cmd.Printf()` for testability.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.