Skip to content

AGENTS.md

Latest commit

 

History

History
55 lines (47 loc) · 4.52 KB

AGENTS.md

File metadata and controls

55 lines (47 loc) · 4.52 KB

Repository Guidelines

Project Structure & Module Organization

This repository is a Go MCP server for pair-programming coordination. It supports a driver/worker model: one configurable driver (e.g. cursor, claude-code, or codex) and N workers that execute tasks with shared context and scope.

  • cmd/mcp-server/: executable entrypoint (main.go, daemon.go, proxy.go, cli_api.go, cli_commands.go). Supports daemon, proxy, and standalone modes. Workers can use CLI subcommands (heartbeat, progress, send, task, read, presence, context, work-ctx) that hit the REST API at /api/w/ over a unix socket. The heartbeat command accepts --session-id for CLI session resume on worker restart.
  • internal/domain/: core entities (AgentInstance, WorkContext, Task, Plan, etc.).
  • internal/app/: application services (CollabService, WorkerManager, TaskOrchestrator).
  • internal/tools/collab/: MCP tool handlers (tasks, messaging, plans, locks, worker_status, heartbeat, work_context, cancel_agent).
  • internal/repository/: persistence backend (sqlite/).
  • internal/policy/: workspace and safety policy; orchestration config (driver, workers); constitution sources (constitution_config.go, constitution_profile.go).
  • internal/constitution/: layered prompt resolver and dir/git-backed sources for team rules. See docs/CONSTITUTION.md.
  • mcp/: runtime config (config.yaml with daemon, orchestration sections).
  • docs/: setup, architecture, and workflow docs.
  • chrome-extension/: Chrome browser extension (alpha) — toolbar popup, badge counter, desktop notifications. Vanilla JS, Manifest V3.
  • scripts/: install, dev-install, hook install/uninstall scripts.

Build, Test, and Development Commands

  • go build -o mcp-stringwork ./cmd/mcp-server: build the server binary.
  • go test ./...: run all unit tests.
  • go test ./... -cover: run tests with coverage output.
  • go run ./cmd/mcp-server: run locally without building.
  • ./mcp-stringwork status claude-code: check unread/pending counts for an agent.
  • ./mcp-stringwork constitution show|init|sync|doctor: manage the layered prompt prepended to worker spawns. See docs/CONSTITUTION.md.

Coding Style & Naming Conventions

  • Follow standard Go formatting: run gofmt on changed files before opening a PR.
  • Use tabs for indentation (Go default); do not align with spaces manually.
  • Keep package names short and lowercase (app, policy, collab).
  • Exported identifiers: PascalCase; internal helpers: camelCase.
  • Test files must end with _test.go; prefer table-driven tests for behavior variants.

Testing Guidelines

  • Primary framework is Go’s built-in testing package.
  • Keep tests close to code under test in the same package directory.
  • Name tests clearly (Test<Function>_<Scenario>), e.g. TestClaimNext_DryRun.
  • Cover success paths, validation failures, and policy/safety edge cases.

Commit & Pull Request Guidelines

Git history is not available in this workspace, so adopt this convention:

  • Commit format: type(scope): imperative summary (e.g. feat(tasks): add dry-run claim).
  • Keep commits focused; separate refactors from behavior changes.
  • PRs should include: purpose, key changes, test evidence (go test ./... output), and linked issue/task.
  • Include config or API examples when behavior changes affect MCP clients.

Local vs Deployed Configuration

  • mcp/config.yaml is the repo default — shipped as a template for new installs.
  • ~/.config/stringwork/config.yaml is the user's live config — contains personal customizations (MCP servers, worktree settings, env vars, comments). Never overwrite it from scripts; only copy it when no config exists yet.
  • scripts/dev-install.sh deliberately skips syncing config.yaml for this reason. If worker prompts or orchestration settings change in the repo default, update the user's live config separately (or document the change so users update manually).
  • Claude Code hooks live at user level (~/.claude/settings.json, ~/.config/stringwork/hooks/) so they work across all projects, not just this repo. The .claude/ directory in this repo only contains command templates. Install with ./scripts/install-claude-hooks.sh, remove cleanly with ./scripts/uninstall-claude-hooks.sh.

Security & Configuration Tips

  • Do not commit local secrets or machine-specific paths.
  • Prefer MCP_CONFIG for local overrides instead of editing shared defaults.
  • Keep workspace path validation intact when changing file-lock or policy code.