AGENTS.md

1# Agent Guidance For `/work`
2 
3When working in this directory, use a product-facing lens first.
4 
5Start from how the work is experienced by users, not from the internal command
6or file structure. In this product there are two users:
7 
8- Humans: they usually do OpenSpec work by prompting agents. They may run shell
9  commands for interactive setup or one-off actions, but prompts are the normal
10  interface.
11- Agents: they need clear intent, discoverable state, unambiguous next actions,
12  and enough structured output to act safely.
13 
14Good human UX is usually good agent UX. A flow that is easy for a human to ask
15for and understand is usually easier for an agent to execute, verify, and
16explain.
17 
18For roadmap or slice exploration:
19 
20- Describe the user-facing flow before the internal implementation.
21- Ask what the human sees, asks for, approves, or corrects.
22- Ask what the agent must discover, decide, execute, and report back.
23- Ground reasoning in the current repo behavior before proposing new shape.
24- Treat shell commands as supporting mechanics, not the primary product story.
25- Prefer concrete workflows over abstract model language.
26 
27When an answer gets confusing, reframe it as:
28 
29```text
30What does the human want?
31What does the agent need to know?
32Where does the work live?
33What changes on disk?
34How does the user know it worked?
35```
36