Sherpa Workflow

Sherpa is Kodebase's implementation agent. It provides your AI assistant with the context and guidance needed to implement features defined by Scout.

How Sherpa Works

1. Check status - See what issues are ready to work on
2. Start an issue - Create a branch and begin implementation
3. Get context - Sherpa provides relevant specs, dependencies, and guidance
4. Complete the work - Follow acceptance criteria and quality gates
5. Submit for review - Validate and mark PR ready

Checking Work Status

Use sherpa_get_status to see:

• Ready issues - Issues you can start working on
• In-progress work - Your current active work
• Completable artifacts - Milestones/initiatives ready to close

Your AI assistant calls this automatically when you ask "what should I work on?"

Starting an Issue

When you're ready to implement an issue:

kb start A.1.1

This command:

1. Creates a new branch named A.1.1 from main
2. Adds an in_progress event to the artifact
3. Creates a draft PR with issue details
4. Pushes the branch to remote

Getting Implementation Context

Sherpa provides rich context through sherpa_get_context:

• Issue details - Title, summary, acceptance criteria
• Parent context - Related milestone and initiative info
• Spec references - Links to relevant specifications
• Implementation guidance - Tips based on artifact type

Quality Gates

Before submitting, Sherpa guides you through quality gates:

pnpm test          # Run tests
pnpm check-types   # Type checking
pnpm lint          # Code linting
pnpm build         # Build verification

Adding Implementation Notes

Before submitting, add implementation_notes to the artifact YAML:

implementation_notes:
  result: "Added dark mode toggle with system preference detection"

  tags:
    - "ui"
    - "accessibility"

  challenges:
    - challenge: "CSS custom properties didn't work in older Safari"
      solution: "Added fallback values for older browsers"

  insights:
    - "prefers-color-scheme media query is well-supported now"

This documentation helps future AI assistants learn from your work.

Submitting for Review

When implementation is complete:

kb submit

This command:

1. Validates implementation_notes exists
2. Adds an in_review event to the artifact
3. Marks the PR as ready for review

Pre-Submit Checklist

Use sherpa_pre_submit_checklist to get a structured checklist:

1. ✓ All acceptance criteria addressed
2. ✓ Tests pass
3. ✓ Types check
4. ✓ Lint passes
5. ✓ Build succeeds
6. ✓ Code documented
7. ✓ READMEs updated (if needed)
8. ✓ implementation_notes added
9. ✓ Changes committed
10. ✓ Changeset added (if needed)

Best Practices

Follow Acceptance Criteria

Each issue has specific acceptance criteria. Check them off as you implement to ensure nothing is missed.

Document Challenges

If you encounter difficulties, document them in implementation_notes. This helps:

• Reviewers understand your decisions
• Future AI assistants learn from your experience
• The Monk pattern recognizer improve suggestions

Commit Frequently

Make small, focused commits. This creates a clear history and makes review easier.

Next Steps

• CLI Reference - All CLI commands
• MCP Tools Reference - All Sherpa MCP tools