Skip to main content

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.

Every software idea that enters Pulse travels through six stages before code ships. The stages are not advisory — they are enforced status transitions in the service layer. An agent cannot skip a stage by moving a card directly; it must call the MCP tools that correspond to each transition, and each transition checks its gate before proceeding. This page explains what happens at each stage, what the enforced thresholds are, and what gets written to the Knowledge Graph along the way.

​
The 6-stage pipeline

Each arrow represents a Pulse MCP tool call. The pipeline is linear by default — though multiple ideations, refinements, and sprints can exist on a board simultaneously, each one follows its own path through the stages. Status enums (source: okto-pulse-core/src/okto_pulse/core/models/db.py):
StageStatuses
Ideationdraft → evaluating → refined → done
Refinementdraft → in_progress → review → approved → done
Specdraft → review → approved → validated → in_progress → done
Sprintdraft → active → review → closed
Cardnot_started → started → in_progress ⇄ on_hold → validation → done

​
Stage 1: Ideation

Ideation is the intake stage. You give Pulse a raw request — one sentence or a paragraph — and Pulse surfaces every material gap before anything gets built.The core problem ideation solves: vague requests produce vague specs. Instead of prompting you to write a spec up-front, Pulse asks questions about the gaps it finds in the raw text.What an agent does here:
  1. Create the ideation: okto_pulse_create_ideation
  2. Evaluate scope — three axes, each justified in writing: okto_pulse_evaluate_ideation
  3. Ask ambiguity-killer questions (text or choice): okto_pulse_ask_ideation_question, okto_pulse_ask_ideation_choice_question
  4. Record answers: okto_pulse_answer_ideation_question
  5. Advance when ready: okto_pulse_move_ideation (draft → evaluating → refined)
Gate: Pulse will not advance an ideation with an ambiguity score above the configured threshold. The scope assessment returns three numeric scores (domains, ambiguity, dependencies) with per-axis justification — not just numbers. An ambiguity score of 4/5 means the ideation needs more Q&A before refinement.What gets written to the KG: Nothing is consolidated at ideation. Knowledge attached to an ideation (okto_pulse_add_ideation_knowledge) is available to downstream stages but is not yet promoted to the graph.
The ambiguity-killer protocol is most useful for requests that contain vague verbs (“add authentication”), undefined nouns (“the admin panel”), or implicit scope (“make it faster”). The more precisely you answer the questions here, the more accurate the derived spec will be.

​
Stage 2: Refinement

Refinement is investigation, not paraphrasing. Its job is to read the actual codebase, query the KG for prior decisions, and produce a concrete evidence-backed description of current behavior, constraints, and dependencies.What distinguishes refinement from a chat conversation: the evidence must be citable. Good refinement output includes source file references (path:line), KG query results, runtime logs, and stakeholder answers. An agent that produces vague findings has not completed refinement.What an agent does here:
  1. Create a refinement linked to the ideation: okto_pulse_create_refinement
  2. Query the KG for prior decisions before deciding anything: okto_pulse_kg_find_similar_decisions, okto_pulse_kg_query_natural
  3. Update findings, evidence, and constraints: okto_pulse_update_refinement
  4. Advance when evidence is complete: okto_pulse_move_refinement (draft → in_progress → review → approved)
  5. Derive a spec from the approved refinement: okto_pulse_derive_spec_from_refinement
Gate: Refinement moves to approved only when evidence, findings, and constraints are recorded. The derived spec is pre-populated from refinement output — not written from scratch.What gets written to the KG: Refinement knowledge entries attached via okto_pulse_add_refinement_knowledge become candidates for the consolidation queue when the downstream spec is consolidated.
Pulse rejects “copying stale repo docs without source verification” as an explicit anti-pattern. Refinement evidence must be checked against the current codebase state, not assumed from memory.

​
Stage 3: Spec

The spec is the implementation contract. It answers “what must be true when this ships?” with enough precision that a different agent (or a different session of the same agent) could implement it without guessing.A strong spec includes:
  • Problem statement
  • Acceptance criteria (each linked to at least one test scenario)
  • Functional requirements → business rule linkage
  • Technical requirements
  • Test scenarios with AC coverage
  • Business rules → card linkage
  • API contracts
  • Architecture decisions
  • Non-goals (explicit scope exclusion)
