Scout Workflow

Scout is Kodebase's planning agent. It takes your rough ideas and transforms them into structured, actionable specifications that your AI assistant can use during implementation.

How Scout Works

1. Start with an idea - Describe what you want to build in natural language
2. Answer clarifying questions - Scout asks targeted questions to understand scope
3. Review generated artifacts - Scout creates initiatives, milestones, and issues
4. Approve and proceed - Once approved, artifacts are written to your repository

Starting a Scout Session

In your AI assistant (Cursor, Claude Code, etc.), describe your idea:

I want to add a dark mode toggle to my application

Your AI will invoke the scout_start_session MCP tool automatically.

The Planning Phases

Phase 1: Gathering

Scout asks clarifying questions about:

• Scope: What exactly should this feature include?
• Technical constraints: Are there specific technologies to use?
• Dependencies: Does this depend on other work?
• Success criteria: How do we know it's done?

Phase 2: Refining

Based on your answers, Scout:

• Creates a draft specification
• Identifies potential gaps
• Suggests acceptance criteria
• Proposes artifact structure

Phase 3: Validating

You review the proposed artifacts:

• Initiative: High-level goal with vision and scope
• Milestones: Major deliverables with clear outcomes
• Issues: Individual tasks with acceptance criteria

Phase 4: Approved

Once you approve, Scout:

• Writes YAML artifacts to .kodebase/artifacts/
• Commits the artifacts to your repository
• Signals Sherpa is ready for implementation

Artifact Hierarchy

Scout creates a three-level hierarchy:

Initiative (A)           - "User Authentication System"
├── Milestone (A.1)      - "Core Authentication"
│   ├── Issue (A.1.1)    - "Login form component"
│   ├── Issue (A.1.2)    - "Session management"
│   └── Issue (A.1.3)    - "Password reset flow"
└── Milestone (A.2)      - "OAuth Integration"
    ├── Issue (A.2.1)    - "Google OAuth provider"
    └── Issue (A.2.2)    - "GitHub OAuth provider"

Best Practices

Be Specific About Scope

Bad: "Add authentication" Good: "Add email/password authentication with password reset. No OAuth for now."

Answer Questions Thoughtfully

Scout's questions help create better artifacts. Take time to think through:

• Edge cases
• Error handling
• User experience details

Review Before Approving

Check that:

• Acceptance criteria are testable
• Dependencies are identified
• Scope matches your intent

Next Steps

• Sherpa Workflow - Implement your planned work
• MCP Tools Reference - All Scout MCP tools