@mriekki/lean 0.0.0-stage → 0.1.1

package/assets/generated/core/core/skills/learning-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: learning-review
+description: Optional structured post-build understanding check using actual implementation, tests, decisions, and work-item context.
+argument-hint: "<work-item ID, external key, or topic>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Learning Review
+
+Default to post-build learning from real evidence.
+
+`/learning-review` is primarily assessment. For an instructional changed-file walkthrough first, use `/code-walkthrough`.
+
+## 1. Context
+
+Read only relevant:
+- work-item/requirements context,
+- changed code/diff,
+- tests and observed results,
+- important decisions/architecture.
+
+Identify 3–6 concepts the developer should understand.
+
+## 2. Continuous cadence
+
+Ask one question at a time:
+
+```text
+question
+→ human answer
+→ critique accuracy/depth/credibility
+→ teach missing concept when useful
+→ next question
+```
+
+Do not ask whether to continue after every answer.
+
+Assess:
+- architecture/request/data flow,
+- technical decisions and alternatives,
+- debugging/testing,
+- failure modes/tradeoffs,
+- interview explanation.
+
+Do not edit production code while in learning-review mode.
+
+## 3. Relationship to code walkthrough
+
+Use `/code-walkthrough` when the primary need is:
+
+```text
+AI explains the actual implementation
+→ developer explores changed files
+→ developer builds a mental model
+```
+
+Use `/learning-review` when the primary need is:
+
+```text
+AI asks
+→ developer explains
+→ AI critiques
+→ gaps become visible
+```
+
+A walkthrough may naturally hand off to a learning review, but neither is required for engineering completion or delivery.
+
+## 4. Credibility
+
+Explicitly distinguish:
+- what the developer actually implemented/used,
+- what AI generated but the developer reviewed/understands,
+- what was studied/practiced,
+- what remains a gap.
+
+Do not manufacture professional experience.
+
+## 5. Completion
+
+Stop when the human stops/switches workflow, the planned check is complete, or no material learning gaps remain for this session.
+
+Summarize:
+- understood well,
+- needs reinforcement,
+- optional next target.
+
+Then offer a small menu such as continue, optional learning notes/progress, return to engineering workflow, or stop.
+
+`/learning-review` is optional and never blocks engineering completion/delivery.

