| **Operator (Bernd)** | Owns the agentic ecosystem; decides which patterns become standards. | A reviewable catalog of patterns with evidence; control over what ships to agents. |
| **Coding agent (Claude / Codex / GrokBuild)** | Runs tasks in a repo; both the *source* of session data and the *consumer* of patterns. | To emit session data cheaply; to receive applicable patterns in its native format at session start. |
| **Repo maintainer agent** | The per-repo agent persona (e.g. `agentic-resources`) following AGENTS.md conventions. | Patterns scoped to its repo/domain; integration via existing workplan + state-hub flow. |
| **Reviewer (human or kaizen agent)** | Evaluates candidate patterns before they become standards. | Clear pattern proposals, supporting evidence, and a discuss/approve/reject workflow. |
## 5. Core Concepts (Domain Model)
- **Session** — one bounded run of a coding agent against a repo. Has an agent flavor,
repo, task reference, timeline of events, outcome, and cost (tokens/time).
- **Session Event** — a normalized atomic record within a session: tool call, edit,
test run, error, retry, human intervention, decision, completion.
- **Signal** — a derived indicator extracted from sessions: e.g. *repeated test
failure on same file*, *budget overrun*, *fast clean resolution*, *retry storm*,
*human escalation*.
- **Problem Pattern** — a recurring negative signal cluster ("agents repeatedly fail
X because Y").
- **Success Pattern** — a recurring positive resolution ("doing Z reliably resolves X
cheaply").
- **Solution Pattern** — a curated, reviewed artifact pairing a problem with one or
more recommended resolutions, written agent-flavor-agnostically, with per-flavor
rendering hints.
- **Pattern Application** — the act of distributing a solution pattern into a specific
agent environment (an instruction snippet, a tool, an extension), plus the record of
its effect on later sessions.
## 6. Functional Requirements
### 6.1 Capture (G1)
- **FR-C1** Ingest session transcripts/logs from each supported agent flavor via a
per-flavor **collector adapter**.
- **FR-C2** Normalize raw logs into the common `Session` + `Session Event` schema,
regardless of source flavor.
- **FR-C3** Tag every session with: agent flavor, repo, domain, task/workplan id (if
any), outcome (success/fail/abandoned), and cost metrics (tokens, wall-clock,
retries).
- **FR-C4** Support both **batch import** (historical logs) and **incremental ingest**
(new sessions as they close).
- **FR-C5** Collection must be low-friction and non-blocking — an agent emitting
session data must never slow or break the actual coding task.
### 6.2 Detect (G2)
- **FR-D1** Run signal extractors over normalized sessions to surface problem and
success signals.
- **FR-D2** Cluster recurring signals across sessions/repos/flavors into candidate
Problem Patterns and Success Patterns.
- **FR-D3** For each candidate pattern, attach **evidence**: the supporting sessions,
frequency, affected repos, affected flavors, and estimated cost impact.
- **FR-D4** Flag **cross-flavor** patterns explicitly (a problem seen in Claude that
Codex also hits) — these are the highest-value reuse targets.
### 6.3 Curate (G3)
- **FR-U1** Present candidate patterns for review with their evidence in a
discuss/approve/reject workflow.
- **FR-U2** Allow a reviewer (human or kaizen agent) to promote a candidate into a
**Solution Pattern**: a named, versioned artifact with problem description,
recommended resolution(s), applicability scope, and per-flavor rendering hints.
- **FR-U3** Maintain a **Pattern Catalog** as the source of truth for approved
solution patterns, versioned and stored as files in-repo (consistent with ADR-001:
files originate work, the hub indexes them).
- **FR-U4** Record pattern decisions through the State Hub decision mechanism so
rationale is auditable.
### 6.4 Distribute (G4)
- **FR-X1** Render each approved solution pattern into per-flavor artifacts via
**distributor adapters**:
- Claude → `CLAUDE.md` snippets, skills, or settings/hooks.
