@mriekki/lean 0.0.0-stage → 0.1.0

package/assets/generated/core/core/process/INTERACTIVE_SESSION_GUIDE.md

@@ -0,0 +1,62 @@
+# Continuous Interactive Sessions
+
+The following modes are continuous after the human explicitly enters them:
+
+```text
+/grill-me
+/grill-with-docs
+/refine-requirements
+/coach
+/learning-review
+/production-readiness
+```
+
+Default cadence:
+
+```text
+question
+→ human answer
+→ critique / teach / reconcile / update as permitted
+→ next material question
+```
+
+## Question presentation
+
+Choose the question shape based on what the interaction is trying to learn or decide.
+
+When a material question has a reasonable bounded answer space and the human is choosing or confirming a decision, prefer a concise choice-first presentation:
+
+- offer a small set of plausible choices, normally 3-6;
+- mark a materially preferred option as `RECOMMENDED` when current evidence or repository guidance justifies it;
+- include `Other / specify` when the choices are not exhaustive;
+- include `Not sure — recommend one` when the human can reasonably delegate the choice;
+- accept a choice label/text or a free-form answer;
+- treat choices as interaction aids, not additional requirements.
+
+Keep questions open-ended when predefined choices would weaken the purpose of the interaction. This includes:
+
+- user-authored problem/outcome/workflow framing where the human's own wording matters;
+- factual values such as a hostname, IP address, path, account, observed error, or environment-specific fact;
+- learning/understanding assessment where the human should explain or reason in their own words;
+- debugging, design, or grilling questions whose purpose is to expose the human's reasoning before options or hints are introduced.
+
+If an open-ended reasoning question stalls, options/hints may be introduced as scaffolding after the initial attempt. Do not manufacture bounded choices merely to make every question look structured.
+
+Do not repeatedly ask `Do you want to continue?`.
+
+Stop when:
+- the human says stop/done/pause,
+- the objective naturally completes,
+- no material questions remain,
+- a genuine approval/scope/action gate appears,
+- the human switches workflows.
+
+Continuous conversation never implies permission for unrelated file, Git, external-system, remote, or production writes.
+
+For modifying sessions such as requirement refinement or production-readiness documentation, one explicit session-level authorization may cover focused updates within the defined scope; do not re-ask after every answer.
+
+Compound action skills may also define their own bounded authorization. In particular, manually invoking `/deliver` after its prerequisites are satisfied authorizes routine branch/stage/commit/push/PR/CI mechanics within the accepted delivery scope. Do not interrupt that compound action with repeated ceremonial permission prompts. `/deliver` still stops for changed evidence, ambiguity/risk, and the explicit merge/finalize decision.
+
+If a tool/channel interruption leaves a compound workflow partially complete, a later invocation should inspect current state and resume from the furthest safe point rather than assuming nothing happened or requiring the same routine authorization again.
+
+`/wait-what` is different. It is a one-turn, read-only communication repair for the immediately preceding explanation. It re-establishes context and clarity, then returns control to the current workflow without silently continuing a pending action or approval gate.

package/assets/generated/core/core/process/PRODUCTION_ENABLEMENT.md

