headquarter/openspec/README.md

# OpenSpec Integration

This project uses [OpenSpec](https://openspec.dev/) as the **single source of truth** for requirements, specifications, and task tracking.

## Philosophy

**Specs live in the repo.** They provide:
- Living documentation of system behavior
- Context for AI agents implementing features
- Reviewable intent before code changes
- Traceability from requirements to implementation

## Structure

```
openspec/
├── README.md                       # This file
├── specs/                          # Living specifications
│   ├── docker-infrastructure/      # Phase 1: Docker, Make, env
│   ├── database-models/            # Phase 1: SQLAlchemy, Alembic
│   ├── auth-oauth/                 # Phase 1: Authentication
│   ├── user-profile/               # Phase 1: Profiles
│   ├── git-repo/                   # Phase 1: Repositories
│   ├── ssh-keys/                   # Phase 1: SSH keys
│   ├── project-management/         # Phase 1: Projects
│   ├── user-config/                # Phase 1: Preferences
│   ├── frontend-foundation/        # Phase 1: React frontend
│   ├── api-documentation/          # Phase 1: OpenAPI, health
│   ├── tool-types/                 # Phase 2: Tool definitions
│   ├── tool-instances/             # Phase 2: Container management
│   └── tool-terminal/              # Phase 2: Web terminal
└── changes/                        # Proposed changes (auto-generated)
```

## Spec-to-PRD Mapping

OpenSpec specs map directly to PRD user stories:

### Phase 1: Foundation

| Spec | PRD Story | Description |
|------|-----------|-------------|
| `docker-infrastructure` | US-001 | Docker Compose, Makefiles, environment setup |
| `database-models` | US-002 | SQLAlchemy models, Alembic migrations |
| `auth-oauth` | US-003 | Authentik OAuth, httpOnly cookies, JWT |
| `user-profile` | US-004 | Profile CRUD, avatar upload |
| `git-repo` | US-005 | Repository creation, cloning, management |
| `ssh-keys` | US-006 | Ed25519 key generation, encryption |
| `project-management` | US-007 | Projects, organization, cascading delete |
| `user-config` | US-008 | Preferences, JSONB storage |
| `frontend-foundation` | US-009 | React, TypeScript, Tailwind, routing |
| `api-documentation` | US-010 | OpenAPI/Swagger, health checks, ADRs |

### Phase 2: Tool Runtime

| Spec | PRD Story | Description |
|------|-----------|-------------|
| `tool-types` | US-011 | Docker Compose templates, built-in tools |
| `tool-types` | US-012 | ToolInstance model, schema |
| `tool-types` | US-013 | Template engine, Jinja2 rendering |
| `tool-instances` | US-014 | Tool spawning, Docker integration |
| `tool-instances` | US-015 | Traefik routes, subdomain generation |
| `tool-terminal` | US-016 | WebSocket terminal, xterm.js |
| `tool-instances` | US-017 | Status monitoring, log streaming |
| `tool-instances` | US-018 | Frontend tool management UI |
| `tool-instances` | US-019 | Config inheritance, env vars |
| All Phase 2 | US-020 | Integration, documentation |

## Workflow

### 1. Propose Changes

When you want to build something, start with OpenSpec:

```bash
# Propose a new change (creates proposal, design, tasks)
npx @fission-ai/openspec@latest propose "add repository templates feature"
```

This creates:
```
openspec/changes/add-repo-templates/
├── .openspec.yaml        # Change metadata
├── proposal.md           # What & why
├── design.md             # How (technical decisions)
├── tasks.md              # Implementation steps
└── specs/                # Updated spec deltas
    └── git-repo/
        └── spec.md       # Modified requirements
```

### 2. Review the Proposal

Read the generated artifacts:
- `proposal.md` - Understand what and why
- `design.md` - Review technical approach
- `tasks.md` - See implementation breakdown
- `specs/` - Review requirement changes

### 3. Implement Tasks

OpenSpec tasks are the unit of work. Each task from `tasks.md` is implemented directly:

```bash
# Apply the change (implements tasks sequentially)
npx @fission-ai/openspec@latest apply add-repo-templates
```

Or implement manually by reading `tasks.md` and working through each task.

### 4. Complete the Change

When all tasks are done:

```bash
# Archive the completed change
npx @fission-ai/openspec@latest archive add-repo-templates
```

## Commands Reference

### OpenSpec

```bash
# Propose a change
npx @fission-ai/openspec@latest propose "description"

# List active changes
npx @fission-ai/openspec@latest list

# Apply a change (implements tasks)
npx @fission-ai/openspec@latest apply <change-id>

# Archive completed change
npx @fission-ai/openspec@latest archive <change-id>

# Explore existing specs
npx @fission-ai/openspec@latest explore

# Check change status
npx @fission-ai/openspec@latest status --change <change-id>
```

## Quality Gates

All changes must:
1. **Update specs first** if requirements change
2. Pass backend tests: `pytest`, `mypy .`, `ruff check .`
3. Pass frontend tests: `npm run typecheck`, `npm run lint`
4. Maintain spec-code alignment (specs reflect actual behavior)

## Rules

1. **Specs are source of truth** - Code implements specs, not the other way around
2. **Changes flow through OpenSpec** - Every feature starts as an OpenSpec proposal
3. **Living documentation** - Update specs when behavior changes
4. **Review intent first** - Review spec deltas before reviewing code diffs

## Integration with AGENTS.md

This project follows the workflow defined in `AGENTS.md`:

1. Read OpenSpec specs for context
2. Use superpowers skills for planning
3. Implement tasks from OpenSpec changes
4. Verify against quality gates

## Dependencies

- [OpenSpec CLI](https://openspec.dev/) - `npx @fission-ai/openspec@latest`