Skip to content

coding-agent-setup.md

Latest commit

 

History

History
283 lines (203 loc) · 17.1 KB

coding-agent-setup.md

File metadata and controls

283 lines (203 loc) · 17.1 KB
Raw

Coding Agent Setup

How the coding agents on this machine are configured, and what this repo stows for them.

This setup targets two harnesses:

  • pi — configured via the dot-pi stow package
  • opencode — configured via ~/.config/opencode/ (not stowed)

The skill tooling (gh skill install and bunx skills add) is harness-agnostic: both accept an --agent flag, so the same commands work for pi, opencode, or any other supported harness. Where an agent has its own system-prompt rules file (pi's APPEND_SYSTEM.md, opencode's instructions/), the rules in this doc are meant to be replicated there.

pi: stowed package dot-pi

The dot-pi/ package stows pi's user settings file to ~/.pi/agent/settings.json:

cd ~/.dotfiles
stow -t ~ --dotfiles dot-pi

(--dotfiles is required: inside the package, dot-pi/ maps to the hidden .pi/ directory in your home.)

What's in settings.json

  • defaultProvider / defaultModel / defaultThinkingLevel / theme — pi's interactive defaults
  • packages — pi package dependencies

Dependencies

The repo pins the pi-subagents extension package (delegation + scripted multi-agent workflows):

Package Spec in settings.json pi.dev page
pi-subagents npm:pi-subagents https://pi.dev/packages/pi-subagents

Install/update pi packages with:

pi install npm:pi-subagents   # adds to settings.json
pi update --all               # update pi + packages
pi list                       # show installed packages

Installed packages live in ~/.pi/agent/npm/ (real directory, not stowed).

pi system prompt

pi ships a default system prompt that you can override:

  • ~/.pi/agent/SYSTEM.md — replaces the default system prompt (global)
  • ~/.pi/agent/APPEND_SYSTEM.md — appends to the default (global)
  • .pi/SYSTEM.md / .pi/APPEND_SYSTEM.md — per-project variants

This repo ships dot-pi/dot-pi/agent/APPEND_SYSTEM.md, which stows to ~/.pi/agent/APPEND_SYSTEM.md. It contains the global agent rules (bun-only JS tooling, "Always use uv for Python", fd/rg for search instead of find/grep with command outputs saved to files, asd-ste100 for documentation, aggressive ask_user / web_search use, subagent review before commit/push, the project-skills loading rule, and the stack-tools rule to find official skills and MCP servers for each technology — e.g. Supabase). The rules are written in ASD-STE100 Simplified Technical English. Changes take effect on the next pi start.

The same rules apply to opencode via ~/.config/opencode/instructions/agent-rules.md (registered in opencode.jsonc under instructions), adapted to opencode's tools (ask, webfetch, /tmp/opencode, general subagents). Keep the two rule files in sync.

opencode: ~/.config/opencode/

opencode's config lives in ~/.config/opencode/ and is not stowed by this repo (it is machine-local). Key files:

  • opencode.jsonc — instructions (which instruction files load every session) and MCP servers
  • instructions/ — always-on guidance, e.g. rust-skills.md, agent-rules.md
  • skills/ — skills loaded into opencode sessions

Warning

~/.config/opencode/ is not safe to stow or commit wholesale. It holds secrets: cli.json and service.json contain credentials/tokens, and node_modules/ / package-lock.json are local tooling. Never add this directory to a stow package or git repo. Only individual files that are known to be safe (e.g. opencode.jsonc, instructions/, skills/) should ever be versioned, and even then only if they contain no secrets — audit them first.

