Markdown project brief template: set scope before work

A project brief fixes the boundaries of one piece of work before anyone starts it. It describes the problem, the intended outcome, the work included, the work excluded, the constraints, the owner and the conditions for accepting the finished work.

Give the agreement a separate .md file. A person can read it before taking the job, or you can give it to a coding agent before it plans changes. For an introduction to the file ending, read the .md format guide.

What the brief settles before work starts

A request such as "add a search field" leaves room for different jobs. Does it search titles or full text? Does it need an account? Who decides whether the work is finished? The brief gives those questions a place to be answered before someone builds the wrong thing.

Keep the brief focused on the agreement about the work. Detailed implementation steps can come later. Acceptance criteria describe what the finished work does, rather than a sequence of tasks to complete along the way.

The project brief template

Save the following block as a new project-brief.md. Replace every instruction with details for one project before handing it over.

# Project brief: name the work

## Problem

Describe the current difficulty and who experiences it.

## Intended outcome

Describe what will be different when this project is finished.

## Work in scope

- Name a deliverable included in this project.

## Work out of scope

- Name a nearby request excluded from this project.

## Constraints

- State a limit on time, access, tools or changes to existing behavior.

## Owner

Name the person who resolves questions and accepts the finished work.

## Acceptance criteria

- Describe an observable condition that the finished work satisfies.
- Describe another condition, including any behavior that needs to stay unchanged.

Each part prevents a different failure:

• Problem: describes the difficulty before naming a solution. Without it, someone can build the requested feature while leaving the original difficulty untouched.
• Intended outcome: describes the desired end state. It gives the person doing the work a reason to question an approach that doesn't serve that end state.
• Work in scope: names the deliverables the owner expects. An unnamed deliverable can become a surprise at acceptance time.
• Work out of scope: names tempting additions that aren't part of this job. An explicit exclusion gives the owner a basis for stopping work from spreading.
• Constraints: states limits before someone chooses an approach. A time limit, restricted access or a requirement to preserve existing behavior can rule out an otherwise plausible solution.
• Owner: names one person who can resolve gaps and accept the work. Without that person, conflicting requests can leave the worker choosing whose direction to follow.
• Acceptance criteria: gives observable conditions for judging the finished work. "Easy to use" leaves the judgment open; "an empty search shows all titles" names behavior someone can try.

Give each heading some breathing room: an empty line before the text below it. Separate paragraphs too; paragraph spacing in Markdown explains the effect when the file is rendered.

A filled brief for Doe Holdings

This invented job adds title search to a local project page. Jane Doe owns the request at the fictional Doe Holdings. Neither the page nor its requirements come from an actual job.

# Project brief: filter project titles

## Problem

Jane Doe reads a local page listing 40 project titles. Finding a title requires scanning the whole list.

## Intended outcome

Jane Doe can narrow the visible titles by typing part of a title on that page.

## Work in scope

- Add one search field above the existing title list.
- Filter the visible titles as text is entered.
- Show a short explanation when no titles match.

## Work out of scope

- Searching project descriptions or files.
- Adding accounts or saving searches.
- Changing the order of the titles.

## Constraints

- Keep the existing page layout apart from the search field and no-match explanation.
- Use the existing title data; do not change the stored titles.
- Finish within two working days after Jane Doe approves this brief.

## Owner

Jane Doe resolves scope questions and accepts the finished work for Doe Holdings.

## Acceptance criteria

- With an empty search field, all 40 titles appear in their existing order.
- Typing part of a title shows only titles containing that text, ignoring letter case.
- A search matching no titles shows "No matching titles" in place of the list.
- Clearing the field restores all 40 titles.
- The search field can be reached and used with a keyboard.
- Searching leaves the stored title data unchanged.

The outcome concerns finding a title; the scope chooses a title filter to serve it. Full-text search stays outside the job. The criteria cover an empty field, a match, no matches, clearing the field, keyboard use and preservation of the stored data.

That last condition matters even though the visible change is small. A filter should change what appears on the page without changing the titles it reads. The brief makes that boundary explicit before implementation.

Read the brief with the person doing the work

Before work begins, have the worker describe the included work and exclusions back to the owner. A disagreement at this point is a gap to resolve in the file, rather than a detail to leave until acceptance.

For a coding agent, provide the file path and ask it to raise missing requirements before changing code. The person named as owner decides scope questions. The agent works from that agreement outside the reader used to open the brief.

When a new request arrives, compare it with Work in scope and Work out of scope. If the owner accepts the addition, revise the intended outcome, limits and acceptance criteria wherever the addition affects them. Resolve the change before the worker takes on the extra work.

Naming and keeping the brief file

Use one brief file per project. For the sample, projects/title-filter/project-brief.md keeps the agreement beside the files for that work. In a shared folder holding several briefs, title-filter-brief.md names the job without requiring someone to open it.

Choose a lasting name using these Markdown naming conventions. Keep that name when other files refer to it. If the scope changes, revise the existing brief rather than leaving competing copies with names such as brief-final-new.md.

Keep completed briefs with their project files. They preserve what the owner accepted, while each new project starts with its own file and its own boundaries.

Where Sashmark fits

Your project brief can share a folder with Markdown written by a coding agent. Reading and editing those files on a desktop is the intended job of Sashmark, an app in development for people working with Markdown from AI agents. You write the brief and settle its scope; the app's role is to let you read and edit that writing.