What an agent does here:
  1. Spec is created automatically via okto_pulse_derive_spec_from_ideation or okto_pulse_derive_spec_from_refinement
  2. Add test scenarios with AC linkage: okto_pulse_add_test_scenario
  3. Add business rules: okto_pulse_add_business_rule
  4. Record design decisions with alternatives: okto_pulse_add_decision
  5. Add API contracts: okto_pulse_add_api_contract
  6. Submit evaluation (score + narrative): okto_pulse_submit_spec_evaluation
  7. Submit validation (completeness/assertiveness/ambiguity): okto_pulse_submit_spec_validation
  8. Advance: okto_pulse_move_spec
Spec evaluation gate (score ≥ 80): okto_pulse_submit_spec_evaluation requires a qualitative score and written narrative. The gate for validated → in_progress will not pass if the evaluation score is below threshold.Spec validation gate: okto_pulse_submit_spec_validation requires three threshold checks — completeness, assertiveness, and ambiguity scores with written evidence. Success locks the spec content. An agent cannot modify a validated spec without explicitly unlocking it via approved_to_draft or validated_to_draft.Spec → done gate (4 coverage checks + 2 structural checks):
  1. 100% acceptance criteria → test scenario coverage
  2. FR → BR linkage complete
  3. BR → Card linkage complete
  4. AC → Scenario linkage complete
  5. Configurable decision coverage threshold met
  6. No non-bug tasks still open
What gets written to the KG on consolidation: Spec is the richest KG source. The consolidation pipeline writes Decision, Criterion, Constraint, Requirement, APIContract, and TestScenario nodes, plus belongs_to, derives_from, tests, and implements edges. These nodes persist in the per-board Kùzu graph (~/.okto-pulse/boards/{id}/graph.lbug) and survive the next session.
The spec is where most of the KG value is created. Every okto_pulse_add_decision call with alternatives and justification becomes a queryable Decision node that future agents can retrieve via okto_pulse_kg_find_similar_decisions before making the same call again.

​
Stage 4: Sprint

A sprint slices a validated spec into reviewable work. Sprints define the scope, objective, and expected outcome for a batch of cards. They are not a time-box — they are a logical delivery slice.What an agent does here:
  1. Get sprint suggestions from the spec: okto_pulse_suggest_sprints
  2. Create the sprint with objective and expected outcome: okto_pulse_create_sprint
  3. Assign cards to the sprint: okto_pulse_assign_tasks_to_sprint
  4. Resolve sprint Q&A before execution: okto_pulse_ask_sprint_question, okto_pulse_answer_sprint_question
  5. Submit sprint evaluation before activating: okto_pulse_submit_sprint_evaluation
  6. Advance: okto_pulse_move_sprint (draft → active)
Sprint evaluation gate: okto_pulse_submit_sprint_evaluation is the quality gate for review → closed. A sprint cannot close without a recorded evaluation. This prevents sprints from being silently abandoned.What gets written to the KG: Sprint consolidation writes Entity and Requirement nodes representing the sprint scope, plus belongs_to edges linking sprint cards back to spec decisions.

​
Stage 5: Cards (Tasks and Bugs)

Cards are execution units. Each card must be self-contained — an implementer agent should be able to work from a card alone without reading the spec from scratch.Card types: normal, test, bugWhat an agent does before starting a card:
  1. Get the full context bundle: okto_pulse_get_task_context — returns card + spec + business rules + test scenarios + decisions + KG context in one call
  2. Copy needed artifacts: okto_pulse_copy_knowledge_to_card, okto_pulse_copy_mockups_to_card, okto_pulse_copy_architecture_to_card
  3. Advance: okto_pulse_move_card (not_started → started → in_progress)
Card → validation → done gate:When implementation is complete, the card moves to validation (not directly to done). To move from validation → done, the closing agent must provide:
  1. conclusion — written summary of what was done
  2. completeness (0–100) — with written justification (e.g., “90 — pagination implemented but not yet perf-tested”)
  3. drift (0–100) — deviation from the original spec, with justification (e.g., “10 — switched from JWT to session tokens per spec amendment”)
  4. If the Task Validation Gate is enabled: an independent reviewer must call okto_pulse_submit_task_validation — auto-fail on threshold violations even if the reviewer recommends approval
Test theater prevention gate: okto_pulse_update_test_scenario_status requires structured evidence: test_file_path, test_function, last_run_at, and output_snippet or test_run_id. Marking a test “passed” without evidence is rejected. Sprint close re-validates this evidence on every passed scenario.Bug card gate (test-first):
  1. A new failing test scenario must exist before the bug card can move to in_progress
  2. A linked test card must exist
