> ## Documentation Index
> Fetch the complete documentation index at: https://yellowhammer.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepare your specification

> Make product intent and completion criteria clear enough for a Night.

Give Yellowhammer a local specification source that explains the product's intended behavior and supplies traceable completion criteria. The author Act reads it when selecting Features and drafting Work Cards.

## Choose the Spec Source

In Add Project, open **Spec Source** and choose one option:

* **A shared spec folder:** select an existing shared source or choose **Choose Another Folder…**. This is a specification checkout outside the Project; several Projects can read it. It has no Repo Role, Check, or Worktree of its own.
* **A Repo in this Project:** select a declared repository, or choose **Add the Spec as a Repo…**. The selected repository has the Repo Role `spec` and belongs to this Project only.

Keep the local source available to the account running Nights. Review the selected source in the Project's Settings before execution.

## Describe bounded outcomes

Write the user-visible outcome, boundaries, constraints, and acceptance criteria in the source. Identify which repositories already provide any contracts the work relies on. Across repositories, a Work Card must be completable against what the other repositories already provide. Work that changes both ends of a declared Repo Dependency needs separate Features, with the producer first.

Within one repository, a Feature can have a sequence of Work Cards. Those Cards share a Worktree and Feature Branch, and each builds on the preceding Card's committed work.

## Make completion verifiable

Give each requirement a stable identifier and observable acceptance criteria. Authored Definition of Done clauses carry a citation to a story ID such as `<epic>/<story>` or a goal ID. Keep those references meaningful when editing the specification. A vague statement such as “checkout is better” does not explain what a reviewer should verify.

### Acme Checkout example

For an illustrative Acme Checkout requirement, use a story ID such as `checkout/show-order-total`. State what the customer sees before confirming an order, which currency and rounding rules apply, and what happens when a cart is empty. Separate those requirements from implementation suggestions. These are example requirements, not behavior Yellowhammer supplies to your product.

## Confirm it worked

The configured Spec Source points to the intended checkout. Your requirements describe bounded outcomes with stable references and observable criteria. After authoring, inspect the Feature and its Work Cards in Linear to check their Definition of Done and citations against the source.

## Common problems

* **The author cannot identify bounded work:** narrow the outcome and spell out the existing contracts and constraints.
* **Completion cannot be observed:** replace subjective wording with a behavior or check a reviewer can assess.
* **A citation is stale:** update the source and relevant planning records rather than treating a missing reference as evidence of completion.

## Next steps

[Run Nights](https://yellowhammer.dev/docs/run/overview.md) · [Verification and Definition of Done](https://yellowhammer.dev/docs/concepts/verification-and-definition-of-done.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.