@mriekki/lean 0.0.0-stage → 0.1.1

package/assets/generated/core/core/skills/pull-latest/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: pull-latest
+description: Guided fast-forward-only Git update so a developer can safely get the latest remote branch state without remembering Git syntax.
+argument-hint: "[optional branch name]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Pull Latest
+
+`/pull-latest` is a small convenience wrapper for routine Git updates. It removes the need to remember `fetch`, `switch`, `pull --ff-only`, or upstream-status syntax while preserving normal repository safety.
+
+Existing repository conventions outrank Lean defaults.
+
+Invocation starts read-only.
+
+## 1. Inspect current state
+
+Inspect:
+
+```text
+git status --short --branch
+git branch --show-current
+git remote -v
+git branch -vv
+```
+
+Resolve:
+- current branch,
+- configured upstream for the current branch,
+- configured default branch when observable,
+- requested branch when one was supplied,
+- whether the working tree is clean enough to switch/update safely.
+
+Do not fetch, switch branches, pull, stash, merge, rebase, reset, clean, or delete anything during this first inspection.
+
+## 2. Safety stop conditions
+
+Stop before update when:
+- tracked/staged/untracked work could be overwritten or makes branch switching unsafe,
+- a merge/rebase/cherry-pick is in progress,
+- the requested branch or remote is ambiguous,
+- no usable upstream exists for the branch being updated,
+- authentication/remote access fails,
+- repository policy requires a different update method.
+
+Never auto-stash user work.
+Never use `reset --hard`, force-push, merge, or rebase as part of `/pull-latest`.
+
+## 3. Choose the update target
+
+If the human supplied a branch, use that branch as the requested target when it can be resolved safely.
+
+If no branch was supplied and the current branch is the default branch, present:
+
+```text
+PULL LATEST READY
+
+Current branch: <branch>
+Working tree: CLEAN
+
+1. Refresh remote state and pull latest <branch> [GIT WRITE] — recommended
+2. Stop [NO ACTION]
+```
+
+If no branch was supplied and the current branch is a non-default branch, present:
+
+```text
+PULL LATEST READY
+
+Current branch: <branch>
+Default branch: <default>
+Working tree: CLEAN
+
+1. Refresh and pull the current branch [GIT WRITE]
+2. Switch to the default branch and pull latest [GIT WRITE] — recommended for returning to baseline
+3. Stop [NO ACTION]
+```
+
+Only the selected option authorizes fetch/switch/pull mechanics for the selected branch.
+
+## 4. Refresh remote state
+
+For the selected remote/branch, run the repository-normal equivalent of:
+
+```text
+git fetch <remote> --prune
+```
+
+Then re-evaluate local branch, upstream, and remote head before pulling.
+
+Classify the branch as:
+- `CURRENT` — local and upstream point to the same commit,
+- `BEHIND` — local can be fast-forwarded to upstream,
+- `AHEAD` — local has commits not on upstream,
+- `DIVERGED` — both local and upstream contain unique commits,
+- `UNKNOWN` — state cannot be established safely.
+
+## 5. Apply only a fast-forward-safe update
+
+### CURRENT
+
+Do not create a no-op commit or other change. Report that the branch is already current.
+
+### BEHIND
+
+Use the repository-normal equivalent of:
+
+```text
+git pull --ff-only
+```
+
+If the user selected the default branch while currently on another branch, first switch to the existing local default branch only after confirming the working tree is safe, then perform the same fast-forward-only update.
+
+### AHEAD
+
+Do not pull, merge, rebase, reset, or push. Report `LOCAL AHEAD` and the observed commit counts when available.
+
+### DIVERGED
+
+Stop. Report `DIVERGED` and recommend explicit inspection. `/pull-latest` must not choose merge, rebase, reset, or force-push on the user's behalf.
+
+### UNKNOWN
+
+Stop and report the missing/ambiguous evidence.
+
+## 6. Verification
+
+After a successful update, inspect:
+
+```text
+git status --short --branch
+git log -1 --oneline
+```
+
+When useful, also confirm the local branch head matches its upstream.
+
+## 7. Completion report
+
+Use:
+
+```text
+PULL LATEST COMPLETE
+
+Branch: <branch>
+Remote/upstream: <remote>/<branch>
+Result: UPDATED | ALREADY CURRENT | LOCAL AHEAD | DIVERGED | BLOCKED
+Head: <sha>
+Working tree: <state>
+```
+
+Do not claim an update succeeded unless the resulting branch/upstream state was observed.
+
+## 8. Boundaries
+
+`/pull-latest` never:
+- modifies application/source files directly,
+- stashes work automatically,
+- creates or deletes branches,
+- commits or pushes,
+- merges or rebases,
+- resets or cleans the worktree,
+- resolves conflicts automatically,
+- changes remotes/upstreams unless a separate explicit action authorizes that configuration change.
+
+It is intentionally just the safe convenience path for `refresh remote state → fast-forward if possible → verify`.

