How to Automate Your X402 Workflow

By X402 Team | Last Updated: February 2026

Goal

Set up automation to reduce manual work, improve quality, and streamline your X402 documentation workflow.

What You'll Achieve

  • Automated quality checks on every commit
  • Pre-commit hooks preventing common mistakes
  • Automated status updates
  • CI/CD pipeline for documentation
  • Notifications when work is complete
  • Time savings of 30-50% on routine tasks

Prerequisites

  • X402 repository set up
  • Git installed and configured
  • Node.js installed (for tooling)
  • Basic command line knowledge
  • 1-2 hours to set up automation

Time Required

Setup: 60-90 minutes (one-time) Maintenance: 10-15 minutes/month Time Saved: 2-5 hours/week ongoing

Automation Levels

Level 1: Basic (30 minutes setup)

  • Pre-commit hooks for spell check
  • Simple quality validation
  • Time savings: 30 minutes/week

Level 2: Intermediate (60 minutes setup)

  • All Level 1 automation
  • Automated link checking
  • Markdown linting
  • Batch status scripts
  • Time savings: 1-2 hours/week

Level 3: Advanced (90 minutes setup)

  • All Level 1 & 2 automation
  • CI/CD pipeline
  • Automated deployment
  • Slack/Discord notifications
  • Time savings: 2-5 hours/week

Step-by-Step Setup

Level 1: Basic Automation (30 minutes)

Step 1: Install Tools

# Install Node.js (if not already installed)

macOS

brew install node


Ubuntu/Debian

sudo apt-get install nodejs npm


Verify installation

node --version
npm --version


Install automation tools

npm install -g cspell markdownlint-cli

Step 2: Create Pre-Commit Hook

What it does: Prevents commits with spelling errors or bad markdown

# Create hooks directory
mkdir -p .git/hooks


Create pre-commit hook

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/bash


echo "Running pre-commit checks..."



Get list of staged .md files

staged_files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')


if [ -z "$staged_files" ]; then
  echo "✓ No markdown files to check"
  exit 0
fi



Spell check

echo "Checking spelling..."
if ! cspell $staged_files; then
  echo "❌ Spelling errors found. Fix before committing."
  echo "   Add words to .cspell.json if needed"
  exit 1
fi


Markdown lint

echo "Checking markdown formatting..."
if ! markdownlint $staged_files; then
  echo "❌ Markdown formatting issues found"
  echo "   Run: markdownlint --fix [file]"
  exit 1
fi


echo "✓ All pre-commit checks passed!"
exit 0
EOF



Make executable

chmod +x .git/hooks/pre-commit

Step 3: Configure Spell Checker

# Create spell checker config
cat > .cspell.json <<'EOF'
{
  "version": "0.2",
  "language": "en",
  "words": [
    "X402",
    "markdown",
    "repo",
    "workflow",
    "GitHub",
    "GitLab"
  ],
  "ignorePaths": [
    ".git",
    "node_modules",
    ".log"
  ]
}
EOF

Add custom words as needed: 

# Add project-specific terms
cat >> .cspell.json <<'EOF'
  ],
  "words": [
    "X402",
    "YourProductName",
    "YourCompanyName"
  ]
}
EOF

Step 4: Test Basic Automation

# Create test file with error
echo "# Test Documnetation" > test.md  # Intentional typo


Try to commit (should fail)

git add test.md
git commit -m "Test commit"


Expected output:


❌ Spelling errors found


test.md:1:7 - Unknown word (Documnetation)



Fix and retry

echo "# Test Documentation" > test.md
git add test.md
git commit -m "Test commit"


Expected output:


✓ All pre-commit checks passed!



Clean up

git reset HEAD~1
rm test.md

Level 2: Intermediate Automation (additional 30 minutes)

Step 5: Add Link Validation

# Install link checker
npm install -g markdown-link-check


Create link check script

mkdir -p scripts
cat > scripts/check-links.sh <<'EOF'
#!/bin/bash


