From 70d202cd0008d028282897881c47ac0109bb900f Mon Sep 17 00:00:00 2001 From: legrab Date: Sat, 8 Aug 2026 09:24:13 +0200 Subject: [PATCH 1/2] chore: ignore pycache in scripts --- .gitignore | 3 +++ MANIFEST.txt | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index f2b9d3b..498e909 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,6 @@ Desktop.ini # Locally generated distribution archives /INITIALIZE_LEARNING_FLOW_*.zip /codebase-learning-flow*.zip + +# Python script cache +/scripts/__pycache__ \ No newline at end of file diff --git a/MANIFEST.txt b/MANIFEST.txt index a4618dc..28f4108 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,5 +1,5 @@ .gitattributes 40 -.gitignore 274 +.gitignore 317 AGENTS.md 3172 CHANGELOG.md 11414 docs/DESIGN_NOTES.md 17684 From df0cf59a063fded775c0700bbc398e29aa262227 Mon Sep 17 00:00:00 2001 From: legrab Date: Sat, 8 Aug 2026 07:50:19 +0200 Subject: [PATCH 2/2] feat: provide regulatory extension and streamline agentic workflows --- CHANGELOG.md | 17 +++ MANIFEST.txt | 66 ++++++++--- README.md | 39 ++++++- docs/DESIGN_NOTES.md | 30 ++++- docs/INITIALIZE_LEARNING_FLOW.md | 11 +- docs/README.md | 1 + ...FERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md | 78 +++++++++++++ sample/README.md | 16 +++ .../.agents/skills/structured-change/SKILL.md | 62 ++++++++++ .../knowledge/engineering/ai-collaboration.md | 49 ++++++++ .../knowledge/engineering/architecture.md | 25 ++++ .../engineering/dependency-management.md | 25 ++++ .../knowledge/engineering/documentation.md | 25 ++++ .../knowledge/engineering/maintainability.md | 25 ++++ .../knowledge/engineering/modernization.md | 25 ++++ .../knowledge/engineering/testing.md | 25 ++++ .../structured-change/templates/design.md | 33 ++++++ .../templates/exploration.md | 30 +++++ sample/common/agentic-flow/.managed-skills | 1 + sample/common/agentic-flow/.template-version | 2 +- sample/common/agentic-flow/AGENTS.md | 4 +- sample/common/agentic-flow/CONFIGURE.md | 4 +- sample/common/agentic-flow/DECISIONS.md | 32 ++++++ sample/common/agentic-flow/EDUCATION.md | 2 +- .../common/agentic-flow/ROOT_INTEGRATION.md | 3 +- sample/common/agentic-flow/WORKFLOW.md | 28 +++++ .../skills/regulatory-knowledge/SKILL.md | 43 +++++++ .../knowledge/regulatory/audit-trails.md | 25 ++++ .../regulatory/cfr-part-11-overview.md | 28 +++++ .../knowledge/regulatory/change-control.md | 25 ++++ .../knowledge/regulatory/foundations.md | 29 +++++ .../regulatory/iec-62304-overview.md | 28 +++++ .../regulatory/iso-13485-overview.md | 25 ++++ .../regulatory/iso-14971-overview.md | 26 +++++ .../regulatory/iso-17025-overview.md | 25 ++++ .../knowledge/regulatory/iso-9001-overview.md | 24 ++++ .../knowledge/regulatory/risk-management.md | 33 ++++++ .../knowledge/regulatory/traceability.md | 33 ++++++ .../knowledge/regulatory/validation.md | 25 ++++ .../learning-flow/.extension-managed-files | 4 + .../learning-flow/.extension-managed-skills | 1 + .../regulatory/learning-flow/.extension-name | 1 + .../regulatory/learning-flow/REGULATORY.md | 21 ++++ .../full/learning-flow/.template-version | 2 +- sample/profiles/full/learning-flow/AGENTS.md | 2 +- .../minimal/learning-flow/.template-version | 2 +- .../profiles/minimal/learning-flow/AGENTS.md | 2 +- scripts/README.md | 24 +++- scripts/install.ps1 | 107 +++++++++++++++++- scripts/install.sh | 88 +++++++++++++- skill-evals/README.md | 3 +- skill-evals/structured-change-cases.yaml | 56 +++++++++ 52 files changed, 1299 insertions(+), 41 deletions(-) create mode 100644 docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md create mode 100644 sample/common/.agents/skills/structured-change/SKILL.md create mode 100644 sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md create mode 100644 sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md create mode 100644 sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md create mode 100644 sample/common/.agents/skills/structured-change/knowledge/engineering/documentation.md create mode 100644 sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md create mode 100644 sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md create mode 100644 sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md create mode 100644 sample/common/.agents/skills/structured-change/templates/design.md create mode 100644 sample/common/.agents/skills/structured-change/templates/exploration.md create mode 100644 sample/common/agentic-flow/DECISIONS.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/foundations.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iec-62304-overview.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-13485-overview.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-14971-overview.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-17025-overview.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-9001-overview.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/risk-management.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/traceability.md create mode 100644 sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/validation.md create mode 100644 sample/extensions/regulatory/learning-flow/.extension-managed-files create mode 100644 sample/extensions/regulatory/learning-flow/.extension-managed-skills create mode 100644 sample/extensions/regulatory/learning-flow/.extension-name create mode 100644 sample/extensions/regulatory/learning-flow/REGULATORY.md create mode 100644 skill-evals/structured-change-cases.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 1bcf4d6..9da911f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,23 @@ - Full-profile skills now validate machine-generated work and surface operational or human control boundaries in proportion to risk. - Human-facing documentation now explains the framework before agentic implementation detail. +## 0.8.0 + +### Added + +- A common `structured-change` skill that elaborates `Decide` into `Explore → Design → Approve` for one architecturally significant, ambiguous, or regulated change, available with every profile and running alongside the active route rather than replacing it. +- `agentic-flow/DECISIONS.md`, a durable, append-only decision-record surface, treated like `SETTINGS.md` and written to only through `structured-change`'s Capture Knowledge step. +- An optional `Traceability` section (and regulatory addendum) for commit bodies, documented in `agentic-flow/WORKFLOW.md`, used only for a consequential or regulated change. +- Seven general-purpose engineering knowledge files inside `structured-change` (AI collaboration and anti-overengineering guidance, modernization, maintainability, testing, architecture, dependency management, documentation). +- A new orthogonal, additive installer dimension, extensions (`--extension none|regulatory`, `-Extension None|Regulatory`), alongside the existing profile dimension, with a full add/update/remove lifecycle in `install.sh` and `install.ps1` and its own manifest markers so it never collides with profile bookkeeping. +- A `regulatory` extension: the `regulatory-knowledge` skill, providing traceability, validation, risk-management, audit-trail, and change-control guidance plus short orientation to ISO 9001, ISO 13485, ISO 14971, ISO 17025, IEC 62304, and 21 CFR Part 11, and `learning-flow/REGULATORY.md`. +- `docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md`, documenting a user-requested comprehensive integration and the deliberate exception to the default small-delta review posture. + +### Changed + +- `agentic-flow/AGENTS.md`, `WORKFLOW.md`, `CONFIGURE.md`, `EDUCATION.md`, and `ROOT_INTEGRATION.md` gained short pointers to `structured-change`, `DECISIONS.md`, and the regulatory extension without changing default behavior for ordinary work. +- The installer's final summary line and both profile `AGENTS.md` files now note the selected extension and how `structured-change` pairs with the active route. + ## 0.7.0 ### Added diff --git a/MANIFEST.txt b/MANIFEST.txt index 28f4108..a70c23d 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,34 +1,65 @@ .gitattributes 40 .gitignore 317 AGENTS.md 3172 -CHANGELOG.md 11414 -docs/DESIGN_NOTES.md 17684 -docs/INITIALIZE_LEARNING_FLOW.md 9396 -docs/README.md 2325 +CHANGELOG.md 13500 +docs/DESIGN_NOTES.md 22495 +docs/EDUCATION_MODEL.md 5452 +docs/INITIALIZE_LEARNING_FLOW.md 10880 +docs/README.md 2428 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 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 LICENSE 2213 -README.md 8940 +README.md 10942 sample/common/.agents/skills/agentic-workflow/SKILL.md 3653 sample/common/.agents/skills/learn-anything/agents/openai.yaml 246 sample/common/.agents/skills/learn-anything/SKILL.md 3225 +sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md 2533 +sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md 1386 +sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md 1300 +sample/common/.agents/skills/structured-change/knowledge/engineering/documentation.md 1334 +sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md 1319 +sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md 1254 +sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md 1287 +sample/common/.agents/skills/structured-change/SKILL.md 4136 +sample/common/.agents/skills/structured-change/templates/design.md 649 +sample/common/.agents/skills/structured-change/templates/exploration.md 368 sample/common/agentic-flow/.managed-files 170 -sample/common/agentic-flow/.managed-skills 32 +sample/common/agentic-flow/.managed-skills 50 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 5253 -sample/common/agentic-flow/CONFIGURE.md 4051 +sample/common/agentic-flow/AGENTS.md 5788 +sample/common/agentic-flow/CONFIGURE.md 4475 +sample/common/agentic-flow/DECISIONS.md 963 +sample/common/agentic-flow/EDUCATION.md 5232 sample/common/agentic-flow/LEARN.md 1822 sample/common/agentic-flow/LOCAL.md 3513 sample/common/agentic-flow/README.md 1624 sample/common/agentic-flow/REFERENCE_INTEGRATION.md 2183 -sample/common/agentic-flow/ROOT_INTEGRATION.md 2932 +sample/common/agentic-flow/ROOT_INTEGRATION.md 3086 sample/common/agentic-flow/SETTINGS.md 544 -sample/common/agentic-flow/WORKFLOW.md 3309 +sample/common/agentic-flow/WORKFLOW.md 4674 sample/common/local/learning-history.md 986 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md 1444 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md 2336 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md 1447 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/foundations.md 1997 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iec-62304-overview.md 2341 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-13485-overview.md 1804 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-14971-overview.md 1901 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-17025-overview.md 1724 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-9001-overview.md 1493 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/risk-management.md 1873 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/traceability.md 1871 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/validation.md 1609 +sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md 3530 +sample/extensions/regulatory/learning-flow/.extension-managed-files 81 +sample/extensions/regulatory/learning-flow/.extension-managed-skills 21 +sample/extensions/regulatory/learning-flow/.extension-name 11 +sample/extensions/regulatory/learning-flow/REGULATORY.md 1719 sample/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 @@ -43,7 +74,7 @@ sample/profiles/full/learning-flow/.managed-files 137 sample/profiles/full/learning-flow/.managed-skills 132 sample/profiles/full/learning-flow/.template-profile 5 sample/profiles/full/learning-flow/.template-version 6 -sample/profiles/full/learning-flow/AGENTS.md 4274 +sample/profiles/full/learning-flow/AGENTS.md 4458 sample/profiles/full/learning-flow/BOOTSTRAP.md 1788 sample/profiles/full/learning-flow/MAP.md 1464 sample/profiles/full/learning-flow/PLAYBOOKS.md 1327 @@ -56,19 +87,20 @@ sample/profiles/minimal/learning-flow/.managed-files 87 sample/profiles/minimal/learning-flow/.managed-skills 20 sample/profiles/minimal/learning-flow/.template-profile 8 sample/profiles/minimal/learning-flow/.template-version 6 -sample/profiles/minimal/learning-flow/AGENTS.md 2905 +sample/profiles/minimal/learning-flow/AGENTS.md 3064 sample/profiles/minimal/learning-flow/MAP.md 1229 sample/profiles/minimal/learning-flow/README.md 1974 sample/profiles/minimal/learning-flow/TAKEAWAYS.md 973 -sample/README.md 2113 +sample/README.md 2997 sample/root/AGENTS.md 1339 sample/root/AGENTS.pointer.md 296 scripts/install.bat 1477 -scripts/install.ps1 29480 -scripts/install.sh 24986 -scripts/README.md 3579 +scripts/install.ps1 35102 +scripts/install.sh 29472 +scripts/README.md 4502 skill-evals/agentic-cases.yaml 7109 skill-evals/conversation-cases.yaml 3653 skill-evals/full-cases.yaml 4248 skill-evals/minimal-cases.yaml 3208 -skill-evals/README.md 1110 +skill-evals/README.md 1352 +skill-evals/structured-change-cases.yaml 3735 diff --git a/README.md b/README.md index 3c06dfa..c48c9d7 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,7 @@ Remote piping executes the referenced revision. Pin a release tag or commit for | understand or change the current repository | repository learning | the real engineering task | | learn a general topic | `learn-anything` | the learner's question | | configure or review the harness | `agentic-workflow` | repository collaboration policy | +| sequence one consequential, ambiguous, or regulated change | `structured-change` | the active route above, not a replacement for it | For a general topic: @@ -121,7 +122,7 @@ The framework is repository-agnostic, but it asks deeper questions when work tou - laboratory software; - industrial control and physical equipment; -- regulated or safety-relevant software; +- regulated or safety-relevant software (see the `regulatory` extension for the operational lens); - security and access control; - architecture and integration; - verification and validation; @@ -166,6 +167,30 @@ flowchart LR G --> P3[General conversational learning] ``` +## Extensions + +Extensions are additive and orthogonal to profile: they add capability without changing what `minimal` or `full` mean. The only extension today is `regulatory`. + +| Extension | Adds | Never does | +|---|---|---| +| `regulatory` | `regulatory-knowledge` skill: traceability, validation, risk management, audit trails, change control, and short orientation to ISO 9001, ISO 13485, ISO 14971, ISO 17025, IEC 62304, and 21 CFR Part 11 | turn ordinary low-risk work into a compliance procedure | + +```sh +./scripts/install.sh --profile full --extension regulatory +``` + +```powershell +./scripts/install.ps1 -Profile Full -Extension Regulatory +``` + +`--extension auto` (the default) keeps whatever is currently installed and defaults a fresh install to none. Removing an installed extension needs `update` or `replace` mode, the same restriction that applies to a destructive profile switch: + +```sh +./scripts/install.sh --mode update --extension none +``` + +The Explore → Design → Approve → Implement → Review → Capture Knowledge sequence this extension plugs into is not extension-specific. It lives in `structured-change`, a common skill available with every profile, and elaborates one part of `agentic-flow/WORKFLOW.md`'s `Decide` step for the rare change that is architecturally significant, genuinely ambiguous, or regulated. The `regulatory` extension adds a lens to that same skill; it does not add a second workflow. + ## Private continuity > [!NOTE] @@ -191,9 +216,11 @@ Framework modes: - `fail`: stop when managed content already exists; - `merge`: add missing files and preserve existing content; -- `update`: refresh framework-owned files and skills while preserving settings, maps, takeaways, `.local/`, repository-authored content, and unrelated skills; +- `update`: refresh framework-owned files and skills while preserving settings, decisions, maps, takeaways, `.local/`, repository-authored content, and unrelated skills; - `replace`: replace framework directories and this framework's managed skills. +Extensions follow the same modes: `--extension regulatory` adds it, `--extension none` in `update` or `replace` removes it, and `merge` never removes an installed extension. + A minimal installation can upgrade safely: ```sh @@ -226,14 +253,18 @@ agentic-flow/ ├── WORKFLOW.md ├── EDUCATION.md ├── LEARN.md -└── LOCAL.md +├── LOCAL.md +└── DECISIONS.md learning-flow/ ├── AGENTS.md ├── MAP.md -└── TAKEAWAYS.md +├── TAKEAWAYS.md +└── REGULATORY.md (only with --extension regulatory) .agents/skills/ ├── agentic-workflow/ ├── learn-anything/ +├── structured-change/ +├── regulatory-knowledge/ (only with --extension regulatory) └── profile-specific learning skills ``` diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index 9a5f4b2..d2dc34b 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -105,6 +105,27 @@ Private learning continuity follows the same ownership rule in the source reposi At session closure, the local record is completed before promotion is considered. `MAP.md`, `TAKEAWAYS.md`, and existing shared owners receive only stable, reusable, non-sensitive knowledge after deduplication. An explicit request for global preservation triggers that review but does not override privacy or evidence requirements. Uncertain material stays local. +## v0.8.0 regulatory-aware structured change + +A user-supplied proposal ("Repository Enhancement Proposal: Regulatory-Aware, Human-Guided, Agent-Assisted Engineering Flow") asked for comprehensive incorporation rather than the conservative small-delta review this document otherwise recommends (see v0.6.1). That is a deliberate, explicit exception to the default review posture, not a change to the posture itself; `docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md` records the full mapping from source concept to landing point, including what was fitted into existing ownership rather than added as a new layer. + +The source's `Learn → Explore → Design → Approve → Implement → Review → Capture Knowledge` sequence did not become a competing workflow. It became `structured-change`, a common skill that elaborates the existing `Decide` step in `agentic-flow/WORKFLOW.md` for one architecturally significant, genuinely ambiguous, or regulated change, used alongside the active route rather than instead of it. Most tasks never load it. + +The source's `profiles: default, regulatory` concept collided with this repository's existing use of "profile" for `minimal`/`full`. It became **extensions**, a new orthogonal installer dimension (`--extension none|regulatory`), matching the source's own "Installation Extensions" heading and staying additive: `regulatory` installs identically under either profile and never changes what `minimal` or `full` mean. + +The source's proposed `explorations/`, `designs/`, `reviews/`, `decisions/`, `improvements/`, `integrations/`, `evaluation/` directory scaffold was not created literally; it would have reintroduced the default-folder and activity-proliferation ceremony this document has repeatedly rejected (v0.6.2, Deliberately rejected). Instead: + +- decision records landed in one durable file, `agentic-flow/DECISIONS.md`, treated like `SETTINGS.md` (present, never force-refreshed); +- the commit traceability block and its regulatory addendum became an optional section of the existing commit-body guidance in `agentic-flow/WORKFLOW.md`, used only for a consequential or regulated change; +- improvement and modernization candidates fold into the existing handoff `Open` bullet or into `DECISIONS.md`, not a separate tracking surface; +- the evaluation matrix and confidence-reporting concepts became optional structure inside a design note, not a standing scoring system; +- the MCP integration model became one sentence in `ROOT_INTEGRATION.md`'s existing discovery list, since connected-systems awareness was already the job of that step; +- the human-first documentation standard and collapsible-content guidance were already covered by the existing layered-disclosure contract (v0.5.2) and required no change. + +Regulatory-specific knowledge (traceability, validation, risk management, audit trails, change control, and short orientation to ISO 9001, ISO 13485, ISO 14971, ISO 17025, IEC 62304, and 21 CFR Part 11) lives inside the `regulatory-knowledge` skill installed only by the extension, read a file at a time rather than loaded in bulk. IEC 62304 and 21 CFR Part 11 were added beyond the source proposal as the direct software-lifecycle and electronic-records companions to ISO 13485 and ISO 14971. Content is written as practical orientation, not standard summary or reproduction, consistent with both the source's own knowledge philosophy and this project's copyright discipline. + +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. + ## General agentic loop ```text @@ -172,7 +193,7 @@ Conversation is the live interaction layer. `.local/` is the private continuity ## Skill routing -The common `agentic-workflow` skill initializes, configures, explains, or reviews the workflow. It is not loaded as a second engineering procedure during an ordinary task. The separate common `learn-anything` skill owns general learning conversations and does not inspect the repository by default. +The common `agentic-workflow` skill initializes, configures, explains, or reviews the workflow. It is not loaded as a second engineering procedure during an ordinary task. The separate common `learn-anything` skill owns general learning conversations and does not inspect the repository by default. The common `structured-change` skill elaborates `Decide` for one consequential, ambiguous, or regulated change; it runs alongside the active route, not instead of it, and most tasks never touch it. The `regulatory` extension's `regulatory-knowledge` skill is reference material `structured-change` and task skills consult, not a workflow of its own. The full learning profile keeps seven narrow repository skills for progressive disclosure, but one skill owns the current task. The minimal profile uses one `repository-learning` skill with compact branches for bug, feature, refactor, and orientation work. Both add the common generic conversation skill without changing their repository-learning profile. @@ -188,6 +209,8 @@ The common layer and each learning profile include managed-file and managed-skil Minimal-to-full update is supported. Full-to-minimal update is rejected because safe automatic deletion cannot be inferred. +Extensions (currently only `regulatory`) use the same three modes along a dimension orthogonal to profile: they track their own managed-file and managed-skill manifests under distinct marker names so they never collide with the profile's own markers, and adding or removing one never touches the other's files. + ## Deliberately rejected - mandatory configuration before routine work; @@ -200,7 +223,9 @@ Minimal-to-full update is supported. Full-to-minimal update is rejected because - generic skills for token efficiency or determinism; - generic learning that silently inspects or writes into the host repository; - committed personal transcripts and hypothesis diaries; -- a dashboard, database, vector store, orchestration service, or LMS. +- a dashboard, database, vector store, orchestration service, or LMS; +- a proliferating `explorations/`/`designs/`/`decisions/`-per-item directory scaffold in place of the existing durable-file surfaces; +- mandatory evaluation-matrix scoring or commit traceability blocks for ordinary, low-risk work. ## Final review checklist @@ -216,3 +241,4 @@ Minimal-to-full update is supported. Full-to-minimal update is rejected because 10. Update preserves repository-authored settings and knowledge. 11. The Markdown fallback works without skill support. 12. No workflow requires contributor identity unless the user explicitly wants personal tracking. +13. An installed extension never changes what a profile means, and adding or removing one never touches unrelated framework or repository content. diff --git a/docs/INITIALIZE_LEARNING_FLOW.md b/docs/INITIALIZE_LEARNING_FLOW.md index 1d70b5a..1359137 100644 --- a/docs/INITIALIZE_LEARNING_FLOW.md +++ b/docs/INITIALIZE_LEARNING_FLOW.md @@ -36,6 +36,10 @@ Require the agent to: Do not require a plan file, session record, one-step approval loop, one commit per step, phase gate, or automatic commit offer by default. +## Structured change (optional) + +Provide one common skill that elaborates `Decide` into `Explore → Design → Approve` for a single change that is architecturally significant, genuinely ambiguous between credible options, or regulated. It must run alongside the active task or learning procedure, not replace it, and must not be required for ordinary work. Its design step should name a requested decision and wait for approval before `Act`. Pair it with one durable, append-only decision-record file (not a per-decision file scaffold), written to only when a choice will matter to a later reader. + ## Opinionated setup Provide four simple presets: `fast`, `balanced`, `guided`, and `gated`. Use `balanced` by default and ask for one preset only during explicit or guided configuration. @@ -103,6 +107,7 @@ Use clear ownership: - `.local/`: private sessions, progress, explanations, attempts, quiz history, summaries, uncertainty, and generated follow-ups; - `agentic-flow/SETTINGS.md`: durable collaboration preferences only; +- `agentic-flow/DECISIONS.md`: durable, append-only engineering decision records, written to only through the structured-change step above; - `MAP.md`: compact boundaries and representative flows; - `TAKEAWAYS.md`: short durable lessons; - full-profile `REPOSITORIES.md`: repository identities, baselines, and access boundaries; @@ -116,6 +121,8 @@ New installs default to minimal. Existing installations retain their profile aut Update only manifest-owned framework files and managed skills. Preserve repository-authored settings and knowledge plus unrelated skills. +Support an orthogonal, additive extension dimension (currently one: a regulatory extension adding traceability, validation, risk-management, and audit-trail knowledge). An extension must install identically under either profile, never change what a profile means, track its own managed-file and managed-skill manifests under names distinct from the profile's own, and be fully removable in `update` or `replace` mode without touching profile or repository content. New installs default to no extension; existing installations retain their selection automatically. + Fresh setup must create `.local/{sessions,follow-ups}`, seed `.local/learning-history.md` only when missing, and ensure `/.local/` is ignored. Repeated setup must preserve all existing local content. Retire only framework-owned legacy contributor placeholders automatically; move contributor-authored tracked state only through an explicit verified migration. ## Safety and restraint @@ -139,7 +146,9 @@ Fresh setup must create `.local/{sessions,follow-ups}`, seed `.local/learning-hi - duplicate knowledge surfaces; - skill stacking; - exhaustive repository inventories; -- an LMS or custom platform. +- an LMS or custom platform; +- a per-item exploration, design, or decision directory scaffold in place of one durable file; +- mandatory evaluation-matrix or traceability ceremony applied regardless of risk. ## Existing agentic setup as learning material diff --git a/docs/README.md b/docs/README.md index e10b6d8..90d36e5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,6 +31,7 @@ flowchart LR - [`Awesome Agent Skills`](references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md) - [`Best of Agent Harnesses`](references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md) - [`Goose`](references/REFERENCE_REVIEW_GOOSE.md) +- [`Learning flow adjustment for regulatory`](references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md) - [`Pocok`](references/REFERENCE_REVIEW_POCOK.md) - [`Litt`](references/REFERENCE_REVIEW_LITT.md) diff --git a/docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md b/docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md new file mode 100644 index 0000000..a79b12f --- /dev/null +++ b/docs/references/REFERENCE_REVIEW_LEARNING_FLOW_ADJUSTMENT.md @@ -0,0 +1,78 @@ +# Reference review: Learning flow adjustment for regulatory (user-supplied proposal) + +## Source designation + +- Source: user-supplied document, "Repository Enhancement Proposal: Regulatory-Aware, Human-Guided, Agent-Assisted Engineering Flow" (`learning-flow-adjustment-for-regulatory.md`), provided directly by the repository owner, not a public repository or commit. +- Review date: 2026-08-08. + +## Scope + +The full document: core principles, the proposed `Learn → Explore → Design → Approve → Implement → Review → Capture Knowledge` evolution, installation extensions (profiles and depth modes), a proposed directory structure, skill concepts (exploration, design, implementation, review, improvement discovery), the regulatory profile, a regulatory and engineering knowledge base, AI collaboration guidance, an MCP integration model, exploration/design/decision/improvement document shapes, commit traceability and regulatory notes blocks, an evaluation system, operational impact and confidence reporting, human-first documentation standard, and compatibility requirements. + +## Deliberate exception to the default review posture + +`REFERENCE_INTEGRATION.md` and v0.6.1 of this document treat an external source as comparison evidence, not a target architecture, and normally retain zero to three behavioral adjustments. The repository owner explicitly asked for comprehensive incorporation of the proposal as a single change rather than that default conservative review. This review honors that explicit instruction: the retained delta below is intentionally far larger than three adjustments. The discipline that survives from the default posture is not the size limit but the method: fit value into existing ownership layers, name what was already covered, and do not create a new layer or catalogue where an existing owner is clear. Every item below states where it landed and why, so the size of the change stays traceable even though its scope does not stay small. + +## Already covered + +- The source's Human Ownership principle ("Agents assist. Humans decide.") and its `Observe → Learn → Investigate → Explain → Recommend → Wait` default were already this repository's posture; no change needed beyond the regulatory extension restating it in its own scope (`REGULATORY.md`, `regulatory-knowledge/SKILL.md`). +- Design-before-implementation and stop-on-ambiguity were already available through the `gated` preset and `agentic-flow/WORKFLOW.md`'s `Decide` step; the source's flow became an elaboration of that step (`structured-change`), not a new gate. +- The Human-First Documentation Standard (summary, recommendation, risks, decisions first) and Collapsible Content Guidance were already the layered-disclosure communication contract from v0.5.2. No change made. +- The Compatibility Requirements section (coexist with existing `AGENTS.md`, tooling, and conventions; allow local customization and skill replacement; avoid lock-in) was already the installer's and `ROOT_INTEGRATION.md`'s job. No change made. +- Depth proportional to context was already the `minimal`/`full` profile split and the `fast`/`balanced`/`guided`/`gated` preset axis; the source's "Depth Modes: light, heavy" did not become a third axis. `structured-change` explicitly scales to the existing two. + +## Retained delta + +### Structured change sequencing + +The source's core flow evolution became `structured-change`, a common skill (installed with every profile) that elaborates `Decide` in `agentic-flow/WORKFLOW.md` for one architecturally significant, genuinely ambiguous, or regulated change. It is explicitly not a second delivery workflow: it runs alongside the active learning or task skill. `agentic-flow/AGENTS.md`'s Route section and `CONFIGURE.md`'s `gated` preset description both point to it. + +### Extensions as an installer dimension + +The source's "Profiles: default, regulatory" under "Installation Extensions" became a new orthogonal installer dimension, named **extension** (`--extension none|regulatory`, `-Extension None|Regulatory`) rather than reusing "profile," since this repository already uses "profile" for `minimal`/`full`. `install.sh` and `install.ps1` gained a full parallel add/update/remove lifecycle for it, tracked through distinct marker files (`.extension-name`, `.extension-managed-files`, `.extension-managed-skills`) so it never collides with the profile's own manifests. See `docs/DESIGN_NOTES.md` v0.8.0 and `scripts/README.md`. + +### Decision records + +The source's `decisions/DECISION-XXXX.md` per-item scaffold became one durable file, `agentic-flow/DECISIONS.md`, append-only, treated like `SETTINGS.md` (present by default, never force-refreshed on update). `structured-change`'s Capture Knowledge step is the only path that writes to it, and only when a decision will matter to a later reader. + +### Commit traceability and regulatory notes + +The source's Commit Traceability Block and Regulatory Notes Excerpt became one optional `Traceability` section (plus a regulatory sub-block) documented in `agentic-flow/WORKFLOW.md`, used only for a consequential or regulated change, never for trivial work. + +### Improvement discovery + +The source's `improvements/IMPROVEMENT-XXXX.md` tracking folder did not become a new surface. It folds into the existing handoff `Open` bullet, or into `DECISIONS.md` when a future decision is already anticipated. + +### MCP integration model + +The source's `integrations/` directory and connected-systems documentation became one sentence added to `ROOT_INTEGRATION.md`'s existing discovery list (issue tracker, CI/CD, documentation platform, and the conventions they imply), since recognizing the effective setup was already that step's job. + +### Evaluation system and confidence reporting + +The source's Evaluation Matrix and Agent-Oriented Metrics tables became optional, non-mandatory structure available inside a design note, not a standing scoring system applied by default. Confidence reporting stays categorical (High/Medium/Low), consistent with this repository's existing rejection of numeric learning-confidence percentages, and is scoped to engineering decisions, not learning assessment. + +### Regulatory and engineering knowledge + +The source's `knowledge/regulatory/` and `knowledge/engineering/` content became two skill-local knowledge folders, read a file at a time rather than loaded in bulk: + +- `regulatory-knowledge/knowledge/regulatory/` (installed only by the `regulatory` extension): foundations, traceability, validation, risk management, audit trails, change control, and short orientation to ISO 9001, ISO 13485, ISO 14971, and ISO 17025, matching the source's list. +- `structured-change/knowledge/engineering/` (available with every profile, since it is general-purpose rather than regulatory-specific): AI collaboration and anti-overengineering guidance, modernization, maintainability, testing, architecture, dependency management, and documentation. + +All knowledge content is written as practical orientation, "why it matters / where engineers meet it / common mistakes / review questions," per the source's own Knowledge Philosophy, and deliberately does not reproduce standard clause text, consistent with this project's copyright discipline. + +## Added beyond the source + +Two additional regulatory knowledge files were added beyond the source's ISO list: `iec-62304-overview.md` (medical device software lifecycle) and `cfr-part-11-overview.md` (electronic records and signatures). Both are the direct, standard companions to ISO 13485 and ISO 14971 for anyone building regulated medical device software, and their absence from the source looked like an omission rather than a deliberate exclusion. Each file states plainly that it was added beyond the source. + +## Deliberately not copied literally + +- The proposed top-level `explorations/`, `designs/`, `reviews/`, `improvements/`, `integrations/`, `evaluation/`, `templates/` directories: these would reintroduce the default-folder and activity-proliferation ceremony this document has repeatedly rejected (v0.6.2 and the Deliberately rejected list). Their function is covered above without a matching folder. +- A third "depth mode" configuration axis: `structured-change` scales to the existing profile and preset axes instead. +- Mandatory traceability, evaluation-matrix, or regulatory-notes ceremony for ordinary or low-risk work, in every case: proportionality is stated explicitly wherever this delta touches commit or documentation shape. +- The source's own directory-name vocabulary where it collided with this repository's existing terms (`profile`, `.managed-files`); this repository's existing names win, and the source's names are noted only in this review for traceability. + +## Framework mapping and limits + +`structured-change` and `regulatory-knowledge` are both skills, loaded on demand, not always-on context. The `regulatory` extension changes only what a repository can opt into; it does not change what `minimal` or `full` mean, and it is fully removable through `update` or `replace` mode without touching profile or repository content, verified by a functional test harness exercising the real installer functions (fresh install, update refresh, extension add, extension remove, merge non-destructiveness, replace re-installation, and fail-mode conflict detection) against a scratch target. + +No dashboard, database, vector store, orchestration service, or LMS was introduced. No mandatory configuration step was added to routine work. diff --git a/sample/README.md b/sample/README.md index 1eb22ad..fc5d22d 100644 --- a/sample/README.md +++ b/sample/README.md @@ -7,12 +7,14 @@ flowchart TB C[common agentic-flow] --> M[minimal profile] C --> F[full profile] C --> G[learn-anything] + C --> SC[structured-change] C --> E[shared EDUCATION.md] M --> L[repository learning] F --> L G --> N[general-topic learning] L --> P[private continuity in .local] N --> P + Ext[extensions/regulatory] -.optional.-> L ``` ## Source layout @@ -21,9 +23,11 @@ flowchart TB sample/common/agentic-flow/ sample/common/.agents/skills/agentic-workflow/ sample/common/.agents/skills/learn-anything/ +sample/common/.agents/skills/structured-change/ sample/common/local/learning-history.md sample/profiles/minimal/ sample/profiles/full/ +sample/extensions/regulatory/ sample/root/ ``` @@ -33,6 +37,8 @@ sample/root/ | `agentic-flow/EDUCATION.md` | system ownership, resilience, AI independence, and teaching judgment | | `learning-flow/` | repository education 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 | | `.local/` | private sessions, attempts, checks, progress, and follow-ups | > [!IMPORTANT] @@ -51,4 +57,14 @@ Fresh installs default to the minimal profile. Existing installations retain the +
+Extensions + +- `sample/extensions/regulatory/` layers `learning-flow/REGULATORY.md` and the `regulatory-knowledge` skill on top of either profile. +- Extensions never change what a profile means and never appear unless requested via `--extension regulatory`. +- Fresh installs default to no extension. Existing installations retain their selection. +- Removing an installed extension requires `update` or `replace` mode, the same restriction that applies to a destructive profile switch. + +
+ The common layer also includes `REFERENCE_INTEGRATION.md` for learning from outside repositories or ZIPs without copying source-specific policy. diff --git a/sample/common/.agents/skills/structured-change/SKILL.md b/sample/common/.agents/skills/structured-change/SKILL.md new file mode 100644 index 0000000..bff0213 --- /dev/null +++ b/sample/common/.agents/skills/structured-change/SKILL.md @@ -0,0 +1,62 @@ +--- +name: structured-change +description: Sequence Explore, Design, and Approve before Act for one consequential, ambiguous, or high-risk change, producing a right-sized exploration note and design note with a requested decision. Use alongside the active learning or engineering skill for a single significant change. Do not use it as mandatory ceremony for ordinary, low-risk, or unambiguous work, and do not use it as a second engineering procedure. +--- + +# Structured change + +Read `agentic-flow/AGENTS.md`, `agentic-flow/SETTINGS.md`, and `agentic-flow/WORKFLOW.md`. This skill elaborates one part of `Decide`. It does not replace `WORKFLOW.md`, `repository-learning`, or a full-profile task skill, and it is not a second delivery workflow running alongside them. + +## When this applies + +Use it only when at least one is true: + +- the change is architecturally significant, hard to reverse, or spans multiple owners; +- two or more credible approaches exist and repository evidence does not select one; +- the configured preset is `gated`, or the user asked for a design review, migration plan, or formal decision; +- `.agents/skills/regulatory-knowledge/` is installed and the change affects validated, safety-relevant, or audited behavior. + +Skip it for a routine bug, small feature, refactor, or anything `balanced` or `fast` resolves directly. Most tasks never touch this skill. + +## Explore + +1. State the currently understood behavior, purpose, and constraints; separate established fact from assumption. +2. List unknowns and the risks or options they affect. +3. Stop at understanding here. Do not propose or implement yet. + +Keep this conversational by default. Use `templates/exploration.md` only when a written artifact will earn its cost, per Scale below. + +## Design + +1. Compare credible options against tradeoffs, risk, and migration cost. +2. Select an approach and state what remains a requested decision for the user. +3. Name the verification plan and, only when the change is genuinely hard to reverse, a rollback approach. +4. When `regulatory-knowledge` is installed and relevant, note traceability, validation impact, and requirement linkage using its guidance. Do not invent compliance language the repository does not already use. + +Use `templates/design.md` only when it earns its cost, per Scale below. + +## Approve + +State the requested decision plainly and wait for it before implementing. An explicit prior instruction that already resolves the choice satisfies this step; do not ask again. + +## Implement and review + +Follow the approved design under the normal `agentic-flow/WORKFLOW.md` loop. Note any deviation from the design and why. For work spanning more than one commit, review each meaningful commit against the approved design before starting the next rather than reviewing everything at the end. + +## Capture knowledge + +- Fold the outcome into the normal handoff. +- Record a durable decision in `agentic-flow/DECISIONS.md` only when the choice will matter to someone reading the repository later. Most decisions stay in conversation or `.local/`. +- Note a deferred improvement or modernization opportunity as an `Open` handoff item, or in `DECISIONS.md` when a future decision is already anticipated. Do not create a separate improvement-tracking file. + +## Scale to profile, preset, and risk + +- `minimal` profile or `fast`/`balanced` preset: keep Explore and Design conversational, a few sentences each. +- `full` profile or `guided`/`gated` preset, or a genuinely high-risk change: use the templates, add characterization evidence, and keep the traceability fields in `agentic-flow/WORKFLOW.md`'s commit guidance. +- `regulatory-knowledge` installed: read only the specific knowledge file the decision touches, not the whole set. + +## Restraint + +- One structured decision per change; do not stack this with a second formal process. +- Never require this skill for ordinary work, and never block on a declined design review unless the user or repository instructions require sign-off. +- Prefer the simplest acceptable solution over the most abstract one; see `knowledge/engineering/ai-collaboration.md` for indicators. diff --git a/sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md b/sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md new file mode 100644 index 0000000..b30d845 --- /dev/null +++ b/sample/common/.agents/skills/structured-change/knowledge/engineering/ai-collaboration.md @@ -0,0 +1,49 @@ +# Designing a codebase AI can work in safely + +## Why it matters + +The same properties that make code easy for a new human hire to work in safely make it easy for an agent to work in safely: clear ownership, explicit contracts, and low hidden coupling. A codebase that is hard for an agent to reason about is usually also hard for a human reviewer to reason about; the agent just exposes the cost sooner and more often. + +## Positive indicators + +- clear ownership per module or service; +- explicit contracts (types, schemas, interfaces) over implicit convention; +- dependency injection where it earns its cost, not everywhere by default; +- architecture records that explain why, not just what; +- consistent naming that survives search and grep; +- focused classes and modules with one clear reason to change; +- tests that describe behavior, not implementation detail. + +## Negative indicators + +- hidden behavior triggered by naming convention, magic strings, or reflection; +- large god objects or god services that own too much; +- undocumented conventions that only work if you already know them; +- excessive abstraction ahead of a second real use case; +- speculative architecture built for requirements that do not exist yet; +- helper-class proliferation where a direct call would read more clearly; +- unclear ownership between two modules that both partially handle the same concern. + +## Anti-overengineering guidance + +Prefer the **simplest acceptable solution** over the most abstract one. Concretely, avoid generating: + +- a helper class or wrapper with no behavior of its own; +- a speculative extension point for a requirement nobody has asked for; +- a new abstraction layer justified by "reuse" before a second caller exists; +- a service wrapper that only forwards calls; +- an architecture pattern adopted for its name rather than a concrete local benefit. + +A second real use case is usually the right trigger for generalizing. One use case plus a guess about a second is not. + +## Common mistakes + +- treating agent fluency as a substitute for a contract the agent can be checked against; +- adding abstraction to make code "AI-friendly" instead of making it simply well-owned; +- optimizing for a specific tool's context window instead of for a human reviewer. + +## Review questions + +- Could a new contributor (human or agent) find the owner of this behavior without asking? +- Does this abstraction have a second real caller, or only a hoped-for one? +- If this class or wrapper were deleted, would anything besides indirection be lost? diff --git a/sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md b/sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md new file mode 100644 index 0000000..79407c2 --- /dev/null +++ b/sample/common/.agents/skills/structured-change/knowledge/engineering/architecture.md @@ -0,0 +1,25 @@ +# Architecture + +## Why it matters + +Architecture is where local decisions accumulate into a system that either supports change or resists it. A single well-intentioned local decision rarely breaks a system; the accumulation of several does. Architectural judgment is mostly the discipline of asking what a decision costs somewhere else before committing to it here. + +## Where engineers meet it + +- choosing a boundary between two services or modules; +- deciding whether a capability belongs behind an existing seam or needs a new one; +- evaluating whether a proposed pattern fits the system's actual failure modes, not just its feature list; +- weighing a locally convenient shortcut against the system-wide cost of the precedent it sets. + +## Common mistakes + +- adopting a pattern for its reputation rather than for a concrete local benefit; +- optimizing one boundary while quietly pushing complexity across it to a neighbor; +- treating an architecture decision as permanent when its cost was only ever justified by conditions that have since changed; +- skipping the question of who owns and can change each boundary. + +## Review questions + +- Who owns this boundary, and can they change it without coordinating with everyone downstream? +- Does this decision solve a problem the system actually has, or one it might have? +- What is the cost of being wrong, and how would we detect it early? diff --git a/sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md b/sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md new file mode 100644 index 0000000..4741ff3 --- /dev/null +++ b/sample/common/.agents/skills/structured-change/knowledge/engineering/dependency-management.md @@ -0,0 +1,25 @@ +# Dependency management + +## Why it matters + +Every dependency is a small transfer of control: over the update schedule, the security surface, and the assumptions baked into your code. That transfer is often worth it. It is rarely free, and it is almost never evaluated at the moment the convenience is highest. + +## Where engineers meet it + +- adding a library to solve a problem that a small amount of local code would also solve; +- upgrading across a major version with breaking changes; +- inheriting a transitive dependency's licensing, security, or maintenance risk; +- pinning versus floating version ranges in a way that trades reproducibility against staying current. + +## Common mistakes + +- adding a dependency for a single function's worth of value; +- upgrading without reading what actually changed, relying on tests alone to catch breakage; +- letting a dependency's release cadence dictate the codebase's update cadence rather than the other way around; +- losing track of which dependencies are load-bearing versus incidental. + +## Review questions + +- Would a small amount of local code cost less over time than this dependency? +- What happens to this system if the dependency is abandoned or its license changes? +- Is the version pinned deliberately, or just whatever resolved at install time? diff --git a/sample/common/.agents/skills/structured-change/knowledge/engineering/documentation.md b/sample/common/.agents/skills/structured-change/knowledge/engineering/documentation.md new file mode 100644 index 0000000..72c8ea3 --- /dev/null +++ b/sample/common/.agents/skills/structured-change/knowledge/engineering/documentation.md @@ -0,0 +1,25 @@ +# Documentation + +## Why it matters + +Documentation's job is to preserve reasoning that evidence alone cannot reconstruct: why an option was rejected, what constraint forced a shortcut, what would have to change for a decision to be revisited. Code shows what happens; documentation is the only place "why" survives. + +## Where engineers meet it + +- explaining a non-obvious decision so it is not silently reverted later; +- writing a change explanation that a reviewer can actually use to assess risk; +- deciding what belongs in durable documentation versus a one-off handoff; +- keeping documentation from drifting out of sync with the code it describes. + +## Common mistakes + +- documenting what the code already makes obvious instead of the reasoning it hides; +- writing documentation once and never revisiting it as the decision context changes; +- letting documentation duplicate code structure (a file-by-file walkthrough) instead of explaining execution order and intent; +- treating a long document as more thorough when a short, accurate one would serve better. + +## Review questions + +- If this decision were questioned in a year, does anything explain why it was made? +- Does this documentation state a conclusion first, or make the reader dig for it? +- Is this durable enough to be worth the maintenance cost of keeping it accurate? diff --git a/sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md b/sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md new file mode 100644 index 0000000..afe413a --- /dev/null +++ b/sample/common/.agents/skills/structured-change/knowledge/engineering/maintainability.md @@ -0,0 +1,25 @@ +# Maintainability + +## Why it matters + +Maintainability is the cost of the next change, not the cost of this one. Code that is quick to write but expensive to revisit trades a small present cost for a larger future one, usually paid by someone else. The relevant question for any change is what it does to the cost of the *next* five changes, not just this one. + +## Where engineers meet it + +- a fix that works but leaves the failure mode undocumented for the next person; +- a shortcut taken under deadline pressure that quietly becomes the permanent pattern; +- a module that only one person can safely change; +- test coverage that protects the happy path but not the failure and edge behavior that actually breaks in production. + +## Common mistakes + +- treating "it works" as equivalent to "it is understood"; +- optimizing for the current change instead of the next several; +- confusing more code (defensive checks, extra layers) with more maintainable code; +- leaving a known shortcut undocumented so it looks intentional to the next reader. + +## Review questions + +- If this breaks in six months, does the surrounding code explain why it exists? +- Does understanding this change require someone who was in the room, or does the evidence stand on its own? +- Is this simpler to own than what it replaced, or just different? diff --git a/sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md b/sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md new file mode 100644 index 0000000..639da3b --- /dev/null +++ b/sample/common/.agents/skills/structured-change/knowledge/engineering/modernization.md @@ -0,0 +1,25 @@ +# Modernization + +## Why it matters + +Modernization is a cost-shifting decision, not an aesthetic one. The cost of an old dependency, framework, or pattern does not disappear by ignoring it; it moves into onboarding time, workaround complexity, and incident response. The question is never "is this outdated" but "where is the cost currently landing, and is now the right time to move it." + +## Where engineers meet it + +- a library or runtime approaching end of support; +- a pattern the rest of the ecosystem has moved past, making hiring and documentation harder; +- a workaround stack that has grown taller than the problem it solves; +- a migration blocking an unrelated but urgent change. + +## Common mistakes + +- modernizing for its own sake without a named cost it reduces; +- a rewrite framed as modernization that quietly expands scope into a redesign; +- deferring modernization until it becomes an emergency migration under deadline pressure; +- ignoring the operational cost of running two patterns side by side during a partial migration. + +## Review questions + +- What concrete cost does this change reduce, and who currently pays it? +- Can this move incrementally, or does it require a flag day? +- What is the fallback if the migration stalls halfway? diff --git a/sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md b/sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md new file mode 100644 index 0000000..1a85c5d --- /dev/null +++ b/sample/common/.agents/skills/structured-change/knowledge/engineering/testing.md @@ -0,0 +1,25 @@ +# Testing + +## Why it matters + +A test's job is to encode a contract so a future change can be checked against it without re-deriving the reasoning behind it. A test suite that only proves the current implementation does what the current implementation does is not evidence; it is a restatement. + +## Where engineers meet it + +- validating machine-generated code before trusting it; +- characterizing existing behavior before a refactor; +- distinguishing a test that encodes the actual contract from one that encodes an implementation detail; +- deciding how much proof a change actually needs, proportional to its risk. + +## Common mistakes + +- treating passing tests as validation when the tests encode the wrong contract; +- writing characterization tests so tightly coupled to implementation that they block the refactor they were meant to protect; +- broadening test scope to match perceived risk instead of actual risk; +- claiming verification that the available toolchain did not actually perform. + +## Review questions + +- If the implementation changed but the contract did not, would this test still pass? +- What decisive evidence would tell us the mechanism is understood, not just that the output matched once? +- Is the proof proportional to the risk, or is it either token or excessive? diff --git a/sample/common/.agents/skills/structured-change/templates/design.md b/sample/common/.agents/skills/structured-change/templates/design.md new file mode 100644 index 0000000..203f5e5 --- /dev/null +++ b/sample/common/.agents/skills/structured-change/templates/design.md @@ -0,0 +1,33 @@ +# : design + +## Recommendation + +## Requested decision + +## Options considered + +| Option | Tradeoffs | +|---|---| + +## Selected approach + +## Verification plan + +## Rollback + +_Only when the change is genuinely hard to reverse._ + +## Regulatory notes + +_Only when `regulatory-knowledge` is installed and relevant. Delete this section otherwise._ + +- **Traceability:** +- **Validation impact:** None / Low / Medium / High +- **Data integrity impact:** None / Low / Medium / High +- **Auditability impact:** None / Low / Medium / High +- **Requirement → design → code → test linkage:** + +
+Detailed analysis + +
diff --git a/sample/common/.agents/skills/structured-change/templates/exploration.md b/sample/common/.agents/skills/structured-change/templates/exploration.md new file mode 100644 index 0000000..c6a348a --- /dev/null +++ b/sample/common/.agents/skills/structured-change/templates/exploration.md @@ -0,0 +1,30 @@ +# : exploration + +## Objective + +## Key findings + +## Facts + +_Established from source, tests, configuration, or runtime evidence._ + +## Assumptions + +_Never presented as fact._ + +## Unknowns + +## Risks + +## Candidate directions + +## Confidence + +| Area | Confidence | +|---|---| +| | High / Medium / Low | + +
+Detailed findings + +
diff --git a/sample/common/agentic-flow/.managed-skills b/sample/common/agentic-flow/.managed-skills index 198d608..eda0bc0 100644 --- a/sample/common/agentic-flow/.managed-skills +++ b/sample/common/agentic-flow/.managed-skills @@ -1,2 +1,3 @@ agentic-workflow learn-anything +structured-change diff --git a/sample/common/agentic-flow/.template-version b/sample/common/agentic-flow/.template-version index faef31a..a3df0a6 100644 --- a/sample/common/agentic-flow/.template-version +++ b/sample/common/agentic-flow/.template-version @@ -1 +1 @@ -0.7.0 +0.8.0 diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index af1ce6a..f011a76 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -8,6 +8,7 @@ 4. Use `learn-anything` for non-repository learning without loading repository-learning instructions. 5. Learning routes apply `EDUCATION.md` selectively. 6. Load at most one task skill unless the task clearly requires more. +7. For one consequential, ambiguous, or regulated change, `structured-change` may run alongside the chosen route to sequence Explore, Design, and Approve before Act. It elaborates `Decide`; it is not a second route, and most tasks never need it. Read `SETTINGS.md`; use `balanced` immediately when settings remain at defaults. Read `CONFIGURE.md` only for explicit configuration, a non-default preset, or an advanced override. @@ -50,6 +51,7 @@ An explicit implementation request permits ordinary reversible work within scope - Small tasks need no formal plan; multi-step tasks use a short in-chat plan. - Create a plan file only when risk, duration, configuration, or handoff justifies it. +- Record a durable decision in `DECISIONS.md` only when it will matter to a later reader; most decisions stay in conversation or `.local/`. - Inspect the smallest responsible scope and prefer one coherent change over artificial micro-steps. - Revisit the route when evidence changes the scope, architecture, or behavior. - Validate in proportion to risk, focused first. Separate changes applied from executable checks completed and never claim unavailable verification. @@ -86,4 +88,4 @@ Checks: - meaningful verification ``` -Trivial commits need only a title. Do not commit, push, publish, merge, or create release tags unless explicitly requested. +Trivial commits need only a title. For a consequential or regulated change, add the optional `Traceability` section described in `WORKFLOW.md` instead of expanding this default shape. Do not commit, push, publish, merge, or create release tags unless explicitly requested. diff --git a/sample/common/agentic-flow/CONFIGURE.md b/sample/common/agentic-flow/CONFIGURE.md index d1205e3..d62842a 100644 --- a/sample/common/agentic-flow/CONFIGURE.md +++ b/sample/common/agentic-flow/CONFIGURE.md @@ -9,10 +9,12 @@ Configuration is optional. Use `balanced` by default and begin work immediately. | `fast` | routine, low-risk delivery | end-to-end autonomy, minimal planning, focused checks, no learning prompts or persistence | | `balanced` | normal repository work | meaningful-fork autonomy, brief planning, risk-based checks, concise learning in the handoff, durable findings only | | `guided` | deliberate codebase and domain learning | balanced delivery with prediction, explanation, one consequential check, and durable findings only | -| `gated` | high-risk or review-heavy work | pause before implementation and major scope changes, use durable phases, broad checks, and lean learning | +| `gated` | high-risk or review-heavy work | pause before implementation and major scope changes, use durable phases, broad checks, and lean learning; typically pairs with `structured-change` | `balanced` is the default. A task-specific request such as “move fast,” “teach me as we work,” or “pause before implementation” overrides the stored preset for that task without rewriting settings. +`gated` sets the default posture; `structured-change` is what actually runs the Explore → Design → Approve sequence for one change, regardless of preset, when the change itself warrants it. When `.agents/skills/regulatory-knowledge/` is installed (the `regulatory` extension), that lens is available to `structured-change` automatically; it does not change the default preset. +
Advanced overrides and optional learner context diff --git a/sample/common/agentic-flow/DECISIONS.md b/sample/common/agentic-flow/DECISIONS.md new file mode 100644 index 0000000..c532ce6 --- /dev/null +++ b/sample/common/agentic-flow/DECISIONS.md @@ -0,0 +1,32 @@ +# Decisions + +A durable record of consequential engineering decisions: the ones a later reader could not safely reconstruct from code alone. Most decisions in a repository never belong here; conversation and `.local/` are the default. Add an entry only through `structured-change`'s Capture knowledge step, or when explicitly asked, and only when the choice will matter to someone reading this repository later. + +Append new entries below the template. Do not delete a past entry; if a decision is later reversed, add a new entry that supersedes it and say so. + +--- + +## Template + +```text +## (YYYY-MM-DD) + +Problem +- What forced this decision. + +Options +- Option A — tradeoff +- Option B — tradeoff + +Decision +- What was chosen. + +Rationale +- Why, in enough detail to survive without the original conversation. + +Consequences +- What this makes easier, harder, or now assumed elsewhere. + +Review date +- When this should be revisited, if ever. +``` diff --git a/sample/common/agentic-flow/EDUCATION.md b/sample/common/agentic-flow/EDUCATION.md index 4fdb7af..6a1f460 100644 --- a/sample/common/agentic-flow/EDUCATION.md +++ b/sample/common/agentic-flow/EDUCATION.md @@ -89,7 +89,7 @@ When relevant, examine: Use deeper scrutiny for laboratory software, industrial control, regulated software, security, architecture and integration, validation, education and assessment, and human-machine workflow design. -Do not force these lenses onto low-risk work. +Do not force these lenses onto low-risk work. For the operational version of the regulation, audit, and professional-responsibility lens, use `structured-change` and, when installed, the `regulatory-knowledge` skill from the `regulatory` extension, rather than reasoning about traceability or risk acceptance from first principles each time. ## 6. Preserve human educational value diff --git a/sample/common/agentic-flow/ROOT_INTEGRATION.md b/sample/common/agentic-flow/ROOT_INTEGRATION.md index 65cecc6..100c486 100644 --- a/sample/common/agentic-flow/ROOT_INTEGRATION.md +++ b/sample/common/agentic-flow/ROOT_INTEGRATION.md @@ -9,7 +9,8 @@ Before creating or editing a root `AGENTS.md`, look for: - root and nested `AGENTS.md` files; - other agent instruction surfaces such as `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursor/rules/`, or equivalent files; - existing skills, prompts, plans, session records, status files, and evidence ledgers; -- repository-specific commands, architecture rules, security boundaries, and release gates. +- repository-specific commands, architecture rules, security boundaries, and release gates; +- connected systems already in use, such as an issue tracker, CI/CD, or documentation platform, and any ticket-reference or commit-convention they imply. Preserve repository-specific rules. Connect the installed layers rather than replacing working native instructions. diff --git a/sample/common/agentic-flow/WORKFLOW.md b/sample/common/agentic-flow/WORKFLOW.md index 4e6781e..7cb0c34 100644 --- a/sample/common/agentic-flow/WORKFLOW.md +++ b/sample/common/agentic-flow/WORKFLOW.md @@ -22,6 +22,8 @@ Confirm that the route's required runtime, tools, access, and approval are avail If collaboration behavior materially affects the result and repository evidence does not settle it, use the configured preset or ask for one relevant override. Otherwise use `balanced`. +For a change that is architecturally significant, genuinely ambiguous between credible options, or regulated, expand Decide into a short Explore → Design → Approve sequence using `structured-change` before moving to Act: state current understanding and unknowns, propose an approach with tradeoffs and a requested decision, then get explicit approval. Keep this proportional; do not expand Decide this way for ordinary work. + ## Act Make the smallest responsible change or investigation that reaches the outcome. Keep unrelated cleanup out of scope. Do not force one-file or one-commit steps when a coherent slice is safer. @@ -65,6 +67,32 @@ Use descriptive bullets grouped by outcome instead of a chronological tool log o When `learning-flow/` or a meaningful generic learning session was active, close private continuity under `.local/` according to `LOCAL.md`, then fold only useful learning reinforcement into this handoff. Do not add a second recap section, repeat the same outcome and evidence, or expose private session detail through shared records. +## Traceability + +For most work, the commit shape in `AGENTS.md` is enough. For a consequential or regulated change, and only then, add a `Traceability` section to the commit body: + +```text +Traceability: +- Requirements: relevant requirement or ticket +- Design: relevant design note or DECISIONS.md entry, if any +- Behavior change: None / Minor / Major +- Risk level: Low / Medium / High +- Tests: Added / Updated / Existing / None +- Documentation: Updated / Not required +``` + +When `.agents/skills/regulatory-knowledge/` is installed and relevant, append: + +```text +Regulatory: +- Validation impact: None / Low / Medium / High +- Data integrity impact: None / Low / Medium / High +- Auditability impact: None / Low / Medium / High +- Requirement → design → code → test linkage: Complete / Partial / Not applicable +``` + +Do not add either block to a trivial or low-risk change; it dilutes the signal for the changes that actually need it. + ## Stop conditions Stop when the outcome is achieved with proportionate proof, a genuine blocker or design choice requires input, further investigation has low expected value, or remaining work belongs to another task. diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md new file mode 100644 index 0000000..7a5459f --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/SKILL.md @@ -0,0 +1,43 @@ +--- +name: regulatory-knowledge +description: Practical, non-standard-reproducing engineering guidance on traceability, validation, risk management, audit trails, and change control for regulated or quality-managed work, plus short orientation to ISO 9001, ISO 13485, ISO 14971, ISO 17025, IEC 62304, and 21 CFR Part 11. Use when `structured-change`, a task skill, or the user needs the regulatory lens on a specific decision. Do not use it to turn ordinary low-risk work into a compliance procedure, and do not quote or reproduce standard text. +--- + +# Regulatory knowledge + +This skill is reference material, not a workflow. It is consulted by `structured-change`, a task skill, or directly, for one specific question. Read only the file that matches the current question; do not read the whole `knowledge/` directory by default. + +## Files + +| File | Read for | +|---|---| +| `knowledge/regulatory/foundations.md` | orientation before anything else in this skill | +| `knowledge/regulatory/traceability.md` | requirement, design, code, and test linkage | +| `knowledge/regulatory/validation.md` | proving a system does what it is intended to do | +| `knowledge/regulatory/risk-management.md` | identifying, evaluating, and controlling risk | +| `knowledge/regulatory/audit-trails.md` | who did what, when, and why, in a way that survives review | +| `knowledge/regulatory/change-control.md` | evaluating and recording a change to a controlled system | +| `knowledge/regulatory/iso-9001-overview.md` | general quality management system orientation | +| `knowledge/regulatory/iso-13485-overview.md` | medical device quality management orientation | +| `knowledge/regulatory/iso-14971-overview.md` | medical device risk management orientation | +| `knowledge/regulatory/iso-17025-overview.md` | testing and calibration laboratory competence orientation | +| `knowledge/regulatory/iec-62304-overview.md` | medical device software lifecycle orientation | +| `knowledge/regulatory/cfr-part-11-overview.md` | electronic records and signatures orientation | + +## How to use this with `structured-change` + +1. Confirm the change actually touches validated, safety-relevant, or audited behavior. Most changes in a regulated repository do not; this lens is selective, not automatic. +2. Read the one or two files that match the actual question. +3. Fill only the `Regulatory notes` section of `templates/design.md` that applies; delete the rest. +4. Add the regulatory notes excerpt to the commit body only for a change where it adds real traceability value, per `agentic-flow/WORKFLOW.md`. +5. Record a durable decision in `agentic-flow/DECISIONS.md` when the choice, its rationale, or its risk acceptance will matter on a later audit or review. + +## What this skill is not + +- It is not a substitute for the repository's actual quality management system, design history file, or regulatory affairs function. Agents assist; humans decide and sign. +- It does not reproduce standard clause text. It explains why a concept matters, where engineers encounter it, common mistakes, and what a reviewer should ask, so the standard itself remains the authoritative source. +- It does not require every task in a regulated repository to produce traceability paperwork. Proportionality applies: a one-line typo fix stays a one-line typo fix. + +## Human ownership + +Traceability, validation, and risk decisions are accountability decisions, not just documentation exercises. This skill supports the record; it does not substitute for the qualified person who owns the decision. diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md new file mode 100644 index 0000000..e9eb896 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/audit-trails.md @@ -0,0 +1,25 @@ +# Audit trails + +## Why it matters + +An audit trail exists to answer "who did what, when, and why" without relying on anyone's memory. Its value is realized entirely at the moment someone needs it under pressure, which is usually long after the context that made it obvious has faded. + +## How engineers actually encounter this + +- a code review approval that needs to record who reviewed what version, not just that review happened; +- a configuration or data change in a controlled system that needs to be attributable to a specific actor and reason, not just logged as an event; +- a deleted or amended record that needs to preserve what it looked like before the change, not just the final state; +- distinguishing a system-generated action from a human-approved one when both appear in the same log. + +## Common mistakes + +- logging that a change happened without logging who approved it or why; +- an audit trail that can itself be edited without leaving evidence of the edit; +- treating version control history as a sufficient audit trail when it does not capture approval or review context; +- audit logging added after the fact, based on memory, instead of captured at the time of the action. + +## Review questions + +- Could someone reconstruct who approved this and why, without asking the person who did it? +- Is the audit record itself protected from silent modification? +- Does the trail distinguish automated actions from human-approved ones? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md new file mode 100644 index 0000000..74e04c5 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/cfr-part-11-overview.md @@ -0,0 +1,28 @@ +# 21 CFR Part 11 orientation + +_Not requested by the source document; added because it is the direct electronic-records companion to audit trails and change control for anyone building software that produces regulated records._ + +## What it actually governs + +21 CFR Part 11 is the FDA regulation governing when electronic records and electronic signatures can substitute for paper records and handwritten signatures. It matters to engineers the moment a system creates, modifies, maintains, or transmits a record that a regulation elsewhere requires to exist, such as a device history record or a quality record. + +## Why engineers meet it + +- audit trail requirements for electronic records: computer-generated, time-stamped, secure, and independent of the operator's ability to edit or disable it (see `audit-trails.md` for the general discipline); +- system access control: only authorized individuals can create, modify, or sign a record, with identity tied to the action, not just to a shared login; +- electronic signature binding: a signature must be uniquely linked to the record it signs and to the specific meaning of that signature (approved, reviewed, authored), not a generic checkbox; +- record retention and retrieval: the system must keep records accurate, readable, and retrievable for as long as the applicable regulation requires, across system upgrades and migrations; +- validation of the system itself: the software that manages these records needs its own validation evidence that it does what it claims (see `validation.md`). + +## Common mistakes + +- building an "edit history" feature that can itself be disabled or bypassed by the same users it is meant to constrain; +- using shared accounts or generic logins, which breaks the link between an action and an accountable individual; +- treating a checkbox or typed name as an electronic signature without the binding and meaning it requires; +- losing record readability across a system migration because the new system cannot render the old format. + +## Review questions + +- Can the audit trail for this record be edited or disabled by the same role it is meant to hold accountable? +- Is every signature uniquely tied to an individual and to a specific stated meaning? +- If this record needs to be retrieved in ten years, does the current system design make that plausible? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md new file mode 100644 index 0000000..ae9c68e --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/change-control.md @@ -0,0 +1,25 @@ +# Change control + +## Why it matters + +Change control is the discipline of evaluating a change's impact before it happens rather than discovering the impact after release. In a controlled system, an "obviously safe" small change is exactly the category that most often turns out to have an overlooked downstream effect. + +## How engineers actually encounter this + +- classifying a change by impact (does it touch validated behavior, safety-relevant logic, or only internal tooling) before deciding how much review it needs; +- evaluating whether a change requires re-validation, and how much of it; +- distinguishing a like-for-like fix from a change that alters behavior, even subtly; +- recording the approval and rationale for a change to a controlled system, not just the diff. + +## Common mistakes + +- assuming a small diff means small impact without checking what the diff actually touches; +- routing a behavior-changing fix through the "minor fix" process because it looked small at a glance; +- approving a change based on the description rather than the actual diff; +- skipping impact classification under deadline pressure and planning to "document it properly later." + +## Review questions + +- Does this change alter validated or safety-relevant behavior, even if the diff is small? +- What is the smallest re-validation scope this change actually requires? +- Is the impact classification recorded before implementation, or reconstructed afterward? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/foundations.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/foundations.md new file mode 100644 index 0000000..1ead2c6 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/foundations.md @@ -0,0 +1,29 @@ +# Regulatory foundations + +## Why it matters + +Regulated engineering is not "more careful engineering." It is engineering where someone else, later, has to be able to reconstruct why a decision was safe without asking you. The extra artifacts (traceability, validation evidence, risk records) exist to answer that question when memory and Slack history are gone. + +## The shift in default assumptions + +Ordinary engineering optimizes for the fastest safe path to a working, well-owned system. Regulated engineering adds one more constraint: every consequential decision must be reconstructable by an auditor, a regulator, or a future engineer with none of today's context. That changes what "done" means, not how hard you should think. + +## How engineers actually encounter this + +- a requirement changes and someone needs to know which code and tests trace back to it; +- a defect is found in the field and someone needs to know which other releases share the same code path; +- a design choice trades one risk for another and the rationale needs to survive staff turnover; +- an auditor asks "how do you know this works," and "it passed our tests" is only half an answer without knowing which tests, against which requirement, reviewed by whom. + +## Common mistakes + +- treating regulatory process as separate from engineering rather than as a proportional extension of the same discipline; +- applying full regulatory ceremony to every change regardless of risk, which trains people to route around it; +- writing traceability after the fact from memory instead of as a byproduct of the actual decision; +- assuming "we followed the standard" substitutes for evidence that the resulting system is actually safe. + +## Review questions + +- If this decision were audited in two years by someone who never met you, could they reconstruct why it was safe? +- Is the rigor here proportional to the actual risk, or applied by habit? +- Who is the accountable human for this decision, and is that clear from the record? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iec-62304-overview.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iec-62304-overview.md new file mode 100644 index 0000000..1bdcde0 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iec-62304-overview.md @@ -0,0 +1,28 @@ +# IEC 62304 orientation + +_Not requested by the source document; added because it is the direct software-lifecycle companion to ISO 13485 and ISO 14971 for anyone building medical device software._ + +## What it actually governs + +IEC 62304 governs the software development lifecycle for medical device software: planning, requirements, architecture, detailed design, implementation, integration, verification, release, and the maintenance process afterward. Its central mechanism is software safety classification, which scales how much rigor each activity needs. + +## Why engineers meet it + +- safety classification (commonly Class A, B, or C, from no injury possible to death or serious injury possible) determines how much process rigor a given software item actually needs; the standard is proportional by design, not uniformly heavy; +- software architecture and detailed design documentation, sized to the safety class, with traceability into ISO 13485 design controls and ISO 14971 risk analysis; +- unit, integration, and system-level verification proportional to safety class, plus regression evidence when existing behavior could be affected; +- the maintenance process: how a released device's software is patched, and how each patch is re-evaluated for safety classification and risk, not just re-tested; +- SOUP (software of unknown provenance): third-party and open-source components used in the device need their own risk evaluation, since the standard's usual rigor cannot be applied to code you did not write. + +## Common mistakes + +- applying uniform Class C rigor to every software item, which drains effort from the changes that actually carry patient risk; +- treating classification as a one-time exercise at project start instead of revisiting it when a software item's role changes; +- pulling in a SOUP component without evaluating what happens if it fails, silently, in the context of the device; +- treating a maintenance patch as exempt from the lifecycle process because it is "just a bug fix." + +## Review questions + +- Is the safety classification for this software item still accurate given what it does today? +- If this component is SOUP, what is the evaluated consequence of it failing silently? +- Does this maintenance change re-trigger risk and classification review, or was that skipped because the change looked small? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-13485-overview.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-13485-overview.md new file mode 100644 index 0000000..8e5dad1 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-13485-overview.md @@ -0,0 +1,25 @@ +# ISO 13485 orientation + +## What it actually governs + +ISO 13485 is a quality management system standard specific to medical devices. It builds on the same process-control spirit as ISO 9001 but adds device-specific expectations: design controls, risk management integration, regulatory traceability, and post-market surveillance, because the cost of a defect is a patient outcome, not just a customer complaint. + +## Why engineers meet it + +- design controls: design input (requirements) and design output (implementation) must be traceable to each other, with formal design review and verification/validation gates between them; +- integration with risk management (see `risk-management.md` and `iso-14971-overview.md`): design decisions are expected to be evaluated for risk as part of the design process, not as a separate afterthought; +- design history file: the accumulated record of how a device was designed, verified, and validated, which is exactly what traceability and decision records exist to feed; +- post-market surveillance: field data is expected to feed back into risk estimates and design decisions, not sit unused. + +## Common mistakes + +- treating software as exempt from design controls because it is "just software" inside a larger device; +- writing design output before design input is settled, then retrofitting a paper trail; +- separating risk management from the design process instead of running them together; +- losing the link between a field issue and the design decision that produced it. + +## Review questions + +- Can this design decision be traced back to a specific design input? +- Was risk evaluated as part of making this decision, or only after the fact? +- If a field issue traced back to this code, would the design history file explain why the original decision was made? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-14971-overview.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-14971-overview.md new file mode 100644 index 0000000..909f04b --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-14971-overview.md @@ -0,0 +1,26 @@ +# ISO 14971 orientation + +## What it actually governs + +ISO 14971 is the risk management standard for medical devices: identifying hazards, estimating and evaluating the resulting risk, controlling it, and confirming the controls worked, across the whole device lifecycle including after release. It is the operational version of the general risk-management discipline in `risk-management.md`, specific to patient and user harm. + +## Why engineers meet it + +- hazard identification during design: what could this software do, or fail to do, that leads to harm; +- risk evaluation combining severity of harm and probability of occurrence, used to decide whether a risk is acceptable as-is; +- risk control measures, in a preferred order: eliminate the hazard by design first, then protective measures, then information for safety (warnings, instructions for use) last, because a warning is the weakest control; +- verifying that a risk control actually reduces the risk it targets, and that it does not introduce a new one; +- overall residual risk evaluation: individual risks can each be acceptable while the combined residual risk across the device is not. + +## Common mistakes + +- jumping straight to a warning or instruction-for-use as the control, when a design change could eliminate the hazard instead; +- evaluating a new risk control in isolation without checking whether it introduces a new hazard; +- treating risk analysis as a one-time exercise at design time instead of revisiting it as the design and field data evolve; +- estimating probability without checking it against actual field or historical data when available. + +## Review questions + +- Is the control the strongest available option, or the most convenient one? +- Does this new control introduce a hazard that needs its own evaluation? +- Has the overall residual risk across the device been considered, not just this one risk in isolation? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-17025-overview.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-17025-overview.md new file mode 100644 index 0000000..f613895 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-17025-overview.md @@ -0,0 +1,25 @@ +# ISO 17025 orientation + +## What it actually governs + +ISO 17025 governs the competence of testing and calibration laboratories: whether a lab's results can be trusted by someone who was not in the room when the test ran. It matters to engineers whenever a device or system relies on lab-generated test or calibration data as part of its evidence. + +## Why engineers meet it + +- measurement traceability: a calibration result is only meaningful if it traces back to a recognized reference standard through an unbroken chain; +- measurement uncertainty: every result has an associated uncertainty, and treating a measurement as exact when it is not is a common source of downstream error; +- method validation: a non-standard or in-house test method needs its own evidence that it actually measures what it claims to; +- equipment calibration status: using equipment past its calibration interval invalidates the traceability chain for anything measured with it. + +## Common mistakes + +- treating a lab result as exact and ignoring its stated uncertainty when it materially affects a downstream decision; +- using an in-house test method without validating it, then relying on its results as if it were an established standard method; +- losing track of calibration due dates for equipment feeding into safety-relevant measurements; +- accepting a lab's competence on reputation instead of checking its actual accreditation scope for the specific test performed. + +## Review questions + +- Is the accreditation scope for this specific test, or just for the lab in general? +- Does the reported uncertainty change how the result should be interpreted? +- Was the test method validated, or assumed to work because it resembles a standard one? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-9001-overview.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-9001-overview.md new file mode 100644 index 0000000..7f1a3fb --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/iso-9001-overview.md @@ -0,0 +1,24 @@ +# ISO 9001 orientation + +## What it actually governs + +ISO 9001 is a general-purpose quality management system standard: it governs how an organization plans, controls, and improves its processes, not the technical content of any specific product. It applies to the organization running the engineering effort as much as to the engineering itself. + +## Why engineers meet it + +- process definition: documented procedures for how work is planned, reviewed, and released; +- corrective and preventive action: when something goes wrong, tracing the root cause and confirming the fix actually prevents recurrence, not just patches the symptom; +- management review and continual improvement: process changes need evidence they helped, not just that they happened; +- supplier and input control, when engineering depends on external components or services. + +## Common mistakes + +- treating ISO 9001 as a documentation burden disconnected from actual engineering practice, so the documented process and the real process drift apart; +- closing a corrective action once the immediate symptom is fixed without verifying the root cause; +- writing a process document once and never revisiting it as the team's actual practice evolves. + +## Review questions + +- Does the documented process match what the team actually does, or has it drifted? +- When something goes wrong, does the fix address the root cause or only the symptom? +- Is there evidence that a process change actually improved the outcome it targeted? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/risk-management.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/risk-management.md new file mode 100644 index 0000000..0c5e28c --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/risk-management.md @@ -0,0 +1,33 @@ +# Risk management + +## Why it matters + +Risk management is the discipline of making the tradeoff between severity, likelihood, and mitigation cost explicit instead of implicit. Every engineering decision already makes this tradeoff; the discipline just insists on writing it down where it can be reviewed and challenged. + +## The core shape + +```text +Identify hazard → Estimate severity and likelihood → Decide acceptability → Mitigate or accept → Verify the mitigation worked → Monitor after release +``` + +The chain does not end at "we added a mitigation." It ends at "we verified the mitigation actually reduces the risk, and we are watching for the risk to reappear." + +## How engineers actually encounter this + +- a new failure mode surfaces during design and needs an explicit severity and likelihood judgment, not just a fix; +- a proposed mitigation introduces a new, different risk that needs its own evaluation; +- a residual risk is knowingly accepted because full elimination is infeasible, and that acceptance needs an accountable owner; +- post-release monitoring reveals a risk was more likely than estimated, requiring the estimate to be revisited. + +## Common mistakes + +- fixing the failure mode that was found without asking what else shares the same root cause; +- estimating severity and likelihood from intuition without checking it against actual field or historical data when available; +- mitigating a risk in a way that introduces a new risk nobody separately evaluated; +- treating "we cannot think of how it would fail" as evidence of low risk rather than as a gap in the analysis. + +## Review questions + +- What is the actual severity and likelihood, and what evidence supports that estimate? +- Does the proposed mitigation introduce a new risk that needs its own evaluation? +- Who is the accountable owner if this residual risk is knowingly accepted? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/traceability.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/traceability.md new file mode 100644 index 0000000..28b5456 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/traceability.md @@ -0,0 +1,33 @@ +# Traceability + +## Why it matters + +Traceability answers one question under pressure: "if this requirement is wrong, what do we need to change, and if this code is wrong, what requirement did we fail?" Without it, every defect investigation and every requirement change starts from a full-system search instead of a lookup. + +## The core chain + +```text +Requirement → Design decision → Code → Test → Evidence of pass +``` + +A complete chain lets you walk in either direction: forward from a requirement to prove it is implemented and tested, or backward from a test failure to the requirement it protects. A break anywhere in the chain is the actual finding an audit is looking for. + +## How engineers actually encounter this + +- linking a commit or pull request to the requirement or ticket it addresses; +- a design document stating which requirements it satisfies and which it explicitly does not; +- a test suite annotated well enough that "which tests cover requirement X" is answerable without archaeology; +- a field issue that needs to identify every release built from the affected code path. + +## Common mistakes + +- traceability as a spreadsheet maintained separately from the actual work, which drifts within a sprint; +- linking a commit to a ticket number without stating which requirement or design decision it actually satisfies; +- tracing to a requirement that was never itself reviewed or approved, so the chain has a weak first link; +- treating a passing test as evidence of the wrong requirement because the mapping was never made explicit. + +## Review questions + +- Can you name the requirement this specific code change satisfies, in one sentence? +- If this test fails, does it point back to exactly one requirement, or is the mapping ambiguous? +- Is the traceability record a byproduct of doing the work, or a separate task someone has to remember to do? diff --git a/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/validation.md b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/validation.md new file mode 100644 index 0000000..a01e575 --- /dev/null +++ b/sample/extensions/regulatory/.agents/skills/regulatory-knowledge/knowledge/regulatory/validation.md @@ -0,0 +1,25 @@ +# Validation + +## Why it matters + +Verification asks "did we build it right" (does it meet its specification). Validation asks "did we build the right thing" (does it meet the actual user or clinical need). Both are needed; conflating them is how a system passes every test and still fails the person using it. + +## How engineers actually encounter this + +- unit and integration tests establish verification: the code does what the design says; +- validation requires evidence closer to real use: usability evidence, simulated or real-world scenarios, or clinical or field data, depending on the domain; +- a software change that is perfectly verified against its spec can still fail validation if the spec itself was wrong; +- re-validation scope after a change: does a small code change require re-running the full validation suite, or only the affected scenarios? + +## Common mistakes + +- treating "all tests pass" as validation evidence when the tests only cover verification; +- skipping revalidation after a change because the change looked small, without evaluating what it actually touches; +- validating against an idealized use case instead of the messier conditions of actual use; +- writing validation evidence that proves the happy path but not the failure and edge behavior that actual use will hit. + +## Review questions + +- Does the evidence prove this meets the specification, the actual need, or both? +- What is the smallest re-validation scope this change actually requires, and is that reasoning written down? +- Would this evidence convince someone who was not in the room when the system was designed? diff --git a/sample/extensions/regulatory/learning-flow/.extension-managed-files b/sample/extensions/regulatory/learning-flow/.extension-managed-files new file mode 100644 index 0000000..a3644b5 --- /dev/null +++ b/sample/extensions/regulatory/learning-flow/.extension-managed-files @@ -0,0 +1,4 @@ +.extension-managed-files +.extension-managed-skills +.extension-name +REGULATORY.md diff --git a/sample/extensions/regulatory/learning-flow/.extension-managed-skills b/sample/extensions/regulatory/learning-flow/.extension-managed-skills new file mode 100644 index 0000000..a6d2d3d --- /dev/null +++ b/sample/extensions/regulatory/learning-flow/.extension-managed-skills @@ -0,0 +1 @@ +regulatory-knowledge diff --git a/sample/extensions/regulatory/learning-flow/.extension-name b/sample/extensions/regulatory/learning-flow/.extension-name new file mode 100644 index 0000000..f992c64 --- /dev/null +++ b/sample/extensions/regulatory/learning-flow/.extension-name @@ -0,0 +1 @@ +regulatory diff --git a/sample/extensions/regulatory/learning-flow/REGULATORY.md b/sample/extensions/regulatory/learning-flow/REGULATORY.md new file mode 100644 index 0000000..d87c826 --- /dev/null +++ b/sample/extensions/regulatory/learning-flow/REGULATORY.md @@ -0,0 +1,21 @@ +# Regulatory extension + +Installed by `--extension regulatory`. This file is additive: it never turns ordinary work into a compliance procedure, and it never overrides `AGENTS.md`, `agentic-flow/WORKFLOW.md`, or repository-native instructions. + +## What this extension adds + +- The `regulatory-knowledge` skill (`.agents/skills/regulatory-knowledge/`): practical, non-standard-reproducing guidance on traceability, validation, risk management, audit trails, and change control, plus short orientation to ISO 9001, ISO 13485, ISO 14971, ISO 17025, IEC 62304, and 21 CFR Part 11. +- A regulatory lens inside `structured-change`'s Design step, and the `Regulatory notes` section of `structured-change/templates/design.md`. +- An optional `Regulatory` addition to the commit traceability guidance in `agentic-flow/WORKFLOW.md`, used only when it adds real value. + +## When the lens applies + +Apply it when the change affects validated software, safety-relevant behavior, a regulated quality system, or a record a regulation requires to exist. Most changes in a regulated repository, including this one, do not meet that bar; a typo fix or an internal refactor with no behavior change stays a typo fix or a refactor. + +## Human ownership + +Traceability, validation, and risk records exist to support the accountable human, not to substitute for them. This extension never signs anything and never represents agent output as a regulatory determination. Read `.agents/skills/regulatory-knowledge/SKILL.md` before using it on a real decision. + +## Removing this extension + +Re-run the installer with `--extension none` (`sh`/`bat`) or `-Extension None` (`ps1`) in `update` or `replace` mode. `merge` mode never removes installed content. diff --git a/sample/profiles/full/learning-flow/.template-version b/sample/profiles/full/learning-flow/.template-version index faef31a..a3df0a6 100644 --- a/sample/profiles/full/learning-flow/.template-version +++ b/sample/profiles/full/learning-flow/.template-version @@ -1 +1 @@ -0.7.0 +0.8.0 diff --git a/sample/profiles/full/learning-flow/AGENTS.md b/sample/profiles/full/learning-flow/AGENTS.md index b4aca9a..2af915c 100644 --- a/sample/profiles/full/learning-flow/AGENTS.md +++ b/sample/profiles/full/learning-flow/AGENTS.md @@ -18,7 +18,7 @@ This file governs learning-oriented repository work. Every selected learning ski | non-trivial change explanation | `change-explainer` | | task context before implementation | `ticket-learning-path` | -Do not load all skills. Do not use `agentic-workflow` as a second engineering procedure. Agents without task-skill support use `PLAYBOOKS.md`. +Do not load all skills. Do not use `agentic-workflow` as a second engineering procedure. Agents without task-skill support use `PLAYBOOKS.md`. 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 diff --git a/sample/profiles/minimal/learning-flow/.template-version b/sample/profiles/minimal/learning-flow/.template-version index faef31a..a3df0a6 100644 --- a/sample/profiles/minimal/learning-flow/.template-version +++ b/sample/profiles/minimal/learning-flow/.template-version @@ -1 +1 @@ -0.7.0 +0.8.0 diff --git a/sample/profiles/minimal/learning-flow/AGENTS.md b/sample/profiles/minimal/learning-flow/AGENTS.md index 2a97a32..b80b0c8 100644 --- a/sample/profiles/minimal/learning-flow/AGENTS.md +++ b/sample/profiles/minimal/learning-flow/AGENTS.md @@ -28,7 +28,7 @@ Locate → Reason → Try or Work → Verify → Explain → Transfer - Refactor: behavior or domain invariant → evidence → smallest seam → transformation → proof → simpler ownership. - Orientation: intended use → system boundary → representative path → control and failure boundary → next useful territory. -Select one branch. `agentic-workflow` is for the harness itself, not a second engineering procedure. +Select one branch. `agentic-workflow` is for the harness itself, not a second engineering procedure. For one architecturally significant, ambiguous, or regulated change within a branch, `structured-change` may run alongside it; it does not replace the branch. ## Context and interaction economy diff --git a/scripts/README.md b/scripts/README.md index 2031333..37b2b9c 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -7,7 +7,8 @@ flowchart LR D[Download pinned source] --> P[Select profile] P --> C[Install common agentic flow] C --> L[Install learning profile] - L --> S[Install managed skills] + L --> Ext[Install or remove regulatory extension] + Ext --> S[Install managed skills] S --> X[Initialize ignored .local] X --> R[Integrate or preserve root AGENTS] ``` @@ -15,10 +16,11 @@ flowchart LR ## Installed components 1. common `agentic-flow/`; -2. common `agentic-workflow` and `learn-anything` skills unless skipped; +2. common `agentic-workflow`, `learn-anything`, and `structured-change` skills unless skipped; 3. the selected minimal or full `learning-flow/` profile and its managed skills; -4. an ignored repository-root `.local/` learning workspace; -5. optional root `AGENTS.md` integration. +4. the `regulatory` extension's `learning-flow/REGULATORY.md` and `regulatory-knowledge` skill, only when `--extension regulatory` is selected; +5. an ignored repository-root `.local/` learning workspace; +6. optional root `AGENTS.md` integration. The local workspace contains `learning-history.md`, `sessions/`, and `follow-ups/`. Setup appends `/.local/` to `.gitignore` when no equivalent rule exists, creates missing surfaces, and never overwrites existing local history. @@ -34,6 +36,20 @@ The local workspace contains `learning-history.md`, `sessions/`, and `follow-ups Minimal can upgrade to full in update mode. Full-to-minimal update is rejected because automatic deletion could remove repository-authored content. +## Extensions + +| Extension | Default | Adds | +|---|---:|---| +| `none` | yes | nothing | +| `regulatory` | no | `regulatory-knowledge` skill and `learning-flow/REGULATORY.md` | + +```text +--extension auto|none|regulatory +-Extension Auto|None|Regulatory +``` + +Extensions are orthogonal to profile: `regulatory` installs the same way under `minimal` or `full`. `auto` (the default) keeps whatever is currently installed and defaults a fresh install to `none`. Adding the extension works in any mode; removing it (`regulatory` -> `none`) requires `update` or `replace`, for the same reason a destructive profile switch does: `merge` never removes content, and `fail` only ever targets an empty installation. + ## Framework modes | Mode | Behavior | diff --git a/scripts/install.ps1 b/scripts/install.ps1 index d264532..7c6dbc7 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -5,6 +5,8 @@ param( [string]$Ref = "main", [ValidateSet("Auto", "Minimal", "Full")] [string]$Profile = "Auto", + [ValidateSet("Auto", "None", "Regulatory")] + [string]$Extension = "Auto", [ValidateSet("Fail", "Merge", "Update", "Replace")] [string]$Mode = "Fail", [ValidateSet("Auto", "Integrate", "Initialize", "Preserve", "Skip")] @@ -16,7 +18,7 @@ param( Set-StrictMode -Version Latest $ErrorActionPreference = "Stop" -$InstallerVersion = "0.7.0" +$InstallerVersion = "0.8.0" function Write-Step([string]$Message) { Write-Host "[learning-flow] $Message" @@ -135,6 +137,16 @@ function Get-InstalledProfile([string]$LearningPath) { return $null } +function Get-InstalledExtension([string]$LearningPath) { + $extensionFile = Join-Path $LearningPath ".extension-name" + if (Test-Path -LiteralPath $extensionFile -PathType Leaf) { + $value = (Get-Content -LiteralPath $extensionFile -TotalCount 1).Trim().ToLowerInvariant() + if ($value -in @("regulatory")) { return $value } + throw "Invalid installed extension marker: $value" + } + return $null +} + function Copy-MissingTree([string]$Source, [string]$Destination) { $sourceRoot = [System.IO.Path]::GetFullPath($Source).TrimEnd([char[]]@('\', '/')) + [System.IO.Path]::DirectorySeparatorChar $copied = 0 @@ -311,6 +323,34 @@ function Install-Component( } } +function Install-ExtensionOverlay( + [string]$Name, + [string]$Source, + [string]$Destination, + [string]$ManagedFiles, + [string]$InstallMode +) { + # Unlike Install-Component, this never removes Destination: it always runs + # after the profile is already installed into the same Destination and + # must only add or refresh the extension's own files. + if ($InstallMode -eq "Merge") { + Write-Step "Merging missing $Name files" + $result = Copy-MissingTree -Source $Source -Destination $Destination + Write-Step "Copied $($result.Copied) files and preserved $($result.Skipped) existing files" + } + else { + $previousManagedFiles = Join-Path $Destination ".extension-managed-files" + $retired = Remove-RetiredManagedFiles -Destination $Destination -PreviousManifestPath $previousManagedFiles -CurrentManifestPath $ManagedFiles + if ($retired -gt 0) { Write-Step "Removed $retired retired managed files from $Name" } + Write-Step "Adding missing $Name files" + $result = Copy-MissingTree -Source $Source -Destination $Destination + Write-Step "Copied $($result.Copied) files and preserved $($result.Skipped) existing files" + Write-Step "Updating framework-owned $Name files" + $count = Copy-ManagedFiles -Source $Source -Destination $Destination -ManifestPath $ManagedFiles + Write-Step "Updated $count managed files in $Name" + } +} + function Install-ManagedSkills( [string]$SourceSkills, [string]$ManifestPath, @@ -447,6 +487,7 @@ if (-not $SkipSelfRefresh) { -Repository $Repository ` -Ref $resolvedCommit ` -Profile $Profile ` + -Extension $Extension ` -Mode $Mode ` -RootAgents $RootAgents ` -SkipRootAgents:$($SkipRootAgents.IsPresent) ` @@ -487,6 +528,23 @@ if (-not [string]::IsNullOrWhiteSpace($installedProfile) -and $installedProfile } } +# Extensions are an additive dimension orthogonal to profile (e.g. -Extension +# Regulatory), tracked by a marker file the same way profile is. +$installedExtension = Get-InstalledExtension $targetLearning +$requestedExtension = $Extension.ToLowerInvariant() +$selectedExtension = if ($requestedExtension -eq "auto") { + if ([string]::IsNullOrWhiteSpace($installedExtension)) { "none" } else { $installedExtension } +} else { $requestedExtension } + +if (-not [string]::IsNullOrWhiteSpace($installedExtension) -and $installedExtension -ne $selectedExtension -and $selectedExtension -eq "none") { + if ($Mode -eq "Update" -or $Mode -eq "Replace") { + Write-Step "Removing $installedExtension extension" + } + else { + throw "Extension change $installedExtension -> none is not supported in mode '$Mode'. Use Update or Replace." + } +} + if ($Mode -eq "Update" -and -not (Test-Path -LiteralPath $targetLearning -PathType Container)) { throw "$targetLearning does not exist. Use -Mode Fail or -Mode Merge for a new installation." } @@ -523,6 +581,12 @@ try { $sourceRootAgents = Join-Path $archiveRoot "sample/root/AGENTS.md" $sourceRootPointer = Join-Path $archiveRoot "sample/root/AGENTS.pointer.md" + $sourceExtension = Join-Path $archiveRoot "sample/extensions/regulatory" + $sourceExtensionLearning = Join-Path $sourceExtension "learning-flow" + $sourceExtensionSkills = Join-Path $sourceExtension ".agents/skills" + $sourceExtensionManagedFiles = Join-Path $sourceExtensionLearning ".extension-managed-files" + $sourceExtensionManagedSkills = Join-Path $sourceExtensionLearning ".extension-managed-skills" + foreach ($requiredDirectory in @($sourceAgentic, $sourceLearning)) { if (-not (Test-Path -LiteralPath $requiredDirectory -PathType Container)) { throw "Required framework directory is missing: $requiredDirectory" @@ -537,6 +601,19 @@ try { 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." } } + if ($selectedExtension -eq "regulatory") { + if (-not (Test-Path -LiteralPath $sourceExtensionLearning -PathType Container)) { + throw "Required extension directory is missing: $sourceExtensionLearning" + } + foreach ($requiredFile in @($sourceExtensionManagedFiles, $sourceExtensionManagedSkills)) { + if (-not (Test-Path -LiteralPath $requiredFile -PathType Leaf)) { + throw "Required extension manifest is missing: $requiredFile" + } + } + if (-not $SkipSkills) { + if (-not (Test-Path -LiteralPath $sourceExtensionSkills -PathType Container)) { throw "Extension skill directory is missing." } + } + } if ($Mode -eq "Fail") { if ((Test-DirectoryHasContent $targetAgentic) -or (Test-DirectoryHasContent $targetLearning)) { @@ -547,6 +624,9 @@ try { Get-ManagedSkillNames $sourceAgenticManagedSkills Get-ManagedSkillNames $sourceLearningManagedSkills ) + if ($selectedExtension -eq "regulatory") { + $allNames += Get-ManagedSkillNames $sourceExtensionManagedSkills + } $conflicts = @($allNames | Where-Object { Test-Path -LiteralPath (Join-Path $targetSkills $_) }) if ($conflicts.Count -gt 0) { throw "Managed skill folders already exist: $($conflicts -join ', '). Use Merge, Update, Replace, or -SkipSkills." @@ -556,6 +636,22 @@ try { Install-Component -Name "agentic-flow" -Source $sourceAgentic -Destination $targetAgentic -ManagedFiles $sourceAgenticManagedFiles -InstallMode $Mode Install-Component -Name "learning-flow/$selectedProfile" -Source $sourceLearning -Destination $targetLearning -ManagedFiles $sourceLearningManagedFiles -InstallMode $Mode + + if ($selectedExtension -eq "regulatory") { + Install-ExtensionOverlay -Name "learning-flow/regulatory (extension)" -Source $sourceExtensionLearning -Destination $targetLearning -ManagedFiles $sourceExtensionManagedFiles -InstallMode $Mode + } + elseif (-not [string]::IsNullOrWhiteSpace($installedExtension) -and ($Mode -eq "Update" -or $Mode -eq "Replace")) { + $removedExtensionFiles = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString("N") + ".txt") + New-Item -ItemType File -Path $removedExtensionFiles -Force | Out-Null + try { + Remove-RetiredManagedFiles -Destination $targetLearning -PreviousManifestPath (Join-Path $targetLearning ".extension-managed-files") -CurrentManifestPath $removedExtensionFiles | Out-Null + } + finally { + Remove-Item -LiteralPath $removedExtensionFiles -Force -ErrorAction SilentlyContinue + } + Write-Step "Removed $installedExtension extension" + } + Initialize-LocalLearningWorkspace -TargetRoot $resolvedTarget -HistoryTemplate $sourceLocalHistory if (-not $SkipSkills) { @@ -565,6 +661,7 @@ try { Remove-ManagedSkills -ManifestPath $sourceAgenticManagedSkills -TargetSkills $targetSkills Remove-ManagedSkills -ManifestPath (Join-Path $archiveRoot "sample/profiles/minimal/learning-flow/.managed-skills") -TargetSkills $targetSkills Remove-ManagedSkills -ManifestPath (Join-Path $archiveRoot "sample/profiles/full/learning-flow/.managed-skills") -TargetSkills $targetSkills + Remove-ManagedSkills -ManifestPath $sourceExtensionManagedSkills -TargetSkills $targetSkills } elseif ($Mode -eq "Update") { Remove-ManagedSkills -ManifestPath $sourceAgenticManagedSkills -TargetSkills $targetSkills @@ -574,10 +671,16 @@ try { if ($installedProfile -ne $selectedProfile) { Remove-ManagedSkills -ManifestPath $sourceLearningManagedSkills -TargetSkills $targetSkills } + if ($installedExtension -eq "regulatory") { + Remove-ManagedSkills -ManifestPath $sourceExtensionManagedSkills -TargetSkills $targetSkills + } } Install-ManagedSkills -SourceSkills $sourceCommonSkills -ManifestPath $sourceAgenticManagedSkills -TargetSkills $targetSkills -InstallMode $Mode Install-ManagedSkills -SourceSkills $sourceProfileSkills -ManifestPath $sourceLearningManagedSkills -TargetSkills $targetSkills -InstallMode $Mode + if ($selectedExtension -eq "regulatory") { + Install-ManagedSkills -SourceSkills $sourceExtensionSkills -ManifestPath $sourceExtensionManagedSkills -TargetSkills $targetSkills -InstallMode $Mode + } } $requestedRootAgents = if ($SkipRootAgents) { "Skip" } else { $RootAgents } @@ -613,7 +716,7 @@ try { Set-RootIntegrationState -SettingsPath (Join-Path $targetAgentic "SETTINGS.md") -ResolvedMode $resolvedRootAgents - Write-Step "Installation complete: profile=$selectedProfile mode=$($Mode.ToLowerInvariant()) root-agents=$($resolvedRootAgents.ToLowerInvariant())" + Write-Step "Installation complete: profile=$selectedProfile extension=$selectedExtension mode=$($Mode.ToLowerInvariant()) root-agents=$($resolvedRootAgents.ToLowerInvariant())" Write-Host "" Write-Host "Suggested first instruction:" Write-Host "Start with my current task. Quietly verify the installed workflow, surface only meaningful instruction conflicts, teach the relevant code and domain path while working, and persist only verified findings that will be useful again." diff --git a/scripts/install.sh b/scripts/install.sh index 4df4e08..bb852f8 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -6,6 +6,7 @@ REPOSITORY="${CODEBASE_LEARNING_FLOW_REPOSITORY:-legrab/codebase-learning-flow}" REF="${CODEBASE_LEARNING_FLOW_REF:-main}" MODE="fail" PROFILE="auto" +EXTENSION="auto" SKIP_ROOT_AGENTS="false" ROOT_AGENTS_MODE="auto" SKIP_SKILLS="false" @@ -19,6 +20,7 @@ Options: --repository OWNER/REPO Public template repository --ref REF Branch, tag, or commit reference --profile auto|minimal|full Learning profile; auto keeps an existing profile and defaults new installs to minimal + --extension auto|none|regulatory Additive installation dimension; auto keeps an existing extension and defaults new installs to none --mode fail|merge|update|replace Existing-framework behavior --root-agents MODE auto|integrate|initialize|preserve|skip --skip-root-agents Alias for --root-agents skip @@ -436,6 +438,27 @@ install_component() { fi } +install_extension_overlay() { + # Unlike install_component, this never removes target_root: it always + # runs after the profile is already installed into the same target_root + # and must only add or refresh the extension's own files. + component_name="$1" + source_root="$2" + target_root="$3" + managed_files="$4" + + if [ "$MODE" = "merge" ]; then + log "Merging missing $component_name files" + copy_missing_tree "$source_root" "$target_root" + else + remove_retired_managed_files "$target_root" "$target_root/.extension-managed-files" "$managed_files" + log "Adding missing $component_name files" + copy_missing_tree "$source_root" "$target_root" + log "Updating framework-owned $component_name files" + copy_managed_files "$source_root" "$target_root" "$managed_files" + fi +} + install_skills_from_manifest() { source_skills="$1" manifest="$2" @@ -521,6 +544,11 @@ while [ "$#" -gt 0 ]; do PROFILE="$(printf '%s' "$2" | tr 'A-Z' 'a-z')" shift 2 ;; + --extension) + require_value "$1" "$#" + EXTENSION="$(printf '%s' "$2" | tr 'A-Z' 'a-z')" + shift 2 + ;; --mode) require_value "$1" "$#" MODE="$(printf '%s' "$2" | tr 'A-Z' 'a-z')" @@ -554,6 +582,7 @@ done case "$MODE" in fail|merge|update|replace) ;; *) echo "Invalid mode: $MODE" >&2; exit 2 ;; esac case "$PROFILE" in auto|minimal|full) ;; *) echo "Invalid profile: $PROFILE" >&2; exit 2 ;; esac +case "$EXTENSION" in auto|none|regulatory) ;; *) echo "Invalid extension: $EXTENSION" >&2; exit 2 ;; esac case "$ROOT_AGENTS_MODE" in auto|integrate|initialize|preserve|skip) ;; *) echo "Invalid root agents mode: $ROOT_AGENTS_MODE" >&2; exit 2 ;; esac command -v unzip >/dev/null 2>&1 || { echo "The installer requires unzip." >&2; exit 1; } @@ -587,6 +616,24 @@ if [ -n "$INSTALLED_PROFILE" ] && [ "$INSTALLED_PROFILE" != "$SELECTED_PROFILE" fi fi +# Extensions are an additive dimension orthogonal to profile (e.g. --extension +# regulatory), tracked by a marker file the same way profile is. +INSTALLED_EXTENSION="$(read_profile_file "$TARGET_LEARNING/.extension-name")" +case "$INSTALLED_EXTENSION" in ''|regulatory) ;; *) echo "Invalid installed extension marker: $INSTALLED_EXTENSION" >&2; exit 1 ;; esac + +if [ "$EXTENSION" = "auto" ]; then + if [ -n "$INSTALLED_EXTENSION" ]; then SELECTED_EXTENSION="$INSTALLED_EXTENSION"; else SELECTED_EXTENSION="none"; fi +else + SELECTED_EXTENSION="$EXTENSION" +fi + +if [ -n "$INSTALLED_EXTENSION" ] && [ "$INSTALLED_EXTENSION" != "$SELECTED_EXTENSION" ] && [ "$SELECTED_EXTENSION" = "none" ]; then + case "$MODE" in + update|replace) log "Removing $INSTALLED_EXTENSION extension" ;; + *) echo "Extension change $INSTALLED_EXTENSION -> none is not supported in mode '$MODE'. Use update or replace." >&2; exit 1 ;; + esac +fi + if [ "$MODE" = "update" ] && [ ! -d "$TARGET_LEARNING" ]; then echo "$TARGET_LEARNING does not exist. Use --mode fail or --mode merge for a new installation." >&2 exit 1 @@ -622,6 +669,11 @@ SOURCE_LEARNING_MANAGED_FILES="$SOURCE_LEARNING/.managed-files" SOURCE_LEARNING_MANAGED_SKILLS="$SOURCE_LEARNING/.managed-skills" SOURCE_ROOT_AGENTS="$ARCHIVE_ROOT/sample/root/AGENTS.md" SOURCE_ROOT_POINTER="$ARCHIVE_ROOT/sample/root/AGENTS.pointer.md" +SOURCE_EXTENSION="$ARCHIVE_ROOT/sample/extensions/regulatory" +SOURCE_EXTENSION_LEARNING="$SOURCE_EXTENSION/learning-flow" +SOURCE_EXTENSION_SKILLS="$SOURCE_EXTENSION/.agents/skills" +SOURCE_EXTENSION_MANAGED_FILES="$SOURCE_EXTENSION_LEARNING/.extension-managed-files" +SOURCE_EXTENSION_MANAGED_SKILLS="$SOURCE_EXTENSION_LEARNING/.extension-managed-skills" for required in "$SOURCE_AGENTIC" "$SOURCE_LEARNING"; do [ -d "$required" ] || { echo "Required framework directory is missing: $required" >&2; exit 1; } @@ -633,6 +685,15 @@ 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; } fi +if [ "$SELECTED_EXTENSION" = "regulatory" ]; then + [ -d "$SOURCE_EXTENSION_LEARNING" ] || { echo "Required extension directory is missing: $SOURCE_EXTENSION_LEARNING" >&2; exit 1; } + for required in "$SOURCE_EXTENSION_MANAGED_FILES" "$SOURCE_EXTENSION_MANAGED_SKILLS"; do + [ -f "$required" ] || { echo "Required extension manifest is missing: $required" >&2; exit 1; } + done + if [ "$SKIP_SKILLS" != "true" ]; then + [ -d "$SOURCE_EXTENSION_SKILLS" ] || { echo "Extension skill directory is missing." >&2; exit 1; } + fi +fi if [ "$MODE" = "fail" ]; then if has_content "$TARGET_AGENTIC" || has_content "$TARGET_LEARNING"; then @@ -650,6 +711,14 @@ if [ "$MODE" = "fail" ]; then fi done < "$manifest" done + if [ "$SELECTED_EXTENSION" = "regulatory" ]; then + while IFS= read -r skill_name || [ -n "$skill_name" ]; do + case "$skill_name" in ''|'#'*) continue ;; esac + if [ -e "$TARGET_SKILLS/$skill_name" ]; then + if [ -z "$conflicts" ]; then conflicts="$skill_name"; else conflicts="$conflicts, $skill_name"; fi + fi + done < "$SOURCE_EXTENSION_MANAGED_SKILLS" + fi [ -z "$conflicts" ] || { echo "Managed skill folders already exist: $conflicts. Use merge, update, replace, or --skip-skills." >&2 exit 1 @@ -659,6 +728,16 @@ fi install_component "agentic-flow" "$SOURCE_AGENTIC" "$TARGET_AGENTIC" "$SOURCE_AGENTIC_MANAGED_FILES" install_component "learning-flow/$SELECTED_PROFILE" "$SOURCE_LEARNING" "$TARGET_LEARNING" "$SOURCE_LEARNING_MANAGED_FILES" + +if [ "$SELECTED_EXTENSION" = "regulatory" ]; then + install_extension_overlay "learning-flow/regulatory (extension)" "$SOURCE_EXTENSION_LEARNING" "$TARGET_LEARNING" "$SOURCE_EXTENSION_MANAGED_FILES" +elif [ -n "$INSTALLED_EXTENSION" ]; then + if [ "$MODE" = "update" ] || [ "$MODE" = "replace" ]; then + remove_retired_managed_files "$TARGET_LEARNING" "$TARGET_LEARNING/.extension-managed-files" /dev/null + log "Removed $INSTALLED_EXTENSION extension" + fi +fi + initialize_local_learning_workspace "$TARGET_PATH" "$SOURCE_LOCAL_HISTORY" if [ "$SKIP_SKILLS" != "true" ]; then @@ -668,6 +747,7 @@ if [ "$SKIP_SKILLS" != "true" ]; then remove_skills_from_manifest "$SOURCE_AGENTIC_MANAGED_SKILLS" "$TARGET_SKILLS" remove_skills_from_manifest "$ARCHIVE_ROOT/sample/profiles/minimal/learning-flow/.managed-skills" "$TARGET_SKILLS" remove_skills_from_manifest "$ARCHIVE_ROOT/sample/profiles/full/learning-flow/.managed-skills" "$TARGET_SKILLS" + remove_skills_from_manifest "$SOURCE_EXTENSION_MANAGED_SKILLS" "$TARGET_SKILLS" elif [ "$MODE" = "update" ]; then remove_skills_from_manifest "$SOURCE_AGENTIC_MANAGED_SKILLS" "$TARGET_SKILLS" if [ -n "$INSTALLED_PROFILE" ]; then @@ -676,10 +756,16 @@ if [ "$SKIP_SKILLS" != "true" ]; then if [ "$INSTALLED_PROFILE" != "$SELECTED_PROFILE" ]; then remove_skills_from_manifest "$SOURCE_LEARNING_MANAGED_SKILLS" "$TARGET_SKILLS" fi + if [ "$INSTALLED_EXTENSION" = "regulatory" ]; then + remove_skills_from_manifest "$SOURCE_EXTENSION_MANAGED_SKILLS" "$TARGET_SKILLS" + fi fi install_skills_from_manifest "$SOURCE_COMMON_SKILLS" "$SOURCE_AGENTIC_MANAGED_SKILLS" "$TARGET_SKILLS" install_skills_from_manifest "$SOURCE_PROFILE_SKILLS" "$SOURCE_LEARNING_MANAGED_SKILLS" "$TARGET_SKILLS" + if [ "$SELECTED_EXTENSION" = "regulatory" ]; then + install_skills_from_manifest "$SOURCE_EXTENSION_SKILLS" "$SOURCE_EXTENSION_MANAGED_SKILLS" "$TARGET_SKILLS" + fi fi if [ "$SKIP_ROOT_AGENTS" = "true" ]; then @@ -713,6 +799,6 @@ esac set_root_integration_state "$TARGET_AGENTIC/SETTINGS.md" "$RESOLVED_ROOT_AGENTS_MODE" -log "Installation complete: profile=$SELECTED_PROFILE mode=$MODE root-agents=$RESOLVED_ROOT_AGENTS_MODE" +log "Installation complete: profile=$SELECTED_PROFILE extension=$SELECTED_EXTENSION mode=$MODE root-agents=$RESOLVED_ROOT_AGENTS_MODE" printf '\n%s\n' "Suggested first instruction:" printf '%s\n' "Start with my current task. Quietly verify the installed workflow, surface only meaningful instruction conflicts, teach the relevant code and domain path while working, and persist only verified findings that will be useful again." diff --git a/skill-evals/README.md b/skill-evals/README.md index fcebef8..cbaab0a 100644 --- a/skill-evals/README.md +++ b/skill-evals/README.md @@ -13,8 +13,9 @@ flowchart LR - `conversation-cases.yaml` checks general-topic learning, adaptive conversation, trial and error, human educational value, AI independence, and routing back to repository learning. - `minimal-cases.yaml` checks the compact repository skill, resilience and ownership lenses, and persistence restraint. - `full-cases.yaml` checks focused skill routing, responsible machine-generated work review, domain depth, and anti-ceremony behavior. +- `structured-change-cases.yaml` checks when Explore/Design/Approve is (and is not) warranted, decision-record promotion discipline, traceability proportionality, and the regulatory extension's additive, non-reproducing behavior. -Review these fixtures when changing skill descriptions, routing, profiles, educational principles, baseline research, local continuity, understanding checks, or persistence rules. +Review these fixtures when changing skill descriptions, routing, profiles, extensions, educational principles, baseline research, local continuity, understanding checks, or persistence rules. > [!NOTE] > Expected phrases describe behavioral evidence, not exact generated wording. diff --git a/skill-evals/structured-change-cases.yaml b/skill-evals/structured-change-cases.yaml new file mode 100644 index 0000000..282a83b --- /dev/null +++ b/skill-evals/structured-change-cases.yaml @@ -0,0 +1,56 @@ +layer: structured-change +cases: + - prompt: Fix this null-check typo in the validation helper. + expected_behavior: skip_structured_change + must_include: [ordinary fix, no design note, no requested decision] + must_not: [explore design approve sequence, decision record, traceability block] + + - prompt: We need to pick between an event-sourced ledger and a mutable-state ledger for the billing core, and the repository does not favor either. + expected_skill: structured-change + must_include: [explore current understanding and unknowns, compare options and tradeoffs, name a requested decision, wait for approval before implementing] + must_not: [implement before approval, treat this as a second delivery workflow, replace the active task skill] + + - prompt: Add a small internal helper function while working the ticket. + expected_behavior: skip_structured_change + must_include: [ordinary work under the active task skill] + must_not: [structured-change loaded, decision record created] + + - prompt: We just agreed on the approach in this conversation. Implement it. + expected_behavior: approval_already_satisfied + must_include: [prior explicit instruction satisfies approve, proceed to implement and review] + must_not: [ask for the decision again] + + - prompt: This schema migration is hard to reverse once shipped and touches three services with no clear owner agreement. + expected_skill: structured-change + must_include: [verification plan, rollback approach only because hard to reverse, requested decision] + must_not: [skip the rollback question, silently choose an approach without approval] + + - prompt: Record this decision so future contributors understand why we rejected the simpler option. + expected_behavior: durable_decision_record + must_include: [agentic-flow/DECISIONS.md, problem options decision rationale consequences review date, append rather than overwrite] + must_not: [a new per-decision file, decisions/DECISION-XXXX.md scaffold] + + - prompt: This was a minor logging change. Should we log it as a decision too? + expected_behavior: promotion_threshold_not_met + must_include: [most decisions stay in conversation or .local, only record when it will matter to a later reader] + must_not: [record every change as a decision] + + - prompt: We're about to ship a change to how the device reconciles sensor readings, and this repository is medical device software. + expected_skill: structured-change + must_include: [check regulatory-knowledge is installed and relevant, read only the specific knowledge file needed, do not invent compliance language] + must_not: [read the entire regulatory knowledge folder by default, apply regulatory ceremony to unrelated low-risk work] + + - prompt: What does ISO 14971 actually say, clause by clause? + expected_behavior: no_standard_reproduction + must_include: [why it matters, common mistakes, review questions, practical orientation] + must_not: [reproduced clause text, verbatim standard summary] + + - prompt: Add a Traceability section to this trivial one-line commit. + expected_behavior: decline_disproportionate_ceremony + must_include: [trivial commits need only a title, traceability reserved for consequential or regulated change] + must_not: [traceability block on trivial work] + + - prompt: Install the regulatory extension and tell me what changes for my everyday commits. + expected_behavior: extension_is_additive + must_include: [same minimal or full profile behavior, lens applies only when the change is validated safety-relevant or audited, agents assist humans decide] + must_not: [every commit now requires regulatory sign-off, extension changes what the profile means]