Merge pull request #1468 from helixml/feature/project_management_skill

Feature/project management skill

Author: nessie993

api/pkg/agent/skill/project/helix_projects_skill.go

@@ -0,0 +1,115 @@
+package project
+
+import (
+	"github.com/helixml/helix/api/pkg/agent"
+	"github.com/helixml/helix/api/pkg/store"
+	"github.com/helixml/helix/api/pkg/util/jsonschema"
+)
+
+const helixProjectsSystemPrompt = `You are an expert project manager for Helix projects. Your role is to help users manage their development tasks through spec-driven task management.
+
+## Available Operations
+
+You can perform the following operations on spec tasks:
+
+1. **List Tasks** - View all tasks in the project with optional filtering
+2. **Create Tasks** - Create new development tasks from user requirements
+3. **Get Task Details** - Retrieve full details of a specific task
+4. **Update Tasks** - Modify task properties like status, priority, name, or description
+
+## Task Workflow
+
+Tasks follow a spec-driven development workflow with these statuses:
+
+### Phase 1: Specification Generation
+- **backlog** - Initial state, task waiting for spec generation
+- **spec_generation** - AI is generating specifications (requirements, design, implementation plan)
+- **spec_review** - Human reviewing the generated specifications
+- **spec_revision** - Human requested changes to the specs
+- **spec_approved** - Specs approved, ready for implementation
+
+### Phase 2: Implementation
+- **implementation_queued** - Waiting for implementation agent pickup
+- **implementation** - Agent actively coding the task
+- **implementation_review** - Code review in progress (PR created)
+- **pull_request** - PR opened, awaiting merge
+- **done** - Task completed
+
+### Error States
+- **spec_failed** - Specification generation failed
+- **implementation_failed** - Implementation failed
+
+## Task Types
+- **feature** - New functionality
+- **bug** - Bug fix
+- **refactor** - Code refactoring
+
+## Task Priorities
+- **low** - Can be addressed when convenient
+- **medium** - Should be addressed in normal workflow
+- **high** - Should be prioritized
+- **critical** - Requires immediate attention
+
+## Best Practices
+
+1. When creating tasks:
+   - Use clear, descriptive names
+   - Provide detailed descriptions with context
+   - Set appropriate priority based on urgency
+   - Choose the correct task type
+
+2. When updating tasks:
+   - Only change status according to the workflow progression
+   - Update priority if urgency changes
+   - Keep descriptions updated with relevant context
+
+3. When listing tasks:
+   - Use filters to narrow down results
+   - Check status distribution to understand project health
+   - Review high-priority items first
+
+4. Always provide context when creating or updating tasks to ensure the development agent has enough information to work effectively.`
+
+const helixProjectsSkillDescription = `Manage Helix project tasks through spec-driven development workflow.
+
+This skill allows you to:
+- List tasks with optional filtering by status, priority, or type
+- Create new development tasks from user requirements
+- Get full details of specific tasks
+- Update task properties like status, priority, name, or description
+
+Use this tool when users want to manage their development tasks, check project status, or create new work items.`
+
+var helixProjectsSkillParameters = jsonschema.Definition{
+	Type: jsonschema.Object,
+	Properties: map[string]jsonschema.Definition{
+		"prompt": {
+			Type:        jsonschema.String,
+			Description: "The instruction describing what task management operation to perform. Examples: 'list all high priority tasks', 'create a new feature task for user authentication', 'update task status to done'",
+		},
+	},
+	Required: []string{"prompt"},
+}
+
+type HelixProjectsSkill struct{}
+
+func NewHelixProjectsSkill(projectID string, store store.Store) agent.Skill {
+	skillTools := []agent.Tool{
+		NewListSpecTasksTool(projectID, store),
+		NewCreateSpecTaskTool(projectID, store),
+		NewGetSpecTaskTool(projectID, store),
+		NewUpdateSpecTaskTool(projectID, store),
+	}
+	return agent.Skill{
+		Name:         "HelixProjects",
+		Description:  helixProjectsSkillDescription,
+		SystemPrompt: helixProjectsSystemPrompt,
+		Parameters:   helixProjectsSkillParameters,
+		Direct:       false, // This is not a direct skill, sub-agent context runner will be used
+		Tools:        skillTools,
+	}
+}
+
+func (s *HelixProjectsSkill) Name() string {
+	return "HelixProjects"
+}