package/assets/generated/core/core/skills/refine-requirements/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: refine-requirements
+description: Assess and continuously refine requirement coverage for the configured authoritative work-item source without forcing a local requirements hierarchy.
+argument-hint: "<work-item ID, external key, or topic>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Refine Requirements
+
+Purpose: make requirements implementation-ready when the work benefits from detailed precision.
+
+This skill is proportional; it is not mandatory for every change.
+
+## 1. Resolve authority and context
+
+Read `.github/lean-workspace.json` when present.
+
+Determine:
+- authoritative work-item source,
+- parent/grouping context when actually available,
+- permitted Product/Feature Brief roles,
+- whether local detailed requirements are authoritative, supplemental, read-only, or not used,
+- relevant accepted ADR/design rules.
+
+Read only the minimum relevant context. Do not preload unrelated work items. Do not claim external content was read unless it is actually available.
+
+Never assume `Jira Epic == Feature Brief`.
+
+## 2. Decide whether detail is warranted
+
+Detailed refinement is useful for behavior such as:
+- lifecycle/state transitions,
+- archive/delete/restore,
+- validation/uniqueness,
+- identity/permissions/attribution,
+- data integrity,
+- concurrency/transactions,
+- destructive/reversible behavior,
+- failure handling,
+- multiple related workflows,
+- cross-layer behavior needing testable boundaries.
+
+For LIGHT/obvious work, say detailed refinement is unnecessary and return to `/start-work`.
+
+## 3. Requirement shape depends on authority
+
+### Local combined requirements permitted
+
+Prefer one combined file rather than separate user-story/domain files.
+
+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
+```
+
+Do not invent personas for technical enablers.
+
+### External work item is primary
+
+If Jira/Issue/another external system is primary and local detailed requirements are not an approved supplement:
+- assess the external content actually provided/accessible,
+- maintain concise proposed external-work-item updates during the session,
+- do not create `requirements.md` merely as a dumping ground.
+
+## 4. Initial behavior is read-only
+
+Report an evidence-backed coverage assessment first:
+
+```text
+REQUIREMENTS COVERAGE
+
+User / engineering outcomes:
+✓ ...
+○ ...
+
+Domain / engineering rules:
+✓ ...
+○ ...
+
+Acceptance / validation:
+✓ ...
+○ ...
+
+Cross-work-item/grouping context:
+✓ / ○ / N/A
+
+Open material decisions:
+- ...
+
+AUTHORITATIVE SOURCE
+<source>
+
+STATUS
+<DRAFT / APPROVED / external status / not represented locally>
+```
+
+Then present only relevant choices, for example:
+
+```text
+1. Review outcomes [READ ONLY]
+2. Review rules [READ ONLY]
+3. Review acceptance scenarios [READ ONLY]
+4. Refine identified gaps [MODIFIES DOCS or PROPOSED EXTERNAL UPDATE]
+5. Grill an unresolved decision [READ ONLY]
+6. Review full requirements/work item [READ ONLY]
+7. Approve local requirements when applicable [REQUIREMENTS GATE]
+8. Stop [NO ACTION]
+```
+
+## 5. Active refinement session
+
+Once the human selects a modifying refinement option, enter a bounded continuous session:
+
+```text
+ask one material requirement question
+→ human answers
+→ reconcile/update/propose only what was resolved
+→ update directly affected validation scenario when useful
+→ summarize exactly what changed
+→ next material question
+```
+
+For bounded requirement decisions such as lifecycle policy, validation behavior, destructive/reversible handling, or a small set of credible alternatives, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep outcome wording, workflow descriptions, acceptance intent, and other human-authored framing open-ended when predefined choices would constrain the requirement.
+
+Do not ask after each answer whether to update.
+
+For local combined requirements:
+- preserve stable IDs,
+- do not renumber approved IDs,
+- keep implementation convenience out unless it is itself an approved requirement.
+
+For external-primary requirements without write authorization:
+- accumulate `PROPOSED EXTERNAL WORK-ITEM UPDATES`.
+
+If a permitted external write integration exists, require explicit `[EXTERNAL WRITE]` authorization before applying those updates.
+
+## 6. Pause only for material conflicts
+
+Stop automatic reconciliation when an answer would:
+- materially change approved higher-level scope,
+- contradict an approved Product/Feature/Enabler rule,
+- contradict an accepted ADR/design decision,
+- require a cross-cutting architecture decision,
+- remain too ambiguous to record faithfully.
+
+Then present a small explicit choice.
+
+## 7. Approval gate
+
+Local detailed requirements use only meaningful authoring states:
+
+```text
+DRAFT
+APPROVED
+```
+
+Human approval is explicit. Do not infer approval from review/planning/implementation.
+
+Before approval report coverage and open material decisions. Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`.
+
+External work-item status/approval follows the external team's conventions; Lean must not fabricate a local approval state.
+
+## 8. Natural completion
+
+Summarize:
+
+```text
+REQUIREMENTS REFINEMENT COMPLETE
+
+Updated/proposed:
+- <outcomes>
+- <rules>
+- <acceptance scenarios>
+
+Open material decisions:
+None / list
+
+Authority/status:
+<source and status>
+```
+
+Then offer review, more grilling/refinement, approval when applicable, or stop.
+
+## 9. Stop boundary
+
+Do not create implementation plans or production code.
+
+When requirements are ready, recommend `/start-work <ID-or-key>`.

