zhongwei/gh-dhofheinz-open-plugins-plugins-git-commit-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d6226e0d80cd717ae74dc79acd6de226d41e987
gh-dhofheinz-open-plugins-p…/commands/message-generation/complete-message.md
Zhongwei Li 0d6226e0d8 Initial commit
2025-11-29 18:20:25 +08:00

15 KiB
Raw Blame History

description
description
Generate complete commit message orchestrating subject, body, and footer

Operation: Complete Message

Generate a complete, well-formatted commit message by orchestrating subject generation, body composition, and footer creation.

Parameters from $ARGUMENTS

Required:

  • type: - Commit type (feat, fix, docs, etc.)

Optional:

  • scope: - Affected module/component
  • description: - Brief description (if not provided, derived from files)
  • files: - Comma-separated file paths for context
  • changes: - Comma-separated list of changes
  • why: - Explanation of why changes were made
  • breaking: - Breaking change description
  • closes: - Issue numbers to close
  • fixes: - Issue numbers to fix
  • include_body: - Include body (true|false, default: true if multiple files)
  • include_footer: - Include footer (true|false, default: true if breaking/issues)

Format: complete type:feat scope:auth files:"file1.js,file2.js" breaking:"API changed" closes:123

Workflow

Step 1: Parse All Parameters

Extract all parameters from $ARGUMENTS:

# Required
type=$(echo "$ARGUMENTS" | grep -oP 'type:\K[^ ]+')

# Optional
scope=$(echo "$ARGUMENTS" | grep -oP 'scope:\K[^ ]+')
description=$(echo "$ARGUMENTS" | grep -oP 'description:"\K[^"]+' || echo "$ARGUMENTS" | grep -oP 'description:\K[^ ]+')
files=$(echo "$ARGUMENTS" | grep -oP 'files:"\K[^"]+' || echo "$ARGUMENTS" | grep -oP 'files:\K[^ ]+')
changes=$(echo "$ARGUMENTS" | grep -oP 'changes:"\K[^"]+')
why=$(echo "$ARGUMENTS" | grep -oP 'why:"\K[^"]+')
breaking=$(echo "$ARGUMENTS" | grep -oP 'breaking:"\K[^"]+')
closes=$(echo "$ARGUMENTS" | grep -oP 'closes:\K[0-9,]+')
fixes=$(echo "$ARGUMENTS" | grep -oP 'fixes:\K[0-9,]+')
include_body=$(echo "$ARGUMENTS" | grep -oP 'include_body:\K(true|false)' || echo "auto")
include_footer=$(echo "$ARGUMENTS" | grep -oP 'include_footer:\K(true|false)' || echo "auto")

Step 2: Validate Required Parameters

Check type is provided:

if [ -z "$type" ]; then
  echo "ERROR: type parameter is required"
  echo "Usage: complete type:<type> [scope:<scope>] [files:\"<files>\"]"
  exit 1
fi

Validate type:

valid_types="feat fix docs style refactor perf test build ci chore revert"
if ! echo "$valid_types" | grep -qw "$type"; then
  echo "ERROR: Invalid type '$type'"
  echo "Valid types: $valid_types"
  exit 1
fi

Step 3: Derive Missing Parameters

If description not provided, derive from files:

if [ -z "$description" ] && [ -n "$files" ]; then
  # Analyze files to create description
  file_count=$(echo "$files" | tr ',' '\n' | wc -l)
  if [ $file_count -eq 1 ]; then
    description="update $(basename $files)"
  else
    # Extract common directory or feature
    description="update ${file_count} files"
  fi
fi

Determine body inclusion:

if [ "$include_body" = "auto" ]; then
  file_count=$(echo "$files" | tr ',' '\n' | wc -l)
  if [ $file_count -gt 1 ] || [ -n "$changes" ] || [ -n "$why" ]; then
    include_body="true"
  else
    include_body="false"
  fi
fi

Determine footer inclusion:

if [ "$include_footer" = "auto" ]; then
  if [ -n "$breaking" ] || [ -n "$closes" ] || [ -n "$fixes" ]; then
    include_footer="true"
  else
    include_footer="false"
  fi
fi

Step 4: Generate Subject Line

Read and execute generate-subject.md:

# Build subject arguments
subject_args="subject type:$type"
[ -n "$scope" ] && subject_args="$subject_args scope:$scope"
[ -n "$description" ] && subject_args="$subject_args description:\"$description\""

# Invoke subject generation
subject_result=$(bash -c "cd /home/danie/projects/plugins/architect/open-plugins/plugins/git-commit-assistant/commands/message-generation && cat generate-subject.md")

# Extract generated subject line
subject_line="<generated subject>"

Store subject line:

COMMIT_MESSAGE="$subject_line"

Step 5: Generate Body (if needed)

If include_body is true, read and execute write-body.md:

