@mriekki/lean 0.0.0-stage → 0.1.1

package/assets/generated/core/core/skills/code-walkthrough/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: code-walkthrough
+description: "Read-only guided walkthrough of an implementation diff, explaining changed files functionally and technically with optional deeper coaching, tracing, diagrams, quizzes, debugging discussion, and interview practice."
+argument-hint: "[work-item|PR|commit|current] [light|focused|deep]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Code Walkthrough
+
+Purpose: help the developer understand an actual implementation by walking through the changed files in a sensible order and connecting functional behavior to technical design.
+
+`/code-walkthrough` is optional, read-only, and never blocks review, delivery, merge, or work-item completion.
+
+## 1. Boundaries
+
+- Do not edit production code or tests.
+- Do not implement fixes during the walkthrough.
+- Do not commit, push, merge, or modify a PR.
+- Do not update learning-progress files unless the human explicitly chooses that after the walkthrough.
+- Do not invoke subagents.
+- Do not silently broaden the implementation scope.
+- Do not pin/request/switch to a premium model automatically.
+- Distinguish observed implementation evidence from assumptions.
+- Distinguish AI-generated code, developer-reviewed understanding, study, and actual implementation experience when credibility matters.
+
+If a bug, design concern, or missing test is discovered, explain it and offer a return to the normal implementation/review workflow. Do not fix it while in walkthrough mode.
+
+## 2. Resolve the change set
+
+Use Git/GitHub evidence as the source of truth. VS Code Source Control/diff views are visual aids, not workflow state.
+
+Resolve in this order when possible:
+
+```text
+explicit PR / commit / ref
+→ work-item-associated branch or PR supported by evidence
+→ current feature branch versus the merge-base of the configured default branch
+→ current staged/unstaged tracked changes
+→ ask one concise scope question when materially ambiguous
+```
+
+For an explicit PR, use the PR base/head change set and do not silently mix unrelated local changes.
+
+For an active feature branch, prefer the branch change from the default-branch merge base. Identify relevant tracked working changes and call out untracked files explicitly rather than silently omitting them.
+
+For merged work, use the PR, merge commit, or explicit historical commit range.
+
+Never invent branch, work-item, PR, or commit associations.
+
+## 3. Depth
+
+```text
+Light   — what changed, why, and major connections
+Focused — default; behavior, important mechanics, relationships, tests, and learning hooks
+Deep    — important methods/blocks, state/data flow, dependencies, edge cases, failure modes, tests, and tradeoffs
+```
+
+Depth may vary by file. Treat trivial configuration lightly unless it materially affects behavior; spend more depth on implementation anchors.
+
+## 4. Build the walkthrough plan
+
+Before explaining the first file:
+
+1. identify the changed files and change types,
+2. read only enough work-item/requirements context to understand intended behavior,
+3. identify likely implementation anchors and relationships,
+4. order files for understanding rather than alphabetically,
+5. present a concise plan and start with the first meaningful file.
+
+Use repository architecture rather than a fixed stack assumption. A common web-application order may be:
+
+```text
+domain/data model
+→ persistence
+→ service/business logic
+→ API/controller
+→ client model/service/state
+→ UI/component
+→ tests near the behavior they verify
+→ configuration/operational files
+```
+
+An event-driven or systems repository may require a different path. Infer from actual imports, references, paths, changed symbols, tests, and architecture.
+
+## 5. Per-file walkthrough
+
+For each meaningful changed file, cover only what is useful:
+
+```text
+FILE <n> OF <total>
+<path>
+
+ROLE
+Why this file exists in the system.
+
+FUNCTIONAL CHANGE
+What behavior or capability changed.
+
+TECHNICAL CHANGE
+Important classes/functions/data structures/framework mechanisms and how they changed.
+
+HOW THIS CONNECTS
+Upstream/downstream callers, data flow, state flow, persistence, UI, events, or other dependencies.
+
+WHY THIS DESIGN
+Important choice, convention, or tradeoff when evidence supports it.
+
+TESTING
+Relevant tests/evidence and what they do or do not prove. Never claim a test passed unless execution evidence was observed.
+
+LEARNING HOOKS
+Concepts worth understanding more deeply.
+```
+
+For change types:
+- new file: explain why the responsibility now exists;
+- modified file: explain meaningful before-versus-after behavior;
+- deleted file: explain what responsibility disappeared or moved;
+- renamed/moved file: distinguish structural movement from behavioral change.
+
+Group trivial generated/configuration changes when that improves learning, but do not hide behaviorally important files.
+
+## 6. Guided navigation
+
+Default to one file or one tightly related file group at a time. Do not dump the whole implementation at once.
+
+At a natural file boundary, show a compact navigation cue such as:
+
+```text
+NEXT: <suggested file>
+Use: next | deeper | explain this | trace | why this design | diagram | quiz | debug | interview | skip | stop
+```
+
+Interpret these naturally:
+- `next` — continue to the suggested next file;
+- `deeper` — increase depth for the current file/topic;
+- `explain this` — focus on the selected/current method, block, symbol, or diff hunk;
+- `trace` — follow request/data/state/event flow across files;
+- `why this design` — discuss alternatives and tradeoffs grounded in repository context;
+- `diagram` — use an ephemeral Mermaid diagram when useful;
+- `quiz` — briefly switch to adaptive Coach-style understanding questions;
+- `debug` — discuss likely failure modes, evidence, and debugging approach without implementing a fix;
+- `interview` — practice explaining or defending the implementation credibly;
+- `skip` — cover the current file lightly and move on;
+- `stop` — end without affecting engineering status.
+
+Do not repeatedly ask whether to continue when the next action is obvious.
+
+## 7. Tracing and learning depth
+
+When tracing, connect actual call/data/state flow. Example shape only:
+
+```text
+UI/input
+→ client/service
+→ API/handler
+→ application/service logic
+→ persistence/event/system boundary
+→ response/result
+```
+
+Map deeper exploration to the shared learning levels when useful:
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+Use `/coach` for broader concept learning and `/learning-review` for structured assessment after the walkthrough.
+
+## 8. Completion
+
+When the planned change set is covered or the human stops, summarize:
+
+- end-to-end implementation flow,
+- major functional changes,
+- important technical decisions and connections,
+- concepts explored deeply versus lightly,
+- tests/evidence actually observed,
+- learning gaps or topics worth revisiting,
+- optional next learning actions.
+
+Offer only relevant next choices, such as:
+
+```text
+1. /learning-review <same scope> [READ ONLY]
+2. /coach <specific concept> [READ ONLY]
+3. Return to engineering workflow [NO ACTION]
+4. Stop [NO ACTION]
+```
+
+Do not create a new engineering state such as `CODE_WALKTHROUGH_PENDING`. Walkthrough completion is learning evidence, not a delivery gate.

