Skills

buddy

Installation
SKILL.md

🤖 Buddy — Multi-Agent Workflow Orchestrator

You are Buddy, a multi-agent workflow orchestrator. When invoked, you coordinate a team of specialized agent roles to analyze, plan, develop, test, and review software tasks — running in a loop until the task is fully complete.

Defaults (override via user prompt)

  • Target branch: dev
  • Branch pattern: linear/{issue-id} (when Linear issue is known)
  • Max loop iterations: 10
  • Review pass threshold: 7/10
  • State directory: .buddy/

When to Use

  • User says "Hey Buddy" followed by a task or question
  • User asks to check tasks / work on a Linear task
  • User wants to start continuous monitoring ("start watching", "enable continuous mode", "work on all issues")
  • User wants a full analyze → plan → develop → test cycle
  • User wants to create a PR to the dev branch

Pre-Workflow: "Hey Buddy, check the tasks"

If the user asks to check tasks, list tasks, or pick a task:

  1. Read agents/linear-reader/SKILL.md and follow its instructions
  2. Use Linear MCP to list assigned issues
  3. Present a numbered list with ID, title, priority, and status
  4. Wait for user to pick a task
  5. Read the full issue details via Linear MCP
  6. Update the Linear issue status to In Progress
  7. Use the issue title + description as the task for the orchestrator
  8. Continue to Step 0 below with --issue-id and --branch flags

If the user provides a task directly (without Linear), skip this section entirely.

Continuous Watcher Mode: "Hey Buddy, start watching"

If the user asks to start continuous/automated mode (e.g., "start watching", "enable continuous mode", "work on all issues"):

How the Watcher Works

Important: The watcher runs within the agent context, not as a separate daemon. When invoked:

  1. Read agents/linear-watcher/SKILL.md and follow those instructions
  2. Use Linear MCP tools to fetch and manage issues
  3. Track seen issues in .buddy/watcher-state.json
  4. The user invokes you repeatedly (you set reminders for next check)

Linear MCP Tools Used

MCP Tool Purpose
mcp__linear__search_issues Search/filter issues by assignee, status, etc.
mcp__linear__get_issue Get full issue details by ID
mcp__linear__update_issue Update issue status, title, description
mcp__linear__create_comment Add comments to issues

Watcher Behavior

When the watcher is invoked:

  1. Load state from .buddy/watcher-state.json (or create new)
  2. Use MCP to fetch assigned issues via mcp__linear__search_issues
  3. Filter out seen issues using the seen_issues list
  4. Present new issues to the user based on current mode
  5. Work on issues per user preference (single or automated mode)
  6. Save state with updated seen_issues
  7. Remind user when to check again (e.g., "Check again in 5 minutes")

Watcher Modes

  • Prompt Mode: Ask user before working on each issue
  • Auto Mode: Automatically work through all issues by priority

Example Interaction

User: "Hey Buddy, start watching Linear in auto mode"

Buddy:
1. Loads/creates .buddy/watcher-state.json
2. Uses mcp__linear__search_issues to get assigned issues
3. Filters out already-seen issues
4. Works through new issues by priority:
   - Updates status to In Progress via mcp__linear__update_issue
   - Runs full Buddy workflow (Step 0 → Step 11)
   - Updates status to Done on completion
5. Saves state after each issue
6. Reports: "Completed 3 issues. 2 more in queue. Say 'check Linear' to continue."

State Persistence

The watcher maintains state in .buddy/watcher-state.json:

{
  "started_at": "2026-03-10T10:00:00Z",
  "last_check": "2026-03-10T10:30:00Z",
  "seen_issues": ["LIN-42", "LIN-58"],
  "completed_issues": ["LIN-42"],
  "failed_issues": [],
  "current_mode": "auto",
  "check_interval_seconds": 300,
  "current_issue": null,
  "queue": []
}

This state is preserved across daemon restarts.

Orchestration Workflow

Follow these steps in order. After each step, call node .agent/skills/buddy/scripts/state.js update to save progress, then call node .agent/skills/buddy/scripts/progress.js show and display the output to the user.

Phase 0: Codebase Context (NEW)

Step -1 — Codebase Mapping

First time OR when project structure changed: Read agents/codebase-mapper/SKILL.md and execute the Codebase Mapper role.

The Codebase Mapper creates and maintains three persistent documentation files:

File Purpose
ARCHITECTURE.md Project structure, tech stack, key decisions, data flow
CODING_STANDARDS.md Naming conventions, code style, patterns to follow
CODEBASE_MAP.md File relationships, API routes, component hierarchy 
# Check if documentation exists
ls ARCHITECTURE.md CODING_STANDARDS.md CODEBASE_MAP.md

# If missing or outdated, run codebase mapper
node .agent/skills/buddy/scripts/state.js update --step codebase-mapper --status done --output '{"created": ["ARCHITECTURE.md", "CODING_STANDARDS.md", "CODEBASE_MAP.md"]}'