package/assets/generated/core/core/skills/next-step/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: next-step
+description: Read-only orientation over work-item, Git, review, PR, PR CI, merge, post-merge default-branch CI, deployment readiness, and deployment handoff state.
+argument-hint: "[optional work-item ID or external key]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Next Step
+
+Purpose: answer `Where am I, and what is the sensible next action?`
+
+Invocation is read-only.
+
+## 1. Resolve minimum context
+
+Read `.github/lean-workspace.json` when present and use the optional work-item key or infer from current branch/session context.
+
+Inspect only what is needed.
+
+Local Git examples:
+
+```text
+git branch --show-current
+git status --short --branch
+git diff --stat
+git diff --cached --stat
+git log -1 --oneline
+```
+
+When GitHub CLI is available/authenticated:
+
+```text
+gh pr status
+gh pr view
+gh pr checks
+```
+
+When post-merge CI matters, inspect the configured default branch/workflow rather than assuming it is named `main`.
+
+Never invent Jira/Issue/PR/CI/review/merge/readiness/deployment state.
+
+## 2. Useful states
+
+Examples:
+
+```text
+IMPLEMENTING
+LOCAL_REVIEW_PENDING
+REVIEW_CHANGES_REQUIRED
+REVIEW_READY
+HUMAN_LOCAL_ACCEPTANCE_PENDING
+DELIVERY_READY
+PUSHED_NO_PR
+PR_CI_PENDING
+PR_CI_FAILED
+PR_CI_GREEN
+MERGE_READY
+MERGED_DEFAULT_BRANCH_CI_PENDING
+MERGED_DEFAULT_BRANCH_CI_FAILED
+DELIVERY_COMPLETE
+ENVIRONMENT_READINESS_PENDING
+ENVIRONMENT_READY
+```
+
+Use only states supported by observed evidence.
+
+Do not add a separate final-PR-acceptance state when the PR still exactly matches the already accepted local implementation. In that normal case, `/deliver` combines final acceptance and merge into the single `MERGE_READY` decision. If PR evidence changed materially, describe the required final PR review explicitly before returning to `MERGE_READY`.
+
+Do not add learning-only states such as `CODE_WALKTHROUGH_PENDING`. Optional coaching does not change engineering delivery state.
+
+## 3. Output
+
+```text
+CURRENT STATE
+<evidence-backed summary>
+
+RECOMMENDED NEXT STEP
+<one action and why>
+
+OPTIONS
+1. ... [READ ONLY]
+2. ... [MODIFIES FILES]
+3. ... [GIT + GITHUB WRITE]
+4. Stop [NO ACTION]
+```
+
+Only show relevant options. `/next-step` orients; it does not become another workflow database.
+
+## 4. Optional learning choices
+
+When implementation is stable enough to learn from and the human appears interested in understanding the code, `/next-step` may offer learning choices without making them gates:
+
+```text
+/code-walkthrough <scope> — guided changed-file explanation [READ ONLY]
+/learning-review <scope> — understanding assessment [READ ONLY]
+/coach <topic> — focused concept coaching [READ ONLY]
+```
+
+Prefer `/code-walkthrough` when the user wants to understand what changed across an implementation. Do not recommend it as mandatory before `/deliver`.
+
+## 5. Delivery handoff
+
+When all are ready:
+
+```text
+implementation complete
+local verification satisfactory
+Reviewer READY
+human meaningful-diff approval complete
+```
+
+recommend `/deliver` rather than separate branch/commit/push/create-PR confirmations.
+
+`/deliver` owns the compound delivery action:
+
+```text
+short-lived branch setup/recovery when needed
+→ selective stage
+→ verify staged diff
+→ commit
+→ push
+→ create/update PR
+→ PR CI
+→ one Merge and finalize delivery decision
+→ merge
+→ post-merge default-branch CI
+→ safe delivered-branch finalization
+```
+
+Because `/deliver` is manually invoked, do not insert another permission menu merely to begin those routine mechanics. It will stop itself for changed evidence, ambiguity/risk, CI failure requiring code changes, or the merge/finalize decision.
+
+If PR CI failed, recommend inspect/diagnose/targeted fix. Do not silently change code.
+
+If PR CI is green and evidence still matches the accepted implementation, return to `/deliver` for the single merge/finalize gate.
+
+Never merge from `/next-step` merely because CI is green.
+
+After merge:
+- if required default-branch CI is pending, return to `/deliver` to resume observation/finalization;
+- if failed, inspect/diagnose;
+- if green and branch finalization is safe/complete, report delivery complete.
+
+## 6. Deployment handoff
+
+For a release/deployment engineering enabler after engineering delivery is complete, recommend:
+
+```text
+/production-readiness <deployment-enabler-ID> enable [environment]
+```
+
+when the selected environment still needs operational discovery/enablement.
+
+When evidence shows a configured named environment is ready for deployment, recommend:
+
+```text
+/deploy [environment]
+```
+
+rather than treating `/production-readiness` as the normal application-deployment executor.
+
+Do not infer readiness of one environment from another. Production is never an implicit/default environment, and `/next-step` never authorizes a remote or production deployment merely by recommending `/deploy`.
+
+## 7. Keep it lean
+
+Do not auto-run Reviewer, auto-run learning activities, auto-merge, auto-deploy, pin/select a model, or maintain duplicate workflow state outside Git/GitHub and the configured work-item/readiness authority.

