A small repository harness for learning real systems with AI while keeping human judgment in charge.
Codebase Learning Flow configures a host coding agent. It provides repository-local instructions, focused skills, learning surfaces, and private local continuity. It does not provide an agent runtime, sandbox, retry engine, or background worker.
Important
Learning-aware behavior is enabled by default after installation. That does not mean every task becomes a lesson. Routine work stays routine. Requests such as help me understand <topic> select the appropriate learning route; implementation work remains normal delivery with learning reinforcement only when useful. Proposed designs are hypotheses to check against repository evidence, not specifications to endorse.
Warning
The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory or quality expertise.
flowchart LR
Q[User question or task] --> R{What needs understanding?}
R -->|Current repository| C[Repository learning]
R -->|General topic| G[Learn anything]
R -->|Mostly execution| A[Agentic delivery]
C --> W[Work and verify]
G --> L[Learn conversationally]
A --> W
W --> H[Explain useful judgment]
L --> H
| Layer | Purpose |
|---|---|
| Agentic Delivery | collaboration, routing, verification, handoff |
| Learning & Ownership | repository learning, general learning, private continuity, durable knowledge |
| Optional Risk Lenses | regulatory, safety, security, or other domain guidance |
The layers are composable. Learning and risk guidance add to an existing workflow rather than becoming another workflow.
Tip
The framework optimizes for ownership, not framework participation: understand the real system, make good decisions, verify AI output, manage failure, and retain enough knowledge to operate without the model.
How the default learning behavior works
The installed AGENTS.md connects the host repository to agentic-flow. The common instructions route understanding requests automatically:
help me understand ...,explain ...,teach me ...→learn-anythingfor general topics- questions about the current codebase → repository learning
- implementation work → normal delivery, with learning reinforcement when useful
- a proposed design or approach → treated as a hypothesis, checked against repository evidence before endorsement or implementation
- an open-ended consequential question → repository evidence is inspected first; the user is asked only the smallest question evidence cannot answer
- one consequential or ambiguous change →
structured-changealongside the active route - regulatory reasoning → the optional regulatory lens when installed
The agent should not turn every task into a lesson. Short questions can receive short answers. Mechanical work can stay mechanical. A check-back is used only when it can expose a mistaken model or improve the next decision.
For team or enterprise use, install a reviewed, versioned release. Substitute the current tag from the badge above or the Releases page.
--release/-Release intentionally has no latest shortcut, so the exact tag must be given.
curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh -o install.sh
sh install.sh --release v1.3.0 --profile minimal& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.3.0 -Profile MinimalThe installer verifies the release checksum before extraction and reports the resolved Version: and Source:.
curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh | sh& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1)))Contributing to the framework itself? Run scripts/install.sh from your local checkout instead of curling the remote copy above.
Profiles, extensions, and update modes
| Choice | Meaning |
|---|---|
minimal |
daily use, smallest context surface |
full |
deliberate onboarding and deeper repository learning |
regulatory |
optional additive risk and traceability guidance |
update |
refresh framework-owned content while preserving repository-authored state |
merge |
add missing content without replacing existing content |
replace |
replace framework-managed directories and skills |
./scripts/install.sh --profile full
./scripts/install.sh --profile full --extension regulatory
./scripts/install.sh --mode update --profile fullA full-to-minimal update is rejected because automatic deletion could destroy repository-authored content. Removing an extension requires update or replace.
| Situation | Route |
|---|---|
| No existing agentic flow | Install minimal; add full or regulatory deliberately |
| Existing custom agentic flow | Use adoption/ADOPT.md and integrate only the useful layers |
| Existing lightweight flow | Add Learning & Ownership and relevant risk lenses without replacing delivery |
Complete installation consumes sample/. Guided adoption integrates selected concepts into an existing setup.
The shared educational constitution is installed as agentic-flow/EDUCATION.md.
flowchart LR
S[Locate] --> R[Reason]
R --> T[Try or work]
T --> O[Observe]
O --> E[Explain]
E --> V[Revise]
V --> X[Transfer]
The model is selective:
- keep the real business, scientific, human, or physical system primary;
- build judgment rather than dependence;
- use small, safe experiments when they clarify the model;
- question generated output, documentation, tests, and authority with evidence;
- distinguish fact, inference, and uncertainty;
- keep human control over consequential decisions;
- use at most one understanding check by default.
Ownership lens
When relevant:
| Question | Why |
|---|---|
| What real outcome matters? | prevents local code from becoming the whole problem |
| What rule or invariant must hold? | defines correctness |
| What evidence could disprove the model? | prevents confident guessing |
| How can it fail? | exposes containment and fallback needs |
| Who controls, validates, deploys, or accepts responsibility? | preserves human ownership |
Low-risk work should not be forced through a safety or regulatory checklist.
| Profile | Learning surface |
|---|---|
minimal |
one compact repository-learning skill |
full |
deeper repository-learning skill (orientation, debugging, feature, refactor), plus baseline, ticket-path, and change-explanation skills |
Both use the same common educational constitution and agentic layer.
The only current extension is regulatory. It adds traceability, validation, risk management, audit trails, change control, and short standards orientation. It does not turn ordinary work into a compliance procedure.
Note
Learn locally first. Promote only reusable knowledge deliberately.
Meaningful sessions may use the ignored .local/ workspace:
.local/
├── learning-history.md
├── sessions/
└── follow-ups/
Only stable, verified, non-sensitive knowledge should move into tracked owners such as learning-flow/MAP.md or learning-flow/TAKEAWAYS.md.
agentic-flow/
learning-flow/
.agents/skills/
.local/
Task-specific templates live inside their owning skills and are materialized only when justified.
docs/EDUCATION_MODEL.md· learning and ownership modeldocs/README.md· design and maintenance mapscripts/README.md· installer lifecycle and safety behaviorCHANGELOG.md· revision historyLICENSE· licensing terms
Source layout
sample/common/
sample/profiles/minimal/
sample/profiles/full/
sample/extensions/regulatory/
sample/root/
The common layer contains agentic-flow, learn-anything, structured-change, shared education guidance, and private-continuity defaults. Profiles add repository-learning depth; extensions add optional domain lenses.