oak-open-curriculum-ecosystem

Structured outward reasoning for analysis, planning, decisions, diagnosis, and design — a direct-trial-first gate, a decision-relevant value-of-information stop gate, and five firing moves (name the kind, frame the problem not the solution, surface the warrant, decide for reversibility, stress-test) that point to the full grammar of thinking for depth. The outward pair to oak-metacognition's inward reflection. Use when facing a gnarly problem, choice, or analysis; especially when investigation or options keep proliferating and you must decide whether to build and observe, keep analysing, stop, or escalate.

Structured outward reasoning for analysis, planning, decisions, diagnosis, and design — a direct-trial-first gate, a decision-relevant value-of-information stop gate, and five firing moves (name the kind, frame the problem not the solution, surface the warrant, decide for reversibility, stress-test) that point to the full grammar of thinking for depth. The outward pair to oak-metacognition's inward reflection. Use when facing a gnarly problem, choice, or analysis; especially when investigation or options keep proliferating and you must decide whether to build and observe, keep analysing, stop, or escalate.

Explore an unshaped concept, phenomenon, recurring incident class, or messy set of observations before solution options or the decision question are well formed. Use when framing options immediately would foreclose the real question; run four alternating metacognition and reason movements to produce a well-formed understanding with warranted, falsifiable proposals. Do not use it as a separate pre-decision pass once the options or decision question are already well formed; continue through the estate's formed-decision workflow instead.

Explore an unshaped concept, phenomenon, recurring incident class, or messy set of observations before solution options or the decision question are well formed. Use when framing options immediately would foreclose the real question; run four alternating metacognition and reason movements to produce a well-formed understanding with warranted, falsifiable proposals. Do not use it as a separate pre-decision pass once the options or decision question are already well formed; continue through the estate's formed-decision workflow instead.

Join a foreign Practice estate and exchange safely with zero prior knowledge of it — the runnable join ceremony for cross-estate work. Fires whenever a session's worktree repo and coordination home are different repos, or the session is about to write into, register presence in, or claim work in any sibling Practice estate's substrate; read-only estate looks are unceremonied, and a solo write into a QUIET sibling estate takes the lighter governance-only path. Enacts the inter-Practice collaboration protocol PDR.

Join a foreign Practice estate and exchange safely with zero prior knowledge of it — the runnable join ceremony for cross-estate work. Fires whenever a session's worktree repo and coordination home are different repos, or the session is about to write into, register presence in, or claim work in any sibling Practice estate's substrate; read-only estate looks are unceremonied, and a solo write into a QUIET sibling estate takes the lighter governance-only path. Enacts the inter-Practice collaboration protocol PDR.

Open a pull request and shepherd it to merge-ready: reviewer-facing description, full-surface harvesting (GraphQL review threads, all comments, all checks, Sonar issues), root-cause-first triage, budgeted watching, re-fetch after every push, and an honest truly-green merge — all checks green, every thread resolved, normal non-admin merge. Use whenever a branch reaches PR closeout or an open PR needs driving to live.

Open a pull request and shepherd it to merge-ready: reviewer-facing description, full-surface harvesting (GraphQL review threads, all comments, all checks, Sonar issues), root-cause-first triage, budgeted watching, re-fetch after every push, and an honest truly-green merge — all checks green, every thread resolved, normal non-admin merge. Use whenever a branch reaches PR closeout or an open PR needs driving to live.

Run the export↔implementation fidelity review for a Claude-Design-converted app: serve the canonical export and the dev server, capture both sides at matched geometry, perceptually diff every declared pair, review the side-by-side report, and record a disposition (fix / deliberate / investigate / matched / superseded) for every finding in the tracked divergence register. Use when judging visual/feature fidelity against a canonical export, before a §D-class sign-off, or when integrating an export refresh.

Run the export↔implementation fidelity review for a Claude-Design-converted app: serve the canonical export and the dev server, capture both sides at matched geometry, perceptually diff every declared pair, review the side-by-side report, and record a disposition (fix / deliberate / investigate / matched / superseded) for every finding in the tracked divergence register. Use when judging visual/feature fidelity against a canonical export, before a §D-class sign-off, or when integrating an export refresh.

The repository's orientation lens — one intent-discerning surface for anyone who wants to understand this repo, get started, or get their bearings. Covers "explain this repo", "tell me about this", "what is this", "give me an overview", "executive summary", "how does X work", "I want to understand the search architecture", "onboard me", "where do I start", "give me a tour", "set me up", and "help me contribute". Discerns the person's interest, angle, and the delivery mode that fits — a pinpoint specific answer, a synthesised area overview, or a paced guided tour — through at most a few friendly conversational questions (never a menu), then delivers, reading all content live from the canonical docs. Machine setup is a distinct, go-ahead-gated capability the tour or an overview can lead into. Use whenever someone is new to the repository or asks to be told about, oriented to, or set up with it.

The repository's orientation lens — one intent-discerning surface for anyone who wants to understand this repo, get started, or get their bearings. Covers "explain this repo", "tell me about this", "what is this", "give me an overview", "executive summary", "how does X work", "I want to understand the search architecture", "onboard me", "where do I start", "give me a tour", "set me up", and "help me contribute". Discerns the person's interest, angle, and the delivery mode that fits — a pinpoint specific answer, a synthesised area overview, or a paced guided tour — through at most a few friendly conversational questions (never a menu), then delivers, reading all content live from the canonical docs. Machine setup is a distinct, go-ahead-gated capability the tour or an overview can lead into. Use whenever someone is new to the repository or asks to be told about, oriented to, or set up with it.

Merge agent memory and state files (napkin, repo-continuity, distilled, thread records, registers) by reconciling CONCEPTS, not lines. Use whenever these files diverge across branches or sessions and a merge, rebase, cherry-pick, or post-update `gh pr merge` would combine them — git line-merges silently corrupt the meaning.

