Draft your first intent in your repo, no account required

The first spec most teams hand an agent is the prompt itself, composed in the chat box and gone when the session ends. Three weeks later nobody can say what the feature was supposed to do, only what it does. The fix doesn't need a platform: your first intent is a markdown file in your repo, drafted in conversation, preflighted before you trust it, and committed next to the code it governs. No Pathmode account is required for local drafting.

The input

A repo and a rough idea of what you're about to build. No intent.md yet, no workspace, no API key. The conversation you were going to have with the agent anyway is the raw material.

The flow

1. Install once, keyless. In Claude Code: /plugin marketplace add pathmodeio/claude-plugin, then /plugin install pathmode@pathmode. For another MCP client, configure npx @pathmode/mcp-server as its server command using the setup reference. Running the command in a terminal alone does not connect it to your editor. With no configured API key, the Pathmode MCP server makes no network requests. Your coding agent may still send context to its own model provider. Use --local to force local mode if a key is already configured.

2. Describe what you're building. Ask your agent to draft the intent from your request and the repository. In clients that support MCP prompts, compile-intent guides this conversation: the agent drafts a spec from what you said and what the repo shows, and every field it inferred rather than heard is labeled an assumption. You correct a draft instead of composing from zero.

3. Save and preflight the draft. Use intent_save with localDraft: true to preserve the draft and its open product choices before implementation. Then check_intent_readiness scores it against six calibrated gates: title, objective, outcomes, constraints, edge cases, verification. Deterministic, no model call. The same draft always gets the same verdict, and a failing one names the exact blockers.

4. Resolve the choices and blockers. Answer each product choice explicitly; answer_product_choice records your words in local mode as an unverified answer. For other readiness blockers, the agent asks a targeted question and proposes an answer for you to review. The implementation workflow stops on unresolved blockers. You can explicitly accept a named risk and ask to proceed; record that decision and keep the failing verdict visible. Accepting risk does not turn the gate green.

5. Save it where the code lives. intent_save writes intent.md to your project root with the current verdict stamped in its frontmatter. It diffs in review and travels with the branch. Need agent-native formats too? intent_export emits CLAUDE.md, AGENTS.md, or .cursorrules from the same spec.

The output

• An intent.md in your repo root: versioned with the code, reviewed like code, readable by any agent
• Assumptions labeled as assumptions, so inferred intent never masquerades as confirmed intent
• A readiness verdict in the file's frontmatter, so the spec carries its own state
• No Pathmode account required for local work. When you need a shared review, adopt the file into a workspace using the steps below. The repository file remains the authority for implementation.

Connect the existing file when your team needs review

If you answered product choices locally, ask the agent to take those answers back with answer_product_choice before adoption, so the team can review the open choices. Adoption refuses locally answered choices; their unverified answers do not become team approval.

1. Open repository setup, sign in, and select the intended workspace and Product.
2. Copy the one-time adoption command the page provides: npx @pathmode/mcp-server@latest adopt pm_adopt_....
3. Run the actual command from the repository root containing your saved intent.md. The placeholder above is not a working code. If your code expires, obtain a fresh one from setup.
4. Follow the connection instructions for your client and restart it if required. Ask the agent to read the repository intent and connected review state.

Adoption uploads the spec and records its workspace identity without replacing the decision in the file. The non-secret repository binding lives in .pathmode/config.json; credentials are stored separately under ~/.pathmode/workspaces/.

setup pm_live_... configures supported clients and credentials. It does not upload and adopt your existing intent. Once connected, ask the agent to attach the original request so the product manager can review and correct the proposal before authorizing implementation.

What preflight adds to a handwritten spec

You can write intent.md yourself and run the same preflight. Drafting with an agent helps expose assumptions; the deterministic checks identify structural gaps. Neither the generated draft nor a passing verdict proves the product decision is right.

Try it yourself

1. /plugin marketplace add pathmodeio/claude-plugin then /plugin install pathmode@pathmode in Claude Code, or configure the Pathmode MCP server in your client
2. Say what you're about to build and ask for a first intent
3. Save the draft, answer each product choice explicitly, and resolve the named readiness blockers
4. Commit intent.md with your next PR

Related

• Run a deterministic preflight before your agent starts building
• Hand the authorized proposal to your coding agent
• Playbook: Your First Spec in 10 Minutes