headquarter/openspec

OpenSpec Integration

This project uses OpenSpec 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:

# 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:

# 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:

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

Commands Reference

OpenSpec

# 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 - npx @fission-ai/openspec@latest