OLS-2882 add spec files into what/how two-layer structure

[joshuawilson]

Create 14 OLS service spec files and add new ones, organized into two layers under .ai/spec/:

what/ (16 behavioral specs + README):
Testable rules defining WHAT the system must do. Technology-neutral,
with [PLANNED: OLS-XXXX] markers for open Jira work. Covers:
system-overview, api, query-processing, agent-modes, conversation-history,
llm-providers, rag, auth, tools, skills, quota, config, security,
observability, prompts, mcp-apps.

how/ (6 architecture specs + README):
HOW the current implementation is structured. Module maps, data flow,
design patterns, extension guides. Covers: project-structure,
query-pipeline, llm-providers, tools, config, cache.

Also updates .ai/jira-*.md files with current open/planned Jira items.

Description

Type of change

• Refactor
• New feature
• Bug fix
• CVE fix
• Optimization
• Documentation Update
• Configuration Update
• Bump-up dependent library
• Bump-up library or tool used for development (does not change the final image)
• CI configuration change
• Konflux configuration change

Related Tickets & Documents

• Related Issue #
• Closes #

Checklist before requesting a review

• I have performed a self-review of my code.
• PR has passed all pre-merge test jobs.
• If it is a core feature, I have added thorough tests.

Testing

• Please provide detailed steps to perform tests related to this code change.
• How were the fix/results from this change verified? Please provide relevant screenshots or results.

[onmete]

Value-add vs. token cost — compare with how ambient-code/platform approached the same problem

I looked at this PR through the lens of the current spec-driven development landscape (Fowler's SDD taxonomy, Anthropic's harness research, PragSpec, Speculate, etc.) and also compared it to ambient-code/platform#1307, which tackled the same goal — giving AI agents better codebase context — but with a very different delivery.

The intent is right. Agents working in this codebase benefit from knowing cross-cutting invariants, intentional behaviors, and planned changes. The what/how split is a thoughtful structure. But the delivery has three problems.

Most content restates the code. how/project-structure.md (324 lines) is what ls and reading imports gives you. what/observability.md lists every Prometheus metric name and type — rg "Counter\|Histogram\|Gauge" ols/app/metrics/ gets the same in one search. what/api.md (778 lines) restates what's in the Pydantic models and endpoint handlers. We already have focused docs/ai/providers.md, docs/ai/config.md, docs/ai/testing.md that cover the non-obvious parts and are referenced from AGENTS.md with "you MUST read" directives. The genuinely valuable content (cross-cutting invariants, intentional-not-a-bug behaviors, [PLANNED: OLS-XXXX] markers) is maybe 10-20% of the 5,035 lines.

Nothing connects these specs to agent workflows. No skill, no AGENTS.md directive, and no hook tells an agent to read .ai/spec/what/tools.md before modifying tool handling. The existing 11 Cursor skills don't reference .ai/spec/ at all. Without a routing layer, these are write-only docs. Contrast with ambient-code#1307, which built 6 review agents that explicitly load co-located docs before running checks, skills that dispatch the agents, hooks that nudge "consider running /amber-review before completing", and evals that verify skill triggering.

Centralized location means specs won't be found or maintained. When an agent works in ols/src/cache/, it won't discover that .ai/spec/how/cache.md exists. When someone refactors DocsSummarizer, they won't see the spec in their diff and won't update it. ambient-code#1307 addressed this by moving their context docs from a centralized .claude/context/ directory into component directories (components/backend/DEVELOPMENT.md, components/backend/ERROR_PATTERNS.md), then linking from CLAUDE.md → component docs → agents → skills → hooks. They also deleted 9 speckit commands (the heavy SDD framework), choosing lighter, co-located, actionable docs instead.

What I'd suggest:

1. Co-locate with the code. Put spec files next to the modules they describe — either ols/src/cache/spec.md or ols/src/tools/spec.md at the package level. When the agent is working there, it sees the spec. When a dev modifies the module, the spec is in the same diff.

2. Only what the code can't say. Keep the cross-cutting invariants ("approval requires streaming", "delete returns 200 not 404 for non-existent conversations", "approval state is ephemeral by design"). Keep the [PLANNED: OLS-XXXX] markers. Drop the module maps, metric catalogs, class hierarchies, and API schema restating — those are the code itself.

3. Wire it in. Extend the AGENTS.md "you MUST read" section to reference spec files by subsystem. Better yet, add a step to the existing safe-code-change skill: "read the spec for the affected module to understand correct behavior before updating tests." Without activation, the best spec in the world does nothing.

4. Drop how/ entirely. The code is the authoritative source for how it's structured. The existing docs/ai/ task-oriented guides cover the non-obvious implementation patterns already.

[joshuawilson]

Interesting feedback.

I agree that we need a reference in Agents.md so that the AI will know to use it. This was only meant to be step one.

Your approach feels like is it human focused. I was attempting to enable the AI. For example; I give claude a jira ticket and tell it to do the work, agents.md brings in the spec, it reads that for context, it knows where to go to work on the code, and then it can check with the spec and run the tests.

This is just my initial idea. Let's discuss this and work out the details.

[onmete]

Thanks Joshua — we're aligned on the goal. Two things to add.

The single-run workflow is where this gets hard. Jira → read spec → implement → check spec → run tests is a lot of context for one agent session. Anthropic's harness research found this "do everything at once" pattern is the primary agent failure mode — context exhaustion mid-task. Splitting into phases gives each agent run a focused context window:

• Feature spec / decompose — agent reads Jira feature, explores codebase, produces structured stories (human approves before Jira creation)
• Plan — agent reads story + relevant spec + explores codebase → produces implementation plan (human checkpoint)
• Deliver — agent implements, raises PR, self-reviews, fixes — all automated against the plan
• Review — agent checks diff against spec invariants and conventions

I've started landing these as skills in lightspeed-team-harness#7 (ols-feature-spec, ols-decompose, ols-plan, ols-deliver). The human provides inputs and approves at gates; the agents do the work. Those skills are the natural consumers of spec content — each phase loads only what it needs.

This shapes where specs should live and how big they should be. In a phased workflow, the implement agent is working in ols/src/cache/ — it needs the 5-line invariant about that module, not the 778-line API spec. Small co-located specs (per package or per module) serve phased workflows naturally. The centralized .ai/spec/ structure optimizes for the single-run model, which is the one that breaks down at scale.

The genuinely valuable content here — cross-cutting invariants, intentional-not-a-bug behaviors, [PLANNED: OLS-XXXX] markers — is great. It just needs to be distilled from the current volume and shaped to match the workflow that will consume it.

[joshuawilson]

My idea has been a phased approach. So I think we are on the same page there.

For the dev phase I think it starts with giving the AI a jira ticket, letting it plan and then execute a solution. After it is finished the human reviews.

If that is the case, I don't understand how specs in features work. Maybe a hybrid approach with some at the root and some in the features?

I do agree that some of this may be token heavy. However, if you wanted to ask AI to rewrite the whole thing with, for example, a completely new ephemeral agent approach, you would need it at the root level.

[onmete]

/lgtm
/approve

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: onmete

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [onmete]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[openshift-ci]

@joshuawilson: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.