feat: Improve agent DX based on error pattern analysis

Analyzed 40 agent errors across td and sidecar projects to identify
systematic CLI friction points. Changes:

- td log: detect issue ID in either arg position (not just first)
- task/epic create: add --parent/--epic/--depends-on/--blocks/--minor flags
- reject: add --comment/-c/--message/--note/--notes aliases
- approve: add -c shorthand for --comment
- review: add "finish" as command alias
- handoff: accept 0 args, infer focused issue with actionable error
- issueIDPattern: match both 6 and 8 char hex IDs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: marcus

cmd/epic.go

@@ -93,6 +93,10 @@ func init() {
 	epicCreateCmd.Flags().StringP("priority", "p", "", "Priority (P0, P1, P2, P3, P4)")
 	epicCreateCmd.Flags().StringP("description", "d", "", "Description text")
 	epicCreateCmd.Flags().String("labels", "", "Comma-separated labels")
+	epicCreateCmd.Flags().String("parent", "", "Parent issue ID")
+	epicCreateCmd.Flags().String("epic", "", "Parent issue ID (alias for --parent)")
+	epicCreateCmd.Flags().String("depends-on", "", "Issues this depends on")
+	epicCreateCmd.Flags().String("blocks", "", "Issues this blocks")
 	// Hidden type flag - set programmatically to "epic"
 	epicCreateCmd.Flags().StringP("type", "t", "", "")
 	epicCreateCmd.Flags().MarkHidden("type")

cmd/handoff.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"strings"
 
+	"github.com/marcus/td/internal/config"
 	"github.com/marcus/td/internal/db"
 	"github.com/marcus/td/internal/git"
 	"github.com/marcus/td/internal/input"
@@ -36,14 +37,42 @@ Or use flags with values, stdin (-), or file (@path):
   --done @done.txt       Items from file (one per line)
   echo "item" | td handoff ID --done -   Items from stdin`,
 	GroupID: "workflow",
-	Args:    cobra.RangeArgs(1, 2),
+	Args:    cobra.RangeArgs(0, 2),
 	RunE: func(cmd *cobra.Command, args []string) error {
-		// Validate issue ID (catch empty strings)
-		if err := ValidateIssueID(args[0], "handoff <issue-id> [message]"); err != nil {
+		baseDir := getBaseDir()
+
+		// Resolve issue ID: from args or focused issue
+		var issueArg string
+		var messageArg string
+		switch len(args) {
+		case 2:
+			issueArg = args[0]
+			messageArg = args[1]
+		case 1:
+			// Check if the single arg is an issue ID or a message
+			if issueIDPattern.MatchString(args[0]) {
+				issueArg = args[0]
+			} else {
+				// Treat as message, infer issue from focus
+				messageArg = args[0]
+			}
+		}
+
+		if issueArg == "" {
+			// Infer from focused issue
+			focusedID, err := config.GetFocus(baseDir)
+			if err != nil || focusedID == "" {
+				output.Error("no issue specified and no focused issue")
+				fmt.Fprintln(os.Stderr, "  Use: td handoff <id> [message]  OR  td start <id> first")
+				return fmt.Errorf("no issue specified")
+			}
+			issueArg = focusedID
+		}
+
+		if err := ValidateIssueID(issueArg, "handoff <issue-id> [message]"); err != nil {
 			output.Error("%v", err)
 			return err
 		}
-		baseDir := getBaseDir()
 
 		database, err := db.Open(baseDir)
 		if err != nil {
@@ -58,7 +87,7 @@ Or use flags with values, stdin (-), or file (@path):
 			return err
 		}
 
-		issueID := args[0]
+		issueID := issueArg
 		issue, err := database.GetIssue(issueID)
 		if err != nil {
 			output.Error("%v", err)
@@ -92,9 +121,9 @@ Or use flags with values, stdin (-), or file (@path):
 			handoff.Done = append(handoff.Done, message)
 		}
 
-		// Handle positional message argument: td handoff <id> "message"
-		if len(args) > 1 && args[1] != "" {
-			handoff.Done = append(handoff.Done, args[1])
+		// Handle positional message argument
+		if messageArg != "" {
+			handoff.Done = append(handoff.Done, messageArg)
 		}
 
 		// Check if stdin has data (YAML format) - only if not already used by flag expansion

cmd/handoff_test.go

@@ -404,9 +404,9 @@ func TestHandoffPositionalMessage(t *testing.T) {
 		t.Errorf("Expected 2 args to be valid: %v", err)
 	}
 
-	// Test with 0 args (should fail)
-	if err := args(handoffCmd, []string{}); err == nil {
-		t.Error("Expected 0 args to fail")
+	// Test with 0 args (should be valid - infers from focused issue)
+	if err := args(handoffCmd, []string{}); err != nil {
+		t.Errorf("Expected 0 args to be valid (infer from focus): %v", err)
 	}
 
 	// Test with 3 args (should fail)

cmd/log.go

@@ -17,8 +17,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// issueIDPattern matches valid issue IDs like "td-a1b2c3d4"
-var issueIDPattern = regexp.MustCompile(`^td-[0-9a-f]{8}$`)
+// issueIDPattern matches valid issue IDs like "td-a1b2c3" or "td-a1b2c3d4"
+var issueIDPattern = regexp.MustCompile(`^td-[0-9a-f]{6,8}$`)
 
 var logCmd = &cobra.Command{
 	Use:   "log [issue-id] <message>",
@@ -60,9 +60,18 @@ Supports stdin input for multi-line messages or piped input:
 		var message string
 
 		if len(args) == 2 {
-			// Two args: first is issue ID, second is message
-			issueID = args[0]
-			message = args[1]
+			// Two args: detect which is issue ID regardless of order
+			if issueIDPattern.MatchString(args[0]) {
+				issueID = args[0]
+				message = args[1]
+			} else if issueIDPattern.MatchString(args[1]) {
+				issueID = args[1]
+				message = args[0]
+			} else {
+				// Neither matches ID pattern; treat as original order (first=ID, second=message)
+				issueID = args[0]
+				message = args[1]
+			}
 		} else if len(args) == 1 {
 			// One arg: check if it's an issue ID or message
 			// Issue IDs match pattern "td-[8 hex chars]", otherwise it's a message

cmd/review.go

@@ -104,7 +104,7 @@ func submitIssueForReview(database *db.DB, issue *models.Issue, sess *session.Se
 
 var reviewCmd = &cobra.Command{
 	Use:     "review [issue-id...]",
-	Aliases: []string{"submit"},
+	Aliases: []string{"submit", "finish"},
 	Short:   "Submit one or more issues for review",
 	Long: `Submits the issue(s) for review. If no handoff exists, a minimal one is
 auto-created (consider using 'td handoff' for better documentation).
@@ -511,8 +511,8 @@ Supports bulk operations:
 				continue
 			}
 
