Imported from swimmwatch/prompt-mcp (AGENTS.md). Install upstream with npx skills add swimmwatch/prompt-mcp. Copyright stays with the author.

AGENTS.md

Operating manual for AI coding agents working in this repository.

About The Project

prompt-mcp is a local stdio MCP server written in Go. It lets an MCP client run recoverable interviews with a local desktop user through a private GTK 4 dialog helper and returns structured responses to the calling tool.

• Runtime: Go; the supported version is declared in go.mod.
• Public surface: a CLI MCP server; stdout is reserved for the stdio transport.
• GUI boundary: prompt-mcp-dialog is a CGO-enabled GTK 4 helper installed beside the CGO-free server. It requires Linux, GTK 4, a user session, and a usable display.
• Project-specific agent assets are in .agents/skills/ and .agents/references/.

Golden Rules

1. Write the simplest code that satisfies the requested behavior.
2. Use official documentation and go doc for Go APIs. Use Context7 when it is available and up-to-date external library documentation is required.
3. Repository code, comments, documentation, identifiers, and commit messages are written in English.
4. Use CodeGraph before broad code search when a .codegraph/ index exists.
5. Never write runtime logs, diagnostics, helper output, or debug text to server stdout. Use stderr for logs; server stdout belongs exclusively to MCP stdio.
6. Resolve only the fixed sibling prompt-mcp-dialog, launch it without a shell, and send typed framed data through private pipes. Never use PATH, caller-selected executables, arguments, or environment values.
7. Preserve published MCP tool names and JSON schemas unless the user explicitly authorizes a contract change.

Intended Layout

Keep the implementation small and keep transport, tool contracts, and the external GUI boundary separate. Adjust this layout only when the code proves a different boundary is warranted.

cmd/prompt-mcp/           CLI entry point
cmd/prompt-mcp-dialog/    GTK 4 helper entry point
internal/mcp/             server setup, transport, and tool handlers
internal/prompt/          request/response contracts and prompt orchestration
internal/interview/       interview domain and application service
internal/journal/         memory and SQLite repositories
internal/dialog/          private helper protocol and process runner
internal/gtkdialog/       GTK 4 flow controller and widgets
internal/diagnostics/     stderr-only logging, when needed

Daily Commands

Use the checks applicable to the changed scope. Once go.mod exists, the baseline is:

go fmt ./...
go vet ./...
go test ./...
go test -race ./...
go build ./...
go mod tidy

Run golangci-lint run and govulncheck ./... when those tools are configured or the change affects quality, dependencies, or security. Do not claim a check passed when it was not available or was not run.

Go

• Run gofmt; do not hand-format Go source.
• Prefer small packages, explicit types at public boundaries, and idiomatic zero values. Avoid speculative interfaces and global mutable state.
• Put context.Context first in functions that wait, spawn processes, or call external services. Respect cancellation and deadlines.
• Return wrapped errors with actionable context. Do not log and return the same error at several layers.
• Add dependencies only when they are imported and justified. Run go mod tidy after dependency changes and review both go.mod and go.sum.
• Keep tests in *_test.go files near the code they verify. Use the standard testing package by default; add a test dependency only when its benefit is concrete.

MCP And Dialog Rules

• Model questions as typed requests and return typed, structured answers. Do not parse human-facing labels as program identifiers; give each choice a stable ID.
• Resolve prompt-mcp-dialog beside os.Executable() and validate the opened inode before execution. Never search PATH or accept a caller-selected path.
• Use the versioned length-prefixed JSON protocol over explicit stdin/stdout pipes. Questions, descriptions, IDs, answers, and confirmations must never travel through argv, environment, logs, or diagnostics.
• Launch the helper directly with its restricted environment, dedicated process group, and no inherited stdout/stderr. Kill and reap it on every terminal or protocol-failure path.
• Validate request sizes, question and option identities, progress, deadlines, event order, acknowledgements, and response shape at the dialog boundary.
• Serialize modal prompts so simultaneous MCP calls cannot create competing dialogs. The queue must honor context cancellation.
• Test helper resolution, framing, process cleanup, and response parsing with a fake sibling. Exercise GTK under Xvfb; CI must not open real desktop dialogs.
• Treat the helper as a local Linux/GTK 4 backend. Do not claim Windows or macOS support unless a tested backend is implemented for those systems.

Tests

• Cover tool input validation, command argument construction, cancellation, timeout, unavailable-display behavior, response parsing, and stdout/stderr separation.
• Tests that create files may write only below t.TempDir() paths they own.
• Use testing/fuzz or property tests for parsers, option normalization, and boundary-heavy request validation where it has a clear benefit.
• Keep real-desktop GTK checks manual and explicitly labelled. Automated tests must use a fake helper or isolated Xvfb display.

Supply Chain And GitHub Security

• Keep workflow permissions least-privilege: use top-level contents: read and grant write permissions only to the job that needs them.
• Pin external GitHub Actions by full commit SHA with the intended upstream version in a trailing comment.
• Pin Docker build and workflow images using tag@sha256:... references.
• Keep secrets out of source, logs, test fixtures, command arguments, and release notes. Do not broadly suppress security-tool findings.
• Run the configured workflow, container, dependency, and vulnerability checks after changes to those boundaries.

Specifications And Tasks

• Create a specification bundle under docs/specs/<slug>/ only for a substantial workstream that needs a durable contract or several implementation steps. Do not create one for a routine, fully defined change.
• Treat a specification as the behavior contract and task packets as execution instructions. Follow .agents/references/task-packets.md for substantial planning and implementation.
• During specification work, follow .agents/references/specification-interview.md, ask material decisions through the global Prompt MCP, and checkpoint non-sensitive answers in docs/specs/<slug>/decisions.yaml. Reload that ledger after compaction or handoff; do not rely on conversation history as the durable decision record.
• Keep spec.md in draft status until the user separately approves it through Prompt MCP. Do not treat proposed batch or recovery tools as available unless they are present in the callable tool set.
• During packet execution, read the applicable AGENTS.md, the current todo.md item, its linked packet, and only task-scoped code and references. Do not load an entire long specification unless the packet identifies a material conflict.

Documentation

• Update README.md and the closest docs/ page when public MCP behavior, CLI usage, GTK prerequisites, configuration, security boundaries, or compatibility changes.
• Document verified behavior, not planned work. State the Linux/GTK 4 desktop limitation prominently when it affects installation or operation.
• Add localized documentation only when the repository establishes it; do not generate or modify translations without explicit scope.
• When introduced, CHANGELOG.md must follow Keep a Changelog 1.1.0. Scan https://keepachangelog.com/en/1.1.0/ before editing release notes.
• For release preparation, publishing, verification, or recovery, read and follow .agents/skills/project-release/SKILL.md. For pull-request work, read and follow .agents/skills/project-pull-request/SKILL.md.

Commit And PR Hygiene

• One logical change per commit.
• Ask the user for explicit confirmation before creating a commit.
• Commit messages follow Conventional Commits 1.0.0. Scan https://www.conventionalcommits.org/en/v1.0.0/ before creating a commit.
• Bump versions only when explicitly requested. Call out security-sensitive changes in the pull-request description.

Things Not To Do

• Do not add Python, Node.js, Electron, a GUI toolkit, or another runtime without explicit approval.
• Do not add dependencies that are not imported.
• Do not spawn a shell to run the helper, search for it through PATH, or let the MCP caller control its executable, arguments, or environment.
• Do not commit binaries, coverage output, temporary files, caches, or local desktop artifacts.
• Do not weaken Go checks, test coverage expectations, workflow permissions, or protocol safety to make a change pass.