AGENTS.md ยท diff
git:20260119.6edb8ef to git:20260121.dfa62fb
56 added, 22 removed. Audit A to A.
- # Repository Guidelines
+ ---
+ title: "Agents"
+ description: "Repository guidelines for AI agents working with the FinFocus codebase"
+ layout: "docs"
+ ---
- ## Project Snapshot
+ ## Repository Guidelines
+ **Table of Contents:**
+
+ - [Project Snapshot](#project-snapshot)
+ - [Build, Lint, and Test Commands](#build-lint-and-test-commands)
+ - [Go Formatting and Imports](#go-formatting-and-imports)
+ - [Types, Naming, and API Surface](#types-naming-and-api-surface)
+ - [Error Handling and Control Flow](#error-handling-and-control-flow)
+ - [Logging Expectations](#logging-expectations)
+ - [Testing Guidelines](#testing-guidelines)
+ - [Testify Assertions (Required)](#testify-assertions-required)
+ - [Documentation and Markdown](#documentation-and-markdown)
+ - [Commit and PR Guidance](#commit-and-pr-guidance)
+ - [Security and Configuration](#security-and-configuration)
+ - [Common Workflows](#common-workflows)
+ - [Current Stack](#current-stack)
+ - [Cursor/Copilot Rules](#cursorcopilot-rules)
+ - [Active Technologies](#active-technologies)
+ - [Recent Changes](#recent-changes)
+
+ ### Project Snapshot
+
- Go CLI for finfocus in `cmd/finfocus` with unexported logic in `internal/`.
- Fixtures live in `examples/`, `testdata/`, and `test/e2e/fixtures/`.
- Docs are in `docs/`; scripts in `scripts/`; build artifacts in `bin/`.
- ## Build, Lint, and Test Commands
+ ### Build, Lint, and Test Commands
- `make build`: Build the `finfocus` binary into `bin/` with version metadata.
- `make run` / `make dev`: Build then run the CLI; `make inspect` launches MCP inspector.
- `make test` | `make test-race`: Run unit tests (optionally with race detector).
- `go test ./...`: Run the full Go test suite.
- `go test -run TestName ./path/to/package`: Run a single test in one package.
- `go test -v ./... -run TestFunc`: Run a single test across all packages.
- `make lint`: Run `golangci-lint` v2.6.2 plus `markdownlint`.
- `make validate`: Run `go mod tidy -diff` and `go vet` checks.
- `make docs-lint`: Lint docs when editing Markdown.
- ## Go Formatting and Imports
+ ### Go Formatting and Imports
- Go 1.25.5+; use tabs for indentation and run `gofmt` on Go files.
- Imports grouped as: standard library, third-party, internal packages.
- `goimports`/`golines` enforced via `golangci-lint`; keep lines tidy.
- Avoid `init()` and global variables (lint rule).
- `//nolint:lintername` only when required and with justification.
- ## Types, Naming, and API Surface
+ ### Types, Naming, and API Surface
- Package names lowercase and short (`engine`, `config`, `pluginhost`).
- Custom domain types preferred (`type Duration time.Duration`).
- Exported identifiers require Go doc comments when part of CLI surface.
- Struct tags use JSON/YAML tags (`yaml:"field_name"`).
- CLI flags are kebab-case; env/config keys uppercase snake (`FINFOCUS_*`).
- Define interfaces before implementations; keep interfaces small.
- Pass `context.Context` through request lifecycles.
- ## Error Handling and Control Flow
+ ### Error Handling and Control Flow
- Wrap errors with `%w`: `fmt.Errorf("operation failed: %w", err)`.
- Sentinel errors are `var ErrName = errors.New("description")`.
- Validate inputs early and return descriptive errors.
- Prefer early returns to reduce nesting.
- Use context cancellation and return partial results where sensible.
- ## Logging Expectations
+ ### Logging Expectations
- Use `internal/logging` for structured logging.
- Fetch logger from context: `log := logging.FromContext(ctx)`.
- Include `component` and `operation` fields for traceability.
- Use `Debug` for detailed flow, `Info` for milestones, `Warn` for recoverable issues.
- ## Testing Guidelines
+ ### Testing Guidelines
- Table-driven tests with clear `wantErr` / `errContains` fields.
- Test both success and failure paths, especially file I/O and validation.
- Use fixtures from `testdata/` or `examples/` over large literals.
- Use integration tests in `examples/` for HTTP/CRUD flows.
- Plugins: add conformance coverage in `internal/conformance` and targeted tests in
`internal/engine` or `internal/registry`.
- ## Testify Assertions (Required)
+ ### Testify Assertions (Required)
**CRITICAL**: All Go tests must use `testify/assert` and `testify/require`.
Required imports:
```go
import (
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
```
Use `require.*` for setup failures and nil checks, `assert.*` for value comparisons.
- ## Documentation and Markdown
+ ### Documentation and Markdown
- Docs use frontmatter with `title`, `description`, and `layout`.
- Frontmatter `title` is the H1; content must start with H2 or body text.
- Run `make docs-lint` after Markdown edits.
- `markdownlint` runs as part of `make lint`.
- ## Commit and PR Guidance
+ ### Commit and PR Guidance
- Conventional Commits required (`feat:`, `fix:`, `chore:`...).
- PRs include summary, linked issues, and a test plan (e.g., `make test`).
- Avoid bundling unrelated changes; call out breaking changes.
- Run `make lint` and `make test` before committing.
- ## Security and Configuration
+ ### Security and Configuration
- Never commit secrets; use `FINFOCUS_PLUGIN_*` env vars or `~/.finfocus/config.yaml`.
- Plugins live in `~/.finfocus/plugins/<name>/<version>/`.
- Validate plugins with `finfocus plugin validate` and `finfocus plugin certify`.
- Scrub Pulumi plan fixtures if identifiers appear.
- ## Common Workflows
+ ### Common Workflows
- ### Adding Resource Types
+ #### Adding Resource Types
- 1. Add resource type to `internal/engine/types.go`.
- 2. Implement validation in the resource `Validate()` method.
- 3. Add pricing data in `specs/` or via plugin support.
- 4. Add unit tests in `internal/engine/types_test.go`.
- 5. Add integration tests in `internal/conformance/`.
+ 1. Declare a resource type in `internal/engine/types.go`.
+ 2. Implement validation in the resource's `Validate()` method.
+ 3. Provide pricing data in `specs/` or via plugin support.
+ 4. Create unit tests in `internal/engine/types_test.go`.
+ 5. Create integration tests in `internal/conformance/`.
- ### Plugin Development
+ #### Plugin Development
- `finfocus plugin init` scaffolds new plugins.
- Implement the protocol from finfocus-spec.
- Install to `~/.finfocus/plugins/<name>/<version>/`.
- ## Current Stack
+ ### Current Stack
- Go 1.25.5 with `github.com/Masterminds/semver/v3` and finfocus plugin SDK.
- charmbracelet/lipgloss v1.0.0 and golang.org/x/term v0.37.0.
- Plugin directory: `~/.finfocus/plugins/<plugin-name>/<version>/`.
- ## Cursor/Copilot Rules
+ ### Cursor/Copilot Rules
- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found.
+
+ ### Active Technologies
+
+ - Go 1.25.5 + finfocus-spec SDK, Cobra CLI, zerolog, gRPC, pluginsdk (001-plugin-init-recorder)
+ - Local filesystem for fixture downloads and recorded request output (001-plugin-init-recorder)
+
+ ### Recent Changes
+
+ - 001-plugin-init-recorder: Added Go 1.25.5 + finfocus-spec SDK, Cobra CLI, zerolog, gRPC, pluginsdk