package/assets/generated/core/core/skills/production-readiness/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: production-readiness
+description: Guided continuous deployment-environment discovery and enablement, including target OS/access, SSH trust, security/network/TLS, read-only checks, bounded provisioning, and readiness handoff to /deploy.
+argument-hint: "<deployment-enabler-ID> [discovery|enable|resume] [environment]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Production Readiness
+
+This is a guided operational workflow for preparing named deployment environments. It is not an autonomous production administrator and it is not the normal deployment executor.
+
+Modes:
+
+```text
+discovery
+enable
+resume
+```
+
+## 1. Resolve minimum context
+
+Read `.github/lean-workspace.json` when present plus only the relevant deployment enabler requirements/decisions/readiness record, release/deployment guidance, environment/target configuration contract, and deployment code/workflows.
+
+Do not assume:
+
+- there is only one deployment environment,
+- an environment named `production` exists,
+- a particular work-item path,
+- target OS/runtime/hostname/IP,
+- SSH alias or discovery mechanism,
+- certificate model or hosting environment.
+
+Use the approved project context and checkout-local non-secret target configuration when the project defines it.
+
+## 2. Mode boundaries
+
+### discovery
+
+May begin early after the application's foundation/walking skeleton is proven.
+
+Purpose:
+
+- identify intended named deployment environments and their roles,
+- discover each selected environment's real target and expected target OS,
+- identify access/security/network/TLS/certificate dependencies,
+- establish the environment-to-target readiness contract without embedding household- or checkout-specific secrets in reusable source,
+- record non-secret facts,
+- surface blockers early.
+
+Discovery does not authorize remote writes or deployment.
+
+### enable
+
+Require evidence that deployment engineering completed the normal delivery path, such as:
+
+```text
+requirements approved under the configured authority model
+implementation complete
+local verification satisfactory
+Reviewer READY
+human meaningful-diff approval
+PR CI green
+merged to default branch
+required post-merge default-branch CI green
+```
+
+If evidence is missing, stop enablement and route back through the failed gate or `/deliver`.
+
+Enablement prepares the selected environment so `/deploy` can safely use it. It does not itself authorize an application deployment.
+
+### resume
+
+Continue from the project's existing environment-specific readiness record when one exists.
+
+## 3. Select the environment before environment-specific readiness
+
+When more than one configured deployment environment exists, select the environment being discovered or enabled before asking environment-specific questions.
+
+Treat these as separate concepts:
+
+```text
+named environment
+→ environment role/policy
+→ configured target binding
+→ stable logical/SSH identity
+→ current address discovery
+→ independently verified host identity
+```
+
+A non-production portable/staging target and a true production target may use the same deployment implementation while retaining independent target identities, data, credentials, readiness evidence, and deployment policy.
+
+Never let one environment silently fall back to another environment or target because discovery/access/readiness fails.
+
+## 4. Session authorization
+
+Invocation begins read-only.
+
+Present a state/menu such as:
+
+```text
+CURRENT STATE
+<selected environment + readiness summary>
+
+RECOMMENDED NEXT STEP
+<one action and why>
+
+OPTIONS
+1. Begin/resume guided readiness [MODIFIES DOCS]
+2. Review readiness evidence [READ ONLY]
+3. Run available read-only checks only [READ ONLY]
+4. Stop [NO ACTION]
+```
+
+If option 1 is selected, focused updates to the existing deployment-readiness/decision record are authorized for the active session. If the repository has no permitted readiness document, keep session notes/proposed updates rather than inventing a competing authority.
+
+Never record secret values.
+
+## 5. Continuous cadence
+
+Once a modifying readiness session is authorized:
+
+```text
+ask one material question
+→ human answers
+→ record the non-secret resolved fact
+→ explain impact/blocker
+→ ask the next material question
+```
+
+Use choice-first presentation from `INTERACTIVE_SESSION_GUIDE.md` for bounded operational decisions such as environment role, exposure mode, approved runtime model, TLS termination pattern, or another small set of credible policy/configuration alternatives.
+
+Ask environment-specific facts such as OS/version, hostname, IP address, target label, account, port, filesystem path, certificate identity, or observed system state as free-form/confirmation questions; do not invent plausible-looking operational values merely to offer choices.
+
+Do not ask after every answer whether to continue/update.
+
+Pause only for:
+
+- human stop,
+- natural readiness/action gate,
+- architecture/security conflict requiring a separate decision,
+- remote/GitHub/security write requiring explicit authorization.
+
+## 6. Resolve the actual target OS and runtime per environment
+
+Do not choose commands before the selected environment and real target are confirmed.
+
+For the selected environment discover/verify, one at a time as relevant:
+
+- environment name and role (`production` or approved non-production role),
+- stable target label / binding,
+- expected target OS and version,
+- actual target OS and version,
+- CPU architecture,
+- hostname/current address/discovery model,
+- LAN/private/public exposure,
+- deployment/SSH account,
+- SSH port/authentication,
+- service-account model,
+- approved runtime (Docker/Compose or other),
+- persistent-data path,
+- backup path,
+- storage capacity.
+
+If the actual target conflicts materially with the environment's approved target OS/runtime/architecture, stop and resolve the design rather than silently adapting.
+
+Readiness is environment-specific. Do not treat successful readiness of one target as evidence that another target is ready.
+
+## 7. SSH target identity and portable discovery
+
+When SSH is the approved deployment transport, keep address discovery separate from trust.
+
+Verify as applicable:
+
+- the selected environment resolves through its approved stable logical target/SSH alias,
+- the expected SSH host identity was independently verified before trust enrollment,
+- an unknown or changed host key stops access,
+- changing DHCP/mDNS/current address does not require weakening host-key verification,
+- no fallback scans the LAN, silently chooses another host, disables strict host-key checks, or enrolls new trust merely because discovery failed,
+- repository configuration does not contain private keys, passphrases, copied trust databases, or secret credentials.
+
+If the project uses a portable trusted-LAN target, a stable discovery name such as mDNS may be appropriate, but discovery technology is project/profile-specific. The reusable invariant is stable logical target identity plus independently verified host identity.
+
+When changing SSH authentication policy, verify intended key access before disabling alternative authentication and preserve an approved recovery path while making the bounded change.
+
+## 8. Network, security, DNS, TLS
+
+Ask/verify as relevant:
+
+- inbound ports,
+- outbound registry/source-hosting/DNS/NTP dependencies,
+- firewall/security approvals,
+- DNS/server name,
+- HTTP vs HTTPS,
+- TLS/certificate source,
+- termination point,
+- trust chain,
+- renewal owner/process.
+
+Certificates may legitimately be N/A for an approved private HTTP design. Public exposure/HTTPS changes that contradict approved design are material security/architecture decisions.
+
+Record external blockers and continue unrelated discovery. Never propose bypassing organizational controls.
+
+## 9. Developer-system read-only checks
+
+Offer a bounded read-only check before changing anything.
+
+Use repository-provided helpers when present; otherwise show platform-appropriate commands for inspection. Common checks include Git, source-hosting CLI/auth, build tooling, approved container runtime, SSH, HTTP tooling, and TLS inspection capability.
+
+Determine the developer workstation OS independently of the deployment target OS. A repository may use different local launchers (for example PowerShell on Windows and shell on macOS/Linux) that invoke the same target-side deployment contract.
+
+State what was actually checked and what was not.
+
+## 10. Source-hosting / CI read-only checks
+
+Where GitHub is used, inspect only non-secret metadata needed for readiness, such as:
+
+- repository/default branch,
+- workflows/recent required CI,
+- environment names,
+- variable names,
+- secret names (never values),
+- release metadata.
+
+For other source/CI systems, use their repository-approved equivalent.
+
+## 11. Remote selected-environment check
+
+After the selected environment's target/user/port are known, explicitly ask:
+
+```text
+Run read-only check against <environment>? [REMOTE READ ONLY]
+```
+
+Only after authorization may remote inspection occur.
+
+Allowed examples:
+
+- host identity/fingerprint evidence when the approved process permits it,
+- OS/version and architecture,
+- current identity/groups,
+- approved runtime version/state,
+- disk/memory,
+- listening ports,
+- basic system state,
+- existence/ownership of approved data/backup paths.
+
+Read-only authorization does not permit:
+
+- package installation,
+- user/group or directory creation,
+- firewall changes,
+- registry login,
+- image pulls,
+- migrations,
+- deployment,
+- data changes.
+
+If automated remote access is prohibited, provide exact read-only commands for an authorized human/admin to run and return non-secret output.
+
+## 12. TLS/certificate check
+
+Only when TLS is part of the selected environment's approved design.
+
+A read-only endpoint certificate check may inspect:
+
+- subject/SAN,
+- issuer,
+- validity dates,
+- trust/policy result,
+- expected server name/port.
+
+Never inspect/copy private keys.
+
+## 13. Bounded provisioning/configuration writes
+
+After discovery, present missing prerequisites as small explicit write actions, for example:
+
+```text
+Create service/deployment account [REMOTE WRITE]
+Install/upgrade runtime [REMOTE WRITE]
+Create data/backup directories [REMOTE WRITE]
+Configure SSH access [SECURITY / REMOTE WRITE]
+Configure firewall [SECURITY / REMOTE WRITE]
+Configure registry credential [SECRET / REMOTE WRITE]
+Create source-hosting environment [SOURCE-HOSTING WRITE]
+Set secret/variable [SOURCE-HOSTING WRITE]
+Install/configure certificate [SECURITY / REMOTE WRITE]
+```
+
+Do not execute a write merely because it is needed. Each bounded write requires explicit human authorization.
+
+Changing an environment's target binding or enrolling a replacement host identity is readiness/configuration work and requires explicit authorization. Do not perform it implicitly from `/deploy`.
+
+Keep secret values out of tracked files and logs.
+
+## 14. Environment deployment readiness
+
+Before declaring the selected environment ready for `/deploy`, verify the evidence required by its approved role/policy.
+
+Common evidence includes:
+
+- selected environment and independently verified target binding,
+- supported developer workstation launcher,
+- expected target OS matches actual target OS,
+- approved release/artifact policy,
+- immutable artifact/image digest when applicable,
+- artifact/registry access,
+- independent environment data/backup paths,
+- migration path,
+- deployment lock behavior,
+- readiness checks,
+- smoke tests,
+- application rollback,
+- explicit database-restore/recovery boundary,
+- unresolved security blockers = none.
+
+A non-production environment may use a less restrictive release policy only when the project's approved requirements say so. Do not infer that staging may deploy arbitrary mutable artifacts.
+
+## 15. Production readiness handoff
+
+For a production-role environment, when readiness prerequisites are satisfied present a summary such as:
+
+```text
+PRODUCTION ENVIRONMENT READY FOR DEPLOYMENT WORKFLOW
+
+Environment: <name>
+Target: <verified target>
+OS/architecture: <verified>
+Release/artifact policy: <verified>
+Exposure/TLS: <verified mode>
+Security blockers: NONE
+Backup: READY
+Migration: READY
+Readiness/Smoke: READY
+Rollback: READY
+
+NEXT
+/deploy <environment>
+```
+
+This is readiness evidence, not deployment authorization.
+
+The actual production write gate belongs to `/deploy`, where the exact environment, verified target, release/artifact, and current evidence are shown together immediately before execution.
+
+Requirements approval, code review, PR merge, CI success, environment readiness, or a previous deployment never imply the next deployment authorization.
+
+## 16. Post-readiness
+
+Once an environment is ready:
+
+- record non-secret readiness evidence in the repository-approved place,
+- keep environment readiness independent from other environments,
+- use `/deploy [environment]` for the repeatable deployment workflow,
+- return to readiness when the target binding, expected OS/runtime, security posture, credentials, or other material prerequisites change.
+
+Deployment outcome evidence may update the repository's operational record after an authorized `/deploy`, but application rollback and database restore/destructive recovery remain separate decisions when data safety warrants it.