Card status transitions: not_started → started → in_progress ⇄ on_hold → validation → doneWhat gets written to the KG: Completed cards contribute Learning nodes (lessons from implementation) and Bug nodes (linked via validates edges to the test scenarios that caught them). The learning_from_bugs query (okto_pulse_kg_get_learning_from_bugs) surfaces these across future sessions.

​
Stage 6: Validation

Validation is the independent quality checkpoint. It is separated from implementation by design — the agent that built the card cannot be the same agent that validates it (enforced by permission presets).Permission presets (source: okto-pulse-core/src/okto_pulse/core/models/db.py:PermissionPreset):
PresetGate permissions
ExecutorCan move cards not_started → validation. Cannot submit validation gates.
ValidatorCan submit spec_validation, spec_evaluation, sprint_evaluation, task_validation. Can move cards validation → done.
QACan write test scenarios. Cannot submit any gate.
Spec WriterOwns ideation/refinement/spec content. Cannot move specs past approved.
What a validator agent does:
  1. Read the card with context: okto_pulse_get_task_validation
  2. Verify the implementation evidence (logs, test output, screenshots)
  3. Submit with structured evidence: okto_pulse_submit_task_validation
Good validation evidence: exact commands run, relevant logs or output, test names, known limitations, unresolved risks.What gets written to the KG: After a successful validation, okto_pulse_kg_commit_consolidation writes the durable decision and learning nodes for this card into the board’s Kùzu graph.

​
Knowledge Graph integration

Every stage produces artifacts that feed the Knowledge Graph. The KG is not a side effect — it is the durable memory layer that makes the next project faster. 11 node types written across the pipeline:
Node typeTypically written at
DecisionSpec (design decisions), Ideation (choice question answers)
CriterionSpec (acceptance criteria, test scenarios)
ConstraintSpec, Refinement (technical constraints)
AssumptionRefinement (documented assumptions)
RequirementSpec (FRs, TRs), Sprint (scope)
EntitySpec (named entities), Sprint
APIContractSpec (API contracts)
TestScenarioSpec (test scenarios)
BugCard stage (bug cards)
LearningCard stage (post-implementation)
AlternativeSpec (alternatives considered in decisions)
10 relationship types connect these nodes: supersedes, contradicts, derives_from, relates_to, mentions, depends_on, violates, implements, tests, validates. What an agent can query mid-task: 
okto_pulse_kg_query_natural("What auth approach did we decide?")
okto_pulse_kg_find_similar_decisions("session token storage")
okto_pulse_kg_find_contradictions()
okto_pulse_kg_get_supersedence_chain(decision_id)
okto_pulse_kg_get_learning_from_bugs("auth module")
These queries run against the embedded Kùzu graph at ~/.okto-pulse/boards/{id}/graph.lbug. They are deterministic (no LLM) and survive across sessions. The KG uses HNSW vector indexes on five node types for semantic search.

​
Why this differs from a kanban

A kanban answers “what is the current status of work?” Pulse answers “did the work satisfy the original intent?” — and refuses to close work that cannot prove it did. The structural differences:
KanbanPulse
Columns represent status onlyStatus transitions enforce coverage gates
Cards are created directlyCards derive from validated specs
Work is done when the developer says soWork requires structured conclusion + completeness + drift evidence
Context lives in chat historyContext lives in KG nodes that outlast sessions
Moving a card requires one clickMoving a card from validation → done requires a validator agent with evidence
No memory of past decisionsPrior decisions surface before new ones are made
The 198 MCP tools Pulse exposes are not shortcuts around this structure — they are the structure. An agent calls okto_pulse_move_card and the service layer checks every gate condition before the status changes.
The traceability report (okto_pulse_get_traceability_report) returns the full lineage: spec → business rules → technical requirements → test scenarios → cards → validations. If a card exists that cannot be traced back to a spec requirement, it should not exist.

​
Where to go next

Quickstart

Walk through the full pipeline with a real example in 5 minutes.

Knowledge Graph

How the KG stores and serves decision history across sessions.

MCP Setup

Connect your agent to the 198 MCP tools that drive this pipeline.

Ideation

Deep-dive into Stage 1 — ambiguity reduction and scope assessment.

Spec

Deep-dive into Stage 3 — writing implementation contracts.

Validation

Deep-dive into Stage 6 — independent quality gates.
Last modified on May 8, 2026