> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first board

> Walk a feature from raw idea to validated card using the full Pulse pipeline — Ideation, Spec, Sprint, Tasks, and Validation.

# Your first board

This guide walks a single feature — adding a rate-limit to an API — from raw idea to a validated, closed card. Every step uses real Pulse MCP tool names so you can follow along in Claude Code, Cursor, or any connected agent.

By the end you will have:

* An ideation with a scope assessment
* A derived spec with acceptance criteria, business rules, and test scenarios
* A sprint with cards
* A card closed with evidence and a conclusion

***

## Prerequisites

* Pulse installed and serving — see [Install](/install)
* An agent connected via MCP — see [MCP setup](/mcp-setup)

Your agent needs to call `okto_pulse_list_my_boards` to discover the board ID it will use throughout this session.

***

## Step 1 — Create an ideation

Ideations are where raw requests land before any design work begins. Paste your request and let the agent structure it.

**What your agent does:**

```text theme={null}
Create an ideation: "Add per-user rate limiting to the /search endpoint. 
Burst: 20 req/s. Sustained: 5 req/s. Return 429 with Retry-After header."
```

**MCP tool called:** `okto_pulse_create_ideation`

```json theme={null}
{
  "board_id": "a1b2c3d4-...",
  "title": "Per-user rate limiting on /search",
  "description": "Burst limit 20 req/s, sustained 5 req/s. Return 429 + Retry-After.",
  "context": "Currently no rate limiting exists. Load tests show search abuse spikes."
}
```

The agent immediately pulls context from the Knowledge Graph before asking anything:

**MCP tool called:** `okto_pulse_get_ideation_context`

This returns prior decisions, constraints, and related entities already in the KG. If rate limiting was discussed in a previous sprint, the agent cites it here rather than re-deciding.

***

## Step 2 — Resolve ambiguity

The agent runs the **ambiguity-killer protocol**: it asks clarifying questions using choice questions (not free text) to zero out ambiguity before advancing.

**MCP tool called:** `okto_pulse_ask_ideation_choice_question`

```json theme={null}
{
  "ideation_id": "...",
  "question": "Where should rate-limit counters be stored?",
  "choices": ["Redis (shared across instances)", "In-process (per-replica, no shared state)", "Database (durable, slower)"]
}
```

You answer by selecting a choice. The agent records your response:

**MCP tool called:** `okto_pulse_answer_ideation_question`

The agent continues until all ambiguous axes are resolved. Open-ended Q\&A is also available:

**MCP tool called:** `okto_pulse_ask_ideation_question` — for questions that don't fit a choice format.

***

## Step 3 — Evaluate scope

Before advancing, the agent evaluates the ideation on three axes: domain breadth, ambiguity, and dependency risk. This produces a scope assessment that gates the move to Refined.

**MCP tool called:** `okto_pulse_evaluate_ideation`

```json theme={null}
{
  "ideation_id": "...",
  "domains": 2,
  "ambiguity": 1,
  "dependencies": 3,
  "justification": "Touches API middleware and Redis infra. Dependencies on cache invalidation and auth service are flagged."
}
```

**MCP tool called:** `okto_pulse_move_ideation`

```json theme={null}
{
  "ideation_id": "...",
  "status": "refined"
}
```

The ideation is now ready to derive a spec from.

***

## Step 4 — Derive a spec

Deriving a spec converts the structured ideation into a working document with acceptance criteria, functional requirements, and technical requirements pre-populated.

**MCP tool called:** `okto_pulse_derive_spec_from_ideation`

```json theme={null}
{
  "ideation_id": "..."
}
```

The response includes the new spec ID. Everything from the ideation — Q\&A, knowledge entries, KG context — carries forward into the spec.

***

## Step 5 — Build the spec

The spec is where implementation detail is locked down. The agent adds test scenarios, business rules, and API contracts. Each addition links to specific acceptance criteria.

### Add a test scenario

**MCP tool called:** `okto_pulse_add_test_scenario`

```json theme={null}
{
  "spec_id": "...",
  "title": "Rate limit exceeded returns 429",
  "description": "Send 21 sequential requests in 1 second as the same user. The 21st returns HTTP 429 with Retry-After header.",
  "acceptance_criteria_ref": "AC-1"
}
```

### Add a business rule

**MCP tool called:** `okto_pulse_add_business_rule`

```json theme={null}
{
  "spec_id": "...",
  "rule": "Rate-limit counters must be scoped to authenticated user ID, not IP address.",
  "rationale": "IP-based limiting blocks shared office networks. Auth user is the correct identity boundary."
}
```

### Add an API contract

**MCP tool called:** `okto_pulse_add_api_contract`

```json theme={null}
{
  "spec_id": "...",
  "endpoint": "GET /search",
  "response_on_limit": {
    "status": 429,
    "headers": {"Retry-After": "<seconds>"},
    "body": {"error": "rate_limit_exceeded", "retry_after": "<seconds>"}
  }
}
```

The agent queries the KG for similar decisions before finalizing contracts:

**MCP tool called:** `okto_pulse_kg_find_similar_decisions`

If the team decided on a 429 error format two sprints ago, that decision appears here. The agent cites it rather than re-deciding.

***

## Step 6 — Evaluate and advance the spec

The spec evaluation is a qualitative gate. The agent (or a human reviewer) submits a structured assessment before the spec can advance past Approved.

**MCP tool called:** `okto_pulse_submit_spec_evaluation`

```json theme={null}
{
  "spec_id": "...",
  "score": 82,
  "narrative": "Acceptance criteria are complete and testable. Business rule on auth-scoped limits is unambiguous. API contract covers success and failure shapes. Missing: load-test baseline for Redis latency under burst — flagged as a card.",
  "recommendation": "approve"
}
```