-			// Log
-			reason, _ := cmd.Flags().GetString("reason")
+			// Log (supports --reason, --message, --comment, --note, --notes)
+			reason := approvalReason(cmd)
 			logMsg := "Rejected"
 			if reason != "" {
 				logMsg = "Rejected: " + reason
@@ -776,12 +776,16 @@ func init() {
 	reviewCmd.Flags().Bool("minor", false, "Mark as minor task (allows self-review)")
 	approveCmd.Flags().StringP("reason", "m", "", "Reason for approval")
 	approveCmd.Flags().String("message", "", "Reason for approval (alias for --reason)")
-	approveCmd.Flags().String("comment", "", "Reason for approval (alias for --message)")
+	approveCmd.Flags().StringP("comment", "c", "", "Reason for approval (alias for --message)")
 	approveCmd.Flags().String("note", "", "Reason for approval (alias for --reason)")
 	approveCmd.Flags().String("notes", "", "Reason for approval (alias for --reason)")
 	approveCmd.Flags().Bool("json", false, "JSON output")
 	approveCmd.Flags().Bool("all", false, "Approve all reviewable issues")
 	rejectCmd.Flags().StringP("reason", "m", "", "Reason for rejection")
+	rejectCmd.Flags().StringP("comment", "c", "", "Reason for rejection (alias for --reason)")
+	rejectCmd.Flags().String("message", "", "Reason for rejection (alias for --reason)")
+	rejectCmd.Flags().String("note", "", "Reason for rejection (alias for --reason)")
+	rejectCmd.Flags().String("notes", "", "Reason for rejection (alias for --reason)")
 	rejectCmd.Flags().Bool("json", false, "JSON output")
 	closeCmd.Flags().StringP("reason", "m", "", "Reason for closing")
 	closeCmd.Flags().String("comment", "", "Reason for closing (alias for --reason)")

cmd/task.go

@@ -93,6 +93,11 @@ func init() {
 	taskCreateCmd.Flags().StringP("priority", "p", "", "Priority (P0, P1, P2, P3, P4)")
 	taskCreateCmd.Flags().StringP("description", "d", "", "Description text")
 	taskCreateCmd.Flags().String("labels", "", "Comma-separated labels")
+	taskCreateCmd.Flags().String("parent", "", "Parent issue ID")
+	taskCreateCmd.Flags().String("epic", "", "Parent issue ID (alias for --parent)")
+	taskCreateCmd.Flags().String("depends-on", "", "Issues this depends on")
+	taskCreateCmd.Flags().String("blocks", "", "Issues this blocks")
+	taskCreateCmd.Flags().Bool("minor", false, "Mark as minor task (allows self-review)")
 	// Hidden type flag - set programmatically to "task"
 	taskCreateCmd.Flags().StringP("type", "t", "", "")
 	taskCreateCmd.Flags().MarkHidden("type")