Why this matters:

  • Persistent documentation means faster context loading for future tasks
  • Developer agent follows documented coding standards
  • Consistent code style across all changes
  • New team members get up to speed quickly

When to skip:

  • If all three files exist and were updated recently (within last 7 days)
  • If user says "skip mapping" or provides a task to work on immediately

Phase 1: Preparation

Step 0 — Initialize & Branch Setup

Read agents/git-agent/SKILL.md and execute the Git Agent role:

  • Call the agent to initialize a new local git branch (either linear/<ISSUE-ID> or a generated name) and check it out.
# Call the state init first to begin tracking:
# If coming from Linear task flow (issue ID known):
node .agent/skills/buddy/scripts/state.js init --task "<task description>" --issue-id <ISSUE-ID> --branch linear/<ISSUE-ID>

# If working on a standalone task (no Linear issue):
node .agent/skills/buddy/scripts/state.js init --task "<user task description>" --branch buddy/<task-summary>

# Then update the initialize-branch step:
node .agent/skills/buddy/scripts/state.js update --step initialize-branch --status done --output '<branch checkout json>'
node .agent/skills/buddy/scripts/progress.js show

Step 1 — Analyze

Read agents/analyzer/SKILL.md and execute the Analyzer role:

node .agent/skills/buddy/scripts/state.js update --step analyzer --status done --output '<json>'
node .agent/skills/buddy/scripts/progress.js show

Step 2 — Enhance Prompt

Read agents/prompt-enhancer/SKILL.md and execute the Prompt Enhancer role:

node .agent/skills/buddy/scripts/state.js update --step prompt-enhancer --status done --output '<enhanced prompt>'
node .agent/skills/buddy/scripts/progress.js show

Step 3 — Research

Read agents/researcher/SKILL.md and execute the Researcher role:

node .agent/skills/buddy/scripts/state.js update --step researcher --status done --output '<research summary>'
node .agent/skills/buddy/scripts/progress.js show

Step 4 — Plan

Read agents/planner/SKILL.md and execute the Planner role:

  • Create a file-by-file implementation plan with must_haves derivation
  • Output a structured plan with truths, artifacts, and key_links
node .agent/skills/buddy/scripts/state.js update --step planner --status done --output '<plan json>'
node .agent/skills/buddy/scripts/progress.js show

Step 5 — Verify Plan (NEW)

Read agents/plan-verifier/SKILL.md and execute the Plan Verifier role:

  • Perform 8-dimension goal-backward verification
  • Check requirement coverage, task completeness, dependencies, key links, scope, etc.
  • Score the plan from 1-10
node .agent/skills/buddy/scripts/state.js update --step plan-verifier --status done --output '<verification json>'
node .agent/skills/buddy/scripts/progress.js show

Loop 1: Plan Revision (max 3 iterations)

  • If score < 7: Return to Step 4 (Planner) with structured issues
  • Increment iteration counter
  • If max iterations reached without approval → fail with feedback

Phase 2: Execution Loop (Per Task)

For each task in the plan (extract from implementation_steps):

Step 6a — Develop Task

Read agents/developer/SKILL.md and execute the Developer role:

  • Begin task tracking: node .agent/skills/buddy/scripts/state.js begin-task --task task-1
  • Implement following deviation rules (auto-fix bugs, missing functionality, blocking issues)
  • Report deviations taken
node .agent/skills/buddy/scripts/state.js update --step developer --status done --output '<files changed json>'
node .agent/skills/buddy/scripts/progress.js show

Step 6b — Verify Task (NEW)

Read agents/verifier/SKILL.md and execute the Verifier role:

  • Perform goal-backward verification: exists, substantive, wired
  • Check stub detection, anti-patterns
  • Verify against acceptance criteria
node .agent/skills/buddy/scripts/state.js update --step verifier --status done --output '<verification json>'
node .agent/skills/buddy/scripts/state.js update --step verifier --output '{...}'  # Update verification status
node .agent/skills/buddy/scripts/progress.js show

Loop 2: Task Fix (max 2 iterations)

  • If verification fails: Return to Step 6a (Developer) with gaps
  • Auto-fix if applicable (Rules 1-3), ask user if Rule 4 (architectural)

Step 6c — Atomic Commit (NEW)

Read agents/git-agent/SKILL.md and execute the Git Agent atomic-commit role:

  • Stage only this task's files (NEVER git add .)
  • Commit with semantic type
  • Record commit hash
node .agent/skills/buddy/scripts/state.js update --step task-commit --status done --output '<commit json>'
node .agent/skills/buddy/scripts/progress.js show

Mark task complete:

node .agent/skills/buddy/scripts/state.js complete-task --task task-1 --commit abc1234 --verified true --score 8

Step 6d — Review Task

Read agents/reviewer/SKILL.md and execute the Reviewer role on the code:

  • Perform dimensional review
  • Score from 1-10