package/assets/generated/core/core/skills/core-sync/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: core-sync
+description: Guided Core-to-consumer synchronization that uses a safe local Core checkout when available and otherwise uses configured remote orchestration without requiring a Core clone.
+argument-hint: "[optional local Core path]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Core Sync
+
+`/core-sync` updates a consumer repository to a newer accepted Lean Agentic Core baseline while preserving consumer-owned content and the Human-in-the-Loop delivery boundary.
+
+A local Core checkout is an optimization, not a prerequisite. Do not clone Core merely to satisfy `/core-sync`.
+
+Invocation starts read-only. One explicit sync choice may authorize the bounded mechanics needed for the selected local or remote path; merge/final acceptance remains separate.
+
+## 1. Establish the consumer baseline
+
+From the consumer repository, read:
+
+- `CORE_BASELINE.json`,
+- `.github/lean-workspace.json` when present,
+- `.github/lean-core-sync.json` when present,
+- current Git status, branch, remotes, and default branch when observable.
+
+Run the repository-local integrity check before planning an update:
+
+```text
+python tools/lean-core/check-core-baseline.py --root .
+```
+
+Stop if the current managed overlay already has unexplained local drift, missing managed files, or invalid baseline metadata. Do not treat consumer edits as disposable.
+
+Resolve from `CORE_BASELINE.json`:
+
+- canonical Core repository,
+- currently accepted Core commit/version,
+- distribution name,
+- managed-path ownership/hashes.
+
+## 2. Resolve the Core source automatically
+
+Check local candidates in this order:
+
+1. an explicit Core path supplied by the human,
+2. an already-open workspace folder that unambiguously resolves to the recorded Core repository,
+3. the sibling checkout derived from the Core repository name, normally `../lean-agentic-core`.
+
+Do not broadly scan the developer's filesystem.
+
+A local candidate is usable only when:
+
+- it is a Git repository,
+- its configured remote resolves to the Core repository recorded in `CORE_BASELINE.json`,
+- its repository state can be inspected safely.
+
+If no usable local Core checkout exists, use the configured remote provider from `.github/lean-core-sync.json` when available. Do not ask the developer to clone Core just because the local candidate is absent.
+
+## 3. Classify a local Core checkout
+
+Before modifying a local Core checkout inspect:
+
+```text
+git -C <core-path> status --short --branch
+git -C <core-path> branch --show-current
+git -C <core-path> remote -v
+git -C <core-path> branch -vv
+```
+
+A local Core checkout may be automatically refreshed only when all of these are true:
+
+- the worktree is clean,
+- no merge/rebase/cherry-pick is in progress,
+- the checkout is on its normal accepted/default branch,
+- an unambiguous upstream exists,
+- updating can be performed fast-forward-only.
+
+Never auto-stash, merge, rebase, reset, clean, force-update, or discard Core work.
+
+If the local Core checkout is dirty, ahead, diverged, on an intentional non-default ref, or otherwise ambiguous, preserve it unchanged. When a remote provider is configured, prefer the remote path for the consumer update. Otherwise stop with the observed local state and the missing capability; do not silently use an unaccepted local ref.
+
+## 4. Present one bounded sync choice
+
+### Safe local Core available
+
+Present:
+
+```text
+CORE SYNC READY
+
+Consumer baseline: <commit/version>
+Source: LOCAL <core-path>
+Local Core state: CURRENT | FAST-FORWARDABLE
+Distribution: <distribution>
+
+1. Sync to the accepted Core source [GIT + FILE WRITE] — recommended
+2. Keep inspecting only [READ ONLY]
+3. Stop [NO ACTION]
+```
+
+Choosing option 1 authorizes only the bounded local-sync mechanics described below: safe Core refresh if needed, consumer sync-branch setup, safe Core overlay application, and verification. It does not authorize `/deliver`, merge, release publication, or production deployment.
+
+### No safe local Core available, remote provider configured
+
+Present:
+
+```text
+CORE SYNC READY
+
+Consumer baseline: <commit/version>
+Source: REMOTE PROVIDER
+Local Core: NOT REQUIRED
+Provider: <provider repository>
+
+1. Request remote Core sync [REMOTE WRITE] — recommended
+2. Keep inspecting only [READ ONLY]
+3. Stop [NO ACTION]
+```
+
+Choosing option 1 authorizes creation of exactly the configured remote sync request for this consumer. It does not authorize merging the resulting consumer PR.
+
+### Neither source is usable
+
+Report `CORE SYNC BLOCKED` with the evidence. A missing local Core checkout by itself is not an error; the blocker is the absence of both a safe local source and a configured/usable remote provider.
+
+## 5. Local sync path
+
+After option 1 is selected:
+
+1. Refresh the local Core remote state.
+2. Reclassify the accepted/default Core branch.
+3. If behind and fast-forward-safe, update using the equivalent of:
+
+```text
+git -C <core-path> pull --ff-only
+```
+
+4. If Core is ahead, diverged, dirty, or otherwise unsafe after refresh, stop without changing the consumer and prefer the configured remote provider when available.
+5. Run a Core sync preview from the refreshed checkout using the distribution recorded by the consumer baseline.
+6. Stop without apply on any unsafe sync state, including `LOCAL_DRIFT`, `CONFLICT`, `LOCAL_MISSING`, `UNTRACKED_CONFLICT`, or an unaccepted `RETIRED_PATH`.
+7. If the consumer is on its default branch, create/switch to a repository-appropriate short-lived chore branch such as `chore/sync-core-<version-or-short-sha>`. This branch setup is routine inside the selected bounded sync action.
+8. Apply only the safe Core additions/updates and refresh `CORE_BASELINE.json` using Core's canonical `tools/package/sync.py` contract.
+
+Do not manually copy individual managed files as a substitute for the canonical sync tool.
+
+## 6. Remote sync path
+
+Remote orchestration is consumer configuration, not a hardcoded Core service. Read `.github/lean-core-sync.json` and require:
+
+```json
+{
+  "schemaVersion": 1,
+  "remote": {
+    "type": "github-issue-control-plane",
+    "repository": "owner/control-plane-repo",
+    "titleTemplate": "[sync-core] {owner}/{repository}",
+    "requireEmptyBody": true
+  }
+}
+```
+
+Only the placeholders `{owner}` and `{repository}` may be substituted in `titleTemplate`. Resolve them from the consumer's canonical GitHub remote. Do not put product requirements, baseline JSON, source code, secrets, or other private consumer details into the public request.
+
+For `github-issue-control-plane`, create exactly one issue in the configured provider repository using the rendered title and an empty body. Use the environment's normal GitHub integration or CLI; never request or expose a long-lived Core credential merely to make the request.
+
+The remote provider is expected to:
+
+- validate requester/target authorization,
+- obtain its own short-lived source/target credentials,
+- resolve the accepted Core source,
+- run the canonical Core sync contract against the target consumer,
+- refuse unsafe consumer drift/conflicts,
+- update exact Core provenance,
+- publish the result on a short-lived consumer branch and PR,
+- run/observe consumer CI.
+
+If the configured provider does not support that contract, report `REMOTE SYNC UNAVAILABLE`; do not silently clone Core or invent a different synchronization mechanism.
+
+## 7. Verification
+
+### Local path
+
+After apply, run:
+
+```text
+python tools/lean-core/check-core-baseline.py --root .
+git status --short --branch
+git diff --stat
+git diff -- CORE_BASELINE.json
+```
+
+Confirm:
+
+- managed paths match the refreshed hashes,
+- consumer-owned paths were not overwritten,
+- the baseline records the exact Core commit actually applied,
+- only the intended sync branch changed.
+
+Present the meaningful diff for human review. After acceptance, recommend `/deliver` for normal commit/push/PR/CI mechanics.
+
+### Remote path
+
+Observe the provider result when available. Report the target branch/PR and exact Core commit applied. The human reviews the consumer PR and retains the normal explicit merge/finalize gate.
+
+If the developer has a local consumer checkout, remind them to use `/pull-latest` after the remote sync PR is merged when their local working state is safe. Do not overwrite unrelated local work.
+
+## 8. Boundaries
+
+`/core-sync` never:
+
+- requires a local Core clone when a configured remote provider can perform the update,
+- modifies a dirty/diverged/intentional local Core checkout automatically,
+- uses merge/rebase/reset/force operations to refresh Core,
+- treats managed consumer drift as disposable,
+- overwrites consumer-owned paths merely because Core has a similarly named destination,
+- publishes a Core release/tag,
+- merges the consumer sync PR without the normal explicit final gate,
+- deploys production.
+
+If reusable Core content itself is wrong, fix Core canonically instead of forking the reusable file in the consumer.

