Coding Guidelines

Hard rules for code quality. Every agent and contributor must reference this document before writing code. These are not suggestions — they are enforced.

Return Values

Never return more than two values from a function unless one of them is error. If you need to return multiple pieces of data, use a struct.

Bad:

func fetch(host, path string) (string, string, string, error)

Three unnamed strings — what's the order? What does each one mean? The caller has to guess or read the implementation.

Good:

type FetchResult struct {
    Status string
    Body   string
    Etag   string
}

func fetch(host, path string) (FetchResult, error)

Named fields, self-documenting, impossible to mix up.

Don't Duplicate Logic

If the same logic exists in more than one place, extract it. Duplicated code leads to inconsistencies when one copy gets updated and the others don't.

Example: Token resolution was duplicated across CLI, TUI, and MCP — each had its own inline version of "load store, check env, check flag." One shared tokens.Resolve function replaced all of them and ensured consistent behavior everywhere.

When you see duplication:

1. Extract to a shared function in the appropriate package
2. Update all call sites
3. Delete the old copies

Function Signatures

Keep function signatures honest and minimal:

• If a parameter can be empty/zero and that's fine, document it
• Don't add parameters "for future use" — add them when needed
• Prefer structs over long parameter lists (more than 4 parameters is a smell)

Shared Behavior Across Clients

CLI, TUI, and MCP must behave consistently. If a feature works one way in the CLI, it must work the same way in TUI and MCP. Shared logic belongs in client/internal/ packages, not duplicated in each cmd/ directory.

When implementing a feature that touches multiple clients:

1. Put the core logic in an internal package
2. Each client calls the shared code
3. Test the shared code once, not three times

Error Handling

• Always handle errors at the point they occur
• Never ignore errors silently (except with a documented reason)
• Wrap errors with context: fmt.Errorf("fetch %s: %w", path, err)

Naming

• Use descriptive names that convey meaning
• Avoid single-letter variables except for loop counters and short closures
• Struct fields should be self-documenting — if a field needs a comment, consider renaming it