The Workflow

Kodebase provides two AI agents that work together to transform ideas into working code: Scout for planning and Sherpa for implementation.

Overview

The Kodebase workflow follows a natural progression:

Idea → Scout → Artifacts → Sherpa → Code → Completion

1. Scout helps you plan by asking questions and generating structured specs
2. Sherpa helps you implement by providing context and guidance during coding
3. kb CLI ties everything together with commands for workflow management

Scout: The Planning Agent

Scout transforms vague ideas into structured, actionable artifacts. It's designed for the planning phase when you know what you want to build but haven't figured out the details.

How Scout Works

1. Start with an idea - Describe what you want to build in natural language
2. Answer questions - Scout asks clarifying questions to understand scope
3. Review the spec - Scout generates a structured specification
4. Generate artifacts - Scout creates initiative, milestone, and issue artifacts

Example Scout Session

You: I want to add user authentication to my app

Scout: I'll help you plan that. Let me ask a few questions:

1. What authentication methods do you need?
   (email/password, OAuth providers, magic links, etc.)

2. Do you need role-based access control?

3. What's your tech stack for the backend?

You: Email/password and Google OAuth. Yes to roles (admin, user).
     Backend is Node.js with Express.

Scout: Based on your answers, here's the proposed spec:

## User Authentication System

### Scope
- Email/password registration and login
- Google OAuth integration
- Role-based access (admin, user roles)
- JWT-based session management

### Milestones
1. Core Auth Infrastructure
2. OAuth Integration
3. Role Management

Should I generate the artifacts?

Scout Commands

Scout is accessed through MCP tools that your AI assistant can use:

Tool	Purpose
scout_start_session	Begin planning a new feature
scout_submit_answers	Answer clarifying questions
scout_validate_spec	Check spec completeness
scout_generate_artifacts	Create YAML artifacts
scout_get_guidance	Get phase-appropriate help

Sherpa: The Implementation Agent

Sherpa provides context and guidance during the implementation phase. It knows what you're working on and can help your AI assistant make informed decisions.

How Sherpa Works

1. Get status - See what's ready to work on
2. Start an issue - Get full context for implementation
3. Get guidance - Access quality gates and best practices
4. Complete work - Submit for review when done

Example Sherpa Session

You: What should I work on next?

Sherpa: Here's your current status:

Ready to start:
- H.1.3: Implement JWT token validation

In progress:
- H.1.2: Session management (PR #42 open)

You: Let me start H.1.3

Sherpa: Starting H.1.3: Implement JWT token validation

Context:
- This issue implements token validation middleware
- Depends on H.1.1 (completed) for token generation
- Blocks H.1.4 (API route protection)

Acceptance Criteria:
1. Validate JWT signature and expiration
2. Extract user info from token payload
3. Handle invalid/expired tokens gracefully
4. Add to request context for downstream use

Suggested approach:
1. Create middleware function in src/middleware/auth.ts
2. Use existing JWT_SECRET from environment
3. Follow error handling patterns from H.1.1

Sherpa Commands

Sherpa is accessed through MCP tools:

Tool	Purpose
sherpa_get_status	See ready and in-progress work
sherpa_get_context	Get full context for an issue
sherpa_start_issue	Begin work on an issue
sherpa_get_guidance	Get implementation guidance

The kb CLI

The kb CLI ties Scout and Sherpa together with workflow commands:

Initialize a Project

kb init

Creates .kodebase/ directory and initial configuration.

Start Work on an Issue

kb start H.1.3

This command:

1. Creates a feature branch (H.1.3)
2. Opens a draft PR
3. Updates artifact state to in_progress
4. Copies issue context to clipboard

Submit for Review

kb submit

This command:

1. Pushes your changes
2. Marks PR ready for review
3. Updates artifact with implementation notes

Check Status

kb status

Shows current work status and what's ready to start.

Putting It Together

Here's a complete workflow example:

1. Plan with Scout

You: I want to add a notification system

Scout: [asks questions, generates spec]
Scout: Created artifacts:
- N: Notification System (initiative)
- N.1: Core Infrastructure (milestone)
- N.1.1: Database schema (issue)
- N.1.2: Notification service (issue)
- N.1.3: Email provider integration (issue)

2. Start Implementation

kb start N.1.1

3. Code with Context

You: I'm working on N.1.1, what should I know?

Sherpa: [provides full context, acceptance criteria, suggestions]

4. Complete and Submit

git add .
git commit -m "feat: add notification database schema"
kb submit

5. Continue to Next Issue

kb start N.1.2

Next Steps

• Learn about IDE Integration for seamless AI assistance
• Get started with the Installation Guide
• See detailed CLI Commands reference