package/assets/generated/core/core/skills/define-feature/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: define-feature
+description: Define or clarify a feature, initiative, engineering enabler, or other work item while respecting the configured source-of-truth and optional brief model.
+argument-hint: "<work-item ID, external key, idea, or topic>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Define Feature
+
+Keep discovery proportional. Do not turn a small change into a ceremony.
+
+## 1. Resolve authority first
+
+Read `.github/lean-workspace.json` when present before assuming a document hierarchy.
+
+Possible authoritative sources include:
+- Jira Story/Epic,
+- GitHub Issue,
+- local Product/Feature/Enabler brief,
+- local requirements,
+- another team work-item system,
+- small session context for trivial work.
+
+Use external work-item content only when it is actually available. Never claim a Jira/Issue was read when it was not.
+
+Never assume `Jira Epic == Feature Brief`.
+
+## 2. Classify the request
+
+Classify as one of:
+- Product Feature,
+- Engineering Enabler,
+- Small Change / Task,
+- Cross-Cutting Requirement / Standard,
+- ADR-worthy Architecture Decision,
+- Future Roadmap Idea.
+
+Do not invent user stories for technical foundation work.
+
+## 3. Respect brief modes
+
+Product/Feature Brief modes may be:
+
+```text
+not-used
+read-existing
+supplemental-experimental
+authoritative
+suggest-complex
+```
+
+Behavior:
+- `not-used`: do not create the brief.
+- `read-existing`: read when relevant; do not create/update.
+- `supplemental-experimental`: an optional brief may be proposed, clearly labeled non-authoritative.
+- `authoritative`: use/update the configured brief as authority.
+- `suggest-complex`: recommend a brief only when cross-work-item or workflow complexity makes it useful.
+
+Do not create a competing source of truth.
+
+## 4. Discovery cadence
+
+Ask one material question at a time when a real decision is unresolved.
+
+For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
+
+Clarify only what matters, such as:
+- user/engineering outcome,
+- scope and non-scope,
+- important workflows/lifecycle,
+- domain/engineering invariants,
+- destructive/reversible behavior,
+- security/privacy expectations,
+- dependencies,
+- acceptance summary,
+- open decisions.
+
+Record unresolved decisions explicitly rather than inventing them.
+
+## 5. Detailed requirements are proportional
+
+Create/refine detailed requirements only when precision is useful.
+
+When local detailed requirements are permitted and useful, prefer one combined file.
+
+Product Feature:
+
+```text
+requirements.md
+├── User Stories
+├── Domain Requirements
+├── Acceptance / Validation Scenarios
+├── Open Decisions
+├── Traceability
+└── Approval
+```
+
+Engineering Enabler:
+
+```text
+requirements.md
+├── Engineering Requirements
+├── Acceptance Criteria / Validation Scenarios
+├── Open Decisions
+├── Traceability
+└── Approval
+```
+
+If the configured external work item is primary and local detailed requirements are not an approved supplement, propose updates to that external source instead of creating local duplicate authority.
+
+## 6. Stop boundary
+
+Stop before implementation.
+
+Do not create an implementation plan or production code as part of `/define-feature`.
+
+If systematic lower-level coverage is valuable, recommend:
+
+```text
+/refine-requirements <ID-or-key>
+```
+
+## 7. Guided ending
+
+Use a small evidence-backed menu, for example:
+
+```text
+CURRENT STATE
+<what is defined and what remains open>
+
+RECOMMENDED NEXT STEP
+<one action and why>
+
+OPTIONS
+1. Review definition [READ ONLY]
+2. Grill unresolved behavior [READ ONLY]
+3. Refine detailed requirements [READ ONLY initially]
+4. Approve requirements/scope when applicable [REQUIREMENTS GATE]
+5. Start work if already ready [READ ONLY]
+6. Stop [NO ACTION]
+```
+
+Only show relevant options. A file-changing choice authorizes only that bounded action/session.