# OpenSpec Manual Setup (Without CLI)

## Overview

You can use the OpenSpec workflow without installing the CLI. This guide shows how to set up and use OpenSpec manually.

## Initial Setup

### 1. Create Directory Structure

```bash
mkdir -p openspec/specs
mkdir -p openspec/changes
mkdir -p openspec/archive
```

### 2. Create Project Context File

Create `openspec/project.md`:

```markdown
# Project Context

## Overview
[Brief description of your project]

## Tech Stack
- Language: [e.g., TypeScript, Python]
- Framework: [e.g., React, Django]
- Database: [e.g., PostgreSQL, MongoDB]

## Conventions
- Code style: [e.g., ESLint, Black]
- Testing: [e.g., Jest, pytest]
- Naming: [e.g., camelCase for variables]

## Architecture
[High-level architecture notes]

## Guidelines
[Project-specific rules and patterns]
```

### 3. Create AGENTS.md Integration

Add to your project's `AGENTS.md` (or create it):

```markdown
# OpenSpec Workflow

This project uses OpenSpec for spec-driven development.

## Directory Structure

- `openspec/specs/` - Current specifications (source of truth)
- `openspec/changes/` - Proposed changes (work in progress)
- `openspec/archive/` - Completed changes
- `openspec/project.md` - Project context and conventions

## Workflow

### Creating a Change

1. Create a new folder: `openspec/changes/<change-name>/`
2. Add `proposal.md` - Why and what
3. Add `tasks.md` - Implementation checklist
4. Add `specs/<component>/spec.md` - Spec deltas

### Implementing a Change

1. Read the spec deltas in `openspec/changes/<change-name>/specs/`
2. Work through `tasks.md` sequentially
3. Mark tasks complete: `- [x]` as you finish
4. Reference specs when making implementation decisions

### Archiving a Change

1. Copy spec deltas to `openspec/specs/`
2. Apply ADDED/MODIFIED/REMOVED sections
3. Move change folder to `openspec/archive/<change-name>/`

## Spec Format

See the spec format guide for details on writing specifications.

### Delta Sections

- `## ADDED Requirements` - New capabilities
- `## MODIFIED Requirements` - Changed behavior
- `## REMOVED Requirements` - Deprecated features

### Requirement Format

```markdown
### Requirement: <Name>
The system SHALL <requirement>.

#### Scenario: <Name>
- WHEN <condition>
- THEN <result>
```
```

### 4. Add to .gitignore (Optional)

If you want to keep changes private:

```bash
echo "openspec/changes/" >> .gitignore
```

## Creating Your First Change

### 1. Create Change Folder

```bash
mkdir -p openspec/changes/add-feature-x
```

### 2. Create Proposal

Create `openspec/changes/add-feature-x/proposal.md`:

```markdown
# Add Feature X

## Motivation
[Why this change is needed]

## Changes
- [What will change]
- [What components are affected]

## Impact
- [Breaking changes]
- [Migration requirements]
- [Dependencies]
```

### 3. Create Tasks

Create `openspec/changes/add-feature-x/tasks.md`:

```markdown
## 1. [Phase Name]
- [ ] 1.1 [Task description]
- [ ] 1.2 [Task description]

## 2. [Phase Name]
- [ ] 2.1 [Task description]
- [ ] 2.2 [Task description]
```

### 4. Create Spec Deltas

Create `openspec/changes/add-feature-x/specs/<component>/spec.md`:

```markdown
# Delta for <Component>

## ADDED Requirements

### Requirement: <Name>
The system SHALL <requirement>.

#### Scenario: <Name>
- WHEN <condition>
- THEN <result>
```

## Working with AI Agents

### Creating a Change

Ask your AI:

```
Create a new OpenSpec change in openspec/changes/add-search-filters/ with:
1. proposal.md explaining why we need search filters
2. tasks.md with implementation steps
3. specs/search/spec.md with the new requirements
```

### Implementing

Ask your AI:

```
Please implement the tasks in openspec/changes/add-search-filters/tasks.md
Reference the specs in openspec/changes/add-search-filters/specs/ for requirements
Mark each task complete as you finish
```

### Archiving

Ask your AI:

```
Please archive the add-search-filters change:
1. Copy spec deltas from openspec/changes/add-search-filters/specs/ to openspec/specs/
2. Apply the ADDED/MODIFIED/REMOVED sections to the source specs
3. Move openspec/changes/add-search-filters/ to openspec/archive/
```

## Limitations Without CLI

- ❌ No automatic validation
- ❌ No slash commands (unless manually configured)
- ❌ Manual archiving process
- ❌ No auto-generated AGENTS.md updates

## Benefits Without CLI

- ✅ No installation required
- ✅ Works immediately
- ✅ Full control over file structure
- ✅ Compatible with all AI agents
- ✅ Simple git workflow

## Upgrading to CLI Later

If you decide to install the CLI later:

```bash
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
```

The CLI will detect your existing structure and integrate with it.