**MCP tool called:** `okto_pulse_move_spec`

```json theme={null}
{
  "spec_id": "...",
  "status": "approved"
}
```

***

## Step 7 — Create a sprint

A sprint is a time-boxed slice of spec work. The agent can suggest sprint splits or you can define the objective directly.

**MCP tool called:** `okto_pulse_suggest_sprints`

The agent proposes sprint slices. Accept one or define your own:

**MCP tool called:** `okto_pulse_create_sprint`

```json theme={null}
{
  "spec_id": "...",
  "title": "Rate limiting — Sprint 1: middleware + Redis counter",
  "objective": "Implement the per-user sliding-window counter in Redis and wire it into the /search middleware. 429 returned and test scenario AC-1 passes.",
  "expected_outcome": "All burst-limit test scenarios pass in CI. No auth-service changes required."
}
```

Evaluate the sprint before activating it:

**MCP tool called:** `okto_pulse_submit_sprint_evaluation`

```json theme={null}
{
  "sprint_id": "...",
  "score": 78,
  "narrative": "Scope is deliverable in one sprint. Redis dependency is flagged — Redis must be running in the test environment.",
  "recommendation": "approve"
}
```

**MCP tool called:** `okto_pulse_move_sprint`

```json theme={null}
{
  "sprint_id": "...",
  "status": "active"
}
```

***

## Step 8 — Create and work cards

Cards are the implementation tasks. The agent creates them linked to the active sprint and spec.

**MCP tool called:** `okto_pulse_create_card`

```json theme={null}
{
  "board_id": "...",
  "title": "Implement sliding-window rate limiter middleware",
  "card_type": "normal",
  "spec_id": "...",
  "sprint_id": "..."
}
```

Link the card to the specific test scenario and business rule it implements:

**MCP tool called:** `okto_pulse_link_task_to_scenario`

**MCP tool called:** `okto_pulse_link_task_to_rule`

When implementation starts, the agent retrieves the full task context before writing any code:

**MCP tool called:** `okto_pulse_get_task_context`

This returns the card, linked spec, all business rules, test scenarios, relevant decisions from the KG, and API contracts — the complete picture in one call. The agent uses this to avoid re-reading specs and decisions from chat history.

Move the card through the workflow as work progresses:

**MCP tool called:** `okto_pulse_move_card` — `not_started → started → in_progress`

***

## Step 9 — Close the card with evidence

When implementation is done, the agent closes the card with a structured conclusion. The gate requires a conclusion, a completeness score, and a drift score.

**MCP tool called:** `okto_pulse_update_card`

```json theme={null}
{
  "card_id": "...",
  "conclusion": "Sliding-window counter implemented in Redis using sorted sets. Middleware added to /search route. Returns 429 + Retry-After header when burst or sustained limit exceeded. All three test scenarios pass in CI.",
  "completeness": 95,
  "completeness_justification": "All acceptance criteria covered. Minor gap: Redis TTL cleanup job not yet automated — added as a follow-up card.",
  "drift": 5,
  "drift_justification": "Minor scope addition: added unit test for edge case where user ID is null. Not in original spec but caught during implementation."
}
```

**MCP tool called:** `okto_pulse_move_card` — `in_progress → done`

The gate enforces: conclusion is required, completeness and drift scores are required, both justification fields are required. The agent cannot close the card without all four.

***

## Step 10 — Update test scenario evidence (optional but recommended)

The test theater prevention gate requires structured evidence before a test scenario can be marked as passing.

**MCP tool called:** `okto_pulse_update_test_scenario_status`

```json theme={null}
{
  "spec_id": "...",
  "scenario_id": "...",
  "status": "passed",
  "test_file_path": "tests/middleware/test_rate_limit.py",
  "test_function": "test_burst_limit_returns_429",
  "last_run_at": "2026-05-07T14:30:00Z",
  "output_snippet": "PASSED tests/middleware/test_rate_limit.py::test_burst_limit_returns_429 in 0.42s"
}
```

This prevents test scenarios from being marked as passing without a real test file and function to back them up. The sprint close re-validates this evidence before the sprint can be closed.

***

## Step 11 — Close the sprint

With cards closed and evidence recorded, the sprint can close.

**MCP tool called:** `okto_pulse_move_sprint` — `active → review`

**MCP tool called:** `okto_pulse_submit_sprint_evaluation` — final review evaluation

**MCP tool called:** `okto_pulse_move_sprint` — `review → closed`

***

## What the Knowledge Graph captured

Every decision made during this flow — the Redis storage choice, the 429 response format, the auth-scoped counter rule — is consolidated into the Knowledge Graph automatically. The next ideation that touches rate limiting or Redis will find these decisions and cite them.

**MCP tool called (automatically by the consolidation pipeline):** `okto_pulse_kg_begin_consolidation`, `okto_pulse_kg_add_node_candidate`, `okto_pulse_kg_commit_consolidation`

In the next sprint, when the agent runs:

**MCP tool called:** `okto_pulse_kg_find_similar_decisions`

...it will surface the decisions made here. Decisions survive session resets, model upgrades, and team changes. The graph persists; the chat does not.

***

## Agent setup

The agent connection details — registering agents, scoping permissions, and rotating API keys — are covered in [Connect your agent](/connect-agent).

***

## Next steps

<CardGroup cols={3}>
  <Card title="ADLC pipeline" href="/concepts/sdlc-flow">
    The enforced stage machine behind every step in this guide.
  </Card>

  <Card title="Knowledge Graph" href="/concepts/knowledge-graph">
    How decisions made here persist across sessions.
  </Card>

  <Card title="MCP tool reference" href="/reference/mcp">
    All 216 tools with descriptions and groupings.
  </Card>
</CardGroup>