bttoxin-pipeline/.claude/skills/ralph-runner/SKILL.md

name, description

name	description
ralph-runner	BtToxin Pipeline development with Ralph autonomous AI agent. Actions: start, monitor, stop, status, commit, push. Features: 16-task concurrency, genome/protein analysis, i18n support, Docker deployment, CRISPR-Cas预留. Domain: bttiaw.hzau.edu.cn

Ralph Runner - BtToxin Pipeline Development

Autonomous AI-powered development using Ralph for the BtToxin Pipeline project.

Prerequisites

Check if Ralph is installed:

which ralph || ls ~/.local/bin/ralph-claude-code/ralph_loop.sh

If Ralph is not installed, install it:

~/.local/bin/claude-switch/tools/ralph-install-external.sh

Verify Ralph project files exist:

ls -la PROMPT.md @fix_plan.md specs/requirements.md

---

How to Use This Skill

When user requests BtToxin Pipeline development (implement, build, fix, add, create), follow this workflow:

Step 1: Check Current Project Status

# Check git status
git status

# Check Ralph status
ralph --status

# View current task list
cat @fix_plan.md

Step 2: Start Ralph Loop

Recommended: With monitoring dashboard

ralph --monitor

Without monitoring (background process)

ralph

With call limit

ralph --monitor --calls 50  # Limit to 50 calls per hour

Step 3: Monitor Progress

# Check status
ralph --status

# View logs
tail -f logs/ralph.log

# Check response analysis
cat status.json | jq .

Step 4: Manual Operations (when needed)

Commit changes

git add .
git commit -m "feat(module): descriptive message"

Push to remote

git push

Reset Ralph circuit breaker

ralph --reset-circuit

Check circuit breaker status

ralph --circuit-status

---

Ralph Configuration

Environment Variables

# Set provider (glm, minimax, local, etc.)
export CLAUDE_PROVIDER=minimax

# Set model
export CLAUDE_MODEL=MiniMax-M2.1

# Set max iterations
export RALPH_MAX_ITERATIONS=20

Ralph Home Directory

• Commands: ~/.local/bin/
• Templates: ~/.ralph/templates/
• Scripts: ~/.ralph/

---

Ralph Project Files

File	Purpose
PROMPT.md	Ralph development instructions (REQUIRED)
@fix_plan.md	Prioritized task list
specs/requirements.md	Technical specifications
@AGENT.md	Build/test/deploy commands

---

Common Workflows

Workflow 1: Start New Development Session

# 1. Pull latest changes
git pull

# 2. Check Ralph status
ralph --status

# 3. Start monitoring
ralph --monitor

Workflow 2: Review Completed Work

# 1. Check git log
git log --oneline -10

# 2. View changed files
git diff HEAD~1

# 3. Check @fix_plan.md progress
grep -E '^\[.\]' @fix_plan.md | wc -l

Workflow 3: Continue After Interruption

# 1. Check status
ralph --status

# 2. Resume if needed
ralph  # or ralph --monitor

Workflow 4: Emergency Stop

# Ctrl+C to stop monitoring
# Or kill process
pkill -f ralph_loop.sh

---

Project-Specific Guidelines

Current Development Priority

Based on @fix_plan.md, current priorities are:

1. P0 - Frontend i18n: ✅ Completed (vue-i18n, navigation, pages)
2. P0 - Upload Enhancement: ✅ Completed (single file, genome/protein toggle)
3. P0 - Task Status: ✅ Completed (queue status, progress)
4. P1 - FastAPI Backend: Next focus
5. P1 - Concurrency Control: Next focus
6. P2 - Docker Deployment: Later focus

Completed Features

• Vue 3 frontend with Element Plus
• vue-i18n (Chinese/English)
• Navigation bar (Home, About, Submit, Status, Tool Guide)
• File upload (.fna/.fa/.fasta/.faa)
• Single file restriction
• Genome/Protein toggle
• Task status pages
• Tool Info page (Shoter methodology, no Digger mentioned)

Pending Features

• FastAPI backend (main.py, tasks.py)
• 16 concurrent task limit
• Redis task queue
• API endpoints (/api/tasks, /api/tasks/{id})
• Docker deployment
• Traefik configuration
• CRISPR-Cas预留 (crispr_cas/ directory)

---

Testing Guidelines

Ralph follows these testing rules:

1. Testing effort: ~20% of total effort
2. Priority: Implementation > Documentation > Tests
3. Coverage: 85% for new code
4. Focus: Core functionality first

---

Troubleshooting

"Prompt file 'PROMPT.md' not found"

# Ensure you're in the project directory
cd /vol1/1000/docker_server/traefik/web/zly
ls -la PROMPT.md

"Ralph not installed"

# Install Ralph
~/.local/bin/claude-switch/tools/ralph-install-external.sh

Ralph stuck in loop

# Reset circuit breaker
ralph --reset-circuit

# Check circuit status
ralph --circuit-status

tmux session lost

# List sessions
tmux list-sessions

# Reconnect
tmux attach -t ralph-watch

# Or create new session
tmux new -s ralph-watch
ralph-monitor

---

Project Structure

web/zly/
├── PROMPT.md              # Ralph instructions
├── @fix_plan.md           # Task list
├── @AGENT.md              # Build commands
├── specs/
│   └── requirements.md    # Tech specs
├── frontend/              # Vue 3 SPA
│   ├── src/
│   │   ├── locales/       # i18n files
│   │   ├── views/         # Pages
│   │   └── components/    # Components
│   └── package.json
├── web/backend/           # FastAPI (to be built)
├── scripts/               # Pipeline scripts
├── docker/                # Docker configs
└── external_dbs/          # BtToxin database

---

Deployment Targets

Target	URL	Status
Development	localhost:5173/8000	✅ Frontend ready
Test	bttiaw.hzau.edu.cn	🔄 In progress
Production	bttiaw.hzau.edu.cn	⏳ Pending

---

Key Contacts

• Project: BtToxin Pipeline
• Domain: bttiaw.hzau.edu.cn
• Maintainer: Claude Code with Ralph