KanbanGit/docs/product-spec.md

KanbanGit Product Specification

Purpose

KanbanGit is a self-hostable project and workflow management application. Its initial product goal is to support project-based Kanban work management with configurable board structure, configurable ticket metadata, ticket hierarchy, auditability, and a future repository integration workflow.

This document describes the intended product behavior. It does not claim that these capabilities exist in the current fresh Laravel 13 starter application.

Current implementation status

• The repository currently contains the default Laravel 13 + Inertia starter structure.
• No Kanban, ticket, permission, team, project, or Git integration domain has been implemented yet.
• This specification is the source of truth for the upcoming product implementation.

Product goals

• Support multiple projects inside one self-hosted installation.
• Provide a configurable board and backlog per project.
• Support tickets with structured metadata, hierarchy, linking, blockers, and change history.
• Support application administration and project-level access control.
• Prepare the product for repository-aware workflows, starting with Gitea.

Roles

Platform admin

A platform admin can manage application-wide administrative settings and user administration. This role exists above project-level permissions.

Project member

A project member may receive project permissions directly or through one or more teams. Project permissions are scoped to a single project.

Project behavior

Each project must include the following product areas:

• Board
• Backlog
• Project settings
• Ticket management
• Future roadmap support

Project creation

When a project is created, it must define:

• A project name
• A project key

Project key rules:

• Maximum length: 5 characters
• Automatically stored and displayed in uppercase
• Unique across the entire application
• Immutable after ticket creation begins, unless a future migration strategy is explicitly designed

The project key is used as the prefix for all ticket keys in that project.

Board and backlog

Each project has one board and one backlog.

Board rules:

• The board supports any number of columns.
• Board columns are configured in project settings.
• Board columns define the valid in-board statuses for tickets.

Backlog rules:

• Every newly created ticket starts in the backlog.
• A backlog ticket is not yet visible in the board columns.
• When a ticket is assigned to a board column status, it appears on the board.
• Tickets may move between backlog and board statuses according to future workflow rules.

Roadmap

Roadmap support belongs to the intended product surface of a project, but it is currently out of scope for the first implementation phases.

Ticket behavior

Tickets are the primary work items inside a project.

Required ticket attributes

Every ticket must support:

• Immutable ticket key
• Title
• Description
• Acceptance criteria
• Status
• Type
• Priority
• Optional parent ticket
• Configurable project-defined field values
• Links to other tickets
• Blocked state with comment
• Worklog
• Future branch references
• Future pull request references

Ticket key

Ticket keys follow the format PROJECTKEY-INDEX.

Rules:

• PROJECTKEY is the uppercase project key.
• INDEX is a monotonically increasing project-local integer sequence.
• The full ticket key is immutable.
• Ticket title is not unique.
• Multiple tickets may share the same title, even within the same project.
• The ticket key is the only guaranteed unique human-readable identifier for a ticket.

Ticket status

Tickets support two status contexts:

• Backlog
• One configured board column

Only tickets assigned to a board column appear on the board.

Ticket type

Each project can configure its own ticket type labels in project settings. Two types must always exist:

• Task
• Parent

Rules:

• Task and Parent are built-in types.
• Built-in types cannot be deleted.
• Built-in types may be renamed per project.
• Additional custom types may be added per project.
• Tickets of any type may have a parent ticket.
• Only tickets of type Parent may act as the parent of another ticket.

Ticket hierarchy

Hierarchy rules:

• A ticket may have zero or one parent ticket.
• A parent ticket must be a ticket whose type is Parent.
• A parent ticket may itself have a parent ticket.
• This allows nested parent structures.
• Parent tickets must show their child tickets in a list.
• Nested child structures should be presented with indentation or another clear hierarchy indicator.

Ticket priority

Each project defines its own list of priorities in project settings.

Rules:

• The available priority options are project-specific.
• A ticket stores one priority value from the project's configured list.

Configurable ticket fields

Each project may define additional ticket field definitions in project settings.

A field definition includes at least:

• Label
• Type

Initial supported field-definition types include:

• User
• Number

Examples:

• Assignee as a user field
• Driver as a user field
• Reviewer as a user field
• Reporter as a user field
• Estimated Story Points as a number field

The field system must be designed to support additional field types in the future.

Ticket links

Tickets may be linked to other tickets.

Rules:

• Link types are project-configurable labels.
• A linked ticket is represented as part of a ticket list on each side of the relationship.
• The implementation may later distinguish directionality, but the first documented requirement is label-based ticket linking configured per project.

Ticket blockers

Tickets can be marked as blocked.

Blocked rules:

• Blocking requires a comment.
• Blocked tickets must be visually distinguished on the board.
• The target visual language is a warning or danger style such as orange or red.

Ticket worklog

Each ticket must have a worklog.

Worklog rules:

• The worklog records every change to the ticket.
• Each worklog entry must record who performed the change.
• The worklog is part of the canonical ticket history.

Expected worklog-triggering changes include:

• Ticket creation
• Title, description, or acceptance criteria edits
• Status changes
• Type changes
• Priority changes
• Parent changes
• Custom field value changes
• Link changes
• Blocked or unblocked state changes

Permissions

The product must support both global administration and project-scoped permissions.

Global permission behavior:

• Platform admins can manage application-wide administrative settings.
• Platform admins can manage users.

Project permission behavior:

• Project permissions include create, view, edit, and delete.
• Project permissions may be assigned directly to users.
• Project permissions may be assigned to teams.
• Users inherit project permissions from their teams.

The full permission system is not implemented in this step, but the product must be built with this model in mind.

Future Git integration

The next major feature after the Kanban foundation is Git provider integration.

Initial expectations:

• Project settings can store one or more repository connections.
• The first supported provider is Gitea.
• Later providers should include GitHub and potentially GitLab.
• Tickets will later expose branch and pull request sections.
• The ticket branch section should eventually allow users to create a new branch directly from the ticket detail view.

Ticket-to-Git matching rule:

• A branch or pull request belongs to a ticket when its branch name starts with the ticket key.

Branch creation expectations:

• The ticket detail view may expose a branch creation action inside the branch section.
• The branch creation flow should let the user choose from all project-linked repositories.
• Repository choices remain visible even when the current user has no matching personal Git connection.
• If the user lacks access to the selected repository, branch creation fields must stay disabled and guide the user to their Git connection settings.
• The suggested branch name should start from the ticket key plus a title-derived suffix and remain editable before creation.
• The UI should validate that the proposed branch name is syntactically acceptable and not already taken before creation is submitted.

Example:

• Ticket key: AUTH-42
• Matching branch: AUTH-42-login-form

Explicitly out of scope for now

• Implementing roadmap features
• Supporting GitHub or GitLab in the first Git integration step
• Implementing the full permission and team management UI in this documentation step
• Finalizing database schema details
• Finalizing API contracts
• Finalizing automation, notifications, or reporting features