This project uses **beads** for feature/issue tracking and **Ralph artifacts** for session continuity.
Sign in to like and favorite skills
This project uses beads for feature/issue tracking and Ralph artifacts for session continuity.
Architecture Note: The
beads_clientYou MUST follow this workflow. It is NOT optional.
# 1. Operational knowledge (~60 lines max) cat AGENTS.md 2>/dev/null || echo "No AGENTS.md" # 2. Current feature plan (delete if stale) cat IMPLEMENTATION_PLAN.md 2>/dev/null || echo "No plan" # 3. Recent history (last 30 lines only) tail -30 IMPLEMENTATION_HISTORY.md 2>/dev/null # 4. Get progress stats beads_client stats
1. LOAD CONTEXT → Read artifacts in order above 2. CLAIM FEATURE → beads_client claim (atomic, returns issue JSON) 3. CREATE BRANCH → feature/{id}-{title-slug} 4. GAP ANALYSIS → Create IMPLEMENTATION_PLAN.md 5. IMPLEMENT → Follow the plan 6. VALIDATE → ./validate.sh (MUST PASS - blocks close) 7. SELF-REVIEW → No TODOs, no placeholders, tests work 8. CLOSE → beads_client close <id> 9. MERGE + EXIT → Merge to main, delete branch, push, EXIT SESSION
Agent exits after completing one feature. agent_app starts a fresh session for the next feature.
These files persist knowledge across sessions. READ THEM FIRST.
| Artifact | Purpose | Created By |
|---|---|---|
| Operational guide: commands, patterns, gotchas | Initializer |
| Current feature: gap analysis, task breakdown | Coding Agent |
| Archive of completed feature plans | Coding Agent |
Contains operational knowledge that EVERY session should read:
Contains the plan for the CURRENT feature:
This file is overwritten for each feature and archived to IMPLEMENTATION_HISTORY.md when complete.
Use
beads_client claim# Claim next available feature (atomic - server handles locking) CLAIM_RESULT=$(beads_client claim) if [ $? -ne 0 ]; then echo "No features available - exiting" exit 0 fi # Parse the claimed issue FEATURE_ID=$(echo "$CLAIM_RESULT" | jq -r '.id') FEATURE_TITLE=$(echo "$CLAIM_RESULT" | jq -r '.title' | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-' | cut -c1-30) # Create feature branch BRANCH="feature/${FEATURE_ID}-${FEATURE_TITLE}" git checkout -b "$BRANCH" echo "Claimed $FEATURE_ID on branch $BRANCH"
The
claimin_progressAfter claiming and creating your branch:
Before closing, validation MUST pass (non-negotiable backpressure):
# Run validation (uses project-specific commands from AGENTS.md) ./validate.sh # If validate.sh doesn't exist, use these defaults: npm run lint && npm run typecheck && npm test # Self-review: verify no TODOs, placeholders, or incomplete code # Only after ALL pass: beads_client close "$FEATURE_ID"
If validation fails, FIX THE ISSUES. DO NOT close with failing validation.
After closing the feature, merge to main and exit:
# Archive plan to history if [ -f IMPLEMENTATION_PLAN.md ]; then { echo "" echo "---" echo "## Completed: $(date '+%Y-%m-%d %H:%M')" cat IMPLEMENTATION_PLAN.md } >> IMPLEMENTATION_HISTORY.md && rm IMPLEMENTATION_PLAN.md fi # Commit final changes git add . git diff --cached --quiet || git commit -m "Implement: $FEATURE_TITLE" # Merge to main git fetch origin main git checkout main && git pull origin main git merge "$BRANCH" --no-ff -m "Merge: $FEATURE_TITLE" git push origin main # Delete feature branch (local and remote) git branch -d "$BRANCH" git push origin --delete "$BRANCH" 2>/dev/null || true # Session complete - exit and let agent_app start fresh session exit 0
If you encounter a blocker:
beads_client update "$FEATURE_ID" --status=blocked beads_client comments add "$FEATURE_ID" "Blocked because: <reason>"
Commit partial work and exit. agent_app will start a new session.
All commands route through the host API for coordination and atomic operations.
| Command | Description |
|---|---|
| Claim next available feature (atomic, server-locked) |
| View feature details |
| List all open features |
| List features being worked on |
| Mark feature as complete |
| Show progress statistics |
| Add a comment to a feature |