@@ -0,0 +1,59 @@
+# Production Enablement
+
+Production enablement is a guided operational lane separate from ordinary engineering delivery.
+
+A repository may have multiple named deployment environments, for example a non-production staging/portable environment and a true production environment. Each environment owns its own verified target binding, readiness evidence, data/backup state, credentials, and deployment policy.
+
+Use:
+
+```text
+/production-readiness <deployment-enabler-ID> discovery [environment]
+```
+
+early enough to discover real target dependencies.
+
+After deployment engineering is reviewed, delivered, merged, and required post-merge default-branch CI is green, use:
+
+```text
+/production-readiness <deployment-enabler-ID> enable [environment]
+```
+
+The readiness workflow covers:
+
+- named environment role/policy,
+- actual target OS/version/architecture/host discovery,
+- stable environment-to-target binding,
+- deployment identity/access,
+- SSH host-trust and portable-addressing safety when SSH is used,
+- developer-machine and source-hosting/CI read-only checks,
+- optionally authorized read-only remote target checks,
+- runtime/storage/data/backup readiness,
+- network/firewall/security/DNS/TLS/certificate readiness,
+- external blockers,
+- separately authorized bounded provisioning/configuration,
+- approved release/artifact policy,
+- migration/readiness/smoke/rollback evidence.
+
+Address discovery is not host trust. When SSH is used, unknown or changed host identity stops access; readiness must not recover by disabling host-key verification, silently enrolling new trust, scanning/selecting another host, weakening network controls, or redirecting to another environment.
+
+Readiness is environment-specific. Readiness of staging does not prove production is ready, and failure of one environment must never cause fallback to another environment or target.
+
+Once the selected environment is ready, the repeatable deployment entry point is:
+
+```text
+/deploy [environment]
+```
+
+`/deploy` requires explicit environment selection when omitted, verifies the environment/target/artifact evidence, dispatches to the repository-provided platform-appropriate deployment launcher, and presents the applicable write gate immediately before execution.
+
+Production is never an implicit/default deployment target. A production-role deployment requires a distinct `[PRODUCTION WRITE]` authorization for the exact environment, verified target, release/artifact, and current evidence shown by `/deploy`.
+
+A non-production remote deployment still requires bounded `[REMOTE WRITE]` authorization.
+
+Developer workstation OS and deployment target OS are separate dimensions. A repository may provide PowerShell on Windows and shell on macOS/Linux while both invoke equivalent deployment behavior against an approved Ubuntu target. Future Windows/macOS target support requires target-specific implementation/readiness; common SSH transport alone does not establish runtime/deployment parity.
+
+Remote read-only authorization never implies permission for writes.
+
+No requirements approval, Reviewer verdict, PR merge, CI result, environment selection, readiness result, or previous deployment implies production-deployment authorization.
+
+Secret values stay out of tracked documentation and logs. Database restore/destructive recovery remains a separate decision when data safety warrants it.

package/assets/generated/core/core/process/PR_WORKFLOW.md

@@ -0,0 +1,53 @@
+# Pull Request / Merge Workflow
+
+After:
+
+```text
+implementation complete
+→ relevant local checks satisfactory
+→ Reviewer READY
+→ human meaningful local-diff approval
+```
+
+run `/deliver`.
+
+Normal delivery is intentionally streamlined:
+
+```text
+/deliver
+→ establish/recover short-lived work branch if needed
+→ selective stage
+→ verify staged diff
+→ commit
+→ push
+→ create/update PR
+→ PR CI
+→ one MERGE + FINALIZE decision
+→ merge
+→ post-merge default-branch CI when configured/required
+→ safe delivered-branch cleanup
+→ delivery complete
+```
+
+Invoking `/deliver` is the bounded authorization for the routine mechanics through PR creation/update and PR-CI inspection. Do not add separate branch/commit/push/PR/CI permission prompts when the work remains inside the already-reviewed delivery scope.
+
+Key rules:
+- existing repository branch/PR/CI/merge policy outranks Lean defaults,
+- `/start-work` should establish the short-lived work branch when implementation begins; `/deliver` may recover safely if reviewed work is still on the default branch,
+- PR templates are internal scaffolding and do not require a separate validation ceremony,
+- because implementation was already meaningfully accepted locally, a final PR acceptance prompt does not need to be separate from merge when the PR head/diff still exactly matches that accepted scope,
+- green PR CI is necessary evidence but never merge authorization by itself,
+- the explicit `Merge and finalize delivery` choice is both final acceptance of the observed PR and merge authorization,
+- if new commits/material diff changes/conflicts/regressed checks appear, final PR review is required before merge,
+- merge authorization is not production-deployment authorization,
+- for a normal short-lived delivered branch, `Merge and finalize delivery` also authorizes safe local/remote cleanup after required post-merge default-branch CI is observed green,
+- no second branch-deletion prompt is needed for that delivered branch when the cleanup evidence remains exact and safe,
+- unrelated, accumulated, protected/default, release/integration/environment, policy-retained, changed, or ambiguous branches are preserved,
+- squash/rebase merges require merged-PR/head-SHA evidence before any local force deletion is considered safe,
+- do not claim checks passed or branches were deleted unless the remote/local state was actually observed,
+- do not silently modify code after CI failure; inspect/diagnose and return through review as warranted,
+- rerunning `/deliver` after interruption resumes from the furthest observed safe delivery state instead of repeating completed actions or re-asking routine authorization.
+
+If PR CI or post-merge CI remains pending beyond the practical interaction/tool window, preserve state and report that rerunning `/deliver` will resume observation/finalization.
+
+Use `/cleanup-branches` for preview-first maintenance of accumulated, previously retained, unrelated, or otherwise out-of-band branches outside the active `/deliver` flow.

