feat: implement docker infrastructure (US-001)
- Add docker-compose.yml with postgres, redis, api, and web services - Add multi-stage Dockerfile for API (Python 3.11) - Add multi-stage Dockerfile for web (Node.js 20 + nginx) - Add Makefile with common development commands - Add .env.example with all required environment variables - Add placeholder pyproject.toml and package.json for builds - Configure health checks for all services - Setup persistent volumes for postgres, redis, and repos - Run services as non-root users
This commit is contained in:
@@ -0,0 +1,170 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user