Introduction
STABLY-CREATE.md is a markdown file you place in your project root to give the Stably AI agent test-generation-specific instructions. Rules defined here apply only to create and build modes — they are loaded when you run stably create or stably build.
Think of it as the test-generation counterpart to STABLY.md. Where STABLY.md provides general project rules across all modes, STABLY-CREATE.md focuses exclusively on how tests should be written.
If you need rules that apply across all agent modes (create, fix, build, init), use STABLY.md instead.
Quick Start
Create the file
Add a STABLY-CREATE.md file to your project root:# Test Generation Rules
- Always use `data-testid` attributes for element selectors
- Follow the Page Object Model pattern
- Include both positive and negative test cases for form validations
- Use `test.describe` blocks to group related scenarios
Run a test generation command
The rules are automatically loaded and applied:stably create "test the checkout flow"
stably build
✓ STABLY-CREATE.md loaded (320 chars)
File Location and Naming
| Requirement | Details |
|---|
| Location | Project root directory (same level as package.json) |
| Filename | Must be uppercase STABLY-CREATE.md |
| Source control | Should be committed to git |
The filename must be uppercase STABLY-CREATE.md. macOS is case-insensitive, so stably-create.md will work locally — but Linux (used in CI/ECS) is case-sensitive and will silently ignore the wrong case.
Commit STABLY-CREATE.md to your repository so your entire team shares the same test generation conventions. This is especially important when stably create runs in CI pipelines or is invoked by background agents.
STABLY-CREATE.md uses freeform markdown. There’s no required structure — write whatever test generation instructions you want the agent to follow. The content is appended directly to the agent’s system prompt as a ## Custom Test Generation Rules section.
Maximum length: 10,000 characters (~2,500 tokens). Files exceeding this limit are automatically truncated with a CLI warning.
When to Use
Use STABLY-CREATE.md for rules that are specific to test generation, such as:
- Test file naming conventions and folder structure
- Test patterns and frameworks (Page Object Model, fixtures, etc.)
- Assertion strategies and test data patterns
- Tags and annotations (
@smoke, @regression)
- Which Stably SDK methods to prefer (
agent.act(), toMatchScreenshotPrompt(), etc.)
For project-wide rules (app context, selector strategy, general do’s and don’ts), use STABLY.md instead.
Example
Here’s a real-world example for a Next.js app:
# Test Generation Rules
## File Structure
- Place all tests in the `tests/` directory
- Name test files using the pattern `<feature>.spec.ts`
- Group related tests with `test.describe` blocks
## Test Patterns
- Use the Page Object Model — put locators in `tests/pages/` directory
- Always use `data-testid` attributes for element selectors
- Fall back to `getByRole` when test IDs aren't available
- Never use CSS class selectors
## Assertions
- Include both positive and negative test cases for form validations
- Use `toMatchScreenshotPrompt()` for visual assertions instead of pixel comparisons
- Use `agent.act()` for complex multi-step UI interactions (e.g., drag-and-drop)
## Test Data
- Create fresh test data in each test — never modify shared records
- Use environment variables for credentials (never hard-code)
- Clean up test data in `afterEach` hooks
## Tags
- Add `@smoke` annotation to critical-path tests
- Add `@regression` annotation to edge-case tests
How It Works
When you run stably create or stably build, the CLI searches upward from your current directory to find STABLY-CREATE.md. This means you can run commands from a subdirectory and it will still find the file at your project root.
The content is appended to the agent’s system prompt as a ## Custom Test Generation Rules section, giving the agent context on your team’s test generation preferences.
STABLY-CREATE.md is not loaded for other modes like fix or init. If you need rules that apply everywhere, use STABLY.md.
Relationship to Other Config Files
Stably has three mechanisms for customizing agent behavior. Each serves a different purpose:
| File | Scope | Modes | Description |
|---|
STABLY.md | Project-wide rules | All modes (create, fix, build, init) | General instructions — project context, selector strategy, do’s and don’ts |
STABLY-CREATE.md | Test generation rules | create and build only | Test-specific conventions — file naming, folder structure, test patterns |
stably.yaml → agent.fix.rules | Fix agent rules | fix | Structured config for the fix agent (max turns, parallel workers, rules) |
[Base System Prompt]
→ stably.yaml agent.fix.rules
→ STABLY-CREATE.md (create/build modes only)
→ STABLY.md (all modes)
Don’t duplicate rules across files. Put general project rules in STABLY.md and test-generation-specific conventions (like file naming patterns or test structure) in STABLY-CREATE.md.
Best Practices
| Do | Avoid |
|---|
Commit STABLY-CREATE.md to source control so CI and teammates share the same test conventions. | Adding STABLY-CREATE.md to .gitignore — CI agents won’t find it. |
| Keep rules focused on test generation concerns (file structure, patterns, assertions). | Putting general project context here — use STABLY.md for that. |
| Use concise, actionable rules the agent can follow. | Writing novel-length instructions that exceed the 10,000 character limit. |
Use the uppercase filename STABLY-CREATE.md. | Using lowercase stably-create.md — it will fail silently on Linux CI servers. |
| Review changes in PRs like any other config file. | Duplicating rules that already exist in STABLY.md or stably.yaml. |
