Quickstart

This guide walks you through the complete Kodebase workflow - from planning an idea with Scout to implementing it with Sherpa.

Prerequisites

Make sure you have:

• Installed Kodebase (MCP server configured)
• An AI assistant with MCP support (Cursor, Claude Code, etc.)
• A project initialized with kb init

Part 1: Planning with Scout

Scout helps you transform a rough idea into structured, actionable artifacts.

Step 1: Start a Planning Session

Tell your AI assistant what you want to build:

I want to add a notification system to my app

Your AI assistant will call scout_start_session to begin the planning process:

{
  "idea": "Add a notification system to my app",
  "domain": "notification-system"
}

Expected output:

✓ Session started: scout-1733842800-abc123
📁 Created: .kodebase/docs/specs/notification-system/draft.md

Initial questions to understand your idea:
1. What problem does this solve for your users?
2. Who are the primary users of this feature?
3. What does success look like?
4. What's the minimum scope for a first version?

Step 2: Answer Clarifying Questions

Scout asks questions in phases to understand your requirements. Answer naturally:

User: The notification system should alert users about important events.
      Primary users are app admins and regular users.
      Success means users never miss critical updates.
      MVP: email notifications for critical events only.

Your AI submits answers via scout_submit_answers:

{
  "sessionId": "scout-1733842800-abc123",
  "answers": [
    { "questionId": "q1", "answer": "Alert users about important events" },
    { "questionId": "q2", "answer": "App admins and regular users" },
    { "questionId": "q3", "answer": "Users never miss critical updates" },
    { "questionId": "q4", "answer": "Email notifications for critical events" }
  ]
}

Expected output:

Progress: 40% complete (4/10 questions)
Status: needs_more_info

Follow-up questions:
- What types of events should trigger notifications?
- How should users configure their notification preferences?

Step 3: Refine the Specification

Continue answering questions until Scout has enough information:

User: Events: new orders, payment failures, system alerts.
      Users should have a settings page to enable/disable each type.

When ready, Scout validates the spec via scout_validate_spec:

Expected output:

Validation Results:
✓ Core functionality: 95% complete
✓ User experience: 90% complete
⚠ Edge cases: 60% - Consider: What happens during email service downtime?
⚠ Integrations: Missing - Which email provider will you use?

Summary: Spec is 85% complete. Ready for approval with minor gaps.

Step 4: Generate Artifacts

Once approved, Scout generates YAML artifacts via scout_generate_artifacts:

Expected output:

Generated artifacts:

📁 .kodebase/artifacts/N.notification-system/
├── N.yml                          # Initiative
├── N.1.core-infrastructure/
│   ├── N.1.yml                    # Milestone: Core Infrastructure
│   ├── N.1.1.database-schema.yml  # Issue: Database schema
│   ├── N.1.2.notification-service.yml
│   └── N.1.3.email-integration.yml
└── N.2.user-preferences/
    ├── N.2.yml                    # Milestone: User Preferences
    └── N.2.1.settings-page.yml

Next steps:
1. Review the generated artifacts
2. Use sherpa_get_status to see what's ready to implement

Part 2: Implementation with Sherpa

Sherpa helps you implement artifacts by providing context, guidance, and tracking progress.

Step 5: Check What's Ready

Ask your AI assistant what you should work on:

What issues are ready to start?

Your AI calls sherpa_get_status:

Expected output:

{
  "ready_issues": [
    {
      "id": "N.1.1",
      "title": "Database schema for notifications",
      "priority": "high",
      "estimation": "S",
      "acceptance_criteria_count": 3
    }
  ],
  "in_progress_issues": [],
  "summary": "1 issue ready to start. Next: N.1.1 (Database schema) - high priority."
}

Step 6: Get Implementation Context

Before coding, get full context for the issue:

I want to work on N.1.1

Your AI calls sherpa_get_context:

{
  "issue_id": "N.1.1"
}

Expected output:

Issue: N.1.1 - Database schema for notifications

Summary: Create the database tables to store notification records

Acceptance Criteria:
1. notifications table with: id, user_id, type, message, created_at, read_at
2. notification_preferences table with: user_id, notification_type, enabled
3. Proper indexes for user_id lookups

Parent Milestone: N.1 - Core Infrastructure (0% complete)
Parent Initiative: N - Notification System

Guidance:
- Phase 1: Create migration files
- Phase 2: Add model definitions
- Phase 3: Write tests for CRUD operations

Quality Gates:
✓ Tests pass (pnpm test)
✓ Types check (pnpm check-types)
✓ Acceptance criteria addressed

Step 7: Start Work on the Issue

Use the CLI to create a branch and draft PR:

kb start N.1.1

Expected output:

Starting work on N.1.1...
✓ Created branch: N.1.1
✓ Created draft PR: #42
✓ Updated artifact state to in_progress
✓ Context copied to clipboard

Paste the context into your AI assistant to begin implementation.

Step 8: Implement the Feature

Work with your AI assistant to implement the feature. The context from Step 6 tells it exactly what to build.

Help me implement the notification database schema based on the acceptance criteria

Your AI uses the context to write code that satisfies the acceptance criteria.

Step 9: Submit for Review

When implementation is complete and tests pass:

kb submit

Expected output:

Submitting N.1.1 for review...
✓ All quality gates passed
✓ PR #42 marked ready for review
✓ Artifact updated with implementation_notes

What happens next:
• Reviewers will be notified
• PR approval triggers completion cascade
• Artifact marked completed on merge

The Complete Flow

┌─────────────────────────────────────────────────────────────┐
│                      PLANNING (Scout)                        │
├─────────────────────────────────────────────────────────────┤
│  Idea → Questions → Answers → Validate → Artifacts          │
│                                                              │
│  scout_start_session → scout_submit_answers →               │
│  scout_validate_spec → scout_generate_artifacts              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   IMPLEMENTATION (Sherpa)                    │
├─────────────────────────────────────────────────────────────┤
│  Status → Context → Start → Code → Submit                   │
│                                                              │
│  sherpa_get_status → sherpa_get_context →                   │
│  kb start → [implement] → kb submit                          │
└─────────────────────────────────────────────────────────────┘

Tips for Success

1. Be specific in your answers - The more detail you provide to Scout, the better your artifacts will be
2. Follow the artifact hierarchy - Start with issues that have no blockers (check blocked_by field)
3. Run quality gates before submit - pnpm test, pnpm check-types, pnpm lint
4. Add implementation notes - Document what you built and any insights for future work

Next Steps

• Scout Workflow Guide - Deep dive into planning
• Sherpa Workflow Guide - Advanced implementation patterns
• CLI Reference - All available commands
• Core Concepts - Artifact hierarchy and lifecycle