diff --git a/README.md b/README.md index 677ee9fc3cf232689b5307b894d627dd57a81a08..9521d556545d1e0577ac90889606bb39ca754ece 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ token count, plus overall metadata usage. I've used and tested them most with - [addressing-code-review-comments](skills/addressing-code-review-comments/SKILL.md): Finds `CR:` comments in code, gathers feedback, and carries out requested changes. +- [amoliths-opinions](skills/amoliths-opinions/SKILL.md): Applies Amolith's + opinions across project setup, tooling, licensing, dependencies, mise tasks, + CLIs, TUIs, MCP servers, web apps, packaging/releases, testing, and + Go-specific ecosystem defaults. - [ast-grep](skills/ast-grep/SKILL.md): Writes [ast-grep] rules for structural code search and modification. - [auditing-repositories](skills/auditing-repositories/SKILL.md): Audits open @@ -265,6 +269,36 @@ Token breakdown: ─────────────────────────────────────────────── Total: 339 tokens +=== amoliths-opinions === + +Token breakdown: + Name: 10 tokens + Description: 89 tokens + Body: 590 tokens (51 lines) + References: + cli.md 385 tokens + golang/baseline.md 860 tokens + golang/cli.md 777 tokens + golang/index.md 599 tokens + golang/licencing.md 206 tokens + golang/mcp.md 524 tokens + golang/mise.md 1331 tokens + golang/packaging.md 947 tokens + golang/preferred-libraries.md 621 tokens + golang/testing.md 486 tokens + golang/tui.md 381 tokens + golang/wails.md 621 tokens + golang/web.md 405 tokens + licencing.md 493 tokens + mcp.md 326 tokens + mise.md 350 tokens + packaging.md 462 tokens + testing.md 345 tokens + tui.md 222 tokens + web.md 400 tokens + ─────────────────────────────────────────────── + Total: 11430 tokens + === ast-grep === Token breakdown: @@ -651,14 +685,14 @@ SUMMARY ============================================================ Skills: 34 -Metadata: 2472 tokens -Combined bodies: 39382 tokens -Overall: 102150 tokens +Metadata: 2461 tokens +Combined bodies: 38718 tokens +Overall: 105475 tokens Validation errors: 0 Largest skills (by total tokens): 1. cooking 27605 tokens - 2. amoliths-go-opinions 7694 tokens + 2. amoliths-opinions 11430 tokens 3. ast-grep 5363 tokens 4. humanize 5020 tokens 5. frontend-accessibility 4770 tokens diff --git a/skills/amoliths-go-opinions/SKILL.md b/skills/amoliths-go-opinions/SKILL.md deleted file mode 100644 index 8d663eb1dcd4de90ac9934b6ce9eba6bd2b2315e..0000000000000000000000000000000000000000 --- a/skills/amoliths-go-opinions/SKILL.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -name: amoliths-go-opinions -description: "Triggers only for Go-focused requests involving Amolith's preferences or opinions, including Go language/tooling, std/community libraries, project setup/modernisation/audit, CLIs/TUIs/MCP servers/Wails desktop apps/web apps, Go-oriented mise tasks, packaging, linting, testing, and companion Go skills. If the user says they're Amolith, use this _every_ time you work in Go projects. If the user doesn't say they're Amolith, only load when explicitly instructed to." -user-invocable: true -license: LicenseRef-MutuaL-1.2 -metadata: - author: Amolith ---- - -Start from Amolith's strict Go baseline, then adapt it deliberately with the -user and the project in front of you. This skill is for shaping a Go project's -tooling, architecture, libraries, tests, packaging, and build workflow, not for -copying a boilerplate blindly. - -## Operating mode - -1. Inspect the repository first: `go.mod`, existing task runner, build files, - packaging files, UI surface, and any tests -2. Classify the project: library, CLI, TUI, MCP server, light web app, Wails - desktop app, frontend-heavy app, service, or some mix. -3. Tell the user what you found and ask only the questions needed to choose the - first step. Prefer specific "keep/adapt/drop this piece?" over open-ended - questionnaires. -4. Start from the strict baseline, then relax, remove, or add further pieces - only when the project needs them. -5. Implement in small slices: tooling first when it unblocks verification, then - one behaviour or surface at a time. -6. Verify each slice with the narrowest useful `mise run ...` task. - -Do not introduce Taskfiles or justfiles by default. If an older project uses -Task or just, translate the useful commands into `mise.toml` unless the user -explicitly asks to keep the old runner. - -## Baseline - -Default to: - -- `mise.toml` for tools and tasks -- `golangci-lint fmt` for formatting -- `golangci-lint run --enable-only modernize --fix ./...` for modernization -- `golangci-lint run --fix` for lint fixes -- `govulncheck ./...` for vulnerability scanning -- slower, race-enabled tests in development: `go test -v -race -count=5 -p=3 - -timeout=5m ./...`, with `CGO_ENABLED=1` for the test task -- pure-Go static release builds for CLIs, TUIs, and MCP servers when the - project does not require CGO -- explicit build/install tasks for binaries -- nFPM when shipping native Linux packages -- small packages with domain names, not generic `utils` -- standard library first unless a preferred library clearly fits -- Amolith's licensing convention when the project does not already say - otherwise: CC0 for docs/examples/config/prompt text, MutuaL for meaningful code - -Use this `.golangci.toml` shape unless the project already has a stronger local -configuration. Replace the module path placeholders with the module from -`go.mod`: - -```toml -version = "2" - -[linters] -enable = ["bodyclose", "errcheck", "errorlint", "exhaustive", "gocognit", "govet", "ineffassign", "modernize", "nilerr", "nilnil", "noctx", "revive", "staticcheck", "unused"] - -[linters.settings.gocognit] -min-complexity = 15 - -[[linters.settings.revive.rules]] -name = "file-length-limit" -arguments = [{ max = 1000, skip-comments = true, skip-blank-lines = true }] - -[[linters.settings.revive.rules]] -name = "max-control-nesting" -arguments = [5] - -[formatters] -enable = ["goimports", "gofumpt", "gci", "golines"] - -[formatters.settings.goimports] -local-prefixes = [""] - -[formatters.settings.gofumpt] -module-path = "" - -[formatters.settings.gci] -sections = ["standard", "default", "localmodule"] - -[formatters.settings.golines] -max-len = 120 -``` - -Default away from: - -- Taskfiles and justfiles in new setup -- clix/kong, even when another Go skill recommends it; use stdlib flags for - tiny tools and Cobra + Fang for user-facing CLIs -- generated wrappers around one command -- large frontend stacks for light server-rendered pages -- configuration frameworks when direct parsing is enough -- hidden global state unless a test seam restores it with `t.Cleanup` - -Use generic Go skills for implementation details, but this skill wins for -Amolith-specific setup choices: mise, golangci-lint formatting/fixing, -modernize, static build shape, CLI framework, packaging, Wails frontend stack, -web styling posture, and explicit gocuke adoption. - -Gocuke is an explicit project choice. Ask whether the project wants gocuke/BDD -automation; if yes, load the gocuke skill after behaviour is formulated. If no, -use ordinary Go tests. - -## Reference map - -Read [references/mise.md](references/mise.md) for every setup or modernisation -task. Then load only the references matching the project: - -- [references/licencing.md](references/licencing.md): Amolith's licensing - preferences and when to defer to `licensing-with-reuse`. -- [references/preferred-libraries.md](references/preferred-libraries.md): - default Go libraries and when to deviate. -- [references/cli.md](references/cli.md): Cobra/Fang CLIs and command layout. -- [references/tui.md](references/tui.md): Amolith-specific TUI setup deltas; - then load `golang-tui` for implementation details and read `cli.md` because - TUIs are command-line binaries. -- [references/mcp.md](references/mcp.md): MCP servers using the official Go SDK; - also read `cli.md` because MCP servers are command-line binaries. -- [references/wails.md](references/wails.md): Wails desktop apps and bindings; - also read `web.md` for frontend patterns and `packaging.md` for releases. -- [references/web.md](references/web.md): light Go web apps versus frontend-heavy - escalation. -- [references/packaging.md](references/packaging.md): nFPM, binary releases, and - Wails package assets; also read `mise.md` for build task templates. -- [references/testing.md](references/testing.md): unit, integration, BDD, and - property testing patterns. -- [references/project-guidance-template.md](references/project-guidance-template.md): - a concise AGENTS.md template for Go projects using this setup. diff --git a/skills/amoliths-go-opinions/references/preferred-libraries.md b/skills/amoliths-go-opinions/references/preferred-libraries.md deleted file mode 100644 index b8faa890bf6afd275f4c8acb4edd2feae80defd8..0000000000000000000000000000000000000000 --- a/skills/amoliths-go-opinions/references/preferred-libraries.md +++ /dev/null @@ -1,32 +0,0 @@ -# Preferred libraries - -Prefer the standard library until a library earns its keep. When a library is -needed, these are the usual defaults. - -| Need | Default | Notes | -| --- | --- | --- | -| TOML config | `github.com/BurntSushi/toml` | Preferred for direct, boring TOML parsing. Avoid heavy config frameworks by default. | -| CLI commands | `github.com/spf13/cobra` + `charm.land/fang/v2` | Cobra for command structure; Fang for polished help, errors, version, and signal handling. Tiny tools may use stdlib. | -| TUI implementation | Charm v2 stack via `golang-tui` | Load `golang-tui` for Bubble Tea, Lip Gloss, Bubbles, testing, layout, keymap, terminal, and performance details. | -| MCP server | `github.com/modelcontextprotocol/go-sdk` | Use typed parameter structs, tool annotations, stdio by default. | -| Wails desktop | `github.com/wailsapp/wails/v2` | Go owns domain logic; frontend renders state and calls bindings. | -| Light web server | `net/http`, `html/template`, `embed` | Default web stack for mostly server-rendered apps. | -| User-provided HTML sanitisation | `github.com/microcosm-cc/bluemonday` | Use strict or UGC policies intentionally. | -| SQLite without CGO | `modernc.org/sqlite` through `database/sql` | Useful for easily shipped binaries. Reconsider if CGO is already required. | -| RSS/Atom | `github.com/mmcdole/gofeed` | Fine for feed ingestion. | -| Git access in-process | `github.com/go-git/go-git/v5` | Useful when shelling out to git is not acceptable. | -| Behaviour specs | `github.com/regen-network/gocuke` | Explicit opt-in only. Ask whether the project wants gocuke before adding it. | -| Property tests | `pgregory.net/rapid` | Add around parsers, state machines, and merge logic. | -| Comparisons in tests | `github.com/google/go-cmp/cmp` | Prefer over ad-hoc string diffs for structured values. | -| Linux packages | `nfpm` | Prefer for `.deb`, `.rpm`, `.apk`, and Arch package artifacts. | - -## Dependency rules - -- Add dependencies with the relevant CLI (`go get`, `go install`, package - manager command); do not hand-edit manifests. -- Keep direct dependencies direct and intentional. Run `go mod tidy` after - changes. -- Prefer concrete types. Avoid broad maps, `any`, or reflection unless parsing a - real untyped boundary. -- If a project already made a different good choice, preserve it unless the user - asked for an opinionated migration. diff --git a/skills/amoliths-go-opinions/references/project-guidance-template.md b/skills/amoliths-go-opinions/references/project-guidance-template.md deleted file mode 100644 index da985ebb369750bd01b461b23aea51858040ea88..0000000000000000000000000000000000000000 --- a/skills/amoliths-go-opinions/references/project-guidance-template.md +++ /dev/null @@ -1,45 +0,0 @@ -# Project guidance template - -Use this when creating AGENTS.md. Keep it project-specific and short. Copy only -sections that apply. - -````markdown -# AGENTS.md - - is . - -## Commands - -```bash -mise run check # Runs fix, tidy, vet, vuln, build, and test:quiet -mise run fix # Runs golangci-lint fmt, modernize, and golangci-lint run --fix -mise run build # Builds -``` - -## Workflow - -- Use `mise` for project tooling and tasks. Run `mise run check` before ending - the turn. While iterating, use narrower tasks such as `mise run fix`, - `mise run test`, or parallelised mise tasks when appropriate. Do not bypass - mise with direct formatter or linter commands. - -- Follow red/green TDD for behaviour changes. Write or update the failing test - first, then implement the smallest slice that makes it green. - -- Do not smoke test unless asked. If smoke testing reveals a gap, add or improve - automated tests so the same issue is caught in the future. - -- Work in tiny slices that are independently verifiable. Keep unrelated - documentation, AGENTS.md, or tooling edits separate from feature changes. - -- If the project uses jujutsu, start by reading `jj status`. Use `jj diff --git` - for git-style diffs. Create a new change before unrelated work. - -- If the project uses a spec tool such as acai, update or confirm the relevant - spec before implementation and reference the exact spec IDs covered by the - slice. - -- If the project explicitly adopts gocuke, keep feature files and step - definitions aligned with the formulated behaviour. Otherwise, use ordinary Go - tests. -```` diff --git a/skills/amoliths-go-opinions/references/tui.md b/skills/amoliths-go-opinions/references/tui.md deleted file mode 100644 index c111e5cbffccb70b049ea4e9722f48acb29865da..0000000000000000000000000000000000000000 --- a/skills/amoliths-go-opinions/references/tui.md +++ /dev/null @@ -1,27 +0,0 @@ -# TUIs - -This file captures Amolith-specific TUI setup choices only. Load `golang-tui` -after this file for Bubble Tea, Lip Gloss, Bubbles, Elm Architecture, layout, -keymap, terminal-compatibility, testing, and performance details. - -TUIs are still command-line binaries. Read `cli.md` alongside this file for -Cobra/Fang setup, command ergonomics, completions, and version-policy guidance. - -## Amolith-specific deltas - -- Use the Charm v2 stack through `golang-tui` unless the project has already - made a different good choice. -- Do not copy Taskfile examples from `golang-tui`; translate useful commands - into `mise.toml` and keep the baseline tasks from `mise.md`. -- Keep the CLI surface consistent with `cli.md`: stdlib for tiny tools, - Cobra/Fang for user-facing commands, and one project-owned version policy when - exact versions matter. -- Use the regular race-enabled Go test task from `mise.md`. Add snapshot/golden - update tasks only when the project actually has snapshot tests. -- Terminal apps should use the same pure-Go static release-build shape as CLIs - when their dependencies allow it. Drop static-only flags for terminal - integrations that require CGO or native libraries. - -If `golang-tui` and this skill conflict, keep `golang-tui` for library/API -details and keep this skill for Amolith-specific tooling, task-runner, -packaging, CLI, and release-build policy. diff --git a/skills/amoliths-opinions/SKILL.md b/skills/amoliths-opinions/SKILL.md new file mode 100644 index 0000000000000000000000000000000000000000..923db396ff970b552f56fc978e1b51ec1878304b --- /dev/null +++ b/skills/amoliths-opinions/SKILL.md @@ -0,0 +1,60 @@ +--- +name: amoliths-opinions +description: "Applies Amolith's engineering opinions across project setup, tooling, licensing, dependency choices, mise tasks, CLIs, TUIs, MCP servers, web and desktop apps, packaging/releases, testing, BDD/property tests, and language/ecosystem defaults including Go. Use when a request asks for Amolith's preferences/opinions, says to impose his defaults, or when the user identifies as Amolith and is making these decisions." +user-invocable: true +license: LicenseRef-MutuaL-1.2 +metadata: + author: Amolith +--- + +Start from Amolith's opinions as defaults, then adapt them deliberately to the +user and repository in front of you. This skill is for shaping project choices: +tooling, architecture, libraries, licensing, tests, packaging, build workflow, +and product surface. Do not copy boilerplate blindly. + +## Operating mode + +1. Inspect the repository first: language manifests, existing task runner, build + files, packaging files, UI surface, tests, licensing, and project guidance. +2. Classify the work by surface: library, CLI, TUI, MCP server, web app, desktop + app, service, tooling-only project, or a mix. +3. Load the generic reference for each touched topic. If the project is Go, route + through [references/golang/index.md](references/golang/index.md) and follow + its required load order instead of jumping straight to a leaf file. +4. Tell the user what you found and ask only the questions needed to choose the + first step. Prefer specific "keep/adapt/drop this piece?" questions over + open-ended questionnaires. +5. Start from the strict opinionated baseline, then relax, remove, or add pieces + only when the project needs them. +6. Implement in small slices and verify each slice with the narrowest useful + project task. + +Explicit project conventions and direct user choices win over these defaults. +If the user is not Amolith and did not ask for Amolith's opinions, do not push +these preferences uninvited. + +## Reference map + +Read only the references needed for the task, but preserve the intended chains: +read the generic topic first, then the language/ecosystem index, then any leaf +files it requires. + +- [references/licencing.md](references/licencing.md): license defaults, REUSE + posture, and when to defer to `licensing-with-reuse`. +- [references/mise.md](references/mise.md): mise as task runner/tool installer + and how to translate older task runners. +- [references/cli.md](references/cli.md): command-line shape, config, versioning, + and UX posture. +- [references/tui.md](references/tui.md): terminal UI posture; also read + `cli.md` because TUIs are command-line programs. +- [references/mcp.md](references/mcp.md): MCP server tool design, transports, + config, and release posture. +- [references/web.md](references/web.md): light web apps, accessibility, CSS, and + when to escalate to frontend-heavy stacks. +- [references/packaging.md](references/packaging.md): release artifacts, version + gating, native packages, and installable apps. +- [references/testing.md](references/testing.md): risk-based testing, BDD, and + property-test posture. +- [references/golang/index.md](references/golang/index.md): Go-specific load + order for Go libraries, CLIs, TUIs, MCP servers, Wails apps, web apps, + packaging, testing, and preferred libraries. diff --git a/skills/amoliths-opinions/references/cli.md b/skills/amoliths-opinions/references/cli.md new file mode 100644 index 0000000000000000000000000000000000000000..5c2b352c81cab769be340107d7abc22ecced2823 --- /dev/null +++ b/skills/amoliths-opinions/references/cli.md @@ -0,0 +1,41 @@ +# CLIs + +Choose the smallest CLI shape that will still feel good to use. Prefer boring, +explicit command structure over clever frameworks, generated wrappers, or hidden +magic. + +## Shape choices + +- **One or two flags, server-style binary**: the ecosystem's standard flag parser + is usually enough. +- **User-facing command with help/version/completions/subcommands**: use a mature + command framework plus a polished help/error layer when the ecosystem has one. +- **Interactive prompts**: add a prompt library only when prompts are central, not + for a single confirmation. +- **Full-screen interaction**: this is a TUI; read [tui.md](tui.md). + +## Config and version policy + +- Read config at the boundary, validate early, and store it in typed domain + structures. +- Prefer explicit config discovery. Avoid magical precedence unless the project + truly needs layering. +- Default precedence is flag, then environment variable, then config file. +- Default config path is `$XDG_CONFIG_HOME//config.toml`, falling back + to `~/.config//config.toml` when `XDG_CONFIG_HOME` is unset. +- Do not add exact version plumbing just for its own sake. Add project-owned + version resolution when the version appears in release artifacts, package + metadata, MCP metadata, tests, or multiple user-visible surfaces. + +## UX rules + +- Human text goes to stderr when stdout may be piped. +- Machine output needs an explicit `--json`, `--jsonl`, or equivalent. +- Destructive commands need names and help text that make the effect obvious. +- Interactive commands need a non-interactive path for scripts and CI. + +## Go path + +For Go CLIs, read [golang/index.md](golang/index.md) first and follow its CLI +chain. Do not jump straight to `golang/cli.md`; the index intentionally forces +the Go baseline, mise, and library context before CLI specifics. diff --git a/skills/amoliths-opinions/references/golang/baseline.md b/skills/amoliths-opinions/references/golang/baseline.md new file mode 100644 index 0000000000000000000000000000000000000000..778b1dea2907a922cf515f971c4452356bdbde9e --- /dev/null +++ b/skills/amoliths-opinions/references/golang/baseline.md @@ -0,0 +1,96 @@ +# Go baseline + +Start from Amolith's strict Go baseline, then adapt it deliberately with the +user and the project in front of you. This file is for Go tooling, +architecture, libraries, tests, packaging, and build workflow, not for copying a +boilerplate blindly. + +## Go operating mode + +1. Inspect `go.mod`, existing task runner, build files, packaging files, UI + surface, and tests. +2. Classify the project: library, CLI, TUI, MCP server, light web app, Wails + desktop app, frontend-heavy app, service, or some mix. +3. Start from the strict baseline, then relax, remove, or add further pieces only + when the project needs them. +4. Verify each slice with the narrowest useful `mise run ...` task. + +Do not introduce Taskfiles or justfiles by default. If an older project uses +Task or just, translate the useful commands into `mise.toml` unless the user +explicitly asks to keep the old runner. + +## Defaults + +Default to: + +- `mise.toml` for tools and tasks +- `golangci-lint fmt` for formatting +- `golangci-lint run --enable-only modernize --fix ./...` for modernization +- `golangci-lint run --fix` for lint fixes +- `govulncheck ./...` for vulnerability scanning +- slower, race-enabled tests in development: `go test -v -race -count=5 -p=3 + -timeout=5m ./...`, with `CGO_ENABLED=1` for the test task +- pure-Go static release builds for CLIs, TUIs, and MCP servers when the project + does not require CGO +- explicit build/install tasks for binaries +- nFPM when shipping native Linux packages +- small packages with domain names, not generic `utils` +- standard library first unless a preferred library clearly fits +- Amolith's licensing convention when the project does not already say + otherwise: CC0 for docs/examples/config/prompt text, MutuaL for meaningful code + +Use this `.golangci.toml` shape unless the project already has a stronger local +configuration. Replace the module path placeholders with the module from +`go.mod`: + +```toml +version = "2" + +[linters] +enable = ["bodyclose", "errcheck", "errorlint", "exhaustive", "gocognit", "govet", "ineffassign", "modernize", "nilerr", "nilnil", "noctx", "revive", "staticcheck", "unused"] + +[linters.settings.gocognit] +min-complexity = 15 + +[[linters.settings.revive.rules]] +name = "file-length-limit" +arguments = [{ max = 1000, skip-comments = true, skip-blank-lines = true }] + +[[linters.settings.revive.rules]] +name = "max-control-nesting" +arguments = [5] + +[formatters] +enable = ["goimports", "gofumpt", "gci", "golines"] + +[formatters.settings.goimports] +local-prefixes = [""] + +[formatters.settings.gofumpt] +module-path = "" + +[formatters.settings.gci] +sections = ["standard", "default", "localmodule"] + +[formatters.settings.golines] +max-len = 120 +``` + +Default away from: + +- Taskfiles and justfiles in new setup +- clix/kong, even when another Go skill recommends it; use stdlib flags for tiny + tools and Cobra + Fang for user-facing CLIs +- generated wrappers around one command +- large frontend stacks for light server-rendered pages +- configuration frameworks when direct parsing is enough +- hidden global state unless a test seam restores it with `t.Cleanup` + +Use generic Go skills for implementation details, but this skill wins for +Amolith-specific setup choices: mise, golangci-lint formatting/fixing, +modernize, static build shape, CLI framework, packaging, Wails frontend stack, +web styling posture, and explicit gocuke adoption. + +Gocuke is an explicit project choice. Ask whether the project wants gocuke/BDD +automation; if yes, load the gocuke skill after behaviour is formulated. If no, +use ordinary Go tests. diff --git a/skills/amoliths-go-opinions/references/cli.md b/skills/amoliths-opinions/references/golang/cli.md similarity index 88% rename from skills/amoliths-go-opinions/references/cli.md rename to skills/amoliths-opinions/references/golang/cli.md index 2bc8059708b8acd42a8d0e60c8fbad0513c6e1bb..1f6f417f963fda639d2b62c2736bc5c43cb35f16 100644 --- a/skills/amoliths-go-opinions/references/cli.md +++ b/skills/amoliths-opinions/references/golang/cli.md @@ -1,6 +1,8 @@ -# CLIs +# Go CLIs -Choose the smallest CLI shape that will still feel good to use. +Read [../cli.md](../cli.md), [baseline.md](baseline.md), [mise.md](mise.md), +and [preferred-libraries.md](preferred-libraries.md) before applying these Go +CLI specifics. ## Shape choices @@ -10,7 +12,7 @@ Choose the smallest CLI shape that will still feel good to use. - Do not follow clix/kong guidance from generic Go skills for Amolith projects. - **Interactive prompts**: add `huh/v2` only when prompts are central, not for a single confirmation. -- **Full-screen interaction**: this is a TUI; read `tui.md`. +- **Full-screen interaction**: this is a TUI; read [tui.md](tui.md). ## Cobra + Fang baseline @@ -91,10 +93,3 @@ keep the same versioning pattern but remove the static-only flags. - Config precedence is flag, then environment variable, then config file. - Config discovery should be explicit and documented; avoid magical precedence unless the project truly needs layering. - -## UX rules - -- Human text goes to stderr when stdout may be piped. -- Machine output needs an explicit `--json`, `--jsonl`, or equivalent. -- Destructive commands need names and help text that make the effect obvious. -- Interactive commands need a non-interactive path for scripts and CI. diff --git a/skills/amoliths-opinions/references/golang/index.md b/skills/amoliths-opinions/references/golang/index.md new file mode 100644 index 0000000000000000000000000000000000000000..c6302fe19f92ba056be05223548590c48967ce80 --- /dev/null +++ b/skills/amoliths-opinions/references/golang/index.md @@ -0,0 +1,40 @@ +# Go opinion index + +This file is the mandatory entry point for Go-specific Amolith opinions. If a +request explicitly names a Go leaf topic such as Wails, MCP, TUI, packaging, or +CLI opinions, start here anyway. The ordering is intentional: agents should grok +the baseline before applying a surface-specific preference. + +Always read [baseline.md](baseline.md) before applying Go-specific opinions. +Then load the files for the project surface: + +- **Setup, modernisation, audit, or tooling**: read [mise.md](mise.md), + [preferred-libraries.md](preferred-libraries.md), and [testing.md](testing.md) + if verification or test posture is changing. +- **Library**: read [preferred-libraries.md](preferred-libraries.md) and + [testing.md](testing.md). Read [licencing.md](licencing.md) when project + metadata or file coverage changes. +- **CLI**: read [mise.md](mise.md), [preferred-libraries.md](preferred-libraries.md), + and [cli.md](cli.md). Read [packaging.md](packaging.md) for release/install + work. +- **TUI**: read [mise.md](mise.md), [preferred-libraries.md](preferred-libraries.md), + [cli.md](cli.md), [tui.md](tui.md), and [testing.md](testing.md). Read + [packaging.md](packaging.md) for release/install work. +- **MCP server**: read [mise.md](mise.md), [preferred-libraries.md](preferred-libraries.md), + [cli.md](cli.md), [mcp.md](mcp.md), and [testing.md](testing.md). Read + [packaging.md](packaging.md) only when system installation, services, or + managed config files are part of the product. +- **Light web app**: read [mise.md](mise.md), [preferred-libraries.md](preferred-libraries.md), + [web.md](web.md), and [testing.md](testing.md). +- **Wails desktop app**: read [mise.md](mise.md), [preferred-libraries.md](preferred-libraries.md), + [web.md](web.md), [wails.md](wails.md), [packaging.md](packaging.md), and + [testing.md](testing.md). +- **Packaging/release work**: read [mise.md](mise.md), [packaging.md](packaging.md), + and [cli.md](cli.md) for binary version policy. Add [wails.md](wails.md) for + Wails desktop releases. +- **Licencing**: read [../licencing.md](../licencing.md), then + [licencing.md](licencing.md) for Go/package metadata notes. + +If a generic reference and a Go reference conflict, keep the generic reference +for cross-ecosystem intent and the Go reference for concrete Go tooling, +libraries, command names, build flags, and implementation details. diff --git a/skills/amoliths-opinions/references/golang/licencing.md b/skills/amoliths-opinions/references/golang/licencing.md new file mode 100644 index 0000000000000000000000000000000000000000..4530a9d4d25410799e647cada320e33494f18c6c --- /dev/null +++ b/skills/amoliths-opinions/references/golang/licencing.md @@ -0,0 +1,18 @@ +# Go licencing + +Read [../licencing.md](../licencing.md) before this file. This file only adds Go +and Go-adjacent metadata notes. + +- Go source files are meaningful source code unless they are generated examples + or samples; use the project license convention from the generic licencing file. +- `go.mod` has no license field. Do not treat module metadata as a substitute for + REUSE coverage or license files. +- When generating nFPM or other package metadata for Go binaries, set the package + `license` field to the chosen SPDX expression or `LicenseRef-*` value. +- When bundling assets for Go web or Wails apps, include their license metadata in + the REUSE model before packaging them. +- Generated Go files still need a licensing decision. Prefer REUSE annotations or + sidecar `.license` files when editing generated content would be fragile. + +Run `reuse lint` after changing licenses, license texts, annotations, vendored +content, generated-file coverage, or package asset coverage. diff --git a/skills/amoliths-go-opinions/references/mcp.md b/skills/amoliths-opinions/references/golang/mcp.md similarity index 72% rename from skills/amoliths-go-opinions/references/mcp.md rename to skills/amoliths-opinions/references/golang/mcp.md index ec9a947be8289f8bb1deb2dccea687bf2cc5ad38..3bee17fd441dc641c8775389f2a4be848d76c295 100644 --- a/skills/amoliths-go-opinions/references/mcp.md +++ b/skills/amoliths-opinions/references/golang/mcp.md @@ -1,11 +1,15 @@ -# MCP servers +# Go MCP servers + +Read [../mcp.md](../mcp.md), [baseline.md](baseline.md), [mise.md](mise.md), +[cli.md](cli.md), and [preferred-libraries.md](preferred-libraries.md) before +applying these Go MCP specifics. Use the official Go SDK: `github.com/modelcontextprotocol/go-sdk`. Default to stdio for local agent use; choose Streamable HTTP only when the server needs networked clients or deployment behind an HTTP boundary. -MCP servers are still command-line binaries. Read `cli.md` alongside this file -for Cobra/Fang setup, command ergonomics, and version-policy guidance. +MCP servers are still command-line binaries. Keep the CLI/versioning rules from +[cli.md](cli.md) in force. ## Shape @@ -43,12 +47,12 @@ them. MCP servers are usually plain static binaries. Use `CGO_ENABLED=0` unless a dependency requires CGO. Add nFPM only when system installation, services, or -managed config files are part of the product (seldom). +managed config files are part of the product. -Prefer the static build shape from `mise.md`: `netgo`, `osusergo`, optional -project-specific `static_build`, `-d -s -w -buildid= -extldflags=-static`, and -explicit version injection when the server exposes `--version` or embeds version -metadata. Do not rely on Fang's CLI fallback alone for MCP implementation +Prefer the static build shape from [mise.md](mise.md): `netgo`, `osusergo`, +optional project-specific `static_build`, `-d -s -w -buildid= -extldflags=-static`, +and explicit version injection when the server exposes `--version` or embeds +version metadata. Do not rely on Fang's CLI fallback alone for MCP implementation metadata; use the same project-owned version value anywhere the server reports it. Remove those static-only pieces when the wrapped API client or storage layer requires CGO. diff --git a/skills/amoliths-go-opinions/references/mise.md b/skills/amoliths-opinions/references/golang/mise.md similarity index 88% rename from skills/amoliths-go-opinions/references/mise.md rename to skills/amoliths-opinions/references/golang/mise.md index f390efc46737af237969117d362b1dd93ebcb66b..af0f8be4edeadffca4756335e4f37584c0252d8c 100644 --- a/skills/amoliths-go-opinions/references/mise.md +++ b/skills/amoliths-opinions/references/golang/mise.md @@ -1,8 +1,9 @@ -# mise +# Go mise -Use `mise.toml` as the project task runner and tool installer. Translate older -Taskfile/justfile commands into mise instead of preserving the old runner by -default. +Read [../mise.md](../mise.md) and [baseline.md](baseline.md) before applying +this file. Use `mise.toml` as the project task runner and tool installer. +Translate older Taskfile/justfile commands into mise instead of preserving the +old runner by default. ## Baseline Go `mise.toml` @@ -131,8 +132,8 @@ go install \ Do not settle version policy by copying the static template. The template leaves `-buildvcs` unspecified, so Go uses its `auto` behavior. For version reporting, those fields matter only if project code or Fang reads them; they can still -matter for reproducibility or privacy, so choose `-buildvcs` explicitly when -that matters. Choose the policy with the user: +matter for reproducibility or privacy, so choose `-buildvcs` explicitly when that +matters. Choose the policy with the user: - **Best-effort local/dev metadata**: leave `-buildvcs` unset and read `runtime/debug.BuildInfo` or Fang's fallback when `unknown` is acceptable. @@ -172,6 +173,7 @@ run = "go tool pprof -http :6061 'http://127.0.0.1:6060/debug/pprof/allocs'" ## Frontend or Wails projects -Add only the tools the project needs. For Wails, see `wails.md`; for light web -apps, see `web.md`. Keep frontend package manager choice project-specific: use -the existing lockfile, or ask before introducing npm, Bun, pnpm, or yarn. +Add only the tools the project needs. For Wails, see [wails.md](wails.md); for +light web apps, see [web.md](web.md). Keep frontend package manager choice +project-specific: use the existing lockfile, or ask before introducing npm, Bun, +pnpm, or yarn. diff --git a/skills/amoliths-go-opinions/references/packaging.md b/skills/amoliths-opinions/references/golang/packaging.md similarity index 85% rename from skills/amoliths-go-opinions/references/packaging.md rename to skills/amoliths-opinions/references/golang/packaging.md index 9bab0447fb11943116d8b6cbd7429cc7fd32fcd7..32cc72cbd893b9f52302a0f791e085a74888719b 100644 --- a/skills/amoliths-go-opinions/references/packaging.md +++ b/skills/amoliths-opinions/references/golang/packaging.md @@ -1,18 +1,18 @@ -# Packaging and releases +# Go packaging and releases -Packaging is part of the baseline when the project is meant to be installed, -not an afterthought. +Read [../packaging.md](../packaging.md), [baseline.md](baseline.md), +[mise.md](mise.md), and [cli.md](cli.md) before applying these Go release +specifics. -Read `mise.md` for build task templates before adding package tasks. For CLI, -TUI, and MCP binaries, also read `cli.md` for version-policy guidance. +Packaging is part of the baseline when the project is meant to be installed, not +an afterthought. ## Choose the artifact - **Plain CLI/MCP server**: cross-compiled binaries are usually enough. - **System service**: add systemd/OpenRC files and consider nFPM packages. - **Desktop/Wails app**: use nFPM for Linux packages, desktop files, icons, and - WebKit runtime dependencies; use Wails/NSIS for Windows installers when - needed. + WebKit runtime dependencies; use Wails/NSIS for Windows installers when needed. - **Library**: no binary packaging unless examples/tools are part of the repo. ## Version gating @@ -30,8 +30,8 @@ version=${version#v} For jj-backed projects, use the project's agreed jj/git-derived release command instead. Do not infer package versions from Go `BuildInfo` unless the project -explicitly chose that policy. For development builds, `VERSION=dev` is fine; -for packages, be stricter. +explicitly chose that policy. For development builds, `VERSION=dev` is fine; for +packages, be stricter. ## nFPM baseline @@ -53,7 +53,7 @@ contents: dst: /usr/bin/example ``` -For desktop apps, add: +For Wails/Linux desktop apps, add package assets and WebKit dependencies: ```yaml contents: @@ -110,10 +110,10 @@ works well for every OS or binary format. - For CLI, TUI, and MCP release binaries, prefer `netgo`, `osusergo`, optional project-specific `static_build`, `-d -s -w -buildid=`, and `-extldflags=-static` when dependencies are pure Go. -- Treat Go VCS build metadata as a policy choice, not the package version - source. If a package needs exact version or commit strings, derive them in the - package task and inject them. If a release intentionally relies on Go - `BuildInfo`, make that explicit and consider `-buildvcs=true`. +- Treat Go VCS build metadata as a policy choice, not the package version source. + If a package needs exact version or commit strings, derive them in the package + task and inject them. If a release intentionally relies on Go `BuildInfo`, make + that explicit and consider `-buildvcs=true`. - Wails/Linux builds require native CGO and WebKitGTK. - Windows Wails cross-builds from Linux need mingw-w64; NSIS packages need `makensis`. diff --git a/skills/amoliths-opinions/references/golang/preferred-libraries.md b/skills/amoliths-opinions/references/golang/preferred-libraries.md new file mode 100644 index 0000000000000000000000000000000000000000..2bba380ec3608f41c8687f21491a5513cb255e51 --- /dev/null +++ b/skills/amoliths-opinions/references/golang/preferred-libraries.md @@ -0,0 +1,33 @@ +# Go preferred libraries + +Read [baseline.md](baseline.md) before this file. Prefer the standard library +until a library earns its keep. When a library is needed, these are the usual Go +defaults. + +| Need | Default | Notes | +| ------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| TOML config | `github.com/BurntSushi/toml` | Preferred for direct, boring TOML parsing. Avoid heavy config frameworks by default. | +| CLI commands | `github.com/spf13/cobra` + `charm.land/fang/v2` | Cobra for command structure; Fang for polished help, errors, version, and signal handling. Tiny tools may use stdlib. | +| TUI implementation | Charm v2 stack via `golang-tui` | Load `golang-tui` for Bubble Tea, Lip Gloss, Bubbles, testing, layout, keymap, terminal, and performance details. | +| MCP server | `github.com/modelcontextprotocol/go-sdk` | Use typed parameter structs, tool annotations, stdio by default. | +| Wails desktop | `github.com/wailsapp/wails/v2` | Go owns domain logic; frontend renders state and calls bindings. | +| Light web server | `net/http`, `html/template`, `embed` | Default web stack for mostly server-rendered apps. | +| User-provided HTML sanitisation | `github.com/microcosm-cc/bluemonday` | Use strict or UGC policies intentionally. | +| SQLite without CGO | `modernc.org/sqlite` through `database/sql` | Useful for easily shipped binaries. Reconsider if CGO is already required. | +| RSS/Atom | `github.com/mmcdole/gofeed` | Fine for feed ingestion. | +| Git access in-process | `github.com/go-git/go-git/v5` | Useful when shelling out to git is not acceptable. | +| Behaviour specs | `github.com/regen-network/gocuke` | Explicit opt-in only. Ask whether the project wants gocuke before adding it. | +| Property tests | `pgregory.net/rapid` | Add around parsers, state machines, and merge logic. | +| Comparisons in tests | `github.com/google/go-cmp/cmp` | Prefer over ad-hoc string diffs for structured values. | +| Linux packages | `nfpm` | Prefer for `.deb`, `.rpm`, `.apk`, and Arch package artifacts. | + +## Dependency rules + +- Add dependencies with the relevant CLI (`go get`, `go install`, package + manager command); do not hand-edit manifests. +- Keep direct dependencies direct and intentional. Run `go mod tidy` after + changes. +- Prefer concrete types. Avoid broad maps, `any`, or reflection unless parsing a + real untyped boundary. +- If a project already made a different good choice, preserve it unless the user + asked for an opinionated migration. diff --git a/skills/amoliths-go-opinions/references/testing.md b/skills/amoliths-opinions/references/golang/testing.md similarity index 81% rename from skills/amoliths-go-opinions/references/testing.md rename to skills/amoliths-opinions/references/golang/testing.md index eae030f550328634982a435a88e0ccd0665eb032..409ae4b4db428d19029c1c79ee60957629068bd9 100644 --- a/skills/amoliths-go-opinions/references/testing.md +++ b/skills/amoliths-opinions/references/golang/testing.md @@ -1,8 +1,7 @@ -# Testing +# Go testing -Test depth should match risk. Tooling changes need command verification; -domain behaviour needs tests; broad shared behaviour deserves BDD or property -coverage. +Read [../testing.md](../testing.md), [baseline.md](baseline.md), and +[mise.md](mise.md) before applying these Go testing specifics. ## Go defaults @@ -34,8 +33,8 @@ Good fits for gocuke: - non-interactive CLI behaviour - lifecycle rules with many examples -Keep step definitions grouped by domain concept, not by feature-file name. -Let gocuke print missing step signatures instead of hand-guessing them. +Keep step definitions grouped by domain concept, not by feature-file name. Let +gocuke print missing step signatures instead of hand-guessing them. ## Property tests @@ -52,8 +51,9 @@ Keep properties small and name the invariant clearly. ## TUI tests Load `golang-tui` for Bubble Tea harnesses, snapshots, and terminal-specific -test patterns. Keep the regular race-enabled Go test task from `mise.md`. Add -snapshot/golden update tasks only when the project actually has snapshot tests. +test patterns. Keep the regular race-enabled Go test task from [mise.md](mise.md). +Add snapshot/golden update tasks only when the project actually has snapshot +tests. ## Wails/frontend tests diff --git a/skills/amoliths-opinions/references/golang/tui.md b/skills/amoliths-opinions/references/golang/tui.md new file mode 100644 index 0000000000000000000000000000000000000000..9c7681fb1838cd4485e331f4f152fbeded5dc37d --- /dev/null +++ b/skills/amoliths-opinions/references/golang/tui.md @@ -0,0 +1,33 @@ +# Go TUIs + +Read [../tui.md](../tui.md), [baseline.md](baseline.md), [mise.md](mise.md), +[cli.md](cli.md), [testing.md](testing.md), and +[preferred-libraries.md](preferred-libraries.md) before applying these Go TUI +specifics. + +This file captures Amolith-specific Go TUI setup choices only. Load `golang-tui` +after this file for Bubble Tea, Lip Gloss, Bubbles, Elm Architecture, layout, +keymap, terminal-compatibility, testing, and performance details. + +TUIs are still command-line binaries. Keep the Cobra/Fang setup, command +ergonomics, completions, and version-policy guidance from [cli.md](cli.md) in +force. + +## Amolith-specific deltas + +- Use the Charm v2 stack through `golang-tui` unless the project has already made + a different good choice. +- Do not copy Taskfile examples from `golang-tui`; translate useful commands into + `mise.toml` and keep the baseline tasks from [mise.md](mise.md). +- Keep the CLI surface consistent with [cli.md](cli.md): stdlib for tiny tools, + Cobra/Fang for user-facing commands, and one project-owned version policy when + exact versions matter. +- Use the regular race-enabled Go test task from [mise.md](mise.md). Add + snapshot/golden update tasks only when the project actually has snapshot tests. +- Terminal apps should use the same pure-Go static release-build shape as CLIs + when their dependencies allow it. Drop static-only flags for terminal + integrations that require CGO or native libraries. + +If `golang-tui` and this skill conflict, keep `golang-tui` for library/API +details and keep this skill for Amolith-specific tooling, task-runner, +packaging, CLI, and release-build policy. diff --git a/skills/amoliths-go-opinions/references/wails.md b/skills/amoliths-opinions/references/golang/wails.md similarity index 74% rename from skills/amoliths-go-opinions/references/wails.md rename to skills/amoliths-opinions/references/golang/wails.md index 9e608b080b8cf522ee47e1bbf8864246f9d315a2..cb219e7bcd78d53a09dcfadfbcb88afde30af70e 100644 --- a/skills/amoliths-go-opinions/references/wails.md +++ b/skills/amoliths-opinions/references/golang/wails.md @@ -1,18 +1,19 @@ # Wails desktop apps +Read [baseline.md](baseline.md), [mise.md](mise.md), [web.md](web.md), +[packaging.md](packaging.md), [testing.md](testing.md), and +[preferred-libraries.md](preferred-libraries.md) before applying these Wails +specifics. + Use Wails when the app is a desktop product, not merely because it has a web view. Go should own application logic; the frontend should render state and call bindings. -Read `web.md` alongside this file for frontend CSS, accessibility, and semantic -token guidance. Read `packaging.md` for every Wails setup; desktop apps need a -packaging story from the start. - ## Build/tooling -Start from the baseline in `mise.md`; keep its fmt, modernize, lint, vuln, -race-enabled test, and check tasks. Then add Wails/frontend tools and tasks in -mise, not Taskfile: +Start from the baseline in [mise.md](mise.md); keep its fmt, modernize, lint, +vuln, race-enabled test, and check tasks. Then add Wails/frontend tools and +tasks in mise, not Taskfile: ```toml [tools] @@ -48,9 +49,9 @@ CLI guidance. ## Frontend stack -Use the existing package manager if one exists. Ask before introducing a new -one. Use Svelte 5 + TypeScript + Vite for Wails frontends. Tailwind and -shadcn-svelte are optional project choices, not defaults to add blindly. +Use the existing package manager if one exists. Ask before introducing a new one. +Use Svelte 5 + TypeScript + Vite for Wails frontends. Tailwind and shadcn-svelte +are optional project choices, not defaults to add blindly. Frontend checks usually split from backend checks: @@ -75,4 +76,5 @@ parse arbitrary English when the backend can categorise the failure. ## Packaging -Read `packaging.md` for nFPM, desktop files, icons, and WebKit dependencies. +Read [packaging.md](packaging.md) for nFPM, desktop files, icons, and WebKit +dependencies. diff --git a/skills/amoliths-go-opinions/references/web.md b/skills/amoliths-opinions/references/golang/web.md similarity index 62% rename from skills/amoliths-go-opinions/references/web.md rename to skills/amoliths-opinions/references/golang/web.md index e70fefd8d1162e3ff0a883395e19a584b4275ed7..912b685d5ddd24f71b88fde45f47084e20b4ec98 100644 --- a/skills/amoliths-go-opinions/references/web.md +++ b/skills/amoliths-opinions/references/golang/web.md @@ -1,4 +1,8 @@ -# Web apps +# Go web apps + +Read [../web.md](../web.md), [baseline.md](baseline.md), [mise.md](mise.md), +[testing.md](testing.md), and [preferred-libraries.md](preferred-libraries.md) +before applying these Go web specifics. Default to a light server-rendered stack unless the product is clearly frontend-heavy. @@ -35,19 +39,6 @@ internal/web/ or web/ Use `template.ParseFS` with named shared templates. Keep handlers thin: parse input, call domain code, render or redirect. -## CSS and accessibility - -- Use semantic HTML and real form controls. -- Include viewport and colour-scheme metadata. -- Use CSS custom properties as semantic design tokens. OKLCH is preferred for - colour palettes when browser support is acceptable. -- Support dark mode by overriding semantic tokens under `prefers-color-scheme`. -- Use spacing, radius, type, and measure scales instead of one-off values. -- Prefer simple responsive layouts with CSS grid/flex. -- Use accessible fonts when bundling fonts; include licence metadata when the - project is REUSE-compliant. -- Do not use ARIA to compensate for avoidable non-semantic markup. - ## Security - Treat form/query values as untrusted. @@ -59,7 +50,7 @@ input, call domain code, render or redirect. ## Escalate to frontend-heavy only when needed Escalate to a frontend-heavy stack only when the UI needs rich local state, -complex component composition, desktop integration, drag/drop, long-running -event streams, or substantial client-side interaction. For Wails, prefer Svelte -5 + TypeScript + Vite; Tailwind and shadcn-svelte remain explicit project -choices. If the page can remain a form and a template, keep it light. +complex component composition, desktop integration, drag/drop, long-running event +streams, or substantial client-side interaction. For Wails, prefer Svelte 5 + +TypeScript + Vite; Tailwind and shadcn-svelte remain explicit project choices. +If the page can remain a form and a template, keep it light. diff --git a/skills/amoliths-go-opinions/references/licencing.md b/skills/amoliths-opinions/references/licencing.md similarity index 82% rename from skills/amoliths-go-opinions/references/licencing.md rename to skills/amoliths-opinions/references/licencing.md index 5d3a8e13e2d2ddb35b0a248735e027f6b4a89e48..db9c37c5c567ba8401cb1de32ce732add73e91a6 100644 --- a/skills/amoliths-go-opinions/references/licencing.md +++ b/skills/amoliths-opinions/references/licencing.md @@ -1,7 +1,7 @@ # Licencing -When applying Amolith's preferences, use the licensing-with-reuse skill to learn -mechanics. If you don't see it already, ask me to add it from +When applying Amolith's preferences, use the `licensing-with-reuse` skill to +learn mechanics. If you don't see it already, ask Amolith to add it from . ## If the user is Amolith @@ -9,7 +9,8 @@ mechanics. If you don't see it already, ask me to add it from If Amolith asks to apply all of his opinions and the project does not already say otherwise, use this convention: -- documentation, examples, sample configs, prompts, and project guidance: `CC0-1.0` +- documentation, examples, sample configs, prompts, and project guidance: + `CC0-1.0` - meaningful source code: `LicenseRef-MutuaL-1.2` Do not make a speech about it. Apply the convention with the REUSE CLI, add any @@ -40,3 +41,9 @@ for evaluation and the user decides against MutuaL, remove the temporary copy. If the user has already stated a license preference, or declines fetching the MutuaL text, do not push. Apply their stated preference with the REUSE CLI. + +## Go path + +For Go projects, read [golang/index.md](golang/index.md) first and follow its +licencing chain. The Go-specific file adds package/build metadata notes; this +file remains the source for Amolith's actual license preferences. diff --git a/skills/amoliths-opinions/references/mcp.md b/skills/amoliths-opinions/references/mcp.md new file mode 100644 index 0000000000000000000000000000000000000000..af620361e35cbe6e6637395864f23f6298adcd56 --- /dev/null +++ b/skills/amoliths-opinions/references/mcp.md @@ -0,0 +1,39 @@ +# MCP servers + +Build MCP servers as small, explicit adapters around a domain or external API. +Default to stdio for local agent use; choose Streamable HTTP only when the server +needs networked clients or deployment behind an HTTP boundary. + +## Shape + +- Keep transport/config setup separate from tool handlers. +- Keep API clients or domain logic outside the MCP layer. +- Prefer typed parameter/result structures when the language supports them. +- If the wrapped API has sharp edges, add a `usage`/instructions tool documenting + them. + +## Tools + +- Add tool annotations: read-only/destructive/idempotent/open-world hints. +- Make descriptions operational: what the tool does, when to use it, and any + required prerequisite tool. +- Return structured errors for real failures. Use tool-level errors for domain + failures the model should see and potentially recover from. +- Clamp or validate bounds at the boundary and document whether clamping is + silent or an error. + +## Config and release + +- Required connection info comes from env vars and/or explicit flags. +- Validate URLs and auth shape before starting the server. +- Allow separate auth layers when real deployments need them, but document how + headers/cookies interact. +- Treat MCP servers as installable command-line binaries unless the deployment + model clearly says otherwise; read [cli.md](cli.md) and [packaging.md](packaging.md) + when building release artifacts. + +## Go path + +For Go MCP servers, read [golang/index.md](golang/index.md) first and follow its +MCP chain. That route intentionally loads Go baseline, CLI, mise, and preferred +library context before `golang/mcp.md`. diff --git a/skills/amoliths-opinions/references/mise.md b/skills/amoliths-opinions/references/mise.md new file mode 100644 index 0000000000000000000000000000000000000000..4583f91923695d42d053ce388a105b64b66fb899 --- /dev/null +++ b/skills/amoliths-opinions/references/mise.md @@ -0,0 +1,36 @@ +# mise + +Use `mise.toml` as Amolith's default project task runner and tool installer when +a project does not already have a stronger local convention. Translate older +Taskfile/justfile commands into mise instead of preserving the old runner by +default. + +## Task shape + +- Keep visible tasks simple and memorable: `fmt`, `lint`, `fix`, `build`, `test`, + `check`, and surface-specific tasks such as `pkg` or `dev`. +- Use hidden/helper tasks only when they reduce duplication or make release steps + safer. +- Prefer one `check` task that performs the project's full local verification. +- Keep mutating tasks honest. If a task fixes or tidies files, name it that way. +- Add tools only when the project needs them; do not install whole ecosystems just + because a template did. +- Preserve existing package-manager lockfiles. Ask before introducing npm, Bun, + pnpm, yarn, or a language-specific package manager to a project without one. + +Do not add Taskfiles or justfiles by default. If an older project uses Task or +just, translate the useful commands into `mise.toml` unless the user explicitly +asks to keep the old runner. + +## Verification posture + +Run the narrowest useful `mise run ...` task while iterating. Run `mise run +check` before ending broad setup, tooling, or release-work turns when the project +has a check task and it is practical to run. + +## Go path + +For Go setup, modernisation, builds, tests, or packaging, read +[golang/index.md](golang/index.md) first and follow its mise chain. Do not jump +straight to `golang/mise.md`; the index intentionally loads the Go baseline and +related topic files first. diff --git a/skills/amoliths-opinions/references/packaging.md b/skills/amoliths-opinions/references/packaging.md new file mode 100644 index 0000000000000000000000000000000000000000..af4460494c5726ddd06352b87067818d16c8d125 --- /dev/null +++ b/skills/amoliths-opinions/references/packaging.md @@ -0,0 +1,57 @@ +# Packaging and releases + +Packaging is part of the baseline when the project is meant to be installed, not +an afterthought. Choose the artifact based on how people will actually use the +project. + +## Choose the artifact + +- **Library**: no binary packaging unless examples/tools are part of the repo. +- **Plain CLI or MCP server**: release archives or cross-compiled binaries are + usually enough. +- **System service**: add service files and consider native packages. +- **Desktop app**: include desktop files, icons, runtime dependencies, and OS + installer/package constraints from the start. + +## Version gating + +Package tasks should fail on ambiguous versions. Prefer exact tags for release +packages. For development builds, `VERSION=dev` is fine; for packages, be +stricter. + +For Git-tagged releases, a package task can gate on an exact tag: + +```sh +version=$(git describe --tags --exact-match 2>/dev/null) || { + echo "Error: package builds require an exact vMAJOR.MINOR.PATCH tag" >&2 + exit 1 +} +version=${version#v} +``` + +For jj-backed projects, use the project's agreed jj/git-derived release command +instead. Do not infer package versions from language build metadata unless the +project explicitly chose that policy. + +## Native Linux packages + +Use nFPM when shipping `.deb`, `.rpm`, `.apk`, or Arch-style package artifacts +from a non-distro package pipeline. Keep package metadata boring, explicit, and +consistent with the project's chosen license. + +Visible mise tasks should be simple: `pkg`, `pkg:deb`, `pkg:rpm`, `pkg:apk`, +`pkg:arch`. Put version resolution, icon conversion, binary staging, package +builds, and optional compression in hidden/helper tasks when needed. + +UPX is optional. Use it only when size matters; do not assume it works well for +every OS or binary format. + +Document cross-compilation constraints in task descriptions and preconditions +rather than letting users discover linker or runtime failures. + +## Go path + +For Go binaries, MCP servers, TUIs, web apps, or Wails releases, read +[golang/index.md](golang/index.md) first and follow its packaging chain. The Go +path covers static builds, CGO exceptions, Wails/Linux constraints, and Go +version-injection policy. diff --git a/skills/amoliths-opinions/references/testing.md b/skills/amoliths-opinions/references/testing.md new file mode 100644 index 0000000000000000000000000000000000000000..94745934511adb9c4ced4ec2215f69eb9f95cc3c --- /dev/null +++ b/skills/amoliths-opinions/references/testing.md @@ -0,0 +1,49 @@ +# Testing + +Test depth should match risk. Tooling changes need command verification; domain +behaviour needs tests; broad shared behaviour deserves BDD or property coverage. + +## Defaults + +- Prefer fast, isolated automated tests over smoke testing. +- Follow red/green TDD for behaviour changes when practical: write or update the + failing test first, then implement the smallest slice that makes it green. +- Do not smoke test unless asked. If smoke testing reveals a gap, add or improve + automated tests so the same issue is caught in the future. +- Use temp directories, scoped environment overrides, and cleanup hooks for + isolation. +- Restore package/module globals after tests that mutate them. +- Add integration tests around real protocol, filesystem, database, or process + boundaries when mocks would hide the risk. + +## Behaviour and BDD + +When behaviour is still being discovered, use the BDD discovery skill first if +available. Do not add a BDD runner implicitly; ask whether the project wants BDD +automation after the behaviour is formulated. + +Good fits for BDD: + +- config merge/precedence rules +- interactive flow rules +- non-interactive CLI behaviour +- lifecycle rules with many examples + +## Property tests + +Use property tests around: + +- parsers and serializers +- path/config expansion +- state machines +- merge logic +- sorting/ranking invariants + +Keep properties small and name the invariant clearly. + +## Go path + +For Go tests, BDD automation, race settings, TUI tests, or Wails/frontend split +checks, read [golang/index.md](golang/index.md) first and follow its testing +chain. The Go path covers gocuke, rapid, go-cmp, race-enabled test tasks, and +Charm/Wails test posture. diff --git a/skills/amoliths-opinions/references/tui.md b/skills/amoliths-opinions/references/tui.md new file mode 100644 index 0000000000000000000000000000000000000000..70c57ec759aad75ce70417daae72a87a84a8d122 --- /dev/null +++ b/skills/amoliths-opinions/references/tui.md @@ -0,0 +1,25 @@ +# TUIs + +Treat TUIs as command-line programs with a full-screen interaction model. Read +[cli.md](cli.md) first for command ergonomics, config, versioning, stdout/stderr, +and non-interactive behaviour. + +## Posture + +- Use a mature TUI framework when the interface has state, layout, focus, + keymaps, or async work. +- Keep the CLI surface consistent with the rest of the project: flags for + startup/config, command context for cancellation, and explicit output modes for + non-interactive use. +- Do not copy another tool's task-runner examples blindly; translate useful + commands into the project's chosen task runner. +- Add snapshot/golden update tasks only when the project actually has snapshot or + golden tests. +- Treat terminal compatibility and performance as product concerns, not polish to + add at the end. + +## Go path + +For Go TUIs, read [golang/index.md](golang/index.md) first and follow its TUI +chain. That route intentionally loads Go baseline, CLI, mise, testing, and Charm +context before `golang/tui.md`. diff --git a/skills/amoliths-opinions/references/web.md b/skills/amoliths-opinions/references/web.md new file mode 100644 index 0000000000000000000000000000000000000000..ab3d311cc386dec5e6b3697b0150b9a347066c37 --- /dev/null +++ b/skills/amoliths-opinions/references/web.md @@ -0,0 +1,48 @@ +# Web apps + +Default to a light server-rendered stack unless the product is clearly +frontend-heavy. If a page can remain a form and a template, keep it light. + +## Default posture + +- Use semantic HTML forms and links before client-side JavaScript. +- Use plain CSS with semantic variables for modest interfaces. +- Add a small frontend toolchain only when formatting, typechecking, bundling, or + component complexity earns it. +- Use existing package managers and lockfiles. Ask before introducing a new one. + +This is the default for admin panels, dashboards, release trackers, internal +tools, and server-rendered apps with modest interaction. + +## CSS and accessibility + +- Use semantic HTML and real form controls. +- Include viewport and colour-scheme metadata. +- Use CSS custom properties as semantic design tokens. OKLCH is preferred for + colour palettes when browser support is acceptable. +- Support dark mode by overriding semantic tokens under `prefers-color-scheme`. +- Use spacing, radius, type, and measure scales instead of one-off values. +- Prefer simple responsive layouts with CSS grid/flex. +- Use accessible fonts when bundling fonts; include licence metadata when the + project is REUSE-compliant. +- Do not use ARIA to compensate for avoidable non-semantic markup. + +## Security + +- Treat form/query values as untrusted. +- Use a sanitizer when rendering user-provided HTML or Markdown-derived HTML. +- Keep auth/session logic in a domain package; handlers should not duplicate + password or token handling. + +## Escalate only when needed + +Escalate to a frontend-heavy stack only when the UI needs rich local state, +complex component composition, desktop integration, drag/drop, long-running event +streams, or substantial client-side interaction. + +## Go path + +For Go web apps or Wails frontends, read [golang/index.md](golang/index.md) +first and follow its web or Wails chain. The Go path covers `net/http`, +templates, `embed`, Wails/Svelte posture, and Go-specific security/library +choices.