package/assets/generated/core/core/process/SETUP_ACCEPTANCE_CHECKLIST.md

@@ -0,0 +1,72 @@
+# Setup Acceptance Checklist
+
+Do not confuse generated files, installed tools, operational dependencies, editor/agent discovery, AI execution-surface discovery, and human acceptance.
+
+Use this checklist after creating or adopting a Lean workspace and before beginning the first substantive work item.
+
+## Workstation
+
+- [ ] All required tools declared by the workspace environment are installed at acceptable versions.
+- [ ] Required external CLIs are authenticated to the intended account when authentication is part of the workflow.
+- [ ] Required local services or engines are actually running, not merely installed.
+- [ ] Container tooling and Compose work when the selected stack declares containers.
+- [ ] Repository-pinned runtimes are active.
+- [ ] Optional tools are either available or consciously deferred.
+
+## Repository / workspace
+
+- [ ] Git repository and remote state are understood.
+- [ ] `AGENTS.md` is present and identifies the repository source-of-truth hierarchy.
+- [ ] `.github/lean-workspace.json` is present.
+- [ ] expected Lean agents, instructions, and skills are present.
+- [ ] product/work-item source documents needed for the next work item are present.
+- [ ] CI configuration is present when CI is part of the workspace contract.
+- [ ] Core baseline integrity passes when `CORE_BASELINE.json` is present.
+
+## Editor / agentic AI discovery
+
+After opening/reloading the intended editor workspace:
+
+- [ ] the selected AI coding assistant is signed in and usable when required.
+- [ ] `Reviewer` is discoverable.
+- [ ] `Coach` is discoverable when the workspace includes coaching.
+- [ ] expected Lean skills are discoverable, including `/start-work`, `/deliver`, and `/wait-what` when included by the distribution/capability set.
+- [ ] path-specific instructions are present when the workspace declares them.
+- [ ] path-specific instructions are recognized/applied for matching files when the host supports them.
+- [ ] the human controls the routine model/tier; the workspace does not silently pin or upgrade it.
+
+## Copilot CLI + VS Code discovery
+
+When GitHub Copilot CLI is an intended execution surface:
+
+- [ ] `copilot` starts successfully from the repository checkout without requiring `--allow-all` or `--yolo`.
+- [ ] `/user` reports the intended GitHub identity.
+- [ ] `/skills list` shows the expected repository-local Lean skills from `.github/skills/`.
+- [ ] the expected custom agents are selectable, including `Reviewer` and `Coach` when included by the distribution/capability set.
+- [ ] `/ide` is connected to the intended trusted VS Code workspace when editor/CLI integration is desired.
+- [ ] CLI-proposed edits can be reviewed through the configured approval flow; when VS Code diff integration is enabled, proposed file edits appear as editor diffs rather than being silently applied.
+- [ ] the `Reviewer` agent exposes only the intended `read`, `search`, and `execute` tool classes and remains non-mutating in practice.
+- [ ] Lean human gates behave the same whether the interaction starts in Copilot Chat or Copilot CLI.
+
+Copilot CLI is an additional supported execution surface, not a separate Lean workflow. Normal Lean use must not require blanket tool approval. Autopilot/delegated execution is outside the default Lean delivery lifecycle unless a repository explicitly defines and accepts that behavior.
+
+## Application stage
+
+- [ ] application scaffold is either intentionally absent for the current stage or present as expected.
+- [ ] declared restore/build/test commands succeed for the artifacts that currently exist.
+- [ ] deferred scaffold-dependent checks are clearly identified rather than reported as passed.
+
+## Smoke test
+
+- [ ] static workspace diagnostics pass when provided.
+- [ ] normal AI chat can summarize the approved product/work-item intent without inventing scope.
+- [ ] a read-only challenge/review capability can be invoked without editing files.
+- [ ] `/wait-what` can re-explain a prior response without changing repository state when the workspace includes it.
+- [ ] the Reviewer remains review-focused when selected.
+- [ ] when Copilot CLI is enabled, invoking a Lean skill there preserves the same scope, source-of-truth, and Human-in-the-Loop rules as the editor chat surface.
+
+## Human acceptance
+
+Setup is accepted only when the human confirms this checkout is usable for the next intended work item.
+
+A successful generator, installer, static file check, tool-version probe, CLI connection, or agent/skill discovery check alone is not human acceptance.