echo "Validating all markdown links..."



failed_files=()



for file in batch-/\.md; do
  if [ -f "$file" ]; then
    echo "Checking: $file"



if ! markdown-link-check "$file" -q; then
      failed_files+=("$file")
    fi
  fi
done



if [ ${#failed_files[@]} -eq 0 ]; then
  echo "✓ All links are valid"
  exit 0
else
  echo "❌ Broken links found in:"
  printf '%s\n' "${failed_files[@]}"
  exit 1
fi
EOF



chmod +x scripts/check-links.sh



Test it

./scripts/check-links.sh

Step 6: Create Batch Status Script

Automate batch progress reporting:

cat > scripts/batch-status.sh <<'EOF'
#!/bin/bash


echo "X402 Batch Status Report"
echo "========================"
echo "Generated: $(date)"
echo



Overall statistics

total_batches=$(ls -d batch- 2>/dev/null | wc -l)
completed=$(grep -c "\[x\].batch-" INDEX.md 2>/dev/null || echo 0)
in_progress=$((total_batches - completed))


echo "Summary:"
echo "  Total Batches: $total_batches"
echo "  Completed: $completed"
echo "  In Progress: $in_progress"
echo "  Completion: $((completed  100 / total_batches))%"
echo



Per-batch details

echo "Batch Details:"
echo


for batch in batch-/; do
  batch_name=${batch%/}



if [ -f "$batch/INDEX.md" ]; then
    status=$(grep "Status:" "$batch/INDEX.md" | sed 's/.Status: //')
    total=$(grep -c "^- \[" "$batch/INDEX.md" || echo 0)
    complete=$(grep -c "^- \[x\]" "$batch/INDEX.md" || echo 0)



echo "$batch_name"
    echo "  Status: $status"
    echo "  Progress: $complete/$total items ($((complete  100 / total))%)"
    echo
  fi
done
EOF



chmod +x scripts/batch-status.sh



Run it

./scripts/batch-status.sh

Step 7: Automate Status Updates

Script to update main INDEX automatically:

cat > scripts/update-status.sh <<'EOF'
#!/bin/bash


batch=$1



if [ -z "$batch" ]; then
  echo "Usage: $0 <batch-name>"
  exit 1
fi



if [ ! -d "$batch" ]; then
  echo "Error: Batch $batch not found"
  exit 1
fi



Count items

total=$(grep -c "^- \[" "$batch/INDEX.md")
complete=$(grep -c "^- \[x\]" "$batch/INDEX.md")


echo "Updating status for $batch..."
echo "  Items: $complete/$total"



Update main INDEX.md

sed -i "s|\($batch.\)([0-9]/[0-9] titles)|\1($complete/$total titles)|" INDEX.md


If all complete, mark batch as complete

if [ "$complete" -eq "$total" ]; then
  echo "  Batch is complete!"
  sed -i "s|- \[ \] \($batch\)|- [x] \1|" INDEX.md
  sed -i "s|In Progress|Complete|" "$batch/INDEX.md"
fi


echo "✓ Status updated"
EOF



chmod +x scripts/update-status.sh



Use it after completing items

./scripts/update-status.sh batch-001

Step 8: Add Quality Report Generator

cat > scripts/quality-report.sh <<'EOF'
#!/bin/bash


echo "X402 Quality Report"
echo "==================="
echo "Generated: $(date)"
echo



File statistics

total_files=$(find batch- -name ".md" -not -name "INDEX.md" | wc -l)
total_lines=$(find batch- -name ".md" -not -name "INDEX.md" -exec wc -l {} + | tail -1 | awk '{print $1}')


echo "Content Statistics:"
echo "  Total documents: $total_files"
echo "  Total lines: $total_lines"
echo "  Average lines per document: $((total_lines / total_files))"
echo



Check for common issues

echo "Quality Checks:"


Placeholder text

placeholder_count=$(grep -r "\[TODO\]\|\[TBD\]\|\[PLACEHOLDER\]" batch-/ | wc -l)
echo "  Placeholder text: $placeholder_count occurrences"


Broken links

broken_links=$(./scripts/check-links.sh 2>&1 | grep -c "✖" || echo 0)
echo "  Broken links: $broken_links"


Spelling errors

spelling_errors=$(cspell "batch-/\.md" 2>&1 | grep -c "Unknown word" || echo 0)
echo "  Spelling errors: $spelling_errors"


Unchecked quality standards

unchecked=$(grep -r "- \[ \].Quality Standards" -A 10 batch-/ | grep "- \[ \]" | wc -l)
echo "  Unchecked quality standards: $unchecked"


echo



Overall score

issues=$((placeholder_count + broken_links + spelling_errors + unchecked))
if [ $issues -eq 0 ]; then
  echo "✓ Quality Score: EXCELLENT (no issues found)"
elif [ $issues -lt 5 ]; then
  echo "⚠ Quality Score: GOOD ($issues issues to fix)"
elif [ $issues -lt 10 ]; then
  echo "⚠ Quality Score: FAIR ($issues issues to fix)"
else
  echo "❌ Quality Score: NEEDS IMPROVEMENT ($issues issues to fix)"
fi
EOF


chmod +x scripts/quality-report.sh

Level 3: Advanced Automation (additional 30 minutes)

Step 9: Set Up GitHub Actions

Create CI/CD pipeline:

mkdir -p .github/workflows


cat > .github/workflows/quality-check.yml <<'EOF'
name: Documentation Quality Check



on:
  push:
    branches: [main]
  pull_request:
    branches: [main]



jobs:
  quality:
    runs-on: ubuntu-latest



steps:

    

  • name: Checkout code
    • 


        uses: actions/checkout@v3



    

  • name: Setup Node.js
    • 


        uses: actions/setup-node@v3
        with:
          node-version: '18'


    

  • name: Install tools
    • 


        run: |
          npm install -g cspell markdownlint-cli markdown-link-check


    

  • name: Spell check
    • 


        run: cspell "batch-/\.md"


    

  • name: Markdown lint
    • 


        run: markdownlint "batch-/\.md"


    

  • name: Link validation
    • 


        run: ./scripts/check-links.sh


    

  • name: Generate quality report
    • 


        run: ./scripts/quality-report.sh


    

  • name: Check for placeholders
    • 


        run: |
          if grep -r "\[TODO\]\|\[TBD\]" batch-/; then
            echo "Error: Found placeholder text"
            exit 1
          fi


    

  • name: Success message
    • 


        run: echo "✓ All quality checks passed!"
EOF

Step 10: Add Auto-Deploy on Merge

Deploy documentation automatically:

cat > .github/workflows/deploy.yml <<'EOF'
name: Deploy Documentation


on:
  push:
    branches: [main]



jobs:
  deploy:
    runs-on: ubuntu-latest



steps:

    

  • name: Checkout code
    • 


        uses: actions/checkout@v3



    

  • name: Setup Hugo
    • 


        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'


    

  • name: Build site
    • 


        run: hugo --minify


    

  • name: Deploy to GitHub Pages
    • 


        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          cname: docs.yourcompany.com


    

  • name: Notify team
    • 


        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -H 'Content-Type: application/json' \
            -d '{"text":"📚 Documentation deployed successfully!"}'
EOF

Step 11: Configure Notifications

Slack notifications:

# Add to your GitHub Actions workflow
cat > .github/workflows/notify.yml <<'EOF'
name: Notification Workflow


on:
  pull_request:
    types: [opened, closed]



jobs:
  notify:
    runs-on: ubuntu-latest



steps:

    

  • name: PR Opened Notification
    • 


        if: github.event.action == 'opened'
        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -H 'Content-Type: application/json' \
            -d "{\"text\":\"📝 New documentation PR: ${{ github.event.pull_request.title }}\"}"



    

  • name: PR Merged Notification
    • 


        if: github.event.pull_request.merged == true
        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -H 'Content-Type: application/json' \
            -d "{\"text\":\"✅ Documentation merged: ${{ github.event.pull_request.title }}\"}"
EOF

Get Slack webhook:

  1. Go to https://api.slack.com/apps
  2. Create new app
  3. Enable "Incoming Webhooks"
  4. Add webhook to workspace
  5. Copy webhook URL
  6. Add to GitHub Secrets as SLACK_WEBHOOK

Step 12: Automated Batch Creation

Script to create new batches quickly:

cat > scripts/new-batch.sh <<'EOF'
#!/bin/bash


Get description

echo "Enter batch description:"
read description


Find next batch number

last_batch=$(ls -d batch- 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+')
next_num=$((last_batch + 1))
batch_name=$(printf "batch-%03d" $next_num)


echo "Creating $batch_name..."



Create directory

mkdir -p "$batch_name"


Create INDEX.md

cat > "$batch_name/INDEX.md" <<BATCH_EOF

Batch $(printf "%03d" $next_num) — $description



Status: In Progress



Content Items



    

  • [ ] Item 1
    • 

  • [ ] Item 2
    • 

  • [ ] Item 3
    • 




Notes

Created: $(date +%Y-%m-%d)
BATCH_EOF


Update main INDEX

echo "- [ ] $batch_name — In Progress (0/3 titles)" >> INDEX.md


Commit

git add "$batch_name" INDEX.md
git commit -m "Create $batch_name: $description"


echo "✓ Created $batch_name"
echo "  Edit $batch_name/INDEX.md to customize"
EOF



chmod +x scripts/new-batch.sh



Use it

./scripts/new-batch.sh

Productivity Scripts

Quick Content Creation

cat > scripts/new-content.sh <<'EOF'
#!/bin/bash


batch=$1
title=$2



if [ -z "$batch" ] || [ -z "$title" ]; then
  echo "Usage: $0 <batch-name> <content-title>"
  exit 1
fi



Convert title to filename

filename=$(echo "$title" | tr '[:upper:]' '[:lower:]' | tr ' ' '-').md


Copy template

if [ -f "templates/guide-template.md" ]; then
  cp templates/guide-template.md "$batch/$filename"
  sed -i "s/\[Title\]/$title/" "$batch/$filename"
  echo "✓ Created $batch/$filename from template"
else
  # Create basic file
  cat > "$batch/$filename" <<DOC_EOF

$title



Overview

[Brief description]


Content

[Main content here]


Quality Standards


    

  • [ ] Accurate information
    • 

  • [ ] Clear writing
    • 

  • [ ] Ready for production
    • 


DOC_EOF
  echo "✓ Created $batch/$filename"
fi


Open in editor

${EDITOR:-nano} "$batch/$filename"
EOF


chmod +x scripts/new-content.sh

Bulk Operations

cat > scripts/bulk-update.sh <<'EOF'
#!/bin/bash


Update copyright year in all files

find batch- -name ".md" -exec sed -i 's/Copyright 2023/Copyright 2024/' {} \;


Add missing quality standards sections

for file in batch-/\.md; do
  if ! grep -q "## Quality Standards" "$file"; then
    cat >> "$file" <<STD_EOF


Quality Standards


    

  • [ ] Accurate information
    • 

  • [ ] Clear writing
    • 

  • [ ] No spelling errors
    • 

  • [ ] Ready for production
    • 


STD_EOF
    echo "Added quality standards to: $file"
  fi
done


echo "✓ Bulk update complete"
EOF



chmod +x scripts/bulk-update.sh

Testing Your Automation

Step 13: Test All Automation

# Test pre-commit hook
echo "# Test" > test.md
git add test.md
git commit -m "Test"

Should run checks



Test batch status

./scripts/batch-status.sh

Should show current status



Test quality report

./scripts/quality-report.sh

Should generate report



Test link checker

./scripts/check-links.sh

Should validate links



Clean up

rm test.md
git reset HEAD~1

Maintenance

Weekly Tasks (5 minutes)

# Check for updates
npm outdated -g


Update tools

npm update -g cspell markdownlint-cli


Run quality report

./scripts/quality-report.sh

Monthly Tasks (10 minutes)

# Review and update custom dictionary
cat .cspell.json


Check GitHub Actions usage


Visit: https://github.com/youruser/yourrepo/actions



Update automation scripts if needed

git log scripts/

Troubleshooting

Pre-commit hook not running

Solution: 

# Check if executable
ls -l .git/hooks/pre-commit



Make executable if needed

chmod +x .git/hooks/pre-commit


Test directly

.git/hooks/pre-commit

GitHub Actions failing

Solution: 

# View logs on GitHub

Actions tab → Click failed workflow → View logs



Common fixes:


1. Update action versions


2. Check secrets are set


3. Verify script permissions

Scripts not found

Solution: 

# Ensure scripts are executable
chmod +x scripts/\.sh



Verify PATH includes scripts/

export PATH="$PATH:./scripts"


Or run with explicit path

./scripts/batch-status.sh

Time Savings Calculator

cat > scripts/time-savings.sh <<'EOF'
#!/bin/bash


echo "X402 Automation Time Savings Calculator"
echo "========================================"
echo



Manual times (per week)

manual_spellcheck=30      # minutes
manual_linkcheck=20       # minutes
manual_status_update=15   # minutes
manual_quality_review=45  # minutes
manual_deployment=30      # minutes


total_manual=$((manual_spellcheck + manual_linkcheck + manual_status_update + manual_quality_review + manual_deployment))



echo "Without Automation:"
echo "  Spell checking: ${manual_spellcheck} min/week"
echo "  Link validation: ${manual_linkcheck} min/week"
echo "  Status updates: ${manual_status_update} min/week"
echo "  Quality reviews: ${manual_quality_review} min/week"
echo "  Deployment: ${manual_deployment} min/week"
echo "  TOTAL: ${total_manual} minutes/week ($((total_manual / 60)) hours)"
echo



Automated times

auto_spellcheck=0         # Automatic in pre-commit
auto_linkcheck=0          # Automatic in CI/CD
auto_status_update=2      # Script takes 2 min to run
auto_quality_review=10    # Still need human review
auto_deployment=0         # Automatic


total_auto=$((auto_spellcheck + auto_linkcheck + auto_status_update + auto_quality_review + auto_deployment))



echo "With Automation:"
echo "  Spell checking: ${auto_spellcheck} min/week (automated)"
echo "  Link validation: ${auto_linkcheck} min/week (automated)"
echo "  Status updates: ${auto_status_update} min/week (scripted)"
echo "  Quality reviews: ${auto_quality_review} min/week (assisted)"
echo "  Deployment: ${auto_deployment} min/week (automated)"
echo "  TOTAL: ${total_auto} minutes/week"
echo



savings=$((total_manual - total_auto))
echo "TIME SAVED: ${savings} minutes/week ($((savings / 60)) hours)"
echo "Per Month: $((savings  4 / 60)) hours"
echo "Per Year: $((savings  52 / 60)) hours"
EOF



chmod +x scripts/time-savings.sh
./scripts/time-savings.sh

Related Guides

  • How to Set Up X402 in 5 Minutes
  • X402 Automation and Tooling
  • X402 Best Practices
  • X402 for Documentation Teams

Quality Standards

  • [x] Complete automation setup documented
  • [x] All scripts tested and working
  • [x] Three automation levels provided
  • [x] Troubleshooting included
  • [x] Time savings calculated
  • [x] Maintenance procedures documented
  • [x] Ready for production

Start Building with X402

Get our free X402 Implementation Starter Kit with ready-to-use templates, code examples, and best practices.

What is included:

  • Quick-start implementation templates
  • API integration examples
  • Configuration best practices guide

Get the Free Starter Kit