package/assets/generated/core/core/skills/start-work/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: start-work
+description: Assess requirement readiness and implementation risk, then guide direct Agent work or native planning for the configured work item.
+argument-hint: "<work-item ID, external key, or concise change>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Start Work
+
+## 1. Resolve the requested work
+
+Read `.github/lean-workspace.json` when present.
+
+Resolve only the context needed:
+- authoritative work-item source,
+- parent/grouping context when actually available,
+- optional Product/Feature/Enabler briefs according to configured authority,
+- local detailed requirements when permitted/present,
+- relevant decisions/ADRs/architecture/standards,
+- current code/tests and branch/diff when relevant.
+
+Do not require local briefs when the repository uses Jira/Issues. Do not invent external content.
+
+## 2. Check requirement readiness before planning
+
+Assess:
+- outcome clarity,
+- acceptance criteria/validation expectations,
+- material domain/engineering rules,
+- dependencies/cross-work-item context,
+- unresolved human decisions,
+- requirement authority/status.
+
+Ask:
+
+```text
+Does detailed precision matter?
+Does the authoritative source contain enough detail?
+If local requirements exist, are they DRAFT or APPROVED?
+Are material decisions unresolved?
+```
+
+If detailed precision is warranted but incomplete, recommend `/refine-requirements`, `/grill-me`, or `/grill-with-docs` rather than silently inventing behavior.
+
+If local requirements are DRAFT and carry material behavior, human approval is the gate before substantive planning/implementation.
+
+If requirements are already sufficient/approved under the configured model, do not force another refinement cycle.
+
+## 3. Classify risk
+
+### LIGHT
+
+Tiny, obvious, low-risk; no meaningful schema/security/concurrency/deployment/major-UX implications.
+
+```text
+Agent
+→ relevant checks
+→ human meaningful-diff review
+```
+
+No formal plan or detailed requirements are required.
+
+### STANDARD
+
+Meaningful multi-file work.
+
+```text
+requirements ready as needed
+→ native plan
+→ HUMAN PLAN APPROVAL
+→ short-lived work branch setup
+→ Agent implementation
+→ checks
+→ Reviewer
+→ human meaningful-diff acceptance
+```
+
+### ELEVATED
+
+Use for:
+- schema/data-loss risk,
+- authentication/security,
+- concurrency/transactions,
+- release/deployment/recovery,
+- significant architecture,
+- broad cross-layer changes,
+- hard-to-reverse decisions.
+
+```text
+detailed approved requirements / ADR as needed
+→ native plan
+→ Reviewer challenges plan
+→ HUMAN PLAN APPROVAL
+→ short-lived work branch setup
+→ implementation in small slices
+→ stronger verification
+→ Reviewer
+→ human acceptance
+```
+
+Explain why the level was chosen.
+
+## 4. Optional learning checkpoint
+
+For STANDARD/ELEVATED work, once requirements are ready, coaching may be offered but is never required:
+
+```text
+1. Continue without coaching — recommended default
+2. /coach for a short pre-build concept review
+3. /grill-me for challenge rather than teaching
+4. Stop
+```
+
+For LIGHT work, do not interrupt with coaching unless requested.
+
+## 5. Planning rules
+
+For STANDARD/ELEVATED work:
+- use the editor's current native planning capability,
+- plan approach, affected areas, key decisions, risks, and verification,
+- require human plan approval before implementation,
+- do not auto-launch subagents,
+- do not create mandatory `spec.md` or `tasks.md`,
+- save a durable plan only when it is useful across sessions or for genuinely complex/risky work.
+
+## 6. Working branch setup
+
+Once implementation is authorized to begin, establish the repository-appropriate short-lived work branch as routine setup before substantive edits.
+
+Do not ask a separate branch-creation permission when all of the following are true:
+- the current branch is the default/integration branch and repository policy expects short-lived work branches,
+- the work-item boundary is clear,
+- the target branch name is unambiguous under repository convention or the Lean fallback below,
+- creating/switching branches does not require history rewriting or discarding work.
+
+Branch naming order:
+1. repository/team convention when defined,
+2. an already-existing branch clearly tied to the work item,
+3. Lean fallback: `<lowercase-work-item-id>-<concise-slug>` for ID-backed work, or `work/<concise-slug>` for a concise ad hoc change.
+
+Examples of the fallback shape are conceptual only; never invent a consumer-specific work-item ID in Core documentation or behavior.
+
+If scoped uncommitted changes already exist on the default branch and clearly belong to this work item, preserve them while creating/switching to the short-lived branch when Git can do so safely. Verify that the worktree diff is unchanged after the branch switch.
+
+Stop and ask only when branch policy/naming is materially ambiguous, the intended branch already exists with divergent work, unrelated changes are present, or the operation would require stash/reset/rebase/force/history rewriting.
+
+For LIGHT work, branch setup is part of the human-selected implementation action. For STANDARD/ELEVATED work, it is part of the approved implementation start after plan approval. Merely inspecting `/start-work` does not authorize implementation before its required gate.
+
+## 7. Production deployment enabler
+
+When a work item owns production release/deployment, classify it ELEVATED.
+
+Production target discovery may begin early with:
+
+```text
+/production-readiness <deployment-enabler-ID> discovery
+```
+
+Discovery is non-destructive and does not authorize production writes.
+
+After implementation review/local acceptance, use `/deliver`. After merge and required post-merge default-branch CI is green, hand off to:
+
+```text
+/production-readiness <deployment-enabler-ID> enable
+```
+
+## 8. Guided ending
+
+Return:
+- CURRENT STATE,
+- risk level and why,
+- requirement readiness,
+- branch state / expected short-lived branch when implementation is about to begin,
+- RECOMMENDED NEXT STEP,
+- a small numbered OPTIONS menu with action labels.
+
+Do not skip an unresolved requirement/plan gate merely because implementation is technically possible. Once implementation is selected/approved, do not insert a separate ceremonial branch-creation gate when the branch setup is safe and deterministic.