if [ "$include_body" = "true" ]; then
  # Build body arguments
  body_args="body"

  if [ -n "$changes" ]; then
    body_args="$body_args changes:\"$changes\""
  elif [ -n "$files" ]; then
    # Derive changes from files
    body_args="$body_args changes:\"$files\""
  fi

  [ -n "$why" ] && body_args="$body_args why:\"$why\""

  # Invoke body generation
  body_result=$(bash -c "cd /home/danie/projects/plugins/architect/open-plugins/plugins/git-commit-assistant/commands/message-generation && cat write-body.md")

  # Extract generated body
  body_content="<generated body>"

  # Append to message (with blank line)
  COMMIT_MESSAGE="$COMMIT_MESSAGE

$body_content"
fi

Step 6: Generate Footer (if needed)

If include_footer is true, read and execute add-footer.md:

if [ "$include_footer" = "true" ]; then
  # Build footer arguments
  footer_args="footer"
  [ -n "$breaking" ] && footer_args="$footer_args breaking:\"$breaking\""
  [ -n "$closes" ] && footer_args="$footer_args closes:$closes"
  [ -n "$fixes" ] && footer_args="$footer_args fixes:$fixes"

  # Invoke footer generation
  footer_result=$(bash -c "cd /home/danie/projects/plugins/architect/open-plugins/plugins/git-commit-assistant/commands/message-generation && cat add-footer.md")

  # Extract generated footer
  footer_content="<generated footer>"

  # Append to message (with blank line)
  COMMIT_MESSAGE="$COMMIT_MESSAGE

$footer_content"
fi

Step 7: Validate Complete Message

Read and execute validate-message.md:

# Invoke validation
validation_result=$(bash -c "cd /home/danie/projects/plugins/architect/open-plugins/plugins/git-commit-assistant/commands/message-generation && cat validate-message.md")

# Parse validation result
validation_status="<VALID|INVALID>"
validation_score="<score>"

Step 8: Format Final Output

Present the complete commit message:

COMPLETE COMMIT MESSAGE GENERATED
═══════════════════════════════════════════════

MESSAGE:
───────────────────────────────────────────────
<subject line>

<body content if present>

<footer content if present>
───────────────────────────────────────────────

COMPONENTS:
───────────────────────────────────────────────
Subject: ✓ Generated (XX chars)
Body: ✓ Generated (X lines) / ⊘ Omitted
Footer: ✓ Generated / ⊘ Omitted

VALIDATION:
───────────────────────────────────────────────
Format: ✓ Conventional Commits
Status: ✓ VALID
Score: XX/100

STATISTICS:
───────────────────────────────────────────────
Total Lines: X
Subject Length: XX/50 chars
Body Lines: X (if present)
Footer Elements: X (if present)

READY TO COMMIT:
───────────────────────────────────────────────
git commit -m "$(cat <<'EOF'
<complete message here>
EOF
)"

═══════════════════════════════════════════════

Output Format

Return structured output with:

  • Complete formatted message
  • Component breakdown
  • Validation results
  • Statistics
  • Ready-to-use git command

Error Handling

Missing required parameters:

ERROR: type parameter is required
Usage: complete type:<type> [scope:<scope>] [files:"<files>"]

Example: complete type:feat scope:auth files:"auth.js,provider.js"

Invalid type:

ERROR: Invalid type 'feature'
Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Validation fails:

WARNING: Generated message has issues
<validation errors>

Message generated but may need manual adjustment.

Insufficient context:

ERROR: Insufficient information to generate message
Provide either:
  - description: explicit description
  - files: files changed for context
  - changes: list of changes made

Example: complete type:feat description:"add authentication"

Integration with Agent

The commit-assistant agent uses this operation as the primary message generation workflow:

1. User: "commit my changes"
   ↓
2. Agent: Analyze changes (/commit-analysis analyze)
   → type=feat, scope=auth, files=[...]
   ↓
3. Agent: Generate complete message (THIS OPERATION)
   → /message-generation complete type:feat scope:auth files:"..."
   ↓
4. Operation: Orchestrate generation
   → Generate subject
   → Generate body (if multiple files)
   → Generate footer (if issues/breaking)
   → Validate complete message
   ↓
5. Return: Complete, validated message
   ↓
6. Agent: Present to user for approval

Usage Examples

Example 1: Simple Commit (Subject Only)

# Input
/message-generation complete type:fix description:"resolve login crash"

# Output
MESSAGE:
fix: resolve login crash

COMPONENTS:
Subject: ✓ (26/50 chars)
Body: ⊘ Omitted (single change)
Footer: ⊘ Omitted (no issues)

VALIDATION: ✓ VALID (100/100)

Example 2: Feature with Multiple Files

# Input
/message-generation complete type:feat scope:auth files:"oauth.js,providers/google.js,providers/github.js"

# Output
MESSAGE:
feat(auth): add OAuth authentication

- Add OAuth2 authentication module
- Implement Google provider
- Implement GitHub provider

COMPONENTS:
Subject: ✓ (36/50 chars)
Body: ✓ Generated (3 lines)
Footer: ⊘ Omitted

VALIDATION: ✓ VALID (95/100)

Example 3: Breaking Change with Issues

# Input
/message-generation complete type:feat scope:api description:"redesign authentication API" breaking:"authentication endpoints changed" closes:100,101

