Core Concepts

Kodebase organizes project work through artifacts - structured YAML files that describe what you're building. This page explains the core concepts you need to understand.

Artifacts

An artifact is a YAML file that describes a unit of work. Every artifact has:

• Metadata - Title, priority, estimation, assignee, relationships
• Content - Summary, acceptance criteria, implementation notes
• Events - Lifecycle transitions with timestamps and actors

metadata:
  title: User authentication system
  priority: high
  estimation: M
  assignee: developer@example.com
  schema_version: 0.0.1
  relationships:
    blocked_by:
      - A.1.1
    blocks:
      - A.1.3
  events:
    - event: draft
      timestamp: 2024-01-15T10:00:00Z
      actor: developer@example.com
      trigger: artifact_created

content:
  summary: Implement OAuth-based authentication with JWT tokens
  acceptance_criteria:
    - Users can sign up with email/password
    - Users can login with Google OAuth
    - JWT tokens expire after 24 hours
    - Refresh token rotation implemented

Artifact Hierarchy

Artifacts are organized in a three-level hierarchy:

Initiative

The top-level artifact representing a major goal or project phase. Initiatives are broad in scope and may span weeks or months.

Example: "Alpha MCP Server" - Ship the first version of the MCP server with core functionality.

.kodebase/artifacts/
└── H.alpha-mcp-server/
    └── H.yml  # Initiative artifact

Milestone

A significant deliverable within an initiative. Milestones group related issues and represent meaningful progress checkpoints.

Example: "Core Planning Tools" - Implement Scout agent for idea-to-spec workflow.

.kodebase/artifacts/
└── H.alpha-mcp-server/
    └── H.1.core-planning-tools/
        └── H.1.yml  # Milestone artifact

Issue

The atomic unit of work. Issues have clear acceptance criteria and can typically be completed in a single work session.

Example: "Implement session management" - Create session store with persistence.

.kodebase/artifacts/
└── H.alpha-mcp-server/
    └── H.1.core-planning-tools/
        ├── H.1.yml
        ├── H.1.1.session-management.yml  # Issue
        └── H.1.2.question-generation.yml # Issue

ID System

Every artifact has a unique ID that encodes its position in the hierarchy:

ID	Type	Meaning
H	Initiative	Initiative H
H.1	Milestone	First milestone of initiative H
H.1.3	Issue	Third issue of milestone H.1

IDs are:

• Stable - Once assigned, they don't change
• Hierarchical - Parent relationship is encoded in the ID
• Human-readable - Easy to reference in conversations and commits

Artifact Lifecycle

Every artifact moves through a defined lifecycle:

draft → ready → in_progress → completed
                     ↓
                  blocked

States

State	Description
draft	Initial state, artifact is being defined
ready	All dependencies met, work can begin
in_progress	Actively being worked on
blocked	Waiting on dependencies
completed	Work finished, acceptance criteria met

Events

State transitions are recorded as events with full context:

events:
  - event: draft
    timestamp: 2024-01-15T10:00:00Z
    actor: developer@example.com
    trigger: artifact_created

  - event: ready
    timestamp: 2024-01-15T10:30:00Z
    actor: agent.cascade@github
    trigger: dependencies_met

  - event: in_progress
    timestamp: 2024-01-16T09:00:00Z
    actor: developer@example.com
    trigger: branch_created
    metadata:
      branch: H.1.1
      pr_number: 42

Relationships

Artifacts can have dependency relationships:

blocked_by

This artifact cannot start until the listed artifacts are completed.

relationships:
  blocked_by:
    - H.1.1  # Must complete session management first
    - H.1.2  # Must complete question generation first

blocks

This artifact must complete before the listed artifacts can start.

relationships:
  blocks:
    - H.1.4  # Validation depends on this
    - H.1.5  # Draft update depends on this

Kodebase automatically tracks these relationships and updates artifact states when dependencies are resolved.

Implementation Notes

When an artifact is completed, implementation notes capture learnings:

implementation_notes:
  result: Successfully implemented OAuth with Google and GitHub providers
  tags:
    - authentication
    - oauth
    - security
  challenges:
    - challenge: Token refresh race conditions
      solution: Implemented mutex lock on refresh endpoint
  insights:
    - Consider adding rate limiting to auth endpoints
    - JWT validation should happen at gateway level

These notes become valuable context for future work on related features.

Next Steps

• Learn about The Workflow with Scout and Sherpa agents
• See how IDE Integration connects everything
• Get started with the Installation Guide