Skip to content
AI Developer Toolkit

Plan: capture intent.md

Intent capture turns an idea, ticket, or production finding into a committed intent.md that a product owner can accept or reject. The originator describes the problem and desired outcome in plain language; the agent structures it, surfaces unknowns, and stops before solution design or implementation.

Ideas stop waiting for someone to write them up. Intent is captured once, in the originator’s own words, as a version-controlled artifact.

Traditional: An idea passes through backlog entries, user stories, story points, and refinement meetings before anyone can act on it. Ownership transfers at each handoff, so what reaches engineering is several steps removed from what the originator meant.

AI-native: The originator brainstorms with the agent and writes the result down as intent.md. The file contains what is wanted, why, and under which constraints. Repeat processes are encoded as skills.

Before you begin

Section titled “Before you begin”
  • Access to Claude (claude.ai or Cowork), Cursor, or ChatGPT / Codex for people who are not engineers
  • An agreed intent.md template (see the artifact chain)
  • A shared, version-controlled home for intent that the product owner watches

Setting up the home is a one-time task for the platform or engineering team. Contributors without git experience do not need to use git directly: a GitHub connector lets the agent commit markdown on their behalf.

Prerequisites: none. This is a starting play.

Capture intent

Section titled “Capture intent”

  1. Describe the problem in your own words.

    Say what you cannot do today, who is affected, what better looks like, or what is out of scope. No formal language is required.

  2. Brainstorm until the idea is concrete.

    Ask the agent the questions an analyst would ask: scope, users, constraints, and what success looks like.

  3. Ask the agent to write intent.md using your organization’s template.

    Encode the template as a skill so every originator gets the same shape: problem, proposed outcome, affected users and systems, constraints, and open questions.

  4. Correct anything the agent misunderstood.

    The originator owns this pass. The product owner has not accepted the file yet.

  5. Commit intent.md to the shared home.

    Author and timestamp join the record. The product owner picks the idea up from there.

Non-engineers can do this from claude.ai or Cowork with a GitHub connector. Engineers can do it in the repo:

I have an idea for FEATURE. Interview me about the problem, who is
affected, what better looks like, and what is out of scope. Then write
intent/FEATURE.md using our intent template. Do not write any code.

Replace FEATURE with a short slug.

Governance

Section titled “Governance”

The evidence is the committed intent.md: author, timestamp, and full revision history in git. The product owner approves. The accept or reject decision that sends the intent into Design is recorded as the merge or the closing review.

Verify

Section titled “Verify”
  • A committed intent.md exists with author and timestamp.
  • The originator has corrected the agent’s first draft.
  • The product owner can find the file without a Slack ping.

Leading indicator: time from first conversation to a committed intent.md (git history). Expect hours, not a multi-week elicitation cycle.

Lagging indicator: the share of intent.md files the product owner accepts into Design rather than closes, plus how often intent.md still changes after the first spec.md commit for the same change.

Apply the play in your tool

Section titled “Apply the play in your tool”
Claude Code adapter Use an interactive repository session, then keep implementation behind Plan mode.
Cursor adapter Use Ask mode for discovery and Agent mode only to save the accepted artifact.
Codex adapter Use /plan or app chat for discovery and preserve the accepted file in Git.

Move accepted intent into design

Section titled “Move accepted intent into design”

After the product owner accepts the file, continue with Design.

Written by

See what's new on the platform.

Privacy Policy Terms of Service Cookie settings