package/assets/generated/core/core/process/WORK_ITEM_MODEL.md

@@ -0,0 +1,56 @@
+# Work-Item Model
+
+Lean reasons from the repository's authoritative work-item system rather than requiring one universal artifact hierarchy.
+
+Possible sources include:
+
+```text
+Product Brief
+Jira Epic
+Feature Brief
+Engineering Enabler
+Jira Story
+GitHub Issue
+local requirements
+ADR
+small session context
+```
+
+Authority labels:
+
+```text
+PRIMARY
+SUPPLEMENTAL
+REFERENCE
+NOT USED
+```
+
+Role labels:
+
+```text
+PRODUCT CONTEXT
+FEATURE CONTEXT
+WORK GROUPING
+IMPLEMENTABLE REQUIREMENT
+TECHNICAL DECISION
+```
+
+Product/Feature Brief modes may be:
+
+```text
+not-used
+read-existing
+supplemental-experimental
+authoritative
+suggest-complex
+```
+
+Never assume:
+
+```text
+Jira Epic == Feature Brief
+```
+
+Possible relationships vary by team: an Epic may be a feature, initiative, technical workstream, or delivery container; one Epic may have no Feature Brief, one brief, or several.
+
+Existing team conventions outrank Lean defaults. Do not create a competing local source of truth merely because Lean has a template.

