Codebase Learning Flow is organized as three layers with different ownership and adoption boundaries.
Codebase Learning Flow
│
├── 1. Agentic Delivery
│ └── How the coding agent collaborates with the repository and humans
│
├── 2. Learning & Ownership
│ └── How the human builds understanding, judgment, and durable knowledge
│
└── 3. Optional Risk Lenses
└── Regulatory, safety, security, or other domain-specific reasoning
The agentic delivery layer is the common collaboration layer. It defines the default engineering loop, instruction precedence, planning and verification behavior, communication, handoff, and boundaries around consequential actions.
Its main installed surface is agentic-flow/.
This layer should remain small because it is the most invasive layer: its instructions influence ordinary coding-agent behavior. Repository-specific architecture rules and task-specific procedures belong elsewhere.
The default engineering loop is:
Frame → Inspect → Decide → Act → Verify → Handoff
The loop is task-scaled. A trivial edit should not acquire a formal learning or change-management ceremony merely because the framework supports those things.
The learning and ownership layer helps a developer understand the system while doing real engineering work and retain useful knowledge without turning every task into documentation.
Its surfaces include:
learning-flow/;- repository-learning skills;
learn-anything;- the learning model in
agentic-flow/EDUCATION.md; - private
.local/continuity; - durable maps and takeaways.
This layer is independently adoptable into an existing agentic workflow.
Conversation remains the default learning surface. Private continuity is used only when meaningful persistence is justified. Shared knowledge is promoted deliberately and should be stable, verified, reusable, and non-sensitive.
The learning layer should not become a second engineering workflow or silently introduce universal execution gates.
Risk lenses add domain-specific reasoning to the active workflow without replacing it.
The current example is the regulatory extension and its regulatory-knowledge skill.
A risk lens may strengthen questions around:
- traceability;
- validation and verification;
- risk management;
- auditability;
- change control;
- safety;
- security;
- professional responsibility.
Risk lenses are selective. They should be activated when the work actually benefits from the lens, not merely because a repository contains a regulated or safety-relevant component.
For a consequential change, a risk lens can work with structured-change. It does not create a parallel workflow.
Warning
The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory/quality expertise.
flowchart TB
D[Agentic Delivery] --> L[Learning & Ownership]
D --> R[Optional Risk Lenses]
L --> K[Private or durable knowledge]
R --> C[Risk-aware reasoning]
A repository may therefore choose:
- Agentic Delivery only for a minimal coding-agent setup;
- Agentic Delivery + Learning & Ownership for the normal learning-oriented setup;
- Agentic Delivery + Risk Lenses when a specific domain requires stronger reasoning;
- all three when both learning and risk-aware engineering are useful.
Existing custom agentic workflows may also adopt Layer 2 or Layer 3 without adopting the framework's common Layer 1. This distinction matters for guided adoption.
Ownership boundaries
| Layer | Owns | Avoid turning it into |
|---|---|---|
| Agentic Delivery | common collaboration policy, task routing, verification, handoff | repository-specific architecture documentation or every task's learning procedure |
| Learning & Ownership | learning routes, durable understanding, private continuity, knowledge promotion | a mandatory lesson plan or universal execution gate |
| Optional Risk Lenses | domain-specific risk and evidence guidance | a claim of compliance, certification, or mandatory procedure for unrelated work |
The repository itself is the reference implementation of these boundaries. Changes should preserve the distinction rather than introduce a new cross-cutting framework layer for every concern.
Adoption versus installation
- Complete installation consumes the framework payload under
sample/and establishes the selected layers. - Guided adoption consumes
adoption/and adapts selected concepts into an existing agentic setup. It must not silently replace the host delivery workflow or rootAGENTS.md.
This separation is a trust and context boundary as well as an installation boundary.
The path an agent actually walks for one task, independent of profile:
flowchart TD
Root[Repository-native instructions] --> AF[agentic-flow/AGENTS.md]
AF --> Route{Task needs repository<br/>learning support?}
Route -->|no| WF[WORKFLOW.md loop]
Route -->|yes| LF[learning-flow/AGENTS.md]
Route -->|general topic, no repo| LA[learn-anything]
LF --> Skill[One learning skill:<br/>bootstrap / repository-learning branch /<br/>change-explainer / ticket-learning-path]
Skill --> WF
WF --> Sig{Consequential, ambiguous,<br/>or regulated?}
Sig -->|yes| SC["structured-change<br/>(+ regulatory-knowledge if installed)"]
Sig -->|no| Act[Act → Verify]
SC --> Act
Act --> HO[Handoff]
HO --> Reuse{Reusable insight?}
Reuse -->|yes| LC[learning-closure →<br/>LOCAL.md / MAP.md / TAKEAWAYS.md]
Reuse -->|no| Done[Done]
Every box is read only when its condition is met; EDUCATION.md is applied selectively inside whichever learning skill runs, not as a separate stop. A maintainer auditing "what does an installed full profile actually load for a bug fix" reads this diagram top to bottom: AGENTS.md → learning-flow/AGENTS.md → repository-learning (Bug branch) → WORKFLOW.md → optionally structured-change → handoff → optionally learning-closure. No other file sits on that path unless the task specifically needs it.
Learning is treated as a lifecycle rather than a second engineering process:
flowchart LR
W[Work] --> O[Observe useful insight]
O --> R[Recommend smallest destination]
R --> U[User decides]
U --> P[Private or durable knowledge]
P --> F[Later freshness check]
learning-closure owns the placement decision at meaningful workflow closure. learning-freshness periodically checks internal documentation and learning claims against implementation evidence. External-source claims remain externally sourced and carry provenance for later revalidation.
The default is not to persist anything. Durable knowledge must earn its maintenance cost.