diff --git a/.gitignore b/.gitignore index b2c9cdb..6d9eafe 100644 --- a/.gitignore +++ b/.gitignore @@ -18,4 +18,5 @@ Desktop.ini *.log # Locally generated distribution archives -/codebase-learning-flow.zip \ No newline at end of file +/INITIALIZE_LEARNING_FLOW_*.zip +/codebase-learning-flow*.zip diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b76f206 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# Codebase Learning Flow maintenance instructions + +## Purpose + +Maintain a small repository-native harness for safe agentic collaboration and deliberate codebase learning. Preserve the separation between: + +- repository-specific engineering rules; +- general collaboration behavior in `agentic-flow/`; +- optional learning behavior in `learning-flow/`; +- temporary task state. + +## Working rules + +- Read `README.md`, `docs/DESIGN_NOTES.md`, and `CHANGELOG.md` before structural changes. +- Keep minimal and full profiles behaviorally compatible where they share concepts. +- Prefer a small common rule over duplicated profile-specific prose. +- Do not add workflow ceremony without a demonstrated problem. +- Treat installer update and preservation behavior as part of the public contract. +- Update manifests, version markers, examples, and regression fixtures with framework changes. + +## External reference integration + +When asked to incorporate value from another repository, article source, or ZIP, follow `docs/references/REFERENCE_INTEGRATION.md`. + +The expected outcome is not a copy of the source harness. Extract the smallest generally useful patterns, preserve source-specific rules only in the reference review, and add `docs/references/REFERENCE_REVIEW_.md` for provenance and historical context. + +## Communication + +Use friendly, direct, summary-first language. Say concretely what changed and why it matters, grouping substantial updates into a few descriptive bullets rather than a tool log or file inventory. Put secondary rationale, long examples, command matrices, and historical notes in `
` blocks when the Markdown renderer supports them. Never hide required warnings, decisions, or next actions inside a collapsed section. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9bfeb0c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,89 @@ +# Changelog + +## 0.5.3 + +### Added + +- Descriptive handoff and commit-message shapes that connect each change to its reason or effect without forcing empty sections. +- Dual licensing: MIT for software and CC BY 4.0 for original documentation, workflow text, templates, and evaluation content. + +### Changed + +- Substantial agent updates now favor a plain-language result and a few outcome-grouped bullets over dry labels, tool chronology, or file inventories. +- Maintenance and reconstruction notes moved under `docs/`; reference integration guidance and provenance reviews moved under `docs/references/`. + +## 0.5.2 + +### Added + +- Root maintenance instructions and `docs/references/REFERENCE_INTEGRATION.md` for reproducible value extraction from a GitHub repository, article source, or ZIP. +- Installed `agentic-flow/REFERENCE_INTEGRATION.md` and external-reference handling in the `agentic-workflow` skill. +- `docs/references/REFERENCE_REVIEW_LITT.md`, designating the exact `geoffreylitt/homepage` revision and source paths behind “Understanding is the new bottleneck.” +- Optional full-profile A/B/C/D learner-context tailoring when experience materially changes useful scaffolding. + +### Changed + +- Communication defaults are friendlier, shorter, summary-first, and concept-first. +- Human-facing Markdown now prefers collapsible sections for optional detail, evidence inventories, examples, and long command output. +- Essential warnings, decisions, failures, and required actions must remain visible. +- Pocok reference review was shortened and aligned with the repeatable reference-review format. +- Root README and common agentic documentation were condensed. + +## 0.5.1 + +### Added + +- Initial learning baseline coverage for the repository's actual agentic setup, including root and nested instructions, tool-specific files, custom skills, prompts, plans, sessions, status artifacts, and evidence ledgers. +- A compact `Agentic collaboration setup` section in both profile map templates. +- `agentic-flow/ROOT_INTEGRATION.md` with separate A/B/C/D choices for repositories with and without a root `AGENTS.md`. +- A lean Pocok-informed root template containing reusable evidence and validation discipline without Pocok-specific package, commit, or release rules. +- Idempotent managed pointer block for connecting existing root instructions to `agentic-flow/` and `learning-flow/`. +- Installer root modes: `auto`, `integrate`, `initialize`, `preserve`, and `skip`. + +### Changed + +- `learning-bootstrap` now maps effective agentic instruction order before code and domain orientation. +- Minimal orientation also maps agentic setup when the baseline has not yet been populated. +- Managed template markers are treated as known evidence so agents research custom additions and integration rather than rereading the framework exhaustively. +- `agentic-workflow` now handles later root integration, custom-harness mapping, conflict review, and learning-map updates. +- The learning module explains the repository's effective setup, not merely the template's intended layer model. +- Interactive installers ask how to handle existing or missing root instructions. Safe non-interactive defaults remain available. + +### Preserved + +- Existing root `AGENTS.md` content is never replaced wholesale. +- `update` does not overwrite repository-authored maps, takeaways, settings, research, or custom skills. +- Root integration and collaboration settings can be completed or revised later through the `agentic-workflow` skill. + +## 0.5.0 + +### Added + +- Common `agentic-flow/` layer for collaboration behavior, separate from `learning-flow/`. +- Minimal workflow: `Frame → Inspect → Decide → Act → Verify → Handoff`. +- `agentic-workflow` skill for setup, configuration, explanation, and review of repository agentic content. +- Four compact A/B/C/D configuration choices for autonomy, planning, validation, and learning or records. +- Balanced defaults that allow routine work before configuration. +- `LEARN.md` module explaining repository-native instructions, workflow settings, skills, learning support, and temporary task state. +- Agentic routing and behavior regression fixtures. +- Exact integration guidance for repositories that already have a root `AGENTS.md`. + +### Changed + +- Root pointer now loads `agentic-flow/` generally and `learning-flow/` only for learning-oriented support. +- Minimal and full learning instructions defer planning, approval, validation depth, records, and handoff to the agentic layer. +- Full-profile skills explicitly avoid competing with `agentic-workflow` as a second task procedure. +- Installer manages common agentic files and skills independently from the selected learning profile. +- `update` installs the new common layer into v0.4 repositories while preserving settings and repository-authored knowledge. +- `replace` replaces both framework directories and their managed skills. + +### Simplified + +- No mandatory plan file, session record, one-step approval loop, one commit per step, or phase gate. +- No configuration questionnaire for trivial work. +- Temporary handoff is excluded from stable instruction files. +- Source changes applied and executable verification completed are reported as separate facts. + +### Reference review + +The revision was informed by the current `legrab/pocok` agentic documentation on `main` at review commit `cdfb8bfaec5dcc74c62e5f6d5d401222c82dc45a`. It preserves Pocok's evidence discipline, current-truth rule, explicit boundaries, and handoff value while removing repository-specific and overly restrictive defaults. diff --git a/INITIALIZE_LEARNING_FLOW.md b/INITIALIZE_LEARNING_FLOW.md deleted file mode 100644 index ceab52a..0000000 --- a/INITIALIZE_LEARNING_FLOW.md +++ /dev/null @@ -1,1303 +0,0 @@ -# Prompt: Initialize a Repository-Native Continuous Learning Flow - -Use this prompt with an AI coding agent inside an existing repository. - ---- - -## Role - -Act as the initializer and first maintainer of a repository-native continuous learning system for software contributors. - -Your job is not merely to write onboarding documentation. Build a durable learning workflow that: - -- helps a contributor become productive on immediate tasks without reducing learning to the one file involved in a ticket; -- builds senior-level architectural, domain, operational, and codebase understanding incrementally; -- supports breadth-first orientation and depth-first specialization; -- remembers what each contributor has encountered, understood, applied, or is still learning; -- accumulates verified repository knowledge that future agents and contributors can reuse; -- improves its shared teaching material whenever contributor confusion exposes a weakness; -- stays cheap to maintain through Git-aware freshness checks, compact personal traces, stable identifiers, and minimal duplication; -- can span several related repositories when the application is split across system, application, and module repositories. - -The system must remain useful after months of intermittent use by one or two contributors. Avoid building a documentation bureaucracy. - ---- - -## Core distinctions - -Keep these concepts separate. - -### 1. Repository research - -Repository research is the internal, shared collection of verified knowledge about the codebase. - -It records facts, evidence, provenance, uncertainty, watched source locations, baseline commits, architectural observations, domain concepts, operational constraints, recurring patterns, and open research directions. - -It is not itself the primary teaching material. - -### 2. Learning material - -A learning material is a reusable thematic unit derived from repository research. - -Examples: - -- overall architecture; -- build, run, configuration, and debugging; -- logging; -- dependency injection; -- a UI framework; -- data access; -- a major product module; -- a domain concept; -- a mathematical technique such as curve fitting; -- a representative end-to-end feature flow; -- testing practices; -- a recurring implementation or operational pattern. - -A material can contain several progressively deeper learning sections. - -### 3. Learning section - -A learning section is one depth or subtopic within a material. - -For example, an architecture material may begin with a foundation section that explains the repository groups, technology stack, runtime composition, and main execution flow. Later sections may separately cover UI composition, data flow, reflection-based loading, background services, dependency injection, configuration, or extension modules. - -Learning sections at the same depth do not need to be sequential. - -### 4. Learning session - -A learning session is one active study cycle by a contributor. - -Plan for roughly 30 to 40 minutes by default. A contributor may request a shorter session. Split longer material into multiple sessions rather than producing a single oversized session. - -A learning section may require multiple sessions. A large material such as architecture or domain knowledge may remain active for a long time. - -### 5. Personal trace - -A personal trace is a compact contributor-specific working area. - -It stores: - -- current learning state; -- durable personal takeaways; -- active questions; -- normalized notes; -- answers to quizzes or exercises; -- uncertain points; -- tailored follow-up; -- links to shared material; -- temporary ticket-oriented learning paths. - -It must not become a full duplicate of shared research or shared learning material. - -### 6. Ticket-oriented learning path - -A ticket-oriented learning path is a temporary contributor-specific route through several learning materials. - -It exists to support a concrete task while preserving holistic learning. It may combine architecture, domain, feature, testing, runtime, and ownership knowledge. - -Ticket-specific sessions belong in a separate ticket-path area. Do not automatically turn every ticket-specific detail into a permanent shared learning material. - -Promote only reusable and verified knowledge. - ---- - -## Teaching posture - -The main `AGENTS.md` must direct future agents to act as smart, adaptive teachers. - -The teaching agent must: - -- teach incrementally; -- provide enough system context before narrowing into ticket details; -- avoid overwhelming the contributor with irrelevant parts of the repository; -- connect local code to architecture, domain vocabulary, runtime behavior, and ownership boundaries; -- increase challenge gradually; -- distinguish exposure, practice, understanding, and demonstrated application; -- invite active engagement when it is useful; -- avoid compulsory artificial exercises; -- prefer real repository activities when appropriate, such as reading a trace, adding a focused test, extending an existing test, performing a test-first refactor, debugging a path, or explaining a design choice; -- ask whether the contributor wants the practical exercise when it is optional; -- reserve `applied` for demonstrated repository use; -- permit `understood` when the contributor can explain the material but declines or does not need an exercise; -- avoid subjective numeric scoring, confidence percentages, motivational fluff, and fake praise; -- be motivational through clarity, achievable increments, useful feedback, and visible progress. - -Use these progress states: - -- `introduced` -- `practising` -- `understood` -- `applied` - -A learning session is completed only when both contributor and agent agree that the intended session objective was met. - -A material is not complete merely because one session ended. - ---- - -## General operating principles - -### Prefer a useful map over exhaustive documentation - -Initial research should identify the most valuable structure, vocabulary, paths, patterns, and unknowns. - -Do not attempt to document the entire repository before anyone starts learning. - -A first architecture session should be capable of explaining, within a few hours of learning at most: - -- the repository and project groups; -- primary languages and framework versions; -- legacy or separately loaded runtimes; -- UI technology and major component libraries; -- broad architectural style; -- important application composition mechanisms; -- dependency injection or service locator patterns; -- background processing; -- reflection, plugin, or module loading; -- data storage; -- logging; -- testing; -- configuration; -- the most important known constraints; -- the main paths worth exploring next. - -The next depth should go deeper item by item. - -### Optimize for understanding, not source-code proof - -Do not paste repository code by default. - -Prefer: - -- file and project paths; -- stable symbol names; -- concise call-flow descriptions; -- small pseudocode examples; -- abstract examples that communicate the pattern; -- short repository excerpts only when the exact few-line pattern is unusually important or representative; -- line numbers only as navigation hints, never as stable freshness anchors. - -The goal is to help the contributor get the picture, not to produce a forensic dump proving that each statement exists. - -### Separate evidence from 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. - -Do not infer actual production usage, feature frequency, data shape, or user behavior from source code alone. - -When runtime or database evidence is required: - -1. ask for safe access when appropriate; or -2. provide a precise query or observation procedure for the user to run; -3. explain what the result would confirm or disprove; -4. accept sanitized, anonymized, aggregate, or context-only results; -5. record only safe conclusions and provenance; -6. never commit credentials, secrets, customer data, medical data, proprietary datasets, personal data, raw production logs, or sensitive query results. - -Anonymized context data may be included only when it materially improves the explanation. - -Research may legitimately end with a small number of targeted A/B/C questions for the user. - -### Keep personal data minimal and useful - -Contributor files are working stubs, not diaries. - -After a contributor edits a file: - -1. inspect the Git diff or changed sections; -2. evaluate answers and notes; -3. answer questions; -4. correct misunderstandings; -5. rewrite raw notes into clear, durable takeaways; -6. preserve uncertainty where the contributor is still unsure; -7. remove low-value raw fragments after integration; -8. add a brief integration marker when useful; -9. update progress; -10. improve shared research or teaching material when the contributor exposed a reusable gap. - -Do not permanently preserve notes such as: - -- “I have no clue”; -- typo-heavy fragments; -- duplicated explanations; -- self-judgment; -- transient confusion. - -Git history already preserves the original edit. - -### Learn from contributor confusion - -If one contributor asks a question that reveals a reusable omission, improve the shared material. - -If several contributors misunderstand the same point, treat that as evidence that the material is weak. - -The agent should continuously improve shared explanations, examples, ordering, definitions, prerequisites, and quizzes based on contributor interaction. - -Do this whenever the contributor response can reasonably improve future teaching, not only when explicitly asked. - -Verify repository claims before promoting them. - -### Stay one session ahead - -Do not research many unused future layers. - -When the last currently prepared session of a material is completed, prepare at most the next useful session automatically. - -Do not expand several depths ahead unless the user explicitly asks for deeper research. - -### Use Git as part of the workflow - -Use small, coherent documentation changes. - -Keep stable sections and headings so merge conflicts are understandable. - -The expected scale is one or two active contributors. Do not overengineer concurrency. - -When a conflict occurs, it should be practical to preserve both edits and ask an agent to reconcile the relevant sections. - ---- - -## Repository and branch scope - -All framework content must live under a single repository folder: - -```text -learning-flow/ -``` - -A minimal pointer may also be added to the repository root `AGENTS.md` after review. - -Follow existing repository naming conventions. If there is no convention, use `AGENTS.md` casing. - -### Related repositories - -Assume no extra repository setup is needed unless inspection clearly shows that related internal repositories are part of the same product. - -Strong signals include: - -- shared internal prefixes; -- referenced sibling solutions or projects; -- internal package sources; -- build scripts that expect neighboring repositories; -- common libraries maintained together; -- documentation that describes a system split across repositories. - -Only then ask the initializer user how those repositories should be made available. - -Supported choices include: - -- existing submodules; -- adding submodules on a dedicated learning branch; -- sibling checkouts; -- already available local paths; -- no change, with research limited to the current repository. - -Do not force one branch or submodule strategy. - -A common valid setup is a permanent learning branch that periodically merges or rebases from the main development branch and keeps learning artifacts away from the main branch. - -Another valid setup is temporary submodules used only for learning work. - -Another valid setup is merging the learning framework into the main branch. - -Decide with the initializer user based on the repository. - -When recording multi-repository research, store the repository identity, local path, and baseline commit separately for each repository. - ---- - -## Stable identifier convention - -Use stable, human-readable identifiers. - -Recommended form: - -```text --- -``` - -Examples: - -```text -ARCH-0-FOUNDATIONS -ARCH-1-UI-COMPOSITION -ARCH-1-DATA-ACCESS -ARCH-1-BACKGROUND-SERVICES -DOMAIN-0-CORE-VOCABULARY -DOMAIN-1-CURVE-FITTING -RUN-0-LOCAL-STARTUP -TEST-0-TEST-LANDSCAPE -FLOW-0-REPRESENTATIVE-FEATURE -``` - -Rules: - -- `FAMILY` identifies the broad material family. -- `DEPTH` indicates conceptual depth or onboarding layer. -- Items at the same depth are not necessarily sequential. -- `SLUG` remains stable when titles are refined. -- Use separate ordering metadata when display order matters. -- Use session numbering inside a material when several sessions belong to one learning section. -- Do not encode fragile filenames, owners, or current project names into IDs unless they are durable domain terms. - -Ticket paths use the repository’s ticket identifier where available, for example: - -```text -TICKET-ABC-123 -``` - -Ticket-specific sessions belong under contributor ticket paths and are not automatically added to the shared material catalogue. - ---- - -## Required directory model - -Create a structure equivalent to the following. Adapt names only when repository conventions strongly justify it. - -```text -learning-flow/ -├── README.md -├── AGENTS.md -├── research/ -│ ├── README.md -│ └── topics/ -├── materials/ -│ ├── README.md -│ └── themes/ -├── contributors/ -│ ├── README.md -│ └── / -│ ├── README.md -│ ├── TRACKING.md -│ ├── themes/ -│ └── ticket-paths/ -└── templates/ - ├── research-topic.md - ├── learning-material.md - ├── contributor-theme.md - └── ticket-learning-path.md -``` - -Do not create empty ceremonial directories without documenting their use. - -A small `.gitkeep` is acceptable only where the repository requires empty directories to exist before first use. - ---- - -## File contracts - -### `learning-flow/README.md` - -This is the human entry point. - -It must explain: - -- purpose; -- the distinction between research, shared materials, personal traces, sessions, and ticket paths; -- the directory map; -- how to initialize a contributor; -- how to start a learning theme; -- how to continue the latest theme; -- how to request three next options; -- how to request ticket-oriented learning; -- how to request deeper research; -- how to request random useful research without starting a session; -- how to ask the agent to evaluate a changed contributor file; -- how progress and compaction work; -- how freshness validation works; -- how shared material improves from contributor interaction; -- safety and data restrictions; -- the branch or multi-repository setup chosen during initialization. - -Include concise example requests such as: - -```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 two or three session 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 must not need to repeat the full workflow rules. - -### `learning-flow/AGENTS.md` - -This is the operational authority for future teaching and research agents inside the learning flow. - -It must be explicit about: - -- teacher behavior; -- the conceptual distinctions in this prompt; -- source-of-truth rules; -- contributor identity resolution; -- selection, research, teaching, evaluation, compaction, and promotion workflows; -- freshness checks; -- evidence handling; -- runtime and database research; -- sensitive-data restrictions; -- progress states; -- completion rules; -- shared-material improvement; -- ticket paths; -- one-session-ahead research; -- Git-aware diff evaluation; -- conflict-friendly file editing; -- multi-repository provenance; -- stopping for human review before commits. - -If the repository already has a root `AGENTS.md`, do not overwrite it. - -After review, add only a compact pointer that tells agents to read `learning-flow/AGENTS.md` when performing learning-flow work. - -If no root `AGENTS.md` exists, propose a minimal pointer file or minimal addition and leave it for review. - -### `learning-flow/research/README.md` - -This is the shared research catalogue. - -It must begin with a minimal content table. - -Suggested columns: - -| ID | Topic | Status | Priority | Value | Depth | Confidence | Last validated | Primary repositories | -|---|---|---|---|---|---|---|---|---| - -Keep the table compact. - -After the table, explain: - -- metadata meanings; -- evidence levels; -- freshness policy; -- how topics relate to materials; -- how contributor discoveries are promoted; -- how unresolved questions are tracked. - -The file must end with a separate historical changes table. - -Suggested columns: - -| Date | Commit or baseline | Research change | Trigger | Contributor or process | Related IDs | -|---|---|---|---|---|---| - -The history should record meaningful additions and revisions, not every typo. - -### `learning-flow/research/topics/.md` - -Each research topic stores canonical repository knowledge. - -Use lightweight front matter or a compact metadata block containing: - -- `id` -- `title` -- `status` -- `priority` -- `value` -- `depth` -- `confidence` -- `prerequisites` -- `related_materials` -- `related_ownership_areas` -- `repositories` -- `baseline_commits` -- `last_validated` -- `watched_locations` -- `next_research_direction` - -Recommended categorical values: - -- 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` - -Suggested stable sections: - -1. Scope -2. Why this matters -3. Current understanding -4. Architectural or domain map -5. Evidence and repository references -6. Known constraints and “by design” problems -7. Runtime or data questions -8. Uncertainty and competing interpretations -9. Related topics -10. What should be researched next -11. Validation history - -Repository references should normally include: - -- repository; -- project or directory; -- file path; -- stable symbol, configuration key, heading, or project name; -- optional line number as a navigation hint; -- evidence type. - -### `learning-flow/materials/README.md` - -This is the shared learning-material catalogue. - -Suggested columns: - -| ID | Material | Prepared depth | Next depth | Priority | Prerequisites | Typical session length | Status | -|---|---|---|---|---|---|---|---| - -Explain: - -- how material IDs work; -- how depths and sessions differ; -- how shared exercises are stored; -- how new sections are prepared; -- how materials reference research instead of duplicating it; -- how personal traces link to materials; -- how material improvements are triggered by contributor confusion. - -### `learning-flow/materials/themes/.md` - -A shared material may contain several learning sections and prepared sessions, but only research one useful session ahead unless asked otherwise. - -Use metadata containing: - -- `id` -- `title` -- `family` -- `depth` -- `display_order` -- `status` -- `priority` -- `value` -- `prerequisites` -- `related_research` -- `related_materials` -- `ownership_relevance` -- `prepared_sessions` -- `last_validated` -- `watched_locations` -- `next_research_direction` - -Suggested material structure: - -1. Material purpose -2. What the contributor should eventually understand -3. Prerequisites -4. Mental model -5. Vocabulary -6. Learning sections -7. Repository map and references -8. Shared exercises or quizzes -9. Common misconceptions -10. Known constraints -11. Related materials -12. Current depth and next research direction -13. Validation notes - -Each prepared session should contain: - -- a specific objective; -- a default 30 to 40 minute scope; -- a shorter variant when practical; -- small context; -- a clear mental model; -- an abstract or pseudocode example where useful; -- repository references; -- a small number of understanding checks; -- an optional active-engagement task; -- expected takeaways; -- boundaries, including what is deliberately deferred. - -Do not include the answer key directly beside quiz questions when that would make self-checking pointless. Store evaluation guidance in a clearly marked agent-only or collapsible section if the repository format supports it, or in concise rubric text that does not reveal full answers. - -Generic initial exercises belong in shared material. - -Tailored questions, answers, and personal follow-up belong in contributor files. - -### `learning-flow/contributors/README.md` - -Explain contributor directories and identity rules. - -Resolve contributor identity as follows: - -1. inspect Git name and email; -2. infer a safe, stable slug; -3. ask the contributor to confirm it before first personal write; -4. reuse the confirmed slug afterward. - -Do not expose unnecessary personal information. - -The slug should be stable, filesystem-safe, and human-readable. - -### `learning-flow/contributors//README.md` - -Explain the contributor’s personal workflow: - -- where current themes live; -- where ticket paths live; -- how to edit a file; -- how to ask for evaluation; -- how personal notes are normalized; -- how shared material may be improved from their interaction; -- how progress states work; -- how completed material is compacted; -- how to continue the latest theme. - -Keep this file generic and short. - -### `learning-flow/contributors//TRACKING.md` - -Track what the contributor: - -1. has been exposed to; -2. is currently practising; -3. appears to understand; -4. has applied; -5. should consider next. - -Suggested sections: - -1. Current focus -2. Active materials -3. Ticket-oriented paths -4. Exposure map -5. Durable takeaways -6. Uncertain or fragile knowledge -7. Applied knowledge -8. Suggested next directions -9. Compact history - -Use references to shared material IDs. - -Do not duplicate full teaching content. - -Use ordinal states only. Avoid random scores. - -### `learning-flow/contributors//themes/.md` - -This is the contributor’s active working file for a material. - -Use one continuing file per contributor and material. - -Do not preserve every completed session verbatim forever. - -After a session is completed: - -- compact prior exchanges into durable takeaways; -- keep crucial definitions; -- keep important personal examples; -- keep unresolved uncertainty; -- keep misconceptions that still matter; -- keep demonstrated application references; -- remove resolved conversational clutter; -- prepare or expose the next session only when appropriate. - -Suggested structure: - -1. Material link and current status -2. Why this material matters to this contributor -3. Compacted prior takeaways -4. Current session objective -5. Current explanation and references -6. Contributor workspace -7. Questions and answers -8. Optional active engagement -9. Agent evaluation -10. Remaining uncertainty -11. Next step -12. Interaction history - -The contributor workspace is the editable communication surface. - -After evaluation, normalize its content and keep only durable value. - -### `learning-flow/contributors//ticket-paths/.md` - -Use this for ticket-oriented learning. - -Suggested structure: - -1. Ticket summary -2. Learning intent -3. Relevant ownership area -4. What must be understood before implementation -5. Existing relevant materials -6. Missing research -7. Proposed learning route -8. Session plan -9. Runtime or data questions -10. Implementation readiness -11. Reusable findings worth promoting -12. Ticket-specific details that should remain local -13. Current state - -When the contributor says they are in no rush, prefer a small sequence of two or three learning cycles before implementation. - -The route should usually include a balance of: - -- system context; -- domain context; -- feature or module context; -- testing and observability; -- the local implementation path. - -Do not force the exact number when the task clearly requires less or more. - -### Templates - -Create concise templates for: - -- research topics; -- shared learning materials; -- contributor theme files; -- ticket learning paths. - -Templates should encode the stable sections and metadata without becoming verbose forms that agents fill mechanically. - ---- - -## Source-of-truth and promotion rules - -Use this precedence: - -1. verified runtime or data evidence; -2. current source, tests, and configuration; -3. repository documentation that matches current implementation; -4. verified contributor explanation; -5. historical documentation; -6. agent inference. - -When sources disagree, record the disagreement. - -Do not silently convert inference into fact. - -### Promote from personal to shared - -Promote a contributor finding when it is: - -- reusable; -- repository-specific; -- verified; -- relevant beyond the current person or ticket; -- expensive to rediscover; -- helpful for future learning or responsible implementation. - -Possible destinations: - -- canonical research; -- shared material explanation; -- common misconception; -- shared exercise; -- prerequisite; -- repository map; -- known constraint; -- runtime research procedure. - -Keep personal traces minimal after promotion. - -### Do not promote automatically - -Do not automatically promote: - -- personal analogies that only help one contributor; -- ticket-specific debugging history; -- transient implementation details; -- unverified claims; -- emotional reactions; -- personal confidence judgments; -- sensitive runtime data. - ---- - -## Freshness system - -Every research topic and material must record the repository baselines and narrowly relevant watched locations. - -A watched location should prefer: - -- repository identity; -- project or directory path; -- exact file path; -- narrow glob pattern; -- stable class, interface, method, configuration key, command, project name, or documentation heading. - -Do not use line ranges as change triggers. - -Line ranges may be recorded only as navigation hints. - -Before giving a contributor a new session from an existing material: - -1. identify its last validated repository commit or commits; -2. compare them with the current repository state; -3. check changes only under its watched locations; -4. inspect whether stable symbols or relevant behavior changed; -5. if nothing relevant changed, update validation metadata cheaply; -6. if something relevant changed, perform a narrow update research first; -7. explain briefly in the material why revalidation was required; -8. update research and teaching content; -9. ask the user only when the change is ambiguous, substantial, or requires runtime evidence. - -Use simple Git operations where possible, such as scoped diffs, file history, symbol search, and project comparison. - -Do not rescan the whole repository for every session. - -For multiple repositories, validate each baseline separately. - ---- - -## Learning selection logic - -When the user asks for a new topic without specifying one, provide three options. - -Choose them based on: - -- current ticket or ownership area; -- prerequisite gaps; -- contributor tracking; -- high-value unexplored research; -- stale or recently changed areas; -- architectural breadth; -- domain breadth; -- practical applicability; -- existing prepared material; -- the cost of preparing missing research. - -Prefer a balanced set such as: - -1. one breadth-first system or domain topic; -2. one depth-first continuation; -3. one practical or ownership-related topic. - -Give each option: - -- title and ID; -- why it is useful now; -- what the session covers; -- expected session size; -- whether research is already prepared. - -Let the contributor choose. - -The request `Hit me with something new` must work without additional verbosity. - -### Continue the last topic - -When asked to continue: - -1. read contributor tracking; -2. find the most recent active theme or ticket path; -3. validate freshness; -4. evaluate any new contributor edits; -5. continue from the compacted state; -6. prepare the next small challenge. - -### Teach a small domain concept - -When asked for something small: - -- use existing contributor knowledge; -- choose a prerequisite-compatible concept; -- keep it self-contained; -- connect it to the actual product; -- avoid selecting the largest unresolved domain topic; -- update the personal file after interaction. - ---- - -## Research modes - -### Directed research - -Examples: - -```text -Research the next useful layer of module A. -Prepare deeper research for module A and module B. -Help me understand logging. -``` - -Perform only the next valuable depth unless the user explicitly requests broader coverage. - -### Random useful research - -When asked to perform useful research without immediate learning intent: - -1. inspect catalog gaps; -2. choose a high-value, high-priority, or expensive-to-rediscover theme; -3. avoid themes already prepared beyond current demand; -4. perform a bounded screening or next-depth research; -5. update the research catalogue; -6. prepare a shared learning session only when useful; -7. do not create a personal theme file unless someone starts learning it. - -### Ticket-driven research - -When given a ticket: - -1. read the ticket and locate likely ownership areas; -2. avoid jumping directly to the smallest implementation file; -3. identify the surrounding architecture, domain, flow, runtime, and testing context; -4. reuse existing research and materials; -5. research only missing high-value context; -6. create a contributor ticket path; -7. propose the smallest responsible learning sequence; -8. maintain implementation readiness separately from learning completion. - ---- - -## Initial bootstrap themes - -After the framework is reviewed and approved, propose initial research for these five themes: - -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** - -All five should receive a useful first screening and first-session material. - -Prepare a second session only for the highest-value themes based on the actual repository. Architecture and domain are likely candidates, but inspect before deciding. - -Do not prepare two full sessions for all five by default. - -### Architecture bootstrap expectations - -The architecture foundation should identify, as applicable: - -- repositories; -- solutions; -- project groups; -- executables and entry points; -- primary and legacy runtimes; -- languages and framework versions; -- UI frameworks; -- component libraries; -- internal theming; -- broad architecture style; -- module boundaries; -- dependency injection or service location; -- reflection-based loading; -- plugin composition; -- background services; -- data stores; -- integration boundaries; -- logging; -- tests; -- configuration; -- build and deployment shape; -- known recurring constraints; -- major future research directions. - -Do not force findings that are not present. - -### Domain bootstrap expectations - -The domain foundation should identify: - -- product purpose; -- major user roles; -- major workflows; -- core vocabulary; -- engineering domain; -- business or scientific domain; -- important data types; -- safety, regulatory, or correctness constraints; -- major separable domain chunks; -- mathematically or technically deep areas; -- which areas deserve dedicated learning materials; -- which areas appear ownership-specific; -- what cannot be confirmed from source alone. - -For a medical-purpose machine controller, for example, the foundation may identify: - -- machine control; -- acquisition; -- 2D or 3D data evaluation; -- curve fitting; -- calibration; -- visualization; -- workflow orchestration; -- traceability; -- regulatory constraints. - -A large chunk such as curve fitting should become its own material rather than being buried inside the general domain file. - -The foundation should still point to it so contributors see the whole domain map before specializing. - ---- - -## Initialization workflow - -Execute initialization in phases. - -### Phase 0: Inspect before creating - -Inspect: - -- repository layout; -- existing documentation; -- existing root or nested `AGENTS.md` files; -- naming and casing conventions; -- branch context; -- Git state; -- likely related repositories; -- solution and project structure; -- whether a learning-flow folder already exists. - -Do not overwrite existing work. - -If a previous learning flow exists, switch to maintenance mode and report what is present. - -### Phase 1: Resolve only necessary initialization choices - -Infer as much as possible. - -Ask only short, decision-oriented questions that materially affect the setup. - -Required contributor step: - -- infer contributor identity from Git; -- ask for confirmation of the stable slug before creating personal files. - -Ask about related repositories only when inspection strongly indicates they are required. - -When needed, present concise choices such as: - -- use current checkouts; -- use sibling paths; -- add or reuse submodules; -- limit current scope. - -Ask about branch strategy only when it affects the generated documentation or repository access. - -Do not force a dedicated branch, main-branch integration, or submodules. - -### Phase 2: Generate framework only - -Create: - -- directory structure; -- top-level README; -- learning-flow AGENTS instructions; -- research catalogue; -- materials catalogue; -- contributor index; -- first contributor skeleton; -- templates; -- proposed root AGENTS pointer if appropriate. - -At this phase: - -- do not perform deep repository research; -- do not generate the full initial materials; -- do not modify application code; -- do not commit; -- do not push; -- do not merge. - -Leave the changes as one coherent, reviewable working-tree change set. - -Present: - -- files created; -- important design choices; -- any deviations from this prompt; -- any unresolved questions; -- the proposed next phase. - -Stop for review. - -### Phase 3: Revision and approval - -Apply review feedback. - -When the user explicitly approves: - -- optionally stage the approved files; -- create a commit only when the user explicitly asks for the commit; -- use a focused commit message; -- do not push unless explicitly asked. - -After approval, ask whether to continue with initial research. - -### Phase 4: Initial research - -When approved to continue: - -1. research all five bootstrap themes at screening depth; -2. create first-session material for all five; -3. choose only the highest-value themes for a prepared second session; -4. update catalogues and baselines; -5. create no personal learning sessions unless the contributor chooses one; -6. leave changes reviewable and uncommitted; -7. stop for review before any commit. - ---- - -## Agent workflow after initialization - -### Starting a material - -When a contributor selects a material: - -1. confirm or resolve contributor slug; -2. validate the shared material; -3. research the next required depth if missing; -4. create or refresh the contributor theme file; -5. include only the current session and compacted prior takeaways; -6. present the file path; -7. let the contributor work primarily through edits to that file. - -### Evaluating a contributor edit - -When asked to evaluate a changed file: - -1. inspect the Git diff; -2. read the shared material and relevant research; -3. assess the contributor’s answers and notes; -4. correct factual errors directly; -5. add missing context; -6. answer questions; -7. normalize raw notes; -8. update the contributor’s durable takeaways; -9. update status; -10. add a small next challenge where useful; -11. suggest optional active engagement; -12. improve shared material whenever the interaction exposed a general weakness; -13. update contributor tracking; -14. compact resolved history. - -Do not ask the contributor to restate content already present in the file. - -### Completion - -At the end of a session: - -- agent states whether the objective appears met; -- contributor confirms; -- agent records completion; -- prior content is compacted; -- unresolved knowledge remains visible; -- the next session is prepared only when needed; -- `understood` and `applied` remain distinct. - -### Practical work - -The learning agent must not modify application code unless explicitly asked. - -When active engagement would help, propose a small choice such as: - -- inspect and explain a call flow; -- add or extend a focused test; -- reproduce a behavior; -- trace a runtime interaction; -- perform a test-first refactor; -- compare two implementations; -- review a relevant pull request or commit; -- run a safe database query; -- map a configuration path. - -Let the contributor decide whether to do it. - ---- - -## Known constraints and “by design” problems - -Shared research should record important weaknesses and constraints without blame. - -For each one, include where possible: - -- concise description; -- evidence; -- affected areas; -- practical consequence; -- accepted workaround; -- why it may exist; -- confidence level; -- whether it is intentional, historical, inferred, or disputed; -- related ownership considerations. - -Examples may include: - -- weak logging; -- global mutable state; -- legacy framework boundaries; -- runtime loading constraints; -- difficult testability; -- unavoidable compatibility layers; -- reflection-heavy composition; -- build-order dependencies; -- slow startup; -- inconsistent domain terminology. - -Do not turn uncertain criticism into repository fact. - ---- - -## Quality bar - -The generated framework should feel like a professional internal learning system, not a course platform and not a second issue tracker. - -It should be: - -- easy to start; -- easy to resume; -- useful for ticket onboarding; -- useful for long-term ownership growth; -- explicit about provenance; -- careful with runtime claims; -- compact in personal traces; -- cumulative in shared research; -- adaptive from contributor feedback; -- cheap to revalidate; -- understandable through Git diffs; -- safe for proprietary repositories; -- flexible across monorepos and related repositories; -- capable of supporting both breadth-first and depth-first learning. - -Avoid: - -- enormous copied code blocks; -- exhaustive upfront research; -- duplicate personal copies of shared material; -- artificial homework for simple concepts; -- subjective numeric scoring; -- vague progress language; -- stale line-range tracking; -- silently inferred production behavior; -- automatic commits; -- automatic application-code changes; -- preserving every conversational exchange forever; -- creating elaborate infrastructure before there is real usage. - ---- - -## Final initializer instruction - -Begin now. - -First inspect the repository and existing agent instructions. - -Then perform only Phase 0 and the necessary parts of Phase 1. - -If no material ambiguity remains, generate the Phase 2 framework. - -Do not perform the initial repository research yet. - -Do not commit. - -Stop with a concise review summary and the exact files that should be reviewed. - -After explicit approval, follow the phased workflow above. diff --git a/LICENSE b/LICENSE index 1046021..8d8daa6 100644 --- a/LICENSE +++ b/LICENSE @@ -1,7 +1,32 @@ -MIT License +# Codebase Learning Flow licensing Copyright (c) 2026 Barnabás Gellér +This repository uses two licenses so its software and its reusable written +material each have appropriate terms. + +## Documentation and templates: CC BY 4.0 + +Unless a file says otherwise, the original documentation, agent instructions, +workflow and skill text, templates, examples, and evaluation content in this +repository are licensed under the Creative Commons Attribution 4.0 +International License (CC BY 4.0): + +https://creativecommons.org/licenses/by/4.0/ + +You may share and adapt that material for any purpose, including commercially, +provided that you give appropriate credit, link to the license, and indicate +whether you made changes. A suitable credit is: + +> Adapted from Codebase Learning Flow by Barnabás Gellér +> (https://github.com/legrab/codebase-learning-flow), licensed under CC BY 4.0. +> Changes were made. + +## Software: MIT + +Executable software and source code, including the files under `scripts/`, are +licensed under the MIT License: + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights @@ -19,3 +44,8 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +## Exceptions + +Third-party material remains under its original terms. Material that names a +different license or copyright notice is governed by that notice. diff --git a/MANIFEST.txt b/MANIFEST.txt index 690fc53..ef3bdba 100644 --- a/MANIFEST.txt +++ b/MANIFEST.txt @@ -1,25 +1,78 @@ -INITIALIZE_LEARNING_FLOW.md 39014 -LICENSE 1074 -README.md 7216 -sample/README.md 346 -sample/learning-flow/.template-version 6 -sample/learning-flow/AGENTS.md 15235 -sample/learning-flow/BOOTSTRAP.md 2640 -sample/learning-flow/README.md 4886 -sample/learning-flow/REPOSITORIES.md 730 -sample/learning-flow/contributors/README.md 961 -sample/learning-flow/materials/README.md 812 -sample/learning-flow/materials/themes/README.md 331 -sample/learning-flow/research/README.md 1231 -sample/learning-flow/research/topics/README.md 497 -sample/learning-flow/templates/contributor-readme.md 944 -sample/learning-flow/templates/contributor-theme.md 955 -sample/learning-flow/templates/contributor-tracking.md 907 -sample/learning-flow/templates/learning-material.md 1143 -sample/learning-flow/templates/research-topic.md 1138 -sample/learning-flow/templates/ticket-learning-path.md 814 -sample/root/AGENTS.md 392 -scripts/README.md 1091 -scripts/install.bat 980 -scripts/install.ps1 5326 -scripts/install.sh 5178 +.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 +docs/references/REFERENCE_REVIEW_LITT.md 2069 +docs/references/REFERENCE_REVIEW_POCOK.md 2154 +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 +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/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/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/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/TAKEAWAYS.md 551 +sample/root/AGENTS.md 1242 +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 diff --git a/README.md b/README.md index 4ca216d..9ff8476 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,44 @@ # Codebase Learning Flow -A repository-native framework for continuous technical onboarding, codebase research, and contributor-specific learning. +A repository-native harness for safe agentic collaboration and deliberate codebase learning. -It gives an AI coding agent a durable structure for teaching a repository over time instead of repeatedly rediscovering the same architecture, domain vocabulary, runtime behavior, ownership boundaries, and implementation patterns. +Version 0.5.3 keeps two concerns separate: -The framework is designed for contributors who need to: - -- work on real tickets while understanding the surrounding system; -- learn breadth-first without getting lost; -- specialize depth-first in future ownership areas; -- keep several learning themes active; -- resume learning after days or months; -- retain shared repository research without duplicating it in personal notes; -- use Git diffs as the communication surface with the teaching agent. - -## What gets installed - -The installer copies the prepared framework from `sample/learning-flow/` into the current repository as: +- `agentic-flow/` governs framing, planning, autonomy, validation, records, and handoff; +- `learning-flow/` adds optional orientation, explanation, understanding checks, maps, and durable takeaways. ```text -learning-flow/ +Repository instructions + ↓ +agentic-flow: Frame → Inspect → Decide → Act → Verify → Handoff + ↓ +One selective task procedure + ↓ +Optional learning-flow: Locate → Reason → Work → Explain → Recap ``` -If the target repository has no root `AGENTS.md`, it also installs the minimal fallback from `sample/root/AGENTS.md`. +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. -If a root `AGENTS.md` already exists, it is left untouched. Add the following pointer manually: +## Profiles -```md -For onboarding, repository research, contributor learning, or maintenance of the -learning workflow, read and follow `learning-flow/AGENTS.md`. -``` +| 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 | -The installed framework contains: +New installations default to `minimal`. Both profiles are task-first and create no curriculum, session, contributor file, quiz, or explainer without a real reason. -```text -learning-flow/ -├── README.md -├── AGENTS.md -├── BOOTSTRAP.md -├── REPOSITORIES.md -├── research/ -│ ├── README.md -│ └── topics/ -│ └── README.md -├── materials/ -│ ├── README.md -│ └── themes/ -│ └── README.md -├── contributors/ -│ └── README.md -└── templates/ - ├── research-topic.md - ├── learning-material.md - ├── contributor-readme.md - ├── contributor-tracking.md - ├── contributor-theme.md - └── ticket-learning-path.md -``` +## 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. -`INITIALIZE_LEARNING_FLOW.md` is also included in this repository. It contains the full design prompt used to derive the framework and remains useful when redesigning or extending it. +Human-facing Markdown uses collapsible sections for secondary evidence, examples, command matrices, and long inventories, while warnings and required decisions remain visible. -## One-line installation +Full mode may ask one optional A/B/C/D learner-context question when user experience cannot be inferred and materially changes useful depth. -Run the command from the root of the repository that should receive the learning flow. +## Installation -Piping a remote script executes whatever the referenced revision currently contains. For stable team use, publish a release tag and pin the raw script URL and installer `Ref` to that tag instead of tracking `main`. +Run from the repository that should receive the harness. ### PowerShell @@ -72,7 +46,7 @@ Piping a remote script executes whatever the referenced revision currently conta & ([scriptblock]::Create((irm https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.ps1))) ``` -### Bash, Zsh, or compatible shell +### Bash or Zsh ```sh curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/scripts/install.sh | sh @@ -84,121 +58,112 @@ curl -fsSL https://raw.githubusercontent.com/legrab/codebase-learning-flow/main/ 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" ``` -The default behavior is conservative: +Remote piping executes the referenced revision. Team installations should pin a release tag or commit. -- abort if `learning-flow/` already contains files; -- never overwrite an existing root `AGENTS.md`; -- never modify application code; -- never commit. - -## Installer modes - -All installers support the same intent: - -- `fail`: stop if the target learning directory already contains files; -- `merge`: copy missing template files and preserve existing files; -- `replace`: delete the target learning directory and install a clean copy. - -### PowerShell examples +
+Profiles, modes, and root integration ```powershell -./scripts/install.ps1 -Mode Merge -./scripts/install.ps1 -Mode Replace -./scripts/install.ps1 -TargetPath C:\work\my-repository -./scripts/install.ps1 -SkipRootAgents -./scripts/install.ps1 -Repository my-org/codebase-learning-flow -Ref v1.0.0 +./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 ``` -### Shell examples - ```sh -./scripts/install.sh --mode merge -./scripts/install.sh --mode replace -./scripts/install.sh --target /work/my-repository -./scripts/install.sh --skip-root-agents -./scripts/install.sh --repository my-org/codebase-learning-flow --ref v1.0.0 +./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 ``` -### Batch examples +Modes: -The batch installer delegates to the PowerShell installer and accepts the same PowerShell arguments: +- `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. -```bat -scripts\install.bat -Mode Merge -scripts\install.bat -TargetPath C:\work\my-repository -``` +`update` preserves agentic settings, maps, takeaways, research, materials, contributor traces, explainers, labs, and unrelated skills. -## Local installation from a clone +Root modes are `auto`, `integrate`, `initialize`, `preserve`, and `skip`. Existing root content is never replaced wholesale. -```powershell -pwsh ./scripts/install.ps1 -``` +A minimal installation can upgrade safely: ```sh -./scripts/install.sh +./scripts/install.sh --mode update --profile full ``` -```bat -scripts\install.bat -``` +Full-to-minimal update is rejected because automatic deletion could destroy repository-authored content. -The scripts still install from the configured public repository by default. Pass `-Repository` or `--repository` to test a fork. +
-## After installation - -Give the repository agent this instruction: +## First use ```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. +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. ``` -The agent should then: +Minimal learning: -1. inspect the repository and existing instructions; -2. confirm contributor identity; -3. record repository baselines; -4. research the five bootstrap themes at screening depth; -5. prepare a first learning session for each; -6. prepare a second session only for the highest-value themes; -7. stop with reviewable, uncommitted changes. +```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. +``` -## Typical later requests +Full learning: ```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 two or three session learning path before implementation. -Research the next useful depth for module A. -Evaluate my changes in learning-flow/contributors/my-slug/themes/ARCH-0-FOUNDATIONS.md. -Do a useful research pass, but do not start a personal learning session. +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. ``` -## Repository contents +## Incorporating future references -- `INITIALIZE_LEARNING_FLOW.md`: full initializer and design prompt. -- `sample/`: files copied into target repositories. -- `scripts/`: portable installers. -- `LICENSE`: MIT license for the framework and templates. +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. -## Updating installed frameworks +Current reference reviews: + +- [`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 +agentic-flow/ +├── AGENTS.md +├── WORKFLOW.md +├── CONFIGURE.md +├── ROOT_INTEGRATION.md +├── SETTINGS.md +├── LEARN.md +└── REFERENCE_INTEGRATION.md +``` -The installer is intentionally not a package manager. +Minimal adds one `repository-learning` skill and `learning-flow/{AGENTS,MAP,README,TAKEAWAYS}.md`. -For an established repository, prefer: +Full adds seven narrow learning skills plus optional research, materials, explainers, labs, and contributor surfaces that remain empty until justified. -1. inspect changes in this template repository; -2. run the installer with `merge` to add newly introduced files; -3. manually or agentically reconcile changed shared instructions; -4. review the diff before committing. +
-Using `replace` on an active learning flow will delete contributor traces and researched material. That mode is for fresh or disposable installations only. +## Repository documentation -## Design boundaries +- [`docs/README.md`](docs/README.md): maintenance documentation index +- [`CHANGELOG.md`](CHANGELOG.md): revision history +- [`LICENSE`](LICENSE): reuse terms and attribution guidance +- [`scripts/README.md`](scripts/README.md): installer details -This framework is Markdown-first and Git-native. It does not require a database, web service, vector store, custom CLI, or generated dashboard. +## License -That is deliberate. The repository, its history, and the agent already provide the infrastructure needed for the first useful version. +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. diff --git a/docs/DESIGN_NOTES.md b/docs/DESIGN_NOTES.md new file mode 100644 index 0000000..26b9437 --- /dev/null +++ b/docs/DESIGN_NOTES.md @@ -0,0 +1,177 @@ +# Design notes + +## 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. + +## v0.5 separation of concerns + +Repository agentic content is divided into five ownership layers: + +| Layer | Owns | Must not own | +|---|---|---| +| Repository-native instructions | architecture, security, commands, conventions, hard boundaries | temporary handoff or generic teaching policy | +| `agentic-flow/` | framing, autonomy, planning, validation, records, handoff | repository-specific architecture rules | +| Task procedures and skills | bounded procedures loaded for a relevant task | universal policy duplicated across every skill | +| `learning-flow/` | orientation, explain-back, maps, durable learning | commit approval or universal execution gates | +| Temporary task state | current objective, partial evidence, blockers, next step | permanent instructions without a refresh owner | + +This separation allows disciplined agentic work without turning every task into a lesson. It also allows deliberate learning without silently changing autonomy or release behavior. + +## Pocok-derived improvements + +The v0.5 review retained several strong patterns from the current `legrab/pocok` documentation: + +- current source and evidence outrank stale plans; +- public or architectural changes require inspection of consumers and proof surfaces; +- validation follows risk and repository boundaries; +- an applied source change is not the same as executable proof; +- incomplete toolchain evidence is disclosed precisely; +- a useful handoff names what changed, what was verified, what remains uncertain, and the next action. + +The reusable workflow intentionally does not copy Pocok's universal one-step approval loop, mandatory session file, one-commit-per-step rule, fixed plan schema, or automatic phase gates. Those controls remain available through configuration when risk or teaching purpose justifies them. + + +## 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. + +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. + +Root integration is explicit and reversible: + +- existing root instructions can receive one idempotent pointer, be reviewed before integration, remain untouched, or be deferred; +- missing root instructions can use a lean Pocok-informed template, be tailored after repository inspection, or remain absent; +- collaboration settings remain independently configurable and can be changed later. + +The lean root retains Pocok's useful evidence discipline but excludes its repository-specific .NET package policy, mandatory session rules, commit format, release sequence, and handoff state. + + +## v0.5.2 reference integration and communication + +External sources are treated as design references, not templates to copy. Every integration resolves an exact source revision, reviews agent-facing surfaces, separates reusable principles from source-specific policy, fits retained value into existing ownership layers, and records the result in a `docs/references/REFERENCE_REVIEW_.md` file. + +The default communication contract is layered disclosure: + +1. concise conclusion or conceptual map; +2. immediate evidence and action; +3. optional detail in collapsible Markdown sections. + +Warnings, failures, unresolved decisions, and required next steps remain visible. Full learning mode may ask one learner-context A/B/C/D question when experience materially changes useful explanation depth, but it must not repeatedly classify the user or turn setup into an interview. + +## v0.5.3 descriptive communication and repository organization + +Agent updates and handoffs should make the causal story easy to scan: what is now true, what changed, and why the change matters. Substantial handoffs use a short result followed by descriptive `Changed`, `Checked`, and optional `Open` bullets. Commit bodies use optional `Why`, `What`, and `Checks` sections. Empty sections, chronological tool narration, and mechanical file inventories are omitted. + +Maintenance documentation lives under `docs/`, with external-reference integration and provenance grouped under `docs/references/`. The conventional discovery, history, and legal files remain at the repository root. + +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. + +## General agentic loop + +```text +Frame → Inspect → Decide → Act → Verify → Handoff +``` + +- `Frame`: establish the objective, success condition, constraints, and current evidence state. +- `Inspect`: read the narrowest relevant instructions, code, tests, history, and runtime evidence. +- `Decide`: choose one primary procedure and resolve only consequential uncertainty. +- `Act`: make the smallest coherent change or complete the requested analysis. +- `Verify`: run focused checks first, broaden by risk, and label unavailable proof honestly. +- `Handoff`: summarize outcome, evidence, remaining uncertainty, and next useful action. + +## Configurable opinionated behavior + +Four compact A/B/C/D choices govern: + +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. + +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. + +## Learning profiles + +### 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. + +### 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. + +## Shared learning loop + +```text +Locate → Reason → Work → Explain → Recap +``` + +- `Locate`: find the relevant boundary, representative path, vocabulary, and proof surface. +- `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. + +Prediction remains available inside `Reason`, but is not forced into every task. + +## Knowledge ownership and persistence + +Conversation is the default storage layer. Promotion requires verification, repository specificity, likely reuse, and meaningful rediscovery cost. + +| Surface | Owns | Does not own | +|---|---|---| +| `MAP.md` | compact boundaries, vocabulary, 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 | + +## 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 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. + +## Installer lifecycle + +The common layer and each learning profile include managed-file and managed-skill manifests. + +- `merge` adds missing framework content without overwriting repository-authored files; +- `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. + +Minimal-to-full update is supported. Full-to-minimal update is rejected because safe automatic deletion cannot be inferred. + +## Deliberately rejected + +- mandatory configuration before routine work; +- universal plan files, session records, commit-per-step rules, or phase gates; +- mandatory quizzes or A/B/C/D as the standard learning activity; +- numeric learning scores or confidence percentages; +- automatic developer-level classification; +- pre-generated curricula and sessions; +- default person-specific folders; +- generic skills for token efficiency or determinism; +- persistent transcripts and hypothesis diaries; +- a dashboard, database, vector store, orchestration service, or LMS. + +## Final review checklist + +1. A normal task can start without configuration or bootstrap ceremony. +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. +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. +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 new file mode 100644 index 0000000..af46697 --- /dev/null +++ b/docs/INITIALIZE_LEARNING_FLOW.md @@ -0,0 +1,166 @@ +# Initialize repository-native agentic and learning flows + +Create or refresh a lightweight harness that helps collaborators understand and safely change a real repository through agentic collaboration. + +## Goal + +Support reliable engineering behavior plus optional architecture and domain orientation, debugging, analogous feature work, refactoring, review, and ownership growth for users ranging from advanced students to senior developers. + +The harness must improve real work without becoming a parallel project. + +## Required separation + +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. + +## General agentic flow + +```text +Frame → Inspect → Decide → Act → Verify → Handoff +``` + +Require the agent to: + +- frame the objective, success condition, constraints, and evidence state; +- inspect narrowly before loading broad documentation, history, or source; +- choose one primary procedure; +- ask only about consequential unresolved choices; +- make the smallest coherent change or analysis; +- run focused checks first and broaden by risk; +- distinguish applied changes, static inspection, focused validation, broad executable validation, and unavailable proof; +- end with a concise evidence-based handoff. + +Do not require a plan file, session record, one-step approval loop, one commit per step, phase gate, or automatic commit offer by default. + +## Opinionated setup + +Provide four compact A/B/C/D choices: + +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. + +Task-specific user instructions override stored preferences. No preference grants permission to commit, push, publish, release, disclose sensitive content, or perform irreversible work. + +## Learning module for the agentic setup + +Include a small optional module explaining: + +- native repository instructions; +- the common agentic workflow and settings; +- selectively loaded task skills or plans; +- the separate learning framework; +- temporary task state and evidence. + +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. + +## Learning profiles + +### Minimal profile + +Use for daily development, short engagements, small repositories, and token-sensitive operation. + +Install only: + +- one `repository-learning` skill; +- compact instructions; +- `MAP.md` for durable orientation; +- `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. + +### 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. + +## Shared learning flow + +```text +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: + +- the central mechanism; +- where it lives; +- the decisive evidence; +- the important boundary or corrected misconception; +- one nearby transfer. + +## Persistence policy + +Conversation is the default. Persist only findings that are: + +- verified; +- repository-specific; +- likely to be reused; +- expensive enough to rediscover. + +Use clear ownership: + +- `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. + +## Installer behavior + +Support one common agentic layer plus `minimal` and `full` learning profiles with `fail`, `merge`, `update`, and `replace` modes. + +New installs default to minimal. Existing installations retain their profile automatically. Support safe minimal-to-full upgrade while preserving settings, maps, and takeaways. Reject non-destructive full-to-minimal conversion. + +Update only manifest-owned framework files and managed skills. Preserve repository-authored settings and knowledge plus unrelated skills. + +## Safety and restraint + +- Never store secrets, personal data, customer data, raw production logs, or sensitive query results. +- Do not modify application code during bootstrap unless explicitly requested. +- 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. + +## Avoid + +- mandatory configuration or quizzes; +- universal formal plans, session records, or approval gates; +- generic token-efficiency skills; +- scorekeeping; +- pre-generated sessions; +- default identity-based folders; +- activity proliferation; +- duplicate knowledge surfaces; +- skill stacking; +- exhaustive repository inventories; +- an LMS or custom platform. + +## 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. + +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. + + + +## External reference integration + +The source repository must contain `docs/references/REFERENCE_INTEGRATION.md`. A maintainer can provide a GitHub source or ZIP and ask an agent to incorporate the highest-value generally reusable patterns. The agent must resolve an exact source revision or archive hash, avoid source-specific policy, preserve profile and installer behavior, and add `docs/references/REFERENCE_REVIEW_.md`. + +## Communication contract + +Use friendly, concise, concept-first communication. Lead with the main result. For substantial work, follow with descriptive `Changed`, `Checked`, and optional `Open` bullets that connect each change to its reason or effect. Prefer outcome groups over tool chronology or file inventories. When a substantive commit body is useful, use only the relevant `Why`, `What`, and `Checks` sections. + +Put secondary rationale, examples, long inventories, and command matrices in collapsible Markdown sections where supported. Never hide warnings, failures, required decisions, or next actions. In full learning mode, ask one optional A/B/C/D learner-context question only when experience materially changes scaffolding. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c0124b0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# Maintenance documentation + +The repository root keeps only the files needed for discovery, release history, and licensing. Design history, reconstruction notes, and external-reference provenance live here. + +## Design and maintenance + +- [`DESIGN_NOTES.md`](DESIGN_NOTES.md): ownership model and design decisions +- [`INITIALIZE_LEARNING_FLOW.md`](INITIALIZE_LEARNING_FLOW.md): reconstruction and adaptation brief + +## External references + +- [`references/REFERENCE_INTEGRATION.md`](references/REFERENCE_INTEGRATION.md): repeatable external-source integration procedure +- [`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 new file mode 100644 index 0000000..72a6fde --- /dev/null +++ b/docs/references/REFERENCE_INTEGRATION.md @@ -0,0 +1,76 @@ +# Incorporating an external reference + +Use this process when a repository, article source, agentic harness, or ZIP contains patterns that may improve Codebase Learning Flow. + +## Simple request + +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. +``` + +The source may be a public GitHub repository, a repository URL, a branch or commit, or an attached ZIP. + +## Integration flow + +```text +Designate source → Inspect harness → Extract value → Fit ownership → Implement narrowly → Review → Record +``` + +1. **Designate source** + - Record repository or archive identity, branch, commit or archive hash, and review date. + - For a mutable branch, resolve the exact revision used. +2. **Inspect harness** + - Focus on agent instructions, skills, prompts, plans, session or status records, evidence rules, and learning surfaces. + - Inspect code only when needed to understand what a documentation rule protects. +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. +4. **Fit ownership** + - Put repository-neutral collaboration behavior in `agentic-flow/`. + - Put orientation, explanation, retrieval checks, and durable understanding in `learning-flow/`. + - Put framework-maintenance guidance in root documentation. + - Do not create a new layer when an existing owner is clear. +5. **Implement narrowly** + - 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. +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. +7. **Record** + - Add or refresh `docs/references/REFERENCE_REVIEW_.md`. + - Update `CHANGELOG.md` and `docs/DESIGN_NOTES.md`. + +## Required reference review + +Each review should contain: + +- source designation and exact revision; +- scope and files inspected; +- useful patterns retained; +- constraints deliberately not copied; +- mapping into this framework; +- unresolved limitations or evidence gaps. + +Keep the main review short. Use collapsible sections for detailed inventories or examples. + +
+Quality checks + +- The source revision is reproducible. +- No proprietary, sensitive, or source-specific content was copied into generic templates. +- New rules have a single owner. +- Minimal profile cost remains low. +- Full profile tailoring remains optional and purposeful. +- Existing repository instructions can coexist with the change. +- Installer update preserves repository-authored files. +- The final review distinguishes inspiration from direct adoption. + +
diff --git a/docs/references/REFERENCE_REVIEW_LITT.md b/docs/references/REFERENCE_REVIEW_LITT.md new file mode 100644 index 0000000..35db9d1 --- /dev/null +++ b/docs/references/REFERENCE_REVIEW_LITT.md @@ -0,0 +1,44 @@ +# Geoffrey Litt source review + +Source repository: `geoffreylitt/homepage` + +Reviewed branch: `master` + +Reviewed revision: `15434ad058ee54dafcf5ea4377231f66000cfbf5` + +Primary source: + +- `source/articles/2026-07-02-understanding-is-the-new-bottleneck.html.haml` +- `data/aie_talk.yml` + +Review date: 2026-07-16 + +## Why this source mattered + +The source argues that human understanding remains necessary not only to verify agent work, but to participate creatively in later iterations. It presents three practical techniques: + +- explanation artifacts that build background and intuition before code detail; +- quizzes as a speed regulator on the agent loop; +- microworlds and shared spaces that make systems easier to explore and discuss. + +## Value incorporated + +- Explain important changes in conceptual order rather than raw file order. +- Treat reading as exposure, not proof of understanding. +- Use one brief retrieval, prediction, trace, or transfer check when misunderstanding matters. +- Use small interactive or synthetic environments only when they materially improve intuition. +- Preserve shared maps and vocabulary so teams can participate in system evolution. +- Keep humans in the loop for creative fluency, not only approval. + +## Adaptations and limits + +The framework does not require five-question quizzes, block delivery on quiz completion, or create an explainer for every change. Checks are varied, usually open-ended, and limited to one by default. Microworlds and durable explainers remain optional because their construction cost must earn reuse. + +
+Source-designation notes + +The public article page is generated from a short Haml wrapper plus structured talk data in `data/aie_talk.yml`. The review records the repository revision and both source paths so later maintainers can distinguish the original source from this framework's adaptations. + +The source also links to Litt's separate `/explain-diff` gist. That gist informed the general idea of literate change explanations, but was not copied into this repository. + +
diff --git a/docs/references/REFERENCE_REVIEW_POCOK.md b/docs/references/REFERENCE_REVIEW_POCOK.md new file mode 100644 index 0000000..adb3746 --- /dev/null +++ b/docs/references/REFERENCE_REVIEW_POCOK.md @@ -0,0 +1,50 @@ +# Pocok agentic documentation review + +Source repository: `legrab/pocok` + +Reviewed branch: `main` + +Reviewed revision: `cdfb8bfaec5dcc74c62e5f6d5d401222c82dc45a` + +Review date: 2026-07-16 + +## Scope + +The review focused on agent-facing Markdown and work-state documentation rather than package implementation: + +- `AGENTS.md`; +- `prompts/agent-base.prompt.md`; +- `prompts/agent-base.plan.md`; +- current records under `sessions/`; +- the consolidation plan and implementation ledger where they define evidence and handoff behavior. + +## Value incorporated + +- Current source and repository evidence outrank stale plans. +- Public or architectural changes require inspection of consumers and proof surfaces. +- Validation follows risk and repository boundaries. +- Applied source changes and executable validation are separate claims. +- Missing toolchain evidence is disclosed instead of being converted into certainty. +- Long-running work benefits from an explicit handoff that names outcome, evidence, uncertainty, and next action. + +## Constraints not copied as universal defaults + +- mandatory explicit starts for ordinary implementation; +- one step and one commit at a time; +- approval before every commit or phase; +- session records for every substantial task; +- fixed plan files and follow-up files for all multi-step work; +- temporary repository handoff embedded in stable root instructions. + +These controls remain available when risk, team coordination, or configured preference justifies them. + +## 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. + +
+Main design concern found in the source + +Pocok's original root `AGENTS.md` mixed durable package policy, current implementation handoff, and execution protocol. Its base prompt also made conservative high-risk controls universal. The framework preserves the engineering discipline while separating stable rules from temporary state and making workflow strictness configurable. + +
diff --git a/sample/README.md b/sample/README.md index c653ced..5e50cf8 100644 --- a/sample/README.md +++ b/sample/README.md @@ -1,13 +1,23 @@ -# Sample installation tree +# Installable framework layers -The installers copy: +The installer combines one common agentic layer with one learning profile: ```text -sample/learning-flow/ +sample/common/agentic-flow/ +sample/common/.agents/skills/agentic-workflow/ +sample/profiles/minimal/ +sample/profiles/full/ ``` -into the target repository as `learning-flow/`. +`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. -They copy `sample/root/AGENTS.md` to the repository root only when no root `AGENTS.md` exists. +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. -Keep this directory repository-neutral. Repository-specific research belongs only in installed target repositories. +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. + +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 new file mode 100644 index 0000000..06f8f71 --- /dev/null +++ b/sample/common/.agents/skills/agentic-workflow/SKILL.md @@ -0,0 +1,54 @@ +--- +name: agentic-workflow +description: Initialize, integrate, configure, explain, map, review, or improve a repository's actual agentic collaboration setup. Use for root AGENTS integration, custom harnesses, instructions, plans, approval gates, validation, session records, external reference integration, or how agentic-flow and learning-flow fit together. Do not load it as a second engineering workflow for an ordinary code task. +--- + +# 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`. + +## Discover the actual setup + +1. Inspect root and nested instructions plus tool-specific files. +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. +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. +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. +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. + +## Explain the setup + +1. Lead with the layer map from `LEARN.md`. +2. Point to actual files for each layer. +3. Distinguish template content from repository-specific additions. +4. Explain precedence and selective loading. +5. Put long inventories and edge cases in collapsible sections when presenting Markdown. +6. Use at most one explain-back check unless a quiz was requested. +7. End with a compact ownership and routing recap. + +## Integrate an external reference + +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. + +## 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. + +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/agentic-flow/.managed-files b/sample/common/agentic-flow/.managed-files new file mode 100644 index 0000000..1ad227a --- /dev/null +++ b/sample/common/agentic-flow/.managed-files @@ -0,0 +1,10 @@ +.managed-files +.managed-skills +.template-version +README.md +AGENTS.md +WORKFLOW.md +CONFIGURE.md +LEARN.md +ROOT_INTEGRATION.md +REFERENCE_INTEGRATION.md diff --git a/sample/common/agentic-flow/.managed-skills b/sample/common/agentic-flow/.managed-skills new file mode 100644 index 0000000..03d201e --- /dev/null +++ b/sample/common/agentic-flow/.managed-skills @@ -0,0 +1 @@ +agentic-workflow diff --git a/sample/common/agentic-flow/.template-version b/sample/common/agentic-flow/.template-version new file mode 100644 index 0000000..be14282 --- /dev/null +++ b/sample/common/agentic-flow/.template-version @@ -0,0 +1 @@ +0.5.3 diff --git a/sample/common/agentic-flow/AGENTS.md b/sample/common/agentic-flow/AGENTS.md new file mode 100644 index 0000000..4808338 --- /dev/null +++ b/sample/common/agentic-flow/AGENTS.md @@ -0,0 +1,83 @@ +# Agentic collaboration instructions + +## Priority + +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. + +## Instruction discovery + +Do not assume this template is the repository's only harness. Respect existing instructions, skills, prompts, plans, records, and agent-specific files. + +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. + +## Default behavior + +Use the repository as current truth. Treat plans, status notes, and previous summaries as evidence that 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. + +## Communication style + +- 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. + +## Questions and approvals + +Read `SETTINGS.md`. If unconfigured, use defaults without blocking routine work. + +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. + +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. + +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 + +- 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. + +## Execution and verification + +- 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. + +## Handoff + +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. + +When asked to write or create a substantive commit, use a short imperative title. Add only the body sections that carry useful context: + +```text +Why: +- the problem, constraint, or intent + +What: +- the concrete behavior or structure 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. diff --git a/sample/common/agentic-flow/CONFIGURE.md b/sample/common/agentic-flow/CONFIGURE.md new file mode 100644 index 0000000..125d887 --- /dev/null +++ b/sample/common/agentic-flow/CONFIGURE.md @@ -0,0 +1,54 @@ +# 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. + +A compact answer such as `1B 2A 3C 4B` is enough. `defaults` selects the balanced choices. + +## 1. Autonomy and pauses + +- **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. + +## 2. Planning depth + +- **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. + +## 3. Validation depth + +- **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. + +## 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. + +## Optional full-profile learner context + +Ask this only when the full learning profile is active, the user's experience cannot be inferred, and the answer would materially change explanation depth or scaffolding: + +- **A. Advanced student or newer developer:** explain vocabulary and execution paths explicitly. +- **B. Experienced developer, new to this repository or domain:** emphasize local architecture and domain concepts. +- **C. Senior or domain-experienced developer:** emphasize constraints, tradeoffs, edge cases, and transfer. +- **D. Adaptive:** infer from the task and adjust without storing a level. + +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. + +## Recording choices + +Update `SETTINGS.md` and set `Status: configured` or `Status: defaults`. + +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. diff --git a/sample/common/agentic-flow/LEARN.md b/sample/common/agentic-flow/LEARN.md new file mode 100644 index 0000000..35260da --- /dev/null +++ b/sample/common/agentic-flow/LEARN.md @@ -0,0 +1,42 @@ +# Understanding the repository's agentic setup + +The repository's agent-facing setup is part of the system collaborators need to understand. Explain it at a high level first, then reveal detail on demand. + +```text +Repository instructions + ↓ +Agentic collaboration workflow + ↓ +One task procedure or skill + ↓ +Optional learning support + ↓ +Temporary evidence and handoff +``` + +## First pass + +Show: + +- which files provide stable rules; +- 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; +- 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. + +## Tailoring + +In full learning mode, ask the optional learner-context A/B/C/D question from `CONFIGURE.md` only when experience materially changes the explanation. Otherwise infer enough from the user's task and prior reasoning. + +Use friendly, simple communication. Prefer a compact layer map and one representative task path. Put deeper file inventories and precedence details in collapsible sections. + +## Check understanding + +Use at most one brief explain-back, trace, or routing question when misunderstanding would affect later work. Do not treat reading or agreement as proof. + +## External references + +When the repository should learn from another harness or article source, follow `REFERENCE_INTEGRATION.md`. Record the source revision and distinguish retained ideas from source-specific policy. diff --git a/sample/common/agentic-flow/README.md b/sample/common/agentic-flow/README.md new file mode 100644 index 0000000..afb6e67 --- /dev/null +++ b/sample/common/agentic-flow/README.md @@ -0,0 +1,22 @@ +# Agentic flow + +A compact repository-native collaboration layer: + +```text +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/`. + +Start with `AGENTS.md`. Use balanced defaults from `SETTINGS.md` unless configuration matters. + +
+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 +- `ROOT_INTEGRATION.md`: connecting existing or missing root instructions +- `LEARN.md`: understanding the effective repository harness +- `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 new file mode 100644 index 0000000..c065ee4 --- /dev/null +++ b/sample/common/agentic-flow/REFERENCE_INTEGRATION.md @@ -0,0 +1,35 @@ +# Learning from an external reference + +Use this when the repository should incorporate high-value workflow or learning patterns from another GitHub repository, article source, or ZIP. + +## Request shape + +```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. +``` + +## Procedure + +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. + +Conversation is the default during review. Create durable research only when the source and conclusions need future traceability. + +
+Do not import by default + +- source-specific architecture or product rules; +- team-specific commit formats and approval chains; +- temporary handoff state; +- mandatory plans, sessions, quizzes, or dashboards; +- copied source text when a short attributed principle is enough. + +
diff --git a/sample/common/agentic-flow/ROOT_INTEGRATION.md b/sample/common/agentic-flow/ROOT_INTEGRATION.md new file mode 100644 index 0000000..e3ff601 --- /dev/null +++ b/sample/common/agentic-flow/ROOT_INTEGRATION.md @@ -0,0 +1,65 @@ +# Root instruction integration + +The installed workflow must coexist with the repository's actual agent-facing setup. Never assume this template is the only source of instructions. + +## First inspect + +Before creating or editing a root `AGENTS.md`, look for: + +- root and nested `AGENTS.md` files; +- other agent instruction surfaces such as `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursor/rules/`, or equivalent files; +- existing skills, prompts, plans, session records, status files, and evidence ledgers; +- repository-specific commands, architecture rules, security boundaries, and release gates. + +Preserve repository-specific rules. Connect the installed layers rather than replacing working native instructions. + +## When a root `AGENTS.md` already exists + +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. + +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. + +## 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. + +The lean template keeps only reusable discipline: + +- repository evidence outranks stale plans; +- inspect consumers and proof surfaces before changing contracts; +- validate in proportion to risk; +- distinguish source changes from executable proof; +- keep temporary handoff out of stable rules; +- require explicit permission for destructive Git or release actions. + +It does not copy Pocok-specific package, .NET, commit, session, or release policy. + +## Managed pointer block + +The installer and the `agentic-workflow` skill may add this idempotent block: + +```md + +For collaboration behavior, planning, validation, and handoff, follow +`agentic-flow/AGENTS.md`. + +For repository learning, onboarding, explanation, and durable understanding, +follow `learning-flow/AGENTS.md` when relevant. + +``` + +Never append a second copy. Existing root content remains repository-owned. + +## Later changes + +The same choices remain available after installation. Use the `agentic-workflow` skill to integrate, review, reconfigure, or explain the setup at any time. diff --git a/sample/common/agentic-flow/SETTINGS.md b/sample/common/agentic-flow/SETTINGS.md new file mode 100644 index 0000000..11060b6 --- /dev/null +++ b/sample/common/agentic-flow/SETTINGS.md @@ -0,0 +1,16 @@ +# Agentic workflow settings + +Status: unconfigured +Agentic setup review: 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 | + +Until configured, use the defaults. A task-specific user instruction overrides this file. + +Configuration shorthand: `1B 2B 3B 4B`. diff --git a/sample/common/agentic-flow/WORKFLOW.md b/sample/common/agentic-flow/WORKFLOW.md new file mode 100644 index 0000000..2767b0a --- /dev/null +++ b/sample/common/agentic-flow/WORKFLOW.md @@ -0,0 +1,62 @@ +# Minimal agentic workflow + +Use this for substantial repository work. Collapse obvious steps for small or mechanical tasks. + +```text +Frame → Inspect → Decide → Act → Verify → Handoff +``` + +## Frame + +State the outcome, important constraints, and observable completion condition. Infer obvious details from repository evidence instead of interviewing the user. + +## Inspect + +Read native instructions and the narrowest relevant code, tests, configuration, documentation, history, and generated surfaces. Reuse existing evidence before rescanning broadly. + +## Decide + +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. + +## Act + +Make the smallest responsible change or investigation that reaches the outcome. Keep unrelated cleanup out of scope. Do not force one-file or one-commit steps when a coherent slice is safer. + +## Verify + +Start with the closest proof surface. Expand according to risk and `SETTINGS.md`. + +Keep evidence labels distinct: + +- change applied; +- static inspection completed; +- focused checks passed; +- broader executable verification passed; +- verification unavailable or incomplete. + +## 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: + +```text +Result in plain language. + +Changed +- Area — what changed and why it matters. + +Checked +- Proof — meaningful result. + +Open +- Remaining risk, decision, or next action. +``` + +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. + +## Stop conditions + +Stop when the outcome is achieved with proportionate proof, a genuine blocker or design choice requires input, further investigation has low expected value, or remaining work belongs to another task. diff --git a/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md b/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md new file mode 100644 index 0000000..768f9e1 --- /dev/null +++ b/sample/profiles/full/.agents/skills/analogous-feature/SKILL.md @@ -0,0 +1,23 @@ +--- +name: analogous-feature +description: Implement, plan, or teach a feature by finding the nearest valid existing analogue and separating shared invariants from intentional differences. Use when similar existing behavior is the primary guide; do not copy the nearest namesake blindly. +--- + +# Analogous feature + +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 the relevant map, tests, and canonical findings. + +1. Define observable behavior and constraints. +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. +5. Separate shared invariants from intentional differences. +6. Use the smallest established extension seam. +7. Implement or propose the coherent path. +8. Prove both the reused invariant and intended difference. + +Ask at most one check about why the analogue is valid or where copying it would be wrong. + +Report selected analogue, invariant/difference table, seam, proof, risks, and deferred divergence. Do not create an abstraction merely because two features look similar. diff --git a/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md b/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md new file mode 100644 index 0000000..fcfd137 --- /dev/null +++ b/sample/profiles/full/.agents/skills/challenge-debugging/SKILL.md @@ -0,0 +1,22 @@ +--- +name: challenge-debugging +description: Diagnose or teach through a concrete bug, failing test, intermittent issue, or incorrect runtime behavior. Use when the primary task is to reproduce, narrow, explain, and safely fix a symptom; do not jump to a guessed patch. +--- + +# Challenge debugging + +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. + +1. State 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. +5. Apply the narrowest responsible fix when requested. +6. Add or improve proportional regression evidence. +7. Stop when one mechanism explains the symptom and decisive evidence distinguishes it from credible alternatives. + +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. diff --git a/sample/profiles/full/.agents/skills/change-explainer/SKILL.md b/sample/profiles/full/.agents/skills/change-explainer/SKILL.md new file mode 100644 index 0000000..2ed4bf3 --- /dev/null +++ b/sample/profiles/full/.agents/skills/change-explainer/SKILL.md @@ -0,0 +1,20 @@ +--- +name: change-explainer +description: Explain a non-trivial diff, pull request, or agent-produced implementation in conceptual execution order. Use only when raw file order hides mechanism, architecture, domain behavior, tradeoffs, or risk; do not create an explainer for routine edits. +--- + +# Change explainer + +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. + +1. Establish exact change range and intended outcome. +2. Explain relevant behavior and 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. + +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/.agents/skills/learning-bootstrap/SKILL.md b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md new file mode 100644 index 0000000..cd05e29 --- /dev/null +++ b/sample/profiles/full/.agents/skills/learning-bootstrap/SKILL.md @@ -0,0 +1,22 @@ +--- +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. +--- + +# Learning bootstrap + +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` 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. +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. +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. diff --git a/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md b/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md new file mode 100644 index 0000000..5a012f8 --- /dev/null +++ b/sample/profiles/full/.agents/skills/repository-orientation/SKILL.md @@ -0,0 +1,22 @@ +--- +name: repository-orientation +description: Explain or map an unfamiliar repository, subsystem, architecture boundary, domain territory, runtime path, or ownership area. Use when orientation is the primary task; do not combine it with a full bug, feature, or refactor workflow. +--- + +# Repository orientation + +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`, 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. +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. + +Ask at most one consequential trace, prediction, or explain-back. Create or update an artifact only when the persistence threshold is met. + +Output a compact mental model, small visual when useful, stable paths/symbols, representative path, evidence, uncertainty, and one next challenge. diff --git a/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md b/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md new file mode 100644 index 0000000..494677c --- /dev/null +++ b/sample/profiles/full/.agents/skills/safe-refactor/SKILL.md @@ -0,0 +1,22 @@ +--- +name: safe-refactor +description: Plan, perform, or teach a behavior-preserving refactor with an explicit contract, sufficient characterization evidence, a small change seam, and regression proof. Use when structural change is primary; do not expand local cleanup into an architecture campaign. +--- + +# Safe refactor + +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 contract and territory. + +1. State observable behavior that must remain stable 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. +5. Run the narrowest useful checks after meaningful steps. +6. Confirm the result is simpler or safer and custom glue was not added unnecessarily. +7. Stop when the contract is explicit, relevant checks pass, and no unproven boundary is hidden. + +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. diff --git a/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md b/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md new file mode 100644 index 0000000..24e8aa0 --- /dev/null +++ b/sample/profiles/full/.agents/skills/ticket-learning-path/SKILL.md @@ -0,0 +1,22 @@ +--- +name: ticket-learning-path +description: Turn a real issue or planned change into a short repository learning route before implementation. Use when the user wants architecture, domain, testing, and ownership context around a ticket; do not create ceremony for a trivial localized change. +--- + +# Ticket learning path + +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. + +1. Read and classify the ticket as bug, feature, refactor, review, or exploration. +2. Locate likely ownership and one representative path. +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. +6. Stop at preparation unless implementation was requested. +7. When implementation is requested, name one handoff: `challenge-debugging`, `analogous-feature`, or `safe-refactor`. + +Do not execute several skills in the same pass. Use `change-explainer` later only when the resulting change warrants it. + +Report ticket summary, ownership, representative path, missing context, short route, readiness, named handoff or stop, and any ticket-local detail that should not be promoted. diff --git a/sample/profiles/full/learning-flow/.managed-files b/sample/profiles/full/learning-flow/.managed-files new file mode 100644 index 0000000..d6c07ad --- /dev/null +++ b/sample/profiles/full/learning-flow/.managed-files @@ -0,0 +1,25 @@ +.managed-files +.managed-skills +.template-profile +.template-version +README.md +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/.managed-skills b/sample/profiles/full/learning-flow/.managed-skills new file mode 100644 index 0000000..6090479 --- /dev/null +++ b/sample/profiles/full/learning-flow/.managed-skills @@ -0,0 +1,7 @@ +learning-bootstrap +repository-orientation +challenge-debugging +analogous-feature +safe-refactor +change-explainer +ticket-learning-path diff --git a/sample/profiles/full/learning-flow/.template-profile b/sample/profiles/full/learning-flow/.template-profile new file mode 100644 index 0000000..2877147 --- /dev/null +++ b/sample/profiles/full/learning-flow/.template-profile @@ -0,0 +1 @@ +full diff --git a/sample/profiles/full/learning-flow/.template-version b/sample/profiles/full/learning-flow/.template-version new file mode 100644 index 0000000..be14282 --- /dev/null +++ b/sample/profiles/full/learning-flow/.template-version @@ -0,0 +1 @@ +0.5.3 diff --git a/sample/profiles/full/learning-flow/AGENTS.md b/sample/profiles/full/learning-flow/AGENTS.md new file mode 100644 index 0000000..3a4a614 --- /dev/null +++ b/sample/profiles/full/learning-flow/AGENTS.md @@ -0,0 +1,98 @@ +# Full learning-flow instructions + +## Priority and scope + +Follow repository-native instructions and `agentic-flow/AGENTS.md` first. This file governs learning-oriented repository work only. + +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. + +## Select one primary learning workflow + +| Need | Primary skill | +|---|---| +| compact initial baseline | `learning-bootstrap` | +| architecture or domain orientation | `repository-orientation` | +| bug or failing behavior | `challenge-debugging` | +| feature similar to an existing one | `analogous-feature` | +| behavior-preserving structural change | `safe-refactor` | +| non-trivial change explanation | `change-explainer` | +| task context before implementation | `ticket-learning-path` | + +Do not load all skills. Do not use `agentic-workflow` as a second engineering procedure. It exists to configure or explain the agentic harness itself. + +Agents without task-skill support use `PLAYBOOKS.md`. + +## Communication and 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 `
` 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. + +## Shared learning flow + +```text +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. +- 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. + +Collapse or skip anything that adds no learning or engineering value. + +## Context economy + +- Search narrowly before reading broad directories, documentation, history, or generated files. +- Read only the selected skill and relevant parts of `MAP.md`, `TAKEAWAYS.md`, or canonical research. +- Reuse verified findings before rescanning source. +- Prefer stable symbols, tests, configuration, and representative paths over inventories. +- Summarize large command output before retaining it in context. +- Stop when the evidence threshold is met. +- Stay at most one useful step ahead unless deeper research was requested. + +## Understanding checks + +Use at most one check by default. Skip it when setting 4A is active, fast delivery was requested, the work is mechanical, or the user already demonstrated the model. Use more only for explicit quiz or guided-learning requests. + +Do not re-check the same concept unless later reasoning contradicts the earlier evidence. See `UNDERSTANDING_CHECKS.md`. + +## Persistence and ownership + +Conversation is the default. Persist only verified, repository-specific findings likely to be reused and costly to rediscover. + +Use one owner: + +- `MAP.md`: compact boundaries, vocabulary, 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. + +## Visual and evidence policy + +Keep `MAP.md` compact. Prefer a small Mermaid diagram, state map, sequence strip, or comparison table when it reduces text. + +Label material claims as verified from source, configuration, tests, runtime evidence, contributor report, or inference. Do not infer production usage or data shape from source alone. + +Rereading and agreement show exposure, not understanding. A sound explanation, prediction, trace, comparison, boundary identification, or application can demonstrate the model. + +## 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. diff --git a/sample/profiles/full/learning-flow/BOOTSTRAP.md b/sample/profiles/full/learning-flow/BOOTSTRAP.md new file mode 100644 index 0000000..f7cbcb0 --- /dev/null +++ b/sample/profiles/full/learning-flow/BOOTSTRAP.md @@ -0,0 +1,40 @@ +# 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. + +## 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 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. + +Do not screen a fixed list of themes. Do not generate sessions or research beyond what is needed for a usable baseline. + +## Completion report + +Follow `agentic-flow/WORKFLOW.md` for validation and handoff. Report: + +- effective agentic instruction order and any unresolved overlap; +- selected learning profile and settings state; +- map entry point; +- build and test entry points; +- representative path; +- uncertain claims; +- up to three useful next tasks. diff --git a/sample/profiles/full/learning-flow/MAP.md b/sample/profiles/full/learning-flow/MAP.md new file mode 100644 index 0000000..3045f11 --- /dev/null +++ b/sample/profiles/full/learning-flow/MAP.md @@ -0,0 +1,46 @@ +# Repository map + +Keep this file compact and visual. It is an orientation surface, not an inventory. + +## Agentic collaboration setup + +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. + +## System boundaries + +_Not mapped yet._ + +## Domain territories and vocabulary + +_Not mapped yet._ + +## Representative paths + +_Not mapped yet._ + +## Build, run, debug, and proof entry points + +_Not mapped yet._ + +## Related repositories and ownership seams + +_Not mapped yet._ + +## High-value unknowns + +- _Add only unknowns likely to affect near-term work or ownership._ + +## Learning coverage + +_Optional. Add only for a deliberate structured learning program._ diff --git a/sample/profiles/full/learning-flow/PLAYBOOKS.md b/sample/profiles/full/learning-flow/PLAYBOOKS.md new file mode 100644 index 0000000..6e3eb0d --- /dev/null +++ b/sample/profiles/full/learning-flow/PLAYBOOKS.md @@ -0,0 +1,18 @@ +# Compact learning fallback + +Use this only when repository task skills are unavailable. General execution behavior remains in `agentic-flow/WORKFLOW.md`. + +```text +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 | + +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. diff --git a/sample/profiles/full/learning-flow/README.md b/sample/profiles/full/learning-flow/README.md new file mode 100644 index 0000000..3cdacbd --- /dev/null +++ b/sample/profiles/full/learning-flow/README.md @@ -0,0 +1,50 @@ +# Full learning flow + +This profile supports deliberate onboarding and long-lived repository understanding. It is separate from the general collaboration workflow in `agentic-flow/`. + +## Learning loop + +```text +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. + +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/`. + +## Persistent surfaces + +| Surface | Purpose | +|---|---| +| `MAP.md` | compact boundaries, vocabulary, 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. + +## 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. + +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. + +## Understanding and recap + +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. + +## 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. + +## Communication + +Lead with a short conceptual answer. Use friendly, simple wording and add detail only when it helps the current task. In Markdown, place optional examples, evidence inventories, and long command output in collapsible sections while keeping warnings and required actions visible. diff --git a/sample/profiles/full/learning-flow/REPOSITORIES.md b/sample/profiles/full/learning-flow/REPOSITORIES.md new file mode 100644 index 0000000..c8e6756 --- /dev/null +++ b/sample/profiles/full/learning-flow/REPOSITORIES.md @@ -0,0 +1,9 @@ +# Repository baselines + +Record only repositories actually needed by the learning flow. + +| Repository | Local path or access method | Branch | Baseline commit | Purpose | Notes | +|---|---|---|---|---|---| +| _Current repository_ | `.` | _unknown_ | _unknown_ | primary | _Populate during compact baseline_ | + +Do not add submodules or alter repository layout automatically. Ask which access method to use when another repository is required. diff --git a/sample/profiles/full/learning-flow/TAKEAWAYS.md b/sample/profiles/full/learning-flow/TAKEAWAYS.md new file mode 100644 index 0000000..0671431 --- /dev/null +++ b/sample/profiles/full/learning-flow/TAKEAWAYS.md @@ -0,0 +1,15 @@ +# Durable takeaways + +Record only verified repository-specific lessons likely to be reused and costly to rediscover. + +```md +## + +- **Model:** +- **Where:** `` +- **Evidence:** +- **Boundary:** +- **Transfer:** +``` + +Link to canonical research when detail is needed. Do not store transcripts, personal progress, raw logs, temporary hypotheses, or copied implementation detail. diff --git a/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md b/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md new file mode 100644 index 0000000..87da1c3 --- /dev/null +++ b/sample/profiles/full/learning-flow/UNDERSTANDING_CHECKS.md @@ -0,0 +1,39 @@ +# Understanding checks + +Understanding checks are a small retrieval and transfer mechanism, not a quiz system. + +## Default + +Use at most one check in a meaningful session when a mistaken mental model would affect future debugging, design, review, or ownership. + +Prefer: + +- explain the mechanism in two to four sentences; +- predict behavior under one changed condition; +- trace one value, request, or event through important boundaries; +- identify what must remain stable; +- compare a valid analogue with a tempting but invalid one; +- spot the flaw in a short explanation; +- transfer the rule to a nearby case. + +Use multiple-choice only when distinguishing plausible mechanisms or misconceptions is itself useful. It is not the default. + +## Skip when + +- the work is mechanical or trivial; +- the user already demonstrated the model through reasoning or implementation; +- the user requested fast execution; +- the answer would merely repeat an obvious fact; +- the same concept was already checked in this task and later reasoning has not contradicted it. + +## Response handling + +- 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. +- Do not infer broad competence from one answer. + +## Session recap + +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. diff --git a/sample/profiles/full/learning-flow/contributors/README.md b/sample/profiles/full/learning-flow/contributors/README.md new file mode 100644 index 0000000..3ca2072 --- /dev/null +++ b/sample/profiles/full/learning-flow/contributors/README.md @@ -0,0 +1,7 @@ +# Optional contributor traces + +Shared repository learning does not require identity. + +Create `contributors//` 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 new file mode 100644 index 0000000..c98b4bf --- /dev/null +++ b/sample/profiles/full/learning-flow/explainers/README.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 0000000..49648b0 --- /dev/null +++ b/sample/profiles/full/learning-flow/labs/README.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 0000000..2299996 --- /dev/null +++ b/sample/profiles/full/learning-flow/materials/README.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 0000000..bae2920 --- /dev/null +++ b/sample/profiles/full/learning-flow/materials/themes/README.md @@ -0,0 +1,3 @@ +# 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 new file mode 100644 index 0000000..66bc8a8 --- /dev/null +++ b/sample/profiles/full/learning-flow/research/README.md @@ -0,0 +1,7 @@ +# 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 new file mode 100644 index 0000000..5ff4c81 --- /dev/null +++ b/sample/profiles/full/learning-flow/research/topics/README.md @@ -0,0 +1,3 @@ +# 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/challenge.md b/sample/profiles/full/learning-flow/templates/challenge.md new file mode 100644 index 0000000..96dcb3a --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/challenge.md @@ -0,0 +1,25 @@ +# + +## Outcome + +## Relevant boundary and representative path + +## Behavior contract, hypothesis, or analogue + +## Work and decisive evidence + +## Optional understanding check + +_Use at most one when consequential._ + +## Recap + +- **Model:** +- **Where:** +- **Evidence:** +- **Boundary:** +- **Transfer:** + +## Promotion decision + +_Keep conversational, update map/takeaways, or create canonical research. State why._ diff --git a/sample/profiles/full/learning-flow/templates/change-explainer.md b/sample/profiles/full/learning-flow/templates/change-explainer.md new file mode 100644 index 0000000..9ee92f5 --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/change-explainer.md @@ -0,0 +1,23 @@ +# + +## Outcome and background + +## Short intuition + +## Conceptual execution order + +## Contracts, decisions, and tradeoffs + +## Risks and unchanged behavior + +## Proof + +## Optional understanding check + +## Reinforcing recap + +- **Model:** +- **Where:** +- **Evidence:** +- **Boundary:** +- **Transfer:** diff --git a/sample/profiles/full/learning-flow/templates/contributor-readme.md b/sample/profiles/full/learning-flow/templates/contributor-readme.md new file mode 100644 index 0000000..8ce436f --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/contributor-readme.md @@ -0,0 +1,11 @@ +# + +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 new file mode 100644 index 0000000..8e1863e --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/contributor-theme.md @@ -0,0 +1,11 @@ +# + +## 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 new file mode 100644 index 0000000..4a71c56 --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/contributor-tracking.md @@ -0,0 +1,11 @@ +# 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 new file mode 100644 index 0000000..539fce7 --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/lab-readme.md @@ -0,0 +1,13 @@ +# + +## 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 new file mode 100644 index 0000000..8779975 --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/learning-material.md @@ -0,0 +1,15 @@ +# + +## 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 new file mode 100644 index 0000000..d959a9e --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/research-topic.md @@ -0,0 +1,13 @@ +# + +## 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/full/learning-flow/templates/ticket-learning-path.md b/sample/profiles/full/learning-flow/templates/ticket-learning-path.md new file mode 100644 index 0000000..5ec1d9d --- /dev/null +++ b/sample/profiles/full/learning-flow/templates/ticket-learning-path.md @@ -0,0 +1,21 @@ +# : + +## Classification and desired outcome + +## Ownership and representative path + +## Existing reusable context + +## Missing high-value context + +## Short route + +1. +2. +3. + +## Readiness and handoff + +_Stop at preparation unless implementation was requested. Name one execution skill if needed._ + +## Ticket-local detail not to promote diff --git a/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md b/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md new file mode 100644 index 0000000..1cbe93e --- /dev/null +++ b/sample/profiles/minimal/.agents/skills/repository-learning/SKILL.md @@ -0,0 +1,52 @@ +--- +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. +--- + +# 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. + +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. +2. Find the smallest discriminating test, log, trace, or reproduction. +3. Explain the mechanism before patching. +4. Apply the narrowest responsible fix when requested. +5. Prove regression behavior and name the untested boundary. + +## Feature + +1. Define observable behavior and constraints. +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. +5. Prove both the reused invariant and intended difference. + +## Refactor + +1. State the observable contract that must remain stable. +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. +5. Confirm the result is simpler and no boundary is hidden. + +## 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. +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. + +## Learning constraints + +- 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. +- Update `MAP.md` or `TAKEAWAYS.md` only when the persistence threshold is met. diff --git a/sample/profiles/minimal/learning-flow/.managed-files b/sample/profiles/minimal/learning-flow/.managed-files new file mode 100644 index 0000000..8329141 --- /dev/null +++ b/sample/profiles/minimal/learning-flow/.managed-files @@ -0,0 +1,6 @@ +.managed-files +.managed-skills +.template-profile +.template-version +README.md +AGENTS.md diff --git a/sample/profiles/minimal/learning-flow/.managed-skills b/sample/profiles/minimal/learning-flow/.managed-skills new file mode 100644 index 0000000..48d5bf5 --- /dev/null +++ b/sample/profiles/minimal/learning-flow/.managed-skills @@ -0,0 +1 @@ +repository-learning diff --git a/sample/profiles/minimal/learning-flow/.template-profile b/sample/profiles/minimal/learning-flow/.template-profile new file mode 100644 index 0000000..dd1a932 --- /dev/null +++ b/sample/profiles/minimal/learning-flow/.template-profile @@ -0,0 +1 @@ +minimal diff --git a/sample/profiles/minimal/learning-flow/.template-version b/sample/profiles/minimal/learning-flow/.template-version new file mode 100644 index 0000000..be14282 --- /dev/null +++ b/sample/profiles/minimal/learning-flow/.template-version @@ -0,0 +1 @@ +0.5.3 diff --git a/sample/profiles/minimal/learning-flow/AGENTS.md b/sample/profiles/minimal/learning-flow/AGENTS.md new file mode 100644 index 0000000..6b248b3 --- /dev/null +++ b/sample/profiles/minimal/learning-flow/AGENTS.md @@ -0,0 +1,54 @@ +# Minimal repository learning instructions + +## Priority and scope + +Follow repository-native instructions and `agentic-flow/AGENTS.md` first. These rules add learning support only. + +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. + +## Core flow + +```text +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. +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. + +## 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. + +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. +- Reuse `MAP.md` and `TAKEAWAYS.md` before rescanning source. +- Skip understanding checks for mechanical edits, already-demonstrated concepts, fast-execution mode, or learning setting 4A. +- Do not repeat a check for the same concept unless later reasoning contradicts it. +- Stop investigating when decisive evidence identifies one responsible mechanism or the remaining uncertainty is explicitly bounded. + +## 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. + +Do not persist raw debugging history, personal notes, speculative claims, copied source, session transcripts, secrets, customer data, raw production logs, or sensitive query results. + +## Evidence + +Distinguish claims verified from source, configuration, tests, runtime evidence, contributor report, and inference. Do not present inferred production behavior as fact. diff --git a/sample/profiles/minimal/learning-flow/MAP.md b/sample/profiles/minimal/learning-flow/MAP.md new file mode 100644 index 0000000..b351025 --- /dev/null +++ b/sample/profiles/minimal/learning-flow/MAP.md @@ -0,0 +1,38 @@ +# Repository map + +Keep this file compact. Prefer one small Mermaid diagram or table plus stable paths and symbols. + +## Agentic collaboration setup + +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. + +## System boundaries + +_Not mapped yet._ + +## Domain vocabulary + +_Not mapped yet._ + +## Representative paths + +_Not mapped yet._ + +## Build and proof entry points + +_Not mapped yet._ + +## High-value unknowns + +- _Add only unknowns likely to affect near-term work._ diff --git a/sample/profiles/minimal/learning-flow/README.md b/sample/profiles/minimal/learning-flow/README.md new file mode 100644 index 0000000..957ea50 --- /dev/null +++ b/sample/profiles/minimal/learning-flow/README.md @@ -0,0 +1,22 @@ +# Minimal learning flow + +This profile adds lightweight repository learning to the general collaboration behavior in `agentic-flow/`. + +```text +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. + +It persists only: + +- `MAP.md` for durable repository orientation; +- `TAKEAWAYS.md` for concise verified lessons likely to be reused. + +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`. + +## Communication + +Lead with a short conceptual answer. Use friendly, simple wording and add detail only when it helps the current task. In Markdown, place optional examples, evidence inventories, and long command output in collapsible sections while keeping warnings and required actions visible. diff --git a/sample/profiles/minimal/learning-flow/TAKEAWAYS.md b/sample/profiles/minimal/learning-flow/TAKEAWAYS.md new file mode 100644 index 0000000..56a350e --- /dev/null +++ b/sample/profiles/minimal/learning-flow/TAKEAWAYS.md @@ -0,0 +1,17 @@ +# Durable takeaways + +Record only verified repository-specific lessons that are likely to be reused and costly to rediscover. + +Use compact entries: + +```md +## <Mechanism or rule> + +- **Model:** <one or two sentences> +- **Where:** `<path or stable symbol>` +- **Evidence:** <test, configuration, source, or safe runtime observation> +- **Boundary:** <where the rule stops applying> +- **Transfer:** <nearby task or territory where this helps> +``` + +Do not store transcripts, personal progress, raw logs, temporary hypotheses, or copied implementation detail. diff --git a/sample/root/AGENTS.md b/sample/root/AGENTS.md index d9bb830..8a09f4a 100644 --- a/sample/root/AGENTS.md +++ b/sample/root/AGENTS.md @@ -1,11 +1,23 @@ # Repository agent instructions -For onboarding, repository research, contributor learning, or maintenance of the learning workflow, read and follow: +## Evidence and scope -```text -learning-flow/AGENTS.md -``` +- Treat repository source, configuration, tests, and current executable evidence as more authoritative than stale plans or summaries. +- Inspect affected consumers, tests, scripts, generated surfaces, and operational boundaries before changing a public or architectural contract. +- Keep changes inside the requested scope and avoid unrelated cleanup. +- Separate facts established by inspection from behavior proven by execution. +- Never claim validation that the available toolchain or environment did not perform. -Do not modify application code as part of the learning workflow unless the user explicitly asks for implementation or experimentation. +## Collaboration layers -Do not commit learning-flow changes without explicit user approval. +<!-- codebase-learning-flow:start --> +For collaboration behavior, planning, validation, and handoff, follow +`agentic-flow/AGENTS.md`. + +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. + +Do not commit, push, publish, merge, rewrite history, or perform destructive Git operations unless explicitly requested. diff --git a/sample/root/AGENTS.pointer.md b/sample/root/AGENTS.pointer.md new file mode 100644 index 0000000..2005c1d --- /dev/null +++ b/sample/root/AGENTS.pointer.md @@ -0,0 +1,7 @@ +<!-- codebase-learning-flow:start --> +For collaboration behavior, planning, validation, and handoff, follow +`agentic-flow/AGENTS.md`. + +For repository learning, onboarding, explanation, and durable understanding, +follow `learning-flow/AGENTS.md` when relevant. +<!-- codebase-learning-flow:end --> diff --git a/scripts/README.md b/scripts/README.md index 9632875..ea2aa0d 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,32 +1,38 @@ -# Installer scripts +# Installers -These scripts install `sample/learning-flow/` into another repository and optionally create a minimal root `AGENTS.md`. +The PowerShell, POSIX shell, and batch entry points install: -## Files +1. the common `agentic-flow/` directory; +2. the common `agentic-workflow` skill unless skills are skipped; +3. the selected minimal or full `learning-flow/` profile and its managed skills; +4. optional root `AGENTS.md` integration. -- `install.ps1`: native PowerShell implementation. -- `install.sh`: POSIX-oriented shell implementation using `curl` or `wget` and `unzip`. -- `install.bat`: Windows Command Prompt wrapper around `install.ps1`. +## Root integration -## Safety behavior +Use: -Default mode is `fail`. +```text +--root-agents auto|integrate|initialize|preserve|skip +-RootAgents Auto|Integrate|Initialize|Preserve|Skip +``` -The installers: +- `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. -- operate in the current directory unless another target is supplied; -- download a GitHub archive into a temporary directory; -- copy only the `sample/learning-flow/` tree; -- create root `AGENTS.md` only when it does not already exist; -- do not append to existing agent instructions; -- do not run Git commands; -- do not commit; -- clean their temporary files. +`--skip-root-agents` and `-SkipRootAgents` remain compatibility aliases for `skip`. -## Supported modes +The installer never replaces an existing root file wholesale. The managed pointer is not appended twice. -- `fail`: abort when the target learning directory contains files. -- `merge`: add only files that do not already exist. -- `replace`: delete and recreate the target learning directory. +## Framework modes -`replace` destroys the existing learning directory. Use it only for fresh or disposable installations. +- `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; +- `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. + +Use `--skip-skills` or `-SkipSkills` for the Markdown-only fallback. diff --git a/scripts/install.ps1 b/scripts/install.ps1 index b561259..d299005 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -3,25 +3,26 @@ param( [string]$TargetPath = (Get-Location).Path, [string]$Repository = "legrab/codebase-learning-flow", [string]$Ref = "main", - [string]$LearningDirectory = "learning-flow", - [ValidateSet("Fail", "Merge", "Replace")] + [ValidateSet("Auto", "Minimal", "Full")] + [string]$Profile = "Auto", + [ValidateSet("Fail", "Merge", "Update", "Replace")] [string]$Mode = "Fail", + [ValidateSet("Auto", "Integrate", "Initialize", "Preserve", "Skip")] + [string]$RootAgents = "Auto", [switch]$SkipRootAgents, + [switch]$SkipSkills, [switch]$SkipSelfRefresh ) Set-StrictMode -Version Latest $ErrorActionPreference = "Stop" -$InstallerVersion = "0.1.2" +$InstallerVersion = "0.5.3" function Write-Step([string]$Message) { Write-Host "[learning-flow] $Message" } -function Resolve-RemoteCommit( - [string]$RepositoryName, - [string]$RequestedRef -) { +function Resolve-RemoteCommit([string]$RepositoryName, [string]$RequestedRef) { if ($RequestedRef -match "^[0-9a-fA-F]{40}$") { return $RequestedRef.ToLowerInvariant() } @@ -36,7 +37,6 @@ function Resolve-RemoteCommit( "refs/tags/$RequestedRef^{}", "refs/tags/$RequestedRef" ) - $lines = @(& git ls-remote $remoteUrl @patterns) if ($LASTEXITCODE -ne 0) { throw "Failed to resolve '$RequestedRef' from $remoteUrl." @@ -45,113 +45,276 @@ function Resolve-RemoteCommit( $headSha = $null $peeledTagSha = $null $tagSha = $null - foreach ($line in $lines) { $parts = $line -split "\s+", 2 - if ($parts.Count -ne 2) { - continue - } - - $sha = $parts[0] - $name = $parts[1] - - if ($name -eq "refs/heads/$RequestedRef") { - $headSha = $sha - } - elseif ($name -eq "refs/tags/$RequestedRef^{}") { - $peeledTagSha = $sha - } - elseif ($name -eq "refs/tags/$RequestedRef") { - $tagSha = $sha - } + if ($parts.Count -ne 2) { continue } + if ($parts[1] -eq "refs/heads/$RequestedRef") { $headSha = $parts[0] } + elseif ($parts[1] -eq "refs/tags/$RequestedRef^{}") { $peeledTagSha = $parts[0] } + elseif ($parts[1] -eq "refs/tags/$RequestedRef") { $tagSha = $parts[0] } } $resolved = @($headSha, $peeledTagSha, $tagSha) | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Select-Object -First 1 - if ([string]::IsNullOrWhiteSpace($resolved)) { throw "Ref '$RequestedRef' was not found in $RepositoryName." } - return $resolved.ToLowerInvariant() } function Test-DirectoryHasContent([string]$Path) { - if (-not (Test-Path -LiteralPath $Path -PathType Container)) { - return $false - } - + if (-not (Test-Path -LiteralPath $Path -PathType Container)) { return $false } return $null -ne (Get-ChildItem -LiteralPath $Path -Force | Select-Object -First 1) } +function Get-InstalledProfile([string]$LearningPath) { + $profileFile = Join-Path $LearningPath ".template-profile" + if (Test-Path -LiteralPath $profileFile -PathType Leaf) { + $value = (Get-Content -LiteralPath $profileFile -TotalCount 1).Trim().ToLowerInvariant() + if ($value -in @("minimal", "full")) { return $value } + throw "Invalid installed profile marker: $value" + } + if (Test-DirectoryHasContent $LearningPath) { return "full" } + return $null +} + function Copy-MissingTree([string]$Source, [string]$Destination) { - $script:copied = 0 - $script:skipped = 0 + $sourceRoot = [System.IO.Path]::GetFullPath($Source).TrimEnd([char[]]@('\', '/')) + [System.IO.Path]::DirectorySeparatorChar + $copied = 0 + $skipped = 0 + + if (-not (Test-Path -LiteralPath $Destination)) { + New-Item -ItemType Directory -Path $Destination -Force | Out-Null + } Get-ChildItem -LiteralPath $Source -Recurse -Force | ForEach-Object { - $relative = [System.IO.Path]::GetRelativePath($Source, $_.FullName) + $fullName = [System.IO.Path]::GetFullPath($_.FullName) + if (-not $fullName.StartsWith($sourceRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + throw "Source item escaped expected root: $fullName" + } + $relative = $fullName.Substring($sourceRoot.Length) $target = Join-Path $Destination $relative - if ($_.PSIsContainer) { if (-not (Test-Path -LiteralPath $target)) { New-Item -ItemType Directory -Path $target -Force | Out-Null } - return } + else { + $parent = Split-Path -Parent $target + if (-not (Test-Path -LiteralPath $parent)) { + New-Item -ItemType Directory -Path $parent -Force | Out-Null + } + if (Test-Path -LiteralPath $target) { + $skipped += 1 + } + else { + Copy-Item -LiteralPath $_.FullName -Destination $target + $copied += 1 + } + } + } - $parent = Split-Path -Parent $target + return [pscustomobject]@{ Copied = $copied; Skipped = $skipped } +} + +function Copy-ManagedFiles([string]$Source, [string]$Destination, [string]$ManifestPath) { + $sourceRoot = [System.IO.Path]::GetFullPath($Source).TrimEnd([char[]]@('\', '/')) + [System.IO.Path]::DirectorySeparatorChar + $destinationRoot = [System.IO.Path]::GetFullPath($Destination).TrimEnd([char[]]@('\', '/')) + [System.IO.Path]::DirectorySeparatorChar + $copied = 0 + + foreach ($rawLine in Get-Content -LiteralPath $ManifestPath) { + $relative = $rawLine.Trim() + if ([string]::IsNullOrWhiteSpace($relative) -or $relative.StartsWith('#')) { continue } + $normalized = $relative.Replace('/', [string][System.IO.Path]::DirectorySeparatorChar) + $sourceFile = [System.IO.Path]::GetFullPath((Join-Path $Source $normalized)) + $targetFile = [System.IO.Path]::GetFullPath((Join-Path $Destination $normalized)) + if (-not $sourceFile.StartsWith($sourceRoot, [System.StringComparison]::OrdinalIgnoreCase) -or + -not $targetFile.StartsWith($destinationRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + throw "Unsafe path in managed-files manifest: $relative" + } + if (-not (Test-Path -LiteralPath $sourceFile -PathType Leaf)) { + throw "Managed source file is missing: $relative" + } + if (Test-Path -LiteralPath $targetFile -PathType Container) { + throw "Managed target path is a directory, expected a file: $relative" + } + $parent = Split-Path -Parent $targetFile if (-not (Test-Path -LiteralPath $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null } + Copy-Item -LiteralPath $sourceFile -Destination $targetFile -Force + $copied += 1 + } + return $copied +} - if (Test-Path -LiteralPath $target) { - $script:skipped += 1 +function Get-ManagedSkillNames([string]$ManifestPath) { + if (-not (Test-Path -LiteralPath $ManifestPath -PathType Leaf)) { return @() } + $names = @( + Get-Content -LiteralPath $ManifestPath | + ForEach-Object { $_.Trim() } | + Where-Object { -not [string]::IsNullOrWhiteSpace($_) -and -not $_.StartsWith('#') } + ) + foreach ($name in $names) { + if ($name -notmatch '^[A-Za-z0-9._-]+$') { + throw "Unsafe skill name in managed-skills manifest: $name" } - else { - Copy-Item -LiteralPath $_.FullName -Destination $target - $script:copied += 1 + } + return $names +} + +function Remove-ManagedSkills([string]$ManifestPath, [string]$TargetSkills) { + foreach ($skillName in Get-ManagedSkillNames $ManifestPath) { + $targetSkill = Join-Path $TargetSkills $skillName + if (Test-Path -LiteralPath $targetSkill) { + Remove-Item -LiteralPath $targetSkill -Recurse -Force + Write-Step "Removed managed skill '$skillName'" } } +} - return [pscustomobject]@{ - Copied = $script:copied - Skipped = $script:skipped +function Install-Component( + [string]$Name, + [string]$Source, + [string]$Destination, + [string]$ManagedFiles, + [string]$InstallMode +) { + if ($InstallMode -eq "Replace" -and (Test-Path -LiteralPath $Destination)) { + Write-Step "Removing existing $Name directory" + Remove-Item -LiteralPath $Destination -Recurse -Force + } + + if ($InstallMode -eq "Merge" -and (Test-Path -LiteralPath $Destination)) { + Write-Step "Merging missing $Name files" + $result = Copy-MissingTree -Source $Source -Destination $Destination + Write-Step "Copied $($result.Copied) files and preserved $($result.Skipped) existing files" + } + elseif ($InstallMode -eq "Update") { + Write-Step "Adding missing $Name files" + $result = Copy-MissingTree -Source $Source -Destination $Destination + Write-Step "Copied $($result.Copied) files and preserved $($result.Skipped) existing files" + Write-Step "Updating framework-owned $Name files" + $count = Copy-ManagedFiles -Source $Source -Destination $Destination -ManifestPath $ManagedFiles + Write-Step "Updated $count managed files in $Name" + } + else { + Write-Step "Installing $Name" + New-Item -ItemType Directory -Path $Destination -Force | Out-Null + Get-ChildItem -LiteralPath $Source -Force | ForEach-Object { + Copy-Item -LiteralPath $_.FullName -Destination $Destination -Recurse -Force + } + } +} + +function Install-ManagedSkills( + [string]$SourceSkills, + [string]$ManifestPath, + [string]$TargetSkills, + [string]$InstallMode +) { + foreach ($skillName in Get-ManagedSkillNames $ManifestPath) { + $sourceSkill = Join-Path $SourceSkills $skillName + $targetSkill = Join-Path $TargetSkills $skillName + if (-not (Test-Path -LiteralPath $sourceSkill -PathType Container)) { + throw "Managed skill source is missing: $skillName" + } + if (Test-Path -LiteralPath $targetSkill) { + if ($InstallMode -eq "Merge") { + Write-Step "Existing skill '$skillName' preserved" + continue + } + Remove-Item -LiteralPath $targetSkill -Recurse -Force + } + Copy-Item -LiteralPath $sourceSkill -Destination $targetSkill -Recurse -Force + Write-Step "Installed skill '$skillName'" } } + +function Test-InteractiveTerminal { + try { + return [Environment]::UserInteractive -and -not [Console]::IsInputRedirected + } + catch { + return $false + } +} + +function Resolve-RootAgentsMode([string]$TargetRoot, [string]$RequestedMode) { + if ($RequestedMode -ne "Auto") { return $RequestedMode } + + $targetRootAgents = Join-Path $TargetRoot "AGENTS.md" + if (Test-Path -LiteralPath $targetRootAgents) { + if (Test-InteractiveTerminal) { + Write-Host "[learning-flow] Existing AGENTS.md found. Choose integration:" + 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" } + default { return "Preserve" } + } + } + return "Preserve" + } + + 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() + switch ($choice) { + "C" { return "Preserve" } + "D" { return "Skip" } + default { return "Initialize" } + } + } + return "Initialize" +} + +function Add-RootPointer([string]$TargetFile, [string]$PointerFile) { + $content = Get-Content -LiteralPath $TargetFile -Raw + if ($content.Contains("<!-- codebase-learning-flow:start -->")) { + Write-Step "Root AGENTS.md already links the installed workflow" + return + } + $pointer = Get-Content -LiteralPath $PointerFile -Raw + $separator = if ($content.EndsWith("`n")) { "`n" } else { "`n`n" } + [System.IO.File]::AppendAllText($TargetFile, $separator + $pointer.TrimEnd() + "`n", [System.Text.UTF8Encoding]::new($false)) + Write-Step "Connected existing root AGENTS.md to agentic-flow and learning-flow" +} + if ($Repository -like "__GITHUB_OWNER__/*") { throw "Replace __GITHUB_OWNER__ in the installer or pass -Repository owner/codebase-learning-flow." } $resolvedCommit = Resolve-RemoteCommit -RepositoryName $Repository -RequestedRef $Ref -$noCacheHeaders = @{ - "Cache-Control" = "no-cache, no-store, max-age=0" - "Pragma" = "no-cache" -} +$headers = @{ "Cache-Control" = "no-cache, no-store, max-age=0"; "Pragma" = "no-cache" } if (-not $SkipSelfRefresh) { $bootstrapRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("codebase-learning-flow-bootstrap-" + [Guid]::NewGuid().ToString("N")) $latestInstaller = Join-Path $bootstrapRoot "install.ps1" $nonce = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() - $latestInstallerUrl = "https://raw.githubusercontent.com/$Repository/$resolvedCommit/scripts/install.ps1?nocache=$nonce" - + $url = "https://raw.githubusercontent.com/$Repository/$resolvedCommit/scripts/install.ps1?nocache=$nonce" try { New-Item -ItemType Directory -Path $bootstrapRoot -Force | Out-Null Write-Step "Refreshing installer v$InstallerVersion from commit $resolvedCommit" - Invoke-WebRequest ` - -Uri $latestInstallerUrl ` - -OutFile $latestInstaller ` - -UseBasicParsing ` - -Headers $noCacheHeaders - + Invoke-WebRequest -Uri $url -OutFile $latestInstaller -UseBasicParsing -Headers $headers & $latestInstaller ` -TargetPath $TargetPath ` -Repository $Repository ` -Ref $resolvedCommit ` - -LearningDirectory $LearningDirectory ` + -Profile $Profile ` -Mode $Mode ` + -RootAgents $RootAgents ` -SkipRootAgents:$($SkipRootAgents.IsPresent) ` + -SkipSkills:$($SkipSkills.IsPresent) ` -SkipSelfRefresh return } @@ -167,6 +330,31 @@ if (-not (Test-Path -LiteralPath $resolvedTarget)) { New-Item -ItemType Directory -Path $resolvedTarget -Force | Out-Null } +$targetAgentic = Join-Path $resolvedTarget "agentic-flow" +$targetLearning = Join-Path $resolvedTarget "learning-flow" +$targetSkills = Join-Path $resolvedTarget ".agents/skills" +$installedProfile = Get-InstalledProfile $targetLearning +$requestedProfile = $Profile.ToLowerInvariant() +$selectedProfile = if ($requestedProfile -eq "auto") { + if ([string]::IsNullOrWhiteSpace($installedProfile)) { "minimal" } else { $installedProfile } +} else { $requestedProfile } + +if (-not [string]::IsNullOrWhiteSpace($installedProfile) -and $installedProfile -ne $selectedProfile) { + if ($Mode -eq "Update" -and $installedProfile -eq "minimal" -and $selectedProfile -eq "full") { + Write-Step "Upgrading learning profile from minimal to full" + } + elseif ($Mode -eq "Replace") { + Write-Step "Replacing learning profile $installedProfile with $selectedProfile" + } + else { + throw "Profile change $installedProfile -> $selectedProfile is not supported in mode '$Mode'. Use Update for minimal -> full, or Replace for a destructive switch." + } +} + +if ($Mode -eq "Update" -and -not (Test-Path -LiteralPath $targetLearning -PathType Container)) { + throw "$targetLearning does not exist. Use -Mode Fail or -Mode Merge for a new installation." +} + $tempRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("codebase-learning-flow-" + [Guid]::NewGuid().ToString("N")) $archivePath = Join-Path $tempRoot "source.zip" $extractPath = Join-Path $tempRoot "extract" @@ -175,67 +363,121 @@ $archiveUrl = "https://github.com/$Repository/archive/$resolvedCommit.zip?nocach try { New-Item -ItemType Directory -Path $extractPath -Force | Out-Null - Write-Step "Downloading $Repository at commit $resolvedCommit" - Invoke-WebRequest ` - -Uri $archiveUrl ` - -OutFile $archivePath ` - -UseBasicParsing ` - -Headers $noCacheHeaders - + Invoke-WebRequest -Uri $archiveUrl -OutFile $archivePath -UseBasicParsing -Headers $headers Write-Step "Extracting template" Expand-Archive -LiteralPath $archivePath -DestinationPath $extractPath -Force - $archiveRoot = Get-ChildItem -LiteralPath $extractPath -Directory | Select-Object -First 1 - if ($null -eq $archiveRoot) { - throw "The downloaded archive did not contain a repository directory." + $archiveRootItem = Get-ChildItem -LiteralPath $extractPath -Directory | Select-Object -First 1 + if ($null -eq $archiveRootItem) { throw "The downloaded archive did not contain a repository directory." } + $archiveRoot = $archiveRootItem.FullName + + $sourceCommon = Join-Path $archiveRoot "sample/common" + $sourceAgentic = Join-Path $sourceCommon "agentic-flow" + $sourceCommonSkills = Join-Path $sourceCommon ".agents/skills" + $sourceAgenticManagedFiles = Join-Path $sourceAgentic ".managed-files" + $sourceAgenticManagedSkills = Join-Path $sourceAgentic ".managed-skills" + + $sourceProfile = Join-Path $archiveRoot "sample/profiles/$selectedProfile" + $sourceLearning = Join-Path $sourceProfile "learning-flow" + $sourceProfileSkills = Join-Path $sourceProfile ".agents/skills" + $sourceLearningManagedFiles = Join-Path $sourceLearning ".managed-files" + $sourceLearningManagedSkills = Join-Path $sourceLearning ".managed-skills" + $sourceRootAgents = Join-Path $archiveRoot "sample/root/AGENTS.md" + $sourceRootPointer = Join-Path $archiveRoot "sample/root/AGENTS.pointer.md" + + foreach ($requiredDirectory in @($sourceAgentic, $sourceLearning)) { + if (-not (Test-Path -LiteralPath $requiredDirectory -PathType Container)) { + throw "Required framework directory is missing: $requiredDirectory" + } + } + foreach ($requiredFile in @($sourceAgenticManagedFiles, $sourceAgenticManagedSkills, $sourceLearningManagedFiles, $sourceLearningManagedSkills)) { + if (-not (Test-Path -LiteralPath $requiredFile -PathType Leaf)) { + throw "Required framework manifest is missing: $requiredFile" + } + } + if (-not $SkipSkills) { + if (-not (Test-Path -LiteralPath $sourceCommonSkills -PathType Container)) { throw "Common skill directory is missing." } + if (-not (Test-Path -LiteralPath $sourceProfileSkills -PathType Container)) { throw "Profile skill directory is missing." } } - $sourceLearning = Join-Path $archiveRoot.FullName "sample/learning-flow" - $sourceRootAgents = Join-Path $archiveRoot.FullName "sample/root/AGENTS.md" - - if (-not (Test-Path -LiteralPath $sourceLearning -PathType Container)) { - throw "Template directory not found in the downloaded archive: sample/learning-flow" + if ($Mode -eq "Fail") { + if ((Test-DirectoryHasContent $targetAgentic) -or (Test-DirectoryHasContent $targetLearning)) { + throw "agentic-flow or learning-flow already contains files. Use -Mode Merge, -Mode Update, or -Mode Replace." + } + if (-not $SkipSkills) { + $allNames = @( + Get-ManagedSkillNames $sourceAgenticManagedSkills + Get-ManagedSkillNames $sourceLearningManagedSkills + ) + $conflicts = @($allNames | Where-Object { Test-Path -LiteralPath (Join-Path $targetSkills $_) }) + if ($conflicts.Count -gt 0) { + throw "Managed skill folders already exist: $($conflicts -join ', '). Use Merge, Update, Replace, or -SkipSkills." + } + } } - $targetLearning = Join-Path $resolvedTarget $LearningDirectory - $hasExistingLearning = Test-DirectoryHasContent $targetLearning + Install-Component -Name "agentic-flow" -Source $sourceAgentic -Destination $targetAgentic -ManagedFiles $sourceAgenticManagedFiles -InstallMode $Mode + Install-Component -Name "learning-flow/$selectedProfile" -Source $sourceLearning -Destination $targetLearning -ManagedFiles $sourceLearningManagedFiles -InstallMode $Mode - if ($hasExistingLearning -and $Mode -eq "Fail") { - throw "$targetLearning already contains files. Use -Mode Merge or -Mode Replace." - } + if (-not $SkipSkills) { + New-Item -ItemType Directory -Path $targetSkills -Force | Out-Null - if ($Mode -eq "Replace" -and (Test-Path -LiteralPath $targetLearning)) { - Write-Step "Removing existing $LearningDirectory directory" - Remove-Item -LiteralPath $targetLearning -Recurse -Force - } + if ($Mode -eq "Replace") { + Remove-ManagedSkills -ManifestPath $sourceAgenticManagedSkills -TargetSkills $targetSkills + Remove-ManagedSkills -ManifestPath (Join-Path $archiveRoot "sample/profiles/minimal/learning-flow/.managed-skills") -TargetSkills $targetSkills + Remove-ManagedSkills -ManifestPath (Join-Path $archiveRoot "sample/profiles/full/learning-flow/.managed-skills") -TargetSkills $targetSkills + } + elseif ($Mode -eq "Update") { + Remove-ManagedSkills -ManifestPath $sourceAgenticManagedSkills -TargetSkills $targetSkills + if (-not [string]::IsNullOrWhiteSpace($installedProfile)) { + Remove-ManagedSkills -ManifestPath (Join-Path $archiveRoot "sample/profiles/$installedProfile/learning-flow/.managed-skills") -TargetSkills $targetSkills + } + if ($installedProfile -ne $selectedProfile) { + Remove-ManagedSkills -ManifestPath $sourceLearningManagedSkills -TargetSkills $targetSkills + } + } - if ($Mode -eq "Merge" -and (Test-Path -LiteralPath $targetLearning)) { - Write-Step "Merging missing template files" - $mergeResult = Copy-MissingTree -Source $sourceLearning -Destination $targetLearning - Write-Step "Copied $($mergeResult.Copied) files and preserved $($mergeResult.Skipped) existing files" - } - else { - Write-Step "Installing $LearningDirectory" - Copy-Item -LiteralPath $sourceLearning -Destination $targetLearning -Recurse -Force + Install-ManagedSkills -SourceSkills $sourceCommonSkills -ManifestPath $sourceAgenticManagedSkills -TargetSkills $targetSkills -InstallMode $Mode + Install-ManagedSkills -SourceSkills $sourceProfileSkills -ManifestPath $sourceLearningManagedSkills -TargetSkills $targetSkills -InstallMode $Mode } + $requestedRootAgents = if ($SkipRootAgents) { "Skip" } else { $RootAgents } + $resolvedRootAgents = Resolve-RootAgentsMode -TargetRoot $resolvedTarget -RequestedMode $requestedRootAgents $targetRootAgents = Join-Path $resolvedTarget "AGENTS.md" - if (-not $SkipRootAgents) { - if (Test-Path -LiteralPath $targetRootAgents) { - Write-Step "Existing root AGENTS.md preserved" - Write-Step "Manually add a pointer to learning-flow/AGENTS.md if it is not already referenced" + switch ($resolvedRootAgents) { + "Integrate" { + if (-not (Test-Path -LiteralPath $sourceRootPointer -PathType Leaf)) { throw "Root pointer template is missing." } + if (Test-Path -LiteralPath $targetRootAgents -PathType Leaf) { + Add-RootPointer -TargetFile $targetRootAgents -PointerFile $sourceRootPointer + } + elseif (Test-Path -LiteralPath $sourceRootAgents -PathType Leaf) { + Copy-Item -LiteralPath $sourceRootAgents -Destination $targetRootAgents + Write-Step "Created lean Pocok-informed root AGENTS.md" + } + } + "Initialize" { + if (Test-Path -LiteralPath $targetRootAgents) { + if (-not (Test-Path -LiteralPath $targetRootAgents -PathType Leaf)) { throw "Root AGENTS.md exists but is not a file." } + Add-RootPointer -TargetFile $targetRootAgents -PointerFile $sourceRootPointer + } + elseif (Test-Path -LiteralPath $sourceRootAgents -PathType Leaf) { + Copy-Item -LiteralPath $sourceRootAgents -Destination $targetRootAgents + Write-Step "Created lean Pocok-informed root AGENTS.md" + } } - elseif (Test-Path -LiteralPath $sourceRootAgents -PathType Leaf) { - Copy-Item -LiteralPath $sourceRootAgents -Destination $targetRootAgents - Write-Step "Created root AGENTS.md" + "Preserve" { + if (Test-Path -LiteralPath $targetRootAgents) { Write-Step "Existing root AGENTS.md preserved" } + else { Write-Step "Root AGENTS.md left absent" } } + "Skip" { Write-Step "Root AGENTS.md integration skipped" } } - Write-Step "Installation complete" + Write-Step "Installation complete: profile=$selectedProfile mode=$($Mode.ToLowerInvariant()) root-agents=$($resolvedRootAgents.ToLowerInvariant())" Write-Host "" - Write-Host "Next instruction for the repository agent:" - Write-Host "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." + 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." } finally { if (Test-Path -LiteralPath $tempRoot) { diff --git a/scripts/install.sh b/scripts/install.sh index a8a2989..80d28ef 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -4,25 +4,42 @@ set -eu TARGET_PATH="$(pwd)" REPOSITORY="${CODEBASE_LEARNING_FLOW_REPOSITORY:-legrab/codebase-learning-flow}" REF="${CODEBASE_LEARNING_FLOW_REF:-main}" -LEARNING_DIRECTORY="learning-flow" MODE="fail" +PROFILE="auto" SKIP_ROOT_AGENTS="false" +ROOT_AGENTS_MODE="auto" +SKIP_SKILLS="false" usage() { cat <<'EOF' Usage: install.sh [options] Options: - --target PATH Target repository directory - --repository OWNER/REPO Public template repository - --ref REF Branch, tag, or commit reference - --learning-dir NAME Target learning directory name - --mode fail|merge|replace Existing-directory behavior - --skip-root-agents Do not create a missing root AGENTS.md - -h, --help Show this help + --target PATH Target repository directory + --repository OWNER/REPO Public template repository + --ref REF Branch, tag, or commit reference + --profile auto|minimal|full Learning profile; auto keeps an existing profile and defaults new installs to minimal + --mode fail|merge|update|replace Existing-framework behavior + --root-agents MODE auto|integrate|initialize|preserve|skip + --skip-root-agents Alias for --root-agents skip + --skip-skills Do not install or update .agents/skills + -h, --help Show this help EOF } +log() { + printf '%s\n' "[learning-flow] $*" +} + +require_value() { + option="$1" + remaining="$2" + [ "$remaining" -ge 2 ] || { + echo "$option requires a value." >&2 + exit 2 + } +} + require_download_tool() { if command -v curl >/dev/null 2>&1; then DOWNLOAD_CMD="curl" @@ -42,14 +59,12 @@ download_file() { curl -fsSL \ -H 'Cache-Control: no-cache, no-store, max-age=0' \ -H 'Pragma: no-cache' \ - "$url" \ - -o "$output" + "$url" -o "$output" else wget -q \ --header='Cache-Control: no-cache, no-store, max-age=0' \ --header='Pragma: no-cache' \ - "$url" \ - -O "$output" + "$url" -O "$output" fi } @@ -94,34 +109,260 @@ resolve_remote_commit() { printf '%s\n' "$resolved" } +is_interactive_terminal() { + [ -t 1 ] && [ -r /dev/tty ] && [ -w /dev/tty ] +} + +read_tty_choice() { + prompt="$1" + default_choice="$2" + if ! is_interactive_terminal; then + printf '%s\n' "$default_choice" + return + fi + 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 +} + +resolve_root_agents_mode() { + target_root="$1" + requested="$2" + if [ "$requested" != "auto" ]; then + printf '%s\n' "$requested" + return + fi + + if [ -e "$target_root/AGENTS.md" ]; then + if is_interactive_terminal; then + cat > /dev/tty <<'EOF' +[learning-flow] Existing AGENTS.md found. Choose integration: + 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 ;; + esac + else + printf '%s\n' preserve + fi + else + 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 +EOF + choice="$(read_tty_choice 'Choice [B]: ' B)" + case "$choice" in + A) printf '%s\n' initialize ;; + B) printf '%s\n' initialize ;; + C) printf '%s\n' preserve ;; + D) printf '%s\n' skip ;; + esac + else + printf '%s\n' initialize + fi + fi +} + +append_root_pointer() { + target_file="$1" + pointer_file="$2" + if grep -q '<!-- codebase-learning-flow:start -->' "$target_file" 2>/dev/null; then + log "Root AGENTS.md already links the installed workflow" + return + fi + printf '\n' >> "$target_file" + cat "$pointer_file" >> "$target_file" + printf '\n' >> "$target_file" + log "Connected existing root AGENTS.md to agentic-flow and learning-flow" +} + parse_bootstrap_source() { while [ "$#" -gt 0 ]; do case "$1" in --repository) - [ "$#" -ge 2 ] || { - echo "--repository requires a value." >&2 - exit 2 - } + [ "$#" -ge 2 ] || { echo "--repository requires a value." >&2; exit 2; } REPOSITORY="$2" shift 2 ;; --ref) - [ "$#" -ge 2 ] || { - echo "--ref requires a value." >&2 - exit 2 - } + [ "$#" -ge 2 ] || { echo "--ref requires a value." >&2; exit 2; } REF="$2" shift 2 ;; - *) - shift + -h|--help) + usage + exit 0 ;; + *) shift ;; esac done } -require_download_tool +read_profile_file() { + profile_file="$1" + [ -f "$profile_file" ] || return 0 + sed -n '1{s/[[:space:]]//g;p;}' "$profile_file" | tr 'A-Z' 'a-z' +} + +has_content() { + directory="$1" + [ -d "$directory" ] && [ -n "$(find "$directory" -mindepth 1 -maxdepth 1 -print -quit 2>/dev/null || true)" ] +} + +copy_missing_tree() { + source_root="$1" + target_root="$2" + + mkdir -p "$target_root" + find "$source_root" -type d | while IFS= read -r source_dir; do + relative="${source_dir#"$source_root"}" + mkdir -p "$target_root$relative" + done + + find "$source_root" -type f | while IFS= read -r source_file; do + relative="${source_file#"$source_root"/}" + target_file="$target_root/$relative" + mkdir -p "$(dirname "$target_file")" + if [ ! -e "$target_file" ]; then + cp "$source_file" "$target_file" + fi + done +} + +copy_managed_files() { + source_root="$1" + target_root="$2" + manifest="$3" + copied=0 + + while IFS= read -r relative || [ -n "$relative" ]; do + case "$relative" in + ''|'#'*) continue ;; + /*|..|../*|*/../*|*/..) + echo "Unsafe path in managed-files manifest: $relative" >&2 + exit 1 + ;; + esac + + source_file="$source_root/$relative" + target_file="$target_root/$relative" + [ -f "$source_file" ] || { + echo "Managed source file is missing: $relative" >&2 + exit 1 + } + [ ! -d "$target_file" ] || { + echo "Managed target path is a directory, expected a file: $relative" >&2 + exit 1 + } + mkdir -p "$(dirname "$target_file")" + cp "$source_file" "$target_file" + copied=$((copied + 1)) + done < "$manifest" + + log "Updated $copied managed files in $(basename "$target_root")" +} + +skill_names_from_manifest() { + manifest="$1" + [ -f "$manifest" ] || return 0 + while IFS= read -r name || [ -n "$name" ]; do + case "$name" in + ''|'#'*) continue ;; + *[!A-Za-z0-9._-]*) + echo "Unsafe skill name in managed-skills manifest: $name" >&2 + exit 1 + ;; + esac + printf '%s\n' "$name" + done < "$manifest" +} + +remove_skills_from_manifest() { + manifest="$1" + target_skills="$2" + [ -f "$manifest" ] || return 0 + + while IFS= read -r skill_name; do + [ -n "$skill_name" ] || continue + target_skill="$target_skills/$skill_name" + if [ -e "$target_skill" ]; then + rm -rf "$target_skill" + log "Removed managed skill '$skill_name'" + fi + done <<EOF +$(skill_names_from_manifest "$manifest") +EOF +} + +install_component() { + component_name="$1" + source_root="$2" + target_root="$3" + managed_files="$4" + + if [ "$MODE" = "replace" ] && [ -e "$target_root" ]; then + log "Removing existing $component_name directory" + rm -rf "$target_root" + fi + + if [ "$MODE" = "merge" ] && [ -d "$target_root" ]; then + log "Merging missing $component_name files" + copy_missing_tree "$source_root" "$target_root" + elif [ "$MODE" = "update" ]; then + log "Adding missing $component_name files" + copy_missing_tree "$source_root" "$target_root" + log "Updating framework-owned $component_name files" + copy_managed_files "$source_root" "$target_root" "$managed_files" + else + log "Installing $component_name" + mkdir -p "$target_root" + cp -R "$source_root"/. "$target_root"/ + fi +} + +install_skills_from_manifest() { + source_skills="$1" + manifest="$2" + target_skills="$3" + + while IFS= read -r skill_name; do + [ -n "$skill_name" ] || continue + source_skill="$source_skills/$skill_name" + target_skill="$target_skills/$skill_name" + [ -d "$source_skill" ] || { + echo "Managed skill source is missing: $skill_name" >&2 + exit 1 + } + + if [ -e "$target_skill" ]; then + if [ "$MODE" = "merge" ]; then + log "Existing skill '$skill_name' preserved" + continue + fi + rm -rf "$target_skill" + fi + + cp -R "$source_skill" "$target_skill" + log "Installed skill '$skill_name'" + done <<EOF +$(skill_names_from_manifest "$manifest") +EOF +} + parse_bootstrap_source "$@" +require_download_tool case "$REPOSITORY" in __GITHUB_OWNER__/*) @@ -133,24 +374,19 @@ esac if [ "${CODEBASE_LEARNING_FLOW_SKIP_SELF_REFRESH:-0}" != "1" ]; then bootstrap_root="$(mktemp -d 2>/dev/null || mktemp -d -t codebase-learning-flow-bootstrap)" bootstrap_script="$bootstrap_root/install.sh" - - cleanup_bootstrap() { - rm -rf "$bootstrap_root" - } + cleanup_bootstrap() { rm -rf "$bootstrap_root"; } trap cleanup_bootstrap EXIT HUP INT TERM resolved_bootstrap_commit="$(resolve_remote_commit "$REPOSITORY" "$REF")" nonce="$(date +%s)" bootstrap_url="https://raw.githubusercontent.com/$REPOSITORY/$resolved_bootstrap_commit/scripts/install.sh?nocache=$nonce" - printf '%s\n' "[learning-flow] Refreshing installer from commit $resolved_bootstrap_commit" + log "Refreshing installer from commit $resolved_bootstrap_commit" download_file "$bootstrap_url" "$bootstrap_script" set +e CODEBASE_LEARNING_FLOW_SKIP_SELF_REFRESH=1 \ - sh "$bootstrap_script" "$@" \ - --repository "$REPOSITORY" \ - --ref "$resolved_bootstrap_commit" + sh "$bootstrap_script" "$@" --repository "$REPOSITORY" --ref "$resolved_bootstrap_commit" status=$? set -e @@ -162,27 +398,42 @@ fi while [ "$#" -gt 0 ]; do case "$1" in --target) + require_value "$1" "$#" TARGET_PATH="$2" shift 2 ;; --repository) + require_value "$1" "$#" REPOSITORY="$2" shift 2 ;; --ref) + require_value "$1" "$#" REF="$2" shift 2 ;; - --learning-dir) - LEARNING_DIRECTORY="$2" + --profile) + require_value "$1" "$#" + PROFILE="$(printf '%s' "$2" | tr 'A-Z' 'a-z')" shift 2 ;; --mode) - MODE="$2" + require_value "$1" "$#" + MODE="$(printf '%s' "$2" | tr 'A-Z' 'a-z')" + shift 2 + ;; + --root-agents) + require_value "$1" "$#" + ROOT_AGENTS_MODE="$(printf '%s' "$2" | tr 'A-Z' 'a-z')" shift 2 ;; --skip-root-agents) SKIP_ROOT_AGENTS="true" + ROOT_AGENTS_MODE="skip" + shift + ;; + --skip-skills) + SKIP_SKILLS="true" shift ;; -h|--help) @@ -197,106 +448,164 @@ while [ "$#" -gt 0 ]; do esac done -case "$MODE" in - fail|merge|replace) ;; - *) - echo "Invalid mode: $MODE" >&2 - exit 2 - ;; -esac +case "$MODE" in fail|merge|update|replace) ;; *) echo "Invalid mode: $MODE" >&2; exit 2 ;; esac +case "$PROFILE" in auto|minimal|full) ;; *) echo "Invalid profile: $PROFILE" >&2; exit 2 ;; esac +case "$ROOT_AGENTS_MODE" in auto|integrate|initialize|preserve|skip) ;; *) echo "Invalid root agents mode: $ROOT_AGENTS_MODE" >&2; exit 2 ;; esac -command -v unzip >/dev/null 2>&1 || { - echo "The installer requires unzip." >&2 - exit 1 -} - -log() { - printf '%s\n' "[learning-flow] $*" -} +command -v unzip >/dev/null 2>&1 || { echo "The installer requires unzip." >&2; exit 1; } mkdir -p "$TARGET_PATH" TARGET_PATH="$(cd "$TARGET_PATH" && pwd)" -TARGET_LEARNING="$TARGET_PATH/$LEARNING_DIRECTORY" -RESOLVED_COMMIT="$(resolve_remote_commit "$REPOSITORY" "$REF")" +TARGET_AGENTIC="$TARGET_PATH/agentic-flow" +TARGET_LEARNING="$TARGET_PATH/learning-flow" +TARGET_SKILLS="$TARGET_PATH/.agents/skills" + +INSTALLED_PROFILE="$(read_profile_file "$TARGET_LEARNING/.template-profile")" +case "$INSTALLED_PROFILE" in ''|minimal|full) ;; *) echo "Invalid installed profile marker: $INSTALLED_PROFILE" >&2; exit 1 ;; esac +if [ -z "$INSTALLED_PROFILE" ] && has_content "$TARGET_LEARNING"; then + INSTALLED_PROFILE="full" +fi + +if [ "$PROFILE" = "auto" ]; then + if [ -n "$INSTALLED_PROFILE" ]; then SELECTED_PROFILE="$INSTALLED_PROFILE"; else SELECTED_PROFILE="minimal"; fi +else + SELECTED_PROFILE="$PROFILE" +fi + +if [ -n "$INSTALLED_PROFILE" ] && [ "$INSTALLED_PROFILE" != "$SELECTED_PROFILE" ]; then + if [ "$MODE" = "update" ] && [ "$INSTALLED_PROFILE" = "minimal" ] && [ "$SELECTED_PROFILE" = "full" ]; then + log "Upgrading learning profile from minimal to full" + elif [ "$MODE" = "replace" ]; then + log "Replacing learning profile $INSTALLED_PROFILE with $SELECTED_PROFILE" + else + echo "Profile change $INSTALLED_PROFILE -> $SELECTED_PROFILE is not supported in mode '$MODE'. Use update for minimal -> full, or replace for a destructive switch." >&2 + exit 1 + fi +fi +if [ "$MODE" = "update" ] && [ ! -d "$TARGET_LEARNING" ]; then + echo "$TARGET_LEARNING does not exist. Use --mode fail or --mode merge for a new installation." >&2 + exit 1 +fi + +RESOLVED_COMMIT="$(resolve_remote_commit "$REPOSITORY" "$REF")" TEMP_ROOT="$(mktemp -d 2>/dev/null || mktemp -d -t codebase-learning-flow)" -cleanup() { - rm -rf "$TEMP_ROOT" -} +cleanup() { rm -rf "$TEMP_ROOT"; } trap cleanup EXIT HUP INT TERM ARCHIVE_PATH="$TEMP_ROOT/source.zip" EXTRACT_PATH="$TEMP_ROOT/extract" NONCE="$(date +%s)" ARCHIVE_URL="https://github.com/$REPOSITORY/archive/$RESOLVED_COMMIT.zip?nocache=$NONCE" - mkdir -p "$EXTRACT_PATH" log "Downloading $REPOSITORY at commit $RESOLVED_COMMIT" download_file "$ARCHIVE_URL" "$ARCHIVE_PATH" - log "Extracting template" unzip -q "$ARCHIVE_PATH" -d "$EXTRACT_PATH" ARCHIVE_ROOT="$(find "$EXTRACT_PATH" -mindepth 1 -maxdepth 1 -type d | head -n 1)" -SOURCE_LEARNING="$ARCHIVE_ROOT/sample/learning-flow" +SOURCE_COMMON="$ARCHIVE_ROOT/sample/common" +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_PROFILE="$ARCHIVE_ROOT/sample/profiles/$SELECTED_PROFILE" +SOURCE_LEARNING="$SOURCE_PROFILE/learning-flow" +SOURCE_PROFILE_SKILLS="$SOURCE_PROFILE/.agents/skills" +SOURCE_LEARNING_MANAGED_FILES="$SOURCE_LEARNING/.managed-files" +SOURCE_LEARNING_MANAGED_SKILLS="$SOURCE_LEARNING/.managed-skills" SOURCE_ROOT_AGENTS="$ARCHIVE_ROOT/sample/root/AGENTS.md" +SOURCE_ROOT_POINTER="$ARCHIVE_ROOT/sample/root/AGENTS.pointer.md" -if [ ! -d "$SOURCE_LEARNING" ]; then - echo "Template directory not found in the downloaded archive: sample/learning-flow" >&2 - exit 1 -fi - -has_content="false" -if [ -d "$TARGET_LEARNING" ] && [ -n "$(find "$TARGET_LEARNING" -mindepth 1 -maxdepth 1 -print -quit)" ]; then - has_content="true" +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 + [ -f "$required" ] || { echo "Required framework manifest is missing: $required" >&2; exit 1; } +done +if [ "$SKIP_SKILLS" != "true" ]; then + [ -d "$SOURCE_COMMON_SKILLS" ] || { echo "Common skill directory is missing." >&2; exit 1; } + [ -d "$SOURCE_PROFILE_SKILLS" ] || { echo "Profile skill directory is missing." >&2; exit 1; } fi -if [ "$has_content" = "true" ] && [ "$MODE" = "fail" ]; then - echo "$TARGET_LEARNING already contains files. Use --mode merge or --mode replace." >&2 - exit 1 -fi +if [ "$MODE" = "fail" ]; then + if has_content "$TARGET_AGENTIC" || has_content "$TARGET_LEARNING"; then + echo "agentic-flow or learning-flow already contains files. Use --mode merge, --mode update, or --mode replace." >&2 + exit 1 + fi -if [ "$MODE" = "replace" ] && [ -e "$TARGET_LEARNING" ]; then - log "Removing existing $LEARNING_DIRECTORY directory" - rm -rf "$TARGET_LEARNING" + if [ "$SKIP_SKILLS" != "true" ]; then + conflicts="" + for manifest in "$SOURCE_AGENTIC_MANAGED_SKILLS" "$SOURCE_LEARNING_MANAGED_SKILLS"; do + while IFS= read -r skill_name || [ -n "$skill_name" ]; do + case "$skill_name" in ''|'#'*) continue ;; esac + if [ -e "$TARGET_SKILLS/$skill_name" ]; then + if [ -z "$conflicts" ]; then conflicts="$skill_name"; else conflicts="$conflicts, $skill_name"; fi + fi + done < "$manifest" + done + [ -z "$conflicts" ] || { + echo "Managed skill folders already exist: $conflicts. Use merge, update, replace, or --skip-skills." >&2 + exit 1 + } + fi fi -if [ "$MODE" = "merge" ] && [ -d "$TARGET_LEARNING" ]; then - log "Merging missing template files" +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" - find "$SOURCE_LEARNING" -type d | while IFS= read -r source_dir; do - relative="${source_dir#"$SOURCE_LEARNING"}" - mkdir -p "$TARGET_LEARNING$relative" - done - - find "$SOURCE_LEARNING" -type f | while IFS= read -r source_file; do - relative="${source_file#"$SOURCE_LEARNING"/}" - target_file="$TARGET_LEARNING/$relative" - mkdir -p "$(dirname "$target_file")" +if [ "$SKIP_SKILLS" != "true" ]; then + mkdir -p "$TARGET_SKILLS" - if [ ! -e "$target_file" ]; then - cp "$source_file" "$target_file" + if [ "$MODE" = "replace" ]; then + remove_skills_from_manifest "$SOURCE_AGENTIC_MANAGED_SKILLS" "$TARGET_SKILLS" + remove_skills_from_manifest "$ARCHIVE_ROOT/sample/profiles/minimal/learning-flow/.managed-skills" "$TARGET_SKILLS" + remove_skills_from_manifest "$ARCHIVE_ROOT/sample/profiles/full/learning-flow/.managed-skills" "$TARGET_SKILLS" + elif [ "$MODE" = "update" ]; then + remove_skills_from_manifest "$SOURCE_AGENTIC_MANAGED_SKILLS" "$TARGET_SKILLS" + if [ -n "$INSTALLED_PROFILE" ]; then + remove_skills_from_manifest "$ARCHIVE_ROOT/sample/profiles/$INSTALLED_PROFILE/learning-flow/.managed-skills" "$TARGET_SKILLS" fi - done + if [ "$INSTALLED_PROFILE" != "$SELECTED_PROFILE" ]; then + remove_skills_from_manifest "$SOURCE_LEARNING_MANAGED_SKILLS" "$TARGET_SKILLS" + fi + fi - log "Merge completed. Existing files were preserved." -else - log "Installing $LEARNING_DIRECTORY" - mkdir -p "$(dirname "$TARGET_LEARNING")" - cp -R "$SOURCE_LEARNING" "$TARGET_LEARNING" + install_skills_from_manifest "$SOURCE_COMMON_SKILLS" "$SOURCE_AGENTIC_MANAGED_SKILLS" "$TARGET_SKILLS" + install_skills_from_manifest "$SOURCE_PROFILE_SKILLS" "$SOURCE_LEARNING_MANAGED_SKILLS" "$TARGET_SKILLS" fi -if [ "$SKIP_ROOT_AGENTS" != "true" ]; then - if [ -e "$TARGET_PATH/AGENTS.md" ]; then - log "Existing root AGENTS.md preserved" - log "Manually add a pointer to learning-flow/AGENTS.md if it is not already referenced" - elif [ -f "$SOURCE_ROOT_AGENTS" ]; then - cp "$SOURCE_ROOT_AGENTS" "$TARGET_PATH/AGENTS.md" - log "Created root AGENTS.md" - fi +if [ "$SKIP_ROOT_AGENTS" = "true" ]; then + ROOT_AGENTS_MODE="skip" fi +RESOLVED_ROOT_AGENTS_MODE="$(resolve_root_agents_mode "$TARGET_PATH" "$ROOT_AGENTS_MODE")" +case "$RESOLVED_ROOT_AGENTS_MODE" in + integrate) + [ -f "$SOURCE_ROOT_POINTER" ] || { echo "Root pointer template is missing." >&2; exit 1; } + if [ -f "$TARGET_PATH/AGENTS.md" ]; then + append_root_pointer "$TARGET_PATH/AGENTS.md" "$SOURCE_ROOT_POINTER" + elif [ -f "$SOURCE_ROOT_AGENTS" ]; then + cp "$SOURCE_ROOT_AGENTS" "$TARGET_PATH/AGENTS.md" + log "Created lean Pocok-informed root AGENTS.md" + fi + ;; + initialize) + if [ -e "$TARGET_PATH/AGENTS.md" ]; then + [ -f "$TARGET_PATH/AGENTS.md" ] || { echo "Root AGENTS.md exists but is not a file." >&2; exit 1; } + append_root_pointer "$TARGET_PATH/AGENTS.md" "$SOURCE_ROOT_POINTER" + elif [ -f "$SOURCE_ROOT_AGENTS" ]; then + cp "$SOURCE_ROOT_AGENTS" "$TARGET_PATH/AGENTS.md" + log "Created lean Pocok-informed root AGENTS.md" + fi + ;; + preserve) + if [ -e "$TARGET_PATH/AGENTS.md" ]; then log "Existing root AGENTS.md preserved"; else log "Root AGENTS.md left absent"; fi + ;; + skip) log "Root AGENTS.md integration skipped" ;; +esac -log "Installation complete" -printf '\n%s\n' "Next instruction for the repository agent:" -printf '%s\n' "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." +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." diff --git a/skill-evals/README.md b/skill-evals/README.md new file mode 100644 index 0000000..b2e3428 --- /dev/null +++ b/skill-evals/README.md @@ -0,0 +1,9 @@ +# Routing and behavior checks + +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. +- `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. diff --git a/skill-evals/agentic-cases.yaml b/skill-evals/agentic-cases.yaml new file mode 100644 index 0000000..bee6f2b --- /dev/null +++ b/skill-evals/agentic-cases.yaml @@ -0,0 +1,60 @@ +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_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. + expected_skill: none_or_task_skill + must_include: [use defaults, no full 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 + must_include: [meaningful fork, concise options] + must_not: [complete 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: 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] + - prompt: Summarize this substantial change and suggest a commit message that makes the reasoning easy to scan. + 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: 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_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_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_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 + - 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 + + - prompt: "Explain this full-profile repository to me; I am not sure how much background you should assume." + expected_skill: agentic-workflow + must_include: + - at most one learner-context A/B/C/D question when experience matters + - concise conceptual overview first + must_not: + - ask the complete setup questionnaire + - hide required decisions inside collapsed content diff --git a/skill-evals/full-cases.yaml b/skill-evals/full-cases.yaml new file mode 100644 index 0000000..c9246a2 --- /dev/null +++ b/skill-evals/full-cases.yaml @@ -0,0 +1,29 @@ +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_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_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_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_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] + - 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] + - 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 new file mode 100644 index 0000000..7c1f698 --- /dev/null +++ b/skill-evals/minimal-cases.yaml @@ -0,0 +1,34 @@ +profile: minimal +cases: + - prompt: Diagnose this failing test and fix it. + expected_skill: repository-learning + expected_branch: bug + must_include: [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] + - prompt: Refactor this parser without changing output. + expected_skill: repository-learning + expected_branch: refactor + must_include: [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] + - 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] + - prompt: Configure how agents should plan and pause in this repository. + expected_skill: agentic-workflow + must_include: [agentic-flow settings] + must_not: [repository-learning as second setup skill] + - 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]