package/assets/generated/core/core/skills/cleanup-branches/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: cleanup-branches
+description: Preview-first cleanup of completed short-lived Git branches locally and on the configured remote, using merged-PR evidence and explicit destructive authorization.
+argument-hint: "[optional branch name/prefix]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Cleanup Branches
+
+`/cleanup-branches` removes completed short-lived branches without treating branch-name patterns or Git ancestry alone as proof that deletion is safe.
+
+Existing repository conventions outrank Lean defaults. Preserve configured default/protected branches, release/integration branches, and any branch the repository intentionally keeps long-lived.
+
+Invocation begins read-only.
+
+## 1. Purpose
+
+Use this skill for branch housekeeping outside the normal `/deliver` path, especially when historical feature/fix/chore branches have accumulated.
+
+Normal delivery should clean its own short-lived branch after merge and successful required post-merge default-branch CI. This skill is for backlog cleanup, interrupted delivery, or explicit inspection.
+
+## 2. Read-only discovery
+
+Inspect current repository state and resolve the actual default branch and remotes. Typical evidence includes:
+
+```text
+git status --short --branch
+git branch --show-current
+git branch -vv
+git branch -r
+git remote -v
+git fetch --all --prune --dry-run
+```
+
+When GitHub CLI is available, inspect repository/PR evidence rather than inferring from names alone:
+
+```text
+gh repo view
+gh pr list --state merged
+gh pr list --state open
+```
+
+For each candidate branch, record when observable:
+- local head SHA,
+- remote head SHA,
+- merged PR number/state,
+- PR head ref and head SHA,
+- whether an open PR still references the branch,
+- whether the branch is default/protected/long-lived by repository policy,
+- whether local commits exist beyond the remote/merged PR head.
+
+Do not modify anything during discovery.
+
+## 3. Classification
+
+Classify every observed non-default branch into one of these buckets.
+
+### SAFE TO DELETE
+
+A branch may be classified safe only when evidence shows it is completed and unchanged since completion. Strong evidence is:
+- a merged PR exists for that exact head branch,
+- the observed branch head still matches the PR head SHA (or the branch is already absent remotely),
+- no open PR references the branch,
+- no local-only commits were added after the approved/merged head,
+- it is not the default, protected, release, integration, environment, or intentionally long-lived branch.
+
+A branch fully merged by ancestry may also be safe when repository policy and commit history make that unambiguous.
+
+### REVIEW REQUIRED
+
+Use this when any material evidence is missing or ambiguous, including:
+- no merged PR and ancestry is not conclusive,
+- remote/local heads differ,
+- branch moved after its PR merged,
+- local-only commits exist,
+- an open PR references it,
+- branch purpose/lifecycle is unclear.
+
+### PRESERVE
+
+Always preserve by default:
+- the configured default branch,
+- protected branches,
+- active/open-PR branches,
+- release/integration/environment branches unless repository policy explicitly says otherwise,
+- any branch the human marks to keep.
+
+Never classify by prefix alone.
+
+## 4. Preview
+
+Present a concrete preview before deletion:
+
+```text
+BRANCH CLEANUP PREVIEW
+
+Default branch: <name>
+Working tree: <clean / details>
+
+SAFE TO DELETE
+  <branch>  local=<sha|absent>  remote=<sha|absent>  evidence=<merged PR / ancestry>
+
+REVIEW REQUIRED
+  <branch>  <reason>
+
+PRESERVE
+  <branch>  <reason>
+
+NO CHANGES HAVE BEEN MADE
+```
+
+If no branch is safely deletable, stop after the preview.
+
+## 5. Cleanup gate
+
+For a non-empty verified-safe set, present one bounded destructive gate:
+
+```text
+BRANCH CLEANUP READY
+
+1. Delete verified-safe local + remote branches [GIT + GITHUB WRITE] — recommended
+2. Delete verified-safe remote branches only [GITHUB WRITE]
+3. Delete verified-safe local branches only [GIT WRITE]
+4. Stop [NO ACTION]
+```
+
+Only the selected option authorizes the corresponding deletions. Do not include REVIEW REQUIRED branches in the bounded action.
+
+## 6. Revalidate before deletion
+
+Immediately before any deletion:
+- fetch/prune remote state,
+- re-resolve the default branch,
+- confirm every candidate branch head still matches the previewed SHA/evidence,
+- confirm no new/open PR now references it,
+- confirm the working tree is safe to switch branches,
+- confirm the current branch is not about to be deleted.
+
+If anything materially changed, stop and return to preview. Do not silently widen the approved set.
+
+## 7. Apply cleanup
+
+Switch to the default branch before deleting the current feature branch and update it with the repository-approved non-rewriting method, normally `git pull --ff-only`.
+
+For each approved remote branch, use the repository's normal remote-deletion mechanism, for example:
+
+```text
+git push origin --delete <branch>
+```
+
+If the remote branch is already absent, treat that as already-clean rather than an error.
+
+For each approved local branch:
+- prefer `git branch -d <branch>` when Git recognizes it as merged,
+- squash/rebase merges may cause `-d` to reject even though the PR is merged,
+- only when merged-PR evidence is exact and the local head has no commits beyond the approved PR head may `git branch -D <branch>` be used under the explicit cleanup authorization.
+
+Never use `-D` merely to bypass uncertainty.
+
+After deletion:
+
+```text
+git fetch origin --prune
+```
+
+## 8. Completion report
+
+Report exactly what happened:
+
+```text
+BRANCH CLEANUP COMPLETE
+
+Deleted remote:
+  ...
+Deleted local:
+  ...
+Already absent:
+  ...
+Preserved / review required:
+  ...
+Default branch: <name>
+Working tree: <state>
+```
+
+Do not claim a branch was deleted unless the resulting local/remote state was observed.
+
+## 9. Relationship to /deliver
+
+`/deliver` owns branch finalization for the work it is actively delivering. `/cleanup-branches` is the standalone maintenance path for accumulated or previously retained branches.