# Output
MESSAGE:
feat(api): redesign authentication API

- Redesign authentication endpoints
- Improve security with OAuth2
- Simplify client integration

BREAKING CHANGE: authentication endpoints changed from /login and
/logout to /auth/login and /auth/logout
Closes #100, #101

COMPONENTS:
Subject: ✓ (42/50 chars)
Body: ✓ Generated (3 lines)
Footer: ✓ Generated (breaking + issues)

VALIDATION: ✓ VALID (100/100)

Example 4: Bug Fix with Context

# Input
/message-generation complete type:fix scope:api files:"user.js" why:"prevent null pointer when user not found" fixes:42

# Output
MESSAGE:
fix(api): resolve null pointer in user endpoint

- Add null check for user lookup
- Return 404 when user not found
- Add error handling

Prevent null pointer exception when user is not found in database.

Fixes #42

COMPONENTS:
Subject: ✓ (46/50 chars)
Body: ✓ Generated (5 lines with context)
Footer: ✓ Generated (issue fix)

VALIDATION: ✓ VALID (100/100)

Example 5: Documentation Update

# Input
/message-generation complete type:docs files:"README.md" description:"add installation instructions"

# Output
MESSAGE:
docs: add installation instructions

COMPONENTS:
Subject: ✓ (36/50 chars)
Body: ⊘ Omitted (docs only)
Footer: ⊘ Omitted

VALIDATION: ✓ VALID (100/100)

Example 6: Explicit Body and Footer Control

# Input
/message-generation complete type:refactor scope:database description:"optimize queries" include_body:true include_footer:false changes:"Add indexes,Optimize joins,Cache results"

# Output
MESSAGE:
refactor(database): optimize queries

- Add database indexes
- Optimize query joins
- Implement result caching

COMPONENTS:
Subject: ✓ (35/50 chars)
Body: ✓ Forced inclusion
Footer: ⊘ Forced omission

VALIDATION: ✓ VALID (95/100)

Best Practices

Provide sufficient context:

  • ✅ type + scope + files (agent can derive details)
  • ✅ type + description + changes (explicit)
  • ❌ type only (insufficient)

Let automation work:

  • ✅ Trust body/footer auto-inclusion logic
  • ❌ Manually force inclusion when not needed

Use breaking and issues:

  • ✅ Always include breaking changes
  • ✅ Always link to issues
  • ❌ Forget to document breaking changes

Validate assumptions:

  • ✅ Review generated message
  • ✅ Check validation results
  • ❌ Blindly commit generated message

Decision Logic

Body inclusion decision tree:

if include_body explicitly set:
  use explicit value
else if multiple files changed (>1):
  include body
else if changes list provided:
  include body
else if why context provided:
  include body
else:
  omit body

Footer inclusion decision tree:

if include_footer explicitly set:
  use explicit value
else if breaking change provided:
  include footer
else if issue numbers provided (closes/fixes):
  include footer
else:
  omit footer

Orchestration Flow

Step-by-step orchestration:

1. Parse parameters
   ↓
2. Validate required (type)
   ↓
3. Derive missing (description from files)
   ↓
4. Determine body/footer inclusion
   ↓
5. Generate subject (always)
   → Invoke: generate-subject.md
   ↓
6. Generate body (if needed)
   → Invoke: write-body.md
   ↓
7. Generate footer (if needed)
   → Invoke: add-footer.md
   ↓
8. Combine all parts
   ↓
9. Validate complete message
   → Invoke: validate-message.md
   ↓
10. Return complete message with validation

Error Recovery

If subject generation fails:

  • Return error immediately
  • Do not proceed to body/footer

If body generation fails:

  • Return subject only
  • Mark body as "generation failed"
  • Continue to footer if needed

If footer generation fails:

  • Return subject + body
  • Mark footer as "generation failed"

If validation fails:

  • Return message anyway
  • Include validation errors
  • Let user decide to fix or use

Performance Considerations

Typical generation time:

  • Subject only: <100ms
  • Subject + body: <200ms
  • Subject + body + footer: <300ms
  • With validation: +50ms

Optimization:

  • Cache repeated operations
  • Minimize script invocations
  • Stream output for large bodies

Advanced Usage

Template-based generation:

# Feature template
complete type:feat scope:$SCOPE template:feature

# Bugfix template
complete type:fix scope:$SCOPE template:bugfix fixes:$ISSUE

From analysis results:

# Agent workflow
analysis=$(/commit-analysis analyze)
type=$(echo "$analysis" | jq -r '.type')
scope=$(echo "$analysis" | jq -r '.scope')
files=$(echo "$analysis" | jq -r '.files | join(",")')

/message-generation complete type:$type scope:$scope files:"$files"

Interactive refinement:

# Generate initial
msg=$(/message-generation complete type:feat scope:auth)

# User: "too long"
# Regenerate with constraint
msg=$(/message-generation complete type:feat scope:auth description:"add OAuth" include_body:false)
Reference in New Issue View Git Blame Copy Permalink