Alex Blank
f728011b2a
When switching terminal sessions in fullscreen mode, the viewport shrank cumulatively because .terminal-wrapper uses grid-template-rows: auto 1fr. With showControls=false, the single child (.terminal-container) landed in the auto track instead of 1fr, creating a feedback loop with xterm fit(). - Add .terminal-wrapper.no-controls with grid-template-rows: 1fr so the container fills the wrapper when the header is hidden. - Apply no-controls class in TerminalComponent when showControls=false. - Replace setTimeout(50) with double requestAnimationFrame in TerminalPage for more reliable fit() timing after tab switches. Quality gates: tsc --noEmit (clean), pytest (208 passed, 6 pre-existing)
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 whydesign.md- Review technical approachtasks.md- See implementation breakdownspecs/- 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:
- Update specs first if requirements change
- Pass backend tests:
pytest,mypy .,ruff check . - Pass frontend tests:
npm run typecheck,npm run lint - Maintain spec-code alignment (specs reflect actual behavior)
Rules
- Specs are source of truth - Code implements specs, not the other way around
- Changes flow through OpenSpec - Every feature starts as an OpenSpec proposal
- Living documentation - Update specs when behavior changes
- Review intent first - Review spec deltas before reviewing code diffs
Integration with AGENTS.md
This project follows the workflow defined in AGENTS.md:
- Read OpenSpec specs for context
- Use superpowers skills for planning
- Implement tasks from OpenSpec changes
- Verify against quality gates
Dependencies
- OpenSpec CLI -
npx @fission-ai/openspec@latest