diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..bd3406e --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +* text=auto eol=lf + +*.bat text eol=crlf diff --git a/.gitignore b/.gitignore index 6d9eafe..f2b9d3b 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ Desktop.ini *.temp *.bak *.log +/.local/ # Locally generated distribution archives /INITIALIZE_LEARNING_FLOW_*.zip diff --git a/AGENTS.md b/AGENTS.md index b76f206..5b52af6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,12 +2,21 @@ ## Purpose -Maintain a small repository-native harness for safe agentic collaboration and deliberate codebase learning. Preserve the separation between: +Maintain a small harness for safe agentic collaboration, deliberate codebase learning, and conversational learning about general topics. Preserve the separation between: - repository-specific engineering rules; - general collaboration behavior in `agentic-flow/`; - optional learning behavior in `learning-flow/`; -- temporary task state. +- generic conversation behavior in the common `learn-anything` skill; +- private learning and temporary task state under `.local/`. + +## Generic conversational learning + +When the user explicitly wants to learn a non-repository topic, treat this checkout as the host rather than the subject. Stay in the conversation and follow `Locate → Reason → Work → Explain → Recap`: find the learner's question, build a compact system model from the useful parts of purpose, boundary, relationships, change or feedback, evidence, and transfer, use one helpful example or practice step, and close without repeating the answer. + +Do not inspect repository code for this route. For a meaningful learning session, use `.local/` as described in `sample/common/agentic-flow/LOCAL.md`: retain the complete private session and compact cross-session history there, then promote only clearly reusable framework knowledge deliberately. General programming concepts are in scope; questions about this codebase continue to use the repository-learning flow. + +If this source checkout has no `.local/` workspace yet, create `.local/{sessions,follow-ups}` and seed `.local/learning-history.md` from `sample/common/local/learning-history.md`. Never overwrite existing local state. ## Working rules diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bfeb0c..f1b99b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,76 @@ # Changelog +## 0.7.0 + +### Added + +- A common `learn-anything` skill for friendly, adaptive learning conversations about non-repository topics. +- Source-repository instructions and routing checks that keep general learning chat-like and send codebase questions back to repository learning. +- An ignored repository-root `.local/` workspace for complete private learning sessions, compact cross-session history, and generated follow-up material. + +### Changed + +- The shared `Locate → Reason → Work → Explain → Recap` loop can now locate a learner's question as well as repository evidence, while retaining one selective route at a time. +- Both profiles install the generic learning skill without adding private study records to tracked learning surfaces. +- Session closure now saves contributor-specific state locally and promotes only stable, reusable, non-sensitive knowledge into existing shared records. +- Installers initialize `.local/` idempotently, preserve existing history, and ensure the directory is excluded through `.gitignore`. +- Repository and general-topic learning now share a selective system lens covering purpose, boundaries, relationships, change or feedback, evidence, and transfer. +- First-use documentation now leads with installation and a real task, while optional modes and reference inventories use progressive disclosure. +- Always-loaded collaboration and profile instructions now defer low-frequency detail to existing canonical guides, reducing repetition without changing behavior. + +## 0.6.2 + +### Changed + +- Normal managed-template integration no longer requires an agentic setup status in the learning map; only durable custom exceptions or conflicts are recorded. +- Full-profile bootstrap is now an explicitly requested onboarding activity rather than a prerequisite for the first real task. +- Learning reinforcement is folded into the normal handoff, limited to a few useful points, and skipped when it would duplicate delivery evidence. + +### Removed + +- Baseline reporting of transient branch, commit, profile, settings, and ordinary template status. +- Separate quota-shaped recap sections after the normal agentic handoff. + +## 0.6.1 + +### Changed + +- Reference integrations now treat external sources as evidence rather than target architectures. +- Reviews name useful value already covered locally and retain only a small gap-closing delta, including an explicit no-change outcome when appropriate. +- The integration contract preserves the repository's educational core, friendly voice, and low-ceremony defaults instead of importing breadth or rigidity for parity. +- Third-party skills now require a lightweight source, capability, and rule-overlap review; catalogue presence or popularity is not treated as endorsement. +- The standard flow now checks only task-critical runtime, tool, access, and approval readiness before acting, then adapts or reports the exact blocker. +- Project and installed READMEs now clarify that the flow configures a host agent rather than providing a tool runtime, sandbox, retry engine, or durable resumption. + +### Reference reviews + +- Reviewed `VoltAgent/awesome-agent-skills` at an exact revision and retained only the external-skill trust boundary. +- Reviewed `aaif-goose/goose` at an exact revision and retained only a lightweight capability-readiness check. +- Reviewed `RyanAlberts/best-of-Agent-Harnesses` at an exact revision and retained only a product-scope clarification. + +## 0.6.0 + +### Added + +- Task-first onboarding that verifies the installed workflow quietly and surfaces only meaningful conflicts. +- Sparse `Now / Found / Next` progress pulses for substantial work without command narration. +- A compact domain slice connecting actors, outcomes, capabilities, invariants, triggers, effects, ownership, and evidence. +- `fast`, `balanced`, `guided`, and `gated` collaboration presets with optional advanced overrides. + +### Changed + +- Initial learning records one agentic setup status instead of inventorying the framework before useful work. +- Learning routes start from the affected domain outcome or rule before tracing implementation. +- The full profile keeps only its durable core visible; task templates now travel inside their owning skills. +- Root integration exposes three behaviorally distinct choices and records `linked`, `pending`, or `explicit-only` in settings. +- Learning depth and persistence are independently configurable. +- Update mode removes retired framework-owned files while preserving repository-authored content. + +### Removed + +- Pre-created full-profile research, material, contributor, explainer, lab, and general template directories. +- The superseded pre-profile `sample/learning-flow/` tree. + ## 0.5.3 ### Added diff --git a/MANIFEST.txt b/MANIFEST.txt index ef3bdba..adbeeec 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,78 +1,74 @@ -.gitignore 265 -AGENTS.md 1749 -CHANGELOG.md 5566 -docs/DESIGN_NOTES.md 10793 -docs/INITIALIZE_LEARNING_FLOW.md 7638 -docs/README.md 776 -docs/references/REFERENCE_INTEGRATION.md 3485 +.gitattributes 40 +.gitignore 274 +AGENTS.md 3010 +CHANGELOG.md 10259 +docs/DESIGN_NOTES.md 17684 +docs/INITIALIZE_LEARNING_FLOW.md 9396 +docs/README.md 1185 +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_LITT.md 2069 -docs/references/REFERENCE_REVIEW_POCOK.md 2154 +docs/references/REFERENCE_REVIEW_POCOK.md 2155 LICENSE 2213 -README.md 6571 -sample/README.md 1328 -sample/common/.agents/skills/agentic-workflow/SKILL.md 3188 -sample/common/agentic-flow/.managed-files 148 -sample/common/agentic-flow/.managed-skills 17 +README.md 8266 +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 3606 +sample/common/agentic-flow/.managed-files 157 +sample/common/agentic-flow/.managed-skills 32 sample/common/agentic-flow/.template-version 6 -sample/common/agentic-flow/AGENTS.md 4242 -sample/common/agentic-flow/CONFIGURE.md 3032 -sample/common/agentic-flow/LEARN.md 1690 -sample/common/agentic-flow/README.md 914 -sample/common/agentic-flow/REFERENCE_INTEGRATION.md 1683 -sample/common/agentic-flow/ROOT_INTEGRATION.md 3053 -sample/common/agentic-flow/SETTINGS.md 418 -sample/common/agentic-flow/WORKFLOW.md 2283 -sample/profiles/full/.agents/skills/analogous-feature/SKILL.md 1338 -sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md 1269 -sample/profiles/full/.agents/skills/change-explainer/SKILL.md 1254 -sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md 1930 -sample/profiles/full/.agents/skills/repository-orientation/SKILL.md 1443 -sample/profiles/full/.agents/skills/safe-refactor/SKILL.md 1273 -sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md 1431 -sample/profiles/full/learning-flow/.managed-files 555 +sample/common/agentic-flow/AGENTS.md 5205 +sample/common/agentic-flow/CONFIGURE.md 4051 +sample/common/agentic-flow/LEARN.md 1822 +sample/common/agentic-flow/LOCAL.md 3157 +sample/common/agentic-flow/README.md 1237 +sample/common/agentic-flow/REFERENCE_INTEGRATION.md 2183 +sample/common/agentic-flow/ROOT_INTEGRATION.md 2932 +sample/common/agentic-flow/SETTINGS.md 544 +sample/common/agentic-flow/WORKFLOW.md 3309 +sample/common/local/learning-history.md 625 +sample/profiles/full/.agents/skills/analogous-feature/SKILL.md 1389 +sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md 1587 +sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md 428 +sample/profiles/full/.agents/skills/change-explainer/SKILL.md 1482 +sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md 290 +sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md 1875 +sample/profiles/full/.agents/skills/repository-orientation/SKILL.md 1547 +sample/profiles/full/.agents/skills/safe-refactor/SKILL.md 1392 +sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md 1633 +sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md 348 +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 5214 -sample/profiles/full/learning-flow/BOOTSTRAP.md 2178 -sample/profiles/full/learning-flow/MAP.md 1421 -sample/profiles/full/learning-flow/PLAYBOOKS.md 1064 -sample/profiles/full/learning-flow/README.md 2904 +sample/profiles/full/learning-flow/AGENTS.md 5302 +sample/profiles/full/learning-flow/BOOTSTRAP.md 2097 +sample/profiles/full/learning-flow/MAP.md 945 +sample/profiles/full/learning-flow/PLAYBOOKS.md 1157 +sample/profiles/full/learning-flow/README.md 2991 sample/profiles/full/learning-flow/REPOSITORIES.md 439 sample/profiles/full/learning-flow/TAKEAWAYS.md 570 -sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md 1580 -sample/profiles/full/learning-flow/contributors/README.md 558 -sample/profiles/full/learning-flow/explainers/README.md 385 -sample/profiles/full/learning-flow/labs/README.md 373 -sample/profiles/full/learning-flow/materials/README.md 285 -sample/profiles/full/learning-flow/materials/themes/README.md 115 -sample/profiles/full/learning-flow/research/README.md 420 -sample/profiles/full/learning-flow/research/topics/README.md 161 -sample/profiles/full/learning-flow/templates/challenge.md 423 -sample/profiles/full/learning-flow/templates/change-explainer.md 308 -sample/profiles/full/learning-flow/templates/contributor-readme.md 199 -sample/profiles/full/learning-flow/templates/contributor-theme.md 134 -sample/profiles/full/learning-flow/templates/contributor-tracking.md 155 -sample/profiles/full/learning-flow/templates/lab-readme.md 202 -sample/profiles/full/learning-flow/templates/learning-material.md 192 -sample/profiles/full/learning-flow/templates/research-topic.md 197 -sample/profiles/full/learning-flow/templates/ticket-learning-path.md 348 -sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md 2789 +sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md 1627 +sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md 3258 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 3404 -sample/profiles/minimal/learning-flow/MAP.md 1316 -sample/profiles/minimal/learning-flow/README.md 1425 +sample/profiles/minimal/learning-flow/AGENTS.md 3762 +sample/profiles/minimal/learning-flow/MAP.md 811 +sample/profiles/minimal/learning-flow/README.md 1648 sample/profiles/minimal/learning-flow/TAKEAWAYS.md 551 -sample/root/AGENTS.md 1242 +sample/README.md 1600 +sample/root/AGENTS.md 1339 sample/root/AGENTS.pointer.md 296 -scripts/README.md 1742 scripts/install.bat 1434 -scripts/install.ps1 22829 -scripts/install.sh 21235 -skill-evals/README.md 695 -skill-evals/agentic-cases.yaml 3826 -skill-evals/full-cases.yaml 1867 -skill-evals/minimal-cases.yaml 1756 +scripts/install.ps1 29480 +scripts/install.sh 24986 +scripts/README.md 2660 +skill-evals/agentic-cases.yaml 6691 +skill-evals/conversation-cases.yaml 2633 +skill-evals/full-cases.yaml 2977 +skill-evals/minimal-cases.yaml 2377 +skill-evals/README.md 1002 diff --git a/README.md b/README.md index 9ff8476..180c42f 100644 --- a/README.md +++ b/README.md @@ -1,94 +1,111 @@ # Codebase Learning Flow -A repository-native harness for safe agentic collaboration and deliberate codebase learning. +A lightweight repository harness for safe agentic collaboration, deliberate codebase learning, and conversational learning about any subject. -Version 0.5.3 keeps two concerns separate: - -- `agentic-flow/` governs framing, planning, autonomy, validation, records, and handoff; -- `learning-flow/` adds optional orientation, explanation, understanding checks, maps, and durable takeaways. +It configures a host agent; it is not an agent runtime. Tool execution, sandboxing, retries, and durable resumption remain the host's responsibility. ```text Repository instructions ↓ -agentic-flow: Frame → Inspect → Decide → Act → Verify → Handoff - ↓ -One selective task procedure - ↓ -Optional learning-flow: Locate → Reason → Work → Explain → Recap -``` - -The repository's own agentic setup is part of initial learning research. Existing instructions, skills, prompts, plans, and records are mapped; known template files are recognized without wasting context. - -## Profiles - -| Profile | Use | Persistent learning | Skills | -|---|---|---:|---:| -| `minimal` | daily work, short engagements, token-sensitive agents | `MAP.md`, `TAKEAWAYS.md` | 1 | -| `full` | deliberate onboarding, teaching, long-lived ownership | map, takeaways, optional research and learning artifacts | 7 | - -New installations default to `minimal`. Both profiles are task-first and create no curriculum, session, contributor file, quiz, or explainer without a real reason. - -## Communication defaults - -Agents use friendly, concise, summary-first language. Substantial updates say what changed and why it matters in a few descriptive, visually distinct bullets; they avoid dry labels, chronological tool logs, and file-by-file inventories. Commit bodies use compact `Why`, `What`, and `Checks` sections only when those sections add useful context. +Agentic work: Frame → Inspect → Decide → Act → Verify → Handoff + ├─ ordinary repository work + ├─ repository learning: Locate → Reason → Work → Explain → Recap + └─ general learning: Locate → Reason → Work → Explain → Recap -Human-facing Markdown uses collapsible sections for secondary evidence, examples, command matrices, and long inventories, while warnings and required decisions remain visible. - -Full mode may ask one optional A/B/C/D learner-context question when user experience cannot be inferred and materially changes useful depth. - -## Installation +Private continuity in .local/ → deliberate promotion → shared learning records +``` -Run from the repository that should receive the harness. +## Start here -### PowerShell +From the repository that should receive the harness, run one installer: ```powershell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) ``` -### Bash or Zsh - ```sh curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh | sh ``` -### Windows Command Prompt +Then start with the real task: -```bat -powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.bat -OutFile '%TEMP%\install-learning-flow.bat'" && "%TEMP%\install-learning-flow.bat" +```text +Start with my current task. Quietly verify the installed workflow, surface only meaningful +instruction conflicts, and teach the relevant code and domain path while working. ``` -Remote piping executes the referenced revision. Team installations should pin a release tag or commit. +New installations use the compact `minimal` profile. Expect summary-first communication, progress only when something meaningful changes, risk-proportional checks, and no curriculum or session artifact without a real reason. + +Remote piping executes the referenced revision. Pin a release tag or commit for team installation.
-Profiles, modes, and root integration +Windows Command Prompt and local installer commands + +```bat +powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.bat -OutFile '%TEMP%\install-learning-flow.bat'" && "%TEMP%\install-learning-flow.bat" +``` ```powershell ./scripts/install.ps1 -Profile Minimal ./scripts/install.ps1 -Profile Full ./scripts/install.ps1 -Mode Update -./scripts/install.ps1 -RootAgents Integrate -./scripts/install.ps1 -RootAgents Initialize ``` ```sh ./scripts/install.sh --profile minimal ./scripts/install.sh --profile full ./scripts/install.sh --mode update -./scripts/install.sh --root-agents integrate -./scripts/install.sh --root-agents initialize ``` -Modes: +
-- `fail`: stop on existing managed content; -- `merge`: add missing framework files while preserving existing content; -- `update`: refresh framework-owned files and managed skills; -- `replace`: replace framework directories and this framework's managed skills. +## Pick a learning route + +For repository work, use the task prompt above. The agent follows repository instructions first, selects at most one relevant task skill, and teaches through the work instead of running a separate course. -`update` preserves agentic settings, maps, takeaways, research, materials, contributor traces, explainers, labs, and unrelated skills. +For a general subject, use this checkout as the learning host rather than the lesson: + +```text +Use learn-anything to help me understand . Keep it conversational, build a compact +mental model, use one helpful example or practice step, and let my questions steer the depth. +``` + +This route covers history, science, languages, arts, mathematics, and general technical concepts without inspecting repository code. + +## Educational core + +Flow keeps learning connected to a real question or activity. A selective system lens keeps explanations causal rather than encyclopedic: + +```text +Purpose → Boundary → Parts and relationships → Change and feedback → Evidence → Transfer +``` -Root modes are `auto`, `integrate`, `initialize`, `preserve`, and `skip`. Existing root content is never replaced wholesale. +Use only what clarifies the subject. Start with the whole, trace one representative interaction, test the model against evidence or an example, and revise it when the learner's reasoning exposes a gap. This is an adaptive loop, not a worksheet. + +| Profile | Best for | Private learning | Shared learning | Learning skills | +|---|---|---|---|---:| +| `minimal` | daily work and short engagements | `.local/` sessions and history | `MAP.md`, `TAKEAWAYS.md` | 2 | +| `full` | deliberate onboarding and long-lived ownership | `.local/` sessions, history, and follow-ups | map, takeaways, baselines, promoted artifacts | 8 | + +Both profiles are task-first. Full mode adds narrower learning skills and may ask one optional learner-context question when the answer materially changes useful depth. + +## Local learning memory + +> Learn locally first. Promote only reusable knowledge deliberately. + +Fresh installation creates an ignored repository-root `.local/` workspace; this source checkout initializes the same structure lazily when first needed. Meaningful sessions keep complete private state in `.local/sessions/`, compact continuity in `.local/learning-history.md`, and generated revision or quiz material in `.local/follow-ups/`. Later sessions read only relevant history, so they can revisit earlier concepts without starting over. + +Only stable, reusable, non-sensitive knowledge is deliberately promoted into tracked owners such as `learning-flow/MAP.md` or `TAKEAWAYS.md`. An explicit request to preserve something globally triggers that review; uncertain or personal information stays local. + +
+Profiles, update modes, and root integration + +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, repository-authored content, `.local/`, and unrelated skills; +- `replace`: replace framework directories and this framework's managed skills. A minimal installation can upgrade safely: @@ -98,72 +115,93 @@ A minimal installation can upgrade safely: Full-to-minimal update is rejected because automatic deletion could destroy repository-authored content. +Root modes are `auto`, `integrate`, `initialize`, `preserve`, and `skip`: + +```powershell +./scripts/install.ps1 -RootAgents Integrate +``` + +```sh +./scripts/install.sh --root-agents integrate +``` + +Existing root instructions are never replaced wholesale. Interactive setup distinguishes linked, pending-review, and explicit-only outcomes and records the result in settings. +
-## First use +
+Explicit configuration and baseline prompts + +Configuration is optional; `balanced` starts work immediately. Review it only when collaboration behavior is the task: ```text -Use the agentic-workflow skill to inspect this repository's actual agent-facing setup. -Recognize installed template files, map custom instructions and effective precedence, -resolve root integration, and use balanced defaults unless a meaningful preference needs -one compact A/B/C/D choice. +Use agentic-workflow to review this repository's agent-facing setup. Treat managed files as +known, map only custom additions or conflicts, and keep balanced defaults unless I ask otherwise. ``` -Minimal learning: +Minimal baseline: ```text -Use repository-learning for the initial baseline or current task. Keep inspection narrow, -persist only verified reusable map or takeaway content, ask at most one consequential -understanding check, and end with a compact recap. +Use repository-learning for the current task or initial baseline. Keep inspection narrow, +persist only verified reusable findings, and fold useful learning into the normal handoff. ``` -Full learning: +Full baseline: ```text -Use learning-bootstrap for a compact baseline, including the actual agentic setup. Ask -about my experience only if it materially changes useful scaffolding. Do not pre-generate -sessions or learning artifacts. Then use the narrowest primary skill for the task. +Use learning-bootstrap for a compact baseline. Record only durable custom conflicts and do +not pre-generate sessions or learning artifacts. ``` -## Incorporating future references +
+ +
+External reference integration + +Follow [`docs/references/REFERENCE_INTEGRATION.md`](docs/references/REFERENCE_INTEGRATION.md). Treat a repository, article, or ZIP as evidence rather than a target architecture: retain only a small gap-closing delta and record exact provenance in `docs/references/REFERENCE_REVIEW_.md`. -Read [`docs/references/REFERENCE_INTEGRATION.md`](docs/references/REFERENCE_INTEGRATION.md), or give an agent the prompt shown there with a GitHub source or ZIP. Every integration must add a concise `docs/references/REFERENCE_REVIEW_.md` that records exact provenance, retained value, rejected source-specific constraints, and resulting framework changes. +Current reviews: -Current reference reviews: +- [`Awesome Agent Skills`](docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md) +- [`Best of Agent Harnesses`](docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md) +- [`Goose`](docs/references/REFERENCE_REVIEW_GOOSE.md) +- [`Pocok`](docs/references/REFERENCE_REVIEW_POCOK.md) +- [`Litt`](docs/references/REFERENCE_REVIEW_LITT.md) -- [`REFERENCE_REVIEW_POCOK.md`](docs/references/REFERENCE_REVIEW_POCOK.md) -- [`REFERENCE_REVIEW_LITT.md`](docs/references/REFERENCE_REVIEW_LITT.md) +
Installed structure -Common: - ```text -.agents/skills/agentic-workflow/SKILL.md +.local/ +├── learning-history.md +├── sessions/ +└── follow-ups/ +.agents/skills/ +├── agentic-workflow/ +├── learn-anything/ +└── profile-specific learning skills agentic-flow/ ├── AGENTS.md +├── SETTINGS.md ├── WORKFLOW.md ├── CONFIGURE.md -├── ROOT_INTEGRATION.md -├── SETTINGS.md ├── LEARN.md -└── REFERENCE_INTEGRATION.md +└── LOCAL.md +learning-flow/ +├── AGENTS.md +├── MAP.md +└── TAKEAWAYS.md ``` -Minimal adds one `repository-learning` skill and `learning-flow/{AGENTS,MAP,README,TAKEAWAYS}.md`. - -Full adds seven narrow learning skills plus optional research, materials, explainers, labs, and contributor surfaces that remain empty until justified. +The full profile adds repository baselines and seven narrow repository-learning skills. Task-specific templates travel inside their owning skills and are materialized only when justified.
-## Repository documentation +## Documentation and license -- [`docs/README.md`](docs/README.md): maintenance documentation index +- [`docs/README.md`](docs/README.md): maintenance and design documentation - [`CHANGELOG.md`](CHANGELOG.md): revision history -- [`LICENSE`](LICENSE): reuse terms and attribution guidance -- [`scripts/README.md`](scripts/README.md): installer details - -## License - -Software is available under the MIT License. Original documentation, workflow text, templates, and evaluation content are available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which permits reuse and adaptation with attribution. See [`LICENSE`](LICENSE) for scope and a copy-ready credit line. +- [`scripts/README.md`](scripts/README.md): complete installer behavior +- [`LICENSE`](LICENSE): MIT software and CC BY 4.0 documentation/template terms, including a copy-ready attribution diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md index 26b9437..9a5f4b2 100644 --- a/docs/DESIGN_NOTES.md +++ b/docs/DESIGN_NOTES.md @@ -2,7 +2,7 @@ ## Purpose -The harness should keep a developer able to reason about a repository while collaborating with an agent. It should improve delivery, code and architecture understanding, domain reasoning, debugging, and ownership growth without making workflow administration or learning administration the primary activity. +The harness should keep a developer able to reason about a repository while collaborating with an agent, and let any learner use the same lightweight methods for a general subject. It should improve delivery, code and architecture understanding, domain reasoning, debugging, ownership growth, and conversational learning without making workflow administration or learning administration the primary activity. ## v0.5 separation of concerns @@ -34,7 +34,7 @@ The reusable workflow intentionally does not copy Pocok's universal one-step app ## v0.5.1 existing-harness integration -The repository's agentic setup is itself a learning territory. Initial research must explain the effective instruction order, stable policy, workflow settings, task procedures, learning support, and temporary evidence locations. +The repository's agentic setup can be a learning territory when custom instructions or conflicts affect work. Managed template state is recognized cheaply; a full instruction-order explanation belongs to an explicit setup review, not every initial baseline. Managed template files are recognizable through version and profile markers. Agents should not spend context rediscovering their intended structure. They inspect root integration and repository-specific additions, overrides, conflicts, and stale material instead. @@ -67,6 +67,44 @@ Maintenance documentation lives under `docs/`, with external-reference integrati Licensing is split by material type: software remains under MIT, while original documentation, workflow text, templates, and evaluation content use CC BY 4.0 so reuse stays broad but requires attribution. +## v0.6 task-first learning and configuration + +The default entry point is now the user's real task. Template integration is recognized quietly, setup mapping is omitted unless durable custom behavior or conflicts matter, and substantial work uses sparse progress pulses instead of tool narration. + +Repository learning uses one compact domain slice to connect actor and outcome, capability, rule or invariant, trigger and effect, owning boundary, and evidence before tracing code. Full mode keeps only durable core files visible; optional task templates travel inside their owning skills. + +Configuration starts from one named preset—`fast`, `balanced`, `guided`, or `gated`—with advanced overrides available on request. Learning depth and persistence are independent. Root integration uses three distinct choices and persists its result. + +## v0.6.1 conservative reference integration + +External repositories are comparison evidence, not target architectures or maturity benchmarks. A review first names useful value already covered, then retains only the smallest delta that closes a clear weakness. Zero framework changes is a valid result. + +The repository keeps its task-first educational core, friendly voice, minimal/full model, and low-ceremony defaults even when a source is popular or extensive. Reference integrations normally add no more than three behavioral adjustments and do not introduce layers, catalogues, rigid administration, or productivity pressure without a demonstrated local need. + +Third-party skill catalogues are discovery surfaces, not trust boundaries. The framework keeps its small repository-owned skill set and adds only a source-and-capability review before adopting external executable instructions; publisher identity and popularity do not substitute for that review. + +The Goose review retained one execution detail: a chosen route should be feasible with the runtime, tools, access, and approval actually available. This is a narrow `Decide` check, not a setup questionnaire, extension catalogue, tool-count target, or second permission system. + +The Best of Agent Harnesses review clarified the product boundary without changing behavior. Codebase Learning Flow is a small, portable configuration layer for a host agent, not a runtime that owns tools, sandboxes, retries, or durable execution. Its task-first entry, minimal default, optional presets, and open Markdown artifacts already favor the lowest adoption surface that solves its educational job. + +## v0.6.2 remove residual learning ceremony + +A normal managed installation no longer creates learning-map work. Baselines recognize it cheaply and write only durable custom instruction exceptions or conflicts. The map therefore describes the repository, not whether the framework inspected itself. + +Deliberate bootstrap is optional even in the full profile; a real task can start with its matching skill. Learning reinforcement is folded into the standard handoff, limited to a few useful points, and omitted when it would duplicate the delivery summary. + +## v0.7.0 add conversational learning without repository ceremony + +The framework now has a common `learn-anything` skill for non-repository subjects. It reuses the established learning loop but changes its evidence surface: `Locate` finds the learner's question and starting point, `Work` uses a small example or practice exchange, and the conversation remains the default storage layer. + +This is a sibling route rather than another layer over engineering work. It does not load repository-learning instructions or inspect repository code. It may retain meaningful private session continuity under `.local/`, but it does not write shared `MAP.md`, `TAKEAWAYS.md`, curricula, or tracked progress records for generic personal learning. General programming concepts use this route; questions that require current codebase evidence return to a repository-learning skill. + +The skill is common to both profiles so minimal and full remain behaviorally compatible without duplicated instructions. Root maintenance guidance contains a compact Markdown fallback, allowing this source repository itself to host the same style of conversation. + +Private learning continuity follows the same ownership rule in the source repository and installed templates: **learn locally first; promote only reusable knowledge deliberately**. Meaningful sessions retain complete contributor-specific state in ignored `.local/sessions/`, compact cross-session memory in `.local/learning-history.md`, and generated follow-ups in `.local/follow-ups/`. This supports revision and later checks without turning personal history into shared repository content. + +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. + ## General agentic loop ```text @@ -82,14 +120,9 @@ Frame → Inspect → Decide → Act → Verify → Handoff ## Configurable opinionated behavior -Four compact A/B/C/D choices govern: +Four named presets cover the common collaboration modes: `fast`, `balanced`, `guided`, and `gated`. Balanced defaults let routine work start immediately. Setup asks for at most one preset rather than a matrix. -1. autonomy and pauses; -2. planning depth; -3. validation depth; -4. learning and records. - -Balanced defaults let routine work start immediately. The agent asks the full set only during setup or explicit configuration. During normal work it asks at most one relevant choice when an unresolved preference would materially change a substantial task. +Autonomy, planning, validation, learning depth, and persistence remain available as advanced overrides. Learning and persistence are separate so teaching depth does not silently create repository records. Root integration is a separate three-way filesystem choice whose result is recorded explicitly. No setting grants permission to commit, push, publish, release, disclose sensitive data, or perform irreversible work. Those actions still require explicit request or repository-native authorization. @@ -97,11 +130,11 @@ No setting grants permission to commit, push, publish, release, disclose sensiti ### Minimal -Designed for daily use and token economy. It persists only a map and durable takeaways, loads one learning skill, and creates no identity-based folders or activity files. +Designed for daily use and token economy. Its shared tracked learning is limited to a map and durable takeaways; private session continuity uses the common ignored `.local/` workspace. It loads one repository-learning skill and creates no tracked identity-based folders or activity files. ### Full -Designed for deliberate onboarding and long-lived learning programs. It retains research, materials, optional personal traces, explainers, labs, and task-specific learning skills. These surfaces are populated on demand, never as ceremony. +Designed for deliberate onboarding and long-lived learning programs. It keeps only maps, takeaways, repository baselines, and task-specific learning skills tracked by default. Private sessions and contributor-specific template instances use `.local/`; promoted shared artifacts remain exceptional. Optional challenge, ticket-path, and change-explainer templates live inside their owning skills and are materialized only on explicit need. ## Shared learning loop @@ -113,28 +146,35 @@ Locate → Reason → Work → Explain → Recap - `Reason`: state the behavior contract, uncertainty, analogue, hypothesis, or safe seam. - `Work`: investigate, implement, refactor, test, simulate, or review. - `Explain`: use one brief retrieval or transfer check only when consequential. -- `Recap`: consolidate the central model, decisive evidence, boundary, and nearby transfer. +- `Recap`: fold useful model, evidence, boundary, or transfer reinforcement into the normal handoff. Prediction remains available inside `Reason`, but is not forced into every task. +Both repository and general-topic learning use a compact system lens: + +```text +Purpose → Boundary → Parts and relationships → Change and feedback → Evidence → Transfer +``` + +The lens is selective. It favors causal relationships, one representative interaction, explicit uncertainty, and model revision over inventories or a mandatory worksheet. + ## Knowledge ownership and persistence -Conversation is the default storage layer. Promotion requires verification, repository specificity, likely reuse, and meaningful rediscovery cost. +Conversation is the live interaction layer. `.local/` is the private continuity layer for meaningful learning sessions. Shared promotion requires verification, repository specificity or framework value, likely reuse, meaningful rediscovery cost, and no sensitive or contributor-specific detail. | Surface | Owns | Does not own | |---|---|---| -| `MAP.md` | compact boundaries, vocabulary, representative paths, high-value unknowns | detailed evidence notes or session history | +| `.local/` | complete private sessions, progress, explanations, attempts, quiz history, compact continuity, generated follow-ups | shared canonical knowledge or committed content | +| `MAP.md` | compact boundaries, domain slices, representative paths, high-value unknowns | detailed evidence notes or session history | | `TAKEAWAYS.md` | short verified lessons worth reusing | raw debugging history or personal notes | -| full-profile `research/` | evidence-rich canonical findings | teaching scripts or progress | -| full-profile `materials/` | reusable teaching material derived from research | canonical source claims | -| full-profile `contributors/` | optional personal working traces | shared repository truth | -| `explainers/` and `labs/` | artifacts that clearly earn maintenance cost | default output for ordinary tasks | +| full-profile `REPOSITORIES.md` | repository identity, baseline, and access boundaries | detailed research or personal progress | +| Optional promoted artifacts | explicitly requested challenges, ticket paths, or explainers with stable team-wide reuse value | contributor-specific instances, pre-created directories, or default output for ordinary tasks | ## 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 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 full learning profile keeps seven narrow 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. +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. ## Installer lifecycle @@ -144,7 +184,7 @@ The common layer and each learning profile include managed-file and managed-skil - `update` refreshes only managed framework files and skills; - `replace` performs an explicit framework reset while preserving unrelated skills. -`agentic-flow/SETTINGS.md`, `MAP.md`, `TAKEAWAYS.md`, repository research, materials, contributor traces, explainers, and labs remain untouched by update mode. +`agentic-flow/SETTINGS.md`, `MAP.md`, `TAKEAWAYS.md`, repository research, materials, and `.local/` history remain untouched by update mode. Retired framework-owned contributor placeholders are removed through the prior managed-file manifest; contributor-authored legacy state requires an explicit copy-verify-remove migration into `.local/`. Minimal-to-full update is supported. Full-to-minimal update is rejected because safe automatic deletion cannot be inferred. @@ -158,7 +198,8 @@ Minimal-to-full update is supported. Full-to-minimal update is rejected because - pre-generated curricula and sessions; - default person-specific folders; - generic skills for token efficiency or determinism; -- persistent transcripts and hypothesis diaries; +- 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. ## Final review checklist @@ -167,11 +208,11 @@ Minimal-to-full update is supported. Full-to-minimal update is rejected because 2. Stable repository rules, collaboration workflow, learning support, and temporary state have distinct owners. 3. One primary task procedure owns the work. 4. Applied changes and executable proof are reported separately. -5. Opinionated behavior is configurable through compact A/B/C/D choices. -6. Trivial work creates no plan, questionnaire, quiz, session file, or learning artifact. +5. Opinionated behavior is configurable through one preset with optional advanced overrides. +6. Trivial work creates no plan, questionnaire, quiz, session file, or learning artifact; meaningful learning sessions close into `.local/`. 7. Consequential learning uses at most one understanding check by default. -8. Meaningful learning sessions end with a concise reinforcing recap. -9. Persistent artifacts have non-overlapping ownership and a reuse threshold. +8. Useful learning reinforcement is folded into the normal handoff without a duplicate recap. +9. Private `.local/` state and promoted shared artifacts have non-overlapping ownership and a reuse threshold. 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. diff --git a/docs/INITIALIZE_LEARNING_FLOW.md b/docs/INITIALIZE_LEARNING_FLOW.md index af46697..1d70b5a 100644 --- a/docs/INITIALIZE_LEARNING_FLOW.md +++ b/docs/INITIALIZE_LEARNING_FLOW.md @@ -15,7 +15,7 @@ Install two distinct layers: 1. `agentic-flow/` for general collaboration behavior; 2. `learning-flow/` for optional educational support. -Repository-native instructions remain authoritative for architecture, security, commands, conventions, and hard boundaries. Temporary handoff must not be embedded in stable instructions. +Repository-native instructions remain authoritative for architecture, security, commands, conventions, and hard boundaries. Private learning and temporary handoff must live in the conversation or ignored repository-root `.local/`, not stable instructions. ## General agentic flow @@ -38,14 +38,9 @@ Do not require a plan file, session record, one-step approval loop, one commit p ## Opinionated setup -Provide four compact A/B/C/D choices: +Provide four simple presets: `fast`, `balanced`, `guided`, and `gated`. Use `balanced` by default and ask for one preset only during explicit or guided configuration. -1. autonomy and pauses; -2. planning depth; -3. validation depth; -4. learning and records. - -Use balanced defaults when the repository is unconfigured. Ask all four only during initialization or explicit configuration. During ordinary tasks, ask at most one relevant choice when it would materially change substantial work. +Keep autonomy, planning, validation, learning depth, and persistence as advanced overrides. Do not ask them as an onboarding questionnaire. Learning depth and persistence remain independent so guided explanation does not require repository records. Task-specific user instructions override stored preferences. No preference grants permission to commit, push, publish, release, disclose sensitive content, or perform irreversible work. @@ -57,7 +52,7 @@ Include a small optional module explaining: - the common agentic workflow and settings; - selectively loaded task skills or plans; - the separate learning framework; -- temporary task state and evidence. +- private learning continuity and temporary task evidence under `.local/`. Show how an ordinary request resolves through these layers. Offer at most one brief explain-back, prediction, trace, or ownership check unless the user requests a quiz. @@ -75,13 +70,13 @@ Install only: - `TAKEAWAYS.md` for verified reusable lessons; - profile and update manifests. -Do not create contributor folders, curricula, activity files, labs, explainers, progress states, or research/material layers. +Do not create tracked contributor folders, curricula, activity files, labs, explainers, progress states, or research/material layers. Private continuity for sessions that actually occur belongs under `.local/`. ### Full profile Use for deliberate onboarding, long-lived ownership development, or teaching programs. -Retain selective learning skills and optional research, materials, contributor traces, explainers, labs, and templates. Populate them only when a verified result will be reused. +Retain selective learning skills, compact shared maps and takeaways, repository baselines, and task templates inside their owning skills. Keep contributor-specific sessions and template instances under `.local/`; add a tracked artifact only after deliberate promotion for clear team-wide reuse. ## Shared learning flow @@ -91,17 +86,13 @@ Locate → Reason → Work → Explain → Recap Keep routine inspection uninterrupted. Use one brief explanation, prediction, trace, comparison, or boundary check only when misunderstanding would affect later work. Skip it when the user already demonstrated understanding or requested fast execution. -Every meaningful learning session ends with a short recap that revisits: +Use a compact system lens across repository and general-topic learning: purpose, boundary, parts and relationships, change or feedback, evidence, and transfer. Select only what improves causal understanding, trace one representative interaction, and revise the model when evidence or learner reasoning contradicts it. -- the central mechanism; -- where it lives; -- the decisive evidence; -- the important boundary or corrected misconception; -- one nearby transfer. +When learning was central, fold up to three useful points about the mechanism, placement, evidence, boundary, or nearby transfer into the normal handoff. Skip them when that value is already present; do not add a second recap section. ## Persistence policy -Conversation is the default. Persist only findings that are: +Conversation is the live interaction layer. Meaningful learning sessions save complete contributor-specific state, compact cross-session history, and generated follow-ups under ignored `.local/`. Persist to shared tracked surfaces only findings that are: - verified; - repository-specific; @@ -110,12 +101,12 @@ Conversation is the default. Persist only findings that are: 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; - `MAP.md`: compact boundaries and representative flows; - `TAKEAWAYS.md`: short durable lessons; -- full-profile `research/`: canonical evidence; -- full-profile `materials/`: reusable teaching; -- full-profile `contributors/`: optional personal working traces only. +- full-profile `REPOSITORIES.md`: repository identities, baselines, and access boundaries; +- optional promoted artifacts: explicitly requested challenges, ticket paths, or explainers with stable team-wide reuse value; contributor-specific instances remain under `.local/`. ## Installer behavior @@ -125,6 +116,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. +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 - Never store secrets, personal data, customer data, raw production logs, or sensitive query results. @@ -132,6 +125,7 @@ Update only manifest-owned framework files and managed skills. Preserve reposito - Do not commit, push, publish, or release automatically. - Do not duplicate repository-native engineering rules into the generic framework. - Do not create a new artifact when conversation or an existing owned surface is sufficient. +- Never store contributor-specific learning state outside `.local/` during normal use. ## Avoid @@ -149,9 +143,9 @@ Update only manifest-owned framework files and managed skills. Preserve reposito ## Existing agentic setup as learning material -The initial repository baseline must inspect and map the repository's effective agentic system, not only the installed template. Cover root, nested, and tool-specific instructions; installed and custom skills; prompts, plans, sessions, status records, and evidence ledgers; precedence; ownership; and refresh rules. +The initial repository baseline recognizes the installed template without mapping it. Inspect root, nested, and tool-specific instructions, custom skills, prompts, plans, sessions, status records, or evidence ledgers only when repository evidence suggests they affect the task. Reserve a complete precedence and ownership map for an explicit agentic setup review. -Use template markers to avoid re-researching managed framework files. Map custom additions, integration, overrides, and conflicts in `MAP.md`. Root integration must support existing and missing `AGENTS.md` files through compact A/B/C/D choices and remain available after installation. +Use template markers to avoid re-researching managed framework files. Do not write ordinary template status to `MAP.md`; map only durable custom additions, overrides, and conflicts that affect future work. Root integration must support existing and missing `AGENTS.md` files through three distinct choices—link or initialize, preserve for later review, and explicit-only—and remain available after installation. diff --git a/docs/README.md b/docs/README.md index c0124b0..9b0e6c9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,5 +10,8 @@ The repository root keeps only the files needed for discovery, release history, ## External references - [`references/REFERENCE_INTEGRATION.md`](references/REFERENCE_INTEGRATION.md): repeatable external-source integration procedure +- [`references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md`](references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md): VoltAgent Awesome Agent Skills review +- [`references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md`](references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md): Best of Agent Harnesses review +- [`references/REFERENCE_REVIEW_GOOSE.md`](references/REFERENCE_REVIEW_GOOSE.md): Goose agent workflow review - [`references/REFERENCE_REVIEW_POCOK.md`](references/REFERENCE_REVIEW_POCOK.md): Pocok source review - [`references/REFERENCE_REVIEW_LITT.md`](references/REFERENCE_REVIEW_LITT.md): Geoffrey Litt source review diff --git a/docs/references/REFERENCE_INTEGRATION.md b/docs/references/REFERENCE_INTEGRATION.md index 72a6fde..e8c3a3e 100644 --- a/docs/references/REFERENCE_INTEGRATION.md +++ b/docs/references/REFERENCE_INTEGRATION.md @@ -8,15 +8,25 @@ A maintainer should be able to give an agent only this instruction: ```text Given this Codebase Learning Flow repository and the following GitHub source or ZIP, -review its agent-facing documentation and workflow. Incorporate the highest-value, -generally reusable ideas into our flow without copying source-specific policy or adding -unnecessary ceremony. Preserve our minimal/full profile model, update validation and -installer behavior where needed, and add a docs/references/REFERENCE_REVIEW_.md file recording -the source revision, reviewed surfaces, retained ideas, rejected constraints, and resulting changes. +review its agent-facing documentation and workflow. Treat it as evidence, not a target +architecture. Keep only a small, clearly useful delta where our current flow would +otherwise be weaker. Preserve our educational core, friendly tone, minimal/full profile +model, and low-ceremony defaults. It is valid to retain no framework change when the value +is already covered. Add a docs/references/REFERENCE_REVIEW_.md file recording the +source revision, reviewed surfaces, retained ideas, rejected constraints, and resulting changes. ``` The source may be a public GitHub repository, a repository URL, a branch or commit, or an attached ZIP. +## Integration posture + +- The source is a comparison point, not a specification or maturity benchmark. +- Preserve this repository's task-first education model and chill, direct voice. +- Retain only the smallest change that closes a clear gap or improves trustworthiness. +- Prefer “already covered” or “not a fit” over new rules, layers, catalogues, or terminology. +- Do not import breadth, rigidity, productivity pressure, or administrative text merely because the source is popular or extensive. +- Avoid generated filler and broad alternative perspectives that do not change a concrete decision. + ## Integration flow ```text @@ -32,6 +42,8 @@ Designate source → Inspect harness → Extract value → Fit ownership → Imp 3. **Extract value** - Separate generally reusable principles from source-specific architecture, tooling, release, and team policy. - Prefer one strong pattern over a catalogue of minor conventions. + - Name what is already covered before proposing a change. + - Use a small retained-delta budget: normally zero to three behavioral adjustments. 4. **Fit ownership** - Put repository-neutral collaboration behavior in `agentic-flow/`. - Put orientation, explanation, retrieval checks, and durable understanding in `learning-flow/`. @@ -41,6 +53,7 @@ Designate source → Inspect harness → Extract value → Fit ownership → Imp - Preserve minimal and full profiles. - Update the smallest set of managed files, skills, manifests, installers, examples, and eval cases needed. - Avoid importing source-specific terminology into generic defaults. + - Do not create a new layer, profile, or persistent artifact unless a demonstrated gap requires it. 6. **Review** - Check token cost, routing ambiguity, administrative burden, profile migration, and existing-harness compatibility. - Confirm that ordinary work still starts without a questionnaire or artifact build. @@ -55,6 +68,7 @@ Each review should contain: - source designation and exact revision; - scope and files inspected; - useful patterns retained; +- useful patterns already covered without change; - constraints deliberately not copied; - mapping into this framework; - unresolved limitations or evidence gaps. @@ -72,5 +86,6 @@ Keep the main review short. Use collapsible sections for detailed inventories or - Existing repository instructions can coexist with the change. - Installer update preserves repository-authored files. - The final review distinguishes inspiration from direct adoption. +- The resulting framework delta is smaller than the source review and can be zero. diff --git a/docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md b/docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md new file mode 100644 index 0000000..3fa7405 --- /dev/null +++ b/docs/references/REFERENCE_REVIEW_AWESOME_AGENT_SKILLS.md @@ -0,0 +1,37 @@ +# Reference review: VoltAgent Awesome Agent Skills + +## Source designation + +- Repository: [`VoltAgent/awesome-agent-skills`](https://github.com/VoltAgent/awesome-agent-skills) +- Branch: `main` +- Reviewed commit: [`c97eda5e3406670f3285c6bf9eb7639a7ecc03cc`](https://github.com/VoltAgent/awesome-agent-skills/tree/c97eda5e3406670f3285c6bf9eb7639a7ecc03cc) +- Review date: 2026-07-16 + +## Scope + +Reviewed `README.md` and `CONTRIBUTING.md`, focusing on catalogue organization, quality criteria, contribution thresholds, client paths, and the security notice. Representative entries were sampled only to understand the catalogue shape; linked third-party skills were not audited. + +## Already covered + +- Codebase Learning Flow already routes one narrow primary skill instead of stacking workflows. +- Skill descriptions already state the task fit and important exclusions. +- Managed skills already use progressive disclosure and repository-relative references. +- The small minimal/full sets avoid making catalogue breadth part of the learning experience. + +## Retained delta + +Added one common adoption boundary: treat third-party skills as executable instructions, inspect their original source and referenced resources at a designated revision, and check tools, access, side effects, and repository-rule overlap. Catalogue presence, publisher identity, and popularity remain discovery signals rather than security approval. + +## Deliberately not copied + +- the large vendor and community catalogue or its category taxonomy; +- fixed metadata token and skill line-count targets as universal rules; +- client-specific installation path matrices; +- popularity or community usage as sufficient evidence of safety or local fit; +- sponsor, submission, and catalogue-maintenance policy. + +## Framework mapping and limits + +The trust boundary belongs to common `agentic-flow/AGENTS.md`, so minimal and full profiles share it without duplicating skill prose. A regression case covers adoption from a popular catalogue. No skill was installed and no profile, routing table, installer behavior, or persistent artifact was added. + +The upstream catalogue explicitly says its entries are curated rather than security-audited. This review therefore supports source inspection at adoption time, not a claim that any listed skill is safe or correct. diff --git a/docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md b/docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md new file mode 100644 index 0000000..653d569 --- /dev/null +++ b/docs/references/REFERENCE_REVIEW_BEST_OF_AGENT_HARNESSES.md @@ -0,0 +1,39 @@ +# Reference review: Best of Agent Harnesses + +## Source designation + +- Repository: [`RyanAlberts/best-of-Agent-Harnesses`](https://github.com/RyanAlberts/best-of-Agent-Harnesses) +- Branch: `main` +- Reviewed commit: [`69ba3c2c0c54e56602a8b9816f967fc00363f818`](https://github.com/RyanAlberts/best-of-Agent-Harnesses/tree/69ba3c2c0c54e56602a8b9816f967fc00363f818) +- Review date: 2026-07-16 + +## Scope + +Lightly reviewed `README.md`, `CONTRIBUTING.md`, `comparisons/how-to-pick-a-harness.md`, and the scoring vocabulary in `scripts/generate.py`. Sampling focused on the distinction between a harness and its UI shell, adoption surface, autonomy, recovery, portability, and progressive disclosure. Individual listed projects and ranking claims were not independently verified. + +## Already covered + +- The real job comes first; routine work does not begin with framework configuration. +- Minimal is the default, and new layers or artifacts require a demonstrated need. +- Autonomy is configurable without prescribing headless execution. +- Selective skills, compact maps, and optional detail already use progressive disclosure. +- Markdown instructions and repository-owned knowledge stay portable across host agents. + +## Retained delta + +Clarified in the project and installed READMEs that Codebase Learning Flow configures a host agent rather than supplying an execution runtime. Tool execution, sandboxing, retries, and durable resumption remain host capabilities. This is a product-scope clarification only; workflow behavior did not change. + +## Deliberately not copied + +- the ranked catalogue, categories, tags, charts, comparison pages, or machine-readable recommendation service; +- popularity, activity, complexity, autonomy, and recovery scoring; +- headless and durable-runtime requirements for a repository configuration layer; +- an MCP server, JSON feed, `llms.txt`, weekly rescoring, or generated site; +- cost and provider comparisons that can change independently of this framework; +- broad harness terminology that would blur the education and collaboration purpose. + +## Framework mapping and limits + +The scope boundary belongs in the two short entry READMEs. No instruction, preset, profile, skill, evaluation case, installer behavior, or persistent artifact was added. + +The source compares formats, skill packs, runtimes, products, and SDKs with editorial dimensions. This review uses those dimensions only to confirm Codebase Learning Flow's narrow category and does not treat its rankings as validation or recommend any listed harness. diff --git a/docs/references/REFERENCE_REVIEW_GOOSE.md b/docs/references/REFERENCE_REVIEW_GOOSE.md new file mode 100644 index 0000000..222b15b --- /dev/null +++ b/docs/references/REFERENCE_REVIEW_GOOSE.md @@ -0,0 +1,38 @@ +# Reference review: Goose + +## Source designation + +- Repository: [`aaif-goose/goose`](https://github.com/aaif-goose/goose) +- Branch: `main` +- Reviewed commit: [`8691970733769f18eb2131197eb7d223ad0dc311`](https://github.com/aaif-goose/goose/tree/8691970733769f18eb2131197eb7d223ad0dc311) +- Review date: 2026-07-16 + +## Scope + +Reviewed the repository's `AGENTS.md`, `.goosehints`, and selected first-party documentation for quickstart, extensions, tool and agent permission modes, persistent instructions, planning, and sessions. Code was consulted only through the documented architecture and entry points; Goose runtime behavior was not executed. + +## Already covered + +- Repository-native instructions already outrank the common collaboration flow, and custom agent surfaces are mapped for conflicts and precedence. +- Autonomy, pauses, planning, and validation already use one optional preset with proportionate overrides. +- One primary task procedure owns the work; plans and session records are created only when useful. +- Applied changes, executable proof, unavailable evidence, and handoff are already distinct. + +## Retained delta + +Added one check to `Decide`: confirm only the runtime, tools, access, and approval material to the chosen route before acting. If a capability is unavailable, adapt the route or identify the exact blocker instead of silently enabling something external or discovering infeasibility late. + +## Deliberately not copied + +- Goose's provider, extension, MCP, recipe, custom-agent, and session systems; +- autonomous-by-default and per-tool permission modes as a second authorization layer; +- fixed enabled-tool count guidance or task-specific permission matrices; +- a dedicated plan mode or standardized multi-round planning interview; +- Goose repository build, test, architecture, UI, and release rules; +- duplicate persistent-instruction formats or Goose terminology. + +## Framework mapping and limits + +Capability readiness belongs in common `agentic-flow/WORKFLOW.md`, so both learning profiles receive it without configuration or setup ceremony. A regression case protects the adapt-or-block behavior. No new setting, tool registry, extension manager, plan artifact, or installer behavior was added. + +Goose's permission documentation notes that tool classification can be best-effort and provider-mediated. Codebase Learning Flow does not emulate that mechanism: repository rules, the host environment, and explicit user authorization remain authoritative. diff --git a/docs/references/REFERENCE_REVIEW_POCOK.md b/docs/references/REFERENCE_REVIEW_POCOK.md index adb3746..a36befc 100644 --- a/docs/references/REFERENCE_REVIEW_POCOK.md +++ b/docs/references/REFERENCE_REVIEW_POCOK.md @@ -40,7 +40,7 @@ These controls remain available when risk, team coordination, or configured pref ## Resulting framework changes -Pocok directly informed the separate `agentic-flow/` layer, risk-based planning and validation, evidence-status language, optional session records, root integration support, and the A/B/C/D collaboration settings. +Pocok directly informed the separate `agentic-flow/` layer, risk-based planning and validation, evidence-status language, optional session records, root integration support, and configurable collaboration behavior.
Main design concern found in the source diff --git a/sample/README.md b/sample/README.md index 5e50cf8..227f449 100644 --- a/sample/README.md +++ b/sample/README.md @@ -5,11 +5,13 @@ The installer combines one common agentic layer with one learning profile: ```text sample/common/agentic-flow/ sample/common/.agents/skills/agentic-workflow/ +sample/common/.agents/skills/learn-anything/ +sample/common/local/learning-history.md sample/profiles/minimal/ sample/profiles/full/ ``` -`agentic-flow/` governs general collaboration. `learning-flow/` adds optional educational support and maps the repository's actual agentic setup during the initial baseline. Keeping them separate prevents every engineering task from becoming a lesson and prevents learning preferences from silently changing approval or commit behavior. +`agentic-flow/` governs general collaboration. `learning-flow/` adds optional repository education and shared durable knowledge. `learn-anything` provides a separate conversational route for non-repository subjects. Both learning routes keep contributor-specific sessions, progress, checks, summaries, and follow-up material under ignored repository-root `.local/`; only reusable stable knowledge is promoted to tracked learning records. Fresh installs default to the minimal learning profile. Existing installations retain their profile. Minimal can upgrade to full through update mode. Full cannot reduce to minimal without replace mode. @@ -18,6 +20,7 @@ Root integration is configurable: - `sample/root/AGENTS.md` is the lean Pocok-informed template for repositories without root instructions; - `sample/root/AGENTS.pointer.md` is the idempotent block used to connect existing instructions; - existing root content is never replaced wholesale; -- integration can be performed during installation or later through the `agentic-workflow` skill. +- interactive setup offers only linked, pending-review, and explicit-only outcomes; +- the result is recorded in settings and can be revised later through the `agentic-workflow` skill. The common agentic layer also includes `REFERENCE_INTEGRATION.md` for learning from external repositories or ZIPs without copying source-specific policy. diff --git a/sample/common/.agents/skills/agentic-workflow/SKILL.md b/sample/common/.agents/skills/agentic-workflow/SKILL.md index 06f8f71..3b5744d 100644 --- a/sample/common/.agents/skills/agentic-workflow/SKILL.md +++ b/sample/common/.agents/skills/agentic-workflow/SKILL.md @@ -5,7 +5,7 @@ description: Initialize, integrate, configure, explain, map, review, or improve # Agentic workflow -Read `agentic-flow/README.md`, `AGENTS.md`, `SETTINGS.md`, and only the relevant section of `ROOT_INTEGRATION.md`, `CONFIGURE.md`, `WORKFLOW.md`, `LEARN.md`, or `REFERENCE_INTEGRATION.md`. +Read `agentic-flow/README.md`, `AGENTS.md`, `SETTINGS.md`, and only the relevant section of `ROOT_INTEGRATION.md`, `CONFIGURE.md`, `WORKFLOW.md`, `LEARN.md`, `LOCAL.md`, or `REFERENCE_INTEGRATION.md`. ## Discover the actual setup @@ -13,19 +13,19 @@ Read `agentic-flow/README.md`, `AGENTS.md`, `SETTINGS.md`, and only the relevant 2. Find skills, prompts, plans, sessions, status files, ADRs, evidence ledgers, and refresh rules. 3. Detect known template markers. 4. Treat managed template content as known; inspect custom additions, overrides, conflicts, and integration points. -5. Separate stable policy, collaboration behavior, task procedure, learning support, and temporary state. +5. Separate stable policy, collaboration behavior, task procedure, shared learning, and private or temporary `.local/` state. 6. Determine effective instruction order from repository evidence. ## Initialize or integrate 1. Preserve repository-specific engineering rules. -2. Use `ROOT_INTEGRATION.md` for the smallest relevant A/B/C/D choice. +2. Use `ROOT_INTEGRATION.md` for the matching three-way filesystem choice. 3. Append the managed pointer only when chosen and never duplicate it. 4. Create the lean root only when chosen. Do not invent architecture rules before inspection. -5. Ask collaboration settings only during requested or guided configuration. +5. Ask for one collaboration preset only during requested or guided configuration. Use advanced overrides only when explicitly needed. 6. In full mode, ask learner context only when it changes useful depth. 7. Update `SETTINGS.md` without rewriting unrelated instructions. -8. Update the learning map when the setup was inspected. +8. Update the learning map only for a durable custom instruction exception or conflict worth reusing. ## Explain the setup @@ -42,13 +42,15 @@ Read `agentic-flow/README.md`, `AGENTS.md`, `SETTINGS.md`, and only the relevant 1. Read `REFERENCE_INTEGRATION.md`. 2. Resolve the exact repository revision or archive hash. 3. Inspect agent-facing documentation and only enough code to understand protected behavior. -4. Retain generally reusable value, not source-specific policy. -5. Fit changes into existing owners and preserve minimal/full behavior. -6. Add a concise reference review with source designation, retained value, rejected constraints, and resulting changes. -7. Review token cost, routing ambiguity, artifact burden, and migration safety. +4. Treat the source as evidence, not a target architecture; name useful value already covered locally. +5. Retain only a small delta that closes a clear gap, normally zero to three behavioral adjustments. +6. Preserve the educational core, friendly voice, low ceremony, and minimal/full behavior. +7. Fit changes into existing owners; do not add layers or catalogues without a demonstrated need. +8. Add a concise reference review with source designation, covered and retained value, rejected constraints, and resulting changes. +9. Review token cost, routing ambiguity, artifact burden, and migration safety. ## Review an existing harness -Look for temporary handoff in stable instructions, mandatory ceremony unrelated to risk, duplicated rules, unchecked completion claims, competing workflows, learning mixed into universal execution, stale records without owners, and ambiguous root integration. +Look for temporary handoff in stable instructions, contributor-specific learning outside ignored `.local/`, mandatory ceremony unrelated to risk, duplicated rules, unchecked completion claims, competing workflows, learning mixed into universal execution, stale records without owners, and ambiguous root integration. Recommend the smallest consolidation. Preserve coherent custom structures. Do not add a framework layer unless it removes more complexity than it adds. diff --git a/sample/common/.agents/skills/learn-anything/SKILL.md b/sample/common/.agents/skills/learn-anything/SKILL.md new file mode 100644 index 0000000..208f479 --- /dev/null +++ b/sample/common/.agents/skills/learn-anything/SKILL.md @@ -0,0 +1,52 @@ +--- +name: learn-anything +description: Guide a friendly, adaptive conversation for learning, exploring, or practicing any general topic, including science, history, languages, arts, design, mathematics, and general technical concepts, with private continuity under .local for meaningful sessions. Use when the learner wants understanding without analyzing the current repository. Do not use for repository orientation, codebase bugs, features, refactors, or setup; use the repository learning skill or relevant task skill there. +--- + +# Learn Anything + +Keep the learning conversational and do not inspect repository code. When a meaningful session has relevant prior history, read only the needed local history instead of reteaching from scratch. + +## Conversation loop + +Adapt the established learning loop to the learner rather than a codebase: + +```text +Locate → Reason → Work → Explain → Recap +``` + +- **Locate:** identify the learner's actual question, goal, and demonstrated starting point. Infer context where safe; ask at most one question only when its answer would materially change the useful route. +- **Reason:** build a compact mental model. Introduce vocabulary or prerequisites only when they unlock the current question, and make important cause-and-effect relationships explicit. +- **Work:** use the smallest helpful activity: one example, analogy, comparison, worked problem, scenario, or practice exchange. Do it with the learner, then adapt from their response. +- **Explain:** invite at most one optional prediction, retrieval, or transfer check when it would deepen understanding. Never make a quiz or proof-of-learning a gate. +- **Recap:** close naturally with the main idea and a useful next direction. Skip a recap when it would merely repeat the answer. + +Collapse obvious stages. A short factual question may need only a direct answer plus one clarifying example. + +## System lens + +For a complex subject, choose only the elements that improve the current explanation: + +- purpose, outcome, or central question; +- boundary and surrounding context; +- important parts, actors, and relationships; +- flows, state changes, rules, feedback, or tradeoffs; +- evidence, exceptions, and uncertainty; +- transfer to a nearby case. + +Prefer one representative interaction through the system over an inventory of facts. Revisit the model when the learner's explanation, prediction, or example exposes a mismatch. + +## Style and boundaries + +- Follow the learner's curiosity rather than imposing a curriculum. +- Alternate explanation and interaction when interaction helps; do not turn every answer into a lesson script. +- Correct mistakes directly and kindly, then reconnect the correction to the mental model. +- Match depth to demonstrated understanding and invite the learner to steer deeper or sideways. +- Distinguish established fact, interpretation, and uncertainty. Verify current or uncertain claims when the host environment requires it. +- General programming concepts belong here when no current repository must be inspected. Repository-specific questions do not. + +## Local continuity + +Read `agentic-flow/LOCAL.md` only when continuity or closure applies. Do not create a session file for a one-off answer. At natural closure of a meaningful session, save its complete private state, update compact history, retain any generated follow-up material, and apply the documented promotion test. + +Do not write generic personal learning into repository `MAP.md` or `TAKEAWAYS.md`. An explicit request to preserve something globally still requires a suitable shared owner and deliberate promotion. diff --git a/sample/common/.agents/skills/learn-anything/agents/openai.yaml b/sample/common/.agents/skills/learn-anything/agents/openai.yaml new file mode 100644 index 0000000..a97b1c6 --- /dev/null +++ b/sample/common/.agents/skills/learn-anything/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Learn Anything" + short_description: "Explore topics with private learning continuity" + default_prompt: "Use $learn-anything to help me learn a topic conversationally and retain useful private continuity in .local/." diff --git a/sample/common/agentic-flow/.managed-files b/sample/common/agentic-flow/.managed-files index 1ad227a..5ea508e 100644 --- a/sample/common/agentic-flow/.managed-files +++ b/sample/common/agentic-flow/.managed-files @@ -6,5 +6,6 @@ AGENTS.md WORKFLOW.md CONFIGURE.md LEARN.md +LOCAL.md ROOT_INTEGRATION.md REFERENCE_INTEGRATION.md diff --git a/sample/common/agentic-flow/.managed-skills b/sample/common/agentic-flow/.managed-skills index 03d201e..198d608 100644 --- a/sample/common/agentic-flow/.managed-skills +++ b/sample/common/agentic-flow/.managed-skills @@ -1 +1,2 @@ agentic-workflow +learn-anything diff --git a/sample/common/agentic-flow/.template-version b/sample/common/agentic-flow/.template-version index be14282..faef31a 100644 --- a/sample/common/agentic-flow/.template-version +++ b/sample/common/agentic-flow/.template-version @@ -1 +1 @@ -0.5.3 +0.7.0 diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md index 4808338..c5c7b75 100644 --- a/sample/common/agentic-flow/AGENTS.md +++ b/sample/common/agentic-flow/AGENTS.md @@ -1,83 +1,88 @@ # Agentic collaboration instructions -## Priority +## Route 1. Follow root, nested, and tool-specific repository instructions first. -2. Follow this agentic workflow for collaboration behavior. -3. Load `learning-flow/AGENTS.md` for deliberate learning, orientation, explanation, or initial mapping of the repository's agentic setup. -4. Load one task skill when useful. Do not stack workflows by default. +2. Use this layer for collaboration behavior. +3. Load `learning-flow/AGENTS.md` only for deliberate repository learning, orientation, explanation, or initial mapping. +4. Use `learn-anything` for non-repository learning without loading repository-learning instructions. +5. Load at most one task skill unless the task clearly requires more. -## Instruction discovery +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. -Do not assume this template is the repository's only harness. Respect existing instructions, skills, prompts, plans, records, and agent-specific files. +## Discover the effective setup -When the setup is not mapped, use `LEARN.md` and `ROOT_INTEGRATION.md` to distinguish stable repository policy, collaboration behavior, task procedures, learning support, and temporary state. Recognize managed template files cheaply and inspect custom additions, overrides, and effective precedence. +Do not assume this template is the repository's only harness. Respect existing instructions, skills, prompts, plans, records, and agent-specific files. Treat managed template files as known; inspect custom additions, overrides, effective precedence, and conflicts only when they affect the work. Use `LEARN.md`, `LOCAL.md`, and `ROOT_INTEGRATION.md` when those boundaries need explanation. + +Treat third-party skills as executable instructions. Before adding or first using one, inspect its pinned source, referenced scripts or resources, required tools, network or secret access, side effects, maintenance, and overlap with repository rules. Popularity or catalogue inclusion is discovery evidence, not a security review. Prefer one narrow skill for a demonstrated need over a broad bundle. ## Default behavior -Use the repository as current truth. Treat plans, status notes, and previous summaries as evidence that may have drifted. +Use current repository evidence as truth; plans and summaries may have drifted. ```text Frame → Inspect → Decide → Act → Verify → Handoff ``` -Collapse obvious steps for small work. Do not create a plan, session file, status artifact, or lesson merely because the framework supports one. +Collapse obvious steps for small work. Do not create a plan, session, status artifact, or lesson merely because the framework supports one. Follow `WORKFLOW.md` when the detailed execution or handoff shape matters. -## Communication style +For a non-repository learning request, use `learn-anything`. Keep the exchange conversational, inspect no repository code, and use `.local/` only for meaningful private continuity as defined in `LOCAL.md`. Questions that require current codebase evidence return to repository learning. -- Be friendly, direct, and calm. -- Lead with the useful conclusion, next action, or compact map. -- Say concretely what changed and why it matters; prefer “changed X so Y” over dry labels or execution chronology. -- Prefer simple language and a compact overview before implementation detail. -- Group substantial updates into a few visually distinct, descriptive bullets by outcome, not a file-by-file inventory. -- Match depth to the task and demonstrated user context. -- In human-facing Markdown, place optional rationale, long evidence, command matrices, alternatives, and examples in `
` sections when supported. -- Keep warnings, unresolved decisions, required actions, and validation failures visible outside collapsed sections. +## Communication -## Questions and approvals +- Lead with the useful result, next action, or compact map. +- Say what changed and why it matters; group substantial updates into a few outcome-based bullets rather than a tool log or file inventory. +- Start substantial work with the intended outcome and a short route when sequencing matters. Update only when the phase or route changes, a blocker appears, or silence would become confusing. +- Prefer plain language and a compact overview before detail. Use `
` for optional rationale, long evidence, command matrices, alternatives, or examples. +- Keep warnings, unresolved decisions, validation failures, and required next actions visible. +- Match depth to the task and the user's demonstrated context. -Read `SETTINGS.md`. If unconfigured, use defaults without blocking routine work. +## Questions and authority -Ask only when a consequential product, architecture, dependency, compatibility, safety, or irreversible choice is unresolved; evidence cannot distinguish responsible options; configured mode requests a gate; or root integration is the task. +Ask only when a consequential product, architecture, dependency, compatibility, safety, or irreversible choice remains unresolved; evidence cannot distinguish responsible options; configured mode requests a gate; or root integration is the task. -When an opinionated default matters, ask the smallest relevant A/B/C/D question from `CONFIGURE.md` or `ROOT_INTEGRATION.md`. Do not repeat full questionnaires during ordinary work. +When collaboration behavior needs configuration, ask for one preset from `CONFIGURE.md`. Ask for an individual override only when no preset fits, and ask the root-integration choice only when that integration is unresolved. Do not run questionnaires during ordinary work. An explicit implementation request permits ordinary reversible work within scope. It does not permit destructive Git operations, publishing, release actions, secret access, or unrelated changes. -## Planning and records +## Planning, execution, and records -- Small tasks need no formal plan. -- Multi-step tasks use a short in-chat plan by default. -- Create a plan file only when risk, configuration, handoff, or duration justifies it. -- Session records, ledgers, and status files are optional evidence tools. -- Keep temporary handoff out of stable instruction files. +- 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. +- Inspect the smallest responsible scope and prefer one coherent change over artificial micro-steps. +- Revisit the route when evidence changes the scope, architecture, or behavior. +- Validate in proportion to risk, focused first. Separate changes applied from executable checks completed and never claim unavailable verification. +- Keep ordinary session records, ledgers, and status files optional. Keep temporary handoff out of stable instructions. +- At natural closure of a meaningful learning session, save private state and compact continuity under `.local/` according to `LOCAL.md`; do not store it elsewhere. -## Execution and verification +## Handoff -- Inspect the smallest responsible scope before acting. -- Prefer one coherent change over artificial micro-steps. -- Revisit the route when evidence changes scope, architecture, or behavior. -- Separate changes applied from executable validation completed. -- Validate in proportion to risk, focused first. -- Never claim verification when the required environment was unavailable. +End substantial work with the plain-language result and only the useful sections below: -## Handoff +```text +Changed +- Area — what changed and why it matters. -End substantial work with a plain-language result followed by compact `Changed`, `Checked`, and, only when needed, `Open` bullets. Each changed bullet should connect the concrete change to its reason or effect. Omit empty sections, repeated narration, and exhaustive file lists. +Checked +- Proof — meaningful result. -When asked to write or create a substantive commit, use a short imperative title. Add only the body sections that carry useful context: +Open +- Remaining risk, decision, or next action. +``` + +Omit empty sections, repeated narration, and exhaustive file lists. When learning was central, fold useful reinforcement into this handoff instead of adding a second recap. + +For a substantive commit, use a short imperative title and only body sections that add context: ```text Why: -- the problem, constraint, or intent +- problem or intent What: -- the concrete behavior or structure changed, and its effect +- behavior changed and its effect Checks: - meaningful verification ``` -Keep trivial commits to a title. Do not turn the template into mandatory ceremony. - -Do not commit, push, publish, merge, or create release tags unless explicitly requested. +Trivial commits need only a title. 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 125d887..d1205e3 100644 --- a/sample/common/agentic-flow/CONFIGURE.md +++ b/sample/common/agentic-flow/CONFIGURE.md @@ -1,36 +1,32 @@ # Configure agentic collaboration -Configuration is optional. Balanced defaults allow work to begin immediately. Ask these choices during setup, on explicit request, or when one unresolved preference materially changes substantial work. +Configuration is optional. Use `balanced` by default and begin work immediately. During setup or explicit configuration, prefer one preset name over a questionnaire. -A compact answer such as `1B 2A 3C 4B` is enough. `defaults` selects the balanced choices. +## Presets -## 1. Autonomy and pauses +| Preset | Best for | Behavior | +|---|---|---| +| `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 | -- **A. Fast:** execute end to end; ask only for blockers, safety, or irreversible choices. -- **B. Balanced, default:** proceed independently and ask at meaningful design forks. -- **C. Reviewed:** show a brief plan before implementation and pause at major scope changes. -- **D. Gated:** pause before implementation and after each major phase. +`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. -## 2. Planning depth +
+Advanced overrides and optional learner context -- **A. Minimal:** no plan unless sequencing is genuinely unclear. -- **B. Brief, default:** short in-chat plan for multi-step work. -- **C. Durable:** create a plan file for substantial or handoff-heavy work. -- **D. Formal:** explicit phases, acceptance criteria, and review gates. +## Optional overrides -## 3. Validation depth +Use overrides only when the user explicitly wants finer control or one preset behavior is a poor fit. Do not ask this list as an onboarding questionnaire. -- **A. Focused:** run the closest checks and disclose the remaining boundary. -- **B. Risk-proportional, default:** focused checks first, then broaden as risk warrants. -- **C. Broad:** focused, affected, and repository-wide validation when available. -- **D. Matrix:** follow a repository-defined command matrix and record each result. +1. **Autonomy and pauses:** `A` end to end, `B` meaningful forks, `C` plan and scope-change review, `D` gated phases. +2. **Planning depth:** `A` minimal, `B` brief in-chat, `C` durable when justified, `D` formal phases and acceptance criteria. +3. **Validation depth:** `A` focused, `B` risk-proportional, `C` broad, `D` repository command matrix. +4. **Learning depth:** `A` delivery only, `B` concise handoff reinforcement, `C` explain-back when consequential, `D` guided prediction and teaching. +5. **Persistence:** `A` no learning history beyond the conversation, `B` private learning continuity in `.local/` plus durable verified shared findings, `C` explicit reusable shared records when justified. -## 4. Learning and records - -- **A. Delivery only:** no learning prompts or persistent records unless requested. -- **B. Lean, default:** concise recap; persist only durable maps, takeaways, decisions, or evidence. -- **C. Explain-back:** one check for consequential concepts plus the lean recap. -- **D. Guided:** deliberate teaching, prediction, explain-back, and optional session records. +Avoid contradictory combinations. Autonomy controls pauses; planning controls representation. A formal plan does not silently remove a configured gate, and fast autonomy does not require formal planning. ## Optional full-profile learner context @@ -43,12 +39,16 @@ Ask this only when the full learning profile is active, the user's experience ca Do not classify the user automatically or ask again once enough context is available. Store the choice only when the user wants it reused. +
+ ## Root integration -Root integration is a separate one-time choice. Read `ROOT_INTEGRATION.md` and ask only the matching A/B/C/D set. Do not combine root integration, four settings, and learner context into one questionnaire. +Root integration is a separate one-time filesystem choice. Read `ROOT_INTEGRATION.md` and ask only the matching three-way choice. Do not combine root integration, preset selection, learner context, and advanced overrides into one questionnaire. ## Recording choices -Update `SETTINGS.md` and set `Status: configured` or `Status: defaults`. +Update `SETTINGS.md`, set `Status: configured`, and record the preset. Keep override rows at `inherit` unless requested; when switching presets, clear old overrides unless the user explicitly keeps them. + +Set `Agentic setup review` to `template-linked`, `custom-mapped`, `conflict`, or `explicit-only`. Set `Root integration` to `linked`, `pending`, or `explicit-only`. Task-specific instructions override stored preferences. Do not turn a one-off request into a permanent setting unless asked. -Set `Agentic setup review` to `template-linked`, `custom-mapped`, or `pending`. Task-specific instructions override stored preferences. Do not turn a one-off request into a permanent setting unless asked. +Legacy settings without a preset or persistence row remain valid: infer `balanced` from the existing B defaults and treat persistence as `B` unless repository instructions say otherwise. Persistence settings never move personal or uncertain state out of `.local/`. diff --git a/sample/common/agentic-flow/LEARN.md b/sample/common/agentic-flow/LEARN.md index 35260da..a65bd34 100644 --- a/sample/common/agentic-flow/LEARN.md +++ b/sample/common/agentic-flow/LEARN.md @@ -11,7 +11,7 @@ One task procedure or skill ↓ Optional learning support ↓ -Temporary evidence and handoff +Private learning and temporary state in .local/ ``` ## First pass @@ -22,7 +22,8 @@ Show: - which workflow governs planning, autonomy, validation, and handoff; - which skills load only for particular tasks; - where learning support lives; -- where temporary plans, sessions, status, or evidence are stored; +- how `.local/` owns private sessions, progress, checks, generated follow-ups, and temporary evidence; +- which verified reusable findings may be promoted to shared learning records; - the effective precedence when rules overlap. Known template files need only recognition. Spend research effort on custom instructions, tool-specific files, overrides, conflicts, stale state, and repository-specific conventions. diff --git a/sample/common/agentic-flow/LOCAL.md b/sample/common/agentic-flow/LOCAL.md new file mode 100644 index 0000000..3e6193a --- /dev/null +++ b/sample/common/agentic-flow/LOCAL.md @@ -0,0 +1,45 @@ +# Local learning state + +Use one rule: + +> Learn locally first. Promote only reusable knowledge deliberately. + +The repository-root `.local/` directory owns private learning continuity. The installer creates it, adds `/.local/` to the root `.gitignore`, and never overwrites existing local files. + +This framework's own source checkout follows the same model lazily: when `.local/` is missing, create the two directories below and copy `sample/common/local/learning-history.md` only if the local history file does not exist. + +```text +.local/ +├── learning-history.md +├── sessions/ +└── follow-ups/ +``` + +- `learning-history.md` is the compact cross-session memory: current system models, concepts encountered, demonstrated understanding, prior checks, fragile areas, and useful next directions. +- `sessions/` holds the complete state of meaningful learning sessions, including goals, explanations, outcomes, questions, quiz or check results, progress, summaries, and next steps. +- `follow-ups/` holds generated revision material, practice, or quizzes intended for later use. + +Do not create a session file for a one-off answer or ordinary engineering task. When a meaningful learning session reaches a natural stopping point: + +1. save its complete contributor-specific state under `.local/sessions/`; +2. update `.local/learning-history.md` so a later session can continue, revise earlier concepts, or generate a relevant check; +3. consider only clearly reusable, stable, non-sensitive findings for `learning-flow/MAP.md`, `learning-flow/TAKEAWAYS.md`, or another existing shared owner; +4. treat an explicit request to preserve something globally as a promotion request, not automatic publication; +5. deduplicate against shared records and keep personal, sensitive, or uncertain information local. + +At the start of a continuing session, read only the relevant history and recent session state. Do not load the entire local archive by default. + +## Ownership boundary + +| State | Owner | +|---|---| +| personal progress, tailored explanations, attempts, quiz history, uncertainty, complete session summaries | `.local/` | +| verified repository boundaries and representative flows useful to future contributors | `learning-flow/MAP.md` | +| concise verified lessons worth sharing and reusing | `learning-flow/TAKEAWAYS.md` | +| unresolved, sensitive, or contributor-specific information | `.local/` only | + +Shared records are curated knowledge, not a compressed personal transcript. Generic-topic learning should be promoted only when it improves this framework or clearly benefits its future contributors. + +## Legacy tracked state + +Older installations may contain contributor-specific content under tracked `learning-flow/contributors/` or similar session, progress, quiz, or follow-up paths. Update mode already retires framework-owned placeholders through the managed-file manifest. For contributor-authored content, copy it into the matching `.local/` area without overwriting existing files, verify the copy, then remove the tracked original as an explicit repository change. Never delete uncertain or user-owned history merely to complete migration. diff --git a/sample/common/agentic-flow/README.md b/sample/common/agentic-flow/README.md index afb6e67..071591c 100644 --- a/sample/common/agentic-flow/README.md +++ b/sample/common/agentic-flow/README.md @@ -6,7 +6,9 @@ A compact repository-native collaboration layer: Frame → Inspect → Decide → Act → Verify → Handoff ``` -It governs planning, autonomy, validation, records, and handoff. Repository-specific architecture and safety rules remain in native instructions. Deliberate teaching and durable understanding remain in `learning-flow/`. +It governs planning, autonomy, validation, records, and handoff. Repository-specific architecture and safety rules remain in native instructions. Deliberate repository teaching and durable understanding remain in `learning-flow/`; general-topic learning uses the common `learn-anything` skill and stays in conversation by default. + +This layer configures a host agent; it does not provide its own tool runtime, sandbox, retry engine, or durable task resumption. Start with `AGENTS.md`. Use balanced defaults from `SETTINGS.md` unless configuration matters. @@ -14,9 +16,10 @@ Start with `AGENTS.md`. Use balanced defaults from `SETTINGS.md` unless configur Supporting guides - `WORKFLOW.md`: execution loop, evidence labels, and descriptive handoff shape -- `CONFIGURE.md`: compact A/B/C/D preferences and optional full-profile learner context +- `CONFIGURE.md`: simple presets, optional advanced overrides, and full-profile learner context - `ROOT_INTEGRATION.md`: connecting existing or missing root instructions - `LEARN.md`: understanding the effective repository harness +- `LOCAL.md`: private learning continuity and deliberate shared promotion - `REFERENCE_INTEGRATION.md`: incorporating high-value patterns from another repository or ZIP
diff --git a/sample/common/agentic-flow/REFERENCE_INTEGRATION.md b/sample/common/agentic-flow/REFERENCE_INTEGRATION.md index c065ee4..b3e8158 100644 --- a/sample/common/agentic-flow/REFERENCE_INTEGRATION.md +++ b/sample/common/agentic-flow/REFERENCE_INTEGRATION.md @@ -6,9 +6,11 @@ Use this when the repository should incorporate high-value workflow or learning ```text Review this source as a reference for our repository's agentic and learning setup. -Keep only generally useful patterns that fit our existing ownership layers. Avoid copying -source-specific policy or adding ceremony. Record the exact source revision and create a -concise reference review explaining what was retained, rejected, and changed. +Treat it as evidence, not a target architecture. Keep only a small, clearly useful delta +that fits our existing ownership layers. Preserve our educational purpose, friendly voice, +and low-ceremony defaults. It is valid to change nothing when the useful value is already +covered. Record the exact source revision and create a concise reference review explaining +what was already covered, retained, rejected, and changed. ``` ## Procedure @@ -16,10 +18,12 @@ concise reference review explaining what was retained, rejected, and changed. 1. Record the source identity, exact revision or archive hash, and review date. 2. Inspect instructions, skills, prompts, plans, records, evidence rules, and learning surfaces. 3. Separate reusable ideas from source-specific architecture, tooling, release, or team policy. -4. Fit each retained idea into repository-native instructions, `agentic-flow/`, `learning-flow/`, or a bounded skill. -5. Implement the smallest coherent change and preserve existing custom harness behavior. -6. Review token cost, routing, artifact burden, and migration safety. -7. Add a short reference review with provenance, scope, retained value, rejected constraints, and resulting changes. +4. Name what is already covered and retain normally no more than zero to three behavioral adjustments. +5. Fit each retained idea into repository-native instructions, `agentic-flow/`, `learning-flow/`, or a bounded skill. +6. Implement the smallest coherent change and preserve existing custom harness behavior. +7. Reject new layers, catalogues, rigid ceremony, productivity pressure, or administrative text unless a demonstrated gap requires them. +8. Review token cost, routing, artifact burden, and migration safety. +9. Add a short reference review with provenance, scope, covered value, retained value, rejected constraints, and resulting changes. Conversation is the default during review. Create durable research only when the source and conclusions need future traceability. @@ -31,5 +35,6 @@ Conversation is the default during review. Create durable research only when the - temporary handoff state; - mandatory plans, sessions, quizzes, or dashboards; - copied source text when a short attributed principle is enough. +- broad alternative perspectives or generated filler without a concrete decision.
diff --git a/sample/common/agentic-flow/ROOT_INTEGRATION.md b/sample/common/agentic-flow/ROOT_INTEGRATION.md index e3ff601..65cecc6 100644 --- a/sample/common/agentic-flow/ROOT_INTEGRATION.md +++ b/sample/common/agentic-flow/ROOT_INTEGRATION.md @@ -18,20 +18,18 @@ Preserve repository-specific rules. Connect the installed layers rather than rep Ask one compact choice when integration has not already been decided: - **A. Link now:** append the managed pointer block and preserve all existing content. -- **B. Review first:** inspect overlaps or conflicts, then propose the smallest integration patch. -- **C. Preserve:** leave the root file untouched and use the installed layers only when explicitly requested. -- **D. Later:** defer integration and record no permanent choice. +- **B. Preserve for review:** leave the root file untouched, record integration as pending, and inspect overlaps only when they affect work. +- **C. Explicit only:** leave the root file untouched and load the installed layers only when explicitly invoked. -Use A only when the existing file does not already point to both installed layers. Use B when the existing file already owns planning, approval, validation, session, or learning behavior that may conflict. +Use A only when the existing file does not already point to both installed layers. Use B when it may already own overlapping workflow behavior. Each choice records a distinct root-integration state in `SETTINGS.md`. ## When no root `AGENTS.md` exists Ask one compact choice: -- **A. Initialize lean:** create the Pocok-informed root template, then ask the four collaboration settings. -- **B. Initialize defaults:** create the lean root template and keep balanced settings until configured later. -- **C. Tailor first:** inspect the repository and propose a repository-specific root file before creating it. -- **D. No root file:** leave the repository without a root `AGENTS.md`; collaborators must invoke the installed layers explicitly. +- **A. Initialize lean, default:** create the Pocok-informed root template and use the balanced preset. +- **B. Tailor later:** leave the root absent, record integration as pending, and propose repository-specific instructions only when needed. +- **C. Explicit only:** leave the root absent and load the installed layers only when explicitly invoked. The lean template keeps only reusable discipline: diff --git a/sample/common/agentic-flow/SETTINGS.md b/sample/common/agentic-flow/SETTINGS.md index 11060b6..a52b873 100644 --- a/sample/common/agentic-flow/SETTINGS.md +++ b/sample/common/agentic-flow/SETTINGS.md @@ -1,16 +1,19 @@ # Agentic workflow settings -Status: unconfigured +Status: defaults +Preset: balanced Agentic setup review: pending +Root integration: pending Full-profile learner context: adaptive -| Setting | Choice | Default | -|---|---|---| -| Autonomy and pauses | B | B | -| Planning depth | B | B | -| Validation depth | B | B | -| Learning and records | B | B | +| Override | Choice | +|---|---| +| Autonomy and pauses | inherit | +| Planning depth | inherit | +| Validation depth | inherit | +| Learning depth | inherit | +| Persistence | inherit | -Until configured, use the defaults. A task-specific user instruction overrides this file. +Use the preset without blocking routine work. A task-specific user instruction overrides this file without changing it. -Configuration shorthand: `1B 2B 3B 4B`. +Configuration shorthand: a preset name, or advanced overrides such as `1C 3C 5A`. diff --git a/sample/common/agentic-flow/WORKFLOW.md b/sample/common/agentic-flow/WORKFLOW.md index 2767b0a..4e6781e 100644 --- a/sample/common/agentic-flow/WORKFLOW.md +++ b/sample/common/agentic-flow/WORKFLOW.md @@ -18,7 +18,9 @@ Read native instructions and the narrowest relevant code, tests, configuration, Choose the smallest coherent route. Use a brief plan only when sequencing, risk, or coordination benefits from it. -If an opinionated choice materially affects the result and repository evidence does not settle it, ask one relevant A/B/C/D question. Otherwise use the configured default. +Confirm that the route's required runtime, tools, access, and approval are available before acting. Check only capabilities material to the task; adapt the route or name the exact blocker instead of inventorying every tool or silently enabling a new external capability. + +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`. ## Act @@ -36,6 +38,12 @@ Keep evidence labels distinct: - broader executable verification passed; - verification unavailable or incomplete. +## Progress visibility + +For substantial work, open with the intended outcome and a two-to-four-step route. After that, update only at a meaningful phase transition, when evidence changes the route, when a blocker appears, or when a long-running step would otherwise leave the user without useful context. + +Use a compact `Now / Found / Next` pulse when those labels improve scanning. Report decisions and evidence, not commands already visible in tool output. Do not restate an unchanged plan. + ## Handoff Lead with one or two sentences explaining what is now true and why that route was chosen. For substantial work, use this compact shape and omit any section that adds no value: @@ -55,7 +63,7 @@ Open Use descriptive bullets grouped by outcome instead of a chronological tool log or file inventory. Put long command output, secondary rationale, alternatives, or exhaustive evidence in collapsible sections. Keep failures and required next actions visible. -Add a learning recap only when `learning-flow/` was active or explanation was requested. +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. ## Stop conditions diff --git a/sample/common/local/learning-history.md b/sample/common/local/learning-history.md new file mode 100644 index 0000000..261a0c8 --- /dev/null +++ b/sample/common/local/learning-history.md @@ -0,0 +1,24 @@ +# Local learning history + +This file is private repository-local learning state. Keep it concise enough to resume useful context without rereading every session. Do not promote it wholesale. + +## Current focus + +## Current system models + +| Topic | Purpose and boundary | Key relationships, change, or feedback | Evidence and uncertainty | +|---|---|---|---| + +## Learned and revisited concepts + +| Topic | Current understanding | Last revisited | Evidence or check | +|---|---|---|---| + +## Fragile or uncertain areas + +## Quiz and check history + +| Date | Topic | Outcome | Revisit when | +|---|---|---|---| + +## Useful next directions diff --git a/sample/learning-flow/.template-version b/sample/learning-flow/.template-version deleted file mode 100644 index 6e8bf73..0000000 --- a/sample/learning-flow/.template-version +++ /dev/null @@ -1 +0,0 @@ -0.1.0 diff --git a/sample/learning-flow/AGENTS.md b/sample/learning-flow/AGENTS.md deleted file mode 100644 index 2345dc4..0000000 --- a/sample/learning-flow/AGENTS.md +++ /dev/null @@ -1,568 +0,0 @@ -# Learning Flow Agent Instructions - -These instructions govern repository research, teaching, contributor traces, and ticket-oriented learning under `learning-flow/`. - -## Mission - -Help contributors become productive on real work while building durable senior-level understanding of: - -- system architecture; -- domain vocabulary and behavior; -- runtime composition; -- ownership boundaries; -- recurring implementation patterns; -- testing and observability; -- known constraints; -- responsible change paths. - -Build cumulative repository knowledge so future agents do not repeatedly pay the same exploration cost. - -Do not turn this directory into a course platform, a second issue tracker, or a permanent transcript archive. - -## Read order - -Before learning-flow work, read: - -1. repository root and relevant nested agent instructions; -2. `learning-flow/README.md`; -3. this file; -4. `learning-flow/REPOSITORIES.md`; -5. relevant research, materials, and contributor tracking. - -For initial population, also read `learning-flow/BOOTSTRAP.md`. - -## Core distinctions - -### Research - -Canonical, shared, evidence-based repository knowledge. - -Research is not the primary teaching surface. - -### Shared material - -Reusable teaching content derived from research. - -Generic first-session exercises belong here when they are useful to most contributors. - -### Contributor trace - -A compact working file for notes, answers, questions, tailored follow-up, uncertainty, and durable personal takeaways. - -Do not duplicate shared material into personal files. - -### Learning section - -A conceptual depth or subtopic inside a material. - -Items at the same depth need not be sequential. - -### Learning session - -A single active cycle, normally 30 to 40 minutes. - -Split longer work into several sessions even when the contributor has more time. - -### Ticket path - -A temporary contributor-specific route through relevant learning materials for a concrete task. - -Keep ticket-specific details separate unless they become reusable verified knowledge. - -## Teaching behavior - -Act as a precise, adaptive teacher. - -- Begin with enough context to locate a topic in the system. -- Narrow gradually toward the contributor's task or ownership area. -- Connect local code to architecture, domain, runtime, testing, and constraints. -- Increase challenge incrementally. -- Prefer mental models, pseudocode, paths, and stable symbols over copied code. -- Use short source excerpts only when the exact pattern matters. -- Invite active engagement when it adds value. -- Do not invent exercises for trivial concepts. -- Let the contributor decline an optional practical task. -- Correct factual errors directly. -- Avoid numeric scores, confidence percentages, fake praise, and motivational filler. - -Use these progress states: - -- `introduced` -- `practising` -- `understood` -- `applied` - -Allow `understood` without an artificial implementation task. - -Reserve `applied` for demonstrated repository use. - -Complete a session only when both contributor and agent agree that its objective was met. - -A material may remain active across many sessions. - -## Default session shape - -A prepared session should normally include: - -1. objective; -2. expected 30 to 40 minute scope; -3. shorter variant when useful; -4. context and mental model; -5. vocabulary; -6. abstract example or pseudocode; -7. repository paths and stable symbols; -8. a few understanding checks; -9. optional active engagement; -10. expected takeaway; -11. deliberate boundaries and deferred topics. - -Do not reveal complete quiz answers beside the questions. - -## Stable identifiers - -Use: - -```text --- -``` - -Examples: - -```text -ARCH-0-FOUNDATIONS -ARCH-1-UI-COMPOSITION -ARCH-1-DATA-ACCESS -DOMAIN-0-CORE-VOCABULARY -DOMAIN-1-CURVE-FITTING -RUN-0-LOCAL-STARTUP -TEST-0-TEST-LANDSCAPE -FLOW-0-REPRESENTATIVE-FEATURE -``` - -- `FAMILY` identifies the broad material family. -- `DEPTH` indicates conceptual depth. -- Same-depth items are not necessarily sequential. -- Use separate display-order metadata where needed. -- Keep IDs stable when titles change. -- Number sessions within a material when several sessions belong to one section. - -Ticket paths use the repository ticket ID, such as `TICKET-ABC-123`. - -## Evidence and source of truth - -Use this precedence: - -1. verified runtime or data evidence; -2. current source, tests, and configuration; -3. repository documentation matching current implementation; -4. verified contributor explanation; -5. historical documentation; -6. agent inference. - -Mark whether a statement is: - -- verified from source; -- verified from configuration; -- verified from tests; -- verified from runtime evidence; -- reported by a contributor; -- inferred and awaiting confirmation. - -When sources disagree, record the disagreement. - -Do not infer real production behavior, usage frequency, data shape, or user workflow from source alone. - -## Runtime and database research - -When source cannot establish actual behavior: - -1. ask for safe access when appropriate; or -2. provide a precise query or observation procedure; -3. explain what the result would confirm or disprove; -4. accept sanitized, aggregate, anonymized, or context-only results; -5. record safe conclusions and provenance only. - -Never commit: - -- credentials; -- secrets; -- customer, patient, or personal data; -- proprietary datasets; -- raw production logs; -- sensitive query results. - -Anonymized context data may be stored only when it materially improves explanation. - -Research may end with a small number of focused A/B/C questions when necessary. - -## Research rules - -Prefer a useful map over exhaustive documentation. - -Initial architecture screening should identify, where applicable: - -- repositories and project groups; -- entry points; -- languages and framework versions; -- primary and legacy runtimes; -- UI and component frameworks; -- internal theming; -- broad architecture style; -- dependency injection or service location; -- reflection, plugin, or module loading; -- background services; -- data stores; -- integration boundaries; -- logging; -- tests; -- configuration; -- build and deployment shape; -- important recurring constraints; -- future research directions. - -Initial domain screening should identify: - -- product purpose; -- users and workflows; -- core vocabulary; -- engineering, business, scientific, or regulatory domains; -- important data types; -- major separable chunks; -- technically or mathematically deep areas; -- ownership-specific areas; -- facts requiring runtime evidence. - -Large domain chunks should receive their own materials while remaining visible in the foundation map. - -## Repository references - -Prefer: - -- repository identity; -- project or directory path; -- exact file path; -- stable class, interface, method, project name, command, configuration key, or heading; -- optional line number as a navigation hint; -- evidence type. - -Do not copy large repository code blocks. - -Use generic examples or pseudocode when they teach the pattern more clearly. - -## Freshness checks - -Every research topic and material must record: - -- repository baselines; -- last validation date; -- narrowly relevant watched locations; -- stable symbols or keys where practical. - -Before providing a new session from existing material: - -1. compare recorded baselines with current commits; -2. inspect changes only in watched locations; -3. check whether referenced symbols or behavior changed; -4. perform narrow update research when relevant; -5. explain briefly why revalidation was needed; -6. update research, material, and baseline metadata; -7. ask the user only when change is ambiguous, substantial, or requires runtime evidence. - -Do not rescan the whole repository for every session. - -Do not use line ranges as freshness triggers. - -Line numbers are navigation hints only. - -Validate multiple repositories independently. - -## Contributor identity - -For first personal use: - -1. inspect Git name and email; -2. infer a safe stable slug; -3. ask the contributor to confirm it; -4. create the contributor directory only after confirmation; -5. reuse the confirmed slug afterward. - -Do not store unnecessary personal information. - -## Personal trace rules - -Contributor files are working stubs, not diaries. - -After a contributor changes a file: - -1. inspect the Git diff and changed sections; -2. evaluate answers and notes; -3. answer questions; -4. correct misunderstandings; -5. rewrite raw notes into durable takeaways; -6. preserve unresolved uncertainty; -7. remove low-value raw fragments after integration; -8. add a brief integration marker when useful; -9. update progress; -10. compact completed conversation history; -11. update contributor tracking; -12. improve shared research or material when the interaction exposed a reusable gap. - -Do not preserve fragments such as: - -- `I have no clue`; -- typo-heavy notes; -- duplicated explanation; -- self-judgment; -- resolved confusion. - -Git history preserves the original edit. - -Keep crucial definitions, important personal examples, unresolved uncertainty, and demonstrated application references. - -## Improve material from interaction - -Treat contributor confusion as feedback on the material. - -When a response reveals a reusable omission: - -- improve the shared explanation; -- improve ordering or prerequisites; -- add or revise an example; -- add a misconception note; -- improve a quiz or exercise; -- promote verified repository findings into research. - -If multiple contributors misunderstand the same point, prioritize the improvement. - -Do this without waiting for an explicit request. - -Do not promote unverified personal interpretation. - -## Promotion rules - -Promote contributor findings when they are: - -- reusable; -- repository-specific; -- verified; -- relevant beyond one person or ticket; -- expensive to rediscover; -- helpful for responsible implementation or future teaching. - -Possible destinations: - -- canonical research; -- material explanations; -- common misconceptions; -- shared exercises; -- prerequisites; -- repository maps; -- known constraints; -- runtime research procedures. - -Do not automatically promote: - -- personal analogies; -- ticket-specific debugging history; -- transient implementation details; -- unverified claims; -- emotional reactions; -- confidence judgments; -- sensitive runtime data. - -## Learning selection - -When asked for a new topic without a specific target, provide three options based on: - -- current tickets or ownership; -- prerequisite gaps; -- contributor tracking; -- high-value unexplored areas; -- architectural and domain breadth; -- practical applicability; -- prepared material; -- cost of missing research. - -Prefer: - -1. one breadth-first system or domain topic; -2. one depth-first continuation; -3. one practical or ownership-related topic. - -For each option provide: - -- ID and title; -- why it is useful now; -- session scope; -- expected duration; -- whether research is ready. - -`Hit me with something new` must work without clarification when enough context exists. - -## Continue workflow - -When asked to continue: - -1. read contributor tracking; -2. locate the most recent active theme or ticket path; -3. inspect contributor edits; -4. validate freshness; -5. evaluate and compact prior work; -6. continue with the next small challenge. - -Do not ask the contributor to repeat information already in the files. - -## Ticket workflow - -When given a ticket: - -1. read the ticket; -2. locate likely ownership areas; -3. avoid jumping directly to the smallest implementation file; -4. identify architecture, domain, feature flow, runtime, testing, and constraints; -5. reuse existing material; -6. research only missing high-value context; -7. create a contributor ticket path; -8. propose the smallest responsible learning sequence; -9. keep implementation readiness distinct from learning completion. - -When the contributor is not in a rush, two or three learning cycles before implementation are often appropriate. - -Do not force the count when the ticket clearly needs less or more. - -## Practical engagement - -Do not modify application code unless the user explicitly requests implementation or experimentation. - -When useful, offer a focused activity such as: - -- trace and explain a call flow; -- add or extend a test; -- reproduce a behavior; -- inspect runtime output; -- perform a test-first refactor; -- compare implementations; -- review a relevant commit; -- run a safe database query; -- map configuration. - -Let the contributor decide. - -## Research depth - -Stay at most one useful session ahead. - -When the last prepared session is completed, prepare the next useful session automatically. - -Do not research several unused depths unless explicitly asked. - -For random useful research: - -1. inspect catalogue gaps; -2. choose a high-value or expensive-to-rediscover topic; -3. perform bounded screening or next-depth research; -4. update research and material when useful; -5. do not create a personal theme file unless someone starts learning it. - -## Known constraints - -Record important weaknesses and accepted constraints without blame. - -Where possible include: - -- description; -- evidence; -- affected areas; -- consequence; -- accepted workaround; -- likely reason; -- confidence; -- intentional, historical, inferred, or disputed status; -- ownership relevance. - -Do not convert uncertain criticism into fact. - -## Multi-repository work - -Assume the current repository is sufficient unless inspection clearly shows related internal repositories are required. - -Strong signals include: - -- shared internal prefixes; -- sibling solutions or project references; -- internal package sources; -- build scripts expecting neighboring repositories; -- common libraries maintained together; -- system documentation describing repository splits. - -When needed, ask the user to choose among: - -- current checkouts; -- sibling paths; -- existing submodules; -- submodules on a dedicated learning branch; -- current repository only. - -Do not force one branch or submodule strategy. - -Record each repository and baseline separately in `REPOSITORIES.md`. - -## Git and review - -The expected scale is one or two contributors. - -Use stable headings and small coherent edits so conflicts are easy to reconcile. - -Do not overengineer concurrency. - -Do not commit, push, merge, or alter branches without explicit user instruction. - -After framework or research generation, stop with: - -- files changed; -- important findings; -- uncertainty; -- required user input; -- exact review scope. - -## Initial bootstrap - -When `BOOTSTRAP.md` applies, screen: - -1. system and repository architecture; -2. build, run, configuration, and debugging; -3. core product and engineering domain; -4. testing and quality practices; -5. one representative end-to-end feature path. - -Create first-session material for all five. - -Prepare a second session only for the highest-value themes. - -Do not create active personal learning files until the contributor chooses a topic. - -## Quality boundary - -Prefer: - -- Markdown; -- Git history; -- stable IDs; -- compact tables; -- repository evidence; -- small sessions; -- reusable research; -- minimal personal traces. - -Avoid: - -- custom infrastructure; -- duplicated knowledge; -- huge copied code blocks; -- exhaustive upfront research; -- arbitrary scores; -- stale line-based tracking; -- automatic application changes; -- automatic commits; -- permanent conversational logs; -- unsupported production assumptions. diff --git a/sample/learning-flow/BOOTSTRAP.md b/sample/learning-flow/BOOTSTRAP.md deleted file mode 100644 index 3874dac..0000000 --- a/sample/learning-flow/BOOTSTRAP.md +++ /dev/null @@ -1,102 +0,0 @@ -# Initial Research Bootstrap - -Follow this file after the learning-flow framework has been installed. - -Do not recreate the framework. Populate it from the actual repository. - -## Constraints - -- Read the repository's root agent instructions first. -- Follow `learning-flow/AGENTS.md`. -- Do not modify application code. -- Do not add submodules or change repository layout without user approval. -- Do not commit. -- Stop with reviewable working-tree changes. - -## Step 1: Inspect and establish scope - -Inspect: - -- repository layout; -- solutions, workspaces, projects, packages, and entry points; -- existing documentation; -- build and test commands; -- configuration; -- Git branch and current commit; -- likely related internal repositories; -- existing root and nested agent instructions. - -If related repositories are clearly required, ask the user how they are available before researching them. - -Record repository identities and baselines in `REPOSITORIES.md`. - -## Step 2: Confirm contributor identity - -Inspect Git name and email. - -Infer a filesystem-safe contributor slug and ask the user to confirm it before creating personal files. - -Create: - -```text -contributors// -├── README.md -├── TRACKING.md -├── themes/ -└── ticket-paths/ -``` - -Use the templates and keep personal information minimal. - -## Step 3: Screen the five bootstrap themes - -Research all five at a bounded screening depth: - -1. system and repository architecture; -2. build, run, configuration, and debugging; -3. core product and engineering domain; -4. testing and quality practices; -5. one representative end-to-end feature path. - -For each theme: - -- create a canonical research topic; -- record evidence and uncertainty; -- record repository baselines and watched locations; -- identify prerequisites and related ownership areas; -- create a useful first learning session; -- record what should be researched next. - -Do not attempt exhaustive coverage. - -## Step 4: Select second-session material - -Prepare a second session only for the highest-value themes. - -Architecture and domain are common candidates, but decide from repository evidence. - -Do not prepare two sessions for all five by default. - -## Step 5: Update catalogues - -Update: - -- `research/README.md`; -- `materials/README.md`; -- `REPOSITORIES.md`; -- meaningful research history. - -Do not create an active personal learning file until the contributor chooses a topic. - -## Step 6: Stop for review - -Report: - -- files created or changed; -- major findings; -- uncertain claims; -- runtime or database evidence still needed; -- proposed three first learning options; -- exact Git status. - -Leave everything uncommitted. diff --git a/sample/learning-flow/README.md b/sample/learning-flow/README.md deleted file mode 100644 index 460ff18..0000000 --- a/sample/learning-flow/README.md +++ /dev/null @@ -1,155 +0,0 @@ -# Learning Flow - -This directory contains the repository's continuous learning system. - -It separates reusable repository knowledge from teaching material and contributor-specific working notes. - -## Concepts - -### Repository research - -Canonical, evidence-based knowledge about architecture, domain concepts, runtime behavior, project boundaries, recurring practices, constraints, and open questions. - -Location: `research/` - -### Shared learning material - -Reusable teaching content derived from research. A material can contain several depths and several short learning sessions. - -Location: `materials/` - -### Contributor trace - -A compact personal workspace for active questions, answers, durable takeaways, uncertain knowledge, progress, and ticket-oriented routes. - -Location: `contributors//` - -### Learning section - -A depth or subtopic in a learning material. Several sections may exist at the same depth. - -### Learning session - -One active study cycle, normally 30 to 40 minutes. A section may require several sessions. - -### Ticket learning path - -A temporary route through existing and newly researched material for a concrete task. It should provide surrounding architecture, domain, runtime, testing, and ownership context instead of jumping directly to the smallest implementation file. - -## Start here - -After the framework is installed, ask the agent: - -```text -Read learning-flow/AGENTS.md and learning-flow/BOOTSTRAP.md. -Inspect the repository, confirm my contributor slug, and perform the initial -research build. Do not modify application code and do not commit. -``` - -## Common requests - -```text -Hit me with something new. -Give me three useful next topics. -Continue my last learning topic. -Teach me a small domain concept based on what I already know. -I have ticket ABC-123. Build a learning path before implementation. -Research the next useful depth for module A. -Prepare deeper research for module A and module B. -Evaluate my changes in learning-flow/contributors//themes/.md. -Do a useful research pass, but do not start a personal learning session. -``` - -The user should not need to restate the workflow. - -## Directory map - -```text -learning-flow/ -├── README.md -├── AGENTS.md -├── BOOTSTRAP.md -├── REPOSITORIES.md -├── research/ -│ ├── README.md -│ └── topics/ -├── materials/ -│ ├── README.md -│ └── themes/ -├── contributors/ -└── templates/ -``` - -## Progress states - -- `introduced`: the contributor has encountered the concept. -- `practising`: the contributor is actively working through it. -- `understood`: the contributor can explain and reason about it. -- `applied`: the contributor has demonstrated it in repository work. - -`understood` does not require an artificial exercise. Reserve `applied` for demonstrated use. - -A session is complete only when the contributor and agent agree that its objective was met. - -## Personal-note lifecycle - -Contributor files are working surfaces, not permanent chat transcripts. - -After the contributor edits a learning file, the agent should: - -1. inspect the Git diff; -2. evaluate answers and questions; -3. correct misunderstandings; -4. rewrite raw notes into durable takeaways; -5. preserve important uncertainty; -6. improve shared material when the interaction exposed a reusable weakness; -7. compact resolved session history. - -Git already preserves the original wording. - -## Freshness - -Shared research and material record: - -- repository baselines; -- relevant paths and narrow glob patterns; -- stable classes, methods, interfaces, project names, configuration keys, or headings. - -Before teaching a new session, the agent checks only those watched locations since the last validated commit. - -Line numbers are navigation hints, not freshness anchors. - -## Related repositories - -The learning flow may cover several repositories. - -Do not add submodules or change repository layout automatically. When related internal repositories are clearly required, the agent should ask which access method to use: - -- existing submodules; -- sibling checkouts; -- submodules on a dedicated learning branch; -- already available local paths; -- current repository only. - -Record each repository and baseline separately in `REPOSITORIES.md`. - -## Safety - -Never commit: - -- credentials or secrets; -- customer or patient data; -- personal data; -- proprietary datasets; -- raw production logs; -- sensitive database query results. - -When runtime evidence is needed, the agent may ask for safe access or provide a query for the user to execute. Store only sanitized conclusions and provenance. - -## Git workflow - -The learning flow can live on a permanent dedicated branch, on the main branch, or in another team-approved arrangement. - -Agents must not commit automatically. - -Keep changes small and sectioned so one or two contributors can resolve conflicts with a focused agentic merge. diff --git a/sample/learning-flow/REPOSITORIES.md b/sample/learning-flow/REPOSITORIES.md deleted file mode 100644 index 2808453..0000000 --- a/sample/learning-flow/REPOSITORIES.md +++ /dev/null @@ -1,25 +0,0 @@ -# Repository Registry - -Record every repository used by the learning flow separately. - -| Logical name | Local path | Remote or origin | Branch | Baseline commit | Access method | Last checked | Notes | -|---|---|---|---|---|---|---|---| - -## Access methods - -Examples: - -- current repository; -- sibling checkout; -- existing submodule; -- learning-branch submodule; -- read-only external checkout. - -Do not add or modify submodules without user approval. - -## Baseline rules - -- Record the exact commit used during research. -- Validate each repository independently. -- Update a baseline only after checking watched locations relevant to the affected research. -- Do not imply that all repositories were synchronized unless that was verified. diff --git a/sample/learning-flow/contributors/README.md b/sample/learning-flow/contributors/README.md deleted file mode 100644 index 2a29e79..0000000 --- a/sample/learning-flow/contributors/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# Contributors - -Each contributor receives a compact personal workspace: - -```text -contributors// -├── README.md -├── TRACKING.md -├── themes/ -└── ticket-paths/ -``` - -## Identity - -Before the first personal write: - -1. inspect Git name and email; -2. infer a filesystem-safe stable slug; -3. ask the contributor to confirm it; -4. create the directory only after confirmation. - -Do not store unnecessary personal information. - -## Personal files - -Personal files should contain: - -- current objective; -- compact prior takeaways; -- contributor questions and answers; -- unresolved uncertainty; -- tailored follow-up; -- progress; -- demonstrated applications. - -They should not duplicate the complete shared material. - -After evaluation, normalize raw notes and compact resolved interaction history. - -## Shared improvement - -When contributor confusion reveals a reusable weakness, improve shared research or material and keep the personal trace minimal. diff --git a/sample/learning-flow/materials/README.md b/sample/learning-flow/materials/README.md deleted file mode 100644 index 132293e..0000000 --- a/sample/learning-flow/materials/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# Shared Learning Materials - -Reusable teaching material lives in `materials/themes/`. - -| ID | Material | Prepared depth | Next depth | Priority | Prerequisites | Typical session length | Status | -|---|---|---|---|---|---|---|---| - -## Rules - -- Derive material from canonical research. -- Reference research instead of duplicating its evidence. -- Plan sessions for 30 to 40 minutes by default. -- Offer shorter variants when useful. -- Split long content into several sessions. -- Stay at most one useful session ahead unless deeper research is requested. -- Store generic exercises here. -- Store tailored questions, answers, and follow-up in contributor files. -- Improve shared explanations whenever contributor confusion reveals a reusable gap. -- Validate watched repository locations before providing a new session. diff --git a/sample/learning-flow/materials/themes/README.md b/sample/learning-flow/materials/themes/README.md deleted file mode 100644 index 413ba14..0000000 --- a/sample/learning-flow/materials/themes/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Learning Themes - -Create one file per stable material ID. - -Use `learning-flow/templates/learning-material.md`. - -A theme can contain several learning sections and several prepared sessions. - -Do not create a new file for every contributor or every learning session. Personal active work belongs under `contributors//themes/`. diff --git a/sample/learning-flow/research/README.md b/sample/learning-flow/research/README.md deleted file mode 100644 index 4182733..0000000 --- a/sample/learning-flow/research/README.md +++ /dev/null @@ -1,55 +0,0 @@ -# Repository Research Catalogue - -Canonical repository knowledge lives in `research/topics/`. - -| ID | Topic | Status | Priority | Value | Depth | Confidence | Last validated | Primary repositories | -|---|---|---|---|---|---|---|---|---| - -## Metadata - -### Status - -- `empty` -- `screened` -- `researched` -- `needs-runtime-evidence` -- `stale` -- `superseded` - -### Priority - -- `low` -- `medium` -- `high` -- `critical` - -### Value - -- `low` -- `medium` -- `high` - -### Confidence - -- `hypothesis` -- `source-supported` -- `runtime-supported` -- `verified` - -## Research rules - -- Keep canonical facts here rather than in contributor traces. -- Record evidence and uncertainty separately. -- Reference repository paths and stable symbols. -- Use line numbers only as navigation hints. -- Record watched locations for narrow Git revalidation. -- Promote reusable verified findings from contributor interaction. -- Do not infer production behavior from source alone. -- Store no sensitive runtime data. - -## Meaningful change history - -Record substantial additions, corrections, promotions, and revalidations. Do not record typo-only edits. - -| Date | Commit or baseline | Research change | Trigger | Contributor or process | Related IDs | -|---|---|---|---|---|---| diff --git a/sample/learning-flow/research/topics/README.md b/sample/learning-flow/research/topics/README.md deleted file mode 100644 index 5a1cb3e..0000000 --- a/sample/learning-flow/research/topics/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# Research Topics - -Create one canonical file per stable topic ID. - -Use `learning-flow/templates/research-topic.md`. - -A topic should contain: - -- scope and value; -- current understanding; -- architectural or domain map; -- evidence and repository references; -- known constraints; -- runtime or data questions; -- uncertainty; -- related materials; -- next research direction; -- validation history. - -Keep teaching structure in `materials/themes/`. Keep contributor-specific interaction in `contributors/`. diff --git a/sample/learning-flow/templates/contributor-readme.md b/sample/learning-flow/templates/contributor-readme.md deleted file mode 100644 index 4a65dc7..0000000 --- a/sample/learning-flow/templates/contributor-readme.md +++ /dev/null @@ -1,40 +0,0 @@ -# Contributor Learning Workspace - -Contributor slug: `` - -## Purpose - -This directory stores compact contributor-specific learning state. - -Shared research and reusable teaching content remain under: - -- `learning-flow/research/` -- `learning-flow/materials/` - -## Workflow - -- Active themes live in `themes/`. -- Ticket-oriented routes live in `ticket-paths/`. -- Overall progress lives in `TRACKING.md`. -- Edit the contributor workspace in an active theme file. -- Ask the agent to evaluate the changed file. -- The agent should inspect the Git diff, correct misunderstandings, answer questions, normalize notes, update progress, and compact resolved history. - -## Progress states - -- `introduced` -- `practising` -- `understood` -- `applied` - -`understood` does not require an artificial task. - -`applied` requires demonstrated repository use. - -## Continue - -A request such as the following should be enough: - -```text -Continue my last learning topic. -``` diff --git a/sample/learning-flow/templates/contributor-theme.md b/sample/learning-flow/templates/contributor-theme.md deleted file mode 100644 index f60031c..0000000 --- a/sample/learning-flow/templates/contributor-theme.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -material_id: -contributor: -status: introduced -current_section: 0 -current_session: 1 -last_interaction: ---- - -# : - -## Shared material - -`learning-flow/materials/themes/<MATERIAL-ID>.md` - -## Why this matters to me - -## Compacted prior takeaways - -Keep durable understanding, crucial definitions, important personal examples, and unresolved uncertainty. - -## Current session objective - -## Current explanation and references - -Reference shared material. Add only tailored context. - -## Contributor workspace - -Edit this section with notes, answers, questions, or uncertainty. - -## Questions and answers - -## Optional active engagement - -## Agent evaluation - -The agent rewrites raw notes into durable takeaways, corrects errors, and records whether the objective appears met. - -## Remaining uncertainty - -## Next step - -## Compact interaction history - -| Date | Session | Result | Important change | -|---|---|---|---| diff --git a/sample/learning-flow/templates/contributor-tracking.md b/sample/learning-flow/templates/contributor-tracking.md deleted file mode 100644 index 8593c21..0000000 --- a/sample/learning-flow/templates/contributor-tracking.md +++ /dev/null @@ -1,44 +0,0 @@ -# Contributor Learning Tracking - -Contributor: `<slug>` - -## Current focus - -## Active materials - -| Material ID | Current section | Current session | State | Last interaction | Next step | -|---|---|---|---|---|---| - -## Ticket-oriented paths - -| Ticket ID | Purpose | State | Related materials | Next step | -|---|---|---|---|---| - -## Exposure map - -| Material ID | State | First exposed | Last reviewed | Notes | -|---|---|---|---|---| - -## Durable takeaways - -Keep only contributor-specific takeaways that are not already clear from shared material. - -## Uncertain or fragile knowledge - -## Applied knowledge - -| Date | Material ID | Repository activity | Evidence | -|---|---|---|---| - -## Suggested next directions - -Prefer a balanced set: - -1. breadth-first architecture or domain; -2. depth-first continuation; -3. practical or ownership-related topic. - -## Compact history - -| Date | Change | Related IDs | -|---|---|---| diff --git a/sample/learning-flow/templates/learning-material.md b/sample/learning-flow/templates/learning-material.md deleted file mode 100644 index 1c56a83..0000000 --- a/sample/learning-flow/templates/learning-material.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -id: <FAMILY>-<DEPTH>-<SLUG> -title: <title> -family: <FAMILY> -depth: 0 -display_order: 0 -status: draft -priority: medium -value: high -prerequisites: [] -related_research: [] -related_materials: [] -ownership_relevance: [] -prepared_sessions: 1 -last_validated: <YYYY-MM-DD> -watched_locations: [] -next_research_direction: <next bounded session> ---- - -# <ID>: <Title> - -## Material purpose - -## Eventual understanding - -## Prerequisites - -## Mental model - -## Vocabulary - -| Term | Meaning | Common confusion | -|---|---|---| - -## Learning sections - -### Section 0: <foundation> - -#### Session 1 - -**Objective** - -**Default scope:** 30 to 40 minutes - -**Short variant** - -**Context** - -**Abstract example or pseudocode** - -**Repository map** - -| Repository | Path | Stable symbol or key | Why it matters | -|---|---|---|---| - -**Understanding checks** - -1. -2. -3. - -**Optional active engagement** - -Ask whether the contributor wants to do this. Do not make up work for a simple concept. - -**Expected takeaways** - -**Deliberately deferred** - -## Common misconceptions - -## Known constraints - -## Related materials - -## Current depth and next research direction - -## Validation notes diff --git a/sample/learning-flow/templates/research-topic.md b/sample/learning-flow/templates/research-topic.md deleted file mode 100644 index 2b150e2..0000000 --- a/sample/learning-flow/templates/research-topic.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -id: <FAMILY>-<DEPTH>-<SLUG> -title: <title> -status: empty -priority: medium -value: high -depth: 0 -confidence: hypothesis -prerequisites: [] -related_materials: [] -related_ownership_areas: [] -repositories: [] -baseline_commits: {} -last_validated: <YYYY-MM-DD> -watched_locations: [] -next_research_direction: <next bounded question> ---- - -# <ID>: <Title> - -## Scope - -## Why this matters - -## Current understanding - -Separate verified facts from inference. - -## Architectural or domain map - -## Evidence and repository references - -| Repository | Path | Stable symbol or key | Navigation hint | Evidence type | Supports | -|---|---|---|---|---|---| - -## Known constraints and by-design problems - -| Constraint | Evidence | Consequence | Workaround | Status | Confidence | -|---|---|---|---|---|---| - -## Runtime or data questions - -For each question, state what evidence is needed and what it would confirm. - -## Uncertainty and competing interpretations - -## Related topics - -## What should be researched next - -Keep this to the next useful depth. - -## Validation history - -| Date | Baseline commits | Validation scope | Result | Trigger | -|---|---|---|---|---| diff --git a/sample/learning-flow/templates/ticket-learning-path.md b/sample/learning-flow/templates/ticket-learning-path.md deleted file mode 100644 index e7ee9af..0000000 --- a/sample/learning-flow/templates/ticket-learning-path.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -ticket_id: <TICKET-ID> -contributor: <slug> -status: planning -created: <YYYY-MM-DD> -related_materials: [] -related_research: [] ---- - -# <TICKET-ID>: Learning Path - -## Ticket summary - -## Learning intent - -## Relevant ownership area - -## What should be understood before implementation - -## Existing relevant materials - -## Missing research - -## Proposed learning route - -Balance: - -- system context; -- domain context; -- feature or module context; -- testing and observability; -- local implementation path. - -## Session plan - -| Session | Objective | Material | Expected duration | State | -|---|---|---|---|---| - -## Runtime or data questions - -## Implementation readiness - -Keep this separate from learning completion. - -## Reusable findings worth promoting - -## Ticket-specific details that should remain local - -## Current state diff --git a/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md b/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md index 768f9e1..e8e1f82 100644 --- a/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md +++ b/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md @@ -9,7 +9,7 @@ Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for planning, app Read `learning-flow/AGENTS.md`. Load only the relevant map, tests, and canonical findings. -1. Define observable behavior and constraints. +1. Define the actor, intended outcome, capability, observable behavior, and governing invariants. 2. Search by behavior and tests, not name alone. 3. Compare the strongest candidates across entry point, domain rules, data flow, configuration, interface, tests, and operational effects. 4. Select the nearest valid analogue. diff --git a/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md b/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md index fcfd137..d23d2d4 100644 --- a/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md +++ b/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md @@ -7,9 +7,9 @@ description: Diagnose or teach through a concrete bug, failing test, intermitten Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for planning, approvals, validation depth, records, and handoff. This skill owns only the learning-specific task procedure. -Read `learning-flow/AGENTS.md`. Load only material for the affected territory. +Read `learning-flow/AGENTS.md`. Load only material for the affected territory. Use `templates/challenge.md` only when the user explicitly wants a durable challenge artifact; keep a contributor-specific instance under `.local/` and use a tracked location only after deliberate shared promotion. -1. State observable symptom and falsifiable expected behavior. +1. State the affected outcome or rule, observable symptom, and falsifiable expected behavior. 2. Find the smallest discriminating reproduction, test, trace, or log. 3. Rank only credible hypotheses and test one uncertainty at a time. 4. Explain the failure mechanism before changing code. @@ -19,4 +19,4 @@ Read `learning-flow/AGENTS.md`. Load only material for the affected territory. Use at most one prediction or explain-back when consequential. Do not keep a hypothesis diary. -Report symptom, expectation, decisive evidence, mechanism, fix or seam, regression proof, untested boundary, and compact recap. +Report symptom, expectation, decisive evidence, mechanism, fix or seam, regression proof, and the untested boundary. Fold in a useful learning point only when it adds value beyond the normal handoff. diff --git a/sample/profiles/full/learning-flow/templates/challenge.md b/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md similarity index 69% rename from sample/profiles/full/learning-flow/templates/challenge.md rename to sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md index 96dcb3a..3a17abd 100644 --- a/sample/profiles/full/learning-flow/templates/challenge.md +++ b/sample/profiles/full/.agents/skills/challenge-debugging/templates/challenge.md @@ -12,14 +12,12 @@ _Use at most one when consequential._ -## Recap +## Reusable learning (optional) - **Model:** -- **Where:** - **Evidence:** - **Boundary:** -- **Transfer:** ## Promotion decision -_Keep conversational, update map/takeaways, or create canonical research. State why._ +_Keep conversational, update map/takeaways, or create a durable repository artifact. State why._ diff --git a/sample/profiles/full/.agents/skills/change-explainer/SKILL.md b/sample/profiles/full/.agents/skills/change-explainer/SKILL.md index 2ed4bf3..0cf9def 100644 --- a/sample/profiles/full/.agents/skills/change-explainer/SKILL.md +++ b/sample/profiles/full/.agents/skills/change-explainer/SKILL.md @@ -7,14 +7,14 @@ description: Explain a non-trivial diff, pull request, or agent-produced impleme Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for planning, approvals, validation depth, records, and handoff. This skill owns only the learning-specific task procedure. -Read `learning-flow/AGENTS.md`. Use `templates/change-explainer.md` only when a persistent artifact is warranted. +Read `learning-flow/AGENTS.md`. Use `templates/change-explainer.md` only when the user explicitly wants a durable artifact; keep a contributor-specific instance under `.local/` and use a tracked location only after deliberate shared promotion. 1. Establish exact change range and intended outcome. -2. Explain relevant behavior and architecture before the diff. +2. Explain the intended outcome, governing rules or invariants, and relevant architecture before the diff. 3. Walk through changed files in conceptual execution order. 4. Record decisions, rejected alternatives, risks, and unchanged contracts. 5. Connect claims to tests or safe runtime evidence. 6. Use at most one understanding check unless the user explicitly requests a quiz covering independent mechanisms. -7. End with a compact reinforcing recap. +7. Fold up to three useful learning points into the normal handoff; do not add a second recap. Keep the explanation conversational unless it meets the persistence threshold. Promote durable findings to their canonical owner and keep temporary review detail temporary. diff --git a/sample/profiles/full/learning-flow/templates/change-explainer.md b/sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md similarity index 83% rename from sample/profiles/full/learning-flow/templates/change-explainer.md rename to sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md index 9ee92f5..26e5f13 100644 --- a/sample/profiles/full/learning-flow/templates/change-explainer.md +++ b/sample/profiles/full/.agents/skills/change-explainer/templates/change-explainer.md @@ -14,10 +14,8 @@ ## Optional understanding check -## Reinforcing recap +## Reusable learning (optional) - **Model:** -- **Where:** - **Evidence:** - **Boundary:** -- **Transfer:** diff --git a/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md index cd05e29..f75eda5 100644 --- a/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md +++ b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md @@ -1,6 +1,6 @@ --- name: learning-bootstrap -description: Create or refresh a compact repository baseline covering boundaries, vocabulary, build and proof entry points, and one representative path. Use for first population or deliberate baseline refresh; do not generate curricula, sessions, contributor files, explainers, or labs. +description: Create or refresh a compact repository baseline covering a domain slice, boundaries, build and proof entry points, and one representative path. Use for first population or deliberate baseline refresh; do not generate curricula, sessions, contributor files, explainers, or labs. --- # Learning bootstrap @@ -9,14 +9,14 @@ Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for planning, app Read `learning-flow/AGENTS.md` and `learning-flow/BOOTSTRAP.md`. Load no other learning-flow file until needed. -1. Inspect repository instructions, shape, entry points, build/test commands, configuration, branch, and commit. If explanation depth depends on unknown user experience, ask the optional full-profile learner-context A/B/C/D question once. -2. Read `agentic-flow/LEARN.md` and map the actual agentic setup: root and nested instructions, tool-specific files, installed and custom skills, prompts, plans, records, effective precedence, and temporary evidence locations. -3. When template markers exist, treat managed template files as known and inspect only integration, custom additions, overrides, and conflicts. +1. Inspect repository instructions, shape, entry points, build/test commands, and relevant configuration. If explanation depth depends on unknown user experience, ask the optional full-profile learner-context A/B/C/D question once. +2. Recognize template markers and root integration quietly. Do not write a normal template status to `MAP.md`. +3. Read `agentic-flow/LEARN.md` only when custom instructions, competing skills, unresolved precedence, or stale records materially affect the work. Record only durable exceptions worth reusing. 4. Update `REPOSITORIES.md` only for repositories actually needed. -5. Create a compact `MAP.md` with the agentic collaboration map, major boundaries, vocabulary, proof entry points, and one representative code or domain path. +5. Create a compact `MAP.md` with major boundaries, one domain slice, proof entry points, and one representative code or domain path. 6. Add only already-qualified durable lessons to `TAKEAWAYS.md`. 7. Stop with reviewable, uncommitted changes. Do not screen fixed themes, prepare sessions, or modify application code. -Report a concise baseline first: effective instruction order, map entry point, representative path, build/test commands, uncertainty, and useful next task. Put long inventories, secondary evidence, and Git detail in collapsible sections when presenting Markdown. +Report a concise baseline first: map entry point, representative path, build/test commands, uncertainty, and one useful next task. Mention instruction order only when a custom rule or conflict affects work. Put long inventories and secondary evidence in collapsible sections when presenting Markdown. diff --git a/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md b/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md index 5a012f8..012da66 100644 --- a/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md +++ b/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md @@ -10,12 +10,12 @@ Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for planning, app Read `learning-flow/AGENTS.md`, then only relevant parts of `MAP.md`, `TAKEAWAYS.md`, and canonical research. 1. If the repository agentic setup is not mapped, identify its effective instruction order and custom surfaces using `agentic-flow/LEARN.md`. -2. Frame the code or domain territory and intended use. -3. Show boundaries and vocabulary before file detail. +2. Frame the intended use, actor or caller, outcome, capability, and governing rule when relevant. +3. Show a compact domain slice and boundaries before file detail. 4. Trace one representative execution or data path. 5. Connect claims to source, tests, configuration, safe runtime evidence, or explicit inference. 6. Identify the important constraint and highest-value unknown. -7. Stop when the user can locate the territory and describe its responsibility. +7. Stop when the user can locate the territory, describe its responsibility, and connect implementation to the intended outcome. Ask at most one consequential trace, prediction, or explain-back. Create or update an artifact only when the persistence threshold is met. diff --git a/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md b/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md index 494677c..ba82ace 100644 --- a/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md +++ b/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md @@ -9,7 +9,7 @@ Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for planning, app Read `learning-flow/AGENTS.md`. Load only material for the affected contract and territory. -1. State observable behavior that must remain stable and internals allowed to change. +1. State the behavior or domain invariant that must remain stable, its observable contract, and internals allowed to change. 2. Inspect existing proof and add characterization only where necessary. 3. Identify the smallest safe seam. 4. Apply reviewable transformations. @@ -19,4 +19,4 @@ Read `learning-flow/AGENTS.md`. Load only material for the affected contract and Ask at most one check about the preserved contract or new responsibility boundary. -Report contract, evidence before and after, transformation sequence, simplification, remaining risk, and recap. +Report the contract, evidence before and after, transformation sequence, simplification, and remaining risk. Fold in a useful learning point only when it adds value beyond the normal handoff. diff --git a/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md b/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md index 24e8aa0..c346279 100644 --- a/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md +++ b/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md @@ -7,10 +7,10 @@ description: Turn a real issue or planned change into a short repository learnin Follow `agentic-flow/AGENTS.md` and `agentic-flow/SETTINGS.md` for planning, approvals, validation depth, records, and handoff. This skill owns only the learning-specific task procedure. -Read `learning-flow/AGENTS.md`. Use `templates/ticket-learning-path.md` only when a durable ticket artifact is justified. +Read `learning-flow/AGENTS.md`. Use `templates/ticket-learning-path.md` only when the user explicitly wants a durable ticket artifact; keep a contributor-specific instance under `.local/` and use a tracked location only after deliberate shared promotion. -1. Read and classify the ticket as bug, feature, refactor, review, or exploration. -2. Locate likely ownership and one representative path. +1. Read and classify the ticket, then state the actor or caller, intended outcome, capability, and governing rule when relevant. +2. Locate likely ownership and one representative path from trigger to effect. 3. Reuse existing map, takeaways, and research before reading broadly. 4. Fill only high-value missing context. 5. Propose the shortest responsible route, usually one to three steps. diff --git a/sample/profiles/full/learning-flow/templates/ticket-learning-path.md b/sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md similarity index 100% rename from sample/profiles/full/learning-flow/templates/ticket-learning-path.md rename to sample/profiles/full/.agents/skills/ticket-learning-path/templates/ticket-learning-path.md diff --git a/sample/profiles/full/learning-flow/.managed-files b/sample/profiles/full/learning-flow/.managed-files index d6c07ad..c0a4695 100644 --- a/sample/profiles/full/learning-flow/.managed-files +++ b/sample/profiles/full/learning-flow/.managed-files @@ -7,19 +7,3 @@ AGENTS.md BOOTSTRAP.md PLAYBOOKS.md UNDERSTANDING_CHECKS.md -contributors/README.md -explainers/README.md -labs/README.md -materials/README.md -materials/themes/README.md -research/README.md -research/topics/README.md -templates/challenge.md -templates/change-explainer.md -templates/contributor-readme.md -templates/contributor-theme.md -templates/contributor-tracking.md -templates/lab-readme.md -templates/learning-material.md -templates/research-topic.md -templates/ticket-learning-path.md diff --git a/sample/profiles/full/learning-flow/.template-version b/sample/profiles/full/learning-flow/.template-version index be14282..faef31a 100644 --- a/sample/profiles/full/learning-flow/.template-version +++ b/sample/profiles/full/learning-flow/.template-version @@ -1 +1 @@ -0.5.3 +0.7.0 diff --git a/sample/profiles/full/learning-flow/AGENTS.md b/sample/profiles/full/learning-flow/AGENTS.md index 3a4a614..319ef63 100644 --- a/sample/profiles/full/learning-flow/AGENTS.md +++ b/sample/profiles/full/learning-flow/AGENTS.md @@ -6,7 +6,7 @@ Follow repository-native instructions and `agentic-flow/AGENTS.md` first. This f General collaboration pace, approval gates, planning, validation depth, records, commit policy, and handoff belong to `agentic-flow/`. Do not duplicate them here. -The compact initial baseline includes the repository's actual agentic setup as a learning territory. Recognize managed template files by their markers, then inspect root integration, custom instructions, tool-specific files, skills, prompts, plans, records, effective precedence, and unresolved conflicts. +For a requested initial baseline, recognize managed template files by their markers. Inspect root integration and custom agent surfaces only when they affect repository work or reveal unresolved precedence. A normal template installation needs no learning-map status. ## Select one primary learning workflow @@ -24,11 +24,9 @@ Do not load all skills. Do not use `agentic-workflow` as a second engineering pr Agents without task-skill support use `PLAYBOOKS.md`. -## Communication and tailoring +## Tailoring -Use friendly, concise, summary-first explanations. Start with the conceptual map, then reveal code-level or historical detail only when useful. In human-facing Markdown, use `<details>` for secondary evidence, long examples, alternatives, and command output. Keep essential warnings and decisions visible. - -When the user's experience cannot be inferred and it materially changes useful scaffolding, ask the optional full-profile learner-context A/B/C/D question in `agentic-flow/CONFIGURE.md`. Do not ask routinely, classify automatically, or repeat the question after enough context exists. +Start with the conceptual map, then reveal code or history only when useful. Ask the optional learner-context question from `agentic-flow/CONFIGURE.md` only when experience cannot be inferred and materially changes useful scaffolding; never classify automatically or ask again after enough context exists. ## Shared learning flow @@ -36,14 +34,16 @@ When the user's experience cannot be inferred and it materially changes useful s Locate → Reason → Work → Explain → Recap ``` -- Locate the relevant boundary, vocabulary, representative path, and proof surface. -- Reason from an explicit behavior contract, hypothesis, valid analogue, or safe seam. +- Locate the intended actor or caller, outcome, capability, governing rule, relevant boundary, representative path, and proof surface. Skip fields that add no value. +- Reason from an explicit domain invariant, behavior contract, hypothesis, valid analogue, or safe seam. - Work through the smallest responsible investigation or change under `agentic-flow/WORKFLOW.md`. - Explain through one brief retrieval or transfer check only when consequential and enabled by settings or request. -- Recap the model, location, evidence, boundary, and nearby transfer. +- Recap only useful learning by folding it into the normal handoff; do not create a second summary. Collapse or skip anything that adds no learning or engineering value. +Treat the selected territory as a system before diving into files. Choose only the useful parts of purpose or outcome, boundary, actors or components, relationships and flows, state changes or feedback, governing rules, evidence, and nearby transfer. Prefer one representative interaction over an inventory; this is a reasoning lens, not a required form. + ## Context economy - Search narrowly before reading broad directories, documentation, history, or generated files. @@ -62,20 +62,15 @@ Do not re-check the same concept unless later reasoning contradicts the earlier ## Persistence and ownership -Conversation is the default. Persist only verified, repository-specific findings likely to be reused and costly to rediscover. +Conversation is the default. Close meaningful learning sessions through `agentic-flow/LOCAL.md`. Promote only verified, repository-specific, non-sensitive findings likely to be reused and costly to rediscover; deduplicate explicit global-preservation requests first. Use one owner: -- `MAP.md`: compact boundaries, vocabulary, representative flows, and high-value unknowns; +- `MAP.md`: compact domain slices, boundaries, representative flows, and high-value unknowns; - `TAKEAWAYS.md`: concise reusable lessons; - `REPOSITORIES.md`: repository identity, baseline, and access boundary; -- `research/`: detailed canonical evidence and uncertainty; -- `materials/`: reusable teaching derived from research; -- `contributors/`: optional personal working traces; -- `explainers/`: warranted non-trivial change walkthroughs; -- `labs/`: bounded interactive harnesses. -Do not copy the same explanation across surfaces. Do not create contributor folders, challenge files, explainers, labs, sessions, or materials in advance. +Task-specific templates stay inside their owning skills until needed. Put contributor-specific instances under `.local/` and track one only after deliberate promotion. Prefer existing test and debug infrastructure; do not pre-create personal tracking, challenges, explainers, labs, sessions, research, or teaching material. ## Visual and evidence policy @@ -87,12 +82,4 @@ Rereading and agreement show exposure, not understanding. A sound explanation, p ## Completion -End meaningful learning work with three to six bullets that revisit: - -- central mechanism or model; -- architecture or domain placement; -- decisive evidence; -- important boundary, tradeoff, or corrected misconception; -- nearest useful transfer. - -Reuse and correct the user's own explanation when available. Store only durable takeaways, not a transcript. +Use the normal `agentic-flow` handoff. When learning was central, include only useful points about the model, decisive evidence, boundary, or transfer; reuse and correct the user's explanation when available. Do not add a second recap or store a transcript. diff --git a/sample/profiles/full/learning-flow/BOOTSTRAP.md b/sample/profiles/full/learning-flow/BOOTSTRAP.md index f7cbcb0..6b66674 100644 --- a/sample/profiles/full/learning-flow/BOOTSTRAP.md +++ b/sample/profiles/full/learning-flow/BOOTSTRAP.md @@ -1,29 +1,24 @@ # Compact repository learning baseline -Use this only for first learning-map population or a deliberate refresh. General agentic setup is initialized through `agentic-flow/ROOT_INTEGRATION.md` and `CONFIGURE.md`, but its actual repository integration is part of this baseline. +Use this only for a requested first learning-map population or deliberate refresh. General agentic setup is initialized through `agentic-flow/ROOT_INTEGRATION.md` and `CONFIGURE.md`; this baseline records only consequential custom exceptions. ## Constraints - Read root, nested, and tool-specific repository instructions, then `agentic-flow/AGENTS.md`. - Follow `learning-flow/AGENTS.md`. - Do not modify application code unless the user explicitly combines bootstrap with implementation. -- Do not create contributor folders, sessions, explainers, labs, or learning materials. +- Do not pre-generate personal tracking, sessions, explainers, labs, research, or learning materials. If bootstrap becomes a meaningful learning session, close its actual private state under `.local/`. - Do not exhaustively reread known managed template files. ## Baseline procedure -1. Inspect repository shape, entry points, existing documentation, build and test commands, configuration, current branch, and commit. -2. Inspect the repository's actual agentic setup using `agentic-flow/LEARN.md`: - - root, nested, and tool-specific instructions; - - installed and custom skills; - - prompts, plans, sessions, status files, ADRs, and evidence ledgers; - - effective precedence, ownership, and refresh rules. -3. When template markers exist, use the known template model and research only root integration, custom additions, overrides, and conflicts. -4. Record a compact agentic collaboration map in `MAP.md`. -5. Record repository identity and access boundaries in `REPOSITORIES.md` only when useful. -6. Populate the remaining `MAP.md` sections with major system boundaries, core domain vocabulary, build and proof entry points, one representative code or domain path, and a short list of high-value unknowns. -7. Add entries to `TAKEAWAYS.md` only when they already meet the persistence threshold. -8. Stop. +1. Inspect repository shape, entry points, existing documentation, build and test commands, and relevant configuration. +2. Recognize template markers and root integration quietly. Do not write a normal template status to `MAP.md`. +3. Use `agentic-flow/LEARN.md` only when custom instructions, tool-specific files, competing skills, unresolved precedence, or stale records materially affect the work. Record only durable differences or conflicts worth reusing. +4. Record repository identity and access boundaries in `REPOSITORIES.md` only when useful. +5. Populate the remaining `MAP.md` sections with major system boundaries, one compact domain slice, build and proof entry points, one representative code or domain path, and a short list of high-value unknowns. +6. Add entries to `TAKEAWAYS.md` only when they already meet the persistence threshold. +7. Stop. Do not screen a fixed list of themes. Do not generate sessions or research beyond what is needed for a usable baseline. @@ -31,10 +26,9 @@ Do not screen a fixed list of themes. Do not generate sessions or research beyon Follow `agentic-flow/WORKFLOW.md` for validation and handoff. Report: -- effective agentic instruction order and any unresolved overlap; -- selected learning profile and settings state; +- any instruction conflict that still affects work; - map entry point; - build and test entry points; - representative path; - uncertain claims; -- up to three useful next tasks. +- one useful next task when there is an obvious continuation. diff --git a/sample/profiles/full/learning-flow/MAP.md b/sample/profiles/full/learning-flow/MAP.md index 3045f11..a11db35 100644 --- a/sample/profiles/full/learning-flow/MAP.md +++ b/sample/profiles/full/learning-flow/MAP.md @@ -2,28 +2,21 @@ Keep this file compact and visual. It is an orientation surface, not an inventory. -## Agentic collaboration setup +## Agentic setup exceptions -Map this during the initial baseline. - -| Concern | Effective owner or path | Notes | -|---|---|---| -| Instruction order | _Not mapped yet._ | Root, nested, tool-specific, installed, and custom precedence | -| Stable repository policy | _Not mapped yet._ | Architecture, security, commands, conventions | -| Collaboration workflow | _Not mapped yet._ | Template profile, settings status, custom workflow | -| Task procedures | _Not mapped yet._ | Installed and custom skills or prompts | -| Learning support | _Not mapped yet._ | Profile, research surfaces, and activation rules | -| Temporary state and evidence | _Not mapped yet._ | Plans, sessions, status, ledgers, or conversation-only state | - -When template markers exist, treat managed content as known and map only integration, custom additions, overrides, and unresolved conflicts. +_None known. Treat managed content as known. Add only custom instructions, unresolved precedence, meaningful overlap, or stale state that will affect future work._ ## System boundaries _Not mapped yet._ -## Domain territories and vocabulary +## Domain slice -_Not mapped yet._ +Add one row per relevant territory, not a comprehensive business glossary. + +| Actor and outcome | Capability | Rule or invariant | Trigger and effect | Owning boundary and evidence | +|---|---|---|---|---| +| _Not mapped yet._ | | | | | ## Representative paths diff --git a/sample/profiles/full/learning-flow/PLAYBOOKS.md b/sample/profiles/full/learning-flow/PLAYBOOKS.md index 6e3eb0d..7feba02 100644 --- a/sample/profiles/full/learning-flow/PLAYBOOKS.md +++ b/sample/profiles/full/learning-flow/PLAYBOOKS.md @@ -8,11 +8,11 @@ Locate → Reason → Work → Explain → Recap | Task | Learning route | |---|---| -| Orientation | boundary map → vocabulary → representative path → constraint | -| Bug | symptom → expectation → decisive probe → mechanism → fix → regression proof | -| Analogous feature | behavior → valid analogue → invariants/differences → seam → implementation → proof | -| Refactor | preserved contract → evidence → smallest seam → transformation → proof → simplification | -| Change explanation | background → intuition → conceptual walkthrough → decisions/risks → proof | -| Ticket path | classify → ownership map → missing context → shortest route → named handoff or stop | +| Orientation | intended use → domain slice → boundary map → representative path → constraint | +| Bug | affected outcome/rule → symptom → expectation → decisive probe → mechanism → fix → proof | +| Analogous feature | actor/outcome → capability and invariants → valid analogue → differences → seam → proof | +| Refactor | behavior/domain invariant → evidence → smallest seam → transformation → proof → simplification | +| Change explanation | intended outcome → governing rules → conceptual walkthrough → decisions/risks → proof | +| Ticket path | actor/outcome → capability and ownership → missing context → shortest route → handoff or stop | -Use one understanding check only when consequential and enabled by the task or settings. Persist only verified, reusable findings. End meaningful learning work with a compact recap. +Use one understanding check only when consequential and enabled by the task or settings. Persist only verified, reusable findings. Fold useful learning into the normal handoff without adding a second recap. diff --git a/sample/profiles/full/learning-flow/README.md b/sample/profiles/full/learning-flow/README.md index 3cdacbd..55b99e1 100644 --- a/sample/profiles/full/learning-flow/README.md +++ b/sample/profiles/full/learning-flow/README.md @@ -8,7 +8,7 @@ This profile supports deliberate onboarding and long-lived repository understand Locate → Reason → Work → Explain → Recap ``` -The initial repository baseline also maps the actual agentic setup: existing root and tool-specific instructions, custom skills and prompts, the installed template integration, effective precedence, and temporary evidence locations. Known template files are not exhaustively re-researched. +A requested repository baseline recognizes managed agentic setup quietly. It maps custom instructions, skills, prompts, precedence, or stale evidence only when they affect work and will be useful again. Prediction, tracing, comparison, and challenge activities are used only when they improve reasoning. Planning, approval gates, validation depth, and handoff remain governed by `agentic-flow/`. @@ -16,34 +16,29 @@ Prediction, tracing, comparison, and challenge activities are used only when the | Surface | Purpose | |---|---| -| `MAP.md` | compact boundaries, vocabulary, representative paths, and high-value unknowns | +| `MAP.md` | compact domain slices, boundaries, representative paths, and high-value unknowns | | `TAKEAWAYS.md` | short verified lessons likely to be reused | | `REPOSITORIES.md` | repository identities, baselines, and access boundaries | -| `research/` | evidence-rich canonical findings | -| `materials/` | reusable teaching content derived from verified research | -| `contributors/` | optional personal working traces, created only on explicit need | -| `explainers/` | non-trivial change explanations that earn reuse | -| `labs/` | bounded synthetic harnesses when interaction materially improves understanding | -Conversation is the default. Do not create a file merely because a template exists. +Meaningful learning sessions keep complete private state, progress, check history, and compact continuation memory under ignored repository-root `.local/`. Task-specific challenge, ticket-path, and change-explainer templates travel inside their owning skills; put contributor-specific instances in `.local/` and promote only reusable, stable, non-sensitive knowledge to the tracked surfaces above. Prefer existing test and debug infrastructure over framework lab folders. ## Start -For a new repository, use `learning-bootstrap` to create only the compact baseline described in `BOOTSTRAP.md`. It must not pre-generate themes, sessions, contributor folders, explainers, or labs. +Use `learning-bootstrap` only when a compact baseline or deliberate onboarding pass is requested. An ordinary task in a new repository can start with the matching task skill. Bootstrap must not pre-generate themes, sessions, personal tracking, explainers, or labs. -After baseline creation, select one primary learning skill for the current task. The `agentic-workflow` skill is only for configuring or understanding the harness itself. +Select one primary learning skill for the current task. The `agentic-workflow` skill is only for configuring or understanding the harness itself. -## Understanding and recap +## Understanding and handoff Use at most one brief open checkpoint by default when misunderstanding would affect future reasoning and setting 4 allows it. A declined check never blocks engineering. -Every meaningful learning session ends with a compact three-to-six-bullet recap revisiting the central model, repository placement, decisive evidence, important boundary or corrected misconception, and nearest transfer. +When learning was central, fold up to three useful points about the model, decisive evidence, boundary, or transfer into the normal handoff. Skip them when the handoff already carries that value; never add a second recap section just to satisfy the framework. ## Artifact budget Create or update a persistent artifact only when the result is verified, repository-specific, likely to be reused, costly enough to rediscover, and owned by exactly one surface. -Contributor identity is never needed for shared repository learning. Personal tracking is explicit opt-in. +Contributor identity is never needed for shared repository learning. Personal tracking stays local and may use a contributor label only when needed to distinguish local learners. ## Communication diff --git a/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md b/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md index 87da1c3..f181022 100644 --- a/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md +++ b/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md @@ -31,9 +31,9 @@ Use multiple-choice only when distinguishing plausible mechanisms or misconcepti - Correct the mental model directly and briefly. - Ask one follow-up only when a central gap remains. - Never block engineering because a check was declined. -- Record `not checked` only when explicit personal tracking is active. +- Record `not checked` only in active private `.local/` learning history. - Do not infer broad competence from one answer. -## Session recap +## Learning handoff -The recap is not another check. Revisit the central model, placement, decisive evidence, important boundary or correction, and nearest transfer in three to six bullets. Reuse the user's explanation where sound. +When it helps, fold up to three points about the central model, placement, decisive evidence, boundary, correction, or transfer into the normal handoff. Reuse the user's explanation where sound. Do not add a separate recap or repeat delivery evidence. diff --git a/sample/profiles/full/learning-flow/contributors/README.md b/sample/profiles/full/learning-flow/contributors/README.md deleted file mode 100644 index 3ca2072..0000000 --- a/sample/profiles/full/learning-flow/contributors/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Optional contributor traces - -Shared repository learning does not require identity. - -Create `contributors/<slug>/` only when the user explicitly requests personal tracking, a durable personal theme, or a ticket-specific learning trace. Ask once for a filesystem-safe slug at that point. - -Personal files are working surfaces, not diaries. Keep evidence, durable takeaways, useful uncertainty, and next challenge. Do not maintain scores or transcripts. Promote reusable verified findings to the shared canonical surface and link back instead of copying them. diff --git a/sample/profiles/full/learning-flow/explainers/README.md b/sample/profiles/full/learning-flow/explainers/README.md deleted file mode 100644 index c98b4bf..0000000 --- a/sample/profiles/full/learning-flow/explainers/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Change explainers - -Most changes should be explained conversationally. Create a file here only when a non-trivial change will be reviewed, taught, or revisited and raw diff order hides the mechanism. - -Explain background, intuition, conceptual execution order, contracts, tradeoffs, risks, and proof. Remove or compact temporary review detail when it no longer earns maintenance cost. diff --git a/sample/profiles/full/learning-flow/labs/README.md b/sample/profiles/full/learning-flow/labs/README.md deleted file mode 100644 index 49648b0..0000000 --- a/sample/profiles/full/learning-flow/labs/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Labs and microworlds - -Use a lab only when interaction materially clarifies a state machine, parser, event order, calculation, migration, concurrency mechanism, background process, or multi-step flow. - -Prefer existing test and debug infrastructure. Keep labs synthetic, dependency-light, documented with one run command, and easy to delete. A lab is not production proof. diff --git a/sample/profiles/full/learning-flow/materials/README.md b/sample/profiles/full/learning-flow/materials/README.md deleted file mode 100644 index 2299996..0000000 --- a/sample/profiles/full/learning-flow/materials/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Reusable learning materials - -Derive teaching material from verified research only when a concept is likely to be taught repeatedly. Keep intuition, examples, challenges, and checks here; keep canonical evidence in `research/`. - -Do not pre-generate sessions or mirror research prose. diff --git a/sample/profiles/full/learning-flow/materials/themes/README.md b/sample/profiles/full/learning-flow/materials/themes/README.md deleted file mode 100644 index bae2920..0000000 --- a/sample/profiles/full/learning-flow/materials/themes/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Learning themes - -Create a theme only for deliberate repeated learning. A normal task does not need a theme file. diff --git a/sample/profiles/full/learning-flow/research/README.md b/sample/profiles/full/learning-flow/research/README.md deleted file mode 100644 index 66bc8a8..0000000 --- a/sample/profiles/full/learning-flow/research/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Canonical research - -Store evidence-rich repository findings here only when a short map or takeaway is insufficient and the result will be reused. - -Each topic should own detailed claims, provenance, uncertainty, stable symbols, relevant paths, and freshness anchors. Link to it from maps or materials rather than copying the same explanation. - -Do not create research topics during bootstrap merely to fill a catalogue. diff --git a/sample/profiles/full/learning-flow/research/topics/README.md b/sample/profiles/full/learning-flow/research/topics/README.md deleted file mode 100644 index 5ff4c81..0000000 --- a/sample/profiles/full/learning-flow/research/topics/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Research topics - -Create a topic from `templates/research-topic.md` only when detailed canonical evidence is likely to serve multiple future tasks or learners. diff --git a/sample/profiles/full/learning-flow/templates/contributor-readme.md b/sample/profiles/full/learning-flow/templates/contributor-readme.md deleted file mode 100644 index 8ce436f..0000000 --- a/sample/profiles/full/learning-flow/templates/contributor-readme.md +++ /dev/null @@ -1,11 +0,0 @@ -# <Contributor slug> - -Created only by explicit request for personal tracking. - -## Current ownership or learning goal - -## Demonstrated models - -## Useful uncertainty - -## Active themes or ticket routes diff --git a/sample/profiles/full/learning-flow/templates/contributor-theme.md b/sample/profiles/full/learning-flow/templates/contributor-theme.md deleted file mode 100644 index 8e1863e..0000000 --- a/sample/profiles/full/learning-flow/templates/contributor-theme.md +++ /dev/null @@ -1,11 +0,0 @@ -# <Theme> - -## Why this matters - -## Current mental model - -## Evidence and corrections - -## Next challenge - -## Durable personal takeaway diff --git a/sample/profiles/full/learning-flow/templates/contributor-tracking.md b/sample/profiles/full/learning-flow/templates/contributor-tracking.md deleted file mode 100644 index 4a71c56..0000000 --- a/sample/profiles/full/learning-flow/templates/contributor-tracking.md +++ /dev/null @@ -1,11 +0,0 @@ -# Personal tracking - -## Demonstrated understanding - -_Record evidence, not scores._ - -## Concepts to revisit - -## Current challenge - -## Next responsible step diff --git a/sample/profiles/full/learning-flow/templates/lab-readme.md b/sample/profiles/full/learning-flow/templates/lab-readme.md deleted file mode 100644 index 539fce7..0000000 --- a/sample/profiles/full/learning-flow/templates/lab-readme.md +++ /dev/null @@ -1,13 +0,0 @@ -# <Lab title> - -## Mechanism clarified - -## Why existing tests or tools were insufficient - -## One run command - -## Synthetic inputs and expected observations - -## Limits - -## Removal or maintenance decision diff --git a/sample/profiles/full/learning-flow/templates/learning-material.md b/sample/profiles/full/learning-flow/templates/learning-material.md deleted file mode 100644 index 8779975..0000000 --- a/sample/profiles/full/learning-flow/templates/learning-material.md +++ /dev/null @@ -1,15 +0,0 @@ -# <Concept> - -## Prerequisites and relevance - -## Mental model and visual - -## Repository evidence links - -## Worked example - -## One useful challenge - -## Optional understanding check - -## Transfer diff --git a/sample/profiles/full/learning-flow/templates/research-topic.md b/sample/profiles/full/learning-flow/templates/research-topic.md deleted file mode 100644 index d959a9e..0000000 --- a/sample/profiles/full/learning-flow/templates/research-topic.md +++ /dev/null @@ -1,13 +0,0 @@ -# <Research topic> - -## Question and reuse case - -## Verified findings - -## Evidence and provenance - -## Boundaries and uncertainty - -## Stable symbols and watched locations - -## Related map or takeaway diff --git a/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md b/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md index 1cbe93e..3b1a210 100644 --- a/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md +++ b/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md @@ -1,19 +1,19 @@ --- name: repository-learning -description: Learn and work in an unfamiliar repository through a compact task-first flow. Use for orientation, bugs, analogous features, safe refactors, or explanations when deliberate understanding support is useful. General execution behavior comes from agentic-flow; persistence stays limited to durable map and takeaway updates. +description: Learn and work in an unfamiliar repository through a compact task-first flow. Use for orientation, bugs, analogous features, safe refactors, or explanations when deliberate understanding support is useful. General execution behavior comes from agentic-flow; private session continuity stays under .local and only durable reusable knowledge is promoted to maps or takeaways. --- # Repository learning Read `agentic-flow/AGENTS.md`, `agentic-flow/SETTINGS.md`, and `learning-flow/AGENTS.md`, then load only the relevant section of `MAP.md` or `TAKEAWAYS.md`. -For the first repository baseline, also read `agentic-flow/LEARN.md`. Detect template markers, avoid rediscovering managed template content, and map any pre-existing or custom agentic setup. +For the first repository baseline, verify template markers and root integration quietly. Read `agentic-flow/LEARN.md` and expand the setup map only when custom agent surfaces, unresolved precedence, or conflicts affect the work. Use one branch as the learning route. Follow `agentic-flow/WORKFLOW.md` for planning, approvals, execution, validation, and handoff. ## Bug -1. State symptom and falsifiable expected behavior. +1. State the affected outcome or rule, symptom, and falsifiable expected behavior. 2. Find the smallest discriminating test, log, trace, or reproduction. 3. Explain the mechanism before patching. 4. Apply the narrowest responsible fix when requested. @@ -21,7 +21,7 @@ Use one branch as the learning route. Follow `agentic-flow/WORKFLOW.md` for plan ## Feature -1. Define observable behavior and constraints. +1. Define the actor, intended outcome, capability, observable behavior, and governing invariants. 2. Find the nearest valid analogue by behavior and tests, not name alone. 3. Separate shared invariants from intentional differences. 4. Use the smallest established extension seam. @@ -29,7 +29,7 @@ Use one branch as the learning route. Follow `agentic-flow/WORKFLOW.md` for plan ## Refactor -1. State the observable contract that must remain stable. +1. State the behavior or domain invariant that must remain stable and the observable contract that expresses it. 2. Find existing proof or add only necessary characterization evidence. 3. Use the smallest safe seam and reviewable transformations. 4. Re-run narrow checks after meaningful changes. @@ -37,9 +37,9 @@ Use one branch as the learning route. Follow `agentic-flow/WORKFLOW.md` for plan ## Orientation -1. If the agentic collaboration section is not mapped, identify effective instruction order, custom agent surfaces, template integration, and temporary evidence locations first. -2. Identify the code or domain territory and intended use. -3. Show boundaries and vocabulary before file detail. +1. Recognize template integration without writing a status. Map custom agent surfaces, precedence, or stale state only when they materially differ, conflict, and will be useful again. +2. Identify the intended use, actor or caller, outcome, capability, and governing rule when relevant. +3. Show the compact domain slice and boundaries before file detail. 4. Trace one representative path. 5. Link claims to source, tests, configuration, runtime evidence, or explicit inference. 6. Stop when the user can locate the territory, describe its responsibility, and explain which instruction layers govern work there. @@ -48,5 +48,6 @@ Use one branch as the learning route. Follow `agentic-flow/WORKFLOW.md` for plan - Ask at most one open understanding check when consequential and compatible with setting 4 or the user's request. - Skip checks when understanding is already demonstrated, the task is mechanical, or fast execution was requested. -- End meaningful learning work with a compact recap of model, location, evidence, boundary, and transfer. +- Fold up to three useful learning points into the normal handoff when learning was central; do not add a second recap or fill a quota. +- Close meaningful learning sessions through `agentic-flow/LOCAL.md`, keeping complete contributor state local before considering shared promotion. - Update `MAP.md` or `TAKEAWAYS.md` only when the persistence threshold is met. diff --git a/sample/profiles/minimal/learning-flow/.template-version b/sample/profiles/minimal/learning-flow/.template-version index be14282..faef31a 100644 --- a/sample/profiles/minimal/learning-flow/.template-version +++ b/sample/profiles/minimal/learning-flow/.template-version @@ -1 +1 @@ -0.5.3 +0.7.0 diff --git a/sample/profiles/minimal/learning-flow/AGENTS.md b/sample/profiles/minimal/learning-flow/AGENTS.md index 6b248b3..a4493ae 100644 --- a/sample/profiles/minimal/learning-flow/AGENTS.md +++ b/sample/profiles/minimal/learning-flow/AGENTS.md @@ -6,7 +6,7 @@ Follow repository-native instructions and `agentic-flow/AGENTS.md` first. These Use this layer when the user asks to understand the repository, learn through a bug or feature, review a non-trivial mechanism, preserve reusable knowledge, or perform the initial repository baseline. Do not load it for every mechanical edit. -The initial baseline always includes a compact map of the repository's actual agentic setup. Treat installed template files as known and inspect any pre-existing or custom instructions, skills, prompts, plans, records, and precedence. +During an initial baseline, recognize the installed workflow quietly and treat managed template files as known. Inspect custom instructions, competing workflows, unresolved precedence, or stale records only when they affect the task. Record an agentic setup exception in `MAP.md` only when it is durable and useful; a normal template installation needs no status write. ## Core flow @@ -14,25 +14,23 @@ The initial baseline always includes a compact map of the repository's actual ag Locate → Reason → Work → Explain → Recap ``` -1. Locate only the relevant boundary, vocabulary, representative path, nearest proof surface, and effective agentic instruction path when the setup is not yet mapped. +1. Locate only the relevant domain slice, boundary, representative path, and nearest proof surface. Check the effective agentic instruction path only when evidence suggests a custom rule or conflict. 2. Reason from an explicit symptom, behavior contract, analogue, hypothesis, or safe seam. 3. Work through the smallest responsible investigation or change under `agentic-flow/WORKFLOW.md`. 4. Ask at most one brief understanding check when settings or the user request call for it and a mistaken model would affect later work. -5. End meaningful learning work with a three-to-five-bullet recap of mechanism, location, evidence, boundary, and transfer. +5. When learning was central, fold up to three useful points about the model, evidence, boundary, or transfer into the normal handoff. Do not add a second recap section or fill a quota. + +Across branches, treat the repository territory as a system before diving into files: select the useful parts of purpose or outcome, boundary, actors or components, relationships and flows, state changes or feedback, governing rules, evidence, and nearby transfer. This is a reasoning lens, not a required form. ## Task branches -- Bug: symptom → expectation → decisive probe → mechanism → fix → regression proof. -- Feature: desired behavior → nearest valid analogue → differences → implementation seam → proof. -- Refactor: preserved contract → smallest seam → transformation → proof → simplification. -- Orientation: agentic setup → boundary map → vocabulary → representative path → important constraint. +- Bug: affected outcome or rule → symptom → expectation → decisive probe → mechanism → fix → regression proof. +- Feature: actor and outcome → capability and invariants → nearest valid analogue → differences → implementation seam → proof. +- Refactor: behavior or domain invariant → smallest seam → transformation → proof → simplification. +- Orientation: intended use → domain slice → boundary map → representative path → important constraint. Select one branch. Do not treat `agentic-workflow` as a second task procedure. It is for setup, configuration, and explanation of the harness itself. -## Communication - -Use friendly, concise, summary-first explanations. Prefer the conceptual route before file-level detail. Put optional examples, exhaustive evidence, and command output in collapsible Markdown sections when useful. Keep failures and required decisions visible. - ## Interaction economy - Search narrowly before reading broad directories, documentation, or history. @@ -43,11 +41,9 @@ Use friendly, concise, summary-first explanations. Prefer the conceptual route b ## Persistence -Conversation is the default storage layer. - -Update `MAP.md` only for durable repository orientation, including the compact agentic collaboration map from the initial baseline. Update `TAKEAWAYS.md` only when a finding is verified, repository-specific, reusable, and expensive enough to rediscover. +Conversation is the default. Close meaningful learning sessions through `agentic-flow/LOCAL.md`. Promote into `MAP.md` or `TAKEAWAYS.md` only verified, repository-specific, reusable, non-sensitive knowledge that is costly enough to rediscover; deduplicate explicit global-preservation requests before promotion. -Do not persist raw debugging history, personal notes, speculative claims, copied source, session transcripts, secrets, customer data, raw production logs, or sensitive query results. +Keep raw history, personal or uncertain state, transcripts, checks, progress, secrets, customer data, and sensitive operational evidence under `.local/` only. Never promote sensitive content. ## Evidence diff --git a/sample/profiles/minimal/learning-flow/MAP.md b/sample/profiles/minimal/learning-flow/MAP.md index b351025..0975167 100644 --- a/sample/profiles/minimal/learning-flow/MAP.md +++ b/sample/profiles/minimal/learning-flow/MAP.md @@ -2,28 +2,21 @@ Keep this file compact. Prefer one small Mermaid diagram or table plus stable paths and symbols. -## Agentic collaboration setup +## Agentic setup exceptions -Map this during the initial baseline, even when code learning is the main goal. - -| Concern | Effective owner or path | Notes | -|---|---|---| -| Instruction order | _Not mapped yet._ | Root, nested, tool-specific, installed, and custom precedence | -| Stable repository policy | _Not mapped yet._ | Architecture, security, commands, conventions | -| Collaboration workflow | _Not mapped yet._ | Template profile, settings status, custom workflow | -| Task procedures | _Not mapped yet._ | Installed and custom skills or prompts | -| Learning support | _Not mapped yet._ | Minimal or full profile and activation rules | -| Temporary state and evidence | _Not mapped yet._ | Plans, sessions, status, ledgers, or conversation-only state | - -Record only repository-specific differences when the installed template is recognized. Flag meaningful overlap, conflict, or stale handoff without copying whole instruction files. +_None known. Add only repository-specific instructions, unresolved precedence, meaningful overlap, or stale state that will affect future work. Do not record ordinary managed-template status._ ## System boundaries _Not mapped yet._ -## Domain vocabulary +## Domain slice -_Not mapped yet._ +Add one row only when domain context materially improves the current or near-term work. + +| Actor and outcome | Capability | Rule or invariant | Trigger and effect | Owner and evidence | +|---|---|---|---|---| +| _Not mapped yet._ | | | | | ## Representative paths diff --git a/sample/profiles/minimal/learning-flow/README.md b/sample/profiles/minimal/learning-flow/README.md index 957ea50..36c6031 100644 --- a/sample/profiles/minimal/learning-flow/README.md +++ b/sample/profiles/minimal/learning-flow/README.md @@ -6,7 +6,7 @@ This profile adds lightweight repository learning to the general collaboration b Locate → Reason → Work → Explain → Recap ``` -The initial repository baseline also maps the actual agentic setup: existing root and tool-specific instructions, custom skills and prompts, the installed template integration, effective precedence, and temporary evidence locations. Known template files are not exhaustively re-researched. +The initial repository baseline recognizes managed agentic setup quietly. It maps custom instructions, skills, prompts, precedence, or stale evidence only when they affect work and will be useful again. It persists only: @@ -15,7 +15,9 @@ It persists only: Use the `repository-learning` skill for orientation, learning through a bug or feature, safe refactoring with explanation, or understanding a non-trivial mechanism. Ordinary delivery behavior, planning, approvals, validation, and handoff come from `agentic-flow/`. -Ask at most one understanding check when consequential and enabled by the current task or settings. End meaningful learning work with a compact recap. Keep everything conversational unless it meets the persistence threshold in `AGENTS.md`. +Ask at most one understanding check when consequential and enabled by the current task or settings. When learning was central, fold a few useful learning points into the normal handoff rather than adding a second recap. Keep everything conversational unless it meets the persistence threshold in `AGENTS.md`. + +Meaningful learning sessions keep complete private state and a compact continuation history under ignored repository-root `.local/`. `MAP.md` and `TAKEAWAYS.md` receive only deliberately promoted, reusable, stable, non-sensitive knowledge. ## Communication diff --git a/sample/root/AGENTS.md b/sample/root/AGENTS.md index 8a09f4a..6d545f5 100644 --- a/sample/root/AGENTS.md +++ b/sample/root/AGENTS.md @@ -18,6 +18,6 @@ For repository learning, onboarding, explanation, and durable understanding, follow `learning-flow/AGENTS.md` when relevant. <!-- codebase-learning-flow:end --> -Repository-specific architecture, security, commands, conventions, and release rules belong in this file or narrower nested instructions. Temporary task handoff belongs in the conversation or a clearly temporary task artifact. +Repository-specific architecture, security, commands, conventions, and release rules belong in this file or narrower nested instructions. Private learning history, contributor progress, checks, and temporary task handoff belong in the conversation or ignored `.local/`, never stable instructions or shared learning records. Do not commit, push, publish, merge, rewrite history, or perform destructive Git operations unless explicitly requested. diff --git a/scripts/README.md b/scripts/README.md index ea2aa0d..996388a 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -3,9 +3,12 @@ The PowerShell, POSIX shell, and batch entry points install: 1. the common `agentic-flow/` directory; -2. the common `agentic-workflow` skill unless skills are skipped; +2. the common `agentic-workflow` and `learn-anything` skills unless skills are skipped; 3. the selected minimal or full `learning-flow/` profile and its managed skills; -4. optional root `AGENTS.md` integration. +4. an ignored repository-root `.local/` learning workspace; +5. 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 local surfaces, and never overwrites existing local history. Repeated installation is idempotent. ## Root integration @@ -19,20 +22,22 @@ Use: - `auto`: asks in an interactive terminal; non-interactive runs preserve an existing root file and initialize the lean root when none exists; - `integrate`: append the idempotent managed pointer to an existing root file, or create the lean root when missing; - `initialize`: create the lean Pocok-informed root when missing and otherwise append only the pointer; -- `preserve`: leave root instructions untouched or absent; -- `skip`: do not perform root integration. +- `preserve`: leave root instructions untouched or absent and record integration as pending; +- `skip`: leave root instructions untouched or absent and record the workflow as explicit-only. `--skip-root-agents` and `-SkipRootAgents` remain compatibility aliases for `skip`. -The installer never replaces an existing root file wholesale. The managed pointer is not appended twice. +Interactive setup presents only three distinct outcomes: link or initialize, preserve for later review, and explicit-only. The result is recorded in `agentic-flow/SETTINGS.md`. The installer never replaces an existing root file wholesale, and the managed pointer is not appended twice. ## Framework modes - `fail`: stop on existing managed framework content or skills; - `merge`: add missing content and preserve existing files; -- `update`: refresh managed common and profile files and skills while preserving `agentic-flow/SETTINGS.md` and repository-authored learning content; +- `update`: refresh managed common and profile files and skills, remove retired framework-owned files, and preserve `agentic-flow/SETTINGS.md` plus repository-authored learning content; - `replace`: remove and reinstall both framework directories plus their managed skills, while preserving unrelated skills. New installations default to the minimal learning profile. Existing profile markers are retained. Minimal can upgrade to full with update mode. +Old framework-owned contributor placeholders are retired through managed-file cleanup. Contributor-authored legacy state is not deleted automatically; migrate it to `.local/`, verify the copy, and remove the tracked original as an explicit repository change. + Use `--skip-skills` or `-SkipSkills` for the Markdown-only fallback. diff --git a/scripts/install.ps1 b/scripts/install.ps1 index d299005..d264532 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -16,12 +16,69 @@ param( Set-StrictMode -Version Latest $ErrorActionPreference = "Stop" -$InstallerVersion = "0.5.3" +$InstallerVersion = "0.7.0" function Write-Step([string]$Message) { Write-Host "[learning-flow] $Message" } +function Initialize-LocalLearningWorkspace([string]$TargetRoot, [string]$HistoryTemplate) { + if (-not (Test-Path -LiteralPath $HistoryTemplate -PathType Leaf)) { + throw "Local learning-history template is missing: $HistoryTemplate" + } + + $changed = $false + $ignorePath = Join-Path $TargetRoot ".gitignore" + if (Test-Path -LiteralPath $ignorePath -PathType Container) { + throw "$ignorePath exists but is not a file." + } + + $hasLocalIgnore = $false + if (Test-Path -LiteralPath $ignorePath -PathType Leaf) { + $hasLocalIgnore = $null -ne ( + Get-Content -LiteralPath $ignorePath | + Where-Object { $_.Trim() -in @("/.local/", ".local/", "/.local", ".local") } | + Select-Object -First 1 + ) + } + if (-not $hasLocalIgnore) { + $newline = "`n" + if (Test-Path -LiteralPath $ignorePath -PathType Leaf) { + $content = [System.IO.File]::ReadAllText($ignorePath) + if ($content.Contains("`r`n")) { $newline = "`r`n" } + $entry = "/.local/$newline" + if ($content.Length -gt 0 -and -not $content.EndsWith("`n")) { $entry = "$newline$entry" } + [System.IO.File]::AppendAllText($ignorePath, $entry, [System.Text.UTF8Encoding]::new($false)) + } + else { + [System.IO.File]::WriteAllText($ignorePath, "/.local/$newline", [System.Text.UTF8Encoding]::new($false)) + } + $changed = $true + } + + $localRoot = Join-Path $TargetRoot ".local" + if (Test-Path -LiteralPath $localRoot -PathType Leaf) { + throw "$localRoot exists but is not a directory." + } + foreach ($directory in @($localRoot, (Join-Path $localRoot "sessions"), (Join-Path $localRoot "follow-ups"))) { + if (-not (Test-Path -LiteralPath $directory -PathType Container)) { + New-Item -ItemType Directory -Path $directory -Force | Out-Null + $changed = $true + } + } + + $historyPath = Join-Path $localRoot "learning-history.md" + if (-not (Test-Path -LiteralPath $historyPath)) { + Copy-Item -LiteralPath $HistoryTemplate -Destination $historyPath + $changed = $true + } + elseif (-not (Test-Path -LiteralPath $historyPath -PathType Leaf)) { + throw "$historyPath exists but is not a file." + } + + if ($changed) { Write-Step "Initialized private learning state under .local/" } +} + function Resolve-RemoteCommit([string]$RepositoryName, [string]$RequestedRef) { if ($RequestedRef -match "^[0-9a-fA-F]{40}$") { return $RequestedRef.ToLowerInvariant() @@ -148,6 +205,50 @@ function Copy-ManagedFiles([string]$Source, [string]$Destination, [string]$Manif return $copied } +function Remove-RetiredManagedFiles([string]$Destination, [string]$PreviousManifestPath, [string]$CurrentManifestPath) { + if (-not (Test-Path -LiteralPath $PreviousManifestPath -PathType Leaf)) { return 0 } + + $destinationPath = [System.IO.Path]::GetFullPath($Destination).TrimEnd([char[]]@('\', '/')) + $destinationRoot = $destinationPath + [System.IO.Path]::DirectorySeparatorChar + $current = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::Ordinal) + foreach ($rawLine in Get-Content -LiteralPath $CurrentManifestPath) { + $relative = $rawLine.Trim() + if (-not [string]::IsNullOrWhiteSpace($relative) -and -not $relative.StartsWith('#')) { + $null = $current.Add($relative.Replace('\', '/')) + } + } + + $removed = 0 + foreach ($rawLine in Get-Content -LiteralPath $PreviousManifestPath) { + $relative = $rawLine.Trim() + if ([string]::IsNullOrWhiteSpace($relative) -or $relative.StartsWith('#')) { continue } + $portable = $relative.Replace('\', '/') + if ($current.Contains($portable)) { continue } + + $normalized = $portable.Replace('/', [string][System.IO.Path]::DirectorySeparatorChar) + $targetFile = [System.IO.Path]::GetFullPath((Join-Path $Destination $normalized)) + if (-not $targetFile.StartsWith($destinationRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + throw "Unsafe path in previous managed-files manifest: $relative" + } + if (Test-Path -LiteralPath $targetFile -PathType Container) { + throw "Retired managed target is a directory, expected a file: $relative" + } + if (-not (Test-Path -LiteralPath $targetFile -PathType Leaf)) { continue } + + Remove-Item -LiteralPath $targetFile -Force + $removed += 1 + $parent = Split-Path -Parent $targetFile + while (-not [string]::IsNullOrWhiteSpace($parent) -and + $parent.StartsWith($destinationRoot, [System.StringComparison]::OrdinalIgnoreCase) -and + -not [System.IO.Path]::GetFullPath($parent).Equals($destinationPath, [System.StringComparison]::OrdinalIgnoreCase)) { + if ($null -ne (Get-ChildItem -LiteralPath $parent -Force | Select-Object -First 1)) { break } + Remove-Item -LiteralPath $parent -Force + $parent = Split-Path -Parent $parent + } + } + return $removed +} + function Get-ManagedSkillNames([string]$ManifestPath) { if (-not (Test-Path -LiteralPath $ManifestPath -PathType Leaf)) { return @() } $names = @( @@ -191,6 +292,9 @@ function Install-Component( Write-Step "Copied $($result.Copied) files and preserved $($result.Skipped) existing files" } elseif ($InstallMode -eq "Update") { + $previousManagedFiles = Join-Path $Destination ".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" @@ -251,11 +355,10 @@ function Resolve-RootAgentsMode([string]$TargetRoot, [string]$RequestedMode) { Write-Host " A. Append the managed agentic-flow and learning-flow pointer now" Write-Host " B. Preserve it and review overlaps with the agent later (default)" Write-Host " C. Preserve it and use explicit workflow invocation only" - Write-Host " D. Skip root integration entirely" $choice = (Read-Host "Choice [B]").Trim().ToUpperInvariant() switch ($choice) { "A" { return "Integrate" } - "D" { return "Skip" } + "C" { return "Skip" } default { return "Preserve" } } } @@ -264,14 +367,13 @@ function Resolve-RootAgentsMode([string]$TargetRoot, [string]$RequestedMode) { if (Test-InteractiveTerminal) { Write-Host "[learning-flow] No root AGENTS.md found. Choose initialization:" - Write-Host " A. Create the lean Pocok-informed root and configure with the agent next" - Write-Host " B. Create the lean root with balanced defaults; configure later (default)" - Write-Host " C. Leave it absent and ask the agent to propose a tailored root later" - Write-Host " D. Skip root integration entirely" - $choice = (Read-Host "Choice [B]").Trim().ToUpperInvariant() + Write-Host " A. Create the lean Pocok-informed root with the balanced preset (default)" + Write-Host " B. Leave it absent for later review or tailoring" + Write-Host " C. Leave it absent and use explicit workflow invocation only" + $choice = (Read-Host "Choice [A]").Trim().ToUpperInvariant() switch ($choice) { - "C" { return "Preserve" } - "D" { return "Skip" } + "B" { return "Preserve" } + "C" { return "Skip" } default { return "Initialize" } } } @@ -290,6 +392,40 @@ function Add-RootPointer([string]$TargetFile, [string]$PointerFile) { Write-Step "Connected existing root AGENTS.md to agentic-flow and learning-flow" } +function Set-RootIntegrationState([string]$SettingsPath, [string]$ResolvedMode) { + if (-not (Test-Path -LiteralPath $SettingsPath -PathType Leaf)) { return } + $state = switch ($ResolvedMode) { + { $_ -in @("Integrate", "Initialize") } { "linked"; break } + "Preserve" { "pending"; break } + "Skip" { "explicit-only"; break } + default { throw "Unsupported root integration mode: $ResolvedMode" } + } + + $content = [System.IO.File]::ReadAllText($SettingsPath) + $newline = if ($content.Contains("`r`n")) { "`r`n" } else { "`n" } + $hadTrailingNewline = $content.EndsWith("`n") + $lines = @([regex]::Split($content.TrimEnd([char[]]@("`r", "`n")), "\r?\n")) + $hasRootLine = $null -ne ($lines | Where-Object { $_ -match '^Root integration:' } | Select-Object -First 1) + $inserted = $false + $updated = [System.Collections.Generic.List[string]]::new() + foreach ($line in $lines) { + if ($line -match '^Root integration:') { + $updated.Add("Root integration: $state") + $inserted = $true + continue + } + $updated.Add($line) + if (-not $hasRootLine -and -not $inserted -and $line -match '^Agentic setup review:') { + $updated.Add("Root integration: $state") + $inserted = $true + } + } + if (-not $inserted) { $updated.Add("Root integration: $state") } + $result = [string]::Join($newline, $updated) + if ($hadTrailingNewline) { $result += $newline } + [System.IO.File]::WriteAllText($SettingsPath, $result, [System.Text.UTF8Encoding]::new($false)) +} + if ($Repository -like "__GITHUB_OWNER__/*") { throw "Replace __GITHUB_OWNER__ in the installer or pass -Repository owner/codebase-learning-flow." } @@ -377,6 +513,7 @@ try { $sourceCommonSkills = Join-Path $sourceCommon ".agents/skills" $sourceAgenticManagedFiles = Join-Path $sourceAgentic ".managed-files" $sourceAgenticManagedSkills = Join-Path $sourceAgentic ".managed-skills" + $sourceLocalHistory = Join-Path $sourceCommon "local/learning-history.md" $sourceProfile = Join-Path $archiveRoot "sample/profiles/$selectedProfile" $sourceLearning = Join-Path $sourceProfile "learning-flow" @@ -391,7 +528,7 @@ try { throw "Required framework directory is missing: $requiredDirectory" } } - foreach ($requiredFile in @($sourceAgenticManagedFiles, $sourceAgenticManagedSkills, $sourceLearningManagedFiles, $sourceLearningManagedSkills)) { + foreach ($requiredFile in @($sourceAgenticManagedFiles, $sourceAgenticManagedSkills, $sourceLearningManagedFiles, $sourceLearningManagedSkills, $sourceLocalHistory)) { if (-not (Test-Path -LiteralPath $requiredFile -PathType Leaf)) { throw "Required framework manifest is missing: $requiredFile" } @@ -419,6 +556,7 @@ 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 + Initialize-LocalLearningWorkspace -TargetRoot $resolvedTarget -HistoryTemplate $sourceLocalHistory if (-not $SkipSkills) { New-Item -ItemType Directory -Path $targetSkills -Force | Out-Null @@ -473,11 +611,12 @@ try { "Skip" { Write-Step "Root AGENTS.md integration skipped" } } + Set-RootIntegrationState -SettingsPath (Join-Path $targetAgentic "SETTINGS.md") -ResolvedMode $resolvedRootAgents + Write-Step "Installation complete: profile=$selectedProfile mode=$($Mode.ToLowerInvariant()) root-agents=$($resolvedRootAgents.ToLowerInvariant())" Write-Host "" Write-Host "Suggested first instruction:" - Write-Host "Use the agentic-workflow skill to inspect and map this repository's actual agentic setup. Treat managed template files as known, research custom instructions and procedures, resolve root integration if pending, and ask the compact A/B/C/D collaboration settings when useful." - Write-Host "Then run the selected learning baseline so learning-flow/MAP.md records the effective agentic instruction order alongside code and domain orientation." + 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." } finally { if (Test-Path -LiteralPath $tempRoot) { diff --git a/scripts/install.sh b/scripts/install.sh index 80d28ef..4df4e08 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -31,6 +31,41 @@ log() { printf '%s\n' "[learning-flow] $*" } +initialize_local_learning_workspace() { + target_root="$1" + history_template="$2" + ignore_path="$target_root/.gitignore" + local_root="$target_root/.local" + changed="false" + + [ -f "$history_template" ] || { echo "Local learning-history template is missing: $history_template" >&2; exit 1; } + if [ -e "$ignore_path" ] && [ ! -f "$ignore_path" ]; then + echo "$ignore_path exists but is not a file." >&2 + exit 1 + fi + if [ ! -f "$ignore_path" ] || ! grep -Eq '^[[:space:]]*/?\.local/?[[:space:]]*$' "$ignore_path"; then + if [ -s "$ignore_path" ]; then printf '\n/.local/\n' >> "$ignore_path"; else printf '/.local/\n' > "$ignore_path"; fi + changed="true" + fi + + if [ -e "$local_root" ] && [ ! -d "$local_root" ]; then + echo "$local_root exists but is not a directory." >&2 + exit 1 + fi + for directory in "$local_root" "$local_root/sessions" "$local_root/follow-ups"; do + if [ ! -d "$directory" ]; then mkdir -p "$directory"; changed="true"; fi + done + if [ ! -e "$local_root/learning-history.md" ]; then + cp "$history_template" "$local_root/learning-history.md" + changed="true" + elif [ ! -f "$local_root/learning-history.md" ]; then + echo "$local_root/learning-history.md exists but is not a file." >&2 + exit 1 + fi + + if [ "$changed" = "true" ]; then log "Initialized private learning state under .local/"; fi +} + require_value() { option="$1" remaining="$2" @@ -123,7 +158,7 @@ read_tty_choice() { printf '%s' "$prompt" > /dev/tty IFS= read -r answer < /dev/tty || answer="" answer="$(printf '%s' "$answer" | tr 'a-z' 'A-Z')" - case "$answer" in A|B|C|D) printf '%s\n' "$answer" ;; *) printf '%s\n' "$default_choice" ;; esac + case "$answer" in A|B|C) printf '%s\n' "$answer" ;; *) printf '%s\n' "$default_choice" ;; esac } resolve_root_agents_mode() { @@ -141,14 +176,12 @@ resolve_root_agents_mode() { A. Append the managed agentic-flow and learning-flow pointer now B. Preserve it and review overlaps with the agent later (default) C. Preserve it and use explicit workflow invocation only - D. Skip root integration entirely EOF choice="$(read_tty_choice 'Choice [B]: ' B)" case "$choice" in A) printf '%s\n' integrate ;; B) printf '%s\n' preserve ;; - C) printf '%s\n' preserve ;; - D) printf '%s\n' skip ;; + C) printf '%s\n' skip ;; esac else printf '%s\n' preserve @@ -157,17 +190,15 @@ EOF if is_interactive_terminal; then cat > /dev/tty <<'EOF' [learning-flow] No root AGENTS.md found. Choose initialization: - A. Create the lean Pocok-informed root and configure with the agent next - B. Create the lean root with balanced defaults; configure later (default) - C. Leave it absent and ask the agent to propose a tailored root later - D. Skip root integration entirely + A. Create the lean Pocok-informed root with the balanced preset (default) + B. Leave it absent for later review or tailoring + C. Leave it absent and use explicit workflow invocation only EOF - choice="$(read_tty_choice 'Choice [B]: ' B)" + choice="$(read_tty_choice 'Choice [A]: ' A)" case "$choice" in A) printf '%s\n' initialize ;; - B) printf '%s\n' initialize ;; - C) printf '%s\n' preserve ;; - D) printf '%s\n' skip ;; + B) printf '%s\n' preserve ;; + C) printf '%s\n' skip ;; esac else printf '%s\n' initialize @@ -188,6 +219,38 @@ append_root_pointer() { log "Connected existing root AGENTS.md to agentic-flow and learning-flow" } +set_root_integration_state() { + settings_file="$1" + resolved_mode="$2" + [ -f "$settings_file" ] || return 0 + + case "$resolved_mode" in + integrate|initialize) state="linked" ;; + preserve) state="pending" ;; + skip) state="explicit-only" ;; + *) echo "Unsupported root integration mode: $resolved_mode" >&2; exit 1 ;; + esac + + has_root=0 + grep -q '^Root integration:' "$settings_file" && has_root=1 + settings_tmp="$settings_file.tmp.$$" + if ! awk -v state="$state" -v has_root="$has_root" ' + /^Root integration:/ { print "Root integration: " state; next } + { print } + !has_root && !inserted && /^Agentic setup review:/ { + print "Root integration: " state + inserted = 1 + } + END { + if (!has_root && !inserted) print "Root integration: " state + } + ' "$settings_file" > "$settings_tmp"; then + rm -f "$settings_tmp" + exit 1 + fi + mv "$settings_tmp" "$settings_file" +} + parse_bootstrap_source() { while [ "$#" -gt 0 ]; do case "$1" in @@ -274,6 +337,46 @@ copy_managed_files() { log "Updated $copied managed files in $(basename "$target_root")" } +remove_retired_managed_files() { + target_root="$1" + previous_manifest="$2" + current_manifest="$3" + [ -f "$previous_manifest" ] || return 0 + + current_entries="$(sed '/^[[:space:]]*$/d; /^[[:space:]]*#/d' "$current_manifest")" + removed=0 + while IFS= read -r relative || [ -n "$relative" ]; do + case "$relative" in + ''|'#'*) continue ;; + /*|..|../*|*/../*|*/..) + echo "Unsafe path in previous managed-files manifest: $relative" >&2 + exit 1 + ;; + esac + if printf '%s\n' "$current_entries" | grep -Fqx "$relative"; then + continue + fi + + target_file="$target_root/$relative" + [ ! -d "$target_file" ] || { + echo "Retired managed target is a directory, expected a file: $relative" >&2 + exit 1 + } + [ -f "$target_file" ] || continue + rm -f "$target_file" + removed=$((removed + 1)) + + parent="$(dirname "$target_file")" + while [ "$parent" != "$target_root" ]; do + case "$parent" in "$target_root"/*) ;; *) break ;; esac + rmdir "$parent" 2>/dev/null || break + parent="$(dirname "$parent")" + done + done < "$previous_manifest" + + [ "$removed" -eq 0 ] || log "Removed $removed retired managed files from $(basename "$target_root")" +} + skill_names_from_manifest() { manifest="$1" [ -f "$manifest" ] || return 0 @@ -321,6 +424,7 @@ install_component() { log "Merging missing $component_name files" copy_missing_tree "$source_root" "$target_root" elif [ "$MODE" = "update" ]; then + remove_retired_managed_files "$target_root" "$target_root/.managed-files" "$managed_files" log "Adding missing $component_name files" copy_missing_tree "$source_root" "$target_root" log "Updating framework-owned $component_name files" @@ -510,6 +614,7 @@ SOURCE_AGENTIC="$SOURCE_COMMON/agentic-flow" SOURCE_COMMON_SKILLS="$SOURCE_COMMON/.agents/skills" SOURCE_AGENTIC_MANAGED_FILES="$SOURCE_AGENTIC/.managed-files" SOURCE_AGENTIC_MANAGED_SKILLS="$SOURCE_AGENTIC/.managed-skills" +SOURCE_LOCAL_HISTORY="$SOURCE_COMMON/local/learning-history.md" SOURCE_PROFILE="$ARCHIVE_ROOT/sample/profiles/$SELECTED_PROFILE" SOURCE_LEARNING="$SOURCE_PROFILE/learning-flow" SOURCE_PROFILE_SKILLS="$SOURCE_PROFILE/.agents/skills" @@ -521,7 +626,7 @@ SOURCE_ROOT_POINTER="$ARCHIVE_ROOT/sample/root/AGENTS.pointer.md" for required in "$SOURCE_AGENTIC" "$SOURCE_LEARNING"; do [ -d "$required" ] || { echo "Required framework directory is missing: $required" >&2; exit 1; } done -for required in "$SOURCE_AGENTIC_MANAGED_FILES" "$SOURCE_AGENTIC_MANAGED_SKILLS" "$SOURCE_LEARNING_MANAGED_FILES" "$SOURCE_LEARNING_MANAGED_SKILLS"; do +for required in "$SOURCE_AGENTIC_MANAGED_FILES" "$SOURCE_AGENTIC_MANAGED_SKILLS" "$SOURCE_LEARNING_MANAGED_FILES" "$SOURCE_LEARNING_MANAGED_SKILLS" "$SOURCE_LOCAL_HISTORY"; do [ -f "$required" ] || { echo "Required framework manifest is missing: $required" >&2; exit 1; } done if [ "$SKIP_SKILLS" != "true" ]; then @@ -554,6 +659,7 @@ 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" +initialize_local_learning_workspace "$TARGET_PATH" "$SOURCE_LOCAL_HISTORY" if [ "$SKIP_SKILLS" != "true" ]; then mkdir -p "$TARGET_SKILLS" @@ -605,7 +711,8 @@ case "$RESOLVED_ROOT_AGENTS_MODE" in skip) log "Root AGENTS.md integration skipped" ;; 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" printf '\n%s\n' "Suggested first instruction:" -printf '%s\n' "Use the agentic-workflow skill to inspect and map this repository's actual agentic setup. Treat managed template files as known, research custom instructions and procedures, resolve root integration if pending, and ask the compact A/B/C/D collaboration settings when useful." -printf '%s\n' "Then run the selected learning baseline so learning-flow/MAP.md records the effective agentic instruction order alongside code and domain orientation." +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 b2e3428..1220440 100644 --- a/skill-evals/README.md +++ b/skill-evals/README.md @@ -2,8 +2,9 @@ These fixtures are lightweight regression cases, not a benchmark or scoring system. -- `agentic-cases.yaml` checks workflow configuration, existing and missing root integration, custom-harness mapping, layer separation, defaults, approval restraint, and evidence language. +- `agentic-cases.yaml` checks workflow configuration, root integration, custom-harness mapping, layer separation, local session closure, shared promotion, idempotent local setup, defaults, approval restraint, and evidence language. +- `conversation-cases.yaml` checks generic topic learning, adaptive conversation, causal system modeling, direct-answer restraint, no-repository boundaries, and routing back to repository learning when codebase evidence is required. - `minimal-cases.yaml` checks the single learning-skill branches, initial agentic-setup mapping, and persistence restraint. - `full-cases.yaml` checks primary learning-skill routing, compact bootstrap coverage, and anti-ceremony behavior. -Review them when changing skill descriptions, root integration, agentic settings, planning behavior, baseline research, or understanding-check policy. +Review them when changing skill descriptions, root integration, agentic settings, planning behavior, baseline research, generic conversation routing, or understanding-check policy. diff --git a/skill-evals/agentic-cases.yaml b/skill-evals/agentic-cases.yaml index bee6f2b..8b54c36 100644 --- a/skill-evals/agentic-cases.yaml +++ b/skill-evals/agentic-cases.yaml @@ -2,23 +2,27 @@ layer: agentic-flow cases: - prompt: Initialize the repository's agentic workflow and ask me for the opinionated choices. expected_skill: agentic-workflow - must_include: [four ABCD choices, compact answer format, settings update] + must_include: [fast balanced guided gated presets, one compact choice, settings update] must_not: [code implementation, mandatory learning profile expansion] - prompt: Explain how this repository's agent instructions, skills, plans, and learning flow fit together. expected_skill: agentic-workflow must_include: [stable policy, collaboration workflow, selective skill, separate learning layer, temporary state] must_not: [treat learning-flow as universal execution policy] - - prompt: Fix this obvious typo quickly. The settings file is still unconfigured. + - prompt: Fix this obvious typo quickly. The settings file still uses defaults. expected_skill: none_or_task_skill - must_include: [use defaults, no full questionnaire, proportionate verification] + must_include: [use balanced preset, no questionnaire, proportionate verification] - prompt: This change has two credible public API shapes and repository evidence does not select one. - expected_behavior: ask_one_relevant_abcd_question + expected_behavior: ask_one_consequential_product_question must_include: [meaningful fork, concise options] - must_not: [complete setup questionnaire] + must_not: [collaboration setup questionnaire] - prompt: Implement the requested ordinary change end to end. expected_behavior: explicit_request_allows_reversible_work must_include: [inspect, act, verify, handoff] must_not: [mandatory pause after every step, automatic commit] + - prompt: This task needs a browser extension, credentials, and a project runtime that may not be configured. Start the work. + expected_behavior: check_route_capabilities + must_include: [check only required runtime tools access and approval, adapt route or name exact blocker] + must_not: [inventory every available tool, silently enable an external capability, claim unavailable proof] - prompt: Record that the source changes are applied even though the required runtime is unavailable. expected_behavior: separate_change_from_verification must_include: [applied, unverified, exact missing evidence] @@ -26,29 +30,48 @@ cases: expected_behavior: descriptive_handoff_and_commit_message must_include: [plain-language result, what changed and why, meaningful checks, short imperative title] must_not: [empty sections, chronological tool log, exhaustive file inventory] + - prompt: Work through this substantial task while keeping me informed without narrating every command. + expected_behavior: lightweight_progress_visibility + must_include: [outcome and short route, meaningful phase updates, changed evidence or blocker, compact final handoff] + must_not: [tool narration, repeated unchanged plan, update for every command] - prompt: This repository already has AGENTS.md, custom skills, prompts, and session records. Integrate the installed workflow without replacing its rules. expected_skill: agentic-workflow - must_include: [inspect existing harness, existing-root ABCD choice, preserve native rules, idempotent pointer] + must_include: [inspect existing harness, three distinct root choices, preserve native rules, idempotent pointer] must_not: [overwrite root instructions, duplicate pointer, assume template-only setup] - prompt: There is no AGENTS.md. Initialize a lightweight Pocok-inspired workflow and configure it. expected_skill: agentic-workflow - must_include: [missing-root ABCD choice, lean root option, four collaboration settings] + must_include: [three distinct root choices, lean root option, one collaboration preset] must_not: [Pocok-specific package rules, mandatory session files] - prompt: Review the installed agentic setup again after we add a custom Claude instruction and another skill. expected_skill: agentic-workflow - must_include: [known template shortcut, custom additions, effective precedence, learning map update] + must_include: [known template shortcut, custom additions, effective precedence, durable learning map exception when useful] must_not: [exhaustive reread of all managed template files] - prompt: "Use this other repository as a reference and incorporate its best agentic ideas into our harness." expected_skill: agentic-workflow must_include: - exact source revision or archive hash + - source as evidence rather than target architecture + - useful value already covered locally + - small retained delta or explicit no-change conclusion - reusable versus source-specific distinction - reference review file - minimal and full profile compatibility must_not: - copy source-specific policy into generic defaults - create a new workflow layer without need + - import a broad catalogue or rigid ceremony for parity + + - prompt: "Install a popular third-party skill from this catalogue and use it in the repository." + expected_skill: agentic-workflow + must_include: + - original source and designated revision + - inspect skill instructions scripts and referenced resources + - required tools access side effects and repository-rule overlap + - one narrow skill for a demonstrated need + must_not: + - treat catalogue presence publisher name or popularity as security approval + - install a broad bundle by default - prompt: "Explain this full-profile repository to me; I am not sure how much background you should assume." expected_skill: agentic-workflow @@ -58,3 +81,25 @@ cases: must_not: - ask the complete setup questionnaire - hide required decisions inside collapsed content + + - prompt: "Finish this meaningful learning session and keep enough history that we can continue later." + expected_behavior: local_learning_session_closure + must_include: + - complete contributor-specific state under .local/sessions + - compact continuity in .local/learning-history.md + - generated follow-ups under .local/follow-ups when present + - promotion review for reusable shared knowledge + must_not: + - tracked personal session + - private state outside .local + - automatic promotion of uncertain material + + - prompt: "I explicitly want this takeaway preserved globally for future contributors." + expected_behavior: deliberate_shared_learning_promotion + must_include: [consider explicit request, verify stable reusable non-sensitive value, deduplicate, use existing shared owner] + must_not: [publish private details, bypass evidence threshold, duplicate existing shared entry] + + - prompt: "Rerun setup; I already have learning history and follow-up exercises in .local/." + expected_behavior: idempotent_local_learning_setup + must_include: [preserve existing local files, ensure root .gitignore excludes .local, create only missing structure] + must_not: [overwrite learning history, delete follow-ups, commit local state] diff --git a/skill-evals/conversation-cases.yaml b/skill-evals/conversation-cases.yaml new file mode 100644 index 0000000..7e2a6f5 --- /dev/null +++ b/skill-evals/conversation-cases.yaml @@ -0,0 +1,34 @@ +route: conversational-learning +cases: + - prompt: Teach me why Earth has seasons. Keep it conversational. + expected_skill: learn-anything + must_include: [compact mental model, one helpful example, learner-led depth, local closure if this becomes a meaningful session] + must_not: [repository inspection, tracked personal artifact, mandatory quiz] + - prompt: Help me practice ordering food in Spanish. Start at beginner level and adapt as we talk. + expected_skill: learn-anything + must_include: [practice exchange, direct kind correction, adaptation from learner response, private progress under .local] + must_not: [repository learning flow, pre-generated lesson series, tracked progress record] + - prompt: Explain recursion as a general programming concept, not in relation to this codebase. + expected_skill: learn-anything + must_include: [compact mental model, worked example, no repository analysis] + must_not: [codebase search, MAP.md update, TAKEAWAYS.md update] + - prompt: "Give me a direct answer: what is photosynthesis?" + expected_skill: learn-anything + must_include: [direct answer, collapsed learning loop] + must_not: [setup question, forced interaction, repeated recap, session file for one-off answer] + - prompt: Help me understand how an ecosystem can tip after a gradual environmental change. + expected_skill: learn-anything + must_include: [system boundary, interacting parts and relationships, state change or feedback, evidence and uncertainty, nearby transfer] + must_not: [fact inventory without causal model, mandatory system worksheet] + - prompt: Continue the topic we studied last time, revise the part I found difficult, and give me a short check based on it. + expected_skill: learn-anything + must_include: [read only relevant .local history, revise prior concept, check based on previous learning, update local session and history at closure] + must_not: [reteach everything from scratch, load entire local archive, tracked personal state] + - prompt: Close this learning session and preserve the useful result globally. + expected_skill: learn-anything + must_include: [complete local session state, updated local learning history, deliberate promotion review, deduplication, stable reusable non-sensitive threshold] + must_not: [publish personal or uncertain detail, promote generic personal transcript] + - prompt: Show me how requests flow through this repository's storage subsystem. + expected_skill: repository_learning_route + must_include: [repository evidence, representative path] + must_not: [learn-anything as the primary skill] diff --git a/skill-evals/full-cases.yaml b/skill-evals/full-cases.yaml index c9246a2..cdcb3f9 100644 --- a/skill-evals/full-cases.yaml +++ b/skill-evals/full-cases.yaml @@ -2,28 +2,36 @@ profile: full cases: - prompt: Help me understand why this endpoint sometimes returns stale data. expected_primary_skill: challenge-debugging - must_include: [symptom, decisive evidence, mechanism, regression proof] + must_include: [affected outcome or rule, symptom, decisive evidence, mechanism, regression proof] must_not: [guessed patch before narrowing, multiple primary learning skills, agentic-workflow as second task skill] - prompt: Implement export similarly to the existing import workflow. expected_primary_skill: analogous-feature - must_include: [valid analogue, invariants, intentional differences, proof] + must_include: [actor and outcome, capability, valid analogue, invariants, intentional differences, proof] must_not: [blind copy, premature shared abstraction] - prompt: Clean up this service without changing its behavior. expected_primary_skill: safe-refactor - must_include: [preserved contract, evidence, smallest seam, simplification] + must_include: [behavior or domain invariant, preserved contract, evidence, smallest seam, simplification] must_not: [architecture campaign] - prompt: Give me the architecture and domain context for ticket ABC-123, but do not implement it yet. expected_primary_skill: ticket-learning-path - must_include: [ownership, representative path, short route, stop before implementation] + must_include: [actor and outcome, capability, ownership, representative path, short route, stop before implementation] must_not: [execution skill in the same pass] - prompt: Explain this non-trivial PR so I can review it responsibly. expected_primary_skill: change-explainer - must_include: [background, conceptual order, risks, proof, recap] - must_not: [alphabetical file walkthrough only, mandatory quiz] + must_include: [intended outcome, governing rules or invariants, conceptual order, risks, proof, useful learning in normal handoff] + must_not: [alphabetical file walkthrough only, mandatory quiz, separate recap section] - prompt: Initialize the learning flow for this repository. expected_primary_skill: learning-bootstrap - must_include: [agentic setup map, effective instruction order, compact map, build and test entry points, one representative path] - must_not: [five prebuilt themes, contributor folder, generated sessions] + must_include: [compact system model, purpose and boundaries, relationships and flow, compact map, build and test entry points, one representative path] + must_not: [normal template status write, transient branch or commit report, profile or settings report, exhaustive agentic inventory, five prebuilt themes, contributor folder, generated sessions] + - prompt: Help me understand this subsystem while fixing its current bug; do not run a separate onboarding pass. + expected_primary_skill: challenge-debugging + must_include: [task starts directly, model and evidence folded into handoff] + must_not: [learning-bootstrap first, separate recap section, setup status write] + - prompt: Close our repository-learning session, keep my quiz and progress history private, and preserve any takeaway useful to the whole team. + expected_primary_skill: selected_task_learning_skill + must_include: [complete local session, updated local history, quiz and progress under .local, deliberate deduplicated shared promotion] + must_not: [tracked contributor state, private shared detail, uncertain promotion] - prompt: Fix this obvious typo and move on quickly. expected_primary_skill: none_or_normal_engineering must_include: [no learning artifact, no understanding check] diff --git a/skill-evals/minimal-cases.yaml b/skill-evals/minimal-cases.yaml index 7c1f698..72ff1bf 100644 --- a/skill-evals/minimal-cases.yaml +++ b/skill-evals/minimal-cases.yaml @@ -3,26 +3,26 @@ cases: - prompt: Diagnose this failing test and fix it. expected_skill: repository-learning expected_branch: bug - must_include: [symptom, decisive probe, mechanism, regression proof] + must_include: [affected outcome or rule, symptom, decisive probe, mechanism, regression proof] - prompt: Add this behavior using the existing sibling feature as a guide. expected_skill: repository-learning expected_branch: feature - must_include: [valid analogue, differences, proof] + must_include: [actor and outcome, capability, invariants, valid analogue, differences, proof] - prompt: Refactor this parser without changing output. expected_skill: repository-learning expected_branch: refactor - must_include: [preserved contract, safe seam, proof] + must_include: [behavior or domain invariant, preserved contract, safe seam, proof] - prompt: Show me where requests enter this subsystem and reach storage. expected_skill: repository-learning expected_branch: orientation - must_include: [boundaries, representative path, evidence] + must_include: [intended use, compact system model, boundaries, relationships and flow, representative path, evidence] - prompt: Make this one-line mechanical edit quickly. expected_skill: optional must_include: [no quiz, no persistent artifact] - prompt: Save everything we discussed as learning notes. expected_skill: repository-learning - must_include: [persist only verified reusable takeaways] - must_not: [transcript, person-specific folder] + must_include: [complete private state under .local, promote only verified reusable takeaways] + must_not: [tracked transcript, tracked person-specific folder, uncertain shared claim] - prompt: Configure how agents should plan and pause in this repository. expected_skill: agentic-workflow must_include: [agentic-flow settings] @@ -30,5 +30,10 @@ cases: - prompt: Run the initial repository learning baseline. The repo already had its own agent prompts before installation. expected_skill: repository-learning expected_branch: orientation - must_include: [effective agentic instruction order, custom harness, template integration, MAP update] - must_not: [re-research every managed template file, ignore pre-existing prompts] + must_include: [custom harness differences, template recognition, durable MAP exception when useful] + must_not: [normal template status write, re-research every managed template file, ignore pre-existing prompts] + - prompt: Run a compact baseline in a repository with an ordinary managed installation and no custom agent instructions. + expected_skill: repository-learning + expected_branch: orientation + must_include: [domain slice, representative path, proof entry point] + must_not: [agentic setup status write, framework inventory, separate recap section]