headquarter/openspec/specs/project-management/spec.md

Project Management Specification

Purpose

Organize repositories into projects for grouping related work.

Requirements

Requirement: Project Creation

The system SHALL allow authenticated users to create new projects and SHALL assign the creator as project owner.

Scenario: Create project

• GIVEN an authenticated user
• WHEN they create a project with name and description
• THEN a project record is created
• AND the user is set as owner

Scenario: Reject unauthenticated creation

• GIVEN a request without a valid authenticated session
• WHEN it attempts to create a project
• THEN the system responds with unauthorized status

Requirement: Project Listing

The system SHALL list projects owned by the authenticated user, including related repositories and default SSH key metadata.

Scenario: List projects

• GIVEN an authenticated user
• WHEN they view the projects page
• THEN all their projects are listed with associated repositories

Scenario: Ownership-scoped listing

• GIVEN multiple users with separate projects
• WHEN one user requests their project list
• THEN only that user's projects are returned

Requirement: Project Card Layout

The projects listing page SHALL display each project card with a Settings link, Delete button, and Open Workspace button, where the Open Workspace button is positioned on the right.

Scenario: View project card actions

• GIVEN the projects listing page
• WHEN a project card is rendered
• THEN it displays:
  • A Settings link navigating to /projects/:id/settings
  • A Delete button with confirmation
  • An Open Workspace button positioned on the right side

Scenario: Navigate to project settings

• GIVEN the projects listing page
• WHEN a user clicks the Settings link on a project card
• THEN they are navigated to the project settings page

Scenario: No inline edit on project cards

• GIVEN the projects listing page
• WHEN a project card is rendered
• THEN no inline Edit button or modal dialog is present

Requirement: Project Updates

The system SHALL support updating project details for project owners via the project settings page.

Scenario: Update project via settings

• GIVEN a project owner viewing the project settings page
• WHEN they update the name or description and save
• THEN the changes are persisted

Scenario: Non-owner update denied

• GIVEN a user who is not the project owner
• WHEN they attempt to update project details via the settings page
• THEN the system responds with forbidden status

Requirement: Project Deletion

The system SHALL support cascading project deletion for project owners.

Scenario: Delete project

• GIVEN a project owner
• WHEN they delete a project
• THEN all associated repositories are deleted
• AND all associated SSH keys are removed
• AND the project record is deleted

Scenario: Non-owner deletion denied

• GIVEN a user who is not the project owner
• WHEN they attempt to delete the project
• THEN the system responds with forbidden status

Requirement: Default SSH Key

The system SHALL allow project owners to set a default SSH key per project and SHALL validate ownership for selected keys.

Scenario: Set default key

• GIVEN a project with SSH keys
• WHEN the owner selects a default key
• THEN it's used for git operations in that project

Scenario: Reject foreign key assignment

• GIVEN a project owner
• WHEN they try setting a default SSH key that does not belong to their allowed scope
• THEN the system rejects the request with validation error

Dependencies

• Database models: Project, User, GitRepository, SSHKey
• git-repo (for cascading delete)
• ssh-keys (for default key)

Quality Gates

• pytest must pass
• mypy . must pass
• ruff check . must pass
• npm run typecheck must pass
• npm run lint must pass