diff --git a/AGENTS.md b/AGENTS.md index 726bad2..32aefa1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,46 +2,49 @@ ## Purpose -Maintain a small harness for safe agentic collaboration, deliberate codebase learning, and conversational learning about general topics. Preserve the separation between: +Maintain a small harness for safe agentic collaboration, repository learning, and conversational learning about general topics. + +Preserve the separation between: - repository-specific engineering rules; -- general collaboration behavior in `agentic-flow/`; -- optional repository learning in `learning-flow/`; -- generic conversation behavior in the common `learn-anything` skill; -- private learning and temporary task state under `.local/`. +- `agentic-flow/` collaboration behavior; +- `learning-flow/` repository learning; +- `learn-anything` general learning; +- private `.local/` continuity. ## Educational authority -Use `sample/common/agentic-flow/EDUCATION.md` as the shared educational constitution for both learning routes. Keep it selective, repository-agnostic, and focused on durable human ownership. +Use `sample/common/agentic-flow/EDUCATION.md` as the shared educational constitution. -Low-frequency task procedures belong in skills. Always-loaded instructions should contain routing, boundaries, and short invariants rather than duplicate teaching scripts. +Learning behavior should be automatic, not opt-in prose. Low-frequency procedures belong in skills. Always-loaded instructions should contain routing, boundaries, and short invariants rather than teaching scripts. -## Generic conversational learning +## Default learning behavior -When the user explicitly wants to learn a non-repository topic, treat this checkout as the host rather than the subject. Use `learn-anything`, do not inspect repository code, and let the direct question govern the session. +For every user request, apply the educational model at the smallest useful depth. -For meaningful continuity, follow `sample/common/agentic-flow/LOCAL.md`. Keep complete private session state under `.local/`, and promote only clearly reusable framework knowledge deliberately. +- `help me understand`, `explain`, `teach me`, and similar general questions → `learn-anything`; +- questions about this repository → repository learning; +- implementation work → normal delivery, with learning reinforcement when it materially improves ownership; +- one consequential or ambiguous change → `structured-change` alongside the active route. -If this source checkout has no `.local/` workspace yet, create `.local/{sessions,follow-ups}` and seed `.local/learning-history.md` from `sample/common/local/learning-history.md`. Never overwrite existing local state. +Keep the exchange conversational. Build a compact model, use one useful example or experiment when helpful, and use at most one check-back when it can reveal a mistaken model. Do not turn mechanical work into a lesson. ## Working rules - Read `README.md`, `docs/DESIGN_NOTES.md`, and `CHANGELOG.md` before structural changes. -- Keep minimal, full, and general learning behavior aligned through the common educational constitution. -- Prefer a small common rule over duplicated profile-specific prose. -- Keep direct session goals primary. Human values, resilience, and domain lenses are selective. +- Prefer one common rule over duplicated profile-specific prose. +- Keep direct task goals primary. - Do not add workflow ceremony without a demonstrated problem. -- Treat installer update and preservation behavior as part of the public contract. -- Update manifests, version markers, examples, and regression fixtures with framework changes. +- Treat installer update and preservation behavior as public contract. - Keep the framework usable across languages, build systems, repository sizes, and industries. - Never persist inferred distress, health, identity, secrets, customer data, or sensitive operational evidence. -## External reference integration +## External references -When asked to incorporate value from another repository, article source, or ZIP, follow `docs/references/REFERENCE_INTEGRATION.md`. +When incorporating another repository, article, or ZIP, follow `docs/references/REFERENCE_INTEGRATION.md`. -Extract the smallest generally useful patterns, preserve source-specific rules only in the reference review, and add `docs/references/REFERENCE_REVIEW_.md` for provenance and historical context. +Extract only the smallest generally useful patterns and record provenance in `docs/references/REFERENCE_REVIEW_.md`. ## Communication -Use direct, summary-first language. Say what changed and why it matters, grouping substantial updates into a few descriptive sections rather than a tool log or file inventory. Put secondary rationale, long examples, command matrices, and historical notes in `
` blocks when supported. Never hide required warnings, decisions, or next actions inside a collapsed section. +Use direct, summary-first language. Group substantial updates by outcome. Put secondary rationale, long examples, command matrices, and historical notes in `
` blocks. Keep warnings, decisions, validation failures, and required next actions visible. diff --git a/MANIFEST.txt b/MANIFEST.txt index 7b56ac5..0eb898a 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,6 +1,6 @@ .gitattributes 40 .gitignore 324 -AGENTS.md 3172 +AGENTS.md 2524 CHANGELOG.md 17352 docs/AGENTIC_WORKFLOW_SANITY.md 7795 docs/ARCHITECTURE.md 6009 @@ -16,10 +16,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 17154 -sample/common/.agents/skills/agentic-workflow/SKILL.md 4185 +README.md 8143 +sample/common/.agents/skills/agentic-workflow/SKILL.md 2686 sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 -sample/common/.agents/skills/learn-anything/SKILL.md 3362 +sample/common/.agents/skills/learn-anything/SKILL.md 1756 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 @@ -27,13 +27,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 4283 +sample/common/.agents/skills/structured-change/SKILL.md 1946 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 86 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 8182 +sample/common/agentic-flow/AGENTS.md 4121 sample/common/agentic-flow/CONFIGURE.md 4475 sample/common/agentic-flow/DECISIONS.md 963 sample/common/agentic-flow/EDUCATION.md 5232 @@ -68,7 +68,7 @@ sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md 4 sample/profiles/full/.agents/skills/change-explainer/SKILL.md 1308 sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md 290 sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md 1522 -sample/profiles/full/.agents/skills/repository-orientation/SKILL.md 1382 +sample/profiles/full/.agents/skills/repository-orientation/SKILL.md 1222 sample/profiles/full/.agents/skills/safe-refactor/SKILL.md 1373 sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md 1519 sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md 348 @@ -89,13 +89,13 @@ 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 3459 +sample/profiles/minimal/learning-flow/AGENTS.md 2369 sample/profiles/minimal/learning-flow/MAP.md 1229 sample/profiles/minimal/learning-flow/README.md 1974 sample/profiles/minimal/learning-flow/TAKEAWAYS.md 973 sample/README.md 2997 -sample/root/AGENTS.md 1339 -sample/root/AGENTS.pointer.md 296 +sample/root/AGENTS.md 2102 +sample/root/AGENTS.pointer.md 551 scripts/install.bat 1477 scripts/install.ps1 40236 scripts/install.sh 34910 diff --git a/README.md b/README.md index db15e9d..9dbadba 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,61 @@ # Codebase Learning Flow -> A small repository harness for learning real systems, using AI aggressively, and keeping human judgment in charge. +> 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 does not provide its own runtime, sandbox, retry engine, or background worker. The repository supplies durable instructions, focused learning skills, and private local continuity. +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] -> The target is not faster code generation by itself. The target is stronger ownership: understanding the business or physical system, choosing what should be built, validating generated work, managing failure, and retaining the ability to operate without the model. +> **Learning is the default behavior after installation.** Users do not need to explain the learning method. A request such as `help me understand ` automatically selects the appropriate learning route, keeps the exchange conversational, builds a compact model, uses a useful example or experiment, and checks back for understanding when that adds value. + +> [!WARNING] +> The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory or quality expertise. ```mermaid flowchart LR - Q[Real question or task] --> L[Locate the system] - L --> R[Reason about outcomes and boundaries] - R --> T[Test assumptions] - T --> W[Work with AI leverage] - W --> V[Verify behavior and failure modes] - V --> E[Explain the judgment] - E --> K[Keep only durable knowledge] - K --> L + 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 ``` -> [!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. +## What gets installed -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. +| 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 | -## Three layers +The layers are composable. Learning and risk guidance add to an existing workflow rather than becoming another workflow. -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. +> [!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. -```text -Agentic Delivery - │ - ├── may use ──► Learning & Ownership - │ - └── may use ──► Optional Risk Lenses - │ - └── elaborates the active workflow when relevant -``` +
+How the default learning behavior works -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. +The installed `AGENTS.md` connects the host repository to `agentic-flow`. The common instructions route understanding requests automatically: -## Instruction budget and workflow sanity +- `help me understand ...`, `explain ...`, `teach me ...` → `learn-anything` for general topics +- questions about the current codebase → repository learning +- implementation work → normal delivery, with learning reinforcement when useful +- one consequential or ambiguous change → `structured-change` alongside the active route +- regulatory reasoning → the optional regulatory lens when installed -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 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. -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. +
## Installation ### Preferred: packaged release -For team and enterprise use, install a reviewed, versioned release rather than -executing a mutable checkout from `main`. `--release`/`-Release` downloads the -packaged artifact published against an exact tag, verifies its checksum -before extracting anything, and refuses `latest`: pin the version the team -actually reviewed. +For team or enterprise use, install a reviewed, versioned release. ```sh curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh -o install.sh @@ -79,221 +66,110 @@ sh install.sh --release v0.9.0 --profile minimal & ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v0.9.0 -Profile Minimal ``` -The installer's closing summary states the resolved `Version:` and `Source:` -so the pinned version is easy to record alongside the installation. See -[`scripts/README.md`](scripts/README.md#installing-a-packaged-release) for -the full flag reference and what checksum verification actually checks. +The installer verifies the release checksum before extraction and reports the resolved `Version:` and `Source:`. ### 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))) -``` - ```sh curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh | sh ``` -Then give the agent the real task: - -```text -Start with my current task. Quietly verify the installed workflow, surface only meaningful -instruction conflicts, and teach the relevant system, domain, and code path while working. +```powershell +& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) ``` -New installations use the compact `minimal` profile. +*For local development, use the installer scripts directly.*
-Windows Command Prompt and local installer commands - -```bat -powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.bat -OutFile '%TEMP%\install-learning-flow.bat'" && "%TEMP%\install-learning-flow.bat" -``` +Profiles, extensions, and update modes -```powershell -./scripts/install.ps1 -Profile Minimal -./scripts/install.ps1 -Profile Full -./scripts/install.ps1 -Mode Update -``` +| 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 | ```sh -./scripts/install.sh --profile minimal ./scripts/install.sh --profile full -./scripts/install.sh --mode update +./scripts/install.sh --profile full --extension regulatory +./scripts/install.sh --mode update --profile full ``` -Remote piping executes whatever `main` currently resolves to. For a team or -enterprise installation, use `--release`/`-Release` with an exact tag (see -"Preferred: packaged release" above) rather than pinning a checkout commit: -the release path adds checksum verification and is what CI actually -validates before publishing. +A full-to-minimal update is rejected because automatic deletion could destroy repository-authored content. Removing an extension requires `update` or `replace`.
-## 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 | -|---|---|---| -| understand or change the current repository | repository learning | the real engineering task | -| learn a general topic | `learn-anything` | the learner's question | -| configure or review the harness | `agentic-workflow` | repository collaboration policy | -| sequence one consequential, ambiguous, or regulated change | `structured-change` | the active route above, not a replacement for it | +## Adoption -For a general topic: +| Situation | Route | +|---|---| +| No existing agentic flow | Install `minimal`; add `full` or `regulatory` deliberately | +| Existing custom agentic flow | Use [`adoption/ADOPT.md`](adoption/ADOPT.md) and integrate only the useful layers | +| Existing lightweight flow | Add Learning & Ownership and relevant risk lenses without replacing delivery | -```text -Use learn-anything to help me understand . Keep it conversational, build a compact -system model, use one useful example or experiment, and let my questions steer the depth. -``` - -The general route does not inspect repository code. It can cover science, history, languages, arts, mathematics, teaching, or general technical ideas. - -## What the framework optimizes for - -| Human ownership | AI leverage | Resilient delivery | -|---|---|---| -| understand the larger system | map unfamiliar territory quickly | identify failure modes and safe boundaries | -| decide what should be built | prototype and compare options | validate generated solutions | -| question assumptions and authority | automate repetitive investigation | retain manual or operational fallback | -| articulate reasoning and tradeoffs | improve teaching material | control access and deployment | -| accept professional responsibility | build domain knowledge faster | integrate legacy and physical systems | - -> [!TIP] -> AI should remove avoidable effort, not remove the learner from the causal chain. A useful session ends with a better model, stronger evidence, or clearer judgment, not merely more generated text. +Complete installation consumes `sample/`. Guided adoption integrates selected concepts into an existing setup. -## The learning compass +## Learning model -The shared educational constitution is installed as `agentic-flow/EDUCATION.md`. Each learning route selects only the lenses that improve the current task. +The shared educational constitution is installed as `agentic-flow/EDUCATION.md`. ```mermaid -flowchart TB - S[System ownership] --> B[Business or physical reality] - S --> J[Judgment about what to build] - S --> F[Failure, safety, and fallback] - S --> H[Human responsibility] - - A[AI leverage] --> M[Map larger systems] - A --> P[Prototype and test assumptions] - A --> X[Automate repetition] - A --> D[Preserve independence] - - L[Learning practice] --> E[Trial and error] - L --> C[Critical and systems thinking] - L --> Q[Question authority] - L --> R[Explain reasoning] +flowchart LR + S[Locate] --> R[Reason] + R --> T[Try or work] + T --> O[Observe] + O --> E[Explain] + E --> V[Revise] + V --> X[Transfer] ``` -### Priority ownership domains - -The framework is repository-agnostic, but it asks deeper questions when work touches: +The model is selective: -- laboratory software; -- industrial control and physical equipment; -- regulated or safety-relevant software (see the `regulatory` extension for the operational lens); -- security and access control; -- architecture and integration; -- verification and validation; -- education and assessment; -- human-machine workflow design. - -These are lenses, not assumptions. A web utility does not need a pretend safety case. A laboratory controller should not be taught as if it were a CRUD demo. +- 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.
-Human educational value +Ownership lens -When the topic involves teaching, teams, classrooms, onboarding, or assessment, the flow can also exercise: +When relevant, consider: -- leadership and standard-setting; -- motivation without fake praise; -- social and group learning; -- noticing disengagement without diagnosing the learner; -- credible assessment based on demonstrated reasoning; -- trusted-adult responsibility and appropriate boundaries; -- judgment, not information transfer alone. +| 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 | -These concerns stay selective. They must not hijack a direct session goal or cause sensitive personal state to be persisted. +*Low-risk work should not be forced through a safety or regulatory checklist.*
-## Profiles - -| Profile | Best for | Shared surfaces | Learning skills | -|---|---|---|---:| -| `minimal` | daily work, short engagements, token-sensitive agents | `MAP.md`, `TAKEAWAYS.md` | 1 repository skill | -| `full` | deliberate onboarding and long-lived ownership | map, takeaways, repository baselines | 7 focused skills | - -Both profiles use the same common collaboration layer and educational constitution. Full mode adds narrower task skills and more structured orientation, not more ceremony by default. +## Profiles and extensions -```mermaid -flowchart LR - C[agentic-flow] --> M[minimal learning-flow] - C --> F[full learning-flow] - C --> G[learn-anything] - M --> P1[One compact repository skill] - F --> P2[Focused orientation, debugging, feature, refactor, explanation skills] - G --> P3[General conversational learning] -``` - -## Extensions - -Extensions are additive and orthogonal to profile: they add capability without changing what `minimal` or `full` mean. The only extension today is `regulatory`. - -| Extension | Adds | Never does | -|---|---|---| -| `regulatory` | `regulatory-knowledge` skill: traceability, validation, risk management, audit trails, change control, and short orientation to ISO 9001, ISO 13485, ISO 14971, ISO 17025, IEC 62304, and 21 CFR Part 11 | turn ordinary low-risk work into a compliance procedure | - -```sh -./scripts/install.sh --profile full --extension regulatory -``` - -```powershell -./scripts/install.ps1 -Profile Full -Extension Regulatory -``` - -`--extension auto` (the default) keeps whatever is currently installed and defaults a fresh install to none. Removing an installed extension needs `update` or `replace` mode, the same restriction that applies to a destructive profile switch: +| Profile | Learning surface | +|---|---| +| `minimal` | one compact repository-learning skill | +| `full` | focused orientation, debugging, feature, refactor, and explanation skills | -```sh -./scripts/install.sh --mode update --extension none -``` +Both use the same common educational constitution and agentic layer. -The Explore → Design → Approve → Implement → Review → Capture Knowledge sequence this extension plugs into is not extension-specific. It lives in `structured-change`, a common skill available with every profile, and elaborates one part of `agentic-flow/WORKFLOW.md`'s `Decide` step for the rare change that is architecturally significant, genuinely ambiguous, or regulated. The `regulatory` extension adds a lens to that same skill; it does not add a second workflow. +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. ## Private continuity > [!NOTE] > Learn locally first. Promote only reusable knowledge deliberately. -Fresh installation creates an ignored repository-root `.local/` workspace: +Meaningful sessions may use the ignored `.local/` workspace: ```text .local/ @@ -302,75 +178,38 @@ Fresh installation creates an ignored repository-root `.local/` workspace: └── follow-ups/ ``` -Meaningful sessions may retain attempts, revised models, checks, and useful next directions. One-off answers and ordinary engineering tasks should not create learning artifacts. - -Only stable, verified, non-sensitive knowledge is promoted into tracked owners such as `learning-flow/MAP.md` or `learning-flow/TAKEAWAYS.md`. - -
-Update modes and root integration - -Framework modes: - -- `fail`: stop when managed content already exists; -- `merge`: add missing files and preserve existing content; -- `update`: refresh framework-owned files and skills while preserving settings, decisions, maps, takeaways, `.local/`, repository-authored content, and unrelated skills; -- `replace`: replace framework directories and this framework's managed skills. - -Extensions follow the same modes: `--extension regulatory` adds it, `--extension none` in `update` or `replace` removes it, and `merge` never removes an installed extension. - -A minimal installation can upgrade safely: - -```sh -./scripts/install.sh --mode update --profile full -``` - -Full-to-minimal update is rejected because automatic deletion could destroy repository-authored content. - -Root modes are `auto`, `integrate`, `initialize`, `preserve`, and `skip`: - -```powershell -./scripts/install.ps1 -RootAgents Integrate -``` - -```sh -./scripts/install.sh --root-agents integrate -``` - -Existing root instructions are never replaced wholesale. - -
+Only stable, verified, non-sensitive knowledge should move into tracked owners such as `learning-flow/MAP.md` or `learning-flow/TAKEAWAYS.md`. ## Installed shape ```text -.local/ agentic-flow/ -├── AGENTS.md -├── SETTINGS.md -├── WORKFLOW.md -├── EDUCATION.md -├── LEARN.md -├── LOCAL.md -└── DECISIONS.md learning-flow/ -├── AGENTS.md -├── MAP.md -├── TAKEAWAYS.md -└── REGULATORY.md (only with --extension regulatory) .agents/skills/ -├── agentic-workflow/ -├── learn-anything/ -├── structured-change/ -├── regulatory-knowledge/ (only with --extension regulatory) -└── profile-specific learning skills +.local/ ``` -Task-specific templates travel inside their owning skills and are materialized only when justified. +Task-specific templates live inside their owning skills and are materialized only when justified. ## Documentation -- [`docs/EDUCATION_MODEL.md`](docs/EDUCATION_MODEL.md): the human learning and ownership model -- [`docs/README.md`](docs/README.md): design and maintenance map -- [`scripts/README.md`](scripts/README.md): installer lifecycle and safety behavior -- [`CHANGELOG.md`](CHANGELOG.md): revision history -- [`LICENSE`](LICENSE): MIT software and CC BY 4.0 documentation and template terms +- [`docs/EDUCATION_MODEL.md`](docs/EDUCATION_MODEL.md) · learning and ownership model +- [`docs/README.md`](docs/README.md) · design and maintenance map +- [`scripts/README.md`](scripts/README.md) · installer lifecycle and safety behavior +- [`CHANGELOG.md`](CHANGELOG.md) · revision history +- [`LICENSE`](LICENSE) · licensing terms + +
+Source layout + +```text +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. + +
diff --git a/sample/common/.agents/skills/agentic-workflow/SKILL.md b/sample/common/.agents/skills/agentic-workflow/SKILL.md index e853a78..ca47251 100644 --- a/sample/common/.agents/skills/agentic-workflow/SKILL.md +++ b/sample/common/.agents/skills/agentic-workflow/SKILL.md @@ -1,61 +1,67 @@ --- name: agentic-workflow -description: Initialize, integrate, configure, explain, map, review, or improve a repository's actual agentic collaboration setup. Use for root AGENTS integration, custom harnesses, instructions, plans, approval gates, validation, session records, external reference integration, or how agentic-flow and learning-flow fit together. Do not load it as a second engineering workflow for an ordinary code task. +description: Initialize, integrate, configure, explain, review, or improve a repository's agentic setup. Use for root AGENTS integration, custom harnesses, instructions, plans, gates, validation, session records, or workflow design. Do not load it as a second engineering workflow. --- # Agentic workflow -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. +Read `agentic-flow/README.md` and `AGENTS.md` first. Read `SETTINGS.md` only when configuration matters. Load only the documents needed for the current operation. -## Discover the actual setup +## Discover 1. Inspect root and nested instructions plus tool-specific files. -2. Find skills, prompts, plans, sessions, status files, ADRs, evidence ledgers, and refresh rules. -3. Detect known template markers. -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. +2. Find skills, prompts, plans, sessions, records, and refresh rules. +3. Detect managed template markers. +4. Inspect custom additions, overrides, conflicts, and precedence. +5. Keep stable policy, task procedures, shared learning, and private `.local/` state distinct. +6. Keep context narrow. ## Initialize or integrate 1. Preserve repository-specific engineering rules. -2. Use `ROOT_INTEGRATION.md` for the matching three-way filesystem choice. -3. Append the managed pointer only when chosen and never duplicate it. -4. Create the lean root only when chosen. Do not invent architecture rules before inspection. -5. Ask for one collaboration preset only during requested or guided configuration. Use advanced overrides only when explicitly needed. -6. In full mode, ask learner context only when it changes useful depth. -7. Update `SETTINGS.md` without rewriting unrelated instructions. -8. Update the learning map only for a durable custom instruction exception or conflict worth reusing. - -## Explain the setup - -1. Lead with the layer map from `LEARN.md`. -2. Point to actual files for each layer. -3. Distinguish template content from repository-specific additions. -4. Explain precedence and selective loading. -5. Put long inventories and edge cases in collapsible sections when presenting Markdown. -6. Use at most one explain-back check unless a quiz was requested. -7. End with a compact ownership and routing recap. - -## Integrate an external reference +2. Use `ROOT_INTEGRATION.md` for the filesystem choice. +3. Add the managed pointer only when chosen and never duplicate it. +4. Create the lean root only when chosen. +5. Ask for configuration only during requested or guided setup. +6. Update `SETTINGS.md` without rewriting unrelated instructions. +7. Update learning maps only for durable custom exceptions or conflicts. + +## Explain + +- Lead with the layer map from `LEARN.md`. +- Point to actual files. +- Distinguish template content from repository-specific additions. +- Explain precedence and selective loading. +- Put inventories and edge cases in collapsibles. +- Use at most one explain-back check unless a quiz was requested. + +## External references 1. Read `REFERENCE_INTEGRATION.md`. -2. Resolve the exact repository revision or archive hash. +2. Resolve the exact source revision or archive hash. 3. Inspect agent-facing documentation and only enough code to understand protected behavior. -4. Treat the source as evidence, not a target architecture; name useful value already covered locally. -5. Retain only a small delta that closes a clear gap, normally zero to three behavioral adjustments. -6. Preserve the educational core, friendly voice, low ceremony, and minimal/full behavior. -7. Fit changes into existing owners; do not add layers or catalogues without a demonstrated need. -8. Add a concise reference review with source designation, covered and retained value, rejected constraints, and resulting changes. -9. Review token cost, routing ambiguity, artifact burden, and migration safety. +4. Treat the source as evidence, not a target architecture. +5. Retain only a small delta that closes a clear gap. +6. Fit changes into existing owners. +7. Record concise provenance. +8. Review token cost, routing ambiguity, artifact burden, and migration safety. + +## Review -## Review an existing harness +Look for: -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. +- temporary handoff in stable instructions; +- contributor-specific learning outside `.local/`; +- mandatory ceremony unrelated to risk; +- duplicated rules; +- unchecked completion claims; +- competing workflows; +- learning mixed into universal execution; +- stale records without owners; +- 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. +Recommend the smallest consolidation. ## 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. +Prefer one authoritative instruction over duplicated policy. If `agentic-flow/AGENTS.md` owns a rule, skills should reference it rather than restate it. Stop when current evidence is sufficient. diff --git a/sample/common/.agents/skills/learn-anything/SKILL.md b/sample/common/.agents/skills/learn-anything/SKILL.md index 9282257..312c71a 100644 --- a/sample/common/.agents/skills/learn-anything/SKILL.md +++ b/sample/common/.agents/skills/learn-anything/SKILL.md @@ -1,59 +1,53 @@ --- name: learn-anything -description: Guide a concise, adaptive conversation for learning, exploring, or practicing any general topic, with optional private continuity under .local for meaningful sessions. Use when the learner wants understanding without analyzing the current repository. Do not use for repository orientation, codebase bugs, features, refactors, or setup. +description: Guide concise, adaptive learning conversations for general topics. Use automatically for understanding, explanation, teaching, or exploration that does not require current repository evidence. --- # Learn Anything -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. +Do not inspect repository code. Read only the relevant parts of `agentic-flow/EDUCATION.md`. -## Conversation loop +## Loop ```text -Locate → Reason → Try → Observe → Explain → Revise → Transfer +Locate → Model → Try → Observe → Revise → Transfer ``` -- **Locate:** identify the actual question, goal, and demonstrated starting point. Infer context where safe; ask at most one question only when it changes the useful route. -- **Reason:** build a compact causal or system model. Introduce vocabulary only when it unlocks the current question. -- **Try:** use the smallest helpful example, comparison, experiment, worked problem, scenario, or practice exchange. -- **Observe:** compare the result with the learner's expectation. -- **Explain:** invite one optional prediction, trace, or articulation when it would deepen understanding. -- **Revise:** correct the model directly when evidence or reasoning exposes a mismatch. -- **Transfer:** connect the insight to one nearby case when useful. +- Identify the question and demonstrated starting point. +- Build the smallest useful causal or system model. +- Use one example, comparison, experiment, worked problem, or practice exchange. +- Compare the result with the learner's expectation. +- Correct the model and follow the learner's questions. +- Transfer to one nearby case when useful. -Collapse obvious stages. A short factual question may need only a direct answer and one clarifying example. +Collapse obvious stages. A short factual question may need only an answer and one example. ## Teaching judgment - Follow curiosity rather than imposing a curriculum. -- Keep flow by matching challenge to demonstrated understanding. -- Use trial and error when attempts are safe and informative. -- Invite the learner to question sources, generated claims, conventions, and authority with evidence. -- Distinguish established fact, interpretation, and uncertainty. -- Use AI examples, simulations, summaries, or practice generation as leverage, but do not present fluency as proof. -- Ask the learner to articulate their reasoning only when it adds value. -- Correct mistakes clearly without humiliation or fake praise. +- Match depth to demonstrated understanding. +- Distinguish fact, interpretation, and uncertainty. +- Question generated claims and authority with evidence. +- Use AI as leverage, not as proof of understanding. +- Ask for articulation only when it adds value. +- Correct mistakes directly without fake praise. -When the topic involves teaching, classrooms, teams, or assessment, selectively apply the human educational section of `agentic-flow/EDUCATION.md`. Do not diagnose or persist sensitive learner state. +Use at most one prediction, trace, or explain-back by default. ## 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: +When useful, select only the relevant subset: - purpose or outcome; -- boundary and surrounding context; -- actors, parts, and relationships; -- flow, state change, feedback, or tradeoff; -- evidence, exceptions, and uncertainty; +- boundary and context; +- parts and relationships; +- flow, state, feedback, or tradeoff; +- evidence and uncertainty; - human judgment or responsibility; -- transfer to a nearby case. - -Prefer one representative interaction through the system over an inventory of facts. +- transfer. -## Local continuity +Prefer one representative interaction over an inventory. -Read `agentic-flow/LOCAL.md` only when continuity or closure applies. Do not create a session file for a one-off answer. +## Continuity -At natural closure of a meaningful session, retain the goal, useful attempts, observations, revised model, learner articulation, and next direction privately. Do not write generic personal learning into repository `MAP.md` or `TAKEAWAYS.md`. +Use `agentic-flow/LOCAL.md` only for meaningful continuity or closure. Do not create session files for one-off answers. diff --git a/sample/common/.agents/skills/structured-change/SKILL.md b/sample/common/.agents/skills/structured-change/SKILL.md index 608b74a..e5dc134 100644 --- a/sample/common/.agents/skills/structured-change/SKILL.md +++ b/sample/common/.agents/skills/structured-change/SKILL.md @@ -1,62 +1,47 @@ --- name: structured-change -description: Sequence Explore, Design, and Approve before Act for one consequential, ambiguous, or high-risk change, producing a right-sized exploration note and design note with a requested decision. Use alongside the active learning or engineering skill for a single significant change. Do not use it as mandatory ceremony for ordinary, low-risk, or unambiguous work, and do not use it as a second engineering procedure. +description: Sequence Explore, Design, and Approve for one consequential, ambiguous, or high-risk change. Use alongside the active route, never as mandatory ceremony for ordinary work. --- # Structured change -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. +Read `agentic-flow/AGENTS.md` and the relevant `WORKFLOW.md` sections. Read `SETTINGS.md` only when the preset affects the decision. -## When this applies +## Use when -Use it only when at least one is true: +- the change is architecturally significant, hard to reverse, or spans owners; +- credible options remain unresolved by evidence; +- `gated` mode or the user explicitly requests a design review or migration plan; +- installed regulatory guidance applies to validated, safety-relevant, or audited behavior. -- the change is architecturally significant, hard to reverse, or spans multiple owners; -- two or more credible approaches exist and repository evidence does not select one; -- the configured preset is `gated`, or the user asked for a design review, migration plan, or formal decision; -- `.agents/skills/regulatory-knowledge/` is installed and the change affects validated, safety-relevant, or audited behavior. - -Skip it for a routine bug, small feature, refactor, or anything `balanced` or `fast` resolves directly. Most tasks never touch this skill. +Skip it for routine, small, reversible, or unambiguous work. ## Explore -1. State the currently understood behavior, purpose, and constraints; separate established fact from assumption. -2. List unknowns and the risks or options they affect. -3. Stop at understanding here. Do not propose or implement yet. - -Keep this conversational by default. Use `templates/exploration.md` only when a written artifact will earn its cost, per Scale below. +State current behavior, purpose, constraints, unknowns, and affected risks. Separate facts from assumptions. Stop here. ## Design -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, 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. +Compare credible options, select an approach, name the remaining decision, and state verification and rollback where genuinely needed. -Use `templates/design.md` only when it earns its cost, per Scale below. +If regulatory guidance applies, read only the specific knowledge needed and note traceability, validation impact, and requirement linkage. Do not invent compliance language. ## Approve -State the requested decision plainly and wait for it before implementing. An explicit prior instruction that already resolves the choice satisfies this step; do not ask again. +State the decision plainly and wait before implementing. An explicit prior instruction that resolves it is approval. ## Implement and review -Follow the approved design under the normal `agentic-flow/WORKFLOW.md` loop. Note any deviation from the design and why. For work spanning more than one commit, review each meaningful commit against the approved design before starting the next rather than reviewing everything at the end. +Follow the normal workflow. Note deviations. For multi-commit work, review each meaningful commit against the approved design. -## Capture knowledge +## Capture -- Fold the outcome into the normal handoff. -- Record a durable decision in `agentic-flow/DECISIONS.md` only when the choice will matter to someone reading the repository later. Most decisions stay in conversation or `.local/`. -- Note a deferred improvement or modernization opportunity as an `Open` handoff item, or in `DECISIONS.md` when a future decision is already anticipated. Do not create a separate improvement-tracking file. +Fold the result into the normal handoff. Record a durable decision only when it will matter later. Keep deferred improvements in `Open` or `DECISIONS.md`, not a new tracker. -## Scale to profile, preset, and risk +## Scale -- `minimal` profile or `fast`/`balanced` preset: keep Explore and Design conversational, a few sentences each. -- `full` profile or `guided`/`gated` preset, or a genuinely high-risk change: use the templates, add characterization evidence, and keep the traceability fields in `agentic-flow/WORKFLOW.md`'s commit guidance. -- `regulatory-knowledge` installed: read only the specific knowledge file the decision touches, not the whole set. +Keep low-risk work conversational. Use written templates only when the change's risk, duration, or handoff justifies them. ## Restraint -- One structured decision per change; do not stack this with a second formal process. -- Never require this skill for ordinary work, and never block on a declined design review unless the user or repository instructions require sign-off. -- Prefer the simplest acceptable solution over the most abstract one; see `knowledge/engineering/ai-collaboration.md` for indicators. +One structured decision per change. Never stack a second formal process on top. Prefer the simplest acceptable solution. diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index 39fd4d9..7889774 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -1,96 +1,83 @@ # Agentic collaboration instructions -## Layer 1: Agentic Delivery +This is the common Agentic Delivery layer. It owns collaboration behavior, routing, verification, handoff, and consequential-action boundaries. -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. +Learning & Ownership and Optional Risk Lenses add guidance without becoming a second workflow. ## Route 1. Follow root, nested, and tool-specific repository instructions first. 2. Use this layer for collaboration behavior. -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. +3. Select one primary task route. +4. **Treat learning as default behavior:** general understanding requests use `learn-anything`; current-repository understanding uses repository learning. +5. During implementation, reinforce understanding when useful without turning the task into a lesson. +6. Use `structured-change` alongside the active route only for one consequential, ambiguous, or regulated change. +7. Read configuration documents only when configuration matters. + +## Learning behavior + +For `help me understand`, `explain`, `teach me`, and similar requests: -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. +- keep the exchange conversational; +- build a compact causal or system model; +- use one useful example, experiment, comparison, or worked problem; +- ask at most one prediction, trace, or explain-back when it improves understanding; +- let the user's questions steer depth; +- correct mistaken models directly; +- collapse the loop for short factual questions. + +For code work, teach the relevant system, rule, boundary, or evidence when that helps ownership. Do not add a quiz or learning artifact merely because the framework can. ## Context budget -The framework is intentionally progressive-disclosure. Context is a limited engineering resource, not a reason to load every framework document. +Context is a limited engineering resource. - 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. +- Select one primary route before loading task-specific instructions. +- Load only files that route names as necessary. +- Treat indexes and manifests as pointers, not preload requests. +- Reuse current evidence instead of rescanning it. +- Stop when the evidence threshold is met. +- Small or mechanical work should use the smallest useful sequence. -The intended default is: +Default: ```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 -Do not assume this template is the repository's only harness. Respect existing instructions, skills, prompts, plans, records, and agent-specific files. Treat managed template files as known; inspect custom additions, overrides, effective precedence, and conflicts only when they affect the work. Use `LEARN.md`, `LOCAL.md`, and `ROOT_INTEGRATION.md` when those boundaries need explanation. +Respect existing instructions, skills, prompts, plans, records, and agent-specific files. Inspect custom additions, overrides, conflicts, and precedence only when they affect the work. -Treat third-party skills as executable instructions. Before adding or first using one, inspect its pinned source, referenced scripts or resources, required tools, network or secret access, side effects, maintenance, and overlap with repository rules. Popularity or catalogue inclusion is discovery evidence, not a security review. Prefer one narrow skill for a demonstrated need over a broad bundle. +Treat third-party skills as executable instructions. Before first use, inspect their source, referenced resources, required tools, access, side effects, maintenance, and overlap with repository rules. Prefer one narrow skill for a demonstrated need. -## Default behavior - -Use current repository evidence as truth; plans and summaries may have drifted. +## Default workflow ```text Frame → Inspect → Decide → Act → Verify → Handoff ``` -Collapse obvious steps for small work. Do not create a plan, session, status artifact, or lesson merely because the framework supports one. Follow `WORKFLOW.md` when the detailed execution or handoff shape matters. - -For a non-repository learning request, use `learn-anything`. Keep the exchange conversational, inspect no repository code, and use `.local/` only for meaningful private continuity as defined in `LOCAL.md`. Questions that require current codebase evidence return to repository learning. - -## Communication - -- Lead with the useful result, next action, or compact map. -- Say what changed and why it matters; group substantial updates into a few outcome-based sections rather than a tool log or file inventory. -- Start substantial work with the intended outcome and a short route when sequencing matters. Update only when the phase or route changes, a blocker appears, or silence would become confusing. -- Prefer plain language and a compact overview before detail. Use `
` for optional rationale, long evidence, command matrices, alternatives, or examples. -- Keep warnings, unresolved decisions, validation failures, and required next actions visible. -- Match depth to the task and the user's demonstrated context. +Collapse obvious steps for small work. Use `WORKFLOW.md` when detailed execution or handoff guidance matters. ## Questions and authority -Ask only when a consequential product, architecture, dependency, compatibility, safety, or irreversible choice remains unresolved; evidence cannot distinguish responsible options; configured mode requests a gate; or root integration is the task. - -When collaboration behavior needs configuration, ask for one preset from `CONFIGURE.md`. Ask for an individual override only when no preset fits, and ask the root-integration choice only when that integration is unresolved. Do not run questionnaires during ordinary work. +Ask only when a consequential choice is unresolved, evidence cannot distinguish responsible options, configured mode requests a gate, or root integration is unresolved. An explicit implementation request permits ordinary reversible work within scope. It does not permit destructive Git operations, publishing, release actions, secret access, or unrelated changes. -## Planning, execution, and records +## Planning and records -- Small tasks need no formal plan; multi-step tasks use a short in-chat plan. +- Small tasks need no formal plan. - Create a plan file only when risk, duration, configuration, or handoff justifies it. -- Record a durable decision in `DECISIONS.md` only when it will matter to a later reader; most decisions stay in conversation or `.local/`. -- Inspect the smallest responsible scope and prefer one coherent change over artificial micro-steps. -- Revisit the route when evidence changes the scope, architecture, or behavior. -- Validate in proportion to risk, focused first. Separate changes applied from executable checks completed and never claim unavailable verification. -- Keep ordinary session records, ledgers, and status files optional. Keep temporary handoff out of stable instructions. -- At natural closure of a meaningful learning session, save private state and compact continuity under `.local/` according to `LOCAL.md`; do not store it elsewhere. +- Record durable decisions only when they matter to later readers. +- Validate in proportion to risk and distinguish applied changes from executable proof. +- Keep temporary state out of stable instructions. +- Use `.local/` for meaningful private learning continuity. ## Handoff -End substantial work with the plain-language result and only the useful sections below: +End substantial work with only useful sections: ```text Changed @@ -103,34 +90,10 @@ Open - Remaining risk, decision, or next action. ``` -Omit empty sections, repeated narration, and exhaustive file lists. When learning was central, fold useful reinforcement into this handoff instead of adding a second recap. - -For a substantive commit, use a short imperative title and only body sections that add context: - -```text -Why: -- problem or intent - -What: -- behavior changed and its effect - -Checks: -- meaningful verification -``` - -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 +Omit empty sections, repeated narration, and exhaustive file lists. -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. +## Learning closure -At pull-request or substantial change completion, make this decision part of -the normal handoff rather than creating a separate documentation ceremony. +Use `learning-closure` only when work produced a reusable insight. Recommend the smallest destination and let the user decide whether to persist it. -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. +Use `learning-freshness` during deliberate maintenance or when durable repository knowledge may have drifted. diff --git a/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md b/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md index 4d09a2e..1d80ac9 100644 --- a/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md +++ b/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md @@ -1,21 +1,21 @@ --- name: repository-orientation -description: Explain or map an unfamiliar repository, subsystem, architecture boundary, domain territory, runtime path, or ownership area. Use when orientation is primary; do not combine it with a full bug, feature, or refactor workflow. +description: Explain or map an unfamiliar repository, subsystem, architecture boundary, domain territory, runtime path, or ownership area. Use when orientation is primary. --- # Repository orientation -Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md`. Read `agentic-flow/EDUCATION.md`, `learning-flow/AGENTS.md`, and only relevant shared records. +Follow `agentic-flow/AGENTS.md` and `SETTINGS.md`. Read only relevant education guidance and shared records. 1. Identify the intended human, business, scientific, or physical outcome. -2. Frame the actor or caller, capability, governing rule, and system boundary. +2. Frame actor or caller, capability, governing rule, and system boundary. 3. Show a compact domain slice before file detail. 4. Trace one representative execution, data, material, or decision path. 5. Connect claims to source, tests, configuration, runtime or domain evidence, or explicit inference. -6. Identify the important failure, access, deployment, legacy, or human control boundary when relevant. +6. Identify important failure, access, deployment, legacy, or human-control boundaries when relevant. 7. Name the highest-value unknown. -8. Stop when the user can locate, explain, challenge, and safely continue in the territory. +8. Stop when the user can locate, explain, challenge, and safely continue. -Ask at most one consequential trace, prediction, or explain-back. Create or update an artifact only when the persistence threshold is met. +Ask at most one consequential trace, prediction, or explain-back. Create or update an artifact only when its persistence value is clear. -Output a compact mental model, small visual when useful, stable paths or symbols, representative path, evidence, uncertainty, control boundary, and one next challenge. +Output a compact mental model, useful visual when appropriate, representative path, evidence, uncertainty, control boundary, and one next challenge. diff --git a/sample/profiles/minimal/learning-flow/AGENTS.md b/sample/profiles/minimal/learning-flow/AGENTS.md index 0ad7917..e07d319 100644 --- a/sample/profiles/minimal/learning-flow/AGENTS.md +++ b/sample/profiles/minimal/learning-flow/AGENTS.md @@ -1,59 +1,46 @@ # Minimal repository learning instructions -## Layer 2: Learning & Ownership +This layer adds repository understanding, learning reinforcement, private continuity, and deliberate knowledge promotion on top of Agentic Delivery. It does not replace delivery or create a universal execution gate. -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. +## When to use -It does not replace the delivery workflow or create a universal execution -gate. Load it only when repository learning materially improves the task. +Use it automatically when the user is trying to understand the current repository, subsystem, bug, feature, refactor, or setup. Do not load it for purely mechanical edits. -## Priority and scope - -Follow repository-native instructions and `agentic-flow/AGENTS.md` first. This layer adds learning support only. - -Use it for repository understanding, learning through a bug or feature, a non-trivial mechanism, safe refactoring with explanation, or a requested baseline. Do not load it for every mechanical edit. - -Read `agentic-flow/EDUCATION.md` through the selected `repository-learning` skill. Apply only the lenses that materially improve the task. +Read `agentic-flow/EDUCATION.md` through the selected learning skill and only the relevant shared records. ## Core flow ```text -Locate → Reason → Try or Work → Verify → Explain → Transfer +Locate → Reason → Work → Verify → Explain → Transfer ``` -1. Locate the relevant business, physical, domain, or technical system before file detail. -2. Identify the outcome, boundary, governing rule, representative path, and nearest proof surface. -3. Use the smallest responsible investigation, experiment, or change under `agentic-flow/WORKFLOW.md`. -4. Validate generated and human work against decisive evidence and relevant failure modes. -5. Ask at most one check when a mistaken model would affect later work. -6. Fold useful learning into the normal handoff without adding a second recap. +1. Locate the relevant business, scientific, human, physical, domain, or technical system. +2. Identify the outcome, boundary, rule or invariant, representative path, and proof surface. +3. Investigate or work through the smallest responsible route. +4. Verify against decisive evidence and relevant failure modes. +5. Use at most one check-back when a mistaken model would affect later work. +6. Fold useful learning into the normal handoff. -## Task branches +## Branches -- Bug: affected outcome or rule → symptom → expectation → decisive probe → mechanism → containment or fix → regression proof. -- Feature: actor and outcome → should it exist → capability and invariants → valid analogue → differences → seam → proof and operational control. -- Refactor: behavior or domain invariant → evidence → smallest seam → transformation → proof → simpler ownership. -- Orientation: intended use → system boundary → representative path → control and failure boundary → next useful territory. +- **Bug:** outcome or rule → symptom → expectation → discriminating probe → mechanism → fix → regression proof. +- **Feature:** actor and outcome → capability and invariants → valid analogue → differences → seam → proof. +- **Refactor:** invariant → observable contract → proof → smallest seam → transformation → simpler ownership. +- **Orientation:** intended use → boundary → representative path → control and failure boundary → next useful territory. -Select one branch. `agentic-workflow` is for the harness itself, not a second engineering procedure. For one architecturally significant, ambiguous, or regulated change within a branch, `structured-change` may run alongside it; it does not replace the branch. +Select one branch. `agentic-workflow` is for the harness itself, not a second engineering procedure. `structured-change` may run alongside one branch for a consequential or ambiguous change. -## Context and interaction economy +## Economy -- Search narrowly before reading broad directories or history. -- Reuse `MAP.md` and `TAKEAWAYS.md` before rescanning. +- Search narrowly before reading broadly. +- Reuse `MAP.md` and `TAKEAWAYS.md`. - Prefer one representative flow over an inventory. -- Stop when decisive evidence identifies the mechanism or remaining uncertainty is bounded. -- Use trial and error only when attempts are safe, small, and informative. -- Do not force regulatory, safety, classroom, or physical-system questions onto unrelated low-risk work. +- Stop when decisive evidence identifies the mechanism or bounds the uncertainty. +- Use safe trial and error only when it is informative. +- Do not force regulatory, safety, classroom, or physical-system lenses onto unrelated work. ## Persistence -Conversation is the default. Close meaningful sessions through `agentic-flow/LOCAL.md`. - -Promote into `MAP.md` or `TAKEAWAYS.md` only verified, repository-specific, reusable, non-sensitive knowledge that is costly enough to rediscover. Keep raw attempts, personal state, uncertainty, secrets, customer data, sensitive operational evidence, and private conflict under `.local/` only. - -## Evidence +Conversation is the default. Use `.local/` for meaningful private continuity. -Distinguish claims verified from source, configuration, tests, runtime evidence, domain evidence, contributor report, and inference. Do not present inferred production behavior as fact. +Promote only verified, repository-specific, reusable, non-sensitive knowledge that is costly enough to rediscover. diff --git a/sample/root/AGENTS.md b/sample/root/AGENTS.md index 6d545f5..77825ca 100644 --- a/sample/root/AGENTS.md +++ b/sample/root/AGENTS.md @@ -1,23 +1,34 @@ # Repository agent instructions +## Default behavior + +Use the repository's current evidence as truth. Keep changes within scope and distinguish inspected facts from executed proof. + +**Learning is part of the default agent behavior.** Do not require the user to describe a learning method. + +- For `help me understand`, `explain`, `teach me`, and similar general questions, use `learn-anything`. +- For questions about this repository, use the repository-learning route. +- For implementation work, follow the normal delivery workflow and teach the relevant system when that improves ownership. +- Build a compact model, use a useful example or experiment when it helps, and check back once when that can expose a mistaken understanding. +- Collapse the learning flow for short or mechanical tasks. Do not turn it into ceremony. + ## Evidence and scope -- Treat repository source, configuration, tests, and current executable evidence as more authoritative than stale plans or summaries. +- Treat source, configuration, tests, and current executable evidence as more authoritative than stale plans or summaries. - Inspect affected consumers, tests, scripts, generated surfaces, and operational boundaries before changing a public or architectural contract. -- Keep changes inside the requested scope and avoid unrelated cleanup. - Separate facts established by inspection from behavior proven by execution. -- Never claim validation that the available toolchain or environment did not perform. +- Never claim validation the available environment did not perform. ## Collaboration layers -For collaboration behavior, planning, validation, and handoff, follow -`agentic-flow/AGENTS.md`. +For collaboration behavior, planning, validation, and handoff, follow `agentic-flow/AGENTS.md`. + +For repository learning, onboarding, explanation, and durable understanding, follow `learning-flow/AGENTS.md` when relevant. -For repository learning, onboarding, explanation, and durable understanding, -follow `learning-flow/AGENTS.md` when relevant. +For general-topic learning, use the common `learn-anything` skill automatically when the question is about understanding a topic rather than the current repository. -Repository-specific architecture, security, commands, conventions, and release rules belong in this file or narrower nested instructions. Private learning history, contributor progress, checks, and temporary task handoff belong in the conversation or ignored `.local/`, never stable instructions or shared learning records. +Repository-specific architecture, security, commands, conventions, and release rules belong in this file or narrower instructions. Private learning history and temporary task state belong in the conversation or ignored `.local/`. Do not commit, push, publish, merge, rewrite history, or perform destructive Git operations unless explicitly requested. diff --git a/sample/root/AGENTS.pointer.md b/sample/root/AGENTS.pointer.md index 2005c1d..ddd60ff 100644 --- a/sample/root/AGENTS.pointer.md +++ b/sample/root/AGENTS.pointer.md @@ -1,7 +1,7 @@ -For collaboration behavior, planning, validation, and handoff, follow -`agentic-flow/AGENTS.md`. +For collaboration behavior, planning, validation, and handoff, follow `agentic-flow/AGENTS.md`. -For repository learning, onboarding, explanation, and durable understanding, -follow `learning-flow/AGENTS.md` when relevant. +**Learning is automatic:** `help me understand`, `explain`, `teach me`, and similar general questions use `learn-anything`; questions about the current repository use repository learning. Build a compact model, use a useful example when helpful, and check back for understanding when it adds value. + +Do not turn mechanical work into a lesson. Keep the user's actual task primary.