next

Documentation

Overview

CANARY: REQ=CP-252; FEATURE="NextPriorityCommand"; ASPECT=CLI; STATUS=BENCHED; TEST=TestCANARY_CBIN_132_CLI_NextPrioritySelection; BENCH=BenchmarkCANARY_CBIN_132_CLI_PriorityQuery; OWNER=canary; UPDATED=2026-08-29

Index

• Variables
• type PromptData
• type RelatedSpec

Variables

var NextCmd = &cobra.Command{
	Use:   "next [flags]",
	Short: "Identify and implement next highest priority requirement",
	Long: `Identify the next highest priority unimplemented requirement and generate
comprehensive implementation guidance.

This command automatically:
- Queries database or scans filesystem for CANARY tokens
- Identifies highest priority STUB or IMPL requirement
- Excludes hidden requirements (test files, templates, examples)
- Verifies dependencies are satisfied
- Generates comprehensive implementation prompt with:
  - Specification details
  - Constitutional principles
  - Test-first guidance
  - Token placement examples

Priority determination factors:
1. PRIORITY field (1=highest, 10=lowest)
2. STATUS (STUB > IMPL > TESTED)
3. DEPENDS_ON (dependencies must be TESTED/BENCHED)
4. UPDATED field (older tokens get priority boost)`,
	RunE: func(cmd *cobra.Command, args []string) error {
		promptArg, _ := cmd.Flags().GetString("prompt-arg")
		if promptArg != "" {
			if _, err := utils.LoadPrompt(promptArg); err != nil {
				return err
			}
		}
		dbPath, _ := cmd.Flags().GetString("db")
		promptFlag, _ := cmd.Flags().GetBool("prompt")
		jsonOutput, _ := cmd.Flags().GetBool("json")
		dryRun, _ := cmd.Flags().GetBool("dry-run")
		filterStatus, _ := cmd.Flags().GetString("status")
		filterAspect, _ := cmd.Flags().GetString("aspect")
		strictExternal, _ := cmd.Flags().GetBool("strict-external")

		filters := make(map[string]string)
		if filterStatus != "" {
			filters["status"] = filterStatus
		}
		if filterAspect != "" {
			filters["aspect"] = filterAspect
		}

		token, err := selectNextPriorityStrict(dbPath, filters, strictExternal)
		if err != nil {
			return fmt.Errorf("select next priority: %w", err)
		}

		if token == nil {
			fmt.Println("🎉 All requirements completed! No work available.")
			fmt.Println("\nSuggestions:")
			fmt.Println("  • Run: canary scan --verify GAP_ANALYSIS.md")
			fmt.Println("  • Review completed requirements")
			fmt.Println("  • Consider creating new specifications")
			return nil
		}

		if dryRun {
			fmt.Printf("Next priority (dry run): %s - %s\n", token.ReqID, token.Feature)
			fmt.Printf("Priority: %d | Status: %s | Aspect: %s\n", token.Priority, token.Status, token.Aspect)
			fmt.Printf("Location: %s\n", token.FilePath)
			return nil
		}

		output, err := renderPrompt(token, promptFlag)
		if err != nil {
			return fmt.Errorf("render prompt: %w", err)
		}

		if jsonOutput {
			out := nextJSONOutput{
				ReqID:    token.ReqID,
				Feature:  token.Feature,
				Aspect:   token.Aspect,
				Status:   token.Status,
				Priority: token.Priority,
				FilePath: token.FilePath,
				Updated:  token.UpdatedAt,
			}
			enc := json.NewEncoder(os.Stdout)
			enc.SetIndent("", "  ")
			if err := enc.Encode(out); err != nil {
				return fmt.Errorf("json encode: %w", err)
			}
			return nil
		}

		fmt.Println(output)
		return nil
	},
}

CANARY: REQ=CP-252; FEATURE="NextCmd"; ASPECT=CLI; STATUS=BENCHED; TEST=TestCANARY_CBIN_132_CLI_NextPrioritySelection; BENCH=BenchmarkCANARY_CBIN_132_CLI_PriorityQuery; OWNER=canary; DOC=user:docs/user/next-priority-guide.md; DOC_HASH=17524f7a14d2c410; UPDATED=2026-08-29

Types

type PromptData

type PromptData struct {
	ReqID             string
	Feature           string
	Aspect            string
	Status            string
	Priority          int
	SpecFile          string
	SpecContent       string
	Constitution      string
	RelatedSpecs      []RelatedSpec
	Dependencies      []*storage.Token
	SuggestedFiles    []string
	TestGuidance      string
	TokenExample      string
	SuccessCriteria   []string
	Today             string
	SuggestedTestFile string
	PackageName       string
}

PromptData holds template variables for prompt generation

type RelatedSpec

type RelatedSpec struct {
	ReqID    string
	Feature  string
	SpecFile string
}

RelatedSpec represents a related specification reference