diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d7bbdd..e0cb812 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,22 @@ ### Added +### Changed + +## 1.1.0 + +Finalized the post-1.0 learning and reasoning improvements for the 1.1.0 release. + +### Added + +- `agentic-flow/ARTIFACTS.md`, defining optional reasoning artifacts such as questions, research, models, designs, structures, plans, verification, and learning without making them workflow stages. +- Focused learning rounds and repository-learning guidance that build understanding incrementally and stop when the evidence threshold is met. +- Human-correction propagation guidance in `agentic-flow/LOCAL.md`, so corrected models and designs are updated rather than silently discarded. +- Optional `Structure` guidance inside `structured-change` for designs with real architectural impact. +- `learning-closure` guidance that prefers changed understanding and recommends the smallest persistence surface. +- `learning-freshness` guidance for checking durable knowledge against current implementation evidence. +- Shared research guidance for competing designs so common evidence is established once before branching into tradeoffs. +- Worked two-round discovery material and corresponding evaluation coverage. - Two behavioral routing rules in `agentic-flow/AGENTS.md`: treat a user's proposed implementation or architecture as a hypothesis to check against repository evidence rather than a specification to endorse, and distinguish repository-resolvable ambiguity (inspect first) from user-intent ambiguity (ask the smallest useful question). - A compact visual decision model for that routing in `agentic-flow/README.md`. - Two regression scenarios (proposed design, open-ended ambiguity) in `docs/AGENTIC_WORKFLOW_SANITY.md`, and matching cases in `skill-evals/agentic-cases.yaml`. @@ -12,8 +28,18 @@ ### Changed +- Tightened the distinction between learning-aware behavior and turning every task into a lesson. +- Clarified proposal and ambiguity routing so repository evidence is inspected before asking user-intent questions where possible. +- Added progressive disclosure around lower-frequency rules, provenance details, and architectural boundaries. +- Added compact flowcharts to make artifact selection, structured change, routing, layer relationships, and learning closure easier to scan. +- Reduced repeated framework language and softened rules where context-sensitive wording is more accurate than universal mandates. - README wording from "learning is the default behavior" to "learning-aware behavior is enabled by default," with routine work stated explicitly as staying routine. +### Fixed + +- Corrected the remaining `AGENTS.md` wording that still described learning as unqualified default behavior. +- Removed a duplicated `LEARN.md` entry from the agentic-flow guide. + ## 1.0.0 First tagged production release. `v0.1.0`/`v0.1.1` on GitHub were release-automation smoke tests and are not part of this line; this release picks up the version sequence documented below, starting at `0.8.0`. diff --git a/MANIFEST.txt b/MANIFEST.txt index 59fb4cd..3f3549b 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,9 +1,9 @@ .gitattributes 40 .gitignore 324 AGENTS.md 2995 -CHANGELOG.md 18727 +CHANGELOG.md 20650 docs/AGENTIC_WORKFLOW_SANITY.md 9207 -docs/ARCHITECTURE.md 6009 +docs/ARCHITECTURE.md 5689 docs/DESIGN_NOTES.md 31120 docs/EDUCATION_MODEL.md 5452 docs/INITIALIZE_LEARNING_FLOW.md 10880 @@ -16,7 +16,7 @@ docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md 9505 docs/references/REFERENCE_REVIEW_LITT.md 2069 docs/references/REFERENCE_REVIEW_POCOK.md 2155 LICENSE 2213 -README.md 9012 +README.md 8888 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 1756 @@ -27,21 +27,21 @@ 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 2599 +sample/common/.agents/skills/structured-change/SKILL.md 2770 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 175 sample/common/agentic-flow/.managed-files 183 sample/common/agentic-flow/.managed-skills 86 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 5447 -sample/common/agentic-flow/ARTIFACTS.md 2333 +sample/common/agentic-flow/AGENTS.md 5443 +sample/common/agentic-flow/ARTIFACTS.md 2605 sample/common/agentic-flow/CONFIGURE.md 4475 sample/common/agentic-flow/DECISIONS.md 963 sample/common/agentic-flow/EDUCATION.md 5232 sample/common/agentic-flow/LEARN.md 1822 sample/common/agentic-flow/LOCAL.md 4179 -sample/common/agentic-flow/README.md 2979 +sample/common/agentic-flow/README.md 3074 sample/common/agentic-flow/REFERENCE_INTEGRATION.md 2183 sample/common/agentic-flow/ROOT_INTEGRATION.md 3086 sample/common/agentic-flow/SETTINGS.md 544 @@ -110,7 +110,7 @@ skill-evals/README.md 1667 skill-evals/structured-change-cases.yaml 4710 adoption/ADOPT.md 3941 adoption/README.md 2057 -sample/common/.agents/skills/learning-closure/SKILL.md 3911 -sample/common/.agents/skills/learning-freshness/SKILL.md 1866 +sample/common/.agents/skills/learning-closure/SKILL.md 3605 +sample/common/.agents/skills/learning-freshness/SKILL.md 1904 skill-evals/learning-lifecycle-cases.yaml 1599 skill-evals/adoption-cases.yaml 1337 diff --git a/README.md b/README.md index caf185c..0bdbde8 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Codebase Learning Flow configures a host coding agent. It provides repository-local instructions, focused skills, learning surfaces, and private local continuity. It does **not** provide an agent runtime, sandbox, retry engine, or background worker. > [!IMPORTANT] -> **Learning-aware behavior is enabled by default after installation** — that does not mean every task becomes a lesson. Routine work stays routine. 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. A proposed design or approach is treated as a hypothesis worth checking against repository evidence, not a specification to endorse. +> **Learning-aware behavior is enabled by default after installation**. That does not mean every task becomes a lesson. Routine work stays routine. Requests such as `help me understand ` select the appropriate learning route; implementation work remains normal delivery with learning reinforcement only when useful. Proposed designs are hypotheses to check against repository evidence, not specifications to endorse. > [!WARNING] > The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory or quality expertise. @@ -46,8 +46,8 @@ The installed `AGENTS.md` connects the host repository to `agentic-flow`. The co - `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 -- a proposed design or approach → treated as a hypothesis, checked against repository evidence before being endorsed or implemented -- an open-ended consequential question → repository evidence is inspected first; the user is asked only the smallest question evidence can't answer +- a proposed design or approach → treated as a hypothesis, checked against repository evidence before endorsement or implementation +- an open-ended consequential question → repository evidence is inspected first; the user is asked only the smallest question evidence cannot answer - one consequential or ambiguous change → `structured-change` alongside the active route - regulatory reasoning → the optional regulatory lens when installed @@ -59,19 +59,17 @@ The agent should not turn every task into a lesson. Short questions can receive ### Preferred: packaged release -For team or enterprise use, install a reviewed, versioned release. Substitute -the current tag from the badge above or the -[Releases page](https://github.com/legrab/codebase-learning-flow/releases) — -`--release`/`-Release` intentionally has no "latest" shortcut, so the exact -tag must be given. +For team or enterprise use, install a reviewed, versioned release. Substitute the current tag from the badge above or the [Releases page](https://github.com/legrab/codebase-learning-flow/releases). + +`--release`/`-Release` intentionally has no `latest` shortcut, so the exact tag must be given. ```sh curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh -o install.sh -sh install.sh --release v1.0.0 --profile minimal +sh install.sh --release v1.1.0 --profile minimal ``` ```powershell -& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.0.0 -Profile Minimal +& ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) -Release v1.1.0 -Profile Minimal ``` The installer verifies the release checksum before extraction and reports the resolved `Version:` and `Source:`. @@ -147,7 +145,7 @@ The model is selective:
Ownership lens -When relevant, consider: +When relevant: | Question | Why | |---|---| diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 880d414..2856b64 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,7 +1,6 @@ # Framework architecture -Codebase Learning Flow is organized as three layers with different ownership and -adoption boundaries. +Codebase Learning Flow is organized as three layers with different ownership and adoption boundaries. ```text Codebase Learning Flow @@ -18,17 +17,11 @@ Codebase Learning Flow ## 1. Agentic Delivery -The agentic delivery layer is the common collaboration layer. It defines the -default engineering loop, instruction precedence, planning and verification -behavior, communication, handoff, and boundaries around consequential actions. +The agentic delivery layer is the common collaboration layer. It defines the default engineering loop, instruction precedence, planning and verification behavior, communication, handoff, and boundaries around consequential actions. Its main installed surface is `agentic-flow/`. -This layer should remain small because it is the most invasive layer: its -instructions influence ordinary coding-agent behavior. - -It must not absorb repository-specific architecture rules or task-specific -procedures that belong elsewhere. +This layer should remain small because it is the most invasive layer: its instructions influence ordinary coding-agent behavior. Repository-specific architecture rules and task-specific procedures belong elsewhere. The default engineering loop is: @@ -36,14 +29,11 @@ The default engineering loop is: Frame → Inspect → Decide → Act → Verify → Handoff ``` -The loop is task-scaled. A trivial edit should not acquire a formal learning or -change-management ceremony merely because the framework supports those things. +The loop is task-scaled. A trivial edit should not acquire a formal learning or change-management ceremony merely because the framework supports those things. ## 2. Learning & Ownership -The learning and ownership layer helps a developer understand the system while -doing real engineering work and retain useful knowledge without turning every -task into documentation. +The learning and ownership layer helps a developer understand the system while doing real engineering work and retain useful knowledge without turning every task into documentation. Its surfaces include: @@ -56,20 +46,15 @@ Its surfaces include: This layer is independently adoptable into an existing agentic workflow. -Conversation remains the default learning surface. Private continuity is used -only when meaningful persistence is justified. Shared knowledge is promoted -deliberately and should be stable, verified, reusable, and non-sensitive. +Conversation remains the default learning surface. Private continuity is used only when meaningful persistence is justified. Shared knowledge is promoted deliberately and should be stable, verified, reusable, and non-sensitive. -The learning layer must not become a second engineering workflow or silently -introduce universal execution gates. +The learning layer should not become a second engineering workflow or silently introduce universal execution gates. ## 3. Optional Risk Lenses -Risk lenses add domain-specific reasoning to the active workflow without -replacing it. +Risk lenses add domain-specific reasoning to the active workflow without replacing it. -The current example is the `regulatory` extension and its -`regulatory-knowledge` skill. +The current example is the `regulatory` extension and its `regulatory-knowledge` skill. A risk lens may strengthen questions around: @@ -82,84 +67,68 @@ A risk lens may strengthen questions around: - security; - professional responsibility. -Risk lenses are selective. They must not be activated merely because a -repository happens to contain a regulated or safety-relevant component. +Risk lenses are selective. They should be activated when the work actually benefits from the lens, not merely because a repository contains a regulated or safety-relevant component. -For a consequential change, a risk lens can work with `structured-change`. -It does not create a parallel workflow. +For a consequential change, a risk lens can work with `structured-change`. It does not create a parallel workflow. > [!WARNING] -> The regulatory extension is a reasoning and workflow aid, not a compliance -> determination or substitute for qualified regulatory/quality expertise. +> The regulatory extension is a reasoning and workflow aid, not a compliance determination or substitute for qualified regulatory/quality expertise. ## Layer relationships -The layers compose downward without requiring all three to be installed: - -```text -Agentic Delivery - │ - ├── may use ──► Learning & Ownership - │ - └── may use ──► Optional Risk Lenses - │ - └── may elaborate the active workflow +```mermaid +flowchart TB + D[Agentic Delivery] --> L[Learning & Ownership] + D --> R[Optional Risk Lenses] + L --> K[Private or durable knowledge] + R --> C[Risk-aware reasoning] ``` A repository may therefore choose: - **Agentic Delivery only** for a minimal coding-agent setup; -- **Agentic Delivery + Learning & Ownership** for the normal learning-oriented - setup; -- **Agentic Delivery + Risk Lenses** when a specific domain requires stronger - reasoning; +- **Agentic Delivery + Learning & Ownership** for the normal learning-oriented setup; +- **Agentic Delivery + Risk Lenses** when a specific domain requires stronger reasoning; - **all three** when both learning and risk-aware engineering are useful. -Existing custom agentic workflows may also adopt Layer 2 or Layer 3 without -adopting the framework's common Layer 1. This distinction is important for -guided adoption. +Existing custom agentic workflows may also adopt Layer 2 or Layer 3 without adopting the framework's common Layer 1. This distinction matters for guided adoption. -## Ownership boundaries +
+Ownership boundaries -| Layer | Owns | Must not become | +| Layer | Owns | Avoid turning it into | |---|---|---| | Agentic Delivery | common collaboration policy, task routing, verification, handoff | repository-specific architecture documentation or every task's learning procedure | | Learning & Ownership | learning routes, durable understanding, private continuity, knowledge promotion | a mandatory lesson plan or universal execution gate | | Optional Risk Lenses | domain-specific risk and evidence guidance | a claim of compliance, certification, or mandatory procedure for unrelated work | -The repository itself is the reference implementation of these boundaries. -Changes should preserve the distinction rather than introduce a fourth -cross-cutting framework layer for every new concern. +The repository itself is the reference implementation of these boundaries. Changes should preserve the distinction rather than introduce a new cross-cutting framework layer for every concern. +
-## Adoption versus installation +
+Adoption versus installation -The repository deliberately separates complete installation from guided adoption. +- **Complete installation** consumes the framework payload under `sample/` and establishes the selected layers. +- **Guided adoption** consumes `adoption/` and adapts selected concepts into an existing agentic setup. It must not silently replace the host delivery workflow or root `AGENTS.md`. -- **Complete installation** consumes the framework payload under `sample/` and - establishes the selected Agentic Delivery, Learning & Ownership, and optional - Risk Lens layers. -- **Guided adoption** consumes `adoption/` and adapts selected concepts into an - existing agentic setup. It is not an installer profile and must not silently - replace the host delivery workflow or root `AGENTS.md`. +This separation is a trust and context boundary as well as an installation boundary. -This separation is a trust and context boundary as well as an installation -boundary. The adoption process can inspect the framework without loading its -entire instruction set into the active agent context. +
## Learning lifecycle Learning is treated as a lifecycle rather than a second engineering process: -```text -work → observe useful insight → recommend destination → user decides - → private continuity or durable shared knowledge → later freshness check +```mermaid +flowchart LR + W[Work] --> O[Observe useful insight] + O --> R[Recommend smallest destination] + R --> U[User decides] + U --> P[Private or durable knowledge] + P --> F[Later freshness check] ``` -`learning-closure` owns the placement decision at meaningful workflow closure. -`learning-freshness` periodically checks internal documentation and learning -claims against implementation evidence. External-source claims remain externally -sourced and carry provenance for later revalidation. +`learning-closure` owns the placement decision at meaningful workflow closure. `learning-freshness` periodically checks internal documentation and learning claims against implementation evidence. External-source claims remain externally sourced and carry provenance for later revalidation. -The default is not to persist anything. Durable knowledge must earn its -maintenance cost. +The default is not to persist anything. Durable knowledge must earn its maintenance cost. diff --git a/docs/EXAMPLE_WALKTHROUGH.md b/docs/EXAMPLE_WALKTHROUGH.md index 388b59f..b65a498 100644 --- a/docs/EXAMPLE_WALKTHROUGH.md +++ b/docs/EXAMPLE_WALKTHROUGH.md @@ -1,15 +1,10 @@ # Worked example: discovery and design challenge -This is a single compact, fictional example showing what the behavior in -`AGENTIC_WORKFLOW_SANITY.md` scenario 10 looks like end to end. It is not -installed into a target repository; it exists here to make the abstract -routing rules concrete. +This is a single compact, fictional example showing what the behavior in `AGENTIC_WORKFLOW_SANITY.md` scenario 10 looks like end to end. It is not installed into a target repository; it exists here to make the abstract routing rules concrete. ## Setting -A legacy .NET order-approval subsystem. A developer asks the agent to add -retry handling around an external ERP call and says: *"I'll just wrap the -existing client call with retries and move on. Anything to add?"* +A legacy .NET order-approval subsystem. A developer asks the agent to add retry handling around an external ERP call and says: *"I'll just wrap the existing client call with retries and move on. Anything to add?"* ## What repository learning establishes @@ -28,19 +23,26 @@ flowchart LR - **Unknown:** whether the ERP client is idempotent, i.e. whether a retried submission can duplicate an order. - **Control boundary:** production deployment and approval stay human-controlled. -## How the model was built (two rounds, not one investigation) +
+How the understanding was built -Round 1 — question: where does an approval request enter the system? -Evidence: the approval endpoint and `OrderService`. Understanding after round 1: operator → endpoint → OrderService → (unknown past this point). +Round 1: where does an approval request enter the system? -Round 2 — question: what happens after `OrderService`? Evidence: -`ApprovalRules`, the approval stored procedure, the ERP client. -Understanding after round 2 is the full flow shown above — sufficient to evaluate the retry proposal, so investigation stops here. +Evidence: the approval endpoint and `OrderService`. + +Understanding: operator → endpoint → `OrderService` → unknown past this point. + +Round 2: what happens after `OrderService`? + +Evidence: `ApprovalRules`, the approval stored procedure, the ERP client. + +Understanding: the full flow shown above. Investigation stops because it is sufficient to evaluate the retry proposal. + +
## Why this is not just implemented as proposed -The proposal ("wrap the call with retries") is treated as a hypothesis, not -a specification: +The proposal ("wrap the call with retries") is treated as a hypothesis, not a specification: ```text Proposal: @@ -81,10 +83,7 @@ I can inspect the ERP contract now, or if you already know it's idempotent, say so and I'll proceed with the narrow retry. ``` -Note what did *not* happen: no learning session was created, no mandatory -design document, no interrogation of unrelated parts of the system. One -material assumption was identified, checked against evidence where possible, -and only the remaining consequential gap was raised. +Note what did *not* happen: no learning session was created, no mandatory design document, no interrogation of unrelated parts of the system. One material assumption was identified, checked against evidence where possible, and only the remaining consequential gap was raised. ## Related diff --git a/sample/common/.agents/skills/learning-closure/SKILL.md b/sample/common/.agents/skills/learning-closure/SKILL.md index c245fdc..94535f0 100644 --- a/sample/common/.agents/skills/learning-closure/SKILL.md +++ b/sample/common/.agents/skills/learning-closure/SKILL.md @@ -5,7 +5,7 @@ description: Decide whether useful learning from a meaningful engineering or lea # Learning closure -Use this skill only when the current work produced a reusable insight worth considering for future work. It is a closure aid, not a mandatory documentation phase. +Use this skill when the current work produced a reusable insight worth considering for future work. It is a closure aid, not a mandatory documentation phase. ## Decide whether anything should persist @@ -21,26 +21,24 @@ Do not persist it if it is: If nothing qualifies, say so and continue the normal handoff. -## Recommend the smallest useful destination - -Choose among: +## Prefer changed understanding -| Destination | Use when | -|---|---| -| No persistent record | The insight is local, temporary, or cheap to rediscover | -| `.local/learning-history.md` | The insight is useful to the current developer/session but is not shared repository knowledge | -| `learning-flow/MAP.md` | It describes stable repository structure, boundaries, controls, or representative flows | -| `learning-flow/TAKEAWAYS.md` | It is a concise, verified reusable engineering or domain lesson | -| Module README/documentation | The knowledge belongs specifically with a module and should be discovered there | -| Skill/workflow documentation | The knowledge changes how this framework or a reusable repository workflow should operate | +Before stating the candidate insight, check whether the most valuable learning is a correction to how investigation or reasoning should happen next time. Prefer that changed reasoning pattern over a merely new fact when it is more reusable. -Prefer the module's own documentation when the knowledge is necessary to use or extend that module correctly. Prefer learning-flow surfaces for cross-cutting repository understanding. +If this session corrected an existing `learning-flow/MAP.md` or `TAKEAWAYS.md` entry, flag that entry for update in the same closure pass. Do not knowingly leave stale knowledge behind. -## Prefer changed understanding over new facts +## Recommend the smallest useful destination -Before stating the candidate insight, check whether the most valuable thing learned is not a new fact but a correction to how investigation should happen next time — for example "trace the queue consumer before reasoning about downstream behavior" is more durable than "ERP submission is asynchronous." Prefer capturing the corrected reasoning pattern when one exists. +| Destination | Use when | +|---|---| +| No persistent record | local, temporary, or cheap to rediscover | +| `.local/learning-history.md` | useful to the current developer/session but not shared repository knowledge | +| `learning-flow/MAP.md` | stable repository structure, boundaries, controls, or representative flows | +| `learning-flow/TAKEAWAYS.md` | concise, verified reusable engineering or domain lesson | +| Module README/documentation | knowledge belongs specifically with a module | +| Skill/workflow documentation | knowledge changes a reusable framework or repository workflow | -If this session corrected an existing `learning-flow/MAP.md` or `TAKEAWAYS.md` entry, flag that entry as needing an update in the same closure pass — do not leave a known-stale record for `learning-freshness` to catch later. +Prefer the module's own documentation when it is necessary to use or extend that module correctly. Prefer learning-flow surfaces for cross-cutting repository understanding. ## Ask at meaningful closure @@ -57,7 +55,7 @@ Recommended destination: , because . Persist it there, keep it private, or discard it? ``` -Offer at most the few destinations that are genuinely plausible. Do not present a generic questionnaire. +Offer only destinations that are genuinely plausible. Do not present a generic questionnaire. If the user chooses a destination, write the smallest useful record and include its evidence/source. @@ -73,7 +71,8 @@ A persistent entry should normally contain: Do not store conversation transcripts, long debugging diaries, confidence scores, or generated filler. -## External sources +
+External-source provenance For learning based on external material, preserve enough provenance to re-check the claim: @@ -85,8 +84,10 @@ Accessed: Relevant section:
``` -External-source metadata does not make the claim current or verified. It only makes future verification possible. +External-source metadata makes future verification possible. It does not make the claim current or internally verified. + +
## Scope -This skill complements the active engineering or learning workflow. It never replaces the primary task procedure, and it should not turn a trivial task into a documentation exercise. +This skill complements the active engineering or learning workflow. It never replaces the primary task procedure or turns a trivial task into a documentation exercise. diff --git a/sample/common/.agents/skills/learning-freshness/SKILL.md b/sample/common/.agents/skills/learning-freshness/SKILL.md index 92c2c49..a10bfb7 100644 --- a/sample/common/.agents/skills/learning-freshness/SKILL.md +++ b/sample/common/.agents/skills/learning-freshness/SKILL.md @@ -31,7 +31,8 @@ Look for concrete divergence first: Reuse existing repository evidence before broad rescanning. -## External evidence +
+External evidence If a claim depends on material outside the repository, do not mark it verified from repository inspection alone. @@ -39,6 +40,8 @@ Use retained provenance such as URL, revision/version, publication date, access If external access is unavailable, report the claim as externally sourced and not revalidated. +
+ ## Output Report only actionable findings: diff --git a/sample/common/.agents/skills/structured-change/SKILL.md b/sample/common/.agents/skills/structured-change/SKILL.md index 6721454..51b9f92 100644 --- a/sample/common/.agents/skills/structured-change/SKILL.md +++ b/sample/common/.agents/skills/structured-change/SKILL.md @@ -16,11 +16,23 @@ Read `agentic-flow/AGENTS.md` and the relevant `WORKFLOW.md` sections. Read `SET Skip it for routine, small, reversible, or unambiguous work. +```mermaid +flowchart LR + E[Explore] --> D[Design] + D --> S{Structure needed?} + S -->|Yes| ST[Structure] + S -->|No| A[Approve] + ST --> A + A --> I[Implement] + I --> V[Review / verify] + V --> C[Capture useful result] +``` + ## Explore State current behavior, purpose, constraints, unknowns, and affected risks. Separate facts from assumptions. Stop here. -When genuinely competing approaches exist, keep exploration findings shared across all of them — do not re-run the same investigation once per option. Branch only in Design, where tradeoffs actually differ. +When genuinely competing approaches exist, keep exploration findings shared across all of them. Branch only in Design, where tradeoffs actually differ. ## Design @@ -30,18 +42,18 @@ If regulatory guidance applies, read only the specific knowledge needed and note ## Structure (optional) -For a design with real architectural impact — several files or components that must change together — answer before detailed planning: +For a design with real architectural impact, answer before detailed planning: - What are the major implementation units? - How do they depend on each other? - What changes together, and what must stay separate? - What order makes verification possible at each step? -Skip this for a design that's already one clear unit of work; go straight to Implement. +Skip this for a design that's already one clear unit of work; go straight to Approve. ## Approve -State the decision plainly and wait before implementing. An explicit prior instruction that resolves it is approval. +State the decision plainly and wait before implementing when approval is actually unresolved. An explicit prior instruction that resolves the decision is approval. ## Implement and review @@ -57,4 +69,4 @@ Keep low-risk work conversational. Use written templates only when the change's ## Restraint -One structured decision per change. Never stack a second formal process on top. Prefer the simplest acceptable solution. +One structured decision per change. Do not 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 089eefa..abbbfd1 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -9,7 +9,7 @@ Learning & Ownership and Optional Risk Lenses add guidance without becoming a se 1. Follow root, nested, and tool-specific repository instructions first. 2. Use this layer for collaboration behavior. 3. Select one primary task route. -4. **Treat learning as default behavior:** general understanding requests use `learn-anything`; current-repository understanding uses repository learning. +4. 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. @@ -49,7 +49,7 @@ repository instructions → Agentic Delivery → one task route → narrow evide ## Discover the effective setup -Respect existing instructions, skills, prompts, plans, records, and agent-specific files. Inspect custom additions, overrides, conflicts, and precedence only when they affect the work. +Respect existing instructions, skills, prompts, plans, records, and agent-specific files. Inspect custom additions, overrides, conflicts, and precedence when they affect the work. 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. @@ -67,15 +67,24 @@ Ask only when a consequential choice is unresolved, evidence cannot distinguish 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. +
+Proposal and ambiguity rules + ### Proposals are hypotheses, not specifications -When the user presents a proposed implementation, architecture, or approach and asks for feedback, additions, or validation, treat it as a hypothesis rather than endorsing, polishing, or implementing it outright. Identify the assumptions it depends on, check the ones repository evidence can confirm or falsify, and surface a missing boundary, risk, or credible alternative before recommending it. Use `structured-change` when the decision is consequential or hard to reverse; otherwise fold the check into the active route. +When the user presents a proposed implementation, architecture, or approach and asks for feedback, additions, or validation, treat it as a hypothesis rather than endorsing, polishing, or implementing it outright. Identify the assumptions it depends on, check the ones repository evidence can confirm or falsify, and surface a missing boundary, risk, or credible alternative before recommending it. + +Use `structured-change` when the decision is consequential or hard to reverse; otherwise fold the check into the active route. An explicit, narrowly scoped instruction ("do exactly X") does not require this challenge; treat it as sufficient intent and proceed. ### Repository ambiguity vs. user-intent ambiguity -When a consequential question has more than one materially different answer, do not silently pick one. Inspect first if repository evidence can settle it. Ask only the smallest useful question when what's missing is the user's intent, scope, tradeoff, or authority — not because the repository is unfamiliar. This is a routing rule, not a fixed sequence: new evidence can change the route mid-task, including abandoning an initial proposal. +When a consequential question has more than one materially different answer, do not silently pick one. Inspect first if repository evidence can settle it. Ask only the smallest useful question when what is missing is the user's intent, scope, tradeoff, or authority, not because the repository is unfamiliar. + +This is a routing rule, not a fixed sequence: new evidence can change the route mid-task, including abandoning an initial proposal. + +
## Planning and records @@ -105,6 +114,6 @@ Omit empty sections, repeated narration, and exhaustive file lists. ## Learning closure -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-closure` when work produced a reusable insight. It is a closure aid, not a mandatory documentation step. Use `learning-freshness` during deliberate maintenance or when durable repository knowledge may have drifted. diff --git a/sample/common/agentic-flow/ARTIFACTS.md b/sample/common/agentic-flow/ARTIFACTS.md index 87df2b7..a6faa43 100644 --- a/sample/common/agentic-flow/ARTIFACTS.md +++ b/sample/common/agentic-flow/ARTIFACTS.md @@ -1,37 +1,39 @@ # Learning and reasoning artifacts -Optional vocabulary for making reasoning explicit. These are not mandatory -workflow stages — a trivial task produces none of them, a consequential -task might produce two or three. +Optional vocabulary for making reasoning explicit. These are not workflow stages. A trivial task produces none; a consequential task might produce two or three. ## Types - **question** — a specific thing that needs an answer before proceeding. - **research** — what is true today, established from evidence. -- **model** — current understanding of a system: components, relationships, - ownership, invariants, evidence, unknowns. See "Model" below. +- **model** — current understanding of a system: components, relationships, ownership, invariants, evidence, unknowns. - **design** — what should change, and why. -- **structure** — the major implementation units for a design and how they - depend on each other. See "Structure" below. +- **structure** — the major implementation units for a design and how they depend on each other. - **plan** — file-level or step-level execution order. - **verification** — what was checked and how. -- **learning** — a durable insight worth persisting (see - `learning-closure`). +- **learning** — a durable insight worth persisting. ## Artifact rule -Create an artifact when making the reasoning explicit materially improves -correctness, communication, or future reuse. Do not create one merely -because the framework has a place to put it. A trivial fix produces zero -artifacts. An unfamiliar, consequential change might produce a `model` and -a `design`; it doesn't need all eight types. +Create an artifact when making reasoning explicit materially improves correctness, communication, or future reuse. Do not create one merely because the framework has a place to put it. + +```mermaid +flowchart LR + T[Task] --> Q{Does explicit reasoning help?} + Q -->|No| N[No artifact] + Q -->|Yes| S[Choose smallest useful artifact] + S --> U[Use it while live] + U --> P{Worth retaining?} + P -->|No| D[Discard] + P -->|Yes| L[Learning closure / durable owner] +``` + +A trivial fix produces zero artifacts. An unfamiliar, consequential change might produce a `model` and a `design`; it does not need all eight types. -## Model +
+Model -Use when accumulated understanding is worth exposing so the user can -correct it before more reasoning builds on top of it. Keep it inline in the -conversation unless the work is meaningful enough for -`agentic-flow/LOCAL.md` continuity. +Use when accumulated understanding is worth exposing so the user can correct it before more reasoning builds on top of it. Keep it inline in the conversation unless the work is meaningful enough for `agentic-flow/LOCAL.md` continuity. ```text Current model: @@ -44,19 +46,17 @@ Unknown: ``` -Do not let a model accumulate unbounded state. If it stops fitting in a -few lines, it has stopped being "current understanding" and started being -documentation — move stable parts to `learning-flow/MAP.md` through the -normal promotion threshold in `LOCAL.md`, and keep only what's still live. +Do not let a model accumulate unbounded state. If it stops fitting in a few lines, it has stopped being "current understanding" and started being documentation. Move stable parts to `learning-flow/MAP.md` through the normal promotion threshold in `LOCAL.md`, and keep only what is still live. + +
+ +
+Structure -## Structure +Use only inside `structured-change`, between Design and Implement, for a design with real architectural impact. See `.agents/skills/structured-change/SKILL.md`. -Use only inside `structured-change`, between Design and Implement, for a -design with real architectural impact. See -`.agents/skills/structured-change/SKILL.md`. +
## Refining an artifact -If the user challenges a `model` or `design`, update it in place instead -of restarting the task. See "Human correction propagation" in -`agentic-flow/LOCAL.md`. +If the user challenges a `model` or `design`, update it in place instead of restarting the task. See "Human correction propagation" in `agentic-flow/LOCAL.md`. diff --git a/sample/common/agentic-flow/README.md b/sample/common/agentic-flow/README.md index 272aa70..01ba9fe 100644 --- a/sample/common/agentic-flow/README.md +++ b/sample/common/agentic-flow/README.md @@ -31,24 +31,24 @@ Start with `AGENTS.md`. Use balanced defaults from `SETTINGS.md` unless configur ## Proposal and ambiguity routing -A proposed design and an open-ended consequential question are handled the same way: check what evidence can settle, ask only what it can't. +A proposed design and an open-ended consequential question share the same first move: inspect what repository evidence can settle. They diverge when the remaining uncertainty is about user intent or about the proposed approach itself. ```mermaid flowchart TD - Q[Proposal or consequential question] --> E{Evidence can resolve it?} - E -->|Yes| I[Inspect, then proceed] - E -->|No| U{Depends on user intent, scope, or authority?} - U -->|Yes| A[Ask the smallest useful question] + Q[Proposal or consequential question] --> E{Can repository evidence settle it?} + E -->|Yes| I[Inspect] + E -->|No| U{Is user intent missing?} + U -->|Yes| A[Ask smallest useful question] U -->|No| I - I --> D{Is it a proposed design or approach?} - D -->|Yes| H[Treat as hypothesis: test assumptions, surface alternatives] - D -->|No| Act[Continue the active route] + I --> D{Proposed design?} + D -->|Yes| H[Test assumptions and alternatives] + D -->|No| Act[Continue active route] H --> R{Consequential or hard to reverse?} R -->|Yes| SC[structured-change] R -->|No| Act ``` -New evidence can change the route mid-task; this is a set of behavioral rules, not a plan to complete. See `AGENTS.md` for the full rule text. +New evidence can change the route mid-task. This is a set of behavioral rules, not a fixed sequence. See `AGENTS.md` for the full rule text. ## Supporting guides @@ -63,18 +63,15 @@ New evidence can change the route mid-task; this is a set of behavioral rules, n | `REFERENCE_INTEGRATION.md` | extracting value from another source | | `ARTIFACTS.md` | optional vocabulary for explicit reasoning outputs | | `LEARN.md` + learning skills | understanding the effective harness and building knowledge | +| `learn-anything` + learning skills | general learning and repository understanding |
Boundary in one sentence -`agentic-flow/` controls how work is performed. `learning-flow/` and learning skills control how understanding is built through that work. +`agentic-flow/` guides how work is performed. `learning-flow/` and learning skills guide how understanding is built through that work.
- ## Learning lifecycle -`learning-closure` decides whether a meaningful change produced reusable -knowledge and recommends the smallest appropriate persistence surface. -`learning-freshness` can later cross-check durable repository knowledge against -current implementation evidence. Neither is a second delivery workflow. +`learning-closure` decides whether a meaningful change produced reusable knowledge and recommends the smallest appropriate persistence surface. `learning-freshness` can later cross-check durable repository knowledge against current implementation evidence. Neither is a second delivery workflow.