> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factory.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Specification Mode
> Turn plain-English specifications into production-ready code with automatic planning and review.
Specification Mode transforms simple feature descriptions into working code with automatic planning and safety checks. You provide a brief description of what you want, and droid creates a detailed specification and implementation plan before making any changes.
Just 4-6 sentences describing what you want built
Droid creates detailed specs and implementation plans
No code changes until you approve the complete plan
Built-in security, compliance, and team standards
## How it works
Provide a simple description in 4-6 sentences. No need to write formal
specifications.
Droid analyzes your request and generates a complete specification with
acceptance criteria, implementation plan, and technical details. You can optionally use [mixed models](/cli/configuration/mixed-models) to configure a different model for planning.
You review the generated specification and implementation plan. Request
changes or approve as-is.
Only after approval does droid begin making actual code changes, showing
each modification for review.
## Example workflow
**Your input:**
```
Add a feature for users to export their personal data.
It should create a ZIP file with their profile, posts, and uploaded files.
Send them an email when it's ready. Make sure it follows GDPR requirements.
The export should work for accounts up to 2GB of data.
```
**Droid generates:**
* Complete specification with detailed acceptance criteria
* Technical implementation plan covering backend, frontend, and email
* File-by-file breakdown of changes needed
* Testing strategy and verification steps
* Security and compliance considerations
**You approve, then droid implements** the complete solution while showing each change for review.
Specification Mode must be manually activated using **Shift+Tab** in the CLI.
It does not automatically activate.
## How to activate Specification Mode
To enter Specification Mode, press **Shift+Tab** while in the CLI. This will enable the specification planning workflow for your next request.
## What happens during planning
**Analysis phase (read-only):**
* Examines your existing codebase and patterns
* Reviews related files and dependencies
* Studies your AGENTS.md conventions
* Gathers context from external sources
**Planning phase:**
* Develops comprehensive implementation strategy
* Identifies all files that need changes
* Plans sequence of modifications
* Considers testing and verification steps
**Safety guarantees:**
* Cannot edit files during analysis
* Cannot run commands that modify anything
* Cannot create, delete, or move files
* All exploration is read-only until you approve
## Writing effective requests
**Focus on outcomes:** Describe what the software should accomplish, not how to build it.
```
Users need to be able to reset their passwords using email verification.
The reset link should expire after 24 hours for security.
Include rate limiting to prevent abuse.
```
**Include important constraints:**
```
Add user data export functionality that works for accounts up to 5GB.
Must comply with GDPR and include audit logging.
Should complete within 10 minutes and not impact application performance.
```
**Reference existing patterns:**
```
Add a notification system similar to how we handle email confirmations.
Use the same background job pattern as our existing report generation.
Follow the authentication patterns we use for other sensitive operations.
```
**Be specific about verification:** Tell droid how to confirm the implementation works correctly.
**Consider the full user journey:** Describe the complete experience, not just technical requirements.
**Include error scenarios:** Specify how failures should be handled and communicated to users.
**Think about scale:** Mention performance requirements and expected usage patterns.
## Enterprise integration
Reference external requirements by pasting links:
```
Implement the user management features described in this Jira ticket:
https://company.atlassian.net/browse/PROJ-123
Follow our security standards and include comprehensive error handling.
```
If you've integrated platforms through Factory's dashboard, droid can read context from tickets, documents, and specs during analysis.
## Benefits
No accidental changes during exploration. See the complete plan before any
modifications.
Comprehensive analysis leads to better architecture decisions and fewer
surprises.
Complete visibility into what will be done before any code changes happen.
Well-planned implementations are more likely to be correct, complete, and
maintainable.
## AGENTS.md integration
Document your project conventions to enhance Specification Mode's planning. See [AGENTS.md](/cli/configuration/agents-md) for more information.
Specification Mode automatically incorporates these conventions, ensuring consistency with your team's standards.
## Breaking down large features
For complex features spanning multiple components, break them into focused phases:
**Phase 1:**
```
Implement user data export backend API and job processing.
Focus only on the server-side functionality, not the UI yet.
```
**Phase 2:**
```
Add the frontend UI for data export using the API from Phase 1.
Include progress indicators and download management.
```
This approach allows you to validate each phase before proceeding to the next.
## Specification approval options
After droid presents the specification, choose how to continue:
1. **Proceed with implementation** – Approve the plan and keep normal (manual) execution controls.
2. **Proceed, and allow file edits and read-only commands (Low)** – Set Autonomy Level to Low so droid can edit files and run safe read-only commands automatically.
3. **Proceed, and allow reversible commands (Medium)** – Set Autonomy Level to Medium so droid can also run reversible commands without additional prompts.
4. **Proceed, and allow all commands (High)** – Set Autonomy Level to High for fully automated execution, including commands that are not easily reversible.
5. **No, keep iterating on spec** – Stay in Specification Mode to refine the plan before implementation.
Selecting any Autonomy Level option sets that level for the rest of the session. Choosing to keep iterating leaves Specification Mode active so you can continue shaping the plan.
## Saving your specifications as Markdown
Specification Mode can automatically write the approved plan to disk. Open the CLI settings and enable **Save spec as Markdown** to turn this on.
* By default, plans are saved to `.factory/docs` inside the nearest project-level `.factory` directory. If none exists, the CLI falls back to `~/.factory/docs` in your home directory.
* Use the **Spec save directory** setting to pick between the project directory, your home directory, or a custom path. Custom values support absolute paths, `~` expansion, `.factory/...` shortcuts, and relative paths from the current workspace.
* The CLI creates the target directory if it does not exist and writes the Markdown exactly as shown in the approval dialog.
* Files are named `YYYY-MM-DD-slug.md`, where the slug comes from the spec title or first heading, and a counter is appended if a file with the same name already exists.
## What happens after approval
Once you approve a specification plan, droid systematically implements the changes while showing each modification for review. You maintain full control through the approval workflow, ensuring quality and alignment with requirements.
For simpler changes that don't need comprehensive planning, droid can proceed directly while still showing all modifications for approval.
Ready to try Specification Mode? Start with a simple description of what you want to build, and let droid handle the specification and planning complexity.