workflow-server AGENTS.md

AGENTS.md

Instructions for AI coding agents working in this repository (Workflow Orchestration MCP Server).

Project overview

This repo is an MCP server for AI agent workflow orchestration (TypeScript, Node.js 18+). Agents discover, navigate, and execute structured workflows via a Goal → Workflow → Activities → Techniques → Tools model. Workflow data lives in a workflows worktree (orphan branch); engineering artifacts live in .engineering/. See README.md for overview and docs/ide-setup.md for rule setup.

Setup commands

• Install: npm install
• Build: npm run build
• Run (stdio, default): npm start or npm run dev
• Run (HTTP): npm run start:http or npm run dev:http
• Tests: npm test (watch) / npm run test:ci (single run)
• Typecheck: npm run typecheck
• Guards: npm run check:all (every guard, one table) / npm run check:delta (only what your change added, against the merge-base)
• Worktree setup: npm run worktree:provision — checks out the submodules and makes node_modules resolvable, so guards and tests measure the worktree you are editing
• A worktree is named for the branch it holds. .worktrees/workflow/353-context-scoped-delivery holds workflow/353-context-scoped-delivery — the branch name in full, slashes and all, as nested directories. git worktree list then reads as a branch index, and a path in a command or a stack trace says which branch it belongs to without anyone inspecting its HEAD. Rename with git worktree move, which fixes the administrative files a mv leaves dangling.
• Workflow data: git worktree add ./workflows workflows (see README.md, setup.md, stdio.md, http.md).

Code and doc style

• TypeScript; follow existing patterns in src/ and schemas/.
• Use clear, professional language; no process attribution in code comments (e.g. “Added by agent”).
• Describe the design, not the change to it. Definitions (workflow, activity, technique, resource prose), code comments, doc comments, and commit subjects state the system as it is, in the present tense, without naming the design they replaced. A reader next year has no memory of the previous design, so naming it makes them learn a dead design just to parse the sentence — and the sentence rots the moment the thing it contrasts against is gone. Write account for token usage per dispatch, not move usage accounting off the transition and onto the dispatch; write cost travels on its own call, not a transition can only account for a dispatch it exits. Same for a value's absence: say what holds when it is missing, not what the old path did. Cut “instead of”, “no longer”, “previously”, “unchanged behaviour”, and any example that was true before the change and false after it. The workflow canon states the same discipline for definition prose as Document in Positive Present.
  • Keep a hazard that is still live, stated as an invariant. A marker is unreadable to a context that never received the bytes survives; this is why the old rule forbade it does not.
  • PR and issue bodies are the exception, and so is a commit body. They exist to explain a change against what preceded it, and stop being read once merged — a reviewer needs the before-state to judge the change. Keep the narrative there and out of everything that persists. A measurement that is a tool's reason to exist may likewise be cited with its provenance.
  • After a behaviour change, sweep for surviving descriptions of the old behaviour: doc comments, tool descriptions, technique ## Rules, resource prose, READMEs. A grep for the old phrasing finds most of them; a stale claim reads as current fact.
• Prefer removing the thing that needs a prohibition. When a change leaves prose warning "do not also use X", that usually means two paths now do one job. Retire one and the warning has nothing left to say — along with any validation or edge-case handling that existed only to police the overlap.
• Keep CLAUDE.md and AGENTS.md in sync by merging, never by copying. They have diverged before, each gaining content the other lacked; overwriting one with the other silently drops the difference.