# App Brief

One-page brief (docs/BRIEF.md) for a new macOS app, written before any code.

- Repository: https://github.com/daveebbelaar/bama (1284 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add daveebbelaar/bama --skill app-brief -g -a claude-code -y`
Codex: `npx skills add daveebbelaar/bama --skill app-brief -g -a codex -y`
Cursor: `npx skills add daveebbelaar/bama --skill app-brief -g -a cursor -y`
Gemini CLI: `npx skills add daveebbelaar/bama --skill app-brief -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add daveebbelaar/bama`

## Description

One-page brief (docs/BRIEF.md) for a new macOS app, written before any code. Use when the user has an app idea, wants to replace an app they pay for, or the research and clone skills are done.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# App brief

Write `docs/BRIEF.md` in a folder named after the app
(`<parent>/<AppName>/docs/BRIEF.md`; ask for the parent folder, default
`~/Developer`). Every later skill reads it. Keep it to one page.

## 1. Name and read what exists

Pick the name first: one UpperCamelCase word (`Tasks`, `DailyLog`), not the
name of an app already in `~/Applications`, and a bundle id
`com.<yourname>.<appname>` in lowercase. The folder, the research, and the
scaffold all use it.

If `docs/research/` or `docs/screens/INDEX.md` exist, read them first.
Skip every question they already answer.

If the user gives you a spec from BAMA's `specs/` folder (a file or a
link), it already holds the brief and the stories. Copy its **Brief** block
to `docs/BRIEF.md` and its **Stories** block to `docs/STORIES.md`. Keep the
rest of the spec as `docs/SPEC.md`, so later skills read its **How it
works** and **Gotchas**. Ask only what the user wants to change, then call
the Skill tool with `new-mac-app`.

## 2. Interview

Ask a few questions at a time. If the user asked you to decide everything,
answer each question yourself from the research, write the choice in the
brief, and note "decided by the agent" next to it.

1. What do you do today, and which app or habit does it replace?
2. What are the three things you do most often? These become the main pages.
3. What data does it hold? Name the nouns: tasks, notes, recipes, invoices.
4. Is there a reference app you like? Then the `clone` skill comes next.
5. Where does it live: a window with a sidebar, a menu bar item, a
   quick-capture panel with a global shortcut, or a mix?
6. Does it need the internet? Default: no.
7. Which three things are out of scope for version one?
8. Should it look like a built-in Mac app, or have its own look? Note a
   brand or accent color, and any app they name ("like Things"): the
   `design-from-app` skill rebuilds its look. No answer means native with
   the Mac's own accent color.

## 3. Cut scope

The rest: https://github.com/daveebbelaar/bama/blob/HEAD/skills/start/app-brief/SKILL.md