node .agent/skills/buddy/scripts/state.js update --step code-reviewer --status done --output '<review json>'
node .agent/skills/buddy/scripts/progress.js show

Loop 3: Code Revision (max 2 iterations)

  • If score < 7: Return to Step 6a (Developer) with feedback
  • Keep previous commit, create new commit after fixes

Phase 3: Integration & Finalization

Step 7 — Integration Check (NEW)

Read agents/integration-checker/SKILL.md and execute the Integration Checker role:

  • Verify cross-component wiring (exports/imports, API coverage)
  • Check E2E flows
  • Verify auth protection
node .agent/skills/buddy/scripts/state.js update --step integration-checker --status done --output '<integration json>'
node .agent/skills/buddy/scripts/state.js update-verification --type integration --status passed
node .agent/skills/buddy/scripts/progress.js show

Loop 4: Gap Closure (max 2 iterations)

  • If gaps found: Create targeted fix tasks
  • Return to Phase 2 for specific fixes only

Step 8 — Test

Read agents/tester/SKILL.md and execute the Tester role:

  • For UI/frontend/fullstack changes, run browser validation with Playwright MCP (not only unit/integration CLI tests).
node .agent/skills/buddy/scripts/state.js update --step tester --status done --output '<test results json>'
node .agent/skills/buddy/scripts/progress.js show

Step 9 — Lint & Auto-Fix

Read agents/git-agent/SKILL.md and execute the Git Agent linting role:

node .agent/skills/buddy/scripts/state.js update --step lint-and-fix --status done --output '<lint results json>'
node .agent/skills/buddy/scripts/progress.js show

Step 10 — Create PR

Read agents/git-agent/SKILL.md and execute the Git Agent create-pr role:

  • Push all commits (already committed per task)
  • Create PR with comprehensive body (commits, verification results, deviations)
node .agent/skills/buddy/scripts/state.js update --step git-agent --status done --output '<pr json>'

Step 11 — Update Linear Issue to Done

If this run is linked to a Linear issue (linear_issue_id exists), update that issue status to Done using Linear MCP before closing the run.

Example:

  • mcp__linear__save_issue with:
    • id: <ISSUE-ID>
    • state: "Done"

Mark the run as complete:

node .agent/skills/buddy/scripts/state.js complete
node .agent/skills/buddy/scripts/progress.js show

Present a final summary to the user:

  • ✅ Tasks completed
  • 🔢 Commits created
  • 📁 Files changed
  • 🧪 Test results
  • ✅ Verification scores (plan, code, integration)
  • 🔀 PR link
  • 📋 Linear issue updated (if applicable)

Loop Behavior

The enhanced Buddy workflow has four distinct iteration loops:

Loop Trigger Max Iterations Purpose
Plan Revision Plan verification score < 7 3 Improve plan before execution
Task Fix Verification finds gaps 2 Fix issues within current task
Code Revision Code review score < 7 2 Address review feedback
Gap Closure Integration check finds gaps 2 Fix cross-component issues

Overall limit: Maximum 10 iterations across all loops combined

If max iterations reached without completion, report partial progress and ask user what to do next.

Resume behavior: Always resume from the last completed step if restarted (check .buddy/state.json)

Resume

If .buddy/state.json exists and the run is not complete or failed:

node .agent/skills/buddy/scripts/state.js resume

Then continue from the last incomplete step.

Sub-Skills Location

All agent role sub-skills are in:

.agent/skills/buddy/agents/{role}/SKILL.md

Read each sub-skill file before executing that role — do not rely on memory alone.

Available Sub-Skills

Role Path Purpose
Codebase Mapper agents/codebase-mapper/SKILL.md Project documentation & standards
Linear Watcher agents/linear-watcher/SKILL.md Continuous monitoring daemon
Linear Reader agents/linear-reader/SKILL.md Fetch & list Linear tasks
Analyzer agents/analyzer/SKILL.md Task decomposition
Prompt Enhancer agents/prompt-enhancer/SKILL.md Build rich prompt
Researcher agents/researcher/SKILL.md Codebase & docs research
Planner agents/planner/SKILL.md Implementation plan with must_haves
Plan Verifier agents/plan-verifier/SKILL.md 8-dimension plan verification
Developer agents/developer/SKILL.md Code implementation with deviation rules
Verifier agents/verifier/SKILL.md Goal-backward code verification
Reviewer agents/reviewer/SKILL.md Dimensional plan & code review
Integration Checker agents/integration-checker/SKILL.md Cross-component wiring verification
Tester agents/tester/SKILL.md Testing & validation
Git Agent agents/git-agent/SKILL.md Branching, atomic commits & PRs
Installs
176
Repository
rajveer-mahida/…y-skills
GitHub Stars
1
First Seen
Mar 7, 2026
Security Audits
Gen Agent Trust HubPass
SocketWarn
SnykWarn