When you add an always-on rule for opencode, put it in an instructions/*.md file and register it in opencode.jsonc under instructions (see the rust-skills.md entry for the pattern).

Per-stack MCP servers

Per the agent rules, use the official MCP server for each technology in the stack instead of hand-rolled API calls. Add each one to the mcp block of opencode.jsonc (and the pi config if pi supports it). The mcp block in this machine's opencode.jsonc already includes Cloudflare (https://mcp.cloudflare.com/mcp) and Supabase (https://mcp.supabase.com/mcp).

To find the official server for a new technology, search the web for <technology> official MCP server and read the project's docs — do not guess the URL. Prefer remote servers with oauth auth when the provider supports it. Servers that require a secret stay out of the committed/stowed config.

wger (workout tracking)

The official wger MCP server exposes the wger REST API (routines, workout logs, sessions, body weight, analytics). Wired into three consumers:

Consumer Config WGER_BASE_URL
opencode (this machine) ~/.config/opencode/opencode.jsonc https://wger.nithitsuki.com
opencode (lumen) ~/.config/opencode/opencode.jsonc http://localhost:8002
Hermes (hermes-agent on lumen) /opt/data/config.yaml → mcp_servers https://wger.nithitsuki.com

All three run it over stdio: uvx wger-mcp --transport stdio. MCP_TOOLS trims the tool surface — 85 tools is ≈18.6k tokens of schema per request. opencode uses the coach profile, Hermes the trainee profile plus analytics:

MCP_TOOLS=routines,workout_logs,workout_sessions,exercises,analytics

The credential is a wger DRF API key (wger → Settings → API key), and it acts as your account, so it is not committed here. opencode reads it from its machine-local config; Hermes reads WGER_API_KEY from containers/hermes-agent/.env, which is SOPS-encrypted in the homelab repo. Mint one with:

podman exec wgernithitsukicom_web_1 sh -c \
  "cd /home/wger/src && python3 manage.py drf_create_token nithitsuki"

Requires wger ≥ 2.6 (this instance is 2.7.0). Hermes also needs the container recreated, not just restarted, for a changed env_file to reach the process: podman-compose up -d --force-recreate.

Deliberately NOT stowed

These live under ~/.pi/agent/ and ~/.config/opencode/ but stay local to the machine:

  • auth.json (pi) / cli.json / service.json (opencode) — API keys / OAuth credentials (secrets, never commit)
  • trust.json — per-project trust decisions (machine-specific paths)
  • npm/ — installed pi package cache
  • node_modules/, package-lock.json — opencode local tooling (machine-local)
  • sessions/, missions/, run-history.jsonl, models-store.json — runtime state

Skills (user scope)

Skills are not stored in this repo. Two harness-agnostic tools install them into the single global skills directory ~/.agents/skills/ — the open agent skills location used by opencode and auto-discovered by pi. Skills live there as real directories, not stowed:

  • The GitHub CLI (gh skill install)
  • The skills CLI (bunx skills add)

Both take an --agent flag. Point them at opencode: it targets the shared ~/.agents/skills/ directory that pi also auto-discovers (see the warning below) — do not pass --agent pi too.

One global location — do not duplicate into ~/.pi/agent/skills. pi auto-discovers ~/.agents/skills, so a skill installed there is available to pi and opencode alike. Install with --agent opencode (which targets ~/.agents/skills) and do not also pass --agent pi: that writes a second copy into ~/.pi/agent/skills, and because pi loads ~/.pi/agent/skills before ~/.agents/skills, the duplicate shadows the global copy and pi logs a name-collision (✗ ~/.agents/skills/<name>/SKILL.md (skipped)). The ~/.pi/agent/skills directory must contain only symlinks to ~/.agents/skills entries (plus ship-quality, which ships via stow). If a skill is wrongly present as a real directory in both places, replace the ~/.pi copy with a symlink so both paths resolve to the same file:

rm -rf ~/.pi/agent/skills/<name>
ln -s ../../../.agents/skills/<name> ~/.pi/agent/skills/<name>

Via the GitHub CLI

Run these during setup:

gh skill install --agent opencode --scope user brycewang-stanford/Auto-Empirical-Research-Skills latex-to-typst
gh skill install --agent opencode --scope user brycewang-stanford/Auto-Empirical-Research-Skills typst-paper
gh skill install --agent opencode --scope user --pin main jihe520/MathModelAgent typst-author
gh skill install --agent opencode --scope user nithitsuki/asd-ste100-skill asd-ste100
Skill Source repo
latex-to-typst brycewang-stanford/Auto-Empirical-Research-Skills
typst-paper brycewang-stanford/Auto-Empirical-Research-Skills
typst-author jihe520/MathModelAgent
asd-ste100 nithitsuki/asd-ste100-skill

Via the skills CLI

The skills CLI is the package manager for the open agent skills ecosystem (skills.sh). It copies each skill into the target agent's global skills directory. Run this during setup:

bunx skills add https://github.com/anthropics/skills --skill skill-creator --agent opencode --global --copy --yes
bunx skills add https://github.com/mattpocock/skills --skill '*' --agent opencode --global --copy --yes

Pass --agent opencode only — do not add --agent pi (see the warning above), or you write a duplicate copy into ~/.pi/agent/skills.

Skill Source repo Purpose
skill-creator anthropics/skills Creates new skills, improves existing skills, runs evals

Update skill-creator with bunx skills update skill-creator --global.

Matt Pocock's skills (mattpocock/skills)

The second command installs all 35 skills from mattpocock/skills. --copy copies the files into the global ~/.agents/skills/ directory, which both opencode and pi read. It does not create symlinks into caches. The CLI registers the skills for all supported agents in ~/.agents/.skill-lock.json, but only the agents passed with --agent receive the files. Pass --agent opencode only — do not add --agent pi, or you create a duplicate ~/.pi/agent/skills copy that collides with (and shadows) the global one.

Engineering skills — these read and write the repo's issue tracker and domain docs. Run setup-matt-pocock-skills in each repo before you use them:

Skill Purpose
setup-matt-pocock-skills Configures the issue tracker, triage labels, and domain doc layout for a repo
triage Moves issues and external PRs through the triage roles
to-spec Turns the conversation into a spec on the issue tracker
to-tickets Breaks a plan or spec into tracer-bullet tickets
wayfinder Plans huge work as a map of decision tickets
implement Implements work from a spec or tickets
tdd Test-driven development (red-green-refactor)
code-review Reviews changes against the repo's standards and spec
codebase-design Shared vocabulary for deep-module design
diagnosing-bugs Diagnosis loop for hard bugs and regressions
research Investigates questions against primary sources
prototype Builds a throwaway prototype to answer a design question
improve-codebase-architecture Scans for deepening opportunities, presents an HTML report
domain-modeling Builds the domain model (CONTEXT.md, ADRs)
resolving-merge-conflicts Resolves in-progress merge and rebase conflicts
migrate-to-shoehorn Migrates as assertions to @total-typescript/shoehorn
setup-ts-deep-modules Wires dependency-cruiser for deep-module TypeScript packages
setup-pre-commit Sets up Husky and lint-staged pre-commit hooks
scaffold-exercises Creates exercise directory structures

Interview and thinking skills:

Skill Purpose
grill-me / grilling / grill-with-docs Relentless interviews to sharpen plans and designs
loop-me Grills specs for workflows in the workspace
wait-what Re-pitches a message that did not land
to-questionnaire Turns a decision into a questionnaire
teach Teaches the user a skill or concept
ask-matt Routes to the right skill or flow
handoff / claude-handoff Hands the conversation to a fresh agent
wizard Generates an interactive bash wizard for human-only steps

Writing and git-safety skills:

Skill Purpose
writing-for-agents Writes documents for agents (skills, AGENTS.md, CLAUDE.md)
writing-beats / writing-fragments / writing-shape Writing workflow: fragments, then shape, then beats
git-guardrails-claude-code Blocks destructive git commands with Claude Code hooks

Update all mattpocock skills with bunx skills update --global.

The asd-ste100 skill is required: the agent rules in APPEND_SYSTEM.md (see above) tell pi to follow it for all documentation.

ship-quality is different — it ships inside this repo at dot-pi/dot-pi/agent/skills/ship-quality/ and stows into ~/.pi/agent/skills/ alongside the gh-managed skills (it has no gh metadata, so gh skill list / gh skill update ignore it — update it via git). The APPEND_SYSTEM.md rules tell pi to load it at session start.

Notes:

  • --agent is case-sensitive: use lowercase opencode.
  • typst-author needs --pin main: the repo's only release tag v0.0.1 predates its skills/ directory, so the default install finds nothing.
  • Security: gh warns that skills may contain prompt injections or malicious scripts. Review SKILL.md contents (and any scripts) after installing or updating.
  • To update installed skills: gh skill update --all.
  • User-scope skills install to the shared ~/.agents/skills/ directory here — do not add them to the dot-pi stow package.

Project skills loading

Rule for every agent and every project session:

  1. Identify the stack. Before touching code, look at the codebase and its architecture (language, framework, tooling — typst, go, rust, cloudflare, etc.) and determine which skills apply.

  2. Load the matching skills. Load every relevant installed skill into context before working. Do not work in a project whose stack skills you have not loaded.

  3. If a matching skill is missing, install it globally first. Do not continue until the install succeeds:

    # via the GitHub CLI (install into the global ~/.agents/skills/, read by pi + opencode)
gh skill install --agent opencode --scope user <owner>/<repo> <skill>

# via the skills CLI
bunx skills add <https://github.com/owner/repo> --skill <skill> --agent opencode --global --copy --yes

  4. Star threshold. Only install skills from repositories with at least 1,000 GitHub stars. Check the star count first with gh repo view <owner>/<repo> --json stargazerCount and skip the repo if it does not meet the threshold. (Exception: this repo's own in-house skills, which ship via dot-pi.)

  5. Prefer this repo's pinned skills (typst-author, latex-to-typst, typst-paper, asd-ste100, the mattpocock engineering skills, and the rust-skills family) when they cover the stack — do not install duplicates.

Rationale: loading the right domain skills up front measurably improves output quality on every task, and the global install makes the skill available to every future session in that stack without re-installing per project.

Notes

  • lastChangelogVersion is stripped from the tracked settings.json — it's ephemeral state that pi rewrites on startup, which would otherwise dirty the repo after every pi update.
  • If the symlink is ever replaced by a real file (e.g. you run pi before stowing on a fresh machine), re-stow or diff the files: pi writes through the symlink, so edits in ~/.pi/agent/settings.json are edits in this repo.
  • The ship-quality skill is an opt-in, risk-scaled quality-gate workflow (spec approval → plan approval → implementation with proof → independent review → user ship approval → lessons) that keeps the developer in the loop, with a user override at any point. APPEND_SYSTEM.md does not load it automatically — ask for it (for example, "use ship-quality") when you want the gates. See its SKILL.md for the full protocol.

Fresh install checklist

# 1. install pi + opencode (see their docs), then stow the pi package
cd ~/.dotfiles && stow -t ~ --dotfiles dot-pi

# 2. install the pinned packages listed in settings.json
pi update --all

# 3. log in to your provider (writes ~/.pi/agent/auth.json, not tracked)
pi /login

# 4. user-scope skills (see "Skills" section above)
gh skill install --agent opencode --scope user brycewang-stanford/Auto-Empirical-Research-Skills latex-to-typst
gh skill install --agent opencode --scope user brycewang-stanford/Auto-Empirical-Research-Skills typst-paper
gh skill install --agent opencode --scope user --pin main jihe520/MathModelAgent typst-author
gh skill install --agent opencode --scope user nithitsuki/asd-ste100-skill asd-ste100
bunx skills add https://github.com/anthropics/skills --skill skill-creator --agent opencode --global --copy --yes
bunx skills add https://github.com/mattpocock/skills --skill '*' --agent opencode --global --copy --yes