An engineer pastes a Linear ticket into Cursor: "payment step is slow, fix it." Nine minutes later there is a retry loop, a clean diff, passing tests, a merge. Two days later support is on fire: the retry double-charges customers on timeout. That edge case existed. It lived in a Slack thread, not in the ticket.
The agent did not lack skill. It lacked the intent: the objective, the "no double-charge on retry" constraint, the verification that would have caught it. The fix is not a better prompt. It is wiring the agent to the layer that already holds that judgment, and making the agent stop when that layer says stop.
Agents inherit context, not judgment
Pasting a ticket gives the agent context: what is broken. It does not give judgment: what must not break, how you will know it worked, and whether anyone has agreed this is the thing to build. Three layers get conflated at the handoff:
- Pathmode is the Why. The intent: objective, evidence, constraints, verification, and the people who stand behind a revision.
- Your coding agent is the How. The code in the repo.
- Linear or Jira is the When. The ticket, the sprint, the status.
The MCP server is the wire between the Why and the How. Context isn't judgment; the wire hands the agent both, and it carries the gate.
Two ways in: keyless and connected
- Keyless. With no API key configured the server runs in local mode: it reads and writes an
intent.mdin your repo, runs the deterministic preflight, and makes no network request at all. Nine tools, no account. - Connected. A workspace API key adds 23 tools: evidence with its trust tier, the constitution, the dependency graph, PM change requests, human authorization of the exact revision, and a merge that grades the real diff.
The nine repo tools behave the same in both modes, so a team can start keyless and connect later without relearning anything. If you want to feel it first, start keyless.
Install and connect
In Claude Code, the plugin installs the server and the skill pack together:
/plugin marketplace add pathmodeio/claude-plugin
/plugin install pathmode@pathmodeNo key needed. When you do want a workspace, enter the key when the plugin prompts for configuration; it goes into your OS keychain, not into a config file. Ran npx @pathmode/mcp-server setup before? Remove that older pathmode entry from .mcp.json, since the plugin registers its own.
For Cursor, Windsurf, Claude Desktop, or Claude Code without the plugin, one command writes the MCP entry at each tool's real config path and stores the key outside the repo:
npx @pathmode/mcp-server@latest setup pm_live_...Or wire it by hand. This is a complete connected entry; drop env for keyless:
{
"mcpServers": {
"pathmode": {
"command": "npx",
"args": ["@pathmode/mcp-server"],
"env": { "PATHMODE_API_KEY": "pm_live_..." }
}
}
}--local exists only to force local mode when a key is configured. Already have a preflighted intent.md you want to connect? The repo onboarding door in Pathmode gives you a one-time npx @pathmode/mcp-server@latest adopt pm_adopt_... that uploads the spec and binds the repository to the workspace you chose. Restart your editor afterward so it picks up the server.
What the agent can now see
Thirty-two tools in connected mode, nine of them keyless. Do not memorize them; they group by the job they do. The per-argument reference lives at /developers.
| Job | Tools | Key |
|---|---|---|
| Read the repo intent | get_current_intent, get_intent, list_intents, search_intents | no |
| Gate it | check_intent_readiness, confirm_intent_dimension | no |
| Write the file | intent_save, intent_export, intent_import | no |
| Read the full context | get_agent_prompt, get_constitution, query_evidence, get_intent_evidence, get_intent_relations, analyze_intent_graph | yes |
| Handle PM judgment | list_intent_change_requests, get_intent_change_request, reject_intent_change_request, propose_spec_change | yes |
| Write back what building taught | record_implementation_finding, record_implementation_context, log_implementation_note, record_outcome_measurement | yes |
| Grade the work | verify_implementation; update_intent_status only for work that never goes through a PR | yes |
Two of these carry the workflow. check_intent_readiness is the agent's first move: it resolves the intent.md bound to the repository the client is working in, refuses to guess when it cannot identify the repository, and grades six gates with no model call. get_agent_prompt takes mode: draft (critique the spec) or mode: execute (implement it) and returns the 8-part IntentSpec with the constitution merged and the evidence grouped by trust tier. Before any instruction, it prints what decides whether the agent may proceed: the authorization state of this revision, open PM change requests, the agent's own unaccepted proposals, and the latest advisory pre-merge review for each open pull request.
For agents that read files instead of calling MCP, intent_export emits CLAUDE.md, AGENTS.md (OpenAI Codex and modern Cursor read it natively), .cursorrules, an outcome rubric, or OpenSpec from the repo's intent.md, with no key. export_context does the same for whole-workspace context in connected mode.
The skill pack
The plugin ships nine skills, a /preflight command, and a session hook. Skills auto-trigger from what you say; there is nothing to memorize. In rough lifecycle order:
| Skill | Use when |
|---|---|
setup-pathmode-workflow | First-time setup: test commands, issue tracker, status conventions |
compile-intent | Turning a rough ask into a structured spec, assumptions labeled |
preflight | A deterministic readiness verdict before an agent builds |
implement-intent | Building under an intent.md, only after preflight and any required authorization |
verify-intent | Designing the executable feedback loop for a spec |
grill-intent | Stress-testing a spec field by field before code is written |
split-intent-to-issues | Paste-ready Linear, Jira, or GitHub tickets from a spec |
review-against-intent | Checking a diff against the outcomes and constraints |
handoff-intent | Preserving decisions and discoveries at the end of a session |
The session hook adds one line to Claude's context when a repo has an intent.md: title, status, and how far the spec has drifted from the work. It reads the file and your git log locally and sends nothing anywhere.
The skills are the Claude Code layer. The server is the same for every MCP client. Not on the plugin? npx @pathmode/mcp-server install-skills copies the pack into .claude/skills/; if you later install the plugin, delete those copies, since the plugin's supersede them.
A real session, ticket to merged
The loop the opening incident was missing, using only shipped pieces:
- "Help me turn this payment ticket into a spec."
compile-intentdrafts from what you said and what the repo shows, and labels every field it inferred rather than heard as an assumption. grill-intentpressure-tests the weakest field and surfaces the question the ticket never asked: what happens on a timeout retry?verify-intentdesigns the feedback loop, fastest check through what must not regress, and writes it once into the spec's verification checks./preflightrunscheck_intent_readiness. Six gates, exact blockers named, one repair question at a time until the verdict flips. The same spec always gets the same verdict.intent_savewritesintent.mdwith the verdict in its frontmatter. Connected, the same save creates the intent in the workspace. It is agent-originated, so it is pending: a signed-in person authorizes that exact revision in Pathmode. The agent cannot do this; the authorization endpoint refuses API keys.get_agent_promptin execute mode returns the spec with Constraints and Constitution merged, so "no double-charge on retry" is in the prompt whether or not this author remembered it. If a PM has an open change request against this revision, it sits at the top: the agent applies it tointent.mdor rejects it with a reason, and stops again until the new revision is authorized.- The agent implements inside the authorized scope. When building shows the spec assumed something false,
record_implementation_findingflips the falsified check andpropose_spec_changerecords the exact correction for a person to accept. It keeps building against the authorized revision until they do. - It names the intent where the merge can find it, branch
intent/<id>orpathmode:<id>in the pull request body, and runsverify_implementationagainst the PR URL: Pathmode reads the diff from GitHub and grades every outcome, constraint, rule, and edge case with citations into the diff. An advisory review also runs as the PR opens and changes. - The merge grades the real diff, moves the intent to shipped, and records what the verdict rested on.
handoff-intentwrites one implementation note so the next session inherits the decisions and the discoveries.
That is the close-the-loop the pasted ticket never had.
Three judgments that do not substitute for each other
The implement-intent skill enforces the distinction, and it is worth knowing before you rely on it:
- Preflight asks whether the spec is concrete enough to build and verify. Deterministic, repeatable, gate-able in CI.
- Accepted risk records a human decision to proceed while a named gap remains. It is saved into the spec as a decision, and it never turns a failing gate green.
- Authorization confirms that a person permits this exact agent-originated revision to be implemented. It does not make a failing gate pass, and a passing gate does not grant it.
Any body edit is a new revision, including the decision that records accepted blockers, and authorization is asked for again. That is the feature: the person who authorized knows precisely what they authorized.
Why this is a wire, not a wrapper
Your agent stays your agent: Cursor's autocomplete, Claude Code's reasoning, untouched. Pathmode hands over judgment under evidence the agent can reason with and push back on, through findings and proposals a person adjudicates.
The anti-pattern is pasting a frozen spec and calling it done. That is how you get the double-charge. Wired, every session reads the spec as it stands, the constitution the team agreed on, the verification the team wrote, and whether anyone has authorized this version. Nothing is re-typed, and nothing is silently implemented.
For what the eight parts mean, read The Anatomy of an Agent-Ready Spec. For what happens when the build contradicts the spec, When the Build Contradicts the Spec.
Common questions
Do I need a Pathmode account? No. Keyless local mode is the default: intent.md, the preflight, and the exports work with nothing configured. A workspace key adds evidence, the constitution, PM change requests, human authorization, and a merge that grades the diff.
Which agents does this work with? Any MCP client: Claude Code, Cursor, Windsurf, Claude Desktop. Agents that read instruction files, OpenAI Codex and modern Cursor, get an AGENTS.md from intent_export. The skill pack is Claude Code's layer.
Does it change how my agent writes code? No. It changes what the agent knows before it writes, and when it stops.
Who decides the agent may build? In connected mode, a signed-in person, by authorizing the exact revision. A passing preflight is not that decision, and neither is accepting blockers. In keyless mode the decision is yours, in the conversation.
Who moves the intent to shipped? The merge, when the branch or PR body names the intent. An agent that marks it shipped by hand replaces a diff-backed verdict with an unverified one.
Is verify-intent a tool or a skill? A skill. It designs the five-dimension verification loop and writes it into the spec. Grading a finished implementation is a separate step: the verify_implementation tool.
Start keyless: install the plugin, run /preflight on an intent.md, and hand the passing spec to your agent. Connect a workspace when the team needs evidence, the constitution, and authorization in the agent's context.