From 86740792feee107b5dda8425c8f2d5423afff451 Mon Sep 17 00:00:00 2001 From: legrab Date: Sat, 8 Aug 2026 10:03:21 +0200 Subject: [PATCH 1/3] feat: redesign core structure for agentic delivery, learning & ownership, and optional risk lenses --- MANIFEST.txt | 10 +- README.md | 35 +++++ docs/ARCHITECTURE.md | 132 ++++++++++++++++++ docs/DESIGN_NOTES.md | 16 ++- docs/README.md | 59 +++++--- sample/common/agentic-flow/AGENTS.md | 9 ++ .../profiles/minimal/learning-flow/AGENTS.md | 9 ++ 7 files changed, 247 insertions(+), 23 deletions(-) create mode 100644 docs/ARCHITECTURE.md diff --git a/MANIFEST.txt b/MANIFEST.txt index a70c23d..2598aad 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -2,10 +2,10 @@ .gitignore 317 AGENTS.md 3172 CHANGELOG.md 13500 -docs/DESIGN_NOTES.md 22495 +docs/DESIGN_NOTES.md 23730 docs/EDUCATION_MODEL.md 5452 docs/INITIALIZE_LEARNING_FLOW.md 10880 -docs/README.md 2428 +docs/README.md 3227 docs/references/REFERENCE_INTEGRATION.md 4551 docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md 2317 docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md 2540 @@ -14,7 +14,7 @@ docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md 9505 docs/references/REFERENCE_REVIEW_LITT.md 2069 docs/references/REFERENCE_REVIEW_POCOK.md 2155 LICENSE 2213 -README.md 10942 +README.md 13264 sample/common/.agents/skills/agentic-workflow/SKILL.md 3653 sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 sample/common/.agents/skills/learn-anything/SKILL.md 3225 @@ -31,7 +31,7 @@ sample/common/.agents/skills/structured-change/templates/exploration.md 368 sample/common/agentic-flow/.managed-files 170 sample/common/agentic-flow/.managed-skills 50 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 5788 +sample/common/agentic-flow/AGENTS.md 6137 sample/common/agentic-flow/CONFIGURE.md 4475 sample/common/agentic-flow/DECISIONS.md 963 sample/common/agentic-flow/EDUCATION.md 5232 @@ -87,7 +87,7 @@ sample/profiles/minimal/learning-flow/.managed-files 87 sample/profiles/minimal/learning-flow/.managed-skills 20 sample/profiles/minimal/learning-flow/.template-profile 8 sample/profiles/minimal/learning-flow/.template-version 6 -sample/profiles/minimal/learning-flow/AGENTS.md 3064 +sample/profiles/minimal/learning-flow/AGENTS.md 3459 sample/profiles/minimal/learning-flow/MAP.md 1229 sample/profiles/minimal/learning-flow/README.md 1974 sample/profiles/minimal/learning-flow/TAKEAWAYS.md 973 diff --git a/README.md b/README.md index c48c9d7..001b0f3 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,41 @@ flowchart LR K --> L ``` +> [!WARNING] +> The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory/quality expertise. + +## What this repository is + +Codebase Learning Flow is both a working, literate example of repository-native agentic engineering and a reusable framework that can be installed into another repository. + +The repository is intentionally literate: its documentation, workflow instructions, skills, examples, and validation describe how the system is supposed to work while also serving as the system being developed. The installable part packages the reusable behavior so another repository can adopt the useful pieces without having to adopt this repository's complete workflow. + +The framework does not provide an agent runtime, sandbox, retry engine, or background worker. It configures a host coding agent through repository-local instructions, skills, learning surfaces, and optional risk lenses. + +## Three layers + +The framework has three explicit layers with different ownership and adoption boundaries: + +| Layer | Purpose | Adoption boundary | +|---|---|---| +| **Agentic Delivery** | Common collaboration policy, task routing, verification, and handoff | Most invasive. A repository may use it as the common agentic baseline. | +| **Learning & Ownership** | Repository learning, general learning, private continuity, and durable knowledge | Independently adoptable into an existing agentic workflow. | +| **Optional Risk Lenses** | Regulatory, safety, security, or other domain-specific reasoning | Selective and additive. Never a replacement for the active workflow. | + +The normal complete installation composes these layers, but they are not inseparable. In particular, a repository with an existing agentic workflow can adopt the learning or risk layers without replacing its own delivery model. + +```text +Agentic Delivery + │ + ├── may use ──► Learning & Ownership + │ + └── may use ──► Optional Risk Lenses + │ + └── elaborates the active workflow when relevant +``` + +This separation is deliberate. Adding a new learning or risk concern should not automatically create another global workflow layer or increase the amount of instruction every task must load. + ## Start in two minutes Run one installer from the repository that should receive the framework: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..2697d9d --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,132 @@ +# Framework architecture + +Codebase Learning Flow is organized as three layers with different ownership and +adoption boundaries. + +```text +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 +``` + +## 1. Agentic Delivery + +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. + +It must not absorb repository-specific architecture rules or task-specific +procedures that belong elsewhere. + +The default engineering loop is: + +```text +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. + +## 2. Learning & Ownership + +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 must not become a second engineering workflow or silently +introduce universal execution gates. + +## 3. Optional Risk Lenses + +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 must not be activated merely because a +repository happens to contain 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. + +## Layer relationships + +The layers compose downward without requiring all three to be installed: + +```text +Agentic Delivery + │ + ├── may use ──► Learning & Ownership + │ + └── may use ──► Optional Risk Lenses + │ + └── may elaborate the active workflow +``` + +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 is important for +guided adoption. + +## Ownership boundaries + +| Layer | Owns | Must not become | +|---|---|---| +| 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 fourth +cross-cutting framework layer for every new concern. diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index d2dc34b..f3117a8 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -4,6 +4,20 @@ The harness should keep a developer able to reason about a repository while collaborating with an agent, and let any learner use the same lightweight methods for a general subject. It should improve delivery, code and architecture understanding, domain reasoning, debugging, ownership growth, and conversational learning without making workflow administration or learning administration the primary activity. +## Current three-layer architecture + +The current architecture consolidates the earlier ownership distinctions into three user-facing framework layers: + +| Layer | Owns | Adoption role | +|---|---|---| +| **Agentic Delivery** | common collaboration policy, task routing, verification, handoff, and consequential-action boundaries | the common agentic baseline; most invasive layer | +| **Learning & Ownership** | repository/general learning, private continuity, durable knowledge, and learning-oriented skills | independently adoptable into an existing agentic workflow | +| **Optional Risk Lenses** | regulatory, safety, security, and similar domain-specific reasoning | selective additive guidance used by the active workflow | + +The previous five ownership layers remain useful as implementation provenance, but they are not a second architecture. Repository-specific instructions, task skills, and temporary state are implementation ownership boundaries inside the three layers rather than additional framework layers. + +This distinction is important for adoption. A repository with its own agentic delivery workflow can adopt Learning & Ownership or an Optional Risk Lens without installing or replacing the common Agentic Delivery layer. + ## v0.5 separation of concerns Repository agentic content is divided into five ownership layers: @@ -31,7 +45,6 @@ The v0.5 review retained several strong patterns from the current `legrab/pocok` The reusable workflow intentionally does not copy Pocok's universal one-step approval loop, mandatory session file, one-commit-per-step rule, fixed plan schema, or automatic phase gates. Those controls remain available through configuration when risk or teaching purpose justifies them. - ## v0.5.1 existing-harness integration The repository's agentic setup can be a learning territory when custom instructions or conflicts affect work. Managed template state is recognized cheaply; a full instruction-order explanation belongs to an explicit setup review, not every initial baseline. @@ -46,7 +59,6 @@ Root integration is explicit and reversible: The lean root retains Pocok's useful evidence discipline but excludes its repository-specific .NET package policy, mandatory session rules, commit format, release sequence, and handoff state. - ## v0.5.2 reference integration and communication External sources are treated as design references, not templates to copy. Every integration resolves an exact source revision, reviews agent-facing surfaces, separates reusable principles from source-specific policy, fits retained value into existing ownership layers, and records the result in a `docs/references/REFERENCE_REVIEW_.md` file. diff --git a/docs/README.md b/docs/README.md index 90d36e5..16d9ddf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,26 +1,44 @@ # Design and maintenance map -This directory explains why the framework is shaped this way, how to evolve it, and how outside ideas are evaluated without turning the repository into a harness catalogue. +This directory explains why the framework is shaped this way, how to evolve it, +and how outside ideas are evaluated without turning the repository into a +harness catalogue. ```mermaid flowchart LR - H[Human learning model] --> D[Design decisions] - D --> I[Installable profiles] - D --> S[Skills and routing] - I --> V[Installer and preservation rules] - S --> V - V --> R[Reference review and revision] + H[Human learning model] --> A[Agentic Delivery] + A --> L[Learning & Ownership] + A --> R[Optional Risk Lenses] + L --> V[Installer and preservation rules] + R --> V + V --> C[Reference review and revision] ``` > [!IMPORTANT] -> Changes should strengthen understanding, ownership, verification, or maintenance while keeping the common path small. A new framework layer must remove more complexity than it adds. +> Changes should strengthen understanding, ownership, verification, or +> maintenance while keeping the common path small. A new framework layer must +> remove more complexity than it adds. + +## Architecture + +[`ARCHITECTURE.md`](ARCHITECTURE.md) is the canonical description of the +framework's three layers: + +1. **Agentic Delivery**: common coding-agent collaboration behavior. +2. **Learning & Ownership**: learning, continuity, and durable knowledge. +3. **Optional Risk Lenses**: selective regulatory, safety, security, or similar + domain guidance. + +The layers have different adoption boundaries. Learning and risk guidance may +be adopted into an existing agentic workflow without replacing that workflow. ## Read by purpose | Need | Start here | |---|---| +| understand the framework architecture | [`ARCHITECTURE.md`](ARCHITECTURE.md) | | understand the educational direction | [`EDUCATION_MODEL.md`](EDUCATION_MODEL.md) | -| understand ownership and architecture decisions | [`DESIGN_NOTES.md`](DESIGN_NOTES.md) | +| understand ownership and historical architecture decisions | [`DESIGN_NOTES.md`](DESIGN_NOTES.md) | | reconstruct or adapt the framework | [`INITIALIZE_LEARNING_FLOW.md`](INITIALIZE_LEARNING_FLOW.md) | | integrate an external source | [`references/REFERENCE_INTEGRATION.md`](references/REFERENCE_INTEGRATION.md) | | inspect installer behavior | [`../scripts/README.md`](../scripts/README.md) | @@ -35,15 +53,24 @@ flowchart LR - [`Pocok`](references/REFERENCE_REVIEW_POCOK.md) - [`Litt`](references/REFERENCE_REVIEW_LITT.md) -A reference is evidence, not a target architecture. Keep exact provenance, name value already covered locally, and retain only the smallest gap-closing delta. +A reference is evidence, not a target architecture. Keep exact provenance, name +value already covered locally, and retain only the smallest gap-closing delta. ## Maintainer checklist -1. Keep generic learning and repository learning behaviorally aligned through `sample/common/agentic-flow/EDUCATION.md`. -2. Keep direct engineering behavior in `agentic-flow/` and task procedures in skills. -3. Keep `.local/` private, ignored, and optional. -4. Preserve repository-authored maps, takeaways, settings, and unrelated skills during updates. -5. Validate both minimal and full installations after changing manifests or managed files. -6. Review the human entry points after structural changes. The root README should remain useful before any agent-facing detail is read. +1. Keep generic learning and repository learning behaviorally aligned through + `sample/common/agentic-flow/EDUCATION.md`. +2. Keep common engineering behavior in the Agentic Delivery layer and task + procedures in skills. +3. Keep Learning & Ownership independently adoptable and avoid making it a + universal execution gate. +4. Keep Optional Risk Lenses selective and additive. +5. Keep `.local/` private, ignored, and optional. +6. Preserve repository-authored maps, takeaways, settings, and unrelated skills + during updates. +7. Validate both minimal and full installations after changing manifests or + managed files. +8. Review the human entry points after structural changes. The root README + should remain useful before any agent-facing detail is read. diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index f011a76..7794cbe 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -1,5 +1,14 @@ # Agentic collaboration instructions +## Layer 1: Agentic Delivery + +This file is the common Agentic Delivery layer. It owns collaboration behavior, +task routing, verification, handoff, and boundaries around consequential +actions. + +Learning & Ownership and Optional Risk Lenses are separate layers. They may be +selected when useful, but this layer must remain usable without either one. + ## Route 1. Follow root, nested, and tool-specific repository instructions first. diff --git a/sample/profiles/minimal/learning-flow/AGENTS.md b/sample/profiles/minimal/learning-flow/AGENTS.md index b80b0c8..0ad7917 100644 --- a/sample/profiles/minimal/learning-flow/AGENTS.md +++ b/sample/profiles/minimal/learning-flow/AGENTS.md @@ -1,5 +1,14 @@ # Minimal repository learning instructions +## Layer 2: Learning & Ownership + +This file belongs to the Learning & Ownership layer. It adds repository +understanding, learning reinforcement, private continuity, and deliberate +knowledge promotion on top of the active Agentic Delivery layer. + +It does not replace the delivery workflow or create a universal execution +gate. Load it only when repository learning materially improves the task. + ## Priority and scope Follow repository-native instructions and `agentic-flow/AGENTS.md` first. This layer adds learning support only. From 560b4664eab73d20659e5355e95b248fcd0c5262 Mon Sep 17 00:00:00 2001 From: legrab Date: Sat, 8 Aug 2026 12:42:28 +0200 Subject: [PATCH 2/3] chore: minor adjustments to skills for efficiency --- MANIFEST.txt | 12 +- README.md | 6 + docs/AGENTIC_WORKFLOW_SANITY.md | 182 ++++++++++++++++++ docs/README.md | 4 + .../.agents/skills/agentic-workflow/SKILL.md | 7 +- .../.agents/skills/learn-anything/SKILL.md | 4 +- .../.agents/skills/structured-change/SKILL.md | 4 +- sample/common/agentic-flow/AGENTS.md | 33 +++- 8 files changed, 236 insertions(+), 16 deletions(-) create mode 100644 docs/AGENTIC_WORKFLOW_SANITY.md diff --git a/MANIFEST.txt b/MANIFEST.txt index 2598aad..1c04111 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -5,7 +5,7 @@ CHANGELOG.md 13500 docs/DESIGN_NOTES.md 23730 docs/EDUCATION_MODEL.md 5452 docs/INITIALIZE_LEARNING_FLOW.md 10880 -docs/README.md 3227 +docs/README.md 3523 docs/references/REFERENCE_INTEGRATION.md 4551 docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md 2317 docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md 2540 @@ -14,10 +14,10 @@ docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md 9505 docs/references/REFERENCE_REVIEW_LITT.md 2069 docs/references/REFERENCE_REVIEW_POCOK.md 2155 LICENSE 2213 -README.md 13264 -sample/common/.agents/skills/agentic-workflow/SKILL.md 3653 +README.md 14109 +sample/common/.agents/skills/agentic-workflow/SKILL.md 4185 sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 -sample/common/.agents/skills/learn-anything/SKILL.md 3225 +sample/common/.agents/skills/learn-anything/SKILL.md 3362 sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md 2533 sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md 1386 sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md 1300 @@ -25,13 +25,13 @@ sample/common/.agents/skills/structured-change/knowledge/engineering/documentati sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md 1319 sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md 1254 sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md 1287 -sample/common/.agents/skills/structured-change/SKILL.md 4136 +sample/common/.agents/skills/structured-change/SKILL.md 4283 sample/common/.agents/skills/structured-change/templates/design.md 649 sample/common/.agents/skills/structured-change/templates/exploration.md 368 sample/common/agentic-flow/.managed-files 170 sample/common/agentic-flow/.managed-skills 50 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 6137 +sample/common/agentic-flow/AGENTS.md 7496 sample/common/agentic-flow/CONFIGURE.md 4475 sample/common/agentic-flow/DECISIONS.md 963 sample/common/agentic-flow/EDUCATION.md 5232 diff --git a/README.md b/README.md index 001b0f3..d9b12a5 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,12 @@ Agentic Delivery This separation is deliberate. Adding a new learning or risk concern should not automatically create another global workflow layer or increase the amount of instruction every task must load. +## Instruction budget and workflow sanity + +The framework treats agent context as a limited engineering resource. The common delivery layer is the baseline; learning and risk material are conditional branches. Ordinary work should select one primary task route, load only the narrow evidence it needs, reuse current findings, and stop when the evidence threshold is met. A skill must not become a second workflow merely because it is related to the task. + +The framework is intentionally tested against representative low-risk, learning, consequential, and regulated scenarios to guard against the main failure mode: **making a competent developer perform framework rituals instead of making them faster and more aware**. See [`docs/AGENTIC_WORKFLOW_SANITY.md`](docs/AGENTIC_WORKFLOW_SANITY.md) for the context-budget rules and sanity scenarios. + ## Start in two minutes Run one installer from the repository that should receive the framework: diff --git a/docs/AGENTIC_WORKFLOW_SANITY.md b/docs/AGENTIC_WORKFLOW_SANITY.md new file mode 100644 index 0000000..f632379 --- /dev/null +++ b/docs/AGENTIC_WORKFLOW_SANITY.md @@ -0,0 +1,182 @@ +# Agentic workflow sanity checks + +These scenarios guard the framework against its main behavioral failure mode: adding process until a competent developer has to perform framework rituals instead of getting useful work done. + +The standard is: + +> **Does the framework make a competent developer faster and more aware, or does it make them perform framework rituals?** + +These are behavioral acceptance scenarios, not a claim that a static CI job can prove agent behavior. Run them against the supported agent surfaces when changing workflow instructions or skills, and review the resulting conversation for unnecessary context loading, questions, artifacts, and repetition. + +## Context-budget rules + +The effective workflow should follow these rules: + +1. **Load the smallest responsible instruction set.** Root instructions and the common Agentic Delivery layer establish the baseline. A task skill, learning layer, or risk lens is loaded only when its route is active. +2. **One primary task procedure.** Ordinary work has one active task route. `structured-change` is an elaboration of `Decide`, not a second delivery procedure. +3. **Progressive disclosure.** Read an index or routing file first, then only the specific document or knowledge file required by the current question. +4. **Do not recursively preload the framework.** A referenced document does not imply that every document it mentions should be read immediately. +5. **Reuse evidence.** Once a current source, test, map, or finding establishes something, do not rescan the same territory merely to satisfy another skill. +6. **Stop at the evidence threshold.** More context is not automatically better. Stop when the mechanism, decision, or remaining uncertainty is sufficiently bounded for the task. +7. **Scale ceremony to risk.** Mechanical and low-risk work should collapse the route. Consequential work may expand it. +8. **Keep learning subordinate to the task.** Learning should improve understanding and future ownership, not create a parallel process for every engineering change. +9. **Do not duplicate handoffs.** Learning reinforcement belongs in the normal handoff when useful; do not create a second summary merely because learning was involved. +10. **Prefer references over copies.** If a rule has one canonical owner, other files should point to it rather than reproduce it. + +## Default active context + +For ordinary repository work, the intended context is approximately: + +```text +repository-native instructions + ↓ +common Agentic Delivery instructions + ↓ +one selected task route, if needed + ↓ +one narrowly relevant knowledge/reference file, if needed +``` + +Learning and regulatory material are conditional branches, not part of the universal baseline. + +## Sanity scenarios + +### 1. Typo-only change + +**Prompt:** Fix a spelling mistake in an existing Markdown document. + +Expected behavior: + +- no formal plan; +- no learning-flow route unless understanding the document is genuinely necessary; +- no `structured-change`; +- no questionnaire; +- no learning artifact; +- minimal verification; +- concise handoff or direct completion. + +Failure signal: the agent starts explaining the framework, creating a session, or loading repository-learning material for a one-line typo. + +### 2. Small configuration change + +**Prompt:** Change one existing configuration value with an obvious intended effect. + +Expected behavior: + +- inspect the configuration and immediate consumers; +- make the smallest change; +- run the closest useful check; +- no structured decision unless the change reveals meaningful ambiguity or risk. + +Failure signal: broad repository mapping or formal design work without evidence that it is needed. + +### 3. Straightforward bug fix + +**Prompt:** Fix a reproducible failing behavior with an existing regression test. + +Expected behavior: + +- use the debugging route; +- identify the mechanism from decisive evidence; +- make the narrow fix; +- run the focused regression proof; +- at most one useful understanding check when it adds value. + +Failure signal: hypothesis diary, multiple explain-back checks, or broad learning artifacts. + +### 4. New feature + +**Prompt:** Add a feature that resembles an existing feature. + +Expected behavior: + +- select the feature route or nearest focused skill; +- find one valid analogue; +- identify shared invariants and intentional differences; +- implement and verify the coherent slice; +- retain only useful learning. + +Failure signal: loading every learning skill or producing a generic architecture exercise before inspecting the analogue. + +### 5. Unfamiliar module + +**Prompt:** Explain how an unfamiliar module works before changing it. + +Expected behavior: + +- deliberately activate repository learning/orientation; +- inspect the smallest useful territory; +- trace one representative path; +- identify important boundary and uncertainty; +- stop once the user can safely continue. + +Failure signal: generating an exhaustive repository inventory instead of a useful mental model. + +### 6. Architecturally significant change + +**Prompt:** Replace a central integration mechanism where two credible designs are possible. + +Expected behavior: + +- use `structured-change` alongside the selected task route; +- Explore → Design → Approve before implementation; +- request a real decision rather than performing ceremony for its own sake; +- verify against the agreed design. + +Failure signal: either skipping a consequential decision or applying the full structured process to an obviously reversible small change. + +### 7. Regulatory or audited behavior + +**Prompt:** Change behavior covered by the repository's validation or audit controls. + +Expected behavior: + +- activate `regulatory-knowledge` only for the relevant question; +- use `structured-change` when its applicability conditions are met; +- capture proportional traceability/validation considerations; +- keep qualified human responsibility explicit. + +Failure signal: reading the entire regulatory knowledge set, applying compliance ceremony to unrelated work, or implying that framework use establishes compliance. + +### 8. General learning request + +**Prompt:** Explain a technical concept unrelated to the current repository. + +Expected behavior: + +- use `learn-anything`; +- do not inspect repository code; +- use a compact conversational learning loop; +- preserve private continuity only when meaningful. + +Failure signal: repository orientation, repository maps, or engineering workflow instructions being loaded merely because the framework is installed. + +### 9. Pull-request completion + +**Prompt:** Finish a substantive change and prepare the handoff. + +Expected behavior: + +- report changed behavior and meaningful verification; +- identify remaining risk or open decisions; +- if reusable knowledge was discovered, recommend whether it belongs in local history, repository learning, module documentation, or no persistent record; +- ask the user only when the placement decision is meaningful. + +Failure signal: automatic dumping of the entire session into `learning-history.md`, or silently creating durable knowledge without a reuse justification. + +## Review checklist + +For each scenario, review the agent interaction for: + +- unnecessary instructions loaded; +- unnecessary questions asked; +- duplicated explanations; +- unnecessary artifacts created; +- incorrect skill activation; +- repeated repository scanning; +- unsupported completion claims; +- proportional verification; +- useful learning reinforcement; +- unnecessary framework terminology in the user-facing result. + +A change to the common workflow or a broadly loaded skill should rerun the affected scenarios. A change to a narrow task skill only needs the scenarios that can route to that skill plus the ordinary-task checks needed to ensure it does not become ambient. diff --git a/docs/README.md b/docs/README.md index 16d9ddf..a1ab26a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -58,6 +58,10 @@ value already covered locally, and retain only the smallest gap-closing delta. +## Agentic workflow sanity checks + +Use [`AGENTIC_WORKFLOW_SANITY.md`](AGENTIC_WORKFLOW_SANITY.md) when changing common agent instructions or broadly loaded skills. It defines the context-budget rules and representative scenarios used to detect framework ritual and context-overflow regressions. + ## Maintainer checklist 1. Keep generic learning and repository learning behaviorally aligned through diff --git a/sample/common/.agents/skills/agentic-workflow/SKILL.md b/sample/common/.agents/skills/agentic-workflow/SKILL.md index 3b5744d..e853a78 100644 --- a/sample/common/.agents/skills/agentic-workflow/SKILL.md +++ b/sample/common/.agents/skills/agentic-workflow/SKILL.md @@ -5,7 +5,7 @@ description: Initialize, integrate, configure, explain, map, review, or improve # Agentic workflow -Read `agentic-flow/README.md`, `AGENTS.md`, `SETTINGS.md`, and only the relevant section of `ROOT_INTEGRATION.md`, `CONFIGURE.md`, `WORKFLOW.md`, `LEARN.md`, `LOCAL.md`, or `REFERENCE_INTEGRATION.md`. +Read `agentic-flow/README.md` and `AGENTS.md` first. Read `SETTINGS.md` only when configuration matters, then load only the specific section or document needed for the current operation. Do not preload the whole `agentic-flow/` directory. ## Discover the actual setup @@ -15,6 +15,7 @@ Read `agentic-flow/README.md`, `AGENTS.md`, `SETTINGS.md`, and only the relevant 4. Treat managed template content as known; inspect custom additions, overrides, conflicts, and integration points. 5. Separate stable policy, collaboration behavior, task procedure, shared learning, and private or temporary `.local/` state. 6. Determine effective instruction order from repository evidence. +7. Keep the active context narrow: do not load every discovered skill, plan, record, or reference merely because it exists. ## Initialize or integrate @@ -54,3 +55,7 @@ Read `agentic-flow/README.md`, `AGENTS.md`, `SETTINGS.md`, and only the relevant Look for temporary handoff in stable instructions, contributor-specific learning outside ignored `.local/`, mandatory ceremony unrelated to risk, duplicated rules, unchecked completion claims, competing workflows, learning mixed into universal execution, stale records without owners, and ambiguous root integration. Recommend the smallest consolidation. Preserve coherent custom structures. Do not add a framework layer unless it removes more complexity than it adds. + +## Context budget + +Prefer one authoritative instruction over duplicated policy. If a rule is already owned by `agentic-flow/AGENTS.md`, a task skill should reference it rather than restate it. Do not load a second task procedure simply because it is related. When an operation can be completed from current repository evidence, stop rather than broadening the context. diff --git a/sample/common/.agents/skills/learn-anything/SKILL.md b/sample/common/.agents/skills/learn-anything/SKILL.md index 1e6696a..9282257 100644 --- a/sample/common/.agents/skills/learn-anything/SKILL.md +++ b/sample/common/.agents/skills/learn-anything/SKILL.md @@ -5,7 +5,7 @@ description: Guide a concise, adaptive conversation for learning, exploring, or # Learn Anything -Do not inspect repository code. Read `agentic-flow/EDUCATION.md` and apply only the lenses that improve the learner's direct question. When a meaningful session has relevant prior history, read only the needed local history instead of reteaching from scratch. +Do not inspect repository code. Read only the relevant parts of `agentic-flow/EDUCATION.md`; do not load repository-learning instructions, maps, or other framework material. When a meaningful session has relevant prior history, read only the needed local history instead of reteaching from scratch. ## Conversation loop @@ -38,6 +38,8 @@ When the topic involves teaching, classrooms, teams, or assessment, selectively ## System lens +Use this only when the topic benefits from a system view. Do not activate every lens by default. + For a complex subject, choose only the useful subset: - purpose or outcome; diff --git a/sample/common/.agents/skills/structured-change/SKILL.md b/sample/common/.agents/skills/structured-change/SKILL.md index bff0213..608b74a 100644 --- a/sample/common/.agents/skills/structured-change/SKILL.md +++ b/sample/common/.agents/skills/structured-change/SKILL.md @@ -5,7 +5,7 @@ description: Sequence Explore, Design, and Approve before Act for one consequent # Structured change -Read `agentic-flow/AGENTS.md`, `agentic-flow/SETTINGS.md`, and `agentic-flow/WORKFLOW.md`. This skill elaborates one part of `Decide`. It does not replace `WORKFLOW.md`, `repository-learning`, or a full-profile task skill, and it is not a second delivery workflow running alongside them. +Read `agentic-flow/AGENTS.md` and the relevant parts of `agentic-flow/WORKFLOW.md`. Read `SETTINGS.md` only when the configured preset affects the decision. This skill elaborates one part of `Decide`. It does not replace `WORKFLOW.md`, `repository-learning`, or a full-profile task skill, and it is not a second delivery workflow running alongside them. ## When this applies @@ -31,7 +31,7 @@ Keep this conversational by default. Use `templates/exploration.md` only when a 1. Compare credible options against tradeoffs, risk, and migration cost. 2. Select an approach and state what remains a requested decision for the user. 3. Name the verification plan and, only when the change is genuinely hard to reverse, a rollback approach. -4. When `regulatory-knowledge` is installed and relevant, note traceability, validation impact, and requirement linkage using its guidance. Do not invent compliance language the repository does not already use. +4. When `regulatory-knowledge` is installed and relevant, read only the one or two knowledge files that answer the current question, then note traceability, validation impact, and requirement linkage using that guidance. Do not invent compliance language the repository does not already use. Use `templates/design.md` only when it earns its cost, per Scale below. diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index 7794cbe..4dc09a7 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -13,13 +13,34 @@ selected when useful, but this layer must remain usable without either one. 1. Follow root, nested, and tool-specific repository instructions first. 2. Use this layer for collaboration behavior. -3. Load `learning-flow/AGENTS.md` only for deliberate repository learning, orientation, explanation, or initial mapping. -4. Use `learn-anything` for non-repository learning without loading repository-learning instructions. -5. Learning routes apply `EDUCATION.md` selectively. -6. Load at most one task skill unless the task clearly requires more. -7. For one consequential, ambiguous, or regulated change, `structured-change` may run alongside the chosen route to sequence Explore, Design, and Approve before Act. It elaborates `Decide`; it is not a second route, and most tasks never need it. +3. Select one primary task route. Do not load multiple task procedures unless the active route explicitly requires a narrow supporting skill. +4. Load `learning-flow/AGENTS.md` only for deliberate repository learning, orientation, explanation, or initial mapping. +5. Use `learn-anything` for non-repository learning without loading repository-learning instructions. +6. Apply `EDUCATION.md` only when a selected learning route needs it. Read only the relevant sections. +7. For one consequential, ambiguous, or regulated change, `structured-change` may run alongside the chosen route to elaborate `Decide`. It is not a second engineering workflow, and most tasks never need it. -Read `SETTINGS.md`; use `balanced` immediately when settings remain at defaults. Read `CONFIGURE.md` only for explicit configuration, a non-default preset, or an advanced override. +Read `SETTINGS.md` when the task depends on collaboration configuration; use `balanced` immediately when settings remain at defaults. Read `CONFIGURE.md` only for explicit configuration, a non-default preset, or an advanced override. Do not load configuration documents merely because they exist. + +## Context budget + +The framework is intentionally progressive-disclosure. Context is a limited engineering resource, not a reason to load every framework document. + +- Start with repository-native instructions and this file. +- Select one primary task route before loading task-specific instructions. +- Load only the files that route names as necessary for the current question. +- Treat indexes, manifests, and routing files as pointers, not requests to preload their entire contents. +- Read one relevant knowledge/reference file at a time when possible. +- Reuse current evidence instead of rescanning the same territory for another skill. +- Stop when the evidence threshold for the decision or implementation is met. +- Small or mechanical work should collapse the route to the smallest useful sequence. + +The intended default is: + +```text +repository instructions → Agentic Delivery → one task route → narrow evidence +``` + +Learning and risk material are conditional branches. They are not part of the universal context. See `docs/AGENTIC_WORKFLOW_SANITY.md` in the framework repository for the behavioral acceptance scenarios and context-budget rationale. ## Discover the effective setup From e670bdf0fb9b4ab49eaf11331ec37ec6d7b6e302 Mon Sep 17 00:00:00 2001 From: legrab Date: Sat, 8 Aug 2026 12:46:19 +0200 Subject: [PATCH 3/3] feat: prompt-based guided adoption and learning propagation from local to history --- MANIFEST.txt | 26 ++-- README.md | 41 +++++- adoption/ADOPT.md | 129 ++++++++++++++++++ adoption/README.md | 57 ++++++++ docs/ARCHITECTURE.md | 33 +++++ docs/README.md | 20 +++ .../.agents/skills/learning-closure/SKILL.md | 86 ++++++++++++ .../skills/learning-freshness/SKILL.md | 55 ++++++++ sample/common/agentic-flow/.managed-skills | 2 + sample/common/agentic-flow/AGENTS.md | 15 ++ sample/common/agentic-flow/README.md | 9 ++ sample/common/agentic-flow/WORKFLOW.md | 4 +- sample/common/local/learning-history.md | 13 ++ .../regulatory/learning-flow/REGULATORY.md | 3 + scripts/README.md | 8 ++ skill-evals/README.md | 8 ++ skill-evals/adoption-cases.yaml | 21 +++ skill-evals/learning-lifecycle-cases.yaml | 21 +++ 18 files changed, 539 insertions(+), 12 deletions(-) create mode 100644 adoption/ADOPT.md create mode 100644 adoption/README.md create mode 100644 sample/common/.agents/skills/learning-closure/SKILL.md create mode 100644 sample/common/.agents/skills/learning-freshness/SKILL.md create mode 100644 skill-evals/adoption-cases.yaml create mode 100644 skill-evals/learning-lifecycle-cases.yaml diff --git a/MANIFEST.txt b/MANIFEST.txt index 1c04111..8920924 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -5,7 +5,7 @@ CHANGELOG.md 13500 docs/DESIGN_NOTES.md 23730 docs/EDUCATION_MODEL.md 5452 docs/INITIALIZE_LEARNING_FLOW.md 10880 -docs/README.md 3523 +docs/README.md 4185 docs/references/REFERENCE_INTEGRATION.md 4551 docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md 2317 docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md 2540 @@ -14,7 +14,7 @@ docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md 9505 docs/references/REFERENCE_REVIEW_LITT.md 2069 docs/references/REFERENCE_REVIEW_POCOK.md 2155 LICENSE 2213 -README.md 14109 +README.md 16282 sample/common/.agents/skills/agentic-workflow/SKILL.md 4185 sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 sample/common/.agents/skills/learn-anything/SKILL.md 3362 @@ -29,20 +29,20 @@ sample/common/.agents/skills/structured-change/SKILL.md 4283 sample/common/.agents/skills/structured-change/templates/design.md 649 sample/common/.agents/skills/structured-change/templates/exploration.md 368 sample/common/agentic-flow/.managed-files 170 -sample/common/agentic-flow/.managed-skills 50 +sample/common/agentic-flow/.managed-skills 86 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 7496 +sample/common/agentic-flow/AGENTS.md 8182 sample/common/agentic-flow/CONFIGURE.md 4475 sample/common/agentic-flow/DECISIONS.md 963 sample/common/agentic-flow/EDUCATION.md 5232 sample/common/agentic-flow/LEARN.md 1822 sample/common/agentic-flow/LOCAL.md 3513 -sample/common/agentic-flow/README.md 1624 +sample/common/agentic-flow/README.md 2039 sample/common/agentic-flow/REFERENCE_INTEGRATION.md 2183 sample/common/agentic-flow/ROOT_INTEGRATION.md 3086 sample/common/agentic-flow/SETTINGS.md 544 -sample/common/agentic-flow/WORKFLOW.md 4674 -sample/common/local/learning-history.md 986 +sample/common/agentic-flow/WORKFLOW.md 5020 +sample/common/local/learning-history.md 1528 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md 1444 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md 2336 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md 1447 @@ -59,7 +59,7 @@ sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md 3530 sample/extensions/regulatory/learning-flow/.extension-managed-files 81 sample/extensions/regulatory/learning-flow/.extension-managed-skills 21 sample/extensions/regulatory/learning-flow/.extension-name 11 -sample/extensions/regulatory/learning-flow/REGULATORY.md 1719 +sample/extensions/regulatory/learning-flow/REGULATORY.md 1882 sample/profiles/full/.agents/skills/analogous-feature/SKILL.md 1408 sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md 1426 sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md 428 @@ -97,10 +97,16 @@ sample/root/AGENTS.pointer.md 296 scripts/install.bat 1477 scripts/install.ps1 35102 scripts/install.sh 29472 -scripts/README.md 4502 +scripts/README.md 4900 skill-evals/agentic-cases.yaml 7109 skill-evals/conversation-cases.yaml 3653 skill-evals/full-cases.yaml 4248 skill-evals/minimal-cases.yaml 3208 -skill-evals/README.md 1352 +skill-evals/README.md 1667 skill-evals/structured-change-cases.yaml 3735 +adoption/ADOPT.md 3941 +adoption/README.md 2057 +sample/common/.agents/skills/learning-closure/SKILL.md 3263 +sample/common/.agents/skills/learning-freshness/SKILL.md 1866 +skill-evals/learning-lifecycle-cases.yaml 1220 +skill-evals/adoption-cases.yaml 1337 diff --git a/README.md b/README.md index d9b12a5..7bf421c 100644 --- a/README.md +++ b/README.md @@ -60,10 +60,22 @@ The framework treats agent context as a limited engineering resource. The common The framework is intentionally tested against representative low-risk, learning, consequential, and regulated scenarios to guard against the main failure mode: **making a competent developer perform framework rituals instead of making them faster and more aware**. See [`docs/AGENTIC_WORKFLOW_SANITY.md`](docs/AGENTIC_WORKFLOW_SANITY.md) for the context-budget rules and sanity scenarios. -## Start in two minutes +## Installation + +### Preferred: packaged release + +For team and enterprise use, install a reviewed, versioned release rather than +executing a mutable checkout from `main`. Release installation will be the +preferred distribution path once packaged releases are published. + +Pin the exact release version used by the team and retain the version in the +installation record. + +### Development checkout Run one installer from the repository that should receive the framework: + ```powershell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) ``` @@ -104,6 +116,33 @@ Remote piping executes the referenced revision. Pin a release tag or commit for +## Adoption situations + +| Situation | Recommended approach | Installation / adoption procedure | +|---|---|---| +| **A. No agentic flow** | Complete installation with `minimal` by default; add `full` or `regulatory` deliberately. | Prefer a pinned packaged release. Use checkout installers for development or experimentation. | +| **B. Custom agentic flow per developer** | Preserve the existing delivery layer and selectively adopt learning/risk capabilities. | Check out this repository and run the guided adoption prompt from [`adoption/ADOPT.md`](adoption/ADOPT.md). | +| **C. Lightweight agentic flow, no learning/regulatory concepts** | Keep the existing delivery workflow and add the Learning & Ownership layer plus relevant risk lenses. | Prefer guided adoption; use complete installation only when the repository explicitly wants to standardize its delivery layer. | + +Complete installation and guided adoption are intentionally different operations. +Complete installation consumes the framework payload under `sample/`; guided +adoption consumes the instructions under `adoption/` and integrates only the +selected concepts into an existing setup. + +## Guided adoption for existing agentic setups + +Check out this repository and ask the host coding agent to read +[`adoption/ADOPT.md`](adoption/ADOPT.md). The agent should inspect the existing +repository workflow, ask about profile and extension choices, propose a +minimal compatible integration, and wait for approval before consequential +changes. + +The guided process considers `structured-change`, `learn-anything`, +`learning-closure`, `learning-freshness`, the Learning & Ownership model, +private `.local/` continuity, and relevant risk extensions. It does **not** +automatically install the common `agentic-flow` or rewrite the root +`AGENTS.md`. + ## Choose the route | You want to... | Route | What stays primary | diff --git a/adoption/ADOPT.md b/adoption/ADOPT.md new file mode 100644 index 0000000..c55b10d --- /dev/null +++ b/adoption/ADOPT.md @@ -0,0 +1,129 @@ +# Guided adoption protocol + +Use this document only for **guided adoption into an existing custom agentic +setup**. It is deliberately separate from the complete installation payload. + +## 1. Inspect before proposing + +Inspect only enough of the target repository to understand: + +- root and nested agent instructions; +- existing skills and task routing; +- existing learning or knowledge surfaces; +- local/session continuity; +- current validation and handoff behavior; +- repository-specific ownership boundaries. + +Do not load the entire Codebase Learning Flow repository into active context. + +Summarize the existing setup before proposing changes. + +## 2. Explain the three layers + +Use these adoption boundaries: + +| Layer | Meaning | Default adoption behavior | +|---|---|---| +| Agentic Delivery | existing task execution, collaboration, verification, and handoff | Preserve the host repository's existing layer unless the user explicitly wants to replace or augment it | +| Learning & Ownership | learning routes, private continuity, durable knowledge, learning closure, freshness checks | Candidate for independent adoption | +| Optional Risk Lenses | regulatory or other selective risk reasoning | Candidate only when relevant | + +The purpose is to add capabilities without accidentally creating a second global +workflow. + +## 3. Ask the user about concrete choices + +Ask only questions whose answers affect the proposed changes. + +At minimum consider: + +1. Which profile or learning depth is wanted: `minimal`, `full`, or a custom subset? +2. Should `structured-change` be adopted? +3. Should `learn-anything` be adopted? +4. Should learning closure be part of substantial/PR handoff? +5. Should learning freshness checks be available? +6. Should private `.local/` continuity be adopted? +7. Is a risk extension such as `regulatory` relevant? + +Do not ask all questions mechanically if repository evidence already answers one. + +The user may choose a custom subset. + +## 4. Build an adoption plan + +For every selected component, identify: + +- existing instruction or skill it complements; +- potential conflict; +- target location; +- whether the change is additive, replacement, or adaptation; +- what will remain untouched. + +Prefer adapting the concept to the repository's existing vocabulary over +copying files wholesale. + +## 5. Approval boundary + +Before modifying consequential repository instructions, present a compact plan: + +```text +Adopting: +- → + +Preserving: +- + +Conflict: +- + +Not adopting: +- → + +Root AGENTS.md: +- unchanged / specific approved edit + +Proceed? +``` + +An explicit user instruction already resolving the choice counts as approval. + +## 6. Integrate selectively + +When implementing: + +- preserve existing repository-authored content; +- add only selected capabilities; +- adapt references to the host repository; +- keep one primary task procedure; +- avoid creating a second competing workflow; +- do not install the complete `agentic-flow` unless the user explicitly changes + the adoption request into a complete installation. + +If the repository already has a root `AGENTS.md`, do not rewrite it automatically. +If a pointer or reference would improve discoverability, propose the smallest +change and obtain approval. + +## 7. Verify the resulting workflow + +After integration, test at least: + +- one trivial task; +- one normal engineering task; +- one meaningful learning task; +- one consequential change if `structured-change` was adopted. + +Check that the selected additions activate only when relevant and do not turn +ordinary work into framework ceremony. + +## 8. Finish with an adoption summary + +Report: + +- selected components; +- files/instructions changed; +- preserved existing behavior; +- conflicts resolved; +- verification performed; +- anything intentionally left for later. + +The result is a host-specific adaptation, not a disguised complete installation. diff --git a/adoption/README.md b/adoption/README.md new file mode 100644 index 0000000..298ea21 --- /dev/null +++ b/adoption/README.md @@ -0,0 +1,57 @@ +# Guided adoption + +This directory is **not part of complete installation**. It is the repository's +guided adoption surface for repositories that already have their own agentic +workflow. + +The distinction is structural: + +- `sample/` contains the framework payload used by complete installation. +- `adoption/` contains guidance for adapting selected framework concepts into + an existing setup. +- `scripts/` contains installers for complete installation. +- `adoption/` must not cause the common `agentic-flow` to be installed or the + target repository's root `AGENTS.md` to be rewritten automatically. + +## Start adoption + +Give the repository-aware coding agent this instruction: + +> Read `adoption/ADOPT.md` in the Codebase Learning Flow repository. Inspect my +> existing repository-native agentic setup before changing anything. Treat this +> as guided adoption, not complete installation. Ask me about the meaningful +> choices, recommend compatible components, and integrate only what I approve. +> Preserve existing instructions and workflows unless I explicitly approve a +> change. + +The agent should then follow `ADOPT.md`. + +## What adoption can add + +The primary candidates are: + +- `structured-change`; +- `learn-anything`; +- `learning-closure`; +- `learning-freshness`; +- the Learning & Ownership model; +- private `.local/` continuity; +- `regulatory-knowledge` where relevant. + +The common Agentic Delivery layer is intentionally not a default adoption target. +An existing repository may already have a better delivery workflow for its users. + +## What adoption must preserve + +Adoption must not: + +- replace the existing agent runtime; +- silently replace the existing agentic workflow; +- automatically install `agentic-flow`; +- automatically rewrite the root `AGENTS.md`; +- overwrite repository-authored skills or documentation; +- create unnecessary framework ceremony. + +If a proposed integration conflicts with an existing instruction, surface the +conflict and ask the user to choose rather than resolving it by silently giving +one instruction higher priority. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2697d9d..880d414 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -130,3 +130,36 @@ guided adoption. The repository itself is the reference implementation of these boundaries. Changes should preserve the distinction rather than introduce a fourth cross-cutting framework layer for every new concern. + + +## Adoption versus installation + +The repository deliberately separates complete installation from guided adoption. + +- **Complete installation** consumes the framework payload under `sample/` and + establishes the selected Agentic Delivery, Learning & Ownership, and optional + Risk Lens layers. +- **Guided adoption** consumes `adoption/` and adapts selected concepts into an + existing agentic setup. It is not an installer profile and must not silently + replace the host delivery workflow or root `AGENTS.md`. + +This separation is a trust and context boundary as well as an installation +boundary. The adoption process can inspect the framework without loading its +entire instruction set into the active agent context. + +## Learning lifecycle + +Learning is treated as a lifecycle rather than a second engineering process: + +```text +work → observe useful insight → recommend destination → user decides + → private continuity or durable shared knowledge → 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. diff --git a/docs/README.md b/docs/README.md index a1ab26a..777be71 100644 --- a/docs/README.md +++ b/docs/README.md @@ -78,3 +78,23 @@ Use [`AGENTIC_WORKFLOW_SANITY.md`](AGENTIC_WORKFLOW_SANITY.md) when changing com managed files. 8. Review the human entry points after structural changes. The root README should remain useful before any agent-facing detail is read. + + +## Current architecture boundaries + +The framework is organized into three layers: + +1. Agentic Delivery; +2. Learning & Ownership; +3. Optional Risk Lenses. + +Complete installation uses the payload under `sample/`. Guided adoption uses the +separate `adoption/` surface and integrates only selected concepts into an +existing agentic workflow. + +Meaningful workflow closure can invoke `learning-closure` to decide whether a +useful insight belongs in private continuity, a learning-flow surface, or +module +documentation. `learning-freshness` provides a periodic internal consistency +check; external-source claims require retained provenance and external +revalidation. diff --git a/sample/common/.agents/skills/learning-closure/SKILL.md b/sample/common/.agents/skills/learning-closure/SKILL.md new file mode 100644 index 0000000..0fb8016 --- /dev/null +++ b/sample/common/.agents/skills/learning-closure/SKILL.md @@ -0,0 +1,86 @@ +--- +name: learning-closure +description: Decide whether useful learning from a meaningful engineering or learning session should be retained, and where it belongs. Use at meaningful workflow closure, especially pull-request or change-set handoff. Do not create learning records for trivial work. +--- + +# Learning closure + +Use this skill only when the current work produced a reusable insight worth considering for future work. It is a closure aid, not a mandatory documentation phase. + +## Decide whether anything should persist + +First state the candidate insight in one sentence. + +Do not persist it if it is: + +- specific only to this session; +- already accurately documented; +- obvious and cheap to rediscover; +- uncertain or unverified; +- sensitive, secret, customer-specific, or contributor-specific. + +If nothing qualifies, say so and continue the normal handoff. + +## Recommend the smallest useful destination + +Choose among: + +| Destination | Use when | +|---|---| +| No persistent record | The insight is local, temporary, or cheap to rediscover | +| `.local/learning-history.md` | The insight is useful to the current developer/session but is not shared repository knowledge | +| `learning-flow/MAP.md` | It describes stable repository structure, boundaries, controls, or representative flows | +| `learning-flow/TAKEAWAYS.md` | It is a concise, verified reusable engineering or domain lesson | +| Module README/documentation | The knowledge belongs specifically with a module and should be discovered there | +| Skill/workflow documentation | The knowledge changes how this framework or a reusable repository workflow should operate | + +Prefer the module's own documentation when the knowledge is necessary to use or extend that module correctly. Prefer learning-flow surfaces for cross-cutting repository understanding. + +## Ask at meaningful closure + +At pull-request or substantial change completion, if a useful candidate exists, present a compact recommendation: + +```text +Learning capture + +I found one reusable insight: +"" + +Recommended destination: , because . + +Persist it there, keep it private, or discard it? +``` + +Offer at most the few destinations that are genuinely plausible. Do not present a generic questionnaire. + +If the user chooses a destination, write the smallest useful record and include its evidence/source. + +## Record quality + +A persistent entry should normally contain: + +- concise statement of what was learned; +- why it matters; +- affected area; +- evidence or source; +- verification date when useful. + +Do not store conversation transcripts, long debugging diaries, confidence scores, or generated filler. + +## External sources + +For learning based on external material, preserve enough provenance to re-check the claim: + +```text +Source: +Revision/version: +Published: +Accessed: +Relevant section:
+``` + +External-source metadata does not make the claim current or verified. It only makes future verification possible. + +## Scope + +This skill complements the active engineering or learning workflow. It never replaces the primary task procedure, and it should not turn a trivial task into a documentation exercise. diff --git a/sample/common/.agents/skills/learning-freshness/SKILL.md b/sample/common/.agents/skills/learning-freshness/SKILL.md new file mode 100644 index 0000000..92c2c49 --- /dev/null +++ b/sample/common/.agents/skills/learning-freshness/SKILL.md @@ -0,0 +1,55 @@ +--- +name: learning-freshness +description: Cross-check durable repository learning and documentation against the current implementation and identify stale claims. Use during deliberate maintenance or when documentation confidence matters. Do not treat external-source claims as internally verified. +--- + +# Learning freshness + +Use this skill periodically or when durable repository knowledge is suspected to be stale. It is a review tool, not a claim that documentation can be semantically proven correct. + +## Internal evidence + +Cross-check relevant learning-flow and module documentation against: + +- current source symbols and paths; +- configuration; +- tests; +- generated interfaces; +- scripts and commands; +- repository structure. + +Look for concrete divergence first: + +- removed or renamed paths; +- missing symbols; +- changed configuration; +- obsolete commands; +- broken internal links; +- examples inconsistent with current APIs; +- workflow references to retired skills; +- architecture descriptions that no longer match repository boundaries. + +Reuse existing repository evidence before broad rescanning. + +## External evidence + +If a claim depends on material outside the repository, do not mark it verified from repository inspection alone. + +Use retained provenance such as URL, revision/version, publication date, access date, and relevant section to identify what must be rechecked externally. + +If external access is unavailable, report the claim as externally sourced and not revalidated. + +## Output + +Report only actionable findings: + +- stale claim; +- affected document; +- current evidence; +- recommended correction or revalidation. + +Do not rewrite documentation automatically unless explicitly requested. + +## Restraint + +Do not turn this into a general repository audit. Check the documentation or learning surface that was requested or is clearly due for review. diff --git a/sample/common/agentic-flow/.managed-skills b/sample/common/agentic-flow/.managed-skills index eda0bc0..ea3d943 100644 --- a/sample/common/agentic-flow/.managed-skills +++ b/sample/common/agentic-flow/.managed-skills @@ -1,3 +1,5 @@ agentic-workflow learn-anything structured-change +learning-closure +learning-freshness diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index 4dc09a7..39fd4d9 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -119,3 +119,18 @@ Checks: ``` Trivial commits need only a title. For a consequential or regulated change, add the optional `Traceability` section described in `WORKFLOW.md` instead of expanding this default shape. Do not commit, push, publish, merge, or create release tags unless explicitly requested. + + +## Learning closure and freshness + +Meaningful engineering work may end with a `learning-closure` decision. Use it +only when the work produced a reusable insight. The agent should recommend the +smallest appropriate destination and let the user decide whether to persist it. + +At pull-request or substantial change completion, make this decision part of +the normal handoff rather than creating a separate documentation ceremony. + +Use `learning-freshness` during deliberate maintenance or when durable +repository knowledge may have drifted from implementation. It can check +repository evidence, but external-source claims require their retained source +metadata and external revalidation. diff --git a/sample/common/agentic-flow/README.md b/sample/common/agentic-flow/README.md index 0cae8a9..ea7605d 100644 --- a/sample/common/agentic-flow/README.md +++ b/sample/common/agentic-flow/README.md @@ -40,6 +40,7 @@ Start with `AGENTS.md`. Use balanced defaults from `SETTINGS.md` unless configur | `LOCAL.md` | private learning continuity and deliberate promotion | | `ROOT_INTEGRATION.md` | connecting existing or missing root instructions | | `REFERENCE_INTEGRATION.md` | extracting value from another source | +| `LEARN.md` + learning skills | understanding the effective harness and building knowledge |
Boundary in one sentence @@ -47,3 +48,11 @@ Start with `AGENTS.md`. Use balanced defaults from `SETTINGS.md` unless configur `agentic-flow/` controls how work is performed. `learning-flow/` and learning skills control how understanding is built through that work.
+ + +## Learning lifecycle + +`learning-closure` decides whether a meaningful change produced reusable +knowledge and recommends the smallest appropriate persistence surface. +`learning-freshness` can later cross-check durable repository knowledge against +current implementation evidence. Neither is a second delivery workflow. diff --git a/sample/common/agentic-flow/WORKFLOW.md b/sample/common/agentic-flow/WORKFLOW.md index 7cb0c34..0a29f53 100644 --- a/sample/common/agentic-flow/WORKFLOW.md +++ b/sample/common/agentic-flow/WORKFLOW.md @@ -65,7 +65,9 @@ Open Use descriptive bullets grouped by outcome instead of a chronological tool log or file inventory. Put long command output, secondary rationale, alternatives, or exhaustive evidence in collapsible sections. Keep failures and required next actions visible. -When `learning-flow/` or a meaningful generic learning session was active, close private continuity under `.local/` according to `LOCAL.md`, then fold only useful learning reinforcement into this handoff. Do not add a second recap section, repeat the same outcome and evidence, or expose private session detail through shared records. +When `learning-flow/` or a meaningful generic learning session was active, close private continuity under `.local/` according to `LOCAL.md`. If the work produced a genuinely reusable insight, invoke `learning-closure` as part of the handoff: recommend the smallest useful destination, ask the user whether to persist it, and write only the approved concise record. Do not add a second recap section, repeat the same outcome and evidence, or expose private session detail through shared records. + +For pull-request or substantial change completion, learning closure is a normal handoff decision when useful knowledge exists. It is not required when no reusable insight was produced. ## Traceability diff --git a/sample/common/local/learning-history.md b/sample/common/local/learning-history.md index c19b781..747be00 100644 --- a/sample/common/local/learning-history.md +++ b/sample/common/local/learning-history.md @@ -32,3 +32,16 @@ This file is private repository-local learning state. Keep it concise enough to |---|---|---|---| ## Useful next directions + + +## Placement guidance + +Learning captured here is private continuity, not the canonical repository +knowledge base. At meaningful change or pull-request closure, the agent may +recommend promoting a verified insight to `learning-flow/MAP.md`, +`learning-flow/TAKEAWAYS.md`, or module documentation. Promotion is always a +deliberate user decision. + +For external-source learning, retain source URL or identifier, revision/version +when applicable, publication/access dates when known, and the relevant +section so the claim can be rechecked later. diff --git a/sample/extensions/regulatory/learning-flow/REGULATORY.md b/sample/extensions/regulatory/learning-flow/REGULATORY.md index d87c826..712927f 100644 --- a/sample/extensions/regulatory/learning-flow/REGULATORY.md +++ b/sample/extensions/regulatory/learning-flow/REGULATORY.md @@ -1,5 +1,8 @@ # Regulatory extension +> [!WARNING] +> The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory/quality expertise. + Installed by `--extension regulatory`. This file is additive: it never turns ordinary work into a compliance procedure, and it never overrides `AGENTS.md`, `agentic-flow/WORKFLOW.md`, or repository-native instructions. ## What this extension adds diff --git a/scripts/README.md b/scripts/README.md index 37b2b9c..c362fe3 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -2,6 +2,14 @@ The PowerShell, POSIX shell, and batch entry points install a repository-native collaboration and learning framework without replacing repository-specific instructions. +These scripts perform **complete installation**. They are intentionally separate +from the guided adoption process under `adoption/`, which is for repositories +that already have their own agentic delivery layer. + +For team and enterprise use, the preferred future distribution path is a pinned +packaged release. Checkout-based installers remain useful for framework +development and experimentation. + ```mermaid flowchart LR D[Download pinned source] --> P[Select profile] diff --git a/skill-evals/README.md b/skill-evals/README.md index cbaab0a..ae93bdc 100644 --- a/skill-evals/README.md +++ b/skill-evals/README.md @@ -19,3 +19,11 @@ Review these fixtures when changing skill descriptions, routing, profiles, exten > [!NOTE] > Expected phrases describe behavioral evidence, not exact generated wording. + + +## Additional lifecycle and adoption cases + +`learning-lifecycle-cases.yaml` covers learning placement and freshness checks. +`adoption-cases.yaml` covers guided integration into repositories with an +existing agentic setup. Both are intended to protect against unnecessary +context expansion and framework ceremony. diff --git a/skill-evals/adoption-cases.yaml b/skill-evals/adoption-cases.yaml new file mode 100644 index 0000000..3318502 --- /dev/null +++ b/skill-evals/adoption-cases.yaml @@ -0,0 +1,21 @@ +layer: guided-adoption +cases: + - prompt: This repository already has a custom agentic workflow. Adopt Codebase Learning Flow without replacing our existing setup. + expected_behavior: guided_adoption + must_include: [inspect existing workflow, ask meaningful choices, preserve native instructions, selected components] + must_not: [install complete agentic-flow, overwrite AGENTS.md, copy entire framework] + + - prompt: We want structured-change and learning support, but not the common agentic flow. Guide me through adoption. + expected_behavior: guided_adoption + must_include: [structured-change, learning layer, explicit approval, no complete installation] + must_not: [automatic agentic-flow installation, root AGENTS replacement] + + - prompt: Adopt the framework into this repository and just decide the profile and extension for me. + expected_behavior: guided_adoption + must_include: [inspect repository, explain choices, ask user] + must_not: [silent profile selection, silent extension activation] + + - prompt: We already have an effective handoff workflow. Add learning closure without creating a second workflow. + expected_behavior: guided_adoption + must_include: [complement existing handoff, learning closure, one primary procedure] + must_not: [parallel delivery workflow, mandatory ceremony] diff --git a/skill-evals/learning-lifecycle-cases.yaml b/skill-evals/learning-lifecycle-cases.yaml new file mode 100644 index 0000000..eea794f --- /dev/null +++ b/skill-evals/learning-lifecycle-cases.yaml @@ -0,0 +1,21 @@ +layer: learning-lifecycle +cases: + - prompt: We just finished a meaningful pull request and discovered a reusable rule about this module. Decide whether to persist it. + expected_skill: learning-closure + must_include: [candidate insight, smallest useful destination, user decision, evidence] + must_not: [automatic publication, transcript, mandatory record for trivial work] + + - prompt: This was a trivial typo fix. Should we create a learning-history entry? + expected_behavior: no_learning_artifact + must_include: [no persistent learning] + must_not: [learning questionnaire, session artifact] + + - prompt: The module README says the service uses X, but the implementation now appears to use Y. Check the durable learning. + expected_skill: learning-freshness + must_include: [current implementation evidence, stale claim, actionable finding] + must_not: [rewrite everything, claim external validation] + + - prompt: This learning came from an external standard. Can repository inspection prove it is still current? + expected_skill: learning-freshness + must_include: [external source, retained provenance, external revalidation] + must_not: [claim internal code proves the external source]