api/pkg/agent/skill/project/spec_task.go

@@ -0,0 +1,60 @@
+package project
+
+import (
+	"fmt"
+	"time"
+)
+
+// SpecTaskSummary is a summary of a spec task
+type SpecTaskSummary struct {
+	ID             string     `json:"id"`
+	Name           string     `json:"name"`
+	Description    string     `json:"description"`
+	Status         string     `json:"status"`
+	Priority       string     `json:"priority"`
+	BranchName     string     `json:"branch_name,omitempty"`
+	PullRequestID  string     `json:"pull_request_id,omitempty"`
+	PullRequestURL string     `json:"pull_request_url,omitempty"`
+	StartedAt      *time.Time `json:"started_at,omitempty"`
+	CompletedAt    *time.Time `json:"completed_at,omitempty"`
+}
+
+func (s *SpecTaskSummary) ToString() string {
+	result := fmt.Sprintf("ID: %s\nTask: %s\nStatus: %s", s.ID, s.Name, s.Status)
+	if s.Description != "" {
+		result += fmt.Sprintf("\nDescription: %s", s.Description)
+	}
+	if s.Priority != "" {
+		result += fmt.Sprintf("\nPriority: %s", s.Priority)
+	}
+	if s.BranchName != "" {
+		result += fmt.Sprintf("\nBranchName: %s", s.BranchName)
+	}
+	if s.PullRequestID != "" {
+		result += fmt.Sprintf("\nPullRequestID: %s", s.PullRequestID)
+	}
+	if s.PullRequestURL != "" {
+		result += fmt.Sprintf("\nPullRequestURL: %s", s.PullRequestURL)
+	}
+	if s.StartedAt != nil {
+		result += fmt.Sprintf("\nStartedAt: %s", s.StartedAt.Format(time.RFC3339))
+	}
+	if s.CompletedAt != nil {
+		result += fmt.Sprintf("\nCompletedAt: %s", s.CompletedAt.Format(time.RFC3339))
+	}
+	return result
+}
+
+type ListSpecTasksResult struct {
+	Tasks []SpecTaskSummary `json:"tasks"`
+	Total int               `json:"total"`
+}
+
+func (r *ListSpecTasksResult) ToString() string {
+	var result string
+	result = fmt.Sprintf("Total Tasks: %d\n\n", r.Total)
+	for i, task := range r.Tasks {
+		result += fmt.Sprintf("--- Task %d ---\n%s\n\n", i+1, task.ToString())
+	}
+	return result
+}

api/pkg/agent/skill/project/spec_task_create_tool.go