package/assets/generated/core/core/skills/coach/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: coach
+description: "Optional guided engineering learning before, during, or after work using actual repository context: concepts, code walkthroughs, debugging, coding/DSA, SQL, design, system design, interview drills, diagrams, and resources."
+argument-hint: "[topic/work-item] [light|focused|deep|broad] [L1-L6]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Coach
+
+Coaching is optional and never blocks planning, implementation, review, delivery, merge, or work-item completion.
+
+## 1. Context and boundaries
+
+- Read only minimum relevant code/work-item/learning context.
+- Do not edit production code or implement fixes while in Coach mode.
+- Do not invoke subagents.
+- Do not silently broaden scope.
+- Do not pin/request/switch to a premium model automatically.
+- Distinguish actual implementation/understanding from AI-generated work and study.
+
+## 2. Depth
+
+```text
+Light    — quick explanation/check
+Focused  — one topic, moderate depth
+Deep     — trace/apply/debug/defend one topic
+Broad    — survey related areas and find gaps
+Coach recommends
+```
+
+Do not force the human to choose a depth when their prompt already makes intent clear.
+
+## 3. Learning levels
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+These measure understanding, not seniority. Do not inflate mastery.
+
+## 4. Modes
+
+Support:
+1. learn a concept,
+2. walk through real project code,
+3. debugging exercise/review,
+4. coding/DSA drill,
+5. SQL/database drill,
+6. design defense,
+7. system-design exercise,
+8. interview drill,
+9. learning-gap assessment,
+10. recommended learning path,
+11. docs/tutorial/video resources,
+12. return to engineering workflow.
+
+Use installed learning assets when present; do not assume they exist.
+
+For a structured walkthrough of implementation changes across a Git/PR/commit change set, prefer `/code-walkthrough`. Coach remains available for ad-hoc explanation of a file, symbol, concept, design choice, or selected code block.
+
+## 5. Continuous adaptive cadence
+
+```text
+question
+→ human answer
+→ critique/teach
+→ next material question
+```
+
+Do not repeatedly ask whether to continue.
+
+Adapt difficulty:
+- weak answer: teach missing mental model, simplify, ask for own-words explanation;
+- solid: apply/edge case;
+- strong: tradeoff/debug/design;
+- very strong: interviewer pressure or changed scale/assumptions.
+
+## 6. Mode guidance
+
+Concept:
+
+```text
+definition → repository/example → diagram if useful → check understanding → application
+```
+
+Debugging:
+
+```text
+symptom → hypotheses → distinguishing evidence → root cause → fix concept → prevention
+```
+
+Do not implement the fix during Coach mode.
+
+Coding/DSA:
+
+```text
+problem → clarifying questions → approach → complexity → code → edge cases/tests → hints → alternatives → feedback
+```
+
+Do not reveal the solution immediately.
+
+SQL/database:
+
+```text
+schema/query problem → human writes SQL → correctness → edge cases → indexing/query plan → ORM translation when useful
+```
+
+System design: start from the actual repository, ask one question at a time, and make the human drive the design.
+
+Interview drill: critique correctness, depth, credibility, structure, concision, overstatement, and missed follow-ups.
+
+## 7. Diagrams/resources
+
+Mermaid diagrams in chat may be used for architecture, request/sequence/state/data/CI/deployment/concurrency understanding. Diagrams are ephemeral unless explicitly requested as durable artifacts.
+
+External resources are optional. Prefer official docs/vendor tutorials, then a small number of current high-quality resources. Show 1–3 at a time, not a link dump. Never make external resources an engineering prerequisite.
+
+## 8. Optional learning progress
+
+Only update a learning-progress tracker when the human explicitly chooses to do so. Skipping it has no engineering impact.
+
+## 9. Credibility
+
+For interview/portfolio discussion distinguish:
+- actually implemented/used,
+- AI-generated but reviewed/understood,
+- studied/practiced,
+- not yet understood.
+
+Never manufacture professional experience.