package/assets/generated/core/core/skills/tear-down/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: tear-down
+description: "Guided destructive environment cleanup for local, Staging, Production, or all supported POC scopes. Preserves exact ownership boundaries, separate Production-data authorization, and delegates deletion mechanics to repository-provided tooling."
+argument-hint: "[local|staging|production|all]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Tear Down
+
+`/tear-down` is the human-facing destructive cleanup workflow for repository-owned POC environments and local runtime state.
+
+The skill owns scope selection, read-only preflight, destructive preview, and Human-in-the-Loop authorization. Repository-provided deployment tooling owns teardown mechanics.
+
+Do not implement Docker, filesystem, route, database, registry, or host cleanup directly in the skill when an approved repository command exists.
+
+## 1. Begin read-only
+
+Invocation starts read-only.
+
+Read only the minimum repository context needed to identify:
+
+- the repository's approved tear-down entry point;
+- the canonical repository/application identity used by that entry point;
+- configured Staging and Production environment-to-target bindings when those scopes are available;
+- the exact local image/package identity used to identify POC-owned local Docker state;
+- the currently supported tear-down scopes and their ownership boundaries.
+
+Do not assume script paths, container names, volume names, environment bindings, target addresses, or package coordinates unless the repository establishes them.
+
+If the repository does not provide an approved deterministic tear-down command for the requested scope, stop. Do not improvise destructive shell commands.
+
+## 2. Select the scope explicitly
+
+Supported generic scope names are:
+
+```text
+local
+staging
+production
+all
+```
+
+If the invocation did not name a scope, present only scopes the current repository actually supports and ask the human to select one.
+
+Rules:
+
+- never silently default to `production` or `all`;
+- never infer destructive scope from a previous deployment or prior conversation;
+- never widen a requested scope after a failure;
+- `all` means all supported tear-down scopes for this one repository/POC, not machine-wide cleanup;
+- selecting a scope does not itself authorize deletion.
+
+If a named scope is unsupported or not configured, fail explicitly.
+
+## 3. Resolve exact ownership and target evidence
+
+Before presenting an authorization gate, resolve the non-secret ownership evidence required by the repository's tear-down contract.
+
+For local cleanup, this should identify the exact POC-owned local runtime/package boundary. For remote environments, this should identify the exact named environment, configured logical target, repository/application identity, and any ownership markers the deterministic tear-down tool verifies.
+
+Preserve the repository's shared-resource boundary. Normal POC tear-down must not broaden into deletion of shared platform infrastructure, unrelated POCs, workstation trust/credentials, or registry packages unless the repository defines a separate explicit lifecycle operation for those resources.
+
+If ownership is ambiguous, a target binding changed, host identity cannot be verified, or the underlying tool reports mismatched ownership, stop without deletion.
+
+## 4. Present the destructive preview
+
+Before authorization, show what will be removed and what will be preserved using the repository's actual contract.
+
+A typical preview is:
+
+```text
+TEAR-DOWN READY
+
+Scope: <local|staging|production|all>
+Repository/app: <verified identity>
+Staging target: <verified logical target or not selected>
+Production target: <verified logical target or not selected>
+Local package/runtime identity: <exact identity or not selected>
+
+Will remove:
+  <repository-supported owned resources>
+
+Will preserve:
+  <shared/unrelated resources established by the repository contract>
+```
+
+For Deployment-Kit consumers, expected behavior includes:
+
+- `local` — exact-package local containers/images and Docker-managed anonymous volumes attached to those owned containers;
+- `staging` — the owned Staging route, runtime, release/evidence state, persistent application data, and backups;
+- `production` — the owned Production route, runtime, release/evidence state, persistent application data, and backups;
+- `all` — Staging + Production + local for the selected POC only.
+
+Do not promise deletion of named/shared Docker volumes or other resources unless the repository has an independent ownership model that safely proves they belong to this POC.
+
+## 5. Require the destructive authorization gate
+
+Every modifying tear-down requires one explicit bounded authorization for the exact previewed scope and evidence:
+
+```text
+[POC TEAR DOWN]
+```
+
+For `production` or `all`, persistent Production data is part of the requested destructive scope. Require an additional independent authorization:
+
+```text
+[PRODUCTION DATA DELETE]
+```
+
+The Production-data authorization is required even when Production was previously deployed, tested, approved, or selected. Deployment authorization does not authorize data deletion.
+
+If the resolved repository/app identity, target binding, ownership evidence, or deletion set materially changes after the preview, stop and require renewed review and authorization.
+
+## 6. Execute only the approved repository command
+
+After the required authorization phrase or phrases are explicitly provided, invoke only the repository-approved tear-down command with the exact selected scope and resolved inputs.
+
+Pass authorization through only when the repository command expects the same bounded contract. Do not translate one approval into broader deletion authority.
+
+Do not add machine-wide Docker prune, shared-network removal, shared Caddy/Avahi removal, unrelated branch/repository cleanup, registry-package deletion, host reprovisioning, target rebinding, or secret/trust cleanup unless those operations are separately defined and explicitly authorized by the repository.
+
+If the deterministic command stops partway through `all`, report the completed and remaining scopes. Do not compensate by manually deleting the remainder.
+
+## 7. Verify and report the outcome
+
+Use repository-provided evidence/status commands when available. Report only what the evidence supports, including:
+
+- requested scope;
+- repository/application identity;
+- environments/targets actually processed;
+- local runtime state actually processed;
+- whether persistent Production data was included;
+- removed versus already-absent resources;
+- any failure point or remaining scope after a partial stop;
+- confirmation that shared/unrelated resources were preserved when the repository provides evidence for that claim.
+
+The operation should remain safe to rerun for already-absent owned resources when the repository's tear-down contract says it is idempotent.