Skip to content
Oka Docs

Team rollout

Oka’s intelligence compounds with usage. A solo developer gets value on day one; a team of ten gets qualitatively different (and better) intelligence within weeks.

Phase 1: Solo adoption (day 1)

Goal: Prove that agents stop repeating your mistakes.

  1. Install @oka-core/reason in your MCP client (quickstart)
  2. Add basic CLAUDE.md instructions
  3. Work normally for a week — let events accumulate
  4. Trigger a consolidation run
  5. Call context on an area you’ve worked on — see the intelligence

What you’ll notice: After a few days, context starts returning useful results. Agents stop making the same mistakes you’ve already discovered and fixed.

Phase 2: Team adoption (week 2-4)

Goal: Shared organizational intelligence across the team.

  1. Share the API key with your team (or provision individual keys)
  2. Have teammates install @oka-core/reason in their clients
  3. Add CLAUDE.md instructions to the shared repository
  4. Establish a tagging convention (see workspaces)

What changes: Context queries now include learnings from other team members’ sessions. When someone discovers that the auth middleware breaks under load, every agent on the team knows it immediately after consolidation runs.

Key metric: Cross-session learning usage — how often agents use learnings from other people’s sessions. This is the signal that organizational intelligence is working.

Phase 3: Org-wide intelligence (month 2+)

Goal: Engineering leadership visibility into systematic friction.

  1. Roll out to all teams using AI agents
  2. Review auto-generated backlog items — PBIs ranked by evidence from actual agent friction
  3. Use patterns to identify systematic issues (e.g., “auth causes the most downstream blockers”)
  4. Set up enforcement for teams that need higher compliance

What emerges: Patterns visible at the org level that no individual could see. “Three different teams independently worked around the same missing API this month.” That kind of intelligence only comes from organizational-scale data.

Common pitfalls

Not enough write events

The most common failure mode is agents that query context but don’t write back. Intelligence is a two-way street:

  • context → read organizational knowledge
  • decision / observe / deviation → contribute back

If your team only reads, the knowledge base stales. Add explicit write instructions to CLAUDE.md and review enforcement options.

Expecting instant results

Consolidation takes time. New events need to be processed into learnings. If someone records an observation now, it might take an hour before consolidation runs and that observation is distilled into a queryable learning.

For urgent insights, use semantic_search — it queries raw events directly, without waiting for consolidation.

Ignoring feedback

The feedback tool is the fastest way to improve result quality. A team that consistently marks learnings as useful/not useful will see dramatically better context results within weeks. A team that never gives feedback will see the same generic ranking indefinitely.