Merge agent memory and state files (napkin, repo-continuity, distilled, thread records, registers) by reconciling CONCEPTS, not lines. Use whenever these files diverge across branches or sessions and a merge, rebase, cherry-pick, or post-update `gh pr merge` would combine them — git line-merges silently corrupt the meaning.

A portable, beginner-friendly primer on working with agentic AI coding agents: what they are, the set-the-goal / it-acts / you-supervise loop, giving good context, reviewing both output and actions, iterating, common failure modes, and working safely. Use as the lead-in for someone new to working with AI coding agents, before any project-specific guidance.

A portable, beginner-friendly primer on working with agentic AI coding agents: what they are, the set-the-goal / it-acts / you-supervise loop, giving good context, reviewing both output and actions, iterating, common failure modes, and working safely. Use as the lead-in for someone new to working with AI coding agents, before any project-specific guidance.

Doctrine for any work that builds, serves, or consumes a graph surface. A graph is not a list: subgraphs are complete within their declared bound or they are wrong; list operations (pagination, truncation, top-N sampling of nodes or edges) never touch a subgraph; responses carry the anchors that navigate to the next bounded response; graph tools are thin deterministic formatters over a smart corpus; a degraded list-shaped answer is never an acceptable substitute for a typed refusal or a well-formed empty result.

Doctrine for any work that builds, serves, or consumes a graph surface. A graph is not a list: subgraphs are complete within their declared bound or they are wrong; list operations (pagination, truncation, top-N sampling of nodes or edges) never touch a subgraph; responses carry the anchors that navigate to the next bounded response; graph tools are thin deterministic formatters over a smart corpus; a degraded list-shaped answer is never an acceptable substitute for a typed refusal or a well-formed empty result.

Run a persistent dedicated Oak knowledge-curation goal until every live curation buffer is empty or explicitly owner-decision-gated and its insight is conserved into permanent homes; wraps start-right-quick and consolidate-docs. Fitness is a signal that routes work, never a completion gate or a reason to trim, archive, split, shard, or rename.

Run a persistent dedicated Oak knowledge-curation goal until every live curation buffer is empty or explicitly owner-decision-gated and its insight is conserved into permanent homes; wraps start-right-quick and consolidate-docs. Fitness is a signal that routes work, never a completion gate or a reason to trim, archive, split, shard, or rename.

Declare and run session-completion or dedicated-knowledge-curation consolidation, including buffer disposition and closeout proof.

Declare and run session-completion or dedicated-knowledge-curation consolidation, including buffer disposition and closeout proof.

Run one curator pass on the repo's knowledge substrate. Use when allocated the curator boundary on team-start, when owner-directed to a curation lane, when a graduation buffer crosses critical fitness, when a pending-graduations trigger fires, or when a landed substrate shows an adoption gap.

Run one curator pass on the repo's knowledge substrate. Use when allocated the curator boundary on team-start, when owner-directed to a curation lane, when a graduation buffer crosses critical fitness, when a pending-graduations trigger fires, or when a landed substrate shows an adoption gap.

Recover ChatGPT-, deep-research-, or other LLM-exported reports from paired markdown, DOCX, and PDF copies into source-faithful clean markdown by copying content as faithfully as possible, repairing structure, and using the DOCX to repair real links.

Invoke Codex as a sub-agent for well-defined tasks using `codex exec`. Provides templates for brief one-shot tasks (no grounding) and longer repo-aware sessions (with oak-start-right-quick). Use when delegating a self-contained task to Codex from Claude Code or from a shell script.

Create a well-formed commit for current changes with conventional message format. Always active, every commit, every session, no trigger required. Enumerates live commitlint constraints inline at draft time, validates the drafted message via `pnpm agent-tools:check-commit-message` BEFORE invoking git commit, and coordinates the short-lived git index/head commit window.

Structured workflow for merging significantly diverged branches. Use when either branch has changed 100+ files, a dry-run merge produces 10+ conflicts, or the other branch refactored core interfaces your branch consumes.

Run all quality gates and fix issues.

Re-ground and structure execution with ACTION/REVIEW/GROUNDING cadence. Use when the user asks to go, re-ground work mid-session, or explicitly apply the GO workflow to structure task execution with periodic self-assessment.

Design ground truth queries for the Oak semantic search service using known-answer-first methodology. Use when creating new ground truths, redesigning existing queries, or working with files in src/lib/search-quality/ground-truth/.

Evaluate and validate ground truths for Oak semantic search using the COMMIT protocol. Use when reviewing existing ground truths, diagnosing low MRR scores, interpreting benchmark results, or running pnpm benchmark.

Reflective thinking — read and apply the metacognition directive.

Maintain a per-repo napkin file at .agent/memory/active/napkin.md that tracks mistakes, corrections, surprises, and what works. Always active, every session, unconditionally. Read distilled.md and napkin.md before doing anything. Write to the napkin continuously as you work. Log your own mistakes, not just user corrections.

Create or promote a plan following the plan architecture.

Lightweight end-of-session continuity update with a conditional consolidation gate.

Apply the repository start-right quick grounding workflow to the active session. Use when the user asks to start right, re-ground work, or explicitly apply the shared start-right-quick skill guidance and linked directives before or during task execution.

Apply repository start-right grounding plus team bootstrapping for multi-agent sessions. Use when a coordinated team is starting, re-grounding, or choosing temporary collaboration responsibilities.

Apply the repository start-right-thorough grounding workflow to the active session. Use for high-risk, cross-workspace, architectural, or planning-heavy work where full one-gate-at-a-time discipline is required from the start.

Write and audit canonical TSDoc plus the adjacent README or ADR updates that belong with a code change.