diff --git a/CHANGELOG.md b/CHANGELOG.md index e0cb812..cd27a12 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,8 @@ Finalized the post-1.0 learning and reasoning improvements for the 1.1.0 release - Two regression scenarios (proposed design, open-ended ambiguity) in `docs/AGENTIC_WORKFLOW_SANITY.md`, and matching cases in `skill-evals/agentic-cases.yaml`. - `docs/EXAMPLE_WALKTHROUGH.md`, a single compact worked example showing the new routing in practice. - A "v1.0 hardening: proposal and ambiguity routing" entry in `docs/DESIGN_NOTES.md` recording the tightened, applied 1.0 behavioral contract in place — change rationale and current-state tracking live only in `DESIGN_NOTES.md` and this changelog, not in a separate status document. +- A canonical `agentic-flow/AGENTS.md` "Output shape" rule: prefer a compact Mermaid flowchart over prose for flows and relationships, and keep verbose agent-only elaboration inside `
` sections rather than the surrounding prose. +- A compact adoption-flow diagram in `adoption/ADOPT.md`. ### Changed @@ -34,11 +36,16 @@ Finalized the post-1.0 learning and reasoning improvements for the 1.1.0 release - 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. +- Added missing `
` collapsibles to the `structure`, `challenge-debugging`, `change-explainer`, and `ticket-learning-path` templates for consistency with `exploration.md`/`design.md`. +- Collapsed `docs/DESIGN_NOTES.md`'s v0.5–v0.8.0 history into one section so the current architecture and most recent rationale read first. ### 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. +- Removed a redundant "Current architecture boundaries" section in `docs/README.md` that restated the layer table already given earlier in the same file. +- Removed the skill-routing table duplicated between `sample/profiles/full/learning-flow/AGENTS.md` and `README.md`; the profile README now points to the canonical table. +- Matched the packaged-release install examples in `scripts/README.md` to the current `v1.1.0` tag referenced in the root README. ## 1.0.0 diff --git a/MANIFEST.txt b/MANIFEST.txt index 3f3549b..dc54496 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,13 +1,13 @@ .gitattributes 40 .gitignore 324 AGENTS.md 2995 -CHANGELOG.md 20650 +CHANGELOG.md 21735 docs/AGENTIC_WORKFLOW_SANITY.md 9207 docs/ARCHITECTURE.md 5689 -docs/DESIGN_NOTES.md 31120 +docs/DESIGN_NOTES.md 31204 docs/EDUCATION_MODEL.md 5452 docs/INITIALIZE_LEARNING_FLOW.md 10880 -docs/README.md 4320 +docs/README.md 4016 docs/references/REFERENCE_INTEGRATION.md 4551 docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md 2317 docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md 2540 @@ -30,18 +30,18 @@ sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md 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/.agents/skills/structured-change/templates/structure.md 243 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 5443 +sample/common/agentic-flow/AGENTS.md 5961 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 3074 +sample/common/agentic-flow/README.md 2969 sample/common/agentic-flow/REFERENCE_INTEGRATION.md 2183 sample/common/agentic-flow/ROOT_INTEGRATION.md 3086 sample/common/agentic-flow/SETTINGS.md 544 @@ -66,14 +66,14 @@ sample/extensions/regulatory/learning-flow/.extension-name 11 sample/extensions/regulatory/learning-flow/REGULATORY.md 1882 sample/profiles/full/.agents/skills/analogous-feature/SKILL.md 1408 sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md 1426 -sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md 428 +sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md 511 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/change-explainer/templates/change-explainer.md 353 sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md 1522 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 +sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md 405 sample/profiles/full/learning-flow/.managed-files 137 sample/profiles/full/learning-flow/.managed-skills 132 sample/profiles/full/learning-flow/.template-profile 5 @@ -82,7 +82,7 @@ sample/profiles/full/learning-flow/AGENTS.md 4716 sample/profiles/full/learning-flow/BOOTSTRAP.md 1788 sample/profiles/full/learning-flow/MAP.md 1464 sample/profiles/full/learning-flow/PLAYBOOKS.md 1327 -sample/profiles/full/learning-flow/README.md 2955 +sample/profiles/full/learning-flow/README.md 2574 sample/profiles/full/learning-flow/REPOSITORIES.md 439 sample/profiles/full/learning-flow/TAKEAWAYS.md 970 sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md 2010 @@ -108,7 +108,7 @@ skill-evals/full-cases.yaml 4640 skill-evals/minimal-cases.yaml 3655 skill-evals/README.md 1667 skill-evals/structured-change-cases.yaml 4710 -adoption/ADOPT.md 3941 +adoption/ADOPT.md 4177 adoption/README.md 2057 sample/common/.agents/skills/learning-closure/SKILL.md 3605 sample/common/.agents/skills/learning-freshness/SKILL.md 1904 diff --git a/adoption/ADOPT.md b/adoption/ADOPT.md index c55b10d..40852d4 100644 --- a/adoption/ADOPT.md +++ b/adoption/ADOPT.md @@ -3,6 +3,17 @@ Use this document only for **guided adoption into an existing custom agentic setup**. It is deliberately separate from the complete installation payload. +```mermaid +flowchart LR + I[Inspect] --> L[Explain the layers] + L --> Q[Ask concrete choices] + Q --> P[Build adoption plan] + P --> A[Approve] + A --> G[Integrate selectively] + G --> V[Verify] + V --> S[Summarize] +``` + ## 1. Inspect before proposing Inspect only enough of the target repository to understand: diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index 669bbc7..574a2be 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -18,6 +18,9 @@ The previous five ownership layers remain useful as implementation provenance, b This distinction is important for adoption. A repository with its own agentic delivery workflow can adopt Learning & Ownership or an Optional Risk Lens without installing or replacing the common Agentic Delivery layer. +
+Earlier version history (v0.5 – v0.8.0) + ## v0.5 separation of concerns Repository agentic content is divided into five ownership layers: @@ -138,6 +141,8 @@ Regulatory-specific knowledge (traceability, validation, risk management, audit Engineering judgment content the source proposed (anti-overengineering guidance, AI-collaboration indicators, modernization, maintainability, testing, architecture, dependency management, documentation) is general-purpose, not regulatory-specific, and lives inside `structured-change`'s own knowledge folder instead. +
+ ## v1.0 hardening: proposal and ambiguity routing A pre-1.0 sanity review found the remaining gap to be behavioral routing, not architecture. The framework already had strong repository discovery, progressive learning, evidence-based reasoning, structured change, and local/shared learning continuity; what it lacked was an explicit rule distinguishing a request to implement from a request to challenge a proposed approach, and an explicit rule distinguishing an ambiguity the repository can resolve from one only the user can resolve. Without those, a proposal offered together with a task could be interpreted as a request to execute rather than a request to challenge, and an open-ended consequential question ("what's the best way to redesign X?") had no rule stopping the agent from silently picking an interpretation. diff --git a/docs/README.md b/docs/README.md index 0871f8a..61cb6ce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -81,21 +81,10 @@ Use [`AGENTIC_WORKFLOW_SANITY.md`](AGENTIC_WORKFLOW_SANITY.md) when changing com should remain useful before any agent-facing detail is read. -## Current architecture boundaries - -The framework is organized into three layers: - -1. Agentic Delivery; -2. Learning & Ownership; -3. Optional Risk Lenses. - -Complete installation uses the payload under `sample/`. Guided adoption uses the -separate `adoption/` surface and integrates only selected concepts into an -existing agentic workflow. +## Learning closure and freshness Meaningful workflow closure can invoke `learning-closure` to decide whether a useful insight belongs in private continuity, a learning-flow surface, or -module -documentation. `learning-freshness` provides a periodic internal consistency -check; external-source claims require retained provenance and external -revalidation. +module documentation. `learning-freshness` provides a periodic internal +consistency check; external-source claims require retained provenance and +external revalidation. diff --git a/sample/common/.agents/skills/structured-change/templates/structure.md b/sample/common/.agents/skills/structured-change/templates/structure.md index 0878b4c..68cdbf9 100644 --- a/sample/common/.agents/skills/structured-change/templates/structure.md +++ b/sample/common/.agents/skills/structured-change/templates/structure.md @@ -10,3 +10,8 @@ 1. ## Seams that must stay separate + +
+Detailed dependency notes + +
diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index abbbfd1..3a3a3af 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -95,6 +95,10 @@ This is a routing rule, not a fixed sequence: new evidence can change the route - Keep temporary state out of stable instructions. - Use `.local/` for meaningful private learning continuity. +## Output shape + +This applies to learning content, design artifacts, and handoffs alike: prefer a compact Mermaid flowchart over prose when explaining a flow, sequence, boundary, or set of relationships. Put verbose, agent-only elaboration — exact code excerpts, exhaustive rationale, long inventories — inside collapsible `
` sections. A short line above the block may say what it contains, but that line must stay factual; it is not a second abstraction that can drift from or contradict what's inside. + ## Handoff End substantial work with only useful sections: diff --git a/sample/common/agentic-flow/README.md b/sample/common/agentic-flow/README.md index 01ba9fe..5f8ff22 100644 --- a/sample/common/agentic-flow/README.md +++ b/sample/common/agentic-flow/README.md @@ -62,8 +62,7 @@ New evidence can change the route mid-task. This is a set of behavioral rules, n | `ROOT_INTEGRATION.md` | connecting existing or missing root instructions | | `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 | +| `learn-anything` | general-topic learning without repository inspection |
Boundary in one sentence diff --git a/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md b/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md index 3a17abd..a370d33 100644 --- a/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md +++ b/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md @@ -21,3 +21,8 @@ _Use at most one when consequential._ ## Promotion decision _Keep conversational, update map/takeaways, or create a durable repository artifact. State why._ + +
+Detailed evidence and reproduction steps + +
diff --git a/sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md b/sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md index 26e5f13..02eb637 100644 --- a/sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md +++ b/sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md @@ -19,3 +19,8 @@ - **Model:** - **Evidence:** - **Boundary:** + +
+Detailed walkthrough + +
diff --git a/sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md b/sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md index 5ec1d9d..6c72a33 100644 --- a/sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md +++ b/sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md @@ -19,3 +19,8 @@ _Stop at preparation unless implementation was requested. Name one execution skill if needed._ ## Ticket-local detail not to promote + +
+Detailed notes + +
diff --git a/sample/profiles/full/learning-flow/README.md b/sample/profiles/full/learning-flow/README.md index acfc0e5..7de64ab 100644 --- a/sample/profiles/full/learning-flow/README.md +++ b/sample/profiles/full/learning-flow/README.md @@ -35,22 +35,7 @@ All skills apply `agentic-flow/EDUCATION.md` selectively. The goal is durable hu 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. -Select one primary learning skill. `agentic-workflow` is only for configuring or understanding the harness itself. - -
-Skill routes - -| Need | Skill | -|---|---| -| compact baseline | `learning-bootstrap` | -| architecture or domain orientation | `repository-orientation` | -| bug or failing behavior | `challenge-debugging` | -| feature based on existing behavior | `analogous-feature` | -| behavior-preserving structural change | `safe-refactor` | -| non-trivial diff or generated change | `change-explainer` | -| context before implementation | `ticket-learning-path` | - -
+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. ## Understanding and assessment diff --git a/scripts/README.md b/scripts/README.md index 824d908..b19fa65 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -32,11 +32,11 @@ flowchart LR ``` ```text -sh install.sh --release v1.0.0 --profile minimal +sh install.sh --release v1.1.0 --profile minimal ``` ```powershell -.\install.ps1 -Release v1.0.0 -Profile Minimal +.\install.ps1 -Release v1.1.0 -Profile Minimal ``` `--release`/`-Release` downloads the packaged artifact and `checksums.txt` @@ -54,7 +54,7 @@ Every install prints which trust boundary it used: ```text Codebase Learning Flow -Version: v1.0.0 +Version: v1.1.0 Source: packaged release (checksum verified) ```