diff --git a/CHANGELOG.md b/CHANGELOG.md index 26aa9b2..6b6e7c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,11 @@ Architectural simplification of the `full` profile: reduced meta-ceremony while - Deduplicated the external-source provenance field list between `learning-closure` and `learning-freshness`; `learning-closure` is now the single owner. - `full/learning-flow/README.md` diagram and "Understanding and assessment" section updated to match the reduced skill count and single canonical rule. - `ticket-learning-path`'s implementation-handoff step now names `repository-learning` instead of the three merged skills. +- Consolidated `repository-learning` into one common skill owner shared by minimal and full profiles, preserving focused Orientation, Bug, Feature, and Refactor routes. +- Reduced profile `learning-flow/AGENTS.md` files to routing and profile-specific persistence concerns, removing duplicated common policy. +- Removed redundant full-profile bootstrap, playbook, and understanding-check documents whose rules are now owned by the common workflow or selected skill. +- Added regression coverage for shared skill ownership and profile routing. + ## 1.1.0 diff --git a/MANIFEST.txt b/MANIFEST.txt index 7de62e5..a04f396 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,14 +1,14 @@ .gitattributes 40 .gitignore 324 AGENTS.md 2995 -CHANGELOG.md 24247 +CHANGELOG.md 24788 LICENSE 2213 README.md 8952 adoption/ADOPT.md 4177 adoption/README.md 2057 -docs/AGENTIC_WORKFLOW_SANITY.md 9207 +docs/AGENTIC_WORKFLOW_SANITY.md 9802 docs/ARCHITECTURE.md 7131 -docs/DESIGN_NOTES.md 35837 +docs/DESIGN_NOTES.md 36475 docs/EDUCATION_MODEL.md 5452 docs/INITIALIZE_LEARNING_FLOW.md 10880 docs/README.md 4016 @@ -19,12 +19,13 @@ docs/references/REFERENCE_REVIEW_GOOSE.md 2486 docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md 9505 docs/references/REFERENCE_REVIEW_LITT.md 2069 docs/references/REFERENCE_REVIEW_POCOK.md 2155 -sample/README.md 2997 +sample/README.md 3065 sample/common/.agents/skills/agentic-workflow/SKILL.md 2686 sample/common/.agents/skills/learn-anything/SKILL.md 1756 sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 sample/common/.agents/skills/learning-closure/SKILL.md 3605 sample/common/.agents/skills/learning-freshness/SKILL.md 1908 +sample/common/.agents/skills/repository-learning/SKILL.md 4904 sample/common/.agents/skills/structured-change/SKILL.md 3059 sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md 2533 sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md 1386 @@ -37,7 +38,7 @@ sample/common/.agents/skills/structured-change/templates/design.md 649 sample/common/.agents/skills/structured-change/templates/exploration.md 368 sample/common/.agents/skills/structured-change/templates/structure.md 243 sample/common/agentic-flow/.managed-files 170 -sample/common/agentic-flow/.managed-skills 86 +sample/common/agentic-flow/.managed-skills 106 sample/common/agentic-flow/.template-version 6 sample/common/agentic-flow/AGENTS.md 5995 sample/common/agentic-flow/CONFIGURE.md 4475 @@ -74,20 +75,19 @@ sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md 1491 sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md 1513 sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md 405 sample/profiles/full/learning-flow/.managed-files 87 -sample/profiles/full/learning-flow/.managed-skills 77 +sample/profiles/full/learning-flow/.managed-skills 57 sample/profiles/full/learning-flow/.template-profile 5 sample/profiles/full/learning-flow/.template-version 6 -sample/profiles/full/learning-flow/AGENTS.md 6548 +sample/profiles/full/learning-flow/AGENTS.md 2580 sample/profiles/full/learning-flow/MAP.md 1464 -sample/profiles/full/learning-flow/README.md 2320 +sample/profiles/full/learning-flow/README.md 2345 sample/profiles/full/learning-flow/REPOSITORIES.md 439 sample/profiles/full/learning-flow/TAKEAWAYS.md 970 -sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md 3718 sample/profiles/minimal/learning-flow/.managed-files 87 -sample/profiles/minimal/learning-flow/.managed-skills 20 +sample/profiles/minimal/learning-flow/.managed-skills 0 sample/profiles/minimal/learning-flow/.template-profile 8 sample/profiles/minimal/learning-flow/.template-version 6 -sample/profiles/minimal/learning-flow/AGENTS.md 2633 +sample/profiles/minimal/learning-flow/AGENTS.md 1362 sample/profiles/minimal/learning-flow/MAP.md 1229 sample/profiles/minimal/learning-flow/README.md 1974 sample/profiles/minimal/learning-flow/TAKEAWAYS.md 973 @@ -95,13 +95,13 @@ sample/root/AGENTS.md 2102 sample/root/AGENTS.pointer.md 551 scripts/README.md 6771 scripts/install.bat 1477 -scripts/install.ps1 40236 -scripts/install.sh 34910 +scripts/install.ps1 40477 +scripts/install.sh 34980 skill-evals/README.md 1667 skill-evals/adoption-cases.yaml 1337 skill-evals/agentic-cases.yaml 8895 skill-evals/conversation-cases.yaml 3653 -skill-evals/full-cases.yaml 4648 -skill-evals/learning-lifecycle-cases.yaml 1599 -skill-evals/minimal-cases.yaml 3655 +skill-evals/full-cases.yaml 5001 +skill-evals/minimal-cases.yaml 3913 skill-evals/structured-change-cases.yaml 4710 +skill-evals/learning-lifecycle-cases.yaml 1599 diff --git a/docs/AGENTIC_WORKFLOW_SANITY.md b/docs/AGENTIC_WORKFLOW_SANITY.md index 990ef5f..a28ec48 100644 --- a/docs/AGENTIC_WORKFLOW_SANITY.md +++ b/docs/AGENTIC_WORKFLOW_SANITY.md @@ -213,3 +213,17 @@ For each scenario, review the agent interaction for: - 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. + +### 12. Shared skill ownership + +**Prompt:** Update the repository-learning behavior used by both minimal and full profiles. + +Expected behavior: + +- identify `repository-learning` as one shared skill owner; +- do not create or edit profile-specific duplicate implementations; +- ensure profile managed-skill declarations and `MANIFEST.txt` resolve to the same source; +- preserve profile-specific routing in `learning-flow/AGENTS.md`. + +Failure signal: a profile declares a skill whose implementation is only discoverable by following another profile, or two profile copies can drift independently. + diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index d6e4b06..ca4f838 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -4,6 +4,15 @@ 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. +## v1.3 consolidation and ownership boundaries + +The 1.3 cleanup makes three small maintenance boundaries explicit: + +1. `repository-learning` has one common skill owner. Minimal and full profiles differ in routing and persistence surfaces, not by carrying duplicate implementations. +2. Profile `learning-flow/AGENTS.md` files are routing contracts. Common collaboration, context economy, evidence, understanding-check, and handoff policy remains owned by the common agentic/education layer. + +The goal is lower effective context, less opportunity for agentic drift, and faster human navigation without introducing another framework layer. + ## Current three-layer architecture The current architecture consolidates the earlier ownership distinctions into three user-facing framework layers: diff --git a/sample/README.md b/sample/README.md index fc5d22d..37013cd 100644 --- a/sample/README.md +++ b/sample/README.md @@ -24,6 +24,7 @@ sample/common/agentic-flow/ sample/common/.agents/skills/agentic-workflow/ sample/common/.agents/skills/learn-anything/ sample/common/.agents/skills/structured-change/ +sample/common/.agents/skills/repository-learning/ sample/common/local/learning-history.md sample/profiles/minimal/ sample/profiles/full/ @@ -35,7 +36,7 @@ sample/root/ |---|---| | `agentic-flow/` | planning, autonomy, validation, records, and handoff | | `agentic-flow/EDUCATION.md` | system ownership, resilience, AI independence, and teaching judgment | -| `learning-flow/` | repository education and durable shared knowledge | +| `learning-flow/` | repository education, profile routing, and durable shared knowledge | | `learn-anything` | conversational learning without repository inspection | | `structured-change` | Explore/Design/Approve sequencing for one consequential change, any profile | | `extensions/regulatory` | optional, additive traceability/validation/risk-management knowledge | diff --git a/sample/common/.agents/skills/repository-learning/SKILL.md b/sample/common/.agents/skills/repository-learning/SKILL.md new file mode 100644 index 0000000..4859598 --- /dev/null +++ b/sample/common/.agents/skills/repository-learning/SKILL.md @@ -0,0 +1,79 @@ +--- +name: repository-learning +description: Understand or work on a repository through one focused route for orientation, bugs, analogous features, or safe refactors. Use when repository understanding materially affects the task; do not turn mechanical work into a learning workflow. +--- + +# Repository learning + +Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md`. Read `agentic-flow/EDUCATION.md` selectively and only the relevant shared records. + +## Shared route + +1. Identify the real outcome, system boundary, governing rule or invariant, representative path, and proof surface. +2. Work from decisive repository evidence before committing to a model or proposed design. +3. Use the smallest responsible investigation, attempt, or change. +4. Verify against decisive evidence and relevant failure modes. +5. Use at most one consequential understanding check when a mistaken model would affect later reasoning. +6. Transfer only verified, reusable learning into the normal handoff or a qualified shared record. + +Select exactly one branch below. Do not load or execute the other branches. + +## Orientation + +1. Identify the intended human, business, scientific, or physical outcome. +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 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. + +Output a compact mental model, useful visual when appropriate, representative path, evidence, uncertainty, control boundary, and one next challenge. + +## Bug + +1. State the affected real-world outcome or rule, observable symptom, and falsifiable expectation. +2. Identify immediate safety, data, access, or operational containment when relevant. +3. Find the smallest discriminating reproduction, test, trace, log, or safe observation. +4. Rank credible hypotheses and test one uncertainty at a time. +5. Explain the failure mechanism before changing code. +6. Validate machine-generated and human hypotheses against decisive evidence. +7. Apply the narrowest responsible containment or fix when requested. +8. Add proportional regression evidence and name the degraded mode, fallback, or untested boundary. +9. Stop when one mechanism explains the symptom and evidence distinguishes it from credible alternatives. + +Do not keep a hypothesis diary. Report symptom, expectation, containment, decisive evidence, mechanism, fix or seam, regression proof, operational boundary, and remaining risk. + +## Feature + +1. Define the actor, intended outcome, capability, observable behavior, and governing invariants. +2. Test whether the behavior should be built or automated, and what must remain a human decision. +3. Search by behavior and evidence, not name alone. +4. Compare candidates across domain rules, data flow, configuration, interface, tests, failure effects, access, and operations. +5. Select the nearest valid analogue. +6. Separate shared invariants from intentional differences. +7. Use the smallest established extension seam. +8. Prove the reused invariant, intended difference, failure behavior, and control boundary in proportion to risk. + +Ask at most one check about why the analogue is valid or where copying it would be wrong. Report the selected analogue, invariant/difference boundary, build judgment, seam, proof, risks, controls, and deferred divergence. + +## Refactor + +1. State the behavior or domain invariant that must remain stable. +2. Identify the observable contract, failure boundary, access or deployment control, and fallback that cannot be lost. +3. Inspect existing proof and add characterization only where necessary. +4. Identify the smallest safe seam. +5. Apply reviewable transformations. +6. Run the narrowest useful checks after meaningful steps. +7. Confirm the result is simpler to own, validate, recover, and explain. +8. Confirm no custom glue or AI dependency was added unnecessarily. +9. Stop when the contract is explicit, relevant checks pass, and no unproven boundary is hidden. + +Ask at most one check about the preserved contract, failure boundary, or new responsibility boundary. Report the contract, evidence before and after, transformation sequence, resilience preserved, simplification, and remaining risk. + +## Persistence + +Use `MAP.md`, `TAKEAWAYS.md`, and, in the full profile, `REPOSITORIES.md` as the single owners for durable shared knowledge. Keep private attempts, personal state, uncertainty, secrets, and sensitive operational evidence under `.local/`. + +Promote only verified, repository-specific, reusable, non-sensitive findings that are costly enough to rediscover. diff --git a/sample/common/agentic-flow/.managed-skills b/sample/common/agentic-flow/.managed-skills index ea3d943..0a1b01d 100644 --- a/sample/common/agentic-flow/.managed-skills +++ b/sample/common/agentic-flow/.managed-skills @@ -3,3 +3,4 @@ learn-anything structured-change learning-closure learning-freshness +repository-learning diff --git a/sample/profiles/full/learning-flow/.managed-skills b/sample/profiles/full/learning-flow/.managed-skills index 45bd2cd..4f8bbab 100644 --- a/sample/profiles/full/learning-flow/.managed-skills +++ b/sample/profiles/full/learning-flow/.managed-skills @@ -1,4 +1,3 @@ learning-bootstrap -repository-learning change-explainer ticket-learning-path diff --git a/sample/profiles/full/learning-flow/AGENTS.md b/sample/profiles/full/learning-flow/AGENTS.md index 6c57138..99d6dbe 100644 --- a/sample/profiles/full/learning-flow/AGENTS.md +++ b/sample/profiles/full/learning-flow/AGENTS.md @@ -1,10 +1,8 @@ # Full learning-flow instructions -## Priority and scope - Follow repository-native instructions and `agentic-flow/AGENTS.md` first. General collaboration, approvals, validation, records, and handoff belong to `agentic-flow/`. -This file governs learning-oriented repository work. Every selected learning skill reads and applies `agentic-flow/EDUCATION.md` selectively. +This profile adds deliberate repository learning surfaces and focused routing. The shared `repository-learning` skill owns the actual Orientation, Bug, Feature, and Refactor procedures. ## Select one primary skill @@ -15,97 +13,28 @@ This file governs learning-oriented repository work. Every selected learning ski | non-trivial change explanation | `change-explainer` | | task context before implementation | `ticket-learning-path` | -`repository-learning` selects one branch — Orientation, Bug, Feature, or Refactor — matching the task; see its `SKILL.md` for the branch routes. Do not load all skills. Do not use `agentic-workflow` as a second engineering procedure. For one architecturally significant, ambiguous, or regulated change within the selected skill's work, `structured-change` may run alongside it; it does not replace the selected skill. - -## Shared learning flow - -```text -Locate → Reason → Try or Work → Verify → Explain → Transfer -``` - -Each pass through Locate–Reason can be one small round: one question, the evidence for it, the resulting understanding, then continue or stop. Stop as soon as the current understanding is sufficient for the task — do not plan the full investigation up front. +Do not load all skills. Do not use `agentic-workflow` as a second engineering procedure. For one architecturally significant, ambiguous, or regulated change within the selected skill's work, `structured-change` may run alongside it; it does not replace the selected skill. -- Locate the real system, outcome, boundary, governing rule, representative path, and proof surface. -- Reason from an explicit invariant, contract, hypothesis, valid analogue, or safe seam. -- Use the smallest responsible attempt, investigation, or change. -- Verify generated and human work against decisive evidence and relevant failure modes. -- Explain through at most one consequential check. -- Transfer only useful learning into the normal handoff or a qualified shared record. +## Fallback routing -Treat the selected territory as a system before diving into files. Prefer one representative interaction over an inventory. - -## Branches - -For an agent without task-skill support, use this table directly instead of loading a `SKILL.md`: +For an agent without task-skill support, use the matching branch in `repository-learning`: | Task | Learning route | |---|---| | Orientation | real outcome → system boundary → representative path → control and failure boundary → next territory | | Bug | affected outcome/rule → symptom → expectation → decisive probe → mechanism → containment/fix → proof | -| Feature | actor/outcome → should it exist → invariants → valid analogue → differences → seam → proof and control | +| Feature | actor/outcome → capability and invariants → valid analogue → differences → seam → proof and control | | Refactor | behavior/invariant → evidence → failure boundary → smallest seam → transformation → proof → simpler ownership | | Change explanation | intended outcome → governing rules → generated/human decisions → conceptual walkthrough → risks and proof | | Ticket path | actor/outcome → ownership → build judgment → missing context → shortest route → handoff or stop | -Use one understanding check only when consequential. Persist only verified, reusable findings. Keep AI leverage visible where useful, but retain independent evidence and fallback in proportion to risk. - -## Ownership depth - -When relevant, identify: - -- what should be built, automated, or kept human; -- the business, scientific, human, or physical reality behind the code; -- failure, containment, degraded mode, recovery, and observability; -- legacy, external, physical, regulatory, security, or organizational constraints; -- validation and evidence quality; -- access, deployment, rollback, and shutdown authority; -- who accepts professional responsibility; -- what capability must remain without the current AI tool. - -Apply deeper scrutiny to laboratory, industrial, regulated, security, architecture and integration, validation, education and assessment, and human-machine workflow domains. Do not force these concerns onto unrelated low-risk work. - -## Context economy - -- Search narrowly before reading broad directories, documentation, or history. -- Read only the selected skill and relevant parts of shared records. -- Reuse verified findings before rescanning. -- Prefer stable symbols, tests, configuration, and representative paths. -- Stop when the evidence threshold is met. -- Stay at most one useful step ahead unless deeper research was requested. - -## Understanding checks +The common Agentic Delivery and Education instructions own the learning loop, context economy, ownership lenses, understanding checks, evidence language, and completion behavior. Do not duplicate those rules here. -Use at most one check by default. Skip it for fast delivery, mechanical work, or already-demonstrated understanding. Use more only for an explicit quiz or guided-learning request. +## Persistent surfaces -Rereading, agreement, confidence, and fluent output are not proof. - -
-Check techniques and handling - -Useful checks: explain the mechanism in the user's own words, predict an outcome before running it, trace a path through the system, name what must stay stable under a change, compare a valid analogue against an invalid one, spot the flaw in a plausible-but-wrong explanation, state what evidence would disprove the current model, or identify the failure or fallback behavior. - -Skip a check when the task is trivial, mechanical, time-critical, or the user has already demonstrated the relevant understanding earlier in the session. - -If the response is confident but wrong, correct it plainly and continue; do not turn it into a teaching detour unless the user asks. If the user declines a check, proceed with the work. - -
- -## Persistence and safety - -Conversation is the default. Close meaningful sessions through `agentic-flow/LOCAL.md`. - -Promote only verified, repository-specific, reusable, non-sensitive findings that are costly to rediscover. Keep raw attempts, personal state, uncertainty, secrets, customer data, sensitive operational evidence, and private conflict under `.local/`. - -Use one owner: - -- `MAP.md`: systems, boundaries, controls, representative flows, and high-value unknowns; -- `TAKEAWAYS.md`: concise reusable models, judgments, evidence, and failure boundaries; +- `MAP.md`: systems, boundaries, controls, representative flows, and high-value unknowns. +- `TAKEAWAYS.md`: concise reusable models, judgments, evidence, and failure boundaries. - `REPOSITORIES.md`: repository identity, baseline, and access boundary. +- `.local/`: private sessions, attempts, uncertainty, and follow-ups. -## Evidence - -Label material claims as verified from source, configuration, tests, runtime evidence, domain evidence, contributor report, or inference. Do not infer production usage or data shape from source alone. - -## Completion - -Use the normal `agentic-flow` handoff. When learning was central, include only useful points about the system model, judgment, decisive evidence, resilience, AI independence, ownership, or transfer. Do not add a second recap or store a transcript. +Promote only verified, repository-specific, reusable, non-sensitive findings that are costly enough to rediscover. diff --git a/sample/profiles/full/learning-flow/README.md b/sample/profiles/full/learning-flow/README.md index 8d70e02..86e9eb1 100644 --- a/sample/profiles/full/learning-flow/README.md +++ b/sample/profiles/full/learning-flow/README.md @@ -12,7 +12,7 @@ flowchart TB X --> K ``` -All skills apply `agentic-flow/EDUCATION.md` selectively. The goal is durable human ownership: system understanding, product judgment, credible validation, resilience, responsible AI leverage, and clear control boundaries. +All selected skills apply `agentic-flow/EDUCATION.md` selectively. The goal is durable human ownership: system understanding, product judgment, credible validation, resilience, responsible AI leverage, and clear control boundaries. ## Persistent surfaces @@ -28,7 +28,7 @@ All skills apply `agentic-flow/EDUCATION.md` selectively. The goal is durable hu ## Start -Use `learning-bootstrap` only for a requested baseline or deliberate onboarding pass. An ordinary task in a new repository can start with its matching task skill. +Use `learning-bootstrap` only for a requested baseline or deliberate onboarding pass. An ordinary task in a new repository can start with its matching repository-learning branch. Select one primary learning skill. `agentic-workflow` is only for configuring or understanding the harness itself. See the "Select one primary skill" table in `learning-flow/AGENTS.md` for the full need-to-skill routing. diff --git a/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md b/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md deleted file mode 100644 index 92c8cc6..0000000 --- a/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: repository-learning -description: Learn and work in an unfamiliar repository through a compact task-first flow that builds system ownership, verifies generated solutions, and keeps private continuity under .local. Use for orientation, bugs, analogous features, safe refactors, or explanations when deliberate understanding support is useful. ---- - -# Repository learning - -Read `agentic-flow/AGENTS.md`, `agentic-flow/SETTINGS.md`, `agentic-flow/EDUCATION.md`, and `learning-flow/AGENTS.md`. Load only relevant parts of `MAP.md` or `TAKEAWAYS.md`. - -Follow `agentic-flow/WORKFLOW.md` for planning, approvals, execution, validation, and handoff. This skill owns one learning route, not a second delivery workflow. - -## Ownership compass - -Select only the questions that matter: - -1. What real business, scientific, human, or physical outcome is involved? -2. What rule or invariant must remain true? -3. Should the requested behavior be built or automated? -4. What evidence can disprove the current model or generated solution? -5. How can it fail, and what containment, fallback, or recovery matters? -6. Which legacy, physical, regulatory, security, or organizational boundary controls the design? -7. Who can approve, access, deploy, stop, roll back, or accept responsibility? -8. What knowledge must remain usable without the current AI tool? - -## Bug - -1. State the affected outcome or rule, symptom, and falsifiable expectation. -2. Find the smallest discriminating test, trace, log, or safe reproduction. -3. Rank credible hypotheses and test one uncertainty at a time. -4. Explain the mechanism and relevant failure boundary before patching. -5. Apply the narrowest responsible containment or fix when requested. -6. Prove regression behavior and name the untested boundary. - -## Feature - -1. Define the actor, intended outcome, capability, observable behavior, and invariants. -2. Test whether the feature should exist and what must remain a human decision. -3. Find the nearest valid analogue by behavior and evidence, not name alone. -4. Separate shared invariants from intentional differences. -5. Use the smallest established seam. -6. Prove behavior, failure handling, access, and operational control in proportion to risk. - -## Refactor - -1. State the behavior or domain invariant that must remain stable. -2. Identify the observable contract, failure boundary, and fallback that cannot be lost. -3. Find existing proof or add only necessary characterization evidence. -4. Use the smallest safe seam and reviewable transformations. -5. Confirm the result is simpler to own, validate, and recover. - -## Orientation - -1. Identify intended use, actor or caller, outcome, and governing rule. -2. Show the compact system and domain boundary before file detail. -3. Trace one representative path from trigger to observable effect. -4. Connect claims to source, tests, configuration, runtime or domain evidence, or explicit inference. -5. Identify the human control point, important failure boundary, and highest-value unknown when relevant. -6. Stop when the user can locate, explain, challenge, and safely continue in the territory. - -## Learning constraints - -- Use safe trial and error when a small attempt can narrow the model. -- Invite at most one prediction, trace, or explain-back when consequential. -- Encourage questioning generated output, documentation, tests, and authority with evidence. -- Prefer one small round (question → evidence → understanding → continue-or-stop) over planning the entire investigation before starting. -- Fold only useful learning into the normal handoff. -- Close meaningful sessions through `agentic-flow/LOCAL.md`. -- Promote to `MAP.md` or `TAKEAWAYS.md` only when the persistence threshold is met. diff --git a/sample/profiles/minimal/learning-flow/.managed-skills b/sample/profiles/minimal/learning-flow/.managed-skills index 48d5bf5..e69de29 100644 --- a/sample/profiles/minimal/learning-flow/.managed-skills +++ b/sample/profiles/minimal/learning-flow/.managed-skills @@ -1 +0,0 @@ -repository-learning diff --git a/sample/profiles/minimal/learning-flow/AGENTS.md b/sample/profiles/minimal/learning-flow/AGENTS.md index 3da9548..c3c0fb2 100644 --- a/sample/profiles/minimal/learning-flow/AGENTS.md +++ b/sample/profiles/minimal/learning-flow/AGENTS.md @@ -1,48 +1,21 @@ # Minimal repository learning instructions -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 layer adds repository learning and durable knowledge on top of Agentic Delivery. It does not replace delivery or create a universal execution gate. ## When to use -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. +Use `repository-learning` when the user is trying to understand the current repository, subsystem, bug, feature, or refactor. Do not load it for purely mechanical edits. -Read `agentic-flow/EDUCATION.md` through the selected learning skill and only the relevant shared records. +Select one `repository-learning` branch: Orientation, Bug, Feature, or Refactor. Read `agentic-flow/EDUCATION.md` only through the selected skill and load only relevant shared records. -## Core flow +`agentic-workflow` is for the harness itself, not a second engineering procedure. `structured-change` may run alongside `repository-learning` for a consequential or ambiguous change. -```text -Locate → Reason → Work → Verify → Explain → Transfer -``` +## Persistent surfaces -Each pass through Locate–Reason can be one small round: one question, the evidence for it, the resulting understanding, then continue or stop. Stop as soon as the current understanding is sufficient for the task — do not plan the full investigation up front. +- `MAP.md`: compact system boundaries, domain slices, controls, representative paths, and high-value unknowns. +- `TAKEAWAYS.md`: verified reusable lessons that are costly to rediscover. +- `.local/`: private attempts, progress, uncertainty, checks, and session continuity. -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. - -## Branches - -- **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. `structured-change` may run alongside one branch for a consequential or ambiguous change. - -## Economy - -- 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 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. Use `.local/` for meaningful private continuity. +The common Agentic Delivery and Education instructions own collaboration, context economy, verification, understanding checks, evidence language, and handoff. Do not duplicate those rules here. Promote only verified, repository-specific, reusable, non-sensitive knowledge that is costly enough to rediscover. diff --git a/scripts/ci-install-test.sh b/scripts/ci-install-test.sh index 4af0a7c..e07d8b5 100755 --- a/scripts/ci-install-test.sh +++ b/scripts/ci-install-test.sh @@ -11,4 +11,9 @@ mkdir -p "$target/.local" printf '%s\n' "CI sentinel" > "$target/.local/ci-sentinel" bash "$repo_root/scripts/install.sh" --target "$target" --repository "$repository" --ref "$ref" --profile minimal --mode update --skip-root-agents grep -Fxq "CI sentinel" "$target/.local/ci-sentinel" -echo "Installer smoke test passed." + +full_target="$(mktemp -d)" +trap 'rm -rf "$target" "$full_target"' EXIT +bash "$repo_root/scripts/install.sh" --target "$full_target" --repository "$repository" --ref "$ref" --profile full --mode fail --skip-root-agents +test -f "$full_target/.agents/skills/repository-learning/SKILL.md" +echo "Installer smoke test passed for minimal and full profiles." diff --git a/scripts/install.ps1 b/scripts/install.ps1 index 8775689..6bebf79 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -691,7 +691,10 @@ try { } if (-not $SkipSkills) { if (-not (Test-Path -LiteralPath $sourceCommonSkills -PathType Container)) { throw "Common skill directory is missing." } - if (-not (Test-Path -LiteralPath $sourceProfileSkills -PathType Container)) { throw "Profile skill directory is missing." } + $profileManagedSkills = @(Get-Content -LiteralPath $sourceLearningManagedSkills | Where-Object { -not [string]::IsNullOrWhiteSpace($_) -and -not $_.Trim().StartsWith("#") }) + if ($profileManagedSkills.Count -gt 0 -and -not (Test-Path -LiteralPath $sourceProfileSkills -PathType Container)) { + throw "Profile skill directory is missing." + } } if ($selectedExtension -eq "regulatory") { if (-not (Test-Path -LiteralPath $sourceExtensionLearning -PathType Container)) { diff --git a/scripts/install.sh b/scripts/install.sh index d2007cd..f439d48 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -810,7 +810,9 @@ for required in "$SOURCE_AGENTIC_MANAGED_FILES" "$SOURCE_AGENTIC_MANAGED_SKILLS" done if [ "$SKIP_SKILLS" != "true" ]; then [ -d "$SOURCE_COMMON_SKILLS" ] || { echo "Common skill directory is missing." >&2; exit 1; } - [ -d "$SOURCE_PROFILE_SKILLS" ] || { echo "Profile skill directory is missing." >&2; exit 1; } + if has_content "$SOURCE_LEARNING_MANAGED_SKILLS"; then + [ -d "$SOURCE_PROFILE_SKILLS" ] || { echo "Profile skill directory is missing." >&2; exit 1; } + fi fi if [ "$SELECTED_EXTENSION" = "regulatory" ]; then [ -d "$SOURCE_EXTENSION_LEARNING" ] || { echo "Required extension directory is missing: $SOURCE_EXTENSION_LEARNING" >&2; exit 1; } diff --git a/skill-evals/full-cases.yaml b/skill-evals/full-cases.yaml index 4788878..f782c66 100644 --- a/skill-evals/full-cases.yaml +++ b/skill-evals/full-cases.yaml @@ -52,3 +52,8 @@ cases: expected_primary_skill: selected_task_learning_skill must_include: [one question, evidence, resulting understanding, continue-or-stop, stop when sufficient] must_not: [plan the entire investigation up front, keep investigating after resolution] + + - prompt: "Use the repository-learning route for a bug, feature, orientation, or refactor." + expected_skill: repository-learning + must_include: [select exactly one branch, orientation bug feature refactor, common skill owner] + must_not: [load repository-orientation, challenge-debugging, analogous-feature, safe-refactor as separate skills] diff --git a/skill-evals/minimal-cases.yaml b/skill-evals/minimal-cases.yaml index b5362db..663fa01 100644 --- a/skill-evals/minimal-cases.yaml +++ b/skill-evals/minimal-cases.yaml @@ -54,3 +54,8 @@ cases: expected_branch: orientation must_include: [one small round, question, evidence, understanding, continue-or-stop, stop when sufficient] must_not: [plan the entire investigation up front, continue investigating after the task is resolved] + + - prompt: "Understand and fix a repository bug using the minimal profile." + expected_skill: repository-learning + must_include: [bug branch, common skill owner, decisive evidence, focused proof] + must_not: [profile-local repository-learning copy]