@@ -0,0 +1,183 @@
+package project
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/helixml/helix/api/pkg/agent"
+	"github.com/helixml/helix/api/pkg/store"
+	"github.com/helixml/helix/api/pkg/system"
+	"github.com/helixml/helix/api/pkg/types"
+	"github.com/helixml/helix/api/pkg/util/jsonschema"
+	"github.com/rs/zerolog/log"
+	"github.com/sashabaranov/go-openai"
+)
+
+// CreateSpecTaskTool - creates a new spec task
+
+var createSpecTaskParameters = jsonschema.Definition{
+	Type: jsonschema.Object,
+	Properties: map[string]jsonschema.Definition{
+		"name": {
+			Type:        jsonschema.String,
+			Description: "Short, descriptive name for the task",
+		},
+		"description": {
+			Type:        jsonschema.String,
+			Description: "Detailed description of what needs to be done",
+		},
+		"type": {
+			Type:        jsonschema.String,
+			Description: "Task type: feature, bug, or refactor",
+			Enum:        []string{"feature", "bug", "refactor"},
+		},
+		"priority": {
+			Type:        jsonschema.String,
+			Description: "Task priority: low, medium, high, or critical",
+			Enum:        []string{"low", "medium", "high", "critical"},
+		},
+		"original_prompt": {
+			Type:        jsonschema.String,
+			Description: "The original user request or prompt that led to this task",
+		},
+	},
+	Required: []string{"name", "description"},
+}
+
+type CreateSpecTaskTool struct {
+	store     store.Store
+	projectID string
+}
+
+func NewCreateSpecTaskTool(projectID string, store store.Store) *CreateSpecTaskTool {
+	return &CreateSpecTaskTool{
+		store:     store,
+		projectID: projectID,
+	}
+}
+
+var _ agent.Tool = &CreateSpecTaskTool{}
+
+func (t *CreateSpecTaskTool) Name() string {
+	return "CreateSpecTask"
+}
+
+func (t *CreateSpecTaskTool) Description() string {
+	return "Create a new spec-driven task in the project"
+}
+
+func (t *CreateSpecTaskTool) String() string {
+	return "CreateSpecTask"
+}
+
+func (t *CreateSpecTaskTool) StatusMessage() string {
+	return "Creating spec task"
+}
+
+func (t *CreateSpecTaskTool) Icon() string {
+	return "AddIcon"
+}
+
+func (t *CreateSpecTaskTool) OpenAI() []openai.Tool {
+	return []openai.Tool{
+		{
+			Type: openai.ToolTypeFunction,
+			Function: &openai.FunctionDefinition{
+				Name:        "CreateSpecTask",
+				Description: "Create a new spec-driven task in the project",
+				Parameters:  createSpecTaskParameters,
+			},
+		},
+	}
+}
+
+type CreateSpecTaskResult struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	Status      string `json:"status"`
+	Priority    string `json:"priority"`
+	Type        string `json:"type"`
+	Message     string `json:"message"`
+}
+
+func (r *CreateSpecTaskResult) ToString() string {
+	return fmt.Sprintf("ID: %s\nTask: %s\nDescription: %s\nStatus: %s\nPriority: %s\nType: %s\nMessage: %s",
+		r.ID, r.Name, r.Description, r.Status, r.Priority, r.Type, r.Message)
+}
+
+func (t *CreateSpecTaskTool) Execute(ctx context.Context, meta agent.Meta, args map[string]interface{}) (string, error) {
+	projectID := t.projectID
+	if projectID == "" {
+		projectContext, ok := types.GetHelixProjectContext(ctx)
+		if !ok {
+			return "", fmt.Errorf("helix project context not found")
+		}
+		projectID = projectContext.ProjectID
+	}
+
+	log.Info().
+		Str("project_id", projectID).
+		Str("user_id", meta.UserID).
+		Str("session_id", meta.SessionID).
+		Interface("args", args).
+		Msg("Executing CreateSpecTask tool")
+
+	name, ok := args["name"].(string)
+	if !ok || name == "" {
+		return "", fmt.Errorf("name is required")
+	}
+
+	description, ok := args["description"].(string)
+	if !ok || description == "" {
+		return "", fmt.Errorf("description is required")
+	}
+
+	taskType := "feature"
+	if t, ok := args["type"].(string); ok && t != "" {
+		taskType = t
+	}
+
+	priority := types.SpecTaskPriorityMedium
+	if p, ok := args["priority"].(string); ok && p != "" {
+		priority = types.SpecTaskPriority(p)
+	}
+
+	originalPrompt := ""
+	if op, ok := args["original_prompt"].(string); ok {
+		originalPrompt = op
+	}
+
+	task := &types.SpecTask{
+		ID:             system.GenerateSpecTaskID(),
+		ProjectID:      projectID,
+		Name:           name,
+		Description:    description,
+		Type:           taskType,
+		Priority:       priority,
+		Status:         types.TaskStatusBacklog,
+		OriginalPrompt: originalPrompt,
+		CreatedBy:      meta.UserID,
+		CreatedAt:      time.Now(),
+		UpdatedAt:      time.Now(),
+	}
+
+	err := t.store.CreateSpecTask(ctx, task)
+	if err != nil {
+		log.Error().Err(err).Str("project_id", projectID).Msg("Failed to create spec task")
+		return "", fmt.Errorf("failed to create spec task: %w", err)
+	}
+
+	result := CreateSpecTaskResult{
+		ID:          task.ID,
+		Name:        task.Name,
+		Description: task.Description,
+		Status:      string(task.Status),
+		Priority:    string(task.Priority),
+		Type:        task.Type,
+		Message:     "Task created successfully",
+	}
+
+	return result.ToString(), nil
+}